[译]Chapter 2 - Installation and Use of Azure RTOS ThreadX 安装与使用

段干博涉

2023-12-01

[译]：https://docs.microsoft.com/zh-cn/azure/rtos/threadx/chapter2

This chapter contains a description of various issues related to installation, setup, and usage of the high-performance Azure RTOS ThreadX kernel.

本章包含与高性能Azure RTOS ThreadX内核的安装、设置和使用相关的各种问题的描述。

Host Considerations

Embedded software is usually developed on Windows or Linux (Unix) host computers. After the application is compiled, linked, and located on the host, it is downloaded to the target hardware for execution.

Usually the target download is done from within the development tool debugger. After the download has completed, the debugger is responsible for providing target execution control (go, halt, breakpoint, etc.) as well as access to memory and processor registers.

Most development tool debuggers communicate with the target hardware via on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and Background Debug Mode (BDM). Debuggers also communicate with target hardware through In-Circuit Emulation (ICE) connections. Both OCD and ICE connections provide robust solutions with minimal intrusion on the target resident software.

As for resources used on the host, the source code for ThreadX is delivered in ASCII format and requires approximately 1 MByte of space on the host computer's hard disk.

主机注意事项

嵌入式软件通常是在Windows或Linux（Unix）主机上开发的。在主机上编译、链接和定位应用程序后，将其下载到目标硬件上执行。

通常，目标下载是从开发工具调试器中完成的。下载完成后，调试器负责提供目标执行控制（go、halt、breakpoint等）以及对内存和处理器寄存器的访问。

大多数开发工具调试器通过片上调试（OCD）连接与目标硬件通信，如JTAG（ieee1149.1）和后台调试模式（BDM）。调试器还通过电路内仿真（ICE）连接与目标硬件通信。OCD和ICE连接都提供了健壮的解决方案，对目标驻留软件的入侵最小。

至于主机上使用的资源，ThreadX的源代码是以ASCII格式提供的，需要主机硬盘上大约1兆字节的空间。

Target Considerations

ThreadX requires between 2 KBytes and 20 KBytes of Read Only Memory (ROM) on the target. It also requires another 1 to 2 KBytes of the target's Random Access Memory (RAM) for the ThreadX system stack and other global data structures.

For timer-related functions like service call time-outs, time-slicing, and application timers to function, the underlying target hardware must provide a periodic interrupt source. If the processor has this capability, it is utilized by ThreadX. Otherwise, if the target processor does not have the ability to generate a periodic interrupt, the user's hardware must provide it. Setup and configuration of the timer interrupt is typically located in the tx_initialize_low_level assembly file in the ThreadX distribution.

备注

ThreadX is still functional even if no periodic timer interrupt source is available. However, none of the timer-related services are functional.

目标注意事项

ThreadX在目标上需要2 KB到20 KB的只读内存（ROM）。它还需要另外1到2千字节的目标随机存取存储器（RAM），用于ThreadX系统堆栈和其他全局数据结构。

对于服务调用超时、时间切片和应用程序计时器等与计时器相关的功能，底层目标硬件必须提供周期性中断源。如果处理器具有此功能，则ThreadX将使用它。否则，如果目标处理器没有能力生成周期性中断，则必须由用户的硬件提供。定时器中断的设置和配置通常位于ThreadX发行版的tx\u initialize\u low\u level汇编文件中。

备注

即使没有周期性定时器中断源可用，ThreadX仍然可以正常工作。但是，与计时器相关的服务都不起作用。

Product Distribution

Azure RTOS ThreadX can be obtained from our public source code repository at https://github.com/azure-rtos/threadx/.

The following is a list of several important files in the repository.

PRODUCT DISTRIBUTION
Filename	Description
tx_api.h	C header file containing all system equates, data structures, and service prototypes.
tx_port.h	C header file containing all development-tool and targetspecific data definitions and structures.
demo_threadx.c	C file containing a small demo application.
tx.a (or tx.lib)	Binary version of the ThreadX C library that is distributed with the standard package.

备注

All file names are in lower-case. This naming convention makes it easier to convert the commands to Linux (Unix) development platforms.

产品发布

Azure RTOS ThreadX可从我们的公共源代码库获取，网址为https://github.com/azure rtos/threadx/。

以下是存储库中几个重要文件的列表。

文件名说明

tx_api.h C头文件，包含所有系统等价物、数据结构和服务原型。

tx_port.h C头文件，包含所有开发工具和特定于目标的数据定义和结构。

demo_threadx.c C文件，包含一个小的演示应用程序的。

