2 * WUSB Wire Adapter: Radio Control Interface (WUSB[8])
3 * Notification and Event Handling
5 * Copyright (C) 2005-2006 Intel Corporation
6 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8 * This program is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License version
10 * 2 as published by the Free Software Foundation.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with this program; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
23 * The RC interface of the Host Wire Adapter (USB dongle) or WHCI PCI
24 * card delivers a stream of notifications and events to the
25 * notification end event endpoint or area. This code takes care of
26 * getting a buffer with that data, breaking it up in separate
27 * notifications and events and then deliver those.
29 * Events are answers to commands and they carry a context ID that
30 * associates them to the command. Notifications are that,
31 * notifications, they come out of the blue and have a context ID of
32 * zero. Think of the context ID kind of like a handler. The
33 * uwb_rc_neh_* code deals with managing context IDs.
35 * This is why you require a handle to operate on a UWB host. When you
36 * open a handle a context ID is assigned to you.
38 * So, as it is done is:
40 * 1. Add an event handler [uwb_rc_neh_add()] (assigns a ctx id)
41 * 2. Issue command [rc->cmd(rc, ...)]
42 * 3. Arm the timeout timer [uwb_rc_neh_arm()]
43 * 4, Release the reference to the neh [uwb_rc_neh_put()]
44 * 5. Wait for the callback
45 * 6. Command result (RCEB) is passed to the callback
47 * If (2) fails, you should remove the handle [uwb_rc_neh_rm()]
48 * instead of arming the timer.
50 * Handles are for using in *serialized* code, single thread.
52 * When the notification/event comes, the IRQ handler/endpoint
53 * callback passes the data read to uwb_rc_neh_grok() which will break
54 * it up in a discrete series of events, look up who is listening for
55 * them and execute the pertinent callbacks.
57 * If the reader detects an error while reading the data stream, call
60 * CONSTRAINTS/ASSUMPTIONS:
62 * - Most notifications/events are small (less thank .5k), copying
65 * - Notifications/events are ALWAYS smaller than PAGE_SIZE
67 * - Notifications/events always come in a single piece (ie: a buffer
68 * will always contain entire notifications/events).
70 * - we cannot know in advance how long each event is (because they
71 * lack a length field in their header--smart move by the standards
72 * body, btw). So we need a facility to get the event size given the
73 * header. This is what the EST code does (notif/Event Size
74 * Tables), check nest.c--as well, you can associate the size to
75 * the handle [w/ neh->extra_size()].
77 * - Most notifications/events are fixed size; only a few are variable
78 * size (NEST takes care of that).
80 * - Listeners of events expect them, so they usually provide a
81 * buffer, as they know the size. Listeners to notifications don't,
82 * so we allocate their buffers dynamically.
84 #include <linux/kernel.h>
85 #include <linux/timer.h>
86 #include <linux/slab.h>
87 #include <linux/err.h>
88 #include <linux/export.h>
90 #include "uwb-internal.h"
93 * UWB Radio Controller Notification/Event Handle
95 * Represents an entity waiting for an event coming from the UWB Radio
96 * Controller with a given context id (context) and type (evt_type and
97 * evt). On reception of the notification/event, the callback (cb) is
98 * called with the event.
100 * If the timer expires before the event is received, the callback is
101 * called with -ETIMEDOUT as the event size.
114 struct timer_list timer
;
115 struct list_head list_node
;
118 static void uwb_rc_neh_timer(unsigned long arg
);
120 static void uwb_rc_neh_release(struct kref
*kref
)
122 struct uwb_rc_neh
*neh
= container_of(kref
, struct uwb_rc_neh
, kref
);
127 static void uwb_rc_neh_get(struct uwb_rc_neh
*neh
)
129 kref_get(&neh
->kref
);
133 * uwb_rc_neh_put - release reference to a neh
136 void uwb_rc_neh_put(struct uwb_rc_neh
*neh
)
138 kref_put(&neh
->kref
, uwb_rc_neh_release
);
143 * Assigns @neh a context id from @rc's pool
145 * @rc: UWB Radio Controller descriptor; @rc->neh_lock taken
146 * @neh: Notification/Event Handle
147 * @returns 0 if context id was assigned ok; < 0 errno on error (if
148 * all the context IDs are taken).
150 * (assumes @wa is locked).
152 * NOTE: WUSB spec reserves context ids 0x00 for notifications and
153 * 0xff is invalid, so they must not be used. Initialization
154 * fills up those two in the bitmap so they are not allocated.
156 * We spread the allocation around to reduce the possibility of two
157 * consecutive opened @neh's getting the same context ID assigned (to
158 * avoid surprises with late events that timed out long time ago). So
159 * first we search from where @rc->ctx_roll is, if not found, we
163 int __uwb_rc_ctx_get(struct uwb_rc
*rc
, struct uwb_rc_neh
*neh
)
166 result
= find_next_zero_bit(rc
->ctx_bm
, UWB_RC_CTX_MAX
,
168 if (result
< UWB_RC_CTX_MAX
)
170 result
= find_first_zero_bit(rc
->ctx_bm
, UWB_RC_CTX_MAX
);
171 if (result
< UWB_RC_CTX_MAX
)
175 set_bit(result
, rc
->ctx_bm
);
176 neh
->context
= result
;
181 /** Releases @neh's context ID back to @rc (@rc->neh_lock is locked). */
183 void __uwb_rc_ctx_put(struct uwb_rc
*rc
, struct uwb_rc_neh
*neh
)
185 struct device
*dev
= &rc
->uwb_dev
.dev
;
186 if (neh
->context
== 0)
188 if (test_bit(neh
->context
, rc
->ctx_bm
) == 0) {
189 dev_err(dev
, "context %u not set in bitmap\n",
193 clear_bit(neh
->context
, rc
->ctx_bm
);
198 * uwb_rc_neh_add - add a neh for a radio controller command
199 * @rc: the radio controller
200 * @cmd: the radio controller command
201 * @expected_type: the type of the expected response event
202 * @expected_event: the expected event ID
203 * @cb: callback for when the event is received
204 * @arg: argument for the callback
206 * Creates a neh and adds it to the list of those waiting for an
207 * event. A context ID will be assigned to the command.
209 struct uwb_rc_neh
*uwb_rc_neh_add(struct uwb_rc
*rc
, struct uwb_rccb
*cmd
,
210 u8 expected_type
, u16 expected_event
,
211 uwb_rc_cmd_cb_f cb
, void *arg
)
215 struct device
*dev
= &rc
->uwb_dev
.dev
;
216 struct uwb_rc_neh
*neh
;
218 neh
= kzalloc(sizeof(*neh
), GFP_KERNEL
);
224 kref_init(&neh
->kref
);
225 INIT_LIST_HEAD(&neh
->list_node
);
226 init_timer(&neh
->timer
);
227 neh
->timer
.function
= uwb_rc_neh_timer
;
228 neh
->timer
.data
= (unsigned long)neh
;
231 neh
->evt_type
= expected_type
;
232 neh
->evt
= cpu_to_le16(expected_event
);
236 spin_lock_irqsave(&rc
->neh_lock
, flags
);
237 result
= __uwb_rc_ctx_get(rc
, neh
);
239 cmd
->bCommandContext
= neh
->context
;
240 list_add_tail(&neh
->list_node
, &rc
->neh_list
);
243 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
252 dev_err(dev
, "cannot open handle to radio controller: %d\n", result
);
253 return ERR_PTR(result
);
256 static void __uwb_rc_neh_rm(struct uwb_rc
*rc
, struct uwb_rc_neh
*neh
)
258 __uwb_rc_ctx_put(rc
, neh
);
259 list_del(&neh
->list_node
);
263 * uwb_rc_neh_rm - remove a neh.
264 * @rc: the radio controller
265 * @neh: the neh to remove
267 * Remove an active neh immediately instead of waiting for the event
270 void uwb_rc_neh_rm(struct uwb_rc
*rc
, struct uwb_rc_neh
*neh
)
274 spin_lock_irqsave(&rc
->neh_lock
, flags
);
275 __uwb_rc_neh_rm(rc
, neh
);
276 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
278 del_timer_sync(&neh
->timer
);
283 * uwb_rc_neh_arm - arm an event handler timeout timer
285 * @rc: UWB Radio Controller
286 * @neh: Notification/event handler for @rc
288 * The timer is only armed if the neh is active.
290 void uwb_rc_neh_arm(struct uwb_rc
*rc
, struct uwb_rc_neh
*neh
)
294 spin_lock_irqsave(&rc
->neh_lock
, flags
);
296 mod_timer(&neh
->timer
,
297 jiffies
+ msecs_to_jiffies(UWB_RC_CMD_TIMEOUT_MS
));
298 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
301 static void uwb_rc_neh_cb(struct uwb_rc_neh
*neh
, struct uwb_rceb
*rceb
, size_t size
)
303 (*neh
->cb
)(neh
->rc
, neh
->arg
, rceb
, size
);
307 static bool uwb_rc_neh_match(struct uwb_rc_neh
*neh
, const struct uwb_rceb
*rceb
)
309 return neh
->evt_type
== rceb
->bEventType
310 && neh
->evt
== rceb
->wEvent
311 && neh
->context
== rceb
->bEventContext
;
315 * Find the handle waiting for a RC Radio Control Event
317 * @rc: UWB Radio Controller
318 * @rceb: Pointer to the RCEB buffer
319 * @event_size: Pointer to the size of the RCEB buffer. Might be
320 * adjusted to take into account the @neh->extra_size
323 * If the listener has no buffer (NULL buffer), one is allocated for
324 * the right size (the amount of data received). @neh->ptr will point
325 * to the event payload, which always starts with a 'struct
326 * uwb_rceb'. kfree() it when done.
329 struct uwb_rc_neh
*uwb_rc_neh_lookup(struct uwb_rc
*rc
,
330 const struct uwb_rceb
*rceb
)
332 struct uwb_rc_neh
*neh
= NULL
, *h
;
335 spin_lock_irqsave(&rc
->neh_lock
, flags
);
337 list_for_each_entry(h
, &rc
->neh_list
, list_node
) {
338 if (uwb_rc_neh_match(h
, rceb
)) {
345 __uwb_rc_neh_rm(rc
, neh
);
347 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
354 * Process notifications coming from the radio control interface
356 * @rc: UWB Radio Control Interface descriptor
357 * @neh: Notification/Event Handler @neh->ptr points to
360 * This function is called by the event/notif handling subsystem when
361 * notifications arrive (hwarc_probe() arms a notification/event handle
362 * that calls back this function for every received notification; this
363 * function then will rearm itself).
365 * Notification data buffers are dynamically allocated by the NEH
366 * handling code in neh.c [uwb_rc_neh_lookup()]. What is actually
367 * allocated is space to contain the notification data.
369 * Buffers are prefixed with a Radio Control Event Block (RCEB) as
370 * defined by the WUSB Wired-Adapter Radio Control interface. We
371 * just use it for the notification code.
373 * On each case statement we just transcode endianess of the different
374 * fields. We declare a pointer to a RCI definition of an event, and
375 * then to a UWB definition of the same event (which are the same,
376 * remember). Event if we use different pointers
379 void uwb_rc_notif(struct uwb_rc
*rc
, struct uwb_rceb
*rceb
, ssize_t size
)
381 struct device
*dev
= &rc
->uwb_dev
.dev
;
382 struct uwb_event
*uwb_evt
;
384 if (size
== -ESHUTDOWN
)
387 dev_err(dev
, "ignoring event with error code %zu\n",
392 uwb_evt
= kzalloc(sizeof(*uwb_evt
), GFP_ATOMIC
);
393 if (unlikely(uwb_evt
== NULL
)) {
394 dev_err(dev
, "no memory to queue event 0x%02x/%04x/%02x\n",
395 rceb
->bEventType
, le16_to_cpu(rceb
->wEvent
),
396 rceb
->bEventContext
);
399 uwb_evt
->rc
= __uwb_rc_get(rc
); /* will be put by uwbd's uwbd_event_handle() */
400 uwb_evt
->ts_jiffies
= jiffies
;
401 uwb_evt
->type
= UWB_EVT_TYPE_NOTIF
;
402 uwb_evt
->notif
.size
= size
;
403 uwb_evt
->notif
.rceb
= rceb
;
405 uwbd_event_queue(uwb_evt
);
408 static void uwb_rc_neh_grok_event(struct uwb_rc
*rc
, struct uwb_rceb
*rceb
, size_t size
)
410 struct device
*dev
= &rc
->uwb_dev
.dev
;
411 struct uwb_rc_neh
*neh
;
412 struct uwb_rceb
*notif
;
415 if (rceb
->bEventContext
== 0) {
416 notif
= kmalloc(size
, GFP_ATOMIC
);
418 memcpy(notif
, rceb
, size
);
419 uwb_rc_notif(rc
, notif
, size
);
421 dev_err(dev
, "event 0x%02x/%04x/%02x (%zu bytes): no memory\n",
422 rceb
->bEventType
, le16_to_cpu(rceb
->wEvent
),
423 rceb
->bEventContext
, size
);
425 neh
= uwb_rc_neh_lookup(rc
, rceb
);
427 spin_lock_irqsave(&rc
->neh_lock
, flags
);
428 /* to guard against a timeout */
430 del_timer(&neh
->timer
);
431 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
432 uwb_rc_neh_cb(neh
, rceb
, size
);
434 dev_warn(dev
, "event 0x%02x/%04x/%02x (%zu bytes): nobody cared\n",
435 rceb
->bEventType
, le16_to_cpu(rceb
->wEvent
),
436 rceb
->bEventContext
, size
);
441 * Given a buffer with one or more UWB RC events/notifications, break
442 * them up and dispatch them.
444 * @rc: UWB Radio Controller
445 * @buf: Buffer with the stream of notifications/events
446 * @buf_size: Amount of data in the buffer
448 * Note each notification/event starts always with a 'struct
449 * uwb_rceb', so the minimum size if 4 bytes.
451 * The device may pass us events formatted differently than expected.
452 * These are first filtered, potentially creating a new event in a new
453 * memory location. If a new event is created by the filter it is also
456 * For each notif/event, tries to guess the size looking at the EST
457 * tables, then looks for a neh that is waiting for that event and if
458 * found, copies the payload to the neh's buffer and calls it back. If
459 * not, the data is ignored.
461 * Note that if we can't find a size description in the EST tables, we
462 * still might find a size in the 'neh' handle in uwb_rc_neh_lookup().
466 * @rc->neh_lock is NOT taken
468 * We keep track of various sizes here:
469 * size: contains the size of the buffer that is processed for the
470 * incoming event. this buffer may contain events that are not
472 * real_size: the actual space taken by this event in the buffer.
473 * We need to keep track of the real size of an event to be able to
474 * advance the buffer correctly.
475 * event_size: the size of the event as expected by the core layer
476 * [OR] the size of the event after filtering. if the filtering
477 * created a new event in a new memory location then this is
478 * effectively the size of a new event buffer
480 void uwb_rc_neh_grok(struct uwb_rc
*rc
, void *buf
, size_t buf_size
)
482 struct device
*dev
= &rc
->uwb_dev
.dev
;
484 struct uwb_rceb
*rceb
;
485 size_t size
, real_size
, event_size
;
491 if (size
< sizeof(*rceb
)) {
492 dev_err(dev
, "not enough data in event buffer to "
493 "process incoming events (%zu left, minimum is "
494 "%zu)\n", size
, sizeof(*rceb
));
499 if (rc
->filter_event
) {
500 needtofree
= rc
->filter_event(rc
, &rceb
, size
,
501 &real_size
, &event_size
);
502 if (needtofree
< 0 && needtofree
!= -ENOANO
) {
503 dev_err(dev
, "BUG: Unable to filter event "
504 "(0x%02x/%04x/%02x) from "
505 "device. \n", rceb
->bEventType
,
506 le16_to_cpu(rceb
->wEvent
),
507 rceb
->bEventContext
);
511 needtofree
= -ENOANO
;
512 /* do real processing if there was no filtering or the
513 * filtering didn't act */
514 if (needtofree
== -ENOANO
) {
515 ssize_t ret
= uwb_est_find_size(rc
, rceb
, size
);
519 dev_err(dev
, "BUG: hw sent incomplete event "
520 "0x%02x/%04x/%02x (%zd bytes), only got "
521 "%zu bytes. We don't handle that.\n",
522 rceb
->bEventType
, le16_to_cpu(rceb
->wEvent
),
523 rceb
->bEventContext
, ret
, size
);
526 real_size
= event_size
= ret
;
528 uwb_rc_neh_grok_event(rc
, rceb
, event_size
);
537 EXPORT_SYMBOL_GPL(uwb_rc_neh_grok
);
541 * The entity that reads from the device notification/event channel has
544 * @rc: UWB Radio Controller
545 * @error: Errno error code
548 void uwb_rc_neh_error(struct uwb_rc
*rc
, int error
)
550 struct uwb_rc_neh
*neh
;
554 spin_lock_irqsave(&rc
->neh_lock
, flags
);
555 if (list_empty(&rc
->neh_list
)) {
556 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
559 neh
= list_first_entry(&rc
->neh_list
, struct uwb_rc_neh
, list_node
);
560 __uwb_rc_neh_rm(rc
, neh
);
561 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
563 del_timer_sync(&neh
->timer
);
564 uwb_rc_neh_cb(neh
, NULL
, error
);
567 EXPORT_SYMBOL_GPL(uwb_rc_neh_error
);
570 static void uwb_rc_neh_timer(unsigned long arg
)
572 struct uwb_rc_neh
*neh
= (struct uwb_rc_neh
*)arg
;
573 struct uwb_rc
*rc
= neh
->rc
;
576 spin_lock_irqsave(&rc
->neh_lock
, flags
);
577 if (neh
->completed
) {
578 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
582 __uwb_rc_neh_rm(rc
, neh
);
585 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
588 uwb_rc_neh_cb(neh
, NULL
, -ETIMEDOUT
);
591 /** Initializes the @rc's neh subsystem
593 void uwb_rc_neh_create(struct uwb_rc
*rc
)
595 spin_lock_init(&rc
->neh_lock
);
596 INIT_LIST_HEAD(&rc
->neh_list
);
597 set_bit(0, rc
->ctx_bm
); /* 0 is reserved (see [WUSB] table 8-65) */
598 set_bit(0xff, rc
->ctx_bm
); /* and 0xff is invalid */
603 /** Release's the @rc's neh subsystem */
604 void uwb_rc_neh_destroy(struct uwb_rc
*rc
)
607 struct uwb_rc_neh
*neh
;
610 spin_lock_irqsave(&rc
->neh_lock
, flags
);
611 if (list_empty(&rc
->neh_list
)) {
612 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
615 neh
= list_first_entry(&rc
->neh_list
, struct uwb_rc_neh
, list_node
);
616 __uwb_rc_neh_rm(rc
, neh
);
617 spin_unlock_irqrestore(&rc
->neh_lock
, flags
);
619 del_timer_sync(&neh
->timer
);
This page took 0.042404 seconds and 5 git commands to generate.