sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget*/translations/zh_CN/arch/s390/driver-modelmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/zh_TW/arch/s390/driver-modelmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/it_IT/arch/s390/driver-modelmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ja_JP/arch/s390/driver-modelmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ko_KR/arch/s390/driver-modelmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/sp_SP/arch/s390/driver-modelmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hS/390 driver model interfacesh]hS/390 driver model interfaces}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhD/var/lib/git/docbuild/linux/Documentation/arch/s390/driver-model.rsthKubh)}(hhh](h)}(h1. CCW devicesh]h1. CCW devices}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(h{All devices which can be addressed by means of ccws are called 'CCW devices' - even if they aren't actually driven by ccws.h]hAll devices which can be addressed by means of ccws are called ‘CCW devices’ - even if they aren’t actually driven by ccws.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hcAll ccw devices are accessed via a subchannel, this is reflected in the structures under devices/::h]hbAll ccw devices are accessed via a subchannel, this is reflected in the structures under devices/:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh literal_block)}(hdevices/ - system/ - css0/ - 0.0.0000/0.0.0815/ - 0.0.0001/0.0.4711/ - 0.0.0002/ - 0.1.0000/0.1.1234/ ... - defunct/h]hdevices/ - system/ - css0/ - 0.0.0000/0.0.0815/ - 0.0.0001/0.0.4711/ - 0.0.0002/ - 0.1.0000/0.1.1234/ ... - defunct/}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhKhhhhubh)}(hIn this example, device 0815 is accessed via subchannel 0 in subchannel set 0, device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.h]hIn this example, device 0815 is accessed via subchannel 0 in subchannel set 0, device 4711 via subchannel 1 in subchannel set 0, and subchannel 2 is a non-I/O subchannel. Device 1234 is accessed via subchannel 0 in subchannel set 1.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXgThe subchannel named 'defunct' does not represent any real subchannel on the system; it is a pseudo subchannel where disconnected ccw devices are moved to if they are displaced by another ccw device becoming operational on their former subchannel. The ccw devices will be moved again to a proper subchannel if they become operational again on that subchannel.h]hXkThe subchannel named ‘defunct’ does not represent any real subchannel on the system; it is a pseudo subchannel where disconnected ccw devices are moved to if they are displaced by another ccw device becoming operational on their former subchannel. The ccw devices will be moved again to a proper subchannel if they become operational again on that subchannel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hoYou should address a ccw device via its bus id (e.g. 0.0.4711); the device can be found under bus/ccw/devices/.h]hoYou should address a ccw device via its bus id (e.g. 0.0.4711); the device can be found under bus/ccw/devices/.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hhhhubh)}(h+All ccw devices export some data via sysfs.h]h+All ccw devices export some data via sysfs.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hhhhubhdefinition_list)}(hhh](hdefinition_list_item)}(h'cutype: The control unit type / model. h](hterm)}(hcutype:h]hcutype:}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhK(hj7ubh definition)}(hhh]h)}(hThe control unit type / model.h]hThe control unit type / model.}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjMubah}(h]h ]h"]h$]h&]uh1jKhj7ubeh}(h]h ]h"]h$]h&]uh1j5hhhK(hj2ubj6)}(h1devtype: The device type / model, if applicable. h](j<)}(hdevtype:h]hdevtype:}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhK+hjjubjL)}(hhh]h)}(h'The device type / model, if applicable.h]h'The device type / model, if applicable.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK+hj|ubah}(h]h ]h"]h$]h&]uh1jKhjjubeh}(h]h ]h"]h$]h&]uh1j5hhhK+hj2hhubj6)}(h[availability: Can be 'good' or 'boxed'; 'no path' or 'no device' for disconnected devices. h](j<)}(h availability:h]h availability:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhK/hjubjL)}(hhh]h)}(hLCan be 'good' or 'boxed'; 'no path' or 'no device' for disconnected devices.h]h\Can be ‘good’ or ‘boxed’; ‘no path’ or ‘no device’ for disconnected devices.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhK/hj2hhubj6)}(honline: An interface to set the device online and offline. In the special case of the device being disconnected (see the notify function under 1.2), piping 0 to online will forcibly delete the device. h](j<)}(honline:h]honline:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhK5hjubjL)}(hhh]h)}(hAn interface to set the device online and offline. In the special case of the device being disconnected (see the notify function under 1.2), piping 0 to online will forcibly delete the device.h]hAn interface to set the device online and offline. In the special case of the device being disconnected (see the notify function under 1.2), piping 0 to online will forcibly delete the device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhK5hj2hhubeh}(h]h ]h"]h$]h&]uh1j0hhhhhhhNubh)}(hLThe device drivers can add entries to export per-device data and interfaces.h]hLThe device drivers can add entries to export per-device data and interfaces.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hhhhubh)}(hXThere is also some data exported on a per-subchannel basis (see under bus/css/devices/):h]hXThere is also some data exported on a per-subchannel basis (see under bus/css/devices/):}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hhhhubj1)}(hhh](j6)}(h2chpids: Via which chpids the device is connected. h](j<)}(hchpids:h]hchpids:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhK=hjubjL)}(hhh]h)}(h)Via which chpids the device is connected.h]h)Via which chpids the device is connected.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK=hj.ubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhK=hjubj6)}(hJpimpampom: The path installed, path available and path operational masks. h](j<)}(h pimpampom:h]h pimpampom:}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhK@hjKubjL)}(hhh]h)}(h>The path installed, path available and path operational masks.h]h>The path installed, path available and path operational masks.}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hj]ubah}(h]h ]h"]h$]h&]uh1jKhjKubeh}(h]h ]h"]h$]h&]uh1j5hhhK@hjhhubeh}(h]h ]h"]h$]h&]uh1j0hhhhhhhNubh)}(hCThere also might be additional data, for example for block devices.h]hCThere also might be additional data, for example for block devices.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhhhhubeh}(h] ccw-devicesah ]h"]1. ccw devicesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h1.1 Bringing up a ccw deviceh]h1.1 Bringing up a ccw device}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKFubh)}(hThis is done in several steps.h]hThis is done in several steps.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjhhubhenumerated_list)}(hhh](h list_item)}(hEach driver can provide one or more parameter interfaces where parameters can be specified. These interfaces are also in the driver's responsibility.h]h)}(hEach driver can provide one or more parameter interfaces where parameters can be specified. These interfaces are also in the driver's responsibility.h]hEach driver can provide one or more parameter interfaces where parameters can be specified. These interfaces are also in the driver’s responsibility.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKJhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hiAfter a. has been performed, if necessary, the device is finally brought up via the 'online' interface. h]h)}(hgAfter a. has been performed, if necessary, the device is finally brought up via the 'online' interface.h]hkAfter a. has been performed, if necessary, the device is finally brought up via the ‘online’ interface.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]enumtype loweralphaprefixhsuffix.uh1jhjhhhhhKJubeh}(h]bringing-up-a-ccw-deviceah ]h"]1.1 bringing up a ccw deviceah$]h&]uh1hhhhhhhhKFubh)}(hhh](h)}(h$1.2 Writing a driver for ccw devicesh]h$1.2 Writing a driver for ccw devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKQubh)}(hkThe basic struct ccw_device and struct ccw_driver data structures can be found under include/asm/ccwdev.h::h]hjThe basic struct ccw_device and struct ccw_driver data structures can be found under include/asm/ccwdev.h:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjhhubh)}(hXstruct ccw_device { spinlock_t *ccwlock; struct ccw_device_private *private; struct ccw_device_id id; struct ccw_driver *drv; struct device dev; int online; void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb); }; struct ccw_driver { struct module *owner; struct ccw_device_id *ids; int (*probe) (struct ccw_device *); int (*remove) (struct ccw_device *); int (*set_online) (struct ccw_device *); int (*set_offline) (struct ccw_device *); int (*notify) (struct ccw_device *, int); struct device_driver driver; char *name; };h]hXstruct ccw_device { spinlock_t *ccwlock; struct ccw_device_private *private; struct ccw_device_id id; struct ccw_driver *drv; struct device dev; int online; void (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb); }; struct ccw_driver { struct module *owner; struct ccw_device_id *ids; int (*probe) (struct ccw_device *); int (*remove) (struct ccw_device *); int (*set_online) (struct ccw_device *); int (*set_offline) (struct ccw_device *); int (*notify) (struct ccw_device *, int); struct device_driver driver; char *name; };}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKVhjhhubh)}(htThe 'private' field contains data needed for internal i/o operation only, and is not available to the device driver.h]hxThe ‘private’ field contains data needed for internal i/o operation only, and is not available to the device driver.}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKohjhhubh)}(hEach driver should declare in a MODULE_DEVICE_TABLE into which CU types/models and/or device types/models it is interested. This information can later be found in the struct ccw_device_id fields::h]hEach driver should declare in a MODULE_DEVICE_TABLE into which CU types/models and/or device types/models it is interested. This information can later be found in the struct ccw_device_id fields:}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjhhubh)}(hstruct ccw_device_id { __u16 match_flags; __u16 cu_type; __u16 dev_type; __u8 cu_model; __u8 dev_model; unsigned long driver_info; };h]hstruct ccw_device_id { __u16 match_flags; __u16 cu_type; __u16 dev_type; __u8 cu_model; __u8 dev_model; unsigned long driver_info; };}hjHsbah}(h]h ]h"]h$]h&]hhuh1hhhhKvhjhhubh)}(h@The functions in ccw_driver should be used in the following way:h]h@The functions in ccw_driver should be used in the following way:}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj1)}(hhh]j6)}(hX probe: This function is called by the device layer for each device the driver is interested in. The driver should only allocate private structures to put in dev->driver_data and create attributes (if needed). Also, the interrupt handler (see below) should be set here. h](j<)}(hprobe:h]hprobe:}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjgubjL)}(hhh]h)}(hXThis function is called by the device layer for each device the driver is interested in. The driver should only allocate private structures to put in dev->driver_data and create attributes (if needed). Also, the interrupt handler (see below) should be set here.h]hXThis function is called by the device layer for each device the driver is interested in. The driver should only allocate private structures to put in dev->driver_data and create attributes (if needed). Also, the interrupt handler (see below) should be set here.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyubah}(h]h ]h"]h$]h&]uh1jKhjgubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjdubah}(h]h ]h"]h$]h&]uh1j0hjhhhhhNubh)}(h'int (*probe) (struct ccw_device *cdev);h]h'int (*probe) (struct ccw_device *cdev);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubj1)}(hhh](j6)}(h5Parameters: cdev - the device to be probed. h](j<)}(h Parameters:h]h Parameters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j1)}(hhh]j6)}(h!cdev - the device to be probed. h](j<)}(hcdevh]hcdev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h bullet_list)}(hhh]j)}(hthe device to be probed. h]h)}(hthe device to be probed.h]hthe device to be probed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]bullet-uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubah}(h]h ]h"]h$]h&]uh1j0hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubj6)}(hremove: This function is called by the device layer upon removal of the driver, the device or the module. The driver should perform cleanups here. h](j<)}(hremove:h]hremove:}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h)}(hThis function is called by the device layer upon removal of the driver, the device or the module. The driver should perform cleanups here.h]hThis function is called by the device layer upon removal of the driver, the device or the module. The driver should perform cleanups here.}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj/ubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjhhubeh}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubh)}(h(int (*remove) (struct ccw_device *cdev);h]h(int (*remove) (struct ccw_device *cdev);}hjRsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubj1)}(hhh](j6)}(h6Parameters: cdev - the device to be removed. h](j<)}(h Parameters:h]h Parameters:}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjcubjL)}(hhh]j1)}(hhh]j6)}(h"cdev - the device to be removed. h](j<)}(hcdevh]hcdev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhj{ubjL)}(hhh]j)}(hhh]j)}(hthe device to be removed. h]h)}(hthe device to be removed.h]hthe device to be removed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhj{ubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjxubah}(h]h ]h"]h$]h&]uh1j0hjuubah}(h]h ]h"]h$]h&]uh1jKhjcubeh}(h]h ]h"]h$]h&]uh1j5hhhKhj`ubj6)}(hset_online: This function is called by the common I/O layer when the device is activated via the 'online' attribute. The driver should finally setup and activate the device here. h](j<)}(h set_online:h]h set_online:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h)}(hThis function is called by the common I/O layer when the device is activated via the 'online' attribute. The driver should finally setup and activate the device here.h]hThis function is called by the common I/O layer when the device is activated via the ‘online’ attribute. The driver should finally setup and activate the device here.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhj`hhubeh}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubh)}(h(int (*set_online) (struct ccw_device *);h]h(int (*set_online) (struct ccw_device *);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubj1)}(hhh](j6)}(hParameters: cdev - the device to be activated. The common layer has verified that the device is not already online. h](j<)}(h Parameters:h]h Parameters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j1)}(hhh]j6)}(hkcdev - the device to be activated. The common layer has verified that the device is not already online. h](j<)}(hcdevh]hcdev}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhj-ubjL)}(hhh]j)}(hhh]j)}(hbthe device to be activated. The common layer has verified that the device is not already online. h]h)}(h`the device to be activated. The common layer has verified that the device is not already online.h]h`the device to be activated. The common layer has verified that the device is not already online.}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjEubah}(h]h ]h"]h$]h&]uh1jhjBubah}(h]h ]h"]h$]h&]jjuh1jhhhKhj?ubah}(h]h ]h"]h$]h&]uh1jKhj-ubeh}(h]h ]h"]h$]h&]uh1j5hhhKhj*ubah}(h]h ]h"]h$]h&]uh1j0hj'ubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubj6)}(hset_offline: This function is called by the common I/O layer when the device is de-activated via the 'online' attribute. The driver should shut down the device, but not de-allocate its private data. h](j<)}(hOset_offline: This function is called by the common I/O layer when the device ish]hOset_offline: This function is called by the common I/O layer when the device is}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h)}(hvde-activated via the 'online' attribute. The driver should shut down the device, but not de-allocate its private data.h]hzde-activated via the ‘online’ attribute. The driver should shut down the device, but not de-allocate its private data.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjhhubeh}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubh)}(h)int (*set_offline) (struct ccw_device *);h]h)int (*set_offline) (struct ccw_device *);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubj1)}(hhh](j6)}(h~Parameters: cdev - the device to be deactivated. The common layer has verified that the device is online. h](j<)}(h Parameters:h]h Parameters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j1)}(hhh]j6)}(hbcdev - the device to be deactivated. The common layer has verified that the device is online. h](j<)}(hcdevh]hcdev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j)}(hhh]j)}(hYthe device to be deactivated. The common layer has verified that the device is online. h]j1)}(hhh]j6)}(hXthe device to be deactivated. The common layer has verified that the device is online. h](j<)}(h2the device to be deactivated. The common layer hash]h2the device to be deactivated. The common layer has}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h)}(h#verified that the device is online.h]h#verified that the device is online.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubah}(h]h ]h"]h$]h&]uh1j0hjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubah}(h]h ]h"]h$]h&]uh1j0hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubj6)}(hXinotify: This function is called by the common I/O layer for some state changes of the device. Signalled to the driver are: * In online state, device detached (CIO_GONE) or last path gone (CIO_NO_PATH). The driver must return !0 to keep the device; for return code 0, the device will be deleted as usual (also when no notify function is registered). If the driver wants to keep the device, it is moved into disconnected state. * In disconnected state, device operational again (CIO_OPER). The common I/O layer performs some sanity checks on device number and Device / CU to be reasonably sure if it is still the same device. If not, the old device is removed and a new one registered. By the return code of the notify function the device driver signals if it wants the device back: !0 for keeping, 0 to make the device being removed and re-registered. h](j<)}(hnotify:h]hnotify:}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhj]ubjL)}(hhh](h)}(hUThis function is called by the common I/O layer for some state changes of the device.h]hUThis function is called by the common I/O layer for some state changes of the device.}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjoubh)}(hSignalled to the driver are:h]hSignalled to the driver are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjoubj)}(hhh](j)}(hX,In online state, device detached (CIO_GONE) or last path gone (CIO_NO_PATH). The driver must return !0 to keep the device; for return code 0, the device will be deleted as usual (also when no notify function is registered). If the driver wants to keep the device, it is moved into disconnected state.h]h)}(hX,In online state, device detached (CIO_GONE) or last path gone (CIO_NO_PATH). The driver must return !0 to keep the device; for return code 0, the device will be deleted as usual (also when no notify function is registered). If the driver wants to keep the device, it is moved into disconnected state.h]hX,In online state, device detached (CIO_GONE) or last path gone (CIO_NO_PATH). The driver must return !0 to keep the device; for return code 0, the device will be deleted as usual (also when no notify function is registered). If the driver wants to keep the device, it is moved into disconnected state.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hXIn disconnected state, device operational again (CIO_OPER). The common I/O layer performs some sanity checks on device number and Device / CU to be reasonably sure if it is still the same device. If not, the old device is removed and a new one registered. By the return code of the notify function the device driver signals if it wants the device back: !0 for keeping, 0 to make the device being removed and re-registered. h]h)}(hXIn disconnected state, device operational again (CIO_OPER). The common I/O layer performs some sanity checks on device number and Device / CU to be reasonably sure if it is still the same device. If not, the old device is removed and a new one registered. By the return code of the notify function the device driver signals if it wants the device back: !0 for keeping, 0 to make the device being removed and re-registered.h]hXIn disconnected state, device operational again (CIO_OPER). The common I/O layer performs some sanity checks on device number and Device / CU to be reasonably sure if it is still the same device. If not, the old device is removed and a new one registered. By the return code of the notify function the device driver signals if it wants the device back: !0 for keeping, 0 to make the device being removed and re-registered.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]j*uh1jhhhKhjoubeh}(h]h ]h"]h$]h&]uh1jKhj]ubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjhhubeh}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubh)}(h)int (*notify) (struct ccw_device *, int);h]h)int (*notify) (struct ccw_device *, int);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubj1)}(hhh]j6)}(hParameters: cdev - the device whose state changed. event - the event that happened. This can be one of CIO_GONE, CIO_NO_PATH or CIO_OPER. h](j<)}(h Parameters:h]h Parameters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j1)}(hhh](j6)}(h'cdev - the device whose state changed. h](j<)}(hcdevh]hcdev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j)}(hhh]j)}(h the device whose state changed. h]h)}(hthe device whose state changed.h]hthe device whose state changed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubj6)}(hYevent - the event that happened. This can be one of CIO_GONE, CIO_NO_PATH or CIO_OPER. h](j<)}(heventh]hevent}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjEubjL)}(hhh]j)}(hhh]j)}(hOthe event that happened. This can be one of CIO_GONE, CIO_NO_PATH or CIO_OPER. h]h)}(hNthe event that happened. This can be one of CIO_GONE, CIO_NO_PATH or CIO_OPER.h]hNthe event that happened. This can be one of CIO_GONE, CIO_NO_PATH or CIO_OPER.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj]ubah}(h]h ]h"]h$]h&]uh1jhjZubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjWubah}(h]h ]h"]h$]h&]uh1jKhjEubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubeh}(h]h ]h"]h$]h&]uh1j0hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubah}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubh)}(hX8The handler field of the struct ccw_device is meant to be set to the interrupt handler for the device. In order to accommodate drivers which use several distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device instead of ccw_driver. The handler is registered with the common layer during set_online() processing before the driver is called, and is deregistered during set_offline() after the driver has been called. Also, after registering / before deregistering, path grouping resp. disbanding of the path group (if applicable) are performed.h]hX8The handler field of the struct ccw_device is meant to be set to the interrupt handler for the device. In order to accommodate drivers which use several distinct handlers (e.g. multi subchannel devices), this is a member of ccw_device instead of ccw_driver. The handler is registered with the common layer during set_online() processing before the driver is called, and is deregistered during set_offline() after the driver has been called. Also, after registering / before deregistering, path grouping resp. disbanding of the path group (if applicable) are performed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hQvoid (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);h]hQvoid (*handler) (struct ccw_device *dev, unsigned long intparm, struct irb *irb);}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubj1)}(hhh]j6)}(hXCParameters: dev - the device the handler is called for intparm - the intparm which allows the device driver to identify the i/o the interrupt is associated with, or to recognize the interrupt as unsolicited. irb - interruption response block which contains the accumulated status. h](j<)}(h>Parameters: dev - the device the handler is called forh]h>Parameters: dev - the device the handler is called for}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]j1)}(hhh](j6)}(hintparm - the intparm which allows the device driver to identify the i/o the interrupt is associated with, or to recognize the interrupt as unsolicited.h](j<)}(h@intparm - the intparm which allows the device driver to identifyh]h@intparm - the intparm which allows the device driver to identify}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h)}(hWthe i/o the interrupt is associated with, or to recognize the interrupt as unsolicited.h]hWthe i/o the interrupt is associated with, or to recognize the interrupt as unsolicited.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubj6)}(hMirb - interruption response block which contains the accumulated status. h](j<)}(hDirb - interruption response block which contains the accumulatedh]hDirb - interruption response block which contains the accumulated}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhKhjubjL)}(hhh]h)}(hstatus.h]hstatus.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubeh}(h]h ]h"]h$]h&]uh1j0hjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhKhjubah}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubh)}(hThe device driver is called from the common ccw_device layer and can retrieve information about the interrupt from the irb parameter.h]hThe device driver is called from the common ccw_device layer and can retrieve information about the interrupt from the irb parameter.}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] writing-a-driver-for-ccw-devicesah ]h"]$1.2 writing a driver for ccw devicesah$]h&]uh1hhhhhhhhKQubh)}(hhh](h)}(h1.3 ccwgroup devicesh]h1.3 ccwgroup devices}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhjbhhhhhKubh)}(hjThe ccwgroup mechanism is designed to handle devices consisting of multiple ccw devices, like qeth or ctc.h]hjThe ccwgroup mechanism is designed to handle devices consisting of multiple ccw devices, like qeth or ctc.}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(hThe ccw driver provides a 'group' attribute. Piping bus ids of ccw devices to this attributes creates a ccwgroup device consisting of these ccw devices (if possible). This ccwgroup device can be set online or offline just like a normal ccw device.h]hThe ccw driver provides a ‘group’ attribute. Piping bus ids of ccw devices to this attributes creates a ccwgroup device consisting of these ccw devices (if possible). This ccwgroup device can be set online or offline just like a normal ccw device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(hEach ccwgroup device also provides an 'ungroup' attribute to destroy the device again (only when offline). This is a generic ccwgroup mechanism (the driver does not need to implement anything beyond normal removal routines).h]hEach ccwgroup device also provides an ‘ungroup’ attribute to destroy the device again (only when offline). This is a generic ccwgroup mechanism (the driver does not need to implement anything beyond normal removal routines).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjbhhubh)}(hA ccw device which is a member of a ccwgroup device carries a pointer to the ccwgroup device in the driver_data of its device struct. This field must not be touched by the driver - it should use the ccwgroup device's driver_data for its private data.h]hA ccw device which is a member of a ccwgroup device carries a pointer to the ccwgroup device in the driver_data of its device struct. This field must not be touched by the driver - it should use the ccwgroup device’s driver_data for its private data.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjbhhubh)}(hTo implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in mind that most drivers will need to implement both a ccwgroup and a ccw driver.h]hTo implement a ccwgroup driver, please refer to include/asm/ccwgroup.h. Keep in mind that most drivers will need to implement both a ccwgroup and a ccw driver.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjbhhubeh}(h]ccwgroup-devicesah ]h"]1.3 ccwgroup devicesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h2. Channel pathsh]h2. Channel paths}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hXChannel paths show up, like subchannels, under the channel subsystem root (css0) and are called 'chp0.'. They have no driver and do not belong to any bus. Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect only the logical state and not the physical state, since we cannot track the latter consistently due to lacking machine support (we don't need to be aware of it anyway).h]hXChannel paths show up, like subchannels, under the channel subsystem root (css0) and are called ‘chp0.’. They have no driver and do not belong to any bus. Please note, that unlike /proc/chpids in 2.4, the channel path objects reflect only the logical state and not the physical state, since we cannot track the latter consistently due to lacking machine support (we don’t need to be aware of it anyway).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj1)}(hhh](j6)}(hX\status - Can be 'online' or 'offline'. Piping 'on' or 'off' sets the chpid logically online/offline. Piping 'on' to an online chpid triggers path reprobing for all devices the chpid connects to. This can be used to force the kernel to re-use a channel path the user knows to be online, but the machine hasn't created a machine check for. h](j<)}(hstatush]hstatus}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhMhjubjL)}(hhh]j)}(hhh]j)}(hXICan be 'online' or 'offline'. Piping 'on' or 'off' sets the chpid logically online/offline. Piping 'on' to an online chpid triggers path reprobing for all devices the chpid connects to. This can be used to force the kernel to re-use a channel path the user knows to be online, but the machine hasn't created a machine check for. h]h)}(hXHCan be 'online' or 'offline'. Piping 'on' or 'off' sets the chpid logically online/offline. Piping 'on' to an online chpid triggers path reprobing for all devices the chpid connects to. This can be used to force the kernel to re-use a channel path the user knows to be online, but the machine hasn't created a machine check for.h]hX^Can be ‘online’ or ‘offline’. Piping ‘on’ or ‘off’ sets the chpid logically online/offline. Piping ‘on’ to an online chpid triggers path reprobing for all devices the chpid connects to. This can be used to force the kernel to re-use a channel path the user knows to be online, but the machine hasn’t created a machine check for.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]jjuh1jhhhMhjubah}(h]h ]h"]h$]h&]uh1jKhjubeh}(h]h ]h"]h$]h&]uh1j5hhhMhjubj6)}(h.type - The physical type of the channel path. h](j<)}(htypeh]htype}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhMhj% ubjL)}(hhh]j)}(hhh]j)}(h'The physical type of the channel path. h]h)}(h&The physical type of the channel path.h]h&The physical type of the channel path.}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj= ubah}(h]h ]h"]h$]h&]uh1jhj: ubah}(h]h ]h"]h$]h&]jjuh1jhhhMhj7 ubah}(h]h ]h"]h$]h&]uh1jKhj% ubeh}(h]h ]h"]h$]h&]uh1j5hhhMhjhhubj6)}(h-shared - Whether the channel path is shared. h](j<)}(hsharedh]hshared}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhM"hjg ubjL)}(hhh]j)}(hhh]j)}(h$Whether the channel path is shared. h]h)}(h#Whether the channel path is shared.h]h#Whether the channel path is shared.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hj ubah}(h]h ]h"]h$]h&]uh1jhj| ubah}(h]h ]h"]h$]h&]jjuh1jhhhM"hjy ubah}(h]h ]h"]h$]h&]uh1jKhjg ubeh}(h]h ]h"]h$]h&]uh1j5hhhM"hjhhubj6)}(h%cmg - The channel measurement group. h](j<)}(hcmgh]hcmg}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhM%hj ubjL)}(hhh]j)}(hhh]j)}(hThe channel measurement group. h]h)}(hThe channel measurement group.h]hThe channel measurement group.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM%hj ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]jjuh1jhhhM%hj ubah}(h]h ]h"]h$]h&]uh1jKhj ubeh}(h]h ]h"]h$]h&]uh1j5hhhM%hjhhubeh}(h]h ]h"]h$]h&]uh1j0hjhhhNhNubeh}(h] channel-pathsah ]h"]2. channel pathsah$]h&]uh1hhhhhhhhM ubh)}(hhh]h)}(h3. System devicesh]h3. System devices}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM(ubah}(h]system-devicesah ]h"]3. system devicesah$]h&]uh1hhhhhhhhM(ubh)}(hhh](h)}(h 3.1 xpramh]h 3.1 xpram}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM+ubh)}(h0xpram shows up under devices/system/ as 'xpram'.h]h4xpram shows up under devices/system/ as ‘xpram’.}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hj hhubeh}(h]xpramah ]h"] 3.1 xpramah$]h&]uh1hhhhhhhhM+ubh)}(hhh](h)}(h3.2 cpush]h3.2 cpus}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj9 hhhhhM0ubh)}(hwFor each cpu, a directory is created under devices/system/cpu/. Each cpu has an attribute 'online' which can be 0 or 1.h]h{For each cpu, a directory is created under devices/system/cpu/. Each cpu has an attribute ‘online’ which can be 0 or 1.}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hj9 hhubeh}(h]cpusah ]h"]3.2 cpusah$]h&]uh1hhhhhhhhM0ubh)}(hhh]h)}(h4. Other devicesh]h4. Other devices}(hjc hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj` hhhhhM7ubah}(h] other-devicesah ]h"]4. other devicesah$]h&]uh1hhhhhhhhM7ubh)}(hhh](h)}(h 4.1 Netiucvh]h 4.1 Netiucv}(hj| hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjy hhhhhM:ubh)}(hThe netiucv driver creates an attribute 'connection' under bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv connection to the specified host.h]hThe netiucv driver creates an attribute ‘connection’ under bus/iucv/drivers/netiucv. Piping to this attribute creates a new netiucv connection to the specified host.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM<hjy hhubh)}(hNetiucv connections show up under devices/iucv/ as "netiucv". The interface number is assigned sequentially to the connections defined via the 'connection' attribute.h]hNetiucv connections show up under devices/iucv/ as “netiucv”. The interface number is assigned sequentially to the connections defined via the ‘connection’ attribute.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hjy hhubj1)}(hhh](j6)}(h%user - shows the connection partner. h](j<)}(huserh]huser}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhMEhj ubjL)}(hhh]j)}(hhh]j)}(hshows the connection partner. h]h)}(hshows the connection partner.h]hshows the connection partner.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhj ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]jjuh1jhhhMEhj ubah}(h]h ]h"]h$]h&]uh1jKhj ubeh}(h]h ]h"]h$]h&]uh1j5hhhMEhj ubj6)}(h?buffer - maximum buffer size. Pipe to it to change buffer size.h](j<)}(hbufferh]hbuffer}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j;hhhMGhj ubjL)}(hhh]j)}(hhh]j)}(h6maximum buffer size. Pipe to it to change buffer size.h]h)}(hj h]h6maximum buffer size. Pipe to it to change buffer size.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhj ubah}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]jjuh1jhhhMHhj ubah}(h]h ]h"]h$]h&]uh1jKhj ubeh}(h]h ]h"]h$]h&]uh1j5hhhMGhj hhubeh}(h]h ]h"]h$]h&]uh1j0hjy hhhNhNubeh}(h]netiucvah ]h"] 4.1 netiucvah$]h&]uh1hhhhhhhhM:ubeh}(h]s-390-driver-model-interfacesah ]h"]s/390 driver model interfacesah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerje error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j? j< jjjjj_j\jjj j j j j6 j3 j] jZ jv js j7 j4 u nametypes}(j? jjj_jj j j6 j] jv j7 uh}(j< hjhjjj\jjjbj jj j j3 j jZ j9 js j` j4 jy u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.