Commit b2ffd8e9 authored by Cornelia Huck's avatar Cornelia Huck Committed by Martin Schwidefsky

[S390] cio: Add docbook comments.

Comment a bunch of function in docbook style and convert existing
comments on structures to docbook.
Signed-off-by: default avatarCornelia Huck <cornelia.huck@de.ibm.com>
Signed-off-by: default avatarMartin Schwidefsky <schwidefsky@de.ibm.com>
Signed-off-by: default avatarHeiko Carstens <heiko.carstens@de.ibm.com>
parent c0208716
...@@ -152,16 +152,24 @@ __ccwgroup_create_symlinks(struct ccwgroup_device *gdev) ...@@ -152,16 +152,24 @@ __ccwgroup_create_symlinks(struct ccwgroup_device *gdev)
return 0; return 0;
} }
/* /**
* try to add a new ccwgroup device for one driver * ccwgroup_create() - create and register a ccw group device
* argc and argv[] are a list of bus_id's of devices * @root: parent device for the new device
* belonging to the driver. * @creator_id: identifier of creating driver
* @cdrv: ccw driver of slave devices
* @argc: number of slave devices
* @argv: bus ids of slave devices
*
* Create and register a new ccw group device as a child of @root. Slave
* devices are obtained from the list of bus ids given in @argv[] and must all
* belong to @cdrv.
* Returns:
* %0 on success and an error code on failure.
* Context:
* non-atomic
*/ */
int int ccwgroup_create(struct device *root, unsigned int creator_id,
ccwgroup_create(struct device *root, struct ccw_driver *cdrv, int argc, char *argv[])
unsigned int creator_id,
struct ccw_driver *cdrv,
int argc, char *argv[])
{ {
struct ccwgroup_device *gdev; struct ccwgroup_device *gdev;
int i; int i;
...@@ -390,8 +398,13 @@ static struct bus_type ccwgroup_bus_type = { ...@@ -390,8 +398,13 @@ static struct bus_type ccwgroup_bus_type = {
.remove = ccwgroup_remove, .remove = ccwgroup_remove,
}; };
int /**
ccwgroup_driver_register (struct ccwgroup_driver *cdriver) * ccwgroup_driver_register() - register a ccw group driver
* @cdriver: driver to be registered
*
* This function is mainly a wrapper around driver_register().
*/
int ccwgroup_driver_register(struct ccwgroup_driver *cdriver)
{ {
/* register our new driver with the core */ /* register our new driver with the core */
cdriver->driver.bus = &ccwgroup_bus_type; cdriver->driver.bus = &ccwgroup_bus_type;
...@@ -406,8 +419,13 @@ __ccwgroup_match_all(struct device *dev, void *data) ...@@ -406,8 +419,13 @@ __ccwgroup_match_all(struct device *dev, void *data)
return 1; return 1;
} }
void /**
ccwgroup_driver_unregister (struct ccwgroup_driver *cdriver) * ccwgroup_driver_unregister() - deregister a ccw group driver
* @cdriver: driver to be deregistered
*
* This function is mainly a wrapper around driver_unregister().
*/
void ccwgroup_driver_unregister(struct ccwgroup_driver *cdriver)
{ {
struct device *dev; struct device *dev;
...@@ -427,8 +445,16 @@ ccwgroup_driver_unregister (struct ccwgroup_driver *cdriver) ...@@ -427,8 +445,16 @@ ccwgroup_driver_unregister (struct ccwgroup_driver *cdriver)
driver_unregister(&cdriver->driver); driver_unregister(&cdriver->driver);
} }
int /**
ccwgroup_probe_ccwdev(struct ccw_device *cdev) * ccwgroup_probe_ccwdev() - probe function for slave devices
* @cdev: ccw device to be probed
*
* This is a dummy probe function for ccw devices that are slave devices in
* a ccw group device.
* Returns:
* always %0
*/
int ccwgroup_probe_ccwdev(struct ccw_device *cdev)
{ {
return 0; return 0;
} }
...@@ -452,8 +478,15 @@ __ccwgroup_get_gdev_by_cdev(struct ccw_device *cdev) ...@@ -452,8 +478,15 @@ __ccwgroup_get_gdev_by_cdev(struct ccw_device *cdev)
return NULL; return NULL;
} }
void /**
ccwgroup_remove_ccwdev(struct ccw_device *cdev) * ccwgroup_remove_ccwdev() - remove function for slave devices
* @cdev: ccw device to be removed
*
* This is a remove function for ccw devices that are slave devices in a ccw
* group device. It sets the ccw device offline and also deregisters the
* embedding ccw group device.
*/
void ccwgroup_remove_ccwdev(struct ccw_device *cdev)
{ {
struct ccwgroup_device *gdev; struct ccwgroup_device *gdev;
......
...@@ -357,8 +357,18 @@ ccw_device_remove_disconnected(struct ccw_device *cdev) ...@@ -357,8 +357,18 @@ ccw_device_remove_disconnected(struct ccw_device *cdev)
cdev->private->dev_id.devno); cdev->private->dev_id.devno);
} }
int /**
ccw_device_set_offline(struct ccw_device *cdev) * ccw_device_set_offline() - disable a ccw device for I/O
* @cdev: target ccw device
*
* This function calls the driver's set_offline() function for @cdev, if
* given, and then disables @cdev.
* Returns:
* %0 on success and a negative error value on failure.
* Context:
* enabled, ccw device lock not held
*/
int ccw_device_set_offline(struct ccw_device *cdev)
{ {
int ret; int ret;
...@@ -396,8 +406,19 @@ ccw_device_set_offline(struct ccw_device *cdev) ...@@ -396,8 +406,19 @@ ccw_device_set_offline(struct ccw_device *cdev)
return ret; return ret;
} }
int /**
ccw_device_set_online(struct ccw_device *cdev) * ccw_device_set_online() - enable a ccw device for I/O
* @cdev: target ccw device
*
* This function first enables @cdev and then calls the driver's set_online()
* function for @cdev, if given. If set_online() returns an error, @cdev is
* disabled again.
* Returns:
* %0 on success and a negative error value on failure.
* Context:
* enabled, ccw device lock not held
*/
int ccw_device_set_online(struct ccw_device *cdev)
{ {
int ret; int ret;
...@@ -1326,8 +1347,19 @@ __ccwdev_check_busid(struct device *dev, void *id) ...@@ -1326,8 +1347,19 @@ __ccwdev_check_busid(struct device *dev, void *id)
} }
struct ccw_device * /**
get_ccwdev_by_busid(struct ccw_driver *cdrv, const char *bus_id) * get_ccwdev_by_busid() - obtain device from a bus id
* @cdrv: driver the device is owned by
* @bus_id: bus id of the device to be searched
*
* This function searches all devices owned by @cdrv for a device with a bus
* id matching @bus_id.
* Returns:
* If a match is found, its reference count of the found device is increased
* and it is returned; else %NULL is returned.
*/
struct ccw_device *get_ccwdev_by_busid(struct ccw_driver *cdrv,
const char *bus_id)
{ {
struct device *dev; struct device *dev;
struct device_driver *drv; struct device_driver *drv;
...@@ -1409,8 +1441,15 @@ struct bus_type ccw_bus_type = { ...@@ -1409,8 +1441,15 @@ struct bus_type ccw_bus_type = {
.remove = ccw_device_remove, .remove = ccw_device_remove,
}; };
int /**
ccw_driver_register (struct ccw_driver *cdriver) * ccw_driver_register() - register a ccw driver
* @cdriver: driver to be registered
*
* This function is mainly a wrapper around driver_register().
* Returns:
* %0 on success and a negative error value on failure.
*/
int ccw_driver_register(struct ccw_driver *cdriver)
{ {
struct device_driver *drv = &cdriver->driver; struct device_driver *drv = &cdriver->driver;
...@@ -1420,8 +1459,13 @@ ccw_driver_register (struct ccw_driver *cdriver) ...@@ -1420,8 +1459,13 @@ ccw_driver_register (struct ccw_driver *cdriver)
return driver_register(drv); return driver_register(drv);
} }
void /**
ccw_driver_unregister (struct ccw_driver *cdriver) * ccw_driver_unregister() - deregister a ccw driver
* @cdriver: driver to be deregistered
*
* This function is mainly a wrapper around driver_unregister().
*/
void ccw_driver_unregister(struct ccw_driver *cdriver)
{ {
driver_unregister(&cdriver->driver); driver_unregister(&cdriver->driver);
} }
......
This diff is collapsed.
...@@ -67,36 +67,53 @@ ccw_device_id_match(const struct ccw_device_id *array, ...@@ -67,36 +67,53 @@ ccw_device_id_match(const struct ccw_device_id *array,
return NULL; return NULL;
} }
/* The struct ccw device is our replacement for the globally accessible /**
* ioinfo array. ioinfo will mutate into a subchannel device later. * struct ccw_device - channel attached device
* @ccwlock: pointer to device lock
* @id: id of this device
* @drv: ccw driver for this device
* @dev: embedded device structure
* @online: online status of device
* @handler: interrupt handler
* *
* Reference: Documentation/s390/driver-model.txt */ * @handler is a member of the device rather than the driver since a driver
* can have different interrupt handlers for different ccw devices
* (multi-subchannel drivers).
*/
struct ccw_device { struct ccw_device {
spinlock_t *ccwlock; spinlock_t *ccwlock;
/* private: */
struct ccw_device_private *private; /* cio private information */ struct ccw_device_private *private; /* cio private information */
struct ccw_device_id id; /* id of this device, driver_info is /* public: */
set by ccw_find_driver */ struct ccw_device_id id;
struct ccw_driver *drv; /* */ struct ccw_driver *drv;
struct device dev; /* */ struct device dev;
int online; int online;
/* This is sick, but a driver can have different interrupt handlers
for different ccw_devices (multi-subchannel drivers)... */
void (*handler) (struct ccw_device *, unsigned long, struct irb *); void (*handler) (struct ccw_device *, unsigned long, struct irb *);
}; };
/* Each ccw driver registers with the ccw root bus */ /**
* struct ccw driver - device driver for channel attached devices
* @owner: owning module
* @ids: ids supported by this driver
* @probe: function called on probe
* @remove: function called on remove
* @set_online: called when setting device online
* @set_offline: called when setting device offline
* @notify: notify driver of device state changes
* @driver: embedded device driver structure
* @name: device driver name
*/
struct ccw_driver { struct ccw_driver {
struct module *owner; /* for automatic MOD_INC_USE_COUNT */ struct module *owner;
struct ccw_device_id *ids; /* probe driver with these devs */ struct ccw_device_id *ids;
int (*probe) (struct ccw_device *); /* ask driver to probe dev */ int (*probe) (struct ccw_device *);
void (*remove) (struct ccw_device *); void (*remove) (struct ccw_device *);
/* device is no longer available */
int (*set_online) (struct ccw_device *); int (*set_online) (struct ccw_device *);
int (*set_offline) (struct ccw_device *); int (*set_offline) (struct ccw_device *);
int (*notify) (struct ccw_device *, int); int (*notify) (struct ccw_device *, int);
struct device_driver driver; /* higher level structure, don't init struct device_driver driver;
this from your driver */
char *name; char *name;
}; };
...@@ -124,36 +141,10 @@ extern void ccw_device_clear_options(struct ccw_device *, unsigned long); ...@@ -124,36 +141,10 @@ extern void ccw_device_clear_options(struct ccw_device *, unsigned long);
/* Allow forced onlining of boxed devices. */ /* Allow forced onlining of boxed devices. */
#define CCWDEV_ALLOW_FORCE 0x0008 #define CCWDEV_ALLOW_FORCE 0x0008
/*
* ccw_device_start()
*
* Start a S/390 channel program. When the interrupt arrives, the
* IRQ handler is called, either immediately, delayed (dev-end missing,
* or sense required) or never (no IRQ handler registered).
* Depending on the action taken, ccw_device_start() returns:
* 0 - Success
* -EBUSY - Device busy, or status pending
* -ENODEV - Device not operational
* -EINVAL - Device invalid for operation
*/
extern int ccw_device_start(struct ccw_device *, struct ccw1 *, extern int ccw_device_start(struct ccw_device *, struct ccw1 *,
unsigned long, __u8, unsigned long); unsigned long, __u8, unsigned long);
/*
* ccw_device_start_timeout()
*
* This function notifies the device driver if the channel program has not
* completed during the specified time. If a timeout occurs, the channel
* program is terminated via xsch(), hsch() or csch().
*/
extern int ccw_device_start_timeout(struct ccw_device *, struct ccw1 *, extern int ccw_device_start_timeout(struct ccw_device *, struct ccw1 *,
unsigned long, __u8, unsigned long, int); unsigned long, __u8, unsigned long, int);
/*
* ccw_device_start_key()
* ccw_device_start_key_timeout()
*
* Same as ccw_device_start() and ccw_device_start_timeout(), except a
* storage key != default key can be provided for the I/O.
*/
extern int ccw_device_start_key(struct ccw_device *, struct ccw1 *, extern int ccw_device_start_key(struct ccw_device *, struct ccw1 *,
unsigned long, __u8, __u8, unsigned long); unsigned long, __u8, __u8, unsigned long);
extern int ccw_device_start_timeout_key(struct ccw_device *, struct ccw1 *, extern int ccw_device_start_timeout_key(struct ccw_device *, struct ccw1 *,
......
...@@ -4,19 +4,41 @@ ...@@ -4,19 +4,41 @@
struct ccw_device; struct ccw_device;
struct ccw_driver; struct ccw_driver;
/**
* struct ccwgroup_device - ccw group device
* @creator_id: unique number of the driver
* @state: online/offline state
* @count: number of attached slave devices
* @dev: embedded device structure
* @cdev: variable number of slave devices, allocated as needed
*/
struct ccwgroup_device { struct ccwgroup_device {
unsigned long creator_id; /* unique number of the driver */ unsigned long creator_id;
enum { enum {
CCWGROUP_OFFLINE, CCWGROUP_OFFLINE,
CCWGROUP_ONLINE, CCWGROUP_ONLINE,
} state; } state;
/* private: */
atomic_t onoff; atomic_t onoff;
struct mutex reg_mutex; struct mutex reg_mutex;
unsigned int count; /* number of attached slave devices */ /* public: */
struct device dev; /* master device */ unsigned int count;
struct ccw_device *cdev[0]; /* variable number, allocate as needed */ struct device dev;
struct ccw_device *cdev[0];
}; };
/**
* struct ccwgroup_driver - driver for ccw group devices
* @owner: driver owner
* @name: driver name
* @max_slaves: maximum number of slave devices
* @driver_id: unique id
* @probe: function called on probe
* @remove: function called on remove
* @set_online: function called when device is set online
* @set_offline: function called when device is set offline
* @driver: embedded driver structure
*/
struct ccwgroup_driver { struct ccwgroup_driver {
struct module *owner; struct module *owner;
char *name; char *name;
...@@ -28,7 +50,7 @@ struct ccwgroup_driver { ...@@ -28,7 +50,7 @@ struct ccwgroup_driver {
int (*set_online) (struct ccwgroup_device *); int (*set_online) (struct ccwgroup_device *);
int (*set_offline) (struct ccwgroup_device *); int (*set_offline) (struct ccwgroup_device *);
struct device_driver driver; /* this driver */ struct device_driver driver;
}; };
extern int ccwgroup_driver_register (struct ccwgroup_driver *cdriver); extern int ccwgroup_driver_register (struct ccwgroup_driver *cdriver);
......
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment