Plug and Play Manager=====================This file contains the documentation written by Thomas Kurschel that was originallyfound in the headers of his pnp_manager.It's outdated but could be used as a basis for the real documentation.PNP Manager-----------PnP manager; Takes care of registration and loading of PnP driversRead 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 nodeget removed automatically as your driver has obviously nothing to workwith 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 eitherspecify its name directly during registration, using aPNP_DRIVER_FIXED_CONSUMER attribute, or let the manager search theappropriate 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 basedirectory (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 informedSpecification of the base directory and of the names of Specificdrivers is done via a file name pattern given by aPNP_DRIVER_DYNAMIC_CONSUMER attribute.First, all substrings of the form "%attribute_name%" are replaced by thecontent 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 theirunsigned decimal value, delimited by %- other attribute types cannot be usedSecond, the resulting name is split into chunks according to the presenceof | characters (you can escape % and | with a ^ character). Thesecharacters are only delimiters and get removed before further processing.The directory before the first | character is the base directory (seeabove). It contains the "generic" and the "universal" subdirectories.The names of the specific drivers are created by first taking the entirefile name, then by removing the last chunk, then by removing the lasttwo chunks and so on until only the first chunk is left.As drivers can contain multiple modules, the module name is constructedby appending the content of the PNP_DRIVER_TYPE attribute to the driver's filename, seperated by a slash character (note: this only applies to dynamicconsumers; for fixed consumers, you specify the module name directly viaPNP_DRIVER_FIXED_CONSUMER).E.g. given a dynamic consumer pattern of"pci/vendor=%vendor_id%|, device=%device_id%" for a device with theattributes vendor_id=0x123 and device_id=0xabcd (both being uint16), thePnP manager tries the specific drivers "pci/vendor=0123, device=abcd" and(if the first one fails/doesn't exist) "pci/vendor=0123". If they bothrefuse to handle the device, all drivers under "pci/generic" are trieduntil 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 busdoesn'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 toreport an error or invoke an user program that tries downloading aproper Specific driver. Universal drivers are mainly used forinformational 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 DMAchannels (called I/O resources), the driver has to acquire theseresources. 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 viarelease_io_resources(). If detection was successful, the list ofthe (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, thedriver loading is blocked. When detection fails, i.e. ifrelease_io_resources() is called, all blocked drivers can be loadedagain. If the detection fails, i.e. the resources are transferredvia register_device(), all blocked devices are unregistered andpending load requests aborted. If a hardware detection collideswith a device whose driver is loaded, acquire_io_resources() failswith B_BUSY. As this makes a hardware rescan impossible if thedriver is loaded, you should define PNP_DRIVER_NO_LIVE_RESCANfor nodes that use I/O resources (see below).To search for new drivers for a given device node, use rescan(). Thismarks all consumer devices as being verified and calls probe()of all consumers drivers (see above) to let them rescan the parentfor devices. The <depth> parameter determines the nesting level, e.g.2 means that first the consumers are scanned and then the consumersof the consumers.Normally, all devices can be rescanned. If a driver cannot handlea rescan safely when it is loaded (i.e. used by a consumer), itmust set PNP_DRIVER_NO_LIVE_RESCAN, in which case the device isignored during rescan if the driver is loaded and attemptsto load the driver during a rescan are blocked until the rescanis finished. If rescanning a device is not possible at all, it musthave set PNP_DRIVER_NEVER_RESCAN to always ignore it.To distinguish between new devices, lost devices and redetecteddevices, consumer devices should provide a connection code and adevice identifier. They are specified by PNP_DRIVER_CONNECTION andPNP_DRIVER_CONNECTION respectively, and are expanded in the same wayas PNP_DRIVER_DYNAMIC_CONSUMER. It is assumed that there can be onlyone device per connection and that a device can be uniquely identifyby a device identifier. If a consumer device is registered on thesame connection as an existing device but with a different deviceidentifier, the old device gets unregistered automatically. If bothconnection and device identifier are the same, registration ishandled as a redetection and ignored (unless a different type ordriver module is specified - in this case, the device is replaced).Devices that were not redetected during a rescan get unregisteredunless they were ignored (see above)... code-block:: cpp// interface of PnP managertypedef 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 driverstatus_t (*init_driver)(device_node_handle node, void *userCookie,driver_module_info **interface, void **cookie);// unload driverstatus_t (*uninit_driver)(device_node_handle node);// rescan node for new dynamic drivers// node - node whose dynamic drivers are to be scannedstatus_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 NULLstatus_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 toostatus_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 nodedevice_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 anymorevoid (*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 driverstatus_t (*acquire_io_resources)(io_resource *resources,io_resource_handle *handles);// release I/O resources// handles - NULL-terminated array of handlesstatus_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 codeint32 (*create_id)(const char *generator);// free unique idstatus_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 callerstatus_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()// directlystatus_t (*get_next_attr)(device_node_handle node,device_attr_handle *attrHandle);// release attribute handle <attr_handle> of <node>;// see get_next_attrstatus_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 explicitelystatus_t (*retrieve_attr)(device_attr_handle attr_handle,const device_attr **attr);// change/add attribute <attr> of/to nodestatus_t (*write_attr)(device_node_handle node,const device_attr *attr);// remove attribute of node by name// <name> is name of attributestatus_t (*remove_attr)(device_node_handle node, const char *name);} device_manager_info;PNP Driver----------Required interface of PnP driversIn contrast to standard BeOS drivers, PnP drivers are normal moduleshaving the interface described below.Every device is described by its driver via a PnP node with propertiesdescribed in PnP Node Attributes. Devices are organized in a hierarchy,e.g. a devfs device is a hard disk device that is connected to acontroller, which is a PCI device, that is connected to a PCI bus.Every device is connected to its lower-level device via a parent linkstored in its Node. The higher-level is called the consumer of thelower-level device. If the lower-level device gets removed, all itsconsumers are removed too.In our example, the hierarchy isdevfs device -> hard disk -> controller -> PCI device -> PCI busIf the PCI bus is removed, everything up to including the devfs deviceis removed too.The driver hierarchy is constructed bottom-up, i.e. the lower-leveldriver searches for a corresponding consumer, which in turns searchesfor its consumer and so on. The lowest driver is usually something likea PCI bus, the highest driver is normally a devfs entry (see pnp_devfs.h).Registration of devices and the search for appropriate consumers isdone via the pnp_manager (see pnp_manager.h).When a potential consumer is found, it gets informed about the newlower-level device and can either refuse its handling or accept it.On accept, it has to create a new node with the lower-level devicenode as its parent.Loading of drivers is done on demand, i.e. if the consumer wants toaccess its lower-level device, it explicitely loads the correspondingdriver, and once it doesn't need it anymore, the lower-level drivermust be unloaded. Usually, this process happens recursively, i.e. inour example, the hard disk driver loads the controller driver, whichloads the PCI device driver which loads the PCI bus driver. The sameprocess applies to unloading.Because of this dynamic loading, drivers must store persistent datain the node of their devices. Please be aware that you cannot modifya node once published.If a device gets removed, you must unregister its node. As said, thePnP manager will automatically unregister all consumers too. Thecorresponding drivers are notified to stop talking to their lower-leveldevices and to terminate running requests. Normally, you want to use adedicated variable that is verified at each call to make sure that theparent is still there. The notification is done independantly of thedriver being loaded by its consumer(s) or not. If it isn't loaded,the notification callback gets NULL as the device cookie; normally, thedriver returns immediately in this case. As soon as both the deviceis removed and the driver is unloaded, device_cleanup gets called tofree resources that couldn't be safely removed in device_removed whenthe 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 parentduring load. In this case, it's up to the parent driver to get apointer to the interface of the consumer. Effectively, such consumershave one interface for their consumers (base on pnp_driver_info), anda another for their parents (with a completely driver-specificstructure).In terms of synchronization, loading/unloading/remove-notificationsare executed synchronously, i.e. if e.g. a device is to be unloadedbut the drive currently handles a remove-notification, the unloadingis delayed until the nofication callback returns. If multiple consumersload a driver, the driver gets initialized only once; subsequent loadrequests increase an internal load count only and return immediately.In turn, unloading only happens once the load count reaches zero... code-block:: cppstruct driver_module_info {module_info info;float (*supports_device)(device_node_handle parent, bool *_noConnection);// check whether this parent is supportedstatus_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 driverstatus_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 unloadedvoid (*get_supported_paths)(const char ***_busses, const char ***_devices);};PNP Bus-------Required interface of PnP bus driversBusses 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 areon top of abstract device nodes.E.g. if we have a PCI bus with an IDE controller on it, we getIDE controller -> PCI device -> PCI buswith:* IDE controller = actual device node* PCI device = abstract device node* PCI bus = bus nodeThe PCI bus manager establishes both the PCI devices and the PCI busses.Abstract device nodes act as a gateway between actual device nodesand the corresponding bus node. They are constructed by the busnode driver via its rescan() hook. To identify a bus node, definePNP_BUS_IS_BUS as an attribute of it. As a result, the PnP managerwill call the rescan() method of the bus driver whenever thebus is to be rescanned. Afterwards, all possible dynamic consumersare informed as done for normal nodes.Normally, potential device drivers are notified immediately whenrescan() registers a new abstract device node. But sometimes, devicedrivers need to know _all_ devices connected to the bus for correctdetection. To ensure this, the bus node must definePNP_BUS_NOTIFY_CONSUMERS_AFTER_RESCAN. In this case, scanning forconsumers 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 isalways loaded and thus capable of handling hot-plug events generatedby the bus controller hardware.