diff --git a/ARM.CMSIS.pdsc b/ARM.CMSIS.pdsc index 4ac5578ad..7a37bedb3 100644 --- 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)) CMSIS-Core(M): 5.6.0 @@ -524,7 +526,7 @@ - + USB Host Driver API for Cortex-M @@ -782,7 +784,7 @@ - + Access to #include Driver_USBH.h file and code template for custom implementation diff --git a/CMSIS/Documentation/Doxygen/Driver/Driver.dxy.in b/CMSIS/Documentation/Doxygen/Driver/Driver.dxy.in index 2547739ee..ac329ed3b 100644 --- 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 index 73f968a7a..7e4f6259f 100644 --- 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 Driver_USBHn_HCI. -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. - -Returned by: - - \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. - -Parameter for: - - \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 index caff0476f..e1ce56aca 100644 --- 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 Version Description + + 2.10.0 + + - Updated USB Host API 2.4.0: + - deprecated: API for OHCI/EHCI Host Controller Interface (HCI) + + 2.9.0 diff --git a/CMSIS/Documentation/Doxygen/General/src/revision_history.md b/CMSIS/Documentation/Doxygen/General/src/revision_history.md index 0054b9e9c..4dc47b0f7 100644 --- 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 Version Description + + 6.1.0 + + - CMSIS-Driver: 2.10.0 + - Updated USB Host API 2.4.0 + + 6.0.0 diff --git a/CMSIS/Driver/DriverTemplates/Driver_USBH.c b/CMSIS/Driver/DriverTemplates/Driver_USBH.c index 3d06689cc..8d92b161d 100644 --- 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 index 4fb779899..f7d6d957a 100644 --- 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 diff --git a/CMSIS/Driver/Include/Driver_USBH.h b/CMSIS/Driver/Include/Driver_USBH.h index bd2689029..bc989fb84 100644 --- a/CMSIS/Driver/Include/Driver_USBH.h +++ b/CMSIS/Driver/Include/Driver_USBH.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 * @@ -14,14 +14,16 @@ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * - * $Date: 31. March 2020 - * $Revision: V2.3 + * + * $Date: 13. May 2024 + * $Revision: V2.4 * * Project: USB Host Driver definitions -*/ + */ /* History: + * Version 2.4 + * Deprecated API for OHCI/EHCI Host Controller Interface (HCI) * Version 2.3 * Removed volatile from ARM_USBH_PORT_STATE * Version 2.2 @@ -58,7 +60,7 @@ extern "C" #include "Driver_USB.h" -#define ARM_USBH_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,3) /* API version */ +#define ARM_USBH_API_VERSION ARM_DRIVER_VERSION_MAJOR_MINOR(2,4) /* API version */ #define _ARM_Driver_USBH_(n) Driver_USBH##n @@ -125,8 +127,6 @@ typedef uint32_t ARM_USBH_PIPE_HANDLE; #define ARM_USBH_EVENT_BUS_ERROR (1UL << 6) ///< Bus Error detected -#ifndef __DOXYGEN_MW__ // exclude from middleware documentation - // Function documentation /** \fn ARM_DRIVER_VERSION ARM_USBH_GetVersion (void) @@ -342,6 +342,8 @@ typedef struct _ARM_DRIVER_USBH { } const ARM_DRIVER_USBH; +#ifndef CMSIS_DISABLE_DEPRECATED + // HCI (OHCI/EHCI) // Function documentation @@ -400,7 +402,7 @@ typedef struct _ARM_USBH_HCI_CAPABILITIES { /** - \brief Access structure of USB Host HCI (OHCI/EHCI) Driver. + \brief Access structure of USB Host HCI (OHCI/EHCI) Driver. @deprecated HCI driver has been deprecated */ typedef struct _ARM_DRIVER_USBH_HCI { ARM_DRIVER_VERSION (*GetVersion) (void); ///< Pointer to \ref ARM_USBH_HCI_GetVersion : Get USB Host HCI (OHCI/EHCI) driver version. @@ -411,7 +413,7 @@ typedef struct _ARM_DRIVER_USBH_HCI { int32_t (*PortVbusOnOff) (uint8_t port, bool vbus); ///< Pointer to \ref ARM_USBH_HCI_PortVbusOnOff : USB Host HCI (OHCI/EHCI) Root HUB Port VBUS on/off. } const ARM_DRIVER_USBH_HCI; -#endif /* __DOXYGEN_MW__ */ +#endif // CMSIS_DISABLE_DEPRECATED #ifdef __cplusplus }