В этом документе описывается функционал драйвера хоста для карт SD (Secure Digital Host Physical Interface Driver, сокращенно SDH PID), который следует стандартной модели драйверов для файловой системы компании Analog Devices (File System Service, ADI FSS). Аппаратура SDH доступна на семействе моделей процессоров серий ADSP-BF54x (и также на процессорах ADSP-BF51x, ADSP-BF60x, где она почему-то называется в документации Removable Storage Interface, RSI). Драйвер SDH поддерживает доступ к данным Secure Digital (SD) карт памяти Version 1.X и Version 2.0 стандартной емкости, повышенной емкости (Higher Capacity Secure Digital, SDHC) и картам памяти Secure Digital IO (карты SDIO, SDIO-Combo). Поддержка карт мультимедиа (Multimedia card, MMC) и функций ввода/вывода карт SDIO и SDIO-combo запланирована для реализации в будущем (здесь приведен перевод документации [1], входящей в комплект поставки среды разработки VisualDSP++ 5.0).

[Файлы драйвера SDH PID]

Подключаемые файлы. Исходный код драйвера использует следующие подключаемые файлы (все эти файлы размещены в подкаталогах системы программирования VisualDSP++ 5.0):

< services/services.h >. Этот файл содержит все определения, прототипы функций и т. п. для всех системных служб (System Services Library, SSL).

< drivers/adi_dev.h >. Этот файл содержит все определения, прототипы функций и т. п. для Менеджера Устройств (Device Manager) и общую информацию по драйверу устройства.

< services/fss/adi_fss.h >. Этот файл содержит все определения, прототипы функций и т. п. для файловой системы ADI (File System Service, FSS).

< drivers/pid/sdh/adi_sdh.h >. Этот файл содержит все определения, прототипы функций и т. п. для драйвера SDH PID.

< drivers/pid/adi_ata.h >. Этот файл содержит определения структуры таблицы диска ATA (ATA Partition Table Structure) и перечисляет идентификаторы поддерживаемых типов разделов диска (Partition type ID).

< string.h >. Этот файл содержит все определения, прототипы функций и т. п. для функций копирования по памяти.

Файлы исходного кода. Исходный код драйвера находится в следующих файлах, размещенных в подкаталоге Blackfin/lib/src/drivers/pid/ каталога установки VisualDSP++ 5.0:

< sdh/adi_sdh.c >. Этот файл содержит исходный код драйвера устройства SDH PID. Весь код написан на языке C, никакие низкоуровневые функции на языке ассемблера не используются.

< sdh/adi_sdh_reg.h >. Этот файл содержит определения всех адресов MMR и макросы доступа к битовым полям регистров аппаратуры SDH.

Документация находится в файле Blackfin\docs\drivers\pid\sdh\adi_sdh.pdf.

Драйвер SDH PID не использует внутри себя никаких дополнительных низкоуровневых драйверов.

[Ресурсы, требуемые для драйвера SDH PID]

Драйверы устройств обычно потребляют некоторое количество системных ресурсов. В этом разделе описаны ресурсы, требуемые для драйвера устройства SDH PID.

Если специально не указано нечто иное в секциях ниже, то SDH PID использует системные службы (System Services, SSL) для доступа и управления требуемой аппаратурой. Информация в этой секции может помочь в определении ресурсов, необходимых для работы драйвера SDH PID, таких как количество обработчиков прерывания или количество каналов DMA и т. п., требуемых от System Services.

Память. Все требования к выделению памяти, кроме структур данных, созданных в стеке, удовлетворяются динамически вызовами функций централизованного управления из FSS, такими как _adi_fss_malloc(), _adi_fss_realloc() и _adi_fss_free(). Эти функции являются обертками над функциями по умолчанию libc (heap_malloc, heap_realloc и heap_free), либо над функциями, специфичными для приложения, которые настроены при конфигурировании службы FSS (подробнее см. описание выделения памяти для FSS в [2], а также описание функций управления динамически выделяемой памяти [3]).

