path: root/drivers/net/wimax/i2400m/i2400m.h

/*
 * Intel Wireless WiMAX Connection 2400m
 * Declarations for bus-generic internal APIs
 *
 *
 * Copyright (C) 2007-2008 Intel Corporation. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in
 *     the documentation and/or other materials provided with the
 *     distribution.
 *   * Neither the name of Intel Corporation nor the names of its
 *     contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Intel Corporation <linux-wimax@intel.com>
 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
 * Yanir Lubetkin <yanirx.lubetkin@intel.com>
 *  - Initial implementation
 *
 *
 * GENERAL DRIVER ARCHITECTURE
 *
 * The i2400m driver is split in the following two major parts:
 *
 *  - bus specific driver
 *  - bus generic driver (this part)
 *
 * The bus specific driver sets up stuff specific to the bus the
 * device is connected to (USB, PCI, tam-tam...non-authoritative
 * nor binding list) which is basically the device-model management
 * (probe/disconnect, etc), moving data from device to kernel and
 * back, doing the power saving details and reseting the device.
 *
 * For details on each bus-specific driver, see it's include file,
 * i2400m-BUSNAME.h
 *
 * The bus-generic functionality break up is:
 *
 *  - Firmware upload: fw.c - takes care of uploading firmware to the
 *        device. bus-specific driver just needs to provides a way to
 *        execute boot-mode commands and to reset the device.
 *
 *  - RX handling: rx.c - receives data from the bus-specific code and
 *        feeds it to the network or WiMAX stack or uses it to modify
 *        the driver state. bus-specific driver only has to receive
 *        frames and pass them to this module.
 *
 *  - TX handling: tx.c - manages the TX FIFO queue and provides means
 *        for the bus-specific TX code to pull data from the FIFO
 *        queue. bus-specific code just pulls frames from this module
 *        to sends them to the device.
 *
 *  - netdev glue: netdev.c - interface with Linux networking
 *        stack. Pass around data frames, and configure when the
 *        device is up and running or shutdown (through ifconfig up /
 *        down). Bus-generic only.
 *
 *  - control ops: control.c - implements various commands for
 *        controlling the device. bus-generic only.
 *
 *  - device model glue: driver.c - implements helpers for the
 *        device-model glue done by the bus-specific layer
 *        (setup/release the driver resources), turning the device on
 *        and off, handling the device reboots/resets and a few simple
 *        WiMAX stack ops.
 *
 * Code is also broken up in linux-glue / device-glue.
 *
 * Linux glue contains functions that deal mostly with gluing with the
 * rest of the Linux kernel.
 *
 * Device-glue are functions that deal mostly with the way the device
 * does things and talk the device's language.
 *
 * device-glue code is licensed BSD so other open source OSes can take
 * it to implement their drivers.
 *
 *
 * APIs AND HEADER FILES
 *
 * This bus generic code exports three APIs:
 *
 *  - HDI (host-device interface) definitions common to all busses
 *    (include/linux/wimax/i2400m.h); these can be also used by user
 *    space code.
 *  - internal API for the bus-generic code
 *  - external API for the bus-specific drivers
 *
 *
 * LIFE CYCLE:
 *
 * When the bus-specific driver probes, it allocates a network device
 * with enough space for it's data structue, that must contain a
 * &struct i2400m at the top.
 *
 * On probe, it needs to fill the i2400m members marked as [fill], as
 * well as i2400m->wimax_dev.net_dev and call i2400m_setup(). The
 * i2400m driver will only register with the WiMAX and network stacks;
 * the only access done to the device is to read the MAC address so we
 * can register a network device.
 *
 * The high-level call flow is:
 *
 * bus_probe()
 *   i2400m_setup()
 *     i2400m->bus_setup()
 *     boot rom initialization / read mac addr
 *     network / WiMAX stacks registration
 *     i2400m_dev_start()
 *       i2400m->bus_dev_start()
 *       i2400m_dev_initialize()
 *
 * The reverse applies for a disconnect() call:
 *
 * bus_disconnect()
 *   i2400m_release()
 *     i2400m_dev_stop()
 *       i2400m_dev_shutdown()
 *       i2400m->bus_dev_stop()
 *     network / WiMAX stack unregistration
 *     i2400m->bus_release()
 *
 * At this point, control and data communications are possible.
 *
 * While the device is up, it might reset. The bus-specific driver has
 * to catch that situation and call i2400m_dev_reset_handle() to deal
 * with it (reset the internal driver structures and go back to square
 * one).
 */

