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

[S390] cio: Kerneldoc comments for cmf.

- Fix existing kerneldoc-style comments.
- Move descriptions of functions from cmb.h to cmf.c.
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 fc5019c5
...@@ -77,16 +77,17 @@ enum cmb_index { ...@@ -77,16 +77,17 @@ enum cmb_index {
* by all machines that we run on * by all machines that we run on
* @CMF_EXTENDED: improved format that was introduced with the z990 * @CMF_EXTENDED: improved format that was introduced with the z990
* machine * machine
* @CMF_AUTODETECT: default: use extended format when running on a z990 * @CMF_AUTODETECT: default: use extended format when running on a machine
* or later machine, otherwise fall back to basic format * supporting extended format, otherwise fall back to
**/ * basic format
*/
enum cmb_format { enum cmb_format {
CMF_BASIC, CMF_BASIC,
CMF_EXTENDED, CMF_EXTENDED,
CMF_AUTODETECT = -1, CMF_AUTODETECT = -1,
}; };
/** /*
* format - actual format for all measurement blocks * format - actual format for all measurement blocks
* *
* The format module parameter can be set to a value of 0 (zero) * The format module parameter can be set to a value of 0 (zero)
...@@ -107,6 +108,7 @@ module_param(format, bool, 0444); ...@@ -107,6 +108,7 @@ module_param(format, bool, 0444);
* either with the help of a special pool or with kmalloc * either with the help of a special pool or with kmalloc
* @free: free memory allocated with @alloc * @free: free memory allocated with @alloc
* @set: enable or disable measurement * @set: enable or disable measurement
* @read: read a measurement entry at an index
* @readall: read a measurement block in a common format * @readall: read a measurement block in a common format
* @reset: clear the data in the associated measurement block and * @reset: clear the data in the associated measurement block and
* reset its time stamp * reset its time stamp
...@@ -120,7 +122,7 @@ struct cmb_operations { ...@@ -120,7 +122,7 @@ struct cmb_operations {
int (*readall)(struct ccw_device *, struct cmbdata *); int (*readall)(struct ccw_device *, struct cmbdata *);
void (*reset) (struct ccw_device *); void (*reset) (struct ccw_device *);
void *(*align) (void *); void *(*align) (void *);
/* private: */
struct attribute_group *attr_group; struct attribute_group *attr_group;
}; };
static struct cmb_operations *cmbops; static struct cmb_operations *cmbops;
...@@ -471,6 +473,7 @@ static void cmf_generic_reset(struct ccw_device *cdev) ...@@ -471,6 +473,7 @@ static void cmf_generic_reset(struct ccw_device *cdev)
* *
* @mem: pointer to CMBs (only in basic measurement mode) * @mem: pointer to CMBs (only in basic measurement mode)
* @list: contains a linked list of all subchannels * @list: contains a linked list of all subchannels
* @num_channels: number of channels to be measured
* @lock: protect concurrent access to @mem and @list * @lock: protect concurrent access to @mem and @list
*/ */
struct cmb_area { struct cmb_area {
...@@ -503,10 +506,20 @@ module_param_named(maxchannels, cmb_area.num_channels, uint, 0444); ...@@ -503,10 +506,20 @@ module_param_named(maxchannels, cmb_area.num_channels, uint, 0444);
/** /**
* struct cmb - basic channel measurement block * struct cmb - basic channel measurement block
* @ssch_rsch_count: number of ssch and rsch
* @sample_count: number of samples
* @device_connect_time: time of device connect
* @function_pending_time: time of function pending
* @device_disconnect_time: time of device disconnect
* @control_unit_queuing_time: time of control unit queuing
* @device_active_only_time: time of device active only
* @reserved: unused in basic measurement mode
*
* The measurement block as used by the hardware. The fields are described
* further in z/Architecture Principles of Operation, chapter 17.
* *
* cmb as used by the hardware the fields are described in z/Architecture * The cmb area made up from these blocks must be a contiguous array and may
* Principles of Operation, chapter 17. * not be reallocated or freed.
* The area to be a contiguous array and may not be reallocated or freed.
* Only one cmb area can be present in the system. * Only one cmb area can be present in the system.
*/ */
struct cmb { struct cmb {
...@@ -804,9 +817,20 @@ static struct cmb_operations cmbops_basic = { ...@@ -804,9 +817,20 @@ static struct cmb_operations cmbops_basic = {
/** /**
* struct cmbe - extended channel measurement block * struct cmbe - extended channel measurement block
* @ssch_rsch_count: number of ssch and rsch
* @sample_count: number of samples
* @device_connect_time: time of device connect
* @function_pending_time: time of function pending
* @device_disconnect_time: time of device disconnect
* @control_unit_queuing_time: time of control unit queuing
* @device_active_only_time: time of device active only
* @device_busy_time: time of device busy
* @initial_command_response_time: initial command response time
* @reserved: unused
* *
* cmb as used by the hardware, may be in any 64 bit physical location, * The measurement block as used by the hardware. May be in any 64 bit physical
* the fields are described in z/Architecture Principles of Operation, * location.
* The fields are described further in z/Architecture Principles of Operation,
* third edition, chapter 17. * third edition, chapter 17.
*/ */
struct cmbe { struct cmbe {
...@@ -1218,7 +1242,15 @@ static ssize_t cmb_enable_store(struct device *dev, ...@@ -1218,7 +1242,15 @@ static ssize_t cmb_enable_store(struct device *dev,
DEVICE_ATTR(cmb_enable, 0644, cmb_enable_show, cmb_enable_store); DEVICE_ATTR(cmb_enable, 0644, cmb_enable_show, cmb_enable_store);
/* enable_cmf/disable_cmf: module interface for cmf (de)activation */ /**
* enable_cmf() - switch on the channel measurement for a specific device
* @cdev: The ccw device to be enabled
*
* Returns %0 for success or a negative error value.
*
* Context:
* non-atomic
*/
int enable_cmf(struct ccw_device *cdev) int enable_cmf(struct ccw_device *cdev)
{ {
int ret; int ret;
...@@ -1240,6 +1272,15 @@ int enable_cmf(struct ccw_device *cdev) ...@@ -1240,6 +1272,15 @@ int enable_cmf(struct ccw_device *cdev)
return ret; return ret;
} }
/**
* disable_cmf() - switch off the channel measurement for a specific device
* @cdev: The ccw device to be disabled
*
* Returns %0 for success or a negative error value.
*
* Context:
* non-atomic
*/
int disable_cmf(struct ccw_device *cdev) int disable_cmf(struct ccw_device *cdev)
{ {
int ret; int ret;
...@@ -1252,11 +1293,31 @@ int disable_cmf(struct ccw_device *cdev) ...@@ -1252,11 +1293,31 @@ int disable_cmf(struct ccw_device *cdev)
return ret; return ret;
} }
/**
* cmf_read() - read one value from the current channel measurement block
* @cdev: the channel to be read
* @index: the index of the value to be read
*
* Returns the value read or %0 if the value cannot be read.
*
* Context:
* any
*/
u64 cmf_read(struct ccw_device *cdev, int index) u64 cmf_read(struct ccw_device *cdev, int index)
{ {
return cmbops->read(cdev, index); return cmbops->read(cdev, index);
} }
/**
* cmf_readall() - read the current channel measurement block
* @cdev: the channel to be read
* @data: a pointer to a data block that will be filled
*
* Returns %0 on success, a negative error value otherwise.
*
* Context:
* any
*/
int cmf_readall(struct ccw_device *cdev, struct cmbdata *data) int cmf_readall(struct ccw_device *cdev, struct cmbdata *data)
{ {
return cmbops->readall(cdev, data); return cmbops->readall(cdev, data);
......
#ifndef S390_CMB_H #ifndef S390_CMB_H
#define S390_CMB_H #define S390_CMB_H
/** /**
* struct cmbdata -- channel measurement block data for user space * struct cmbdata - channel measurement block data for user space
*
* @size: size of the stored data * @size: size of the stored data
* @ssch_rsch_count: XXX * @elapsed_time: time since last sampling
* @sample_count: * @ssch_rsch_count: number of ssch and rsch
* @device_connect_time: * @sample_count: number of samples
* @function_pending_time: * @device_connect_time: time of device connect
* @device_disconnect_time: * @function_pending_time: time of function pending
* @control_unit_queuing_time: * @device_disconnect_time: time of device disconnect
* @device_active_only_time: * @control_unit_queuing_time: time of control unit queuing
* @device_busy_time: * @device_active_only_time: time of device active only
* @initial_command_response_time: * @device_busy_time: time of device busy (ext. format)
* @initial_command_response_time: initial command response time (ext. format)
* *
* all values are stored as 64 bit for simplicity, especially * All values are stored as 64 bit for simplicity, especially
* in 32 bit emulation mode. All time values are normalized to * in 32 bit emulation mode. All time values are normalized to
* nanoseconds. * nanoseconds.
* Currently, two formats are known, which differ by the size of * Currently, two formats are known, which differ by the size of
* this structure, i.e. the last two members are only set when * this structure, i.e. the last two members are only set when
* the extended channel measurement facility (first shipped in * the extended channel measurement facility (first shipped in
* z990 machines) is activated. * z990 machines) is activated.
* Potentially, more fields could be added, which results in a * Potentially, more fields could be added, which would result in a
* new ioctl number. * new ioctl number.
**/ */
struct cmbdata { struct cmbdata {
__u64 size; __u64 size;
__u64 elapsed_time; __u64 elapsed_time;
...@@ -49,44 +49,9 @@ struct cmbdata { ...@@ -49,44 +49,9 @@ struct cmbdata {
#ifdef __KERNEL__ #ifdef __KERNEL__
struct ccw_device; struct ccw_device;
/**
* enable_cmf() - switch on the channel measurement for a specific device
* @cdev: The ccw device to be enabled
* returns 0 for success or a negative error value.
*
* Context:
* non-atomic
**/
extern int enable_cmf(struct ccw_device *cdev); extern int enable_cmf(struct ccw_device *cdev);
/**
* disable_cmf() - switch off the channel measurement for a specific device
* @cdev: The ccw device to be disabled
* returns 0 for success or a negative error value.
*
* Context:
* non-atomic
**/
extern int disable_cmf(struct ccw_device *cdev); extern int disable_cmf(struct ccw_device *cdev);
/**
* cmf_read() - read one value from the current channel measurement block
* @cmf: the channel to be read
* @index: the name of the value that is read
*
* Context:
* any
**/
extern u64 cmf_read(struct ccw_device *cdev, int index); extern u64 cmf_read(struct ccw_device *cdev, int index);
/**
* cmf_readall() - read one value from the current channel measurement block
* @cmf: the channel to be read
* @data: a pointer to a data block that will be filled
*
* Context:
* any
**/
extern int cmf_readall(struct ccw_device *cdev, struct cmbdata *data); extern int cmf_readall(struct ccw_device *cdev, struct cmbdata *data);
#endif /* __KERNEL__ */ #endif /* __KERNEL__ */
......
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