From ba6fb7522c7333b3a9081a823f2b93a425b36022 Mon Sep 17 00:00:00 2001 From: Sam Anthony Date: Thu, 4 Sep 2025 19:05:46 -0400 Subject: fw: usb --- fw/usb_descriptors.c | 304 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100755 fw/usb_descriptors.c (limited to 'fw/usb_descriptors.c') diff --git a/fw/usb_descriptors.c b/fw/usb_descriptors.c new file mode 100755 index 0000000..ebc2c06 --- /dev/null +++ b/fw/usb_descriptors.c @@ -0,0 +1,304 @@ +/******************************************************************************* +Copyright 2016 Microchip Technology Inc. (www.microchip.com) + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +To request to license the code under the MLA license (www.microchip.com/mla_license), +please contact mla_licensing@microchip.com +*******************************************************************************/ + +/******************************************************************** +-usb_descriptors.c- +------------------------------------------------------------------- +Filling in the descriptor values in the usb_descriptors.c file: +------------------------------------------------------------------- + +[Device Descriptors] +The device descriptor is defined as a USB_DEVICE_DESCRIPTOR type. +This type is defined in usb_ch9.h Each entry into this structure +needs to be the correct length for the data type of the entry. + +[Configuration Descriptors] +The configuration descriptor was changed in v2.x from a structure +to a uint8_t array. Given that the configuration is now a byte array +each byte of multi-byte fields must be listed individually. This +means that for fields like the total size of the configuration where +the field is a 16-bit value "64,0," is the correct entry for a +configuration that is only 64 bytes long and not "64," which is one +too few bytes. + +The configuration attribute must always have the _DEFAULT +definition at the minimum. Additional options can be ORed +to the _DEFAULT attribute. Available options are _SELF and _RWU. +These definitions are defined in the usb_device.h file. The +_SELF tells the USB host that this device is self-powered. The +_RWU tells the USB host that this device supports Remote Wakeup. + +[Endpoint Descriptors] +Like the configuration descriptor, the endpoint descriptors were +changed in v2.x of the stack from a structure to a uint8_t array. As +endpoint descriptors also has a field that are multi-byte entities, +please be sure to specify both bytes of the field. For example, for +the endpoint size an endpoint that is 64 bytes needs to have the size +defined as "64,0," instead of "64," + +Take the following example: + // Endpoint Descriptor // + 0x07, //the size of this descriptor // + USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor + _EP02_IN, //EndpointAddress + _INT, //Attributes + 0x08,0x00, //size (note: 2 bytes) + 0x02, //Interval + +The first two parameters are self-explanatory. They specify the +length of this endpoint descriptor (7) and the descriptor type. +The next parameter identifies the endpoint, the definitions are +defined in usb_device.h and has the following naming +convention: +_EP<##>_ +where ## is the endpoint number and dir is the direction of +transfer. The dir has the value of either 'OUT' or 'IN'. +The next parameter identifies the type of the endpoint. Available +options are _BULK, _INT, _ISO, and _CTRL. The _CTRL is not +typically used because the default control transfer endpoint is +not defined in the USB descriptors. When _ISO option is used, +addition options can be ORed to _ISO. Example: +_ISO|_AD|_FE +This describes the endpoint as an isochronous pipe with adaptive +and feedback attributes. See usb_device.h and the USB +specification for details. The next parameter defines the size of +the endpoint. The last parameter in the polling interval. + +------------------------------------------------------------------- +Adding a USB String +------------------------------------------------------------------- +A string descriptor array should have the following format: + +rom struct{byte bLength;byte bDscType;word string[size];}sdxxx={ +sizeof(sdxxx),DSC_STR,}; + +The above structure provides a means for the C compiler to +calculate the length of string descriptor sdxxx, where xxx is the +index number. The first two bytes of the descriptor are descriptor +length and type. The rest are string texts which must be +in the unicode format. The unicode format is achieved by declaring +each character as a word type. The whole text string is declared +as a word array with the number of characters equals to . + has to be manually counted and entered into the array +declaration. Let's study this through an example: +if the string is "USB" , then the string descriptor should be: +(Using index 02) +rom struct{byte bLength;byte bDscType;word string[3];}sd002={ +sizeof(sd002),DSC_STR,'U','S','B'}; + +A USB project may have multiple strings and the firmware supports +the management of multiple strings through a look-up table. +The look-up table is defined as: +rom const unsigned char *rom USB_SD_Ptr[]={&sd000,&sd001,&sd002}; + +The above declaration has 3 strings, sd000, sd001, and sd002. +Strings can be removed or added. sd000 is a specialized string +descriptor. It defines the language code, usually this is +US English (0x0409). The index of the string must match the index +position of the USB_SD_Ptr array, &sd000 must be in position +USB_SD_Ptr[0], &sd001 must be in position USB_SD_Ptr[1] and so on. +The look-up table USB_SD_Ptr is used by the get string handler +function. + +------------------------------------------------------------------- + +The look-up table scheme also applies to the configuration +descriptor. A USB device may have multiple configuration +descriptors, i.e. CFG01, CFG02, etc. To add a configuration +descriptor, user must implement a structure similar to CFG01. +The next step is to add the configuration descriptor name, i.e. +cfg01, cfg02,.., to the look-up table USB_CD_Ptr. USB_CD_Ptr[0] +is a dummy place holder since configuration 0 is the un-configured +state according to the definition in the USB specification. + +********************************************************************/ + +/********************************************************************* + * Descriptor specific type definitions are defined in: + * usb_device.h + * + * Configuration options are defined in: + * usb_config.h + ********************************************************************/ +#ifndef __USB_DESCRIPTORS_C +#define __USB_DESCRIPTORS_C + +/** INCLUDES *******************************************************/ +#include "usb.h" +#include "usb_device_cdc.h" + +/** CONSTANTS ******************************************************/ +#if defined(__18CXX) +#pragma romdata +#endif + +/* Device Descriptor */ +const USB_DEVICE_DESCRIPTOR device_dsc= +{ + 0x12, // Size of this descriptor in bytes + USB_DESCRIPTOR_DEVICE, // DEVICE descriptor type + 0x0200, // USB Spec Release Number in BCD format + CDC_DEVICE, // Class Code + 0x00, // Subclass code + 0x00, // Protocol code + USB_EP0_BUFF_SIZE, // Max packet size for EP0, see usb_config.h + 0x04D8, // Vendor ID + 0x000A, // Product ID: CDC RS-232 Emulation Demo + 0x0100, // Device release number in BCD format + 0x01, // Manufacturer string index + 0x02, // Product string index + 0x00, // Device serial number string index + 0x01 // Number of possible configurations +}; + +/* Configuration 1 Descriptor */ +const uint8_t configDescriptor1[]={ + /* Configuration Descriptor */ + 0x09,//sizeof(USB_CFG_DSC), // Size of this descriptor in bytes + USB_DESCRIPTOR_CONFIGURATION, // CONFIGURATION descriptor type + 67,0, // Total length of data for this cfg + 2, // Number of interfaces in this cfg + 1, // Index value of this configuration + 0, // Configuration string index + _DEFAULT | _SELF, // Attributes, see usb_device.h + 50, // Max power consumption (2X mA) + + /* Interface Descriptor */ + 9,//sizeof(USB_INTF_DSC), // Size of this descriptor in bytes + USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type + 0, // Interface Number + 0, // Alternate Setting Number + 1, // Number of endpoints in this intf + COMM_INTF, // Class code + ABSTRACT_CONTROL_MODEL, // Subclass code + V25TER, // Protocol code + 0, // Interface string index + + /* CDC Class-Specific Descriptors */ + sizeof(USB_CDC_HEADER_FN_DSC), + CS_INTERFACE, + DSC_FN_HEADER, + 0x10,0x01, + + sizeof(USB_CDC_ACM_FN_DSC), + CS_INTERFACE, + DSC_FN_ACM, + USB_CDC_ACM_FN_DSC_VAL, + + sizeof(USB_CDC_UNION_FN_DSC), + CS_INTERFACE, + DSC_FN_UNION, + CDC_COMM_INTF_ID, + CDC_DATA_INTF_ID, + + sizeof(USB_CDC_CALL_MGT_FN_DSC), + CS_INTERFACE, + DSC_FN_CALL_MGT, + 0x00, + CDC_DATA_INTF_ID, + + /* Endpoint Descriptor */ + //sizeof(USB_EP_DSC),DSC_EP,_EP02_IN,_INT,CDC_INT_EP_SIZE,0x02, + 0x07,/*sizeof(USB_EP_DSC)*/ + USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor + _EP01_IN, //EndpointAddress + _INTERRUPT, //Attributes + 0x0A,0x00, //size + 0x02, //Interval + + /* Interface Descriptor */ + 9,//sizeof(USB_INTF_DSC), // Size of this descriptor in bytes + USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type + 1, // Interface Number + 0, // Alternate Setting Number + 2, // Number of endpoints in this intf + DATA_INTF, // Class code + 0, // Subclass code + NO_PROTOCOL, // Protocol code + 0, // Interface string index + + /* Endpoint Descriptor */ + //sizeof(USB_EP_DSC),DSC_EP,_EP03_OUT,_BULK,CDC_BULK_OUT_EP_SIZE,0x00, + 0x07,/*sizeof(USB_EP_DSC)*/ + USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor + _EP02_OUT, //EndpointAddress + _BULK, //Attributes + 0x40,0x00, //size + 0x00, //Interval + + /* Endpoint Descriptor */ + //sizeof(USB_EP_DSC),DSC_EP,_EP03_IN,_BULK,CDC_BULK_IN_EP_SIZE,0x00 + 0x07,/*sizeof(USB_EP_DSC)*/ + USB_DESCRIPTOR_ENDPOINT, //Endpoint Descriptor + _EP02_IN, //EndpointAddress + _BULK, //Attributes + 0x40,0x00, //size + 0x00, //Interval +}; + + +//Language code string descriptor +const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[1];}sd000={ +sizeof(sd000),USB_DESCRIPTOR_STRING,{0x0409}}; + +//Manufacturer string descriptor +const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[25];}sd001={ +sizeof(sd001),USB_DESCRIPTOR_STRING, +{'M','i','c','r','o','c','h','i','p',' ', +'T','e','c','h','n','o','l','o','g','y',' ','I','n','c','.' +}}; + +//Product string descriptor +const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[25];}sd002={ +sizeof(sd002),USB_DESCRIPTOR_STRING, +{'C','D','C',' ','R','S','-','2','3','2',' ', +'E','m','u','l','a','t','i','o','n',' ','D','e','m','o'} +}; + +//Serial number string descriptor. If a serial number string is implemented, +//it should be unique for every single device coming off the production assembly +//line. Plugging two devices with the same serial number into a computer +//simultaneously will cause problems (in extreme cases BSOD). +//Note: Common OSes put restrictions on the possible values that are allowed. +//For best OS compatibility, the serial number string should only consist +//of UNICODE encoded numbers 0 through 9 and capital letters A through F. +//ROM struct{BYTE bLength;BYTE bDscType;WORD string[10];}sd003={ +//sizeof(sd003),USB_DESCRIPTOR_STRING, +//{'0','1','2','3','4','5','6','7','8','9'}}; + +//Array of configuration descriptors +const uint8_t *const USB_CD_Ptr[]= +{ + (const uint8_t *const)&configDescriptor1 +}; +//Array of string descriptors +const uint8_t *const USB_SD_Ptr[USB_NUM_STRING_DESCRIPTORS]= +{ + (const uint8_t *const)&sd000, + (const uint8_t *const)&sd001, + (const uint8_t *const)&sd002 + //(const uint8_t *const)&sd003 //uncomment if implementing a serial number string descriptor named sd003 +}; + +#if defined(__18CXX) + #pragma code +#endif + +#endif +/** EOF usb_descriptors.c ****************************************************/ -- cgit v1.2.3