WDM驱动程序开发之读写设备寄存器：KIoRange类

KIoRange类：

一、Overview
    KIoRange类将一系列特殊的外围总线的地址映射到CPU总线的地址空间。CPU总线上的地址即可能在CPU的I/O空间，也可能在CPU的内存空间，这取决于平台和外围总线的控制方式。考虑到可移植性，所有对I/O周期(I/O cycle)进行译码的设备驱动程序必须用这个类对I/O的位置(location)进行正确的访问(access)。KIoRange是KPeripheralAddress类的派生类。
    一旦映射关系建立起来，驱动程序就用KIoRange类的成员函数去控制设备的I/O寄存器。这个类提供了8位、16位和32位I/O访问控制的函数。这些函数是以内联(in-line)函数方式来使用的，它们调用系统内相应的宏来产生依赖于平台的代码。
    对I/O位置(location)进行访问的另一种备选方案是创建一个KIoRegister的实例。这要通过取得一个KIoRange对象的数组元素来实现。
    为了访问一系列外围总线内存空间的地址，需要用KMemoryRange类。

二、Member Functions

1、KIoRange － Constructor (4 forms)
    构造函数
【函数原型】
FORM 1:

KIoRange( void );

FORM 2: (NTDDK Only)

KIoRange(
   INTERFACE_TYPE IntfType,
   ULONG BusNumber ,
   ULONGLONG BaseBusAddress,
   ULONG Count,
   BOOLEAN MapToSystemVirtual =TRUE
);

FORM 3 (WDM):

KIoRange(
   ULONGLONG CpuPhysicalAddress,
   BOOLEAN InCpuIoSpace,
   ULONG Count,
   BOOLEAN MapToSystemVirtual =TRUE
);

FORM 4 (WDM): (NOTE: This form is deprecated as of DriverStudio version 2.0.)

KIoRange(
   PCM_RESOURCE_LIST pTranslatedResourceList,
   ULONG Ordinal=0,
   BOOLEAN MapToSystemVirtual =TRUE
);

FORM 5 (WDM):

KIoRange(
   PCM_RESOURCE_LIST pTranslatedResourceList,
   PCM_RESOURCE_LIST pRawResourceList,
   ULONG Ordinal=0,
   BOOLEAN MapToSystemVirtual =TRUE
);

【Parameters】
    IntfType                    指定总线类型。列举如下：Internal, Isa, Eisa, MicroChannel, TurboChannel, PCIBus。
    BusNumber            一个表示总线的整数。这种与IntfType联合起来的表示方法当一个系统上有多条相同类型总线的时候是有意义的。这些数以0为对照并由系统分配。
    BaseBusAddress              被构造的对象所映射到的地址区域的首地址。
    Count                       以字节计数的地址区域大小。
    MapToSystemVirtual          一个布尔值，用来指明构造函数是否要创建一个到系统非分页内存地址的映射。
    CpuPhysicalAddress          CPU总线上的物理地址或被翻译好的外围地址。
    InCpuIoSpace                 如果I/O范围在CPU总线的I/O空间则为TRUE，否则为FALSE。细节参看KResourceAssignment::Flags。
    pTranslatedResourceList     指向一个在KPnpDevice::OnStartDevice中可用的已翻译的资源列表的指针。可以通过KIrp::TranslatedResources获得。
    pRawResourceList            指向一个在KPnpDevice::OnStartDevice中可用的原始资源列表的指针。可以通过KIrp::AllocatedResources获得。
    Ordinal                     序号。从pTranslatedResourceList指向的资源列表中指定一个特殊的端口资源。0表示第一个端口，1表示第二个端口，依次类推。
【Comments】
    如果用Form1，需要调用Initialize()才能建立映射。当对象被嵌入KDevice派生类对象时，这是一个常用的方法。
    Form3和Form5只能用在WDM平台。Form3需要一个已经译码到CPU空间的物理地址作为参数。Form5需要一个已经译码的资源列表和一个指定列表中一个特定资源的序号。这种形式需要从资源中提取信息来创建对象。设置Ordinal为0可以指定列表中的第一个资源，1指定第二个，依次类推。除了端口之外的类型列表中的资源没有被计数(not counted)。
    注意：Form5要比Form4(以一个资源列表作为参数)优越，因为Form5考虑到了一个I/O端口也可能被映射到译码资源列表中的一个内存区域。这种情况如果不考虑会在非IA-32系统上会导致一些问题。Form5提取了必要的信息，从传进来的资源列表构建KIoRange对象。
    使用成员函数ConstructorStatus()来获取构造函数的执行状态。
    支撑它的底层系统服务是HalTranslateBusAddress (只对FORM 2有效) 和 MmMapIoSpace。
    这个函数只能在PASSIVE_LEVEL级别上被调用。

