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

[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);
} }
......
...@@ -25,6 +25,16 @@ ...@@ -25,6 +25,16 @@
#include "device.h" #include "device.h"
#include "chp.h" #include "chp.h"
/**
* ccw_device_set_options_mask() - set some options and unset the rest
* @cdev: device for which the options are to be set
* @flags: options to be set
*
* All flags specified in @flags are set, all flags not specified in @flags
* are cleared.
* Returns:
* %0 on success, -%EINVAL on an invalid flag combination.
*/
int ccw_device_set_options_mask(struct ccw_device *cdev, unsigned long flags) int ccw_device_set_options_mask(struct ccw_device *cdev, unsigned long flags)
{ {
/* /*
...@@ -40,6 +50,15 @@ int ccw_device_set_options_mask(struct ccw_device *cdev, unsigned long flags) ...@@ -40,6 +50,15 @@ int ccw_device_set_options_mask(struct ccw_device *cdev, unsigned long flags)
return 0; return 0;
} }
/**
* ccw_device_set_options() - set some options
* @cdev: device for which the options are to be set
* @flags: options to be set
*
* All flags specified in @flags are set, the remainder is left untouched.
* Returns:
* %0 on success, -%EINVAL if an invalid flag combination would ensue.
*/
int ccw_device_set_options(struct ccw_device *cdev, unsigned long flags) int ccw_device_set_options(struct ccw_device *cdev, unsigned long flags)
{ {
/* /*
...@@ -59,6 +78,13 @@ int ccw_device_set_options(struct ccw_device *cdev, unsigned long flags) ...@@ -59,6 +78,13 @@ int ccw_device_set_options(struct ccw_device *cdev, unsigned long flags)
return 0; return 0;
} }
/**
* ccw_device_clear_options() - clear some options
* @cdev: device for which the options are to be cleared
* @flags: options to be cleared
*
* All flags specified in @flags are cleared, the remainder is left untouched.
*/
void ccw_device_clear_options(struct ccw_device *cdev, unsigned long flags) void ccw_device_clear_options(struct ccw_device *cdev, unsigned long flags)
{ {
cdev->private->options.fast &= (flags & CCWDEV_EARLY_NOTIFICATION) == 0; cdev->private->options.fast &= (flags & CCWDEV_EARLY_NOTIFICATION) == 0;
...@@ -67,8 +93,22 @@ void ccw_device_clear_options(struct ccw_device *cdev, unsigned long flags) ...@@ -67,8 +93,22 @@ void ccw_device_clear_options(struct ccw_device *cdev, unsigned long flags)
cdev->private->options.force &= (flags & CCWDEV_ALLOW_FORCE) == 0; cdev->private->options.force &= (flags & CCWDEV_ALLOW_FORCE) == 0;
} }
int /**
ccw_device_clear(struct ccw_device *cdev, unsigned long intparm) * ccw_device_clear() - terminate I/O request processing
* @cdev: target ccw device
* @intparm: interruption parameter; value is only used if no I/O is
* outstanding, otherwise the intparm associated with the I/O request
* is returned
*
* ccw_device_clear() calls csch on @cdev's subchannel.
* Returns:
* %0 on success,
* -%ENODEV on device not operational,
* -%EINVAL on invalid device state.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm)
{ {
struct subchannel *sch; struct subchannel *sch;
int ret; int ret;
...@@ -89,10 +129,33 @@ ccw_device_clear(struct ccw_device *cdev, unsigned long intparm) ...@@ -89,10 +129,33 @@ ccw_device_clear(struct ccw_device *cdev, unsigned long intparm)
return ret; return ret;
} }
int /**
ccw_device_start_key(struct ccw_device *cdev, struct ccw1 *cpa, * ccw_device_start_key() - start a s390 channel program with key
unsigned long intparm, __u8 lpm, __u8 key, * @cdev: target ccw device
unsigned long flags) * @cpa: logical start address of channel program
* @intparm: user specific interruption parameter; will be presented back to
* @cdev's interrupt handler. Allows a device driver to associate
* the interrupt with a particular I/O request.
* @lpm: defines the channel path to be used for a specific I/O request. A
* value of 0 will make cio use the opm.
* @key: storage key to be used for the I/O
* @flags: additional flags; defines the action to be performed for I/O
* processing.
*
* 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).
* Returns:
* %0, if the operation was successful;
* -%EBUSY, if the device is busy, or status pending;
* -%EACCES, if no path specified in @lpm is operational;
* -%ENODEV, if the device is not operational.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_start_key(struct ccw_device *cdev, struct ccw1 *cpa,
unsigned long intparm, __u8 lpm, __u8 key,
unsigned long flags)
{ {
struct subchannel *sch; struct subchannel *sch;
int ret; int ret;
...@@ -135,11 +198,38 @@ ccw_device_start_key(struct ccw_device *cdev, struct ccw1 *cpa, ...@@ -135,11 +198,38 @@ ccw_device_start_key(struct ccw_device *cdev, struct ccw1 *cpa,
return ret; return ret;
} }
/**
int * ccw_device_start_timeout_key() - start a s390 channel program with timeout and key
ccw_device_start_timeout_key(struct ccw_device *cdev, struct ccw1 *cpa, * @cdev: target ccw device
unsigned long intparm, __u8 lpm, __u8 key, * @cpa: logical start address of channel program
unsigned long flags, int expires) * @intparm: user specific interruption parameter; will be presented back to
* @cdev's interrupt handler. Allows a device driver to associate
* the interrupt with a particular I/O request.
* @lpm: defines the channel path to be used for a specific I/O request. A
* value of 0 will make cio use the opm.
* @key: storage key to be used for the I/O
* @flags: additional flags; defines the action to be performed for I/O
* processing.
* @expires: timeout value in jiffies
*
* 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).
* This function notifies the device driver if the channel program has not
* completed during the time specified by @expires. If a timeout occurs, the
* channel program is terminated via xsch, hsch or csch, and the device's
* interrupt handler will be called with an irb containing ERR_PTR(-%ETIMEDOUT).
* Returns:
* %0, if the operation was successful;
* -%EBUSY, if the device is busy, or status pending;
* -%EACCES, if no path specified in @lpm is operational;
* -%ENODEV, if the device is not operational.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_start_timeout_key(struct ccw_device *cdev, struct ccw1 *cpa,
unsigned long intparm, __u8 lpm, __u8 key,
unsigned long flags, int expires)
{ {
int ret; int ret;
...@@ -152,18 +242,67 @@ ccw_device_start_timeout_key(struct ccw_device *cdev, struct ccw1 *cpa, ...@@ -152,18 +242,67 @@ ccw_device_start_timeout_key(struct ccw_device *cdev, struct ccw1 *cpa,
return ret; return ret;
} }
int /**
ccw_device_start(struct ccw_device *cdev, struct ccw1 *cpa, * ccw_device_start() - start a s390 channel program
unsigned long intparm, __u8 lpm, unsigned long flags) * @cdev: target ccw device
* @cpa: logical start address of channel program
* @intparm: user specific interruption parameter; will be presented back to
* @cdev's interrupt handler. Allows a device driver to associate
* the interrupt with a particular I/O request.
* @lpm: defines the channel path to be used for a specific I/O request. A
* value of 0 will make cio use the opm.
* @flags: additional flags; defines the action to be performed for I/O
* processing.
*
* 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).
* Returns:
* %0, if the operation was successful;
* -%EBUSY, if the device is busy, or status pending;
* -%EACCES, if no path specified in @lpm is operational;
* -%ENODEV, if the device is not operational.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_start(struct ccw_device *cdev, struct ccw1 *cpa,
unsigned long intparm, __u8 lpm, unsigned long flags)
{ {
return ccw_device_start_key(cdev, cpa, intparm, lpm, return ccw_device_start_key(cdev, cpa, intparm, lpm,
PAGE_DEFAULT_KEY, flags); PAGE_DEFAULT_KEY, flags);
} }
int /**
ccw_device_start_timeout(struct ccw_device *cdev, struct ccw1 *cpa, * ccw_device_start_timeout() - start a s390 channel program with timeout
unsigned long intparm, __u8 lpm, unsigned long flags, * @cdev: target ccw device
int expires) * @cpa: logical start address of channel program
* @intparm: user specific interruption parameter; will be presented back to
* @cdev's interrupt handler. Allows a device driver to associate
* the interrupt with a particular I/O request.
* @lpm: defines the channel path to be used for a specific I/O request. A
* value of 0 will make cio use the opm.
* @flags: additional flags; defines the action to be performed for I/O
* processing.
* @expires: timeout value in jiffies
*
* 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).
* This function notifies the device driver if the channel program has not
* completed during the time specified by @expires. If a timeout occurs, the
* channel program is terminated via xsch, hsch or csch, and the device's
* interrupt handler will be called with an irb containing ERR_PTR(-%ETIMEDOUT).
* Returns:
* %0, if the operation was successful;
* -%EBUSY, if the device is busy, or status pending;
* -%EACCES, if no path specified in @lpm is operational;
* -%ENODEV, if the device is not operational.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_start_timeout(struct ccw_device *cdev, struct ccw1 *cpa,
unsigned long intparm, __u8 lpm,
unsigned long flags, int expires)
{ {
return ccw_device_start_timeout_key(cdev, cpa, intparm, lpm, return ccw_device_start_timeout_key(cdev, cpa, intparm, lpm,
PAGE_DEFAULT_KEY, flags, PAGE_DEFAULT_KEY, flags,
...@@ -171,8 +310,23 @@ ccw_device_start_timeout(struct ccw_device *cdev, struct ccw1 *cpa, ...@@ -171,8 +310,23 @@ ccw_device_start_timeout(struct ccw_device *cdev, struct ccw1 *cpa,
} }
int /**
ccw_device_halt(struct ccw_device *cdev, unsigned long intparm) * ccw_device_halt() - halt I/O request processing
* @cdev: target ccw device
* @intparm: interruption parameter; value is only used if no I/O is
* outstanding, otherwise the intparm associated with the I/O request
* is returned
*
* ccw_device_halt() calls hsch on @cdev's subchannel.
* Returns:
* %0 on success,
* -%ENODEV on device not operational,
* -%EINVAL on invalid device state,
* -%EBUSY on device busy or interrupt pending.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_halt(struct ccw_device *cdev, unsigned long intparm)
{ {
struct subchannel *sch; struct subchannel *sch;
int ret; int ret;
...@@ -193,8 +347,20 @@ ccw_device_halt(struct ccw_device *cdev, unsigned long intparm) ...@@ -193,8 +347,20 @@ ccw_device_halt(struct ccw_device *cdev, unsigned long intparm)
return ret; return ret;
} }
int /**
ccw_device_resume(struct ccw_device *cdev) * ccw_device_resume() - resume channel program execution
* @cdev: target ccw device
*
* ccw_device_resume() calls rsch on @cdev's subchannel.
* Returns:
* %0 on success,
* -%ENODEV on device not operational,
* -%EINVAL on invalid device state,
* -%EBUSY on device busy or interrupt pending.
* Context:
* Interrupts disabled, ccw device lock held
*/
int ccw_device_resume(struct ccw_device *cdev)
{ {
struct subchannel *sch; struct subchannel *sch;
...@@ -260,11 +426,21 @@ ccw_device_call_handler(struct ccw_device *cdev) ...@@ -260,11 +426,21 @@ ccw_device_call_handler(struct ccw_device *cdev)
return 1; return 1;
} }
/* /**
* Search for CIW command in extended sense data. * ccw_device_get_ciw() - Search for CIW command in extended sense data.
* @cdev: ccw device to inspect
* @ct: command type to look for
*
* During SenseID, command information words (CIWs) describing special
* commands available to the device may have been stored in the extended
* sense data. This function searches for CIWs of a specified command
* type in the extended sense data.
* Returns:
* %NULL if no extended sense data has been stored or if no CIW of the
* specified command type could be found,
* else a pointer to the CIW of the specified command type.
*/ */
struct ciw * struct ciw *ccw_device_get_ciw(struct ccw_device *cdev, __u32 ct)
ccw_device_get_ciw(struct ccw_device *cdev, __u32 ct)
{ {
int ciw_cnt; int ciw_cnt;
...@@ -276,8 +452,14 @@ ccw_device_get_ciw(struct ccw_device *cdev, __u32 ct) ...@@ -276,8 +452,14 @@ ccw_device_get_ciw(struct ccw_device *cdev, __u32 ct)
return NULL; return NULL;
} }
__u8 /**
ccw_device_get_path_mask(struct ccw_device *cdev) * ccw_device_get_path_mask() - get currently available paths
* @cdev: ccw device to be queried
* Returns:
* %0 if no subchannel for the device is available,
* else the mask of currently available paths for the ccw device's subchannel.
*/
__u8 ccw_device_get_path_mask(struct ccw_device *cdev)
{ {
struct subchannel *sch; struct subchannel *sch;
...@@ -357,8 +539,7 @@ out_unlock: ...@@ -357,8 +539,7 @@ out_unlock:
return ret; return ret;
} }
void * void *ccw_device_get_chp_desc(struct ccw_device *cdev, int chp_no)
ccw_device_get_chp_desc(struct ccw_device *cdev, int chp_no)
{ {
struct subchannel *sch; struct subchannel *sch;
struct chp_id chpid; struct chp_id chpid;
......
...@@ -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 /**