|
ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference
|
IOPCCard16Device |
| Inherits from: | |
| Declared In: |
Class that represents a 16-bit PC Card device.
Introduction
After the discovery of a 16-bit PC Card, the PC Card Family creates and publishes an instance of the IOPCCard16Device provider nub. This nub provides the driver with methods to handle card initialization, simplified memory and I/O window management, and access to Card Services.
Typically, drivers that attach to the IOPCCard16Device nub will either subclass from another IOKit family or directly from IOService. The IOPCCard16Device class is not meant to be subclassed.
Writing drivers for 16-bit PC Cards should be very similar to writing drivers for PCI or CardBus devices. The main difference is that a card's configuration will also need to be selected before the card can be used. Once the configuration is selected, the mapping of register windows works exactly as with PCI or CardBus device. Most drivers should never need to make a Card Services call to support their card.
The IOPCCard16Device class defers much of its work to an instance of IOPCCard16Enabler class. The enabler does the work of finding, ordering, reserving, and enabling possible card configurations. It handles the details of requesting and releasing individual elements of that configuration from Card Services. The PC Card Family provides a default enabler that should handle most cards. The default enabler is automatically installed for you.
During sleep, PC Cards are completely powered off. When power is returned, cards are automatically reconfigured and left in basically the same state as if the configure method had just been called. The driver is responsible for saving any additional card state across this power management event or it can just reinitialize the card from scratch. The driver should also protect itself at this time from outside events and try to avoid touching the hardware. Typical events include: user requests, spurious interrupts, timer events, card ejection events, ...
When cards are powered down from the menu bar or physically ejected, the driver will first receive a Card Services event through its message method before being terminated. Power management events are handled in the usual IOKit manner.
Types of Driver Matching Supported by IOPCCard16Device
Matching is done by comparing the driver's matching properties against information retrieved from the PC Card's CIS information. In addition to what is provided by IOService, the following types of matching are supported:
"IONameMatch"
The "IONameMatch" property matches the name give by the PC Card Bridge driver to a card's driver. Normally, this name will be of the form "pccardX,Y", where X is the manufacturer ID and Y is the card ID. Both IDs are taken from the tuple CISTPL_MANFID.
If the card has no CIS on it, the name will be "pccard-no-cis". If the card has CIS but it does not have the CISTPL_MANFID tuple the name will be "pccard-no-manfid".
"VersionOneInfo"
The "VersionOneInfo" property match is based on the CISTPL_VERS_1 tuple. It matches against an array of strings, where each string is one of the entries from the version one tuple. Trailing entries that are omitted from the driver's matching entry are treated as wild matches.
"FunctionName"
The "FunctionName" property match is based on the CISTPL_FUNCID tuple. The following function type strings are supported:
"Multi-Function", "Memory", "Serial Port", "Parallel Port", "Fixed Disk", "Video Adapter", "Network Adapter", "AIMS", "SCSI", "Security", "Instrument", "Vendor-Specific", "Anonymous"
The "Anonymous" string is used if no CIS information was found on the card.
"FunctionID"
The "FunctionID" property match is is also based on the CISTPL_FUNCID tuple. Instead of looking for a string, it matches on the actual ID number.
"VendorID"
The "VendorID" property match is based on the manufacturer ID in the CISTPL_MANFID tuple.
"DeviceID"
The "DeviceID" property match is based on the device ID in the CISTPL_MANFID tuple.
"MemoryDeviceName"
The "MemoryDeviceName" property match is based on the CISTPL_DEVICE and CISTPL_DEVICE_A tuples. It matches against the following memory types:
"ROM", "OTPROM", "EPROM", "EEPROM", "Flash", "SRAM", "DRAM", "Function Specific", "Extended"
Makes a call to Card Services.
Selects a 16-bit card configuration and enables it for use.
Returns the Card Services client handle for this card.
Returns information on the card's current configuration.
Returns the current state of the card.
Returns the attributes of this window.
Returns the number of windows that have been configured.
Returns the Card Services handle for this window.
Returns the offset that this window is currently at.
Returns the size of this window.
Returns the window type.
Installs an alternate 16-bit PC Card enabler.
Accessor to the I/O space aperture for this bus.
Reads a 16-bit value from an I/O space aperture.
Reads a 32-bit value from an I/O space aperture.
Reads an 8-bit value from an I/O space aperture.
Writes a 16-bit value to an I/O space aperture.
Writes a 32-bit value to an I/O space aperture.
Writes an 8-bit value to an I/O space aperture.
Sets the offset for this window.
Unconfigures a card.
cardServices |
Makes a call to Card Services.
public
virtual int cardServices( int func, void *arg1 = 0, void *arg2 = 0, void *arg3 = 0);
funcThe Card Services function index.
arg1Argument number one.
arg2Argument number two.
arg3Argument number three.
See "IOKit/pccard/cs.h" for return codes.
This method is used to directly make calls to Card Services. You should always call Card Services using this method. This will ensure that it is run on the correct IOPCCardBridge workloop. See the file "doc/PCMCIA-PROG" in the IOPCCardFamily Darwin project and header file "IOKit/pccard/cs.h" for more info.
In most cases, you should never need to use this method and its misuse will cause problems.
configure |
Selects a 16-bit card configuration and enables it for use.
public
virtual bool configure( UInt32 index = 0);
indexIndex of configuration to try. If no index is given then try all indexes, one by one, until successful.
Returns true if the card configuration was successful.
This method uses the indicated index from the 16-bit PC Card Configuration Table Entry Tuple, CISTPL_CFTABLE_ENTRY, to allocate resources and properly configure the card. If the index is not specified, the currently installed enabler will decide the order in which configuration entries are to be tried. If no index is given, configuration entries are tried one by one until the card is successfully configured. The default enabler sorts entries first by looking for the least number of windows, preferring memory windows over I/O windows.
After making this call, windows need to be mapped into the kernel virtual address space by using the mapDeviceMemoryWithIndex(). This step is the same as the one you would take in a PCI or Cardbus based driver. Additional information about the configured windows can be obtained from this class. This information is sometimes needed when writing a generic driver that matches against multiple cards.
getCardServicesHandle |
Returns the Card Services client handle for this card.
public
virtual client_handle_t getCardServicesHandle( void);
Returns Card Services client handle. This should always be successful.
This method returns the Card Services client handle for this card. This handle is created for the driver when the card was bound to Card Services. This handle is needed to make most Card Services calls. In most cases you should not need to use this method.
getConfigurationInfo |
Returns information on the card's current configuration.
public
virtual bool getConfigurationInfo( config_info_t *config);
configPointer to config_info_t structure to be filled in.
Returns true on success.
This is a convenience method used to call the Card Services call GetConfigurationInfo. Normally this call is not needed.
getState |
Returns the current state of the card.
public
virtual u_int getState( void);
Current state of card. Returns zero if the enabler has not been installed.
This method returns the current state of the card by asking the enabler.
getWindowAttributes |
Returns the attributes of this window.
public
virtual bool getWindowAttributes( UInt32 index, UInt32 *attributes);
indexIndex of window.
attributesPointer to the attribute flags to be filled in.
Returns attributes for the window.
This method returns the attributes for the specified window. The meaning of the attributes flags varies depending on the type of window. The most useful attributes are the data access width flags for I/O windows. For definitions of these flags for both types of windows see "IOKit/pccard/cs.h".
getWindowCount |
Returns the number of windows that have been configured.
public
virtual UInt32 getWindowCount( void);
Returns the number of windows.
This method returns the number of windows in this configuration.
getWindowHandle |
Returns the Card Services handle for this window.
public
virtual bool getWindowHandle( UInt32 index, window_handle_t *handle);
indexIndex to window.
handlePointer to the window_handle_t structure to be filled in.
Returns true if the window handle was found.
This method returns the Card Services handle for the window requested. This call is only valid for memory windows. Normally this call is not needed.
getWindowOffset |
Returns the offset that this window is currently at.
public
virtual bool getWindowOffset( UInt32 index, UInt32 *offset);
indexIndex of window.
offsetThe current offset for this window.
Returns true if the returned window offset is valid.
This method returns the current offset for this window into the card's memory space. This call is only valid for memory windows.
getWindowSize |
Returns the size of this window.
public
virtual UInt32 getWindowSize( UInt32 index);
indexIndex of window.
Returns the size of the window in bytes.
This method returns the size of the window in bytes.
getWindowType |
Returns the window type.
public
virtual UInt32 getWindowType( UInt32 index);
indexIndex of window.
Returns IOPCCARD16_MEMORY_WINDOW, IOPCCARD16_IO_WINDOW or IOPCCARD16_BAD_INDEX.
This method is used to find the type of window given its index. There are two types of windows, I/O and memory. if they are available in a specific configuration, memory windows will always come first in the list of windows.
installEnabler |
Installs an alternate 16-bit PC Card enabler.
public
virtual bool installEnabler( IOPCCard16Enabler *customEnabler = 0);
customEnablerPointer in the instance of an alternate enabler.
Returns true if the enabler was successfully installed.
This method switches out the default enabler for a user-supplied enabler. It is not necessary to call this method if the default enabler is going to be used.
ioDeviceMemory |
Accessor to the I/O space aperture for this bus.
public
virtual IODeviceMemory * ioDeviceMemory( void);
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.
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.
public
virtual UInt16 ioRead16( UInt16 offset, IOMemoryMap *map = 0 );
offsetAn offset into a bus or device's I/O space aperture.
mapIf 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's I/O space.
The value read in host byte order (big endian on PPC).
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 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.
public
virtual UInt32 ioRead32( UInt16 offset, IOMemoryMap *map = 0 );
offsetAn offset into a bus or device's I/O space aperture.
mapIf 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's I/O space.
The value read in host byte order (big endian on PPC).
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 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 an 8-bit value from an I/O space aperture.
public
virtual UInt8 ioRead8( UInt16 offset, IOMemoryMap *map = 0 );
offsetAn offset into a bus or device's I/O space aperture.
mapIf 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's I/O space.
The value read in host byte order (big endian on PPC).
This method will read an 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 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.
public
virtual void ioWrite16( UInt16 offset, UInt16 value, IOMemoryMap *map = 0 );
offsetAn offset into a bus or device's I/O space aperture.
valueThe value to be written in host byte order (big endian on PPC).
mapIf 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's I/O space.
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 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.
public
virtual void ioWrite32( UInt16 offset, UInt32 value, IOMemoryMap *map = 0 );
offsetAn offset into a bus or device's I/O space aperture.
valueThe value to be written in host byte order (big endian on PPC).
mapIf 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's I/O space.
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 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 an 8-bit value to an I/O space aperture.
public
virtual void ioWrite8( UInt16 offset, UInt8 value, IOMemoryMap *map = 0 );
offsetAn offset into a bus or device's I/O space aperture.
valueThe value to be written in host byte order (big endian on PPC).
mapIf 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's I/O space.
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 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.
setWindowOffset |
Sets the offset for this window.
public
virtual bool setWindowOffset( UInt32 index, UInt32 newOffset);
indexIndex of window.
offsetThe new offset for this window.
Returns true if the window offset was successfully updated.
This method updates the offset into the card's memory space for this window. This call is only valid for memory windows.
unconfigure |
Unconfigures a card.
public
virtual bool unconfigure( void);
Returns true if the card was successfully unconfigured.
This method releases resources that were previously allocated back to Card Services. It does not unmap windows. Virtual-to-physical mappings need to be released separately.
|
Last Updated: 2008-12-19