2、Initialize － Initialize or reinitialize an instance (3 forms)
初始化或重新初始化KIoRange实例。
【函数原型】
FORM 1: (NTDDK Only)

NTSTATUS Initialize(
   INTERFACE_TYPE IntfType,
   ULONG BusNumber ,
   ULONGLONG BaseBusAddress,
   ULONG Count,
   BOOLEAN MapToSystemVirtual=TRUE
);

FORM 2 (WDM):

NTSTATUS Initialize(
   ULONGLONG CpuPhysicalAddress,
   BOOLEAN InCpuIoSpace,
   ULONG Count,
   BOOLEAN MapToSystemVirtual=TRUE
);

FORM 3 (WDM): (NOTE: This form is deprecated as of DriverStudio version 2.0.)

NTSTATUS Initialize(
   PCM_RESOURCE_LIST pTranslatedResourceList,
   ULONG Ordinal=0,
   BOOLEAN MapToSystemVirtual =TRUE
);

FORM 4 (WDM):

Initialize(
   PCM_RESOURCE_LIST pTranslatedResourceList,
   PCM_RESOURCE_LIST pRawResourceList,
   ULONG Ordinal=0,
   BOOLEAN MapToSystemVirtual =TRUE

);

【Parameters】和【Comments】
    对照构造函数来看，只是当构造函数选择Form1时需要调用Initialize()进行初始化，如果构造函数采用后四种形式，那么Initialize()就没有必要了，因为Initialize的四种形式和构造函数的四种形式是一一对照的。
    当然，在调用Invalidate 函数后可以调用这个函数进行重新初始化。
    支撑它的底层系统服务是HalTranslateBusAddress (只对FORM 1有效) 和 MmMapIoSpace。
    这个函数只能在PASSIVE_LEVEL级别上被调用。

3、~KIoRange － Destructor
    析构函数。
【函数原型】
    ~KIoRange( void );
【Comments】
    支撑它的底层系统服务是MmUnmapIoSpace。
    这个函数只能在PASSIVE_LEVEL级别上被调用。

4、Invalidate － Removes the object from an initialized state
    从已初始化的状态下删除对象。
【函数原型】
    VOID Invalidate( void );
【Comments】
    这个函数是从KPeripheralAddress类继承过来的函数。
    这个函数打破任何底层系统资源之间的联系，取消由构造函数和Initialize()初始化函数所建立的映射关系。从这个状态上对象可以被重新初始化。
    支撑它的底层系统服务是MmUnmapIoSpace。
    析构函数在析构对象的时候调用了这个函数。

5、IsValid － Test if the object is initialized
    测试这个对象是否被正确的初始化了。
【函数原型】
    BOOLEAN IsValid( void );
【Returns】
    如果当前KIoRange对象被正确的初始化了就返回TRUE。
【Comments】
    这个函数是从KPeripheralAddress类继承过来的函数。
    如果对象和底层系统I/O范围(range)取得了联系就认为对象是被正确初始化了。

6、inb － Read a byte or multiple bytes (2 forms)
    从映射空间读一个或多个字节。
【函数原型】
FORM 1:

UCHAR inb( ULONG ByteOffset );

FORM 2:

VOID inb(
   ULONG ByteOffset,
   PUCHAR Buffer,
   ULONG Count
);

【Parameters】
ByteOffset           以0为基地址的字节偏移量，从范围开始(the start of range)到目标单元的开始(the start of target location)之间的偏移。
Buffer            指向获取要读的数据的缓冲区指针。
Count           要读取的字节数。
【Returns】
    Form1返回的是读取的字节内容。
【Comments】
    Form1读单个字节，Form2从相同的I/O寄存器读多个字节。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KIoRegister类实例。

7、outb － Write a byte or multiple bytes (2 forms)
    向映射空间写一个或多个字节。
【函数原型】
FORM 1:

VOID outb(
   ULONG ByteOffset,
   UCHAR Data
);

FORM 2:

VOID outb(
   ULONG ByteOffset,
   PUCHAR Buffer,
   ULONG Count
);

