IOPCIDevice

Inherits from
IOService
Availability
Available in OS X v10.0 and later.
Declared in
IOPCIDevice.h

Overview

An IOService class representing a PCI device.

The discovery of a PCI device by the PCI bus family results in an instance of the IOPCIDevice being created and published. It provides services for looking up and mapping memory mapped hardware, and access to the PCI configuration and I/O spaces.

Matching Supported by IOPCIDevice

Two types of matching are available, OpenFirmware name matching and PCI register matching. Currently, only one of these two matching schemes can be used in the same property table.

OpenFirmware Name Matching

IOService performs matching based on the IONameMatch property (see IOService). IOPCIDevices created with OpenFirmware device tree entries will name match based on the standard OpenFirmware name matching properties.

PCI Register Matching

A PCI device driver can also match on the values of certain config space registers.

In each case, several matching values can be specified, and an optional mask for the value of the config space register may follow the value, preceded by an '&' character.

kIOPCIMatchKey, "IOPCIMatch"

The kIOPCIMatchKey property matches the vendor and device ID (0x00) register, or the subsystem register (0x2c).

kIOPCIPrimaryMatchKey, "IOPCIPrimaryMatch"

The kIOPCIPrimaryMatchKey property matches the vendor and device ID (0x00) register.

kIOPCISecondaryMatchKey, "IOPCISecondaryMatch"

The kIOPCISecondaryMatchKey property matches the subsystem register (0x2c).

kIOPCIClassMatchKey, "IOPCIClassMatch"

The kIOPCIClassMatchKey property matches the class code register (0x08). The default mask for this register is 0xffffff00.

Examples:

&ltkey&gtIOPCIMatch&lt/key&gt

&ltstring&gt0x00261011&lt/string&gt

Matches a device whose vendor ID is 0x1011, and device ID is 0x0026, including subsystem IDs.

&ltkey&gtIOPCIMatch&lt/key&gt

&ltstring&gt0x00789004&0x00ffffff 0x78009004&0x0xff00ffff&lt/string&gt

Matches with any device with a vendor ID of 0x9004, and a device ID of 0xzz78 or 0x78zz, where 'z' is don't care.

&ltkey&gtIOPCIClassMatch&lt/key&gt

&ltstring&gt0x02000000&0xffff0000&lt/string&gt

Matches a device whose class code is 0x0200zz, an ethernet device.

Tasks

Miscellaneous

Instance Methods

configRead16

Reads a 16-bit value from the PCI device's configuration space.

UInt16 configRead16( IOByteCount offset )
Parameters
offset

An offset into configuration space, of which bit 0 is ignored.

Return Value

An 16-bit value in host byte order (big endian on PPC).

Discussion

This method reads a 16-bit configuration space register on the device and returns its value.

configRead32

Reads a 32-bit value from the PCI device's configuration space.

UInt32 configRead32( IOByteCount offset )
Parameters
offset

An offset into configuration space, of which bits 0-1 are ignored.

Return Value

An 32-bit value in host byte order (big endian on PPC).

Discussion

This method reads a 32-bit configuration space register on the device and returns its value.

configRead8

Reads a 8-bit value from the PCI device's configuration space.

UInt8 configRead8( IOByteCount offset )
Parameters
offset

An offset into configuration space.

Return Value

An 8-bit value.

Discussion

This method reads a 8-bit configuration space register on the device and returns its value.

configWrite16

Writes a 16-bit value to the PCI device's configuration space.

void configWrite16( IOByteCount offset, UInt16 data )
Parameters
offset

An offset into configuration space, of which bit 0 is ignored.

data

An 16-bit value to be written in host byte order (big endian on PPC).

Discussion

This method write a 16-bit value to a configuration space register on the device.

configWrite32

Writes a 32-bit value to the PCI device's configuration space.

void configWrite32( IOByteCount offset, UInt32 data )
Parameters
offset

An offset into configuration space, of which bits 0-1 are ignored.

data

An 32-bit value to be written in host byte order (big endian on PPC).

Discussion

This method write a 32-bit value to a configuration space register on the device.

configWrite8

Writes a 8-bit value to the PCI device's configuration space.

void configWrite8( IOByteCount offset, UInt8 data )
Parameters
offset

An offset into configuration space.

data

An 8-bit value to be written.

Discussion

This method write a 8-bit value to a configuration space register on the device.

enablePCIPowerManagement

enable PCI power management for sleep state

virtual IOReturn enablePCIPowerManagement( IOOptionBits state = 0xffffffff);
Parameters
state(optional)

