/* usb/defs.h
 *
 * (c) 2002 Simtec Electronics
 *
 * Ben Dooks
 *
 * USB definitions to go with the header files
 *
 * $Id: defs.h,v 1.25 2003/10/20 15:40:36 ben Exp $
 *
 * This Library file is part of the Simtec Electronics USB stack development
 *   suite.
 * Specific licence is granted to use this file by third parties for the
 *   development of USB device drivers.
*/

#ifndef __USB_DEFS_H
#define __USB_DEFS_H "$Id: defs.h,v 1.25 2003/10/20 15:40:36 ben Exp $"

/* Additional Transaction Information */
/** USB transaction Exact size flag
@memo USB transaction Exact size flag
*/
#define USB_TRANSACTION_EXACT_SIZE     0x00000001

/** USB transaction frame start flag
@memo USB transaction frame start flag
*/
#define USB_TRANSACTION_FRAME_START    0x00000002

/** USB transaction setup eval flag
@memo USB transaction setup eval flag
*/
#define USB_TRANSACTION_SETUP_EVAL     0x00000004

/** USB transaction status stage flag
@memo USB transaction status stage flag
*/
#define USB_TRANSACTION_STATUS_STAGE   0x00000008

/** USB transaction timeout enable
@memo USB transaction timeout enable
*/
#define USB_TRANSACTION_TIMEOUT        0x00000010

/** USB transaction request first flag
@memo USB transaction request first flag
*/
#define USB_TRANSACTION_REQUEST_FIRST  0x40000000

/** USB transaction cancelled flag
@memo USB transaction cancelled flag
*/
#define USB_TRANSACTION_CANCELLED      0x80000000


typedef int usb_transaction_result_t;

/* The values can be used as results to a transaction/request */
/** USB transaction result ok
@memo USB transaction result ok
 */
#define USB_TRANSACTION_RESULT_OK                 (0)

/* USB Reply from USB Host Controller Driver */
/** USB transaction result halted
@memo USB transaction result halted
 */
#define USB_TRANSACTION_RESULT_HALTED             (-1)

/** USB transaction result aborted
@memo USB transaction result aborted
 */
#define USB_TRANSACTION_RESULT_ABORTED            (-2)

/* USB Reply from USB Host Controller Driver */
/** USB transaction result transmission failed
@memo USB transaction result transmission failed
 */
#define USB_TRANSACTION_RESULT_TRANSMISSION_FAILED (-3)

/** USB transaction result invalid size
@memo USB transaction result invalid size
 */
#define USB_TRANSACTION_RESULT_INVALID_SIZE       (-4)

/** USB transaction result working
@memo USB transaction result. The transaction is still working.
 */
#define USB_TRANSACTION_RESULT_WORKING            (-5)

/** USB transaction result - bus error
 @memo USB transaction result. Physical transmission protocol error
*/
#define USB_TRANSACTION_RESULT_BUSPROTO_ERR       (-6)

/** USB transaction result - stall
 @memo USB transaction result. Transfer stalled
*/
#define USB_TRANSACTION_RESULT_STALL              (-7)

/** USB transaction result - no response
 @memo USB transaction result. The device did not respond to the transaction
*/
#define USB_TRANSACTION_RESULT_NORESPONSE         (-8)

/** USB transaction result - controller buffer problem
 @memo USB transaction result. Controller either ran out of buffer, or could not keep up with the data transfer
*/
#define USB_TRANSACTION_RESULT_HC_BUFF_ERR        (-9)

/** USB transaction result - transaction buffer length problem
 * the controller either got too much data (greater than maximum packet size)
 * or ran out of buffer to put the data in
 * @memo USB transaction result. Controller either ran out of buffer, or got too much data
 */
#define USB_TRANSACTION_RESULT_BUS_DATASZ        (-10)

/** USB transaction result - internal system failure
 *
 * the system had an internal failure and could not complete the
 * transaction
 * @memo USB transaction result. Internal system error
 */

#define USB_TRANSACTION_RESULT_INTERNAL          (-11)

/** USB transaction result - transaction timed out
 *
 * The transaction did not complete within the specified timeout, and has
 * been aborted. The system does no more clearing up after aborting the
 * transaction and it is up to the initiator of the request to sort out
 * any problems that a partial transaction may have caused.
 *
 * @memo  USB transaction result - transaction timed out
*/

