PIC24 tnkernel:ref:task

TNKernel : Задачи

2010-10-26T15:30:19+03:00

TNKernel : Задачи

Введение

Задача в TNKernel это часть программного кода, которая с точки зрения программиста выполняется одновременно с другими задачами, что обеспечивается разделением процессорного времени между ними. Каждая задача может быть представлена как независимое приложение, которое владеет уникальными ресурсами (регистры процессора, указатель стека и т.п.). Эти ресурсы называются контекстом задачи, а время в течении которого задача выполняется можно назвать временем в контексте задачи.

Когда текущая задача приостанавливает выполнение (в случае прерывания или вызова сервиса), осуществляется переключение контекста - контекст текущей задачи сохраняется в ее стеке, а контекст наиболее приоритетной задачи из готовых к выполнению восстанавливается. Этот механизм в TNKernel называется "диспетчером".

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

В TNKernel используется приоритетное вытесняющее планирование, основанное на приоритете, назначаемом каждой задаче, при этом чем меньше величина, тем выше уровень приоритета. В TNKernel доступно 32 уровня приоритета для 32-битных контроллеров (ARM, MIPS) и 16 уровней приоритета для 16-битных контроллеров (PIC24/dsPIC).

Приоритеты 0 (самый высокий) и 31(15) (самый низкий) зарезервированы для системных задач. Для пользовательских задач доступны приоритеты от 1 до 30(14) включительно. В TNKernel несколько задач могут иметь одинаковый приоритет.

Состояния задач

Задачи в TNKernel могут находится в одном из четырех состояний:

RUNNING

Задача выполняется в данный момент

READY

Задача готова к выполнению, но не может получить , так как в данный момент выполняется задача с более высоким (или равным) приоритетом. В TNKernel оба состояния RUNNING и READY называются RUNNABLE

WAIT/SUSPEND

Когда задача находится в состоянии WAIT/SUSPEND она не может начать выполнение до тех пор пока не выполнится условие, которого задача ожидает. При входе в состояние WAIT/SUSPEND контекст задачи сохраняется, при выходе из этого состояния контекст восстанавливается. Состояние WAIT/SUSPEND делится на три типа:

`WAITING`	Задача находится в состоянии `WAIT/SUSPEND` до тех пор пока не наступит событие, которого она ожидает - завершится таймаут, освободится семафор, установится флаг и т.п.
`SUSPENDED`	Задача перемещена в состояние `WAIT/SUSPEND` другой задачей или самостоятельно путем вызова специального сервиса
`WAITING_SUSPENDED`	Задача находится как в состоянии `WAITING`, так и в состоянии `SUSPENDED` (ожидает события и приостановлена специальным сервисом). Если задача освобождается от состояния `WAITING` (ожидаемое событие наступило), то она остается в состоянии `SUSPENDED` и наоборот.

DORMANT

Задача уже создана, но еще ни разу не запускалась

Выполнение задачи завершено с помощью специального таймера.

Можно так же выделить состояние задачи, в котором она еще не создана - состояние NON-EXISTENT.

Граф перехода между состояниями изображен на рисунке:

Сервисы, вызов которых приводит к изменению состояния задачи указаны возле направлений перехода. Для простоты префикс tn_task_ и префикс i (вызов из прерывания) опущены.

Переход задачи из состояния READY в состояние RUNNING происходит тогда, когда ее приоритет наивысший из приоритетов всех задач находящихся в состоянии READY.

Переход задачи из состояния RUNNING в состояние READY происходит тогда, когда ее приоритет меньше чем приоритет одной из задач, находящихся в состоянии READY.

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

Задача переходит из состояния WAITING в состояние READY когда событие, которого она ожидала произошло. Например, освободился семафор или окончился таймаут ожидания.

Правила планирования

В TNKernel во время выполнения задачи с наивысшим приоритетом ни одна из других задач не может получить управление до тех пор, пока эта задача не перейдет в состояние WAITING/SUSPEND или DORMANT.

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

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

Пример: пусть задача А имеет приоритет 1, задачи Б, В, Г, Д - приоритет 3, задачи Е и Ж - приоритет 4, задача З - приоритет 5. Если все задачи находятся в состоянии READY последовательность выполнения будет следующая:

1. Задача А с наиболее высоким приоритетом (приоритет 1)
2. Задачи Б, В, Г и Д в той последовательности в которой они перешли в состояние READY (приоритет 3)
3. Задачи Е и Ж в той последовательности, в которой они перешли в состояние READY (приоритет 4)
4. Задача З, так как она имеет наиболее низкий приоритет (приоритет 5)

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

Системные задачи

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

Одна из этих задач (timer_task) имеет наивысший приоритет (0) и обеспечивает функционирование системного таймера.

Вторая задача (idle_task) имеет минимальный приоритет (31/15) и получает управление тогда, когда нет пользовательских задач готовых к выполнению. Эта задача может использоваться для сбора статистики или перевода процессора в состояние пониженного потребления энергии.

Размеры стеков системных задач определяет пользователь, исходя из особенностей приложение. Кроме того, необходимо объявить функцию idle_user_cb(), которая циклически вызывается из задачи idle_task.

Структура управления задачей

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

typedef struct TN_TCB_S_STRUCT
{
    TN_UWORD                * task_stk;
    CDLL_QUEUE_S              task_queue;
    CDLL_QUEUE_S              timer_queue;
    CDLL_QUEUE_S              block_queue;
    CDLL_QUEUE_S              create_queue;
    CDLL_QUEUE_S              mutex_queue;
    CDLL_QUEUE_S            * pwait_queue;
    struct TN_TCB_S_STRUCT  * blk_task;
 
    TN_UWORD                * stk_start;
    TN_UWORD                  stk_size;
 
    void                    * task_func_addr;
    void                    * task_func_param;
 
    TN_UWORD                  base_priority;
    TN_UWORD                  priority;
    TN_UWORD                  id_task;
 
    TN_WORD                   task_state;
    TN_UWORD                  task_wait_reason;
    TN_WORD                   task_wait_rc;
    TN_UWORD                  tick_count;
    TN_UWORD                  tslice_count;
 
    TN_UWORD                  ewait_pattern;
    TN_UWORD                  ewait_mode;
 
    void                    * data_elem;
 
    TN_UWORD                  activate_count;
    TN_UWORD                  wakeup_count;
    TN_UWORD                  suspend_count;
} TN_TCB_S;

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

`task_stk`	Указатель на вершину стека задачи
`task_queue`	Элемент очереди для включения задачи в список существующих задач
`timer_queue`	Элемент очереди для включения задачи в список задач, ожидающих события таймера (таймаут и т.п.)
`block_queue`	Элемент очереди для включения задачи в список заблокированных задач (используется в протоколе priority ceiling системных мютексов)
`create_queue`	Элемент очереди для включения задачи в список созданных задач
`mutex_queue`	Список всех мютексов, заблокированных задачей
`pwait_queue`	Указатель на очередь объектов (семафоров, флагов), ожидаемых задачей
`blk_task`	Указатель на структуру задачи которая заблокировала эту задачу (используется в протоколе priority ceiling системных мютексов)
`stk_start`	Указатель на базовый адрес стека задачи
`stk_size`	Размер стека задачи
`task_func_addr`	Указатель на функцию задачи
`task_func_param`	Укащатель на параметр, передаваемый в функцию задачи
`base_priority`	Базовый приоритет задачи
`priority`	Текущий приоритет задачи
`id_task`	Поле идентификации объекта как задачи
`task_state`	Состояние задачи
`task_wait_reason`	Причина нахождения в состоянии `WAITING`
`task_wait_rc`	Код, возвращаемый задачей при выходе из состояния `WAITING` (причина, по которой задача вышла из состояния ожидания)
`tick_count`	Время до истечения таймаута в системных тиках
`tslice_count`	Счетчик кванта времени для round-robin планирования в системных тиках
`ewait_pattern`	Маска ожидаемых флагов
`ewait_mode`	Тип ожидания флагов (И или ИЛИ, т.е. все флаги, или хотя бы один из маски)
`data_elem`	Указатель на очередь сообщений
`activate_count`	Счетчик запросов на активацию задачи
`wakeup_count`	Счетчик запросов на пробуждение задачи
`suspend_count`	Счетчик запросов на останов задачи

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