Enables PCI Power Management by placing the function in the given state (e.g. kPCIPMCSPowerStateD3). If state is not specified or is 0xffffffff, then the IOPCIDevice determines the desired state. If state is kPCIPMCSPowerStateD0 (0) then PCI Power Management is disabled.

Return Value

kIOReturnSuccess if there were no errors

Discussion

This method will enable PCI Bus Powermanagement when going to sleep mode.

extendedConfigRead16

Reads a 16-bit value from the PCI device's configuration space.

UInt16 extendedConfigRead16( IOByteCount offset );
Parameters
offset

A byte offset into configuration space, of which bit 0 is ignored.

Return Value

An 16-bit value in host byte order (big endian on PPC).

Discussion

This method reads a 16-bit configuration space register on the device and returns its value.

extendedConfigRead32

Reads a 32-bit value from the PCI device's configuration space.

UInt32 extendedConfigRead32( IOByteCount offset );
Parameters
offset

A byte offset into configuration space, of which bits 0-1 are ignored.

Return Value

An 32-bit value in host byte order (big endian on PPC).

Discussion

This method reads a 32-bit configuration space register on the device and returns its value.

extendedConfigRead8

Reads a 8-bit value from the PCI device's configuration space.

UInt8 extendedConfigRead8( IOByteCount offset );
Parameters
offset

A byte offset into configuration space.

Return Value

An 8-bit value.

Discussion

This method reads a 8-bit configuration space register on the device and returns its value.

extendedConfigWrite16

Writes a 16-bit value to the PCI device's configuration space.

void extendedConfigWrite16( IOByteCount offset, UInt16 data );
Parameters
offset

A byte offset into configuration space, of which bit 0 is ignored.

data

An 16-bit value to be written in host byte order (big endian on PPC).

Discussion

This method writes a 16-bit value to a configuration space register on the device.

extendedConfigWrite32

Writes a 32-bit value to the PCI device's configuration space.

void extendedConfigWrite32( IOByteCount offset, UInt32 data );
Parameters
offset

A byte offset into configuration space, of which bits 0-1 are ignored.

data

An 32-bit value to be written in host byte order (big endian on PPC).

Discussion

This method writes a 32-bit value to a configuration space register on the device.

extendedConfigWrite8

Writes a 8-bit value to the PCI device's configuration space.

void extendedConfigWrite8( IOByteCount offset, UInt8 data );
Parameters
offset

A byte offset into configuration space.

data

An 8-bit value to be written.

Discussion

This method writes a 8-bit value to a configuration space register on the device.

extendedFindPCICapability

Search configuration space for a PCI capability register.

virtual UInt32 extendedFindPCICapability( UInt32 capabilityID, IOByteCount *offset = 0 );
Parameters
capabilityID

A PCI capability ID. PCI Express devices may support extended capabilities in config space starting at offset 0x100. To search this space, the ID passed should be the negated value of the PCI-SIG assigned ID for the extended capability.

offset

An optional in/out parameter to return the offset into config space where the capability was found, and to set the start point of the next search. Initialize the offset to zero before the first call to extendedFindPCICapability() and subsequent calls will find all capabilty blocks that may exist on the device with the same ID.

Return Value

The 32-bit value of the capability register if one was found, zero otherwise.

Discussion

This method searches the device's config space for a PCI capability register matching the passed capability ID, if the device supports PCI capabilities.

findPCICapability

Search configuration space for a PCI capability register.

virtual UInt32 findPCICapability( UInt8 capabilityID, UInt8 *offset = 0 );
Parameters
capabilityID

An 8-bit PCI capability ID.

offset

An optional pointer to return the offset into config space where the capability was found.

Return Value

The 32-bit value of the capability register if one was found, zero otherwise.

Discussion

This method searches the device's config space for a PCI capability register matching the passed capability ID, if the device supports PCI capabilities. To search for PCI Express extended capabilities or for multiple capablities with the same ID, use the extendedFindPCICapability() method.

getBusNumber

Accessor to return the PCI device's assigned bus number.

virtual UInt8 getBusNumber( void );
Return Value

The 8-bit value of device's PCI bus number.

Discussion

This method is an accessor to return the PCI device's assigned bus number.

getDeviceMemoryWithRegister

Returns an instance of IODeviceMemory representing one of the device's memory mapped ranges.

virtual IODeviceMemory * getDeviceMemoryWithRegister( UInt8 reg );
Parameters
reg

The 8-bit configuration space register that is the base address register for the desired range.

Return Value

A pointer to an instance of IODeviceMemory, or zero no such range was found. The IODeviceMemory is retained by the provider, so is valid while attached, or while any mappings to it exist. It should not be released by the caller.

Discussion

This method will return a pointer to an instance of IODeviceMemory for the physical memory range that was assigned to the configuration space base address register passed in. It is analogous to IOService::getDeviceMemoryWithIndex.

getDeviceNumber

Accessor to return the PCI device's device number.

virtual UInt8 getDeviceNumber( void );
Return Value

The 5-bit value of device's device number.

Discussion

This method is an accessor to return the PCI device's device number.

getFunctionNumber

Accessor to return the PCI device's function number.

virtual UInt8 getFunctionNumber( void );
Return Value

The 3-bit value of device's function number.

Discussion

This method is an accessor to return the PCI device's function number.

hasPCIPowerManagement

determine whether or not the device supports PCI Bus Power Management.

virtual bool hasPCIPowerManagement( IOOptionBits state = 0);
Parameters
state(optional)

Check for support of a specific state (e.g. kPCIPMCPMESupportFromD3Cold). If state is not suuplied or is 0, then check for a property in the registry which tells which state the hardware expects the device to go to during sleep.

Return Value

true if the specified state is supported

Discussion

This method will look at the device's capabilties registers and determine whether or not the device supports the PCI BUS Power Management Specification.

ioDeviceMemory

Accessor to the I/O space aperture for the bus.

virtual IODeviceMemory * ioDeviceMemory( void );
Return Value

A pointer to an IODeviceMemory object for the I/O aperture. The IODeviceMemory is retained by the provider, so is valid while attached, or while any mappings to it exist. It should not be released by the caller.

Discussion

This method will return a reference to the IODeviceMemory for the I/O aperture of the bus the device is on.

ioRead16

Reads a 16-bit value from an I/O space aperture.

virtual UInt16 ioRead16( UInt16 offset, IOMemoryMap *map = 0 );
Parameters
offset

An offset into a bus or device's I/O space aperture.

map

If the offset is relative to the beginning of a device's aperture, an IOMemoryMap object for that object should be passed in. Otherwise, passing zero will write the value relative to the beginning of the bus' I/O space.

Return Value

The value read in host byte order (big endian on PPC).

Discussion

This method will read a 16-bit value from a 2 byte aligned offset in an I/O space aperture. If a map object is passed in, the value is read relative to it, otherwise to the value is read relative to the I/O space aperture for the bus. This function encapsulates the differences between architectures in generating I/O space operations. An eieio instruction is included on PPC.

ioRead32

Reads a 32-bit value from an I/O space aperture.

virtual UInt32 ioRead32( UInt16 offset, IOMemoryMap *map = 0 );
Parameters
offset

An offset into a bus or device's I/O space aperture.

map

If the offset is relative to the beginning of a device's aperture, an IOMemoryMap object for that object should be passed in. Otherwise, passing zero will write the value relative to the beginning of the bus' I/O space.

Return Value

The value read in host byte order (big endian on PPC).

Discussion

This method will read a 32-bit value from a 4 byte aligned offset in an I/O space aperture. If a map object is passed in, the value is read relative to it, otherwise to the value is read relative to the I/O space aperture for the bus. This function encapsulates the differences between architectures in generating I/O space operations. An eieio instruction is included on PPC.

ioRead8

Reads a 8-bit value from an I/O space aperture.

virtual UInt8 ioRead8( UInt16 offset, IOMemoryMap *map = 0 );
Parameters
offset

An offset into a bus or device's I/O space aperture.

map

If the offset is relative to the beginning of a device's aperture, an IOMemoryMap object for that object should be passed in. Otherwise, passing zero will write the value relative to the beginning of the bus' I/O space.

Return Value

The value read.

Discussion

This method will read a 8-bit value from an offset in an I/O space aperture. If a map object is passed in, the value is read relative to it, otherwise to the value is read relative to the I/O space aperture for the bus. This function encapsulates the differences between architectures in generating I/O space operations. An eieio instruction is included on PPC.

ioWrite16

Writes a 16-bit value to an I/O space aperture.

virtual void ioWrite16( UInt16 offset, UInt16 value, IOMemoryMap *map = 0 );
Parameters
offset

An offset into a bus or device's I/O space aperture.

value

The value to be written in host byte order (big endian on PPC).

map

If the offset is relative to the beginning of a device's aperture, an IOMemoryMap object for that object should be passed in. Otherwise, passing zero will write the value relative to the beginning of the bus' I/O space.

Discussion

