В этой статье приведен перевод раздела "Programmable Flag Service" из документации "VisualDSP++ 5.0 Device Drivers and System Services Manual for Blackfin® Processors" [1]. Описывается Служба Программируемых Флагов (programmable flag service, PFS) и её интерфейс программирования (API). PFS в составе библиотеки Системных Служб предоставляют приложению простой в использовании интерфейс к подсистеме программируемых флагов (которые иногда называют порты ввода/вывода общего назначения, или GPIO [4, 5]) процессора Blackfin.

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

• Функционирование Programmable Flag Service (PFS)
• Интерфейс программирования PFS (API)
• Публичные типы данных, перечисления и макросы, связанные с PFS

С использованием возможностей других служб, служба PFS позволяет клиенту управлять направлением флагов, значениями, записываемыми в них, читать уровень на флаге вывода и оповещать клиента об изменении состояния флага вывода с помощью немедленных (live) или отложенных (deferred) функций обратного вызова (callback) [2].

Прим. переводчика: почему-то компания Analog Devices выбрала называть ножки процессора флагами, а программу приложения клиентом. Эти термины в тексте документации встречаются довольно часто, так что помните, что флаги это просто ножки портов GPIO процессора, а клиент - программа приложения либо поток, который работает в этом приложении (если приложение многопоточное, наподобие VDK).

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

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

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

Служба PFS использует не конфликтующую с другими службами систему именования API. Для этого все значения перечислений (enum), операторы определения типа (typedef) используют для PFS-имен префикс ADI_FLAG_, и функции и глобальные переменные используют эквивалентный префикс с буквами в нижнем регистре adi_flag_.

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

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

[Функционирование Programmable Flag Service (PFS)]

В этом разделе описаны общие принципы работы PFS. Также приведены некоторые подробности для использования API.

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

PFS предоставляет возможность вызвать callback при определенных событиях, связанных с флагом, если это указано клиентом и он предоставил callback-функцию прерывания. Подробнее см. раздел "Функции обратного вызова (callback)".

Чтобы обслуживать callback-и и управлять ими, PFS нуждается в небольшом количестве памяти, чтобы сохранять в ней необходимую информацию о каждом callback. Точное количество памяти в байтах определяется макросом ADI_FLAG_CALLBACK_MEMORY. Клиент предоставляет количество памяти, равное ADI_FLAG_CALLBACK_MEMORY столько раз, сколько callback-ов одновременно установлено в любой момент времени.

Например, если одновременно установлены callback-и для двух флагов, то клиент предоставляет ADI_FLAG_CALLBACK_MEMORY * 2 байт памяти. Если не используются callback-и для флагов, то клиентом не нужно предоставлять память.

Завершение PFS. Когда клиенту больше не нужна функциональность службы PFS, вызывается функция завершения adi_flag_Terminate. Эта функция деинсталлирует любые callback-и флагов и любая память, предоставленная для функции инициализации флагов, возвращается обратно клиенту.

Идентификаторы флагов (Flag ID). Все функции API PFS, кроме функция инициализации и завершения, принимают параметр, который идентифицирует управляемый флаг. Этот параметр имеет тип ADI_FLAG_ID и называется идентификатором флага (flag ID). Подключаемый заголовочный файл adi_flag.h службы PFS определяет flag ID для каждого флага, предоставленного процессором. Имена flag ID указываются в форме ADI_FLAG_x, где x уникально идентифицирует отдельный флаг.

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

adi_flag_Open() вызывается перед любой из функцией управления отдельным флагом. В зависимости от специфического устройства Blackfin, функция adi_flag_Open инициализирует любую аппаратуру, необходимую для работы флага. Например, с ADSP-BF534, ADSP-BF536, ADSP-BF537 (и будущими) процессорами, эта функция конфигурирует логику управления порта с помощью системной службы управления портом для флага, используемого как ножка GPIO. На процессорах ADSP-BF561, ADSP-BF531, ADSP-BF532, ADSP-BF533 эта функция ничего не делает, и просто возвращает управление в вызывающий код (это сделано с целью унификации и упрощения портирования). Описание функции также см. во врезке adi_flag_Open.

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

adi_flag_SetDirection. Флаги можно сконфигурировать как входы или как выходы. Функция adi_flag_SetDirection() используется для установки направления работы флага на вход или выход. Эта функция не меняет значение (состояние уровня) флага. Описание функции также см. во врезке adi_flag_SetDirection.

adi_flag_Set. Когда флаг сконфигурирован как выход, функция adi_flag_Set() устанавливает значение флага в лог. 1, что переводит его в высокий уровень выходного напряжения. Описание функции также см. во врезке adi_flag_Set.

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

adi_flag_Toggle. Когда флаг сконфигурирован как выход, функция adi_flag_Toggle() инвертирует текущее значение флага. Если флаг был очищен (находился в лог. 0), то эта функция поменяет его значение на установленное (лог. 1). Если флаг был установлен (находился в лог. 1), то эта функция поменяет его значение на очищенное (лог. 0).  Описание функции также см. во врезке adi_flag_Toggle.

adi_flag_Sense. Когда флаг сконфигурирован как вход, функция adi_flag_Sense() может прочитать значение флага, и сохранить это значение в ячейку памяти, предоставленную клиентом. Если флаг очищен (в состоянии лог. 0), то в эту ячейку будет сохранено значение FALSE. Если флаг установлен (в состоянии лог. 1), то в эту ячейку будет сохранено значение TRUE. Описание функции также см. во врезке adi_flag_Sense.

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

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

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

Может случиться так, что клиентам нужно использовать все возможности службы PFS, но не использовать при этом возможности callback. Если callback-и не используются клиентом, то не нужно предоставлять память для функции инициализации службы PFS.

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

В зависимости от модели процессора Blackfin, программируемые флаги могут генерировать любое из нескольких прерываний (иногда процессор имеет ограничение, какой флаг может генерировать какое прерывание. Подробности можно узнать в соответствующем аппаратном руководстве процессора Blackfin processor Hardware Reference). Идентификатор периферийного устройства (peripheral ID) перечисляет прерывание, генерируемое этим флагом.

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

Тип срабатывания описывает, при каком условии происходит событие для вызова callback. Поддерживаются следующие типы срабатывания (все они перечислены в подключаемом файле заголовка adi_flag.h):

• Высокий уровень – вызов callback генерируется при наличии на флаге уровня лог. 1.
• Низкий уровень – вызов callback генерируется при наличии на флаге уровня лог. 0.
• Перепад нарастания – вызов callback генерируется при наличии на флаге перехода уровня от лог. 0 к лог. 1.
• Перепад спада – вызов callback генерируется при наличии на флаге перехода уровня от лог. 1 к лог. 0.
• Оба перепада – вызов callback генерируется на любом переходе уровня (обратите внимание, что этот вариант не поддерживается на моделях процессоров ADSP-BF54x).

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

• ClientHandle – значение, предоставленное клиентом, когда callback был установлен.
• ADI_FLAG_EVENT_CALLBACK – показывает событие для callback флага.
• FlagID – идентификатор флага (flag ID), задающий флаг, для которого генерируется callback.

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

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

Функция установки callback adi_flag_InstallCallback не меняет настройку флага (например его направление) и состояние флага. Описание функции также см. во врезке adi_flag_InstallCallback.

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

adi_flag_SuspendCallbacks. Функция adi_flag_SuspendCallbacks() используется для временной приостановки срабатывания callback-ов для указанного флага, но сам callback при этом не деинсталлируется. Эта функция обычно используется совместно с функцией adi_flag_ResumeCallbacks. Описание функции также см. во врезке adi_flag_SuspendCallbacks.

adi_flag_ResumeCallbacks. Функция adi_flag_ResumeCallbacks() используется для возобновления работы callback-ов, когда их работа была приостановлена функцией adi_flag_SuspendCallbacks function. Подробнее см. во врезке adi_flag_ResumeCallbacks.

adi_flag_SetTrigger. Функция adi_flag_SetTrigger() устанавливает условие для флага, которое вызывает срабатывание callback. Эта функция обычно не вызывается клиентами, потому что условие срабатывание автоматически задается функцией adi_flag_InstallCallback. Функция adi_flag_SetTrigger предоставлена для удобства тех пользователей, которые хотят получить дополнительную возможность управления callback-ами. Описание функции также см. во врезке adi_flag_SetTrigger.

// Память для службы:

static u8 FlagServiceData[ADI_FLAG_CALLBACK_MEMORY * 1];

// Возвращаемое значение:
ADI_FLAG_RESULT Result;

// Количество поддерживаемых callback-ов:
u32 ResponseCount;

Result = adi_flag_Init(FlagServiceData, sizeof(FlagServiceData),
                       &ResponseCount, NULL);

Result = adi_flag_Open(ADI_FLAG_PF0);
Result = adi_flag_Open(ADI_FLAG_PF1);

Result = adi_flag_SetDirection(ADI_FLAG_PF0, ADI_FLAG_DIRECTION_INPUT);
Result = adi_flag_SetDirection(ADI_FLAG_PF1, ADI_FLAG_DIRECTION_OUTPUT);

Result = adi_flag_Set(ADI_FLAG_PF0);      // установка выхода в лог. 1
Result = adi_flag_Clear(ADI_FLAG_PF0);    // установка выхода в лог. 0
Result = adi_flag_Toggle(ADI_FLAG_PF0);   // переключение уровня выхода

u32 Value;  //Переменная, куда будет сохранено состояние флага.
Result = adi_flag_Sense(ADI_FLAG_PF0, &Value);// Проверка состояния флага:if (Value == TRUE)
{
   // Здесь действия для лог. 1 на флаге:
   ...
}else
{
   // Здесь действия для лог. 0 на флаге:
   ...
}

...
Result = adi_flag_InstallCallback(ADI_FLAG_PF1, ADI_INT_PFA,
                                  ADI_FLAG_TRIGGER_LEVEL_HIGH,
                                  TRUE, (void *)0x12345678, NULL, Callback);
...

void Callback(void *ClientHandle, u32 Event, void *pArg)
{
   // ClientHandle = 0x12345678
   // Event = ADI_FLAG_EVENT_CALLBACK
   switch ((ADI_FLAG_ID)pArg)
   {
   case ADI_FLAG_PF1:
      // В этом месте нужно выполнить код, связанный
      // с изменением состояния флага PF1:
      break;
   // тут могут быть добавлены обработки и для других флагов:
   //case ...:
   //   break;
   }
}

Result = adi_flag_SuspendCallbacks(ADI_FLAG_PF1);

Result = adi_flag_ResumeCallbacks(ADI_FLAG_PF1);

Result = adi_flag_RemoveCallback(ADI_FLAG_PF1);

ADI_FLAG_RESULT Result;          // возвращаемое значение
Result = adi_flag_Terminate();

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

В этом разделе предоставлено описание API PFS.

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

ADI_FLAG_RESULT adi_flag_Clear(ADI_FLAG_ID FlagID);

ADI_FLAG_RESULT adi_flag_Close(ADI_FLAG_ID FlagID);

ADI_FLAG_RESULT adi_flag_Init(void *pMemory,
                              const size_t MemorySize,
                              u32 *pMaxEntries,
                              void *pEnterCriticalArg);

ADI_FLAG_RESULT adi_flag_Open(ADI_FLAG_ID FlagID);

ADI_FLAG_RESULT adi_flag_Sense(ADI_FLAG_ID FlagID, u32 *pValue);

ADI_FLAG_RESULT adi_flag_Toggle(ADI_FLAG_ID FlagID);

ADI_FLAG_RESULT adi_flag_Terminate(void);

ADI_FLAG_RESULT adi_flag_Set(ADI_FLAG_ID FlagID);

ADI_FLAG_RESULT adi_flag_SetDirection(ADI_FLAG_ID FlagID,
                                      ADI_FLAG_DIRECTION Direction);

ADI_FLAG_RESULT adi_flag_SetTrigger(ADI_FLAG_ID FlagID,
                                    ADI_FLAG_TRIGGER Trigger);

ADI_FLAG_RESULT adi_flag_InstallCallback(ADI_FLAG_ID FlagID,
                                         ADI_INT_PERIPHERAL_ID PeripheralID,
                                         ADI_FLAG_TRIGGER Trigger,
                                         u32 WakeupFlag,
                                         void *ClientHandle,
                                         ADI_DCB_HANDLE DCBHandle,
                                         ADI_DCB_CALLBACK_FN ClientCallback);

ADI_FLAG_RESULT adi_flag_RemoveCallback(ADI_FLAG_ID FlagID);

ADI_FLAG_RESULT adi_flag_ResumeCallbacks(ADI_FLAG_ID FlagID,
                                         ADI_INT_PERIPHERAL_ID PeripheralID);

ADI_FLAG_RESULT adi_flag_SuspendCallbacks(ADI_FLAG_ID FlagID,
                                          ADI_INT_PERIPHERAL_ID PeripheralID);

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

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

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

[Ссылки]

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