RTX5. Ядро (информация и управление)

Описание

Группа функций информации и управления ядром позволяет:

• получить информацию о системе и ядре.
• получить информацию о версии интерфейса CMSIS-RTOS.
• инициализация ядра RTOS для создания объектов.
• запуск ядра RTOS и переключение потоков.

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

Инициализация ядра для RTX5 описана в разделе «Запуск системы»

Пример кода

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

/*----------------------------------------------------------------------------
 * Главный поток приложения
 *---------------------------------------------------------------------------*/
void app_main (void *argument) {
 
  // ...
  for (;;) {}
}
 
int main (void) {
 
  // Инициализация системы
  SystemCoreClockUpdate();
  // ...
 
  osKernelInitialize();                 // Инициализация CMSIS-RTOS
  osThreadNew(app_main, NULL, NULL);    // Создание главного потока приложения
  osKernelStart();                      // Запускает ядро RTOS и начинает переключение потоков
  for (;;) {}
}

Структуры

struct osVersion_t

Поля структуры:

uint32_t api  API версия (major.minor.rev: mmnnnrrrr dec).
uint32_t kernel Версия ядра (major.minor.rev: mmnnnrrrr dec).

Определяет версию ядра и API. Версия представлена в виде объединенного десятичного числа в формате: major.minor.rev: mmnnnrrrr

Используйте функцию osKernelGetInfo для получения номеров версий.

Перечисления

enum osKernelState_t

Перечислители:

• osKernelInactive  Неактивный. Ядро еще не готово. osKernelInitialize должен быть успешно выполнен.
• osKernelReady  Готовность к использованию. Ядро еще не запущено. osKernelStart переводит ядро в рабочее состояние.
• osKernelRunning  Запущено. Ядро инициализировано и запущено.
  
• osKernelLocked  Заблокировано. Ядро было заблокировано с помощью функции osKernelLock. Функции osKernelUnlock или osKernelRestoreLock разблокируют его.
  
• osKernelSuspended Приостановленный. Ядро было приостановлено с помощью osKernelSuspend. Функция osKernelResume возвращает к нормальной работе.
• osKernelError Ошибка. Произошла ошибка.
• osKernelReserved Зарезервированный.
  

Состояние ядра, полученное с помощью функции osKernelGetState. В случае ошибки функции osKernelGetState или если она вызывается из ISR, функция возвращает osKernelError, в противном случае она возвращает состояние ядра.

Функции

osStatus_t osKernelInitialize (void)

Функция osKernelInitialize инициализирует ядро RTOS. До вызова этой функции можно вызывать только osKernelGetInfo и osKernelGetState.

Возвращает код состояния, который указывает на статус выполнения функции.

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

• osOK в случае успешного выполнения.
• osError если произошла неуказанная ошибка.
• osErrorISR если вызывается из программы обработки прерываний.
• osErrorNoMemory если память не может быть зарезервирована для операции.

Эта функция не может быть вызвана из подпрограмм обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

#include "RTE_Components.h"
#include  CMSIS_device_header
#include "cmsis_os2.h"
 
/*----------------------------------------------------------------------------
 * Главный поток приложения
 *---------------------------------------------------------------------------*/
void app_main (void *argument) {
 
  // ...
  for (;;) {}
}
 
int main (void) {
 
  // Инициализация системы
  SystemCoreClockUpdate();
  // ...
 
  osKernelInitialize();                 // Инициализация CMSIS-RTOS
  osThreadNew(app_main, NULL, NULL);    // Создание главного потока приложения
  osKernelStart();                      // Запускает ядро RTOS и начинает переключение потоков
  for (;;) {}
}

osStatus_t osKernelGetInfo (osVersion_t * version, char * id_buf, uint32_t id_size)
Параметры
[out] version  указатель на буфер для получения информации о версии.
[out] id_buf указатель на буфер для получения строки идентификации ядра.
[in]  id_size размер буфера для строки идентификации ядра.

Результат
код состояния, который указывает на статус выполнения функции.

Функция osKernelGetInfo извлекает версию API и ядра на основе ядра RTOS и читаемую человеком строку идентификатора для ядра. Ее можно безопасно вызвать до инициализации или запуска RTOS (вызов osKernelInitialize или osKernelStart).

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

• osOK в случае успешного выполнения.
• osError если произошла неуказанная ошибка.

Эта функция  может быть вызвана из подпрограмм обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9
10
11
12

void info (void) {
  char infobuf[100];
  osVersion_t osv;
  osStatus_t status;
 
  status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));
  if(status == osOK) {
    printf("Kernel Information: %s\r\n", infobuf);
    printf("Kernel Version    : %d\r\n", osv.kernel);
    printf("Kernel API Version: %d\r\n", osv.api);
  }
}

osKernelState_t osKernelGetState (void)

Результат
текущее состояние ядра RTOS

