Basic Introduction#
The standard instrument equipment interface is used for communication between the host computer and instruments, such as oscilloscopes, power supplies, signal generators, etc. The commonly used standard instrument interfaces and their corresponding communication protocols are as follows.
| Communication Interface | Communication Protocol |
|---|---|
| LAN | VXI-11 |
| USB | USB-TMC |
| GPIB | IEEE488 |
The communication protocol for LAN is essentially the same as TCP Client/Server and RAW Socket of TCP/IP; as long as one of them is supported, it can be recognized normally.
The communication protocol for GPIB is relatively complex, and the physical layer uses parallel transmission, which can almost only communicate using dedicated transceiver chips. The control method for dedicated transceivers is similar to SRAM, and there are no particularly difficult problems to solve.
The communication method for USB must be appreciated.
As a company that provides testing devices and instruments, it is surprising that we have no technical accumulation in this area, so let me take a closer look at what USB-TMC enumeration is.
Overall Idea#
First and foremost, it is very important to review the standard documents. I have two bilingual versions that I translated myself, which need to be viewed in a two-page layout.
USBTMC_1_00_EnCh.pdf | yono's file
USBTMC_usb488_subclass_1_00_EnCh.pdf | yono's file
Secondly, it is very unimportant to find a competitor's standard instrument to capture data packets and see what the situation is.
ps: In fact, I have not even glanced at the second document; I completely relied on capturing data and cross-referencing with the first document to complete the driver development.
It is worth noting that the USB-TMC class enumeration actually has only one subclass, USB488, and there are still many reserved data locations and communication processes, so I believe that this TMC enumeration can still be used for many years.
Enumeration Process#
As we all know, during the enumeration phase of USB devices, the driver needs to query descriptors, and how this descriptor is written is key to enumerating as a TMC device.
After capturing packets, an example device descriptor has emerged, and it should be exactly the same as follows.
UCHAR device_framework_full_speed_demo[] = {
/* Device descriptor */
0x12, // len(static)
0x01, // device(static)
0x00, 0x02, // USB2.0(static)
0x00, // DeviceClass(static)
0x00, // DeviceSubClass(static)
0x00, // bDeviceProtocol(static)
0x40, // bMaxPacketSize0
0x69, 0x0A, // idVendor (VID): 0x0A69
0x8A, 0x08, // idProduct (PID): 0x088A
0x00, 0x01, // bcdDevice: Device release number 0x0100
0x01, // iManufacturer (static)
0x02, // iProduct (static)
0x03, // iSerialNumber (static)
0x01, // bNumConfigurations(static)
/* Device qualifier descriptor */
0x0a, // len(static)
0x06, // bDescriptorType: Device Qualifier Descriptor(static)
0x00, 0x02, // USB2.0(static)
0x00, // DeviceClass(static)
0x00, // DeviceSubClass(static)
0x00, // bDeviceProtocol(static)
0x40, // bMaxPacketSize0
0x01, // bNumConfigurations(static)
0x00, // reserve(static)
/* Configuration descriptor */
0x09, // len(static)
0x02, // bDescriptorType: Configuration Descriptor(static)
0x20, 0x00, // wTotalLength: Total length of data for this configuration (32 bytes)
0x01, // bNumInterfaces(static)
0x01, // bConfigurationValue(static)
0x00, // iConfiguration: Index of configuration string descriptor
0x80, // bmAttributes: Self-powered
0x64, // bMaxPower: 200 mA (0x64 * 2 mA)
/* Interface descriptor */
0x09, // len(static)
0x04, // bDescriptorType: Interface Descriptor(static)
0x00, // bInterfaceNumber: Interface 0
0x00, // bAlternateSetting
0x02, // bNumEndpoints: 2 endpoints(static)
0xFE, // bInterfaceClass: TMC(static)
0x03, // bInterfaceSubClass: USB488(static)
0x01, // bInterfaceProtocol(static)
0x00, // iInterface: Index of interface string descriptor(static)
/* Endpoint descriptor (Bulk Out) */
0x07, // len(static)
0x05, // bDescriptorType: Endpoint Descriptor(static)
0x81, // bEndpointAddress: Endpoint address (IN direction, endpoint number 1)
0x02, // bmAttributes: Transfer type is Bulk
0x40, 0x00, // wMaxPacketSize: Maximum packet size 64 bytes
0x00, // bInterval: Polling interval (0 for bulk transfer)
/* Endpoint descriptor (Bulk In) */
0x07, // len(static)
0x05, // bDescriptorType: Endpoint Descriptor(static)
0x01, // bEndpointAddress: Endpoint address (OUT direction, endpoint number 1)
0x02, // bmAttributes: Transfer type is Bulk
0x40, 0x00, // wMaxPacketSize: Maximum packet size 64 bytes
0x00, // bInterval: Polling interval (0 for bulk transfer)
};
The most critical parts are bInterfaceClass and bInterfaceSubClass in the Interface descriptor, which directly determine our enumeration type. Of course, all other parts marked with (static) in the descriptor must be exactly the same as the example, as per standard regulations. Some are TMC standards, and some are USB standards; in any case, the parts marked with (static) must be identical.
Notably, the USB-TMC protocol does not distinguish between high-speed and full-speed; regardless of what USB line it operates on, a device qualifier is required, which is different from other modern USB protocol stacks.
Another special point is that USB-TMC devices cannot use composite enumeration, as it will disrupt NI-VISA's recognition and resource invocation for USB-TMC. For example, I tried to composite enumerate as TMC + serial device, and it showed up in the device manager (enumeration successful), but when using VISA calls, only the serial port could be invoked, and the TMC device could not be called.
Sending Commands to the Instrument#
In communication, messages are sent to the instrument through the Bulk Out endpoint described earlier. Therefore, the device should repeatedly open this Bulk Out endpoint to receive any possible messages. If the device does not open the Bulk Out endpoint, it will generate a large number of NAK packets, triggering a setup command to restart the endpoint.
For example, a classic message is as follows:
0x01, 0x02, 0xFD, 0x00, 0x06, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x2A, 0x49, 0x44, 0x4E, 0x3F, 0x0A, 0x00, 0x00
This message can be parsed according to the description in the USBTMC_1_00 standard document, divided into the following segments.
| Message Segment | Meaning |
|---|---|
| 0x01 | Indicates that this message is an OUT request, meaning the instrument needs to parse the content of this message to take action. |
| 0x02, 0xFD | Message tag and its complement; this tag will be different for each message. |
| 0x00 | Fixed 0. |
| 0x06, 0x00, 0x00, 0x00 | Indicates that the content length is 6, transmitted in little-endian 32-bit. |
| 0x01, 0x00, 0x00, 0x00 | Only the first bit of the first byte is meaningful; 1 indicates that the content statement has been fully transmitted, while 0 indicates that there is more content to follow. |
| 0x2A, 0x49, 0x44, 0x4E, 0x3F, 0x0A | The formal content of 6 bytes, which is *IDN?\r, where \r is the escape character for carriage return. |
| 0x00, 0x00 | Padding zeros to ensure the total message length is 4-byte aligned. |
In simple terms, it means parsing the first byte of the message data received from the Bulk Out endpoint; if it is 0x01, then proceed with further parsing to extract the formal SCPI command "*IDN?" and process it.
Receiving Replies from the Instrument#
In communication, the instrument cannot arbitrarily send replies to the host via USB, which is different from serial communication. When the host expects to receive reply data, it will send a message on the Bulk Out endpoint indicating that the instrument can now send a reply. A classic message to enable replies is as follows:
0x02, 0x03, 0xFC, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
This message can be parsed according to the description in the USBTMC_1_00 standard document, divided into the following segments.
| Message Segment | Meaning |
|---|---|
| 0x02 | Indicates that this message is an IN request, meaning the instrument should send any possible replies. |
| 0x03, 0xFC | Message tag and its complement; this tag will be different for each message. |
| 0x00 | Fixed 0. |
| 0x00, 0x04, 0x00, 0x00 | Indicates that the host has opened a 0x0400 buffer for receiving 1024 bytes; this value does not need to be considered; the host has abundant resources, and if communication fails, it can just increase the size. |
| 0x00 | The D1 bit, which is the &0x2 bit, is meaningful; if it is 1, it means that the next byte is a terminator that the host supports and the device must support; if it is 0, it can be ignored. Other bits are reserved. |
| 0x00 | If the previous byte's D1 bit is 1, then this byte indicates the supported terminator, such as \r. |
| 0x00, 0x00 | Padding reserved characters, which also ensures that the total message length is 4-byte aligned. |
In simple terms, it means parsing the first byte of the message data received from the Bulk Out endpoint; if it is 0x02, then open the device's sending channel. For example, if the host previously transmitted the formal SCPI command "*IDN?", then the device needs to transmit the reply generated.
As for the specified terminator function, it will not be supported; in the subsequent necessary setup packet introduction, it will be explained how to let the host know that we do not support this specification.
A classic reply transmission message is as follows:
0x02, 0x03, 0xFC, 0x00, 0x06, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x2A, 0x49, 0x44, 0x4E, 0x3F, 0x0A, 0x00, 0x00,
| Message Segment | Meaning |
|---|---|
| 0x02 | Indicates that this message is a reply to an IN request. |
| 0x03, 0xFC | Message tag and its complement; this tag should replicate the request message. |
| 0x00 | Fixed 0. |
| 0x06, 0x00, 0x00, 0x00 | Indicates that the valid reply data is a total of 6 bytes, transmitted in little-endian 32-bit. |
| 0x01, 0x00, 0x00, 0x00 | Only the first bit of the first byte is meaningful; 1 indicates that the content statement has been fully transmitted, while 0 indicates that there is more content to follow. |
| 0x2A, 0x49, 0x44, 0x4E, 0x3F, 0x0A | *IDN?\r, this is a loopback test; my instrument will copy the last received command to respond to any reply. |
| 0x00, 0x00 | Padding zeros to ensure the total message length is 4-byte aligned. |
An Excellent Method for 4-Byte Alignment#
Using bitwise operations is a very convenient and efficient way to achieve 4-byte alignment.
uint8_t *data; // Original message buffer
uint32_t len = OriginalLen; // Original length
for(uint32_t i = len; i < ((len + 0x3) & ~0x3U); i++)
{
data[i] = 0x00;
}
_write(data, ((len + 0x3) & ~0x3U));
Handling Setup Packets#
The standard setup packets starting with 0x80,0x06 have the following categories; I am also unable to assist much, as I completely rely on the usbx protocol stack for automatic processing.
#define UX_GET_STATUS 0u
#define UX_CLEAR_FEATURE 1u
#define UX_SET_FEATURE 3u
#define UX_SET_ADDRESS 5u
#define UX_GET_DESCRIPTOR 6u
#define UX_SET_DESCRIPTOR 7u
#define UX_GET_CONFIGURATION 8u
#define UX_SET_CONFIGURATION 9u
#define UX_GET_INTERFACE 10u
#define UX_SET_INTERFACE 11u
#define UX_SYNCH_FRAME 12u
The COMMAND_REQUEST packets starting with 0xA1 or 0xA2 have the following content that we must handle.
Starting with 0xA1,0x07, it indicates querying the device's features. An example reply packet is as follows. The content is quite extensive; you can refer to the document yourself, but it is recommended to directly respond with this.
0x01, 0x00, 0x10, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
Starting with 0xA2,0x01, it indicates clearing the bulk-out transfer; we don't need to worry about anything, just reply successfully, and the reply packet is as follows.
0x01, tag (copy the second byte of the setup packet starting from 0).
Starting with 0xA2,0x02, it indicates inquiring about the status of the previously cleared bulk-out transfer request; we don't need to worry about anything, just reply successfully, and the reply packet is as follows.
0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00.
As for other COMMAND_REQUEST packets, they are not commonly used and can be ignored.
[!NOTE]
First, you should be somewhat familiar with the practice of usbx, at least having used existing examples like CDC_ACM; otherwise, the following content will be meaningless. The following is an example of how to add TMC enumeration into the usbx USB protocol stack framework.
Practice of Enumeration Descriptors in usbx#
Pay attention to the _ux_device_stack_initialize function, where there is such a part, which means that it will only register based on the position of the Interface descriptor and Configuration descriptor in the overall descriptor. Everything before the Configuration descriptor is treated as the ==device descriptor==, and everything after the Interface descriptor is treated as the ==endpoint descriptor==.
switch(descriptor_type)
{
case UX_INTERFACE_DESCRIPTOR_ITEM:
......
break;
case UX_CONFIGURATION_DESCRIPTOR_ITEM:
......
break;
default:
break;
}
Then, it is necessary to slightly modify the content of the original ux_device_descriptors.c file in the USBD_Device_Framework_Builder function, which originally should have content similar to the following. It specifies that only high-speed USB requires a device qualifier; however, our USB-TMC usually operates on full-speed USB, and since the USB-TMC protocol does not distinguish between high-speed and full-speed, we need to remove this if condition so that regardless of high-speed or full-speed, this device qualifier is included in the descriptor.
/* Check if USBx is in high speed mode to add qualifier descriptor */
if(Speed == USBD_HIGH_SPEED)
{
pDevQualDesc = (USBD_DevQualiDescTypedef *)(pDevFrameWorkDesc + pdev->CurrDevDescSz);
pDevQualDesc->bLength = (uint8_t)sizeof(USBD_DevQualiDescTypedef);
pDevQualDesc->bDescriptorType = UX_DEVICE_QUALIFIER_DESCRIPTOR_ITEM;
pDevQualDesc->bcdDevice = 0x0200;
pDevQualDesc->Class = 0x00;
pDevQualDesc->SubClass = 0x00;
pDevQualDesc->Protocol = 0x00;
pDevQualDesc->bMaxPacketSize = 0x40;
pDevQualDesc->bNumConfigurations = 0x01;
pDevQualDesc->bReserved = 0x00;
pdev->CurrDevDescSz += (uint32_t)sizeof(USBD_DevQualiDescTypedef);
}
Other parts do not require major adjustments; just modify the parameters segment by segment according to the example descriptor. The modified ux_device_descriptors.c and ux_device_descriptors.h files based on the original file are as follows.
/* USER CODE BEGIN Header */
/**
******************************************************************************
* @file ux_device_descriptors.c
* @author MCD Application Team
* @brief USBX Device descriptor header file
******************************************************************************
* @attention
*
* Copyright (c) 2020-2021 STMicroelectronics.
* All rights reserved.
*
* This software is licensed under terms that can be found in the LICENSE file
* in the root directory of this software component.
* If no LICENSE file comes with this software, it is provided AS-IS.
*
******************************************************************************
*/
/* USER CODE END Header */
/* Includes ------------------------------------------------------------------*/
#include "ux_device_descriptors.h"
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
/* USER CODE END Includes */
/* Private typedef -----------------------------------------------------------*/
/* USER CODE BEGIN PTD */
/* USER CODE END PTD */
/* Private define ------------------------------------------------------------*/
/* USER CODE BEGIN PD */
/* USER CODE END PD */
/* Private macro -------------------------------------------------------------*/
/* USER CODE BEGIN PM */
/* USER CODE END PM */
/* Private variables ---------------------------------------------------------*/
USBD_DevClassHandleTypeDef USBD_Device_FS, USBD_Device_HS;
uint8_t UserClassInstance[USBD_MAX_CLASS_INTERFACES] = {
CLASS_TYPE_TMC,
};
uint8_t UserTMCInterface[] = {
INTERFACE_TMC_USB488,
};
/* The generic device descriptor buffer that will be filled by builder
Size of the buffer is the maximum possible device FS descriptor size. */
#if defined(__ICCARM__) /* IAR Compiler */
#pragma data_alignment = 4
#endif /* defined ( __ICCARM__ ) */
__ALIGN_BEGIN static uint8_t DevFrameWorkDesc_FS[USBD_FRAMEWORK_MAX_DESC_SZ] __ALIGN_END = {0};
/* The generic device descriptor buffer that will be filled by builder
Size of the buffer is the maximum possible device HS descriptor size. */
#if defined(__ICCARM__) /* IAR Compiler */
#pragma data_alignment = 4
#endif /* defined ( __ICCARM__ ) */
__ALIGN_BEGIN static uint8_t DevFrameWorkDesc_HS[USBD_FRAMEWORK_MAX_DESC_SZ] __ALIGN_END = {0};
static uint8_t *pDevFrameWorkDesc_FS = DevFrameWorkDesc_FS;
static uint8_t *pDevFrameWorkDesc_HS = DevFrameWorkDesc_HS;
/* USER CODE BEGIN PV0 */
/* USER CODE END PV0 */
/* String Device Framework :
Byte 0 and 1 : Word containing the language ID : 0x0904 for US
Byte 2 : Byte containing the index of the descriptor
Byte 3 : Byte containing the length of the descriptor string
*/
#if defined(__ICCARM__) /* IAR Compiler */
#pragma data_alignment = 4
#endif /* defined ( __ICCARM__ ) */
__ALIGN_BEGIN UCHAR USBD_string_framework[USBD_STRING_FRAMEWORK_MAX_LENGTH] __ALIGN_END = {0};
/* Multiple languages are supported on the device, to add
a language besides English, the Unicode language code must
be appended to the language_id_framework array and the length
adjusted accordingly. */
#if defined(__ICCARM__) /* IAR Compiler */
#pragma data_alignment = 4
#endif /* defined ( __ICCARM__ ) */
__ALIGN_BEGIN UCHAR USBD_language_id_framework[LANGUAGE_ID_MAX_LENGTH] __ALIGN_END = {0};
/* USER CODE BEGIN PV1 */
/* USER CODE END PV1 */
/* Private function prototypes -----------------------------------------------*/
static void USBD_Desc_GetString(uint8_t *desc, uint8_t *Buffer, uint16_t *len);
static uint8_t USBD_Desc_GetLen(uint8_t *buf);
static uint8_t *USBD_Device_Framework_Builder(USBD_DevClassHandleTypeDef *pdev, uint8_t *pDevFrameWorkDesc, uint8_t *UserClassInstance, uint8_t Speed);
static uint8_t USBD_FrameWork_AddToConfDesc(USBD_DevClassHandleTypeDef *pdev, uint8_t Speed, uint8_t *pCmpstConfDesc);
static uint8_t USBD_FrameWork_AddClass(USBD_DevClassHandleTypeDef *pdev, USBD_CompositeClassTypeDef class, uint8_t cfgidx, uint8_t Speed, uint8_t *pCmpstConfDesc);
static uint8_t USBD_FrameWork_FindFreeIFNbr(USBD_DevClassHandleTypeDef *pdev);
static void USBD_FrameWork_AddConfDesc(uint32_t Conf, uint32_t *pSze);
static void USBD_FrameWork_AssignEp(USBD_DevClassHandleTypeDef *pdev, uint8_t Add, uint8_t Type, uint32_t Sze);
static void USBD_FrameWork_TMC_Desc(USBD_DevClassHandleTypeDef *pdev, uint32_t pConf, uint32_t *Sze);
/* USER CODE BEGIN PFP */
/* USER CODE END PFP */
/* Private user code ---------------------------------------------------------*/
/* USER CODE BEGIN 0 */
/* USER CODE END 0 */
/**
* @brief USBD_Get_Device_Framework_Speed
* Return the device speed descriptor
* @param Speed : HIGH or FULL SPEED flag
* @param length : length of HIGH or FULL SPEED array
* @retval Pointer to descriptor buffer
*/
uint8_t *USBD_Get_Device_Framework_Speed(uint8_t Speed, ULONG *Length)
{
uint8_t *pFrameWork = NULL;
/* USER CODE BEGIN Device_Framework0 */
/* USER CODE END Device_Framework0 */
if(USBD_FULL_SPEED == Speed)
{
USBD_Device_Framework_Builder(&USBD_Device_FS, pDevFrameWorkDesc_FS, UserClassInstance, Speed);
/* Get the length of USBD_device_framework_full_speed */
*Length = (ULONG)(USBD_Device_FS.CurrDevDescSz + USBD_Device_FS.CurrConfDescSz);
pFrameWork = pDevFrameWorkDesc_FS;
}
else
{
USBD_Device_Framework_Builder(&USBD_Device_HS, pDevFrameWorkDesc_HS, UserClassInstance, Speed);
/* Get the length of USBD_device_framework_high_speed */
*Length = (ULONG)(USBD_Device_HS.CurrDevDescSz + USBD_Device_HS.CurrConfDescSz);
pFrameWork = pDevFrameWorkDesc_HS;
}
/* USER CODE BEGIN Device_Framework1 */
/* USER CODE END Device_Framework1 */
return pFrameWork;
}
/**
* @brief USBD_Get_String_Framework
* Return the language_id_framework
* @param Length : Length of String_Framework
* @retval Pointer to language_id_framework buffer
*/
uint8_t *USBD_Get_String_Framework(ULONG *Length)
{
uint16_t len = 0U;
uint8_t count = 0U;
/* USER CODE BEGIN String_Framework0 */
/* USER CODE END String_Framework0 */
/* Set the Manufacturer language Id and index in USBD_string_framework */
USBD_string_framework[count++] = USBD_LANGID_STRING & 0xFF;
USBD_string_framework[count++] = USBD_LANGID_STRING >> 8;
USBD_string_framework[count++] = USBD_IDX_MFC_STR;
/* Set the Manufacturer string in string_framework */
USBD_Desc_GetString((uint8_t *)USBD_MANUFACTURER_STRING, USBD_string_framework + count, &len);
/* Set the Product language Id and index in USBD_string_framework */
count += len + 1;
USBD_string_framework[count++] = USBD_LANGID_STRING & 0xFF;
USBD_string_framework[count++] = USBD_LANGID_STRING >> 8;
USBD_string_framework[count++] = USBD_IDX_PRODUCT_STR;
/* Set the Product string in USBD_string_framework */
USBD_Desc_GetString((uint8_t *)USBD_PRODUCT_STRING, USBD_string_framework + count, &len);
/* Set Serial language Id and index in string_framework */
count += len + 1;
USBD_string_framework[count++] = USBD_LANGID_STRING & 0xFF;
USBD_string_framework[count++] = USBD_LANGID_STRING >> 8;
USBD_string_framework[count++] = USBD_IDX_SERIAL_STR;
/* Set the Serial number in USBD_string_framework */
USBD_Desc_GetString((uint8_t *)USBD_SERIAL_NUMBER, USBD_string_framework + count, &len);
/* USER CODE BEGIN String_Framework1 */
/* USER CODE END String_Framework1 */
/* Get the length of USBD_string_framework */
*Length = strlen((const char *)USBD_string_framework);
return USBD_string_framework;
}
/**
* @brief USBD_Get_Language_Id_Framework
* Return the language_id_framework
* @param Length : Length of Language_Id_Framework
* @retval Pointer to language_id_framework buffer
*/
uint8_t *USBD_Get_Language_Id_Framework(ULONG *Length)
{
uint8_t count = 0U;
/* Set the language Id in USBD_language_id_framework */
USBD_language_id_framework[count++] = USBD_LANGID_STRING & 0xFF;
USBD_language_id_framework[count++] = USBD_LANGID_STRING >> 8;
/* Get the length of USBD_language_id_framework */
*Length = strlen((const char *)USBD_language_id_framework);
return USBD_language_id_framework;
}
/**
* @brief USBD_Get_Interface_Number
* Return interface number
* @param class_type : Device class type
* @param interface_type : Device interface type
* @retval interface number
*/
uint16_t USBD_Get_Interface_Number(uint8_t class_type, uint8_t interface_type)
{
uint8_t itf_num = 0U;
uint8_t idx = 0U;
/* USER CODE BEGIN USBD_Get_Interface_Number0 */
/* USER CODE END USBD_Get_Interface_Number0 */
for(idx = 0; idx < USBD_MAX_SUPPORTED_CLASS; idx++)
{
if((USBD_Device_FS.tclasslist[idx].ClassType == class_type) && (USBD_Device_FS.tclasslist[idx].InterfaceType == interface_type))
{
itf_num = USBD_Device_FS.tclasslist[idx].Ifs[0];
}
}
/* USER CODE BEGIN USBD_Get_Interface_Number1 */
/* USER CODE END USBD_Get_Interface_Number1 */
return itf_num;
}
/**
* @brief USBD_Get_Configuration_Number
* Return configuration number
* @param class_type : Device class type
* @param interface_type : Device interface type
* @retval configuration number
*/
uint16_t USBD_Get_Configuration_Number(uint8_t class_type, uint8_t interface_type)
{
uint8_t cfg_num = 1U;
/* USER CODE BEGIN USBD_Get_CONFIGURATION_Number0 */
/* USER CODE END USBD_Get_CONFIGURATION_Number0 */
/* USER CODE BEGIN USBD_Get_CONFIGURATION_Number1 */
/* USER CODE END USBD_Get_CONFIGURATION_Number1 */
return cfg_num;
}
/**
* @brief USBD_Desc_GetString
* Convert ASCII string into Unicode one
* @param desc : descriptor buffer
* @param Unicode : Formatted string buffer (Unicode)
* @param len : descriptor length
* @retval None
*/
static void USBD_Desc_GetString(uint8_t *desc, uint8_t *unicode, uint16_t *len)
{
uint8_t idx = 0U;
uint8_t *pdesc;
if(desc == NULL)
{
return;
}
pdesc = desc;
*len = (uint16_t)USBD_Desc_GetLen(pdesc);
unicode[idx++] = *(uint8_t *)len;
while(*pdesc != (uint8_t)'\0')
{
unicode[idx++] = *pdesc;
pdesc++;
}
}
/**
* @brief USBD_Desc_GetLen
* return the string length
* @param buf : pointer to the ASCII string buffer
* @retval string length
*/
static uint8_t USBD_Desc_GetLen(uint8_t *buf)
{
uint8_t len = 0U;
uint8_t *pbuff = buf;
while(*pbuff != (uint8_t)'\0')
{
len++;
pbuff++;
}
return len;
}
/**
* @brief USBD_Device_Framework_Builder
* Device Framework builder
* @param pdev: device instance
* @param pDevFrameWorkDesc: Pointer to the device framework descriptor
* @param UserClassInstance: type of the class to be added
* @param Speed: Speed parameter HS or FS
* @retval status
*/
static uint8_t *USBD_Device_Framework_Builder(USBD_DevClassHandleTypeDef *pdev, uint8_t *pDevFrameWorkDesc, uint8_t *UserClassInstance, uint8_t Speed)
{
static USBD_DeviceDescTypedef *pDevDesc;
static USBD_DevQualiDescTypedef *pDevQualDesc;
uint8_t Idx_Instance = 0U;
/* Set Dev and conf descriptors size to 0 */
pdev->CurrConfDescSz = 0U;
pdev->CurrDevDescSz = 0U;
/* Set the pointer to the device descriptor area*/
pDevDesc = (USBD_DeviceDescTypedef *)pDevFrameWorkDesc;
/* Start building the generic device descriptor common part */
pDevDesc->bLength = (uint8_t)sizeof(USBD_DeviceDescTypedef);
pDevDesc->bDescriptorType = UX_DEVICE_DESCRIPTOR_ITEM;
pDevDesc->bcdUSB = USB_BCDUSB;
pDevDesc->bDeviceClass = 0x00;
pDevDesc->bDeviceSubClass = 0x00;
pDevDesc->bDeviceProtocol = 0x00;
pDevDesc->bMaxPacketSize = USBD_MAX_EP0_SIZE;
pDevDesc->idVendor = USBD_VID;
pDevDesc->idProduct = USBD_PID;
pDevDesc->bcdDevice = 0x0100;
pDevDesc->iManufacturer = USBD_IDX_MFC_STR;
pDevDesc->iProduct = USBD_IDX_PRODUCT_STR;
pDevDesc->iSerialNumber = USBD_IDX_SERIAL_STR;
pDevDesc->bNumConfigurations = USBD_MAX_NUM_CONFIGURATION;
pdev->CurrDevDescSz += (uint32_t)sizeof(USBD_DeviceDescTypedef);
/* Check if USBx is in high speed mode to add qualifier descriptor */
pDevQualDesc = (USBD_DevQualiDescTypedef *)(pDevFrameWorkDesc + pdev->CurrDevDescSz);
pDevQualDesc->bLength = (uint8_t)sizeof(USBD_DevQualiDescTypedef);
pDevQualDesc->bDescriptorType = UX_DEVICE_QUALIFIER_DESCRIPTOR_ITEM;
pDevQualDesc->bcdDevice = 0x0200;
pDevQualDesc->Class = 0x00;
pDevQualDesc->SubClass = 0x00;
pDevQualDesc->Protocol = 0x00;
pDevQualDesc->bMaxPacketSize = 0x40;
pDevQualDesc->bNumConfigurations = 0x01;
pDevQualDesc->bReserved = 0x00;
pdev->CurrDevDescSz += (uint32_t)sizeof(USBD_DevQualiDescTypedef);
/* Build the device framework */
while(Idx_Instance < USBD_MAX_SUPPORTED_CLASS)
{
if((pdev->classId < USBD_MAX_SUPPORTED_CLASS) && (pdev->NumClasses < USBD_MAX_SUPPORTED_CLASS) && (UserClassInstance[Idx_Instance] != CLASS_TYPE_NONE))
{
/* Call the composite class builder */
(void)USBD_FrameWork_AddClass(pdev, (USBD_CompositeClassTypeDef)UserClassInstance[Idx_Instance], 0, Speed, (pDevFrameWorkDesc + pdev->CurrDevDescSz));
/* Increment the ClassId for the next occurrence */
pdev->classId++;
pdev->NumClasses++;
}
Idx_Instance++;
}
/* Check if there is a composite class and update device class */
if(pdev->NumClasses > 1)
{
pDevDesc->bDeviceClass = 0xEF;
pDevDesc->bDeviceSubClass = 0x02;
pDevDesc->bDeviceProtocol = 0x01;
}
else
{
/* Check if the CDC ACM class is set and update device class */
if(UserClassInstance[0] == CLASS_TYPE_CDC_ACM)
{
pDevDesc->bDeviceClass = 0x02;
pDevDesc->bDeviceSubClass = 0x02;
pDevDesc->bDeviceProtocol = 0x00;
}
}
return pDevFrameWorkDesc;
}
/**
* @brief USBD_FrameWork_AddToConfDesc
* Add a new class to the configuration descriptor
* @param pdev: device instance
* @param Speed: device speed
* @param pCmpstConfDesc: to composite device configuration descriptor
* @retval status
*/
uint8_t USBD_FrameWork_AddToConfDesc(USBD_DevClassHandleTypeDef *pdev, uint8_t Speed, uint8_t *pCmpstConfDesc)
{
uint8_t interface = 0U;
pdev->Speed = Speed;
if(pdev->classId == 0U)
{
/* Add configuration and IAD descriptors */
USBD_FrameWork_AddConfDesc((uint32_t)pCmpstConfDesc, &pdev->CurrConfDescSz);
}
switch(pdev->tclasslist[pdev->classId].ClassType)
{
case CLASS_TYPE_TMC:
switch(pdev->tclasslist[pdev->classId].InterfaceType)
{
case INTERFACE_TMC_USB488:
/* Find the first available interface slot and Assign number of interfaces */
interface = USBD_FrameWork_FindFreeIFNbr(pdev);
pdev->tclasslist[pdev->classId].NumIf = 1U;
pdev->tclasslist[pdev->classId].Ifs[0] = interface;
/* Assign endpoint numbers */
pdev->tclasslist[pdev->classId].NumEps = 2U; /* EP_IN, EP_OUT */
/* Check the current speed to assign endpoints */
if(pdev->Speed == USBD_HIGH_SPEED)
{
/* Assign IN Endpoint */
USBD_FrameWork_AssignEp(pdev, USBD_TMC_NONE_EPIN_ADDR, USBD_EP_TYPE_BULK, USBD_TMC_NONE_EPIN_HS_MPS);
/* Assign OUT Endpoint */
USBD_FrameWork_AssignEp(pdev, USBD_TMC_NONE_EPOUT_ADDR, USBD_EP_TYPE_BULK, USBD_TMC_NONE_EPOUT_HS_MPS);
}
else
{
USBD_FrameWork_AssignEp(pdev, USBD_TMC_NONE_EPIN_ADDR, USBD_EP_TYPE_BULK, USBD_TMC_NONE_EPIN_FS_MPS);
USBD_FrameWork_AssignEp(pdev, USBD_TMC_NONE_EPOUT_ADDR, USBD_EP_TYPE_BULK, USBD_TMC_NONE_EPOUT_FS_MPS);
}
USBD_FrameWork_TMC_Desc(pdev, (uint32_t)pCmpstConfDesc, &pdev->CurrConfDescSz);
break;
default:
break;
}
break;
default:
break;
}
return UX_SUCCESS;
}
/**
* @brief USBD_FrameWork_AddClass
* Register a class in the class builder
* @param pdev: device instance
* @param class: type of the class to be added (from USBD_CompositeClassTypeDef)
* @param cfgidx: configuration index
* @param speed: device speed
* @param pCmpstConfDesc: to composite device configuration descriptor
* @retval status
*/
uint8_t USBD_FrameWork_AddClass(USBD_DevClassHandleTypeDef *pdev, USBD_CompositeClassTypeDef class, uint8_t cfgidx, uint8_t Speed, uint8_t *pCmpstConfDesc)
{
static uint8_t interface_idx = 0U;
if((pdev->classId < USBD_MAX_SUPPORTED_CLASS) && (pdev->tclasslist[pdev->classId].Active == 0U))
{
/* Store the class parameters in the global tab */
pdev->tclasslist[pdev->classId].ClassId = pdev->classId;
pdev->tclasslist[pdev->classId].Active = 1U;
pdev->tclasslist[pdev->classId].ClassType = class;
if(class == CLASS_TYPE_TMC)
{
pdev->tclasslist[pdev->classId].InterfaceType = UserTMCInterface[interface_idx];
interface_idx++;
if(interface_idx == sizeof(UserTMCInterface))
{
interface_idx = 0U;
}
}
/* Call configuration descriptor builder and endpoint configuration builder */
if(USBD_FrameWork_AddToConfDesc(pdev, Speed, pCmpstConfDesc) != UX_SUCCESS)
{
return UX_ERROR;
}
}
UNUSED(cfgidx);
return UX_SUCCESS;
}
/**
* @brief USBD_FrameWork_FindFreeIFNbr
* Find the first interface available slot
* @param pdev: device instance
* @retval The interface number to be used
*/
static uint8_t USBD_FrameWork_FindFreeIFNbr(USBD_DevClassHandleTypeDef *pdev)
{
uint32_t idx = 0U;
/* Unroll all already activated classes */
for(uint32_t i = 0U; i < pdev->NumClasses; i++)
{
/* Unroll each class interfaces */
for(uint32_t j = 0U; j < pdev->tclasslist[i].NumIf; j++)
{
/* Increment the interface counter index */
idx++;
}
}
/* Return the first available interface slot */
return (uint8_t)idx;
}
/**
* @brief USBD_FrameWork_AddConfDesc
* Add a new class to the configuration descriptor
* @param Conf: configuration descriptor
* @param pSze: pointer to the configuration descriptor size
* @retval none
*/
static void USBD_FrameWork_AddConfDesc(uint32_t Conf, uint32_t *pSze)
{
/* Intermediate variable to comply with MISRA-C Rule 11.3 */
USBD_ConfigDescTypedef *ptr = (USBD_ConfigDescTypedef *)Conf;
ptr->bLength = (uint8_t)sizeof(USBD_ConfigDescTypedef);
ptr->bDescriptorType = UX_CONFIGURATION_DESCRIPTOR_ITEM;
ptr->wDescriptorLength = 0x20;
ptr->bNumInterfaces = 1U;
ptr->bConfigurationValue = 1U;
ptr->iConfiguration = USBD_CONFIG_STR_DESC_IDX;
ptr->bmAttributes = USBD_CONFIG_BMATTRIBUTES;
ptr->bMaxPower = USBD_CONFIG_MAXPOWER;
*pSze += sizeof(USBD_ConfigDescTypedef);
}
/**
* @brief USBD_FrameWork_AssignEp
* Assign and endpoint
* @param pdev: device instance
* @param Add: Endpoint address
* @param Type: Endpoint type
* @param Sze: Endpoint max packet size
* @retval none
*/
static void USBD_FrameWork_AssignEp(USBD_DevClassHandleTypeDef *pdev, uint8_t Add, uint8_t Type, uint32_t Sze)
{
uint32_t idx = 0U;
/* Find the first available endpoint slot */
while(((idx < (pdev->tclasslist[pdev->classId]).NumEps) && ((pdev->tclasslist[pdev->classId].Eps[idx].is_used) != 0U)))
{
/* Increment the index */
idx++;
}
/* Configure the endpoint */
pdev->tclasslist[pdev->classId].Eps[idx].add = Add;
pdev->tclasslist[pdev->classId].Eps[idx].type = Type;
pdev->tclasslist[pdev->classId].Eps[idx].size = (uint16_t)Sze;
pdev->tclasslist[pdev->classId].Eps[idx].is_used = 1U;
}
/**
* @brief USBD_FrameWork_TMC_Desc
* Configure and Append the TMC Descriptor
* @param pdev: device instance
* @param pConf: Configuration descriptor pointer
* @param Sze: pointer to the current configuration descriptor size
* @retval None
*/
static void USBD_FrameWork_TMC_Desc(USBD_DevClassHandleTypeDef *pdev, uint32_t pConf, uint32_t *Sze)
{
static USBD_IfDescTypedef *pIfDesc;
static USBD_EpDescTypedef *pEpDesc;
switch(pdev->tclasslist[pdev->classId].InterfaceType)
{
case INTERFACE_TMC_USB488:
/* Append Interface descriptor to Configuration descriptor */
__USBD_FRAMEWORK_SET_IF(pdev->tclasslist[pdev->classId].Ifs[0], 0U, (uint8_t)(pdev->tclasslist[pdev->classId].NumEps), UX_DEVICE_CLASS_TMC_CLASS, UX_DEVICE_SUB_CLASS_USB488_CLASS, INTERFACE_TMC_USB488, 0U);
if(pdev->Speed == USBD_HIGH_SPEED)
{
/* Append Endpoint descriptor to Configuration descriptor */
__USBD_FRAMEWORK_SET_EP(pdev->tclasslist[pdev->classId].Eps[0].add, USBD_EP_TYPE_BULK, (uint16_t)pdev->tclasslist[pdev->classId].Eps[0].size, USBD_TMC_NONE_EPIN_FS_BINTERVAL, USBD_TMC_NONE_EPIN_HS_BINTERVAL);
__USBD_FRAMEWORK_SET_EP(pdev->tclasslist[pdev->classId].Eps[1].add, USBD_EP_TYPE_BULK, (uint16_t)pdev->tclasslist[pdev->classId].Eps[1].size, USBD_TMC_NONE_EPOUT_HS_BINTERVAL, USBD_TMC_NONE_EPOUT_FS_BINTERVAL);
}
else
{
/* Append Endpoint descriptor to Configuration descriptor */
__USBD_FRAMEWORK_SET_EP(pdev->tclasslist[pdev->classId].Eps[0].add, USBD_EP_TYPE_BULK, (uint16_t)pdev->tclasslist[pdev->classId].Eps[0].size, USBD_TMC_NONE_EPIN_FS_BINTERVAL, USBD_TMC_NONE_EPIN_HS_BINTERVAL);
__USBD_FRAMEWORK_SET_EP(pdev->tclasslist[pdev->classId].Eps[1].add, USBD_EP_TYPE_BULK, (uint16_t)pdev->tclasslist[pdev->classId].Eps[1].size, USBD_TMC_NONE_EPOUT_HS_BINTERVAL, USBD_TMC_NONE_EPOUT_FS_BINTERVAL);
}
break;
default:
break;
}
}
/* USER CODE BEGIN Header */
/**
******************************************************************************
* @file ux_device_descriptors.h
* @author MCD Application Team
* @brief USBX Device descriptor header file
******************************************************************************
* @attention
*
* Copyright (c) 2020-2021 STMicroelectronics.
* All rights reserved.
*
* This software is licensed under terms that can be found in the LICENSE file
* in the root directory of this software component.
* If no LICENSE file comes with this software, it is provided AS-IS.
*
******************************************************************************
*/
/* USER CODE END Header */
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __UX_DEVICE_DESCRIPTORS_H__
#define __UX_DEVICE_DESCRIPTORS_H__
#ifdef __cplusplus
extern "C"
{
#endif
/* Includes ------------------------------------------------------------------*/
#include "ux_api.h"
#include "ux_stm32_config.h"
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "main.h"
/* USER CODE END Includes */
/* Private defines -----------------------------------------------------------*/
#define USBD_MAX_NUM_CONFIGURATION 1U
#define USBD_MAX_SUPPORTED_CLASS 3U
#define USBD_MAX_CLASS_ENDPOINTS 9U
#define USBD_MAX_CLASS_INTERFACES 12U
#define USBD_HID_CUSTOM_ACTIVATED 1U
#define USBD_CONFIG_MAXPOWER 0x64 // bMaxPower: 200 mA (0x64 * 2 mA)
#define USBD_COMPOSITE_USE_IAD 1U
#define USBD_DEVICE_FRAMEWORK_BUILDER_ENABLED 1U
#define USBD_FRAMEWORK_MAX_DESC_SZ 200U
/* Exported types ------------------------------------------------------------*/
/* USER CODE BEGIN ET */
/* USER CODE END ET */
/* Enum Class Type */
typedef enum
{
CLASS_TYPE_NONE = 0,
CLASS_TYPE_HID = 1,
CLASS_TYPE_CDC_ACM = 2,
CLASS_TYPE_MSC = 3,
CLASS_TYPE_CDC_ECM = 4,
CLASS_TYPE_DFU = 5,
CLASS_TYPE_VIDEO = 6,
CLASS_TYPE_PIMA_MTP = 7,
CLASS_TYPE_CCID = 8,
CLASS_TYPE_PRINTER = 9,
CLASS_TYPE_RNDIS = 10,
CLASS_TYPE_AUDIO_10 = 11,
CLASS_TYPE_AUDIO_20 = 12,
CLASS_TYPE_TMC = 40,
} USBD_CompositeClassTypeDef;
/* Enum NONE Interface Type */
typedef enum
{
INTERFACE_NONE_DEFIN = 0
} USBD_NONEInterfaceTypeDef;
/* Enum HID Interface Type */
typedef enum
{
INTERFACE_HID_CUSTOM = 0,
INTERFACE_HID_KEYBOARD = 1,
INTERFACE_HID_MOUSE = 2,
} USBD_HIDInterfaceTypeDef;
typedef enum
{
INTERFACE_TMC_USB488 = 1,
} USBD_TMCInterfaceTypeDef;
/* USB Endpoint handle structure */
typedef struct
{
uint32_t status;
uint32_t total_length;
uint32_t rem_length;
uint32_t maxpacket;
uint16_t is_used;
uint16_t bInterval;
} USBD_EndpointTypeDef;
/* USB endpoint handle structure */
typedef struct
{
uint8_t add;
uint8_t type;
uint16_t size;
uint8_t is_used;
} USBD_EPTypeDef;
/* USB Composite handle structure */
typedef struct
{
USBD_CompositeClassTypeDef ClassType;
uint32_t ClassId;
uint8_t InterfaceType;
uint32_t Active;
uint32_t NumEps;
uint32_t NumIf;
USBD_EPTypeDef Eps[USBD_MAX_CLASS_ENDPOINTS];
uint8_t Ifs[USBD_MAX_CLASS_INTERFACES];
} USBD_CompositeElementTypeDef;
/* USB Device handle structure */
typedef struct _USBD_DevClassHandleTypeDef
{
uint8_t Speed;
uint32_t classId;
uint32_t NumClasses;
USBD_CompositeElementTypeDef tclasslist[USBD_MAX_SUPPORTED_CLASS];
uint32_t CurrDevDescSz;
uint32_t CurrConfDescSz;
} USBD_DevClassHandleTypeDef;
/* USB Device endpoint direction */
typedef enum
{
OUT = 0x00,
IN = 0x80,
} USBD_EPDirectionTypeDef;
/* USB Device descriptors structure */
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint16_t bcdUSB;
uint8_t bDeviceClass;
uint8_t bDeviceSubClass;
uint8_t bDeviceProtocol;
uint8_t bMaxPacketSize;
uint16_t idVendor;
uint16_t idProduct;
uint16_t bcdDevice;
uint8_t iManufacturer;
uint8_t iProduct;
uint8_t iSerialNumber;
uint8_t bNumConfigurations;
} __PACKED USBD_DeviceDescTypedef;
/* USB Iad descriptors structure */
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t bFirstInterface;
uint8_t bInterfaceCount;
uint8_t bFunctionClass;
uint8_t bFunctionSubClass;
uint8_t bFunctionProtocol;
uint8_t iFunction;
} __PACKED USBD_IadDescTypedef;
/* USB interface descriptors structure */
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t bInterfaceNumber;
uint8_t bAlternateSetting;
uint8_t bNumEndpoints;
uint8_t bInterfaceClass;
uint8_t bInterfaceSubClass;
uint8_t bInterfaceProtocol;
uint8_t iInterface;
} __PACKED USBD_IfDescTypedef;
/* USB endpoint descriptors structure */
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t bEndpointAddress;
uint8_t bmAttributes;
uint16_t wMaxPacketSize;
uint8_t bInterval;
} __PACKED USBD_EpDescTypedef;
/* USB Config descriptors structure */
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint16_t wDescriptorLength;
uint8_t bNumInterfaces;
uint8_t bConfigurationValue;
uint8_t iConfiguration;
uint8_t bmAttributes;
uint8_t bMaxPower;
} __PACKED USBD_ConfigDescTypedef;
/* USB Qualifier descriptors structure */
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint16_t bcdDevice;
uint8_t Class;
uint8_t SubClass;
uint8_t Protocol;
uint8_t bMaxPacketSize;
uint8_t bNumConfigurations;
uint8_t bReserved;
} __PACKED USBD_DevQualiDescTypedef;
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
uint16_t bcdTMC;
uint16_t bCountryCode;
uint8_t bNumDescriptors;
uint8_t bTMCDescriptorType;
uint16_t wDescriptor;
} __PACKED USBD_TMCDescTypedef;
/* Exported functions prototypes ---------------------------------------------*/
/* USER CODE BEGIN EFP */
/* USER CODE END EFP */
uint8_t *USBD_Get_Device_Framework_Speed(uint8_t Speed, ULONG *Length);
uint8_t *USBD_Get_String_Framework(ULONG *Length);
uint8_t *USBD_Get_Language_Id_Framework(ULONG *Length);
uint16_t USBD_Get_Interface_Number(uint8_t class_type, uint8_t interface_type);
uint16_t USBD_Get_Configuration_Number(uint8_t class_type, uint8_t interface_type);
/* Private defines -----------------------------------------------------------*/
/* USER CODE BEGIN Private_defines */
/* USER CODE END Private_defines */
#define USBD_VID 0x0A69
#define USBD_PID 0x088A
#define USBD_LANGID_STRING 1033 /* English (United States) */
#define USBD_MANUFACTURER_STRING "YONO"
#define USBD_PRODUCT_STRING "yonoDevice"
#define USBD_SERIAL_NUMBER "123456789"
#define USB_DESC_TYPE_INTERFACE 0x04U
#define USB_DESC_TYPE_ENDPOINT 0x05U
#define USBD_EP_TYPE_CTRL 0x00U
#define USBD_EP_TYPE_ISOC 0x01U
#define USBD_EP_TYPE_BULK 0x02U
#define USBD_EP_TYPE_INTR 0x03U
#define USBD_FULL_SPEED 0x00U
#define USBD_HIGH_SPEED 0x01U
#define USB_BCDUSB 0x0200U
#define LANGUAGE_ID_MAX_LENGTH 2U
#define USBD_IDX_MFC_STR 0x01U
#define USBD_IDX_PRODUCT_STR 0x02U
#define USBD_IDX_SERIAL_STR 0x03U
#define USBD_MAX_EP0_SIZE 64U
#define USBD_DEVICE_QUALIFIER_DESC_SIZE 0x0AU
#define USBD_STRING_FRAMEWORK_MAX_LENGTH 256U
/* */
#define UX_DEVICE_CLASS_TMC_CLASS 0xFEU
#define UX_DEVICE_SUB_CLASS_USB488_CLASS 0x03U
/* Device TMC none */
#define USBD_TMC_NONE_EPIN_ADDR 0x81U
#define USBD_TMC_NONE_EPOUT_ADDR 0x01U
#define USBD_TMC_NONE_EPIN_FS_MPS 0x40U
#define USBD_TMC_NONE_EPIN_HS_MPS 0x40U
#define USBD_TMC_NONE_EPIN_FS_BINTERVAL 5U
#define USBD_TMC_NONE_EPIN_HS_BINTERVAL 0U
#define USBD_TMC_NONE_EPOUT_FS_MPS 0x40U
#define USBD_TMC_NONE_EPOUT_HS_MPS 0x40U
#define USBD_TMC_NONE_EPOUT_FS_BINTERVAL 0U
#define USBD_TMC_NONE_EPOUT_HS_BINTERVAL 5U
#ifndef USBD_CONFIG_STR_DESC_IDX
#define USBD_CONFIG_STR_DESC_IDX 0x00
#endif /* USBD_CONFIG_STR_DESC_IDX */
#ifndef USBD_CONFIG_BMATTRIBUTES
#define USBD_CONFIG_BMATTRIBUTES 0x80
#endif /* USBD_CONFIG_BMATTRIBUTES */
/* Private macro -----------------------------------------------------------*/
/* USER CODE BEGIN Private_macro */
/* USER CODE END Private_macro */
#define __USBD_FRAMEWORK_SET_EP(epadd, eptype, epsize, HSinterval, FSinterval) \
do \
{ \
/* Append Endpoint descriptor to Configuration descriptor */ \
pEpDesc = ((USBD_EpDescTypedef *)((uint32_t)pConf + *Sze)); \
pEpDesc->bLength = (uint8_t)sizeof(USBD_EpDescTypedef); \
pEpDesc->bDescriptorType = USB_DESC_TYPE_ENDPOINT; \
pEpDesc->bEndpointAddress = (epadd); \
pEpDesc->bmAttributes = (eptype); \
pEpDesc->wMaxPacketSize = (epsize); \
if(pdev->Speed == USBD_HIGH_SPEED) \
{ \
pEpDesc->bInterval = (HSinterval); \
} \
else \
{ \
pEpDesc->bInterval = (FSinterval); \
} \
*Sze += (uint32_t)sizeof(USBD_EpDescTypedef); \
} \
while(0)
#define __USBD_FRAMEWORK_SET_IF(ifnum, alt, eps, class, subclass, protocol, istring) \
do \
{ \
/* Interface Descriptor */ \
pIfDesc = ((USBD_IfDescTypedef *)((uint32_t)pConf + *Sze)); \
pIfDesc->bLength = (uint8_t)sizeof(USBD_IfDescTypedef); \
pIfDesc->bDescriptorType = USB_DESC_TYPE_INTERFACE; \
pIfDesc->bInterfaceNumber = (ifnum); \
pIfDesc->bAlternateSetting = (alt); \
pIfDesc->bNumEndpoints = (eps); \
pIfDesc->bInterfaceClass = (class); \
pIfDesc->bInterfaceSubClass = (subclass); \
pIfDesc->bInterfaceProtocol = (protocol); \
pIfDesc->iInterface = (istring); \
*Sze += (uint32_t)sizeof(USBD_IfDescTypedef); \
} \
while(0)
#ifdef __cplusplus
}
#endif
#endif /* __UX_DEVICE_DESCRIPTORS_H__ */
Sending and Receiving in usbx Practice#
Regardless of the details, just look at the code. A total of 3 buffers are opened, which is necessary because the USB transmission line will occupy one buffer, one is needed to store the complete statement received, and one is needed for sending storage. It is worth noting that the _ux_device_class_dpump_tmc_read function, even after my modifications, is still a blocking function, so the TMC transmission and reception support in TMC_Engine() needs to occupy a separate thread.
The TMC_Dpump pointer will be bound and unbound in the activate and deactivate of the TMC_Device.
/********************************************************************************
**** Copyright (C), 2024, Yuanlong Xu <[email protected]> ****
**** All rights reserved ****
********************************************************************************
* File Name : ux_device_tmc.c
* Author : yono
* Date : 2025-01-07
* Version : 1.0
********************************************************************************/
/**************************************************************************/
/*
TMC user parsing
*/
/* Includes ------------------------------------------------------------------*/
#include <stdint.h>
#include <stdlib.h>
#include <stdbool.h>
#include "ux_api.h"
#include "ux_device_class_dpump.h"
/* Private types -------------------------------------------------------------*/
/* Private variables ---------------------------------------------------------*/
#define UX_HOST_CLASS_DPUMP_PACKET_SIZE 255
extern UX_SLAVE_CLASS_DPUMP *TMC_Dpump;
/* Channel buffer */
uint8_t device_buffer[UX_HOST_CLASS_DPUMP_PACKET_SIZE];
/* Frame information */
uint8_t TransferEMO = 0; // Transmission end flag 0x00 continue transmission 0x01 transmission end
uint8_t TransferTag = 0; // Transmission token, copied during reply
/* Information buffer */
uint8_t SCPI_Read[255];
uint32_t SCPI_Read_Length = 0;
uint8_t SCPI_Write[255];
uint32_t SCPI_Write_Length = 0;
/* Private Constants ---------------------------------------------------------*/
/* Private macros ------------------------------------------------------------*/
/* Private function prototypes -----------------------------------------------*/
uint32_t TMC_Write(uint8_t *data, uint32_t len);
extern UINT _ux_device_class_dpump_tmc_read(UX_SLAVE_CLASS_DPUMP *dpump, UCHAR *buffer, ULONG requested_length, ULONG *actual_length);
/* Private functions ---------------------------------------------------------*/
void TMC_Engine(void)
{
UINT status;
ULONG actual_length;
if(TMC_Dpump != UX_NULL)
{
/* Receive part */
status = _ux_device_class_dpump_tmc_read(TMC_Dpump, device_buffer, UX_HOST_CLASS_DPUMP_PACKET_SIZE, &actual_length);
if(status == UX_SUCCESS)
{
if((0xff ^ device_buffer[1] ^ device_buffer[2]) || device_buffer[3] != 0)
return; // Bad message
switch(device_buffer[0]) // Command
{
case 0x01:
// Receiving branch
ux_utility_memory_copy(&SCPI_Read[0 + SCPI_Read_Length], // Compatible with segmented transmission, starting from the length of the previous transmission
&device_buffer[12], // Actual data starting position
*(uint32_t *)(&device_buffer[4])); // Bytes 4~7 form the data length in little-endian
SCPI_Read_Length += *(uint32_t *)(&device_buffer[4]);
TransferEMO = device_buffer[8] & 0x01;
if(TransferEMO)
{
/* Loopback test */
TMC_Write(SCPI_Read, SCPI_Read_Length);
/* End compatibility */
// Transmission end triggers parsing
SCPI_Read_Length = 0;
}
else
{
// Transmission not ended, do not process
}
break;
case 0x02:
TransferTag = device_buffer[1]; // Store token
/* 0~3 are request and token, no need to change */
*(uint32_t *)(&device_buffer[4]) = SCPI_Write_Length; // Bytes 4~7 form the data length in little-endian
/* Fixed success data */
device_buffer[8] = 0x1; // Success reply
device_buffer[9] = 0x00;
device_buffer[10] = 0x00;
device_buffer[11] = 0x00;
/* Fill in sending data */
ux_utility_memory_copy(&device_buffer[12], SCPI_Write, SCPI_Write_Length);
/* Fill 0x00; if originally 4-byte aligned, it will add 4 more zeros */
for(uint32_t i = 12 + SCPI_Write_Length; i < ((12 + SCPI_Write_Length + 0x3) & ~0x3U); i++)
{
device_buffer[i] = 0x00;
}
/* Request to send */
status = _ux_device_class_dpump_write(TMC_Dpump, device_buffer, ((12 + SCPI_Write_Length + 0x3) & ~0x3U), &actual_length);
/* Clear sending request */
SCPI_Write_Length = 0;
break;
default:
break;
}
}
}
}
uint32_t TMC_Write(uint8_t *data, uint32_t len)
{
if(sizeof(SCPI_Write) < (SCPI_Write_Length + len))
return 1;
ux_utility_memory_copy(&SCPI_Write[0 + SCPI_Write_Length], // Compatible with segmented filling
data,
len);
SCPI_Write_Length += len;
return 0;
}
/**************************************************************************/
/* */
/* Copyright (c) Microsoft Corporation. All rights reserved. */
/* */
/* This software is licensed under the Microsoft Software License */
/* Terms for Microsoft Azure RTOS. Full text of the license can be */
/* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */
/* and in the root directory of this software. */
/* */
/**************************************************************************/
/**************************************************************************/
/**************************************************************************/
/** */
/** USBX Component */
/** */
/** Device DPUMP Class */
/** */
/**************************************************************************/
/**************************************************************************/
#define UX_SOURCE_CODE
/* Include necessary system files. */
#include "ux_api.h"
#include "ux_device_class_dpump.h"
#include "ux_device_stack.h"
/**
* @brief A non-blocking version based on ux_device_class_dpump_read, suitable for TMC device reception
*/
/**************************************************************************/
/* */
/* FUNCTION RELEASE */
/* */
/* _ux_device_class_dpump_tmc_read PORTABLE C */
/* 6.1 */
/* AUTHOR */
/* */
/* yono, yono233.cn */
/* */
/* DESCRIPTION */
/* */
/* This function reads from the DPUMP class of TMC, */
/* non-blocking of function _ux_device_class_dpump_write. */
/* */
/* INPUT */
/* */
/* dpump Address of dpump class */
/* instance */
/* */
/* OUTPUT */
/* */
/* None */
/* */
/* CALLS */
/* */
/* _ux_device_stack_transfer_request Request transfer */
/* _ux_utility_memory_copy Copy memory */
/* */
/* CALLED BY */
/* */
/* ThreadX */
/* */
/* RELEASE HISTORY */
/* */
/* DATE NAME DESCRIPTION */
/* */
/* 05-19-2020 Chaoqiong Xiao Initial Version 6.0 */
/* 09-30-2020 Chaoqiong Xiao Modified comment(s), */
/* verified memset and memcpy */
/* cases, */
/* resulting in version 6.1 */
/* 01-07-2025 yono Copy and modify to */
/* non-blocking */
/* */
/**************************************************************************/
UINT _ux_device_class_dpump_tmc_read(UX_SLAVE_CLASS_DPUMP *dpump, UCHAR *buffer, ULONG requested_length, ULONG *actual_length)
{
UX_SLAVE_ENDPOINT *endpoint;
UX_SLAVE_DEVICE *device;
UX_SLAVE_TRANSFER *transfer_request;
UINT status;
ULONG local_requested_length;
/* If trace is enabled, insert this event into the trace buffer. */
UX_TRACE_IN_LINE_INSERT(UX_TRACE_DEVICE_CLASS_DPUMP_READ, dpump, buffer, requested_length, 0, UX_TRACE_DEVICE_CLASS_EVENTS, 0, 0)
/* Get the pointer to the device. */
device = &_ux_system_slave->ux_system_slave_device;
/* As long as the device is in the CONFIGURED state. */
if(device->ux_slave_device_state != UX_DEVICE_CONFIGURED)
{
/* Error trap. */
_ux_system_error_handler(UX_SYSTEM_LEVEL_THREAD, UX_SYSTEM_CONTEXT_CLASS, UX_CONFIGURATION_HANDLE_UNKNOWN);
/* If trace is enabled, insert this event into the trace buffer. */
UX_TRACE_IN_LINE_INSERT(UX_TRACE_ERROR, UX_CONFIGURATION_HANDLE_UNKNOWN, device, 0, 0, UX_TRACE_ERRORS, 0, 0)
/* Cannot proceed with command, the interface is down. */
return (UX_CONFIGURATION_HANDLE_UNKNOWN);
}
/* Locate the OUT endpoint. */
endpoint = dpump->ux_slave_class_dpump_bulkout_endpoint;
/* Check endpoint. If NULL, we have not yet received the proper SET_INTERFACE command. */
if(endpoint == UX_NULL)
{
/* Error trap. */
_ux_system_error_handler(UX_SYSTEM_LEVEL_THREAD, UX_SYSTEM_CONTEXT_CLASS, UX_ENDPOINT_HANDLE_UNKNOWN);
return (UX_ENDPOINT_HANDLE_UNKNOWN);
}
/* All DPUMP reading are on the endpoint OUT, from the host. */
transfer_request = &endpoint->ux_slave_endpoint_transfer_request;
/* Reset the actual length. */
*actual_length = 0;
/* Set return status to SUCCESS to make certain compilers happy. */
status = UX_SUCCESS;
/* Check if we need more transactions. */
while(device->ux_slave_device_state == UX_DEVICE_CONFIGURED && requested_length != 0)
{
/* Check if we have enough in the local buffer. */
if(requested_length > UX_SLAVE_REQUEST_DATA_MAX_LENGTH)
/* We have too much to transfer. */
local_requested_length = UX_SLAVE_REQUEST_DATA_MAX_LENGTH;
else
/* We can proceed with the demanded length. */
local_requested_length = requested_length;
/* Send the request to the device controller. */
status = _ux_device_stack_transfer_request(transfer_request, local_requested_length, local_requested_length);
/* Check the status */
if(status == UX_SUCCESS)
{
/* We need to copy the buffer locally. */
_ux_utility_memory_copy(buffer, transfer_request->ux_slave_transfer_request_data_pointer, local_requested_length); /* Use case of memcpy is verified. */
/* Next buffer address. */
buffer += transfer_request->ux_slave_transfer_request_actual_length;
/* Set the length actually received. */
*actual_length += transfer_request->ux_slave_transfer_request_actual_length;
/* Decrement what left has to be done. */
requested_length -= transfer_request->ux_slave_transfer_request_actual_length;
/* actual_length > 0 */
if(*actual_length > 0)
{
return UX_SUCCESS;
}
}
else
/* We got an error. */
return (status);
}
/* Check why we got here, either completion or device was extracted. */
if(device->ux_slave_device_state != UX_DEVICE_CONFIGURED)
{
/* Error trap. */
_ux_system_error_handler(UX_SYSTEM_LEVEL_THREAD, UX_SYSTEM_CONTEXT_CLASS, UX_TRANSFER_NO_ANSWER);
/* If trace is enabled, insert this event into the trace buffer. */
UX_TRACE_IN_LINE_INSERT(UX_TRACE_ERROR, UX_TRANSFER_NO_ANSWER, transfer_request, 0, 0, UX_TRACE_ERRORS, 0, 0)
/* Device must have been extracted. */
return (UX_TRANSFER_NO_ANSWER);
}
else
/* Simply return the last transaction result. */
return (status);
}
Special Support for Setup in usbx Practice#
We know that to enable a device class in usbx, we must call the ux_device_stack_class_register() API, which is suitable for passing an _entry function as the class driver. According to the official examples and documentation of usbx, it is best to base custom class enumeration on the dpump class, so here we modify a TMC class driver based on _ux_device_class_dpump_entry.
The main modifications are needed in the **UX_SLAVE