Рабочая семантика МБ

Асинхронные транзакции

Модель драйвера MB предполагает неблокировку операционной семантики между драйверами службы MB и минипорта с помощью асинхронного механизма уведомления, предоставленного в NDIS 6.x. Этот механизм позволяет службе MB продолжать отправлять запросы OID в драйвер мини-порта для обработки, не дожидаясь завершения текущей операции.

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

Асинхронные запросы наборов и запросов

Многие из наборов изапросов OID-запросов, используемых службой MB, обрабатываются асинхронно. Дополнительные сведения о запросах OID и заданиях см. в разделе NDIS_OID_REQUEST. Таблица "Идентификаторы OID для WWAN" в разделе Модель данных MB определяет, какие идентификаторы OID обрабатываются асинхронно.

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

Трехстороннее подтверждение одинаково как для запросов, так и для запросов set .

За исключением OID_WWAN_DRIVER_CAPS, все остальные запросы OID, относящиеся к МБ, используют асинхронный механизм транзакций для обмена информацией между драйверами мини-порта и службой MB Со следующими дополнительными примечаниями:

• Драйверы мини-портов должны немедленно завершать запрос OID при любом условии ошибки, например при недопустимом запросе OID.

• Драйверы мини-портов должны возвращать все условия ошибок, относящиеся к WWAN, с правильным кодом ошибки (например, WWAN_STATUS_XXX), указанным в элементе uStatus структуры уведомлений о событиях. Драйверы мини-портов также должны соответствующим образом заполнить элементы, следующие за элементом uStatus , при необходимости. Например, драйверы мини-порта должны заполнить элемент ContextState.uNwError структуры NDIS_WWAN_CONTEXT_STATE , если он доступен. Однако в случае сбоя при обработке идентификаторов OID, связанных с ПИН-кодами, драйверы мини-портов могут не обязательно иметь сведения о текущем состоянии ПИН-кода, которые нужно указать в элементе PinInfo.PinStateNDIS_WWAN_PIN_INFO.

• Драйверы miniport должны возвращать NDIS_STATUS_INDICATION_REQUIRED в качестве предварительного ответа для всех асинхронных запросов OID.

• Драйверы мини-портов должны отличать изменения состояния устройства, вызванные запросом OID, от других причин. Драйверы минипорта должны отправлять транзакционные уведомления об изменениях состояния в результате запросов OID, а также отправлять незапрошенные уведомления об изменениях состояния по другим причинам.

• Драйверы мини-портов отвечают за управление памятью в режиме ядра, хотя служба MB изначально выделяет память для запросов. После того как служба MB получит ответ от драйвера мини-порта, служба может освободить память в пользовательском режиме, выделенную для запроса OID.

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

Асинхронный ответ

В спецификации NDIS 6.0 (выпущенной вместе с Windows Vista) появился новый код состояния, NDIS_STATUS_INDICATION_REQUIRED, для драйверов мини-порта, чтобы передать асинхронный характер транзакции в службу MB в предварительном ответе драйвера минипорта на запрос OID.

Как упоминалось в обзоре интерфейса MB, служба MB не имеет прямого доступа к памяти в режиме ядра, выделенной драйвером мини-порта MB. Предполагается, что результат выполнения, хранящийся в памяти режима ядра, копируется и предоставляется службе MB с помощью некоторых посредников, таких как WMI или драйвер фильтра NDIS. Таким образом, драйверы мини-портов могут освободить выделенную память в режиме ядра после того, как вызов функции NdisMIndicateStatusEx возвращается в указании транзакции.

Процедуры подтверждения, которым должны следовать драйверы мини-порта и служба MB Service, описаны в следующей процедуре.

Процедура драйвера мини-порта MB

Получив запрос OID, драйверы мини-порта должны выполнить следующие действия:

1. Выделение памяти в режиме ядра для копирования содержимого NDIS_OID_REQUEST структуры данных, связанной с запросом OID.

2. Из параметров запроса убедитесь, что элементы RequestId и RequestHandle структуры запроса OID также скопированы. Эти элементы будут использоваться позже при указании транзакций.

3. Верните предварительный NDIS_STATUS_INDICATION_REQUIRED ответ о состоянии, чтобы сообщить службе MB, что драйвер мини-порта выполнит запрос асинхронно.

4. По завершении операции сохраните результат в локальной памяти или памяти, выделенной драйвером, соответствующим образом.

