В этой статье приведен перевод раздела "Timer Service" из документации "VisualDSP++ 5.0 Device Drivers and System Services Manual for Blackfin® Processors" [1]. Описывается Служба Таймеров, предоставляющая простой в использовании интерфейс программирования (API) для доступа к таймеру ядра, сторожевому таймеру (watchdog), таймерам общего назначения процессора Blackfin.

Рассматриваются следующие вопросы:

• Общее описание работы Службы Таймеров
• Интерфейс программирования (API)
• Публичные типы данных, перечисления и макросы

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

Прим. переводчика: под "клиентом" подразумевается код программы приложения или код потока (для многопоточных приложений).

Для поддержки всех функций Службы Таймеров требуется использование Менеджера Прерываний [2] и Менеджера DCB [3]. Если вызовы callback-функций делаются не откладываемыми, а немедленно исполняемыми в обработчике прерывания таймера, то Менеджер DCB не нужен. Если callback-функции не нужны, то тогда не нужен ни Менеджер Прерываний, ни Менеджер DCB.

Чтобы уменьшить необходимое количество ножек корпуса процессора, выводы таймеров иногда совмещаются на тех же выводах, которые используют другие периферийные устройства. Служба Таймеров не предоставляет функционал арбитража для управления мультиплексированием вывода процессора. Поэтому программа клиента должна гарантировать, чтобы периферийное устройство и Служба Таймеров не использовали один и тот же вывод одновременно. Для процессоров ADSP-BF531, ADSP-BF532, ADSP-BF533 и процессоров ADSP-BF561, это требует гарантии корректной установки соответствующих регистров управления периферийными устройствами. Для ADSP-BF534, ADSP-BF536, ADSP-BF537 (и будущих) процессоров Служба Таймеров автоматически привлекает службу управления портами, чтобы повлиять на любые изменения в мультиплексоре вывода. При этом никакое вмешательство пользователя не требуется.

Служба Таймеров использует недвусмысленное соглашение об именовании, обеспечивающее отсутствие конфликтов имен с другими программными библиотеками от Analog Devices или других источников кода. Все значения перечислений и операторы typedef используют префикс ADI_TMR_, и функции и глобальные переменные используют эквивалентный префикс в нижнем регистре adi_tmr_.

Каждая функция в интерфейсе программирования (API) Службы Таймеров возвратит код ошибки из перечисления типа ADI_TMR_RESULT. Как и у всех системных служб, возвращаемое значение 0 (ADI_TMR_RESULT_SUCCESS) показывает отсутствие ошибок. Не нулевое значение показывает ошибку. Как и у всех системных служб, коды ошибок Службы Таймеров являются уникальными, отличающимися от всех других системных служб. Подключаемый файл adi_tmr.h перечисляет все коды ошибки, которые возвращает Служба Таймеров.

Проверка параметров в отладочных версиях библиотеки Системных Служб предоставляют более полный тест параметров API-функции и условий, которые могут привести к ошибкам. Компания Analog Devices настоятельно рекомендует разрабатывать приложения с помощью debug-версий библиотеки Системных Служб, и заключительное тестирование и окончательную разработку следует выполнять на release-версии библиотеки.

[Общее описание работы Службы Таймеров]

В этом разделе описаны общие принципы работы Службы Таймеров. Подробное описание каждой функции см. в разделе "Интерфейс программирования (API) Службы Таймеров".

Инициализация Службы Таймеров. Перед использованием Службы Таймеров клиент должен должен сначала её инициализировать. Для этого клиент передает функции инициализации adi_tmr_Init() параметр, который передается функции критического региона, чтобы защитить регион кода. Также опционально в функцию инициализации передается непрерывный блок памяти, чтобы служба могла использовать функции обратного вызова (callback).

Если клиент задал использование callback-функции, то её вызов будет срабатывать, когда время таймера истекло. См. секцию "Функции обратного вызова (callback)" для получения дополнительной информации о функционировании callback-ов. В отличие от других системных служб, когда клиент предоставляет службе память, чтобы она могла работать, Служба Таймеров не требует никакой дополнительной памяти.

