新添USB host class驱动开发

站长荐语：虽然本文谈的主题是添加USB Host Class驱动，但文中所用到的方法具有普遍意义，所有MCU工程师都可以使用这种方法，参照已有功能做其它功能的扩展。

前 言

由于NXP有专业的MCU USB软件开发团队，NXP SDK USB协议栈支持了众多的常用class，功能异常强大，为用户带来了很多的便利，加速了客户的产品研发。

1. 实现一个新的USB host class需要解决的问题。

2. SDK USB host协议栈的基础知识。

3. 实现新的USB host class的一些要点展示。

需要解决的问题

实现一个新的USB host class，我们需要解决以下问题：

• 如何进行枚举，拿到设备的各种描述符？

• 如何建立pipe（Bulk, Inerrupt, … …）通信？

• 如何进行USB host class的上层开发？

小编整理了一个USB 应用的模型结构如下图所示。

从这个结构图中，我们可以看到，基于USB协议栈，我们要重点实现pipe通信，在pipe通信之上，是具体的USB class的实现。而最终的应用是基于class实现的基础之上的。

这个图同时也说明，class的实现以及应用，可以通过pipe与USB stack进行隔离，相互保持独立。软件模块之间保持独立/低耦合，可以使软件系统更加易于调试、维护和更新。

而USB控制器，在强大的SDK USB协议栈的加持下，对我们来说完全可以不关心。小编整个开发过程中，完全不需要去了解USB控制器的任何知识就可以完成新的host class的开发。

协议栈的基础知识

一、从task的角度来看USB host协议栈

了解task结构对于了解USB host协议栈是如何工作的非常有帮助。

几个关键点（图中红色字体所示）就在于：

1. 应用层事件的回调机制
2. 设备状态管理，主要是设备的接入、拔除、枚举等。
3. Class状态管理，这里是设备运行的状态机管理，包含了关键的class的interface和pipe的建立，class的初始化等等。

二、从函数调用栈的角度看USB host协议栈

对于复杂的软件系统，分析调用栈是个不二捷径，屡试不爽。

软件工程学里面有一个概念，叫隔离。隔离是一个非常重要的概念，软件工程学者认为隔离可以给软件系统带来很多的好处，两个隔离的模块，一个模块做了内部改动的同时，不会影响到另一个模块。对于复杂系统来说，这点尤其重要。

而具体到C语言，这种隔离的具体体现就是函数指针。

void open_door(void)
{
action of open door
}

然后调用的时候我们只需要：

open_door();

就可以了。

引入隔离和指针后，我们就看不见函数的实现了，甚至看不到被调用的函数名，而是只需要知道通过指针进行访问。

当然，我们的SDK USB协议栈是由专业的软件团队开发的，自然也不可避免的使用了这一理念，在带来各种强大而精彩的功能的同时，也不可避免的引入了其弊端。所以我们是无法用静态代码阅读的方式去快速了解这套软件的。

小编的解决方法是观察调用栈，几个核心的调用栈被列出来后，整个软件的运行体系就自然而然水落石出，山高月小。

调用栈分析的方法除了可以用在有函数指针的场景下，对于没有函数指针的复杂软件分析的场景也同样适用，可以用海量的代码中迅速看到函数之间的多层级联调用关系，这是快速分析复杂软件的很高效的方法。

这里小编列出了6个核心调用栈给大家参考，根据小编的实际使用体验，这6个核心调用栈已经足以帮助小编解决新的USB host classk开发中的所有问题了。如果读者有别的问题，也可以采用类似的方法来了解整个软件体系的结构，这比直接阅读代码要高效太多太多。

核心调用栈2：在何处解析配置描述符？

核心调用栈3：Host event是如何回调回来的？

核心调用栈4：什么时候打开系统的控制interface/pipe？

核心调用栈5：什么时候打开class的控制interface/pipe？

核心调用栈6：什么时候打开class的数据interface/pipe？

实现的一些要点展示

在本章节中，将探讨如何基于现有的USB host CDC class来实现USB host CCID class。本章节会展示一些关键点，也基本上是step by step的guide。

一、获取设备描述符内容

获取设备描述符的相关函数在USB_HostProcessCallback()in usb_host_devices.c

这里我们只需要加入内存打印语句，就可以把从device获取到的描述符打印出来。

由于我们重用了USB host CDC的架构，这部分不需要做任何改动就可以直接进行枚举。

case kStatus_DEV_GetDes8: /* process get 8 bytes descriptor result */
… … 
usb_echo("kStatus_DEV_GetDes8\r\n");
mem_dump_8(deviceInstance->deviceDescriptor, dataLength);
case kStatus_DEV_GetDes: /* process get full device descriptor result */
… … 
usb_echo("kStatus_DEV_GetDes\r\n");
mem_dump_8(deviceInstance->deviceDescriptor, dataLength);
break;
case kStatus_DEV_GetCfg9: /* process get 9 bytes configuration result */
… … 
usb_echo("kStatus_DEV_GetCfg9\r\n");
mem_dump_8(configureDesc, dataLength);
case kStatus_DEV_GetCfg: /* process get configuration result */
… … 
usb_echo("kStatus_DEV_GetCfg\r\n");
mem_dump_8(deviceInstance->configurationDesc, dataLength);

