Projects/AVRISP-MKII/AVRISPDescriptors.c

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2015.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2015  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(1,1,0),
  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(2,0,0),
  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 = USB_STRING_DESCRIPTOR_ARRAY(LANGUAGE_ID_ENG);
 146
 147 /** Manufacturer descriptor string. This is a Unicode string containing the manufacturer's details in human readable
 148  *  form, and is read out upon request by the host when the appropriate string ID is requested, listed in the Device
 149  *  Descriptor.
 150  */
 151 const USB_Descriptor_String_t PROGMEM AVRISP_ManufacturerString = USB_STRING_DESCRIPTOR(L"ATMEL");
 152
 153 /** Product descriptor string. This is a Unicode string containing the product's details in human readable form,
 154  *  and is read out upon request by the host when the appropriate string ID is requested, listed in the Device
 155  *  Descriptor.
 156  */
 157 const USB_Descriptor_String_t PROGMEM AVRISP_ProductString = USB_STRING_DESCRIPTOR(L"AVRISP mkII");
 158
 159 /** Serial number string. This is a Unicode string containing the device's unique serial number, expressed as a
 160  *  series of uppercase hexadecimal digits.
 161  */
 162 USB_Descriptor_String_t AVRISP_SerialString = USB_STRING_DESCRIPTOR(L"000200012345\0"
 163     // Note: Real AVRISP-MKII has the embedded NUL byte, bug in firmware?
 164 );
 165
 166 /** This function is called by the library when in device mode, and must be overridden (see library "USB Descriptors"
 167  *  documentation) by the application code so that the address and size of a requested descriptor can be given
 168  *  to the USB library. When the device receives a Get Descriptor request on the control endpoint, this function
 169  *  is called so that the descriptor details can be passed back and the appropriate descriptor sent back to the
 170  *  USB host.
 171  */
 172 uint16_t AVRISP_GetDescriptor(const uint16_t wValue,
 173                               const uint8_t wIndex,
 174                               const void** const DescriptorAddress,
 175                               uint8_t* DescriptorMemorySpace)
 176 {
 177         const uint8_t  DescriptorType   = (wValue >> 8);
 178         const uint8_t  DescriptorNumber = (wValue & 0xFF);
 179
 180         const void* Address = NULL;
 181         uint16_t    Size    = NO_DESCRIPTOR;
 182
 183         *DescriptorMemorySpace = MEMSPACE_FLASH;
 184
 185         switch (DescriptorType)
 186         {
 187                 case DTYPE_Device:
 188                         Address = &AVRISP_DeviceDescriptor;
 189                         Size    = sizeof(USB_Descriptor_Device_t);
 190                         break;
 191                 case DTYPE_Configuration:
 192                         *DescriptorMemorySpace = MEMSPACE_RAM;
 193                         #if defined(RESET_TOGGLES_LIBUSB_COMPAT)
 194                                 /* Update the configuration descriptor with the current endpoint address */
 195                                 AVRISP_ConfigurationDescriptor.AVRISP_DataInEndpoint.EndpointAddress = AVRISP_CurrDataINEndpointAddress;
 196                         #endif
 197
 198                         Address = &AVRISP_ConfigurationDescriptor;
 199                         Size    = sizeof(AVRISP_USB_Descriptor_Configuration_t);
 200                         break;
 201                 case DTYPE_String:
 202                         switch (DescriptorNumber)
 203                         {
 204                                 case AVRISP_STRING_ID_Language:
 205                                         Address = &AVRISP_LanguageString;
 206                                         Size    = pgm_read_byte(&AVRISP_LanguageString.Header.Size);
 207                                         break;
 208                                 case AVRISP_STRING_ID_Manufacturer:
 209                                         Address = &AVRISP_ManufacturerString;
 210                                         Size    = pgm_read_byte(&AVRISP_ManufacturerString.Header.Size);
 211                                         break;
 212                                 case AVRISP_STRING_ID_Product:
 213                                         Address = &AVRISP_ProductString;
 214                                         Size    = pgm_read_byte(&AVRISP_ProductString.Header.Size);
 215                                         break;
 216                                 case AVRISP_STRING_ID_Serial:
 217                                         Address = &AVRISP_SerialString;
 218                                         Size    = AVRISP_SerialString.Header.Size;
 219
 220                                         /* Update serial number to have a different serial based on the current endpoint address */
 221                                         ((uint16_t*)&AVRISP_SerialString.UnicodeString)[6] = cpu_to_le16('0' + (AVRISP_DATA_IN_EPADDR & ENDPOINT_EPNUM_MASK));
 222
 223                                         *DescriptorMemorySpace = MEMSPACE_RAM;
 224                                         break;
 225                         }
 226
 227                         break;
 228         }
 229
 230         *DescriptorAddress = Address;
 231         return Size;
 232 }
 233
 234 #if defined(RESET_TOGGLES_LIBUSB_COMPAT) || defined(__DOXYGEN__)
 235 /** Checks the state of the system status register MCUSR and indicates via a flag if
 236  *  the current AVRISP driver compatibility mode needs to be reset.
 237  *
 238  *  When the \c RESET_TOGGLES_LIBUSB_COMPAT compile time option is enabled, pulling
 239  *  the reset line of the AVR low will toggle between Jungo and libUSB compatibility
 240  *  modes. Other forms of reset (such as power on or watchdog) will not force a mode
 241  *  change.
 242  */
 243 void CheckExternalReset(void)
 244 {
 245         /* If an external reset occurred, we need to change compatibility mode */
 246         AVRISP_NeedCompatibilitySwitch = (MCUSR == (1 << EXTRF));
 247
 248         MCUSR = 0;
 249 }
 250
 251 /** Updates the device descriptors so that the correct compatibility mode is used
 252  *  when the \c RESET_TOGGLES_LIBUSB_COMPAT compile time option is enabled. This
 253  *  configures the programmer for either Jungo or libUSB driver compatibility. Each
 254  *  time the AVR is reset via pulling the reset line low the compatibility mode will
 255  *  be toggled. The current mode is stored in EEPROM and preserved through power
 256  *  cycles of the AVR.
 257  */
 258 void UpdateCurrentCompatibilityMode(void)
 259 {
 260         /* Load the current IN endpoint address stored in EEPROM */
 261         AVRISP_CurrDataINEndpointAddress = eeprom_read_byte(&AVRISP_CurrDataINEndpointAddress_EEPROM);
 262
 263         /* Check if we need to switch compatibility modes */
 264         if (AVRISP_NeedCompatibilitySwitch)
 265         {
 266                 /* Toggle between compatibility modes */
 267                 AVRISP_CurrDataINEndpointAddress = (AVRISP_CurrDataINEndpointAddress == AVRISP_DATA_IN_EPADDR_LIBUSB) ?
 268                                 AVRISP_DATA_IN_EPADDR_JUNGO : AVRISP_DATA_IN_EPADDR_LIBUSB;
 269
 270                 /* Save the new mode into EEPROM */
 271                 eeprom_update_byte(&AVRISP_CurrDataINEndpointAddress_EEPROM, AVRISP_CurrDataINEndpointAddress);
 272         }
 273
 274         LEDs_SetAllLEDs(LEDS_NO_LEDS);
 275
 276         /* Validate IN endpoint address and indicate current mode via LED flashes */
 277         switch (AVRISP_CurrDataINEndpointAddress)
 278         {
 279                 default:
 280                         /* Default to Jungo compatibility mode if saved EEPROM is invalid */
 281                         AVRISP_CurrDataINEndpointAddress = AVRISP_DATA_IN_EPADDR_JUNGO;
 282                 case AVRISP_DATA_IN_EPADDR_JUNGO:
 283                         /* Two flashes for Jungo compatibility mode */
 284                         for (uint8_t i = 0; i < 4; i++)
 285                         {
 286                                 LEDs_ToggleLEDs(LEDS_ALL_LEDS);
 287                                 Delay_MS(100);
 288                         }
 289                         break;
 290                 case AVRISP_DATA_IN_EPADDR_LIBUSB:
 291                         /* Five flashes for libUSB compatibility mode */
 292                         for (uint8_t i = 0; i < 10; i++)
 293                         {
 294                                 LEDs_ToggleLEDs(LEDS_ALL_LEDS);
 295                                 Delay_MS(100);
 296                         }
 297                         break;
 298         }
 299
 300         Delay_MS(500);
 301 }
 302 #endif