aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/s390/cds.txt
diff options
context:
space:
mode:
authorCornelia Huck <cornelia.huck@de.ibm.com>2007-05-21 05:25:19 -0400
committerMartin Schwidefsky <schwidefsky@de.ibm.com>2007-05-21 05:25:27 -0400
commit85ee32d02901bfd2e287ac669709758e04d73c4d (patch)
tree61f4a7cd8a61e352c7476858f3341bc404995bff /Documentation/s390/cds.txt
parent55b637c6a003a8c4850b41a2c2fd6942d8a7f530 (diff)
[S390] cio: Update documentation.
- read_dev_chars()/read_conf_data() are deprecated. Don't document them, but advise to issue the channel program from the driver itself. - Remove some really obsolete and incorrect stuff. Signed-off-by: Cornelia Huck <cornelia.huck@de.ibm.com> Signed-off-by: Martin Schwidefsky <schwidefsky@de.ibm.com>
Diffstat (limited to 'Documentation/s390/cds.txt')
-rw-r--r--Documentation/s390/cds.txt82
1 files changed, 4 insertions, 78 deletions
diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt
index 05a2b4f7e38f..58919d6a593a 100644
--- a/Documentation/s390/cds.txt
+++ b/Documentation/s390/cds.txt
@@ -51,13 +51,8 @@ The major changes are:
51* The interrupt handlers must be adapted to use a ccw_device as argument. 51* The interrupt handlers must be adapted to use a ccw_device as argument.
52 Moreover, they don't return a devstat, but an irb. 52 Moreover, they don't return a devstat, but an irb.
53* Before initiating an io, the options must be set via ccw_device_set_options(). 53* Before initiating an io, the options must be set via ccw_device_set_options().
54 54* Instead of calling read_dev_chars()/read_conf_data(), the driver issues
55read_dev_chars() 55 the channel program and handles the interrupt itself.
56 read device characteristics
57
58read_conf_data()
59read_conf_data_lpm()
60 read configuration data.
61 56
62ccw_device_get_ciw() 57ccw_device_get_ciw()
63 get commands from extended sense data. 58 get commands from extended sense data.
@@ -130,11 +125,6 @@ present their hardware status by the same (shared) IRQ, the operating system
130has to call every single device driver registered on this IRQ in order to 125has to call every single device driver registered on this IRQ in order to
131determine the device driver owning the device that raised the interrupt. 126determine the device driver owning the device that raised the interrupt.
132 127
133In order not to introduce a new I/O concept to the common Linux code,
134Linux/390 preserves the IRQ concept and semantically maps the ESA/390
135subchannels to Linux as IRQs. This allows Linux/390 to support up to 64k
136different IRQs, uniquely representing a single device each.
137
138Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel). 128Up to kernel 2.4, Linux/390 used to provide interfaces via the IRQ (subchannel).
139For internal use of the common I/O layer, these are still there. However, 129For internal use of the common I/O layer, these are still there. However,
140device drivers should use the new calling interface via the ccw_device only. 130device drivers should use the new calling interface via the ccw_device only.
@@ -151,9 +141,8 @@ information during their initialization step to recognize the devices they
151support using the information saved in the struct ccw_device given to them. 141support using the information saved in the struct ccw_device given to them.
152This methods implies that Linux/390 doesn't require to probe for free (not 142This methods implies that Linux/390 doesn't require to probe for free (not
153armed) interrupt request lines (IRQs) to drive its devices with. Where 143armed) interrupt request lines (IRQs) to drive its devices with. Where
154applicable, the device drivers can use the read_dev_chars() to retrieve device 144applicable, the device drivers can use issue the READ DEVICE CHARACTERISTICS
155characteristics. This can be done without having to request device ownership 145ccw to retrieve device characteristics in its online routine.
156previously.
157 146
158In order to allow for easy I/O initiation the CDS layer provides a 147In order to allow for easy I/O initiation the CDS layer provides a
159ccw_device_start() interface that takes a device specific channel program (one 148ccw_device_start() interface that takes a device specific channel program (one
@@ -170,69 +159,6 @@ SUBCHANNEL (HSCH) command without having pending I/O requests. This function is
170also covered by ccw_device_halt(). 159also covered by ccw_device_halt().
171 160
172 161
173read_dev_chars() - Read Device Characteristics
174
175This routine returns the characteristics for the device specified.
176
177The function is meant to be called with the device already enabled; that is,
178at earliest during set_online() processing.
179
180The ccw_device must not be locked prior to calling read_dev_chars().
181
182The function may be called enabled or disabled.
183
184int read_dev_chars(struct ccw_device *cdev, void **buffer, int length );
185
186cdev - the ccw_device the information is requested for.
187buffer - pointer to a buffer pointer. The buffer pointer itself
188 must contain a valid buffer area.
189length - length of the buffer provided.
190
191The read_dev_chars() function returns :
192
193 0 - successful completion
194-ENODEV - cdev invalid
195-EINVAL - an invalid parameter was detected, or the function was called early.
196-EBUSY - an irrecoverable I/O error occurred or the device is not
197 operational.
198
199
200read_conf_data(), read_conf_data_lpm() - Read Configuration Data
201
202Retrieve the device dependent configuration data. Please have a look at your
203device dependent I/O commands for the device specific layout of the node
204descriptor elements. read_conf_data_lpm() will retrieve the configuration data
205for a specific path.
206
207The function is meant to be called with the device already enabled; that is,
208at earliest during set_online() processing.
209
210The function may be called enabled or disabled, but the device must not be
211locked
212
213int read_conf_data(struct ccw_device, void **buffer, int *length);
214int read_conf_data_lpm(struct ccw_device, void **buffer, int *length, __u8 lpm);
215
216cdev - the ccw_device the data is requested for.
217buffer - Pointer to a buffer pointer. The read_conf_data() routine
218 will allocate a buffer and initialize the buffer pointer
219 accordingly. It's the device driver's responsibility to
220 release the kernel memory if no longer needed.
221length - Length of the buffer allocated and retrieved.
222lpm - Logical path mask to be used for retrieving the data. If
223 zero the data is retrieved on the next path available.
224
225The read_conf_data() function returns :
226 0 - Successful completion
227-ENODEV - cdev invalid.
228-EINVAL - An invalid parameter was detected, or the function was called early.
229-EIO - An irrecoverable I/O error occurred or the device is
230 not operational.
231-ENOMEM - The read_conf_data() routine couldn't obtain storage.
232-EOPNOTSUPP - The device doesn't support the read configuration
233 data command.
234
235
236get_ciw() - get command information word 162get_ciw() - get command information word
237 163
238This call enables a device driver to get information about supported commands 164This call enables a device driver to get information about supported commands