Чтобы открыть поток памяти (memory stream), клиент вызывает функцию adi_dma_MemoryOpen. В эту функцию клиент передает следующие параметры:

• Указатель handle на Менеджер DMA, который управляет потоком.

• Идентификатор потока (stream ID, значение типа ADI_DMA_STREAM_ID), который идентифицирует поток MDMA при его использовании.

• Указатель handle клиента, который передается обратно в функцию обратного вызова (callback), которую предоставил клиент. Это значение предоставляется клиентом, и предположительно может что-то значить для клиента, когда передается обратно в его client-функцию. С помощью этого значения клиент может связать значение с потоком, который привел к вызову callback-функции.

• Указатель на место, в которое Менеджер DMA сохраняет handle потока памяти (stream handle). Этот stream handle является значением, определяемым Менеджером DMA, и оно уникально идентифицирует поток для Менеджера DMA.

• Хендл на службу отложенных функций обратного вызова (deferred callback service [4]) или значение NULL. Если предоставлено значение NULL, то Менеджер DMA делает так называемые live callback-и для приложения. Live callback работает в контексте аппаратного обработчика прерывания. Если предоставлен handle службы отложенных функций обратного вызова, то все callback-и для потока будут использовать эту службу, чтобы выполнить отложенную обработку вызова callback-функции, после того как завершится ISR аппаратного прерывания (в этом случае callback-функция выполняется в низкоприоритетном контексте deferred callback service).

Одномерные (линейные передачи) перемещения данных по памяти обрабатываются вызовом функции adi_dma_MemoryCopy(). Когда вызывается эта функция, клиент предоставляет следующие параметры:

• Хендл потока (stream handle). Это значение предоставлено клиенту во время вызова функции открытия потока adi_dma_MemoryOpen().

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

• Начальный адрес источника, откуда будут копироваться данные.

• Ширина (в байтах) каждого отдельного копируемого элемента. Менеджер DMA использует это значение для планирования 8-, 16- или 32-битных передач.

• Количество копируемых элементов.

• Адрес callback-функции, которая будет вызвана по завершении передачи. Вовлечение callback-функции зависит от значения handle службы обратных вызовов, которое было предоставлено для потока, когда он было открыт - либо при отложенном (deferred) выполнении, либо при немедленном (live) выполнении прямо в ISR аппаратного прерывания.

Если в функцию adi_dma_MemoryCopy() передано значение NULL для параметра адреса callback-функции, то передача произойдет синхронно, и функция adi_dma_MemoryCopy() не выполнит возврат в клиентский вызывающий код, пока не завершится передача. В этом случае не будут сделаны никакие-вызовы callback-функций.

Двухмерные (матричные) передачи в памяти обрабатываются вызовом функции adi_dma_MemoryCopy2D(). Когда вызывается эта функция, клиент предоставляет следующие параметры:

• Хендл потока (stream handle). Это значение предоставлено клиенту во время вызова функции открытия потока adi_dma_MemoryOpen().

• Указатель на структуру данных (типа ADI_DMA_2D_TRANSFER), которая определяет, как данные сохраняются в памяти места назначения.

• Указатель на структуру данных (типа ADI_DMA_2D_TRANSFER), которая определяет, как данные читаются из памяти источника.

• Ширина (в байтах) каждого отдельного копируемого элемента. Менеджер DMA использует это значение для планирования 8-, 16- или 32-битных передач.

• Адрес callback-функции, которая будет вызвана по завершении передачи. Вовлечение callback-функции зависит от значения handle службы обратных вызовов, которое было предоставлено для потока, когда он было открыт - либо при отложенном (deferred) выполнении, либо при немедленном (live) выполнении прямо в ISR аппаратного прерывания.

Если в функцию adi_dma_MemoryCopy2D() передано значение NULL для параметра адреса callback-функции, то передача произойдет синхронно, и функция adi_dma_MemoryCopy2D() не выполнит возврат в клиентский вызывающий код, пока не завершится передача. В этом случае не будут сделаны никакие-вызовы callback-функций.

Тип данных ADI_DMA_2D_TRANSFER хранит необходимые значения, описывающие двухмерную передачу. Этот тип данных содержит начальный адрес в памяти, значение XCount для количества столбцов, значение YCount для количества строк, и значения XModify и YModify, описывающая шаг итераций для столбцов и строк.

Чтобы открыть канал DMA, клиент вызывает функцию adi_dma_Open(). Клиент передает в эту функцию следующие параметры:

