include/linux/uwb.h

   1 /*
   2  * Ultra Wide Band
   3  * UWB API
   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  * FIXME: doc: overview of the API, different parts and pointers
  24  */
  25
  26 #ifndef __LINUX__UWB_H__
  27 #define __LINUX__UWB_H__
  28
  29 #include <linux/limits.h>
  30 #include <linux/device.h>
  31 #include <linux/mutex.h>
  32 #include <linux/timer.h>
  33 #include <linux/wait.h>
  34 #include <linux/workqueue.h>
  35 #include <linux/uwb/spec.h>
  36
  37 struct uwb_dev;
  38 struct uwb_beca_e;
  39 struct uwb_rc;
  40 struct uwb_rsv;
  41 struct uwb_dbg;
  42
  43 /**
  44  * struct uwb_dev - a UWB Device
  45  * @rc: UWB Radio Controller that discovered the device (kind of its
  46  *     parent).
  47  * @bce: a beacon cache entry for this device; or NULL if the device
  48  *     is a local radio controller.
  49  * @mac_addr: the EUI-48 address of this device.
  50  * @dev_addr: the current DevAddr used by this device.
  51  * @beacon_slot: the slot number the beacon is using.
  52  * @streams: bitmap of streams allocated to reservations targeted at
  53  *     this device.  For an RC, this is the streams allocated for
  54  *     reservations targeted at DevAddrs.
  55  *
  56  * A UWB device may either by a neighbor or part of a local radio
  57  * controller.
  58  */
  59 struct uwb_dev {
  60         struct mutex mutex;
  61         struct list_head list_node;
  62         struct device dev;
  63         struct uwb_rc *rc;              /* radio controller */
  64         struct uwb_beca_e *bce;         /* Beacon Cache Entry */
  65
  66         struct uwb_mac_addr mac_addr;
  67         struct uwb_dev_addr dev_addr;
  68         int beacon_slot;
  69         DECLARE_BITMAP(streams, UWB_NUM_STREAMS);
  70         DECLARE_BITMAP(last_availability_bm, UWB_NUM_MAS);
  71 };
  72 #define to_uwb_dev(d) container_of(d, struct uwb_dev, dev)
  73
  74 /**
  75  * UWB HWA/WHCI Radio Control {Command|Event} Block context IDs
  76  *
  77  * RC[CE]Bs have a 'context ID' field that matches the command with
  78  * the event received to confirm it.
  79  *
  80  * Maximum number of context IDs
  81  */
  82 enum { UWB_RC_CTX_MAX = 256 };
  83
  84
  85 /** Notification chain head for UWB generated events to listeners */
  86 struct uwb_notifs_chain {
  87         struct list_head list;
  88         struct mutex mutex;
  89 };
  90
  91 /* Beacon cache list */
  92 struct uwb_beca {
  93         struct list_head list;
  94         size_t entries;
  95         struct mutex mutex;
  96 };
  97
  98 /* Event handling thread. */
  99 struct uwbd {
 100         int pid;
 101         struct task_struct *task;
 102         wait_queue_head_t wq;
 103         struct list_head event_list;
 104         spinlock_t event_list_lock;
 105 };
 106
 107 /**
 108  * struct uwb_mas_bm - a bitmap of all MAS in a superframe
 109  * @bm: a bitmap of length #UWB_NUM_MAS
 110  */
 111 struct uwb_mas_bm {
 112         DECLARE_BITMAP(bm, UWB_NUM_MAS);
 113         DECLARE_BITMAP(unsafe_bm, UWB_NUM_MAS);
 114         int safe;
 115         int unsafe;
 116 };
 117
 118 /**
 119  * uwb_rsv_state - UWB Reservation state.
 120  *
 121  * NONE - reservation is not active (no DRP IE being transmitted).
 122  *
 123  * Owner reservation states:
 124  *
 125  * INITIATED - owner has sent an initial DRP request.
 126  * PENDING - target responded with pending Reason Code.
 127  * MODIFIED - reservation manager is modifying an established
 128  * reservation with a different MAS allocation.
 129  * ESTABLISHED - the reservation has been successfully negotiated.
 130  *
 131  * Target reservation states:
 132  *
 133  * DENIED - request is denied.
 134  * ACCEPTED - request is accepted.
 135  * PENDING - PAL has yet to make a decision to whether to accept or
 136  * deny.
 137  *
 138  * FIXME: further target states TBD.
 139  */
 140 enum uwb_rsv_state {
 141         UWB_RSV_STATE_NONE = 0,
 142         UWB_RSV_STATE_O_INITIATED,
 143         UWB_RSV_STATE_O_PENDING,
 144         UWB_RSV_STATE_O_MODIFIED,
 145         UWB_RSV_STATE_O_ESTABLISHED,
 146         UWB_RSV_STATE_O_TO_BE_MOVED,
 147         UWB_RSV_STATE_O_MOVE_EXPANDING,
 148         UWB_RSV_STATE_O_MOVE_COMBINING,
 149         UWB_RSV_STATE_O_MOVE_REDUCING,
 150         UWB_RSV_STATE_T_ACCEPTED,
 151         UWB_RSV_STATE_T_DENIED,
 152         UWB_RSV_STATE_T_CONFLICT,
 153         UWB_RSV_STATE_T_PENDING,
 154         UWB_RSV_STATE_T_EXPANDING_ACCEPTED,
 155         UWB_RSV_STATE_T_EXPANDING_CONFLICT,
 156         UWB_RSV_STATE_T_EXPANDING_PENDING,
 157         UWB_RSV_STATE_T_EXPANDING_DENIED,
 158         UWB_RSV_STATE_T_RESIZED,
 159
 160         UWB_RSV_STATE_LAST,
 161 };
 162
 163 enum uwb_rsv_target_type {
 164         UWB_RSV_TARGET_DEV,
 165         UWB_RSV_TARGET_DEVADDR,
 166 };
 167
 168 /**
 169  * struct uwb_rsv_target - the target of a reservation.
 170  *
 171  * Reservations unicast and targeted at a single device
 172  * (UWB_RSV_TARGET_DEV); or (e.g., in the case of WUSB) targeted at a
 173  * specific (private) DevAddr (UWB_RSV_TARGET_DEVADDR).
 174  */
 175 struct uwb_rsv_target {
 176         enum uwb_rsv_target_type type;
 177         union {
 178                 struct uwb_dev *dev;
 179                 struct uwb_dev_addr devaddr;
 180         };
 181 };
 182
 183 struct uwb_rsv_move {
 184         struct uwb_mas_bm final_mas;
 185         struct uwb_ie_drp *companion_drp_ie;
 186         struct uwb_mas_bm companion_mas;
 187 };
 188
 189 /*
 190  * Number of streams reserved for reservations targeted at DevAddrs.
 191  */
 192 #define UWB_NUM_GLOBAL_STREAMS 1
 193
 194 typedef void (*uwb_rsv_cb_f)(struct uwb_rsv *rsv);
 195
 196 /**
 197  * struct uwb_rsv - a DRP reservation
 198  *
 199  * Data structure management:
 200  *
 201  * @rc:             the radio controller this reservation is for
 202  *                  (as target or owner)
 203  * @rc_node:        a list node for the RC
 204  * @pal_node:       a list node for the PAL
 205  *
 206  * Owner and target parameters:
 207  *
 208  * @owner:          the UWB device owning this reservation
 209  * @target:         the target UWB device
 210  * @type:           reservation type
 211  *
 212  * Owner parameters:
 213  *
 214  * @max_mas:        maxiumum number of MAS
 215  * @min_mas:        minimum number of MAS
 216  * @sparsity:       owner selected sparsity
 217  * @is_multicast:   true iff multicast
 218  *
 219  * @callback:       callback function when the reservation completes
 220  * @pal_priv:       private data for the PAL making the reservation
 221  *
 222  * Reservation status:
 223  *
 224  * @status:         negotiation status
 225  * @stream:         stream index allocated for this reservation
 226  * @tiebreaker:     conflict tiebreaker for this reservation
 227  * @mas:            reserved MAS
 228  * @drp_ie:         the DRP IE
 229  * @ie_valid:       true iff the DRP IE matches the reservation parameters
 230  *
 231  * DRP reservations are uniquely identified by the owner, target and
 232  * stream index.  However, when using a DevAddr as a target (e.g., for
 233  * a WUSB cluster reservation) the responses may be received from
 234  * devices with different DevAddrs.  In this case, reservations are
 235  * uniquely identified by just the stream index.  A number of stream
 236  * indexes (UWB_NUM_GLOBAL_STREAMS) are reserved for this.
 237  */
 238 struct uwb_rsv {
 239         struct uwb_rc *rc;
 240         struct list_head rc_node;
 241         struct list_head pal_node;
 242         struct kref kref;
 243
 244         struct uwb_dev *owner;
 245         struct uwb_rsv_target target;
 246         enum uwb_drp_type type;
 247         int max_mas;
 248         int min_mas;
 249         int max_interval;
 250         bool is_multicast;
 251
 252         uwb_rsv_cb_f callback;
 253         void *pal_priv;
 254
 255         enum uwb_rsv_state state;
 256         bool needs_release_companion_mas;
 257         u8 stream;
 258         u8 tiebreaker;
 259         struct uwb_mas_bm mas;
 260         struct uwb_ie_drp *drp_ie;
 261         struct uwb_rsv_move mv;
 262         bool ie_valid;
 263         struct timer_list timer;
 264         struct work_struct handle_timeout_work;
 265 };
 266
 267 static const
 268 struct uwb_mas_bm uwb_mas_bm_zero = { .bm = { 0 } };
 269
 270 static inline void uwb_mas_bm_copy_le(void *dst, const struct uwb_mas_bm *mas)
 271 {
 272         bitmap_copy_le(dst, mas->bm, UWB_NUM_MAS);
 273 }
 274
 275 /**
 276  * struct uwb_drp_avail - a radio controller's view of MAS usage
 277  * @global:   MAS unused by neighbors (excluding reservations targetted
 278  *            or owned by the local radio controller) or the beaon period
 279  * @local:    MAS unused by local established reservations
 280  * @pending:  MAS unused by local pending reservations
 281  * @ie:       DRP Availability IE to be included in the beacon
 282  * @ie_valid: true iff @ie is valid and does not need to regenerated from
 283  *            @global and @local
 284  *
 285  * Each radio controller maintains a view of MAS usage or
 286  * availability. MAS available for a new reservation are determined
 287  * from the intersection of @global, @local, and @pending.
 288  *
 289  * The radio controller must transmit a DRP Availability IE that's the
 290  * intersection of @global and @local.
 291  *
 292  * A set bit indicates the MAS is unused and available.
 293  *
 294  * rc->rsvs_mutex should be held before accessing this data structure.
 295  *
 296  * [ECMA-368] section 17.4.3.
 297  */
 298 struct uwb_drp_avail {
 299         DECLARE_BITMAP(global, UWB_NUM_MAS);
 300         DECLARE_BITMAP(local, UWB_NUM_MAS);
 301         DECLARE_BITMAP(pending, UWB_NUM_MAS);
 302         struct uwb_ie_drp_avail ie;
 303         bool ie_valid;
 304 };
 305
 306 struct uwb_drp_backoff_win {
 307         u8 window;
 308         u8 n;
 309         int total_expired;
 310         struct timer_list timer;
 311         bool can_reserve_extra_mases;
 312 };
 313
 314 const char *uwb_rsv_state_str(enum uwb_rsv_state state);
 315 const char *uwb_rsv_type_str(enum uwb_drp_type type);
 316
 317 struct uwb_rsv *uwb_rsv_create(struct uwb_rc *rc, uwb_rsv_cb_f cb,
 318                                void *pal_priv);
 319 void uwb_rsv_destroy(struct uwb_rsv *rsv);
 320
 321 int uwb_rsv_establish(struct uwb_rsv *rsv);
 322 int uwb_rsv_modify(struct uwb_rsv *rsv,
 323                    int max_mas, int min_mas, int sparsity);
 324 void uwb_rsv_terminate(struct uwb_rsv *rsv);
 325
 326 void uwb_rsv_accept(struct uwb_rsv *rsv, uwb_rsv_cb_f cb, void *pal_priv);
 327
 328 void uwb_rsv_get_usable_mas(struct uwb_rsv *orig_rsv, struct uwb_mas_bm *mas);
 329
 330 /**
 331  * Radio Control Interface instance
 332  *
 333  *
 334  * Life cycle rules: those of the UWB Device.
 335  *
 336  * @index:    an index number for this radio controller, as used in the
 337  *            device name.
 338  * @version:  version of protocol supported by this device
 339  * @priv:     Backend implementation; rw with uwb_dev.dev.sem taken.
 340  * @cmd:      Backend implementation to execute commands; rw and call
 341  *            only  with uwb_dev.dev.sem taken.
 342  * @reset:    Hardware reset of radio controller and any PAL controllers.
 343  * @filter:   Backend implementation to manipulate data to and from device
 344  *            to be compliant to specification assumed by driver (WHCI
 345  *            0.95).
 346  *
 347  *            uwb_dev.dev.mutex is used to execute commands and update
 348  *            the corresponding structures; can't use a spinlock
 349  *            because rc->cmd() can sleep.
 350  * @ies:         This is a dynamically allocated array cacheing the
 351  *               IEs (settable by the host) that the beacon of this
 352  *               radio controller is currently sending.
 353  *
 354  *               In reality, we store here the full command we set to
 355  *               the radio controller (which is basically a command
 356  *               prefix followed by all the IEs the beacon currently
 357  *               contains). This way we don't have to realloc and
 358  *               memcpy when setting it.
 359  *
 360  *               We set this up in uwb_rc_ie_setup(), where we alloc
 361  *               this struct, call get_ie() [so we know which IEs are
 362  *               currently being sent, if any].
 363  *
 364  * @ies_capacity:Amount of space (in bytes) allocated in @ies. The
 365  *               amount used is given by sizeof(*ies) plus ies->wIELength
 366  *               (which is a little endian quantity all the time).
 367  * @ies_mutex:   protect the IE cache
 368  * @dbg:         information for the debug interface
 369  */
 370 struct uwb_rc {
 371         struct uwb_dev uwb_dev;
 372         int index;
 373         u16 version;
 374
 375         struct module *owner;
 376         void *priv;
 377         int (*start)(struct uwb_rc *rc);
 378         void (*stop)(struct uwb_rc *rc);
 379         int (*cmd)(struct uwb_rc *, const struct uwb_rccb *, size_t);
 380         int (*reset)(struct uwb_rc *rc);
 381         int (*filter_cmd)(struct uwb_rc *, struct uwb_rccb **, size_t *);
 382         int (*filter_event)(struct uwb_rc *, struct uwb_rceb **, const size_t,
 383                             size_t *, size_t *);
 384
 385         spinlock_t neh_lock;            /* protects neh_* and ctx_* */
 386         struct list_head neh_list;      /* Open NE handles */
 387         unsigned long ctx_bm[UWB_RC_CTX_MAX / 8 / sizeof(unsigned long)];
 388         u8 ctx_roll;
 389
 390         int beaconing;                  /* Beaconing state [channel number] */
 391         int beaconing_forced;
 392         int scanning;
 393         enum uwb_scan_type scan_type:3;
 394         unsigned ready:1;
 395         struct uwb_notifs_chain notifs_chain;
 396         struct uwb_beca uwb_beca;
 397
 398         struct uwbd uwbd;
 399
 400         struct uwb_drp_backoff_win bow;
 401         struct uwb_drp_avail drp_avail;
 402         struct list_head reservations;
 403         struct list_head cnflt_alien_list;
 404         struct uwb_mas_bm cnflt_alien_bitmap;
 405         struct mutex rsvs_mutex;
 406         spinlock_t rsvs_lock;
 407         struct workqueue_struct *rsv_workq;
 408
 409         struct delayed_work rsv_update_work;
 410         struct delayed_work rsv_alien_bp_work;
 411         int set_drp_ie_pending;
 412         struct mutex ies_mutex;
 413         struct uwb_rc_cmd_set_ie *ies;
 414         size_t ies_capacity;
 415
 416         struct list_head pals;
 417         int active_pals;
 418
 419         struct uwb_dbg *dbg;
 420 };
 421
 422
 423 /**
 424  * struct uwb_pal - a UWB PAL
 425  * @name:    descriptive name for this PAL (wusbhc, wlp, etc.).
 426  * @device:  a device for the PAL.  Used to link the PAL and the radio
 427  *           controller in sysfs.
 428  * @rc:      the radio controller the PAL uses.
 429  * @channel_changed: called when the channel used by the radio changes.
 430  *           A channel of -1 means the channel has been stopped.
 431  * @new_rsv: called when a peer requests a reservation (may be NULL if
 432  *           the PAL cannot accept reservation requests).
 433  * @channel: channel being used by the PAL; 0 if the PAL isn't using
 434  *           the radio; -1 if the PAL wishes to use the radio but
 435  *           cannot.
 436  * @debugfs_dir: a debugfs directory which the PAL can use for its own
 437  *           debugfs files.
 438  *
 439  * A Protocol Adaptation Layer (PAL) is a user of the WiMedia UWB
 440  * radio platform (e.g., WUSB, WLP or Bluetooth UWB AMP).
 441  *
 442  * The PALs using a radio controller must register themselves to
 443  * permit the UWB stack to coordinate usage of the radio between the
 444  * various PALs or to allow PALs to response to certain requests from
 445  * peers.
 446  *
 447  * A struct uwb_pal should be embedded in a containing structure
 448  * belonging to the PAL and initialized with uwb_pal_init()).  Fields
 449  * should be set appropriately by the PAL before registering the PAL
 450  * with uwb_pal_register().
 451  */
 452 struct uwb_pal {
 453         struct list_head node;
 454         const char *name;
 455         struct device *device;
 456         struct uwb_rc *rc;
 457
 458         void (*channel_changed)(struct uwb_pal *pal, int channel);
 459         void (*new_rsv)(struct uwb_pal *pal, struct uwb_rsv *rsv);
 460
 461         int channel;
 462         struct dentry *debugfs_dir;
 463 };
 464
 465 void uwb_pal_init(struct uwb_pal *pal);
 466 int uwb_pal_register(struct uwb_pal *pal);
 467 void uwb_pal_unregister(struct uwb_pal *pal);
 468
 469 int uwb_radio_start(struct uwb_pal *pal);
 470 void uwb_radio_stop(struct uwb_pal *pal);
 471
 472 /*
 473  * General public API
 474  *
 475  * This API can be used by UWB device drivers or by those implementing
 476  * UWB Radio Controllers
 477  */
 478 struct uwb_dev *uwb_dev_get_by_devaddr(struct uwb_rc *rc,
 479                                        const struct uwb_dev_addr *devaddr);
 480 struct uwb_dev *uwb_dev_get_by_rc(struct uwb_dev *, struct uwb_rc *);
 481 static inline void uwb_dev_get(struct uwb_dev *uwb_dev)
 482 {
 483         get_device(&uwb_dev->dev);
 484 }
 485 static inline void uwb_dev_put(struct uwb_dev *uwb_dev)
 486 {
 487         put_device(&uwb_dev->dev);
 488 }
 489 struct uwb_dev *uwb_dev_try_get(struct uwb_rc *rc, struct uwb_dev *uwb_dev);
 490
 491 /**
 492  * Callback function for 'uwb_{dev,rc}_foreach()'.
 493  *
 494  * @dev:  Linux device instance
 495  *        'uwb_dev = container_of(dev, struct uwb_dev, dev)'
 496  * @priv: Data passed by the caller to 'uwb_{dev,rc}_foreach()'.
 497  *
 498  * @returns: 0 to continue the iterations, any other val to stop
 499  *           iterating and return the value to the caller of
 500  *           _foreach().
 501  */
 502 typedef int (*uwb_dev_for_each_f)(struct device *dev, void *priv);
 503 int uwb_dev_for_each(struct uwb_rc *rc, uwb_dev_for_each_f func, void *priv);
 504
 505 struct uwb_rc *uwb_rc_alloc(void);
 506 struct uwb_rc *uwb_rc_get_by_dev(const struct uwb_dev_addr *);
 507 struct uwb_rc *uwb_rc_get_by_grandpa(const struct device *);
 508 void uwb_rc_put(struct uwb_rc *rc);
 509
 510 typedef void (*uwb_rc_cmd_cb_f)(struct uwb_rc *rc, void *arg,
 511                                 struct uwb_rceb *reply, ssize_t reply_size);
 512
 513 int uwb_rc_cmd_async(struct uwb_rc *rc, const char *cmd_name,
 514                      struct uwb_rccb *cmd, size_t cmd_size,
 515                      u8 expected_type, u16 expected_event,
 516                      uwb_rc_cmd_cb_f cb, void *arg);
 517 ssize_t uwb_rc_cmd(struct uwb_rc *rc, const char *cmd_name,
 518                    struct uwb_rccb *cmd, size_t cmd_size,
 519                    struct uwb_rceb *reply, size_t reply_size);
 520 ssize_t uwb_rc_vcmd(struct uwb_rc *rc, const char *cmd_name,
 521                     struct uwb_rccb *cmd, size_t cmd_size,
 522                     u8 expected_type, u16 expected_event,
 523                     struct uwb_rceb **preply);
 524
 525 size_t __uwb_addr_print(char *, size_t, const unsigned char *, int);
 526
 527 int uwb_rc_dev_addr_set(struct uwb_rc *, const struct uwb_dev_addr *);
 528 int uwb_rc_dev_addr_get(struct uwb_rc *, struct uwb_dev_addr *);
 529 int uwb_rc_mac_addr_set(struct uwb_rc *, const struct uwb_mac_addr *);
 530 int uwb_rc_mac_addr_get(struct uwb_rc *, struct uwb_mac_addr *);
 531 int __uwb_mac_addr_assigned_check(struct device *, void *);
 532 int __uwb_dev_addr_assigned_check(struct device *, void *);
 533
 534 /* Print in @buf a pretty repr of @addr */
 535 static inline size_t uwb_dev_addr_print(char *buf, size_t buf_size,
 536                                         const struct uwb_dev_addr *addr)
 537 {
 538         return __uwb_addr_print(buf, buf_size, addr->data, 0);
 539 }
 540
 541 /* Print in @buf a pretty repr of @addr */
 542 static inline size_t uwb_mac_addr_print(char *buf, size_t buf_size,
 543                                         const struct uwb_mac_addr *addr)
 544 {
 545         return __uwb_addr_print(buf, buf_size, addr->data, 1);
 546 }
 547
 548 /* @returns 0 if device addresses @addr2 and @addr1 are equal */
 549 static inline int uwb_dev_addr_cmp(const struct uwb_dev_addr *addr1,
 550                                    const struct uwb_dev_addr *addr2)
 551 {
 552         return memcmp(addr1, addr2, sizeof(*addr1));
 553 }
 554
 555 /* @returns 0 if MAC addresses @addr2 and @addr1 are equal */
 556 static inline int uwb_mac_addr_cmp(const struct uwb_mac_addr *addr1,
 557                                    const struct uwb_mac_addr *addr2)
 558 {
 559         return memcmp(addr1, addr2, sizeof(*addr1));
 560 }
 561
 562 /* @returns !0 if a MAC @addr is a broadcast address */
 563 static inline int uwb_mac_addr_bcast(const struct uwb_mac_addr *addr)
 564 {
 565         struct uwb_mac_addr bcast = {
 566                 .data = { 0xff, 0xff, 0xff, 0xff, 0xff, 0xff }
 567         };
 568         return !uwb_mac_addr_cmp(addr, &bcast);
 569 }
 570
 571 /* @returns !0 if a MAC @addr is all zeroes*/
 572 static inline int uwb_mac_addr_unset(const struct uwb_mac_addr *addr)
 573 {
 574         struct uwb_mac_addr unset = {
 575                 .data = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }
 576         };
 577         return !uwb_mac_addr_cmp(addr, &unset);
 578 }
 579
 580 /* @returns !0 if the address is in use. */
 581 static inline unsigned __uwb_dev_addr_assigned(struct uwb_rc *rc,
 582                                                struct uwb_dev_addr *addr)
 583 {
 584         return uwb_dev_for_each(rc, __uwb_dev_addr_assigned_check, addr);
 585 }
 586
 587 /*
 588  * UWB Radio Controller API
 589  *
 590  * This API is used (in addition to the general API) to implement UWB
 591  * Radio Controllers.
 592  */
 593 void uwb_rc_init(struct uwb_rc *);
 594 int uwb_rc_add(struct uwb_rc *, struct device *dev, void *rc_priv);
 595 void uwb_rc_rm(struct uwb_rc *);
 596 void uwb_rc_neh_grok(struct uwb_rc *, void *, size_t);
 597 void uwb_rc_neh_error(struct uwb_rc *, int);
 598 void uwb_rc_reset_all(struct uwb_rc *rc);
 599 void uwb_rc_pre_reset(struct uwb_rc *rc);
 600 int uwb_rc_post_reset(struct uwb_rc *rc);
 601
 602 /**
 603  * uwb_rsv_is_owner - is the owner of this reservation the RC?
 604  * @rsv: the reservation
 605  */
 606 static inline bool uwb_rsv_is_owner(struct uwb_rsv *rsv)
 607 {
 608         return rsv->owner == &rsv->rc->uwb_dev;
 609 }
 610
 611 /**
 612  * enum uwb_notifs - UWB events that can be passed to any listeners
 613  * @UWB_NOTIF_ONAIR: a new neighbour has joined the beacon group.
 614  * @UWB_NOTIF_OFFAIR: a neighbour has left the beacon group.
 615  *
 616  * Higher layers can register callback functions with the radio
 617  * controller using uwb_notifs_register(). The radio controller
 618  * maintains a list of all registered handlers and will notify all
 619  * nodes when an event occurs.
 620  */
 621 enum uwb_notifs {
 622         UWB_NOTIF_ONAIR,
 623         UWB_NOTIF_OFFAIR,
 624 };
 625
 626 /* Callback function registered with UWB */
 627 struct uwb_notifs_handler {
 628         struct list_head list_node;
 629         void (*cb)(void *, struct uwb_dev *, enum uwb_notifs);
 630         void *data;
 631 };
 632
 633 int uwb_notifs_register(struct uwb_rc *, struct uwb_notifs_handler *);
 634 int uwb_notifs_deregister(struct uwb_rc *, struct uwb_notifs_handler *);
 635
 636
 637 /**
 638  * UWB radio controller Event Size Entry (for creating entry tables)
 639  *
 640  * WUSB and WHCI define events and notifications, and they might have
 641  * fixed or variable size.
 642  *
 643  * Each event/notification has a size which is not necessarily known
 644  * in advance based on the event code. As well, vendor specific
 645  * events/notifications will have a size impossible to determine
 646  * unless we know about the device's specific details.
 647  *
 648  * It was way too smart of the spec writers not to think that it would
 649  * be impossible for a generic driver to skip over vendor specific
 650  * events/notifications if there are no LENGTH fields in the HEADER of
 651  * each message...the transaction size cannot be counted on as the
 652  * spec does not forbid to pack more than one event in a single
 653  * transaction.
 654  *
 655  * Thus, we guess sizes with tables (or for events, when you know the
 656  * size ahead of time you can use uwb_rc_neh_extra_size*()). We
 657  * register tables with the known events and their sizes, and then we
 658  * traverse those tables. For those with variable length, we provide a
 659  * way to lookup the size inside the event/notification's
 660  * payload. This allows device-specific event size tables to be
 661  * registered.
 662  *
 663  * @size:   Size of the payload
 664  *
 665  * @offset: if != 0, at offset @offset-1 starts a field with a length
 666  *          that has to be added to @size. The format of the field is
 667  *          given by @type.
 668  *
 669  * @type:   Type and length of the offset field. Most common is LE 16
 670  *          bits (that's why that is zero); others are there mostly to
 671  *          cover for bugs and weirdos.
 672  */
 673 struct uwb_est_entry {
 674         size_t size;
 675         unsigned offset;
 676         enum { UWB_EST_16 = 0, UWB_EST_8 = 1 } type;
 677 };
 678
 679 int uwb_est_register(u8 type, u8 code_high, u16 vendor, u16 product,
 680                      const struct uwb_est_entry *, size_t entries);
 681 int uwb_est_unregister(u8 type, u8 code_high, u16 vendor, u16 product,
 682                        const struct uwb_est_entry *, size_t entries);
 683 ssize_t uwb_est_find_size(struct uwb_rc *rc, const struct uwb_rceb *rceb,
 684                           size_t len);
 685
 686 /* -- Misc */
 687
 688 enum {
 689         EDC_MAX_ERRORS = 10,
 690         EDC_ERROR_TIMEFRAME = HZ,
 691 };
 692
 693 /* error density counter */
 694 struct edc {
 695         unsigned long timestart;
 696         u16 errorcount;
 697 };
 698
 699 static inline
 700 void edc_init(struct edc *edc)
 701 {
 702         edc->timestart = jiffies;
 703 }
 704
 705 /* Called when an error occured.
 706  * This is way to determine if the number of acceptable errors per time
 707  * period has been exceeded. It is not accurate as there are cases in which
 708  * this scheme will not work, for example if there are periodic occurences
 709  * of errors that straddle updates to the start time. This scheme is
 710  * sufficient for our usage.
 711  *
 712  * @returns 1 if maximum acceptable errors per timeframe has been exceeded.
 713  */
 714 static inline int edc_inc(struct edc *err_hist, u16 max_err, u16 timeframe)
 715 {
 716         unsigned long now;
 717
 718         now = jiffies;
 719         if (now - err_hist->timestart > timeframe) {
 720                 err_hist->errorcount = 1;
 721                 err_hist->timestart = now;
 722         } else if (++err_hist->errorcount > max_err) {
 723                         err_hist->errorcount = 0;
 724                         err_hist->timestart = now;
 725                         return 1;
 726         }
 727         return 0;
 728 }
 729
 730
 731 /* Information Element handling */
 732
 733 struct uwb_ie_hdr *uwb_ie_next(void **ptr, size_t *len);
 734 int uwb_rc_ie_add(struct uwb_rc *uwb_rc, const struct uwb_ie_hdr *ies, size_t size);
 735 int uwb_rc_ie_rm(struct uwb_rc *uwb_rc, enum uwb_ie element_id);
 736
 737 /*
 738  * Transmission statistics
 739  *
 740  * UWB uses LQI and RSSI (one byte values) for reporting radio signal
 741  * strength and line quality indication. We do quick and dirty
 742  * averages of those. They are signed values, btw.
 743  *
 744  * For 8 bit quantities, we keep the min, the max, an accumulator
 745  * (@sigma) and a # of samples. When @samples gets to 255, we compute
 746  * the average (@sigma / @samples), place it in @sigma and reset
 747  * @samples to 1 (so we use it as the first sample).
 748  *
 749  * Now, statistically speaking, probably I am kicking the kidneys of
 750  * some books I have in my shelves collecting dust, but I just want to
 751  * get an approx, not the Nobel.
 752  *
 753  * LOCKING: there is no locking per se, but we try to keep a lockless
 754  * schema. Only _add_samples() modifies the values--as long as you
 755  * have other locking on top that makes sure that no two calls of
 756  * _add_sample() happen at the same time, then we are fine. Now, for
 757  * resetting the values we just set @samples to 0 and that makes the
 758  * next _add_sample() to start with defaults. Reading the values in
 759  * _show() currently can race, so you need to make sure the calls are
 760  * under the same lock that protects calls to _add_sample(). FIXME:
 761  * currently unlocked (It is not ultraprecise but does the trick. Bite
 762  * me).
 763  */
 764 struct stats {
 765         s8 min, max;
 766         s16 sigma;
 767         atomic_t samples;
 768 };
 769
 770 static inline
 771 void stats_init(struct stats *stats)
 772 {
 773         atomic_set(&stats->samples, 0);
 774         wmb();
 775 }
 776
 777 static inline
 778 void stats_add_sample(struct stats *stats, s8 sample)
 779 {
 780         s8 min, max;
 781         s16 sigma;
 782         unsigned samples = atomic_read(&stats->samples);
 783         if (samples == 0) {     /* it was zero before, so we initialize */
 784                 min = 127;
 785                 max = -128;
 786                 sigma = 0;
 787         } else {
 788                 min = stats->min;
 789                 max = stats->max;
 790                 sigma = stats->sigma;
 791         }
 792
 793         if (sample < min)       /* compute new values */
 794                 min = sample;
 795         else if (sample > max)
 796                 max = sample;
 797         sigma += sample;
 798
 799         stats->min = min;       /* commit */
 800         stats->max = max;
 801         stats->sigma = sigma;
 802         if (atomic_add_return(1, &stats->samples) > 255) {
 803                 /* wrapped around! reset */
 804                 stats->sigma = sigma / 256;
 805                 atomic_set(&stats->samples, 1);
 806         }
 807 }
 808
 809 static inline ssize_t stats_show(struct stats *stats, char *buf)
 810 {
 811         int min, max, avg;
 812         int samples = atomic_read(&stats->samples);
 813         if (samples == 0)
 814                 min = max = avg = 0;
 815         else {
 816                 min = stats->min;
 817                 max = stats->max;
 818                 avg = stats->sigma / samples;
 819         }
 820         return scnprintf(buf, PAGE_SIZE, "%d %d %d\n", min, max, avg);
 821 }
 822
 823 static inline ssize_t stats_store(struct stats *stats, const char *buf,
 824                                   size_t size)
 825 {
 826         stats_init(stats);
 827         return size;
 828 }
 829
 830 #endif /* #ifndef __LINUX__UWB_H__ */