【Parameters】
ByteOffset           以0为基地址的字节偏移量，从范围开始(the start of range)到目标单元的开始(the start of target location)之间的偏移。
Buffer            指向获取要读的数据的缓冲区指针。
Count           要写的字节数。
【Comments】
    Form1写单个字节，Form2向相同的I/O寄存器写多个字节。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KIoRegister类实例。

8、inw － Read a word or multiple words (2 forms)
    从映射空间读一个或多个16位字。
【函数原型】
FORM 1:

USHORT inw( ULONG ByteOffset );

FORM 2:

VOID inw(
   ULONG ByteOffset,
   PUSHORT Buffer,
   ULONG Count
);
【Parameters】
ByteOffset           以0为基地址的字节偏移量，从范围开始(the start of range)到目标单元的开始(the start of target location)之间的偏移。
Buffer     指向获取要读的数据的缓冲区指针。
Count      要读取的字数(以字为单位)。
【Returns】
    Form1返回的是读取的字内容。
【Comments】
    Form1读单个字，Form2从相同的I/O寄存器读多个字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KIoRegister类实例。

9、outw － Write a word or multiple words (2 forms)
    向映射空间写一个或多个16位字。
【函数原型】
FORM 1:

VOID outw(
   ULONG ByteOffset,
   USHORT Data
);

FORM 2:

VOID outw(
   ULONG ByteOffset,
   PUSHORT Buffer,
   ULONG Count
);
【Parameters】
ByteOffset                以0为基地址的字节偏移量，从范围开始(the start of range)到目标单元的开始(the start of target location)之间的偏移。
Buffer     指向获取要读的数据的缓冲区指针。
Count      要写的字数(以16位字为单位)。
【Comments】
    Form1写单个16位字，Form2向相同的I/O寄存器写多个16位字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KIoRegister类实例。

10、ind － Read a dword or multiple dwords (2 forms)
    从映射空间读一个或多个32位双字。
【函数原型】
FORM 1:

ULONG ind( ULONG ByteOffset );

FORM 2:

VOID ind(
   ULONG ByteOffset,
   PULONG Buffer,
   ULONG Count
);
【Parameters】
ByteOffset                以0为基地址的字节偏移量，从范围开始(the start of range)到目标单元的开始(the start of target location)之间的偏移。
Buffer     指向获取要读的数据的缓冲区指针。
Count      要读取的双字数(以双字为单位)。
【Returns】
    Form1返回的是读取的32位双字内容。
【Comments】
    Form1读单个32位双字，Form2从相同的I/O寄存器读多个32位双字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KIoRegister类实例。

11、outd － Write a dword or multiple dwords (2 forms)
    向映射空间写一个或多个32位双字。
【函数原型】
FORM 1:

VOID outd(
   ULONG ByteOffset,
   ULONG Data
);

FORM 2:

VOID outd(
   ULONG ByteOffset,
   PULONG Buffer,
   ULONG Count
);
【Parameters】
ByteOffset               以0为基地址的字节偏移量，从范围开始(the start of range)到目标单元的开始(the start of target location)之间的偏移。
Buffer     指向获取要读的数据的缓冲区指针。
Count      要写的字数(以32位双字为单位)。
【Comments】
    Form1写单个32位双字，Form2向相同的I/O寄存器写多个32位双字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KIoRegister类实例。

12、operator [ ] － Array element overload used to create instance of KIoRegister
    重载数组元素操作符，用来包含一个KIoRegister类实例。
【函数原型】
    KIoRegister operator [ ] ( int index );
【Parameters】
    index            在映射空间的字节偏移，用来为准备返回的KIoRegister类对象指定在空间中的位置。
【Returns】
    返回一个可以被用来访问I/O寄存器的KIoRegister类实例。注意这个返回值是一个对象，而不是一个指针或参考(reference)。
【Comments】
    一个KIoRange类的数组对象操作符返回一个KIoRegister对象。这些重载操作是为了后来的的类那些类可以用一种比较自然化的语法结构对I/O寄存器进行读和写。比如，假如在名为DevRegs变量里有一个KIoRange的实例，并且我们需要访问在偏移地址为4和6的位置访问字大小的寄存器：
    KIoRegister TxData = DevRegs[4];
    KIoRegister RxData = DevRegs[6];
    USHORT data_in, data_out;
 
    TxData = data_out; // write data to I/O register
    data_in = RxData; // read data from I/O register

                                            －－－－－－－－－－－－－－－－
                                            § 译自"DriverWorks帮助文件"  §
                                            §   李文凯 2008年03月26日    §
                                            －－－－－－－－－－－－－－－－