• Хендл (handle) Менеджера DMA, который управляет каналом.

• Идентификатор канала, channel ID (типа ADI_DMA_CHANNEL_ID), который будет идентифицировать открытый канал DMA.

• Хендл клиента (client handle) который будет передаваться в функцию обратного вызова клиента (callback). Это значение предоставляется клиентом и может что-то значить для него, и оно будет передано обратно в callback-функцию клиента, чтобы клиент мог связать это значение с потоком, вызвавшим этот callback.

• Указатель на место в памяти, где Менеджер DMA хранит хендл канала (channel handle). Значение этого channel handle определяется Менеджером DMA, и оно уникально идентифицирует канал для Менеджера DMA.

• Рабочий режим, который определяет для канала, как будут перемещаться данные. Подробнее см. ниже врезку "Одиночные передачи".

• Хендл для службы отложенных вызовов (deferred callback service), или значение NULL. Если предоставлено значение NULL, то Менеджер DMA делает так называемые live callback-и для приложения. Live callback работает в контексте аппаратного обработчика прерывания. Если предоставлен handle службы отложенных функций обратного вызова, то callback-и для канала будут использовать эту службу, чтобы выполнить отложенную обработку вызова callback-функции, после того как завершится ISR аппаратного прерывания (в этом случае callback-функция выполняется в низкоприоритетном контексте deferred callback service).

• Адрес callback-функции, которая будет вызвана для оповещения клиента о событиях. События могут быть как ожидаемыми (такие как запросы на оповещение, когда передача завершилась), так и неожиданными (такие как ошибка DMA). Когда происходит действительный вызов callback-функции (deferred или live), для неё будет предоставлено значение хендла службы обратных вызовов (callback service handle).

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

Менеджер DMA поддерживает следующие рабочие режимы для контроллера DMA процессора Blackfin:

• Одиночные передачи
• Кольцевые передачи
• Модель цепочек больших дескрипторов (Large Descriptor Chaining Model)
• Модель цепочек малых дескрипторов (Small Descriptor Chaining Model)

Режим одиночных передач (single transfer operating mode, ADI_DMA_MODE_SINGLE) выполняет отдельные, однобуферные пересылки данных. Когда используется режим одиночной передачи, клиент вызывает функцию adi_dma_Buffer(), чтобы запланировать передачу. В функцию клиент передает следующие параметры:

• Хендл канала (channel handle). Это значение было предоставлено клиенту вызовом функции adi_dma_Open().

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

• Конфигурационное слово для передачи. Это 16-битное значение, представляющее управляющий регистр конфигурации (DMA configuration control register) для канала DMA. Менеджер DMA подключает заголовочный файл, в котором предоставлены макросы, позволяющие клиенту быстро и просто создать слово конфигурации. Ниже перечислены только те поля слова конфигурации, которые должны быть предоставлены.

• Значение XCount. Для одномерных передач это значение определяет количество элементов для передачи. Для двунаправленных передач это значение определяет внутренний счетчик цикла (количество столбцов).

• Значение XModify. Для одномерных передач это значение определяет инкремент/декремент адреса (шаг) для каждого последующего элемента. Для двухмерных передач это значение задает шаг инкремента/декремента адреса внутреннего цикла для каждого последующего элемента, но не включая последний элемент для каждого внутреннего цикла. После последнего элемента каждого внутреннего цикла вместо этого будет применено значение YModify, исключая самый последний элемент в передаче.

• Значение YCount. Для одномерных передач этот параметр игнорируется. Для двухмерных передач это значение представляет счетчик внешнего цикла (количество строк).

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

Независимо от того, разрешен ли поток данных на канале, функция adi_dma_Buffer() немедленно возвращает управление в вызывающий код. Если поток данных уже разрешен на канале, то Менеджер DMA начинает передачу; иначе передаче не начнется, пока поток данных не будет разрешен вызовом функции adi_dma_Control(). Когда используется режим одиночной передачи, функция adi_dma_Buffer() может быть вызвана в любой момент, пока не идет передача на канале.

Режим кольцевой передачи (circular transfer mode, ADI_DMA_MODE_CIRCULAR) задействует возможность автобуфера контроллера DMA. С использованием режима кольцевой передачи клиент предоставляет Менеджеру DMA один непрерывный буфер, состоящий из n подбуферов, как это показано на рис. 6-1.

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

Когда используется режим кольцевой передачи, клиент вызывает функцию adi_dma_Buffer() со следующими параметрами:

