PIC24 tnkernel:ref:event

TNKernel : Флаги

2008-07-21T01:33:17+03:00

TNKernel : Флаги

Введение

Флаг, как и семафор, является объектом RTOS, предназначенным для синхронизации задач. В отличие от семафора флаг не имеет счетчика свободных ресурсов, однако с каждым флагом ассоциирован элемент, называемый битовой маской. Битовая маска это переменная с разрядностью, равной, как правило, разрядности машинного слова. В TNKernel битовая маска флага имеет разрядность 16 бит для PIC24/dsPIC и 32 бита для ARM/PIC32.

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

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

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

В сервис ожидания в качестве параметра передается аргумент, который указывает, какая логика будет использоваться для ожидания битовой маски: AND или OR. В первом случае задача будет переведена в состояние готовых к выполнению, если все ожидаемые биты будут установлены. Во втором случае - если хотя бы один из ожидаемых битов будет установлен.

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

Структура управления флагом

Каждый флаг ассоциируется со структурой управления:

typedef struct _TN_EVENT_S
{
    CDLL_QUEUE_S        wait_queue;
    TN_UWORD            attr;
    TN_UWORD            pattern;
    TN_OBJ_ID           id_event;
} TN_EVENT_S;

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

`wait_queue`	Очередь задач, ожидающих флаг
`attr`	Тип флага - для всех задач или для одной задачи
`pattern`	Битовая маска флага
`id_event`	Поле идентификации объекта как флага

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

Сервисы управления флагами

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

Сервис	Описание	Свойства
Создание и удаление флага
tn_event_create()	Создание флага
tn_event_delete()	Удаление флага
Установка и сброс битовой маски флага
tn_event_set()	Установка битов в битовой маске
tn_event_iset()	Установка битов в битовой маске в прерывании
tn_event_clear()	Сброс битов в битовой маске
tn_event_iclear()	Сброс битов в битовой маске в прерывании
Ожидание флага
tn_event_wait()	Ожидание флага
tn_event_iwait()	Ожидание флага в прерывании
tn_event_wait_polling()	Ожидание флага без блокировки

tn_event_clear()

2008-07-21T00:41:37+03:00

tn_event_clear()

Функция предназначена для сброса битов в битовой маске флага evf. Биты сбрасываются по логическому И с параметром-маской pattern.

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

Вызов:

TN_RETVAL tn_event_clear (TN_EVENT *evf, TN_UWORD pattern);

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

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

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

evf: указатель на объект типа флаг
pattern: сбрасываемые биты в битовой маске флага. Замечание: сбрасываемые биты должны быть равны 0, параметр pattern не должен принимать значения 0xFFFF. Например, если битовая маска флага до вызова сервиса была равна 0b0011001101010101, а параметр pattern равен 0b1100111111111111, то битовая маска флага станет равна 0b0000001101010101

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

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

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

TN_EVENT event;
 
tn_event_clear(&event, ~(0x8000));

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

tn_event_create()

2009-04-20T22:48:57+03:00

tn_event_create()

Функция предназначена для создания флага. Поле id_event структуры evf должно быть равно нулю до момента создания флага. Таким образом уже созданные флаги защищаются от повторного создания.

Память для управляющей структуры evf должна быть выделена до момента создания флага. Память может быть выделена на этапе компиляции (объявление глобальной переменной типа TN_EVENT), либо динамически, если пользовательское приложение использует менеджер памяти.

Параметр attr определяет тип флага. Если параметр равен TN_EVENT_ATTR_MULTI, то флаг может ожидать несколько задач. Если параметр равен TN_EVENT_ATTR_SINGLE - флаг может ожидать только одна задача. В этом случае допустимо объявление параметра TN_EVENT_ATTR_CLR, который указывает на то, что битовая маска будет сбрасываться автоматически. Параметр TN_EVENT_ATTR_CLR объявляется вместе с параметром TN_EVENT_ATTR_SINGLE: (TN_EVENT_ATTR_SINGLE | TN_EVENT_ATTR_CLR).

Вызов:

TN_RETVAL tn_event_create (TN_EVENT *evf, TN_UWORD attr, TN_UWORD pattern);

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

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

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

evf

указатель на структуру флага типа TN_EVENT. Структура должна быть создана до момента вызова функции, статически или динамически

attr

тип флага:

`TN_EVENT_ATTR_MULTI`	флаг может ожидать несколько задач
`TN_EVENT_ATTR_SINGLE`	флаг может ожидать только одна задача
`TN_EVENT_ATTR_CLR`	битовая маска будет сброшена автоматически. Определение может быть объединено по ИЛИ только с `TN_EVENT_ATTR_SINGLE`

pattern

значение битовой маски сразу после создания флага

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

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_EXS: попытка создания флага, который уже создан
TERR_NO_ERR: успешное выполнение

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