Завершение работы Службы Таймеров. Когда клиенту больше не нужна функциональность Службы Таймеров, вызывается функция завершения adi_tmr_Terminate(). Эта функция деинсталлирует все инсталлируемые callback-и таймеров и закрывает все открытые таймеры.

Идентификаторы таймеров (Timer ID). Всем функциям API Службы таймеров, кроме функций инициализации и завершения, передается параметр, который идентифицирует управляемый таймер. Подключаемый файл для службы таймеров adi_tmr.h, задает идентификаторы таймеров, поддерживаемые используемым процессором. Параметр timer ID определен как тип u32, но это не простое значение перечисления. В действительности timer ID это комплексное значение, которое содержит информацию, специфичную для таймера, и которую можно объединить операцией ИЛИ таким образом, что несколько таймеров можно разрешить или запретить одновременно.

Базовые функции таймеров. Функции, описанные в этом разделе, являются общими для всех типов таймеров: таймеры общего назначения, таймер ядра, сторожевой таймер. В эти функции может быть передан любой индивидуальный идентификатор таймера (timer ID), независимо от того, к какому таймеру этот идентификатор относится - таймеру общего назначения, таймеру ядра или сторожевому таймеру.

adi_tmr_Open. Функция adi_tmr_Open() вызывается, чтобы открыть таймер. В зависимости от используемого процессора Blackfin, эта функция инициализирует аппаратуру, необходимую для работы таймера. Эта функция также сбрасывает таймер в его настройки по умолчанию. См. также описание функции во врезке adi_tmr_Open.

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

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

Функции таймеров общего назначения. В этой секции описаны функции, применяемые только для обычных таймеров. Как правило, в процессоре Blackfin таких таймеров несколько. Эти функции вернут ошибку, если в них будет передан неправильный идентификатор таймера, такой как core timer ID или watchdog timer ID.

adi_tmr_GPControl. Функция adi_tmr_GPControl() конфигурирует таймер общего назначения. В эту функцию передается timer ID, идентификатор команды (command ID), указывающий адресуемый параметр функции, и параметр, зависящий от команды. Список идентификаторов команд, применимый для таймеров общего назначения и соответствующие командам параметры описаны во врезке ADI_TMR_GP_CMD. См. также описание функции во врезке adi_tmr_GPControl.

adi_tmr_GPGroupEnable. Функция adi_tmr_GPGroupEnable() разрешает или запрещает таймер общего назначения или сразу группу таймеров общего назначения. В эту функцию передается параметр, в котором задан либо один идентификатор таймера, либо сразу несколько, объединенных друг с другом операцией ИЛИ. Также передается флаг, показывающий, что нужно сделать с таймером или группой таймеров - разрешить (если значение флага TRUE) или запретить (если значение флага FALSE).

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

Функции таймера ядра. Описанные в этой секции функции используются только для таймера ядра (core timer).

adi_tmr_CoreControl. Функция adi_tmr_CoreControl() используется для конфигурирования таймера ядра. Аналогично функции управления таймерами общего назначения, эта функция принимает идентификатор команды, указывающую адресуемый параметр функции, и параметр, зависящий от команды. Список команд, применимых к таймеру ядра, и соответствующих зависящих от команды параметров описан во врезке ADI_TMR_CORE_CMD.

См. также описание функции во врезке adi_tmr_CoreControl.

Функции сторожевого таймера. Описанные в этой секции функции используются только для сторожевого таймера (watchdog timer).

adi_tmr_WatchdogControl. Функция adi_tmr_WatchdogControl() конфигурирует сторожевой таймер. Аналогично функциям управления таймерами общего назначения и таймером ядра, эта функция принимает идентификатор команды, указывающую адресуемый параметр функции, и параметр, зависящий от команды. См. также описание функции во врезке adi_tmr_WatchdogControl.

Список команд, применимых к сторожевому таймеру, и соответствующих зависящих от команды параметров описан во врезке ADI_TMR_WDOG_CMD.

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

adi_tmr_GetPeripheralID. Функция adi_tmr_GetPeripheralID() может быть вызвана, чтобы определить идентификатор периферийного устройства (peripheral ID) для указанного таймера. Хотя эта функция обычно не нужна, она все-таки может быть полезна, если требуется более изощренная логика управления прерыванием, чем может быть предоставлена Службой Таймеров. Значение peripheral ID может быть передано в функции обслуживания прерывания. Имейте в виду, что таймер ядра не имеет связанного peripheral ID, потому что таймер ядра привязан к фиксированному уровню IVG. Несмотря на это, идентификатор таймера ядра может быть передан в эту функцию, и она не возвратит код ошибки. См. также описание функции во врезке adi_tmr_GetPeripheralID.