• Хендл канала (channel handle). Это значение было предоставлено клиенту вызовом функции adi_dma_Open().

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

• Конфигурационное слово для передачи. Это 16-битное значение, представляющее управляющий регистр конфигурации (DMA configuration control register) для канала DMA. Менеджер DMA подключает заголовочный файл, в котором предоставлены макросы, позволяющие клиенту быстро и просто создать слово конфигурации. Ниже перечислены поля слова конфигурации, которые должны быть предоставлены клиентом.

• Значение XCount. Установите этот параметр в количество элементов в одном подбуфере.

• Значение XModify. Ширина (в байтах) каждого элемента. Допустимы только значения 1, 3 и 4.

• Значение YCount. Установите этот параметр в количество подбуферов, содержащихся во всем буфере.

• Значение YModify. Этот параметр игнорируется.

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

Рис. 6-1. Использование режима кольцевого буфера для циклической передачи.

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

Используя режим цепочки больших дескрипторов, клиент предоставляет Менеджеру DMA одну или большее количество цепочек дескрипторов, как это показано на рис. 6-2.

Рис. 6-2. Цепочка дескрипторов (Descriptor Chain).

Дескрипторы могут быть предоставлены в любое время, независимо от состояния потока данных. Менеджер DMA обслуживает независимые очереди дескрипторов для каждого канала, удерживая контроллер DMA занятым передачами, пока не будут обработаны все поставленные в очередь дескрипторы.

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

Когда используется модель цепочки больших дескрипторов, цепочки дескрипторов предоставляются для канала с использованием функции adi_dma_Queue(), куда передаются следующие параметры:

• Хендл канала (channel handle). Это значение было предоставлено клиенту вызовом функции adi_dma_Open().

• Хендл типа ADI_DMA_DESCRIPTOR_HANDLE для дескриптора. Из-за того, что одна и та же функция adi_dma_Queue() используется для всех рабочих режимов DMA, основанных на дескрипторах (включая большие дескрипторы, малые дескрипторы и массивы дескрипторов), тип данных ADI_DMA_DESCRIPTOR_HANDLE действует как контейнер, который удобно представляет каждый тип дескриптора.

Для режима цепочки больших дескрипторов, дескрипторы имеют тип ADI_DMA_DESCRIPTOR_LARGE, определяющий модель больших дескрипторов. Когда вызывается функция adi_dma_Queue(), клиент может передать адрес объединения дескриптора (ADI_DMA_DESCRIPTOR_UNION), или альтернативно адрес самого дескриптора (ADI_DMA_DESCRIPTOR_LARGE) для типа данных ADI_DMA_DESCRIPTOR_HANDLE. Этот дескриптор может быть одиночным дескриптором, или первым дескриптором в цепочке дескрипторов.

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

• Указатель на следующий большой дескриптор в цепочке. Если в этом поле NULL, то данный дескриптор единственный, который клиент предоставил для канала.

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

• Конфигурационное слово для передачи. Это 16-битное значение, представляющее управляющий регистр конфигурации (DMA configuration control register) для канала DMA. Менеджер DMA подключает заголовочный файл, в котором предоставлены макросы, позволяющие клиенту быстро и просто создать слово конфигурации. Ниже перечислены поля слова конфигурации, которые должны быть предоставлены клиентом.

• Значение XCount. Для одномерных передач это значение определяет количество передаваемых элементов. Для двухмерных передач это значение задает счетчик внутреннего цикла (количество столбцов).

• Значение XModify. Для одномерных передач это значение определяет инкремент/декремент адреса (шаг) для каждого последующего элемента. Для двухмерных передач это значение задает шаг инкремента/декремента адреса внутреннего цикла для каждого последующего элемента, но не включая последний элемент для каждого внутреннего цикла. После последнего элемента каждого внутреннего цикла вместо этого будет применено значение YModify, исключая самый последний элемент в передаче.

• Значение YCount. Для одномерных передач этот параметр игнорируется. Для двухмерных передач это значение представляет счетчик внешнего цикла (количество строк).

• Значение YModify. Для одномерных передач этот параметр игнорируется. Для двухмерных передач, это значение определяет декремент/инкремент (шаг) адреса внешнего цикла, который будет применен после завершения каждого внутреннего цикла. Это значение будет смещением между последним элементов одной строки и первым элементом следующей строки.

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

