ht32 系列微控制器 usb 設備開發工具包 - holtek · ht32 系列的 usb...

HT32 系列微控制器 USB 設備開發工具包


文件編碼：AN0309T

簡介HT32 系列的 USB 設備開發工具包由幾個部分組成，包括 USB 設備韌體庫、類別範例和基於

Windows 的 UI 展示。它支援所有具有 USB 設備控制器 Holtek HT32 系列微控制器。本應用範

例有助於用戶熟悉 HT32 系列的 USB 設備開發工具包，創建自己的 USB 應用。類別範例代碼

包含了所有的 USB 傳輸類型，如控制、中斷、批量和等時。本文檔提供了以下元件的描述：

HT32 系列的 USB 設備韌體庫：外設驅動、USB 核心和應用層

人機週邊設備（HID）範例：控制和中斷傳輸

大容量儲存範例：批量傳輸

虛擬 COM 埠範例：中斷和批量傳輸

USB 視頻範例：等時傳輸

HT32 系列USB設備韌體庫

本章節描述 HT32 系列 USB 設備韌體庫的結構和應用程式編程介面（API）。HT32 系列 USB

設備韌體庫為實現以下功能提供了參考。

HT32 USB 設備控制器的初始化

USB 匯流排事件處理

USB 枚舉

USB 描述符

USB 標準請求

USB 類別請求

USB 端點 IN 和 OUT 傳輸

1


概述

結構

HT32 USB 設備韌體庫可以分為三層，硬體和外設驅動器、USB 核心以及應用。圖 1 顯示了每

一層的介面及其交互作用。任何具有 USB 控制器的 HT32 系列微控制器只需很少修改，就可重

複使用 USB 核心層和應用層。對於大多數類別應用，需要修改類別和描述符，以適應應用的需

求。USB 核心層和 USB 驅動層在一般情況下不需要修改。

圖 1 HT32 USB 設備韌體庫方塊圖

每一層的功能：

USB 外設驅動：USB 外設驅動層提供了基本的硬體初始化，暫存器層訪問和端點緩衝區訪

問功能。

USB 核心：USB 核心層負責管理主要的 USB 協定，包括匯流排事件、枚舉和標準請求。它

提供了一個中斷服務程式來處理所有的 USB 匯流排活動。

應用：應用層包括 USB 描述符資料、類別請求和端點資料處理。USB 類別的主要功能設在

這一層。

2


檔組織

圖 2 為 HT32 系列微控制器的 USB 設備驅動器、USB 核心和類別範例代碼的檔組織圖。請注意，

不同類別範例代碼的類別應用層檔可能不同。

圖 2 HT32 USB 設備韌體庫的檔組織

表 1 顯示了每一層的檔：

表 1 HT32 USB 設備韌體庫的檔列表

層文件描述

ht32_usb.h 頭檔，提供 HT32 韌體庫給 API

ht32fxxxx_usbd.h 外設驅動器的頭檔

ht32fxxxx_usbdinit.h 從 "ht32fxxxx_usbdconf.h" 檔案，檢查和處理定義

的頭檔

USB 外設驅動

ht32fxxxx_usbd.c 外設驅動器的原始檔案

ht32_usbd_core.h USB 核心的頭文件 USB 核心

ht32f_usbd_core.c USB 核心的原始檔案

ht32f_usbd_class.c 類別範例代碼的原始檔案

ht32f_usbd_class.h 類別範例代碼的頭檔

ht32_usbd_descriptor.c 描述符的原始檔案應用

ht32_usbd_descriptor.h 描述符的頭檔

CCllaassss // DDeessccrriippttoorr // AApppplliiccaattiioonn

UUSSBB CCoorree

UUSSBB DDrriivveerr

3


源代碼的命名規則

HT32 USB 設備韌體庫使用下面的命名規則。明確貼切的命名規則有助於用戶更容易理解和修

改源代碼。

表 2 HT32 USB 設備韌體庫的命名規則

類型命名規則/範例描述

函數名

Prefix_FunctionName（模組名首碼）

USBDCore_FunctionName: USB 核心

USBD_FunctionName: USB 驅動

USBDClass_FunctionName: 類別應用

所有的函數名添加模組名首碼，以助

於用戶識別該函數屬於哪個模組。

USB 核心層使用 API 巨集定義作為

USB 驅動層的介面。它為 USB 驅動提

供了靈活的函數名。只要在驅動器的

頭檔中定義特定的 API 巨集，USB 驅

動器就可以使用任何函數名。

API 巨集

API_USB_NAME (參數)

#define API_USB_INIT(driver)

(USBD_Init(driver))

常量定義 #define DEFINE_NAME

#define DESC_LEN_HID ((u32)(9)) 定義全部大寫

枚舉類型定義

Prefix_NAME_Enum

typedef enum

{

….

} USBD_EPTn_Enum;

以模組名首碼開頭，以"Enum"結尾

結構類型定義

Prefix_NAME_TypeDef

typedef struct

{

…

} USBDCore_Info_TypeDef;

以模組名首碼開頭，以"TypeDef"結尾

指標以"p"為首碼 Pointer: u32 *pDriver;

無符號變數以"u"為首碼 u8/u16/u32: u32 uPara;

s8/s16/s32: s32 sByteLength; 符號變數以"s"為首碼變數

Structure: USBDCore_TypeDef USBCore;

Enumeration: USBDCore_Action_Enum Action;所有的結構或枚舉變數都無首碼

總體變數 u8 gInputReportBuffer[64]; 總體變數以"g"為首碼

4


USB外設驅動

USB 外設驅動包括"ht32_usb.h"、"ht32fxxxx_usbd.h"、"ht32fxxxx_usbdinit.h"和"ht32fxxxx_usbd.c"

幾個檔案。下表列出了 USB 外設驅動模組。

表 3 USB 外設驅動模組

模組描述

USB 核心的 HT32 韌體庫 API。通過 USB 核心的該檔案可以瞭解

外設驅動的檔案名稱。 ht32_usb.h

外設驅動器提供硬體初始化、暫存器層訪問和端點緩衝區訪問功

能。 ht32fxxxx_usbd (.h, .c)

此檔案提供了在應用層的"ht32fxxxx_usbdconf.h"檔中定義的參數

的預處理器檢查。 ht32fxxxx_usbdinit.h

USB 外設驅動使用 API 進行硬體初始化、暫存器層訪問、端點緩衝區訪問等等。API 可分為

兩種，全局 API 和端點 API。之後的章節簡單介紹了全局 API，端點 API 以及作為 USB 核

心層與驅動層介面的 API 巨集。更詳細的資訊，請參考相應設備的編程指南。

全局 API

全局 API 表示 USB 設備控制器共同設定的函數，如電源控制、設備位址和中斷操作等。正如

我們之前提到的，所有的全局 API 都有"USBD_"首碼和一個便於理解的函數名。下表顯示了所

有的 API 與其描述。

表 4 USB 外設驅動器的全局 API

API 名稱描述

USB 外設初始化，包括端點的初始值、電源控

制和中斷遮罩。 void USBD_Init(u32 *pDriver);

此函數通過應用層的"ht32fxxxx_usbdconf.h"檔

案中的值初始化"USBD_Driver_TypeDef"結構。void USBD_PreInit(USBD_Driver_TypeDef *pDriver);

void USBD_DeInit(void); USB 外設取消初始化。

void USBD_PowerOff(void); 進入 USB 設備暫停模式。

void USBD_PowerOn(void); 退出 USB 設備暫停模式。

void USBD_RemoteWakeup(void); 向 USB 主機發送恢復請求進行遠端喚醒。

void USBD_ReadSETUPData(u32 *pBuffer); 從 USB 緩衝區讀取端點 0 的 SETUP 數據。

void USBD_SetAddress(u32 address); 設定 USB 設備位址。

void USBD_EnableINT(u32 INTFlag); 使能 USB 設備中斷。

void USBD_DisableINT(u32 INTFlag); 除能 USB 設備中斷。

u32 USBD_GetINT(void); 獲取 USB 設備中斷旗標。

void USBD_ClearINT(u32 INTFlag); 清除 USB 設備中斷旗標。

USBD_EPTn_Enum USBD_GetEPTnINTNumber(u32

INTFlag); 獲取發生中斷的有效 USB 端點編號。

5


6

端點 API

端點 API 是用來控制端點的初始化、重定、緩衝區訪問、匯流排響應（STALL/NAK/ACK）和

中斷操作的函數。所有的端點 API 都有"USBD_EPT"首碼和一個便於理解的函數名。下表顯示

了所有的 API 與其描述。

表 5 USB 外設驅動器的端點 API

API 名稱描述

void USBD_EPTInit(USBD_EPTn_Enum EPTn, u32 *pDriver); 端點初始化，包括控制和中斷暫存器。

void USBD_EPTReset(USBD_EPTn_Enum EPTn); 端點重置到默認狀態。

void USBD_EPTEnableINT(USBD_EPTn_Enum EPTn, u32 INTFlag); 使能端點中斷。

u32 USBD_EPTGetINT(USBD_EPTn_Enum EPTn); 獲取端點中斷旗標。

void USBD_EPTClearINT(USBD_EPTn_Enum EPTn, u32 INTFlag); 清除端點中斷旗標。

u32 USBD_EPTGetHalt(USBD_EPTn_Enum EPTn); 獲取端點暫停狀態。

void USBD_EPTSendSTALL(USBD_EPTn_Enum EPTn); 在指定端點發送 STALL。

void USBD_EPTSetHalt(USBD_EPTn_Enum EPTn); 設定端點暫停狀態。

void USBD_EPTClearHalt(USBD_EPTn_Enum EPTn); 清除端點暫停狀態。

void USBD_EPTWaitSTALLSent(USBD_EPTn_Enum EPTn); 等待 STALL 發送。

void USBD_EPTClearDTG(USBD_EPTn_Enum EPTn); 清除端點資料觸發位元。

u32 USBD_EPTGetBuffer0Addr(USBD_EPTn_Enum EPTn); 獲取端點緩衝區 0 的地址。

u32 USBD_EPTGetBuffer1Addr(USBD_EPTn_Enum EPTn); 獲取端點緩衝區 1 的地址。

u32 USBD_EPTGetBufferLen(USBD_EPTn_Enum EPTn); 獲取端點緩衝區長度。

u32 USBD_EPTGetTransferCount(USBD_EPTn_Enum EPTn,

USBD_TCR_Enum type); 獲取端點傳輸計數。

u32 USBD_EPTWriteINData(USBD_EPTn_Enum EPTn, u32 *pFrom,

u32 len); 寫 IN 數據到 USB 緩衝區。

u32 USBD_EPTReadOUTData(USBD_EPTn_Enum EPTn, u32 *pTo,

u32 len); 從端點緩衝區讀OUT資料，清除NAK位元。

u32 USBD_EPTReadMemory(USBD_EPTn_Enum EPTn, u32 *pTo,

u32 len); 從端點緩衝區讀 OUT 數據。


API 巨集

USB 核心使用 API 巨集作為與 USB 外設驅動層連接的介面，以保持它們之間的資訊全透明。

下表顯示了 USB 核心使用的所有 API 巨集。更詳細的資訊請參考"ht32fxxxx_usbd.h"文件。任

何與 USB 核心層一起使用的外設驅動器，應在頭檔中正確地定義特定的 API 巨集。與 USB 外

設驅動器一樣，API 巨集可以分為兩種，全局和端點。所有的全局 API 巨集都有"API_USB"首

碼和一個便於理解的函數名。所有的端點 API 巨集都有"API_USB_EPTn"首碼和一個便於理解

的函數名。

表 6 USB 核心和 USB 外設驅動層之間的 API 巨集

API 巨集名稱描述

全局 API 巨集

API_USB_INIT(driver) USB 外設初始化 API 巨集通過 USBDCore_Init()函數呼叫。

USB 外設取消初始化函數。當重定事件發生在 USB 匯流排，

USBDCore_Reset()函數將呼叫這個 API 巨集。 API_USB_DEINIT()

API_USB_POWER_OFF() 此 API 巨集用於關閉 USB 設備的電源。

API_USB_POWER_ON() 此 API 巨集用於打開 USB 設備的電源。

API_USB_REMOTE_WAKEUP() 此 API 巨集用於向 USB 主機發送恢復請求進行遠端喚醒。

API_USB_READ_SETUP(buffer) 從 USB 緩衝區讀取 SETUP 數據。

API_USB_SET_ADDR(addr) 設定 USB 設備位址。

API_USB_GET_CTRL_IN_LEN() 獲取控制 IN 資料長度。

API_USB_ENABLE_INT(flag) 使能全局中斷。

API_USB_GET_INT() 獲取全局中斷旗標。

API_USB_GET_EPT_NUM(flag) 獲取發生中斷的有效 USB 端點編號。

API_USB_IS_RESET_INT(flag) 決定是否產生重置中斷。

API_USB_CLR_RESET_INT() 清除重置中斷。

API_USB_IS_SOF_INT(flag) 決定是否產生幀起始中斷。

API_USB_CLR_SOF_INT() 清除幀起始中斷。

API_USB_IS_RESUME_INT(flag) 決定是否產生恢復中斷。

API_USB_CLR_RESUME_INT() 清除恢復中斷。

API_USB_IS_SUSPEND_INT(flag) 決定是否產生暫停中斷。

API_USB_CLR_SUSPEND_INT() 清除暫停中斷。

API_USB_IS_EPTn_INT(flag, EPTn) 決定是否產生端點中斷。

API_USB_CLR_EPTn_INT(EPTn) 清除端點中斷。

端點 API 巨集

API_USB_EPTn_INIT(EPTn, driver) 端點初始化 API 巨集通過 Set Configuration 標準命令呼叫。

API_USB_EPTn_RESET(EPTn) 端點重置到默認狀態。

API_USB_EPTn_SEND_STALL(EPTn) 發送 STALL 到特定端點。

API_USB_EPTn_GET_INT(EPTn) 獲取端點中斷旗標。

API_USB_EPTn_IS_IN_INT(flag) 決定是否產生端點 IN 中斷。

API_USB_EPTn_CLR_IN_INT(EPTn) 清除端點 IN 中斷旗標。

API_USB_EPTn_IS_OUT_INT(flag) 決定是否產生端點 OUT 中斷。

API_USB_EPTn_CLR_OUT_INT(EPTn) 清除端點 OUT 中斷旗標。

API_USB_EPTn_IS_INT(flag) 決定是否產生端點 IN 或 OUT 中斷。

API_USB_EPTn_CLR_INT(EPTn) 清除端點 IN 或 OUT 中斷旗標。

API_USB_EPTn_GET_HALT(EPTn) 獲取端點暫停狀態。

API_USB_EPTn_SET_HALT(EPTn) 設定端點暫停狀態。

7


API 巨集名稱描述

API_USB_EPTn_CLR_HALT(EPTn) 清除端點暫停狀態。

