NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ALLOWED CALLING CONTEXTS | ATTRIBUTES | SEE ALSO
#include <ddi/hsc/hsc.h>
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DDI
Provides a generic interface to access the Hot Swap control and status register.
typedef struct PciSwapOps { PciSwapVersion version; KnError (*open) __((DevClientId reg_id, /* svDeviceLookup id */ void* dev_cookie, /* handlers cookie */ PciSwapEvents* events_tbl, /* table of events handlers */ PciSwapId* dev_id)); /* returned client id */ KnError (*lock)__((PciSwapId dev_id, PciPropDevNum dev_num)); KnError (*unlock)__((PciSwapId dev_id, PciPropDevNum dev_num)); KnError (*eject)__((PciSwapId dev_id, PciPropDevNum dev_num)); void (*close) __((PciSwapId dev_id)); } PciSwapOps;
A pointer to the PciSwapOps structure is exported by the driver via the svDeviceRegister() microkernel call. A driver client invokes the svDeviceLookup() and svDeviceEntry() microkernel calls in order to obtain a pointer to the device service routine vector. Once the pointer is obtained, the driver client is able to invoke the driver service routine (via the indirect function call) in order to handle the ENUM# signal.
open() opens a connection to a given PciSwap driver. open() must be the first call to the device driver. The PciSwap device driver are designed to be used by hot-swappable bus driver. The DevNode argument is the node of the client driver (usually an hot swappable pci bus driver). The PciSwap driver will check if the device corresponding to the device node given as argument is allowed to handle hot swap events.
The device id retrieved from the device registry
The data to give back as argument to the client PciSwap event handler.
Contains opaque data given back from the PciSwap driver identifying the driver client.
On success K_OK is returned. And the dev_id argument contains the driver client identification.
On failure, an error code is returned as follow:
Not enough memory resource.
close() closes the connection with a given PciSwap device driver.
Identifies the connection with the device driver. This parameter was given back to the driver client by the open service routine.
It locks the given pci slot identified by the pci device number. Each time a device driver is started and performs an open() on the parent hot-swapable pci bus, this pci bus should lock the device num throughout this method. It indicates that the given pci slot is busy. At init time an 'hot-swapable' bus driver should lock all slot before probing and initializing its children device, and unlocking all pci slot after initialization is done.
pciswap device identifier.
The logical slot to lock.
On success K_OK is returned. On failure, an error code is returned as follow:
This method unlocks the given slot number given as argument. When the lock counter reach 0, it provokes a slotfree event to the client. This method has to be called after the shutdown of the 'hot-swapable' pci bus children. This method is generally called by the bus driver after its child driver has close its connection.
The pciswap device identifier.
The logical slot number to unlock.
On success K_OK is returned. On failure, an error code is returned as follow:
The counter has been decremented but has not reached 0. The slot is still busy.
This method has to be called when a free slot has to be ejected. The blue led will be on forever.
The pciswap device identifier.
The device number to eject.
typedef struct PciSwapEvents { void (*inserted) __((void* cookie, PciPropDevNum dev)); void (*toremove) __((void* cookie, PciPropDevNum dev)); void (*slotfree) __((void* cookie, PciPropDevNum dev)); void (*ejected) __((void* cookie, PciPropDevNum dev)); } PciSwapEvents;
When a board insertion occurs, the pciswap driver client will be notified through the inserted PciSwapEvents given at open time.
The data pointer given by the client through the open() method.
The logical slot number (pci device number).
In this event handler the pciswap client is supposed to start/initialize the newly inserted device driver. This event handler is called in the context of the DKI thread.
When a board extraction occurs, the pciswap driver client will be notified through the toremove() PciSwapEvents given at open time.
The data pointer given by the client through the open() method.
The logical slot number which is going to be extracted.
In this event handler the pciswap client is supposed to shutdown the correponding device driver instance, by the same way the lock() number should reach 0. This event handler is called in the context of the DKI thread.
When the lock count is decreased to 0, the pciswap driver notifies its client through this event.
The data pointer given by the client through the open() method.
The logical slot number (pci device number).
In this event handler, the client is supposed to update the device tree. The client can optionally call in this handler the eject() method in order to turn the blue LED on. This event handler is called synchronously from the unlock() method when the lock counter reaches 0.
This event handler is called when to indicates the completion of the eject() method.
The data pointer given by the client through the open() method.
The logical slot number (pci device number).
This event handler is optional and can be to perform final operations. This event is not implemented in the references driver (pciswap/dec2115x).
The following table specifies the contexts in which a caller is allowed to invoke each service:
Services | Base level | DKI thread | Interrupt | Blocking |
---|---|---|---|---|
PciSwapOps.open() | + | + | + | |
PciSwapOps.close() | + | + | + | |
PciSwapOps.lock() | + | + | ||
PciSwapOps.unlock() | + | + | ||
PciSwapOps.eject() | + | + |
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ALLOWED CALLING CONTEXTS | ATTRIBUTES | SEE ALSO