Release 6.2.0

Author: TiejunZhou-CN

README.md

@@ -2,106 +2,105 @@
 
 A high-performance USB host, device, and on-the-go (OTG) embedded stack, Azure RTOS USBX is fully integrated with Azure RTOS ThreadX and available for all Azure RTOS ThreadX–supported processors. Like Azure RTOS ThreadX, Azure RTOS USBX is designed to have a small footprint and high performance, making it ideal for deeply embedded applications that require an interface with USB devices.
 
-## Documentation
+Here are the key features and modules of USBX:
 
-Documentation for this library can be found here: http://docs.microsoft.com/azure/rtos/usbx
+![USBX Key Features](./docs/usbx-features.png)
 
-# Understanding inter-component dependencies
+## Getting Started
 
-The main components of Azure RTOS are each provided in their own repository, but there are dependencies between them--shown in the following graph--that are important to understand when setting up your builds.
+Azure RTOS USBX as part of Azure RTOS has been integrated to the semiconductor's SDKs and development environment. You can develop using the tools of choice from [STMicroelectronics](https://www.st.com/content/st_com/en/campaigns/x-cube-azrtos-azure-rtos-stm32.html), [NXP](https://www.nxp.com/design/software/embedded-software/azure-rtos-for-nxp-microcontrollers:AZURE-RTOS), [Renesas](https://github.com/renesas/azure-rtos) and [Microchip](https://mu.microchip.com/get-started-simplifying-your-iot-design-with-azure-rtos).
 
-![dependency graph](docs/deps.png)
+We also provide [samples](https://github.com/azure-rtos/samples) using hero development boards from semiconductors you can build and test with.
 
-# Building and using the library
+See [Overview of Azure RTOS USBX](https://learn.microsoft.com/azure/rtos/usbx/overview-usbx) for the high-level overview, and all documentation and APIs can be found in: [Azure RTOS USBX documentation](https://learn.microsoft.com/azure/rtos/usbx/).
 
-## Prerequisites
+## Repository Structure and Usage
 
-Install the following tools:
+### Directory layout
 
-* [CMake](https://cmake.org/download/) version 3.0 or later
-* [GCC compilers for arm-none-eabi](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads)
-* [Ninja](https://ninja-build.org/)
+    .
+    ├── cmake                   # CMakeList files for building the project
+    ├── common                  # Core USBX files
+    ├── ports                   # Architecture and compiler specific files
+    ├── samples                 # Sample codes
+    ├── support                 # Misc platform configurations file used by USBX
+    ├── LICENSE.txt             # License terms
+    ├── LICENSE-HARDWARE.txt    # Licensed hardware from semiconductors
+    ├── CONTRIBUTING.md         # Contribution guidance
+    └── SECURITY.md             # Microsoft repo security guidance
 
-## Cloning the repo
+### Branches & Releases
 
-```bash
-$ git clone https://github.com/azure-rtos/usbx.git
-```
+The master branch has the most recent code with all new features and bug fixes. It does not represent the latest General Availability (GA) release of the library. Each official release (preview or GA) will be tagged to mark the commit and push it into the Github releases tab, e.g. `v6.2-rel`.
 
-## Building as a static library
+## Component dependencies
 
-Each component of Azure RTOS comes with a composible CMake-based build system that supports many different MCUs and host systems. Integrating any of these components into your device app code is as simple as adding a git submodule and then including it in your build using the CMake command `add_subdirectory()`.
+The main components of Azure RTOS are each provided in their own repository, but there are dependencies between them, as shown in the following graph. This is important to understand when setting up your builds.
 
-While the typical usage pattern is to include threadx into your device code source tree to be built & linked with your code, you can compile this project as a standalone static library to confirm your build is set up correctly.
+![dependency graph](docs/deps.png)
 
-```bash
-$ cmake -Bbuild -DCMAKE_TOOLCHAIN_FILE=cmake/cortex_m4.cmake -GNinja .
+> You will have to take the dependency graph above into account when building anything other than ThreadX itself.
 
-$ cmake --build ./build
-```
+### Building and using the library
 
-NOTE: You will have to take the dependency graph above into account when building anything other than threadx itself.
+Instruction for building the USBX as static library using Arm GNU Toolchain and CMake. If you are using toolchain and IDE from semiconductor, you might follow its own instructions to use Azure RTOS components as explained in the [Getting Started](#getting-started) section.
 
-# Repository Structure and Usage
+1. Install the following tools:
 
-## Branches & Releases
+    * [CMake](https://cmake.org/download/) version 3.0 or later
+    * [Arm GNU Toolchain for arm-none-eabi](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
+    * [Ninja](https://ninja-build.org/)
 
-The master branch has the most recent code with all new features and bug fixes. It does not represent the latest General Availability (GA) release of the library.
+1. Build the [ThreadX library](https://github.com/azure-rtos/threadx#building-and-using-the-library) as the dependency.
 
-## Releases
+1. Cloning the repo.
 
-Each official release (preview or GA) will be tagged to mark the commit and push it into the Github releases tab, e.g. `v6.0-rel`.
+    ```bash
+    $ git clone https://github.com/azure-rtos/usbx.git
+    ```
 
-## Directory layout
+1. Define the features and addons you need in `ux_user.h` and build together with the component source code. You can refer to [`ux_user_sample.h`](https://github.com/azure-rtos/usbx/blob/master/common/core/inc/ux_user_sample.h) as an example.
 
-```
-- cmake
-- common
-  - inc
-  - src
-- ports
-  - cortex_m0/gnu
-    - inc
-    - src
-  - cortex_m3/gnu
-    - inc
-    - src
-  - cortex_m4/gnu
-    - inc
-    - src
-  - cortex_m7/gnu
-    - inc
-    - src
-- samples
-```
+1. Building as a static library
 
-# Security
+    Each component of Azure RTOS comes with a composable CMake-based build system that supports many different MCUs and host systems. Integrating any of these components into your device app code is as simple as adding a git submodule and then including it in your build using the CMake `add_subdirectory()`.
 
-Azure RTOS provides OEMs with components to secure communication and to create code and data isolation using underlying MCU/MPU hardware protection mechanisms. It is ultimately the responsibility of the device builder to ensure the device fully meets the evolving security requirements associated with its specific use case.
+    While the typical usage pattern is to include USBX into your device code source tree to be built & linked with your code, you can compile this project as a standalone static library to confirm your build is set up correctly.
+
+    An example of building the library for Cortex-M4:
+
+    ```bash
+    $ cmake -Bbuild -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/cortex_m4.cmake .
+
+    $ cmake --build ./build
+    ```
 
-# Licensing
+## Professional support
 
-License terms for using Azure RTOS are defined in the LICENSE.txt file of this repo. Please refer to this file for all definitive licensing information. No additional license fees are required for deploying Azure RTOS on hardware defined in the LICENSED-HARDWARE.txt file. If you are using hardware not defined in the LICENSED-HARDWARE.txt file or have licensing questions in general, please contact Microsoft directly at https://aka.ms/azrtos-license.
+[Professional support plans](https://azure.microsoft.com/support/options/) are available from Microsoft. For community support and others, see the [Resources](#resources) section below.
 
-# Contribution, feedback, issues, and professional support
+## Licensing
 
-If you encounter any bugs, have suggestions for new features, or if you would like to become an active contributor to this project, please follow the instructions provided in the contribution guideline for the corresponding repo.
+License terms for using Azure RTOS are defined in the LICENSE.txt file of this repo. Please refer to this file for all definitive licensing information. No additional license fees are required for deploying Azure RTOS on hardware defined in the [LICENSED-HARDWARE.txt](./LICENSED-HARDWARE.txt) file. If you are using hardware not listed in the file or having licensing questions in general, please contact Microsoft directly at https://aka.ms/azrtos-license.
 
-For basic support, click Issues in the command bar or post a question to [Stack Overflow](http://stackoverflow.com/questions/tagged/azure-rtos+threadx) using the `threadx` and `azure-rtos` tags.
+## Resources
 
-Professional support plans (https://azure.microsoft.com/en-us/support/options/) are available from Microsoft.
+The following are references to additional Azure RTOS resources:
+
+- **Product introduction and white papers**: https://azure.com/rtos
+- **General technical questions**: https://aka.ms/QnA/azure-rtos
+- **Product issues and bugs, or feature requests**: https://github.com/azure-rtos/usbx/issues
+- **Licensing and sales questions**: https://aka.ms/azrtos-license
+- **Product roadmap and support policy**: https://aka.ms/azrtos/lts
+- **Blogs and videos**: http://msiotblog.com and https://aka.ms/iotshow
+- **Azure RTOS TraceX Installer**: https://aka.ms/azrtos-tracex-installer
+
+You can also check [previous questions](https://stackoverflow.com/questions/tagged/azure-rtos+usbx) or ask new ones on StackOverflow using the `azure-rtos` and `usbx` tags.
+
+## Security
+
+Azure RTOS provides OEMs with components to secure communication and to create code and data isolation using underlying MCU/MPU hardware protection mechanisms. It is ultimately the responsibility of the device builder to ensure the device fully meets the evolving security requirements associated with its specific use case.
 
-# Additional Resources
+## Contribution
 
-The following are references to additional Azure RTOS and Azure IoT in general:
-| Content | Link |
-|---|---|
-| TraceX Installer | https://aka.ms/azrtos-tracex-installer |
-| Azure RTOS Documentation and Guides: | https://docs.microsoft.com/azure/rtos |
-| Azure RTOS Website: | https://azure.microsoft.com/services/rtos/ |
-| Azure RTOS Sales Questions: | https://aka.ms/azrtos-license |
-| Azure RTOS Product Support Policy | https://aka.ms/azrtos/lts |
-| Azure RTOS Functional Safety Artifacts | https://aka.ms/azrtos/tuv |
-| For technical questions check out Microsoft Q/A for Azure IoT | https://aka.ms/QnA/azure-rtos |
-| Internet of Things Show for latest announcements and online training | https://aka.ms/iotshow |
-| IoT Tech Community | https://aka.ms/community/azure-rtos |
+Please follow the instructions provided in the [CONTRIBUTING.md](./CONTRIBUTING.md) for the corresponding repository.

common/core/inc/ux_api.h

@@ -26,7 +26,7 @@
 /*  APPLICATION INTERFACE DEFINITION                       RELEASE        */ 
 /*                                                                        */ 
 /*    ux_api.h                                            PORTABLE C      */ 
-/*                                                           6.1.12       */
+/*                                                           6.2.0        */
 /*  AUTHOR                                                                */
 /*                                                                        */
 /*    Chaoqiong Xiao, Microsoft Corporation                               */
@@ -122,6 +122,12 @@
 /*                                            added shared device config  */
 /*                                            descriptor for enum scan,   */
 /*                                            resulting in version 6.1.12 */
+/*  10-31-2022     Chaoqiong Xiao           Modified comment(s),          */
+/*                                            added some ETH error codes, */
+/*                                            allowed align minimal def,  */
+/*                                            added interface instance    */
+/*                                            creation strategy control,  */
+/*                                            resulting in version 6.2.0  */
 /*                                                                        */
 /**************************************************************************/
 
@@ -288,8 +294,8 @@ typedef signed char               SCHAR;
 /* Define basic constants for the USBX Stack.  */
 #define AZURE_RTOS_USBX
 #define USBX_MAJOR_VERSION            6
-#define USBX_MINOR_VERSION            1
-#define USBX_PATCH_VERSION            12
+#define USBX_MINOR_VERSION            2
+#define USBX_PATCH_VERSION            0
 
 /* Macros for concatenating tokens, where UX_CONCATn concatenates n tokens.  */
 
@@ -1102,7 +1108,6 @@ VOID    _ux_trace_event_update(TX_TRACE_BUFFER_ENTRY *event, ULONG timestamp, UL
 
 #define UX_NO_ALIGN                                                     0u
 #define UX_ALIGN_16                                                     0x0fu
-#define UX_ALIGN_MIN                                                    0x0fu
 #define UX_ALIGN_32                                                     0x1fu
 #define UX_ALIGN_64                                                     0x3fu
 #define UX_ALIGN_128                                                    0x7fu 
@@ -1113,6 +1118,9 @@ VOID    _ux_trace_event_update(TX_TRACE_BUFFER_ENTRY *event, ULONG timestamp, UL
 #define UX_ALIGN_4096                                                   0xfffu
 #define UX_SAFE_ALIGN                                                   0xffffffffu
 #define UX_MAX_SCATTER_GATHER_ALIGNMENT                                 4096
+#ifndef UX_ALIGN_MIN
+#define UX_ALIGN_MIN                                                    UX_ALIGN_16
+#endif
 
 #define UX_MAX_USB_DEVICES                                              127
 
@@ -1483,6 +1491,10 @@ VOID    _ux_trace_event_update(TX_TRACE_BUFFER_ENTRY *event, ULONG timestamp, UL
 #define UX_HOST_CLASS_AUDIO_WRONG_FREQUENCY                             0x82
 
 #define UX_CLASS_CDC_ECM_LINK_STATE_DOWN_ERROR                          0x90
+#define UX_CLASS_ETH_LINK_STATE_DOWN_ERROR                              0x90
+#define UX_CLASS_ETH_PACKET_POOL_ERROR                                  0x91
+#define UX_CLASS_ETH_PACKET_ERROR                                       0x92
+#define UX_CLASS_ETH_SIZE_ERROR                                         0x93
 
 
 /* Define USBX HCD API function constants.  */                          
@@ -2049,6 +2061,12 @@ typedef struct UX_CONFIGURATION_STRUCT
     ULONG           ux_configuration_iad_protocol;
 } UX_CONFIGURATION;
 
+#define UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_ALL     0 /* Default: all things created.  */
+#define UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_OWNED   1 /* Owned: class owned things created.  */
+#ifndef UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_CONTROL
+#define UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_CONTROL UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_ALL
+#endif
+
 
 /* Define USBX Interface Descriptor structure.  */
 

common/core/inc/ux_user_sample.h

@@ -26,7 +26,7 @@
 /*  PORT SPECIFIC C INFORMATION                            RELEASE        */ 
 /*                                                                        */ 
 /*    ux_user.h                                           PORTABLE C      */ 
-/*                                                           6.1.12       */
+/*                                                           6.2.0        */
 /*                                                                        */
 /*  AUTHOR                                                                */
 /*                                                                        */
@@ -83,6 +83,12 @@
 /*                                            added device CDC_ACM and    */
 /*                                            printer write auto ZLP,     */
 /*                                            resulting in version 6.1.12 */
+/*  10-31-2022     Chaoqiong Xiao           Modified comment(s),          */
+/*                                            deprecated ECM pool option, */
+/*                                            added align minimal config, */
+/*                                            added host stack instance   */
+/*                                            creation strategy control,  */
+/*                                            resulting in version 6.2.0  */
 /*                                                                        */
 /**************************************************************************/
 
@@ -116,6 +122,10 @@
 /* Override various options with default values already assigned in ux_api.h or ux_port.h. Please 
    also refer to ux_port.h for descriptions on each of these options.  */
 
+/* Defined, this value represents minimal allocated memory alignment in number of bytes.
+   The default is UX_ALIGN_16 (0x0f) to align allocated memory to 16 bytes.  */
+/* #define UX_ALIGN_MIN UX_ALIGN_16  */
+
 /* Defined, this value represents how many ticks per seconds for a specific hardware platform. 
    The default is 1000 indicating 1 tick per millisecond.  */
 
@@ -317,7 +327,9 @@
 
 /* #define UX_HOST_CLASS_CDC_ECM_PACKET_POOL_INSTANCE_WAIT  10 */
 
-/* Defined, this enables CDC ECM class to use the packet pool from NetX instance.  */
+/* Defined, this enables CDC ECM class to use the packet pool from NetX instance.
+   It's deprecated, packet pool from NetX instance is always used now.
+ */
 
 /* #define UX_HOST_CLASS_CDC_ECM_USE_PACKET_POOL_FROM_NETX */
 
@@ -427,6 +439,15 @@
 /* Defined, host audio optional interrupt endpoint is support.  */
 /* #define UX_HOST_CLASS_AUDIO_INTERRUPT_SUPPORT  */
 
+/* Defined, this value controls host configuration instance creation, include all
+   interfaces and endpoints physical resources.
+   Possible settings:
+    UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_ALL (0) - The default, create all inside configuration.
+    UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_OWNED (1) - Create things owned by class driver.
+   Not defined, default setting is applied.
+ */
+/* #define UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_CONTROL UX_HOST_STACK_CONFIGURATION_INSTANCE_CREATE_OWNED */
+
 /* Defined, this value will only enable the host side of usbx.  */
 /* #define UX_HOST_SIDE_ONLY   */