API_USB_EPTn_WAIT_STALL_SENT(EPTn) 等待 STALL 發送。

API_USB_EPTn_CLR_DTG(EPTn) 清除端點資料觸發位元。

API_USB_EPTn_GET_BUFFLEN(EPTn) 獲取端點緩衝區長度。

API_USB_EPTn_GET_CNT(EPTn, type) 獲取端點傳輸計數。

API_USB_EPTn_WRITE_IN(EPTn, from, len) 寫 IN 數據到 USB 緩衝區。

API_USB_EPTn_READ_OUT(EPTn, to, len) 從端點緩衝區讀 OUT 資料，清除 NAK 位元。

API_USB_EPTn_READ_MEM(EPTn, to, len) 從端點緩衝區讀 OUT 數據。

USB核心

USB 核心由 "ht32_usbd_core.h" 和 "ht32_usbd_core.c" 兩個檔案組成。所有的 USB 核心功能，

如匯流排事件處理程式、標準請求、枚舉和控制 IN/OUT，都可以在這一層實現。以下幾節描

述了變數結構、USB 核心操作以及 USB 核心 API。

表 7 USB 核心模組

模組描述

USB 核心模組，包括 USB 匯流排事件處理程式、標準請求、枚舉和控制 IN/OUT

功能。 ht32_usbd_core (.h, .c)

變數結構

對於 USB 核心操作，USB 核心層提供了一個名為 "USBDCore_TypeDef" 的結構，為 USB 核心

函數提供必要的變數。用戶應聲明這個結構作為總體變數，並傳送到 "USBDCore_Init()" 函數

的儲存位址。 "USBDCore_TypeDef " 結構也為應用層函數提供必要的變數，如

"USBDDesc_Init()" 和 "USBDClass_Init()" 函數。詳細的使用資訊稍後將在應用層討論。下表

顯示了 "USBDCore_TypeDef" 結構的所有成員及其描述。更詳細的資訊請參考

"ht32_usbd_core.c/h" 文件。

表 8 USB 核心的變數結構

名稱類型描述

bmRequestType：請求特性。

bRequest：特定請求。

wValueL：請求參數低位元組。

wValueH：請求參數高位元組。

wIndex：請求參數。

Request.

(USBDCore_Reque

st_TypeDef)

wLength：資料傳輸階段的位元組數。

pDeviceDesc：設備描述符的資料指標。

pConfnDesc：配置描述符的資料指標。

Desc.

(USBDCore_Desc_

TypeDef) pStringDesc[n]：字串描述符的資料指標。

uBuffer[2]：臨時緩衝區。

pData：控制 IN/OUT 資料的指標。

sByteLength：控制 IN/OUT 傳輸的總長度。

Action：STALL、控制 IN 或 OUT。

(USBDCore_Action_Enum)

Device.

(USBDCore_Dev

ice_TypeDef)

Transfer.

(USBDCore_Transf

er_TypeDef)

CallBack_OUT.func/uPara：控制 OUT 的回調函數指標

和參數。

uCurrentConfiguration：用於設定/獲取配置請求。

uCurrentInterface：用於設定/獲取介面請求。

CurrentStatus：設備的狀態。(USBDCore_Status_Enum)

USBCore.

(USBDCore_Typ

eDef)

Info.

(USBDCore_Info

_TypeDef)

LastStatus：設備暫停前的狀態。(USBDCore_Status_Enum)

8


名稱類型描述

CurrentFeature：用於設定/清除特性，並獲取狀態請求。

(USBDCore_Feature_TypeDef)

uIsDiscardClearFeature：放棄清除大容量儲存的特性請求。

CallBack_MainRoutine.func/uPara：類別主程式的回調函數/參數。

CallBack_StartOfFrame：類別 SOF 的回調函數。

CallBack_ClassGetDescriptor：類別獲取描述符的回調函數。

CallBack_ClassSetInterface(pDev)：類別設置介面的回調函數。

CallBack_ClassRequest(pDev)：類別請求回調函數。

Class.

(USBDCore_Clas

s_TypeDef)

CallBack_EPTn[MAX_EP_NUM](EPTn)：端點 n 回調函數。

pDriver (u32) USB 設備驅動器的初始化結構。

Power.

(USBDCore_Pow

er_TypeDef)

CallBack_Suspend.func/uPara：暫停時系統低功耗函數/參數。

USB 核心操作

當特定的 USB 匯流排事件發生後，USB 設備 IP 發出中斷信號，通知 CPU 發生了事件，需要處

理。中斷控制器和 CPU 完成所有必要的操作後，CPU 開始執行中斷服務程式（ISR），來處理

USB 匯流排事件。USB 核心層提供了 ISR 函數 "USBDCore_IRQHandler()" 來完成上述操作。

"USBDCore_IRQHandler()" 通過 API 巨集（外設驅動層）檢查 USB 設備 IP 的狀態暫存器，以

確定 USB 匯流排事件，然後呼叫相應的函數來處理它。下表給出了所有 USB 匯流排事件及其

相應函數。詳細的操作請參考 "ht32_usbd_core.c" 檔中的 "USBDCore_IRQHandler()" 函數。

表 9 USB 匯流排事件和 USB 核心層的相應函數

匯流排事件相應函數描述

當 USB 匯流排重定事件發生，USB 核心將

重置所有狀態到預設值，打開 USB IP 電源

和最初的控制端點，並使能 USB 中斷。上

述操作完成後，控制端點將通過 USB 位址

0 準備接收/發送資料。全局狀態變數和

USB 設備的 IP 控制暫存器也被重置。

重置 _USBDCore_Reset(pCore);

當 USB 匯流排恢復事件發生，USB 核心將

打開 IP 電源，恢復當前的狀態變數（恢復

到進入暫停模式之前的值）。

恢復 _USBDCore_Resume(pCore);

當 USB 匯流排暫停事件發生，USB 核心將

改變當前的狀態變數為"暫停"。它使 USB

核心執行應用層的暫停回調函數，讓晶片

進入低功耗模式。

暫停 _USBDCore_Suspend(pCore);

當 SETUP 資料已準備就緒，USB 核心使用

此函數來處理 SETUP 資料。此函數需要考

慮 USB 標準、類別和供應商的要求。

控制端點 SETUP 包準備就緒 _USBDCore_Setup(pCore);

當最後一筆控制 IN 資料傳輸完畢後，USB

核心使用此函數來處理下一筆 IN 資料。此

函數必要時也需要考慮零長度包（ZLP）。

控制端點 IN 資料傳輸 _USBDCore_ControlIN (pCore);

控制端點 OUT 資料準備就緒_USBDCore_ControlOUT

(pCore);

當接收到控制 OUT 資料，USB 核心使用此

函數來處理 OUT 資料。

端點 n IN 資料傳輸

端點 n OUT 數據準備就緒

pCore->Class.CallBack_EPTn

[EPTn](EPTn);

回調函數需考慮端點 IN 或 OUT 的資料傳

輸，通過"USBDClass_Init()"函數設定。

9


10

USB 核心層提供了 "回調" 能夠處理一些在已知的情況下需要涉及到應用層的匯流排事件。例

如，幀起始、獲取類別描述符、設定介面或類別請求，可能需要除 USB 核心層外的操作。在類

別初始化階段，用戶應指定回調函數給 USB 核心層。然而，在某些特定情況下，用戶可能需要

修改 USB 核心層，以適應類別應用的要求。但不得經常發生。

USB 核心 API

USB 核心層為應用層提供以下 API 實現類別應用功能。對於統一的用戶介面，USB 核心 API

