PIC24 tnkernel:ref:dqueue

TNKernel : Очереди сообщений

2008-07-21T01:38:46+03:00

TNKernel : Очереди сообщений

Введение

Очередь сообщений - это объект RTOS, предназначенный для передачи данных между задачами и между прерываниями и задачами.

В не RTOS системе передача данных между различными подпрограммами, которые вызываются в бесконечном цикле (условно их можно назвать задачами), происходит, как правило, с помощью глобальных переменных.

Однако в многозадачной системе использование глобальных переменных крайне не рекомендуется - так как вытеснение может произойти в любой момент, необходимо реализовать для доступа к глобальной переменной критическую секцию, что может привести к значительной трате ресурсов. Поэтому передача данных в RTOS как правило реализуется с помощью специальных объектов - очередей сообщений.

Кроме защиты сообщений, объект реализует очередь, то есть возможность передать несколько сообщений, которые могут быть обработаны принимающей стороной позднее.

Очередь сообщений ассоциируется со структурой управления и буфером сообщений. Буфер является очередью типа FIFO, т.е. первым будет получено сообщение, которое отправлено раньше.

В TNKernel под сообщением (т.е. элементом, который хранится в буфере) понимается указатель на данные, а не сами данные. Другими словами - сообщение это не данные, а указатель на данные. Такой подход имеет как плюсы, так и минусы.

Плюсы:

объем передаваемых данных может быть сколь угодно большим - в качестве сообщения можно передавать указатель на структуру или массив
маленький размер буфера, так как в нем хранятся только указатели на данные

Минусы:

данные по передаваемому указателю не могут быть изменены до тех пор, пока сообщение не будет принято и обработано. Это можно обойти, используя пересылку с подтверждением, либо блоки памяти фиксированного размера.

Тем не менее, в качестве сообщения можно передавать не указатель, а например, код команды - для этого необходимо явно привести типы при передаче параметров в сервисы отсылки и приема сообщения.

Основными сервисами управления очередями сообщений являются отсылка сообщения и прием сообщения.

Если задача вызывает сервис приема сообщения, а в буфер очереди пуст, задача переводится в состояние ожидания, до тех пор, пока сообщение не будет отправлено другой задачей или пока не истечет таймаут.

В TNKernel будет запущена задача, которая стоит первой в очереди задач ожидающих сообщение, вне зависимости от приоритетов задач в очереди.

Если задача вызывает сервис передачи сообщения, а буфер сообщения полон, то она переводится в состояние ожидания до тех пор, пока хотя бы одно сообщение не будет принято.

Структура управления очередью сообщений

Каждая очередь сообщений ассоциируется со структурой управления:

typedef struct _TN_DQUE_S
{
    CDLL_QUEUE_S        wait_send_list;
    CDLL_QUEUE_S        wait_receive_list;
 
    void             ** data_fifo;
    TN_UWORD            num_entries;
    TN_UWORD            tail_cnt;
    TN_UWORD            header_cnt;
    TN_OBJ_ID           id_dque;
} TN_DQUE_S;

В состав структуры очереди входят следующие элементы:

`wait_send_list`	Очередь задач, посылающих сообщение
`wait_receive_list`	Очередь задач, принимающих сообщение
`data_fifo`	Указатель на буфер сообщений. Буфер сообщений это массив указателей на `void`
`num_entries`	Объем буфера (максимальное количество сообщений в очереди)
`tail_cnt`	Индекс принимаемого сообщения
`header_cnt`	Индекс отсылаемого сообщения
`id_dque`	Поле идентификации объекта как очереди сообщений

Структура очереди сообщений доступна только при определении TN_DEBUG. Тем не менее, прямой доступ к элементам структуры крайне не рекомендуется, так как это является вмешательством в работу планировщика и других сервисов RTOS.

Сервисы управления очередями сообщений

TNKernel имеет следующий набор функций (сервисов) для управления очередями сообщений:

