Данные, который вдвигаются через устройство или выдвигаются через устройство наружу, инкапсулируются в буфере. API Менеджера Устройств определяет 3 разные типа буфера:

• Одномерные буферы ADI_DEV_1D_BUFFER
• Двумерные буферы ADI_DEV_2D_BUFFER
• Кольцевые буферы (автобуферы) ADI_DEV_CIRCULAR_BUFFER

Из-за того, что физическое перемещение данных связано со значительными вычислительными затратами, между программными компонентами передаются только указатели на буферы. API Менеджера Устройств определяет тип данных ADI_DEV_BUFFER как указатель на объединение (union) одномерного буфера, двумерного буфера и кольцевого буфера. Хотя каждый из этих типов обрабатывается по-разному, нет значительных отличий в обработке, так что в этой документации они все вместе упоминаются просто как буфер.

Обычно приложения предоставляют буферы через API-функции Менеджера Устройств, где буферы обрабатываются и затем снова делаются доступными для приложения. Функция adi_dev_Write предоставляет устройству буферы, которые содержат данные для отправки через устройство. Соответственно функция adi_dev_Read предоставляет устройству буферы, которые устройство заполняет приходящими данными.

Буферы обрабатываются в том порядке, в котором они были получены. Буферы, предоставленные для определенного устройства, не должны быть какого-то универсального размера; каждый индивидуальный буфер может иметь любой произвольный размер. Кроме того, для одного устройства могут быть предоставлены как одномерные, так и двумерные буферы. Кольцевые буферы более сложные (подробнее см. врезку "Предоставление буферов для устройства").

Перед использованием устройства приложение (или клиент) должно сначала инициализировать Менеджер Устройств. Клиент делает это вызовом функции adi_dev_Init, в которую передается блок памяти, который Менеджер Устройств может использовать для своей внутренней обработки. Клиент решает, какое количество памяти (и какая область памяти используется, SRAM или SDRAM) следует предоставить Менеджеру Устройств; чем больше памяти предоставлено, тем большее количество физических устройств может быть открыто одновременно.

Менеджер Устройств требует для себя непрерывный блок памяти, которую делит внутри себя на 2 части. Одна часть это базовая память, необходимая Менеджеру Устройств для инициации самого себя, и другая часть памяти требуется для поддержки n одновременно открытых драйверов устройств. Предоставляются макросы (ADI_DEV_BASE_MEMORY и ADI_DEV_DEVICE_MEMORY), чтобы определить количество памяти (в байтах), требуемое соответственно для базовой памяти и для открытых добавляемых драйверов устройств.

Например, если клиент хочет инициализировать Менеджер Устройств, и нужно в любой момент времени обеспечить одновременное открытие 4 драйверов устройств, то требуемое количество памяти в байтах будет вычисляется следующим образом:

ADI_DEV_BASE_MEMORY+(ADI_DEV_DEVICE_MEMORY*4))

Будучи вызванной, функция adi_dev_Init(), инициализирует предоставленную память. Как и все функции Менеджера Устройств, функция инициализации вернет код, который покажет специфическую ошибку, возникшую при вызове функции. Все API-функции Менеджера Устройств возвратят код ADI_DEV_RESULT_SUCCESS, если вызов функции был завершен успешно. Все коды возврата по ошибке имеют имена вида ADI_DEV_RESULT_XXXX.

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

Другой параметр, передаваемый в функцию adi_dev_Init(), это параметр критического региона. Когда необходимо защитить критический регион кода, Менеджер Устройства и все физические драйверы полагаются на системную службу Менеджера Прерываний [4], чтобы защитить критический код. Параметр критического региона передается в adi_dev_Init(), после чего он внутренне передается в функцию adi_int_EnterCriticalRegion(). Подробнее см. врезку с описанием функции adi_int_Init на страничке [4].

Примечание: текущая реализация библиотеки системных служб и VDK не использует вложенные критические регионы, поэтому в параметре критического кода может быть передан любой параметр. Т. е. обычное приложение VisualDSP или VDK приложение должно вызвать adi_int_Init с параметром NULL для критической секции кода. Если же используется RTOS, отличающаяся от VDK, или в приложении используются вложенные критическое области, то значение в этом параметре зависит от использования критических секций кода в этой RTOS или приложении.

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

√ Во многих встраиваемых системах работа Менеджера Устройств никогда не завершается.

После того, как Менеджер Устройств был инициализирован, для использования устройства клиент должен сначала вызвать API-функцию adi_dev_Open() для открытия устройства. Клиент передает в неё параметры, показывающие драйвер устройства, который надо открыть (параметр pEntryPoint), номер устройства, которое надо открыть (параметр DevNumber; он нужен, потому что однотипных устройств в процессоре может быть несколько, так что они нумеруются по порядку, начиная с 0 - например SPI0, SPI1 и т. д.), направление потока данных (inbound, outbound или both), и т. д. Клиент также передает хендл на службу DMA для использования Менеджером Устройств и физическим драйвером. Этот параметр может быть равен NULL, если клиент знает, что это устройство не использует DMA.

Параметр pDeviceHandle указывает на место в памяти, куда Менеджер Устройства сохранит хендл на открываемый драйвер устройства. Все последующие вызовы API для этого устройства должны использовать этот хендл. ClientHandle это параметр, который Менеджер Устройств передает обратно клиенту при каждом вызове callback-функции клиента.

В функцию adi_dev_Open() еще передаются 2 других параметра. Они также связаны с функцией callback. Параметр DCBHandle это хендл на службу отложенных функций обратного вызова (Менеджер DCB [5]), которая должна использоваться для вызова клиентской callback-функции. Если DCBHandle не NULL, то драйвер устройства использует указанную службу отложенных функций обратного вызова для всех запусков callback этого устройства. Если же указано DCBHandle равным NULL, все вызовы callback будут немедленными (live); это означают, что их выполнение не будет отложено на менее приоритетный код, и они будут сразу выполняться в контексте обработчика аппаратного прерывания (обычно это ISR, работающий на каком-то уровне приоритета IVG). Параметр ClientCallback указывает на callback-функцию клиента.

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

Поток данных не начинается с вызовом функции adi_dev_Open(). Эта функция просто открывает устройство для использования; для устройства может потребоваться некое конфигурирование, чтобы мог начаться поток данных через устройство.

Функция adi_dev_Control() используется для конфигурирования и разрешения/запрета потока данных через устройство. При открытии большинство драйверов инициализируют устройство некоторыми настройками по умолчанию. Если эти настройки подходят для приложения, то со стороны приложения потребуются совсем незначительные настройки, или они совсем не потребуются. В других случаях, когда настройки драйвера по умолчанию не соответствуют потребностям приложения, для устройства требуется некоторое конфигурирование. Для того, чтобы выполнить настройки, и определить, какие настройки сейчас используются, предназначена функция adi_dev_Control().