函數並沒有真的存在，它只是一個重新定義 API 名稱的 API 巨集（USB 外設驅動層）。請注意，

應用層應避免直接使用除 USB 核心 API 外的其他任何函數。因此，它可以保持每一層的獨立

性，提高模組更換的可能性。

表 10 USB 核心 API

API 名稱描述

初始化和系統 API

void USBDCore_Init(USBDCore_TypeDef *pCore); USB 核心初始化。

void USBDCore_IRQHandler(USBDCore_TypeDef *pCore); USB 核心的中斷服務程式。

void USBDCore_MainRoutine(USBDCore_TypeDef *pCore); USB 核心的應用主程式。

u32 USBDCore_IsSuspend(USBDCore_TypeDef *pCore); 返回暫停狀態。

u32 USBDCore_GetRemoteWakeUpFeature(USBDCore_TypeDef *pCore); 返回遠端喚醒狀態，通過 SET FEATURE

標準命令設定。

void USBDCore_TriggerRemoteWakeup(void); 打開 USB 電源，遠端喚醒主機。

端點 API

void USBDCore_EPTReset(USBD_EPTn_Enum EPTn); 端點重置到默認狀態。

u32 USBDCore_EPTGetBufferLen(USBD_EPTn_Enum EPTn); 獲取端點緩衝區長度。

u32 USBDCore_EPTGetTransferCount(USBD_EPTn_Enum EPTn,

USBD_TCR_Enum type); 獲取端點傳輸計數。

void USBDCore_EPTSetSTALL(USBD_EPTn_Enum EPTn); 設置端點暫停狀態。

Void USBDCore_EPTWaitSTALLSent(USBD_EPTn_Enum EPTn); 等待 STALL 發送。

Void USBDCore_EPTClearDataToggle(USBD_EPTn_Enum EPTn); 清除端點暫停狀態。

端點數據 API

u32 USBDCore_EPTWriteINData(USBD_EPTn_Enum EPTn, u32

*pFrom, u32 len); 寫 IN 數據到 USB 緩衝區。

u32 USBDCore_EPTReadOUTData(USBD_EPTn_Enum EPTn, u32

*pTo, u32 len);

從端點緩衝區讀 OUT 資料，清除 NAK

位元。

u32 USBDCore_EPTReadMemory(USBD_EPTn_Enum EPTn, u32

*pTo, u32 len); 從端點緩衝區讀 OUT 數據。


應用層

應用層包括用於配置、描述符、類別請求和端點資料處理的幾個檔案。USB 類別的主要功能設

在這一層。用戶可以在應用層修改檔案，以適應應用需求。下表顯示了應用層的模組和檔案。

每個模組的詳細資訊將在本節稍後討論。本節還提供如何配置以及最初的 USB 核心和描述符的

詳細資訊。

表 11 應用層模組

模組描述

ht32fxxxx_usbdconf.h USB 設備的配置檔案，包括與 USB 設備 IP 相關的中斷和端點設定。

USB 設備的描述符，包括設備、配置和字串。此模組提供了初始化函數用於設

定描述符的資料指標，為 USB 核心獲取描述符請求。 ht32_usbd_descriptor (.c, .h)

ht32f_usbd_class (.c, .h) 類別相關功能，包括初始化、主程式、類別標準請求、類別請求和端點資料處理。

配置檔（ht32fxxxx_usbdconf.h）

配置檔用於配置 HT32 USB 外設，包括全局中斷使能位元和端點設定。下圖為 KEIL uVision IDE

的配置嚮導視窗。用戶還可以通過直接編輯 "ht32fxxxx_usbdconf.h" 檔案改變設定。

注意，帶 "（Default）" 旗標的專案在一般情況下不得被禁用。

圖 3 Keil uVision IDE 的配置嚮導

11


下列步驟顯示了配置流程和注意事項。

對於 USB 中斷設定（UIER），應確保帶 "（Default）" 旗標的專案使能。根據類別/應用的

端點使用，使能端點 n 中斷（EPnIE）。

根據 USB 緩衝記憶體的使用情況，配置控制端點 0 的緩衝區長度為 8、16、32 或 64 位元組。

確保端點 0 的 ODRXIE、IDTXIE 和 SDRXIE 中斷使能位元開啟。USB 核心層依靠這些匯流

排事件來處理 USB 控制傳輸。

根據類別/應用的端點使用來配置端點 n 設定。下表顯示了應要注意的設定。

表 12 端點設定

設定描述

端點地址一般情況下不需要修改。

端點使能端點使用前應打開。

端點傳輸類型端點 1 ~ 3：批量或中斷

端點 4 ~ 7：等時，批量或中斷。

端點方向 IN 或 OUT。

端點緩衝區長度

中斷：1 ~ 64 位元組

批量：8, 16, 32 或 64 位元組

等時：1 ~ 1023 位元組。（注意：因為 USB 緩衝區至少保留 8 + 8 位元組用於 SETUP 資料

和端點 0，所以等時端點的實際最大緩衝區長度為 1008 位元組）

對於 IN 端點，韌體通常使用 IN 資料包傳送中斷使能（IDTXIE）來處理資料傳輸程式。

對於 OUT 端點，韌體通常使用 OUT 資料包接收中斷使能（ODRXIE）來處理資料傳輸程

式。其他中斷可用於調試或其他用途。更多詳細資訊，請參考 HT32Fxxxx 用戶手冊。

端點中斷使能

描述符設定

設備、配置、介面、端點和字串描述符都包含在應用層的 "ht32_usbd_descriptor.c " 文件中。用

戶可根據類別/應用的要求修改它們。下圖顯示了設備 KEIL uVision IDE 的配置嚮導和配置描述

符。對於其他 IDE 或描述符，用戶可以通過直接編輯 "ht32_usbd_descriptor.c" 檔案修改描述符。

圖 4 設備 Keil uVision IDE 的配置嚮導和配置描述符

12


初始化流程

下面的源代碼，給出了一個如何初始化 USB 描述符、類別和核心的例子。初始化流程完成後，

應用程式應呼叫 "USBDCore_MainRoutine(&gUSBCore)" 函數定期處理暫停回調函數和類別主

程式。

__ALIGN4 USBDCore_TypeDef gUSBCore; /* USB 核心記憶體，必須 4 位元組對齊 */ USBD_Driver_TypeDef gUSBDriver; /* USB 驅動記憶體 */ void USB_Configuration(void) { gUSBCore.pDriver = (u32 *)&gUSBDriver; /* 初始化 USB 驅動的儲存指標 */ gUSBCore.Power.CallBack_Suspend.func = Suspend; /* 安裝暫停回調函數到 USB 核心 */ USBDDesc_Init(&gUSBCore.Device.Desc); /* 初始化描述符的儲存指標 */ USBDClass_Init(&gUSBCore.Class); /* 初始化 USB 類別層 */ USBDCore_Init(&gUSBCore); /* 初始化 USB 核心層 */ NVIC_EnableIRQ(USB_IRQn); /* 使能 USB 設備中斷 */ } int main(void) { ... USB_Configuration(); /* USB 相關配置 */ /* 連接 USB，並等待枚舉完成 */ HT32F_DVB_USBConnect(); while(gUSBCore.Info.CurrentStatus != USB_STATE_CONFIGURED); ... while (1) { ... USBDCore_MainRoutine(&gUSBCore); /* USB 核心主程式 */ ... } ... }

類別實現

本節提供了類別實現的詳細資訊，包括類別請求、端點資料處理和類別主程式。本節的目的是

描述如何修改應用層，以適應 USB 類別請求。

類別的初始化