#ifndef __I2400M_H__
#define __I2400M_H__

#include <linux/usb.h>
#include <linux/netdevice.h>
#include <linux/completion.h>
#include <linux/rwsem.h>
#include <linux/atomic.h>
#include <net/wimax.h>
#include <linux/wimax/i2400m.h>
#include <asm/byteorder.h>

enum {
/* netdev interface */
	/*
	 * Out of NWG spec (R1_v1.2.2), 3.3.3 ASN Bearer Plane MTU Size
	 *
	 * The MTU is 1400 or less
	 */
	I2400M_MAX_MTU = 1400,
};

/* Misc constants */
enum {
	/* Size of the Boot Mode Command buffer */
	I2400M_BM_CMD_BUF_SIZE = 16 * 1024,
	I2400M_BM_ACK_BUF_SIZE = 256,
};

enum {
	/* Maximum number of bus reset can be retried */
	I2400M_BUS_RESET_RETRIES = 3,
};

/**
 * struct i2400m_poke_table - Hardware poke table for the Intel 2400m
 *
 * This structure will be used to create a device specific poke table
 * to put the device in a consistent state at boot time.
 *
 * @address: The device address to poke
 *
 * @data: The data value to poke to the device address
 *
 */
struct i2400m_poke_table{
	__le32 address;
	__le32 data;
};

#define I2400M_FW_POKE(a, d) {		\
	.address = cpu_to_le32(a),	\
	.data = cpu_to_le32(d)		\
}


/**
 * i2400m_reset_type - methods to reset a device
 *
 * @I2400M_RT_WARM: Reset without device disconnection, device handles
 *     are kept valid but state is back to power on, with firmware
 *     re-uploaded.
 * @I2400M_RT_COLD: Tell the device to disconnect itself from the bus
 *     and reconnect. Renders all device handles invalid.
 * @I2400M_RT_BUS: Tells the bus to reset the device; last measure
 *     used when both types above don't work.
 */
enum i2400m_reset_type {
	I2400M_RT_WARM,	/* first measure */
	I2400M_RT_COLD,	/* second measure */
	I2400M_RT_BUS,	/* call in artillery */
};

struct i2400m_reset_ctx;
struct i2400m_roq;
struct i2400m_barker_db;

