Перевод может содержать ошибки. Читайте первоисточник: xStreamBufferCreateStatic(), xStreamBufferCreateStaticWithCallback()
| Назад: [xStreamBufferCreateStatic()] | Вверх: [ИПП: Буферы потока] | Вперёд: [xStreamBufferSend()] |
Функция объявляется в файле stream_buffer.h, кроме того, в проект должен быть включён файл исходного кода FreeRTOS/source/stream_buffer.c.
StreamBufferHandle_t xStreamBufferCreateStaticWithCallback(
size_t xBufferSizeBytes,
size_t xTriggerLevelBytes,
uint8_t *pucStreamBufferStorageArea,
StaticStreamBuffer_t *pxStaticStreamBuffer,
StreamBufferCallbackFunction_t pxSendCompletedCallback,
StreamBufferCallbackFunction_t pxReceiveCompletedCallback );
Функция создаёт новый буфер потока, используя статически выделенную память.
Для того, чтобы функция xStreamBufferCreateStaticWithCallback() была доступна, параметр configSUPPORT_STATIC_ALLOCATION в файле FreeRTOSConfig.h должен быть установлен в 1 (не определённым оставлять нельзя, т.к. по-умолчанию определяется как 0). Дополнительно должен быть установлен в 1 параметр configUSE_SB_COMPLETED_CALLBACK (по-умолчанию также определяется как 0).
Буфер потока выполняет соответствующий обратный вызов после завершения каждой операции отправки и получения. Буферы потока, созданные с помощью вызова ИПП xStreamBufferCreateStaticWithCallback(), НЕ используют общие для всех функции обратного вызова, определяемые с помощью макросов sbSEND_COMPLETED() и sbRECEIVE_COMPLETED(). В отличие от xStreamBufferCreateStatic() используются индивидуальные функции обратного вызова. Если индивидуальные функции не требуются, достаточно буферов потока, создаваемых вызовом xStreamBufferCreateStatic().
Если требуется размещать буферы потока в динамически выделяемой памяти (в куче FreeRTOS), используйте соответствующие вызовы xStreamBufferCreate() и xStreamBufferCreateWithCallback(). Более подробно отличия динамического и статического распределения ОЗУ описаны здесь.
Параметры
| xBufferSizeBytes | Общее количество байт, которое буфер потока может хранить одновременно. |
| xTriggerLevelBytes | Уровень срабатывания. Это количество байт, которое должно появиться в буфере потока, чтобы задача, заблокированная на ожидании данных в буфере потока, была выведена из заблокированного состояния. Например, если задача заблокирована при чтении из пустого буфера потока, у которого уровень срабатывания установлен равным 1, то задача будет разблокирована, когда в буфер потока будет записан один байт или когда истечёт время блокировки на ожидании данных в буфере потока. Ещё пример: если некая задача заблокирована на чтении пустого буфера потока с установленным уровнем срабатывания 10, то эта задача не будет разблокироваться до тех пор, пока в буфере не накопится как минимум 10 байт или пока не истечёт время блокировки задачи. Если время блокировки читающей задачи истечёт до достижения уровня срабатывания, то задача сможет получить столько байт, сколько будет фактически доступно. Установка уровня срабатывания в 0 приведёт к использованию уровня срабатывания 1. И, разумеется, недопустимо устанавливать уровень срабатывания, превышающий размер буфера. |
| pucStreamBufferStorageArea | Параметр должен указывать на массив элементов uint8_t, размером не менее xBufferSizeBytes + 1 байт. Это массив, в который копируются данные при записи в буфер потока. |
| pxStaticStreamBuffer |
Параметр должен указывать на переменную с типом StaticStreamBuffer_t, которая используется для хранения структуры данных буфера потока. |
| pxSendCompletedCallback |
Функция обратного вызова, которая вызывается, если запись в буфер приводит к тому, что количество байт в буфере потока становится больше уровня срабатывания. Если параметр задан равным NULL, будет использована реализация по-умолчанию, которая предоставляется макросом sbSEND_COMPLETED. Функция обратного вызова, выполняемая при записи в буфер, должна иметь прототип, определяемый с помощью StreamBufferCallbackFunction_t, и выглядит он следующим образом: |
| pxReceiveCompletedCallback |
Функция обратного вызова, которая вызывается, если из буфера потока были считаны данные (больше нуля байтов). Если параметр задан NULL, будет использована реализация по-умолчанию, которая предоставляется макросом sbRECEIVE_COMPLETED. Функция обратного вызова, выполняемая при завершении приёма, должна иметь прототип, определяемый с помощью StreamBufferCallbackFunction_t, и выглядит он следующим образом: |
Возвращаемое значение
Если буфер потока успешно создан, будет возвращён указатель на хэндлер буфера потока.
Если же хотя бы один из параметров pucStreamBufferStorageArea и pxStaticstreamBuffer при вызове был указан равным NULL, то и возвращено будет значение NULL.
Пример использования:
/* Общее количество байтов, которое буфер потока
может хранить в любой момент времени. */
#define STREAM_BUFFER_SIZE_BYTES 1000
/* Место в памяти, где буфер потока фактически хранит данные.
Обратите внимание, что места буферу потока требуется на 1 байт больше,
чем количество одновременно хранимых байт: (STREAM_BUFFER_SIZE_BYTES + 1). */
static uint8_t ucStreamBufferWithCallbackStorage[ STREAM_BUFFER_SIZE_BYTES + 1 ];
/* Переменная для хранения структуры буфера потока. */
StaticStreamBuffer_t xStreamBufferWithCallbackStruct;
void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
/* Здесь должен быть размещён код, который вызывается, когда операция
записи данных в буфер потока приводит к тому, что число байтов в буфере
становится больше уровня срабатывания. Это полезно, когда потоковый буфер
используется для передачи данных между ядрами многоядерного процессора.
В таком сценарии этот обратный вызов может быть реализован для активации
прерывания в другом ядре ЦП, а обработчик прерывания может затем
использовать функцию API xStreamBufferSendCompletedFromISR()
для проверки и, при необходимости, разблокировки задачи, ожидающей данные. */
}
void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
BaseType_t xIsInsideISR,
BaseType_t * const pxHigherPriorityTaskWoken )
{
/* Здесь может быть размещён код, который вызывается при чтении данных
из буфера потока. Это полезно, когда буфер потока используется для передачи
данных между ядрами многоядерного процессора. В таком сценарии этот
обратный вызов может быть реализован для активации прерывания в другом
ядре ЦП, а обработчик прерывания может затем использовать функцию ИПП
xStreamBufferReceiveCompletedFromISR() для проверки и, при необходимости,
разблокировки задачи, ожидающей отправки данных. */
}
void MyFunction( void )
{
StreamBufferHandle_t xStreamBufferWithCallback;
const size_t xTriggerLevel = 1;
/* Создаём буфер потока, который использует функции vSendCallbackFunction
и vReceiveCallbackFunction в качестве функций обратного вызова для отправки и
получения завершенных данных. */
xStreamBufferWithCallback = xStreamBufferCreateStaticWithCallback(
STREAM_BUFFER_SIZE_BYTES,
xTriggerLevel,
ucStreamBufferWithCallbackStorage,
&xStreamBufferWithCallbackStruct,
vSendCallbackFunction,
vReceiveCallbackFunction );
/* Поскольку параметры pucStreamBufferStorageArea и pxStaticStreamBuffer
не были равны NULL, xStreamBufferWithCallback не будет
равен NULL и может использоваться для ссылки на созданный потоковый буфер
в других вызовах функций ИПП потоковых буферов. */
/* Здесь может располагаться некоторый код, использующий буфер потока. */
}