Службой File System Service поддерживается 2 типа куч, это куча для кэша (cache heap), предназначенная для буферов данных наподобие памяти источника и назначения передач DMA, и общая куча (general heap), где содержатся такие данные, как экземпляры объектов библиотек и драйвера SDH PID. Драйвер SDH PID использует general heap, определенную в FSS. Приложение может установить индекс используемой SDH кучи для кэша (cache heap) с использованием соответствующей пары команда-значение, которая может быть отправлена как часть таблицы конфигурации SDH по умолчанию из структуры определения SDH PID.

{ ADI_FSS_CMD_SET_CACHE_HEAP_ID, (void*)CacheHeapIndex }

Здесь CacheHeapIndex это либо индекс в массиве heap_table_t heap_table (см. файл < имя проекта >_heaptab.c), либо индекс, полученный при вызове heap_install (подробнее см. [3]):

static u8 myheap[1024];

#define MY_HEAP_ID 1234
...

int CacheHeapIndex = heap_install((void *)&myheap, sizeof(myheap), MY_HEAP_ID );

Примечание: использование настраиваемых куч может зависеть от окружения, в котором ведется разработка системы. Если выбранное окружение не поддерживает настраиваемых куч, то подпрограммы выделения памяти FSS будут модифицированы, чтобы игнорировать аргумент индекса кучи.

Прерывания. SDH PID требует памяти для трех обработчиков прерывания (ISR) – обработчик прерывания данных DMA SDH, обработчик прерывания ошибки DMA SDH и обработчик прерывания статуса SDH. Каждый из этих ISR требует памяти размером в ADI_INT_SECONDARY_MEMORY.

DMA. Драйвер SDH PID поддерживает только SD-протокол (в режиме полудуплекса) и требует/использует один канал DMA для перемещения данных между процессором и подключенным устройством памяти (карта памяти SD, SDHC и т. п.). Приложение во время процесса инициализации должно выделить память для одного канала SDH DMA размером ADI_DMA_CHANNEL_MEMORY.

Таймеры. Драйвер SDH PID не требует использования службы таймеров.

Семафоры. Драйвер SDH PID требует 2 семафора, один как семафор блокировки (Lock Semaphore) для предоставления исключительного доступа к драйверу SDH PID только для одного процесса за одно обращение, и еще один для сигнализации о завершении внутренних перемещений данных. Для этой цели должна использоваться служба семафоров (Semaphore Service), чтобы создавать и манипулировать всеми семафорами. Каждый семафор требует для себя памяти размером в ADI_SEM_SEMAPHORE_MEMORY.

Часы реального времени, RTC. Драйвер SDH PID не требует службы RTC (Real-Time Clock, часы для отсчета реального времени).

Программируемые флаги. Драйвер SDH PID не требует использования программируемых флагов.

Выводы процессора. SDH требует как минимум 3 выводов для подключения сигналов Command, Clock и Data слота карт SD. Приложение может выбрать работу SDH в режиме широкой шины (wide-bus mode), который расширяет шину данных SDH до 4 бит, тогда это потребует дополнительных 3 выводов процессора. На моделях процессоров Blackfin, где используется мультиплексирование выводов с другими функциями, в зависимости от значений регистра SDH, драйвер SDH PID автоматически переконфигурирует выводы программируемых флагов (programmable flag, PF), чтобы разрешить требуемые выводы для использования в интерфейсе карты SD. Разработчик должен с внимательно распределить выводы процессора таким образом, чтобы SDH не использовал программируемые флаги, которые используют другие устройства ввода/вывода общего назначения, и наоборот.

[Функции, поддерживаемые драйвером SDH PID]

Направление. Драйвер поддерживает типы направлений потоков данных, перечисленные в следующей таблице.

Таблица 2. Поддерживаемые направления данных.

Методы потока данных. Драйвер SDH PID может поддерживать только метод потока цепочек буферов, ADI_DEV_MODE_CHAINED. Когда драйвер используется совместно с FSS, это конфигурируется автоматически внутри службы FSS. Если драйвер работает отдельно, без FSS, то тогда важно при конфигурировании драйвера SDH PID послать ему команду, устанавливающую метод потока:

{ ADI_DEV_CMD_SET_DATAFLOW_METHOD, (void*)ADI_DEV_MODE_CHAINED },