Модель цепочек малых дескрипторов (ADI_DMA_MODE_DESCRIPTOR_SMALL) подобна модели цепочек больших дескрипторов (Large Descriptor Chaining Model). Единственное существенное отличие между этими двумя моделями в том, что в малой модели указатель на следующий дескриптор в цепочке дескрипторов составлен только из младших 16 бит адреса, а не из полного 32-битного адреса. Это означает, что все дескрипторы канала, использующие модель малых дескрипторов, должны иметь одинаковыми старшие 16 бит адреса. Другими словами, все дескрипторы малой модели для канала должны быть размещены в одном сегменте памяти размером 64 килобайта.

Это отличие отражено в типе данных ADI_DMA_DESCRIPTOR_SMALL. Чтобы избежать проблем выравнивания данных, последовательность имеет указатель на следующий дескриптор как 16-битную запись, а не 32-битную запись, с начальным адресом данных в дескрипторе, определенном как две 16-битные записи, а не как одна 32-битная запись. С выполнением двух 16-битных доступов к памяти вместо одного 32-битного доступа, можно избежать исключений нарушения выравнивания.

За исключением этих отличий модель цепочек малых дескрипторов функционально идентична модели цепочек больших дескрипторов (Large Descriptor Chaining Model).

Режим массивов дескрипторов (ADI_DMA_MODE_DESCRIPTOR_ARRAY) пока не поддерживается Менеджером DMA.

Когда используются MDMA, если клиент предоставил callback-функцию как параметр для функций adi_dma_MemoryCopy() или adi_dma_MemoryCopy2D(), то callback-функция будет запущена Менеджером DMA после завершения передачи.

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

• Хендл клиента (client handle). Это значение предоставляет клиент при вызове функции adi_dma_MemoryOpen().

• Идентификатор события (Event ID). Это значение ADI_DMA_EVENT_DESCRIPTOR_PROCESSED.

• Начальный адрес места назначения передачи.

Когда используется метод кольцевых передач (ADI_DMA_MODE_CIRCULAR), клиент использует слово конфигурации для указания частоты callback-ов. Когда указано запускать callback клиента на каждом завершении подбуфера, Менеджер DMA запускает callback-функцию клиента по завершении обработки каждого подбуфера. Это полезно в схемах с двойной буферизацией, когда используются 2 подбуфера (ping/pong).

При использовании кольцевой передачи в callback-функцию клиента передаются следующие аргументы:

• Хендл клиента (client handle). Это значение предоставляет клиент при вызове функции adi_dma_MemoryOpen().

• Идентификатор события (Event ID). Это значение ADI_DMA_EVENT_INNER_LOOP_PROCESSED, когда была завершена обработка подбуфера, или ADI_DMA_EVENT_OUTER_LOOP_PROCESSED, когда была завершена обработка всего буфера.

• Начальный адрес буфера данных.

Когда используется любой из методов передачи DMA, основанный на дескрипторах (ADI_DMA_MODE_DESCRIPTOR_LARGE, ADI_DMA_MODE_DESCRIPTOR_SMALL или ADI_DMA_DESCRIPTOR_ARRAY), клиент использует слово конфигурации дескриптора, чтобы определить, должен ли быть сгенерирован вызов callback-функции при обработке дескриптора. Когда указано использовать callback клиента по завершении дескриптора, в callback-функцию клиента передаются следующие аргументы:

• Хендл клиента (client handle). Это значение предоставляет клиент при вызове функции adi_dma_MemoryOpen().

• Идентификатор события (Event ID). Это значение ADI_DMA_EVENT_DESCRIPTOR_PROCESSED.

• Начальный адрес данных.

Подрежим loopback управляется командой ADI_DMA_CMD_SET_LOOPBACK.

Когда разрешен подрежим loopback (после обработки Менеджером DMA последнего дескриптора в цепочке дескрипторов, предоставленной для канала), то автоматически происходит зацикливание на первый дескриптор канала. Это эффективно создает бесконечный цикл дескрипторов, как показано на рис. 6-3. Например, с подрежимом loopback клиент может предоставить дескрипторы в момент инициализации, позволяя Менеджеру DMA обработать дескрипторы, и при этом может никогда не потребоваться необходимость повторного предоставления Менеджеру DMA дополнительных дескрипторов.

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

Рис. 6-3. Цепочка дескрипторов с применением Loopback.

Подрежим streaming управляется командой ADI_DMA_CMD_SET_STREAMING.