Сервисы управления задачами

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

Сервис	Описание	Свойства
Создание и удаление задачи
tn_task_create()	Создание задачи
tn_task_delete()	Удаление задачи
Перезапуск задачи
tn_task_exit()	Выход из текущей задачи
tn_task_terminate()	Завершение работы задачи
tn_task_activate()	Перезапуск задачи
tn_task_iactivate()	Перезапуск задачи из прерывания
Останов и восстановление задачи
tn_task_suspend()	Останов задачи
tn_task_isuspend()	Останов задачи в прерывании
tn_task_resume()	Восстановление задачи
tn_task_iresume()	Восстановление задачи в прерывании
Приостановка выполнения и пробуждение задачи
tn_task_sleep()	Приостановка выполнения задачи
tn_task_wakeup()	Пробуждение приостановленной задачи
tn_task_iwakeup()	Пробуждение приостановленной задачи в прерывании
Форсированный вывод задачи из состояния `WAITING`
tn_task_release_wait()	Форсированный вывод задачи из состояния `WAITING`
tn_task_irelease_wait()	Форсированный вывод задачи из состояния `WAITING` в прерывании
Изменение приоритета задачи
tn_task_change_priority()	Изменение приоритета задачи
Получение информации о задаче
tn_task_reference()	Получение информации о задаче
tn_task_ireference()	Получение информации о задаче в прерывании

tn_task_activate()

2008-07-21T02:15:14+03:00

tn_task_activate()

Функция активизирует задачу - переводит задачу task из состояния DORMANT в состояние READY.

Вызов:

TN_RETVAL tn_task_activate(TN_TCB *task);

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

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

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

task: указатель на TCB активизируемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_activate_task_1)
    tn_task_activate(&tcb_Task1);
/* ... */

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

tn_task_change_priority()

2008-07-21T02:22:07+03:00

tn_task_change_priority()

Функция изменяет натуральный (заданный при создании) приоритет задачи.

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

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

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

Изменение приоритета задачи, находящейся в состоянии останова или ожидания не меняет состояния задачи.

Вызов:

TN_RETVAL tn_task_change_priority (TN_TCB *task, TN_UWORD new_priority);

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

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

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

task: указатель на TCB задачи, изменяющей приоритет. Задача может изменить свой приоритет.
new_priority: новый приоритет задачи от 1 до 14 для 16-битных контроллеров и от 1 до 30 - для 32-битных контроллеров. Если значение параметра равно 0, то задача восстанавливает базовый приоритет, назначенный при создании.

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

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

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

tn_task_change_priority(&myTask, 10);

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

tn_task_create()

2008-07-21T02:12:47+03:00

tn_task_create()

Функция предназначена для создания задачи. Поле id_task TCB задачи task должно быть равно нулю до момента создания задачи, таким образом уже созданные задачи защищаются от повторного создания. Память для управляющей структуры TCB task и для стека задачи должна быть выделена до момента создания задачи. Память может быть выделена на этапе компиляции (объявление глобальной переменной типа TN_TASK для TCB задачи и массива с элементами типа TN_UWORD для стека задачи), либо динамически, если пользовательское приложение использует менеджер памяти.

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

Стек задачи - это массив элементов типа TN_UWORD, разрядность TN_UWORD соответствует разрядности машинного слова микроконтроллера. Для ARM7 sizeof(TN_UWORD) = 4, для PIC24/dsPIC sizeof(TN_UWORD) = 2.

Параметр task_stack_start является указателем на вершину стека. Если в используемой архитектуре стек растет от младшего адреса к старшему (PIC24/dsPIC), то параметр task_stack_start должен быть равен адресу первого элемента массива. В противном случае параметр должен быть равен последнему элементу массива.

Вызов:

TN_RETVAL tn_task_create(TN_TCB   *task,
                         void     (*task_func)(void *param),
                         TN_UWORD priority,
                         TN_UWORD *task_stack_start,
                         TN_UWORD task_stack_size,
                         void     *param,
                         TN_UWORD option
                        );

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

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

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