#define USB_TRANSACTION_RESULT_TIMEOUT           (-12)

/** USB transaction result - transaction aborted due to removal
 *
 * The transaction was aborted because either the endpoint or the device
 * it is related to has been removed from the system. This is generated by
 * usb_endpoint_deregister() and will in future be generated by the hub when
 * a device remove event is detected.
*/

#define USB_TRANSACTION_RESULT_REMOVAL          (-13)

/* Transaction PIDs according USB specification */
#define USB_TRANSACTION_CODE_OUT   0x01
#define USB_TRANSACTION_CODE_ACK   0x02
#define USB_TRANSACTION_CODE_DATA0 0x03
#define USB_TRANSACTION_CODE_SOF   0x05
#define USB_TRANSACTION_CODE_IN    0x09
#define USB_TRANSACTION_CODE_NAK   0x0A
#define USB_TRANSACTION_CODE_DATA1 0x0B
#define USB_TRANSACTION_CODE_PRE   0x0C
#define USB_TRANSACTION_CODE_SETUP 0x0D
#define USB_TRANSACTION_CODE_STALL 0x0E

/* ---------- pipe ---------- */

/* Important: The numbers of the transfer types are defining the bits inside
   some selection masks.  These numbers are also given the according endpoint
   list holding pending tranactions inside the host controller structure. */

/* Transaction types of USB specification. */

/** Pipe type for control pipe
 * @memo Pipe type for control pipe
*/

#define USB_PIPE_TYPE_CONTROL    0

/** Pipe type for ISOCHRONOUS pipe
 * @memo Pipe type for ISOCHRONOUS pipe
*/
#define USB_PIPE_TYPE_ISOCHRONUS 1

/** Pipe type for a BULK pipe
@memo Pipe type for a BULK pipe
*/
#define USB_PIPE_TYPE_BULK       2

/** Pipe type for an INTERRUPT pipe
 * @memo Pipe type for an INTERRUPT pipe
*/

#define USB_PIPE_TYPE_INTERRUPT  3

/** Maximum value for USB_PIPE_TYPE
 * @memo Maximum value for USB_PIPE_TYPE
 * @see USB_PIPE_TYPE_INTERRUPT
 * @see USB_PIPE_TYPE_BULK
 * @see USB_PIPE_TYPE_ISOCHRONUS
 * @see USB_PIPE_TYPE_CONTROL
*/
#define USB_PIPE_TYPE_MAX        4

/* Format of an endpoint address
   !!! used at USB-Module (not inside USB request standard structures) !!!
   Bit 0-29 Number of Endpoint
   Bit 30 - Bit 31 gives direction (0) or both (1)
   Bit 31 - Direction (set to zero if both directions).
            0 - OUT endpoint
            1 - IN endpoint */

/** Mask for pipe endpoint address
 * @memo Mask for pipe endpoint address
*/
#define USB_PIPE_ADDRESS_MASK (0x3FFFFFFF)

/** Bit definition for pipe being bi-directional
 * @memo Bit definition for pipe being bi-directional
*/
#define USB_PIPE_ADDRESS_BOTH (0x40000000)

/** Bit definition for pipe being IN pipe
 * @memo Bit definition for pipe being IN pipe
 * @see USB_PIPE_ADDRESS_BOTH
 * @see USB_PIPE_ADDRESS_OUT
*/
#define USB_PIPE_ADDRESS_IN   (0x80000000)

/** Bit definition for pipe being OUT pipe
 * @memo Bit definition for pipe being OUT pipe
 * @see USB_PIPE_ADDRESS_BOTH
 * @see USB_PIPE_ADDRESS_IN
*/

#define USB_PIPE_ADDRESS_OUT  (0x00000000)

/** Definition for address of default control pipe
 * @memo Definition for address of default control pipe
 * @see USB_PIPE_ADDRESS_BOTH
 * @see USB_PIPE_ADDRESS_IN
 * @see USB_PIPE_ADDRESS_OUT
*/

#define USB_PIPE_DEFAULT (0x00000000 | USB_PIPE_ADDRESS_BOTH)