類別的初始化安裝相關回調函數/參數，包括：

類別主程式

幀起始

標準獲取描述符請求類別

標準設定介面請求

類別請求

端點處理程式

初始化函數 "USBDClass_Init" 可以在每個類別範例代碼的 "ht32_usbd_class.c" 文件中找

到。用戶可以按照以下範例來安裝其類別/應用的回調函數。

13


圖 5 類別的初始化範例

類別請求

當 USB 核心收到 SETUP 傳輸和解碼類別請求，USB 核心將執行類別請求回調函數

（CallBack_ClassRequest）。USB 核心類別請求通過 "USBDCore_Device_TypeDef" 結構點

作為回調函數的參數。更多資訊請參考 "表 8 USB 核心的變數結構"。

"ht32_usbd_class.c" 檔案中的 "USBDClass_Request()" 函數，給出了一個如何處理類別請求

的例子。用戶可以根據其要求實現自己的類別請求函數。類別請求函數應設定作為

"USBDClass_Init" 函數的回調函數，如下所示。

static void USBDClass_Request(USBDCore_Device_TypeDef *pDev); void USBDClass_Init(USBDCore_Class_TypeDef *pClass) { ... pClass->CallBack_ClassRequest = USBDClass_Request; ... }

端點處理程式

對於 USB 的特性，韌體通常配置 USB 設備控制器在 IN 資料包發送或收到 OUT 資料包時，

發出端點中斷。當端點中斷發生，USB 核心將檢查中斷旗標，並執行相應的端點處理程式。

端點處理程式負責端點資料處理。以下 USB 核心函數用於端點資料處理。

表 13 USB 核心資料處理 API

API 名稱描述

USBDCore_EPTWriteINData 寫 IN 數據到 USB 緩衝區。

USBDCore_EPTReadOUTData 從端點緩衝區讀 OUT 資料，清除 NAK 位元。

USBDCore_EPTReadMemory 從端點緩衝區讀 OUT 數據。

14


15

韌體可處理端點處理程式的內部資料，或只設定一個軟體旗標位元，以通知應用 IN/OUT 資

料。注意微控制器在中斷模式下執行端點處理程式，將根據優先順序阻止其他中斷。如果

USB 資料很大，我們應當防止在端點處理程式內部處理資料。用戶應當設定端點處理程式

作為 "USBDClass_Init" 函數的回調函數，如下所示。

static void USBDClass_Request(USBDCore_Device_TypeDef *pDev); void USBDClass_Init(USBDCore_Class_TypeDef *pClass) { ... pClass->CallBack_EPTn[1] = USBDClass_Endpoint1; pClass->CallBack_EPTn[2] = USBDClass_Endpoint2; //pClass->CallBack_EPTn[3] = USBDClass_Endpoint3; //pClass->CallBack_EPTn[4] = USBDClass_Endpoint4; //pClass->CallBack_EPTn[5] = USBDClass_Endpoint5; //pClass->CallBack_EPTn[6] = USBDClass_Endpoint6; //pClass->CallBack_EPTn[7] = USBDClass_Endpoint7; ...

}

類別主程式

如果韌體在 USB ISR 期間花了太多時間在端點資料處理過程上，那麼一些優先順序較低的

中斷將不能被 MCU 回應。它可能不適合一些需要特定回應時間的外設。因此，我們建議在

端點處理程式外部來處理這些低優先順序的端點資料。"USBDClass_MainRoutine()" 可以幫

助用戶實現。當端點中斷發生時，用戶可以將端點處理程式中的軟體旗標置高。USB ISR

返回後，檢查旗標位元，處理 "USBDClass_MainRoutine()" 函數中的 IN 或 OUT 資料。同

時，對於帶 DMA 控制器的微控制器，使用 DMA 來防止上述情況也是一個好辦法。當 DMA

傳輸完成時，可以觸發端點處理程式的 DMA，處理 "USBDClass_MainRoutine()" 函數中的

資料。

USB 核心將定期執行 "USBDClass_MainRoutine()" 函數。用戶應當設定它作為

"USBDClass_Init" 函數的回調函數。回調函數保留 "uPara" 參數為將來使用。更多資訊請

參考 "ht32_usbd_class.c" 文件。

static void USBDClass_MainRoutine(u32 uPara) void USBDClass_Init(USBDCore_Class_TypeDef *pClass) { ... pClass->CallBack_MainRoutine.func = USBDClass_MainRoutine; //pClass->CallBack_MainRoutine.uPara = (u32)NULL; ...

}


使用HT32 USB設備的類別範例代碼

本章介紹類別範例代碼的基本用法，包括項目、Windows 驅動器和 USB 核心調試模式。

專案檔

類別範例代碼提供 KEIL MDK-ARM、IAR EWARM 和 CooCox CoIDE 的項目檔，包括：

USBD/CLASS_EXAMPLE/CoIDE_EXAMPLENAME/CoIDE_EXAMPLENAME.cob

USBD/CLASS_EXAMPLE/EWARM/Project.eww

USBD/CLASS_EXAMPLE/MDK_ARM/Project.uvproj

USBD/CLASS_EXAMPLE/SourceryG++Lite/Project.uvproj

圖 6 類別範例代碼的專案檔

可以打開每個類別範例代碼的專案檔的首選 IDE 在開發板上進行測試。請參考每個 IDE 快速入

門指南的編譯、下載和調試操作。

Windows的USB驅動

所有的類別範例代碼（除了虛擬 COM 埠範例）使用 Windows 內置驅動器連接到你的電腦。你不

必為它們指定驅動器。虛擬 COM 埠範例使用由 Holtek 所提供的 "HT32_VCP.inf" 檔，告訴

Windows應該載入哪個驅動器。當連接虛擬COM埠範例到Windows時，需要指定 "HT32_VCP.inf"

的路徑。"HT32_VCP.inf" 位元於 "{Firmware Library Path}\xxxx_CMSIS_FWLib\example\USBD\

Virtual_COM\"。

所有的類別範例代碼使用相同的 VID 和 PID，0x04D9 和 0x8008。當使用相同的 VID 和 PID 連接

不同的類別範例代碼到同一台電腦上，Windows 可能無法正確載入驅動器。同樣，如果修改描述

符，但保持相同的 VID 和 PID，上述情況也可能發生。Windows 設備管理器顯示 USB 設備 "故

障"。下面步驟顯示了如何解決 Windows XP 下的上述問題。在其他版本的 Windows 或其他作業

系統，你可能需要尋找相同的功能。

按控制面板系統對話方塊中 "硬體" 選項卡的按鈕，打開 "設備管理器"。

在列表中找出插入到電腦的 USB 設備（帶 "故障" 圖示）。

在設備上單擊右鍵，選擇 "卸載"，然後從電腦上拔下並重新連接。

Windows 自動重新安裝正確的 USB 設備驅動器。

16


USB核心調試模式

用於調試目的，可以通過設定 "USBDCORE_DEBUG" 的定義值為 1（在 ht32_usbd_core.h），

打開 USB 核心調試模式。根據韌體庫的重定向設定，USB 核心使用 printf 函數通過 UART 或

ITM 介面顯示調試資訊。需要注意的是 USB 核心調試模式會降低性能，在一定條件下可能會導

致 USB 出錯。在最終應用上應關閉 USB 調試模式。我們強烈建議當 USB 調試消息被重定向到

UART 介面時，關閉 "轉存 USB 調試資料（USBDCORE_DEBUG_DATA）" 選項。

圖 7 USB 核心調試模式設定

圖 8顯示了USB核心調試模式的輸出範例。

圖 8 USB 核心調試模式的輸出範例

17


人機週邊設備 (HID)

簡介

人機週邊設備（HID）是專為人類別控制電腦主機設計的。HID 使用報告的概念，通過控制或

中斷管道交換資料。由於大多數作業系統支援內置 HID 驅動器，我們可以使用 HID 類別的方

便方式與電腦交換資料，而無需執行任何作業系統的驅動程式。USB 設備 HID 的範例代碼顯示

了如何使用 HT32 USB 設備庫、枚舉、端點中斷傳輸和 HID 獲取/設定報告。這個例子只是說

明如何回送 HID 輸出報告給輸入報告以及設定特性報告回送給獲取特性報告。

使用HID範例代碼 HID 的範例代碼在 HT32 系列開發板實現 USB HID 類別。當範例代碼下載到開發板，USB 連

接到 PC，你可以在設備管理器中找到一個新的 HID 設備（VID = 0x04D9, PID = 0x8008），如下

圖所示。

圖 9 設備管理器的 HID 設備

18


HID 範例代碼還提供基於 PC 的展示 UI "HID_Demo_UI.exe"，顯示了 HID 設備如何與 PC 交換

資料。展示 UI 基於 Microsoft Virtual C++ 2005。HID 展示 UI 的源代碼位於 HID 範例代碼路徑

中的 "HID_Demo_UI_Src.zip" 文件中。用戶可以根據 HID 展示 UI 範例代碼開發定制基於 PC

的應用。

圖 10 基於 PC 的 HID 範例代碼的展示 UI

HID類別的實現

本節介紹 HID 類別的實現，包括 HID 報告描述符、端點配置、類別請求和資料傳輸。

HID 報告描述符

HID 報告描述符， "USB_HID_ReportDesc[]" 陣列位於 "ht32_usnd_class.c" 文件中，定義了 HID

報告的格式和目的。更多資訊，請參考 HID 規格書。USB 實施者論壇提供了一個名為 "HID

Descriptor Tool" 的工具可自動生成 HID 報告描述符。你可以使用這個工具生成 HID 報告描述

符，並保存為頭文件（*.H）。頭檔中報告描述符的陣列資料可以直接複製和粘貼到

"USB_HID_ReportDesc[]" 陣列。請注意，HID 報告描述符的長度定義（DESC_LEN_RPOT）

位於 "ht32_usbd_class.h" 文件中。當 HID 報告描述符的長度改變時，必須修改。

圖 11 HID 報告描述符的長度定義

19


20

端點配置

HID 的範例代碼使用三個端點用於控制和報告傳輸。下表顯示了端點的數量、方向和傳輸類型。

端點的詳細設定，可以在 "ht32xxxx_usbdconf.h" 文件中找到。

表 14 端點的 HID 範例代碼

端點號傳輸類型

端點 0 控制 IN 或 OUT

端點 1 IN 中斷

端點 2 OUT 中斷

端點 0（控制）：用於 USB 標準/類別請求。使用此端點進行設定報告和獲取報告的資料

傳輸。

端點 1（IN 中斷）：用於 HID 輸入報告的資料傳輸。

端點 2（OUT 中斷）：用於 HID 輸出報告的資料傳輸。

類別請求

USB HID 設備定義了六個類別專用請求。這些類別請求可以在 HID 範例代碼的

"ht32_usbd_class.c" 檔中執行。不是所有的命令都是必需的。下表顯示了所有已定義的 HID 類

別請求和在此範例代碼中其執行情況。

表 15 HID 類別請求

類別請求描述請求？執行？

獲取報告主機通過控制管道接收來自設備的輸入或特性報告。 Y Y

獲取空閒主機讀取當前閒置率。 N N

獲取協議主機讀取有效協定（啟動或報告）。 N(*) N

設定報告主機通過控制管道發送輸出或特性報告給設備。 N Y

設定空閒主機設定設備的閒置率以節省帶寬。 N N

設定協議主機切換設備的啟動或報告協定。 N(*) N

*注：啟動設備所需

資料傳輸

下表顯示了 HID 展示範例代碼的資料傳輸流程。更多詳細資訊，請參考端點處理程式和

“ht32_usbd_class.c”文件的類別主程式。

表 16 展示範例代碼的資料傳輸流程

主機設備動作

設定輸出報告端點 0（控制）

輸出報告（讀文件）端點 2（OUT）保存到 gOutputReportBuffer，並複製到 gInputReportBuffer

獲取輸入報告端點 0（控制）

輸入報告（寫文件）端點 1（IN）從 gInputReportBuffer 中傳輸資料

設定特性報告端點 0（控制）保存到 gFeatureReportBuffer

獲取特性報告端點 0（控制）從 gFeatureReportBuffer 中傳輸資料


大容量儲存

簡介

USB 設備大容量儲存的範例代碼顯示了如何使用 HT32 USB 設備庫、枚舉和端點批量傳輸。此

範例代碼使用僅批量傳輸（BOT）協定與 PC 主機通信。媒體訪問、SCSI（小型電腦系統介面）

塊命令、RAM 磁片和 SD 卡相關的功能也可以在此範例代碼中實現。此範例代碼能夠支援 RAM

磁片和 SD 卡。RAM 磁片的範例可以幫助用戶瞭解 USB 大容量儲存、BOT 方式和 SCSI 命令

的架構。RAM 磁片功能也是一個很好的起點，以創建自定義的資料交換應用。客戶的資料交換

可以利用大容量儲存的好處，如快速批量傳輸和大多數作業系統無需驅動。

使用大容量儲存範例代碼請參考 "使用 HT32 USB 設備的類別範例代碼" 章節，建立和下載大容量儲存的範例代碼到

HT32 系列開發板，插入 SD 卡，連接 USB 到電腦主機。當 USB 枚舉完成後，可以通過 Windows

檔資源管理訪問 RAM 磁片和 SD 卡。資料可以通過檔資源管理從 SD 卡讀取或寫入。可以用於

通過 PC 更新 SD 卡內容。

圖 12 Windows 中的 RAM 磁片和 SD 卡的大容量儲存範例代碼

RAM 磁片中有一個 "README.00TXT" 檔案，其中包含範例文本資料。你可以簡單地雙擊

打開這個檔案。它顯示了如何通過 RAM 磁片功能進行 PC 主機和 USB 設備之間的資料交換。

圖 13 "README.TXT" 的範例文本資料

21


大容量儲存類別的實現

大容量儲存範例實現了僅批量傳輸（BOT）協議、SCSI 塊命令（SBC-3 和 SPC-4）、RAM 磁片

和 SD 卡的相關功能。本節說明了上述功能的基本資訊。大容量儲存的類別範例代碼可以分為

三層，BOT 協議、SCSI 塊命令和媒體訪問。下表顯示了大容量儲存的範例代碼模組。

表 17 大容量儲存的範例代碼模組

模組描述

ht32f_usbd_class (.c, .h) 作為 USB 核心和 BOT 協議的中間層。它負責初始化、資料傳輸和類別請求。

usb_bulk_only_transport (.c, . h) BOT 協定命令處理程式和功能。

usb_scsi_block_command (.c, .h) SCSI 塊命令處理程式和功能。

usb_scsi.h SCSI 協定的相關定義、結構和常數。

MEDIA_disk (.c, .h) 媒體訪問的相關功能。

範例代碼支援透明的 SCSI 命令集（0x06，由配置描述符的 "bInterfaceSubClass" 子類別代碼設

定）和 USB 大容量儲存類別僅批量傳輸（0x50 BBB 協定，由配置描述符的"bInterfaceProtocol"

設定）。以下各節提供了 BOT 和 SCSI 命令的簡要說明。更多資訊請參考各個規格書。

僅批量傳輸（BOT）

僅批量傳輸協定使用批量 IN 和 OUT 端點來傳輸命令塊包（CBW）、命令狀態包（CSW）和

IN/OUT 資料。BOT 協定的傳輸不需要控制和中斷管道。大容量儲存 BOT 的執行分為三個階段，

命令階段（CBW），可選資料階段（IN 或 OUT）和狀態階段（CSW）。BOT 流程如下。

圖 14 大容量儲存 BOT 協定流程

22


以下兩圖顯示了 CBW 和 CSW 的格式。更多詳細資訊，請參考僅批量傳輸規格書。

圖 15 命令塊包的格式

圖 16 命令狀態包的格式

BOT CBW 包括設備要執行命令塊的 CBWCB 領域。在這個範例代碼中，CBWCB 執行 SCSI SBC-3

和 SPC-4 命令將被傳遞到 SCSI 層，在 "usb_bulk_only_transport.c" 檔案中執行所有必需的函數。

下表顯示了函數及其說明。

表 18 BOT 層的 API

函數描述

void BOT_Init(void);

BOT 初始化函數。包括 CSW 領域、SCSI 層和媒體。

void BOT_Reset(void);

BOT 重定函數，用於僅批量傳輸大容量儲存重定類別請求。

uc8 *BOT_GetMaxLUNAddress(void);

獲取最大邏輯單元號（LUN）。

void BOT_OUTProcess(void);

此函數用於處理 USB OUT 資料。此函數應在端點處理程式或類別主程式中執行。

void BOT_INProcess(void);

此函數用於處理 USB IN 資料。此函數應在端點處理程式或類別主程式中執行。

u32 BOT_CheckCBWParameter(BOT_Dir_Enum DeviceDirection, u32 uDeviceLength);

此函數用於檢查 CBW 參數是否有效（Cass1 ~ Cass13）。

void BOT_WriteINData(u8 *pBuffer, u32 uLen, BOT_State_Enum status);

寫 BOT IN 資料和更新 BOT 狀態/CSW。

void BOT_ReadOUTData(u8 *pBuffer, u32 uLen);

讀 BOT OUT 資料和更新 CSW。

void BOT_SendCSW(BOT_CSW_STATUS_Enum status);

此函數用於向主機發送 CSW。

void BOT_ErrorHandler(BOT_STALL_Enum StallEPT, BOT_CSW_STATUS_Enum CSWstatus);

此函數用於處理錯誤狀態，包括端點 STALL 和發送 CSW。

23


小型電腦系統介面（SCSI）命令

小型電腦系統介面（SCSI）命令為 SCSI 設備和主機之間提供有效的通信。大容量儲存的範例代碼

實現了一部分 SBC-3 和 SPC-4 命令。更多資訊請參考 SBC-3 和 SPC-4 規格。下表顯示了大容量儲

存範例代碼所支援的命令。這些命令在 "usb_scsi_block_command.c" 檔案實現。BOT 層將傳送命令

塊（CB）給 SCSI 層的 SBC_CMDHandler()函數。該函數查找命令的操作碼，並執行 SCSI 命令的相

應函數。

表 19 大容量儲存所支援的 SCSI 命令集

命令名稱操作碼描述

TEST UNIT READY 0x00 檢查邏輯單元是否準備就緒。

設備伺服器發送參數資料（包括感測器資料）到應用用

戶端。 REQUEST SENSE 0x03

INQUIRY 0x12 向應用用戶端發送邏輯單元和 SCSI 目標設備資訊。

MODE SENSE (6) 0x1A 向應用用戶端報告參數。

READ FORMAT CAPACITY 0x23 主機請求報告當前媒體的可格式化能力。

PREVENT ALLOW MEDIUM REMOVAL 0x1E 請求邏輯單元使能或除能移除媒體。

此命令請求設備伺服器傳送 8 個位元組的參數資料到資

料登錄緩衝區，該資料描述直接訪問塊設備的容量和媒

體格式。

READ CAPACITY (10) 0x25

此命令請求設備伺服器讀取指定的邏輯塊，並將它們傳

送到資料登錄緩衝區。 READ (10) 0x28

此命令請求設備伺服器從資料輸出緩衝區傳送指定的邏

輯塊，並將它們寫入媒體。 WRITE (10) 0x2A

媒體訪問

媒體訪問的相關函數位於 "ram_disk.c" 或 "sd_disk.c" 文件中。 BOT 層提供

"BOT_Media_TypeDef" 結構用於媒體資訊。磁片資訊和訪問函數被該結構定義為總體變數，

"usb_bulk_inly_transport.c" 文件中的 "gMediaInfo"。下表顯示了 "gMediaInfo" 變數的成員。

表 20 "BOT_Media_TypeDef" 結構成員

成員描述

媒體唯一的 ID。此 ID 用於識別不同媒體上支持多個 LUN 的單一媒體驅動

器。SCSI 層會發送這個 ID 給媒體驅動器。 u32 uId;

BOT_MediaSize_Typedef Size; 尺寸資訊。包括塊數，塊大小和媒體大小。

pInit Init; 媒體的初始化函數。

pReadFun Read; 媒體的讀取函數。

pWriteFun Write; 媒體的寫入函數。

pGetStatusFun GetStatus; SCSI 層使用此函數來測試媒體是否準備就緒。

u8 *pSBC_InquiryData; 查詢命令的資料指標。

u8 *pSBC_SenseData; 請求檢測資料命令的資料指標。

24


用戶應當按照上面的格式執行其他媒體的訪問函數。BOT 和 SCSI 層通過上述資訊和函數訪

問特定的媒介。下表給出了 RAM 磁片訪問函數的例子。

表 21 RAM 磁片訪問函數範例

函數描述

u32 RAMDISK_Read(u32 uId, u8 **pBuffer,

u32 uAddress, u32 uLength); 讀取媒體參數。SCSI 讀取命令使用此函數讀取媒體。

u32 RAMDISK_Write(u32 uId, u8 *pBuffer,

u32 uAddress, u32 uLength); 寫入媒體參數。SCSI 寫入命令使用此函數寫入媒體。

此函數用於報告媒體狀態。SCSI 的 "TEST UNIT READY" 命令使

用此函數來測試媒體狀態。

u32 RAMDISK_GetStatus(u32 uId,

BOT_MediaSize_Typedef *pSizeInfo);

端點配置

大容量儲存範例代碼使用三個端點用於控制和批量傳輸。下表顯示了端點的數量、方向和傳輸

類型。端點的詳細設定，可以在 "ht32xxxx_usbdconf.h" 文件中找到。

表 22 端點的 HID 範例代碼



端點 1 批量 IN

端點 2 批量 OUT

端點 0（控制）：用於 USB 標準/類別請求。

端點 1（批量 IN）：用於大容量儲存 BOT 協定的 CSW 傳輸。

端點 2（批量 OUT）：用於大容量儲存 BOT 協定的 CBW 傳輸。

類別請求

大容量儲存 BOT 協定定義了兩個類別專用請求。這些類別請求可以在大容量儲存範例代碼的

"ht32_usbd_class.c" 檔案中執行。下表顯示了所有已定義的類別請求及其描述。

表 23 大容量儲存 BOT 的類別請求

類別請求描述

僅批量大容量儲存重定該請求用於重定大容量儲存設備及其相應介面。

該請求用於確定設備所支援的邏輯單元數量。LUN 應從 LUN 0 開始

到 15（最大）連續編號。獲取最大 LUN

25


26

配置

範例代碼支援多個 LUN（邏輯單元號）功能，通過單個 USB 大容量儲存設備可訪問不同的媒

體。此範例代碼能夠支援 RAM 磁片和 SD 卡。 RAM 磁片和 SD 卡功能由

"usb_bulk_only_transport.h" 文件使能或除能。同一個檔的 LUN 數量也可以改變。

圖 17 總 LUN、媒體和訪問 LED 的配置

RAM 磁片的 FAT12 範例資料顯示了 PC 主機上的磁片內容和資訊。FAT 表被定義在

"ram_disk.c" 文件中名為 "guMemory0" 和 "guMemory1" 的變數中。檔案名稱、檔案內容、

磁片標籤等都可以在 FAT 表中找到和修改。更多資訊請參考 FAT12 規格。


USB視頻

簡介

此章節利用 HT32 系列開發板展示 USB 視頻設備範例。送出 320x240 單色變化影像至 PC 顯示，

展示 USB 等時傳輸功能。USB 視頻類別（UVC）裝置為 USB 設備類別所定義的通用視頻影像

裝置，包含動態影像裝置，如數位攝影機、攝像頭等裝置。此裝置連接至 PC，不需要自行撰寫

任何驅動程式，即插即用。

使用USB視頻範例代碼此範例使用HT32 系列開發板並將其撰寫為USB UVC Device。利用PC上通用影像程式開啟裝

置。UVC裝置即會傳送影像資料至PC，完成等時資料傳輸功能。連接至PC後可在設備管理器

下看到裝置，如圖 18 。通過任何 PC 端的影像程式軟體開啟，例如 AMCAP

（http://noeld.com/programs.asp?cat=video）。以AMCAP為例，在PC端安裝完此影像程式軟體。

開啟此軟體，在Device中，選擇USB-UVC Demo。並點選Option → Preview，流程如圖 19。在

此範例中，Preview勾選後，USB即開始上傳資料，傳輸單色變化影像結果如圖 20。

圖 18 設備管理器的 USB 視頻設備

圖 19 AMCAP 中 USB 視頻設備選擇

27

http://noeld.com/programs.asp?cat=video


圖 20 USB 視頻設備單色變化影像

USB視頻類別的實現

USB 視頻範例程式採用 USB 視頻設備類別規格中定義影像格式為未壓縮的有效載荷掛載 UVC

裝置，並實現等時資料傳輸。關於更多影像格式定義請參考 "USB Video Payload" 相關規格。

端點配置

UVC 設備使用三個端點進行資料傳輸，如表 24。

表 24 USB 視頻範例代碼的端點



端點 1 IN 中斷

端點 4 等時 IN

端點 0（控制）：USB 枚舉資料傳輸和回應 USB 請求。

端點 1（中斷）：中斷端點用於狀態返回。此端點是可選的，但在一定條件下可能是強制的。

端點 4（等時）：主要作為影像資料傳輸，將有效載荷頭及有效載荷資料傳送至 PC。

類別請求

為了實現 UVC 裝置，設備需支援 USB 視頻類別中所定義的 USB 類別請求。如表 25。這些函

數定義在 "ht32_usb_class.c" 文件中，如需更詳細瞭解，請參考 "USB Device Class Definition for

Video Devices" 規格書的章節。

表 25 UVC 類別請求

類別請求描述

GET_CUR 返回當前狀態。

GET_MIN 返回最小值

GET_MAX 返回最大值

GET_RES 返回解析度

GET_DEF 返回預設值

GET_LEN 返回長度

GET_INFO 查詢功能和狀態

SET_CUR 設定當前狀態

28


29

配置

用戶可針對 UVC 的範例程式進行修改。此範例程式提供用戶常用變數以及等時資料傳輸功能，

方便用戶依照需求進行修改。

變更影像尺寸大小，如表 26：

表 26 變更影像尺寸

檔案名定義名稱描述

DESC_IMAGE_WIDTH 影像寬度 ht32_usbd_class.h

DESC_IMAGE_HEIGHT 影像高度

等時資料傳輸功能

void USBDClass_Endpoint4(USBD_EPTn_Enum EPTn)

用戶自行將需要傳輸資料的程式內容撰寫於此，即可輕易實現通過 USB 等時傳輸資料。

此函數位於 ht32_usbd_class.c 文件中。

USB 相關硬體配置

使用者可以在 ht32fxxxx_usbdconf.h 檔案中修改 USB 相關配置，如圖 21。另外，USB1.1

規範中，定義等時傳輸速率最大為 1023 位元組/ms，而 UVC 裝置在 1ms 中所能傳送的資

料大小為端點緩衝區所設定長度，使用者在修改上需特別注意。

圖 21 USB 端點的配置（ht32fxxxx_usbdconf.h）


虛擬COM埠

簡介

此章節利用 HT32 系列開發板展示 USB 虛擬 COM 埠（VCP）範例。執行簡單的資料傳輸 loopback

行為，展示 USB 批量 IN/OUT 功能。USB 是連接電腦系統與週邊裝置的標準技術規範，但在

電腦剛問世時，外接式裝置的傳輸大多通過 COM 埠傳輸，現今仍有許多軟體與週邊使用。USB

提供標準的類別以完成 COM 埠功能，大幅減少軟體重新開發的時間，並且提高傳輸速度。USB

VCP Demo 提供 HT32 系列 IC 的韌體範例以及 PC 驅動器。以下章節將會說明如何使用此範例。

使用虛擬COM埠範例代碼此範例使用 HT32 系列開發板並將其撰寫為 USB VCP Class Device。在 PC 上使用 Hyper Terminal

傳送資料至 USB VCP Class Device（HT32 系列開發板），HT32 系列開發板接收到 USB 資料並

回傳至 Hyper Terminal，完成資料 Loopback 行為。發展環境示意如圖 22。

USB

圖 22 虛擬 COM 埠範例代碼的發展環境

在第一次執行 USB VCP Demo 時，將 HT32 系列開發板與 PC 連接時需要安裝程式，此時搜

尋 USB VCP Demo 程式中的 HT32_VCP.inf 並且安裝。安裝完成後，在設備管理器中可以看

到新增的 Holtek USB 虛擬 COM 埠，代表安裝完成，如圖所示。

圖 23 設備管理器的 VCP 設備

30


31

虛擬COM埠類別的實現

VCP 範例程式使用 USB 通信設備類別（CDC）規格中定義抽象控制模式實現通用的 COM 埠

設備。

端點配置

虛擬 COM 埠設備使用四個端點進行資料傳輸。

端點 0（控制 IN/OUT）：USB 枚舉資料傳輸和回應 USB 標準請求。

端點 2（IN 中斷）：主要傳送通知請求，在此範例中並無傳輸任何資料。

端點 3（批量 OUT）：接收 PC 送出 COM 埠資料。

端點 1（批量 IN）：傳送 COM 埠資料至 PC。

類別請求

在 USB 通信設備類別（CDC）的抽象控制模式中定義虛擬 COM 埠設備必要的特殊類別請求。

SET_LINE_CODING：此命令用於配置串口參數，包含比特率、停止位元的數目、奇偶校

驗和資料位元數。

GET_LINE_CODING：此命令用於請求串口參數，包含比特率、停止位元的數目、奇偶校

驗和資料位元數。

SET_CONTROL_LINE_STATE：此命令用於設定 RS-232 信號 RTS 和 DTR。

ht32 系列微控制器 usb 設備開發工具包 - holtek · ht32 系列的 usb...

Documents