下载 FreeRTOS
 

出色的 RTOS & 嵌入式软件

库
首页
入门指南
所有库
最新资讯
简化任何设备的身份验证云连接。
带有 ExpressLink 的 Wi-Fi 和蜂窝连接模块如何帮助创建安全的云连接设备。请参阅博客文章。
利用 CoAP 设计节能型云连接 IoT 解决方案。
基于 UDP 的客户端/服务器、请求/响应协议，具有高效性和云兼容性。请参阅博客文章。
11.0.0 版 FreeRTOS 内核简介：
支持对称多处理 (SMP) 的重要版本。请参阅博客文章。
FreeRTOS 路线图和代码贡献流程。
FreeRTOS 路线图和代码贡献流程现已在此处和 GitHub 上发布。请参阅博客文章。
使用 FreeRTOS 实现 OPC-UA over TSN。
一个开发项目，旨在让应用程序能够一致地访问硬件 TSN 功能。请参阅博客文章。

FreeRTOS_ioctl()

[FreeRTOS-Plus-IO API]

FreeRTOS_IO.h 
BaseType_t FreeRTOS_ioctl( Peripheral_Descriptor_t const xPeripheral, 
                              uint32_t ulRequest, 
                              void *pvValue );

ioctl() 是输入输出控制的简称，一般作为标准名称表示 用于输入输出设备控制（包括设备特定配置）的函数 。 FreeRTOS_ioctl() 是 FreeRTOS-Plus-IO 的等效函数。 通过调用 FreeRTOS_ioctl() 执行的操作 由作为第二个参数传递到 FreeRTOS_ioctl() 的请求代码标识。

参数：

pxPeripheral   与 FreeRTOS_ioctl () 调用将影响的外围设备相关的描述符。 该描述符将 从用于开启外围设备的 FreeRTOS_open() 调用中返回。
ulRequest   请求代码。 通用请求代码如下文所列。 板级支持包特定的请求代码 随板级支持包 文档一起提供。
pvValue   所使用请求代码的特定参数。 例如，如果请求代码用于设置 超时值，则此参数用于定义 超时。

许多请求代码不需要参数。 在 这种情况下，为确保将来的兼容性， 建议将 pvValue 设置为 NULL。

pvValue 是一个 void 指针，因此可以用于传递 任何数据类型——无论是简单的整数值 （强制转换为 void *），还是指向更复杂 数据类型的指针。

返回：

如果请求代码已成功处理，返回 pdPASS。 其他情况则返回 pdFAIL。


用法示例：

所有这些代码示例均假定 pxPort 描述符已经 打开并且有效。

示例 1 代码片段展示了如何将外围设备配置为 使用零拷贝传输模式。 此处请求未使用 pvValue 参数， 因此该参数设置为 NULL。 



FreeRTOS_ioctl( pxPort, ioctlUSE_ZERO_COPY_TX, NULL );




Example 1: Configuring the peripheral associated with the pxPort descriptor to


use zero copy writes.


示例 2 代码片段展示了如何配置外围设备的 写入超时。 在这种情况下，pvValue 参数用于传递 以 tick 为单位的超时值。 常量 portTICK_PERIOD_MS 用于 将 200 毫秒转换为 tick 数。 



FreeRTOS_ioctl( pxPort, ioctlSET_TX_TIMEOUT, ( void * ) ( 200 / portTICK_PERIOD_MS ) );




Example 1: Configuring the write timeout for the peripheral associated with the

pxPort descriptor.


示例 3 代码片段展示了如何设置 与 I2C 端口相关的从地址。 在这种情况下， pvValue参数用于传递 待使用的从地址，即 0x20。 



FreeRTOS_ioctl( pxPort, ioctlSET_I2C_SLAVE_ADDRESS, ( void * ) 0x20 );




Example 1: Using FreeRTOS_ioctl() to set the slave address associated with an


I2C port.


请求代码参考

用于设置待使用传输模式的请求代码

以下请求代码用于设置传输模式。 板级支持包文档详细描述了 各种外围设备适用的传输模式。

请求代码 说明 参数
ioctlUSE_POLLED_TX 将外围设备配置为使用轮询传输模式写入 字节数据。

所有外围设备最初打开时均默认为 使用轮询传输模式。 目前很少有外围设备能够在 手动选择其他配置后返回到轮询传输模式 。