/** Constant to use with usb_pipe_clear to re-activate an halted pipe
 * @memo USB_PIPE_CLEAR_ACTIVATE
*/
#define USB_PIPE_CLEAR_ACTIVATE 0x00000001

/** Constant to use with usb_pipe_open to open a shared pipe
 * @memo Constant to use with usb_pipe_open to open a shared pipe
*/
#define USB_PIPE_OPEN_SHARED 0x00000001

/** Constant to use with usb_pipe_open to open a pipe exclusively
 * @memo Constant to use with usb_pipe_open to open a pipe exclusively
 */

#define USB_PIPE_OPEN_EXCLUSIVE 0x0

/** Constant to use with usb_pipe_open or usb_pipe_clear to clear data-toggle
 *
 * When this flag is used, opening the pipe will also clear the value of the
 * data-toggle for this endpoint back to zero. This should not normally be
 * needed.
 *
 * @memo Constant to use with usb_pipe_open to clear data-toggle
*/
#define USB_PIPE_CLEAR_TOGGLE 0x10000000

/* internal flag - cause pipe clear to abort all outstanding transactions */
#define USB_PIPE_FLAG_ABORT  0x20000000

/* internal flag - change abort code to device removed */
#define USB_PIPE_FLAG_DEVRM  0x40000000

/* internal flag - halt the endpoint */
#define USB_PIPE_FLAG_HALT   0x01000000

/* internal flag - halt is due to endpoint removal */
#define USB_PIPE_FLAG_EPRM   0x02000000

/* ---------- usb device ---------- */
#define USB_DEVICE_MAX            127

#define USB_DEVICE_AUTO_NUMBER    0xFFFFFFFF
#define USB_DEVICE_DEFAULT_NUMBER 0

/* Device speed ordered by speed */
#define USB_DEVICE_SPEED_SLOW       0x00
#define USB_DEVICE_SPEED_NORMAL     0x01
#define USB_DEVICE_SPEED_FULL       USB_DEVICE_SPEED_NORMAL

/* Device states of USB specification */
#define USB_DEVICE_STATE_UNPLUGGED  0x00
#define USB_DEVICE_STATE_ATTACHED   0x01
#define USB_DEVICE_STATE_POWERED    0x02
#define USB_DEVICE_STATE_DEFAULT    0x03
#define USB_DEVICE_STATE_ADDRESS    0x04
#define USB_DEVICE_STATE_CONFIGURED 0x05
/* This is always an additional information */
#define USB_DEVICE_STATE_SUSPENDED  0x40

#define USB_DEVICE_ADDRESS_OP_CHANGE  0x00000000
#define USB_DEVICE_ADDRESS_OP_CLAIM   0x00000001
#define USB_DEVICE_ADDRESS_OP_RELEASE 0x00000002

/* ---------- various ---------- */

/* reference types */

/** reference type for an endpoint for usb_find_object and the usb_reference
 * calls.
 *
 * @memo reference type for endpoint
 * @see usb_reference_deregister
 * @see usb_find_object
*/
#define USB_REFERENCE_ENDPOINT   0

/** reference type for an device for usb_find_object and the usb_reference
 * calls.
 *
 * @memo reference type for endpoint
 * @see usb_reference_deregister
 * @see usb_find_object
*/
#define USB_REFERENCE_DEVICE     1

/** reference type for an host controller for usb_find_object and the usb_reference
 * calls.
 *
 * @memo reference type for a host controller
 * @see usb_reference_deregister
 * @see usb_find_object
*/
#define USB_REFERENCE_CONTROLLER 2


/* independent Bits controlling behaviour of USB_FindObject */



/** usb_find_object will automatically decrement the reference count of
 * the master structure passed if this flag is un-set. If you want to
 * keep the reference count of the master argument then set this flag.
 *
 * this flag does not affect the reference count of the returned object
 *
 * @memo usb_find_object - keep master structure reference
 * @see usb_find_object
 */
#define USB_FIND_KEEP_REFERENCE (1)

/** Used with usb_find_object to search through a list of the specified type
 * of object.
 * @memo Enable searching with usb_find_object
 * @see usb_find_object
 * @see USB_REFERENCE_ENDPOINT
 * @see USB_REFERENCE_DEVICE
 * @see USB_REFERENCE_CONTROLLER
*/
#define USB_FIND_NEXT_OBJECT    (2)

