usbd.h

Linux2.4.20针对三星公司的s3c2440内核基础上的一些设备驱动代码

/*
 * linux/drivers/usbd/usbd.h 
 *
 * Copyright (c) 2000, 2001, 2002 Lineo
 * Copyright (c) 2001 Hewlett Packard
 *
 * By: 
 *      Stuart Lynne <[e-mail]>, 
 *      Tom Rushworth <[e-mail]>, 
 *      Bruce Balden <[e-mail]>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 */


/*
 * USB Device Support structures
 *
 * Descriptors:
 *
 * Driver description:
 * 
 *   struct usb_device_description 
 *
 * Driver instance configuration:
 *
 *   struct usb_device_instance 
 *   struct usb_endpoint_instance;
 *
 *   struct usb_function_instance
 *   struct usb_bus_instance
 *
 * Data transfer:
 *
 *   struct urb; 
 *
 */

/*
 *
 * Notes...
 *
 * 1. The order of loading must be:
 *
 *        usb-device                    default driver for endpoint 0
 *        usb-function(s)               one or more function drivers
 *        usb-bus-interface(s)          one or more bus interface drivers
 *
 * 2. Loading usb-function modules allows them to register with the 
 * usb-device layer. This makes their usb configuration descriptors 
 * available.
 *
 * 3. Loading usb-bus-interface modules causes them to register with
 * the usb-device layer.
 *
 * 4. The last action from loading a usb-bus-interface driver is to enable
 * their upstream port. This in turn will cause the upstream host to
 * enumerate this device.
 *
 * 5. The usb-device layer provides a default configuration for endpoint 0 for
 * each device. 
 *
 * 6. Additional configurations are added to support the configuration
 * function driver when entering the configured state.
 *
 * 7. The usb-device maintains a list of configurations from the loaded
 * function drivers. It will provide this to the USB HOST as part of the
 * enumeration process and will add someof them as the active configuration
 * as per the USB HOST instructions.
 * 
 *
 */

#ifndef MODULE
#undef __init
#define __init
#undef __exit
#define __exit
#undef GET_USE_COUNT
#define GET_USE_COUNT(module) 0
#undef THIS_MODULE
#define THIS_MODULE 0
#endif


#ifndef MIN
#define MIN(a,b) ((a) < (b) ? (a) : (b))
#endif
#ifndef MAX
#define MAX(a,b) ((a) > (b) ? (a) : (b))
#endif

/* Overview
 *
 * USB Descriptors are used to build a configuration database for each USB
 * Function driver.
 *
 * USB Function Drivers register a configuration that may be used by the
 * default endpoint 0 driver to provide a USB HOST with options.
 *
 * USB Bus Interface drivers find and register specific physical bus
 * interfaces.
 *
 * The USB Device layer creates and maintains a device structure for each
 * physical interface that specifies the bus interface driver, shows possible 
 * configurations, specifies the default endpoint 0 driver, active
 * configured function driver and configured endpoints.
 *
 *
 */

struct urb;

struct usb_endpoint_instance;
struct usb_configuration_description;
struct usb_function_driver;
struct usb_function_instance;

struct usb_device_instance;

struct usb_bus_driver;
struct usb_bus_instance;


/* USB definitions
 */
#if 0
#define USB_ENDPOINT_CONTROL            0x00
#define USB_ENDPOINT_ISOC               0x01
#define USB_ENDPOINT_BULK               0x02
#define USB_ENDPOINT_INT                0x03

#define USB_CONFIG_REMOTEWAKE           0x20
#define USB_CONFIG_SELFPOWERED          0x40
#define USB_CONFIG_BUSPOWERED           0x80


