FreeRTOS_IO.h
size_t FreeRTOS_write( Peripheral_Descriptor_t const pxPeripheral,
const void *pvBuffer,
const size_t xBytes );
Writes one or more bytes to an open peripheral.
The board support package
defines the peripherals that are available to be opened. FreeRTOS_ioctl()
is used to select between interrupt driven and polled write modes.
Parameters:
pxPeripheral
|
The descriptor associated with the peripheral to
which bytes are being written. The descriptor will have
been returned from the
FreeRTOS_open()
call used to open the peripheral.
|
pvBuffer
|
A pointer to the first byte of data to write.
|
xBytes
|
The total number of bytes to write.
When an interrupt driven transfer mode
is being used, the actual number of bytes written to a peripheral may
be less than the requested number if not all the bytes
could be written before the peripheral's write timeout
expired. FreeRTOS_ioctl() is used
to set the write timeout value.
|
Returns:
When the polled transfer mode
is used, the returned value is the total number
of bytes actually written to the peripheral. This will be the total number
requested assuming no errors occurred.
When the interrupt driven character queue transfer mode
is used,
the returned value is the total number of bytes actually written
to the write queue. This will be less than the requested number
of bytes if there was not enough space in the queue for all the
bytes to be written immediately, and the peripheral's write timeout
expired before enough space became available. The actual transmission
of data is controlled
by the FreeRTOS-Plus-IO interrupt service routine, and may complete after
the call to FreeRTOS_write() has returned.
When the interrupt driven zero copy transfer mode
is used, then:
-
If the task calling FreeRTOS_write() holds the write mutex,
the returned value will be the total number of bytes to transmit,
assuming no errors occurred. The actual transmission of data
is controlled by the FreeRTOS-Plus-IO interrupt service routine, and
may complete after the call to FreeRTOS_write() has returned.
-
If the task calling FreeRTOS_write() does not hold the write
mutex, or if FreeRTOSIOConfig.h is not configured to include
the zero copy write transfer mode for the peripheral, then
zero is returned.
FreeRTOS_ioctl() is used to set
the write timeout value.
Example usage:
The example 1 code snippet demonstrates how to perform a write when a peripheral
is configured to use the polled transfer mode. Peripherals
default to polled mode when they are opened.
xBytesWritten = FreeRTOS_write( xPort, ucBuffer, sizeof( ucBuffer ) );
configASSERT( xBytes == sizeof( ucBuffer ) );
Example 1: Writing bytes to a peripheral that is configured to use the polled transfer mode.
The example 2 code snippet demonstrates how to perform a write when a peripheral
is configured to use the interrupt driven character queue transfer mode.
In this mode, the task making the FreeRTOS_write() call is held in the
Blocked state (not using any CPU time) until either all the requested number of
bytes have been sent to the queue, or the write timeout expires. FreeRTOS_ioctl()
is used with the ioctlSET_TX_TIMEOUT request code to configure
the write timeout, and the ioctlWAIT_PREVIOUS_WRITE_COMPLETE request code
wait for the write queue to be empty.
xBytesWritten = FreeRTOS_write( xPort, ucBuffer, sizeof( ucBuffer ) );
if( xBytesWritten < sizeof( ucBuffer ) )
{
}
else
{
}
Example 2: Writing bytes to a peripheral that is configured to use the interrupt
driven character queue transfer mode.
The example 3 code snippet demonstrates how to perform a write when a peripheral
is configured to use the interrupt driven zero copy transfer mode.
In this mode, the task making the FreeRTOS_write() call will always return
immediately. If the returned value equals the number of bytes that
are to be written, then the FreeRTOS_write() call successfully started
the interrupt driven transmission. If the returned value equals zero, then
the FreeRTOS_write() call could not start the transmission, either because it did
not hold the write mutex, or because FreeRTOSIOConfig.h was not configured to support it.
xMutexObtained = FreeRTOS_ioctl( xPort,
ioctlOBTAIN_WRITE_MUTEX,
( void * ) ( 50 / portTICK_PERIOD_MS ) );
if( xMutexObtained != pdFAIL )
{
xBytesWritten = FreeRTOS_write( xPort, ucBuffer, sizeof( ucBuffer ) );
configASSERT( xBytesWritten == sizeof( ucBuffer ) );
xMutexObtained = FreeRTOS_ioctl( xPort,
ioctlOBTAIN_WRITE_MUTEX,
( void * ) ( 50 / portTICK_PERIOD_MS ) );
if( xMutexObtained != pdFAIL )
{
FreeRTOS_ioctl( xPort, ioctlRELEASE_WRITE_MUTEX, NULL );
}
}
Example 3: Writing bytes to a peripheral that is configured to use the interrupt
driven zero copy transfer mode.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.