В этой статье приведен перевод раздела "Port Control Service" из документации "VisualDSP++ 5.0 Device Drivers and System Services Manual for Blackfin® Processors" [1]. Описывается Служба Управления Портами, доступная для всех процессоров Blackfin с портами ввода/вывода общего назначения (GPIO), начиная с процессоров ADSP-BF534, ADSP-BF536, ADSP-BF537.

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

• Использование Менеджера Управления Портами.
• Виртуальные устройства и индексация устройств.
• Менеджер Управления Портами и его API.
• Публичные типы данных, перечисления и макросы.

Служба Менеджера Управления Портами (port control manager service) в составе библиотеки Системных Служб предоставляет разработчику клиентских приложений возможность присваивания различных функций портам GPIO. Например, различные данные, такты и сигналы фрейма, требуемые для SPORT0, могут быть настроены единственным вызовом функции adi_ports_EnableSPORT.

Когда это необходимо, MMR-регистры для соответствующих периферийных устройств будут опрошены для определения поведения периферийного устройства. Например, Менеджер Управления Портами может прочитать регистр PPI_CONTROL, чтобы определить, требуется ли 2 внутренних сигнала синхронизации фрейма (frame sync). Однако в зоне ответственности кода клиентской программы находится конфигурирования регистров управления PPI, перед тем как будут разрешены необходимые выводы флагов. Это обычная практика модели драйверов устройств, где управление портами и значения флагов осуществляются в точке разрешения потока данных.

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

Служба Управления Портами применима для процессоров, у которых есть поддержка управления портами, что является для всех процессоров Blackfin стандартной функцией, начиная с класса процессоров ADSP-BF534, ADSP-BF536 и ADSP-BF537 Blackfin.

Все поддерживаемые процессоры Blackfin используют одинаковый общий базовый API Службы Управления Портами, включая функции adi_ports_Init() и adi_ports_Terminate(). Начальное управлений портами (на процессорах ADSP-BF534, ADSP-BF536 и ADSP-BF537) также включено в выделенном вызове функции adi_ports_EnableXxx() для каждого из соответствующих устройств (Xxx соответствует PPI, SPI, SPORT и т. д.). Эти разрешающие функции работают с фиксированным набором ресурсов и все еще поддерживаются в целях совместимости.

Поскольку на новых процессорах Blackfin появились более разнообразные встроенные аппаратные ресурсы и возможности расширенного мультиплексирования порта, то управляющие функции разрешения портов (adi_ports_EnableXxx()) были перенесены в соответствующий код драйвера как более общий стандартный API adi_ports_Configure() который поддерживает более надежное и динамическое управление аппаратурой и мультиплексированием.

Независимо от того, используется ли устаревшее (все еще поддерживаемое) adi_ports_EnableXxx() API, или более новое adi_ports_Configure() API, Менеджер Управления Портами использует непротиворечивое соглашение об именовании, чтобы защититься от конфликтов с другими программными библиотеками, предоставленными компанией Analog Devices или какими-нибудь другими источниками. Все значения перечислений и операторы typedef используют префикс ADI_PORTS_, и функции и глобальные переменные используют эквивалентный префикс в нижнем регистре adi_ports_.

Описание API (старого и нового) находится в разделе "Менеджер Управления Портами и его API". Примеры использования находятся в разделе "Использование Менеджера Управления Портами".

[Использование Менеджера Управления Портами]

В зависимости от семейства процессоров, для облуживания конфигураций устройств и портов используются либо API adi_ports_EnableXxx() для устаревших моделей (ADSP-BF534, ADSP-BF536 и ADSP-BF537) или adi_ports_Configure() для более новых моделей процессоров. Пример для каждого варианта будет показан в этом разделе документации.

Использование устаревшего API adi_ports_EnableXxx(). Чтобы продемонстрировать работу Менеджера Управления Портами, в примере представлена конфигурация PPI для двух внутренних frame sync. Менеджер Управления Портами инициализируется следующим образом.

adi_ports_Init(      // Инициализация Менеджера Управления Портами.
               NULL  // Не требуется специальной области данных для
                     // критических регионов кода.
              );

Чтобы разрешить выводы флагов для требуемого использования PPI, функция adi_ports_EnablePPI вызывается с массивом директив, который определяет, как конфигурировать регистр.

// Конфигурирование регистра PPI_CONTROL:
ADI_PPI_CONTROL_REG ppi_control;
ppi_control.port_en = 0;   // запрет до готовности
ppi_control.port_dir = 0;  // режим приема
ppi_control.xfr_type = 3;  // не режим ITU-R 656
ppi_control.port_cfg = 1;  // 2 или 3 сигнала frame sync
ppi_control.dlen = 7;      // длина данных 16 бит
ppi_control.polc = 0;      // не инвертировать PPI_CLK
ppi_control.pols = 0;      // не инвертировать PPI_FS1 и PPI_FS2

// установка PPI_COUNT в 1 для выборки двух 16-битных слов.
u16 ppi_count = 1;
u16 ppi_frame = 1;
ADI_DEV_CMD_VALUE_PAIR PPI_config[] =
{
   { ADI_PPI_CMD_SET_CONTROL_REG, (void*)(*(u16*)&ppi_control) },
   { ADI_PPI_CMD_SET_TRANSFER_COUNT_REG, (void*)(*(u16*)&ppi_count) },
   { ADI_PPI_CMD_SET_LINES_PER_FRAME_REG, (void*)(*(u16*)&ppi_frame) },
   { ADI_DEV_CMD_END, 0 }
};

// Программирование периферийного устройства PPI:
adi_dev_Control(ppiHandle,
                ADI_DEV_CMD_TABLE,
                (void*)PPI_config);

// Другой код конфигурирования для PPI, таймеров, и т. д.

// будет где-то в клиентском коде.

// Конфигурирование выводов для использования PPI:
u32 ppi_config[] = { ADI_PORTS_DIR_PPI_BASE };
adi_ports_EnablePPI(ppi_config,                    // массив директив
                    sizeof(ppi_config)/sizeof(u32),// количество директив
                    1                              // разрешить PPI
                   );

// Разрешить поток данных:
adi_dev_Control(ppiHandle, ADI_DEV_CMD_SET_DATAFLOW, 1);

И наконец, когда Менеджер Управления Портов больше не нужен, служба останавливается вызовом adi_ports_Terminate:

adi_ports_Terminate();

Использование более нового API adi_ports_Configure(). Здесь тоже используются общие функции adi_ports_Init() и adi_ports_Terminate(). В контексте нового API следующий пример показывает такое же конфигурирование PPI, но с использованием adi_ports_Configure() (это кусок кода из реализации драйвера PPI для процессора ADSP-BF518 Blackfin).

static u32 ppiSetPortControl (ADI_PPI *pDevice, u32 OpenFlag)
{
   u32 nDirectives;  // Количество передаваемых директив
   u32 eResult;      // Код возврата

   /* Директивы для разрешения портов тактов и данных PPI */
   ADI_PORTS_DIRECTIVE aePpiClkDataDirectives [] =
   {
      ADI_PORTS_DIRECTIVE_PPI_CLK_MUX2,
      ADI_PORTS_DIRECTIVE_PPI_D0,
      ADI_PORTS_DIRECTIVE_PPI_D1,
      ADI_PORTS_DIRECTIVE_PPI_D2,
      ADI_PORTS_DIRECTIVE_PPI_D3,
      ADI_PORTS_DIRECTIVE_PPI_D4,
      ADI_PORTS_DIRECTIVE_PPI_D5,
      ADI_PORTS_DIRECTIVE_PPI_D6,
      ADI_PORTS_DIRECTIVE_PPI_D7,
      ADI_PORTS_DIRECTIVE_PPI_D8,
      ADI_PORTS_DIRECTIVE_PPI_D9,
      ADI_PORTS_DIRECTIVE_PPI_D10,
      ADI_PORTS_DIRECTIVE_PPI_D11,
      ADI_PORTS_DIRECTIVE_PPI_D12,
      ADI_PORTS_DIRECTIVE_PPI_D13,
      ADI_PORTS_DIRECTIVE_PPI_D14,
      ADI_PORTS_DIRECTIVE_PPI_D15,
   };
   
   /* Директивы для разрешения портов PPI frame sync */
   ADI_PORTS_DIRECTIVE aePpiFsDirectives [] =
   {
      ADI_PORTS_DIRECTIVE_PPI_FS1_MUX2,
      ADI_PORTS_DIRECTIVE_PPI_FS2_MUX2,
      ADI_PORTS_DIRECTIVE_PPI_FS3
   };
   
   /* Для устройства PPI нужны выводы тактов и данных по умолчанию от 0 до 7 */
   nDirectives = 9;

   /* Если (длина данных PPI больше 8 бит) */
   if (pDevice->PPIControl->dlen > 0)
   {
      /* Разрешить остальные выводы данных в зависимости от длины данных PPI */
      /* PPI не поддерживает 9-битные данные, так что счетчик директив

         увеличивается на длину данных + 1 */
      nDirectives += (pDevice->PPIControl->dlen + 1);
   }
   
   /* Вызов управления портами для разрешения выводов тактов и данных PPI */
   eResult = adi_ports_Configure(aePpiClkDataDirectives, nDirectives);
   
   /* Если (выводы данных и тактов PPI успешно разрешены) */
   if (eResult == ADI_PORTS_RESULT_SUCCESS)
   {
      /* Если (PPI сконфигурирован для использования frame sync) */
      if (pDevice->PPIControl->xfr_type == 3)
      {
         /* предположительно не требуется отправка директив FS */
         nDirectives = 0;
         /* Если (PPI конфигурируется в режиме передачи) */
         if (pDevice->PPIControl->port_dir)
         {
            /* Если (используется 2 или 3 frame sync) */
            if ((pDevice->PPIControl->port_cfg == 1) ||
                (pDevice->PPIControl->port_cfg == 3))
            {
               /* Разрешить FS2 и FS3 */
               nDirectives = 2;
            }
         }
         /* Иначе (PPI конфигурируется в режиме приема) */
         else
         {
            /* Если (используется 2 или 3 frame sync) */
            if ((pDevice->PPIControl->port_cfg == 1) ||
                (pDevice->PPIControl->port_cfg == 2))
            {
               /* Разрешить FS2 и FS3 */
               nDirectives = 2;/
            }
         }
         /* Вызов управления портами для разрешения выводов FS PPI */
         eResult = adi_ports_Configure(aePpiFsDirectives, nDirectives);
      }
   }
   return (eResult);
}

[Виртуальные устройства и индексация устройств]

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

Термин "виртуальный" может также рассматриваться как "вторичный". Однако важно помнить, что номер устройства это индекс массива, начинающийся с 0, который распространяется на все "первичные" привязки устройства плюс все "виртуальные" (или вторичные) привязки.

Например, процессоры ADSP-BF526 и ADSP-BF527 имеют два разных встроенных устройства SPORT (SPORT0 и SPORT1). Физическая привязка SPORT к соответствующим выводам портов управляется кодом драйвера SPORT (adi_sport.c) через набор специфических для процессора определений привязок выводов (adi_ports_bf52x.h), таких как ADI_PORTS_DIRECTIVE_SPORT0F_DRPRI. Код драйвера выбирает подходящую привязку, основываясь на индексе устройства, как это было указано в параметре DevNumber вызова функции adi_dev_open().

В рассматриваемом случае SPORT0 и SPORT1 имеют первичные привязки к разным выводам PORTF, соответствующие индексам устройства 0 и 1. Но SPORT0 также предоставляет вторичную привязку через PORTG как устройство с индексом 2, реализуя третье существующее периферийное устройство, хотя фактически в процессоре имеется только два физических устройства SPORT.

Записи в таблице виртуальных устройств (и индексация) используются всякий раз, когда периферийное устройство может быть привязано к нескольким вариантам ножек портов. Будет ошибкой привязать одно и то же физическое устройство одновременно к нескольким вариантам выводов; для работы поддерживается только одна физическая привязка, независимо от того, какая она - первичная или вторичная (виртуальная). Для процессоров ADSP-BF526 и ADSP-BF527 имеется только 2 устройства SPORT: SPORT0 может быть привязан к PORTF (индекс устройства 0) или к PORTG (индекс устройства 2), но не одновременно к обоим, в то время как привязка SPORT1 ограничена единичной первичной привязкой как устройство с индексом 1.

[Менеджер Управления Портами и его API]

В этом разделе описан интерфейс программирования (application programming interface, API) Службы Менеджера Управления Портами.

! Устаревшее API (adi_ports_EnableXxx()) также подробно описано в этом разделе. Более новое API (adi_ports_Configure()) описано здесь в общем виде, и дополнительные подробности см. в соответствующей документации Драйвера Устройства, находящейся в подкаталоге документации .../Blackfin/docs.

ADI_PORTS_RESULT adi_ports_Init (void *pCriticalRegionArg);

ADI_PORTS_RESULT adi_ports_Terminate (void);

ADI_PORTS_RESULT adi_ports_Configure (ADI_PORTS_DIRECTIVE *pDirectives,
                                      u32 nDirectives);

ADI_PORTS_RESULT adi_ports_EnablePPI (u32 *Directives,
                                      u32 nDirectives,
                                      u32 Enable);

ADI_PORTS_RESULT adi_ports_EnableSPI (u32 *Directives,
                                      u32 nDirectives,
                                      u32 Enable);

ADI_PORTS_RESULT adi_ports_EnableSPORT (u32 *Directives,
                                        u32 nDirectives,
                                        u32 Enable);

ADI_PORTS_RESULT adi_ports_EnableUART (u32 *Directives,
                                       u32 nDirectives,
                                       u32 Enable);

ADI_PORTS_RESULT adi_ports_EnableCAN (u32 *Directives,
                                      u32 nDirectives,
                                      u32 Enable);

ADI_PORTS_RESULT adi_ports_EnableTimer (u32 *Directives,
                                        u32 nDirectives,
                                        u32 Enable);

ADI_PORTS_RESULT adi_ports_EnableGPIO (u32 *Directives,
                                       u32 nDirectives,
                                       u32 Enable);

ADI_PORTS_RESULT adi_ports_ClearProfile (ADI_PORTS_PROFILE *profile);

ADI_PORTS_RESULT adi_ports_GetProfile (ADI_PORTS_PROFILE *profile);

ADI_PORTS_RESULT adi_ports_SetProfile (ADI_PORTS_PROFILE *profile);

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

В этом разделе определены устаревшие публичные структуры данных и перечисления, используемые Менеджером Управления Портами в API-вызовах adi_ports_EnableXxx().

! Всегда проверяйте содержимое подключаемого заголовочного файла Менеджера Управления Портами adi_ports.h, или соответствующий подключаемый файл драйвера устройства (для более новых процессоров), чтобы получить самую актуальную информацию об API.

! Более новое API (adi_ports_Configure()) документировано в соответствующей документации по драйверу устройства, находящейся в подкаталоге .../Blackfin/docs.

[Ссылки]

1. VisualDSP++ 5.0 Device Drivers and System Services Manual for Blackfin® Processors site:analog.com.
2. VDK: менеджер прерываний.
3. VDK: служба таймеров.