#define USB_REQUEST_GET_STATUS          0x01
#define USB_REQUEST_XXXXXXXXXXXXE       0x02
#define USB_REQUEST_CLEAR_FEATURE       0x03
#define USB_REQUEST_SET_FEATURE         0x04
#define USB_REQUEST_SET_ADDRESS         0x05
#define USB_REQUEST_GET_DESCRIPTOR      0x06
#define USB_REQUEST_SET_DESCRIPTOR      0x07
#define USB_REQUEST_GET_CONFIGURATION   0x08
#define USB_REQUEST_SET_CONFIGURATION   0x09
#define USB_REQUEST_GET_INTERFACE       0x0A
#define USB_REQUEST_SET_INTERFACE       0x0B

#define USB_DESCRIPTOR_DEVICE           0x01
#define USB_DESCRIPTOR_CONFIG           0x02
#define USB_DESCRIPTOR_STRING           0x03
#define USB_DESCRIPTOR_INTERFACE        0x04
#define USB_DESCRIPTOR_ENDPOINT         0x05
#endif


/*
 * Device and/or Interface Class codes
 */
#define USB_CLASS_PER_INTERFACE         0	/* for DeviceClass */
#define USB_CLASS_AUDIO                 1
#define USB_CLASS_COMM                  2
#define USB_CLASS_HID                   3
#define USB_CLASS_PHYSICAL              5
#define USB_CLASS_PRINTER               7
#define USB_CLASS_MASS_STORAGE          8
#define USB_CLASS_HUB                   9
#define USB_CLASS_DATA                  10
#define USB_CLASS_APP_SPEC              0xfe
#define USB_CLASS_VENDOR_SPEC           0xff

/*
 * USB types
 */
#define USB_TYPE_STANDARD               (0x00 << 5)
#define USB_TYPE_CLASS                  (0x01 << 5)
#define USB_TYPE_VENDOR                 (0x02 << 5)
#define USB_TYPE_RESERVED               (0x03 << 5)

/*
 * USB recipients
 */
#define USB_RECIP_DEVICE                0x00
#define USB_RECIP_INTERFACE             0x01
#define USB_RECIP_ENDPOINT              0x02
#define USB_RECIP_OTHER                 0x03

/*
 * USB directions
 */
#define USB_DIR_OUT                     0
#define USB_DIR_IN                      0x80

/*
 * Descriptor types
 */
#define USB_DT_DEVICE                   0x01
#define USB_DT_CONFIG                   0x02
#define USB_DT_STRING                   0x03
#define USB_DT_INTERFACE                0x04
#define USB_DT_ENDPOINT                 0x05

#define USB_DT_HID                      (USB_TYPE_CLASS | 0x01)
#define USB_DT_REPORT                   (USB_TYPE_CLASS | 0x02)
#define USB_DT_PHYSICAL                 (USB_TYPE_CLASS | 0x03)
#define USB_DT_HUB                      (USB_TYPE_CLASS | 0x09)

/*
 * Descriptor sizes per descriptor type
 */
#define USB_DT_DEVICE_SIZE              18
#define USB_DT_CONFIG_SIZE              9
#define USB_DT_INTERFACE_SIZE           9
#define USB_DT_ENDPOINT_SIZE            7
#define USB_DT_ENDPOINT_AUDIO_SIZE      9	/* Audio extension */
#define USB_DT_HUB_NONVAR_SIZE          7
#define USB_DT_HID_SIZE                 9

/*
 * Endpoints
 */
#define USB_ENDPOINT_NUMBER_MASK        0x0f	/* in bEndpointAddress */
#define USB_ENDPOINT_DIR_MASK           0x80

#define USB_ENDPOINT_XFERTYPE_MASK      0x03	/* in bmAttributes */
#define USB_ENDPOINT_XFER_CONTROL       0
#define USB_ENDPOINT_XFER_ISOC          1
#define USB_ENDPOINT_XFER_BULK          2
#define USB_ENDPOINT_XFER_INT           3

/*
 * USB Packet IDs (PIDs)
 */