TN_EVENT event_test;
 
/* Создается флаг, который может ожидать только одна задача с
   автоматическим сбросом соответствующих битов в битовой
   маске. Начальное значение битовой маски равно 0x5555
*/
tn_event_create(&event_test, TN_EVENT_ATTR_SINGLE | TN_EVENT_ATTR_CLR, 0x5555);

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

tn_event_delete()

2008-04-29T00:33:53+03:00

tn_event_delete()

Функция предназначена для удаления флага. Поле id_event структуры evf после выполнения сервиса устанавливается в 0. Все задачи, ожидающие флаг, выйдут из сервиса ожидания с кодом возврата TERR_DLT.

Вызов:

TN_RETVAL tn_event_delete (TN_EVENT *evf);

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

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

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

evf: указатель на структуру удаляемого флага

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

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

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

TN_EVENT event_test;
 
tn_event_delete(&event_test);

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

tn_event_iclear()

2008-07-21T00:43:43+03:00

tn_event_iclear()

Функция предназначена для сброса битов в битовой маске флага evf в прерывании. Биты сбрасываются по логическому И с параметром-маской pattern.

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

Вызов:

TN_RETVAL tn_event_iclear (TN_EVENT *evf, TN_UWORD pattern);

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

В прерывании

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

evf: указатель на объект типа флаг
pattern: сбрасываемые биты в битовой маске флага. Замечание: сбрасываемые биты должны быть равны 0, параметр pattern не должен принимать значения 0xFFFF. Например, если битовая маска флага до вызова сервиса была равна 0b0011001101010101, а параметр pattern равен 0b1100111111111111, то битовая маска флага станет равна 0b0000001101010101

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

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

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

extern TN_EVENT event;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_event_iclear(&event, ~(0x8000));
}

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

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

tn_event_iset()

2008-07-21T00:40:14+03:00

tn_event_iset()

Функция предназначена для установки битов в битовой маске флага evf в прерывании. Биты устанавливаются по логическому ИЛИ с параметром-маской pattern.

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

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

Если флаг имеет атрибут TN_EVENT_ATTR_CLR, то битовая маска флага сбрасывается.

Вызов:

TN_RETVAL tn_event_iset (TN_EVENT *evf, TN_UWORD pattern);

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

В прерывании

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

evf: указатель на объект типа флаг
pattern: устанавливаемые биты в битовой маске флага. Например, если битовая маска флага до вызова сервиса была равно 0b0011001101010101, а параметр pattern равен 0b1100000000000000, то битовая маска флага станет равна 0b1111001101010101

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

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

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

extern TN_EVENT event;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_event_iset(&event, 0x8000);
}

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

tn_event_iwait()

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

tn_event_iwait()

Функция предназначена для проверки битовой маски флага в прерывании.

Условие проверки определяется маской wait_pattern и режимом ожидания wait_mode. Если условие выполняется, битовая маска флага будет возвращена по указателю p_flags_pattern.

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

Если флаг evf имеет атрибут TN_EVENT_ATTR_SINGLE, а очередь ожидания флага не пуста, то функция вернет код ошибки TERR_ILUSE, что означает попытку проверки флага, предназначенного только для одной (уже ожидающей его) задачи.

Если флаг evf имеет атрибут TN_EVENT_ATTR_CLR, битовая маска флага обнуляется.

Параметр wait_mode формирует условие совпадения. Если wait_mode == TN_EVENT_WCOND_OR, то условие будет выполнено, если хотя бы один бит из битовой маски флага будет соответствовать wait_pattern. Если wait_mode == TN_EVENT_WCOND_AND, то для выполнения условия необходимо чтобы все биты битовой маски флага соответствовали параметру wait_pattern.

Вызов:

TN_RETVAL tn_event_iwait (TN_EVENT *evf,
                          TN_UWORD wait_pattern,
                          TN_UWORD wait_mode,
                          TN_UWORD *p_flags_pattern
                         );

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

В прерывании

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

evf

указатель на объект типа флаг

wait_pattern

параметр сравнения с битовой маской флага

wait_mode

условие совпадения, может принимать одно из двух значений:

`TN_EVENT_WCOND_OR`	условие выполняется, если хотя бы один из битов маски флага совпадает с маской сравнения `wait_pattern`
`TN_EVENT_WCOND_AND`	условие выполняется только в том случае, если хотя все биты маски флага совпадают с маской сравнения `wait_pattern`

p_flags_pattern

указатель по которому возвращается значение битовой маски флага если условие выполнено

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

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

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

extern TN_EVENT event_test;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    TN_UWORD flag;
 
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_event_wait(&event_test, 0x8000, TN_EVENT_WCOND_AND, &flag);
}

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

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

tn_event_set()