Типы буферов. Драйвер поддерживает только один тип буферов, линейный одномерный буфер ADI_DEV_1D_BUFFER. Этот буфер встраивается внутрь структуры супербуфера службы FSS (подробнее см. документацию FSS [2], где описывается структура супербуфера). Поля с буфере ADI_DEV_1D_BUFFER используются следующим образом:

CallbackParameter. Здесь всегда содержится адрес структуры супербуфера файловой системы (FSS Super Buffer), и это поле не должно оставаться не измененным.
ProcessedFlag. Это поле не используется драйвером SDH PID.
pAdditionalInfo. Это поле не используется драйвером SDH PID.

Идентификаторы команд. В этой секции перечислены команды, которые поддерживаются/требуется драйвером SDH PID. Эти команды поделены на 3 секции. Первая врезка описывает команды, которые поддерживаются напрямую Менеджером Устройств (Device Manager). Вторая врезка описывает общие команды драйвера устройства, которые поддерживает SDH PID. Эти команды поддерживают все драйверы PID. Следующая, третья врезка описывает поддерживаемые команды PID. И последняя, четвертая врезка описывает команды, специфичные именно для драйвера SDH PID.

Команды передаются драйверу через функцию adi_dev_Control(). Функция adi_dev_Control() принимает 3 аргумента:

DeviceHandle. Этот параметр имеет тип ADI_DEV_DEVICE_HANDLE, который уникально идентифицирует драйвер устройства. Этот хендл предоставляется клиенту как результат работы вызова функции adi_dev_Open() драйвера.
CommandID. Этот параметр типа u32, он задает идентификатор команды.
Value. Этот параметр типа void *, и его значение зависит от контекста, т. е. используемой команды.

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

Коды возврата. Все API-функции драйвера устройства возвращают код статуса, показывающий успешность завершения работы функции, или информацию о том, какая произошла ошибка. В этой секции перечислены коды возврата, которые драйвер устройства SDH PID может вернуть клиенту. Возвращенное значение ADI_DEV_RESULT_SUCCESS или ADI_FSS_RESULT_SUCCESS показывают успешное завершение, в то время как любое другое значение показывает ошибку или какой-то другой информативный результат. Значения ADI_DEV_RESULT_SUCCESS и ADI_FSS_RESULT_SUCCESS всегда равны 0. Все другие значения не нулевые.

Коды возврата поделены на 2 категории, перечислены в отдельных врезках. Первая описывает коды возврата, общие для большинства драйверов устройств. Следующая секция описывает специальные коды возврата, которые относятся именно к драйверу SDH PID. Клиент должен подготовить обработку для каждого из кодов возврата, описанных в этих врезках.

Обычно приложение должно проверить код возврата на равенство ADI_DEV_RESULT_SUCCESS, и предпринять соответствующие корректирующие действия, когда не был возвращен код ADI_DEV_RESULT_SUCCESS (обработать ошибку). Например:

if (adi_dev_Xxxx(...) == ADI_DEV_RESULT_SUCCESS)
{
   // Нормальная обработка, ошибки нет:
   ...
}

else
{
   // Обработка ошибки:
   ...
}

[Структуры данных]

ADI_DEV_PDD_ENTRY_POINT. Это так называемая структура точек входа в драйвер (Device Driver Entry Points). Эта структура используется в общем для всех драйверов, удовлетворяющих модели драйверов устройств Analog Devices (ADI Device Driver model), и она содержит адреса стандартного набора функций драйвера устройства. Эта структура определена в модуле исходного кода SDH PID, файл adi_sdh.c, и декларирована как переменная extern в заголовочном файле SDH PID, adi_sdh.h:

extern ADI_DEV_PDD_ENTRY_POINT ADI_SDH_EntryPoint;

ADI_DEV_CMD_VALUE_PAIR. Это структура для определения пары команда-значение, используемая всеми драйверами устройств, удовлетворяющих модели драйверов устройств Analog Devices (ADI Device Driver model). Структура используется в основном для начальной конфигурации драйвера. Драйвер SDH PID должен поддерживать все 3 метода передачи пар команда-значение:

adi_dev_Control( ..., ADI_DEV_CMD_TABLE, (void*)< адрес таблицы пар команда-значение > );
adi_dev_Control( ..., ADI_DEV_CMD_PAIR, (void*)< адрес одной пары команда-значение > );
adi_dev_Control( ..., < команда >, (void*)< значение, связанное с командой > );

ADI_FSS_DEVICE_DEF. Это структура определения устройства, используемая для инструктирования FSS, как открыть и сконфигурировать SDH PID. Содержимое этой структуры в основном это набор параметров, переданных как аргументы в вызов adi_dev_Open(). Структура определена в заголовочном файле службы файловой системы adi_fss.h следующим образом:

typedef struct
{
   u32 DeviceNumber;
   ADI_DEV_PDD_ENTRY_POINT *pEntryPoint;
   ADI_DEV_CMD_VALUE_PAIR *pConfigTable;
   void *pCriticalRegionData;
   ADI_DEV_DIRECTION Direction;
   ADI_DEV_DEVICE_HANDLE DeviceHandle;
   ADI_FSS_VOLUME_IDENT DefaultMountPoint;
} ADI_FSS_DEVICE_DEF;

Поля этой структуры назначаются, как показано в следующей таблице:

Экземпляр по умолчанию этой структуры определена в заголовочном файле SDH PID, adi_sdh.h, защищена от повторного подключения в исходном модуле PID, и будет доступна в модуле приложения только если разработчик определит в нем макрос _ADI_SDH_DEFAULT_DEF_:

#if defined(_ADI_SDH_DEFAULT_DEF_)

static ADI_FSS_DEVICE_DEF ADI_SDH_Def = { ... };
...

#endif

ADI_FSS_VOLUME_DEF. Это структура определения тома, используемая в SDH PID для обмена с FSS. В ней представлено описание тома, который можно использовать. Адрес глобального экземпляра этой структуры будет возвращен как третий аргумент callback-функции, посланный к FSS вместе с событием ADI_FSS_EVENT_VOLUME_DETECTED. Структура определена в заголовочном файле службы файловой системе adi_fss.h следующим образом:

typedef struct
{
   u32 FileSystemType;
   u32 StartAddress;
   u32 VolumeSize;
   u32 SectorSize;
   u32 DeviceNumber;
} ADI_FSS_VOLUME_DEF;

Поля этой структуры назначаются, как показано в следующей таблице:

Служба файловой системы (FSS) рассматривает эту структуру как volatile, и будет делать копию ее содержимого.

typedef struct ADI_FSS_SUPER_BUFFER
{
   ADI_DEV_1D_BUFFER Buffer;
   struct adi_cache_block *pBlock;
   u8 LastInProcessFlag;
   ADI_FSS_LBA_REQUEST LBARequest;
   ADI_SEM_HANDLE SemaphoreHandle;
   ADI_FSS_FILE_DESCRIPTOR *pFileDesc;
   ADI_DCB_CALLBACK_FN FSDCallbackFunction;
   void *FSDCallbackHandle;
   ADI_DCB_CALLBACK_FN PIDCallbackFunction;
   void *PIDCallbackHandle;
} ADI_FSS_SUPER_BUFFER;

ADI_FSS_LBA_REQUEST. Эта структура используется для передачи запроса на количество секторов для чтения с установленного носителя данных (представляет запрос LBA). Адрес экземпляра этой структуры должен быть послан драйверу SDH PID командой ADI_PID_CMD_SEND_LBA_REQUEST. Структура ADI_FSS_LBA_REQUEST определена в заголовочном файле FSS adi_fss.h следующим образом:

typedef struct ADI_FSS_LBA_REQUEST
{
   u32 SectorCount;
   u32 StartSector;
   u32 DeviceNumber;
   u32 ReadFlag;
   ADI_FSS_SUPER_BUFFER *pBuffer;
} ADI_FSS_LBA_REQUEST;

Поля этой структуры назначаются, как показано в следующей таблице:

Использование драйвером структуры ADI_DEV_1D_BUFFER. Драйвером SDH PID может использоваться только структура буфера типа ADI_DEV_1D_BUFFER. Подробное описание определения этой структуры см. в руководстве по системным службам (библиотека System Services, SSL) и драйверу устройства (библиотека Device Driver, DDL).

Использование структуры ADI_FSS_SUPER_BUFFER. Хотя вызовы adi_dev_Read/adi_dev_Write передают адрес структуры ADI_DEV_BUFFER, в пределах фреймворка FSS этот адрес в действительности указывает сразу и на адрес структуры ADI_DEV_BUFFER, и на адрес структуры ADI_FSS_SUPER_BUFFER одновременно. Так происходит потому, что в структуру ADI_FSS_SUPER_BUFFER как первое поле входит структура ADI_DEV_BUFFER, и в структуре супербуфера ADI_FSS_SUPER_BUFFER содержится другая важная информация, требуемая для обмена с другими компонентами фреймворка FSS. Структура супербуфера содержит следующие поля данных:

[Инициализация]

Работа драйвера совместно с FSS. Служба файловой системы File System Service (FSS) автоматически откроет и сконфигурирует драйвер SDH PID вызовом его функций adi_dev_Open() и adi_dev_Control() в соответствии с записью в связанном списке устройств (Devices Linked list, одна из особенностей библиотек ADI).

Чтобы использовать SDH PID совместно с FSS, определите структуру ADI_FSS_DEVICE_DEF (как было описано выше в разделе "Структуры данных"). Обратите внимание, что может использоваться структура по умолчанию, которая будет определена, если будет определен макрос _ADI_SDH_DEFAULT_DEF_ перед подключением заголовочного файла драйвера, в этом случае структура ADI_FSS_DEVICE_DEF получит имя ADI_SDH_Def.

Имейте в виду, что FSS попытается применить букву по умолчанию точки монтирования для этого устройства, и сохранять её при смене носителей данных. Если буква диска по умолчанию не требуется, то это значение может быть установлено в NULL. Если запрошенная буква недоступна на любой стадии функционирования, то FSS назначит следующую доступную букву диска, начиная с буквы "C". В определении по умолчанию ADI_SDH_Def не указана буква диска по умолчанию.

Адрес структуры ADI_FSS_DEVICE_DEF может быть затем зарегистрирован со службой файловой системы FSS с использованием следующей пары команда-значение, переданной в таблице конфигурации на входе в функцию adi_fss_Init(), например:

{ ADI_FSS_CMD_ADD_DRIVER, (void*)&ADI_SDH_Def },

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

{ ADI_PID_CMD_MEDIA_ACTIVATE, (void *)TRUE },

При получении этой команды SDH PID инициализирует регистры SDH и вернет ADI_FSS_RESULT_SUCCESS, если инициализация была успешна, или в противном случае вернет ADI_FSS_RESULT_FAILED. На этой стадии SDH PID автоматически инициализирует поток данных с менеджером устройств (Device Manager) через следующую пару команда-значение:

{ ADI_DEV_CMD_SET_DATAFLOW, (void*)TRUE },

Начиная с этого момента контроллер DMA будет отвечать на запросы от устройства хранения данных (mass storage device), когда это необходимо. Как только SDH PID был активизирован, он будет опрошен на предмет определения наличия носителя данных в слоте карты SD. Перед тем, как сделать это, FSS передает адрес своей callback-функции в драйвер SDH PID следующей парой команда-значение:

{ ADI_PID_CMD_SET_DIRECT_CALLBACK, (void *)< callback-функция FSS > },

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

Чтобы опросить наличие носителя данных FSS посылает следующую пару команда-значение драйверу SDH PID:

{ ADI_PID_CMD_POLL_MEDIA_CHANGE, (void*)NULL },

Если был детектирован допустимый носитель данных, то драйвер SDH PID выдаст событие в callback-функцию FSS, которая была определена, как описано выше. Это немедленный вызов (live callback), и он выполняется со следующими аргументами:

1. Аргумент с адресом DeviceHandle, который был предоставлен как третий аргумент в вызове функции adi_pdd_Open() драйвера SDH PID.
2. Событие ADI_FSS_EVENT_MEDIA_INSERTED.
3. Адрес переменной типа u32. SDH PID устанавливает значение переменной в 0 (индицируя Device Number). При возврате из этого callback указанная переменная будет установлена в подходящий код результата: либо ADI_FSS_RESULT_FAILED, либо ADI_FSS_RESULT_SUCCESS. Последнее значение показывает, что FSS корректно поддерживает детектированный носитель данных.

Если драйвер SDH PID детектирует извлечение носителя, то он выдает событие ADI_FSS_EVENT_MEDIA_REMOVED в callback-функцию DMcallback (это callback Менеджера Устройств). Аргументы вызова следующие:

1. Аргумент с адресом DeviceHandle, который был предоставлен как третий аргумент в вызове функции adi_pdd_Open() драйвера SDH PID.
2. Событие ADI_FSS_EVENT_MEDIA_REMOVED.
3. Адрес переменной типа u32. Драйвер SDH PID устанавливает эту переменную в 0 (индицируя Device Number).

В ответ на установку носителя FSS будет инструктировать PID детектировать рабочие тома/разделы следующей парой команда-значение:

{ ADI_PID_CMD_DETECT_VOLUMES, (void*)< device-number > },

SDH PID не принимает во внимание переданный device-number, и подразумевает здесь 0.

При детектировании допустимого тома PID выдает другое событие ADI_FSS_EVENT_VOLUME_DETECTED в callback-функцию FSS. Аргументы вызова следующие:

1. Аргумент с адресом DeviceHandle, который был предоставлен как третий аргумент в вызове функции adi_pdd_Open() драйвера SDH PID.
2. Событие ADI_FSS_EVENT_VOLUME_DETECTED.
3. Адрес структуры ADI_FSS_VOLUME_DEF, определяющей том. Подробнее об этой структуре см. описание в разделе "Структуры данных".

Самостоятельная работа драйвера. В тех случаях, когда SDH PID используется напрямую (без FSS), например когда требуется создать на носителе разделы, или в случаях, когда встраиваемое приложение это периферийное устройство USB флешки (здесь поддержка файловой системы предоставляется хостом PC), может потребоваться инициализировать PID отдельно от контекста FSS. В этой секции как раз описывается, что для этого нужно.

Структура определения драйвера ADI_SDH_Def предоставляет основные требуемые данных для вызова adi_dev_Open(), чтобы открыть драйвер устройства SDH PID:

Result = adi_dev_Open (< DeviceManagerHandle >,
                       ADI_SDH_Def.pEntryPoint,
                       ADI_SDH_Def.DeviceNumber,
                       &ADI_SDH_Def.DeviceHandle,
                       &ADI_SDH_Def.DeviceHandle,
                       ADI_SDH_Def.Direction,
                       < DMAManagerHandle >,
                       < DCBQueueHandle >,
                       < Callback-function >);

В этом вызове нужно предоставить и другие аргументы. Аргументы < DeviceManagerHandle > и < DMAManagerHandle > обычно бывают получены при инициализации системных служб и Менеджера Устройств [4]. Аргумент < DCBQueueHandle > это хендл к очереди DCB (так называемый Менеджер DCB [5]), callback-вызовы < Callback-function > из драйвера SDH PID должны быть отложены в контекст основного выполнения кода (callback не будет вызываться немедленно в прерывании).

Далее PID нужно сконфигурировать требуемыми настройками (см. ниже "Дополнительные необходимые настройки конфигурации"), или например могут быть изменены настройки по умолчанию (см. ниже "Настройки по умолчанию").

< Callback-function > передается в вызов adi_dev_Open() не из PDD-секции драйвера устройства, и из часть менеджера устройств драйвера устройства. Если используется очередь откладывания вызовов callback-функций и был указан хендл Менеджера DCB < DCBQueueHandle >, то этот вызов будет осуществляться с откладыванием запуска (запуск не в прерывании). Однако процедура детектирования носителя требует немедленного вызова (live-callback) либо в ту же самую callback-функцию (как в случае, когда инициализация осуществлялась во фреймворке FSS), либо в отдельную функцию. В любом случае callback-функция должна быть зарегистрирована с драйвером SDH PID командой ADI_PID_CMD_SET_DIRECT_CALLBACK, как это было показано выше.