Сервис	Описание	Свойства
Создание и удаление очереди сообщений
tn_queue_create()	Создание очереди
tn_queue_delete()	Удаление очереди
Отсылка сообшения
tn_queue_send()	Отсылка сообшения
tn_queue_send_polling()	Отсылка сообщения без блокировки задачи
tn_queue_isend_polling()	Отсылка сообщения из прерывания
Прием сообщения
tn_queue_receive()	Прием сообщения
tn_queue_receive_polling()	Прием сообщения без блокировки задачи
tn_queue_ireceive()	Прием сообщения в прерывании

tn_queue_create()

2009-11-17T16:54:10+03:00

tn_queue_create()

Функция предназначена для создания очереди сообщений. Поле id_dque очереди dque должно быть равно нулю до момента создания, таким образом уже созданные очереди защищаются от повторного создания.

Память для управляющей структуры dque и буфера сообщений должна быть выделена до момента создания очереди. Память может быть выделена на этапе компиляции (объявление глобальной переменной типа TN_DQUE для управляющей структуры и массива с элементами типа *void для буфера), либо динамически, если пользовательское приложение использует менеджер памяти. В последнем случае размер буфера сообщений должен быть равен (в байтах) (sizeof(*void) · num_entries)

Вызов:

TN_RETVAL tn_queue_create (TN_DQUE   *dque,
                           void     **data_fifo,
                           TN_UWORD   num_entries
                          );

Разрешен вызов:

В контексте задачи, в пользовательской критической секции, в прерывании

Параметры функции:

dque: указатель на объект очереди сообщений. Структура dque типа TN_DQUE должна быть создана до момента вызова функции, статически или динамически
data_fifo: указатель на буфер сообщений, который представляет собой массив элементов типа *void. Параметр может быть равен 0 или TN_NULL - в этом случае сервисы будут возвращать код ошибки TERR_OUT_OF_MEM.
num_entries: размер буфера сообщений. Другими словами, максимальное количество сообщений, хранимых в очереди. Параметр должен быть равен количеству элементов в массиве data_fifo. Если указатель data_fifo равен 0 или TN_NULL, значение параметра может быть произвольным.

Внимание! Количество элементов очереди должно быть фактически на 1 больше, чем планируется использовать. Т.е. если num_entries = 2, то в очереди будет хранится один элемент и при попытке передачи второго сервис вернет ошибку. Не следует использовать очередь с одним элементом.

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_EXS: попытка создания очереди, которая уже создана
TERR_NO_ERR: успешное выполнение

Пример вызова:

#define QUEUE_SIZE    8
 
TN_DQUE  queue                   TN_DATA;  /* объект типа очередь */
void     *queue_fifo[QUEUE_SIZE] TN_DATA;  /* буфер сообщений     */
 
tn_queue_create(&queue, queue_fifo, QUEUE_SIZE);

К списку сервисов

¹⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_queue_delete()

2008-07-21T00:48:26+03:00

tn_queue_delete()

Функция предназначена для удаления очереди сообщений. Поле id_dque очереди dque после выполнения сервиса устанавливается в 0.

Все задачи, ожидающие сообщения или ожидающие освобождения очереди будут переведены в состояние готовности к выполнению - сервисы приема и отсылки сообщения вернут код TERR_DLT.

Вызов:

TN_RETVAL tn_queue_delete (TN_DQUE *dque);

Разрешен вызов:

В контексте задачи

Параметры функции:

dque: указатель на очередь сообщений

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_NOEXS: попытка удаления объекта, не являющегося очередью сообщений ²⁾
TERR_WCONTEXT: вызов функции из пользовательской критической секции или из обработчика прерывания
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_DQUE  queue TN_DATA;
 
tn_queue_delete(&queue);

К списку сервисов

¹⁾ , ²⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_queue_ireceive()

2008-05-06T17:39:24+03:00

tn_queue_ireceive()

Функция предназначена для приема сообщения через очередь сообщений dque в прерывании. Принятое сообщение (точнее говоря адрес сообщения) сохраняется по указателю data_ptr.

