The FreeRTOS kernel is now an MIT licensed AWS open source project, and these pages are being updated accordingly.

The FreeRTOS Ecosystem Showcase . . .
A Selection of Add-on and Complementary Products

Homepage

FreeRTOS+ Products

FreeRTOS Labs

Support Forum

Contact / Enquiries

FreeRTOS Labs

FreeRTOS+POSIX:
POSIX API for FreeRTOS

FreeRTOS+FAT:
Thread aware file system

FreeRTOS_ioctl()

[FreeRTOS+IO API]

FreeRTOS_IO.h

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

Short for Input Output Control, ioctl() is the standard name for functions that are used for input output device control, including device specific configuration. FreeRTOS_ioctl() is the FreeRTOS+IO equivalent. The action to be performed by a call to FreeRTOS_ioctl() is identified by the request code passed into FreeRTOS_ioctl() as the second parameter.

Parameters:

pxPeripheral	The descriptor associated with the peripheral the FreeRTOS_ioctl() call will affect. The descriptor will have been returned from the FreeRTOS_open() call used to open the peripheral.
ulRequest	The request code. Generic request codes are listed below. Board support package specific request codes are provided with the board support package documentation.
pvValue	A parameter that is specific to the request code being used. For example, where the request code is used to set a timeout value, the parameter is used to define the timeout. Many request codes do not require a parameter. When this is the case, for future compatibility, it is advised to set pvValue to NULL. pvValue is a void pointer so it can be used to pass any data type - be it a simple integer value (cast to a void *), or a pointer to a more complex data type.

Returns:

pdPASS is returned if the request code was processed successfully. pdFAIL is returned in other cases.

Example usage:

All these code examples assume the pxPort descriptor has already been opened, and is valid.

The example 1 code snippet demonstrates how to configure a peripheral to use the zero copy transfer mode. The pvValue parameter is not used with this request, so is set to NULL.


FreeRTOS_ioctl( pxPort, ioctlUSE_ZERO_COPY_TX, NULL );

Example 1: Configuring the peripheral associated with the pxPort descriptor to
use zero copy writes.

The example 2 code snippet demonstrates how to configure a peripheral's write timeout. In this case, the pvValue parameter is used to pass the timeout value in ticks. The constant portTICK_PERIOD_MS is used to convert 200 milliseconds into ticks.


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.

The example 3 code snippet demonstrates how to set the slave address associated with an I2C port. In this case, the pvValue parameter is used to pass the slave address to use, which is 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.

Request Code Reference

Request codes that set the transfer mode to use

The following request codes are used to set the transfer mode. The board support package documentation details which transfer modes are applicable to which peripherals.

Request Code	Description	Parameter
ioctlUSE_POLLED_TX	Configure the peripheral to use the polled transfer mode when writing bytes. All peripherals default to using the polled transfer mode when they are initially opened. Very few peripherals currently provide a means of returning to a polled transfer mode after an alternative mode has been manually selected.	Not used.
ioctlUSE_POLLED_RX	Configure the peripheral to use the polled transfer mode when reading bytes. All peripherals default to using the polled transfer mode when they are initially opened. Very few peripherals currently provide a means of returning to a polled transfer mode after an alternative mode has been manually selected.	Not used.
ioctlUSE_ZERO_COPY_TX	Configure the peripheral to use the interrupt driven zero copy transfer mode when writing bytes. This request code will enable the peripheral's interrupts, and set the peripheral's interrupt priority to the lowest possible value. The ioctlSET_INTERRUPT_PRIORITY request code can be used to raise the interrupt priority if required. Peripheral interrupt service routines are provided within the FreeRTOS+IO code, so do not need to be implemented by the application code.	Not used.
ioctlUSE_CHARACTER_QUEUE_TX	Configure the peripheral to use the interrupt driven character queue transfer mode when writing bytes. This request code will enable the peripheral's interrupts, and set the peripheral's interrupt priority to the lowest possible value. The ioctlSET_INTERRUPT_PRIORITY request code can be used to raise the interrupt priority if required. Peripheral interrupt service routines are provided within the FreeRTOS+IO code, so do not need to be implemented by the application.	The length, in bytes, of the queue used to hold bytes that are waiting to be written to the peripheral by the FreeRTOS+IO interrupt service routine. The queue is created by the FreeRTOS+IO code, and does not need to be created by the application code.
ioctlUSE_CHARACTER_QUEUE_RX	Configure the peripheral to use the interrupt driven character queue transfer mode when reading bytes. This request code will enable the peripheral's interrupts, and set the peripheral's interrupt priority to the lowest possible value. The ioctlSET_INTERRUPT_PRIORITY request code can be used to raise the interrupt priority if required. Peripheral interrupt service routines are provided within the FreeRTOS+IO code, so do not need to be implemented by the application.	The length, in bytes, of the queue used to hold bytes that have been received, but not yet returned by a call to FreeRTOS_read(). The queue is created by the FreeRTOS+IO code, and does not need to be created by the application code.
ioctlUSE_CIRCULAR_BUFFER_RX	Configure the peripheral to use the interrupt driven circular buffer transfer mode when reading bytes. This request code will enable the peripheral's interrupts, and set the peripheral's interrupt priority to the lowest possible value. The ioctlSET_INTERRUPT_PRIORITY request code can be used to raise the interrupt priority if required. Peripheral interrupt service routines are provided within the FreeRTOS+IO code, so do not need to be implemented by the application.	The length, in bytes, of the circular buffer used to hold characters received by the FreeRTOS+IO interrupt service routine, but not yet returned by a call to FreeRTOS_read(). The circular buffer is created by the FreeRTOS+IO code, and does not need to be allocated by the application code.

Request codes that affect the behaviour of a transfer mode

The following request codes are specific to one or more transfer modes.

Request Code	Description	Parameter
ioctlOBTAIN_WRITE_MUTEX	This request code is only applicable when the peripheral is using the interrupt driven zero copy transfer mode. When using the zero copy transfer mode, the peripheral's write mutex must be obtained before calling FreeRTOS_write(). ioctlOBTAIN_WRITE_MUTEX is a request to obtain the mutex. FreeRTOS_ioctl() returns pdPASS if the mutex was successfully obtained, and pdFAIL in all other cases. The FreeRTOS+IO interrupt service routine automatically releases the mutex when all the bytes have been written. Therefore, successfully obtaining the write mutex is also an indication that no writes are currently in progress, and the buffer that was being written is free for re-use. The mutex must be manually released using the ioctlRELEASE_WRITE_MUTEX request code if it is obtained by a task, but the task does not then call FreeRTOS_write(). See the ioctlWAIT_PREVIOUS_WRITE_COMPLETE for an alternative. See the the example code on the interrupt driven zero copy write transfer mode documentation page.	The maximum amount of time, in ticks, that the calling task will wait in the Blocked state for the mutex to become available. The portTICK_PERIOD_MS constant can be used to convert milliseconds into ticks. For example, to wait 50 milliseconds, specify a value of ( 50UL / portTICK_PERIOD_MS ).
ioctlWAIT_PREVIOUS_WRITE_COMPLETE	This request code is only applicable when the peripheral is using either the interrupt driven zero copy transfer mode, or the interrupt driven character queue transfer mode. ioctlWAIT_PREVIOUS_WRITE_COMPLETE results in the calling task being held in the Blocked state until the current write operation completes. It should be noted that only one task is removed from the Blocked state at a time. Therefore, if two tasks use the ioctlWAIT_PREVIOUS_WRITE_COMPLETE request code on the same peripheral simultaneously, then only the task with the highest priority will exit the Blocked state when the transmission is complete. See the the example code on the interrupt driven zero copy write transfer mode documentation page.	The maximum amount of time, in ticks, that the calling task will wait in the Blocked state for the current write operation to complete. The portTICK_PERIOD_MS constant can be used to convert milliseconds into ticks. For example, to wait 50 milliseconds, specify a value of ( 50UL / portTICK_PERIOD_MS ).
ioctlRELEASE_WRITE_MUTEX	This request code is only applicable when the peripheral is using the interrupt driven zero copy transfer mode. When using the zero copy transfer mode, the peripheral's write mutex must be obtained before calling FreeRTOS_write(). The mutex will then be automatically released by the FreeRTOS+IO interrupt service routine when the write is complete. The mutex must be manually released using the ioctlRELEASE_WRITE_MUTEX request code if it is obtained by a task, but the task does not then call FreeRTOS_write(). See also the ioctlWAIT_PREVIOUS_WRITE_COMPLETE and ioctlOBTAIN_WRITE_MUTEX request codes.	Not used.
ioctlSET_TX_TIMEOUT	This request code is only applicable when the peripheral is using the interrupt driven character queue transfer mode. When using the character queue transfer mode, FreeRTOS_write() places the bytes to be written into a queue. If there is not enough space in the queue to hold all the bytes, then the calling task is placed into the Blocked state to wait for more space to become available. ioctlSET_TX_TIMEOUT sets the maximum amount of time the task should remain in the Blocked state. FreeRTOS_write() returns the number of bytes successfully written to the queue, which will be less than the requested number of bytes if its write timeout expired.	The maximum amount of time, in ticks, that a task calling FreeRTOS_write() will remain in the Blocked state to wait for there to be enough space in the write queue for it to complete its FreeRTOS_write() operation. The portTICK_PERIOD_MS constant can be used to convert milliseconds into ticks. For example, to set a maximum block time of 50 milliseconds, use the value ( 50UL / portTICK_PERIOD_MS ).
ioctlSET_RX_TIMEOUT	This request code is only applicable when the peripheral is using either the interrupt driven character queue transfer mode, or the interrupt driven circular buffer transfer mode. When using one of these modes, FreeRTOS_read() returns bytes that have been buffered (in a queue or circular buffer) by the FreeRTOS+IO interrupt service routine. If the buffer does not already contain the requested number of bytes, then the task calling FreeRTOS_read() is held in the Blocked state to wait for more bytes to become available. ioctlSET_RX_TIMEOUT is used to set the maximum time the task will remain in the Blocked state. FreeRTOS_read() returns the number of bytes that were successfully read, which will be less than the requested number of bytes if its read timeout expired.	The maximum amount of time, specified in ticks, the task calling FreeRTOS_read() will remain in the Blocked state while it is waiting to complete its FreeRTOS_read() operation. The portTICK_PERIOD_MS constant can be used to convert milliseconds into ticks. For example, to set a maximum block time of 50 milliseconds, use the value ( 50UL / portTICK_PERIOD_MS ).
ioctlCLEAR_RX_BUFFER	This request code is only applicable when the peripheral is using either the interrupt driven character queue transfer mode, or the interrupt driven circular buffer transfer mode. When using one of these modes, FreeRTOS_read() returns bytes that have been buffered (in a queue or circular buffer) by the FreeRTOS+IO interrupt service routine. The ioctlCLEAR_RX_BUFFER request code will remove (and loose) bytes that are already contained in the buffer, leaving the buffer empty.	Not used.

