drivers/uwb/neh.c

   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 }