|
前言 Azure RTOS 是一套面向嵌入式系统的实时操作系统及中间件软件平台，采用模块化设计，主要包括 ThreadX 实时操作系统内核，以及 USBX、NetX Duo、FileX 和 LevelX 等组件，可满足实时控制、USB 通信、网络通信、文件系统和 Flash 存储管理等应用需求。 为了帮助开发者快速掌握 Azure RTOS 在 AT32 MCU 上的开发与应用，本文档介绍了 Azure RTOS 的软件架构、系统配置及各组件的基本使用方法，并结合典型示例说明 ThreadX、USBX、NetX Duo、FileX 和 LevelX 的配置流程及应用开发。 本文档适用于基于 AT32 MCU 进行 Azure RTOS 应用开发的工程师，可作为 Azure RTOS 移植、配置及应用开发的参考资料。
支持型号列表：AT32 MCU
备注说明：本文档仅供参考使用， 纯作分享，本文档中所涉及的相关视频或资料，可访问雅特力官网获取
1 概述Azure RTOS 是一套面向嵌入式系统的实时操作系统及中间件软件平台，提供高效、可靠的系统运行环境，广泛应用于工业控制、 物联网、消费电子等领域。
本文档基于 AT32 MCU 平台，介绍 Azure RTOS 各组件的应用方法，包括 ThreadX、USBX、NetX Duo、FileX 和 LevelX。文档重点说明各组件的配置流程、使用方法及典型应用示例，帮助开发者快速基于 AT32 Azure RTOS 软件平台进行应用开发。 Azure RTOS 主要由以下几个组件组成： l ThreadX：实时操作系统内核，负责线程调度、任务同步、内存管理和系统定时等功能。 l USBX：USB 协议栈，支持 USB Device 和 USB Host 两种模式，并提供多种 USB Class。 l NetX Duo：TCP/IP 网络协议栈，支持 IPv4 和 IPv6，同时提供 TCP、UDP、DHCP、DNS 等网络协议。 l FileX：FAT 文件系统，支持多种存储介质，如 SD Card、SPI Flash、QSPI Flash 等。
l LevelX：Flash 管理层，提供磨损均衡（Wear Leveling）及 Flash 擦写管理功能，可与 FileX 配合实现 Flash 文件系统。
1.1 硬件环境
本文档中的demo基于AT-START-F437开发板实现。
1.2 软件环境本文档配套提供多个 Azure RTOS 示例工程，覆盖 ThreadX、USBX、NetX Duo、FileX 和 LevelX 等组件的典型应用场景。开发者可根据实际应用需求选择对应工程进行学习和开发。
1.2.1 Azure RTOS 软件包介绍源码包将Azure RTOS组件放置在middlewares/3rd_party目录下，并以源码方式加入MDK工程。用户配置文件位于各Demo的inc目录，如tx_user.h、ux_user.h、nx_user.h、fx_user.h。
工程通过宏定义TX_INCLUDE_USER_DEFINE_FILE、UX_INCLUDE_USER_DEFINE_FILE、NX_INCLUDE_USER_DEFINE_FILE、FX_INCLUDE_USER_DEFINE_FILE引入这些配置。
| 组件 | 目录 | 定位 | 本源码包中的作用 | | Threadx | middlewares/3rd_party/threadx | 实时内核 | 提供线程调度、字节池、信号量、队列等基础能力，所有Demo均依赖 | | USBX | middlewares/3rd_party/usbx | USB协议栈 | 实现HID、CDC ACM、MSC Device、MSC+CDC复合设备和USB Host MSC等。 | | NetX Duo | middlewares/3rd_party/netxduo | 网络协议栈 | 实现DHCP客户端、TCP Socket和TCP Echo Server等。 | | FileX | middlewares/3rd_party/filex | FAT文件系统 | 操作U盘FX_MEDIA或内部Flash FAT媒体。 | | LevelX | middlewares/3rd_party/levelx | Flash管理层 | Flash管理层 对AT32内部NOR Flash提供逻辑扇区访问和擦写管理，并对接
FileX。 |
1.2.2 示例工程简介工程代码路径: utilities ├── threadx_netxduo ├── threadx_usbx_hid ├── threadx_usbx_device_cdc_acm ├── threadx_usbx_device_msc ├── threadx_usbx_device_msc_cdc_acm ├── threadx_usbx_device_msc_cdc_acm_levelx └── threadx_usbx_host_msc 各工程功能说明如下：
threadx_netxduo：基于ThreadX 和 NetX Duo 的网络通信示例，展示TCP/IP 协议栈初始化及网络应用开发流程 threadx_usbx_hid：基于ThreadX 和 USBX 的HID Device 示例，实现 USB HID 设备功能 threadx_usbx_device_cdc_acm：基于USBX 的 CDC ACM Device 示例，实现USB 虚拟串口通信 threadx_usbx_device_msc：基于USBX 的 MSC Device 示例，实现USB Mass Storage 设备功能 threadx_usbx_device_msc_cdc_acm：基于USBX 的 Composite Device 示例，同时实现MSC 和 CDC ACM 功能，并同时使用FileX访问文件 threadx_usbx_device_msc_cdc_acm_levelx：基于USBX、FileX 和LevelX 的综合应用示例，实现MSC、CDC ACM 以及Flash 文件存储功能 threadx_usbx_host_msc：基于USBX Host 的 MSC 示例，实现USB Host 读取外部存储设备功能
Note: 本应用笔记的项目基于keil 5而建立，若用户需要在其他编译环境上使用，请参考AT32Fxx_Firmware_Library_V2.x.x\project\at_start_f4xx\templates中各种编译环境（例如IAR6/7,keil4/5）进行简单修改即可。
2 AzureRTOS 软件架构AzureRTOS 采用分层模块化架构，由应用层、中间件层、ThreadX 内核层、AT32 BSP 驱动层以及硬件层组成。 在 AT32 MCU 平台中，ThreadX 作为系统核心，负责任务调度、线程管理、同步通信及内存管理；USBX、NetX Duo、FileX和 LevelX 基于 ThreadX 运行，为应用提供 USB 通信、网络连接、文件系统以及 Flash 管理等功能。 通过该架构，用户可以根据应用需求灵活组合不同组件，快速实现 USB 设备、网络通信、文件存储等功能
2.1 软件架构图
1. 应用层 包含文件，main.c等业务线程入口，主要完成硬件初始化，进入Threadx 内核，实现用户业务状态机。 2. 组件封装层 包含示例文件如app_usb_device.c/app_usb_host.c/app_netxduo.c/app_filex.c等文件，封装USB/网络/文件系统的初始化，是二次开发的主要入口。 3. Azure RTOS组件层 此部分的使用可参考Azure RTOS组件的使用说明文档，这里使用tx_api.h、ux_api.h、nx_api.h、fx_api.h、lx_api.h等API接口，提供内核、USB、网络、文件系统、FLASH管理API接口。 4. AT32适配层 此部分包含USB/EMAC/文件系统等的适配， usbx\common\usbx_at32_device_controllers包含USB deivce的适配，usbx\common\usbx_at32_host_controllers 包含USB host的适配，netxduo\common\drivers\emac 包含网络的适配。这些适配层将组件请求转换为AT32底层外设操作。 5. BSP/驱动层 此部分包含AT32 MCU BSP里面的驱动代码，提供时钟，USART, USB, EMAC, SDIO, FLASH等外设的能力。
[url=]2.2 软件目录结构
如下是整体源码包的目录结构
3 AzureRTOS 初始化流程
本节简单介绍使用Azure RTOS时的初始化流程 1. main()完成时钟、NVIC、串口、LED以及USB/EMAC/SDIO等外设初始化。 2. 调用tx_kernel_enter()进入ThreadX内核。 3. ThreadX完成低层初始化后调用tx_application_define()。 4. tx_application_define()创建字节池、调用组件初始化函数、创建线程和同步对象。 5. 业务线程开始运行，执行USB枚举、DHCP获取、TCP服务、文件读写或Flash管理。
4 ThreadX使用说明ThreadX负责所有Demo的线程调度和基础同步。源码中常见对象包括TX_BYTE_POOL、TX_THREAD、TX_SEMAPHORE和TX_QUEUE。应用扩展时建议优先新增线程和同步对象，而不是在中断或main()中放置复杂业务逻辑。 | 对象 | 源码示例 | 用途 | | TX_BYTE_POOL | nx_app_byte_pool、fx_app_byte_pool、ux_host_app_byte_pool | 统一管理组件和线程内存。 | | TX_THREAD | nx_main_thread、nx_tcp_thread、nx_link_thread、ux_app_thread、msc_app_thread、fx_thread | 执行网络、USB、文件系统业务逻辑。 | | TX_SEMAPHORE | nx_semaphore | 等待DHCP IP获取完成或TCP连接事件。 | | TX_QUEUE | ux_app_MsgQueue、ux_app_MsgQueue_msc USB | Host事件线程和MSC文件线程之间传递消息。 |
NetXDuo Demo中的TCP线程以TX_DONT_START创建，等DHCP获取IP后再由主线程tx_thread_resume()启动。这种方式可以避免网络尚未准备好时TCP线程提前执行。 4.1 Threadx 相关文件
ThreadX在本软件包中由通用内核源码、Cortex-M4移植层、用户配置文件和各Demo应用入口共同组成。用户开发时通常需要关注tx_user.h、tx_initialize_low_level.s、main.c和app_xxx.c；ThreadX内核公共源码一般不建议修改。 | 文件或目录 | 作用 | 用户关注点 | | middlewares/3rd_party/threadx/common/inc/tx_api.h | ThreadX公共API头文件，声明线程、字节池、信号量、队列、事件标志、定时器等接口。 | 应用代码包含tx_api.h后即可调用ThreadX API。 | | middlewares/3rd_party/threadx/common/src | ThreadX内核公共源码，包含tx_thread_create.c、tx_byte_pool_create.c、tx_queue_create.c等实现。 | 通常不修改；升级ThreadX版本时整体替换。 | | middlewares/3rd_party/threadx/ports/cortex_m4/keil/inc/tx_port.h | Cortex-M4Keil移植层头文件，定义端口相关类型、栈对齐、中断控制和上下文切换配置。 | 更换编译器或内核架构时重点检查。 | | middlewares/3rd_party/threadx/ports/cortex_m4/keil/src | Cortex-M4Keil汇编移植层，包含上下文保存/恢复、调度、定时器中断等文件 | 一般保持原样；若切换到IAR/GCC需使用对应ports目录 | | utilities/*/src/tx_initialize_low_level.s | 各Demo使用的ThreadX低层初始化文件，负责设置系统栈、向量表相关符号和SysTick定时器入口。 | 移植到其他工程时必须随工程一起加入。 | | utilities/*/inc/tx_user.h | 各Demo的ThreadX用户配置文件。 | 用于裁剪功能、关闭通知回调、配置定时器处理方式等 | | utilities/*/src/main.c | 硬件初始化和ThreadX启动入口。 | 完成时钟、NVIC、串口、外设初始化后调用tx_kernel_enter()。 | | utilities/*/src/app_xxx.c | 应用级ThreadX对象创建和业务线程实现。 | 新增线程、队列、信号量、字节池时优先修改这里。 |
4.2 Threadx 启动与移植流程
AT32工程启动后先运行启动文件和SystemInit()，随后进入main()。main()完成AT32外设初始化后调用tx_kernel_enter()，ThreadX内核再调用用户实现的tx_application_define()。因此，用户不应在main()中编写长期循环业务，而应在tx_application_define()中创建线程，由ThreadX调度执行。 - int main(void)
- {
- system_clock_config();
- nvic_priority_group_config(NVIC_PRIORITY_GROUP_4);
- uart_print_init(115200);
- tx_kernel_enter(); /* 进入ThreadX内核，不再返回 */
- }
tx_application_define()是ThreadX应用对象创建的统一入口。在本源码包中，不同Demo会在该函数中创建TX_BYTE_POOL，调用USBX、NetX Duo、FileX、LevelX初始化函数，或直接创建业务线程。 - VOID tx_application_define(void *first_unused_memory)
- {
- tx_byte_pool_create(&app_byte_pool, "app byte pool", buffer, buffer_size);
- app_component_init(first_unused_memory);
- tx_thread_create(&app_thread, "app thread", app_thread_entry, 0,
- app_stack, sizeof(app_stack), 5, 5,
- TX_NO_TIME_SLICE, TX_AUTO_START);
- }
USBX 是 Azure RTOS 提供的 USB 协议栈，支持 USB Device 和 USB Host 两种工作模式。AT32 Azure RTOS 软件包已经完成 USBX 在 AT32 MCU 平台上的移植，并提供了多种示例工程，用户可以快速实现 USB 通信功能。 USBX 采用模块化架构设计，应用程序无需直接操作 USB 底层寄存器，只需完成 USBX 初始化并注册相应的 USBClass，即可实现 USB 设备或主机功能。 AT32 软件包支持用户根据应用需求灵活选择所需的 USB Class，并可同时结合 ThreadX、FileX等组件构建完整的 USB 应用。 5.1 USBX 软件架构
USBX 通过统一的接口向应用程序提供 USB 功能，不同 USB Class 共用同一套协议栈，因此用户只需关注具体的业务逻辑，而无需处理 USB 协议细节。
5.2 USBX 相关文件USBX相关源码由USBX协议栈、AT32 USB控制器适配层、设备/主机类应用文件和用户配置文件组成。用户开发时重点关注app_usbx_device.c、app_usbx_host.c、ux_user.h、USB描述符文件以及Storage/CDC/HID类回调。 | 文件或目录 | 作用 | 用户关注点 | middlewares/3rd_party/usbx/ common/core | 提供Host/Device通用状态机、 内存管理和传输请求处理。 | 通常不修改，升级组件时整体替换。 | middlewares/3rd_party/usbx/ |
common/usbx_device_classes |
包含CDC ACM、HID、Storage等类。 | 根据产品需要选择加入工程的类源码。 | middlewares/3rd_party/usbx/ |
common/usbx_host_classes |
包含各种host类 |
包含各种host类 | middlewares\3rd_party\usbx\ |
common\usbx_at32_device_controllers | AT32USB device外设兼容驱动 | 开发时根据具体device或者host功能选择 | middlewares\3rd_party\usbx\ |
common\usbx_at32_host_controllers | AT32USB Host外设兼容驱动 | 开发时根据具体device或者host功能选择 | | utilities/*/inc/ux_user.h | USBX用户配置文件。 | 配置Device/Host方向、类数量、描述符长度、内存参数等。 | | utilities/*/src/app_usbx_device.c | USBDevice应用封装。 | 完成ux_system_initialize、ux_device_stack_initialize、类注册和DCD初始化 |
5.3 USBX Device 调用方法
Device侧一般在tx_application_define()中调用ux_application_init()，该函数先初始化USBX系统内存，再安装Device栈，随后注册CDC、HID或MSC类。线程运行后调用usb_device_dcd_initialize()连接AT32 OTGFS DCD，PC即可枚举设备。
- /* ux system initialize*/
- ux_system_initialize(memory_ptr, UX_DEVICE_MEMORY_STACK_SIZE, UX_NULL, 0);
- /* device stack initialize */
- ux_device_stack_initialize(device_framework_hs, hs_length,
- device_framework_fs, fs_length,
- string_framework, string_length,
- language_id_framework, language_id_length,
- UX_NULL);
- /* class register */
- ux_device_stack_class_register(_ux_system_slave_class_cdc_acm_name,
- ux_device_class_cdc_acm_entry, 1, 0, &cdc_acm_parameter);
- /* controller initialize */
- usb_device_dcd_initialize();
Host侧先初始化USBX Host内存，再调用ux_host_stack_initialize()安装Host栈，例注册Storage类，最后注册AT32HCD。U盘插入后事件回调获取UX_HOST_CLASS_STORAGE_MEDIA中的FX_MEDIA指针，再交给FileX线程执行文件操作。
- /* ux system initialize*/
- ux_system_initialize(ux_memory, USBX_MEMORY_SIZE, UX_NULL, 0);
- /* host stack initialize */
- ux_host_stack_initialize(ux_host_event_callback);
- /* class register */
- ux_host_stack_class_register(_ux_system_host_class_storage_name, ux_host_class_storage_entry);
- /* controller initialize */
- ux_host_stack_hcd_register("at32_hcd", _ux_hcd_at32_initialize, USB_OTGFS1_BASE, 0);
修改Device描述符后，需要同步检查配置描述符总长度、接口号、端点号和类注册时的interface参数。 CDCACM、MSC、HID等类所需内存不同，增加类或增加端点后应同步调整UX_DEVICE_MEMORY_STACK_SIZE和相关类数量配置。 MSC读写回调必须保证block地址、block数量和介质容量一致，否则PC端可能出现无法格式化或文件系统损坏。 HostMSC中不要在USB事件回调里直接执行耗时文件操作，应通过队列通知文件处理线程。 建议用户按照以下流程开发 USB 应用： 1. 选择对应的 USB 示例工程。 2. 完成 BSP 和系统时钟配置。 3. 初始化 ThreadX。 4. 初始化 USBX。 5. 注册所需 USB Class。 6. 启动 USB Device 或 USB Host。 7. 在应用线程中实现数据处理逻辑。
建议优先基于官方 Demo 工程进行开发，以减少工程配置工作量。
6 NetXDuo 使用说明NetXDuo 是 Azure RTOS 提供的高性能 TCP/IP 网络协议栈，支持 IPv4 和 IPv6 双协议栈，可运行于资源受限的嵌入式系统。AT32 Azure RTOS 软件包已经完成 NetX Duo 在 AT32 MCU 平台上的移植，并提供 Ethernet 网络驱动及相关示例工程，方便用户快速开发网络通信应用。NetX Duo 提供 TCP、UDP、ICMP、ARP、DHCP、DNS 等网络协议，并可扩展 HTTP、MQTT、SNTP、FTP 等网络应用组件，适用于工业控制、物联网网关、数据采集和远程监控等应用。
6.1 NetX Duo 软件架构 NetXDuo 位于 ThreadX 内核之上，通过网络驱动与 Ethernet MAC 和 PHY 通信，为应用程序提供统一的 Socket 和网络接口。 初始化过程中通常包括以下步骤： 1. 初始化 NetX Duo 系统。 2. 创建网络数据包内存池（Packet Pool）。 3. 创建 IP 实例（IP Instance）。 4. 注册 Ethernet 驱动。 5. 根据应用需要启用 TCP、UDP、ARP、ICMP 等协议。
6. 启动网络应用线程。
6.2 NetX Duo 相关文件| 文件或目录 | 作用 | 用户关注点 | middlewares/3rd_party/netxduo/ |
common/src |
内存管理和传输请求处理 | 通常不修改。 | middlewares/3rd_party/netxduo/ |
common/inc/nx_api.h | NetXDuo公共API头文件。 | 应用层调用NetX Duo接口时包含该文件。 | middlewares/3rd_party/netxduo/ |
common/drivers/emac /nx_at32_eth_driver.c | AT32EMAC驱动适配入口。 | 负责收发以太网帧、处理驱动命令、与PHY/描述符交互。 | | utilities/*/inc/nx_user.h | NetXDuo用户配置文件。 | 配置驱动延迟处理、接口数量、功能裁剪等。 | | utilities/*/inc/nx_at32_eth_config.h | AT32以太网参数配置 | 配置TX/RX描述符数量、链路检测周期、PHY相关参数。 | | utilities/*/inc/ux_user.h | USBX用户配置文件。 | 配置Device/Host方向、类数量、描述符长度、内存参数等 | | utilities/*/src/app_netxduo.c | 网络应用入口。 | 创建Packet Pool、IP实例、DHCP客户端、TCP线程和链路检测线程 |
6.3 NetX Duo 调用方法网络初始化建议放在线程或组件初始化函数中完成，顺序为系统初始化、Packet Pool创建、IP实例创建、协议启用、DHCP启动和业务Socket创建。
- /* NetX Duo system initialize */
- nx_system_initialize();
- /* NetX Duo pool create */
- nx_packet_pool_create(&nx_pool, "nx packet pool", PAYLOAD_SIZE, pointer, NX_PACKET_POOL_SIZE);
- /* NetX Duo ip create */
- nx_ip_create(&nx_ip_instance, "main ip instance", NULL_ADDRESS, NULL_ADDRESS,
- &nx_pool, nx_at32_eth_driver, pointer, stack_size, priority);
- /* NetX Duo arp/icmp/udp/tcp/dhcp enable */
- nx_arp_enable(&nx_ip_instance, arp_memory, arp_size);
- nx_icmp_enable(&nx_ip_instance);
- nx_udp_enable(&nx_ip_instance);
- nx_tcp_enable(&nx_ip_instance);
- nx_dhcp_create(&nx_dhcp_client, &nx_ip_instance, "dhcp client");
- nx_dhcp_start(&nx_dhcp_client);
PacketPool大小需要根据最大并发连接数、TCP窗口、应用数据长度和驱动收发队列综合配置。 网卡驱动必须正确处理缓存一致性、DMA描述符和PHY链路状态，否则会出现能获取IP但通信不稳定的问题。 链路断开后应停止或重启DHCP客户端，并在链路恢复时重新使能NX_LINK_ENABLE。 如果增加HTTP、FTP、MQTT等应用协议，应单独分配线程栈和应用内存，并评估优先级。 建议用户按照以下流程开发网络应用： 1. 选择官方 NetX Duo 示例工程。 2. 完成 Ethernet 硬件初始化。 3. 初始化 ThreadX。 4. 初始化 NetX Duo。 5. 创建 Packet Pool。 6. 创建 IP Instance。 7. 配置静态 IP 或 DHCP。 8. 创建 TCP 或 UDP Socket。 9. 编写网络应用程序。 10 .下载程序并验证网络通信。 建议以官方 Demo 为基础进行开发，可减少工程配置工作量
7 FileX使用说明本章介绍 Azure RTOS FileX 文件系统在 AT32 MCU 平台上的软件架构、初始化流程及基本使用方法，并说明 FileX 与 ThreadX、USBX 及 LevelX 的关系，帮助用户快速建立嵌入式文件系统应用。FileX 是 Azure RTOS 提供的高性能 FAT 文件系统，支持 FAT12、FAT16、FAT32，并可选支持 exFAT，适用于 RAM、SDCard、NOR Flash、NAND Flash 等多种存储介质。 FileX是 Azure RTOS 提供的嵌入式 FAT 文件系统，负责管理文件、目录以及存储介质的数据访问。AT32 Azure RTOS 软件包已经完成 FileX 的移植，用户无需关心 FAT 文件系统的底层实现，只需调用 FileX API 即可完成文件和目录操作。 FileX具有以下特点： l 支持 FAT12、FAT16、FAT32 文件系统 l 可选支持 exFAT 文件系统 l 支持长文件名（LFN） l 支持 Unicode 文件名 l 支持多存储介质管理 l 支持缓存机制，提高文件访问效率 l 可与 LevelX 配合，实现 Flash 磨损均衡 l 可与 USBX MSC 配合，实现 USB 存储设备功能
FileX采用模块化设计，可方便集成到 ThreadX 应用中，并能够通过驱动接口适配不同类型的存储设备。
7.1 FileX 软件架构FileX位于 ThreadX 内核之上，通过 Media Driver 访问底层存储设备。 初始化步骤一版包括： 1. 初始化 FileX 系统。 2. 初始化底层存储驱动。 3. 打开存储介质（Media）。 4. 挂载 FAT 文件系统。 5. 创建或打开文件。
6. 进入应用程序运行阶段。
7.2 FileX 相关文件
| 文件或目录 | 作用 | 用户关注点 | middlewares/3rd_party/filex/ |
common/src | FileX文件系统核心源码。 | 通常不修改。 | middlewares/3rd_party/filex/ |
common/inc/fx_api.h | FileX公共API头文件。 | 应用层调用fx_media_open、fx_file_write等接口时包含。 | | utilities/*/inc/fx_user.h | FileX用户配置文件。 | 用于功能裁剪和行为配置。 | | fx_at32_nor_flash_driver.c | FileX媒体驱动。 | 把FileX读写请求转换为内部Flash或LevelX操作。 |
7.3 FileX 调用方法在使用FileX的初始化时可按照如下调用：
- /* fx system initialize */
- fx_system_initialize();
- /* open media */
- status = fx_media_open(&nor_flash_disk, "FX_LX_NOR_DISK",
- fx_at32_levelx_nor_driver, driver_info,
- media_memory, sizeof(media_memory));
- if (status != FX_SUCCESS)
- {
- /* Media format */
- fx_media_format(&nor_flash_disk, fx_at32_levelx_nor_driver, driver_info,
- media_memory, sizeof(media_memory), "NOR_FLASH_DISK",
- 1, 32, 0, total_sectors, 512, 8, 1, 1);
- }
使用FileX 进行文件读写操作时，可按照如下调用方法： - /* create file */
- fx_file_create(&nor_flash_disk, "AT32.TXT");
- /* open file */
- fx_file_open(&nor_flash_disk, &file, "AT32.TXT", FX_OPEN_FOR_WRITE);
- fx_file_seek(&file, 0);
- /* write data to file */
- fx_file_write(&file, write_buffer, write_size);
- fx_media_flush(&nor_flash_disk);
- /* close file */
- fx_file_close(&file);
- /* open file as read only */
- fx_file_open(&nor_flash_disk, &file, "AT32.TXT", FX_OPEN_FOR_READ);
- /* read data */
- fx_file_read(&file, read_buffer, read_size, &actual_size);
首次使用空白Flash或无效FAT媒体时，fx_media_open()失败是正常现象，应执行fx_media_format()后重新打开。 文件写入后建议调用fx_media_flush()，尤其是在USB MSC场景中，避免PC端或设备断电造成数据未落盘。 FileX驱动中的扇区大小、总扇区数和介质物理擦写大小必须匹配，否则可能造成文件系统异常。 如果同一媒体同时被USB MSC和本地应用访问，需要设计互斥和访问时序，避免PC端和MCU端同时修改FAT。 建议用户按照以下步骤开发 FileX 应用： 选择官方 FileX 示例工程。 1. 初始化 ThreadX。 2. 初始化 FileX。 3. 初始化存储驱动。 4. 打开 Media。 5. 挂载文件系统。 6. 创建或打开文件。 7. 完成数据读写。 8. 关闭文件及 Media。 建议以官方 Demo 为基础进行开发，可减少底层驱动配置工作。
8 LevelX使用说明本章介绍 Azure RTOS LevelX 在 AT32 MCU 平台上的软件架构、初始化流程及基本使用方法，并说明 LevelX 与 FileX 的配合关系。LevelX是 Azure RTOS 提供的 Flash 管理组件，负责 Flash 擦除管理、逻辑块映射及磨损均衡（Wear Leveling），本身不提供文件系统接口，而是作为 FileX 的底层存储管理层使用。 NORFlash 和 NAND Flash 都具有擦写次数有限的特点。如果长期对同一物理区域进行写入，将导致 Flash 提前老化甚至失效。 LevelX的主要作用是在文件系统与 Flash 驱动之间增加一层 Flash 管理模块，通过逻辑地址映射、擦除管理和磨损均衡等机制，使应用程序无需关心 Flash 的物理组织结构，即可像访问普通块设备一样访问 Flash。LevelX 通常与 FileX 配合使用，为 FAT 文件系统提供可靠的底层存储支持。 LevelX主要具有以下特点： 支持 NOR Flash 和 NAND Flash 提供 Flash 擦除管理 提供 Wear Leveling（磨损均衡） 支持坏块管理（NAND Flash） 提供统一的 Flash 访问接口 可与 FileX 无缝集成 8.1 LevelX 软件架构在整个软件架构中： FileX负责文件和目录管理； LevelX负责 Flash 数据管理； FlashDriver 负责访问具体 Flash 器件； BSP 提供 SPI、QSPI 等硬件驱动。
这种分层设计提高了软件的可移植性，当更换 Flash 型号时，通常只需修改底层 Flash Driver，而无需修改 FileX 或应用程序。
8.2 LevelX 相关文件| 文件或目录 | 作用 | 用户关注点 | middlewares/3rd_party/levelx/ |
common/src | LevelX核心源码。 | 通常不修改。 | middlewares/3rd_party/levelx/ |
common/inc/lx_api.h | LevelX公共API头文件。 | LevelX公共API头文件。 | | lx_at32_internal_nor_flash_driver.c | AT32内部Flash LevelX底层驱动。 | 实现初始化、读、写、擦除和系统错误回调。 | | fx_at32_nor_flash_driver.c | FileX媒体驱动。 | 把FileX读写请求转换为内部Flash或LevelX操作。 |
8.3 LevelX 调用方法本源码包中用户通常不直接在业务代码中调用LevelX，而是由FileX媒体驱动fx_at32_levelx_nor_driver()在FX_DRIVER_INIT时调用lx_nor_flash_open()。如果用户需要单独验证LevelX，也可直接创建LX_NOR_FLASH对象并调用LevelX API。 - /* open nor flash */
- lx_nor_flash_open(&nor_flash, "AT32 NOR Flash",
- lx_at32_flash_initialize);
- /* read */
- lx_nor_flash_sector_read(&nor_flash, logical_sector, buffer);
- /* write */
- lx_nor_flash_sector_write(&nor_flash, logical_sector, buffer);
使用 LevelX 时，建议注意以下事项： l LevelX 仅负责 Flash 管理，不提供文件系统功能。 l Flash Driver 应正确实现读、写、擦除等基本操作，并保证操作完成后返回正确状态。 l Flash 擦除单位应与 LevelX 配置保持一致。 l 建议预留足够的空闲块，以提高 Wear Leveling 的效果。 l 对于 NOR Flash，建议使用 FileX + LevelX 的组合管理数据，避免应用层直接管理擦除和地址映射。 l 若系统支持在线升级（IAP）或掉电保护，应根据应用需求规划 Flash 分区，避免与 LevelX 管理区域重叠。 建议用户按照以下步骤开发基于 Flash 的文件系统应用： 1. 初始化 ThreadX。 2. 初始化 Flash Driver。 3. 初始化 LevelX。 4. 打开 FileX Media。 5. 挂载文件系统。 6. 创建文件或目录。 7. 进行数据读写。 8. 完成后关闭文件系统。
对于存储参数、日志或升级文件，建议统一通过 FileX 接口访问，而不要直接操作 Flash。
9 Demo使用说明本章介绍 AT32 Azure RTOS 软件包提供的示例工程。所有 Demo均已完成 ThreadX 及相关中间件的移植和配置，用户可直接编译运行，并在此基础上进行二次开发。
目前软件包中包含如下demo： | 工程名称 | 功能说明 | | threadx_netxduo | 基于ThreadX 和 NetX Duo 的网络通信示例，展示TCP/IP 协议栈初始化及网络应用开发流程 | | threadx_usbx_hid | 基于ThreadX 和 USBX 的HID Device 示例，实现 USB HID 设备功能 | | threadx_usbx_device_cdc_acm | 基于USBX 的 CDC ACM Device 示例，实现USB 虚拟串口通信 | | threadx_usbx_device_msc | 基于USBX 的 MSC Device 示例，实现USB Mass Storage 设备功能 | | threadx_usbx_device_msc_cdc_acm | 基于USBX 的 Composite Device 示例，同时实现MSC 和 CDC ACM 功能，并同时使用FileX访问文件 | | threadx_usbx_device_msc_cdc_acm_levelx | 基于USBX、FileX 和LevelX 的综合应用示例，实现MSC、CDC ACM 以及Flash 文件存储功能 | | threadx_usbx_host_msc | 基于USBX Host 的 MSC 示例，实现USB Host 读取外部存储设备功能 |
9.1 ThreadX + NetX Duo Demo该示例演示 NetX Duo TCP/IP 协议栈在 AT32 平台上的基本使用方法，完成 ThreadX 与 NetX Duo 的初始化，并建立Ethernet 网络通信功能。 该 Demo 同时演示了： l ThreadX l NetX Duo l Ethernet Driver l TCP/IP 协议栈初始化 l Packet Pool 管理 l IP Instance 创建 9.1.1 硬件资源如1.1章节硬件环境。 使用外设EMAC. 9.1.2 软件资源
1) utilities\threadx_netxduo 9.1.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 连接网线到路由器 3. 将PC与开发板接到同一个路由器下 4. 在PC上Ping 开发板 能正常ping通，表示成功。
9.2 ThreadX USBX HID Demo该示例演示 USB HID Mouse 功能。 运行后 MCU 将被识别为 USB 鼠标设备 9.2.1 硬件资源如1.1章节硬件环境。 使用外设OTG. 9.2.2 软件资源1) utilities\threadx_usbx_hid 9.2.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 使用USB线连接到PC
3. 在PC上成功枚举出Mouse设备
9.3 ThreadX USBX CDC-ACM Demo该示例演示 USB Device CDC ACM（Virtual COM Port）功能。 运行后，PC 将识别出一个虚拟串口设备，用户可通过串口工具与 MCU 进行数据通信。 9.3.1 硬件资源如1.1章节硬件环境。 使用外设OTG. 9.3.2 软件资源1) utilities\threadx_usbx_device_cdc_acm 9.3.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 使用USB线连接到PC 3. 在PC上成功枚举出CDC设备
4. 可使用串口工具打开设备进行数据收发
9.4 ThreadX USBX MSC Demo该示例演示 USB Mass Storage Device 功能。 运行后，MCU 将被 PC 识别为一个 U 盘设备，用户可通过 PC 对存储介质进行读写。 9.4.1 硬件资源如1.1章节硬件环境。 使用外设OTG/SDIO. 9.4.2 软件资源1) utilities\threadx_usbx_device_msc 9.4.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 使用USB线连接到PC 3. 在PC上成功枚举出mass storage设备
4. 可进行数据存取
9.5 ThreadX USBX MSC + FILEX+ CDCACM Composite Demo该示例演示 1． USB Composite Device。 2． FILEX 存取FLASH文件 设备同时具备： l USB MSC l USB CDC ACM l FILEX 读取FLASH 文件 运行后 PC 将同时识别： l 虚拟串口 l USB U盘 9.5.1 硬件资源如1.1章节硬件环境。 使用外设OTG. 9.5.2 软件资源1) utilities\ threadx_usbx_device_msc_cdc_acm 9.5.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 使用USB线连接到PC 3. 在PC上成功枚举出CDC和massstorage设备 4. 可使用串口工具与CDC设备通信，可对mass storage设备进行数据存取
5. 同时软件使用FileX API 读写文件。
9.6 ThreadX USBX MSC + FILEX +LEVELX+ CDC ACM Composite Demo该示例演示 1． USB Composite Device。 2． FILEX 通过LEVELX 存取FLASH文件 设备同时具备： l USB MSC l USB CDC ACM l FILEX 通过LEVELX读取FLASH文件 运行后 PC 将同时识别： l 虚拟串口 l USB U盘 9.6.1 硬件资源如1.1章节硬件环境。 使用外设OTG. 9.6.2 软件资源1) utilities\threadx_usbx_device_msc_cdc_acm_levelx 9.6.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 使用USB线连接到PC 3. 在PC上成功枚举出CDC和massstorage设备 4. 可使用串口工具与CDC设备通信，可对mass storage设备进行数据存取
5. 同时软件使用FileX + LevelX API 读写文件。
9.7 ThreadX USBX HOST MSC Demo该示例演示 USB Host Mass Storage 功能。 MCU 作为 USB Host，可识别并访问外部 U盘。 9.7.1 硬件资源如1.1章节硬件环境。 使用外设OTG. 9.7.2 软件资源1) utilities\ threadx_usbx_host_msc 9.7.3 示例使用1. 打开demo程序，编译完成，下载到开发板 2. 使用U盘接到开发板USB A口
3. Demo成功识别到U盘
[/url]
| 
/1 
|手机版|OpenEdv-开源电子网
( 粤ICP备12000418号-1 )
发表于 2026-7-23 15:25:17