Функции обратного вызова (callback). Как и другие системные службы, Служба Таймеров использует механизм callback-ов, чтобы оповещать клиента об асинхронных событиях, таких как истечение времени таймера. Callback-и могут использоваться для всех типов таймеров: таймеры общего назначения, таймер ядра, сторожевой таймер.

Таймеры процессора Blackfin могут конфигурироваться для генерации прерываний. Служба Таймеров предоставляет внутренний обработчик прерывания (ISR), который обрабатывает прерывания от аппаратуры таймеров. Этот ISR делает соответствующие вызовы в callback-функции клиентского приложения. Когда клиент устанавливает callback на таймер, параметр для функции установки диктует, как будет использоваться callback-немедленно (live) или его выполнение будет отложено (deferred). Live callback-и выполняются прямо в контексте обработчика прерывания, а отложенные callback-и выполняются после завершения ISR, с меньшим приоритетом, с помощью Службы DCB [3].

Когда используется возможность callback для Службы Таймеров, клиентам не надо предпринимать никакие программные действия вне API Службы Таймеров. Не требуется делать вызовы Менеджера Прерываний [2] или Службы DCB [3], кроме инициализации этих служб при необходимости.

Обратите внимание, что для клиентов доступны все возможности Службы Таймеров, и можно не использовать любую из возможностей callback-функции.

adi_tmr_InstallCallback. Функция adi_tmr_InstallCallback() используется для установки callback для указанного таймера. В дополнение к идентификатору таймера (timer ID), клиент предоставляет флаг пробуждения (wakeup flag), адрес callback-функции, хендл клиента и хендл Службы DCB.

Флаг пробуждения задает, должен ли процессор выходить из состояния пониженного энергопотребления (low-power state), когда происходит событие таймера.

Адрес callback-функции задает функцию обратного вызова типа ADI_DCB_CALLBACK_FN (см. описание Менеджера DCB [3] для получения подробной информации). Будучи вызванной, callback-функция получает следующие 3 параметра:

• ClientHandle – значение, предоставленное клиентом при инсталляции callback
• ADI_TMR_EVENT_TIMER_EXPIRED – показывает, что произошло событие callback таймера
• TimerID – идентификатор таймера, который сгенерировал вызов callback

Когда функции установки callback adi_tmr_InstallCallback был передан параметр хендла Службы DCB, равный NULL, callback-функция будет выполняться немедленно (live), прямо в коде ISR. Если же хендл Службы DCB не NULL, то Служба Таймеров использует Службу DCB для запуска callback-функции.

Одна callback-функция может быть установлена и использована для любого количества таймеров; при этом callback-функция может использовать параметр TimerID, чтобы определить, какой таймер сгенерировал callback. Однако обратите внимание, что что на определенный таймер может быть инсталлирована только одна callback-функция.

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

adi_tmr_RemoveCallback. Функция adi_tmr_RemoveCallback() используется при удалении callback-а для указанного таймера. Эта функция запрещает генерацию для таймера и удаляет callback из внутренних таблиц. Для этого таймера больше не будут срабатывать callback-и, пока не будет выполнена повторная установка callback. Функция удаления callback не меняет управление таймером. Подробнее см. описание функции во врезке adi_tmr_RemoveCallback.

ADI_TMR_RESULT Result;        // возвращаемое значение
Result = adi_tmr_Init(NULL);

Result = adi_tmr_Open(ADI_TMR_GP_TIMER_0);
Result = adi_tmr_Open(ADI_TMR_GP_TIMER_1);
Result = adi_tmr_Open(ADI_TMR_CORE_TIMER);
Result = adi_tmr_Open(ADI_TMR_WDOG_TIMER);