/**
 * struct i2400m - descriptor for an Intel 2400m
 *
 * Members marked with [fill] must be filled out/initialized before
 * calling i2400m_setup().
 *
 * Note the @bus_setup/@bus_release, @bus_dev_start/@bus_dev_release
 * call pairs are very much doing almost the same, and depending on
 * the underlying bus, some stuff has to be put in one or the
 * other. The idea of setup/release is that they setup the minimal
 * amount needed for loading firmware, where us dev_start/stop setup
 * the rest needed to do full data/control traffic.
 *
 * @bus_tx_block_size: [fill] USB imposes a 16 block size, but other
 *     busses will differ.  So we have a tx_blk_size variable that the
 *     bus layer sets to tell the engine how much of that we need.
 *
 * @bus_tx_room_min: [fill] Minimum room required while allocating
 *     TX queue's buffer space for message header. USB requires
 *     16 bytes. Refer to bus specific driver code for details.
 *
 * @bus_pl_size_max: [fill] Maximum payload size.
 *
 * @bus_setup: [optional fill] Function called by the bus-generic code
 *     [i2400m_setup()] to setup the basic bus-specific communications
 *     to the the device needed to load firmware. See LIFE CYCLE above.
 *
 *     NOTE: Doesn't need to upload the firmware, as that is taken
 *     care of by the bus-generic code.
 *
 * @bus_release: [optional fill] Function called by the bus-generic
 *     code [i2400m_release()] to shutdown the basic bus-specific
 *     communications to the the device needed to load firmware. See
 *     LIFE CYCLE above.
 *
 *     This function does not need to reset the device, just tear down
 *     all the host resources created to  handle communication with
 *     the device.
 *
 * @bus_dev_start: [optional fill] Function called by the bus-generic
 *     code [i2400m_dev_start()] to do things needed to start the
 *     device. See LIFE CYCLE above.
 *
 *     NOTE: Doesn't need to upload the firmware, as that is taken
 *     care of by the bus-generic code.
 *
 * @bus_dev_stop: [optional fill] Function called by the bus-generic
 *     code [i2400m_dev_stop()] to do things needed for stopping the
 *     device. See LIFE CYCLE above.
 *
 *     This function does not need to reset the device, just tear down
 *     all the host resources created to handle communication with
 *     the device.
 *
 * @bus_tx_kick: [fill] Function called by the bus-generic code to let
 *     the bus-specific code know that there is data available in the
 *     TX FIFO for transmission to the device.
 *
 *     This function cannot sleep.
 *
 * @bus_reset: [fill] Function called by the bus-generic code to reset
 *     the device in in various ways. Doesn't need to wait for the
 *     reset to finish.
 *
 *     If warm or cold reset fail, this function is expected to do a
 *     bus-specific reset (eg: USB reset) to get the device to a
 *     working state (even if it implies device disconecction).
 *
 *     Note the warm reset is used by the firmware uploader to
 *     reinitialize the device.
 *
 *     IMPORTANT: this is called very early in the device setup
 *     process, so it cannot rely on common infrastructure being laid
 *     out.
 *
 *     IMPORTANT: don't call reset on RT_BUS with i2400m->init_mutex
 *     held, as the .pre/.post reset handlers will deadlock.
 *
 * @bus_bm_retries: [fill] How many times shall a firmware upload /
 *     device initialization be retried? Different models of the same
 *     device might need different values, hence it is set by the
 *     bus-specific driver. Note this value is used in two places,
 *     i2400m_fw_dnload() and __i2400m_dev_start(); they won't become
 *     multiplicative (__i2400m_dev_start() calling N times
 *     i2400m_fw_dnload() and this trying N times to download the
 *     firmware), as if __i2400m_dev_start() only retries if the
 *     firmware crashed while initializing the device (not in a
 *     general case).
 *
 * @bus_bm_cmd_send: [fill] Function called to send a boot-mode
 *     command. Flags are defined in 'enum i2400m_bm_cmd_flags'. This
 *     is synchronous and has to return 0 if ok or < 0 errno code in
 *     any error condition.
 *
 * @bus_bm_wait_for_ack: [fill] Function called to wait for a
 *     boot-mode notification (that can be a response to a previously
 *     issued command or an asynchronous one). Will read until all the
 *     indicated size is read or timeout. Reading more or less data
 *     than asked for is an error condition. Return 0 if ok, < 0 errno
 *     code on error.
 *
 *     The caller to this function will check if the response is a
 *     barker that indicates the device going into reset mode.
 *
 * @bus_fw_names: [fill] a NULL-terminated array with the names of the
 *     firmware images to try loading. This is made a list so we can
 *     support backward compatibility of firmware releases (eg: if we
 *     can't find the default v1.4, we try v1.3). In general, the name
 *     should be i2400m-fw-X-VERSION.sbcf, where X is the bus name.
 *     The list is tried in order and the first one that loads is
 *     used. The fw loader will set i2400m->fw_name to point to the
 *     active firmware image.
 *
 * @bus_bm_mac_addr_impaired: [fill] Set to true if the device's MAC
 *     address provided in boot mode is kind of broken and needs to
 *     be re-read later on.
 *
 * @bus_bm_pokes_table: [fill/optional] A table of device addresses
 *     and values that will be poked at device init time to move the
 *     device to the correct state for the type of boot/firmware being