Эта функция получает в качестве параметров DeviceHandle (указывающий на открытое устройство, см. врезку "Открытие устройства"), идентификатор команды (command ID, который задает действие - установить параметры устройства или их прочитать), и указатель на область памяти, где содержится значение устанавливаемого параметра (или куда должно быть записано значение считанного параметра). Менеджер Устройств определяет некоторые стандартные параметры; однако физические драйверы свободны в добавлении своих собственных идентификаторов команд помимо определенных Менеджером Устройств. Например, драйвер физического устройства может создать command ID, чтобы установить уровень громкости на выходе.

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

Независимо от того, какие нужно сделать изменения конфигурации устройства для клиента, он должен сделать (как минимум) 2 вызова функции adi_dev_Control(). Эти вызовы устанавливают метод работы потока данных (см. врезку ниже), и разрешают поток данных для устройства.

Возможные методы потока данных определены в перечислении ADI_DEV_MODE, которое находится в файле adi_dev.h (папка Blackfin\include\drivers в каталоге установки VisualDSP++ 5.0):

typedef enum {                          /* Методы потока данных (Dataflow) */
    ADI_DEV_MODE_UNDEFINED,             /* не определено */
    ADI_DEV_MODE_CIRCULAR,              /* кольцевой буфер */
    ADI_DEV_MODE_CHAINED,               /* цепочка буферов */
    ADI_DEV_MODE_CHAINED_LOOPBACK,      /* цепочка с автопереходом на начало цепочки */
    ADI_DEV_MODE_SEQ_CHAINED,           /* последовательность цепочек буферов */
    ADI_DEV_MODE_SEQ_CHAINED_LOOPBACK   /* последовательность цепочек с переходом на начало */
} ADI_DEV_MODE;

Менеджер Устройств поддерживает 3 метода потока данных: circular (кольцевой или автобуфер), chained (соединение буферов в цепочку) и chained with loopback (цепочка буферов с возвратом на начало цепочки). Перед предоставлением для Менеджера Устройств каких-либо буферов или разрешением потока данных, приложение должно информировать Менеджер Устройства об используемом методе работы потока данных вызовом функции adi_dev_Control() с идентификатором команды ADI_DEV_CMD_SET_DATAFLOW_METHOD. После того, как метод потока данных был определен, клиент должен может предоставить для устройства входящие буферы (вызовом функции adi_dev_Read) или исходящие буферы (вызовом функции adi_dev_Write).

Как показано на рис. 10-2, метод кольцевого потока использует один предоставляемый для Менеджера Устройств кольцевой буфер, при этом предполагается, что устройство было открыто для однонаправленного трафика.

Рис. 10-2. Работа кольцевого буфера (автобуфер).

Когда Менеджеру Устройств предоставляется кольцевой буфер, приложение информирует Менеджер Устройств о том, сколько находится подбуферов внутри кольцевого буфера; два подбуфера используется для традиционной схемы двойной буферизации (ping-pong), хотя процессоры Blackfin поддерживают любое количество подбуферов. Приложение также говорит Менеджеру Устройств, когда оно хочет вызвать callback во время обработки кольцевого буфера.

Предоставляется 3 опции для организации оповещения приложения об обработке буфера: никогда не вызывать callback, callback после обработки каждого подбуфера и callback после обработки всего буфера. Менеджер Устройства начинает обработку от начала буфера. Установленным способом Менеджер Устройств оповещает приложение путем вызова callback-функции, когда завершается обработка каждого подбуфера, или когда был обработан весь буфер целиком. После того, как был достигнут конец буфера, Менеджер Устройств автоматически перезапускает обработку с начала буфера, и процесс циклически продолжается.

На рис. 10-3 показан метод потока данных с соединением буферов в цепочку (chained dataflow), где для Менеджера Устройств предоставлен один или большее количество одномерных и/или двумерных буферов. Может быть предоставлено любое количество буферов; буферы могут быть любых размеров, для одного и того же устройства могут быть предоставлены как одномерные, так и двумерные буферы. Только один из всех буферов, или все буферы, или никакой из буферов могут быть помечены для генерации вызова callback-функции приложения, когда буфер был обработан. Дополнительные буферы могут быть предоставлены в любой момент времени - либо до, либо после того, как поток данных было разрешен. Менеджер Устройств гарантирует обработку буферов в том порядке, в каком они были предоставлены для Менеджера Устройств.

Рис. 10-3. Соединенные в цепочку буферы (chained dataflow).

Когда используется метод chained dataflow, приложение может дать команду Менеджеру Устройств работать в синхронном режиме. Обычно Менеджер Устройств работает в асинхронном режиме, когда функции adi_dev_Read и adi_dev_Write сразу делают возврат в приложение до того, как были обработаны предоставленные ими буферы. В синхронном режиме функции adi_dev_Read и adi_dev_Write не возвратят управление, пока не будут обработаны все предоставленные ими буферы. Хотя синхронный режим редко когда используется в системах реального времени, Менеджер Устройств все-таки предоставляет такую возможность.

На рис. 10-4 показан метод потока данных с соединением буферов в цепочку, когда после обработки последнего буфера происходит возврат на начало цепочки (chained dataflow with loopback). Он похож на метод обработки chained dataflow, отличие только в том, что Менеджер Устройств после обработки последнего буфера возвращается к обработке первого буфера в цепочке, предоставленной устройству. Такой метод потока данных эффективно создает бесконечный цикл из последовательности буферов. При использовании метода chained with loopback приложение может предоставить буферы во время инициализации, позволяя Менеджеру Устройств обрабатывать буферы, после чего не предоставлять Менеджеру Устройств никакие буферы. При таком методе работы, так же и как с методом chained dataflow, для каждого одного буфера в цепочке, для всех буферов цепочки, или ни для одного буфера цепочки может быть задано запускать вызов функции callback для оповещения приложения.

Рис. 10-4. Соединенные в цепочку буферы с возвратом на начало (Loopback).

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

Буферы для устройства предоставляются через вызовы API-функций adi_dev_Read и adi_dev_Write. Функция adi_dev_Read предоставляет буферы для входящих данных, adi_dev_Write для исходящих данных. Каким образом клиент предоставляет буферы для устройства через эти вызовы API зависит с небольшими различиями от выбранного метода работы потока данных (см. врезку "Методы работы потока данных").