未使用。
ioctlUSE_POLLED_RX 将外围设备配置为使用轮询传输模式读取 字节数据。

所有外围设备最初打开时均默认为 使用轮询传输模式。 目前很少有外围设备能够在 手动选择其他配置后返回到轮询传输模式 。

未使用。
ioctlUSE_ZERO_COPY_TX 将外围设备配置为使用中断驱动的零拷贝传输模式 来写入字节数据。

此请求代码将启用外围设备的 中断，并将外围设备的中断优先级设置为最低 可能值。 ioctlSET_INTERRUPT_PRIORITY 请求代码可用于 在必要时提高中断优先级。

外围设备中断服务程序 在 FreeRTOS-Plus-IO 代码中提供，因此无需通过应用程序代码来实现 。

未使用。
ioctlUSE_CHARACTER_QUEUE_TX 将外围设备配置为使用中断驱动的字符队列传输模式 来写入字节数据。

此请求代码将启用外围设备的 中断，并将外围设备的中断优先级设置为最低 可能值。 ioctlSET_INTERRUPT_PRIORITY 请求代码可用于 在必要时提高中断优先级。

外围设备中断服务程序 在 FreeRTOS-Plus-IO 代码中提供，因此无需通过应用程序来实现。

队列长度（以字节为单位），该队列用于容纳 等待通过 FreeRTOS-Plus-IO 中断服务程序写入外围设备的字节数据。 队列由 FreeRTOS-Plus-IO 代码创建， 无需由应用程序代码创建。
ioctlUSE_CHARACTER_QUEUE_RX 将外围设备配置为使用中断驱动的字符队列传输模式 来读取字节数据。

此请求代码将启用外围设备的 中断，并将外围设备的中断优先级设置为最低 可能值。 ioctlSET_INTERRUPT_PRIORITY 请求代码可用于 在必要时提高中断优先级。

外围设备中断服务程序 在 FreeRTOS-Plus-IO 代码中提供，因此无需通过应用程序来实现。

队列长度（以字节为单位），该队列用于容纳 FreeRTOS_read() 调用已收到但尚未返回的字节数据。 队列由 FreeRTOS-Plus-IO 代码创建， 无需由应用程序代码创建。
ioctlUSE_CIRCULAR_BUFFER_RX 将外围设备配置为使用中断驱动的循环缓冲区传输模式来读取字节数据。

此请求代码将启用外围设备的 中断，并将外围设备的中断优先级设置为最低 可能值。 ioctlSET_INTERRUPT_PRIORITY 请求代码可用于 在必要时提高中断优先级。

外围设备中断服务程序 在 FreeRTOS-Plus-IO 代码中提供，因此无需通过应用程序来实现。

循环缓冲区的长度（以字节为单位），该缓冲区用于容纳 FreeRTOS-Plus-IO 中断服务程序已接收， 但 FreeRTOS_read() 调用尚未返回的字符数据。 循环缓冲区由 FreeRTOS-Plus-IO 代码创建， 无需由应用程序代码分配。


影响传输模式行为的请求代码

以下请求代码适用于一种或多种传输模式。

请求代码 说明 参数
ioctlOBTAIN_WRITE_MUTEX 此请求代码仅适用于以下情况：外围设备正在使用 中断驱动的零拷贝传输模式。

当使用零拷贝传输模式时，必须 在调用 FreeRTOS_write() 之前获得外围设备的写互斥锁。 ioctlOBTAIN_WRITE_MUTEX 是 用来获取互斥锁的请求。

如果成功获得互斥锁，FreeRTOS_ioctl() 返回 pdPASS， 其他任何情况则返回 pdFAIL。

FreeRTOS-Plus-IO 中断服务程序会在所有字节数据都已写入时自动释放 互斥锁。 因此，成功 获得写互斥锁也表示当前没有正在进行的写操作， 之前写入的缓冲区已被释放，可供重新使用 。

如果 互斥锁是通过任务获得，但该任务后来并未调用 FreeRTOS_write()，则必须使用 ioctlRELEASE_WRITE_MUTEX 请求代码手动释放互斥锁。 请参阅 ioctlWAIT_PREVIOUS_WRITE_COMPLETE， 了解 替代方案。

有关示例代码，请参阅 中断驱动的零拷贝写入传输模式 文档页面。

调用任务的最大等待时间（以 tick 为单位）， 调用任务将保持在阻塞状态，以等待 互斥锁变为可用。

