linux/drivers/uwb/neh.c
<<
>>
Prefs
   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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.