NOTIFICATION_INFO structure

The bus driver passes NOTIFICATION_INFO to pass information to the driver-provided notification routine for a driver-allocated address range in the computer's IEEE 1394 address space. The bus driver calls the notification routine when it receives an asynchronous I/O request packet for that address.

Syntax


typedef struct _NOTIFICATION_INFO {
  PMDL            Mdl;
  ULONG           ulOffset;
  ULONG           nLength;
  ULONG           fulNotificationOptions;
  PVOID           Context;
  PADDRESS_FIFO   Fifo;
  PVOID           RequestPacket;
  PMDL            ResponseMdl;
  PVOID           *ResponsePacket;
  PULONG          ResponseLength;
  PKEVENT         *ResponseEvent;
#if (NTDDI_VERSION >= NTDDI_WINXP)
  RCODE           ResponseCode;
#endif 
} NOTIFICATION_INFO, *PNOTIFICATION_INFO;

Members

Mdl

If non-NULL, Mdl specifies the memory descriptor list (MDL) for the allocated address range.

ulOffset

Specifies the byte offset with the MDL that corresponds to the address that received a request packet. Only used when Mdl is non-NULL.

nLength

Specifies the number of bytes affected by the request packet. Only used when Mdl is non-NULL.

fulNotificationOptions

Specifies which type of event triggered the bus driver to call the notification routine. The possible events the bus driver can return are the following:

  • NOTIFY_FLAGS_AFTER_READ
  • NOTIFY_FLAGS_AFTER_WRITE
  • NOTIFY_FLAGS_AFTER_LOCK

This member is only used when Mdl is non-NULL.

Context

Pointer to specific context data for this allocated address range. The driver supplies this data through the u.AllocateAddressRange.Context member of the IRB for the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

Fifo

Pointer to the ADDRESS_FIFO structure that contains the FIFO element just completed. Only used if the driver submitted an ADDRESS_FIFO list in the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

RequestPacket

If non-NULL, RequestPacket points to the original request packet. The bus driver only supplies this if the device driver did not supply an MDL or an ADDRESS_FIFO list in the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

ResponseMdl

If non-NULL, ResponseMdl points to an uninitialized MDL. The driver must initialize this MDL for a nonpageable buffer, and fill the buffer with the response packet. The bus driver only supplies this if the device driver did not supply an MDL or an ADDRESS_FIFO list in the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

ResponsePacket

If non-NULL, ResponsePacket points to a memory location that the driver fills in with a pointer to the data (quadlet or block) to be returned in the response packet. The bus driver only supplies this if the device driver did not supply an MDL or an ADDRESS_FIFO list in the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

ResponseLength

If non-NULL, ResponseLength points to a memory location that the driver fills in with the length of its response packet. The bus driver only supplies this if the device driver did not supply an MDL or an ADDRESS_FIFO list in the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

ResponseEvent

If non-NULL, ResponseEvent points to a memory location that the driver fills in with the kernel event the bus driver should use to signal that it has completed sending the response packet. The bus driver only supplies this if the device driver did not supply an MDL or an ADDRESS_FIFO list in the original REQUEST_ALLOCATE_ADDRESS_RANGE request.

ResponseCode

Specifies the result of the driver's response to the request. The driver must report the response result by setting ResponseCode to a valid RCODE value.

The following table describes the RCODE values:

RCODE valueDescription
RCODE_RESPONSE_COMPLETEThe driver has successfully completed the request.
RCODE_RESERVED1Reserved. The driver must not use this value to report the response result.
RCODE_RESERVED2Reserved. The driver must not use this value to report the response result.
RCODE_RESERVED3Reserved. The driver must not use this value to report the response result.
RCODE_CONFLICT_ERRORA resource conflict was detected. The request may be retried by the bus driver.
RCODE_DATA_ERRORA hardware error has occurred and data is unavailable.
RCODE_TYPE_ERRORA member in the request packet header was set to an unsupported or incorrect value, or an invalid transaction was attempted (such as a write request to a read-only address).
RCODE_ADDRESS_ERRORThe destination offset member in the request packet was set to an invalid or inaccessible address.
RCODE_TIMED_OUTThe 1394 device did not respond to the request.

 

Important  Under certain conditions in Windows 7, a memory leak could occur if the driver's notification routine modifies the ResponseCode member. For more information, see Memory Leak in IEEE 1394 Bus Driver Performing Asynchronous Notification Callbacks.

Remarks

When a driver allocates an address range on the computer's IEEE 1394 address space, it may require that the bus driver notify it for some or all request packets sent to the allocated addresses. As part of the original allocate request, the driver may either require that the bus driver forward each packet for handling, or it may require that the bus driver handle the packet and notify the device driver when it has finished. For more information, see REQUEST_ALLOCATE_ADDRESS_RANGE.

If the device driver provides no backing store, the bus driver forwards each packet to the device driver for handling. The bus driver passes NULL for Mdl, and passes the packet in RequestPacket. The bus driver also passes pointers to memory locations that the device driver must fill in with the buffer for the response packet (in ResponsePacket), the buffer length (in ResponseLength), and an MDL for the buffer (in ResponseMdl). The bus driver also supplies a memory location that the driver can use to pass a kernel event object in ResponseEvent. If the device driver provides an event object, the bus driver uses it to signal the driver when it has finished sending the response packet.

If the driver provides the backing store in the original allocate address range request, the bus driver uses the driver's notification routine to signal that it has completed reading or writing data from the backing store. It passes the MDL of the backing store in the Mdl member, and the starting location and size within the associated buffer in ulOffset and nLength. The bus driver also passes the type of event that led to notification in fulNotificationOptions.

If the device driver is using a linked list of ADDRESS_FIFO's as the backing store, the bus driver returns the list element it popped off in Fifo.

Requirements

Header

1394.h (include 1394.h)

See also

REQUEST_ALLOCATE_ADDRESS_RANGE

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft