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

KMemoryRange类：

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

二、Member Functions

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

KMemoryRange( void );

FORM 2: (NTDDK Only)

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

FORM 3 (WDM):

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

FORM 4 (WDM):

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

FORM 5 (WDM):

KMemoryRange(
   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总线上的物理地址或被翻译好的外围地址。
    pTranslatedResourceList     指向一个在KPnpDevice::OnStartDevice中可用的已翻译的资源列表的指针。可以通过KIrp::TranslatedResources获得。
    pRawResourceList            指向一个在KPnpDevice::OnStartDevice中可用的原始资源列表的指针。可以通过KIrp::AllocatedResources获得。
    Ordinal                     序号。从pTranslatedResourceList指向的资源列表中指定一个特殊的端口资源。0表示第一个端口，1表示第二个端口，依次类推。
【Comments】
    如果用Form1，需要调用Initialize()才能建立映射。当对象被嵌入KDevice派生类对象时，这是一个常用的方法。
    Form3,Form4和Form5只能用在WDM平台。Form3需要一个已经译码到CPU空间的物理地址作为参数。Form4需要一个已经译码的资源列表和一个指定列表中一个特定资源的序号。这种形式需要从资源中提取信息来创建对象。设置Ordinal为0可以指定列表中的第一个资源，1指定第二个，依次类推。除了端口之外的类型列表中的资源没有被计数(not counted)。
    使用成员函数ConstructorStatus()来获取构造函数的执行状态。
    支撑它的底层系统服务是HalTranslateBusAddress (只对FORM 2有效) 和 MmMapIoSpace。
    注意：如果我们用Form4，就必须强制转换第二个参数，以避免和Form5的形式混淆。
    这个函数只能在PASSIVE_LEVEL级别上被调用。

2、Initialize － Initialize or reinitialize an instance (3 forms)
初始化或重新初始化KMemoryRange实例。
【函数原型】
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,
   ULONG Count,
   BOOLEAN MapToSystemVirtual=TRUE
);

FORM 3 (WDM):

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、~KMemoryRange － Destructor
    析构函数。
【函数原型】
    ~KMemoryRange( 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】
    如果当前KMemoryRange对象被正确的初始化了就返回TRUE。
【Comments】
    这个函数是从KPeripheralAddress类继承过来的函数。
    如果对象和底层系统memory范围(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从相同的memory读多个字节。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KMemoryRegister类实例。

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向相同的memory写多个字节。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KMemoryRegister类实例。

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从相同的memory读多个字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KMemoryRegister类实例。

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向相同的memory写多个16位字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KMemoryRegister类实例。

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从相同的memory读多个32位双字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KMemoryRegister类实例。

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向相同的memory写多个32位双字。
    这个函数是内联实现的(in-line)，使用了恰当的系统宏来访问。
    对于单个单元的访问，一个备选方案是创建一个KMemoryRegister类实例。

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

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