Функция osKernelGetState возвращает текущее состояние ядра и может безопасно вызываться до инициализации или запуска RTOS (вызов osKernelInitialize или osKernelStart). В случае неудачи он возвращает osKernelError, в противном случае возвращает состояние ядра (список состояний ядра см. в osKernelState_t).

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

• osKernelError если произошла неуказанная ошибка.
• фактическое состояние ядра в противном случае.

Эта функция может быть вызвана из подпрограмм обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9

int main (void) {
  // Инициализация системы
  SystemCoreClockUpdate();
  // ...
  if(osKernelGetState() == osKernelInactive) {     // Ядро инициализировано?
     osKernelInitialize();                         // Инициализировать ядро CMSIS-RTOS
  }
  ;
}

osKernelState_t osKernelStart (void)

Результат
  код состояния, который указывает на статус выполнения функции.

Функция osKernelStart запускает ядро RTOS и начинает переключение потоков. Онf не вернется к своей вызывающей функции в случае успеха. Перед успешным выполнением могут быть вызваны только функции osKernelGetInfo, osKernelGetState и функции создания объектов (osXxxNew).

По крайней мере, один начальный поток должен быть создан до osKernelStart, смотрите функцию osThreadNew.

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

• osError если произошла неуказанная ошибка.
• osErrorISR если вызывается из программы обработки прерываний.

Эта функция может быть вызвана из подпрограмм обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9
10
11
12
13
14

int main (void) {
  // Инициализация системы
  SystemCoreClockUpdate();
  // ...
  if(osKernelGetState() == osKernelInactive) {
    osKernelInitialize();
  }
  ; // ... Start Threads
  if (osKernelGetState() == osKernelReady) {        // Если ядро готово к запуску ...
    osKernelStart();                                // ... начать выполнение потока
    }
 
  while(1);                                         // достигается только в случае ошибки
}

int32_t osKernelLock (void)

Результат
  предыдущее состояние блокировки (1 — заблокировано, 0 — не заблокировано, код ошибки, если результат отрицательный).

Функция osKernelLock позволяет заблокировать переключение всех задач. Она возвращает предыдущее значение состояния блокировки (1, если оно было заблокировано, 0, если оно было разблокировано) или отрицательное число, представляющее код ошибки в противном случае (смотрите osStatus_t).

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

• osError если произошла неуказанная ошибка.
• osErrorISR если вызывается из программы обработки прерываний.

Пример кода

1
2
3

int32_t state = osKernelLock();
// ... критический код
osKernelRestore(state);

int32_t osKernelUnlock (void)

Результат

предыдущее состояние блокировки (1 — заблокировано, 0 — не заблокировано, код ошибки, если результат отрицательный).

Функция osKernelUnlock возобновляет работу после вызова osKernelLock. Она возвращает предыдущее значение состояния блокировки (1, если оно было заблокировано, 0, если оно было разблокировано) или отрицательное число, представляющее код ошибки в противном случае (смотрите osStatus_t).

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

• osError если произошла неуказанная ошибка.
• osErrorISR если вызывается из программы обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9

int32_t sl = osKernelLock();
// ... критический код
{
  int32_t su = osKernelUnlock();
  // ... некритический код
  osKernelRestoreLock(su);
}
// ... критический код
osKernelRestoreLock(sl);

int32_t osKernelRestoreLock (int32_t lock)

Параметры
[in] lock состояние блокировки, полученное с помощью osKernelLock или osKernelUnlock.

Результат

новое состояние блокировки (1 — заблокировано, 0 — не заблокировано, код ошибки, если результат отрицательный).

Функция osKernelRestoreLock восстанавливает предыдущее состояние блокировки после osKernelLock или osKernelUnlock.

Аргумент lock указывает состояние блокировки, полученное с помощью osKernelLock или osKernelUnlock.

Функция возвращает новое значение состояния блокировки (1, если оно было заблокировано, 0, если оно было разблокировано) или отрицательное число, представляющее код ошибки в противном случае (смотрите osStatus_t).

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

• osError если произошла неуказанная ошибка.
• osErrorISR если вызывается из программы обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9

int32_t sl = osKernelLock();
// ... критический код
{
  int32_t su = osKernelUnlock();
  // ... некритический код
  osKernelRestoreLock(su);
}
// ... критический код
osKernelRestoreLock(sl);

uint32_t osKernelSuspend (void)

Результат

время в тиках, как долго система может спать или выключаться (power-down).

CMSIS-RTOS обеспечивает расширение для работы без тиков, что полезно для приложений, которые используют режимы с низким энергопотреблением, где таймер SysTick также отключен. Чтобы обеспечить отсчет тиков времени в таких режимах энергосбережения,  используется таймер пробуждения для получения интервалов таймера. Функция osKernelSuspend приостанавливает работу планировщика ядра RTX и, таким образом, включает спящие режимы.

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

Эта функция не может быть вызвана из подпрограмм обработки прерываний.