This method will write a 16-bit value to a 2 byte aligned offset in an I/O space aperture. If a map object is passed in, the value is written relative to it, otherwise to the value is written relative to the I/O space aperture for the bus. This function encapsulates the differences between architectures in generating I/O space operations. An eieio instruction is included on PPC.

ioWrite32

Writes a 32-bit value to an I/O space aperture.

virtual void ioWrite32( UInt16 offset, UInt32 value, IOMemoryMap *map = 0 );
Parameters
offset

An offset into a bus or device's I/O space aperture.

value

The value to be written in host byte order (big endian on PPC).

map

If the offset is relative to the beginning of a device's aperture, an IOMemoryMap object for that object should be passed in. Otherwise, passing zero will write the value relative to the beginning of the bus' I/O space.

Discussion

This method will write a 32-bit value to a 4 byte aligned offset in an I/O space aperture. If a map object is passed in, the value is written relative to it, otherwise to the value is written relative to the I/O space aperture for the bus. This function encapsulates the differences between architectures in generating I/O space operations. An eieio instruction is included on PPC.

ioWrite8

Writes a 8-bit value to an I/O space aperture.

virtual void ioWrite8( UInt16 offset, UInt8 value, IOMemoryMap *map = 0 );
Parameters
offset

An offset into a bus or device's I/O space aperture.

value

The value to be written in host byte order (big endian on PPC).

map

If the offset is relative to the beginning of a device's aperture, an IOMemoryMap object for that object should be passed in. Otherwise, passing zero will write the value relative to the beginning of the bus' I/O space.

Discussion

This method will write a 8-bit value to an offset in an I/O space aperture. If a map object is passed in, the value is written relative to it, otherwise to the value is written relative to the I/O space aperture for the bus. This function encapsulates the differences between architectures in generating I/O space operations. An eieio instruction is included on PPC.

mapDeviceMemoryWithRegister

Maps a physical range of the device.

virtual IOMemoryMap * mapDeviceMemoryWithRegister( UInt8 reg, IOOptionBits options = 0 );
Parameters
reg

The 8-bit configuration space register that is the base address register for the desired range.

options

Options to be passed to the IOMemoryDescriptor::map() method.

Return Value

An instance of IOMemoryMap, or zero if the index is beyond the count available. The mapping should be released only when access to it is no longer required.

Discussion

This method will create a mapping for the IODeviceMemory for the physical memory range that was assigned to the configuration space base address register passed in, with IODeviceMemory::map(options). The mapping is represented by the returned instance of IOMemoryMap, which should not be released until the mapping is no longer required. This method is analogous to IOService::mapDeviceMemoryWithIndex.

setBusMasterEnable

Sets the device's bus master enable.

virtual bool setBusMasterEnable( bool enable );
Parameters
enable

True or false to enable or disable bus mastering.

Return Value

True if bus mastering was previously enabled, false otherwise.

Discussion

This method sets the bus master enable bit in the device's command config space register to the passed value, and returns the previous state of the enable.

setConfigBits

Sets masked bits in a configuration space register.

virtual UInt32 setConfigBits( UInt8 offset, UInt32 mask, UInt32 value );
Parameters
offset

An 8-bit offset into configuration space, of which bits 0-1 are ignored.

mask

An 32-bit mask indicating which bits in the value parameter are valid.

data

An 32-bit value to be written in host byte order (big endian on PPC).

Return Value

The value of the register masked with the mask before the write.

Discussion

This method sets masked bits in a configuration space register on the device by reading and writing the register. The value of the masked bits before the write is returned.

setIOEnable

Sets the device's I/O space response.

virtual bool setIOEnable( bool enable, bool exclusive = false );
Parameters
enable

True or false to enable or disable the I/O space response.

exclusive

If true, only one setIOEnable with the exclusive flag set will be allowed at a time on the bus, this should be only for temporary access.

Return Value

True if the I/O space response was previously enabled, false otherwise.

Discussion

This method sets the I/O space response bit in the device's command config space register to the passed value, and returns the previous state of the enable. The exclusive option allows only one exclusive device on the bus to be enabled concurrently, this should be only for temporary access.

setMemoryEnable

Sets the device's memory space response.

virtual bool setMemoryEnable( bool enable );
Parameters
enable

True or false to enable or disable the memory space response.

Return Value

True if the memory space response was previously enabled, false otherwise.

Discussion

This method sets the memory space response bit in the device's command config space register to the passed value, and returns the previous state of the enable.

Instance Variables

reserved

struct IOPCIDeviceExpansionData * reserved;

Reserved for future use. (Internal use only)