Función SerCx2SystemDmaReceiveCreate (sercx.h)

Artículo
10/30/2024

El método SerCx2SystemDmaReceiveCreate crea un objeto SerCx2 system-DMA-receive, que la versión 2 de la extensión de marco serie (SerCx2) usa para realizar transacciones system-DMA-receive.

Sintaxis

NTSTATUS SerCx2SystemDmaReceiveCreate(
  [in]           WDFDEVICE                         Device,
  [in]           PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES            Attributes,
  [out]          SERCX2SYSTEMDMARECEIVE            *SystemDmaReceive
);

Parámetros

[in] Device

Un identificador WDFDEVICE para el objeto de dispositivo de marco que representa el controlador serie. El controlador de controlador serie creó este objeto en su función de devolución de llamada EvtDriverDeviceAdd. Para obtener más información, vea SerCx2InitializeDevice.

[in] SystemDmaReceiveConfig

Puntero a una estructura de SERCX2_SYSTEM_DMA_RECEIVE_CONFIG. Antes de llamar a este método, el autor de la llamada debe llamar a la función SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT o SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION para inicializar la estructura. Esta estructura contiene punteros a un conjunto de rutinas de devolución de llamada de eventos implementadas por el controlador del controlador serie. SerCx2 llama a estas funciones para realizar transacciones system-DMA-receive.

[in, optional] Attributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES que describe los atributos que se van a asignar al nuevo objeto system-DMA-receive. Antes de llamar a este método, el autor de la llamada debe llamar a la función WDF_OBJECT_ATTRIBUTES_INIT para inicializar la estructura. Este parámetro es opcional y se puede especificar como WDF_NO_OBJECT_ATTRIBUTES si el controlador del controlador serie no necesita asignar atributos al objeto . Para obtener más información, vea Comentarios.

[out] SystemDmaReceive

Puntero a una ubicación a la que este método escribe un identificador de SERCX2SYSTEMDMARECEIVE en el objeto system-DMA-receive recién creado. SerCx2 y el controlador del controlador serie usan este identificador en llamadas posteriores para hacer referencia a este objeto.

Valor devuelto

Este método devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes códigos de estado.

Código devuelto	Descripción
STATUS_INVALID_DEVICE_REQUEST	Ya existe un objeto system-DMA-receive de un anterior serCx2SystemDmaReceiveCreate llamada; o ya existe un objeto de recepción personalizada desde una llamada anterior al método SerCx2CustomReceiveCreate; o existe un objeto de transmisión personalizada de una llamada anterior al método SerCx2CustomTransmitCreate; o no se ha llamado a serCx2PioReceiveCreate para crear un objeto pio-receive.
STATUS_INFO_LENGTH_MISMATCH	El valorTamaño de no es igual a tamaño de(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	Un valor de parámetro no es válido.
STATUS_INSUFFICIENT_RESOURCES	Los recursos insuficientes están disponibles para realizar la operación solicitada.

Observaciones

El controlador de controlador de serie llama a este método para crear un objeto system-DMA-receive. SerCx2 usa este objeto para realizar transacciones de recepción del sistema DMA, que son transacciones de E/S que usan el controlador DMA del sistema para leer los datos recibidos por el controlador serie.

Normalmente, un controlador de controlador serie llama a serCx2SystemDmaReceiveCreate desde su EvtDevicePrepareHardware función de devolución de llamada. Esta función recibe una lista de recursos de hardware, que puede incluir canales DMA del sistema.

Un controlador de controlador serie debe llamar correctamente a los métodos SerCx2InitializeDevice y SerCx2PioReceiveCreate métodos antes de llamar a SerCx2SystemDmaReceiveCreate.

Antes de llamar a SerCx2SystemDmaReceiveCreate, el controlador de controlador serie debe llamar a la función SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT o SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION para inicializar la estructura de SERCX2_SYSTEM_DMA_RECEIVE_CONFIG a la que apunta SystemDmaReceiveConfig. Estas funciones establecen los siguientes miembros de la estructura en cero:

MaximumScatterGatherFragments
minimumTransferUnitOverride
DmaAlignment de
minimumTransactionLength
exclusivo

Si es necesario, el controlador de controlador serie puede establecer cualquiera de estos miembros en valores distintos de cero después de que se devuelva la función de inicialización. Sin embargo, para mayor comodidad, SerCx2SystemDmaReceiveCreate usa los siguientes valores predeterminados si estos miembros son cero:

Si MaximumScatterGatherFragments es cero, SerCx2 establece el número máximo de elementos de una lista de dispersión/recopilación en ((ULONG)-1).
Si minimumTransferUnitOverride es cero, SerCx2 establece la unidad de transferencia mínima en su valor predeterminado, que se especifica en la estructura de DMA_ADAPTER para el controlador DMA del sistema. Para obtener más información sobre esta estructura, vea WdfDmaEnablerWdmGetDmaAdapter.
Si DmaAlignment es cero, SerCx2 establece el valor de alineación en la unidad de transferencia mínima. Si minimumTransferUnitOverride es cero, se usa la unidad de transferencia mínima predeterminada.
Si minimumTransactionLength es cero, SerCx2 establece la longitud mínima de la transacción en un byte.
Si exclusivo es cero (FALSE), el modo exclusivo está deshabilitado.

Si el controlador de llamada establece Exclusive en TRUE, los miembros MinimumTransferUnitOverride, DmaAlignmenty MinimumTransactionLength miembros deben ser cero. Para obtener más información, vea SERCX2_SYSTEM_DMA_RECEIVE_CONFIG.

Si la combinación especificada de funciones de devolución de llamada implementadas no es válida, SeCx2SystemDmaReceiveCreate produce un error y devuelve STATUS_INVALID_PARAMETER. El controlador debe implementar o ninguna de las funciones EvtSerCx2SystemDmaReceiveEnableNewDataNotification y EvtSerCx2SystemDmaReceiveCancelNewDataNotification.

Como opción, un controlador de controlador en serie puede usar el parámetro Attributes para crear un contexto para el objeto system-DMA-receive y proporcionar punteros a EvtCleanupCallback y Funciones EvtDestroyCallback que se llaman para preparar el objeto para su eliminación. Para obtener más información, vea WDF_OBJECT_ATTRIBUTES.

Si el parámetro Attributes apunta a una estructura WDF_OBJECT_ATTRIBUTES, el autor de la llamada no debe sobrescribir los valores que escribe la función de inicialización WDF_OBJECT_ATTRIBUTES_INIT en el ParentObject, ExecutionLevely SynchronizationScope miembros de esta estructura.

Para obtener más información sobre cómo crear objetos system-DMA-receive, vea SERCX2SYSTEMDMARECEIVE. Para obtener más información sobre las transacciones de recepción de system-DMA, consulte SerCx2 System-DMA-Receive Transactions.