strmini.h

书中的主要程序文件。在打开例题的.dsw文件后,请读者在 tools菜单下的 Options 的 Directories 标签中选择 Executable files

    // pointer to array of media (optional)
    //

    const KSPIN_MEDIUM*     Mediums;

    //
    // indicates that this stream is a bridge stream (COMMUNICATIONS BRIDGE)
    // this field should be set to FALSE by most minidrivers.
    //

    BOOLEAN         BridgeStream;

    ULONG Reserved[2];    // Reserved for future use

}               HW_STREAM_INFORMATION, *PHW_STREAM_INFORMATION;


typedef struct _HW_STREAM_DESCRIPTOR {

    //
    // header as defined above
    //

    HW_STREAM_HEADER StreamHeader;

    //
    // one or more of the following, as indicated by NumberOfStreams in the
    // header.
    //

    HW_STREAM_INFORMATION StreamInfo;

}               HW_STREAM_DESCRIPTOR, *PHW_STREAM_DESCRIPTOR;

//
// STREAM Time Reference structure
//

typedef struct _STREAM_TIME_REFERENCE {
    STREAM_TIMESTAMP CurrentOnboardClockValue;  // current value of adapter
    // clock
    LARGE_INTEGER   OnboardClockFrequency;  // frequency of adapter clock
    LARGE_INTEGER   CurrentSystemTime;  // KeQueryPeformanceCounter time
    ULONG Reserved[2];    // Reserved for future use
}               STREAM_TIME_REFERENCE, *PSTREAM_TIME_REFERENCE;

//
// data intersection structure.   this structure is point to by the
// Srb->CommandData.IntersectInfo field of the SRB on an 
// SRB_GET_DATA_INTERSECTION operation.  
//

typedef struct _STREAM_DATA_INTERSECT_INFO {

    //
    // stream number to check
    //

    ULONG StreamNumber;

    //
    // pointer to the input data range to verify.
    //

    PKSDATARANGE DataRange;

    //
    // pointer to buffer which receives the format block if successful
    //

    PVOID   DataFormatBuffer;

    //
    // size of the above buffer.  set to sizeof(ULONG) if the caller just
    // wants to know what size is needed.
    //

    ULONG  SizeOfDataFormatBuffer;

}               STREAM_DATA_INTERSECT_INFO, *PSTREAM_DATA_INTERSECT_INFO;

//
// stream property descriptor structure.  this descriptor is referenced in
// Srb->CommandData.PropertyInfo field of the SRB on an SRB_GET or
// SRB_SET_PROPERTY operation.
//

typedef struct _STREAM_PROPERTY_DESCRIPTOR {

    //
    // pointer to the property GUID and ID
    //

    PKSPROPERTY     Property;

    //
    // zero-based ID of the property, which is an index into the array of
    // property sets filled in by the minidriver.
    //

    ULONG           PropertySetID;

    //
    // pointer to the information about the property (or the space to return
    // the information) passed in by the client
    //

    PVOID           PropertyInfo;

    //
    // size of the client's input buffer
    //

    ULONG           PropertyInputSize;

    //
    // size of the client's output buffer
    //

    ULONG           PropertyOutputSize;
}               STREAM_PROPERTY_DESCRIPTOR, *PSTREAM_PROPERTY_DESCRIPTOR;


//
// STREAM I/O Request Block (SRB) structures and functions
//

#define STREAM_REQUEST_BLOCK_SIZE sizeof(STREAM_REQUEST_BLOCK)

//
// SRB command codes
//

typedef enum _SRB_COMMAND {

    //
    // stream specific codes follow
    //

    SRB_READ_DATA,              // read data from hardware
    SRB_WRITE_DATA,             // write data to the hardware
    SRB_GET_STREAM_STATE,       // get the state of the stream
    SRB_SET_STREAM_STATE,       // set the state of the stream
    SRB_SET_STREAM_PROPERTY,    // set a property of the stream
    SRB_GET_STREAM_PROPERTY,    // get a property value for the stream
    SRB_OPEN_MASTER_CLOCK,      // indicates that the master clock is on this
    // stream
    SRB_INDICATE_MASTER_CLOCK,  // supplies the handle to the master clock
    SRB_UNKNOWN_STREAM_COMMAND, // IRP function is unknown to class driver
    SRB_SET_STREAM_RATE,        // set the rate at which the stream should run
    SRB_PROPOSE_DATA_FORMAT,    // propose a new format, DOES NOT CHANGE IT!
    SRB_CLOSE_MASTER_CLOCK,     // indicates that the master clock is closed
    SRB_PROPOSE_STREAM_RATE,    // propose a new rate, DOES NOT CHANGE IT!
    SRB_SET_DATA_FORMAT,        // sets a new data format
    SRB_GET_DATA_FORMAT,        // returns the current data format
    SRB_BEGIN_FLUSH,            // beginning flush state
    SRB_END_FLUSH,              // ending flush state

    //
    // device/instance specific codes follow
    //

    SRB_GET_STREAM_INFO = 0x100,// get the stream information structure
    SRB_OPEN_STREAM,            // open the specified stream
    SRB_CLOSE_STREAM,           // close the specified stream
    SRB_OPEN_DEVICE_INSTANCE,   // open an instance of the device
    SRB_CLOSE_DEVICE_INSTANCE,  // close an instance of the device
    SRB_GET_DEVICE_PROPERTY,    // get a property of the device
    SRB_SET_DEVICE_PROPERTY,    // set a property for the device
    SRB_INITIALIZE_DEVICE,      // initialize the device
    SRB_CHANGE_POWER_STATE,     // change power state 
    SRB_UNINITIALIZE_DEVICE,    // uninitialize the device
    SRB_UNKNOWN_DEVICE_COMMAND, // IRP function is unknown to class driver
    SRB_PAGING_OUT_DRIVER,      // indicates that the driver is to be paged out
                                // only sent if enabled in registry.  board ints
                                // should be disabled & STATUS_SUCCESS returned.
    SRB_GET_DATA_INTERSECTION,  // returns stream data intersection
    SRB_INITIALIZATION_COMPLETE,// indicates init sequence has completed
    SRB_SURPRISE_REMOVAL        // indicates surprise removal of HW has occurred

}               SRB_COMMAND;

//
// definition for scatter/gather
//

typedef struct {
    PHYSICAL_ADDRESS    PhysicalAddress;
    ULONG               Length;
} KSSCATTER_GATHER, *PKSSCATTER_GATHER;


typedef struct _HW_STREAM_REQUEST_BLOCK {
    ULONG           SizeOfThisPacket;   // sizeof STREAM_REQUEST_BLOCK
    // (version check)
    SRB_COMMAND     Command;    // SRB command, see SRB_COMMAND enumeration
    NTSTATUS        Status;     // SRB completion status
    PHW_STREAM_OBJECT StreamObject;
    // minidriver's stream object for this request
    PVOID           HwDeviceExtension;  // minidriver's device ext.
    PVOID           SRBExtension;   // per-request workspace for the
    // minidriver

    //
    // the following union passes in the information needed for the various
    // SRB
    // functions.
    //

    union _CommandData {

        //
        // pointer to the data descriptor for SRB_READ or SRB_WRITE_DATA
        //

        PKSSTREAM_HEADER DataBufferArray;

        //
        // pointer to the stream descriptor for SRB_GET_STREAM_INFO
        //

        PHW_STREAM_DESCRIPTOR StreamBuffer;

        //
        // pointer to the state for SRB_GET or SRB_SET_DEVICE_STATE
        //

        KSSTATE         StreamState;

        //
        // pointer to the time structure for SRB_GET and
        // SRB_SET_ONBOARD_CLOCK
        //

        PSTREAM_TIME_REFERENCE TimeReference;

        //
        // pointer to the property descriptor for SRB_GET and
        // SRB_SET_PROPERTY
        //

        PSTREAM_PROPERTY_DESCRIPTOR PropertyInfo;

        //
        // pointer to the requested format for SRB_OPEN_STREAM and 
        // SRB_PROPOSE_DATA_FORMAT
        //

        PKSDATAFORMAT   OpenFormat;

        //
        // pointer to the PORT_CONFIGURATION_INFORMATION struct for
        // SRB_INITIALIZE_DEVICE
        //

        struct _PORT_CONFIGURATION_INFORMATION *ConfigInfo;

        //
        // handle to the master clock.
        //

        HANDLE          MasterClockHandle;

        //
        // power state
        //

        DEVICE_POWER_STATE DeviceState;

        //
        // data intersection info
        //

        PSTREAM_DATA_INTERSECT_INFO IntersectInfo;

    }               CommandData;// union for command data

    //
    // field for indicating the number of KSSTREM_HEADER elements pointed to
    // by the DataBufferArray field above.
    //

    ULONG NumberOfBuffers;

    //
    // the following fields are used to time the request.   The class driver
    // will set both of these fields to a nonzero value when the request
    // is received by the minidriver, and then begin counting down the
    // TimeoutCounter field until it reaches zero.   When it reaches zero,
    // the minidriver's timeout handler will be called.   If the minidriver
    // queues a request for a long time, it should set the TimeoutCounter to
    // zero to turn off the timer, and once the request is dequeued should
    // set the TimeoutCounter field to the value in TimeoutOriginal.
    //

    ULONG           TimeoutCounter; // timer countdown value in seconds
    ULONG           TimeoutOriginal;    // original timeout value in seconds
    struct _HW_STREAM_REQUEST_BLOCK *NextSRB;
    // link field available to minidriver for queuing
    PIRP            Irp;        // pointer to original IRP, usually not
    // needed.
    ULONG           Flags;      // flags defined below.
    PVOID           HwInstanceExtension;
    // pointer to the instance extension
    //
    // the following union is used to indicate to the minidriver the amount
    // of data to transfer, and used by the minidriver to report the amount
    // of data it was actually able to transfer.
    //

    union {
        ULONG           NumberOfBytesToTransfer;
        ULONG           ActualBytesTransferred;
    };

    PKSSCATTER_GATHER ScatterGatherBuffer; // buffer pointing to array
                                           // of s/g elements
    ULONG           NumberOfPhysicalPages; // # of physical pages in request

    ULONG           NumberOfScatterGatherElements;
                                         // # of physical elements pointed  
                                         // to by ScatterGatherBuffer  

    ULONG Reserved[1];    // Reserved for future use

}               HW_STREAM_REQUEST_BLOCK, *PHW_STREAM_REQUEST_BLOCK;

//
// flags definitions for CRB
//

//
// this flag indicates that the request is either an SRB_READ_DATA or
// SRB_WRITE_DATA request, as opposed to a non-data request.
//

#define SRB_HW_FLAGS_DATA_TRANSFER  0x00000001

//
// this flag indicates that the request is for a stream, as opposed to being
// for the device.
//

#define SRB_HW_FLAGS_STREAM_REQUEST 0x00000002

//
// Structure defining the buffer types for StreamClassGetPhysicalAddress.
//

typedef enum {
    PerRequestExtension,        // indicates the phys address of the SRB
    // extension
    DmaBuffer,                  // indicates the phys address of the DMA
    // buffer
    SRBDataBuffer               // indicates the phys address of a data
    // buffer
}               STREAM_BUFFER_TYPE;

//
// Structure for I/O and Memory address ranges
//

typedef struct _ACCESS_RANGE {
    STREAM_PHYSICAL_ADDRESS RangeStart; // start of the range
    ULONG           RangeLength;// length of the range
    BOOLEAN         RangeInMemory;  // FALSE if a port address
    ULONG           Reserved;   //
}               ACCESS_RANGE, *PACCESS_RANGE;


//
// Configuration information structure.  Contains the information necessary
// to initialize the adapter.
//

typedef struct _PORT_CONFIGURATION_INFORMATION {
    ULONG           SizeOfThisPacket;   // Size of this structure, used as
    // version check
    PVOID           HwDeviceExtension;  // minidriver's device extension

    //
    // the below field supplies a pointer to the device's functional
    // device object, which is created by stream class.  
    // Most minidrivers will not need to use this.  
    //

    PDEVICE_OBJECT  ClassDeviceObject;  // class driver's FDO

    //
    // the below field supplies a pointer to the device's "attached" physical
    // device object, which is returned from IoAttachDeviceToDeviceStack.  
    // Most minidrivers will not need to use this.  
    // This PDO must be used for calls to IoCallDriver.  See the note below 
    // for the RealPhysicalDeviceObject, and also see WDM documentation.
    //

    PDEVICE_OBJECT  PhysicalDeviceObject;   // attached physical device object

    ULONG           SystemIoBusNumber;  // IO bus number (0 for machines that
    // have
    // only 1 IO bus)

    INTERFACE_TYPE  AdapterInterfaceType;   // Adapter interface type
    // supported by HBA:
    // Internal
    // Isa
    // Eisa
    // MicroChannel
    // TurboChannel
    // PCIBus