WDM驱动程序开发之读写设备寄存器：KIoRange类2009-11-09 14:05WDM驱动程序开发之读写设备寄存器：KIoRange类收藏KIoRange类：一、OverviewKIoRange类将一系列特殊的外围总线的地址映射到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 Functions1、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)向映射空间写一个或多个字节。