task

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

(*task_func)(void *param)

указатель на функцию задачи. Функция задачи имеет следующий прототип: void (*task_func)(void *param)

priority

приоритет задачи. Пользовательские задачи могут иметь приоритет от 1 до TN_NUM_PRIORITY - 1 включительно(приоритеты 0 и TN_NUM_PRIORITY зарезервированы для служебных задач)

task_stack_start

указатель на стек задачи. Для PIC24/dsPIC - указатель на первый элемент массива стека задачи

task_stack_size

размер стека задачи в машинных словах (количество элементов в массиве стека)

param

параметр передаваемый в функцию задачи

option

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

`TN_TASK_DORMANT_ON_CREATION`	после создания задача переводится в состояние DORMANT
`TASK_START_ON_CREATION`	после создания задача переводится в состояние RUNNABLE

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

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

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

#define TASK_1_STACK_SIZE      128              /* размер стека задачи */
#define TASK_1_PRIORITY        11               /* приоритет задачи    */
 
TN_TCB   tcb_Task1 TN_DATA;                     /* TCB задачи */
TN_UWORD stk_Task1[TASK_1_STACK_SIZE] TN_DATA;  /* стек задачи */
 
void TN_TASK Task1(void *par);                  /* прототип функции задачи */
 
/* ... создание задачу... */
 
    tn_task_create(&tcb_Task1,
                   Task1,
                   TASK_1_PRIORITY,
                   stk_Task1,
                   TASK_1_STACK_SIZE,
                   TN_NULL,
                   TN_TASK_START_ON_CREATION
                  );
 
/* ... */
 
void TN_TASK Task1 (void *par)                 /* функция задачи */
{
    for (;;)
    {
        tn_task_sleep(10);
    }
}

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

tn_task_delete()

2008-07-21T02:13:25+03:00

tn_task_delete()

Функция удаляет задачу, находящуюся в состоянии DORMANT. Если удаляемая задача будет находиться в другом состоянии, сервис вернет код ошибки.

Функция сбрасывает поле id_task TCB задачи, и удаляет задачу из списка доступных в системе. Освободившуюся память можно использовать для создания другой задачи. Процесс удаления необратимый - для запуска удаленной задачи нужно создать ее заново функцией tn_task_create.

Вызов:

TN_RETVAL tn_task_delete(TN_TCB *task);

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

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

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

task: указатель на TCB удаляемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_delete_task_1)
    tn_task_delete(&tcb_Task1);
/* ... */

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

tn_task_exit()

2009-12-19T16:33:04+03:00

tn_task_exit()

Функция прекращает выполнение текущей задачи, при этом задача перемещается в состояние DORMANT. Все ресурсы (мютексы) занятые задачей разблокируются. Задача может быть дополнительно удалена, если сервис вызван с параметром TN_EXIT_AND_DELETE_TASK.

Если счетчик запросов на активацию задачи больше 1, то счетчик декрементируется, а задача переводится в состояние READY. Как только задача станет наиболее приоритетной, она запустится с точки входа в функцию задачи (так же как и первый раз после создания). Следует заметить, что задача будет поставлена в очередь готовых к выполнению (этого же приоритета) последней.

Задача может быть выведена из состояния DORMANT с помощью сервисов tn_task_activate() и tn_task_iactivate(). В этом случае задача будет запущена с точки входа в функцию задачи и поставлена в очередь готовых к выполнению (этого же приоритета) последней.

Функция tn_task_exit() может использоваться только для прекращения выполнения текущей задачи. Для прекращения выполнения другого потока необходимо использовать функцию tn_task_terminate().

Вызов:

void tn_task_exit (TN_UWORD attr);

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

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

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

attr

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

`TN_EXIT_TASK`	функция прекратит выполнение текущей задачи. Для запуска задачи необходимо использовать сервисы `tn_task_activate()` или `tn_task_iactivate()`
`TN_EXIT_AND_DELETE_TASK`	после прекращения выполнения задача будет удалена. Для запуска удаленной задачи нужно создать ее заново функцией `tn_task_create`

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