Request codes that affect the behaviour of more than one type of peripheral

Request codes listed here are applicable to more than one peripheral type. The board support package documentation details which request codes are applicable to which peripheral.

Request Code	Description	Parameter
ioctlSET_SPEED	Configures the speed of a serial bus. For example, if the peripheral is a UART, this request code will set the UART baud rate. This request code is applicable to most, if not all, serial peripherals.	The absolute bus speed. For example, use 9600 to set the baud rate of a UART to 9600, use 200000 to set the SPI bus speed to 200000.
ioctlSET_INTERRUPT_PRIORITY	Sets the priority of interrupts generated by the peripheral. Note that, for all FreeRTOS ports that implement the configMAX_SYSCALL_INTERRUPT_PRIORITY setting, the priority assigned to an interrupt must be at or below the priority defined by configMAX_SYSCALL_INTERRUPT_PRIORITY.	The absolute value of the interrupt priority. On Cortex-M devices, the interrupt priority must be specified using the format expected by the CMSIS NVIC_SetPriority() function. Remember that Cortex-M devices use numerically low priority values to denote high interrupt priorities.

SPI specific request codes

Request Code	Description	Parameter
ioctlSET_SPI_DATA_BITS	Sets the number of data bits used in SPI transfers.	The number of data bits. For example, use 8 to specify that data uses 8 bits.
ioctlSET_SPI_CLOCK_PHASE	Sets the SPI clock phase (CPHA).	There are two valid values. boardSPI_SAMPLE_ON_LEADING_EDGE_CPHA_0: Use boardSPI_SAMPLE_ON_LEADING_EDGE_CPHA_0 to capture data on the leading clock edge (regardless of its polarity). boardSPI_SAMPLE_ON_LEADING_EDGE_CPHA_0 is equivalent to a CPHA value of 0. boardSPI_SAMPLE_ON_TRAILING_EDGE_CPHA_1: Use boardSPI_SAMPLE_ON_TRAILING_EDGE_CPHA_1 to capture data on the trailing clock edge (regardless of its polarity). boardSPI_SAMPLE_ON_TRAILING_EDGE_CPHA_1 is equivalent to a CPHA value of 1.
ioctlSET_SPI_CLOCK_POLARITY	Sets the polarity of the SPI clock (CPOL).	There are two valid values. boardSPI_CLOCK_BASE_VALUE_CPOL_1: Use boardSPI_CLOCK_BASE_VALUE_CPOL_1 to set the base value of the clock between frames to high, and the active clock to low. boardSPI_CLOCK_BASE_VALUE_CPOL_1 is equivalent to a CPOL value of 1. boardSPI_CLOCK_BASE_VALUE_CPOL_0: Use boardSPI_CLOCK_BASE_VALUE_CPOL_0 to set the base value of the clock between frames to low, and the active clock to high. boardSPI_CLOCK_BASE_VALUE_CPOL_0 is equivalent to a CPOL value of 0.
ioctlSET_SPI_MODE	Sets the bus into master or slave mode.	There are two valid values. boardSPI_MASTER_MODE: boardSPI_MASTER_MODE sets the SPI peripheral into master mode. boardSPI_SLAVE_MODE: boardSPI_SLAVE_MODE sets the SPI peripheral into slave mode. Note that slave mode is not yet supported.

I²C specific request codes

Request Code	Description	Parameter
ioctlSET_I2C_SLAVE_ADDRESS	Sets the address written to when the I2C peripheral is in master mode. All I2C transfers will use this address until it is changed by another ioctlSET_I2C_SLAVE_ADDRESS request.	The slave address to set. For example, use 0x20 to write to address 0x20.

[ Back to the top ] [ About FreeRTOS ] [ Privacy ] [ FreeRTOS+ Sitemap ] [ Main FreeRTOS Sitemap ] [ ]

The FreeRTOS Ecosystem Showcase . . . A Selection of Add-on and Complementary Products

FreeRTOS_ioctl() [FreeRTOS+IO API]