При работе не в подрежиме streaming Менеджер DMA ставит контроллер DMA на паузу после обработки дескриптора, который помечен для генерации callback-а, когда он обработан. Менеджер DMA делает это потому, что контроллер DMA процессора Blackfin не предоставляет никакой информации о состоянии, показывающей, что был обработан определенный дескриптор. Если Менеджер DMA не ставил бы на паузу контроллер, то могло произойти так, что перед тем, как Менеджер DMA может распознать и обработать прерывание callback для имеющегося дескриптора, контроллер DMA может завершить обработку уже другого дескриптора. Без постановки на паузу контроллера DMA, пока Менеджер DMA обрабатывает прерывание, Менеджер DMA не может однозначно определить, какое прерывание callback с каким дескриптором связано.

Когда не происходит streaming, Менеджер DMA также ставит контроллер DMA на паузу, когда канал исчерпал свои предоставленные дескрипторы.

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

В подрежиме streaming клиенту требуется гарантировать выполнение следующих условий:

• У канала всегда есть дескрипторы для обработки, и он никогда не вылетает из последовательности дескрипторов.

• Время отклика системы достаточно мало, чтобы Менеджер DMA мог обслужить callback-прерывание для любого дескриптора, помеченного с применением callback до того, как на том же канале потребуется обработка другого callback.

Соблюдение этих условий довольно легко обеспечить в большинстве систем.

Клиент вызывает функцию adi_dma_GetMapping(), чтобы определить идентификатор канала DMA (DMA channel ID), к которому привязано периферийное устройство. Функция adi_dma_GetMapping() принимает следующие параметры:

• Идентификатор периферийного устройства (peripheral ID). Это значение типа ADI_DMA_PMAP, привязку которого нужно определить.

• Указатель на значение ADI_DMA_CHANNEL_ID. Это значение является адресом на место в памяти, куда функция сохранит идентификатор канала (channel ID) к которому привязано указанное периферийное устройство.

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

• Идентификатор периферийного устройства (peripheral ID). Это значение типа ADI_DMA_PMAP указывает периферийное устройство, на которое должна быть установлена привязка канала.

• Идентификатор канала (channel ID). Это значение типа ADI_DMA_CHANNEL_ID, указывающее канал DMA, к которому должна быть сделана привязка периферийного устройства.

Когда клиент открывает первый канал DMA, функция adi_dma_Open() подцепляет к соответствующую цепочку IVG для прерывания ошибки DMA. Обработчик ошибок DMA ничего не другого не делает, кроме как очищает соответствующую ошибку DMA и оповещает клиента о возникновении ошибки вызовом callback-функции.

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

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

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

ADI_DMA_RESULT adi_dma_Buffer(
      ADI_DMA_CHANNEL_HANDLE ChannelHandle,
      void *StartAddress,
      ADI_DMA_CONFIG_REG Config,
      u16 XCount,
      s16 XModify,
      u16 YCount,
      s16 YModify);

Аргументы:

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

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

ADI_DMA_RESULT adi_dma_Close(
      ADI_DMA_CHANNEL_HANDLE ChannelHandle,
      u32 WaitFlag);

Аргументы:

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

Функция adi_dma_Control() управляет/запрашивает операцию на указанном канале DMA. Прототип функции:

ADI_DMA_RESULT adi_dma_Control(
      ADI_DMA_CHANNEL_HANDLE ChannelHandle,
      ADI_DMA_CM Command,
      void *Value);

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

• Передается одна команда.

adi_dma_Control(ChannelHandle, ADI_DMA_CMD_SET_LOOPBACK, (void*)TRUE);

• Передается одна пара команда-значение.

ADI_DMA_CMD_VALUE_PAIR cmd = {ADI_DMA_CMD_SET_WORD_SIZE,
                              (void*)ADI_DMA_WDSIZE_32BIT};
adi_dma_Control(ChannelHandle, cmd.CommandID, cmd.Value);

• Передается (по ссылке) одна структура ADI_DMA_CMD_VALUE_PAIR.

adi_dma_Control(ChannelHandle, ADI_DMA_CMD_VALUE_PAIR, &cmd);

• Передается таблица структур ADI_COMMAND_PAIR. Таблица должна иметь следующую запись-терминатор, чтобы определить конец таблицы команд: { ADI_DMA_CMD_END, 0 }. Например:

ADI_DMA_CMD_VALUE_PAIR table = {
      {ADI_DMA_CMD_SET_LOOPBACK, (void*)LoopbackFlag},
      {ADI_DMA_CMD_SET_DATAFLOW, (void*)TRUE},
      { ADI_DMA_CMD_END, NULL }};