tx.a (or tx.lib) 随标准软件包分发的ThreadX C库的二进制版本。

备注

所有文件名都是小写的。这种命名约定使得将命令转换为Linux（Unix）开发平台更加容易。

ThreadX Installation

ThreadX is installed by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the ThreadX repository on your PC.

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

Alternatively you can download a copy of the repository using the download button on the GitHub main page.

You will also find instructions for building the ThreadX library on the front page of the online repository.

备注

Application software needs access to the ThreadX library file (usually tx.a or tx.lib) and the C include files tx_api.h and tx_port.h. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.

ThreadX安装

ThreadX是通过将GitHub存储库克隆到本地计算机来安装的。以下是在PC上创建ThreadX存储库克隆的典型语法。

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

或者，您可以使用GitHub主页上的下载按钮下载存储库的副本。

您还可以在联机存储库的首页上找到构建ThreadX库的说明。

备注

应用软件需要访问ThreadX库文件（通常是tx.a或tx.lib)和C文件，比如tx_api.h和tx_port.h。这可以通过为开发工具设置适当的路径或将这些文件复制到应用程序开发区域来实现。

Using ThreadX

To use ThreadX, the application code must include tx_api.h during compilation and link with the ThreadX run-time library tx.a (or tx.lib).

There are four steps required to build a ThreadX application.

Include the tx_api.h file in all application files that use ThreadX services or data structures.
Create the standard C main function. This function must eventually call tx_kernel_enter to start ThreadX. Application-specific initialization that does not involve ThreadX may be added prior to entering the kernel.

重要

The ThreadX entry function tx_kernel_enter does not return. So be sure not to place any processing or function calls after it.
Create the tx_application_define function. This is where the initial system resources are created. Examples of system resources include threads, queues, memory pools, event flags groups, mutexes, and semaphores.
Compile application source and link with the ThreadX run-time library tx.lib. The resulting image can be downloaded to the target and executed!

使用ThreadX

要使用ThreadX，应用程序代码必须在编译过程中包含tx_api.h，并链接到ThreadX运行时库tx.a（或tx.lib).

构建ThreadX应用程序需要四个步骤。

在所有使用ThreadX服务或数据结构的应用程序文件中包括tx_api.h文件。
创建标准C主函数。此函数最终必须调用tx_kernel_enter来启动ThreadX。在进入内核之前，可以添加不涉及ThreadX的特定于应用程序的初始化。
创建tx_application_define函数。这是创建初始系统资源的地方。系统资源的示例包括线程、队列、内存池、事件标志组、互斥锁和信号量。
编译应用程序源代码并链接到ThreadX运行时库tx.lib. 生成的图像可以下载到目标并执行！

重要

ThreadX entry函数tx_kernel_enter不返回。因此，请确保不要在它后面放置任何处理或函数调用。

Small Example System

The small example system in Figure 1 shows the creation of a single thread with a priority of 3. The thread executes, increments a counter, then sleeps for one clock tick. This process continues forever.

#include "tx_api.h"
unsigned long my_thread_counter = 0;
TX_THREAD my_thread;
main( )
{
    /* Enter the ThreadX kernel. */
    tx_kernel_enter( );
}
void tx_application_define(void *first_unused_memory)
{
    /* Create my_thread! */
    tx_thread_create(&my_thread, "My Thread",
    my_thread_entry, 0x1234, first_unused_memory, 1024,
    3, 3, TX_NO_TIME_SLICE, TX_AUTO_START);
}
void my_thread_entry(ULONG thread_input)
{
    /* Enter into a forever loop. */
    while(1)
    {
        /* Increment thread counter. */
        my_thread_counter++;
        /* Sleep for 1 tick. */
        tx_thread_sleep(1);
    }
}

FIGURE 1. Template for Application Development

Although this is a simple example, it provides a good template for real application development.

图1中的小示例系统显示了优先级为3的单个线程的创建。线程执行，递增一个计数器，然后休眠一个时钟周期。这一进程将永远持续下去。

虽然这是一个简单的示例，但它为实际应用程序开发提供了一个很好的模板。

Troubleshooting

Each ThreadX port is delivered with a demonstration application. It is always a good idea to first get the demonstration system running—either on actual target hardware or simulated environment.

If the demonstration system does not execute properly, the following are some troubleshooting tips.

Determine how much of the demonstration is running.
Increase stack sizes (this is more important in actual application code than it is for the demonstration).
Rebuild the ThreadX library with TX_ENABLE_STACK_CHECKING defined. This enables the built-in ThreadX stack checking.
Temporarily bypass any recent changes to see if the problem disappears or changes. Such information should prove useful to support engineers.