ADI_TMR_CORE_CMD_VALUE_PAIR CoreTable [] =
{
   { ADI_TMR_CORE_CMD_SET_COUNT,       (void *)0x12345678 },
   { ADI_TMR_CORE_CMD_SET_PERIOD,      (void *)0xabcdef },
   { ADI_TMR_CORE_CMD_SET_SCALE,       (void *)0x10 },
   { ADI_TMR_CORE_CMD_SET_ACTIVE_MODE, (void *)TRUE },
   { ADI_TMR_CORE_CMD_END, NULL },
};

Result = adi_tmr_CoreControl(ADI_TMR_CORE_CMD_TABLE,
                             CoreTable);
Result = adi_tmr_GPControl(ADI_TMR_GP_TIMER_0,
                           ADI_TMR_GP_CMD_SET_PERIOD,
                           (void *)0x800000);
Result = adi_tmr_GPControl(ADI_TMR_GP_TIMER_0,
                           ADI_TMR_GP_CMD_SET_WIDTH,
                           (void *)0x400000);
Result = adi_tmr_GPControl(ADI_TMR_GP_TIMER_0,
                           ADI_TMR_GP_CMD_SET_TIMER_MODE,
                           (void *)0x1);
Result = adi_tmr_GPControl(ADI_TMR_GP_TIMER_1,
                           ADI_TMR_GP_CMD_SET_PERIOD,
                           (void *)0x800000);
Result = adi_tmr_GPControl(ADI_TMR_GP_TIMER_1,
                           ADI_TMR_GP_CMD_SET_WIDTH,
                           (void *)0x400000);
Result = adi_tmr_GPControl(ADI_TMR_GP_TIMER_1,
                           ADI_TMR_GP_CMD_SET_TIMER_MODE,
                           (void *)0x1);
Result = adi_tmr_WatchdogControl(ADI_TMR_WDOG_CMD_EVENT_SELECT,
                           (void *)0x0);
Result = adi_tmr_WatchdogControl(ADI_TMR_WDOG_CMD_SET_COUNT,
                           (void *)0x12345678);

Result = adi_tmr_WatchdogControl(ADI_TMR_WDOG_CMD_ENABLE_TIMER, (void *)TRUE);
Result = adi_tmr_GPGroupEnable(ADI_TMR_GP_TIMER_0 | ADI_TMR_GP_TIMER_1, TRUE);

Result = adi_tmr_WatchdogControl(ADI_TMR_WDOG_CMD_ENABLE_TIMER, (void *)FALSE);
Result = adi_tmr_GPGroupEnable(ADI_TMR_GP_TIMER_0 | ADI_TMR_GP_TIMER_1, FALSE);

...
Result = adi_tmr_InstallCallback(ADI_TMR_GP_TIMER_0, TRUE,
                                 (void *)0x00000000, NULL, Callback);
Result = adi_tmr_InstallCallback(ADI_TMR_GP_TIMER_1, TRUE,
                                 (void *)0x11111111, NULL, Callback);
Result = adi_tmr_InstallCallback(ADI_TMR_CORE_TIMER, TRUE,
                                 (void *)0x22222222, NULL, Callback);
Result = adi_tmr_InstallCallback(ADI_TMR_WDOG_TIMER, TRUE,
                                 (void *)0x33333333, NULL, Callback);
...

void Callback(void *ClientHandle, u32 Event, void *pArg)
{
   // Event = ADI_TMR_EVENT_TIMER_EXPIRED
   switch ((u32)pArg)
   {
   case ADI_TMR_GP_TIMER_0:
      // Здесь делается обработка события истечения времени таймера общего назначения 0.
      // ClientHandle = 0x00000000
      break;
   case ADI_TMR_GP_TIMER_1:
      // Здесь делается обработка события истечения времени таймера общего назначения 1.
      // ClientHandle = 0x11111111
      break;
   case ADI_TMR_CORE_TIMER:
      // Здесь делается обработка события истечения времени таймера ядра.
      // ClientHandle = 0x22222222
      break;
   case ADI_TMR_WDOG_TIMER:
      // Здесь делается обработка события истечения времени сторожевого таймера.
      // ClientHandle = 0x33333333
      break;
   }
}

Result = adi_tmr_RemoveCallback(ADI_TMR_GP_TIMER_0);
Result = adi_tmr_RemoveCallback(ADI_TMR_GP_TIMER_1);
Result = adi_tmr_RemoveCallback(ADI_TMR_CORE_TIMER);
Result = adi_tmr_RemoveCallback(ADI_TMR_WDOG_TIMER);