Console output:
kStatus_DEV_GetDes8
0x20003fa8: 12 01 00 02 00 00 00 40 
kStatus_DEV_GetCfg9
0x20003fba: 09 02 5d 00 01 01 00 c0 
0x000000c7: 32 -- -- -- -- -- -- -- 
kStatus_DEV_GetCfg
0x20003fd0: 09 02 5d 00 01 01 00 c0 
0x20003fd8: 32 09 04 00 00 03 0b 00 
0x20003fe0: 00 03 36 21 10 01 01 02 
0x20003fe8: 01 00 00 00 fc 0d 00 00 
0x20003ff0: fc 0d 00 00 00 80 25 00 
0x20003ff8: 00 80 25 00 00 00 00 00 
0x20004000: 00 00 00 00 00 00 00 00 
0x20004008: 00 00 38 00 02 00 0f 01 
0x20004010: 00 00 00 00 00 00 00 01 
0x20004018: 07 05 81 02 40 00 00 07 
0x20004020: 05 02 02 40 00 00 07 05 
0x000000f7: 83 03 08 00 08 -- -- --
device not supported.

从这里我们可以看到从设备获取的设备描述符和配置描述符，但是进一步显示设备不支持。

二、为什么设备不支持？

要得到答案，这个问题还是要研究一下的，这里小编就不绕弯子，直接公布答案了：

在USB_HostCdcEvent(), host_cdc.c，这里面会解析配置描述符的信息，看是不是CDC的class，因为我们接入的是CCID设备，而原始代码是按照CDC class去解析，自然就会失败。

