Mac Developer Library

Developer

IOPCIDevice Class Reference

Options
Deployment Target:

On This Page
Language:

IOPCIDevice

Inheritance


  • IOPCIDevice

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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.

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

    Declaration

    C++

    UInt16 configRead16( IOByteCountoffset )

    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.

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

    Declaration

    C++

    UInt32 configRead32( IOByteCountoffset )

    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.

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

    Declaration

    C++

    UInt8 configRead8( IOByteCountoffset )

    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.

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

    Declaration

    C++

    void configWrite16( IOByteCountoffset, UInt16data )

    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.

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

    Declaration

    C++

    void configWrite32( IOByteCountoffset, UInt32data )

    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.

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

    Declaration

    C++

    void configWrite8( IOByteCountoffset, UInt8data )

    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.

  • enable PCI power management for sleep state

    Declaration

    C++

    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.

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

    Declaration

    C++

    UInt16 extendedConfigRead16( IOByteCountoffset );

    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.

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

    Declaration

    C++

    UInt32 extendedConfigRead32( IOByteCountoffset );

    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.

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

    Declaration

    C++

    UInt8 extendedConfigRead8( IOByteCountoffset );

    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.

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

    Declaration

    C++

    void extendedConfigWrite16( IOByteCountoffset, UInt16data );

    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.

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

    Declaration

    C++

    void extendedConfigWrite32( IOByteCountoffset, UInt32data );

    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.

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

    Declaration

    C++

    void extendedConfigWrite8( IOByteCountoffset, UInt8data );

    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.

  • Search configuration space for a PCI capability register.

    Declaration

    C++

    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.

  • Search configuration space for a PCI capability register.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    virtual IODeviceMemory * getDeviceMemoryWithRegister( UInt8reg );

    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.

  • Accessor to return the PCI device's device number.

    Declaration

    C++

    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.

  • Accessor to return the PCI device's function number.

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.

  • Maps a physical range of the device.

    Declaration

    C++

    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.

  • Sets the device's bus master enable.

    Declaration

    C++

    virtual bool setBusMasterEnable( boolenable );

    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.

  • Sets masked bits in a configuration space register.

    Declaration

    C++

    virtual UInt32 setConfigBits( UInt8offset, UInt32mask, UInt32data );

    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.

  • Sets the device's I/O space response.

    Declaration

    C++

    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.

  • Sets the device's memory space response.

    Declaration

    C++

    virtual bool setMemoryEnable( boolenable );

    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 for future use. (Internal use only)

    Declaration

    C++

    struct IOPCIDeviceExpansionData * reserved;