Result = adi_tmr_Terminate();

[Интерфейс программирования (API)]

В этом разделе предоставлено описание интерфейса программирования Службы Таймеров (API).

! Приведенная здесь информация была точна на момент создания этого документа. Однако следует проверить содержимое подключаемого файла adi_tmr.h Службы Таймеров, чтобы получить текущую версию информации.

ADI_TMR_RESULT adi_tmr_Init (void *pCriticalRegionArg);

ADI_TMR_RESULT adi_tmr_Open (u32 TimerID);

ADI_TMR_RESULT adi_tmr_Terminate (void);

ADI_TMR_RESULT adi_tmr_Close (u32 TimerID);

ADI_TMR_RESULT adi_tmr_Reset (u32 TimerID);

ADI_TMR_RESULT adi_tmr_CoreControl (ADI_TMR_CORE_CMD Command, void *Value);

ADI_TMR_RESULT adi_tmr_WatchdogControl (ADI_TMR_WDOG_CMD Command, void *Value);

ADI_TMR_RESULT adi_tmr_GPControl (u32 TimerID,
                                  ADI_TMR_GP_CMD Command,
                                  void *Value);

ADI_TMR_RESULT adi_tmr_GPGroupEnable (u32 TimerID, u32 EnableFlag);

ADI_TMR_RESULT adi_tmr_InstallCallback (u32 TimerID,
                                        u32 WakeupFlag,
                                        void *ClientHandle,
                                        ADI_DCB_HANDLE DCBHandle,
                                        ADI_DCB_CALLBACK_FN ClientCallback);

ADI_TMR_RESULT adi_tmr_RemoveCallback (u32 TimerID);

ADI_TMR_RESULT adi_tmr_GetPeripheralID (u32 TimerID,
                                        ADI_INT_PERIPHERAL_ID *pPeripheralID);

[Публичные типы данных, перечисления и макросы]

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

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

Идентификаторы таймеров (Timer ID). Служба Таймеров предоставляет уникальный идентификатор для каждого таймера. Timer ID это 32-битные значения, которые не просто индекс; вместо этого они представляют комбинацию из двух информационных частей. Биты 31..27 в timer ID это индекс, перечисляющий каждый таймер в системе, включая таймеры общего назначения, таймер ядра и сторожевой таймер. Биты 26..0 используются только для таймеров общего назначения, формируя маску, чтобы можно было их разрешать и запрещать одновременно, групповой операцией.

В файле adi_tmr.h предоставлены макросы для создания timer ID, для доступа к значениям бит 26..0 и для доступа к значениям бит 31..27. Эти макросы используются внутри Службы Таймеров, и обычно они не нужны для применения в приложениях. Однако, когда приложению нужно опросить все таймеры общего назначения, идентификаторы timer ID могут быть созданы макросом ADI_TMR_CREATE_GP_TIMER_ID(x), где x это число от 0 до числа ADI_TMR_GP_TIMER_COUNT-1.

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

u32 i, TimerID;
ADI_TMR_RESULT Result;

for (i = 0; i < ADI_TMR_GP_TIMER_COUNT; i++)
{
   TimerID = ADI_TMR_CREATE_GP_TIMER_ID(i);
   Result = adi_tmr_Open(TimerID);
}

Для большинства функций в API Службы Таймеров значение timer ID передается в функцию для идентификации адресуемого таймера. Однако функция adi_tmr_GPGroupEnable() может в качестве параметра получить одно значение timer ID, или сразу несколько значений timer ID, объединенных друг с другом операцией ИЛИ. Структура значений timer ID позволяет в одном передаваемом параметре для функции идентифицировать сразу несколько таймеров общего назначения.

Связанные макросы. Эти макросы определены для использования Службой Таймеров.

[Ссылки]

1. VisualDSP++ 5.0 Device Drivers and System Services Manual for Blackfin® Processors site:analog.com.
2. VDK: менеджер прерываний.
3. VDK: менеджер отложенных функций обратного вызова.
4. ADSP-BF538: таймеры.
5. Сторожевой таймер ADSP-BF538.