5. Вызовите функцию NdisMIndicateStatusEx , чтобы уведомить службу MB о завершении невыполненных операций. Драйверы мини-портов должны заполнять элементы структуры NDIS_STATUS_INDICATION следующим образом:

   1. Задайте для элемента StatusCode тип уведомления о состоянии. Например, NDIS_STATUS_WWAN_XXX.
   2. Задайте элемент DestinationHandle для элемента RequestHandle , который был получен в структуре данных NDIS_OID_REQUEST, когда драйвер мини-порта получил соответствующий запрос OID.
   3. Задайте элемент RequestId в соответствии с элементом RequestId структуры состояния NDIS_OID_REQUEST, когда драйвер мини-порта получил соответствующий запрос OID.
   4. Задайте элементы StatusBuffer и StatusBufferSize , чтобы они указывали на память, выделенную драйвером мини-порта, и размер буфера памяти соответственно. Этот буфер памяти содержит результат завершенной операции.
   5. Если операция успешно завершена, задайте для элемента uStatus значение WWAN_STATUS_SUCCESS. В противном случае задайте члену uStatus соответствующее значение WWAN_STATUS_XXX, чтобы указать тип сбоя.

6. Когда вызов функции возвращается, драйвер мини-порта должен освободить память, выделенную для запроса OID.

Процедура службы MB

Служба MB обрабатывает асинхронные транзакции с помощью следующей процедуры:

1. Выделение буферной памяти для запроса на основе структуры данных OID. Заполните члены структуры данных соответствующими значениями.

2. Вызовите функцию NdisOidRequest с элементом InformationBuffer , указывающим на структуру данных OID для запроса OID, и дождитесь ответа драйвера мини-порта.

3. После получения NDIS_STATUS_INDICATION_REQUIRED предварительного ответа от драйвера мини-порта служба MB сохраняет RequestId, освобождает выделенную память и помечает транзакцию как открытую. На этом этапе служба MB может бесплатно обрабатывать последующие запросы и уведомления OID.

4. При получении уведомления с NDIS_STATUS_WWAN_XXX в качестве значения StatusCode проверка, совпадает ли значение RequestId с любой транзакцией, помеченной как открытая. При наличии совпадения служба закрывает транзакцию. Если совпадение не найдено, обработайте уведомление как уведомление о незапрашиваемом событии.

5. Обработайте данные, возвращенные в элементе StatusBuffer , и внесите соответствующие изменения в состояние службы MB.

Показания

Существует два типа признаков, характерных для WWAN, которые могут создавать драйверы мини-портов:

• Уведомления о событиях, которые возникают в результате изменения состояния объекта на устройстве в МБ.

• Уведомления о транзакциях, которые сигналит о завершении асинхронной операции.

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

Уведомление о событии

Уведомление о событии является нежелательным в том смысле, что драйвер мини-порта заблаговременно отправляет указание в службу MB как событие изменения состояния. Изменение состояния вызвано действием из какой-либо сущности, отличной от службы MB. Служба MB предполагает, что драйверы мини-порта могут обнаружить причину изменения.

Для уведомлений о событиях, относящихся к WWAN, драйверы мини-портов должны задать элемент RequestId структуры NDIS_STATUS_INDICATION равным нулю. Элемент StatusCode указывает, какой объект на устройстве MB был изменен. Драйвер мини-порта может задать этому объекту любое из следующих значений:

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

NDIS_STATUS_WWAN_HOME_PROVIDER

NDIS_STATUS_WWAN_PREFERRED_PROVIDERS

NDIS_STATUS_WWAN_VISIBLE_PROVIDERS

NDIS_STATUS_WWAN_REGISTER_STATE

NDIS_STATUS_WWAN_PACKET_SERVICE

NDIS_STATUS_WWAN_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

Служба MB также может обрабатывать другие уведомления о событиях из NDIS. Эти уведомления о событиях, отличные от МБ, не обязательно регулируются требованием, чтобы их значения RequestId были равны нулю.

Уведомления о транзакциях

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

Служба MB ожидает уведомления о транзакциях, чтобы закрыть открытые транзакции. Это окончательный обмен трехсторонним подтверждением между службой МБ и драйвером мини-порта в асинхронной транзакции. Значение элемента RequestId NDIS_STATUS_INDICATION в любом уведомлении транзакции должно быть ненулевым, которое копируется из соответствующего запроса в той же транзакции.