Callback-функция (или функции) должна обрабатывать следующие события. Во всех этих событиях первым аргументом в вызове callback-функции будет адрес места размещения хендла устройства драйвера SDH PID (т. е. DeviceHandle), у которого будет то же значение, которое было получено при вызове adi_dev_Open(), по имени это будет &ADH_SDH_Def.DeviceHandle; аргумент Event будет одним из следующих значений, и третий аргумент будет интерпретирован соответствующим образом, как это описано ниже.

ADI_FSS_EVENT_MEDIA_INSERTED. Третий аргумент это адрес ячейки (тип u32*), содержащего номер того устройства (device number), на котором был детектирован носитель. При возврате эта ячейка должна содержать код возврата, показывающий успешность вызова callback.

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

ADI_FSS_EVENT_VOLUME_DETECTED. Третий аргумент это адрес структуры ADI_FSS_VOLUME_DEF, определяющей детектированный том. Определение этой структуры и назначение её полей см. в разделе "Структуры данных". Ответное действие в callback-функции будет зависеть от назначения приложения.

ADI_DEV_EVENT_BUFFER_PROCESSED. Это событие завершения перемещения данных в контексте периферийного DMA. Третий аргумент pArg в этом случае содержит поле CallbackParameter структуры ADI_DEV_1D_BUFFER, переданной в соответствующий вызов adi_dev_Read() или adi_dev_Write(). Это значение должно быть адресом внешней структуры ADI_FSS_SUPER_BUFFER. В этом событии callback-функция должна вызвать SDH PID через его callback-функцию, идентифицированную полем PIDCallbackFunction структуры ADI_FSS_SUPER_BUFFER. Первый аргумент в этом вызове должен быть установлен в поле PIDCallbackHandle структуры ADI_FSS_SUPER_BUFFER, аргументы Event и pArg должны быть просто переданы как есть:

(pSuperBuffer->PIDCallbackFunction) (pSuperBuffer->PIDCallbackHandle,
                                     Event,
                                     pArg);

Дальнейшее действие может потребоваться в зависимости от приложения. Например, поле pNext буфера не равно 0, и значение SectorCount запроса LBA следующего супербуфера не 0, тогда могут потребоваться действия для постановки в очередь следующего запроса LBA с драйвером PID, как это происходит в случае работы драйвера в фреймворке FSS. Подробнее см. раздел "Передача данных".

ADI_PID_EVENT_DEVICE_INTERRUPT. Это событие завершения данных в контексте самого устройства. Оно обрабатывается идентично обработке события ADI_DEV_EVENT_BUFFER_PROCESSED.

Настройки по умолчанию. Таблица 4 описывает конфигурационные настройки по умолчанию для драйвера SDH PID. Если настройки по умолчанию не подходят для имеющейся системы, то приложение должно поменять их командами, либо перечисленными в таблице, либо выдаваемыми по отдельности, через вызов функции adi_dev_Control, чтобы настроить драйвер соответствующим образом. Любые настройки, не перечисленные в таблице 4, не определены.

Таблица 4. Настройки SDH PID по умолчанию.

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

Таблица 5. Дополнительные требуемые настройки.

[Передача данных]

В описываемой процедуре перемещения данных важно отличать друг от друга события устройства (инициированные физическим mass storage device) и события хоста (инициированным программно). В контексте SDH передача данных активна от получения команды запроса для перемещения нужного количества секторов до завершения этого перемещения. Мы будем называть это как блок DRQ. Другими словами, хост считает событием завершения передачи данных момент, когда он примет вызов callback по завершению обработки каждого буфера ADI_DEV_1D_BUFFER.

Когда цепочка таких буферов определит непрерывную порцию данных на носителе, и один запрос LBA был отправлен к драйверу SDH PID, чтобы покрыть цепочку или часть её будет осуществлено несколько событий завершения передач хоста на одно событие завершения передачи устройства, или блок DRQ. Необходимо для драйвера SDH PID заблокировать к себе доступ на время выполнения этого блока DRQ. Это достигается путем поддерживающего семафора блокировки (Lock Semaphore), который является двоичным, с начальным значением 1, и который используется с помощью функций службы семафоров(Semaphore Service).