Если буфер очереди сообщений не пуст, функция передает первое сообщение в буфере по указателю data_ptr. Таким образом, после выхода из сервиса data_ptr будет указывать на сообщение, которое было отправлено через очередь. Если есть задача (задачи) ожидающая освобождения буфера для того чтобы отправить сообщение - эта задача будет переведена в состояние готовых к выполнению, а ее сообщение будет положено в очередь.

Если буфер очереди сообщений пуст, функция возвращает код ошибки TERR_TIMEOUT.

Вызов:

TN_RETVAL tn_queue_ireceive (TN_DQUE *dque, void **data_ptr);

Разрешен вызов:

В обработчике прерывания

Параметры функции:

dque: указатель на объект очереди сообщений.
data_ptr: указатель на указатель, в который сохраняется адрес сообщения

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка обращения к объекту, который не является очередью (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_WCONTEXT: вызов сервиса в пользовательской критической секции или в контексте задачи
TERR_TIMEOUT: очередь сообщений пуста
TERR_NO_ERR: успешное выполнение

Пример вызова:

extern TN_DQUE  queue TN_DATA;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    MY_MSG   message;
 
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
 
    if (tn_queue_ireceive(&queue, &message) == TERR_NO_ERR)
    {
        if (message->a)
        {
            /* ... */
        }
    }
}

К списку сервисов

tn_queue_isend_polling()

2010-02-10T13:56:37+03:00

tn_queue_isend_polling()

Функция предназначена для отсылки сообщения data_ptr через очередь сообщений dque из прерывания.

Если очередь задач, ожидающих сообщение не пуста, сервис переводит первую в очереди задачу в состояние готовой к выполнению и передает сообщение data_ptr в эту задачу, минуя буфер сообщений.

Если ни одна из задач системы не ожидает сообщение, параметр data_ptr кладется в конец буфера сообщений очереди. Если буфер сообщений заполнен, то функция возвращает код ошибки TERR_TIMEOUT.

Вызов:

TN_RETVAL tn_queue_isend_polling (TN_DQUE *dque, void *data_ptr);

Разрешен вызов:

В прерывании

Параметры функции:

dque: указатель на объект очереди сообщений.
data_ptr: указатель на сообщение

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_NOEXS: попытка обращения к объекту, который не является очередью ²⁾
TERR_WCONTEXT: вызов сервиса в контексте задачи или в пользовательской критической секции
TERR_TIMEOUT: буфер сообщения заполнен, невозможно отослать сообщение
TERR_NO_ERR: успешное выполнение

Пример вызова:

extern TN_DQUE  queue TN_DATA;
extern MY_MSG   message;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
 
    message.a = 1;
    message.b = 2;
 
    if (tn_queue_isend_polling(&queue, (void*)&message) == TERR_NO_ERR)
    {
        /* ... */
    }
}

К списку сервисов

¹⁾ , ²⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_queue_receive()

2009-06-25T22:25:37+03:00

tn_queue_receive()

Функция предназначена для приема сообщения через очередь сообщений dque. Принятое сообщение (точнее говоря адрес сообщения) сохраняется по указателю data_ptr.

Если буфер очереди сообщений пуст, и нет задач, ожидающих освобождение буфера, то задача, вызвавшая сервис переводится в состояние ожидания. Если значение параметра timeout не равно TN_WAIT_INFINITE, то задача "проснется" по истечении timeout системных тиков с кодом ошибки TERR_TIMEOUT.

Вызов:

TN_RETVAL tn_queue_receive (TN_DQUE     *dque,
                            void       **data_ptr,
                            TN_TIMEOUT   timeout
                           );

Разрешен вызов:

В контексте задачи

Параметры функции:

dque: указатель на объект очереди сообщений.
data_ptr: указатель на указатель, в который сохраняется адрес сообщения
timeout: время по истечении которого задача будет переведена из состояния ожидания в состояние готовых к выполнению, если не будет получено сообщения

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка обращения к объекту, который не является очередью (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_WCONTEXT: вызов сервиса в пользовательской критической секции или в обработчике прерывания
TERR_TIMEOUT: выход из функции по таймауту
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_DQUE  queue TN_DATA;    /* очередь сообщений      */
MY_MSG   *message;         /* указатель на сообщение */
 
tn_queue_receive(&queue, &message, 10);
if (message->a)
{
    /* ... */
}

К списку сервисов

tn_queue_receive_polling()

2009-03-05T00:00:14+03:00

tn_queue_receive_polling()

Функция предназначена для приема сообщения через очередь сообщений dque. Принятое сообщение (точнее говоря адрес сообщения) сохраняется по указателю data_ptr. Если в очереди отсутствуют сообщение, то задача не блокируется, а функция возвращает код ошибки TERR_TIMEOUT.

Вызов:

TN_RETVAL tn_queue_receive_polling (TN_DQUE *dque, void **data_ptr);

Разрешен вызов:

В контексте задачи

Параметры функции:

dque: указатель на объект очереди сообщений.
data_ptr: указатель на указатель, в который сохраняется адрес сообщения

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка обращения к объекту, который не является очередью (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_WCONTEXT: вызов сервиса в пользовательской критической секции или в обработчике прерывания
TERR_TIMEOUT: очередь сообщений пуста
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_DQUE  queue TN_DATA;    /* очередь сообщений      */
MY_MSG   *message;         /* указатель на сообщение */
 
if (tn_queue_receive_polling(&queue, &message) == TERR_NO_ERR)
{
    if (message->a)
    {
        /* ... */
    }
}

К списку сервисов

tn_queue_send()

2008-07-21T00:49:23+03:00

tn_queue_send()

Функция предназначена для отсылки сообщения data_ptr через очередь сообщений dque.

Если ни одна из задач системы не ожидает сообщение, параметр data_ptr кладется в конец буфера сообщений очереди и задача продолжает выполнение. Если буфер сообщений заполнен, то задача, посылающая сообщение переводится в состояние ожидания до тех пор, пока хотя бы одно сообщение из буфера не будет принято. При этом задача может выйти из ожидания с кодом TERR_TIMEOUT по истечении timeout системных тиков.

Вызов:

TN_RETVAL tn_queue_send (TN_DQUE    *dque,
                         void       *data_ptr,
                         TN_TIMEOUT  timeout
                        );

Разрешен вызов:

В контексте задачи

Параметры функции:

dque: указатель на объект очереди сообщений.
data_ptr: указатель на сообщение
timeout: таймаут ожидания освобождения буфера в системных тиках. Значение параметра должно больше нуля. Если значение параметра равно TN_WAIT_INFINITE, задача, посылающая сообщение будет ожидать освобождения буфера.

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_NOEXS: попытка обращения к объекту, который не является очередью ²⁾
TERR_WCONTEXT: вызов сервиса в пользовательской критической секции или в обработчике прерывания
TERR_TIMEOUT: выход из сервиса по таймауту
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_DQUE  queue TN_DATA;
MY_MSG   message;
 
message.a = 1;
message.b = 2;
 
tn_queue_send(&queue, (void*)&message, TN_WAIT_INFINITE);

К списку сервисов

¹⁾ , ²⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_queue_send_polling()

2008-07-21T00:50:13+03:00

tn_queue_send_polling()

Функция предназначена для отсылки сообщения data_ptr через очередь сообщений dque без блокирования вызывающей задачи.

Вызов:

TN_RETVAL tn_queue_send_polling (TN_DQUE *dque, void *data_ptr);

Разрешен вызов:

В контексте задачи

Параметры функции:

dque: указатель на объект очереди сообщений.
data_ptr: указатель на сообщение

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_NOEXS: попытка обращения к объекту, который не является очередью ²⁾
TERR_WCONTEXT: вызов сервиса в пользовательской критической секции или в обработчике прерывания
TERR_TIMEOUT: буфер сообщения заполнен, невозможно отослать сообщение
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_DQUE  queue TN_DATA;
MY_MSG   message;
 
message.a = 1;
message.b = 2;
 
if (tn_queue_send_polling(&queue, (void*)&message) == TERR_NO_ERR)
{
    /* ... */
}

К списку сервисов

¹⁾ , ²⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров