В этой статье приведен перевод раздела "STDIO Service" из документации "VisualDSP++ 5.0 Device Drivers and System Services Manual for Blackfin® Processors" [1]. Описывается использование Службы STDIO из библиотеки Системных Служб.

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

• Быстрый старт с STDIO
• API Службы STDIO
• Структуры, определения и перечисления, относящиеся к API STDIO

Служба STDIO помогает перенаправить потоки стандартного ввода/вывода STDIO (STDIN, STDOUT и STDERR) в различные периферийные устройства. Каждый поток STDIO может быть перенаправлен на различные выходные устройства. Например, по умолчанию работающий через JTAG-интерфейс поток STDIN можно перенаправить на устройство UART. API разработано так, что в будущем можно будет поддерживать большее количество устройств (пока поддерживается только UART).

Служба STDIO разработана в расчете на работу в многопоточном окружении. В таком случае используются нижележащие службы RTOS, чтобы защитить критические регионы кода.

[Быстрый старт с STDIO]

В этой секции приведено общее описание работы службы STDIO. Подробности API можно найти в разделе "API Службы STDIO". Все функции API и связанные определения, структуры и перечисления можно найти в подключаемом файле заголовка adi_stdio.h.

Инициализация. Перед использованием службы STDIO приложению нужно инициализировать службу вызовом функции adi_stdio_Init.

Функция adi_stdio_Init инициализирует все внутренние структуры данных службы STDIO. Чтобы защитить структуры данных от переинициализации, когда они используются, эта функция может быть вызвана только один раз. Обратите внимание, что если приложение вызвало функцию adi_stdio_Terminate, то для того, чтобы снова можно было использовать службу STDIO, нужно повторно вызвать adi_stdio_Init.

Каждое устройство STDIO требует некоторого количества памяти, чтобы содержать в ней внутренние структуры данных. Требуемая память выделяется динамически службой STDIO из системной кучи (system heap) с использованием функций выделения памяти из кучи. Приложение должно также передать хендлы для других требуемых служб (Менеджер Устройств [2], Менеджер DMA [3] и Менеджер DCB [4]) через функцию инициализации. Функция инициализации возвратит хендл на устройство STDIO по умолчанию (JTAG). Хендл STDIO по умолчанию можно использовать для перенаправления потоков STDIO обратно на устройство по умолчанию. Кусок кода ниже показывает типичную процедуру инициализации.

#include < services/stdio/adi_stdio.h > /* подключаемый файл службы STDIO */

uint32_t main(void)
{
   ADI_STDIO_RESULT eResult;  //переменная для кода возврата
   // Здесь должна быть инициализация других требуемых служб, чтобы
   // получить adi_dev_ManagerHandle, adi_dma_ManagerHandle.
   ...
   // Инициализация службы STDIO:
   eResult = adi_stdio_Init(
         adi_dev_ManagerHandle,  // хендл Менеджера Устройств
         adi_dma_ManagerHandle,  // хендл Менеджера DMA
         adi_dcb_ManagerHandle,  // хендл Менеджера DCB
         // Указатель на хендл устройства JTAG STDIO:
         &hSTDIOJTAG);
   // Проверка, была ли служба STDIO успешно инициализирована:
   if(eResult != ADI_STDIO_RESULT_SUCCESS)
   {
      // Что-то пошло не так, здесь должен быть код по обработке
      // ошибки:
      ...
   }
   ...
   ...
}

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

// Регистрация типа устройства UART:
adi_stdio_RegisterUART();

Открытие требуемого устройства STDIO. Как только требуемое устройство было зарегистрировано для службы STDIO, оно может быть открыто. Устройство STDIO должно быть открыто перед тем, как в него можно будет перенаправить любые потоки STDIO. Служба STDIO берет на себя заботу по конфигурированию устройства STDIO значениями по умолчанию (см. секцию "Команды (ADI_STDIO_COMMAND)" для значений по умолчанию для каждого параметра конфигурации), чтобы сделать устройство работоспособным. Приложение использует интерфейс управления (API-функция adi_stdio_ControlDevice), чтобы поменять конфигурационные значения по умолчанию. Следующий код показывает процедуру открытия устройства UART.

// Открытие типа устройства UART:
eResult = adi_stdio_OpenDevice(ADI_STDIO_DEVICE_TYPE_UART,  // UART Device Type
                               0,                           // физический номер устройства
                               &hSTDIOUART                  // указатель на хендл
                              );

// Проверка, было ли успешно открыто устройство STDIO:

if(eResult != ADI_STDIO_RESULT_SUCCESS)
{
   // Ошибка открытия типа устройства STDIO, здесь нужно предпринять
   // соответствующие действия:
   ...
}

Конфигурирование устройства STDIO. После того, как устройство открыто, его можно сконфигурировать, чтобы поменять конфигурационные значения по умолчанию (см. секцию "Команды (ADI_STDIO_COMMAND)", где приведены значения по умолчанию для каждого конфигурационного параметра). Этот шаг можно пропустить, если значения по умолчанию конфигурации подходят для нужд приложения. Следующий код показывает пример, как запретить эхо символов на устройстве STDOUT.

// Запрет символьного эха для устройства UART:
eResult = adi_stdio_ControlDevice(hSTDIOUART,    // UART Device Type
                                  ADI_STDIO_COMMAND_ENABLE_CHAR_ECHO, /* Command ID */
                                  (void *) false // false, чтобы запретить
                                 );

// Проверка, была ли успешно выполнена команда:

if(eResult != ADI_STDIO_RESULT_SUCCESS)
{
   // Что-то пошло не так, команда управления STDIO не выполнена.
   // Здесь должны быть предприняты для этого соответствующие действия:
   ...
}

Перенаправление потока STDIO. После того, как устройство было открыто, любой из стандартных потоков STDIO (STDIN, STDOUT, STDERR) могут быть перенаправлен в это открытое устройство. Потоки STDIO перечислены в ADI_STDIO_STREAM_STDIN, ADI_STDIO_STREAM_STDOUT, ADI_STDIO_STREAM_STDERR для STDIN, STDOUT, STDERR соответственно, и ADI_STDIO_STREAM_ALL_CONSOLE_IO представляет все три потока STDIO. См. секци. "Типы потоков (ADI_STDIO_STREAM_TYPE)" для более подробного объяснения типов потоков. По умолчанию все потоки STDIO направлены в устройство по умолчанию STDIO (JTAG) библиотекой кода реального времени выполнения (run-time library). Приложение может выбрать отдельный поток STDIO, и перенаправить этот поток в устройство STDIO, которое было открыто, и остальные потоки останутся направленными в устройство STDIO по умолчанию. Следующий кусок кода показывает перенаправление всех потоков на устройство UART, которое уже открыто.

// Перенаправление всех потоков STDIO на UART:
eResult = adi_stdio_RedirectStream (hSTDIOUART, // UART Device Handle
                                    ADI_STDIO_STREAM_ALL_CONSOLE_IO // тип потока
                                   );

// Проверка, были ли потоки успешно перенаправлены:

if(eResult != ADI_STDIO_RESULT_SUCCESS)
{
   // Не получилось перенаправить потоки STDIO, здесь должны быть
   // предприняты соответствующие действия:
   ...
}

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

Запрет потока STDIO. Если необходимо, приложение может запретить отдельный поток. Когда отдельный поток запрещен, его поток данных перенаправляется в устройство NULL. Это делается внутри службы STDIO. Такая возможность полезна, когда приложению нужно запретить вывод всех отладочных сообщений в окне консоли. В таком случае, приложение может запретить поток STDOUT (ADI_STDIO_STREAM_STDOUT) и все еще продолжать выводить сообщения об ошибках, сохраняя поток STDERR разрешенным. Следующий код показывает, как запретить работу потока STDOUT.

// Запрет только потока STDOUT:
eResult = adi_stdio_DisableStream (
                     ADI_STDIO_STREAM_STDOUT // тип потока, который будет запрещен
                                  );

// Проверка, были ли успешно запрещен поток:

if(eResult != ADI_STDIO_RESULT_SUCCESS)
{
   // Что-то пошло не так, не получилось запретить поток STDOUT, здесь
   // должны быть предприняты по этому поводу какие-то действия:
   ...
}

Завершение. Служба STDIO может быть завершена вызовом функции adi_stdio_Terminate. После того, как служба STDIO была завершена, её API перестанет работать. Чтобы использовать API службы STDIO, она должна быть заново инициализирована.

// Завершение службы STDIO:
eResult = adi_stdio_Terminate();

// Проверка, была ли служба STDIO успешно завершена:

if (eResult != ADI_STDIO_RESULT_SUCCESS)
{
   // Не получилось завершить службу STDIO, здесь должны быть
   // предприняты соответствующие действия:
   ...
}

[API Службы STDIO]

В этом разделе описан интерфейс программирования (API) службы STDIO. Чтобы защититься от конфликтов с другими библиотеками Analog Devices или библиотеками других источников, служба STDIO использует недвусмысленное соглашение об именовании: значения перечислений и операторы typedef используют для имен префикс ADI_STDIO_. Функции и глобальные переменные получают аналогичный префикс в нижнем регистре adi_stdio_.

Каждая API-функция службы STDIO возвращает код ошибки типа ADI_STDIO_RESULT. Наподобие других Системных Служб, возвращаемое значение 0 (ADI_STDIO_RESULT_SUCCESS) показывает, что не было ошибки при вызове функции. Любое ненулевое значение сигнализирует об ошибке определенного типа. Коды ошибки для службы STDIO уникальны от кодов ошибок других системных служб, и они определены в подключаемом файле adi_stdio.h. Это позволяет пользователю определить причину ошибки, просматривая описание кодов ошибок в этом файле.

ADI_STDIO_RESULT adi_stdio_Init (ADI_DEV_MANAGER_HANDLE const hDeviceMgr,
                                 ADI_DMA_MANAGER_HANDLE const hDMAMgr,
                                 ADI_DCB_HANDLE const hDcbMgr,
                                 ADI_STDIO_DEVICE_HANDLE *phDefaultDevice);

void adi_stdio_RegisterUART (void);

ADI_STDIO_RESULT adi_stdio_OpenDevice (ADI_STDIO_DEVICE_TYPE eDeviceType,
                                       uint32_t nPhysicalDevNum,
                                       ADI_STDIO_DEVICE_HANDLE *phStdioDevice);

ADI_STDIO_RESULT adi_stdio_RedirectStream (ADI_STDIO_DEVICE_HANDLE hStdioDevice,
                                           ADI_STDIO_STREAM_TYPE eStreamType);

ADI_STDIO_RESULT adi_stdio_DisableStream (ADI_STDIO_STREAM_TYPE eStreamType);

ADI_STDIO_RESULT adi_stdio_ControlDevice (ADI_STDIO_DEVICE_HANDLE hStdioDevice,
                                          uint32_t nCommandID,
                                          void *const pValue);

ADI_STDIO_RESULT adi_stdio_CloseDevice (ADI_STDIO_DEVICE_HANDLE const hStdioDevice);

ADI_STDIO_RESULT adi_stdio_Terminate (void);

[Структуры, определения и перечисления, относящиеся к API STDIO]

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

Типы потоков (ADI_STDIO_STREAM_TYPE). В таблице 14-1 приведен список перечисления поддерживаемых типов потоков STDIO. Эти значения используются для указания потока, который должен быть перенаправлен в определенное устройство, или для запрета потока.

Таблица 14-1. Типы потоков и их описание.

Типы устройств (ADI_STDIO_DEVICE_TYPE). В таблице 14-2 приведен список перечисления поддерживаемых типов устройств STDIO. Тип устройства используется для открытия устройства с STDIO.

Таблица 14-2. Типы устройств и их описание.

Команды (ADI_STDIO_COMMAND). Здесь приведены описания некоторых команд, доступных для установки или получения конфигурационного параметра.

uint8_t nWordLength;

uint8_t nStopBits;

uint8_t cAutoBaud;

uint16_t nBaudRate;

Типы четности (ADI_STDIO_PARITY_TYPE). В таблице 14-3 приведен список перечисления для возможных типов проверки данных на четность.

Таблица 14-3. Типы четности и их описание.

Коды возврата (ADI_STDIO_RESULT). В таблице 14-4 приведен список перечисления возможных кодов возврата из API-функций службы STDIO.

Таблица 14-4. Коды возврата и их описание.

[Ссылки]

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