usb_status_t USB_HostCdcEvent(usb_device_handle deviceHandle,
usb_host_configuration_handle configurationHandle,
uint32_t event_code)
{
… … 
switch (event_code)
{
case kUSB_HostEventAttach:
… … 
for (interface_index = 0; interface_index < configuration->interfaceCount; ++interface_index)
{
hostInterface = &configuration->interfaceList[interface_index];
id            = hostInterface->interfaceDesc->bInterfaceClass;
if (id == USB_HOST_CCID_CLASS_CODE)                
{                    
usb_echo("***ccid device detected. \r\n");
cdcDataInterfaceHandle = hostInterface;
cdcDeviceHandle      = deviceHandle;
break;
}
}

if ((NULL != cdcDataInterfaceHandle) && (NULL != cdcDeviceHandle))
{
status = kStatus_USB_Success;
}
else
{
status = kStatus_USB_NotSupported;
}
break;

当我们在这里正确的识别到CCID class设备，返回kStatus_USB_Success，就不会出现设备不支持了。

Console output:
kStatus_DEV_GetDes8
0x20003fa8: 12 01 00 02 00 00 00 40 
kStatus_DEV_GetCfg9
0x20003fba: 09 02 5d 00 01 01 00 c0 
0x000000b6: 32 -- -- -- -- -- -- -- 
kStatus_DEV_GetCfg
0x20003fd0: 09 02 5d 00 01 01 00 c0 
0x20003fd8: 32 09 04 00 00 03 0b 00 
0x20003fe0: 00 03 36 21 10 01 01 02 
0x20003fe8: 01 00 00 00 fc 0d 00 00 
0x20003ff0: fc 0d 00 00 00 80 25 00 
0x20003ff8: 00 80 25 00 00 00 00 00 
0x20004000: 00 00 00 00 00 00 00 00 
0x20004008: 00 00 38 00 02 00 0f 01 
0x20004010: 00 00 00 00 00 00 00 01 
0x20004018: 07 05 81 02 40 00 00 07 
0x20004020: 05 02 02 40 00 00 07 05 
0x000000e6: 83 03 08 00 08 -- -- -- 
***ccid device detected.

可以看到，我们目前拿到了CCID的配置描述符，并且根据spec正确的识别到了CCID设备，这样枚举就过了。

是不是感觉很轻松？

三、CCID配置描述符解析

这里仅列出CCID配置描述符的结构。

重点是我们要知道，CCID class有一个interface，里面有3个EP，一个Bulk In，一个Bulk Out，一个Interrupt In，我们会根据这个信息在下一步调整class状态机。

四、class状态机分析

Class状态机在USB_HostCdcTask()中实现。

先看看CDC的状态机：

与CDC相比，CCID只有一个interface，并且设备相关上层操作小编想独立出来在另外的地方做，于是CCID的状态机如下，灰色部分为跳过的部分。

五、打开interface和pipe

打开interface和pipe和操作在USB_HostCdcOpenDataInterface(), 位于文件usb_host_cdc.c中。

for (ep_index = 0; ep_index < interfaceHandle->epCount; ++ep_index)
{
usb_echo("ep_index = %x\r\n", ep_index);

ep_desc = interfaceHandle->epList[ep_index].epDesc;
if (((ep_desc->bEndpointAddress & USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_MASK) ==
USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_IN) &&
((ep_desc->bmAttributes & USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_TYPE_MASK) == USB_ENDPOINT_BULK))
{
… …
status  = USB_HostOpenPipe(cdcInstance->hostHandle, &cdcInstance->inPipe, &pipeInit);
… …
}
else if (((ep_desc->bEndpointAddress & USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_MASK) ==
USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_OUT) &&
((ep_desc->bmAttributes & USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_TYPE_MASK) == USB_ENDPOINT_BULK))
{
… … 
status = USB_HostOpenPipe(cdcInstance->hostHandle, &cdcInstance->outPipe, &pipeInit);
… … 
}
else if (((ep_desc->bEndpointAddress & USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_MASK) ==
USB_DESCRIPTOR_ENDPOINT_ADDRESS_DIRECTION_IN) &&
((ep_desc->bmAttributes & USB_DESCRIPTOR_ENDPOINT_ATTRIBUTE_TYPE_MASK) == USB_ENDPOINT_INTERRUPT))
{
… … 
status = USB_HostOpenPipe(cdcInstance->hostHandle, &cdcInstance->interruptPipe, &pipeInit);
……
}

需要注意的是，USB协议栈会自动解析interface和endpoint，这里的数据结构是前面已经解析过的。我们需要在这里去识别Bulk In, Bulk Out, 以及Interrupt In。

Console log:***ccid device detected. 
device cdc attached:
pid=0x9cvid=0x1fc9 address=1
cdc device attached
s - kUSB_HostCdcRunSetControlInterfaceDone 
--> USB_HostCdcOpenDataInterface 
ep_index = 0bulk in ep_index = 1bulk out ep_index = 2interrupt in 
s - kUSB_HostCdcRunSetDataInterfaceDone

从log我们可以看到，我们已经成功的检测到interface下面的3个EP了，Bulk In， Bulk Out，Interrupt In。

六、测试pipe的通信

既然pipe已经打开，下面我们就要测试一下pipe的通信了。

这里我们沿用了USB stack的task的做法，在一个无限loop里面去做处理，所以需要变量记录状态。

case kUSB_HostCdcRunSetControlInterfaceDone:
... ...
if (USB_HostCdcSetDataInterface(cdcInstance->classHandle, cdcInstance->dataInterfaceHandle, 0,
USB_HostCdcControlCallback, &g_cdc) != kStatus_USB_Success)
{
usb_echo("set data interface error\r\n");
}
… …            
ccid_communication_ready();
break;

然后我们就可以基于USB stack的API进行pipe通信了，相关代码如下(位于函数ccid_app_task()中)：

if(flag_test == 0)
{
usb_echo("ccid_ready_for_communicatio \r\n");        USB_HostCdcDataSend(g_cdc.classHandle, "12345", 5, USB_CCID_BULK_OUT_Callback, &g_cdc);
}
else if(flag_test == 2)
{        USB_HostCdcInterruptRecv(g_cdc.classHandle, buf, 8,USB_CCID_HID_Callback, &g_cdc);
}
else if(flag_test == 4)
{        USB_HostCdcDataRecv(g_cdc.classHandle, buf, 8,USB_CCID_BULK_IN_Callback, &g_cdc);
}

注意这里的收发API都是基于回调机制，收发完成后和app通过回调函数进行同步（通信）。

回调机制是一个非常优秀的机制（这同时也是小编前面吐槽的函数指针，又爱又恨），这样避免了低效率的状态轮询。

完成相关的代码后，接下来测试pipe，看看log输出：

Console log:ep_index = 0
bulk in 
ep_index = 1
bulk out 
ep_index = 2
interrupt in 
ccid_ready_for_communicatio 
s - kUSB_HostCdcRunSetDataInterfaceDone 
USB_CCID_BULK_OUT_Callback
USB_CCID_HID_Callback
USB_CCID_BULK_IN_Callback

这里我们可以看到回调机制已经正确触发了。

这里可以看到，我们已经正确的触发了Bulk In，Bulk Out以及Interrupt transfer。

七、关于新的class的开发和上层应用开发

在pipe的通信已经正确的建立后，class的开发和上层应用的开发，并没有统一的模式。每个工程师很可能都有自己的想法去实现，这部分的实现，自由度可以很大。

对于CCID我们要做的主要工作是集成spec定义的消息，以及spec定义的相关的通信状态机。这部分本文并不做重点讨论，每个class都有自己的特点和定义，需要参考spec和应用场景去具体实现。

小编这里推荐尽量把具体的class处理的这部分相对于USB stack独立出来，这样系统的整体设计脉络更加清晰一些，让我们更能聚焦在新的USBhost class的开发，也便于软件的长期开发和维护。

八、本文的相关代码

本文的相关代码可以从以下链接进行获取，该代码下载后可以直接编译并且运行在i.MXRT1020 EVK上。

https://github.com/jiaguonxpcom/usb_host_ccid

小 结

本文基于i.MX RT1020平台，向读者展示了如何基于NXP SDK USB host来实现一个新的class，重点讲述了相关pipe的建议。建立pipe通信是实现新的USB host的核心步骤。

希望本文能给需要做相关类似开发的读者一些参考，避免少走弯路，而愉快的基于SDK USB协议栈完成相关的新任务的开发。