нет

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
void Task1 (void *param)
{
    for (;;)
    {
        if (need_restart_task_1)
        tn_task_exit(TN_EXIT_TASK);
        /* ... */
    }
}

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

tn_task_iactivate()

2008-07-21T02:15:55+03:00

tn_task_iactivate()

Функция активизирует задачу из прерывания - переводит задачу task из состояния DORMANT в состояние READY.

Вызов:

TN_RETVAL tn_task_iactivate(TN_TCB *task);

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

В прерывании

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

task: указатель на TCB активизируемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
tn_sys_interrupt (_T3Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_task_iactivate(&tcb_Task1);     /* активация задачи tcb_Task1 */
}

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

tn_task_ireference()

2009-06-24T10:27:08+03:00

tn_task_ireference()

Функция предназначена для получения информации о задаче в прерывании. После вызова функции заполняется структура типа TN_TASK_REF, указатель на которую передается в качестве параметра функции:

typedef struct _TN_TASK_REF
{
    TN_TASK_STATE       state;
    TN_TASK_WAIT_REASON wait_reason;
    TN_UWORD            base_priority;
    TN_UWORD            current_priority;
    TN_TIMEOUT          timeout;
} TN_TASK_REF;

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

state

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

`TSK_STATE_RUNNABLE`	Задача находится в очереди готовых к выполнению
`TSK_STATE_WAIT`	Задача ожидает событие
`TSK_STATE_SUSPEND`	Задача приостановлена
`TSK_STATE_DORMANT`	Задача создана, но еще не запущена

wait_reason

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

`TSK_WAIT_REASON_SLEEP`	Задача ожидает таймаута, переведена в состояние ожидания функцией `tn_task_sleep()`
`TSK_WAIT_REASON_SEM`	Задача ожидает освобождения семафора
`TSK_WAIT_REASON_EVENT`	Задача ожидает флаг
`TSK_WAIT_REASON_DQUE_WSEND`	Задача ожидает освобождение очереди сообщений
`TSK_WAIT_REASON_DQUE_WRECEIVE`	Задача ожидает сообщения
`TSK_WAIT_REASON_MUTEX_C`	Задача ожидает освобождения ресурса, заблокированного "priority ceiling" мютексом
`TSK_WAIT_REASON_MUTEX_C_BLK`	Задача ожидает освобождения ресурса, заблокированного "priority ceiling" мютексом
`TSK_WAIT_REASON_MUTEX_I`	Задача ожидает освобождения ресурса, заблокированного "priority inheritance" мютексом
`TSK_WAIT_REASON_WFIXMEM`	Задача ожидает освобождения блока памяти фиксированного размера

base_priority

базовый приоритет задачи (назначенный при ее создании)

current_priority

текущий приоритет задачи

timeout

время в системных тиках до момента перевода задачи в состояние TSK_STATE_RUNNABLE (актуально в случае, если задача находится в состоянии ожидания с таймаутом)

Вызов:

TN_RETVAL tn_task_ireference(TN_TCB *task, TN_TASK_REF *ref);

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

В прерывании

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

task: указатель на TCB задачи
ref: указатель на структуру информации о задаче

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
TN_TASK_REF  task_info;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    if (tn_task_ireference(&tcb_Task1, &task_info) == TERR_NO_ERR)
    {
        if (task_info.state == TSK_STATE_SUSPEND)
            tn_task_iresume(&tcb_Task1);
    }
}

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

tn_task_irelease_wait()

2008-07-21T02:19:03+03:00

tn_task_irelease_wait()

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

Если задача находится в состоянии WAITING, она переводится в состояние READY. Если задача находится в состоянии WAITING_SUSPEND, она переводится в состояние SUSPEND. Если задача находилась в состоянии WAITING по причине вызова функции tn_task_sleep(), вызов функции tn_task_irelease_wait() с указателем на эту задачу кроме всего прочего сбрасывает счетчик попыток пробуждения задачи. Функция не может использоваться для активации задачи, которая находится в состоянии SUSPEND.

Вызов:

TN_RETVAL tn_task_irelease_wait (TN_TCB *task);

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

В прерывании

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

