Projects/AVRISP-MKII/AVRISPDescriptors.c

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2013.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2013  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaims all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *
  33  *  USB Device Descriptors, for library use when in USB device mode. Descriptors are special
  34  *  computer-readable structures which the host requests upon device enumeration, to determine
  35  *  the device's capabilities and functions.
  36  */
  37
  38 #include "AVRISPDescriptors.h"
  39
  40 #if defined(RESET_TOGGLES_LIBUSB_COMPAT) || defined(__DOXYGEN__)
  41         /** Indicates if an external reset has occurred and the compatibility mode needs to be altered */
  42         static bool AVRISP_NeedCompatibilitySwitch ATTR_NO_INIT;
  43
  44         /** Current AVRISP data IN endpoint address. */
  45         uint8_t AVRISP_CurrDataINEndpointAddress;
  46
  47         /** Saved AVRISP data IN endpoint address in EEPROM. */
  48         uint8_t AVRISP_CurrDataINEndpointAddress_EEPROM EEMEM;
  49 #endif
  50
  51 /** Device descriptor structure. This descriptor, located in FLASH memory, describes the overall
  52  *  device characteristics, including the supported USB version, control endpoint size and the
  53  *  number of device configurations. The descriptor is read out by the USB host when the enumeration
  54  *  process begins.
  55  */
  56 const USB_Descriptor_Device_t PROGMEM AVRISP_DeviceDescriptor =
  57 {
  58         .Header                 = {.Size = sizeof(USB_Descriptor_Device_t), .Type = DTYPE_Device},
  59
  60         .USBSpecification       = VERSION_BCD(01.10),
  61         .Class                  = USB_CSCP_VendorSpecificClass,
  62         .SubClass               = USB_CSCP_NoDeviceSubclass,
  63         .Protocol               = USB_CSCP_NoDeviceProtocol,
  64
  65         .Endpoint0Size          = FIXED_CONTROL_ENDPOINT_SIZE,
  66
  67         .VendorID               = 0x03EB,
  68         .ProductID              = 0x2104,
  69         .ReleaseNumber          = VERSION_BCD(02.00),
  70
  71         .ManufacturerStrIndex   = AVRISP_STRING_ID_Manufacturer,
  72         .ProductStrIndex        = AVRISP_STRING_ID_Product,
  73         .SerialNumStrIndex      = AVRISP_STRING_ID_Serial,
  74
  75         .NumberOfConfigurations = FIXED_NUM_CONFIGURATIONS
  76 };
  77
  78 /** Configuration descriptor structure. This descriptor, located in FLASH memory, describes the usage
  79  *  of the device in one of its supported configurations, including information about any device interfaces
  80  *  and endpoints. The descriptor is read out by the USB host during the enumeration process when selecting
  81  *  a configuration so that the host may correctly communicate with the USB device.
  82  */
  83 AVRISP_USB_Descriptor_Configuration_t AVRISP_ConfigurationDescriptor =
  84 {
  85         .Config =
  86                 {
  87                         .Header                 = {.Size = sizeof(USB_Descriptor_Configuration_Header_t), .Type = DTYPE_Configuration},
  88
  89                         .TotalConfigurationSize = sizeof(AVRISP_USB_Descriptor_Configuration_t),
  90                         .TotalInterfaces        = 1,
  91
  92                         .ConfigurationNumber    = 1,
  93                         .ConfigurationStrIndex  = NO_DESCRIPTOR,
  94
  95                         .ConfigAttributes       = (USB_CONFIG_ATTR_RESERVED | USB_CONFIG_ATTR_SELFPOWERED),
  96
  97                         .MaxPowerConsumption    = USB_CONFIG_POWER_MA(100)
  98                 },
  99
 100         .AVRISP_Interface =
 101                 {
 102                         .Header                 = {.Size = sizeof(USB_Descriptor_Interface_t), .Type = DTYPE_Interface},
 103
 104                         .InterfaceNumber        = INTERFACE_ID_AVRISP,
 105                         .AlternateSetting       = 0,
 106
 107                         .TotalEndpoints         = 2,
 108
 109                         .Class                  = USB_CSCP_VendorSpecificClass,
 110                         .SubClass               = USB_CSCP_NoDeviceSubclass,
 111                         .Protocol               = USB_CSCP_NoDeviceProtocol,
 112
 113                         .InterfaceStrIndex      = NO_DESCRIPTOR
 114                 },
 115
 116         .AVRISP_DataInEndpoint =
 117                 {
 118                         .Header                 = {.Size = sizeof(USB_Descriptor_Endpoint_t), .Type = DTYPE_Endpoint},
 119
 120 #if defined(RESET_TOGGLES_LIBUSB_COMPAT)
 121                         .EndpointAddress        = 0,
 122 #else
 123                         .EndpointAddress        = AVRISP_DATA_IN_EPADDR,
 124 #endif
 125                         .Attributes             = (EP_TYPE_BULK | ENDPOINT_ATTR_NO_SYNC | ENDPOINT_USAGE_DATA),
 126                         .EndpointSize           = AVRISP_DATA_EPSIZE,
 127                         .PollingIntervalMS      = 0x0A
 128                 },
 129
 130         .AVRISP_DataOutEndpoint =
 131                 {
 132                         .Header                 = {.Size = sizeof(USB_Descriptor_Endpoint_t), .Type = DTYPE_Endpoint},
 133
 134                         .EndpointAddress        = AVRISP_DATA_OUT_EPADDR,
 135                         .Attributes             = (EP_TYPE_BULK | ENDPOINT_ATTR_NO_SYNC | ENDPOINT_USAGE_DATA),
 136                         .EndpointSize           = AVRISP_DATA_EPSIZE,
 137                         .PollingIntervalMS      = 0x0A
 138                 },
 139 };
 140
 141 /** Language descriptor structure. This descriptor, located in FLASH memory, is returned when the host requests
 142  *  the string descriptor with index 0 (the first index). It is actually an array of 16-bit integers, which indicate
 143  *  via the language ID table available at USB.org what languages the device supports for its string descriptors.
 144  */
 145 const USB_Descriptor_String_t PROGMEM AVRISP_LanguageString =
 146 {
 147         .Header                 = {.Size = USB_STRING_LEN(1), .Type = DTYPE_String},
 148
 149         .UnicodeString          = {LANGUAGE_ID_ENG}
 150 };
 151
 152 /** Manufacturer descriptor string. This is a Unicode string containing the manufacturer's details in human readable
 153  *  form, and is read out upon request by the host when the appropriate string ID is requested, listed in the Device
 154  *  Descriptor.
 155  */
 156 const USB_Descriptor_String_t PROGMEM AVRISP_ManufacturerString =
 157 {
 158         .Header                 = {.Size = USB_STRING_LEN(5), .Type = DTYPE_String},
 159
 160         .UnicodeString          = L"ATMEL"
 161 };
 162
 163 /** Product descriptor string. This is a Unicode string containing the product's details in human readable form,
 164  *  and is read out upon request by the host when the appropriate string ID is requested, listed in the Device
 165  *  Descriptor.
 166  */
 167 const USB_Descriptor_String_t PROGMEM AVRISP_ProductString =
 168 {
 169         .Header                 = {.Size = USB_STRING_LEN(11), .Type = DTYPE_String},
 170
 171         .UnicodeString          = L"AVRISP mkII"
 172 };
 173
 174 /** Serial number string. This is a Unicode string containing the device's unique serial number, expressed as a
 175  *  series of uppercase hexadecimal digits.
 176  */
 177 USB_Descriptor_String_t AVRISP_SerialString =
 178 {
 179         .Header                 = {.Size = USB_STRING_LEN(13), .Type = DTYPE_String},
 180
 181         .UnicodeString          = L"000200012345\0" // Note: Real AVRISP-MKII has the embedded NUL byte, bug in firmware?
 182 };
 183
 184 /** This function is called by the library when in device mode, and must be overridden (see library "USB Descriptors"
 185  *  documentation) by the application code so that the address and size of a requested descriptor can be given
 186  *  to the USB library. When the device receives a Get Descriptor request on the control endpoint, this function
 187  *  is called so that the descriptor details can be passed back and the appropriate descriptor sent back to the
 188  *  USB host.
 189  */
 190 uint16_t AVRISP_GetDescriptor(const uint16_t wValue,
 191                               const uint8_t wIndex,
 192                               const void** const DescriptorAddress,
 193                               uint8_t* DescriptorMemorySpace)
 194 {
 195         const uint8_t  DescriptorType   = (wValue >> 8);
 196         const uint8_t  DescriptorNumber = (wValue & 0xFF);
 197
 198         const void* Address = NULL;
 199         uint16_t    Size    = NO_DESCRIPTOR;
 200
 201         *DescriptorMemorySpace = MEMSPACE_FLASH;
 202
 203         switch (DescriptorType)
 204         {
 205                 case DTYPE_Device:
 206                         Address = &AVRISP_DeviceDescriptor;
 207                         Size    = sizeof(USB_Descriptor_Device_t);
 208                         break;
 209                 case DTYPE_Configuration:
 210                         *DescriptorMemorySpace = MEMSPACE_RAM;
 211                         #if defined(RESET_TOGGLES_LIBUSB_COMPAT)
 212                                 /* Update the configuration descriptor with the current endpoint address */
 213                                 AVRISP_ConfigurationDescriptor.AVRISP_DataInEndpoint.EndpointAddress = AVRISP_CurrDataINEndpointAddress;
 214                         #endif
 215
 216                         Address = &AVRISP_ConfigurationDescriptor;
 217                         Size    = sizeof(AVRISP_USB_Descriptor_Configuration_t);
 218                         break;
 219                 case DTYPE_String:
 220                         switch (DescriptorNumber)
 221                         {
 222                                 case AVRISP_STRING_ID_Language:
 223                                         Address = &AVRISP_LanguageString;
 224                                         Size    = pgm_read_byte(&AVRISP_LanguageString.Header.Size);
 225                                         break;
 226                                 case AVRISP_STRING_ID_Manufacturer:
 227                                         Address = &AVRISP_ManufacturerString;
 228                                         Size    = pgm_read_byte(&AVRISP_ManufacturerString.Header.Size);
 229                                         break;
 230                                 case AVRISP_STRING_ID_Product:
 231                                         Address = &AVRISP_ProductString;
 232                                         Size    = pgm_read_byte(&AVRISP_ProductString.Header.Size);
 233                                         break;
 234                                 case AVRISP_STRING_ID_Serial:
 235                                         Address = &AVRISP_SerialString;
 236                                         Size    = AVRISP_SerialString.Header.Size;
 237
 238                                         /* Update serial number to have a different serial based on the current endpoint address */
 239                                         ((uint16_t*)&AVRISP_SerialString.UnicodeString)[6] = cpu_to_le16('0' + (AVRISP_DATA_IN_EPADDR & ENDPOINT_EPNUM_MASK));
 240
 241                                         *DescriptorMemorySpace = MEMSPACE_RAM;
 242                                         break;
 243                         }
 244
 245                         break;
 246         }
 247
 248         *DescriptorAddress = Address;
 249         return Size;
 250 }
 251
 252 #if defined(RESET_TOGGLES_LIBUSB_COMPAT) || defined(__DOXYGEN__)
 253 /** Checks the state of the system status register MCUSR and indicates via a flag if
 254  *  the current AVRISP driver compatibility mode needs to be reset.
 255  *
 256  *  When the \c RESET_TOGGLES_LIBUSB_COMPAT compile time option is enabled, pulling
 257  *  the reset line of the AVR low will toggle between Jungo and libUSB compatibility
 258  *  modes. Other forms of reset (such as power on or watchdog) will not force a mode
 259  *  change.
 260  */
 261 void CheckExternalReset(void)
 262 {
 263         /* If an external reset occurred, we need to change compatibility mode */
 264         AVRISP_NeedCompatibilitySwitch = (MCUSR == (1 << EXTRF));
 265
 266         MCUSR = 0;
 267 }
 268
 269 /** Updates the device descriptors so that the correct compatibility mode is used
 270  *  when the \c RESET_TOGGLES_LIBUSB_COMPAT compile time option is enabled. This
 271  *  configures the programmer for either Jungo or libUSB driver compatibility. Each
 272  *  time the AVR is reset via pulling the reset line low the compatibility mode will
 273  *  be toggled. The current mode is stored in EEPROM and preserved through power
 274  *  cycles of the AVR.
 275  */
 276 void UpdateCurrentCompatibilityMode(void)
 277 {
 278         /* Load the current IN endpoint address stored in EEPROM */
 279         AVRISP_CurrDataINEndpointAddress = eeprom_read_byte(&AVRISP_CurrDataINEndpointAddress_EEPROM);
 280
 281         /* Check if we need to switch compatibility modes */
 282         if (AVRISP_NeedCompatibilitySwitch)
 283         {
 284                 /* Toggle between compatibility modes */
 285                 AVRISP_CurrDataINEndpointAddress = (AVRISP_CurrDataINEndpointAddress == AVRISP_DATA_IN_EPADDR_LIBUSB) ?
 286                                 AVRISP_DATA_IN_EPADDR_JUNGO : AVRISP_DATA_IN_EPADDR_LIBUSB;
 287
 288                 /* Save the new mode into EEPROM */
 289                 eeprom_update_byte(&AVRISP_CurrDataINEndpointAddress_EEPROM, AVRISP_CurrDataINEndpointAddress);
 290         }
 291
 292         LEDs_SetAllLEDs(LEDS_NO_LEDS);
 293
 294         /* Validate IN endpoint address and indicate current mode via LED flashes */
 295         switch (AVRISP_CurrDataINEndpointAddress)
 296         {
 297                 default:
 298                         /* Default to Jungo compatibility mode if saved EEPROM is invalid */
 299                         AVRISP_CurrDataINEndpointAddress = AVRISP_DATA_IN_EPADDR_JUNGO;
 300                 case AVRISP_DATA_IN_EPADDR_JUNGO:
 301                         /* Two flashes for Jungo compatibility mode */
 302                         for (uint8_t i = 0; i < 4; i++)
 303                         {
 304                                 LEDs_ToggleLEDs(LEDS_ALL_LEDS);
 305                                 Delay_MS(100);
 306                         }
 307                         break;
 308                 case AVRISP_DATA_IN_EPADDR_LIBUSB:
 309                         /* Five flashes for libUSB compatibility mode */
 310                         for (uint8_t i = 0; i < 10; i++)
 311                         {
 312                                 LEDs_ToggleLEDs(LEDS_ALL_LEDS);
 313                                 Delay_MS(100);
 314                         }
 315                         break;
 316         }
 317
 318         Delay_MS(500);
 319 }
 320 #endif