/** Used with usb_find_object to modify USB_FIND_NEXT_OBJECT to allow any
 * objects that are currently hidden from the normal user (such as devices
 * pending deletion) are returned in the find. Note, this may also remove
 * any of the ordering of results that USB_FIND_NEXT_OBJECT was doing)
 *
 *
 * @memo Modify searching with usb_find_object
 * @see usb_find_object
 * @see USB_REFERENCE_ENDPOINT
 * @see USB_REFERENCE_DEVICE
 * @see USB_REFERENCE_CONTROLLER
 * @see USB_FIND_NEXT_OBJECT
*/

#define USB_FIND_HIDDEN_OBJECTS (4)

/* Level 2 Module Controller Communication */

/* ---------- Control Request ---------- */
/* Characteristics of Request */
#define USB_CONTROL_SETUP_TRANSFER_TO_DEVICE  0x00
#define USB_CONTROL_SETUP_TRANSFER_TO_HOST    0x80
#define USB_CONTROL_SETUP_TYPE_STANDARD       0x00
#define USB_CONTROL_SETUP_TYPE_CLASS          0x20
#define USB_CONTROL_SETUP_TYPE_VENDOR         0x40
#define USB_CONTROL_SETUP_RECIPIENT_DEVICE    0x00
#define USB_CONTROL_SETUP_RECIPIENT_INTERFACE 0x01
#define USB_CONTROL_SETUP_RECIPIENT_ENDPOINT  0x02
#define USB_CONTROL_SETUP_RECIPIENT_OTHER     0x03

/* Standard Control Request Codes */
#define USB_CONTROL_REQUEST_GET_STATUS        0x00
#define USB_CONTROL_REQUEST_CLEAR_FEATURE     0x01
#define USB_CONTROL_REQUEST_SET_FEATURE       0x03
#define USB_CONTROL_REQUEST_SET_ADDRESS       0x05
#define USB_CONTROL_REQUEST_GET_DESCRIPTOR    0x06
#define USB_CONTROL_REQUEST_SET_DESCRIPTOR    0x07
#define USB_CONTROL_REQUEST_GET_CONFIGURATION 0x08
#define USB_CONTROL_REQUEST_SET_CONFIGURATION 0x09
#define USB_CONTROL_REQUEST_GET_INTERFACE     0x0A
#define USB_CONTROL_REQUEST_SET_INTERFACE     0x0B
#define USB_CONTROL_REQUEST_SYNCH_FRAME       0x0C

/* Descriptor Types */
#define USB_CONTROL_DESCRIPTOR_DEVICE                    0x01
#define USB_CONTROL_DESCRIPTOR_CONFIGURATION             0x02
#define USB_CONTROL_DESCRIPTOR_STRING                    0x03
#define USB_CONTROL_DESCRIPTOR_INTERFACE                 0x04
#define USB_CONTROL_DESCRIPTOR_ENDPOINT                  0x05

/* Setup Features */
#define USB_CONTROL_FEATURE_ENDPOINT_HALT        0x00
#define USB_CONTROL_FEATURE_DEVICE_REMOTE_WAKEUP 0x01

/* Technical Problems:
 *
 * USB packets can have data aligned on non-system word aligned boundaries,
 * making reading some fields difficult for some compiler/cpu combinations.
 *
 * For example, Norcroft/ARM7 cannot easily load from arbitray aligned 16
 * or 32bit quantiied.
 *
 * The usb data acess function in data.h use the following tags to create
 * code to load from these structures.
 *
 * tag is formed from:
 *     bits 00..15: offset from the start of the structure
 *     bits 16..24: size of the value
 *     bits 25..32: arrary size for when in array
 *
*/


/* ---------- Special USB defined structures ---------- */
/* Standard Request Setup Buffer */
#define USB_STRUCT_SETUP_BUFFER_bmRequestType              0x00010000
#define USB_STRUCT_SETUP_BUFFER_bRequest                   0x00010001
#define USB_STRUCT_SETUP_BUFFER_wValue                     0x00020002
#define USB_STRUCT_SETUP_BUFFER_wIndex                     0x00020004
#define USB_STRUCT_SETUP_BUFFER_wLength                    0x00020006
#define USB_STRUCT_SETUP_BUFFER_SIZE                       0x00000008