Follow the procedures outlined in "Customer Support Center" to send the information gathered from the troubleshooting steps.

故障排查

每个ThreadX端口都附带了一个演示应用程序。首先让演示系统运行总是一个好主意，不管是在实际目标硬件还是在模拟环境上。

如果演示系统执行不正确，以下是一些故障排查提示。

确定演示的运算量。
增加堆栈大小（这在实际应用程序代码中比在演示中更重要）。
重新生成定义了TX_ENABLE_STACK_CHECKING的ThreadX库。这将启用内置的ThreadX堆栈检查。
暂时绕过任何最近的更改以查看问题是否消失或更改。这些信息应该证明对支持工程师是有用的。

按照“客户支持中心”中概述的步骤发送从故障排除步骤收集的信息。

Configuration Options

There are several configuration options when building the ThreadX library and the application using ThreadX. The options below can be defined in the application source, on the command line, or within the tx_user.h include file.

重要

Options defined in tx_user.h are applied only if the application and ThreadX library are built with TX_INCLUDE_USER_DEFINE_FILE defined.

配置选项

在使用ThreadX构建ThreadX库和应用程序时，有几个配置选项。下面的选项可以在应用程序源、命令行或tx_user.h include文件中定义。

重要

仅当应用程序和ThreadX库是使用定义的TX_INCLUDE_USER_DEFINE_FILE 文件构建的时，才会应用tx_user.h中定义的选项。

Smallest Configuration

For the smallest code size, the following ThreadX configuration options should be considered (in absence of all other options).

TX_DISABLE_ERROR_CHECKING
TX_DISABLE_PREEMPTION_THRESHOLD
TX_DISABLE_NOTIFY_CALLBACKS
TX_DISABLE_REDUNDANT_CLEARING
TX_DISABLE_STACK_FILLING
TX_NOT_INTERRUPTABLE
TX_TIMER_PROCESS_IN_ISR

最小配置

对于最小的代码大小，应该考虑以下ThreadX配置选项（在没有所有其他选项的情况下）。

Fastest Configuration

For the fastest execution, the same configuration options used for the Smallest Configuration previously, but with these options also considered.

TX_REACTIVATE_INLINE
TX_INLINE_THREAD_RESUME_SUSPEND

Detailed configuration options are described.

最快配置

对于最快的执行，以前用于最小配置的配置选项相同，但也考虑了这些选项。

Global Time Source

For other Microsoft Azure RTOS products (FileX, NetX, GUIX, USBX, etc.), ThreadX defines the number of ThreadX timer ticks that represents one second. Others derive their time requirements based on this constant. By default, the value is 100, assuming a 10ms periodic interrupt. The user may override this value by defining TX_TIMER_TICKS_PER_SECOND with the desired value in tx_port.h or within the IDE or command line.

全局时间源

对于其他Microsoft Azure RTOS产品（FileX、NetX、GUIX、USBX等），ThreadX定义表示1秒的ThreadX计时器计时信号数。其他人则根据这个常数得出他们的时间要求。默认情况下，该值为100，假设为10ms周期性中断。用户可以通过在tx_port.h或IDE或命令行中用所需值定义TX_TIMER_TICKS_PER_SECOND 来覆盖此值。

Detailed Configuration Options

TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO

When defined, this option enables the gathering of performance information on byte pools. By default, this option is not defined.

定义此选项后，可以收集字节池上的性能信息。默认情况下，未定义此选项。

TX_DISABLE_ERROR_CHECKING

Bypasses basic service call error checking. When defined in the application source, all basic parameter error checking is disabled. This may improve performance by as much as 30% and may also reduce the image size.

备注

It is only safe to disable error checking if the application can absolutely guarantee all input parameters are always valid under all circumstances, including input parameters derived from external input. If invalid input is supplied to the API with error checking disabled, the resulting behavior is undefined and could result in memory corruption or system crash.

备注

ThreadX API return values not affected by disabling error checking are listed in bold in the “Return Values” section of each API description in Chapter 4. The nonbold return values are void if error checking is disabled by using the TX_DISABLE_ERROR_CHECKING option.

禁用基本服务调用错误检查。在应用程序源中定义时，将禁用所有基本参数错误检查。这可以将性能提高高达30%，还可以减小镜像文件大小。

备注