#define USB_PID_UNDEF_0                        0xf0
#define USB_PID_OUT                            0xe1
#define USB_PID_ACK                            0xd2
#define USB_PID_DATA0                          0xc3
#define USB_PID_PING                           0xb4	/* USB 2.0 */
#define USB_PID_SOF                            0xa5
#define USB_PID_NYET                           0x96	/* USB 2.0 */
#define USB_PID_DATA2                          0x87	/* USB 2.0 */
#define USB_PID_SPLIT                          0x78	/* USB 2.0 */
#define USB_PID_IN                             0x69
#define USB_PID_NAK                            0x5a
#define USB_PID_DATA1                          0x4b
#define USB_PID_PREAMBLE                       0x3c	/* Token mode */
#define USB_PID_ERR                            0x3c	/* USB 2.0: handshake mode */
#define USB_PID_SETUP                          0x2d
#define USB_PID_STALL                          0x1e
#define USB_PID_MDATA                          0x0f	/* USB 2.0 */

/*
 * Standard requests
 */
#define USB_REQ_GET_STATUS              0x00
#define USB_REQ_CLEAR_FEATURE           0x01
#define USB_REQ_SET_FEATURE             0x03
#define USB_REQ_SET_ADDRESS             0x05
#define USB_REQ_GET_DESCRIPTOR          0x06
#define USB_REQ_SET_DESCRIPTOR          0x07
#define USB_REQ_GET_CONFIGURATION       0x08
#define USB_REQ_SET_CONFIGURATION       0x09
#define USB_REQ_GET_INTERFACE           0x0A
#define USB_REQ_SET_INTERFACE           0x0B
#define USB_REQ_SYNCH_FRAME             0x0C

#define USBD_DEVICE_REQUESTS(x) (((unsigned int)x <= USB_REQ_SYNCH_FRAME) ? usbd_device_requests[x] : "UNKNOWN")

/*
 * HID requests
 */
#define USB_REQ_GET_REPORT              0x01
#define USB_REQ_GET_IDLE                0x02
#define USB_REQ_GET_PROTOCOL            0x03
#define USB_REQ_SET_REPORT              0x09
#define USB_REQ_SET_IDLE                0x0A
#define USB_REQ_SET_PROTOCOL            0x0B


/*
 * USB Spec Release number
 */

#define USB_BCD_VERSION                 0x0200


/*
 * Device Requests      (c.f Table 9-2)
 */

#define USB_REQ_DIRECTION_MASK          0x80
#define USB_REQ_TYPE_MASK               0x60
#define USB_REQ_RECIPIENT_MASK          0x1f

#define USB_REQ_DEVICE2HOST             0x80
#define USB_REQ_HOST2DEVICE             0x00

#define USB_REQ_TYPE_STANDARD           0x00
#define USB_REQ_TYPE_CLASS              0x20
#define USB_REQ_TYPE_VENDOR             0x40

#define USB_REQ_RECIPIENT_DEVICE        0x00
#define USB_REQ_RECIPIENT_INTERFACE     0x01
#define USB_REQ_RECIPIENT_ENDPOINT      0x02
#define USB_REQ_RECIPIENT_OTHER         0x03

/*
 * get status bits
 */

#define USB_STATUS_SELFPOWERED          0x01
#define USB_STATUS_REMOTEWAKEUP         0x02

#define USB_STATUS_HALT                 0x01

/* 
 * descriptor types
 */

#define USB_DESCRIPTOR_TYPE_DEVICE                      0x01
#define USB_DESCRIPTOR_TYPE_CONFIGURATION               0x02
#define USB_DESCRIPTOR_TYPE_STRING                      0x03
#define USB_DESCRIPTOR_TYPE_INTERFACE                   0x04
#define USB_DESCRIPTOR_TYPE_ENDPOINT                    0x05
#define USB_DESCRIPTOR_TYPE_DEVICE_QUALIFIER            0x06
#define USB_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION   0x07
#define USB_DESCRIPTOR_TYPE_INTERFACE_POWER             0x08
#define USB_DESCRIPTOR_TYPE_HID                         0x21
#define USB_DESCRIPTOR_TYPE_REPORT                      0x22