常量 portTICK_PERIOD_MS 可用于将毫秒数转换为 tick 数。 例如，要等待 50 毫秒，则指定值 ( 50UL / portTICK_PERIOD_MS ) 即可。

ioctlWAIT_PREVIOUS_WRITE_COMPLETE 此请求代码仅适用于以下情况：外围设备正在使用 中断驱动的零拷贝传输模式 或中断驱动的字符队列传输模式。

ioctlWAIT_PREVIOUS_WRITE_COMPLETE 可使调用任务 保持在阻塞状态，直到当前写入操作完成。

请注意，每次只能从已阻塞状态移除一个任务 。 因此，如果有两个任务同时对同一外围设备使用 ioctlWAIT_PREVIOUS_WRITE_COMPLETE 请求代码，则在传输完成时 仅具有最高优先级的任务将退出已阻塞状态 。

有关示例代码，请参阅 中断驱动的零拷贝写入传输模式 文档页面。

调用任务的最大等待时间（以 tick 为单位）， 调用任务将保持在阻塞状态，以等待当前写入操作完成。

常量 portTICK_PERIOD_MS 可用于将毫秒数转换为 tick 数。 例如，要等待 50 毫秒，则指定值 ( 50UL / portTICK_PERIOD_MS ) 即可。

ioctlRELEASE_WRITE_MUTEX 此请求代码仅适用于以下情况：外围设备正在使用 中断驱动的零拷贝传输模式。

当使用零拷贝传输模式时，必须 在调用 FreeRTOS_write() 之前获得外围设备的写互斥锁。 当写入完成后，该互斥锁会被 FreeRTOS-Plus-IO 中断服务程序自动释放。

如果 互斥锁是通过任务获得，但该任务后来并未调用 FreeRTOS_write()，则必须使用 ioctlRELEASE_WRITE_MUTEX 请求代码手动释放互斥锁。 另请参阅 ioctlWAIT_PREVIOUS_WRITE_COMPLETE 和 ioctlOBTAIN_WRITE_MUTEX 请求代码。

未使用。
ioctlSET_TX_TIMEOUT 此请求代码仅适用于以下情况：外围设备正在使用 中断驱动的字符队列传输模式。

当使用字符队列传输模式时，FreeRTOS_write() 会将待写入的字节数据放置在一个队列中 。 如果队列中没有足够的空间 来容纳所有字节数据，那么调用任务 将进入已阻塞状态，以等待更多空间 变为可用。 ioctlSET_TX_TIMEOUT 用来设置任务应保持在已阻塞状态的最大时间 。 FreeRTOS_write() 可返回 成功写入队列的字节数据的数目， 如果写超时到期，此数目将小于请求的字节数 。

FreeRTOS_write() 调用任务的最大等待时间（以 tick 为单位）， 调用任务将保持在已阻塞状态，以等待写队列中有足够的空间 来完成其 FreeRTOS_write() 操作。

常量 portTICK_PERIOD_MS 可用于将毫秒数转换为 tick 数。 例如，要设置最大阻塞时间为 50 毫秒， 则使用值 ( 50UL / portTICK_PERIOD_MS ) 即可。

ioctlSET_RX_TIMEOUT 此请求代码仅适用于以下情况：外围设备正在使用 中断驱动的字符队列传输模式 或中断驱动的循环缓冲区传输模式。

使用这些模式时，FreeRTOS_read() 会返回 FreeRTOS-Plus-IO 中断服务程序（在队列或循环缓冲区中）已缓冲的字节数据 。 如果缓冲区中所含字节数据的数目未达到 请求的字节数，那么 FreeRTOS_read() 调用任务 将进入已阻塞状态，以等待更多字节 变为可用。 ioctlSET_RX_TIMEOUT 用于设置任务将保持在已阻塞状态的最大时间 。 FreeRTOS_read() 会返回已成功读取的字节数据的数目， 如果读超时到期，此数目将小于请求的字节数 。

FreeRTOS_read() 调用任务的最大等待时间（以 tick 为单位）， 调用任务将保持在已阻塞状态，以等待 其 FreeRTOS_read() 操作完成。

常量 portTICK_PERIOD_MS 可用于将毫秒数转换为 tick 数。 例如，要设置最大阻塞时间为 50 毫秒， 则使用值 ( 50UL / portTICK_PERIOD_MS ) 即可。

ioctlCLEAR_RX_BUFFER 此请求代码仅适用于以下情况：外围设备正在使用 中断驱动的字符队列传输模式 或中断驱动的循环缓冲区传输模式。

使用这些模式时，FreeRTOS_read() 会返回 FreeRTOS-Plus-IO 中断服务程序（在队列或循环缓冲区中）已缓冲的字节数据 。 ioctlCLEAR_RX_BUFFER 请求代码 将移除（和释放）缓冲区中已含有的字节数据， 使缓冲区清空。

未使用。


可影响多种外围设备行为的请求代码

下列请求代码 适用于多种外围设备类型。 板级支持包 文档中详细说明了各种外围设备适用的请求代码。

请求代码 说明 参数
ioctlSET_SPEED 配置串行总线的速度。 例如，如果外围设备是 UART， 则此请求代码将设置 UART 波特率。 此请求代码 适用于大多数（如非全部）串行外围设备。 绝对总线速度。 例如，使用 9600 将 UART 的波特率设为 9600，使用 200000 将 SPI 总线速度设置为 200000。
ioctlSET_INTERRUPT_PRIORITY 设置由外围设备生成中断的优先级。

请注意，对于所有 FreeRTOS 移植，如果其使用 configMAX_SYSCALL_INTERRUPT_PRIORITY 设置，则分配给中断的优先级必须等于或低于 configMAX_SYSCALL_INTERRUPT_PRIORITY 定义的优先级。

中断优先级的绝对值。

在 Cortex-M 设备上，必须使用 CMSIS NVIC_SetPriority() 函数所需的格式来指定中断优先级。 请注意， Cortex-M 设备使用数字低序值表示高中断优先级。


SPI 特定请求代码

请求代码 说明 参数
ioctlSET_SPI_DATA_BITS 设置 SPI 传输中使用的数据位数。 数据位数。 例如，使用 8 指定数据 使用 8 个位。
ioctlSET_SPI_CLOCK_PHASE 设置 SPI 时钟的相位 (CPHA)。 有两个有效值。
  • boardSPI_SAMPLE_ON_LEADING_EDGE_CPHA_0： 使用 boardSPI_SAMPLE_ON_LEADING_EDGE_CPHA_0 在前时钟沿捕获数据（无论其 极性如何）。 boardSPI_SAMPLE_ON_LEADING_EDGE_CPHA_0 等效于值为 0 的 CPHA。

  • boardSPI_SAMPLE_ON_TRAILING_EDGE_CPHA_1： 使用 boardSPI_SAMPLE_ON_TRAILING_EDGE_CPHA_1 在后时钟沿捕获数据（无论其极性如何）。 boardSPI_SAMPLE_ON_TRAILING_EDGE_CPHA_1 等效于 值为 1 的 CPHA。
ioctlSET_SPI_CLOCK_POLARITY 设置 SPI 时钟的极性 (CPOL)。 有两个有效值。
  • boardSPI_CLOCK_BASE_VALUE_CPOL_1： 使用 boardSPI_CLOCK_BASE_VALUE_CPOL_1 可将帧间时钟信号基值设为高电平，而有效时钟信号设为低电平 。 boardSPI_CLOCK_BASE_VALUE_CPOL_1 等效于值为 1 的 CPOL 。

  • boardSPI_CLOCK_BASE_VALUE_CPOL_0： 使用 boardSPI_CLOCK_BASE_VALUE_CPOL_0 可将帧间时钟信号基值设为低电平，而有效时钟信号设为高电平。boardSPI_CLOCK_BASE_VALUE_CPOL_0 等效于值为 0 的 CPOL。
ioctlSET_SPI_MODE 将总线设置为主模式或从模式。 有两个有效的值。
  • boardSPI_MASTER_MODE： boardSPI_MASTER_MODE 将 SPI 外围设备 设置为主模式。

  • boardSPI_SLAVE_MODE： boardSPI_SLAVE_MODE 将 SPI 外围设备设置为从模式。 请注意，暂且不支持从模式。


I2C 特定请求代码

请求代码 说明 参数
ioctlSET_I2C_SLAVE_ADDRESS 设置 I2C 外围设备处于主模式时的写入地址。 所有的 I2C 传输 均将使用此地址，直到其因另一个 ioctlSET_I2C_SLAVE_ADDRESS 请求而发生变更 。 待设置的从地址。 例如，要写入地址 0x20，使用 0x20 即可。
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.