Commit 9fc1427a authored by Cornelia Huck's avatar Cornelia Huck Committed by Linus Torvalds
Browse files

[PATCH] s390: cio documentation 



Synchronize documentation with current interface.

Signed-off-by: default avatarMartin Schwidefsky <schwidefsky@de.ibm.com>
Signed-off-by: default avatarAndrew Morton <akpm@osdl.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@osdl.org>
parent af6c8eed

Documentation/s390/cds.txt

+41 −4
Original line number Diff line number Diff line
@@ -56,12 +56,16 @@ read_dev_chars() 
   read device characteristics

   

read_conf_data()

read_conf_data_lpm()

   read configuration data.



ccw_device_get_ciw()

   get commands from extended sense data.



ccw_device_start()	

ccw_device_start_timeout()

ccw_device_start_key()

ccw_device_start_key_timeout()

   initiate an I/O request.



ccw_device_resume()
@@ -197,19 +201,21 @@ The read_dev_chars() function returns : 
          operational.





read_conf_data() - Read Configuration Data

read_conf_data(), read_conf_data_lpm() - Read Configuration Data



Retrieve the device dependent configuration data. Please have a look at your 

device dependent I/O commands for the device specific layout of the node 

descriptor elements. 

descriptor elements. read_conf_data_lpm() will retrieve the configuration data

for a specific path.



The function is meant to be called with an irq handler in place; that is,

The function is meant to be called with the device already enabled; that is,

at earliest during set_online() processing.



The function may be called enabled or disabled, but the device must not be

locked



int read_conf_data(struct ccw_device, void **buffer, int *length, __u8 lpm);

int read_conf_data(struct ccw_device, void **buffer, int *length);

int read_conf_data_lpm(struct ccw_device, void **buffer, int *length, __u8 lpm);



cdev   - the ccw_device the data is requested for.

buffer - Pointer to a buffer pointer. The read_conf_data() routine
@@ -263,6 +269,25 @@ int ccw_device_start(struct ccw_device *cdev, 
		     unsigned long intparm,

		     __u8 lpm,

		     unsigned long flags);

int ccw_device_start_timeout(struct ccw_device *cdev,

			     struct ccw1 *cpa,

			     unsigned long intparm,

			     __u8 lpm,

			     unsigned long flags,

			     int expires);

int ccw_device_start_key(struct ccw_device *cdev,

			 struct ccw1 *cpa,

			 unsigned long intparm,

			 __u8 lpm,

			 __u8 key,

			 unsigned long flags);

int ccw_device_start_key_timeout(struct ccw_device *cdev,

				 struct ccw1 *cpa,

				 unsigned long intparm,

				 __u8 lpm,

				 __u8 key,

				 unsigned long flags,

				 int expires);



cdev         : ccw_device the I/O is destined for

cpa          : logical start address of channel program
@@ -272,7 +297,12 @@ user_intparm : user specific interrupt information; will be presented 
               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	     : the storage key to use for the I/O (useful for operating on a

	       storage with a storage key != default key)

flag         : defines the action to be performed for I/O processing

expires      : timeout value in jiffies. The common I/O layer will terminate

	       the running program after this and call the interrupt handler

	       with ERR_PTR(-ETIMEDOUT) as irb.



Possible flag values are :
@@ -327,6 +357,13 @@ current (last) I/O request. In case of a delayed status notification no special 
interrupt will be presented to indicate I/O completion as the I/O request was

never started, even though ccw_device_start() returned with successful completion.



The irb may contain an error value, and the device driver should check for this

first:



-ETIMEDOUT: the common I/O layer terminated the request after the specified

            timeout value

-EIO:       the common I/O layer terminated the request due to an error state



If the concurrent sense flag in the extended status word in the irb is set, the

field irb->scsw.count describes the numer of device specific sense bytes

available in the extended control word irb->scsw.ecw[0]. No device sensing by