USB: update USB Device config file

- change "relocate" to "locate" - update comments - update source files related to "relocate" to "locate" change - update documentation - update examples - update examples for CI
ARM-software · Jun 4, 2024 · 602a940 · 602a940
1 parent d3d7611
commit 602a940
Show file tree

Hide file tree

Showing 19 changed files with 91 additions and 74 deletions.
diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_0.h b/.ci/USB/Device/RTE/USB/USBD_Config_0.h
@@ -41,7 +41,7 @@
 #define USBD0_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD0_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD0_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD0_BUF_MEM_RELOC             0
+#define USBD0_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD0_BUF_MEM_SECTION_NAME      ".driver.usbd0"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_0.h.base@8.0.0 b/.ci/USB/Device/RTE/USB/USBD_Config_0.h.base@8.0.0
@@ -41,7 +41,7 @@
 #define USBD0_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD0_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD0_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD0_BUF_MEM_RELOC             0
+#define USBD0_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD0_BUF_MEM_SECTION_NAME      ".driver.usbd0"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_1.h b/.ci/USB/Device/RTE/USB/USBD_Config_1.h
@@ -41,7 +41,7 @@
 #define USBD1_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD1_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD1_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD1_BUF_MEM_RELOC             0
+#define USBD1_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD1_BUF_MEM_SECTION_NAME      ".driver.usbd1"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_1.h.base@8.0.0 b/.ci/USB/Device/RTE/USB/USBD_Config_1.h.base@8.0.0
@@ -41,7 +41,7 @@
 #define USBD1_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD1_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD1_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD1_BUF_MEM_RELOC             0
+#define USBD1_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD1_BUF_MEM_SECTION_NAME      ".driver.usbd1"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_2.h b/.ci/USB/Device/RTE/USB/USBD_Config_2.h
@@ -41,7 +41,7 @@
 #define USBD2_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD2_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD2_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD2_BUF_MEM_RELOC             0
+#define USBD2_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD2_BUF_MEM_SECTION_NAME      ".driver.usbd2"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_2.h.base@8.0.0 b/.ci/USB/Device/RTE/USB/USBD_Config_2.h.base@8.0.0
@@ -41,7 +41,7 @@
 #define USBD2_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD2_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD2_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD2_BUF_MEM_RELOC             0
+#define USBD2_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD2_BUF_MEM_SECTION_NAME      ".driver.usbd2"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_3.h b/.ci/USB/Device/RTE/USB/USBD_Config_3.h
@@ -41,7 +41,7 @@
 #define USBD3_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD3_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD3_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD3_BUF_MEM_RELOC             0
+#define USBD3_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD3_BUF_MEM_SECTION_NAME      ".driver.usbd3"
+
 //     </e>
 //   </h>
 

diff --git a/.ci/USB/Device/RTE/USB/USBD_Config_3.h.base@8.0.0 b/.ci/USB/Device/RTE/USB/USBD_Config_3.h.base@8.0.0
@@ -41,7 +41,7 @@
 #define USBD3_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD3_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD3_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD3_BUF_MEM_RELOC             0
+#define USBD3_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD3_BUF_MEM_SECTION_NAME      ".driver.usbd3"
+
 //     </e>
 //   </h>
 

diff --git a/Components/USB/Config/USBD_Config.h b/Components/USB/Config/USBD_Config.h
@@ -41,7 +41,7 @@
 #define USBD%Instance%_DEV_DESC_IDPRODUCT        0x0000
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD%Instance%_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -113,15 +113,16 @@
 #define USBD%Instance%_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD%Instance%_BUF_MEM_RELOC             0
+#define USBD%Instance%_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD%Instance%_BUF_MEM_SECTION_NAME      ".driver.usbd%Instance%"
+
 //     </e>
 //   </h>
 

diff --git a/Components/USB/Source/usbd_compatibility.h b/Components/USB/Source/usbd_compatibility.h
@@ -40,8 +40,8 @@
 #ifndef USBD0_EP0_BUF_SIZE
 #define USBD0_EP0_BUF_SIZE                      (USBD0_MAX_PACKET0)
 #endif
-#ifndef USBD0_BUF_MEM_RELOC
-#define USBD0_BUF_MEM_RELOC                     (0)
+#ifndef USBD0_BUF_MEM_LOCATE
+#define USBD0_BUF_MEM_LOCATE                    (0)
 #endif
 
 #ifndef USBD1_CORE_THREAD_STACK_SIZE
@@ -62,8 +62,8 @@
 #ifndef USBD1_EP0_BUF_SIZE
 #define USBD1_EP0_BUF_SIZE                      (USBD1_MAX_PACKET0)
 #endif
-#ifndef USBD1_BUF_MEM_RELOC
-#define USBD1_BUF_MEM_RELOC                     (0)
+#ifndef USBD1_BUF_MEM_LOCATE
+#define USBD1_BUF_MEM_LOCATE                    (0)
 #endif
 
 #ifndef USBD2_CORE_THREAD_STACK_SIZE
@@ -84,8 +84,8 @@
 #ifndef USBD2_EP0_BUF_SIZE
 #define USBD2_EP0_BUF_SIZE                      (USBD2_MAX_PACKET0)
 #endif
-#ifndef USBD2_BUF_MEM_RELOC
-#define USBD2_BUF_MEM_RELOC                     (0)
+#ifndef USBD2_BUF_MEM_LOCATE
+#define USBD2_BUF_MEM_LOCATE                    (0)
 #endif
 
 #ifndef USBD3_CORE_THREAD_STACK_SIZE
@@ -106,8 +106,8 @@
 #ifndef USBD3_EP0_BUF_SIZE
 #define USBD3_EP0_BUF_SIZE                      (USBD3_MAX_PACKET0)
 #endif
-#ifndef USBD3_BUF_MEM_RELOC
-#define USBD3_BUF_MEM_RELOC                     (0)
+#ifndef USBD3_BUF_MEM_LOCATE
+#define USBD3_BUF_MEM_LOCATE                    (0)
 #endif
 
 

diff --git a/Components/USB/Source/usbd_section.h b/Components/USB/Source/usbd_section.h
@@ -16,31 +16,31 @@
 #define USBDn_DEV_BUF_MEM_SECTION_(str) __attribute__((section(str)))
 
 #ifdef  USBD0_PORT
-#if    (USBD0_BUF_MEM_RELOC == 1)
+#if    (USBD0_BUF_MEM_LOCATE == 1)
 #define USBD0_DEV_BUF_MEM_SECTION       USBDn_DEV_BUF_MEM_SECTION_(USBD0_BUF_MEM_SECTION_NAME)
 #else 
 #define USBD0_DEV_BUF_MEM_SECTION
 #endif
 #endif
 
 #ifdef  USBD1_PORT
-#if    (USBD1_BUF_MEM_RELOC == 1)
+#if    (USBD1_BUF_MEM_LOCATE == 1)
 #define USBD1_DEV_BUF_MEM_SECTION       USBDn_DEV_BUF_MEM_SECTION_(USBD1_BUF_MEM_SECTION_NAME)
 #else 
 #define USBD1_DEV_BUF_MEM_SECTION
 #endif
 #endif
 
 #ifdef  USBD2_PORT
-#if    (USBD2_BUF_MEM_RELOC == 1)
+#if    (USBD2_BUF_MEM_LOCATE == 1)
 #define USBD2_DEV_BUF_MEM_SECTION       USBDn_DEV_BUF_MEM_SECTION_(USBD2_BUF_MEM_SECTION_NAME)
 #else 
 #define USBD2_DEV_BUF_MEM_SECTION
 #endif
 #endif
 
 #ifdef  USBD3_PORT
-#if    (USBD3_BUF_MEM_RELOC == 1)
+#if    (USBD3_BUF_MEM_LOCATE == 1)
 #define USBD3_DEV_BUF_MEM_SECTION       USBDn_DEV_BUF_MEM_SECTION_(USBD3_BUF_MEM_SECTION_NAME)
 #else 
 #define USBD3_DEV_BUF_MEM_SECTION

diff --git a/Documentation/Doxygen/USB/src/images/usbd_config_0_h.png b/Documentation/Doxygen/USB/src/images/usbd_config_0_h.png
diff --git a/Documentation/Doxygen/USB/src/rl_usb.txt b/Documentation/Doxygen/USB/src/rl_usb.txt
@@ -638,8 +638,10 @@ The configuration file <b>USBD_Config_<i>n</i>.h</b> contains the following sett
   - Enable <b>OS String</b> for device to contain Microsoft OS string descriptor.
     - <b>Vendor Code</b> specifies the vendor code used to retrieve associated feature descriptors.
 - <b>Control Transfer Buffer Size</b> specifies the maximum size of control transfer.
-- <b>Data Buffers</b> specifies the relocation of the USB data buffers in memory.
-  - <b>Relocate</b> specifies if the USB data buffers are relocated to a specific memory address (via the linker script).
+- <b>Data Buffers</b> is used for locating the USB data buffers in memory.
+  - <b>Locate</b> specifies if the USB data buffers are located in a specific memory (via the linker script).
+    This is usually necessary in case that USB Controller has some specific requirements regarding memory for USB transfers.
+    For example if USB Controller can only access specific memory, or if this memory needs to be non-cacheable.
   - <b>Section Name</b> specifies the section name for the USB data buffers that is used by the linker script to position it in memory.
     Default section name is <c>.driver.usbd<instance></c>, for example for USB Device 0 the default section name is <c>.driver.usbd0</c>.
 - Use the <b>OS Resources Settings</b> to optimize the usage of OS resources.

diff --git a/Examples/USB/Device/HID/RTE/USB/USBD_Config_0.h b/Examples/USB/Device/HID/RTE/USB/USBD_Config_0.h
@@ -47,7 +47,7 @@
 #define USBD0_DEV_DESC_IDPRODUCT        0x5901
 
 //     <o.0..15>Device Release Number <0x0000-0xFFFF>
-//     <i>Device Release Number in binary-coded decimal (bcdDevice)
+//     <i>Device Release Number in binary-coded decimal (bcdDevice).
 #define USBD0_DEV_DESC_BCDDEVICE        0x0100
 
 //   </h>
@@ -119,15 +119,16 @@
 #define USBD0_EP0_BUF_SIZE              128
 
 //   <h>Data Buffers
-//     <e>Relocate
-//       <i>Specifies if the USB data buffers are located at a specific memory address
+//     <e>Locate
+//       <i>Specifies if the USB data buffers are located in a specific memory
 //       <i>(via the linker script).
-#define USBD0_BUF_MEM_RELOC             0
+#define USBD0_BUF_MEM_LOCATE            0
 
 //       <s.128>Section Name
 //         <i>Specifies the section name for the USB data buffers
 //         <i>(for positioning via the linker script).
 #define USBD0_BUF_MEM_SECTION_NAME      ".driver.usbd0"
+
 //     </e>
 //   </h>