24cea645f1
We might want to use it as a basis for the device manager documentation. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@12634 a95241bf-73f2-0310-859d-f6bbb57e9c96
407 lines
18 KiB
Plaintext
407 lines
18 KiB
Plaintext
This file contains the documentation written by Thomas Kurschel that was originally
|
|
found in the headers of his pnp_manager.
|
|
It's outdated but could be used as a basis for the real documentation.
|
|
|
|
// former pnp_manager.h
|
|
/*
|
|
Copyright (c) 2003-04, Thomas Kurschel
|
|
|
|
PnP manager; Takes care of registration and loading of PnP drivers
|
|
|
|
Read pnp_driver.h first to understand the basic idea behind PnP drivers.
|
|
|
|
To register a driver node, use register_driver. If the device got lost,
|
|
use unregister_driver (note: if the parent node is removed, your node
|
|
get removed automatically as your driver has obviously nothing to work
|
|
with anymore). To get access to a (parent) device, use load_driver/
|
|
unload_driver.
|
|
|
|
To let the manager find a consumer (see pnp_driver.h), you can either
|
|
specify its name directly during registration, using a
|
|
PNP_DRIVER_FIXED_CONSUMER attribute, or let the manager search the
|
|
appropriate consumer(s) via a PNP_DRIVER_DYNAMIC_CONSUMER attribute.
|
|
|
|
Searching of dynamic consumers is done as follows:
|
|
|
|
- First, the manager searches for a Specific driver in the base
|
|
directory (see below)
|
|
- If no Specific driver is found, all Generic drivers stored under
|
|
"generic" sub-directory are informed in turn until one returns success
|
|
- Finally, _all_ Universal drivers, stored in the "universal" sub-
|
|
directory, are informed
|
|
|
|
Specification of the base directory and of the names of Specific
|
|
drivers is done via a file name pattern given by a
|
|
PNP_DRIVER_DYNAMIC_CONSUMER attribute.
|
|
|
|
First, all substrings of the form "%attribute_name%" are replaced by the
|
|
content of the attribute "attribute_name" as follows:
|
|
|
|
- if the attribute contains an integer value, its content is converted to hex
|
|
(lowercase) with a fixed length according to the attribute's value range
|
|
- the content of string attributes is quoted by " and invalid characters
|
|
(i.e. /%" and all characters outside 32..126) are replaced by their
|
|
unsigned decimal value, delimited by %
|
|
- other attribute types cannot be used
|
|
|
|
Second, the resulting name is split into chunks according to the presence
|
|
of | characters (you can escape % and | with a ^ character). These
|
|
characters are only delimiters and get removed before further processing.
|
|
The directory before the first | character is the base directory (see
|
|
above). It contains the "generic" and the "universal" subdirectories.
|
|
The names of the specific drivers are created by first taking the entire
|
|
file name, then by removing the last chunk, then by removing the last
|
|
two chunks and so on until only the first chunk is left.
|
|
|
|
As drivers can contain multiple modules, the module name is constructed
|
|
by appending the content of the PNP_DRIVER_TYPE attribute to the driver's file
|
|
name, seperated by a slash character (note: this only applies to dynamic
|
|
consumers; for fixed consumers, you specify the module name directly via
|
|
PNP_DRIVER_FIXED_CONSUMER).
|
|
|
|
E.g. given a dynamic consumer pattern of
|
|
"pci/vendor=%vendor_id%|, device=%device_id%" for a device with the
|
|
attributes vendor_id=0x123 and device_id=0xabcd (both being uint16), the
|
|
PnP manager tries the specific drivers "pci/vendor=0123, device=abcd" and
|
|
(if the first one fails/doesn't exist) "pci/vendor=0123". If they both
|
|
refuse to handle the device, all drivers under "pci/generic" are tried
|
|
until one accepts the device. Finally, all drivers under "pci/universal"
|
|
are loaded, whatever happened before.
|
|
|
|
In practise, you should try to use specific drivers as much as possible.
|
|
If detection based on device IDs is impossible (e.g. because the bus
|
|
doesn't support them at all), you can put the driver under "generic".
|
|
Generic drivers can also be used to specify wrappers that try to load old-
|
|
style drivers if no new driver can be found. Also, they can be used to
|
|
report an error or invoke an user program that tries downloading a
|
|
proper Specific driver. Universal drivers are mainly used for
|
|
informational purposes, e.g. to publish data about each found device,
|
|
or to provide raw access to all devices.
|
|
|
|
If the device uses physical address space or I/O space or ISA DMA
|
|
channels (called I/O resources), the driver has to acquire these
|
|
resources. During hardware detection (usually via probe()),
|
|
acquire_io_resources() must be called to get exclusive access.
|
|
If no hardware could be found, they must be released via
|
|
release_io_resources(). If detection was successful, the list of
|
|
the (acquired) resources must be passed to register_device().
|
|
Resources can either belong to one hardware detection or to a device.
|
|
If a hardware detection collides with another, it has to wait;
|
|
if it collides with a device whose driver is not loaded, the
|
|
driver loading is blocked. When detection fails, i.e. if
|
|
release_io_resources() is called, all blocked drivers can be loaded
|
|
again. If the detection fails, i.e. the resources are transferred
|
|
via register_device(), all blocked devices are unregistered and
|
|
pending load requests aborted. If a hardware detection collides
|
|
with a device whose driver is loaded, acquire_io_resources() fails
|
|
with B_BUSY. As this makes a hardware rescan impossible if the
|
|
driver is loaded, you should define PNP_DRIVER_NO_LIVE_RESCAN
|
|
for nodes that use I/O resources (see below).
|
|
|
|
To search for new drivers for a given device node, use rescan(). This
|
|
marks all consumer devices as being verified and calls probe()
|
|
of all consumers drivers (see above) to let them rescan the parent
|
|
for devices. The <depth> parameter determines the nesting level, e.g.
|
|
2 means that first the consumers are scanned and then the consumers
|
|
of the consumers.
|
|
|
|
Normally, all devices can be rescanned. If a driver cannot handle
|
|
a rescan safely when it is loaded (i.e. used by a consumer), it
|
|
must set PNP_DRIVER_NO_LIVE_RESCAN, in which case the device is
|
|
ignored during rescan if the driver is loaded and attempts
|
|
to load the driver during a rescan are blocked until the rescan
|
|
is finished. If rescanning a device is not possible at all, it must
|
|
have set PNP_DRIVER_NEVER_RESCAN to always ignore it.
|
|
|
|
To distinguish between new devices, lost devices and redetected
|
|
devices, consumer devices should provide a connection code and a
|
|
device identifier. They are specified by PNP_DRIVER_CONNECTION and
|
|
PNP_DRIVER_CONNECTION respectively, and are expanded in the same way
|
|
as PNP_DRIVER_DYNAMIC_CONSUMER. It is assumed that there can be only
|
|
one device per connection and that a device can be uniquely identify
|
|
by a device identifier. If a consumer device is registered on the
|
|
same connection as an existing device but with a different device
|
|
identifier, the old device gets unregistered automatically. If both
|
|
connection and device identifier are the same, registration is
|
|
handled as a redetection and ignored (unless a different type or
|
|
driver module is specified - in this case, the device is replaced).
|
|
Devices that were not redetected during a rescan get unregistered
|
|
unless they were ignored (see above).
|
|
*/
|
|
|
|
// interface of PnP manager
|
|
typedef struct device_manager_info {
|
|
module_info info;
|
|
|
|
// load driver
|
|
// node - node whos driver is to be loaded
|
|
// user_cookie - cookie to be passed to init_device of driver
|
|
// interface - interface of loaded driver
|
|
// cookie - device cookie issued by loaded driver
|
|
status_t (*init_driver)(device_node_handle node, void *userCookie,
|
|
driver_module_info **interface, void **cookie);
|
|
// unload driver
|
|
status_t (*uninit_driver)(device_node_handle node);
|
|
|
|
// rescan node for new dynamic drivers
|
|
// node - node whose dynamic drivers are to be scanned
|
|
status_t (*rescan)(device_node_handle node);
|
|
|
|
// register device
|
|
// parent - parent node
|
|
// attributes - NULL-terminated array of node attributes
|
|
// io_resources - NULL-terminated array of I/O resources (can be NULL)
|
|
// node - new node handle
|
|
// on return, io_resources are invalid: on success I/O resources belong
|
|
// to node, on fail they are released;
|
|
// if device is already registered, B_OK is returned but *node is NULL
|
|
status_t (*register_device)(device_node_handle parent,
|
|
const device_attr *attrs,
|
|
const io_resource_handle *io_resources,
|
|
device_node_handle *node);
|
|
// unregister device
|
|
// all nodes having this node as their parent are unregistered too.
|
|
// if the node contains PNP_MANAGER_ID_GENERATOR/PNP_MANAGER_AUTO_ID
|
|
// pairs, the id specified this way is freed too
|
|
status_t (*unregister_device)(device_node_handle node);
|
|
|
|
// find device by node content
|
|
// the given attributes must _uniquely_ identify a device node;
|
|
// parent - parent node (-1 for don't-care)
|
|
// attrs - list of attributes (can be NULL)
|
|
// The node you got will be automatically put on the next call
|
|
// to this function.
|
|
status_t (*get_next_child_device)(device_node_handle parent,
|
|
device_node_handle *_node, const device_attr *attrs);
|
|
|
|
// get parent device node
|
|
device_node_handle (*get_parent)(device_node_handle node);
|
|
|
|
// Must be called after get_next_child_device() (if you don't iterate through)
|
|
// and get_parent() to make sure the node is freed when it's not used anymore
|
|
void (*put_device_node)(device_node_handle node);
|
|
|
|
// acquire I/O resources
|
|
// resources - NULL-terminated array of resources to acquire
|
|
// handles - NULL-terminated array of handles (one per resource);
|
|
// array must be provided by caller
|
|
// return B_BUSY if a resource is used by a loaded driver
|
|
status_t (*acquire_io_resources)(io_resource *resources,
|
|
io_resource_handle *handles);
|
|
// release I/O resources
|
|
// handles - NULL-terminated array of handles
|
|
status_t (*release_io_resources)(const io_resource_handle *handles);
|
|
|
|
// create unique id
|
|
// generator - name of id set
|
|
// if result >= 0 - unique id
|
|
// result < 0 - error code
|
|
int32 (*create_id)(const char *generator);
|
|
// free unique id
|
|
status_t (*free_id)(const char *generator, uint32 id);
|
|
|
|
// helpers to extract attribute by name.
|
|
// if <recursive> is true, parent nodes are scanned if
|
|
// attribute isn't found in current node; unless you declared
|
|
// the attribute yourself, use recursive search to handle
|
|
// intermittent nodes, e.g. defined by filter drivers, transparently.
|
|
// for raw and string attributes, you get a copy that must
|
|
// be freed by caller
|
|
status_t (*get_attr_uint8)(device_node_handle node,
|
|
const char *name, uint8 *value, bool recursive);
|
|
status_t (*get_attr_uint16)(device_node_handle node,
|
|
const char *name, uint16 *value, bool recursive);
|
|
status_t (*get_attr_uint32)(device_node_handle node,
|
|
const char *name, uint32 *value, bool recursive);
|
|
status_t (*get_attr_uint64)(device_node_handle node,
|
|
const char *name, uint64 *value, bool recursive);
|
|
status_t (*get_attr_string)(device_node_handle node,
|
|
const char *name, char **value, bool recursive);
|
|
status_t (*get_attr_raw)(device_node_handle node,
|
|
const char *name, void **data, size_t *_size,
|
|
bool recursive);
|
|
|
|
// get next attribute of node;
|
|
// on call, *<attr_handle> must contain handle of an attribute;
|
|
// on return, *<attr_handle> is replaced by the next attribute or
|
|
// NULL if it was the last;
|
|
// to get the first attribute, <attr_handle> must point to NULL;
|
|
// the returned handle must be released by either passing it to
|
|
// another get_next_attr() call or by using release_attr()
|
|
// directly
|
|
status_t (*get_next_attr)(device_node_handle node,
|
|
device_attr_handle *attrHandle);
|
|
|
|
// release attribute handle <attr_handle> of <node>;
|
|
// see get_next_attr
|
|
status_t (*release_attr)(device_node_handle node,
|
|
device_attr_handle attr_handle);
|
|
|
|
// retrieve attribute data with handle given;
|
|
// <attr> is only valid as long as you don't release <attr_handle>
|
|
// implicitely or explicitely
|
|
status_t (*retrieve_attr)(device_attr_handle attr_handle,
|
|
const device_attr **attr);
|
|
|
|
// change/add attribute <attr> of/to node
|
|
status_t (*write_attr)(device_node_handle node,
|
|
const device_attr *attr);
|
|
|
|
// remove attribute of node by name
|
|
// <name> is name of attribute
|
|
status_t (*remove_attr)(device_node_handle node, const char *name);
|
|
} device_manager_info;
|
|
|
|
// former pnp_driver.h
|
|
/*
|
|
Copyright (c) 2003-04, Thomas Kurschel
|
|
|
|
Required interface of PnP drivers
|
|
|
|
In contrast to standard BeOS drivers, PnP drivers are normal modules
|
|
having the interface described below.
|
|
|
|
Every device is described by its driver via a PnP node with properties
|
|
described in PnP Node Attributes. Devices are organized in a hierarchy,
|
|
e.g. a devfs device is a hard disk device that is connected to a
|
|
controller, which is a PCI device, that is connected to a PCI bus.
|
|
Every device is connected to its lower-level device via a parent link
|
|
stored in its Node. The higher-level is called the consumer of the
|
|
lower-level device. If the lower-level device gets removed, all its
|
|
consumers are removed too.
|
|
|
|
In our example, the hierarchy is
|
|
|
|
devfs device -> hard disk -> controller -> PCI device -> PCI bus
|
|
|
|
If the PCI bus is removed, everything up to including the devfs device
|
|
is removed too.
|
|
|
|
The driver hierarchy is constructed bottom-up, i.e. the lower-level
|
|
driver searches for a corresponding consumer, which in turns searches
|
|
for its consumer and so on. The lowest driver is usually something like
|
|
a PCI bus, the highest driver is normally a devfs entry (see pnp_devfs.h).
|
|
Registration of devices and the search for appropriate consumers is
|
|
done via the pnp_manager (see pnp_manager.h).
|
|
|
|
When a potential consumer is found, it gets informed about the new
|
|
lower-level device and can either refuse its handling or accept it.
|
|
On accept, it has to create a new node with the lower-level device
|
|
node as its parent.
|
|
|
|
Loading of drivers is done on demand, i.e. if the consumer wants to
|
|
access its lower-level device, it explicitely loads the corresponding
|
|
driver, and once it doesn't need it anymore, the lower-level driver
|
|
must be unloaded. Usually, this process happens recursively, i.e. in
|
|
our example, the hard disk driver loads the controller driver, which
|
|
loads the PCI device driver which loads the PCI bus driver. The same
|
|
process applies to unloading.
|
|
|
|
Because of this dynamic loading, drivers must store persistent data
|
|
in the node of their devices. Please be aware that you cannot modify
|
|
a node once published.
|
|
|
|
If a device gets removed, you must unregister its node. As said, the
|
|
PnP manager will automatically unregister all consumers too. The
|
|
corresponding drivers are notified to stop talking to their lower-level
|
|
devices and to terminate running requests. Normally, you want to use a
|
|
dedicated variable that is verified at each call to make sure that the
|
|
parent is still there. The notification is done independantly of the
|
|
driver being loaded by its consumer(s) or not. If it isn't loaded,
|
|
the notification callback gets NULL as the device cookie; normally, the
|
|
driver returns immediately in this case. As soon as both the device
|
|
is removed and the driver is unloaded, device_cleanup gets called to
|
|
free resources that couldn't be safely removed in device_removed when
|
|
the driver was still loaded.
|
|
|
|
If a device has exactly one consumer, they often interact in some way.
|
|
To simplify that, the consumer can pass a user-cookie to its parent
|
|
during load. In this case, it's up to the parent driver to get a
|
|
pointer to the interface of the consumer. Effectively, such consumers
|
|
have one interface for their consumers (base on pnp_driver_info), and
|
|
a another for their parents (with a completely driver-specific
|
|
structure).
|
|
|
|
In terms of synchronization, loading/unloading/remove-notifications
|
|
are executed synchronously, i.e. if e.g. a device is to be unloaded
|
|
but the drive currently handles a remove-notification, the unloading
|
|
is delayed until the nofication callback returns. If multiple consumers
|
|
load a driver, the driver gets initialized only once; subsequent load
|
|
requests increase an internal load count only and return immediately.
|
|
In turn, unloading only happens once the load count reaches zero.
|
|
*/
|
|
|
|
struct driver_module_info {
|
|
module_info info;
|
|
|
|
float (*supports_device)(device_node_handle parent, bool *_noConnection);
|
|
// check whether this parent is supported
|
|
|
|
status_t (*register_device)(device_node_handle parent);
|
|
// Register your device node.
|
|
|
|
status_t (*init_driver)(device_node_handle node, void *user_cookie, void **_cookie);
|
|
// driver is loaded.
|
|
// node - node of device
|
|
// user_cookie - cookie passed by loading driver
|
|
// cookie - cookie issued by this driver
|
|
|
|
status_t (*uninit_driver)(void *cookie);
|
|
// driver gets unloaded.
|
|
|
|
void (*device_removed)(device_node_handle node, void *cookie);
|
|
// a device node, registered by this driver, got removed.
|
|
// if the driver wasn't loaded when this happenes, no (un)init_device
|
|
// is called and thus <cookie> is NULL;
|
|
|
|
void (*device_cleanup)(device_node_handle node);
|
|
// a device node, registered by this driver, got removed and
|
|
// the driver got unloaded
|
|
|
|
void (*get_supported_paths)(const char ***_busses, const char ***_devices);
|
|
};
|
|
|
|
// former pnp_bus.h
|
|
/*
|
|
Copyright (c) 2003-04, Thomas Kurschel
|
|
|
|
Required interface of PnP bus drivers
|
|
|
|
Busses consist of two node layers: the lower layer defines the bus,
|
|
the upper layer defines the abstract devices connected to the bus.
|
|
Both layers are handled by a bus manager. Actual device nodes are
|
|
on top of abstract device nodes.
|
|
|
|
E.g. if we have a PCI bus with an IDE controller on it, we get
|
|
|
|
IDE controller -> PCI device -> PCI bus
|
|
|
|
with:
|
|
IDE controller = actual device node
|
|
PCI device = abstract device node
|
|
PCI bus = bus node
|
|
|
|
The PCI bus manager establishes both the PCI devices and the PCI busses.
|
|
|
|
Abstract device nodes act as a gateway between actual device nodes
|
|
and the corresponding bus node. They are constructed by the bus
|
|
node driver via its rescan() hook. To identify a bus node, define
|
|
PNP_BUS_IS_BUS as an attribute of it. As a result, the PnP manager
|
|
will call the rescan() method of the bus driver whenever the
|
|
bus is to be rescanned. Afterwards, all possible dynamic consumers
|
|
are informed as done for normal nodes.
|
|
|
|
Normally, potential device drivers are notified immediately when
|
|
rescan() registers a new abstract device node. But sometimes, device
|
|
drivers need to know _all_ devices connected to the bus for correct
|
|
detection. To ensure this, the bus node must define
|
|
PNP_BUS_NOTIFY_CONSUMERS_AFTER_RESCAN. In this case, scanning for
|
|
consumers is postponed until rescan() has finished.
|
|
|
|
If hot-plugging of devices can be detected automatically (e.g. USB),
|
|
you should define PNP_DRIVER_ALWAYS_LOADED, so the bus driver is
|
|
always loaded and thus capable of handling hot-plug events generated
|
|
by the bus controller hardware.
|
|
*/
|
|
|