adi_dma_Control(ChannelHandle, ADI_DMA_CMD_TABLE,&table);

Набор команд, который может быть использован с функцией adi_dma_Control, определен а разделе "Команды DMA".

Аргументы:

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

Функция adi_dma_GetMapping() используется для определения привязки идентификатора канала DMA (DMA channel ID) к периферийному устройству, совместимому с DMA.

ADI_DMA_RESULT adi_dma_GetMapping(ADI_DMA_PMAP pmap,
                                  ADI_DMA_CHANNEL_ID *pChannelID);

Аргументы:

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

Функция adi_dma_GetPeripheralInterruptID получает идентификатор прерывания периферийного устройства (peripheral interrupt ID) для указанного идентификатора канала DMA (DMA channel ID).

ADI_DMA_RESULT adi_dma_GetPeripheralInterruptID(
      ADI_DMA_CHANNEL_ID ChannelID,
      ADI_INT_PERIPHERAL_ID *pPeripheralID);

Аргументы:

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

Функция adi_dma_Init() инициализирует Менеджер DMA.

ADI_DMA_RESULT adi_dma_Init(
      void *pMemory,
      const size_t MemorySize,
      u32 *pMaxChannels
      ADI_DMA_MANAGER_HANDLE *pManagerHandle,
      void *pCriticalRegionArg);

Аргументы:

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

Функция adi_dma_MemoryClose() закрывает (останавливает) поток MDMA, освобождая все использовавшиеся для этого ресурсы.

ADI_DMA_RESULT adi_dma_MemoryClose(
      ADI_DMA_STREAM_HANDLE StreamHandle,
      u32 WaitFlag);

Аргументы:

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

Функция adi_dma_MemoryCopy() выполняет одномерное (линейное, 1D) копирование памяти.

ADI_DMA_RESULT adi_dma_MemoryCopy(
      ADI_DMA_STREAM_HANDLE StreamHandle,
      void *pDest,
      void *pSrc,
      u16 ElementWidth,
      u16 ElementCount,
      ADI_DCB_CALLBACK_FN ClientCallback);

Аргументы:

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

Функция adi_dma_MemoryCopy2D() выполняет двухмерное (2D) копирование памяти.

ADI_DMA_RESULT adi_dma_MemoryCopy2D(
      ADI_DMA_STREAM_HANDLE StreamHandle,
      ADI_DMA_2D_TRANSFER *pDest,
      ADI_DMA_2D_TRANSFER *pSrc,
      u32 ElementWidth,
      ADI_DCB_CALLBACK_FN ClientCallback);

Аргументы:

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

Функция adi_dma_MemoryOpen() открывает для использования поток MDMA. После открытия на потоке могут быть запланированы передачи MDMA.

ADI_DMA_RESULT adi_dma_MemoryOpen(
      ADI_DMA_MANAGER_HANDLE ManagerHandle,
      ADI_DMA_STREAM_ID StreamID,
      void *ClientHandle,
      ADI_DMA_STREAM_HANDLE *pStreamHandle,
      void *DCBHandle);

Аргументы:

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

Функция adi_dma_MemoryQueue() ставит в очередь дескрипторы MDMA для потока.

ADI_DMA_RESULT adi_dma_MemoryQueue(
      ADI_DMA_STREAM_HANDLE StreamHandle,
      ADI_DMA_DESCRIPTOR_LARGE *pSourceDescriptor,
      ADI_DMA_DESCRIPTOR_LARGE *pDestinationDescriptor);

Аргументы:

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

Функция adi_dma_MemoryQueueClose() закрывает поток MDMA который был открыт для очередей передач по памяти.

ADI_DMA_RESULT adi_dma_MemoryQueueClose(
      ADI_DMA_STREAM_HANDLE StreamHandle,
      u32 WaitFlag);

Аргументы:

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

Функция adi_dma_MemoryQueueControl() управляет потоком MDMA или конфигурирует его.

ADI_DMA_RESULT adi_dma_MemoryQueueControl(
      ADI_DMA_STREAM_HANDLE StreamHandle,
      ADI_DMA_CMD Command,
      void *Value);

Аргументы:

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

Функция adi_dma_MemoryQueueOpen() открывает поток MDMA для очередей передач по памяти.