Для правильной работы асинхронного механизма необходимо правильно задать элемент RequestId структуры NDIS_STATUS_INDICATION. Служба MB гарантирует, что значение RequestId является уникальным и ненулевым среди всех невыполненных запросов. Драйверы минипорта должны возвращать то же значение RequestId в соответствующем указании , чтобы служба МБ сопоставила это указание с открытой транзакцией.

Структура индикации состояния

Как асинхронный ответ для заданного запроса OID, так и структуры уведомлений о незапрошенных событиях совместно используют следующие элементы структуры, на которые указывает элемент StatusBuffer параметра StatusIndication для NdisMIndicateStatusEx:

typedef struct _NDIS_WWAN_XXX {
  NDIS_OBJECT_HEADER Header;
  WWAN_STATUS uStatus;
  ULONG uNwError;//Optional. Only used for network operations.
  WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;

Значение нуля в элементе RequestId структуры NDIS_STATUS_INDICATION означает, что это уведомление о незапрошенном событии, которое может произойти в любое время.

Если элемент uStatus в возвращаемом указании любого набора или запроса OID не равен WWAN_STATUS_SUCCESS члены связанной структуры NDIS_WWAN_XXX не должны быть допустимыми.

В случае уведомлений о нежелательных событиях, основанных на сетевых событиях, драйверы минипорта должны заполнить член uNwError соответствующим образом, если это применимо.

В следующей таблице показаны значения ошибок кода регистрации, присоединения пакетов и отсоединения пакетов, определенные в спецификации 3GPP TS 24.008 для сетей на основе GSM.

Например, если сеть инициирует событие контекста деактивации, так как роуминг запрещен в области расположения, драйверы минипорта должны установить для члена uNwError значение 13 в соответствии с кодами причин 3GPP TS 24.008 для сетей на основе GSM.

Аналогичную логику следует применять и к сетям на основе CDMA. Однако стандарт для кодов сетевых ошибок на основе CDMA не существует. Устройства на основе CDMA должны использовать коды ошибок для конкретной сети или устройства.

В случае асинхронного ответа драйвера минипорта на запросы OID элемент RequestId структуры NDIS_STATUS_INDICATION является ненулевым числом, которое было передано драйверу минипорта в составе набора или запроса . Драйвер мини-порта должен заполнить элемент uStatus соответствующим образом. Например, WWAN_STATUS_SUCCESS или любое из соответствующих значений ошибок, перечисленных в следующем разделе. В дополнение к этому драйвер мини-порта должен заполнить элемент uNwError , где это необходимо и доступно.

Состояние уведомления о событии

В следующей таблице перечислены коды WWAN_STATUS, которые драйверы мини-порта МБ могут указывать в элементе uStatus NDIS_WWAN_XXX структур уведомлений о событиях.

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

Примечание Эти коды состояния WWAN используются только для асинхронных транзакций в элементе uStatus NDIS_WWAN_XXX структур.

Драйверы miniport используют уведомления о событиях, чтобы сообщить службе MB об изменении состояния объекта на своем устройстве в МБ без предварительного получения запроса OID. Служба MB использует уведомления о событиях только для обновления конечного автомата.

Имейте в виду, что хотя NDIS сериализует все запросы, отправляемые драйверам мини-порта, драйверы мини-портов могут не возвращать ответы в том же порядке. Это связано с тем, что запросы в очереди в драйвере мини-порта могут обрабатываться параллельно. Таким образом, служба MB гарантирует, что если два запроса зависят друг от друга, она не будет отправлять второй запрос, пока драйвер мини-порта не завершит первый запрос.

Уведомление об изменении состояния

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

1. Драйверам мини-портов не нужно отправлять NDIS_STATUS_WWAN_PIN_LIST событие, указывающее на изменение состояния ПИН-кода, так как служба MB запрашивает включение или отключение ПИН-кода.

2. Драйверам минипорта не нужно возвращать обновленный список подготовленных контекстов в транзакционных ответах для операций OID_WWAN_PROVISIONED_CONTEXT задания .

3. Драйверам мини-портов не нужно отвечать обновленным списком предпочтительных поставщиков в транзакционных ответах на операции OID_WWAN_PREFERRED_PROVIDERS задания . Служба MB может определить эти сведения на основе начального списка и состояния успешности операции задания .

4. Драйверам мини-портов не нужно отвечать текущим значением WWAN_SMS_CONFIGURATION для операций установки OID_WWAN_SMS_CONFIGURATION.