Освобождение этого семафора будет ожидаться при получении команды ADI_FSS_CMD_ACQUIRE_LOCK_SEMAPHORE:

adi_sem_Pend ( pDevice->LockSemaphoreHandle, ADI_SEM_TIMEOUT_FOREVER);

и освобождаться этот семафор будет при получении команды ADI_FSS_CMD_RELEASE_LOCK_SEMAPHORE:

adi_sem_Post (pDevice->LockSemaphoreHandle);

Процесс выдачи этого запроса (что обычно осуществляется драйвером файловой системы FSD [6]) выполняется следующим образом:

1. Lock Semaphore захватывается в SDH PID выдачей ему пары команда-значение:

{ ADI_FSS_CMD_ACQUIRE_LOCK_SEMAPHORE, NULL },

2. Для драйвера SDH PID предоставляется запрос LBA для первого буфера в цепочке выдачей пары команда-значение, например:

{ ADI_PID_CMD_SEND_LBA_REQUEST, (void*)&pSuperBuffer->LBARequest },

Драйвер SDH PID назначает поля PIDCallbackFunction и PIDCallbackHandle структуры супербуфера ADI_FSS_SUPER_BUFFER, на которую указывает поле pBuffer структуры запроса LBA, и сохраняет копию структуры запроса LBA в данных своего экземпляра.

3. Затем FSD предоставляет цепочку буферов для SDH PID вызовом adi_dev_Read() или adi_dev_Write(), например:

adi_dev_Read{ ..., ADI_DEV_1D, (ADI_DEV_BUFFER*)pSuperBuffer },

4. Поток данных разрешается отправкой следующей командой драйверу SDH PID:

{ ADI_PID_CMD_ENABLE_DATAFLOW, (void*)TRUE},

Lock Semaphore, захваченный на шаге 1, будет освобожден драйвером FSD либо по завершению блока DRQ для одного буфера (если нет цепочки буферов), или по завершению блока DRQ на последнем подбуфере цепочки.

На событии завершения передачи хоста для драйвера SDH PID будет выдано событие ADI_DEV_EVENT_BUFFER_PROCESSED через часть Менеджера Устройств драйвера. По завершении каждого юнита DRQ драйвер SDH PID выдает событие ADI_PID_EVENT_DEVICE_INTERRUPT. Эти вызовы callback-функций должны быть сделаны через Device Manger со следующими аргументами:

1. Аргумент DeviceHandle, предоставленный как третий аргумент, переданный в adi_pdd_Open() драйвера SDH PID.
2. Соответствующий код события.
3. Адрес pBuffer в структуре запроса LBA, который был сохранен на шаге 2 вышеописанного процесса.

В ответ на эти события FSS сделает вызов в драйвер SDH PID, используя поля PIDCallbackFunction и PIDCallbackHandle структуры ADI_FSS_SUPER_BUFFER:

(pSuperBuffer->PIDCallbackFunction) (pSuperBuffer->PIDCallbackHandle,
                                     Event,
                                     pArg);

В этой функции SDH PID проверит статус завершения передачи. Если передача данных для блока DRQ была неудачной, то ProcessedElementCount буфера, соответствующего блоку DRQ, будет установлен в 0. Кроме того, в ответе на событие ADI_PID_EVENT_DEVICE_INTERRUPT драйвер SDH PID освободит свой Lock Semaphore, и опубликует его только если SemaphoreHandle в ADI_FSS_SUPER_BUFFER равен хендлу семафора SDH PID.

[Ссылки]

1. adi_sdh.pdf - SECURE DIGITAL HOST (ADI_SDH) PHYSICAL INTERFACE DRIVER site:analog.com.
2. Служба файловой системы Blackfin.
3. VisualDSP: работа с динамически выделяемой памятью.
4. VDK: менеджер драйверов устройств.
5. VDK: менеджер отложенных функций обратного вызова.
6. Драйвер FSD для FAT от компании Analog Devices.
7. Драйвер интерфейса (PID) для службы файловой системы (FSS).