Пример кода

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

void osRtxIdleThread (void) {
/* Ожидающий поток запускается, когда нет других потоков готовых к запуску                      */
  unsigned int sleep;
 
  for (;;) {
                                               /* Здесь можно разместить пользовательский код который нужно запустить когда нет запущенных потоков*/
    sleep = osKernelSuspend();                 /*Приостановить работу планировщика потоков RTX */
 
    if (sleep) {                               /* Как долго мы можем спать?       */
                                               /* "сон" в тиках таймера RTX
                                                   что составляет 1 мс в этой
                                                   конфигурации              */
 
                                               /* Настройка пробуждения, например watchdog  */
 
      __WFE();                                 /* Вход в режим выключения питания        */
 
                                               /* После пробуждения                 */
      sleep = tc;                              /* Отрегулируйте с циклами сна     */  
    }
 
    osKernelResume(sleep);                     /* Восстановить планировщик*/
  }
}

void osKernelResume (uint32_t sleep_ticks )

Параметры
[in] sleep_ticks время в тиках, как долго система находилась в режиме сна или выключения.

CMSIS-RTOS обеспечивает расширение для работы без тиков, что полезно для приложений, которые используют режимы с низким энергопотреблением, где таймер SysTick также отключен. Чтобы обеспечить отсчет тиков времени в таких режимах энергосбережения, таймер пробуждения используется для получения интервалов таймера. Функция osKernelResume включает планировщик ядра RTX и, таким образом, выводит систему из спящего режима.

Эта функция не может быть вызвана из подпрограмм обработки прерываний.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

void osRtxIdleThread (void) {
/* Ожидающий поток запускается, когда нет других потоков готовых к запуску                      */
  unsigned int sleep;
 
  for (;;) {
                                               /* Здесь можно разместить пользовательский код который нужно запустить когда нет запущенных потоков*/
    sleep = osKernelSuspend();                 /*Приостановить работу планировщика потоков RTX */
 
    if (sleep) {                               /* Как долго мы можем спать?       */
                                               /* "сон" в тиках таймера RTX
                                                   что составляет 1 мс в этой
                                                   конфигурации              */
 
                                               /* Настройка пробуждения, например watchdog  */
 
      __WFE();                                 /* Вход в режим выключения питания        */
 
                                               /* После пробуждения                 */
      sleep = tc;                              /* Отрегулируйте с циклами сна     */  
    }
 
    osKernelResume(sleep);                     /* Восстановить планировщик*/
  }
}

uint32_t osKernelGetTickCount (void)

Результат

Текущее количество тиков ядра RTOS.

Функция osKernelGetTickCount возвращает текущее количество тиков ядра RTOS.

Эта функция может быть вызвана из подпрограмм обработки прерываний.

1
2
3
4
5
6
7
8
9

void Thread_1 (void *arg)  {                // Функция потока
  uint32_t tick;
  tick = osKernelGetTickCount();            // получить количество системных тиков
  for (;;) {
    tick += 1000;                           // задержка 1000 тиков периодически
    osDelayUntil(tick);
    // ...
  }
}

Из-за ограниченного диапазона значений, используемого для подсчета тиков, он может переполниться во время выполнения, то есть после (2 в 32 степени) тиков, что примерно составляет 49 дней при 1 мс. Как правило, не нужно особенно заботиться об этом, если не нужен монотонный счетчик. Для такого случая дополнительный 64-битный счетчик тиков может быть реализован следующим образом. В данном примере требуется, чтобы GetTick() вызывался как минимум дважды за переполнение тика для правильной работы.

1
2
3
4
5
6
7
8
9
10
11

uint64_t GetTick(void) {
  static uint32_t tick_h = 0U;
  static uint32_t tick_l = 0U;
         uint32_t tick;
  tick = osKernelGetTickCount();
  if (tick < tick_l) {
    tick_h++;
  }
  tick_l = tick;
  return (((uint64_t)tick_h << 32) | tick_l);
}

uint32_t osKernelGetTickFreq ( void )

Результат
частота тиков ядра в герцах, т.е. тиков ядра в секунду.

Функция osKernelGetTickFreq возвращает текущую частоту тиков ядра RTOS.

Эта функция может быть вызвана из подпрограмм обработки прерываний.

uint32_t osKernelGetSysTimerCount ( void )

Результат
Текущий системный таймер ядра RTOS счетчик как 32-битное значение.

Функция osKernelGetSysTimerCount возвращает текущий системный таймер ядра RTOS в виде 32-разрядного значения.

Эта функция может быть вызвана из подпрограмм обработки прерываний.

uint32_t osKernelGetSysTimerFreq ( void )

Результат
частота системного таймера в герцах, т. е. такты таймера в секунду.

Функция osKernelGetSysTimerFreq возвращает частоту текущего системного таймера ядра RTOS.

Эта функция может быть вызвана из подпрограмм обработки прерываний.