task: указатель на TCB задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
tn_sys_interrupt (_T3Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_task_irelease_wait(&tcb_Task1);       /* восстановление задачи tcb_Task1 */
}

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

tn_task_iresume()

2008-07-21T02:18:02+03:00

tn_task_iresume()

Функция предназначена для вывода задачи из состояния SUSPENDED в прерывании.

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

Вызов:

TN_RETVAL tn_task_iresume (TN_TCB *task);

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

В прерывании

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

task: указатель на TCB восстанавливаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
tn_sys_interrupt (_T3Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_task_iresume(&tcb_Task1);       /* восстановление задачи tcb_Task1 */
}

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

tn_task_isuspend()

2009-05-04T18:17:52+03:00

tn_task_isuspend()

Функция приостанавливает выполнение задачи, переводя ее в состояние SUSPENDED из прерывания. Если задача находится в состоянии WAITING, она переводится в состояние WAITING_SUSPENDED.

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

Вызов:

TN_RETVAL tn_task_isuspend (TN_TCB *task);

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

В прерывании

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

task: указатель на TCB приостанавливаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_task_isuspend(&tcb_Task1);      /* приостановка выполнения задачи tcb_Task1 */
}

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

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

tn_task_iwakeup()

2008-07-21T02:18:32+03:00

tn_task_iwakeup()

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

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

Вызов:

TN_RETVAL tn_task_wakeup (TN_TCB *task);

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

В прерывании

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

task: указатель на TCB пробуждаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
tn_sys_interrupt (_T3Interrupt)        /* прерывание от таймера */
{
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    tn_task_iwakeup(&tcb_Task1);       /* активация задачи tcb_Task1 */
}

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

tn_task_reference()

2009-06-24T10:05:32+03:00

tn_task_reference()

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

typedef struct _TN_TASK_REF
{
    TN_TASK_STATE       state;
    TN_TASK_WAIT_REASON wait_reason;
    TN_UWORD            base_priority;
    TN_UWORD            current_priority;
    TN_TIMEOUT          timeout;
} TN_TASK_REF;

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

state

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

`TSK_STATE_RUNNABLE`	Задача находится в очереди готовых к выполнению
`TSK_STATE_WAIT`	Задача ожидает событие
`TSK_STATE_SUSPEND`	Задача приостановлена
`TSK_STATE_DORMANT`	Задача создана, но еще не запущена

wait_reason

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

`TSK_WAIT_REASON_SLEEP`	Задача ожидает таймаута, переведена в состояние ожидания функцией `tn_task_sleep()`
`TSK_WAIT_REASON_SEM`	Задача ожидает освобождения семафора
`TSK_WAIT_REASON_EVENT`	Задача ожидает флаг
`TSK_WAIT_REASON_DQUE_WSEND`	Задача ожидает освобождение очереди сообщений
`TSK_WAIT_REASON_DQUE_WRECEIVE`	Задача ожидает сообщения
`TSK_WAIT_REASON_MUTEX_C`	Задача ожидает освобождения ресурса, заблокированного "priority ceiling" мютексом
`TSK_WAIT_REASON_MUTEX_C_BLK`	Задача ожидает освобождения ресурса, заблокированного "priority ceiling" мютексом
`TSK_WAIT_REASON_MUTEX_I`	Задача ожидает освобождения ресурса, заблокированного "priority inheritance" мютексом
`TSK_WAIT_REASON_WFIXMEM`	Задача ожидает освобождения блока памяти фиксированного размера

base_priority

базовый приоритет задачи (назначенный при ее создании)

current_priority

текущий приоритет задачи

timeout

Вызов:

TN_RETVAL tn_task_reference(TN_TCB *task, TN_TASK_REF *ref);

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

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

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

task: указатель на TCB задачи
ref: указатель на структуру информации о задаче

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

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

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

TN_TASK_REF task_info;
 
if (tn_task_reference(&task_1, &task_info) == TERR_NO_ERR)
{
    if (task_info.state       == TSK_STATE_WAIT &&
        task_info.wait_reason == TSK_WAIT_REASON_SLEEP
       )
    {
        tn_task_wakeup(&task_1);
    }
}