只有当应用程序能够绝对保证所有输入参数在所有情况下都始终有效（包括从外部输入派生的输入参数）时，才可以安全地禁用错误检查。如果在禁用错误检查的情况下向API提供无效输入，则结果行为未定义，可能导致内存损坏或系统崩溃。

备注

不受禁用错误检查影响的ThreadX API返回值在第4章每个API描述的“返回值”部分以粗体列出。如果使用TX_DISABLE_ERROR_CHECKING 选项禁用错误检查，则非粗体返回值无效。

TX_DISABLE_NOTIFY_CALLBACKS

When defined, disables the notify callbacks for various ThreadX objects. Using this option slightly reduces code size and improves performance. By default, this option is not defined.

定义时，禁用各种ThreadX对象的notify回调。使用此选项可以略微减小代码大小并提高性能。默认情况下，未定义此选项。

TX_DISABLE_PREEMPTION_THRESHOLD

When defined, disables the preemption-threshold feature and slightly reduces code size and improves performance. Of course, the preemption-threshold capabilities are no longer available. By default, this option is not defined.

定义后，将禁用抢占阈值功能，并略微减小代码大小和提高性能。当然，抢占阈值功能不再可用。默认情况下，未定义此选项。

TX_DISABLE_REDUNDANT_CLEARING

When defined, removes the logic for initializing ThreadX global C data structures to zero. This should only be used if the compiler's initialization code sets all un-initialized C global data to zero. Using this option slightly reduces code size and improves performance during initialization. By default, this option is not defined.

定义后，删除将ThreadX global C数据结构初始化为零的逻辑。仅当编译器的初始化代码将所有未初始化的C全局数据设置为零时，才应使用此选项。使用此选项可以略微减小代码大小，并在初始化期间提高性能。默认情况下，未定义此选项。

TX_DISABLE_STACK_FILLING

When defined, disables placing the 0xEF value in each byte of each thread's stack when created. By default, this option is not defined.

定义时，禁止在创建时将0xEF值放置在每个线程堆栈的每个字节中。默认情况下，未定义此选项。

TX_ENABLE_EVENT_TRACE

When defined, ThreadX enables the event gathering code for creating a TraceX trace buffer.

定义后，ThreadX启用事件收集代码来创建TraceX跟踪缓冲区。

TX_ENABLE_STACK_CHECKING

When defined, enables ThreadX run-time stack checking, which includes analysis of how much stack has been used and examination of data pattern "fences" before and after the stack area. If a stack error is detected, the registered application stack error handler is called. This option does result in slightly increased overhead and code size. Review the tx_thread_stack_error_notify API function for more information. By default, this option is not defined.

定义后，启用ThreadX运行时堆栈检查，包括分析使用了多少堆栈以及检查堆栈区域前后的数据模式“fences”。如果检测到堆栈错误，则调用已注册的应用程序堆栈错误处理程序。此选项会导致开销和代码大小略微增加。有关详细信息，请查看tx_thread_stack_error_notify API函数。默认情况下，未定义此选项。

TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO

When defined, enables the gathering of performance information on event flags groups. By default, this option is not defined.

定义后，启用收集事件标志组的性能信息。默认情况下，未定义此选项。

TX_INLINE_THREAD_RESUME_SUSPEND

When defined, ThreadX improves the tx_thread_resume and tx_thread_suspend API calls via in-line code. This increases code size but enhances performance of these two API calls.

定义后，ThreadX通过内嵌代码改进了tx_thread_resume 和tx_thread_suspend API调用。这增加了代码大小，但提高了这两个API调用的性能。

TX_MAX_PRIORITIES

Defines the priority levels for ThreadX. Legal values range from 32 through 1024 (inclusive) and must be evenly divisible by 32. Increasing the number of priority levels supported increases the RAM usage by 128 bytes for every group of 32 priorities. However, there is only a negligible effect on performance. By default, this value is set to 32 priority levels.

定义ThreadX的优先级。合法值的范围从32到1024（含），并且必须能被32整除。增加支持的优先级级别的数量会使32个优先级的每组的RAM使用量增加128字节。但是，对性能的影响微乎其微。默认情况下，此值设置为32个优先级。

TX_MINIMUM_STACK

Defines the minimum stack size (in bytes). It is used for error checking when threads are created. The default value is port-specific and is found in tx_port.h.

定义最小堆栈大小（以字节为单位）。它用于在创建线程时进行错误检查。默认值是端口特定的，可以在tx_port.h中找到。

TX_MISRA_ENABLE

When defined, ThreadX utilizes MISRA C compliant conventions. Refer to ThreadX_MISRA_Compliance.pdf for details.

