path: root/include/linux/uwb.h

/*
 * Ultra Wide Band
 * UWB API
 *
 * Copyright (C) 2005-2006 Intel Corporation
 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA.
 *
 *
 * FIXME: doc: overview of the API, different parts and pointers
 */

#ifndef __LINUX__UWB_H__
#define __LINUX__UWB_H__

#include <linux/limits.h>
#include <linux/device.h>
#include <linux/mutex.h>
#include <linux/timer.h>
#include <linux/wait.h>
#include <linux/workqueue.h>
#include <linux/uwb/spec.h>

struct uwb_dev;
struct uwb_beca_e;
struct uwb_rc;
struct uwb_rsv;
struct uwb_dbg;

/**
 * struct uwb_dev - a UWB Device
 * @rc: UWB Radio Controller that discovered the device (kind of its
 *     parent).
 * @bce: a beacon cache entry for this device; or NULL if the device
 *     is a local radio controller.
 * @mac_addr: the EUI-48 address of this device.
 * @dev_addr: the current DevAddr used by this device.
 * @beacon_slot: the slot number the beacon is using.
 * @streams: bitmap of streams allocated to reservations targeted at
 *     this device.  For an RC, this is the streams allocated for
 *     reservations targeted at DevAddrs.
 *
 * A UWB device may either by a neighbor or part of a local radio
 * controller.
 */
struct uwb_dev {
	struct mutex mutex;
	struct list_head list_node;
	struct device dev;
	struct uwb_rc *rc;		/* radio controller */
	struct uwb_beca_e *bce;		/* Beacon Cache Entry */

	struct uwb_mac_addr mac_addr;
	struct uwb_dev_addr dev_addr;
	int beacon_slot;
	DECLARE_BITMAP(streams, UWB_NUM_STREAMS);
	DECLARE_BITMAP(last_availability_bm, UWB_NUM_MAS);
};
#define to_uwb_dev(d) container_of(d, struct uwb_dev, dev)

/**
 * UWB HWA/WHCI Radio Control {Command|Event} Block context IDs
 *
 * RC[CE]Bs have a 'context ID' field that matches the command with
 * the event received to confirm it.
 *
 * Maximum number of context IDs
 */
enum { UWB_RC_CTX_MAX = 256 };


/** Notification chain head for UWB generated events to listeners */
struct uwb_notifs_chain {
	struct list_head list;
	struct mutex mutex;
};

/* Beacon cache list */
struct uwb_beca {
	struct list_head list;
	size_t entries;
	struct mutex mutex;
};

/* Event handling thread. */
struct uwbd {
	int pid;
	struct task_struct *task;
	wait_queue_head_t wq;
	struct list_head event_list;
	spinlock_t event_list_lock;
};

/**
 * struct uwb_mas_bm - a bitmap of all MAS in a superframe
 * @bm: a bitmap of length #UWB_NUM_MAS
 */
struct uwb_mas_bm {
	DECLARE_BITMAP(bm, UWB_NUM_MAS);
	DECLARE_BITMAP(unsafe_bm, UWB_NUM_MAS);
	int safe;
	int unsafe;
};

/**
 * uwb_rsv_state - UWB Reservation state.
 *
 * NONE - reservation is not active (no DRP IE being transmitted).
 *
 * Owner reservation states:
 *
 * INITIATED - owner has sent an initial DRP request.
 * PENDING - target responded with pending Reason Code.
 * MODIFIED - reservation manager is modifying an established
 * reservation with a different MAS allocation.
 * ESTABLISHED - the reservation has been successfully negotiated.
 *
 * Target reservation states:
 *
 * DENIED - request is denied.
 * ACCEPTED - request is accepted.
 * PENDING - PAL has yet to make a decision to whether to accept or
 * deny.
 *
 * FIXME: further target states TBD.
 */
enum uwb_rsv_state {
	UWB_RSV_STATE_NONE = 0,
	UWB_RSV_STATE_O_INITIATED,
	UWB_RSV_STATE_O_PENDING,
	UWB_RSV_STATE_O_MODIFIED,
	UWB_RSV_STATE_O_ESTABLISHED,
	UWB_RSV_STATE_O_TO_BE_MOVED,
	UWB_RSV_STATE_O_MOVE_EXPANDING,
	UWB_RSV_STATE_O_MOVE_COMBINING,
	UWB_RSV_STATE_O_MOVE_REDUCING,
	UWB_RSV_STATE_T_ACCEPTED,
	UWB_RSV_STATE_T_DENIED,
	UWB_RSV_STATE_T_CONFLICT,
	UWB_RSV_STATE_T_PENDING,
	UWB_RSV_STATE_T_EXPANDING_ACCEPTED,
	UWB_RSV_STATE_T_EXPANDING_CONFLICT,
	UWB_RSV_STATE_T_EXPANDING_PENDING,
	UWB_RSV_STATE_T_EXPANDING_DENIED,
	UWB_RSV_STATE_T_RESIZED,

	UWB_RSV_STATE_LAST,
};

