第 2 章 - 安装和使用 Azure RTOS FileX

本章介绍 Azure RTOS FileX 及其安装条件、安装过程和用法。

主机注意事项

计算机类型

嵌入式开发通常在 Windows 或 Linux (Unix) 主机计算机上执行。 在对应用程序进行编译和链接并将其放置在主机上之后,应用程序将下载到目标硬件进行执行。

下载接口

通常,目标下载是从开发工具调试器内完成的。 在下载后,调试器负责提供目标执行控制(“执行”、“暂停”和“断点”等)以及对内存和处理器寄存器的访问。

调试工具

大多数开发工具调试器通过 JTAG (IEEE 1149.1) 和背景调试模式 (BDM) 等芯片调试 (OCD) 连接与目标硬件进行通信。 调试器还通过线路内仿真 (ICE) 连接与目标硬件进行通信。 OCD 和 ICE 连接提供可靠的解决方案,对目标常驻软件的干扰已降至最低限度。

所需的硬盘空间

FileX 的源代码以 ASCII 格式提供,并要求主计算机的硬盘上具有约 500 KB 的可用空间

目标注意事项

FileX 要求目标具有 6 KB 到 30 KB 的只读内存 (ROM)。 FileX 全局数据结构要求目标具有额外的 100 字节随机存取内存 (RAM)。 每个打开的媒体除了要求提供 RAM(通常为 512 字节)用于存储一个扇区的数据以外,还要求为控制块提供 1.5 KB RAM。

为了使日期/时间戳记正常运行,FileX 依赖于 ThreadX 计时器设施。 这是通过在 FileX 初始化期间创建 FileX 特定的计时器实现的。 FileX 还依赖于 ThreadX 信号灯来实现多线程保护和 I/O 挂起。

产品分发

可以从我们的公共源代码存储库获取 Azure RTOS FileX,网址为:https://github.com/azure-rtos/filex/

下面列出了该存储库中的几个重要文件:

  • fx_api.h:此 C 头文件包含所有系统等式、数据结构和服务原型。
  • fx_port.h:此 C 头文件包含所有特定于开发工具的数据定义和结构。
  • demo_filex.c:此 C 文件包含小型演示应用程序。
  • fx.a(或 fx.lib):这是 FileX C 库的二进制版本。 它随标准包一起分发。

重要

所有文件名均为小写。 通过此命名约定可以更轻松地将命令转换为 Linux (Unix) 开发平台的命令。

FileX 安装

可以通过将 GitHub 存储库克隆到本地计算机来安装 FileX。 下面是用于在电脑上创建 FileX 存储库的克隆的典型语法:

    git clone https://github.com/azure-rtos/filex

或者,也可以使用 GitHub 主页上的“下载”按钮来下载存储库的副本。

还可以在联机存储库的首页上找到有关生成 FileX 库的说明。

重要

应用程序软件需要访问 FileX 库文件(通常为 fx.a 或 fx.lib)和 C include 文件 fx_api.h 和 fx_port.h。 为实现此目的,可以设置开发工具的相应路径,或者将这些文件复制到应用程序开发区域。

使用 FileX

FileX 很容易使用。 简单而言,应用程序代码在编译期间必须包含 fx_api.h,并且必须与 FileX 运行时库 fx.a(或 fx.lib)相链接。 当然,ThreadX 文件 - 即 tx_api.h 和 tx.a(或 tx.lib)- 也是必需的。

重要

在独立模式下使用 FileX 时(必须定义 FX_STANDALONE_ENABLE),不需要 ThreadX 文件/库。

假设你已在使用 ThreadX,需要执行四个步骤来生成 FileX 应用程序:

  1. 在所有使用 FileX 服务或数据结构的应用程序文件中包括 fx_api.h 文件。

  2. 通过从 tx_application_define 函数或应用程序线程调用 fx_system_initialize 来初始化 FileX 系统。

    重要

    在独立模式下使用 FileX 时,应直接从应用程序代码调用 fx_system_initialize

  3. 添加对 fx_media_open 的一个或多个调用可设置 FileX 媒体。 必须从应用程序线程的上下文发出此调用。

    重要

    请记住,fx_media_open 调用需要足够的 RAM 来存储一个扇区的数据

  4. 编译应用程序源,并与 FileX 和 ThreadX 运行库 fx.a(或 fx.lib)及 tx.a(或 tx.lib)相链接。 生成的图像可下载到目标并执行!

疑难解答

每个 FileX 端口都随演示应用程序一起提供。 最好先让演示系统在目标硬件或特定演示环境上运行。

如果演示系统无法工作,请尝试通过以下方法缩小问题的范围:

  1. 确定演示的运行量。
  2. 增加堆栈大小(这在实际的应用程序代码中比在演示中更为重要)。
  3. 请确保为 32 KB 默认 RAM 磁盘大小提供足够的 RAM。 基本系统运行时使用的 RAM 会少得多;但是,随着使用的 RAM 磁盘越来越多,在内存不足的情况下,问题就会出现。
  4. 暂时跳过最近所做的任何更改,以查看问题是否消失或发生更改。 此类信息对于 Microsoft 支持工程师非常有用。 按照“客户支持中心”中概述的步骤,发送从故障排除步骤中收集的信息。

配置选项

使用 FileX 生成 FileX 库和应用程序时,有几个配置选项可用。 可以在应用程序源、命令行或 fx_user.h include 文件中定义以下选项。

重要

