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