ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

 

IOPCCard16Enabler

Inherits from:
Declared In:

Overview

Class used to control the configuration of 16-bit PC Card devices.

Discussion

When a 16-bit PC Card is inserted, the PC Card Family creates an IOPCCard16Device provider nub for drivers to match against. The provider nub allows the attached driver to control the card. For each instance of the IOPCCard16Device provider nub there is also an IOPCCard16Enabler object. Most calls to the provider nub are routed to the enabler object. All calls to the enabler come from the provider nub.

16-bit drivers need to take the additional step of configuring the card before they can request to have hardware registers mapped into virtual memory for them. This differs from the PCI or CardBus drivers where the card is presented to the driver in a state that is basically ready to go.

The class IOPCCard16Enabler implements the "default" card enabler for the configuration of cards. For most cards, this default enabler is sufficient for handling the needs of your attached driver. Some drivers may require additional support. The IOPCCard16Enabler class can be subclassed to provide additional support.

The attached 16-bit PC Card driver can replace the default enabler prior to requesting a configuration by calling its provider's installEnabler() method. If your driver supports multiple cards, it can implement more than one enabler and install the correct enabler depending on the card that it matches against.

The most common reason to create your own enabler is to override the default sorting of the configuration tuple entries (CISTPL_CFTABLE_ENTRY) in the card's Card Information Structure (CIS) or Metaformat. Drivers may want to look for different window configurations first. You may wish to filter out certain configurations or in the case of a mistake in the CIS on your card you may need to replace parts the CIS and/or override parts of the configuration process.

The configure method in the provider's nub calls the enabler's configure method to do three things: retrieve the configuration entries from the card's CIS, sort those entries, and then try each entry one by one until a configuration is found that works with that machine's overall configuration. Any or all of these steps can be overridden if necessary.


Functions

configure

Selects a 16-bit card configuration and enables it for use.

eventHandler

Hook for Card Services events.

getConfigurationInfo

Returns information on the card's current configuration.

getConfigurations

Adds configuration data from the card's CIS to the configTable array.

getState

Returns the current state of the card.

getWindowAttributes

Returns the attributes of this window.

getWindowCount

Returns the number of windows that have been configured.

getWindowHandle

Returns the Card Services handle for this window.

getWindowOffset

Returns the offset that this window is currently at.

getWindowSize

Returns the size of this window.

getWindowType

Returns the window type.

setPowerState

Hook for power management state changes.

setWindowOffset

Sets the offset for this window.

sortConfigurations

Sorts configurations in the selection order.

tryConfiguration

Tests if a configuration can be used.

unconfigure

Unconfigures a card.

withDevice

Sets up a new enabler.

configure

Selects a 16-bit card configuration and enables it for use. 

public

virtual bool configure(
    UInt32 index=0);
Parameters
index

Index of configuration to try. If no index is given then it is up to the enabler to decide.

Return Value

Returns true if the card configuration was successful.

Discussion

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 enabler will decide which configuration entries are to be tried.

eventHandler

Hook for Card Services events. 

public

virtual int eventHandler(
    cs_event_t event,
    int priority,
    event_callback_args_t *args);
Return Value

A return value of non-zero prevents the event from being passed on to the socket drivers.

Discussion

This method allows the enabler to catch Card Services events prior to routing them to the attached driver(s). This may be helpful if you need to do addition work or clean up for certain events. The default enabler does nothing.

getConfigurationInfo

Returns information on the card's current configuration. 

public

virtual bool getConfigurationInfo(
    config_info_t *config);
Parameters
config

Pointer to config_info_t structure to be filled in.

Return Value

Returns true on success.

Discussion

This is a convenience method used to call the Card Services call GetConfigurationInfo.

getConfigurations

Adds configuration data from the card's CIS to the configTable array. 

public

virtual bool getConfigurations(
    void);
Return Value

Returns true if any configurations were successfully found.

Discussion

This method fetches configuration data from the card's CIS and expands them out into a form that is easier to use.

getState

Returns the current state of the card. 

public

virtual u_int getState(
    void);
Return Value

Current state of card.

Discussion

This method returns the current state of the card enabler.

getWindowAttributes

Returns the attributes of this window. 

public

virtual bool getWindowAttributes(
    UInt32 index,
    UInt32 *attributes);
Parameters
index

Index of window.

attributes

Pointer to the attribute flags to be filled in.

Return Value

Returns attributes for the window.

Discussion

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);
Return Value

Returns the number of windows.

Discussion

This method returns the number of windows that have been reserved in this configuration.

getWindowHandle

Returns the Card Services handle for this window. 

public

virtual bool getWindowHandle(
    UInt32 index,
    window_handle_t *handle);
Parameters
index

Index to window.

handle

Pointer to the window_handle_t structure to be filled in.

Return Value

Returns true if the window handle was found.

Discussion

This method returns the Card Services handle for the window requested. This call is only valid for memory windows.

getWindowOffset

Returns the offset that this window is currently at. 

public

virtual bool getWindowOffset(
    UInt32 index,
    UInt32 *offset);
Parameters
index

Index of window.

offset

The current offset for this window.

Return Value

Returns true if the returned window offset is valid.

Discussion

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);
Parameters
index

Index of window.

Return Value

Returns the size of the window in bytes.

Discussion

This method returns the size of the window in bytes.

getWindowType

Returns the window type. 

public

virtual UInt32 getWindowType(
    UInt32 index);
Parameters
index

Index of window.

Return Value

Returns IOPCCARD16_MEMORY_WINDOW, IOPCCARD16_IO_WINDOW or IOPCCARD16_BAD_INDEX.

Discussion

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.

setPowerState

Hook for power management state changes. 

public

virtual IOReturn setPowerState(
    unsigned long,
    IOService *);
Return Value

The return value is currently ignored.

Discussion

This method allows the enabler to catch power management events. This may be helpful if you need to do addition work or clean up for certain events. The default enabler uses this to track the state of power management.

setWindowOffset

Sets the offset for this window. 

public

virtual bool setWindowOffset(
    UInt32 index,
    UInt32 newOffset);
Parameters
index

Index of window.

offset

The new offset for this window.

Return Value

Returns true if the window offset was successfully updated.

Discussion

This method updates the offset into the card's memory space for this window. This call is only valid for memory windows.

sortConfigurations

Sorts configurations in the selection order. 

public

virtual bool sortConfigurations(
    void);
Return Value

Returns true if any configurations were successfully found.

Discussion

This method sorts configurations into the order in which they should be tried. This method can also be used to eliminate configurations that might not be valid.

tryConfiguration

Tests if a configuration can be used. 

public

virtual bool tryConfiguration(
    UInt32 index);
Return Value

Returns true if any configurations were successfully found.

Discussion

This method is used to test if a configuration can be reserved from Card Services. If all resources are successfully reserved, the configuration is kept. The configure method enables the configuration later on. The built configuration is kept in the state variable, configuration.

unconfigure

Unconfigures a card. 

public

virtual bool unconfigure();
Return Value

Returns true if the card was successfully unconfigured.

Discussion

This method releases resources that were previously allocated back to Card Services.

withDevice

Sets up a new enabler. 

public

static IOPCCard16Enabler * withDevice(
    IOPCCard16Device *provider);
Return Value

Returns the address of the new enabler.

Discussion

This factory method creates and connects an enabler to a 16-bit PC Card provider nub.

Member Data

configTable

protected

cistpl_cftable_entry_t * configTable[ 32];
Discussion

Stores the expanded information from the CIS configuration tuples

configuration

protected

config_req_t configuration;
Discussion

Stores the configuration reserved from Card Services

device

protected

IOPCCard16Device * device;
Discussion

Pointer to the provider nub

handle

protected

client_handle_t handle;
Discussion

Stores the Card Services handle for this socket

io

protected

io_req_t io;
Discussion

Tracks the current I/O reservations

ioWindowCount

protected

UInt32 ioWindowCount;
Discussion

Number of reserved I/O windows

irq

protected

irq_req_t irq;
Discussion

Tracks the current IRQ reservations

map

protected

memreq_t map[CISTPL_MEM_MAX_WIN];
Discussion

Tracks the current common memory mapping

memoryWindowCount

protected

UInt32 memoryWindowCount;
Discussion

Number of reserved memory windows

req

protected

win_req_t req[CISTPL_MEM_MAX_WIN];
Discussion

Tracks the current common memory reservations

state

protected

u_int state;
Discussion

Stores the current state of this socket

tableEntryCount

protected

u_int tableEntryCount;
Discussion

Number of entries stored in the configTable

win

protected

window_handle_t win[CISTPL_MEM_MAX_WIN];
Discussion

Stores the Card Services handle for a memory window


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19