fx2lib/include/setupdat.h

   1 // Copyright (C) 2009 Ubixum, Inc.
   2 //
   3 // This library is free software; you can redistribute it and/or
   4 // modify it under the terms of the GNU Lesser General Public
   5 // License as published by the Free Software Foundation; either
   6 // version 2.1 of the License, or (at your option) any later version.
   7 //
   8 // This library is distributed in the hope that it will be useful,
   9 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 // Lesser General Public License for more details.
  12 //
  13 // You should have received a copy of the GNU Lesser General Public
  14 // License along with this library; if not, see <http://www.gnu.org/licenses/>.
  15
  16 #ifndef SETUPDAT_H
  17 #define SETUPDAT_H
  18
  19 #include "fx2regs.h"
  20 #include "delay.h"
  21 /** \file setupdat.h
  22   Utilities for handling setup data and vendor commands.
  23
  24  \verbatim
  25
  26  This module needs initialized with a device descriptor.
  27  NOTE that your descriptors need to be located in code memory
  28  to use the SUDPTRH:L to auto transfer the data
  29
  30  and vendor commands handler.  You have to provide callbacks.
  31
  32 DEVICE DESCRIPTORS
  33
  34  // copy the dscr_asm file from the lib dir to your
  35  // own project directory, change it how
  36  // you want, and link it against your project
  37
  38 VENDOR COMMANDS
  39
  40   0xA0 is handled by ez-usb firmware.  (Upload/Download ram)
  41   0xA1-0xAF is reserved for other ez-usb functions so don't use that
  42   Any other value (Above 0x0C anyway) can be used for device specific
  43   commands.
  44
  45   If you include this file, you need to define a function for vendor
  46   commands even if you don't want to implement any vendor commands.
  47   The function should return TRUE if you handled the command and FALSE
  48   if you didn't.  The handle_setup function calls
  49   EP0CS |= bmHSNAK;
  50   before returning so there is no reason to set that bit in your
  51   vendor command handler.  (You do need to Set EP0 data and
  52   byte counts appropriately though.)
  53
  54   // return TRUE if you handle the command
  55   // you can directly get SETUPDAT[0-7] for the data sent with the command
  56   BOOL handle_vendorcommand(BYTE cmd) { return FALSE; }
  57   // a note  on vencor commands
  58   // this from the usb spec for requesttype
  59         D7 Data Phase Transfer Direction
  60         0 = Host to Device
  61         1 = Device to Host
  62         D6..5 Type
  63         0 = Standard
  64         1 = Class
  65         2 = Vendor
  66         3 = Reserved
  67         D4..0 Recipient
  68         0 = Device
  69         1 = Interface
  70         2 = Endpoint
  71         3 = Other
  72         4..31 = Reserved
  73   // if you want libusb to send data back to the host via ep0, you need to make
  74   // sure the requesttype had 1 in bit 7.  This is for libusb on linux anyway.
  75
  76
  77   // set *alt_ifc to the current alt interface for ifc
  78   BOOL handle_get_interface(BYTE ifc, BYTE* alt_ifc) { *ifc=0;*alt_ifc=0;}
  79   // return TRUE if you set the interface requested
  80   // NOTE this function should reconfigure and reset the endpoints
  81   // according to the interface descriptors you provided.
  82   BOOL handle_set_interface(BYTE ifc,BYTE alt_ifc) { return TRUE; }
  83   // handle getting and setting the configuration
  84   // 0 is the default.  If you support more than one config
  85   // keep track of the config number and return the correct number
  86   // config numbers are set int the dscr file.
  87   BYTE handle_get_configuration() { return 1; }
  88   // return TRUE if you handle this request
  89   // NOTE changing config requires the device to reset all the endpoints
  90   BOOL handle_set_configuration(BYTE cfg) { return FALSE; }
  91   // ep num (byte 7 is dir 1=IN,0=OUT)
  92   // client needs to reset the endpoint to default state
  93   void handle_reset_ep(BYTE ep) { }
  94
  95   \endverbatim
  96 */
  97
  98
  99 #define SETUP_VALUE() MAKEWORD(SETUPDAT[3],SETUPDAT[2])
 100 #define SETUP_INDEX() MAKEWORD(SETUPDAT[5],SETUPDAT[4])
 101 #define SETUP_LENGTH() MAKEWORD(SETUPDAT[7],SETUPDAT[6])
 102 #define SETUP_TYPE SETUPDAT[0]
 103
 104 /**
 105  * self_powered is set to FALSE by default.  It is
 106  * used for GET_FEATURE requests.  Firmware can set it to
 107  * TRUE if the device is not powered by the USB bus.
 108  **/
 109 extern volatile BOOL self_powered;
 110
 111 /**
 112  * remote_wakeup_allowed defaults to FALSE but can be
 113  * set to TRUE with SET_FEATURE from the host. (firmware shouldn't
 114  * set this.)
 115  **/
 116 extern volatile BOOL remote_wakeup_allowed;
 117
 118 //! see TRM 2-3
 119 //! here are the usb setup data commands
 120 //! these are the usb spec pretty much
 121
 122 typedef enum {
 123     GET_STATUS,
 124     CLEAR_FEATURE,
 125     // 0x02 is reserved
 126     SET_FEATURE=0x03,
 127     // 0x04 is reserved
 128     SET_ADDRESS=0x05, // this is handled by EZ-USB core unless RENUM=0
 129     GET_DESCRIPTOR,
 130     SET_DESCRIPTOR,
 131     GET_CONFIGURATION,
 132     SET_CONFIGURATION,
 133     GET_INTERFACE,
 134     SET_INTERFACE,
 135     SYNC_FRAME
 136 } SETUP_DATA;
 137
 138
 139 /**
 140  * returns the control/status register for an end point
 141  * (bit 7=1 for IN, 0 for out
 142  **/
 143 __xdata BYTE* ep_addr(BYTE ep);
 144
 145 /*
 146  You can call this function directly if you are polling
 147  for setup data in your main loop.
 148  You can also use the usbjt and enable the sudav isr
 149  and call the function from withing the sudav isr routine
 150 */
 151 void handle_setupdata(void);
 152
 153
 154 /**
 155     For devices to properly handle usb hispeed
 156     (This is if your descriptor has high speed and full speed versions
 157      and it should since the fx2lp is a high speed capable device
 158     )
 159     enable both USBRESET and HISPEED interrupts and
 160     call this function to switch the descriptors.  This function uses
 161     a __critical section to switch the descriptors and is safe to call
 162     from the hispeed or reset interrupt.  See \ref fw.c
 163
 164     \param highspeed Call the function with highspeed = TRUE if
 165         calling because the highspeed interrupt was received.
 166         If calling from usbreset, call with highspeed=false
 167 **/
 168 void handle_hispeed( BOOL highspeed );
 169
 170
 171 /* descriptor types */
 172 #define DSCR_DEVICE_TYPE 1
 173 #define DSCR_CONFIG_TYPE 2
 174 #define DSCR_STRING_TYPE 3
 175 #define DSCR_DEVQUAL_TYPE 6
 176 #define DSCR_OTHERSPD_TYPE 7
 177
 178 /* usb spec 2 */
 179 #define DSCR_BCD 2
 180
 181
 182 /* device descriptor */
 183 #define DSCR_DEVICE_LEN 18
 184
 185 typedef struct {
 186     BYTE dsc_len; // descriptor length (18 for this )
 187     BYTE dsc_type; // dscr type
 188     WORD bcd; // bcd
 189     BYTE dev_class; // device class
 190     BYTE dev_subclass; // sub class
 191     BYTE dev_protocol; // sub sub class
 192     BYTE max_pkt; // max packet size
 193     WORD vendor_id;
 194     WORD product_id;
 195     WORD dev_version; // product version id
 196     BYTE idx_manstr; //  manufacturer string index
 197     BYTE idx_devstr; // product string index
 198     BYTE idx_serstr; // serial number index
 199     BYTE num_configs; // number of configurations
 200
 201 } DEVICE_DSCR;
 202
 203
 204 /* config descriptor */
 205 #define DSCR_CONFIG_LEN 9
 206 typedef struct {
 207     BYTE dsc_len; // 9 for this one
 208     BYTE dsc_type; // dscr type
 209
 210 } CONFIG_DSCR;
 211
 212 /* string descriptor */
 213 typedef struct {
 214     BYTE dsc_len;
 215     BYTE dsc_type;
 216     BYTE pstr;
 217 } STRING_DSCR;
 218
 219
 220
 221
 222 #endif