Когда устройство сконфигурировано для использования кольцевого метода потока данных (circular dataflow), приложение предоставляет драйверу устройства один и только один буфер для входящих данных и/или один и только один буфер для исходящих данных. Данные предоставленных буферов указывают на непрерывные участки памяти, соответствующие однако нескольким подбуферам, которые приложение хочет использовать.

Например, предположим, что приложение хочет обработать данные в инкрементах по 512 байт, и хочет работать традиционным способом "ping-pong" (2 подбуфера). Тогда приложение предоставляет драйверу устройства 1 буфер данных размером 1024 байта, состоящий из 2 подбуферов, каждый по 512 байт. Таким способом одновременно могут быть использованы два подбуфера - с одним подбуфером из 512 байт работает приложение, а с другим подбуфером из 512 байт работает драйвер.

Другой пример - приложение хочет обработать стандартный кадр видео формата NTSC (525 строк, на каждую по 1716 байт). Буфер, предоставленный для Менеджера Устройств, должен быть непрерывным куском памяти размером 900900 байт (525 * 1716). В этом случае количество подбуферов будет 525. Независимо от того, сколько предоставлено подбуферов, с методом кольцевого потока данных (circular dataflow), для драйвера устройства предоставлен один буфер, приложению никогда не нужно предоставлять устройству другой буфер, поскольку один и тот же буфер используется бесконечно.

Когда устройство сконфигурировано для использования метода потока данных с цепочкой буферов (chained dataflow), для устройства может быть предоставлено любое количество одномерных и двумерных буферов. Буферы могут быть предоставлены для устройства либо по одному, либо сразу несколько, через один вызова adi_dev_Read и/или один вызов adi_dev_Write. Приложение может предоставить Драйверу Устройства дополнительные буферы в любое время до (или даже после) момента разрешения потока данных. Предположим, что Драйвер Устройства работает в асинхронном режиме, тогда любой один из буферов, или никакой из буферов, или все буферы, или только некоторые из них, могут быть помечены для генерации callback, когда драйвер устройства завершил его обработку. Каждый буфер может быть индивидуального размера, и для одного и того же устройства может быть предоставлены как одномерные, так и двумерные буферы.

Предоставление буферов для метода потока с цепочкой буферов и переходом от конца к началу цепочки (chained-with-loopback dataflow) идентично предоставлению буферов для устройств, использующих метод chained dataflow, за исключением того, что буферы могут быть предоставлены только когда поток данных запрещен.

Когда устройство больше не нужно для клиента, то оно закрывается вызовом API-функции adi_dev_Close. Она завершает поток данных, если он был разрешен, и освобождает все ресурсы, включая DMA и другие, используемые Драйвером Устройства. Если приложению нужно опять использовать устройство после того, как оно было закрыто, оно может быть открыто повторно вызовом API-функции adi_dev_Open.

Менеджер Устройств вызывает callback-функцию приложения, чтобы оповестить клиента о происходящих событиях. События бывают ожидаемые (такие как завершение обработки буфера) или неожиданные (такие как ошибка на аппаратуре устройства). Обычно callback-функция клиента организована как эквивалентный оператор switch на языке C, вовлекая подходящую обработку, какая требуется для имеющегося типа события. Менеджер Устройств определяет несколько событий, и физические драйверы могут добавить дополнительные события, которые требуются для управляемого ими устройства.

Поскольку Менеджер Устройств и физические драйверы полагаются на системные сервисы, то эти сервисы должны быть инициализированы перед открытием Драйвера Устройства. Например, когда открывается Драйвер Устройства, то Менеджер Устройств нуждается в хендлах к службе отложенных функций обратного вызова (хендл Менеджера DCB [5]) и к службам DMA (хендл Менеджера DMA) - если предположить, что используются и DCB, и DMA. Таким образом, хорошей практикой будет инициализировать и открыть системные службы перед открытием любого Драйвера Устройства. См. "Инициализация" и "Завершение" в статье [2] для дополнительной информации по драйверам устройств и системным службам.

Могут быть созданы такие драйверы, которые вызывают другие драйверы. Например, плата разработчика Blackfin EZ-KIT Lite содержит аудиокодек AD1836. Этот кодек имеет интерфейс управления и статуса, который подходит для подключения к порту SPI, в то время как аудиоданные AD1836 представляются устройству использованием высокоскоростной последовательной линии связи (в этом случае периферийное устройство SPORT). Если система разработана так, что кодек AD1836 это только одно устройство, подключенное к процессору, то один физический драйвер должен быть написан для управления и обслуживания SPI и SPORT.

Альтернативно драйвер AD1836 может быть иерархически находиться над драйверами SPI и SPORT, делая вызовы в эти физические драйверы по мере необходимости. Это особенно верно, если другие периферийные устройства также совместно используют порт SPI (например, разные драйверы SPI и SPORT могут управляться драйвером AD1836). Таким методом в виде стека могут быть созданы более сложные драйверы, такие как драйвер AD1836 или драйвер стандартного стека TCP/IP, находящегося поверх драйвера контроллера Ethernet.

Структура данных ADI_DEV_1D_BUFFER используется для описания линейного массива данных, который обрабатывает Драйвер Устройства. Приложения заполняют различные поля в буфере, полностью описывающие данные для Драйвера Устройства. Для одномерных буферов приложения заполняют следующие поля в структуре ADI_DEV_1D_BUFFER:

Data. Если буфер предоставлен функции adi_dev_Write(), то это поле содержит начальный адрес данных (Data это указатель), отправляемых наружу из устройства. Если буфер был предоставлен для функции adi_dev_Read(), то это поле содержит начальный адрес области памяти, куда Драйвер Устройства будет сохранять данные, принятые устройством снаружи.

ElementCount. Это поле показывает количество элементов, на которое указывает поле Data.

ElementWidth. Это поле показывает ширину (в байтах) каждого элемента данных.

CallbackParameter. Это указатель на параметр функции обратного вызова приложения. Если здесь указано значение NULL, то Драйвер Устройства не будет использовать вызов callback после обработки буфера. Если же здесь не NULL, то Драйвер Устройства запустит callback-функцию приложения после того, как буфер был обработан драйвером, при этом в callback-функцию третьим параметром будет передано значение CallbackParameter.

pNext. Это поле указывает на следующий одномерный буфер в цепочке, если таковой имеется. Если здесь NULL, то этот буфер последний в цепочке, предоставленный для функций adi_dev_Read() или adi_dev_Write(). Если не NULL, то это поле содержит адрес следующего одномерного буфера в цепочке буферов, переданной в функцию adi_dev_Read() или adi_dev_Write().

pAdditionalInfo. Это поле содержит значение, зависящее от драйвера. Оно не используется большинством Драйверов Устройств. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