只有当应用程序和 ThreadX 库在构建时定义了 TX_INCLUDE_USER_DEFINE_FILE,才会应用在 tx_user.h 中定义的选项。 在独立模式下使用 FileX 时(必须定义 FX_STANDALONE_ENABLE),不需要 ThreadX 文件/库。

以下列表详细描述了每个配置选项:

定义 含义
FX_MAX_LAST_NAME_LEN 此值定义最大文件名长度(包括完整路径名称)。 默认情况下,此值为 256。
FX_DONT_UPDATE_OPEN_FILES 已定义,FileX 不会更新已打开的文件。
FX_MEDIA_DISABLE_SEARCH_CACHE 已定义,将禁用文件搜索缓存优化。
FX_MEDIA_DISABLE_SEARCH_CACHE 已定义,将禁用文件搜索缓存优化。
FX_DISABLE_DIRECT_DATA_READ_CACHE_FILL 已定义,将禁用缓存的直接读取扇区更新。
FX_MEDIA_STATISTICS_DISABLE 已定义,将禁用媒体统计信息收集。
FX_SINGLE_OPEN_LEGACY 已定义,将为同一文件启用传统单开逻辑。
FX_RENAME_PATH_INHERIT 已定义,将重命名继承路径信息。
FX_DISABLE_ERROR_CHECKING 删除基本 FileX 错误检查 API,可提高性能(最高 30%)并减少代码量。
FX_MAX_LONG_NAME_LEN 指定 FileX 的最大文件名大小。 默认值为 256,但可以使用命令行定义重写此值。 合法值的范围为 13 到 256。
FX_MAX_SECTOR_CACHE 指定可由 FileX 缓存的最大逻辑扇区数。 可缓存的实际扇区数小于此常量,以及在 fx_media_open 提供的内存量中可装入的扇区数。 默认值为 256。 所有值必须是 2 的幂。
FX_FAT_MAP_SIZE 指定可在 FAT 更新映射中表示的扇区数。 默认值为 256,但可以使用命令行定义重写此值。 较大的值有助于减少不必要地更新辅助 FAT 扇区。
FX_MAX_FAT_CACHE 指定内部 FAT 缓存中的条目数。 默认值为 16,但可以使用命令行定义重写此值。 所有值必须是 2 的幂。
FX_FAULT_TOLERANT 如果已定义,FileX 会立即将所有系统扇区(启动、FAT 和目录扇区)的写入请求传递到媒体的驱动程序。 这可能会降低性能,但有助于限制对已丢失的簇造成损坏。 请注意,启用此功能不会自动启用 FileX 容错模块(可通过定义来启用)
FX_FAULT_TOLERANT_DATA 如果已定义,FileX 会立即将所有文件数据写入请求传递到媒体的驱动程序。 这可能会降低性能,但有助于限制文件数据丢失。 请注意,启用此功能不会自动启用 FileX 容错模块,该模块可通过定义 FX_ENABLE_FAULT_TOLERANT 启用
FX_NO_LOCAL_PATH 从 FileX 中删除本地路径逻辑,从而减少代码量。
FX_NO_TIMER 消除了用于更新 FileX 系统时间和日期的 ThreadX 计时器设置。 这会导致在所有文件操作中添加默认时间和日期。
FX_UPDATE_RATE_IN_SECONDS 指定调整 FileX 中系统时间的频率。 默认情况下值为 10,它指定每隔 10 秒更新 FileX 系统时间。
FX_ENABLE_EXFAT 如果已定义,则在 FileX 中启用用于处理 exFAT 文件系统的逻辑。 默认未定义此符号。
FX_UPDATE_RATE_IN_TICKS 指定与 FX_UPDATE_RATE_IN_SECONDS(参阅上文)相同的频率,但基础 ThreadX 计时器频率方面除外。 默认值为 1000(采用 10 毫秒 ThreadX 计时器频率和 10 秒间隔)。
FX_SINGLE_THREAD 消除 FileX 源中的 ThreadX 保护逻辑。 如果仅从一个线程使用 FileX,或者使用了 FileX 但未使用 ThreadX,则应使用该选项。
FX_DRIVER_USE_64BIT_LBA 如果已定义后,将启用 I/O 驱动程序中使用的 64 位扇区地址。 默认未定义此选项。
FX_ENABLE_FAULT_TOLERANT 如果已定义,将启用 FileX 容错模块。 启用容错会自动定义符号 FX_FAULT_TOLERANT 和 FX_FAULT_TOLERANT_DATA。 默认未定义此选项。
FX_FAULT_TOLERANT_BOOT_INDEX 定义容错日志簇所在的引导扇区中的字节偏移量。 默认情况下,此值为 116。 此字段采用 4 个字节。 之所以选择第 116 到 119 字节,是因为它们已根据 FAT 12/16/32/exFAT 规范标记为保留字节。
FX_FAULT_TOLERANT_MINIMAL_CLUSTER 此符号已弃用。 FileX 容错不再使用它。
FX_STANDALONE_ENABLE 已定义,将允许在独立模式下使用 FileX(不带 Azure RTOS)。 默认未定义此符号。

重要

如果已定义 FX_STANDALONE_ENABLE,则会禁用本地路径逻辑和 ThreadX 计时器设置。

FileX 版本 ID

当前版本的 FileX 在运行时可供用户和应用程序软件使用。 程序员可以通过检查 fx_port.h 文件来获取 FileX 版本。 此外,该文件还包含相应端口的版本历史记录。 应用程序软件可以通过检查全局字符串 fx_version_id 来获取 FileX 版本。