ADI_DMA_RESULT adi_dma_MemoryQueueOpen(
      ADI_DMA_MANAGER_HANDLE ManagerHandle,
      ADI_DMA_STREAM_ID StreamID,
      void *ClientHandle
      ADI_DMA_STREAM_HANDLE *pStreamHandle,
      void *DCBHandle,
      ADI_DCB_CALLBACK_FN ClientCallback);

Аргументы:

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

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

ADI_DMA_RESULT adi_dma_Open(
      ADI_DMA_MANAGER_HANDLE ManagerHandle
      ADI_DMA_CHANNEL_ID ChannelID
      void *ClientHandle,
      ADI_DMA_CHANNEL_HANDLE *pChannelHandle,
      ADI_DMA_MODE Mode,
      ADI_DCB_HANDLE DCBHandle,
      ADI_DCB_CALLBACK_FN ClientCallback);

Аргументы:

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

Функция adi_dma_Queue() запрашивает дескриптор или цепочку дескрипторов для указанного канала DMA.

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

ADI_DMA_RESULT adi_dma_Queue(
      ADI_DMA_CHANNEL_HANDLE ChannelHandle,
      ADI_DMA_DESCRIPTOR_HANDLE DescriptorHandle);

Аргументы:

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

Функция adi_dma_SetConfigWord() устанавливает биты в слове конфигурации цепочки дескрипторов.

ADI_DMA_RESULT adi_dma_SetConfigWord(
      ADI_DMA_CHANNEL_HANDLE ChannelHandle,
      ADI_DMA_DESCRIPTOR_HANDLE DescriptorHandle);

Аргументы:

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

Функция adi_dma_SetMapping() привязывает идентификатор канала DMA (DMA channel ID) к указанному периферийному устройству.

ADI_DMA_RESULT adi_dma_SetMapping(
      ADI_DMA_PMAP pmap,
      ADI_DMA_CHANNEL_ID ChannelID);

Аргументы:

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

Функция adi_dma_Terminate() закрывает (останавливает) любую активность DMA и завершает работу Менеджера DMA.

ADI_DMA_RESULT adi_dma_Terminate(ADI_DMA_MANAGER_HANDLE ManagerHandle);

Аргумент:

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

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

Структура данных ADI_DMA_DESCRIPTOR_UNION представляет объединение (union) типов данных малого дескриптора, большого дескриптора и массива дескрипторов. ADI_DMA_DESCRIPTOR_HANDLE это typedef, который описывает указатель на это объединение. ADI_DMA_DESCRIPTOR_HANDLE передается в функцию adi_dma_Queue(), что означает предоставить этой функции a) цепочку малых дескрипторов, b) цепочку больших дескрипторов или c) массив дескрипторов. Путем использования хендла/объединения (handle/union), требуется одна функция single adi_dma_Queue(), вместо отдельных функций для каждого типа данных дескриптора.

typedef union ADI_DMA_DESCRIPTOR_UNION
{
   ADI_DMA_DESCRIPTOR_SMALL Small;
   ADI_DMA_DESCRIPTOR_LARGE Large;
   ADI_DMA_DESCRIPTOR_ARRAY Array;
}ADI_DMA_DESCRIPTOR_UNION;

typedef ADI_DMA_DESCRIPTOR_UNION *ADI_DMA_DESCRIPTOR_HANDLE;

Тип данных ADI_DMA_STREAM_HANDLE идентифицирует поток памяти для Менеджера DMA. Когда он передается в функции adi_dma_MemoryXXX, этот handle уникально идентифицирует поток в памяти, с которым работает Менеджер DMA. Менеджер DMA возвратит этот хендл для приложения, когда открывается поток DMA в памяти. Все другие функции потока в памяти требуют передачи этого параметра.

Структура ADI_DMA_2D_TRANSFER определяет характеристики компонента источника или места назначения для двухмерного копирования в памяти.

typedef struct ADI_DMA_2D_TRANSFER
{
   void *StartAddress;
   u16 XCount;
   s16 XModify;
   u16 YCount;
   s16 YModify;
}ADI_DMA_2D_TRANSFER;

Тип ADI_DMA_CONFIG_REG определяет структуру для управляющего слова конфигурации DMA (DMA configuration control word). Дополнительно предоставлены макросы, позволяющие клиенту установить отдельные поля в слове.

Структура ADI_DMA_DESCRIPTOR_ARRAY определяет содержимое элемента массива дескрипторов.

