1 // SPDX-License-Identifier: GPL-2.0-only
2 /*
3 * WUSB Wire Adapter: Radio Control Interface (WUSB[8])
4 * Notification and Event Handling
5 *
6 * Copyright (C) 2005-2006 Intel Corporation
7 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8 *
9 * The RC interface of the Host Wire Adapter (USB dongle) or WHCI PCI
10 * card delivers a stream of notifications and events to the
11 * notification end event endpoint or area. This code takes care of
12 * getting a buffer with that data, breaking it up in separate
13 * notifications and events and then deliver those.
14 *
15 * Events are answers to commands and they carry a context ID that
16 * associates them to the command. Notifications are that,
17 * notifications, they come out of the blue and have a context ID of
18 * zero. Think of the context ID kind of like a handler. The
19 * uwb_rc_neh_* code deals with managing context IDs.
20 *
21 * This is why you require a handle to operate on a UWB host. When you
22 * open a handle a context ID is assigned to you.
23 *
24 * So, as it is done is:
25 *
26 * 1. Add an event handler [uwb_rc_neh_add()] (assigns a ctx id)
27 * 2. Issue command [rc->cmd(rc, ...)]
28 * 3. Arm the timeout timer [uwb_rc_neh_arm()]
29 * 4, Release the reference to the neh [uwb_rc_neh_put()]
30 * 5. Wait for the callback
31 * 6. Command result (RCEB) is passed to the callback
32 *
33 * If (2) fails, you should remove the handle [uwb_rc_neh_rm()]
34 * instead of arming the timer.
35 *
36 * Handles are for using in *serialized* code, single thread.
37 *
38 * When the notification/event comes, the IRQ handler/endpoint
39 * callback passes the data read to uwb_rc_neh_grok() which will break
40 * it up in a discrete series of events, look up who is listening for
41 * them and execute the pertinent callbacks.
42 *
43 * If the reader detects an error while reading the data stream, call
44 * uwb_rc_neh_error().
45 *
46 * CONSTRAINTS/ASSUMPTIONS:
47 *
48 * - Most notifications/events are small (less thank .5k), copying
49 * around is ok.
50 *
51 * - Notifications/events are ALWAYS smaller than PAGE_SIZE
52 *
53 * - Notifications/events always come in a single piece (ie: a buffer
54 * will always contain entire notifications/events).
55 *
56 * - we cannot know in advance how long each event is (because they
57 * lack a length field in their header--smart move by the standards
58 * body, btw). So we need a facility to get the event size given the
59 * header. This is what the EST code does (notif/Event Size
60 * Tables), check nest.c--as well, you can associate the size to
61 * the handle [w/ neh->extra_size()].
62 *
63 * - Most notifications/events are fixed size; only a few are variable
64 * size (NEST takes care of that).
65 *
66 * - Listeners of events expect them, so they usually provide a
67 * buffer, as they know the size. Listeners to notifications don't,
68 * so we allocate their buffers dynamically.
69 */
70 #include <linux/kernel.h>
71 #include <linux/timer.h>
72 #include <linux/slab.h>
73 #include <linux/err.h>
74 #include <linux/export.h>
75
76 #include "uwb-internal.h"
77
78 /*
79 * UWB Radio Controller Notification/Event Handle
80 *
81 * Represents an entity waiting for an event coming from the UWB Radio
82 * Controller with a given context id (context) and type (evt_type and
83 * evt). On reception of the notification/event, the callback (cb) is
84 * called with the event.
85 *
86 * If the timer expires before the event is received, the callback is
87 * called with -ETIMEDOUT as the event size.
88 */
89 struct uwb_rc_neh {
90 struct kref kref;
91
92 struct uwb_rc *rc;
93 u8 evt_type;
94 __le16 evt;
95 u8 context;
96 u8 completed;
97 uwb_rc_cmd_cb_f cb;
98 void *arg;
99
100 struct timer_list timer;
101 struct list_head list_node;
102 };
103
104 static void uwb_rc_neh_timer(struct timer_list *t);
105
106 static void uwb_rc_neh_release(struct kref *kref)
107 {
108 struct uwb_rc_neh *neh = container_of(kref, struct uwb_rc_neh, kref);
109
110 kfree(neh);
111 }
112
113 static void uwb_rc_neh_get(struct uwb_rc_neh *neh)
114 {
115 kref_get(&neh->kref);
116 }
117
118 /**
119 * uwb_rc_neh_put - release reference to a neh
120 * @neh: the neh
121 */
122 void uwb_rc_neh_put(struct uwb_rc_neh *neh)
123 {
124 kref_put(&neh->kref, uwb_rc_neh_release);
125 }
126
127
128 /**
129 * Assigns @neh a context id from @rc's pool
130 *
131 * @rc: UWB Radio Controller descriptor; @rc->neh_lock taken
132 * @neh: Notification/Event Handle
133 * @returns 0 if context id was assigned ok; < 0 errno on error (if
134 * all the context IDs are taken).
135 *
136 * (assumes @wa is locked).
137 *
138 * NOTE: WUSB spec reserves context ids 0x00 for notifications and
139 * 0xff is invalid, so they must not be used. Initialization
140 * fills up those two in the bitmap so they are not allocated.
141 *
142 * We spread the allocation around to reduce the possibility of two
143 * consecutive opened @neh's getting the same context ID assigned (to
144 * avoid surprises with late events that timed out long time ago). So
145 * first we search from where @rc->ctx_roll is, if not found, we
146 * search from zero.
147 */
148 static
149 int __uwb_rc_ctx_get(struct uwb_rc *rc, struct uwb_rc_neh *neh)
150 {
151 int result;
152 result = find_next_zero_bit(rc->ctx_bm, UWB_RC_CTX_MAX,
153 rc->ctx_roll++);
154 if (result < UWB_RC_CTX_MAX)
155 goto found;
156 result = find_first_zero_bit(rc->ctx_bm, UWB_RC_CTX_MAX);
157 if (result < UWB_RC_CTX_MAX)
158 goto found;
159 return -ENFILE;
160 found:
161 set_bit(result, rc->ctx_bm);
162 neh->context = result;
163 return 0;
164 }
165
166
167 /** Releases @neh's context ID back to @rc (@rc->neh_lock is locked). */
168 static
169 void __uwb_rc_ctx_put(struct uwb_rc *rc, struct uwb_rc_neh *neh)
170 {
171 struct device *dev = &rc->uwb_dev.dev;
172 if (neh->context == 0)
173 return;
174 if (test_bit(neh->context, rc->ctx_bm) == 0) {
175 dev_err(dev, "context %u not set in bitmap\n",
176 neh->context);
177 WARN_ON(1);
178 }
179 clear_bit(neh->context, rc->ctx_bm);
180 neh->context = 0;
181 }
182
183 /**
184 * uwb_rc_neh_add - add a neh for a radio controller command
185 * @rc: the radio controller
186 * @cmd: the radio controller command
187 * @expected_type: the type of the expected response event
188 * @expected_event: the expected event ID
189 * @cb: callback for when the event is received
190 * @arg: argument for the callback
191 *
192 * Creates a neh and adds it to the list of those waiting for an
193 * event. A context ID will be assigned to the command.
194 */
195 struct uwb_rc_neh *uwb_rc_neh_add(struct uwb_rc *rc, struct uwb_rccb *cmd,
196 u8 expected_type, u16 expected_event,
197 uwb_rc_cmd_cb_f cb, void *arg)
198 {
199 int result;
200 unsigned long flags;
201 struct device *dev = &rc->uwb_dev.dev;
202 struct uwb_rc_neh *neh;
203
204 neh = kzalloc(sizeof(*neh), GFP_KERNEL);
205 if (neh == NULL) {
206 result = -ENOMEM;
207 goto error_kzalloc;
208 }
209
210 kref_init(&neh->kref);
211 INIT_LIST_HEAD(&neh->list_node);
212 timer_setup(&neh->timer, uwb_rc_neh_timer, 0);
213
214 neh->rc = rc;
215 neh->evt_type = expected_type;
216 neh->evt = cpu_to_le16(expected_event);
217 neh->cb = cb;
218 neh->arg = arg;
219
220 spin_lock_irqsave(&rc->neh_lock, flags);
221 result = __uwb_rc_ctx_get(rc, neh);
222 if (result >= 0) {
223 cmd->bCommandContext = neh->context;
224 list_add_tail(&neh->list_node, &rc->neh_list);
225 uwb_rc_neh_get(neh);
226 }
227 spin_unlock_irqrestore(&rc->neh_lock, flags);
228 if (result < 0)
229 goto error_ctx_get;
230
231 return neh;
232
233 error_ctx_get:
234 kfree(neh);
235 error_kzalloc:
236 dev_err(dev, "cannot open handle to radio controller: %d\n", result);
237 return ERR_PTR(result);
238 }
239
240 static void __uwb_rc_neh_rm(struct uwb_rc *rc, struct uwb_rc_neh *neh)
241 {
242 __uwb_rc_ctx_put(rc, neh);
243 list_del(&neh->list_node);
244 }
245
246 /**
247 * uwb_rc_neh_rm - remove a neh.
248 * @rc: the radio controller
249 * @neh: the neh to remove
250 *
251 * Remove an active neh immediately instead of waiting for the event
252 * (or a time out).
253 */
254 void uwb_rc_neh_rm(struct uwb_rc *rc, struct uwb_rc_neh *neh)
255 {
256 unsigned long flags;
257
258 spin_lock_irqsave(&rc->neh_lock, flags);
259 __uwb_rc_neh_rm(rc, neh);
260 spin_unlock_irqrestore(&rc->neh_lock, flags);
261
262 del_timer_sync(&neh->timer);
263 uwb_rc_neh_put(neh);
264 }
265
266 /**
267 * uwb_rc_neh_arm - arm an event handler timeout timer
268 *
269 * @rc: UWB Radio Controller
270 * @neh: Notification/event handler for @rc
271 *
272 * The timer is only armed if the neh is active.
273 */
274 void uwb_rc_neh_arm(struct uwb_rc *rc, struct uwb_rc_neh *neh)
275 {
276 unsigned long flags;
277
278 spin_lock_irqsave(&rc->neh_lock, flags);
279 if (neh->context)
280 mod_timer(&neh->timer,
281 jiffies + msecs_to_jiffies(UWB_RC_CMD_TIMEOUT_MS));
282 spin_unlock_irqrestore(&rc->neh_lock, flags);
283 }
284
285 static void uwb_rc_neh_cb(struct uwb_rc_neh *neh, struct uwb_rceb *rceb, size_t size)
286 {
287 (*neh->cb)(neh->rc, neh->arg, rceb, size);
288 uwb_rc_neh_put(neh);
289 }
290
291 static bool uwb_rc_neh_match(struct uwb_rc_neh *neh, const struct uwb_rceb *rceb)
292 {
293 return neh->evt_type == rceb->bEventType
294 && neh->evt == rceb->wEvent
295 && neh->context == rceb->bEventContext;
296 }
297
298 /**
299 * Find the handle waiting for a RC Radio Control Event
300 *
301 * @rc: UWB Radio Controller
302 * @rceb: Pointer to the RCEB buffer
303 * @event_size: Pointer to the size of the RCEB buffer. Might be
304 * adjusted to take into account the @neh->extra_size
305 * settings.
306 *
307 * If the listener has no buffer (NULL buffer), one is allocated for
308 * the right size (the amount of data received). @neh->ptr will point
309 * to the event payload, which always starts with a 'struct
310 * uwb_rceb'. kfree() it when done.
311 */
312 static
313 struct uwb_rc_neh *uwb_rc_neh_lookup(struct uwb_rc *rc,
314 const struct uwb_rceb *rceb)
315 {
316 struct uwb_rc_neh *neh = NULL, *h;
317 unsigned long flags;
318
319 spin_lock_irqsave(&rc->neh_lock, flags);
320
321 list_for_each_entry(h, &rc->neh_list, list_node) {
322 if (uwb_rc_neh_match(h, rceb)) {
323 neh = h;
324 break;
325 }
326 }
327
328 if (neh)
329 __uwb_rc_neh_rm(rc, neh);
330
331 spin_unlock_irqrestore(&rc->neh_lock, flags);
332
333 return neh;
334 }
335
336
337 /*
338 * Process notifications coming from the radio control interface
339 *
340 * @rc: UWB Radio Control Interface descriptor
341 * @neh: Notification/Event Handler @neh->ptr points to
342 * @uwb_evt->buffer.
343 *
344 * This function is called by the event/notif handling subsystem when
345 * notifications arrive (hwarc_probe() arms a notification/event handle
346 * that calls back this function for every received notification; this
347 * function then will rearm itself).
348 *
349 * Notification data buffers are dynamically allocated by the NEH
350 * handling code in neh.c [uwb_rc_neh_lookup()]. What is actually
351 * allocated is space to contain the notification data.
352 *
353 * Buffers are prefixed with a Radio Control Event Block (RCEB) as
354 * defined by the WUSB Wired-Adapter Radio Control interface. We
355 * just use it for the notification code.
356 *
357 * On each case statement we just transcode endianess of the different
358 * fields. We declare a pointer to a RCI definition of an event, and
359 * then to a UWB definition of the same event (which are the same,
360 * remember). Event if we use different pointers
361 */
362 static
363 void uwb_rc_notif(struct uwb_rc *rc, struct uwb_rceb *rceb, ssize_t size)
364 {
365 struct device *dev = &rc->uwb_dev.dev;
366 struct uwb_event *uwb_evt;
367
368 if (size == -ESHUTDOWN)
369 return;
370 if (size < 0) {
371 dev_err(dev, "ignoring event with error code %zu\n",
372 size);
373 return;
374 }
375
376 uwb_evt = kzalloc(sizeof(*uwb_evt), GFP_ATOMIC);
377 if (unlikely(uwb_evt == NULL)) {
378 dev_err(dev, "no memory to queue event 0x%02x/%04x/%02x\n",
379 rceb->bEventType, le16_to_cpu(rceb->wEvent),
380 rceb->bEventContext);
381 return;
382 }
383 uwb_evt->rc = __uwb_rc_get(rc); /* will be put by uwbd's uwbd_event_handle() */
384 uwb_evt->ts_jiffies = jiffies;
385 uwb_evt->type = UWB_EVT_TYPE_NOTIF;
386 uwb_evt->notif.size = size;
387 uwb_evt->notif.rceb = rceb;
388
389 uwbd_event_queue(uwb_evt);
390 }
391
392 static void uwb_rc_neh_grok_event(struct uwb_rc *rc, struct uwb_rceb *rceb, size_t size)
393 {
394 struct device *dev = &rc->uwb_dev.dev;
395 struct uwb_rc_neh *neh;
396 struct uwb_rceb *notif;
397 unsigned long flags;
398
399 if (rceb->bEventContext == 0) {
400 notif = kmalloc(size, GFP_ATOMIC);
401 if (notif) {
402 memcpy(notif, rceb, size);
403 uwb_rc_notif(rc, notif, size);
404 } else
405 dev_err(dev, "event 0x%02x/%04x/%02x (%zu bytes): no memory\n",
406 rceb->bEventType, le16_to_cpu(rceb->wEvent),
407 rceb->bEventContext, size);
408 } else {
409 neh = uwb_rc_neh_lookup(rc, rceb);
410 if (neh) {
411 spin_lock_irqsave(&rc->neh_lock, flags);
412 /* to guard against a timeout */
413 neh->completed = 1;
414 del_timer(&neh->timer);
415 spin_unlock_irqrestore(&rc->neh_lock, flags);
416 uwb_rc_neh_cb(neh, rceb, size);
417 } else
418 dev_warn(dev, "event 0x%02x/%04x/%02x (%zu bytes): nobody cared\n",
419 rceb->bEventType, le16_to_cpu(rceb->wEvent),
420 rceb->bEventContext, size);
421 }
422 }
423
424 /**
425 * Given a buffer with one or more UWB RC events/notifications, break
426 * them up and dispatch them.
427 *
428 * @rc: UWB Radio Controller
429 * @buf: Buffer with the stream of notifications/events
430 * @buf_size: Amount of data in the buffer
431 *
432 * Note each notification/event starts always with a 'struct
433 * uwb_rceb', so the minimum size if 4 bytes.
434 *
435 * The device may pass us events formatted differently than expected.
436 * These are first filtered, potentially creating a new event in a new
437 * memory location. If a new event is created by the filter it is also
438 * freed here.
439 *
440 * For each notif/event, tries to guess the size looking at the EST
441 * tables, then looks for a neh that is waiting for that event and if
442 * found, copies the payload to the neh's buffer and calls it back. If
443 * not, the data is ignored.
444 *
445 * Note that if we can't find a size description in the EST tables, we
446 * still might find a size in the 'neh' handle in uwb_rc_neh_lookup().
447 *
448 * Assumptions:
449 *
450 * @rc->neh_lock is NOT taken
451 *
452 * We keep track of various sizes here:
453 * size: contains the size of the buffer that is processed for the
454 * incoming event. this buffer may contain events that are not
455 * formatted as WHCI.
456 * real_size: the actual space taken by this event in the buffer.
457 * We need to keep track of the real size of an event to be able to
458 * advance the buffer correctly.
459 * event_size: the size of the event as expected by the core layer
460 * [OR] the size of the event after filtering. if the filtering
461 * created a new event in a new memory location then this is
462 * effectively the size of a new event buffer
463 */
464 void uwb_rc_neh_grok(struct uwb_rc *rc, void *buf, size_t buf_size)
465 {
466 struct device *dev = &rc->uwb_dev.dev;
467 void *itr;
468 struct uwb_rceb *rceb;
469 size_t size, real_size, event_size;
470 int needtofree;
471
472 itr = buf;
473 size = buf_size;
474 while (size > 0) {
475 if (size < sizeof(*rceb)) {
476 dev_err(dev, "not enough data in event buffer to "
477 "process incoming events (%zu left, minimum is "
478 "%zu)\n", size, sizeof(*rceb));
479 break;
480 }
481
482 rceb = itr;
483 if (rc->filter_event) {
484 needtofree = rc->filter_event(rc, &rceb, size,
485 &real_size, &event_size);
486 if (needtofree < 0 && needtofree != -ENOANO) {
487 dev_err(dev, "BUG: Unable to filter event "
488 "(0x%02x/%04x/%02x) from "
489 "device. \n", rceb->bEventType,
490 le16_to_cpu(rceb->wEvent),
491 rceb->bEventContext);
492 break;
493 }
494 } else
495 needtofree = -ENOANO;
496 /* do real processing if there was no filtering or the
497 * filtering didn't act */
498 if (needtofree == -ENOANO) {
499 ssize_t ret = uwb_est_find_size(rc, rceb, size);
500 if (ret < 0)
501 break;
502 if (ret > size) {
503 dev_err(dev, "BUG: hw sent incomplete event "
504 "0x%02x/%04x/%02x (%zd bytes), only got "
505 "%zu bytes. We don't handle that.\n",
506 rceb->bEventType, le16_to_cpu(rceb->wEvent),
507 rceb->bEventContext, ret, size);
508 break;
509 }
510 real_size = event_size = ret;
511 }
512 uwb_rc_neh_grok_event(rc, rceb, event_size);
513
514 if (needtofree == 1)
515 kfree(rceb);
516
517 itr += real_size;
518 size -= real_size;
519 }
520 }
521 EXPORT_SYMBOL_GPL(uwb_rc_neh_grok);
522
523
524 /**
525 * The entity that reads from the device notification/event channel has
526 * detected an error.
527 *
528 * @rc: UWB Radio Controller
529 * @error: Errno error code
530 *
531 */
532 void uwb_rc_neh_error(struct uwb_rc *rc, int error)
533 {
534 struct uwb_rc_neh *neh;
535 unsigned long flags;
536
537 for (;;) {
538 spin_lock_irqsave(&rc->neh_lock, flags);
539 if (list_empty(&rc->neh_list)) {
540 spin_unlock_irqrestore(&rc->neh_lock, flags);
541 break;
542 }
543 neh = list_first_entry(&rc->neh_list, struct uwb_rc_neh, list_node);
544 __uwb_rc_neh_rm(rc, neh);
545 spin_unlock_irqrestore(&rc->neh_lock, flags);
546
547 del_timer_sync(&neh->timer);
548 uwb_rc_neh_cb(neh, NULL, error);
549 }
550 }
551 EXPORT_SYMBOL_GPL(uwb_rc_neh_error);
552
553
554 static void uwb_rc_neh_timer(struct timer_list *t)
555 {
556 struct uwb_rc_neh *neh = from_timer(neh, t, timer);
557 struct uwb_rc *rc = neh->rc;
558 unsigned long flags;
559
560 spin_lock_irqsave(&rc->neh_lock, flags);
561 if (neh->completed) {
562 spin_unlock_irqrestore(&rc->neh_lock, flags);
563 return;
564 }
565 if (neh->context)
566 __uwb_rc_neh_rm(rc, neh);
567 else
568 neh = NULL;
569 spin_unlock_irqrestore(&rc->neh_lock, flags);
570
571 if (neh)
572 uwb_rc_neh_cb(neh, NULL, -ETIMEDOUT);
573 }
574
575 /** Initializes the @rc's neh subsystem
576 */
577 void uwb_rc_neh_create(struct uwb_rc *rc)
578 {
579 spin_lock_init(&rc->neh_lock);
580 INIT_LIST_HEAD(&rc->neh_list);
581 set_bit(0, rc->ctx_bm); /* 0 is reserved (see [WUSB] table 8-65) */
582 set_bit(0xff, rc->ctx_bm); /* and 0xff is invalid */
583 rc->ctx_roll = 1;
584 }
585
586
587 /** Release's the @rc's neh subsystem */
588 void uwb_rc_neh_destroy(struct uwb_rc *rc)
589 {
590 unsigned long flags;
591 struct uwb_rc_neh *neh;
592
593 for (;;) {
594 spin_lock_irqsave(&rc->neh_lock, flags);
595 if (list_empty(&rc->neh_list)) {
596 spin_unlock_irqrestore(&rc->neh_lock, flags);
597 break;
598 }
599 neh = list_first_entry(&rc->neh_list, struct uwb_rc_neh, list_node);
600 __uwb_rc_neh_rm(rc, neh);
601 spin_unlock_irqrestore(&rc->neh_lock, flags);
602
603 del_timer_sync(&neh->timer);
604 uwb_rc_neh_put(neh);
605 }
606 }