enum uwb_rsv_target_type {
	UWB_RSV_TARGET_DEV,
	UWB_RSV_TARGET_DEVADDR,
};

/**
 * struct uwb_rsv_target - the target of a reservation.
 *
 * Reservations unicast and targeted at a single device
 * (UWB_RSV_TARGET_DEV); or (e.g., in the case of WUSB) targeted at a
 * specific (private) DevAddr (UWB_RSV_TARGET_DEVADDR).
 */
struct uwb_rsv_target {
	enum uwb_rsv_target_type type;
	union {
		struct uwb_dev *dev;
		struct uwb_dev_addr devaddr;
	};
};

struct uwb_rsv_move {
	struct uwb_mas_bm final_mas;
	struct uwb_ie_drp *companion_drp_ie;
	struct uwb_mas_bm companion_mas;
};

/*
 * Number of streams reserved for reservations targeted at DevAddrs.
 */
#define UWB_NUM_GLOBAL_STREAMS 1

typedef void (*uwb_rsv_cb_f)(struct uwb_rsv *rsv);

/**
 * struct uwb_rsv - a DRP reservation
 *
 * Data structure management:
 *
 * @rc:             the radio controller this reservation is for
 *                  (as target or owner)
 * @rc_node:        a list node for the RC
 * @pal_node:       a list node for the PAL
 *
 * Owner and target parameters:
 *
 * @owner:          the UWB device owning this reservation
 * @target:         the target UWB device
 * @type:           reservation type
 *
 * Owner parameters:
 *
 * @max_mas:        maxiumum number of MAS
 * @min_mas:        minimum number of MAS
 * @sparsity:       owner selected sparsity
 * @is_multicast:   true iff multicast
 *
 * @callback:       callback function when the reservation completes
 * @pal_priv:       private data for the PAL making the reservation
 *
 * Reservation status:
 *
 * @status:         negotiation status
 * @stream:         stream index allocated for this reservation
 * @tiebreaker:     conflict tiebreaker for this reservation
 * @mas:            reserved MAS
 * @drp_ie:         the DRP IE
 * @ie_valid:       true iff the DRP IE matches the reservation parameters
 *
 * DRP reservations are uniquely identified by the owner, target and
 * stream index.  However, when using a DevAddr as a target (e.g., for
 * a WUSB cluster reservation) the responses may be received from
 * devices with different DevAddrs.  In this case, reservations are
 * uniquely identified by just the stream index.  A number of stream
 * indexes (UWB_NUM_GLOBAL_STREAMS) are reserved for this.
 */
struct uwb_rsv {
	struct uwb_rc *rc;
	struct list_head rc_node;
	struct list_head pal_node;
	struct kref kref;

	struct uwb_dev *owner;
	struct uwb_rsv_target target;
	enum uwb_drp_type type;
	int max_mas;
	int min_mas;
	int max_interval;
	bool is_multicast;

	uwb_rsv_cb_f callback;
	void *pal_priv;

	enum uwb_rsv_state state;
	bool needs_release_companion_mas;
	u8 stream;
	u8 tiebreaker;
	struct uwb_mas_bm mas;
	struct uwb_ie_drp *drp_ie;
	struct uwb_rsv_move mv;
	bool ie_valid;
	struct timer_list timer;
	struct work_struct handle_timeout_work;
};

static const
struct uwb_mas_bm uwb_mas_bm_zero = { .bm = { 0 } };

static inline void uwb_mas_bm_copy_le(void *dst, const struct uwb_mas_bm *mas)
{
	bitmap_copy_le(dst, mas->bm, UWB_NUM_MAS);
}

/**
 * struct uwb_drp_avail - a radio controller's view of MAS usage
 * @global:   MAS unused by neighbors (excluding reservations targetted
 *            or owned by the local radio controller) or the beaon period
 * @local:    MAS unused by local established reservations
 * @pending:  MAS unused by local pending reservations
 * @ie:       DRP Availability IE to be included in the beacon
 * @ie_valid: true iff @ie is valid and does not need to regenerated from
 *            @global and @local
 *
 * Each radio controller maintains a view of MAS usage or
 * availability. MAS available for a new reservation are determined
 * from the intersection of @global, @local, and @pending.
 *
 * The radio controller must transmit a DRP Availability IE that's the
 * intersection of @global and @local.
 *
 * A set bit indicates the MAS is unused and available.
 *
 * rc->rsvs_mutex should be held before accessing this data structure.
 *
 * [ECMA-368] section 17.4.3.
 */
struct uwb_drp_avail {
	DECLARE_BITMAP(global, UWB_NUM_MAS);
	DECLARE_BITMAP(local, UWB_NUM_MAS);
	DECLARE_BITMAP(pending, UWB_NUM_MAS);
	struct uwb_ie_drp_avail ie;
	bool ie_valid;
};

struct uwb_drp_backoff_win {
	u8 window;
	u8 n;
	int total_expired;
	struct timer_list timer;
	bool can_reserve_extra_mases;
};

const char *uwb_rsv_state_str(enum uwb_rsv_state state);
const char *