typedef struct ADI_DMA_DESCRIPTOR_ARRAY
{
   void *StartAddress;
   ADI_DMA_CONFIG_REG Config;
   u16 XCount;
   s16 XModify;
   u16 YCount;
   s16 YModify;
   u16 CallbackFlag;
} ADI_DMA_DESCRIPTOR_ARRAY;

! Элемент дескриптора CallbackFlag определен как u16, но он должен получать только значения 0 или 1 (FALSE или TRUE соответственно). Передача значения больше 1 может дать непредсказуемые результаты.

Структура ADI_DMA_DESCRIPTOR_LARGE определяет содержимое большого дескриптора.

typedef struct ADI_DMA_DESCRIPTOR_LARGE
{
   struct ADI_DMA_DESCRIPTOR_LARGE *pNext;
   void *StartAddress;
   ADI_DMA_CONFIG_REG Config;
   u16 XCount;
   s16 XModify;
   u16 YCount;
   s16 YModify;
   u16 CallbackFlag;
}ADI_DMA_DESCRIPTOR_LARGE;

! Элемент дескриптора CallbackFlag определен как u16, но он должен получать только значения 0 или 1 (FALSE или TRUE соответственно). Передача значения больше 1 может дать непредсказуемые результаты.

Структура ADI_DMA_DESCRIPTOR_SMALL определяет содержимое малого дескриптора.

typedef struct ADI_DMA_DESCRIPTOR_SMALL
{
   u16 *pNext;
   u16 StartAddressLow;
   u16 StartAddressHigh;
   ADI_DMA_CONFIG_REG Config;
   u16 XCount;
   s16 XModify;
   u16 YCount;
   s16 YModify;
   u16 CallbackFlag;
}ADI_DMA_DESCRIPTOR_SMALL;

! Элемент дескриптора CallbackFlag определен как u16, но он должен получать только значения 0 или 1 (FALSE или TRUE соответственно). Передача значения больше 1 может дать непредсказуемые результаты.

Структура ADI_DMA_TC_SET используется для установки параметра управления трафиком DMA (DMA traffic control parameter). Поле ParameterID задает, какой тип параметра устанавливается, и это определяется с использованием перечисления ADI_DMA_TC_PARAMETER. ControllerID задает контроллер DMA для установки (там, где имеется несколько контроллеров DMA), нумерация контроллеров начинается с 0 (первый контроллер имеет номер 0). Поле Value задает значение для записи.

typedef struct ADI_DMA_TC_SET
{
   ADI_DMA_TC_PARAMETER ParameterID;
   u16 ControllerID;
   u16 Value;
}ADI_DMA_TC_SET;

Структура ADI_DMA_TC_GET используется для установки или считывания параметра управления трафиком DMA (DMA traffic control parameter). Поле ParameterID задает тип параметра, и это определяется перечислением ADI_DMA_TC_PARAMETER. ControllerID задает контроллер DMA (там, где имеется несколько контроллеров DMA), нумерация контроллеров начинается с 0 (первый контроллер имеет номер 0). Поле Value задает место, куда будет сохранено значение параметра.

typedef struct ADI_DMA_TC_GET
{
   ADI_DMA_TC_PARAMETER ParameterID;
   u16 ControllerID;
   u16 *pValue;
}ADI_DMA_TC_GET;

Перечисление ADI_DMA_CHANNEL_ID содержит значения для каждого канала DMA процессора. Это значение используется в функции adi_dma_Open(), чтобы идентифицировать канал для открытия. Специфичные значения перечисления зависят от используемого целевого процессора.

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

Таблица 6-2. ADI_DMA_EVENT

Перечисление ADI_DMA_MODE определяет, как работает канал DMA для обработки перемещаемых данных. Это перечисление получает значения, показанные в таблице 6-3.

Таблица 6-3. ADI_DMA_MODE.

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

Все публичные функции Менеджера DMA возвращают код из перечисления типа ADI_DMA_RESULT. Возможные значения этого перечисления показаны в таблице 6-4.

Таблица 6-4. Коды ADI_DMA_RESULT.

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

Перечисление ADI_DMA_TC_PARAMETER определяет параметры управления трафиком DMA (DMA traffic control parameter), которые можно использовать в поле ParameterID структуры данных ADI_DMA_TC_SET или ADI_DMA_TC_GET, когда Менеджеру DMA передаются команды ADI_DMA_CMD_GET_TC и ADI_DMA_CMD_SET_TC. Возможные значения показаны в таблице 6-5.

Таблица 6-5. ADI_DMA_TC_PARAMETER