定义时，ThreadX使用符合MISRA C的约定。请参阅ThreadX_MISRA_Compliance.pdf详情。

TX_MUTEX_ENABLE_PERFORMANCE_INFO

When defined, enables the gathering of performance information on mutexes. By default, this option is not defined.

定义后，启用对互斥体的性能信息的收集。默认情况下，未定义此选项。

TX_NO_TIMER

When defined, the ThreadX timer logic is completely disabled. This is useful in cases where the ThreadX timer features (thread sleep, API timeouts, time-slicing, and application timers) are not utilized. If TX_NO_TIMER is specified, the option TX_TIMER_PROCESS_IN_ISR must also be defined.

定义后，ThreadX计时器逻辑将被完全禁用。这在ThreadX计时器特性（线程休眠、API超时、时间切片和应用程序计时器）未使用的情况下非常有用。如果指定了TX_NO_TIMER ，则还必须定义ISR中的TX_TIMER_PROCESS_IN_ISR 选项。

TX_NOT_INTERRUPTABLE

When defined, ThreadX does not attempt to minimize interrupt lockout time. This results in faster execution but does slightly increase interrupt lockout time.

定义时，ThreadX不会尝试最小化中断锁定时间。这会加快执行速度，但会略微增加中断锁定时间。

TX_QUEUE_ENABLE_PERFORMANCE_INFO

When defined, enables the gathering of performance information on queues. By default, this option is not defined.

定义后，启用队列性能信息的收集。默认情况下，未定义此选项。

TX_REACTIVATE_INLINE

When defined, performs reactivation of ThreadX timers inline instead of using a function call. This improves performance but slightly increases code size. By default, this option is not defined.

定义后，执行ThreadX 计时器的内联重新激活，而不是使用函数调用。这会提高性能，但会略微增加代码大小。默认情况下，未定义此选项。

TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO

When defined, enables the gathering of performance information on semaphores. By default, this option is not defined.

定义后，启用信号量性能信息的收集。默认情况下，未定义此选项。

TX_THREAD_ENABLE_PERFORMANCE_INFO

When defined, enables the gathering of performance information on threads. By default, this option is not defined.

定义后，启用线程上性能信息的收集。默认情况下，未定义此选项。

TX_TIMER_ENABLE_PERFORMANCE_INFO

When defined, enables the gathering of performance information on timers. By default, this option is not defined.

定义后，启用计时器性能信息的收集。默认情况下，未定义此选项。

TX_TIMER_PROCESS_IN_ISR

When defined, eliminates the internal system timer thread for ThreadX. This results in improved performance on timer events and smaller RAM requirements because the timer stack and control block are no longer needed. However, using this option moves all the timer expiration processing to the timer ISR level. By default, this option is not defined.

备注

Services allowed from timers may not be allowed from ISRs and thus might not be allowed when using this option.

定义后，消除ThreadX的内部系统计时器线程。由于不再需要计时器堆栈和控制块，因此这将提高计时器事件的性能并减少RAM需求。但是，使用此选项会将所有计时器过期处理移到计时器ISR级别。默认情况下，未定义此选项。

备注

计时器允许的服务可能不允许ISR提供，因此在使用此选项时可能不允许。

TX_TIMER_THREAD_PRIORITY

Defines the priority of the internal ThreadX system timer thread. The default value is priority 0—the highest priority in ThreadX. The default value is defined in tx_port.h.

定义内部ThreadX系统计时器线程的优先级。默认值是priority 0—ThreadX中的最高优先级。默认值在tx_port.h中定义。

TX_TIMER_THREAD_STACK_SIZE

Defines the stack size (in bytes) of the internal ThreadX system timer thread. This thread processes all thread sleep requests as well as all service call timeouts. In addition, all application timer callback routines are invoked from this context. The default value is port-specific and is found in tx_port.h.

定义内部ThreadX系统计时器线程的堆栈大小（以字节为单位）。此线程处理所有线程睡眠请求以及所有服务调用超时。此外，所有应用程序计时器回调例程都是从该上下文调用的。默认值是端口特定的，可以在tx_port.h中找到。

ThreadX Version ID

The programmer can obtain the ThreadX version from examination of the tx_port.h file. In addition, this file also contains a version history of the corresponding port. Application software can obtain the ThreadX version by examining the global string _tx_version_id.

ThreadX版本ID

程序员可以通过检查tx_port.h文件获得ThreadX版本。此外，此文件还包含相应端口的版本历史记录。应用软件可以通过检查全局字符串_tx_version_id来获取ThreadX版本。