CMSIS-Driver: Update USB Host Driver API 2.4.0

ARM-software · May 13, 2024 · bf65f34 · bf65f34
1 parent 86f0663
commit bf65f34
Show file tree

Hide file tree

Showing 8 changed files with 44 additions and 225 deletions.
diff --git a/ARM.CMSIS.pdsc b/ARM.CMSIS.pdsc
@@ -19,6 +19,8 @@
         - Added support for Cortex-M52
         - Added deprecated CoreDebug symbols for CMSIS 5 compatibility
         - Added define CMSIS_DISABLE_DEPRECATED to hide deprecated symbols
+      CMSIS-Driver: 2.10.0
+        - Updated USB Host Interface API 2.4.0 (deprecated API for OHCI/EHCI Host Controller Interface (HCI))
     </release>
     <release version="5.9.0" date="2022-05-02">
       CMSIS-Core(M): 5.6.0
@@ -524,7 +526,7 @@
         <file category="header" name="CMSIS/Driver/Include/Driver_USBD.h" />
       </files>
     </api>
-    <api Cclass="CMSIS Driver" Cgroup="USB Host" Capiversion="2.3.0" exclusive="0">
+    <api Cclass="CMSIS Driver" Cgroup="USB Host" Capiversion="2.4.0" exclusive="0">
       <description>USB Host Driver API for Cortex-M</description>
       <files>
         <file category="doc" name="CMSIS/Documentation/html/Driver/group__usbh__interface__gr.html" />
@@ -782,7 +784,7 @@
         <file category="sourceC" attr="template" name="CMSIS/Driver/DriverTemplates/Driver_USBD.c" select="USB Device Driver"/>
       </files>
     </component>
-    <component Cclass="CMSIS Driver" Cgroup="USB Host" Csub="Custom" Cversion="1.0.0" Capiversion="2.3.0" custom="1">
+    <component Cclass="CMSIS Driver" Cgroup="USB Host" Csub="Custom" Cversion="1.0.0" Capiversion="2.4.0" custom="1">
       <description>Access to #include Driver_USBH.h file and code template for custom implementation</description>
       <files>
         <file category="header" name="CMSIS/Driver/Include/Driver_USBH.h" />

diff --git a/CMSIS/Documentation/Doxygen/Driver/Driver.dxy.in b/CMSIS/Documentation/Doxygen/Driver/Driver.dxy.in
@@ -47,7 +47,7 @@ PROJECT_NAME           = "CMSIS-Driver"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "Version 2.9.0"
+PROJECT_NUMBER         = "Version 2.10.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

diff --git a/CMSIS/Documentation/Doxygen/Driver/src/Driver_USBH.c b/CMSIS/Documentation/Doxygen/Driver/src/Driver_USBH.c
@@ -1,20 +1,13 @@
 /**
-\defgroup usbh_interface_gr USB Host Interface
-\ingroup usb_interface_gr
-\brief  Driver API for USB Host Peripheral (%Driver_USBH.h)
-*/
-
-/**
-\defgroup usbh_host_gr USB Host
-\ingroup usbh_interface_gr
-\brief  Driver API for USB Host
-
+\defgroup   usbh_interface_gr USB Host Interface
+\ingroup    usb_interface_gr
+\brief      Driver API for USB Host Peripheral (%Driver_USBH.h)
 @{
 */
 
 /** 
-\struct ARM_DRIVER_USBH
-\details 
+\struct     ARM_DRIVER_USBH
+\details
 The functions of the USB Host driver are accessed by function pointers. Refer to \ref DriverFunctions for 
 overview information.
 
@@ -31,7 +24,7 @@ The default is \token{0}, which connects a middleware to the first instance of a
 *****************************************************************************************************************/
 
 /**
-\struct ARM_USBH_CAPABILITIES 
+\struct     ARM_USBH_CAPABILITIES 
 \details  
 A USB Host driver can be implemented with different capabilities.
 The data fields of this structure encode the capabilities implemented by this driver.
@@ -44,7 +37,7 @@ The data fields of this structure encode the capabilities implemented by this dr
 
 /**
 \struct     ARM_USBH_PORT_STATE 
-\details  
+\details
 This structure stores information about the state of the USB Host Port. The data fields encode whether a device 
 is connected to the port, if port overcurrent is detected, and the port speed.
 
@@ -175,7 +168,7 @@ ARM_DRIVER_VERSION ARM_USBH_GetVersion (void)  {
   return { 0, 0 };
 }
 /**
-\fn       ARM_DRIVER_VERSION ARM_USBH_GetVersion (void)
+\fn     ARM_DRIVER_VERSION ARM_USBH_GetVersion (void)
 \details
 The function \b ARM_USBH_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
  - API version is the version of the CMSIS-Driver specification used to implement this driver.
@@ -490,192 +483,4 @@ Parameter \em event                       | Bit| Description
 /**
 @}
 */ 
-
-
-
-/**
-\defgroup usbh_hci_gr USB OHCI/EHCI
-\ingroup usbh_interface_gr
-\brief  Driver API for USB OHCI/EHCI
-\details
-OHCI and EHCI compliant interfaces have memory mapped registers that are used to control the USB host.
-
-Only certain functionalities (interrupts, VBUS control, power control) require device specific interface which is provided through functions
-of the struct \ref ARM_DRIVER_USBH_HCI (functionality accessed with the struct \ref ARM_DRIVER_USBH is not needed). 
-@{
-*/
-
-/** 
-\struct ARM_DRIVER_USBH_HCI
-\details
-The functions of the USB Host HCI (OHCI/EHCI) driver are accessed by function pointers. Refer to \ref DriverFunctions for 
-overview information.
-
-Each instance of an USBH provides such an access struct. The instance is indicated by
-a postfix in the symbol name of the access struct, for example:
- - \b Driver_USBH0_HCI is the name of the access struct of the first instance (no. 0).
- - \b Driver_USBH1_HCI is the name of the access struct of the second instance (no. 1).
-
-
-A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_USBH<i>n</i>_HCI</b>.
-The default is \token{0}, which connects a middleware to the first instance of a driver.
-
-\note    The struct must remain unchanged.
-*/
-
-
-/**
-\struct ARM_USBH_HCI_CAPABILITIES
-\details
-A USB Host HCI (OHCI/EHCI) driver can be implemented with different capabilities.
-The data fields of this structure encode the capabilities implemented by this driver.
-
-<b>Returned by:</b>
-  - \ref ARM_USBH_HCI_GetCapabilities
-
-\note    The struct must remain unchanged.
-*****************************************************************************************************************/
-
-/**
-\typedef    ARM_USBH_HCI_Interrupt_t
-\details
-Provides the typedef for the interrupt handler \ref ARM_USBH_HCI_Interrupt.
-
-<b>Parameter for:</b>
-  - \ref ARM_USBH_HCI_Initialize
-*******************************************************************************************************************/
-
-
-//
-// Functions
-//
-
-ARM_DRIVER_VERSION ARM_USBH_HCI_GetVersion (void)  {
-  return { 0, 0 };
-}
-/**
-\fn       ARM_DRIVER_VERSION ARM_USBH_HCI_GetVersion (void)
-\details
-The function \b ARM_USBH_HCI_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
- - API version is the version of the CMSIS-Driver specification used to implement this driver.
- - Driver version is source code version of the actual driver implementation.
-
-Example:
-\code
-extern ARM_DRIVER_USBH Driver_USBH0_HCI;
-ARM_DRIVER_USBH *drv_info;
- 
-void setup_usbh (void)  {
-  ARM_DRIVER_VERSION  version;
- 
-  drv_info = &Driver_USBH0_HCI;  
-  version = drv_info->GetVersion ();
-  if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
-    // error handling
-    return;
-  }
-}
-\endcode
-*****************************************************************************************************************/
-
-ARM_USBH_HCI_CAPABILITIES ARM_USBH_HCI_GetCapabilities (void)  {
-  return { 0 };
-}
-/**
-\fn       ARM_USBH_HCI_CAPABILITIES ARM_USBH_HCI_GetCapabilities (void)
-\details
-The function \b ARM_USBH_HCI_GetCapabilities returns information about capabilities in this driver implementation.
-The data fields of the structure \ref ARM_USBH_HCI_CAPABILITIES encode various capabilities, for example
-available HUB ports.
- 
-Example:
-\code
-extern ARM_DRIVER_USBH_HCI Driver_USBH0_HCI;
-ARM_DRIVER_USBH_HCI *drv_info;
-  
-void read_capabilities (void)  {
-  ARM_USBH_HCI_CAPABILITIES drv_capabilities;
- 
-  drv_info = &Driver_USBH0_HCI;  
-  drv_capabilities = drv_info->GetCapabilities ();
-  // interrogate capabilities
- 
-}
-\endcode
-*****************************************************************************************************************/
-
-int32_t ARM_USBH_HCI_Initialize (ARM_USBH_HCI_Interrupt_t *cb_interrupt)  {
-  return ARM_DRIVER_OK;
-}
-/**
-\fn       int32_t ARM_USBH_HCI_Initialize (ARM_USBH_HCI_Interrupt_t *cb_interrupt)
-\details
-The function \b ARM_USBH_HCI_Initialize initializes the USB Host HCI (OHCI/EHCI) interface. 
-It is called when the middleware component starts operation.
-
-The function performs the following operations:
-  - Initializes the resources needed for the USBH interface.
-  - Registers the \ref ARM_USBH_HCI_Interrupt interrupt handler.
-
-The parameter \em cb_interrupt is a pointer to the interrupt routine of the OHCI/EHCI peripheral
-that needs to be registered. This function is called as ECHI Interrupt Service Handler.
-
-\b Example:
- - see \ref usbh_interface_gr - Driver Functions
-
-*****************************************************************************************************************/
-
-int32_t ARM_USBH_HCI_Uninitialize (void) {
-  return ARM_DRIVER_OK;
-}
-/**
-\fn       int32_t ARM_USBH_HCI_Uninitialize (void)
-\details
-The function \ref ARM_USBH_HCI_Uninitialize de-initializes the resources of USB Host HCI (OHCI/EHCI) interface.
-
-It is called when the middleware component stops operation and releases the software resources used by the interface.
-*****************************************************************************************************************/
-
-int32_t ARM_USBH_HCI_PowerControl (ARM_POWER_STATE state)  {
-  return ARM_DRIVER_OK;
-}
-/**
-\fn int32_t ARM_USBH_HCI_PowerControl (ARM_POWER_STATE state)
-\details
-The function \b ARM_USBH_HCI_PowerControl operates the power modes of the USB Host HCI (OHCI/EHCI) interface.  
-
-The parameter \em state sets the operation and can have the following values:
-  - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. 
-                          Can be called multiple times. If the peripheral is already in this mode the function performs 
-						  no operation and returns with \ref ARM_DRIVER_OK.
-  - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
-  - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
-      
-Refer to \ref CallSequence for more information.
-*****************************************************************************************************************/
-
-int32_t ARM_USBH_HCI_PortVbusOnOff (uint8_t port, bool vbus)  {
-  return ARM_DRIVER_OK;
-}
-/**
-\fn int32_t ARM_USBH_HCI_PortVbusOnOff (uint8_t port, bool vbus)
-\details
-The function \b  ARM_USBH_HCI_PortVbusOnOff controls the VBUS signal of the specified port.
-Most HCI complained USB Host controllers do not require this optional function.
-It is only required when a external VBUS interface (for example via I/O pin) is required.
-
-*****************************************************************************************************************/
-
-void ARM_USBH_HCI_Interrupt (void)  {
-  // function body
-}
-/**
-\fn void ARM_USBH_HCI_Interrupt (void)
-\details
-The function \b ARM_USBH_HCI_Interrupt is called from the USBH HCI Interrupt Handler.
-*****************************************************************************************************************/
-
-/**
-@}
-*/ 
 // End USBH Interface
diff --git a/CMSIS/Documentation/Doxygen/Driver/src/history.md b/CMSIS/Documentation/Doxygen/Driver/src/history.md
@@ -9,6 +9,13 @@ The table below provides information about the changes delivered with specific v
       <th>Version</th>
       <th>Description</th>
     </tr>
+    <tr>
+      <td>2.10.0</td>
+      <td>
+        - Updated USB Host API 2.4.0:
+          - deprecated: API for OHCI/EHCI Host Controller Interface (HCI)
+      </td>
+    </tr>
     <tr>
       <td>2.9.0</td>
       <td>

diff --git a/CMSIS/Documentation/Doxygen/General/src/revision_history.md b/CMSIS/Documentation/Doxygen/General/src/revision_history.md
@@ -15,6 +15,13 @@ Release history of other CMSIS components and tools can be found in their docume
       <th>Version</th>
       <th>Description</th>
     </tr>
+    <tr>
+      <td>6.1.0</td>
+      <td>
+       - CMSIS-Driver: 2.10.0
+         - Updated USB Host API 2.4.0
+      </td>
+    </tr>
     <tr>
       <td>6.0.0</td>
       <td>

diff --git a/CMSIS/Driver/DriverTemplates/Driver_USBH.c b/CMSIS/Driver/DriverTemplates/Driver_USBH.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013-2020 Arm Limited. All rights reserved.
+ * Copyright (c) 2013-2024 Arm Limited. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -29,7 +29,7 @@ static const ARM_DRIVER_VERSION usbh_driver_version = {
 };
 
 /* Driver Capabilities */
-static const ARM_USBH_CAPABILITIES usbd_driver_capabilities = {
+static const ARM_USBH_CAPABILITIES usbh_driver_capabilities = {
     0x0001, /* Root HUB available Ports Mask   */
     0,      /* Automatic SPLIT packet handling */
     0,      /* Signal Connect event */
@@ -49,7 +49,7 @@ static ARM_DRIVER_VERSION ARM_USBH_GetVersion(void)
 
 static ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities(void)
 {
-  return usbd_driver_capabilities;
+  return usbh_driver_capabilities;
 }
 
 static int32_t ARM_USBH_Initialize(ARM_USBH_SignalPortEvent_t cb_port_event,

diff --git a/CMSIS/Driver/Include/Driver_USBD.h b/CMSIS/Driver/Include/Driver_USBD.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013-2020 ARM Limited. All rights reserved.
+ * Copyright (c) 2013-2024 ARM Limited. All rights reserved.
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
- * $Date:        31. March 2020
+ * $Date:        13. May 2024
  * $Revision:    V2.3
  *
  * Project:      USB Device Driver definitions
@@ -85,8 +85,6 @@ typedef struct _ARM_USBD_STATE {
 #define ARM_USBD_EVENT_IN               (1UL << 2)      ///< IN Packet(s)
 
 
-#ifndef __DOXYGEN_MW__                  // exclude from middleware documentation
-
 // Function documentation
 /**
   \fn          ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
@@ -268,8 +266,6 @@ typedef struct _ARM_DRIVER_USBD {
   uint16_t              (*GetFrameNumber)            (void);                                              ///< Pointer to \ref ARM_USBD_GetFrameNumber : Get current USB Frame Number.
 } const ARM_DRIVER_USBD;
 
-#endif /* __DOXYGEN_MW__ */
-
 #ifdef  __cplusplus
 }
 #endif