if (tn_task_reference(&task_1, &task_info) == TERR_NOEXS)
{
    /* задача не создана */
}

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

tn_task_release_wait()

2008-07-21T02:21:25+03:00

tn_task_release_wait()

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

Если задача находится в состоянии WAITING, она переводится в состояние READY. Если задача находится в состоянии WAITING_SUSPEND, она переводится в состояние SUSPEND. Если задача находилась в состоянии WAITING по причине вызова функции tn_task_sleep(), вызов функции tn_task_release_wait() с указателем на эту задачу кроме всего прочего сбрасывает счетчик попыток пробуждения задачи. Функция не может использоваться для активации задачи, которая находится в состоянии SUSPEND. Задача не может вызывать функцию tn_task_release_wait() с указателем на саму себя.

Вызов:

TN_RETVAL tn_task_release_wait (TN_TCB *task);

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

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

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

task: указатель на TCB задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_forse_task_1)
    tn_task_release_wait(&tcb_Task1);
/* ... */

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

tn_task_resume()

2008-07-21T02:16:55+03:00

tn_task_resume()

Функция предназначена для вывода задачи из состояния SUSPENDED.

Вызов:

TN_RETVAL tn_task_resume (TN_TCB *task);

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

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

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

task: указатель на TCB восстанавливаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_resume_task_1)
    tn_task_resume(&tcb_Task1);
/* ... */

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

tn_task_sleep()

2008-07-21T02:20:27+03:00

tn_task_sleep()

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

Задача может быть переведена в ожидание с параметром TN_WAIT_INFINITE. В этом случае задача будет находится в ожидании до тех пор, пока не будет вызван сервис tn_task_wakeup() или tn_task_iwakeup().

Каждая задача имеет счетчик запросов на пробуждение. Если у текущей задачи этот счетчик больше или равен 1, то вызов сервиса tn_task_sleep() декрементирует счетчик, а задача продолжает выполнение.

Вызов:

TN_RETVAL tn_task_sleep (TN_TIMEOUT timeout);

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

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

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

timeout: интервал времени в системных тиках на который задача будет переведена в ожидание. timeout ⊆ [1..TN_WAIT_INFINITE], где TN_WAIT_INFINITE = 65‘535 для 16-битных контроллеров и TN_WAIT_INFINITE = 4‘294‘967‘295 для 32-битных контроллеров

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

TERR_WRONG_PARAM: некорректное значение параметра, timeout = 0 (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_WCONTEXT: попытка вызова сервиса в прерывании или в пользовательской критической секции
TERR_NO_ERR: успешное выполнение

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

void TN_TASK Task1 (void *param)
{
    for (;;)
    {
        /* ... */
        tn_task_sleep(10);
        /* ... */
    }
}

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

tn_task_suspend()

2008-07-21T02:16:27+03:00

tn_task_suspend()

Функция приостанавливает выполнение задачи, переводя ее в состояние SUSPENDED. Если задача находится в состоянии WAITING, она переводится в состояние WAITING_SUSPENDED.

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

Вызов:

TN_RETVAL tn_task_suspend (TN_TCB *task);

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

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

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

task: указатель на TCB приостанавливаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_suspend_task_1)
    tn_task_suspend(&tcb_Task1);
/* ... */

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

tn_task_terminate()

2008-07-21T02:14:43+03:00

tn_task_terminate()

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

Задача не может остановить свое выполнение с помощью сервиса tn_task_terminate(), для этого необходимо использовать сервис tn_task_exit().

Вызов:

TN_RETVAL tn_task_terminate(TN_TCB *task);

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

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

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

task: указатель на TCB перезапускаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_stop_task_1)
    tn_task_terminate(&tcb_Task1);
/* ... */

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

tn_task_wakeup()

2008-07-21T02:20:55+03:00

tn_task_wakeup()

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

Вызов:

TN_RETVAL tn_task_wakeup (TN_TCB *task);

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

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

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

task: указатель на TCB пробуждаемой задачи

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

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

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

extern TN_TCB tcb_Task1  TN_DATA;
 
/* ... */
if (need_wakeup_task_1)
    tn_task_wakeup(&tcb_Task1);
/* ... */

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