Когда буферы были предоставлены для Драйвера Устройства через функции adi_dev_Read() или adi_dev_Write(), некоторые Драйверы Устройства не требуют заполнения следующих полей:

ProcessedFlag. Некоторые Драйверы Устройств устанавливают это значение в TRUE после обработки буфера. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

ProcessedElementCount. Некоторые Драйверы Устройств устанавливают это значение в количество элементов, обработанных драйвером для этого буфера. Например, если сетевому драйверу предоставлен буфер размером 100 байт функцией adi_dev_Read(), для входящего пакета, который содержит только 75 байта данных, драйвер может установить это значение в число 75. Это должно означать, что хотя было запрошено 100 байт, имеется в наличии всего лишь 75 байт. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

Например, следующий фрагмент кода подготавливает и предоставляет одиночный буфер из 128 элементов, каждый размером 16 бит для функции adi_dev_Read(). Драйвер вызовет callback-функцию приложения, когда буфер будет обработан, передавая значение 0x12345678 в качестве параметра callback-функции.

#define SAMPLES_PER_BUFFER (128)    // количество выборок (элементов)
                                    // в буфере данных

static u16 Data[SAMPLES_PER_BUFFER];// хранилище для данных

static ADI_DEV_1D_BUFFER Buffer;    // актуальный буфер

// создание буфера для обработки драйвером
Buffer.Data = Data;
Buffer.ElementCount = SAMPLES_PER_BUFFER;
Buffer.ElementWidth = 2;
Buffer.CallbackParameter = (void *)0x12345678;  // параметр pArg = 0x12345678 для
                                                // callback-функции
Buffer.pNext = NULL; // только один буфер в цепочке

// предоставление буфера для драйвера, чтобы он заполнил его данными:
Result = adi_dev_Read(Handle, ADI_DEV_1D, (ADI_DEV_BUFFER*)&Buffer);

Следующий фрагмент кода подготавливает и предоставляет для функции adi_dev_Read() цепочку из 4 буферов, каждый из которых описан как 128 элементов, каждый по 32 бита данных. Драйвер запустит callback-функцию приложения после обработки каждого буфера, передавая адрес буфера, который был обработан, в качестве параметра для callback-функции.

#define NUM_BUFFERS (4)          // количество используемых буферов

#define SAMPLES_PER_BUFFER (128) // количество выборок (элементов) в буфере данных

static u32 Data[NUM_BUFFERS*SAMPLES_PER_BUFFER];

// хранилище для актуальных буферов

static ADI_DEV_1D_BUFFER Buffer[NUM_BUFFERS];

// создание буферов для обработки драйвером:

for (u32 i = 0; i < NUM_BUFFERS; i++)
{
   Buffer[i].Data = &Data[i * SAMPLES_PER_BUFFER];
   Buffer[i].ElementCoun = SAMPLES_PER_BUFFER;
   Buffer[i].ElementWid = 4;
   Buffer[i].CallbackParameter = &Buffer[i]; // при запуске callback-функции её
   Buffer[i].pNext = &Buffer[i+1];           // параметр, pArg будет равен адресу
                                             // буфера в цепочке
}
Buffer[NUM_BUFFERS - 1].pNext = NULL;        // завершение цепочки буферов

// предоставление буферов для драйвера, чтобы он заполнил их данными:
Result = adi_dev_Read(Handle, ADI_DEV_1D, (ADI_DEV_BUFFER*)Buffer);

Структура данных ADI_DEV_2D_BUFFER используется для описания двумерного массива данных, который обрабатывает Драйвер Устройства. Приложение заполняет различные параметры этой структуры, чтобы полностью описать данные для Драйвера Устройства. Для двумерных буферов приложение заполняет следующие поля структуры ADI_DEV_2D_BUFFER:

Data. Если буфер предоставлен функции adi_dev_Write(), то это поле содержит начальный адрес данных (Data это указатель), отправляемых наружу из устройства. Если буфер был предоставлен для функции adi_dev_Read(), то это поле содержит начальный адрес области памяти, куда Драйвер Устройства будет сохранять данные, принятые устройством снаружи.

ElementWidth. Это поле показывает ширину (в байтах) каждого элемента данных.

XCount. Это поле задает количество элементов - столбцов.

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

YCount. Это поле задает количество элементов - строк.

YModify. Это поле задает байтовый инкремент адреса (переход по буферу) после передачи каждой строки.

CallbackParameter. Это указатель на параметр функции обратного вызова приложения. Если здесь указано значение NULL, то Драйвер Устройства не будет использовать вызов callback после обработки буфера. Если же здесь не NULL, то Драйвер Устройства запустит callback-функцию приложения после того, как буфер был обработан драйвером, при этом в callback-функцию третьим параметром будет передано значение CallbackParameter.

pNext. Это поле указывает на следующий одномерный буфер в цепочке, если таковой имеется. Если здесь NULL, то этот буфер последний в цепочке, предоставленный для функций adi_dev_Read() или adi_dev_Write(). Если не NULL, то это поле содержит адрес следующего двумерного буфера в цепочке буферов, переданной в функцию adi_dev_Read() или adi_dev_Write().

pAdditionalInfo. Это поле содержит значение, зависящее от драйвера. Оно не используется большинством Драйверов Устройств. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

Когда буферы были предоставлены для Драйвера Устройства через функции adi_dev_Read() или adi_dev_Write(), некоторые Драйверы Устройства не требуют заполнения следующих полей:

ProcessedFlag. Некоторые Драйверы Устройств устанавливают это значение в TRUE после обработки буфера. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

ProcessedElementCount. Некоторые Драйверы Устройств устанавливают это значение в количество элементов, обработанных драйвером для этого буфера. Например, если сетевому драйверу предоставлен буфер размером 100 байт функцией adi_dev_Read(), для входящего пакета, который содержит только 75 байта данных, драйвер может установить это значение в число 75. Это должно означать, что хотя было запрошено 100 байт, имеется в наличии всего лишь 75 байт. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

Например, следующий фрагмент кода подготавливает и предоставляет для функции adi_dev_Write() пару двумерных буферов, чтобы они были переданы драйвером наружу. Каждый буфер описывает данные для кадра видео формата NTSC ITU-656. Каждый кадр содержит 525 строк, в каждой строке имеется 1716 байт данных. Драйвер вызовет callback-функцию приложения, когда будет обработан каждый буфер, передавая адрес буфера, который был только что обработан, в качестве параметра callback-функции.

#define NUM_BUFFERS  (2)      // количество буферов

#define NUM_FRAMES   (2)      // количество кадров

#define COLUMNS      (1716)   // количество столбцов

#define ROWS         (525)    // количество строк

static u8 Frames[NUM_FRAMES][COLUMNS * ROWS];   // хранилище для данных

static ADI_DEV_2D_BUFFER Buffer[NUM_BUFFERS];   // актуальные буферы

// создание буферов, которые будет обрабатывать драйвер:

for (u32 i = 0; i < NUM_BUFFERS; i++)
{
   Buffer[i].Data = &Frames[i][0];
   Buffer[i].ElementWidth = 2;
   Buffer[i].XCount = (COLUMNS >> 1);
   Buffer[i].XModify = 2;
   Buffer[i].YCount = ROWS;
   Buffer[i].YModify = 2;
   Buffer[i].CallbackParameter = &Buffer[i]; // при запуске callback-функции
                                             // её аргумент pArg = адресу буфера
   Buffer[i].pNext = &Buffer[i+1];
}
Buffer[NUM_BUFFERS - 1].pNext = NULL;        // завершение цепочки буферов

// предоставление буферов для драйвера, чтобы он отправил их:
Result = adi_dev_Write(Handle, ADI_DEV_2D, (ADI_DEV_BUFFER*)Buffer);

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

Для кольцевых буферов приложение заполняет следующие поля структуры ADI_DEV_CIRCULAR_BUFFER:

Data. Если буфер предоставлен функции adi_dev_Write(), то это поле содержит начальный адрес данных (Data это указатель), отправляемых наружу из устройства. Если буфер был предоставлен для функции adi_dev_Read(), то это поле содержит начальный адрес области памяти, куда Драйвер Устройства будет сохранять данные, принятые устройством снаружи.

ElementWidth. Это поле показывает ширину (в байтах) каждого элемента данных.

SubBufferCount. Это поле задает количество подбуферов, на которые поделены данные буфера.

SubBufferElementCount. Это поле задает количество элементов в каждом подбуфере.

CallbackType. Это поле задает, как должна вызываться callback-функция приложения, и в нем могут быть следующие значения:

   • ADI_DEV_CIRC_NO_CALLBACK - нет вызовов callback-функции.
   • ADI_DEV_CIRC_SUB_BUFFER - вызов callback-функции после обработки каждого подбуфера.
   • ADI_DEV_CIRC_FULL_BUFFER - вызов callback-функции только после обработки всего буфера целиком.

pAdditionalInfo. Это поле содержит значение, зависящее от драйвера. Оно не используется большинством Драйверов Устройств. Информацию о том, как это поле используется каждым отдельным драйвером, можно получить из документации по этому драйверу (документация находится в подкаталоге .../Blackfin/docs).

Например, следующий фрагмент кода подготавливает и предоставляет для функции adi_dev_Write() кольцевой буфер для передачи наружу через Драйвер Устройства. Буфер описан как непрерывный блок памяти из 1024 байт, поделенный на 8 подбуферов размером по 128 байт каждый. Драйвер вызовет callback-функцию приложения после обработки каждого подбуфера. Как только поток данных разрешен, драйвер с повторениями обрабатывает кольцевой буфер, пока не будет остановлен поток данных.

#define SUB_BUFFERS (8)

#define SUB_BUFFER_ELEMENTS (128)

static u8 Data[SUB_BUFFERS * SUB_BUFFER_ELEMENTS]; // хранилище для данных

static ADI_DEV_CIRCULAR_BUFFER Buffer;             // актуальный буфер

// создание буфера для обработки драйвером
Buffer.Data = Data;
Buffer.ElementWidth = 1;
Buffer.SubBufferCount = SUB_BUFFERS;
Buffer.SubBufferElementCount = SUB_BUFFER_ELEMENTS;
Buffer.CallbackType = ADI_DEV_CIRC_SUB_BUFFER;

// предоставление буфера для драйвера, чтобы он оправлял данные:
Result = adi_dev_Write(Handle, ADI_DEV_CIRC, (ADI_DEV_BUFFER*)&Buffer);

Структура ADI_DEV_SEQ_1D_BUFFER используется для описания последовательного, одномерного (линейного) массива данных, который обрабатывает Драйвер Устройства. Подобно стандартным одномерным буферам, приложение заполняет различные поля структуры, чтобы полностью описать данные для Драйвера Устройства. Фактически последовательный одномерный буфер это урезанный вариант стандартного одномерного буфера, с полем направления, добавленном в конец стандартного буфера. Для последовательных одномерных буферов приложение заполняет следующие поля структуры ADI_DEV_SEQ_1D_BUFFER:

Buffer. Указатель на буфер, идентичный полю Data стандартного одномерного буфера, который заполняется точно так же (см. врезку "Создание одномерных буферов (1D)").

Direction. Это поле заполняется следующими значениями по выбору:

   • ADI_DEV_DIRECTION_INBOUND – соответствует буферу для данных, принимаемых устройством.
   • ADI_DEV_DIRECTION_OUTBOUND – соответствует буферу для данных, передаваемых устройством.   

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

#define ELEMENT_WIDTH (1)        // ширина элемента данных в байтах

#define NUM_BUFFERS (2)          // количество буферов

#define INBOUND_ELEMENTS (64)    // количество читаемых элементов

#define OUTBOUND_ELEMENTS (2)    // количество записываемых элементов

static u32 InboundData[INBOUND_ELEMENTS];    // входящие данные

static u32 OutboundData[OUTBOUND_ELEMENTS];  // исходящие данные

static ADI_DEV_SEQ_1D_BUFFER SeqBuffer[NUM_BUFFERS];  // актуальные буферы

// создание исходящего буфера для обработки драйвером:
SeqBuffer[0].Buffer.Data = OutboundData;
SeqBuffer[0].Buffer.ElementCount = OUTBOUND_ELEMENTS;
SeqBuffer[0].Buffer.ElementWidth = ELEMENT_WIDTH;
SeqBuffer[0].Buffer.CallbackParameter = NULL;   // нет вызова callback-функции
SeqBuffer[0].Buffer.pNext = (ADI_DEV_1D_BUFFER*)&SeqBuffer[1];
SeqBuffer[0].Direction = ADI_DEV_DIRECTION_OUTBOUND;

// создание входящего буфера для обработки драйвером:
SeqBuffer[1].Buffer.Data = InboundData;
SeqBuffer[1].Buffer.ElementCount = INBOUND_ELEMENTS;
SeqBuffer[1].Buffer.ElementWidth = ELEMENT_WIDTH;
SeqBuffer[1].Buffer.CallbackParameter = &SeqBuffer[1];   // callback
SeqBuffer[1].Buffer.pNext = NULL;               // конец цепочки
SeqBuffer[1].Direction = ADI_DEV_DIRECTION_INBOUND;

// предоставление буферов для драйвера:
Result = adi_dev_SequentialIO(Handle, ADI_DEV_SEQ_1D, (ADI_DEV_BUFFER *)SeqBuffer);

Весь код Менеджера Устройств сосредоточен в файле adi_dev.c. Этот файл находится в директории Blackfin/Lib/Src/Drivers.

Структуры данных. Здесь определены только дополнительные структуры данных ADI_DEV_MANAGER и ADI_DEV_DEVICE. Эти структуры содержат все необходимы данные, которые нужны для работы самого Менеджера Устройств и управления физическим драйвером.

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

Декларации статических функций. Эта секция декларирует статические функции, которые используются в Менеджере Устройств. Каждая из них описана в следующих секциях. Глобально декларируются только функции API; все другие функции являются для Менеджера Устройств статическими.

[Функциональное описание API]

В этой секции приведено описание функциональности, выполняемой каждой из API-функций Менеджера Устройств. Вот эти функции:

• adi_dev_Init
• adi_dev_Open
• adi_dev_Close
• adi_dev_Read
• adi_dev_Write
• adi_dev_Control

Для подробной информацией по параметрам функций и их прототипам см. раздел "Интерфейс программирования (API) Менеджера Устройств".

adi_dev_Init. Эта функция используется для инициализации Менеджера Устройств. Для подробной информации о параметрах функции и кодах возврата см. её описание во врезке adi_dev_Init.

Обработка начинается с проверки, достаточно ли предоставленное количество памяти для работы Менеджера Устройств. Затем функция определяет, сколько физических устройств можно поддерживать оставшейся предоставленной памятью.

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

adi_dev_Open. Эта функция используется для открытия устройства, чтобы можно было его использовать. Для подробной информации о параметрах функции и кодах возврата см. её описание во врезке adi_dev_Open.

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

Структура ADI_DEV_DEVICE инициализируется и заполняется информацией, описывающей устройство.

Как только структура ADI_DEV_DEVICE была инициализирована, Менеджер Устройств вызывает функцию adi_pdd_Open физического драйвера. Запускается код физического драйвера, который делает все необходимое, чтобы открыть управляемое им устройство. Если физический драйвер не может открыть устройство, то Менеджер Устройств освобождает структуру ADI_DEV_DEVICE, и передает соответствующий код возврата в приложение. Обратите внимание, что из-за того, что коды возврата могут быть расширены физическим драйвером, код возврата может быть специфическим, описывающим какие-либо возможные причины ошибки при открытии устройства.

Если физическое устройство было корректно открыто, то Менеджер Устройств взаимодействует с физическим устройством, чтобы определить, поддерживается ли периферийный DMA. Менеджер Устройства сохраняет эту информацию в структуре ADI_DEV_DEVICE.

adi_dev_Close. Эта функция вызывается приложением, когда устройство больше не нужно. Для подробной информации о параметрах функции и кодах возврата см. её описание во врезке adi_dev_Close.

После того, как хендл устройства был проверен, подразумевая, что разрешена проверка на ошибку, функция вызывает функцию adi_pdd_Control физического драйвера чтобы остановить поток данных. Как только поток данных был остановлен, закрываются любые открытые устройством каналы DMA. Затем вызывается функция adi_pdd_Close физического драйвера, чтобы выключить устройство и освободить любые ресурсы, используемые физическим устройством. И в завершение структура ADI_DEV_DEVICE помечается как закрытая, так что она может быть впоследствии использована повторно.

adi_dev_Read. Эта функция вызывается приложением, чтобы предоставить устройству буферы, куда могут быть помещены приходящие данные. Предположительно проверка ошибок разрешена, тогда в этой функции обработка начинается проверкой хендла устройства на предмет того, что устройство действительно открыто для входящего (или для двунаправленного) трафика, и что определен метод потока данных. Если метод потока данных еще не задан, то Менеджеру Устройств не предоставлено достаточно информации для того, чтобы определить, что делать дальше с этим буфером. Для подробной информации о параметрах функции и кодах возврата см. её описание во врезке adi_dev_Read.

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

Как только список буферов подготовлен, проверяется поддерживается ли устройство периферийным DMA. Если да, то вызывается Менеджер DMA, чтобы поставить в очередь буферы на подходящем канале DMA, используя соответствующий метод организации потока данных - связанные в цепочку дескрипторы передаются Менеджеру DMA через вызов функции adi_dma_Queue, и кольцевые буферы передаются через функцию adi_dma_Buffer. Если периферийный DMA не поддерживается, то буферы передаются напрямую к физическому драйверу с использованием функции adi_pdd_Read. Обратите внимание, что когда устройство поддерживается периферийным DMA, физический драйвер экстремально прост, потому что Менеджер Устройств обрабатывает все буферы данных для физического устройства.

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

adi_dev_Write. Эта функция виртуально работает идентично функции adi_dev_Read, за исключением того, что предназначена для передачи данных в обратном направлении. Для подробной информации о параметрах функции и кодах возврата см. её описание во врезке adi_dev_Write.

adi_dev_Control. Эта функция используется для обработки команд приложения, относящихся к конфигурации устройства. Как и все API-функции, если разрешена проверка ошибок, на входе в функцию будет проверен хендл устройства. Для подробной информации о параметрах функции и кодах возврата см. её описание во врезке adi_dev_Control.

Обработка внутри функции adi_dev_Control основана на command ID, переданном в качестве параметра. Некоторые команды полностью обрабатываются Менеджером Устройств, а некоторые только физическим драйвером, и другие команды требуют совместной обработки и Менеджером Устройств, и физическим драйвером. Чтобы выполнить все это, блок кода этой функции выполнен как оператор switch языка C. Каждая команда Менеджеру Устройств обрабатывается отдельной веткой оператора switch.

Когда передана команда, которую должен обработать Менеджер Устройств, то он обрабатывает команду и затем устанавливает флаг, сигнализируя этим, нужно ли передать обработку команды ниже, к физическому драйверу. Когда обработка спускается ниже в функции, если нужно передать команду в физический драйвер, то вызывается функция adi_pdd_Control физического драйвера, и код возврата из физического драйвера будет передан обратно в приложение. Это позволяет каждому физическому драйверу расширить список идентификаторов команд (command ID), и позволяет создать свои собственные уникальные command ID, которыми может управлять приложение.

Менеджер Устройств обрабатывает следующие команды:

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

ADI_DEV_CMD_SET_SYNCHRONOUS. Эта команда используется для перевода Менеджера Устройств в синхронный режим для указанного устройства. Обработка команды заключается только в установке флага в структуре ADI_DEV_DEVICE. Эта команда никогда не передается физическому драйверу, так как вся синхронная активность управляется Менеджером Устройств. Скрытие синхронности от физического драйвера дает то преимущество, что для физического драйвера не требуется заботиться (не надо иметь для этого специальной обработки) о реализации синхронного или асинхронного режимов. Физический драйвер может работать таким образом, чтобы лучше всего взаимодействовать с устройством.

ADI_DEV_CMD_SET_DATAFLOW_METHOD. Эта команда используется для установки метода потока данных для указанного устройства. Если устройство не поддерживается периферийным DMA, то Менеджер Устройств не предпринимает никаких действий, кроме как обработку метода потока данных и передачи команды в физический драйвер через функцию adi_pdd_Control. Если устройство поддерживается периферийным DMA, то значение по умолчанию, используемое конфигурационным регистром управления DMA, обновляется соответствующими настройками, подходящими для метода потока данных. Кроме того, как только метод потока данных определен приложением, Менеджер Устройств открывает необходимое количество каналов DMA, требуемое для поддержки устройства. С физическим драйвером происходи взаимодействие через функцию adi_pdd_Control, с которой задается, какой контроллер DMA и какой номер канала назначается устройству для входящих и/или исходящих данных. Затем к Менеджеру DMA осуществляется доступ для открытия соответствующих каналов в соответствующих режимах, таких как кольцевые или цепочечные дескрипторы. Если устройство открыто с методом потока данных ADI_DEV_MODE_CHAINED_LOOPBACK, то Менеджер DMA также конфигурируется. Обратите внимание, что структура ADI_DEV_DEVICE поддерживается обновленной соответствующей информацией, какие контроллеры и какие каналы открыты или закрыты, в каких рабочих режимах они находятся и т. д.

ADI_DEV_CMD_SET_DATAFLOW. Эта команда выдается, чтобы разрешить или запретить поток данных через устройство. Логика, используемая для разрешения или запрещения потока довольно сложна, и изолирована в статической функции SetDataflow (см. далее её описание).

ADI_DEV_CMD_SET_STREAMING. Эта команда выдается для разрешения или запрета режима стриминга для Драйвера Устройства. Чтобы полностью понять, что влечет за собой режим стриминга, пользователи должны быть знакомы с возможностью стриминга системной службы Менеджера DMA [3]. Хотя поддержка периферийного DMA не требуется, чтобы устройство поддерживало стриминг, все-таки устройства с поддержкой периферийного DMA автоматически задействуют возможности стриминга Менеджера DMA.

Когда разрешен режим стриминга, устройство конфигурируется так, чтобы обрабатывать входящие и/или исходящие данные как продолжающийся непрерывный поток данных. Обычно это позволяет драйверу устройства передавать и принимать данные через устройство на максимально возможной скорости. Чтобы можно было использовать режим стриминга Менеджера Устройств, приложение должно гарантировать удовлетворение следующих условий:

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

• Диаграммы времени работы системы спроектированы так, что Менеджер Устройств может подтвердить и обработать callback-и для буфера перед тем, как будет сгенерирован вызов callback для другого буфера того же самого устройства и того же самого направления данных (входящего или исходящего). Эти условия можно довольно легко обеспечить в большинстве систем.

Статические функции. Ниже приведено описание статических функций Менеджера Устройств, которые используются в поддержке API-функций.

PDDCallback. Эта функция вызывается в ответ на события из физического драйвера. После проверки на ошибку хендла устройства (если разрешена проверка ошибок) Менеджер Устройств просто передает эти события обратно в приложение.

Обратите внимание, что в этой подпрограмме (и функции DMACallback) Менеджер Устройств напрямую вызовет callback-функцию клиента, независимо от того, немедленный это (live) callback, или нет. Это можно сделать, так как физическому драйверу передан хендл на службу отложенных функций обратного вызова (см. Менеджер DCB [5]) как часть функции adi_pdd_Open.

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

DMACallback. Эта функция вызывается в ответ на события DMA из Менеджера DMA для устройств, которые поддерживаются периферийным DMA. Если разрешена проверка ошибок, то сначала будет проверен хендл устройства. Затем эта функция определяет событие, которое произошло, и выполняет обработку, основываясь на типе события.

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

Если событие показывает, что обработка DMA сгенерировала событие ADI_DEV_EVENT_SUBBUFFER_PROCESSED, то функция делает соответствующий вызов callback приложения, объявляя этим о завершении обработки подбуфера. Если событие показывает, что обработка DMA сгенерировала событие ADI_DEV_EVENT_BUFFER_PROCESSED, то функция делает соответствующий вызов callback приложения, объявляя этим о завершении обработки всего буфера.

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

Обратите внимание, что в этой подпрограмме (и в функции PDDCallback) Менеджер Устройств вызывает callback-функцию клиента напрямую, не заботясь о том, немедленный (live) ли это callback или нет. Это возможно благодаря тому, что Менеджеру DMA передан хендл на службу отложенных функций обратного вызова (Менеджер DCB [5]) как часть функции adi_dma_Open. Таким образом, если используется служба отложенных обратных вызовов, то запуск функции DMACallback в Менеджере Устройств будет отложен Менеджером DMA. Таким способом функция dmaCallback может напрямую вызвать callback-функцию клиента.

PrepareBufferList. Функция подготавливает список из одного буфера или список из нескольких буферов для использования в Менеджере DMA (в том случае, когда устройство поддерживается периферийным DMA) или использования физическим драйвером (когда устройство не поддерживается периферийным DMA).

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

Если передан кольцевой буфер, то функция предполагает, что здесь есть только один буфер в списке буферов. Для устройств, открытых с методом потока данных ADI_DEV_MODE_CIRCULAR, предоставляется только один буфер, так что это предположение справедливо. Функция конфигурирует регистр управления конфигурацией DMA в соответствии с параметрами, находящимися в структуре кольцевого буфера. Регистр управления конфигурацией DMA устанавливается для генерации прерываний по внутренним циклам, если приложение хочет вызывать callback, когда завершена обработка каждого подбуфера, или устанавливается для генерации прерываний по внешним цикла, если приложение хочет вызывать callback при завершении обработки всего буфера, или ничего не настраивается для запуска callback, если приложению оповещение не нужно. Размер слова устанавливается на ширину элемента данных в буфере, и соответствующим образом устанавливается поле направления. Затем функция возвращает управления в вызывающий код.

Если в функцию передан одномерный или двумерный тип буфера, обработка буферов увеличивается с некоторыми исключениями.

Для каждого переданного буфера очищаются поля флага завершения обработки и счетчика обработки в структуре буфера. Если физическое устройство поддерживается периферийным DMA, то зарезервированная область в начале каждой структуры буфера преобразуется в модель большого дескриптора (large model descriptor). Дескриптор конфигурируется в соответствии с параметрами в структуре буфера, включая такие параметры, как размер буфера, ширина элемента, направления данных, одномерный буфер или двумерный, и т. д. Дескриптор для каждого буфера в цепочке обновляется для указания следующего буфера в цепочке. Последний дескриптор в цепочке, соответствующий последнему буферу в цепочке, обновляется значением NULL для следующего дескриптора. После завершения обработки цепочка буферов оказывается установленной. Все буферы инициализированы правильным образом, и зарезервированная область в каждом буфере содержит дескриптор DMA для этого буфера, который в свою очередь указывает на дескриптор DMA для следующего буфера в цепочке.

И наконец, если устройство открыто для синхронного режима и поддерживается периферийным DMA, по последний дескриптор в цепочке настраивается для генерации callback из Менеджера DMA к Менеджеру Устройств. Это позволяет Менеджеру Устройств получить подтверждение, когда обработан последний буфер, так чтобы он смог соответствующим образом обновить поля завершения обработки. Последний дескриптор также действует как триггер, который срабатывает каждый раз, когда функция adi_dev_Read или adi_dev_Write возвращает управление обратно в приложение.

SetDataflow. Эта функция вызывается в ответ на команду ADI_DEV_CMD_SET_DATAFLOW, принятую API-функцией adi_dev_Control. В ответ разрешается или запрещается поток данных в соответствии с флагом.

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

Когда поток данных запрещен, функция сначала вызывает функцию adi_pdd_Control физического драйвера, чтобы запретить поток данных. Если устройство использует периферийный DMA, важно сначала запретить поток на устройстве перед выключением DMA. Как только физический драйвер запретил поток данных, закрываются любые каналы DMA, которые были открыты для устройства. Это выполняется вызовом Менеджера DMA.

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

Функция adi_dev_Close() закрывает устройство. Поток данных останавливается, если он не был остановлен, и устройство переводится обратно в состояние ожидания. Чтобы можно было снова получить доступ к устройству после вызова adi_dev_Close, нужно обязательно открыть его вызовом adi_dev_Open.

u32 adi_dev_Close (ADI_DEV_DEVICE_HANDLE DeviceHandle);

Аргумент:

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

Функция adi_dev_Control() устанавливает или считывает параметр конфигурации устройства.

u32 adi_dev_Control (ADI_DEV_DEVICE_HANDLE DeviceHandle,
                     u32 Command,
                     void *pArg);

Аргументы:

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

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

u32 adi_dev_Init (void *pMemory,
                  size_t MemorySize,
                  u32 *pMaxDevices,
                  ADI_DEV_MANAGER_HANDLE *pManagerHandle,
                  void *pEnterCriticalParam);

Аргументы:

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

Функция adi_dev_Open() открывает устройство для использования. Инициализируются внутренние структуры, устанавливается предварительное управление устройством, устройство сбрасывается и подготавливается для использования.

u32 adi_dev_Open (ADI_DEV_MANAGER_HANDLE ManagerHandle,
                  ADI_DEV_PDD_ENTRY_POINT *pEntryPoint,
                  u32 DeviceNumber,
                  void *ClientHandle,
                  ADI_DEV_DEVICE_HANDLE *pDeviceHandle,
                  ADI_DEV_DIRECTION Direction,
                  ADI_DMA_MANAGER_HANDLE DMAHandle,
                  ADI_DCB_HANDLE DCBHandle,
                  ADI_DCB_CALLBACK_FN ClientCallback);

Аргументы:

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

Функция adi_dev_Read() читает данные из устройства, или ставит в очередь буферы приема для устройства.

u32 adi_dev_Read (ADI_DEV_DEVICE_HANDLE DeviceHandle,
                  ADI_DEV_BUFFER_TYPE BufferType,
                  ADI_DEV_BUFFER *pBuffer);

Аргументы:

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

Функция adi_dev_Terminate() освобождает всю память, используемую Менеджером Устройств, останавливает потоки данных, закрывает все открытые драйверы устройств и завершает Менеджер Устройств.

u32 adi_dev_Terminate (ADI_DEV_MANAGER_HANDLE ManagerHandle);

Аргумент:

Возвращаемое значение:

Функция adi_dev_Write() записывает данные в устройство, или ставит в очередь буферы передачи для устройства.

u32 adi_dev_Write (ADI_DEV_DEVICE_HANDLE DeviceHandle,
                   ADI_DEV_BUFFER_TYPE BufferType,
                   ADI_DEV_BUFFER *pBuffer);

Аргумент:

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

Функция adi_pdd_Close() закрывает устройство. Поток данных останавливается, если он не был уже остановлен, и устройство переводится обратно в состояние ожидания (idle state).

u32 adi_pdd_Close (ADI_PDD_DEVICE_HANDLE PDDHandle);

Аргумент:

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

Функция adi_pdd_Control() устанавливает или считывает параметр конфигурации устройства.

u32 adi_pdd_Control (ADI_DEV_PDD_HANDLE PDDHandle,
                     u32 Command,
                     void *pArg); 

Аргументы:

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

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

u32 adi_ppd_Open (ADI_DEV_MANAGER_HANDLE ManagerHandle,
                  u32 DeviceNumber,
                  ADI_DEV_DEVICE_HANDLE DeviceHandle,
                  ADI_DEV_PDD_HANDLE *pPDDHandle,
                  ADI_DEV_DIRECTION Direction,
                  void *pEnterCriticalParam,
                  ADI_DMA_MANAGER_HANDLE DMAHandle,
                  ADI_DCB_HANDLE DCBHandle,
                  ADI_DCB_CALLBACK_FN DMCallback); 

Аргументы:

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

Функция adi_pdd_Read() предоставляет буферы для устройства, чтобы получить входящие данные. Эта функция никогда не вызывается для тех устройств, у которых есть поддержка периферийного DMA.

u32 adi_pdd_Read (ADI_DEV_PDD_HANDLE PDDHandle,
                  ADI_DEV_BUFFER_TYPE BufferType,
                  ADI_DEV_BUFFER *pBuffer); 

Аргументы:

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

Функция adi_pdd_Write() предоставляет буферы для устройства, чтобы передать наружу исходящие данные. Эта функция никогда не вызывается для тех устройств, у которых есть поддержка периферийного DMA.

u32 adi_pdd_Write (ADI_DEV_PDD_HANDLE PDDHandle,
                   ADI_DEV_BUFFER_TYPE BufferType,
                   ADI_DEV_BUFFER *pBuffer); 

Аргументы:

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