/* ---------- Descriptors ---------- */
/* Common to all Descriptors */
#define USB_STRUCT_DESCR_bLength                           0x00010000
#define USB_STRUCT_DESCR_bDescriptorType                   0x00010001

/* Device Descriptor */
#define USB_STRUCT_DESCR_DEVICE_bcdUSB                     0x00020002
#define USB_STRUCT_DESCR_DEVICE_bDeviceClass               0x00010004
#define USB_STRUCT_DESCR_DEVICE_bDeviceSubClass            0x00010005
#define USB_STRUCT_DESCR_DEVICE_bDeviceProtocol            0x00010006
#define USB_STRUCT_DESCR_DEVICE_bMaxPacketSize0            0x00010007
#define USB_STRUCT_DESCR_DEVICE_IdVendor                   0x00020008
#define USB_STRUCT_DESCR_DEVICE_IdProduct                  0x0002000A
#define USB_STRUCT_DESCR_DEVICE_bcdDevice                  0x0002000C
#define USB_STRUCT_DESCR_DEVICE_iManufacturer              0x0001000E
#define USB_STRUCT_DESCR_DEVICE_iProduct                   0x0001000F
#define USB_STRUCT_DESCR_DEVICE_iSerialNumber              0x00010010
#define USB_STRUCT_DESCR_DEVICE_bNumConfigurations         0x00010011
#define USB_STRUCT_DESCR_DEVICE_SIZE                       0x00000012

/* Configuration */
#define USB_STRUCT_DESCR_CONFIGURATION_wTotalLength        0x00020002
#define USB_STRUCT_DESCR_CONFIGURATION_bNumInterfaces      0x00010004
#define USB_STRUCT_DESCR_CONFIGURATION_bConfigurationValue 0x00010005
#define USB_STRUCT_DESCR_CONFIGURATION_iConfiguration      0x00010006
#define USB_STRUCT_DESCR_CONFIGURATION_bmAttributes        0x00010007
#define USB_STRUCT_DESCR_CONFIGURATION_bMaxPower           0x00010008
#define USB_STRUCT_DESCR_CONFIGURATION_SIZE                0x00000009

/* Language */
#define USB_STRUCT_DESCR_LANGUAGE_wLANGID                  0x7E020002
#define USB_STRUCT_DESCR_LANGUAGE_SIZE                     0x000000FE

/* String */
#define USB_STRUCT_DESCR_STRING_bString                    0xFD010002
#define USB_STRUCT_DESCR_STRING_SIZE                       0x000000FF

/* Interface */
#define USB_STRUCT_DESCR_INTERFACE_bInterfaceNumber        0x00010002
#define USB_STRUCT_DESCR_INTERFACE_bAlternateSetting       0x00010003
#define USB_STRUCT_DESCR_INTERFACE_bNumEndpoints           0x00010004
#define USB_STRUCT_DESCR_INTERFACE_bInterfaceClass         0x00010005
#define USB_STRUCT_DESCR_INTERFACE_bInterfaceSubClass      0x00010006
#define USB_STRUCT_DESCR_INTERFACE_bInterfaceProtocol      0x00010007
#define USB_STRUCT_DESCR_INTERFACE_iInterface              0x00010008
#define USB_STRUCT_DESCR_INTERFACE_SIZE                    0x00000009

/* Endpoint */
#define USB_STRUCT_DESCR_ENDPOINT_bEndpointAddress         0x00010002
#define USB_STRUCT_DESCR_ENDPOINT_bmAttributes             0x00010003
#define USB_STRUCT_DESCR_ENDPOINT_wMaxPacketSize           0x00020004
#define USB_STRUCT_DESCR_ENDPOINT_bInterval                0x00010006
#define USB_STRUCT_DESCR_ENDPOINT_SIZE                     0x00000007

/* On The Go */
#define USB_STRUCT_DESCR_OTG_bmAttributes                  0x00010002
#define USB_STRUCT_DESCR_OTG_SIZE                          0x00000003

/* include system specific definitions */

#include "usb/sys/usb-defs.h"

/* incldue the structure definitons here for the moment... */

#include "usb/errors.h"
#include "usb/waiting.h"
#include "usb/structs.h"

#endif  /* __USB_DEFS_H */