#define USBD_DEVICE_DESCRIPTORS(x) (((unsigned int)x <= USB_DESCRIPTOR_TYPE_INTERFACE_POWER) ? \
                usbd_device_descriptors[x] : "UNKNOWN")

/*
 * standard feature selectors
 */
#define	USB_ENDPOINT_HALT		0x00
#define USB_DEVICE_REMOTE_WAKEUP	0x01
#define	USB_TEST_MODE			0x02


/* USB Requests
 *
 */

struct usb_device_request {
	__u8 bmRequestType;
	__u8 bRequest;
	__u16 wValue;
	__u16 wIndex;
	__u16 wLength;
} __attribute__ ((packed));


/* USB Status
 *
 */
typedef enum urb_send_status {
	SEND_IN_PROGRESS,
	SEND_FINISHED_OK,
	SEND_FINISHED_ERROR,
	RECV_READY,
	RECV_OK,
	RECV_ERROR
} urb_send_status_t;

/*
 * Structure member address manipulation macros.
 * These are used by client code (code using the urb_link routines), since
 * the urb_link structure is embedded in the client data structures.
 *
 * Note: a macro offsetof equivalent to member_offset is defined in stddef.h
 *       but this is kept here for the sake of portability.
 *
 * p2surround returns a pointer to the surrounding structure given
 * type of the surrounding structure, the name memb of the structure
 * member pointed at by ptr.  For example, if you have:
 * 
 *      struct foo {
 *          int x;
 *          float y;
 *          char z;
 *      } thingy;
 *  
 *      char *cp = &thingy.z;
 *
 * then
 *
 *      &thingy == p2surround(struct foo, z, cp)
 *
 * Clear?
 */

#define _cv_(ptr)                 ((char*)(void*)(ptr))
#define member_offset(type,memb)  (_cv_(&(((type*)0)->memb))-(char*)0)
#define p2surround(type,memb,ptr) ((type*)(void*)(_cv_(ptr)-member_offset(type,memb)))

typedef struct urb_link {
	struct urb_link *next;
	struct urb_link *prev;
} urb_link;

struct urb;

/* 
 * Device Events 
 *
 * These are defined in the USB Spec (c.f USB Spec 2.0 Figure 9-1).
 *
 * There are additional events defined to handle some extra actions we need
 * to have handled.
 *
 */
typedef enum usb_device_event {

	DEVICE_UNKNOWN,		// bi - unknown event
	DEVICE_INIT,		// bi  - initialize
	DEVICE_CREATE,		// bi  - 
	DEVICE_HUB_CONFIGURED,	// bi  - bus has been plugged int
	DEVICE_RESET,		// bi  - hub has powered our port

	DEVICE_ADDRESS_ASSIGNED,	// ep0 - set address setup received
	DEVICE_CONFIGURED,	// ep0 - set configure setup received
	DEVICE_SET_INTERFACE,	// ep0 - set interface setup received

	DEVICE_SET_FEATURE,	// ep0 - set feature setup received
	DEVICE_CLEAR_FEATURE,	// ep0 - clear feature setup received

	DEVICE_DE_CONFIGURED,	// ep0 - set configure setup received for ??

	DEVICE_BUS_INACTIVE,	// bi  - bus in inactive (no SOF packets)
	DEVICE_BUS_ACTIVITY,	// bi  - bus is active again

	DEVICE_POWER_INTERRUPTION,	// bi  - hub has depowered our port
	DEVICE_HUB_RESET,	// bi  - bus has been unplugged
	DEVICE_DESTROY,		// bi  - device instance should be destroyed

	DEVICE_FUNCTION_PRIVATE,	// function - private

} usb_device_event_t;

#define USBD_DEVICE_EVENTS(x) (((unsigned int)x <= DEVICE_FUNCTION_PRIVATE) ? \
                usbd_device_events[x] : "UNKNOWN")


/* Endpoint configuration
 *
 * Per endpoint configuration data. Used to track which function driver owns
 * an endpoint.
 *
 */
struct usb_endpoint_instance {
	int endpoint_address;	// logical endpoint address