firmware/usbdrv/usbconfig-prototype.h

   1 /* Name: usbconfig.h
   2  * Project: AVR USB driver
   3  * Author: Christian Starkjohann
   4  * Creation Date: 2005-04-01
   5  * Tabsize: 4
   6  * Copyright: (c) 2005 by OBJECTIVE DEVELOPMENT Software GmbH
   7  * License: GNU GPL v2 (see License.txt) or proprietary (CommercialLicense.txt)
   8  * This Revision: $Id: usbconfig-prototype.h 358 2007-06-23 13:30:30Z cs $
   9  */
  10
  11 #ifndef __usbconfig_h_included__
  12 #define __usbconfig_h_included__
  13
  14 /*
  15 General Description:
  16 This file is an example configuration (with inline documentation) for the USB
  17 driver. It configures AVR-USB for an ATMega8 with USB D+ connected to Port D
  18 bit 2 (which is also hardware interrupt 0) and USB D- to Port D bit 0. You may
  19 wire the lines to any other port, as long as D+ is also wired to INT0.
  20 To create your own usbconfig.h file, copy this file to the directory
  21 containing "usbdrv" (that is your project firmware source directory) and
  22 rename it to "usbconfig.h". Then edit it accordingly.
  23 */
  24
  25 /* ---------------------------- Hardware Config ---------------------------- */
  26
  27 #define USB_CFG_IOPORTNAME      D
  28 /* This is the port where the USB bus is connected. When you configure it to
  29  * "B", the registers PORTB, PINB and DDRB will be used.
  30  */
  31 #define USB_CFG_DMINUS_BIT      0
  32 /* This is the bit number in USB_CFG_IOPORT where the USB D- line is connected.
  33  * This may be any bit in the port.
  34  */
  35 #define USB_CFG_DPLUS_BIT       2
  36 /* This is the bit number in USB_CFG_IOPORT where the USB D+ line is connected.
  37  * This may be any bit in the port. Please note that D+ must also be connected
  38  * to interrupt pin INT0!
  39  */
  40 /* #define USB_CFG_CLOCK_KHZ       (F_CPU/1000) */
  41 /* Clock rate of the AVR in MHz. Legal values are 12000, 16000 or 16500.
  42  * The 16.5 MHz version of the code requires no crystal, it tolerates +/- 1%
  43  * deviation from the nominal frequency. All other rates require a precision
  44  * of 2000 ppm and thus a crystal!
  45  * Default if not specified: 12 MHz
  46  */
  47
  48 /* ----------------------- Optional Hardware Config ------------------------ */
  49
  50 /* #define USB_CFG_PULLUP_IOPORTNAME   D */
  51 /* If you connect the 1.5k pullup resistor from D- to a port pin instead of
  52  * V+, you can connect and disconnect the device from firmware by calling
  53  * the macros usbDeviceConnect() and usbDeviceDisconnect() (see usbdrv.h).
  54  * This constant defines the port on which the pullup resistor is connected.
  55  */
  56 /* #define USB_CFG_PULLUP_BIT          4 */
  57 /* This constant defines the bit number in USB_CFG_PULLUP_IOPORT (defined
  58  * above) where the 1.5k pullup resistor is connected. See description
  59  * above for details.
  60  */
  61
  62 /* --------------------------- Functional Range ---------------------------- */
  63
  64 #define USB_CFG_HAVE_INTRIN_ENDPOINT    1
  65 /* Define this to 1 if you want to compile a version with two endpoints: The
  66  * default control endpoint 0 and an interrupt-in endpoint 1.
  67  */
  68 #define USB_CFG_HAVE_INTRIN_ENDPOINT3   0
  69 /* Define this to 1 if you want to compile a version with three endpoints: The
  70  * default control endpoint 0, an interrupt-in endpoint 1 and an interrupt-in
  71  * endpoint 3. You must also enable endpoint 1 above.
  72  */
  73 #define USB_CFG_IMPLEMENT_HALT          0
  74 /* Define this to 1 if you also want to implement the ENDPOINT_HALT feature
  75  * for endpoint 1 (interrupt endpoint). Although you may not need this feature,
  76  * it is required by the standard. We have made it a config option because it
  77  * bloats the code considerably.
  78  */
  79 #define USB_CFG_INTR_POLL_INTERVAL      20
  80 /* If you compile a version with endpoint 1 (interrupt-in), this is the poll
  81  * interval. The value is in milliseconds and must not be less than 10 ms for
  82  * low speed devices.
  83  */
  84 #define USB_CFG_IS_SELF_POWERED         0
  85 /* Define this to 1 if the device has its own power supply. Set it to 0 if the
  86  * device is powered from the USB bus.
  87  */
  88 #define USB_CFG_MAX_BUS_POWER           100
  89 /* Set this variable to the maximum USB bus power consumption of your device.
  90  * The value is in milliamperes. [It will be divided by two since USB
  91  * communicates power requirements in units of 2 mA.]
  92  */
  93 #define USB_CFG_IMPLEMENT_FN_WRITE      0
  94 /* Set this to 1 if you want usbFunctionWrite() to be called for control-out
  95  * transfers. Set it to 0 if you don't need it and want to save a couple of
  96  * bytes.
  97  */
  98 #define USB_CFG_IMPLEMENT_FN_READ       0
  99 /* Set this to 1 if you need to send control replies which are generated
 100  * "on the fly" when usbFunctionRead() is called. If you only want to send
 101  * data from a static buffer, set it to 0 and return the data from
 102  * usbFunctionSetup(). This saves a couple of bytes.
 103  */
 104 #define USB_CFG_IMPLEMENT_FN_WRITEOUT   0
 105 /* Define this to 1 if you want to use interrupt-out (or bulk out) endpoint 1.
 106  * You must implement the function usbFunctionWriteOut() which receives all
 107  * interrupt/bulk data sent to endpoint 1.
 108  */
 109 #define USB_CFG_HAVE_FLOWCONTROL        0
 110 /* Define this to 1 if you want flowcontrol over USB data. See the definition
 111  * of the macros usbDisableAllRequests() and usbEnableAllRequests() in
 112  * usbdrv.h.
 113  */
 114
 115 /* -------------------------- Device Description --------------------------- */
 116
 117 #define  USB_CFG_VENDOR_ID       0xc0, 0x16
 118 /* USB vendor ID for the device, low byte first. If you have registered your
 119  * own Vendor ID, define it here. Otherwise you use obdev's free shared
 120  * VID/PID pair. Be sure to read USBID-License.txt for rules!
 121  * This template uses obdev's shared VID/PID pair for HIDs: 0x16c0/0x5df.
 122  * Use this VID/PID pair ONLY if you understand the implications!
 123  */
 124 #define  USB_CFG_DEVICE_ID       0xdf, 0x05
 125 /* This is the ID of the product, low byte first. It is interpreted in the
 126  * scope of the vendor ID. If you have registered your own VID with usb.org
 127  * or if you have licensed a PID from somebody else, define it here. Otherwise
 128  * you use obdev's free shared VID/PID pair. Be sure to read the rules in
 129  * USBID-License.txt!
 130  * This template uses obdev's shared VID/PID pair for HIDs: 0x16c0/0x5df.
 131  * Use this VID/PID pair ONLY if you understand the implications!
 132  */
 133 #define USB_CFG_DEVICE_VERSION  0x00, 0x01
 134 /* Version number of the device: Minor number first, then major number.
 135  */
 136 #define USB_CFG_VENDOR_NAME     'w', 'w', 'w', '.', 'o', 'b', 'd', 'e', 'v', '.', 'a', 't'
 137 #define USB_CFG_VENDOR_NAME_LEN 12
 138 /* These two values define the vendor name returned by the USB device. The name
 139  * must be given as a list of characters under single quotes. The characters
 140  * are interpreted as Unicode (UTF-16) entities.
 141  * If you don't want a vendor name string, undefine these macros.
 142  * ALWAYS define a vendor name containing your Internet domain name if you use
 143  * obdev's free shared VID/PID pair. See the file USBID-License.txt for
 144  * details.
 145  */
 146 #define USB_CFG_DEVICE_NAME     'T', 'e', 'm', 'p', 'l', 'a', 't', 'e'
 147 #define USB_CFG_DEVICE_NAME_LEN 8
 148 /* Same as above for the device name. If you don't want a device name, undefine
 149  * the macros. See the file USBID-License.txt before you assign a name if you
 150  * use a shared VID/PID.
 151  */
 152 /*#define USB_CFG_SERIAL_NUMBER   'N', 'o', 'n', 'e' */
 153 /*#define USB_CFG_SERIAL_NUMBER_LEN   0 */
 154 /* Same as above for the serial number. If you don't want a serial number,
 155  * undefine the macros.
 156  * It may be useful to provide the serial number through other means than at
 157  * compile time. See the section about descriptor properties below for how
 158  * to fine tune control over USB descriptors such as the string descriptor
 159  * for the serial number.
 160  */
 161 #define USB_CFG_DEVICE_CLASS        0
 162 #define USB_CFG_DEVICE_SUBCLASS     0
 163 /* See USB specification if you want to conform to an existing device class.
 164  */
 165 #define USB_CFG_INTERFACE_CLASS     3   /* HID */
 166 #define USB_CFG_INTERFACE_SUBCLASS  0
 167 #define USB_CFG_INTERFACE_PROTOCOL  0
 168 /* See USB specification if you want to conform to an existing device class or
 169  * protocol.
 170  * This template defines a HID class device. If you implement a vendor class
 171  * device, set USB_CFG_INTERFACE_CLASS to 0 and USB_CFG_DEVICE_CLASS to 0xff.
 172  */
 173 #define USB_CFG_HID_REPORT_DESCRIPTOR_LENGTH    42  /* total length of report descriptor */
 174 /* Define this to the length of the HID report descriptor, if you implement
 175  * an HID device. Otherwise don't define it or define it to 0.
 176  * Since this template defines a HID device, it must also specify a HID
 177  * report descriptor length. You must add a PROGMEM character array named
 178  * "usbHidReportDescriptor" to your code which contains the report descriptor.
 179  * Don't forget to keep the array and this define in sync!
 180  */
 181
 182 /* #define USB_PUBLIC static */
 183 /* Use the define above if you #include usbdrv.c instead of linking against it.
 184  * This technique saves a couple of bytes in flash memory.
 185  */
 186
 187 /* ------------------- Fine Control over USB Descriptors ------------------- */
 188 /* If you don't want to use the driver's default USB descriptors, you can
 189  * provide our own. These can be provided as (1) fixed length static data in
 190  * flash memory, (2) fixed length static data in RAM or (3) dynamically at
 191  * runtime in the function usbFunctionDescriptor(). See usbdrv.h for more
 192  * information about this function.
 193  * Descriptor handling is configured through the descriptor's properties. If
 194  * no properties are defined or if they are 0, the default descriptor is used.
 195  * Possible properties are:
 196  *   + USB_PROP_IS_DYNAMIC: The data for the descriptor should be fetched
 197  *     at runtime via usbFunctionDescriptor().
 198  *   + USB_PROP_IS_RAM: The data returned by usbFunctionDescriptor() or found
 199  *     in static memory is in RAM, not in flash memory.
 200  *   + USB_PROP_LENGTH(len): If the data is in static memory (RAM or flash),
 201  *     the driver must know the descriptor's length. The descriptor itself is
 202  *     found at the address of a well known identifier (see below).
 203  * List of static descriptor names (must be declared PROGMEM if in flash):
 204  *   char usbDescriptorDevice[];
 205  *   char usbDescriptorConfiguration[];
 206  *   char usbDescriptorHidReport[];
 207  *   char usbDescriptorString0[];
 208  *   int usbDescriptorStringVendor[];
 209  *   int usbDescriptorStringDevice[];
 210  *   int usbDescriptorStringSerialNumber[];
 211  * Other descriptors can't be provided statically, they must be provided
 212  * dynamically at runtime.
 213  *
 214  * Descriptor properties are or-ed or added together, e.g.:
 215  * #define USB_CFG_DESCR_PROPS_DEVICE   (USB_PROP_IS_RAM | USB_PROP_LENGTH(18))
 216  *
 217  * The following descriptors are defined:
 218  *   USB_CFG_DESCR_PROPS_DEVICE
 219  *   USB_CFG_DESCR_PROPS_CONFIGURATION
 220  *   USB_CFG_DESCR_PROPS_STRINGS
 221  *   USB_CFG_DESCR_PROPS_STRING_0
 222  *   USB_CFG_DESCR_PROPS_STRING_VENDOR
 223  *   USB_CFG_DESCR_PROPS_STRING_PRODUCT
 224  *   USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER
 225  *   USB_CFG_DESCR_PROPS_HID
 226  *   USB_CFG_DESCR_PROPS_HID_REPORT
 227  *   USB_CFG_DESCR_PROPS_UNKNOWN (for all descriptors not handled by the driver)
 228  *
 229  */
 230
 231 #define USB_CFG_DESCR_PROPS_DEVICE                  0
 232 #define USB_CFG_DESCR_PROPS_CONFIGURATION           0
 233 #define USB_CFG_DESCR_PROPS_STRINGS                 0
 234 #define USB_CFG_DESCR_PROPS_STRING_0                0
 235 #define USB_CFG_DESCR_PROPS_STRING_VENDOR           0
 236 #define USB_CFG_DESCR_PROPS_STRING_PRODUCT          0
 237 #define USB_CFG_DESCR_PROPS_STRING_SERIAL_NUMBER    0
 238 #define USB_CFG_DESCR_PROPS_HID                     0
 239 #define USB_CFG_DESCR_PROPS_HID_REPORT              0
 240 #define USB_CFG_DESCR_PROPS_UNKNOWN                 0
 241
 242 /* ----------------------- Optional MCU Description ------------------------ */
 243
 244 /* The following configurations have working defaults in usbdrv.h. You
 245  * usually don't need to set them explicitly. Only if you want to run
 246  * the driver on a device which is not yet supported or with a compiler
 247  * which is not fully supported (such as IAR C) or if you use a differnt
 248  * interrupt than INT0, you may have to define some of these.
 249  */
 250 /* #define USB_INTR_CFG            MCUCR */
 251 /* #define USB_INTR_CFG_SET        ((1 << ISC00) | (1 << ISC01)) */
 252 /* #define USB_INTR_CFG_CLR        0 */
 253 /* #define USB_INTR_ENABLE         GIMSK */
 254 /* #define USB_INTR_ENABLE_BIT     INT0 */
 255 /* #define USB_INTR_PENDING        GIFR */
 256 /* #define USB_INTR_PENDING_BIT    INTF0 */
 257
 258 #endif /* __usbconfig_h_included__ */