2008-07-21T00:40:51+03:00

tn_event_set()

Функция предназначена для установки битов в битовой маске флага evf. Биты устанавливаются по логическому ИЛИ с параметром-маской pattern.

Если флаг имеет атрибут TN_EVENT_ATTR_CLR, то битовая маска флага сбрасывается.

Вызов:

TN_RETVAL tn_event_set (TN_EVENT *evf, TN_UWORD pattern);

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

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

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

evf: указатель на объект типа флаг
pattern: устанавливаемые биты в битовой маске флага. Например, если битовая маска флага до вызова сервиса была равно 0b0011001101010101, а параметр pattern равен 0b1100000000000000, то битовая маска флага станет равна 0b1111001101010101

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

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

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

TN_EVENT event_test;
 
tn_event_set(&event_test, 0x8000);

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

tn_event_wait()

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

tn_event_wait()

Функция предназначена для перевода вызвавшей ее задачи в состояние ожидания до тех пор, пока условие совпадения с битовой маской флага evf не будет выполнено. Условие определяется параметром wait_pattern и режимом ожидания wait_mode. Как только условие будет выполнено, битовая маска флага будет возвращена по указателю p_flags_pattern.

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

Если на момент вызова функции условие не выполняется, то задача переводится в состояние ожидания и ставится в очередь ожидания флага. Функция может быть вызвана с таймаутом - если значение параметра timeout не равно TN_WAIT_INFINITE, то по прошествии timeout системных тиков, функция вернет управление прерванной задаче с кодом возврата TERR_TIMEOUT.

Если флаг evf имеет атрибут TN_EVENT_ATTR_SINGLE, а очередь ожидания флага не пуста, то функция вернет код ошибки TERR_ILUSE, что означает попытку ожидания флага, предназначенного только для одной (уже ожидающей его) задачи.

Если флаг evf имеет атрибут TN_EVENT_ATTR_CLR, битовая маска флага обнуляется.

Параметр wait_mode формирует условие ожидания флага. Если wait_mode == TN_EVENT_WCOND_OR, то условие ожидания будет выполнено, если хотя бы один бит из битовой маски флага будет соответствовать wait_pattern. Если wait_mode == TN_EVENT_WCOND_AND, то для выполнения условия ожидания необходимо чтобы все биты битовой маски флага соответствовали параметру wait_pattern.

Вызов:

TN_RETVAL tn_event_wait (TN_EVENT   *evf,
                         TN_UWORD   wait_pattern,
                         TN_UWORD   wait_mode,
                         TN_UWORD   *p_flags_pattern,
                         TN_TIMEOUT timeout
                        );

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

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

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

evf

указатель на объект типа флаг

wait_pattern

параметр сравнения с битовой маской флага

wait_mode

режим ожидания, формирующий условие, может принимать одно из двух значений:

`TN_EVENT_WCOND_OR`	условие выполняется, если хотя бы один из битов маски флага совпадает с маской сравнения `wait_pattern`
`TN_EVENT_WCOND_AND`	условие выполняется только в том случае, если хотя все биты маски флага совпадают с маской сравнения `wait_pattern`

p_flags_pattern

указатель по которому возвращается значение битовой маски флага после выполнения условия

timeout

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

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

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

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

TN_EVENT event_test;
TN_UWORD flag;
 
tn_event_wait(&event_test, 0x8000, TN_EVENT_WCOND_AND, &flag, TN_WAIT_INFINITE);

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

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

tn_event_wait_polling()

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

tn_event_wait_polling()

Функция предназначена для проверки битовой маски флага без блокировки задачи.

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

Если флаг evf имеет атрибут TN_EVENT_ATTR_CLR, битовая маска флага обнуляется.

Вызов:

TN_RETVAL tn_event_wait_polling (TN_EVENT *evf,
                                 TN_UWORD wait_pattern,
                                 TN_UWORD wait_mode,
                                 TN_UWORD *p_flags_pattern
                                );

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

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

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

evf

указатель на объект типа флаг

wait_pattern

параметр сравнения с битовой маской флага

wait_mode

условие совпадения, может принимать одно из двух значений:

`TN_EVENT_WCOND_OR`	условие выполняется, если хотя бы один из битов маски флага совпадает с маской сравнения `wait_pattern`
`TN_EVENT_WCOND_AND`	условие выполняется только в том случае, если хотя все биты маски флага совпадают с маской сравнения `wait_pattern`

p_flags_pattern

указатель по которому возвращается значение битовой маски флага если условие выполнено

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

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

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

TN_EVENT event_test;
TN_UWORD flag;
 
if (tn_event_wait_polling(&event_test, 0x8000, TN_EVENT_WCOND_AND, &flag) == TERR_TIMEOUT)
{
    /* ... */
}

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

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