1/* 2 * WUSB Wire Adapter: Radio Control Interface (WUSB[8]) 3 * Notification and Event Handling 4 * 5 * Copyright (C) 2005-2006 Intel Corporation 6 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com> 7 * 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. 11 * 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. 16 * 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 20 * 02110-1301, USA. 21 * 22 * 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. 28 * 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. 34 * 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. 37 * 38 * So, as it is done is: 39 * 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 46 * 47 * If (2) fails, you should remove the handle [uwb_rc_neh_rm()] 48 * instead of arming the timer. 49 * 50 * Handles are for using in *serialized* code, single thread. 51 * 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. 56 * 57 * If the reader detects an error while reading the data stream, call 58 * uwb_rc_neh_error(). 59 * 60 * CONSTRAINTS/ASSUMPTIONS: 61 * 62 * - Most notifications/events are small (less thank .5k), copying 63 * around is ok. 64 * 65 * - Notifications/events are ALWAYS smaller than PAGE_SIZE 66 * 67 * - Notifications/events always come in a single piece (ie: a buffer 68 * will always contain entire notifications/events). 69 * 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()]. 76 * 77 * - Most notifications/events are fixed size; only a few are variable 78 * size (NEST takes care of that). 79 * 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. 83 */ 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> 89 90#include "uwb-internal.h" 91 92/* 93 * UWB Radio Controller Notification/Event Handle 94 * 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. 99 * 100 * If the timer expires before the event is received, the callback is 101 * called with -ETIMEDOUT as the event size. 102 */ 103struct uwb_rc_neh { 104 struct kref kref; 105 106 struct uwb_rc *rc; 107 u8 evt_type; 108 __le16 evt; 109 u8 context; 110 u8 completed; 111 uwb_rc_cmd_cb_f cb; 112 void *arg; 113 114 struct timer_list timer; 115 struct list_head list_node; 116}; 117 118static void uwb_rc_neh_timer(unsigned long arg); 119 120static void uwb_rc_neh_release(struct kref *kref) 121{ 122 struct uwb_rc_neh *neh = container_of(kref, struct uwb_rc_neh, kref); 123 124 kfree(neh); 125} 126 127static void uwb_rc_neh_get(struct uwb_rc_neh *neh) 128{ 129 kref_get(&neh->kref); 130} 131 132/** 133 * uwb_rc_neh_put - release reference to a neh 134 * @neh: the neh 135 */ 136void uwb_rc_neh_put(struct uwb_rc_neh *neh) 137{ 138 kref_put(&neh->kref, uwb_rc_neh_release); 139} 140 141 142/** 143 * Assigns @neh a context id from @rc's pool 144 * 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). 149 * 150 * (assumes @wa is locked). 151 * 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. 155 * 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 160 * search from zero. 161 */ 162static 163int __uwb_rc_ctx_get(struct uwb_rc *rc, struct uwb_rc_neh *neh) 164{ 165 int result; 166 result = find_next_zero_bit(rc->ctx_bm, UWB_RC_CTX_MAX, 167 rc->ctx_roll++); 168 if (result < UWB_RC_CTX_MAX) 169 goto found; 170 result = find_first_zero_bit(rc->ctx_bm, UWB_RC_CTX_MAX); 171 if (result < UWB_RC_CTX_MAX) 172 goto found; 173 return -ENFILE; 174found: 175 set_bit(result, rc->ctx_bm); 176 neh->context = result; 177 return 0; 178} 179 180 181/** Releases @neh's context ID back to @rc (@rc->neh_lock is locked). */ 182static 183void __uwb_rc_ctx_put(struct uwb_rc *rc, struct uwb_rc_neh *neh) 184{ 185 struct device *dev = &rc->uwb_dev.dev; 186 if (neh->context == 0) 187 return; 188 if (test_bit(neh->context, rc->ctx_bm) == 0) { 189 dev_err(dev, "context %u not set in bitmap\n", 190 neh->context); 191 WARN_ON(1); 192 } 193 clear_bit(neh->context, rc->ctx_bm); 194 neh->context = 0; 195} 196 197/** 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 205 * 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. 208 */ 209struct 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) 212{ 213 int result; 214 unsigned long flags; 215 struct device *dev = &rc->uwb_dev.dev; 216 struct uwb_rc_neh *neh; 217 218 neh = kzalloc(sizeof(*neh), GFP_KERNEL); 219 if (neh == NULL) { 220 result = -ENOMEM; 221 goto error_kzalloc; 222 } 223 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; 229 230 neh->rc = rc; 231 neh->evt_type = expected_type; 232 neh->evt = cpu_to_le16(expected_event); 233 neh->cb = cb; 234 neh->arg = arg; 235 236 spin_lock_irqsave(&rc->neh_lock, flags); 237 result = __uwb_rc_ctx_get(rc, neh); 238 if (result >= 0) { 239 cmd->bCommandContext = neh->context; 240 list_add_tail(&neh->list_node, &rc->neh_list); 241 uwb_rc_neh_get(neh); 242 } 243 spin_unlock_irqrestore(&rc->neh_lock, flags); 244 if (result < 0) 245 goto error_ctx_get; 246 247 return neh; 248 249error_ctx_get: 250 kfree(neh); 251error_kzalloc: 252 dev_err(dev, "cannot open handle to radio controller: %d\n", result); 253 return ERR_PTR(result); 254} 255 256static void __uwb_rc_neh_rm(struct uwb_rc *rc, struct uwb_rc_neh *neh) 257{ 258 __uwb_rc_ctx_put(rc, neh); 259 list_del(&neh->list_node); 260} 261 262/** 263 * uwb_rc_neh_rm - remove a neh. 264 * @rc: the radio controller 265 * @neh: the neh to remove 266 * 267 * Remove an active neh immediately instead of waiting for the event 268 * (or a time out). 269 */ 270void uwb_rc_neh_rm(struct uwb_rc *rc, struct uwb_rc_neh *neh) 271{ 272 unsigned long flags; 273 274 spin_lock_irqsave(&rc->neh_lock, flags); 275 __uwb_rc_neh_rm(rc, neh); 276 spin_unlock_irqrestore(&rc->neh_lock, flags); 277 278 del_timer_sync(&neh->timer); 279 uwb_rc_neh_put(neh); 280} 281 282/** 283 * uwb_rc_neh_arm - arm an event handler timeout timer 284 * 285 * @rc: UWB Radio Controller 286 * @neh: Notification/event handler for @rc 287 * 288 * The timer is only armed if the neh is active. 289 */ 290void uwb_rc_neh_arm(struct uwb_rc *rc, struct uwb_rc_neh *neh) 291{ 292 unsigned long flags; 293 294 spin_lock_irqsave(&rc->neh_lock, flags); 295 if (neh->context) 296 mod_timer(&neh->timer, 297 jiffies + msecs_to_jiffies(UWB_RC_CMD_TIMEOUT_MS)); 298 spin_unlock_irqrestore(&rc->neh_lock, flags); 299} 300 301static void uwb_rc_neh_cb(struct uwb_rc_neh *neh, struct uwb_rceb *rceb, size_t size) 302{ 303 (*neh->cb)(neh->rc, neh->arg, rceb, size); 304 uwb_rc_neh_put(neh); 305} 306 307static bool uwb_rc_neh_match(struct uwb_rc_neh *neh, const struct uwb_rceb *rceb) 308{ 309 return neh->evt_type == rceb->bEventType 310 && neh->evt == rceb->wEvent 311 && neh->context == rceb->bEventContext; 312} 313 314/** 315 * Find the handle waiting for a RC Radio Control Event 316 * 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 321 * settings. 322 * 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. 327 */ 328static 329struct uwb_rc_neh *uwb_rc_neh_lookup(struct uwb_rc *rc, 330 const struct uwb_rceb *rceb) 331{ 332 struct uwb_rc_neh *neh = NULL, *h; 333 unsigned long flags; 334 335 spin_lock_irqsave(&rc->neh_lock, flags); 336 337 list_for_each_entry(h, &rc->neh_list, list_node) { 338 if (uwb_rc_neh_match(h, rceb)) { 339 neh = h; 340 break; 341 } 342 } 343 344 if (neh) 345 __uwb_rc_neh_rm(rc, neh); 346 347 spin_unlock_irqrestore(&rc->neh_lock, flags); 348 349 return neh; 350} 351 352 353/* 354 * Process notifications coming from the radio control interface 355 * 356 * @rc: UWB Radio Control Interface descriptor 357 * @neh: Notification/Event Handler @neh->ptr points to 358 * @uwb_evt->buffer. 359 * 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). 364 * 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. 368 * 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. 372 * 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 377 */ 378static 379void uwb_rc_notif(struct uwb_rc *rc, struct uwb_rceb *rceb, ssize_t size) 380{ 381 struct device *dev = &rc->uwb_dev.dev; 382 struct uwb_event *uwb_evt; 383 384 if (size == -ESHUTDOWN) 385 return; 386 if (size < 0) { 387 dev_err(dev, "ignoring event with error code %zu\n", 388 size); 389 return; 390 } 391 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); 397 return; 398 } 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; 404 405 uwbd_event_queue(uwb_evt); 406} 407 408static void uwb_rc_neh_grok_event(struct uwb_rc *rc, struct uwb_rceb *rceb, size_t size) 409{ 410 struct device *dev = &rc->uwb_dev.dev; 411 struct uwb_rc_neh *neh; 412 struct uwb_rceb *notif; 413 unsigned long flags; 414 415 if (rceb->bEventContext == 0) { 416 notif = kmalloc(size, GFP_ATOMIC); 417 if (notif) { 418 memcpy(notif, rceb, size); 419 uwb_rc_notif(rc, notif, size); 420 } else 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); 424 } else { 425 neh = uwb_rc_neh_lookup(rc, rceb); 426 if (neh) { 427 spin_lock_irqsave(&rc->neh_lock, flags); 428 /* to guard against a timeout */ 429 neh->completed = 1; 430 del_timer(&neh->timer); 431 spin_unlock_irqrestore(&rc->neh_lock, flags); 432 uwb_rc_neh_cb(neh, rceb, size); 433 } else 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); 437 } 438} 439 440/** 441 * Given a buffer with one or more UWB RC events/notifications, break 442 * them up and dispatch them. 443 * 444 * @rc: UWB Radio Controller 445 * @buf: Buffer with the stream of notifications/events 446 * @buf_size: Amount of data in the buffer 447 * 448 * Note each notification/event starts always with a 'struct 449 * uwb_rceb', so the minimum size if 4 bytes. 450 * 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 454 * freed here. 455 * 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. 460 * 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(). 463 * 464 * Assumptions: 465 * 466 * @rc->neh_lock is NOT taken 467 * 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 471 * formatted as WHCI. 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 479 */ 480void uwb_rc_neh_grok(struct uwb_rc *rc, void *buf, size_t buf_size) 481{ 482 struct device *dev = &rc->uwb_dev.dev; 483 void *itr; 484 struct uwb_rceb *rceb; 485 size_t size, real_size, event_size; 486 int needtofree; 487 488 itr = buf; 489 size = buf_size; 490 while (size > 0) { 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)); 495 break; 496 } 497 498 rceb = itr; 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); 508 break; 509 } 510 } else 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); 516 if (ret < 0) 517 break; 518 if (ret > 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); 524 break; 525 } 526 real_size = event_size = ret; 527 } 528 uwb_rc_neh_grok_event(rc, rceb, event_size); 529 530 if (needtofree == 1) 531 kfree(rceb); 532 533 itr += real_size; 534 size -= real_size; 535 } 536} 537EXPORT_SYMBOL_GPL(uwb_rc_neh_grok); 538 539 540/** 541 * The entity that reads from the device notification/event channel has 542 * detected an error. 543 * 544 * @rc: UWB Radio Controller 545 * @error: Errno error code 546 * 547 */ 548void uwb_rc_neh_error(struct uwb_rc *rc, int error) 549{ 550 struct uwb_rc_neh *neh; 551 unsigned long flags; 552 553 for (;;) { 554 spin_lock_irqsave(&rc->neh_lock, flags); 555 if (list_empty(&rc->neh_list)) { 556 spin_unlock_irqrestore(&rc->neh_lock, flags); 557 break; 558 } 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); 562 563 del_timer_sync(&neh->timer); 564 uwb_rc_neh_cb(neh, NULL, error); 565 } 566} 567EXPORT_SYMBOL_GPL(uwb_rc_neh_error); 568 569 570static void uwb_rc_neh_timer(unsigned long arg) 571{ 572 struct uwb_rc_neh *neh = (struct uwb_rc_neh *)arg; 573 struct uwb_rc *rc = neh->rc; 574 unsigned long flags; 575 576 spin_lock_irqsave(&rc->neh_lock, flags); 577 if (neh->completed) { 578 spin_unlock_irqrestore(&rc->neh_lock, flags); 579 return; 580 } 581 if (neh->context) 582 __uwb_rc_neh_rm(rc, neh); 583 else 584 neh = NULL; 585 spin_unlock_irqrestore(&rc->neh_lock, flags); 586 587 if (neh) 588 uwb_rc_neh_cb(neh, NULL, -ETIMEDOUT); 589} 590 591/** Initializes the @rc's neh subsystem 592 */ 593void uwb_rc_neh_create(struct uwb_rc *rc) 594{ 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 */ 599 rc->ctx_roll = 1; 600} 601 602 603/** Release's the @rc's neh subsystem */ 604void uwb_rc_neh_destroy(struct uwb_rc *rc) 605{ 606 unsigned long flags; 607 struct uwb_rc_neh *neh; 608 609 for (;;) { 610 spin_lock_irqsave(&rc->neh_lock, flags); 611 if (list_empty(&rc->neh_list)) { 612 spin_unlock_irqrestore(&rc->neh_lock, flags); 613 break; 614 } 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); 618 619 del_timer_sync(&neh->timer); 620 uwb_rc_neh_put(neh); 621 } 622} 623