Documentation/s390/cds.txt

   1 Linux/390
   2
   3 Common Device Support (CDS)
   4 Device Driver I/O Support Routines
   5
   6 Author : Ingo Adlung
   7
   8 Copyright, IBM Corp. 1999
   9
  10 Introduction
  11
  12 This document describes the common device support routines for Linux/390.
  13 Different than other hardware architectures, ESA/390 hasdefined a unified
  14 I/O access method. This gives relief to the device drivers as they don't
  15 have to deal with different bus types, polling versus interrupt
  16 processing, shared versus non-shared interrupt processing, DMA versus port
  17 I/O (PIO), and other hardware features more. However, this implies that
  18 either every single device driver needs to implement the hardware I/O
  19 attachment functionality itself, or the operating system provides for a
  20 unified method to access the hardware, providing all the functionality that
  21 every single device driver would have to provide itself.
  22
  23 The document does not intend to explain the ESA/390 hardware architecture in
  24 every detail.This information can be obtained from the ESA/390 Principles of
  25 Operation manual (IBM Form. No. SA22-7201).
  26
  27 In order to build common device support for ESA/390 I/O interfaces, a
  28 functional layer was introduced that provides generic I/O access methods to
  29 the hardware. The following figure shows the usage of the common device support
  30 of Linux/390 using a TbCP/IP driven device access an example. Similar figures
  31 could be drawn for other access methods, e.g. file system access to disk
  32 devices.
  33
  34 The common device support layer shown above comprises the I/O support routines
  35 defined below. Some of them implement common Linux device driver interfaces,
  36 while some of them are ESA/390 platform specific.
  37
  38 get_dev_info_by_irq() / get_dev_info_by_devno()
  39    allow a device driver to determine the devices attached (visible) to the
  40    system and their current status.
  41
  42 get_irq_by_devno() / get_devno_by_irq()
  43    get irq (subchannel) from device number and vice versa.
  44
  45 read_dev_chars()
  46    read device characteristics
  47
  48 request_irq()
  49    obtain ownership for a specific device.
  50
  51 free_irq()
  52    release ownership for a specific device.
  53
  54 disable_irq()
  55    disable a device from presenting interrupts.
  56
  57 enable_irq()
  58    enable a device, allowing for I/O interrupts.
  59
  60 do_IO()
  61    initiate an I/O request.
  62
  63 halt_IO()
  64    terminate the current I/O request processed on the device.
  65
  66 do_IRQ()
  67    generic interrupt routine. This function is called by the interrupt entry
  68    routine whenever an I/O interrupt is presented to the system. The do_IRQ()
  69    routine determines the interrupt status and calls the device specific
  70    interrupt handler according to the rules (flags) defined during I/O request
  71    initiation with do_IO().
  72
  73 The next chapters describe the functions, other than do_IRQ() in more details.
  74 The do_IRQ() interface is not described, as it is called from the Linux/390
  75 first level interrupt handler only and does not comprise a device driver
  76 callable interface. Instead, the functional description of do_IO() also
  77 describes the input to the device specific interrupt handler.
  78
  79
  80 Common Device Support (CDS) for Linux/390 Device Drivers
  81
  82 General Information
  83
  84 The following chapters describe the I/O related interface routines the
  85 Linux/390 common device support (CDS) provides to allow for device specific
  86 driver implementations on the IBM ESA/390 hardware platform. Those interfaces
  87 intend to provide the functionality required by every device driver
  88 implementaion to allow to drive a specific hardware device on the ESA/390
  89 platform. Some of the interface routines are specific to Linux/390 and some
  90 of them can be found on other Linux platforms implementations too.
  91 Miscellaneous function prototypes, data declarations, and macro definitions
  92 can be found in the architecture specific C header file
  93 linux/arch/s390/kernel/irq.h.
  94
  95 Overview of CDS interface concepts
  96
  97 Different to other hardware platforms, the ESA/390 architecture doesn't define
  98 interrupt lines managed by a specific interrupt controller and bus systems
  99 that may or may not allow for shared interrupts, DMA processing, etc.. Instead,
 100 the ESA/390 architecture has implemented a so called channel subsystem, that
 101 provides a unified view of the devices physically attached to the systems.
 102 Though the ESA/390 hardware platform knows about a huge variety of different
 103 peripheral attachments like disk devices (aka. DASDs), tapes, communication
 104 controllers, etc. they can all by accessed by a well defined access method and
 105 they are presenting I/O completion a unified way : I/O interruptions. Every
 106 single device is uniquely identified to the system by a so called subchannel,
 107 where the ESA/390 architecture allows for 64k devices be attached.
 108
 109 Linux, however was first built on the Intel PC architecture, with its two
 110 cascaded 8259 programmable interrupt controllers (PICs), that allow for a
 111 maximum of 15 different interrupt lines. All devices attached to such a system
 112 share those 15 interrupt levels. Devices attached to the ISA bus system must
 113 not share interrupt levels (aka. IRQs), as the ISA bus bases on edge triggered
 114 interrupts. MCA, EISA, PCI and other bus systems base on level triggered
 115 interrupts, and therewith allow for shared IRQs. However, if multiple devices
 116 present their hardware status by the same (shared) IRQ, the operating system
 117 has to call every single device driver registered on this IRQ in order to
 118 determine the device driver owning the device that raised the interrupt.
 119
 120 In order to not introduce a new I/O concept to the common Linux code,
 121 Linux/390 preserves the IRQ concept and semantically maps the ESA/390
 122 subchannels to Linux as IRQs. This allows Linux/390 to support up to 64k
 123 different IRQs, uniquely representig a single device each.
 124
 125 During its startup the Linux/390 system checks for peripheral devices. Each
 126 of those devices is uniquely defined by a so called subchannel by the ESA/390
 127 channel subsystem. While the subchannel numbers are system generated, each
 128 subchannel also takes a user defined attribute, the so called device number.
 129 Both, subchannel number and device number can not exceed 65535. The
 130 init_IRQ() routine gathers the information about control unit type and device
 131 types that imply specific I/O commands (channel command words - CCWs) in
 132 order to operate the device. Device drivers can retrieve this set of hardware
 133 information during their initialization step to recognize the devices they
 134 support using get_dev_info_by_irq() or get_dev_info_by_devno() respectively.
 135 This methods implies that Linux/390 doesn't require to probe for free (not
 136 armed) interrupt request lines (IRQs) to drive its devices with. Where
 137 applicable, the device drivers can use the read_dev_chars() to retrieve device
 138 characteristics. This can be done without having to request device ownership
 139 previously.
 140
 141 When a device driver has recognized a device it wants to claim ownership for,
 142 it calls request_irq() with the device's subchannel id serving as pseudo irq
 143 line. One of the required parameters it has to specify is dev_id, defining a
 144 device status block, the CDS layer will use to notify the device driver's
 145 interrupt handler about interrupt information observed. It depends on the
 146 device driver to properly handle those interrupts.
 147
 148 In order to allow for easy I/O initiation the CDS layer provides a do_IO()
 149 interface that takes a device specific channel program (one or more CCWs) as
 150 input sets up the required architecture specific control blocks and initiates
 151 an I/O request on behalf of the device driver. The do_IO() routine allows for
 152 different I/O methods, synchronous and asynchronous, and allows to specify
 153 whether it expects the CDS layer to notify the device driver for every
 154 interrupt it observes, or with final status only. It also provides a scheme
 155 to allow for overlapped I/O processing. See do_IO() for more details. A device
 156 driver must never issue ESA/390 I/O commands itself, but must use the
 157 Linux/390 CDS interfaces instead.
 158
 159 For long running I/O request to be canceled, the CDS layer provides the
 160 halt_IO() function. Some devices require to initially issue a HALT SUBCHANNEL
 161 (HSCH) command without having pending I/O requests. This function is also
 162 covered by halt_IO().
 163
 164 When done with a device, the device driver calls free_irq() to release its
 165 ownership for the device. During free_irq() processing the CDS layer also
 166 disables the device from presenting further interrupts - the device driver
 167 doesn't need to assure it. The device will be reenabled for interrupts with
 168 the next call to request_irq().
 169
 170
 171
 172 get_dev_info_by_irq() / get_dev_info_by_devno() - Retrieve Device Information
 173
 174 During system startup - init_IRQ() processing - the generic I/O device support
 175 checks for the devices available. For all devices found it collects the
 176 SenseID information. For those devices supporting the command it also obtains
 177 extended SenseID information.
 178
 179 int get_dev_info_by_irq( int         irq,
 180                          dev_info_t *devinfo);
 181
 182 int get_dev_info_by_devno( unsigned int  irq,
 183                            dev_info_t   *devinfo);
 184
 185 irq     - defines the subchannel, status information is to be
 186           returned for.
 187 devno   - device number.
 188 devinfo - pointer to a user buffer of type dev_info_t that should
 189           be filled with device specific information.
 190
 191 typedef struct {
 192      unsigned int devno;     /* device number */
 193      unsigned int status;    /* device status */
 194      senseid_t    sid_data;  /* senseID data  */
 195 } dev_info_t;
 196
 197 devno     - device number as configured in the IOCDS.
 198 status    - device status
 199 sid_data  - data obtained by a SenseID call
 200
 201 Possible status values are :
 202
 203 DEVSTAT_NOT_OPER - device was found not-operational. In this case
 204                    the caller should disregard the sid_data
 205                    buffer content.
 206
 207 //
 208 // SenseID response buffer layout
 209 //
 210 typedef struct {
 211   /* common part */
 212       unsigned char  reserved;     /* always 0x'FF' */
 213       unsigned short cu_type;      /* control unit type */
 214       unsigned char  cu_model;     /* control unit model */
 215       unsigned short dev_type;     /* device type */
 216       unsigned char  dev_model;    /* device model */
 217       unsigned char  unused;       /* padding byte */
 218   /* extended part */
 219       ciw_t    ciw[62];            /* variable # of CIWs */
 220 } senseid_t;
 221
 222 The ESA/390 I/O architecture defines certain device specific I/O functions.
 223 The device returns the device specific command code together with the SenseID
 224 data in so called Command Information Words (CIW) :
 225
 226 typedef struct _ciw {
 227    unsigned int et       :  2;    // entry type
 228    unsigned int reserved :  2;    // reserved
 229    unsigned int ct       :  4;    // command type
 230    unsigned int cmd      :  8;    // command
 231    unsigned int count    : 16;    // count
 232 } ciw_t;
 233
 234 Possible CIW entry types are :
 235
 236 #define CIW_TYPE_RDC    0x0;      // read configuration data
 237 #define CIW_TYPE_SII    0x1;      // set interface identifier
 238 #define CIW_TYPE_RNI    0x2;      // read node identifier
 239
 240 The device driver may use these commands as appropriate.
 241
 242 The get_dev_info_by_irq() / get_dev_info_by_devno() functions return:
 243
 244       0 - successful completion
 245 -ENODEV - irq or devno don't specify a known subchannel or device
 246           number.
 247 -EINVAL - invalid devinfo value.
 248
 249 Usage Notes :
 250
 251 In order to scan for known devices a device driver should scan all irqs by
 252 calling     get_dev_info() until it returns -ENODEV as there aren't any more
 253 available devices.
 254
 255 If a device driver wants to request ownership for a specific device it must
 256 call request_irq() prior to be able to issue any I/O request for it, including
 257 above mentioned   device dependent commands.
 258
 259 Please see the "ESA/390 Common I/O-Commandss and Self Description" manual,
 260 with IBM form number SA22-7204 for more details on how to read the Sense-ID
 261 output, CIWs and device independent commands.
 262
 263
 264
 265 get_irq_by_devno() / get_devno_by_irq() - Convert device identifiers
 266
 267 While some device drivers act on the irq (subchannel) only, others take user
 268 defined device configurations on device number base, according to the device
 269 numbers configured in the IOCDS. The following routines serve the purpose to
 270 convert irq values into device numbers and vice versa.
 271
 272 int get_irq_by_devno( unsigned int devno );
 273
 274 unsigned int get_devno_by_irq( int irq );
 275
 276 The functions return :
 277
 278 the requested irq/devno values
 279 -1 if the requested conversion can't be accomplished.
 280
 281 This could either be caused by irq/devno be outside the valid range
 282 ( value > 0xffff or value < 0 ) or not identifying a known device.
 283
 284
 285 read_dev_chars() - Read Device Characteristics
 286
 287 This routine returns the characteristics for the device specified.
 288
 289 The function is meant to be called without an irq handler be in place.
 290 However, the irq for the requested device must not be locked or this will
 291 cause a deadlock situation ! Further, the driver must assure that nobody
 292 else has claimed ownership for the requested irq yet or the owning device
 293 driver's internal accounting may be affected.
 294
 295 In case of a registered interrupt handler, the interrupt handler must be
 296 able to properly react on interrupts related to the read_dev_chars() I/O
 297 commands. While the request is procesed synchronously, the device interrupt
 298 handler is called for final ending status. In case of error situations the
 299 interrupt handler may recover appropriately. The device irq handler can
 300 recognize the corresponding interrupts by the interruption parameter be
 301 0x00524443. If using the function with an existing device interrupt handler
 302 in place, the irq must be locked prior to call read_dev_chars().
 303
 304 The function may be called enabled or disabled.
 305
 306 int read_dev_chars( int irq, void **buffer, int length );
 307
 308 irq    - specifies the subchannel the device characteristic
 309          retrieval is requested for
 310 buffer - pointer to a buffer pointer. The buffer pointer itself
 311          may be NULL to have the function allocate a buffer or
 312          must contain a valid buffer area.
 313 length - length of the buffer provided or to be allocated.
 314
 315 The read_dev_chars() function returns :
 316
 317       0 - successful completion
 318 -ENODEV - irq doesn't specify a valid subchannel number
 319 -EINVAL - an invalid parameter was detected
 320 -EBUSY  - an irrecoverable I/O error occurred or the device is not
 321           operational.
 322
 323 Usage Notes :
 324
 325 The function can be used in two ways :
 326
 327 If the caller doesn't provide a data buffer, read_dev_chars() allocates a
 328 data buffer and provides the device characteristics together. It's the
 329 caller's responsability to release the kernel memory if not longer needed.
 330 This behaviour is triggered by specifying a NULL buffer area (*buffer == NULL).
 331
 332 Alternatively, if the user specifies a buffer area himself, nothing is
 333 allocated.
 334
 335 In either case the caller must provide the data area length - for the buffer
 336 he specifies, or the buffer he wants to be allocated.
 337
 338
 339 request_irq() - Request Device Ownership
 340
 341 As previously discussed a device driver will scan for the devices its supports
 342 by calling get_dev_info(). Once it has found a device it will call
 343 request_irq() to request ownership for it. This call causes the subchannel to
 344 be enabled for interrupts if it was found operational.
 345
 346 int request_irq( unsigned int   irq,
 347                  int          (*handler)( int,
 348                                           void *,
 349                                           struct pt_regs *),
 350                  unsigned long  irqflags,
 351                  const char    *devname,
 352                  void          *dev_id);
 353
 354 irq      : specifies the subchannel the ownership is requested for
 355 handler  : specifies the device driver's interrupt handler to be
 356            called for interrupt processing
 357 irqflags : IRQ flags, must be 0 (zero) or SA_SAMPLE_RANDOM
 358 devname  : device name
 359 dev_id   : required pointer to a device specific buffer of type
 360            devstat_t
 361
 362 typedef struct {
 363      unsigned int  devno;   /* device number from irb */
 364      unsigned int  intparm; /* interrupt parameter */
 365      unsigned char cstat;   /* channel status - accumulated */
 366      unsigned char dstat;   /* device status - accumulated */
 367      unsigned char lpum;    /* last path used mask from irb */
 368      unsigned char unused;  /* not used - reserved */
 369      unsigned int  flag;    /* flag : see below */
 370      unsigned long cpa;     /* CCW addr from irb at prim. status */
 371      unsigned int  rescnt;  /* count from irb at primary status */
 372      unsigned int  scnt;    /* sense count, if available */
 373      union {
 374         irb_t   irb;        /* interruption response block */
 375         sense_t sense;      /* sense information */
 376         } ii;               /* interrupt information */
 377   } devstat_t;
 378
 379 During request_irq() processing, the devstat_t layout does not matter as it
 380 won't be used during request_irq() processing. See do_IO() for a functional
 381 description of its usage.
 382
 383 The request_irq() function returns :
 384
 385       0 - successful completion
 386 -EINVAL - an invalid parameter was detected
 387 -EBUSY  - device (subchannel) already owned
 388 -ENODEV - the device is not-operational
 389 -ENOMEM - not enough kernel memory to process request
 390
 391 Usage Notes :
 392
 393 While Linux for Intel defines dev_id as a unique identifier for shared
 394 interrupt lines it has a totally different purpose on Linux/390. Here it
 395 serves as a shared interrupt status area between the generic device support
 396 layer, and the device specific driver. The value passed to request_irq()
 397 must therefore point to a valid devstat_t type buffer area the device driver
 398 must preserve for later usage. I.e. it must not be released prior to a call
 399 to free_irq()
 400
 401 The only value parameter irqflags supports is SA_SAMPLE_RANDOM if appropriate.
 402 The Linux/390 kernel does neither know about "fast" interrupt handlers, nor
 403 does it allow for interrupt sharing. Remember, the term interrupt level (irq),
 404 device, and subchannel are used interchangeably in Linux/390.
 405
 406 If request_irq() was called in enabled state, or if multiple CPUs are present,
 407 the device may present an interrupt to the specified handler prior to
 408 request_irq() return to the caller  already ! This includes the possibility
 409 of unsolicited interrupts or a pending interrupt status from an earlier
 410 solicited I/O request. The device driver must be able to handle this situation
 411 properly or the device may become unoperational otherwise !
 412
 413 Although the interrupt handler is defined to be called with a pointer to a
 414 struct pt_regs buffer area, this is not implemented by the Linux/390 generic
 415 I/O device driver support layer. The device driver's interrupt handler must
 416 therefore not rely on this parameter on function entry.
 417
 418
 419 free_irq() - Release Device Ownership
 420
 421 A device driver may call free_irq() to release ownership of a previously
 422 acquired device.
 423
 424 void free_irq( unsigned int  irq,
 425                void         *dev_id);
 426
 427 irq      : specifies the subchannel the ownership is requested for
 428 dev_id   : required pointer to a device specific buffer of type
 429            devstat_t. This must be the same as the one specified
 430            during a previous call to request_irq().
 431
 432 Usage Notes :
 433
 434 Unfortunately the free_irq() is defined not to return error codes. I.e. if
 435 called with wrong  parameters a device may still be operational although there
 436 is no device driver available to handle its interrupts. Further, during
 437 free_irq() processing we may possibly find pending interrupt conditions. As
 438 those need to be processed, we have to delay free_irq() returning until a
 439 clean device status is found by synchronously handling them.
 440
 441 The call to free_irq() will also cause the device (subchannel) be disabled for
 442 interrupts. The device driver must not release any data areas required for
 443 interrupt processing prior to free_irq() return to the caller as interrupts
 444 can occur prior to free_irq() returning. This is also true when called in
 445 disabled state if either multiple CPUs are presents or a pending interrupt
 446 status was found during free_irq() processing.
 447
 448
 449 disable_irq() - Disable Interrupts for a given Device
 450
 451 This function may be called at any time to disable interrupt processing for
 452 the specified irq. However, as Linux/390 maps irqs to the device (subchannel)
 453 one-to-one, this may require more extensive I/O processing than anticipated,
 454 especially if an interrupt status is found pending on the subchannel that
 455 requires synchronous error processing.
 456
 457 int disable_irq( unsigned int irq );
 458
 459 irq : specifies the subchannel to be disabled
 460
 461 The disable-irq() routine may return :
 462
 463       0 - successful completion
 464 -EBUSY  - device (subchannel) is currently processing an I/O
 465           request
 466 -ENODEV - the device is not-operational or irq doesn't specify a
 467           valid subchannel
 468
 469 Usage Notes :
 470
 471 Unlike the Intel based hardware architecture the ESA/390 architecture does
 472 not have a programmable interrupt controller (PIC) where a specific interrupt
 473 line can be disabled. Instead the subchannel logically representing the device
 474 in the channel subsystem must be disabled for interrupts. However, if there
 475 are still inetrrupt conditions pending they must   be processed first in order
 476 to allow for proper processing after reenabling the device at a later time.
 477 This may lead to delayed disable processing.
 478
 479 As described above the disable processing may require extensive processing.
 480 Therefore    disabling and re-enabling the device using disable_irq() /
 481 enable_irq() should be avoided and is not suitable for high frequency
 482 operations.
 483
 484 Linux for Intel defines this function
 485
 486 void disable_irq( int irq);
 487
 488 This is suitable for the Intel PC architecture as this only causes to mask
 489 the requested irq line in the PIC which is not applicable for the ESA/390
 490 architecture. Therefore we allow   for returning error codes.
 491
 492
 493 enable_irq() - Enable Interrupts for a given Device
 494
 495 This function is used to enable a previously disabled device (subchannel).
 496 See disable_irq() for more details.
 497
 498 int enable_irq( unsigned int irq );
 499
 500 irq : specifies the subchannel to be enabled
 501
 502 The enable-irq() routine may return :
 503
 504       0 - successful completion
 505 -EBUSY  - device (subchannel) is currently processing an I/O
 506           request. This implies the device is already in enabled
 507           state
 508 -ENODEV - the device is not-operational or irq doesn't specify a
 509           valid subchannel
 510
 511
 512
 513 do_IO() - Initiate I/O Request
 514
 515 The do_IO() routines is the I/O request front-end processor. All device driver
 516 I/O requests must be issued using this routine. A device driver must not issue
 517 ESA/390 I/O commands itself. Instead the do_IO() routine provides all
 518 interfaces required to drive arbitrary devices.
 519
 520 This description also covers the status information passed to the device
 521 driver's interrupt handler as this is related to the rules (flags) defined
 522 with the associated I/O request when calling do_IO().
 523
 524 int do_IO( int            irq,
 525            ccw1_t        *cpa,
 526            unsigned long  intparm,
 527            unsigned int   lpm,
 528            unsigned long  flag);
 529
 530 irq     : irq (subchannel) the I/O request is destined for
 531 cpa     : logical start address of channel program
 532 intparm : user specific interrupt information; will be presented
 533           back to the device driver's interrupt handler. Allows a
 534           device driver to associate the interrupt with a
 535           particular I/O request.
 536 lpm     : defines the channel path to be used for a specific I/O
 537           request. Valid with flag value DOIO_VALID_LPM only.
 538 flag    : defines the action to e parformed for I/O processing
 539
 540 Possible flag values are :
 541
 542 DOIO_EARLY_NOTIFICATION  - allow for early interrupt notification
 543 DOIO_VALID_LPM           - LPM input parameter is valid (see usage
 544                            notes below for details)
 545 DOIO_WAIT_FOR_INTERRUPT  - wait synchronously for final status
 546 DOIO_REPORT_ALL          - report all interrupt conditions
 547
 548 The cpa parameter points to the first format 1 CCW of a channel program :
 549
 550 typedef struct {
 551    char            cmd_code; /* command code */
 552    char            flags;    /* flags, like IDA addressing, etc. */
 553    unsigned short  count;    /* byte count */
 554    void           *cda;      /* data address */
 555 } ccw1_t __attribute__ ((aligned(8)));
 556
 557 with the following CCW flags values defined :
 558
 559 CCW_FLAG_DC        - data chaining
 560 CCW_FLAG_CC        - command chaining
 561 CCW_FLAG_SLI       - suppress incorrct length
 562 CCW_FLAG_SKIP      - skip
 563 CCW_FLAG_PCI       - PCI
 564 CCW_FLAG_IDA       - indirect addressing
 565 CCW_FLAG_SUSPEND   - suspend
 566
 567
 568
 569 The do_IO() function returns :
 570
 571       0 - successful completion or request successfully initiated
 572 -EBUSY  - the do_io() function was caled out of sequence. The
 573           device is currently processing a previous I/O request
 574 -ENODEV - irq doesn't specify a valid subchannel, the device is
 575           not operational (check dev_id.flags) or the irq is not
 576           owned.
 577 -EINVAL - both, DOIO_EARLY_NOTIFICATION and DOIO_REORT_ALL flags
 578           have been specified. The usage of those flags is mutual
 579           exclusive.
 580
 581 When the I/O request completes, the CDS first level interrupt handler will
 582 setup the dev_id buffer of type devstat_t defined during request_irq()
 583 processing. See request_irq() for the devstat_t data layout. The
 584 dev_id->intparm field in the device status area will contain the value the
 585 device driver has associated with a particular I/O request. If a pending
 586 device status was recognized dev_id->intparm will be set to 0 (zero). This
 587 may happen during I/O initiation or delayed by an alert status notification.
 588 In any case this status is not related to the current (last) I/O request. In
 589 case of a delayed status notification no special interrupt will be presented
 590 to indicate I/O completion as the I/O request was never started, even though
 591 do_IO() returned with successful completion.
 592
 593 Possible dev_id->flag values are :
 594
 595 DEVSTAT_FLAG_SENSE_AVAIL - sense data is available
 596 DEVSTAT_NOT_OPER         - device is not-operational
 597 DEVSTAT_START_FUNCTION   - interrupt is presented as result of a
 598                            call to do_IO()
 599 DEVSTAT_HALT_FUNCTION    - interrupt is presented as result of a
 600                            call to halt_IO()
 601 DEVSTAT_STATUS_PENDING   - a pending status was found. The I/O
 602                            resquest (if any) was not initiated.
 603                            This status might have been presented
 604                            delayed, after do_IO() or halt_IO() have
 605                            successfully be started previously.
 606 DEVSTAT_FINAL_STATUS     - This is a final interrupt status for the
 607                            I/O requst identified by intparm.
 608
 609 If device status DEVSTAT_FLAG_SENSE_AVAIL is indicated in field dev_id->flag,
 610 field dev_id->scnt describes the numer of device specific sense bytes
 611 available in the sense area dev_id->ii.sense. No device sensing by the device
 612 driver itself is required.
 613
 614 typedef struct {
 615    unsigned char res[32];       /* reserved   */
 616    unsigned char data[32];      /* sense data */
 617 } sense_t;
 618
 619 The device interrupt handler can use the following definitions to investigate
 620 the primary unit check source coded in sense byte 0 :
 621
 622 SNS0_CMD_REJECT         0x80
 623 SNS0_INTERVENTION_REQ   0x40
 624 SNS0_BUS_OUT_CHECK      0x20
 625 SNS0_EQUIPMENT_CHECK    0x10
 626 SNS0_DATA_CHECK         0x08
 627 SNS0_OVERRUN            0x04
 628
 629 Depending on the device status, multiple of those values may be set together.
 630 Please refer to the device specific documentation for details.
 631
 632 The devi_id->cstat field provides the (accumulated) subchannel status :
 633
 634 SCHN_STAT_PCI            - program controlled interrupt
 635 SCHN_STAT_INCORR_LEN     - incorrect length
 636 SCHN_STAT_PROG_CHECK     - program check
 637 SCHN_STAT_PROT_CHECK     - protection check
 638 SCHN_STAT_CHN_DATA_CHK   - channel data check
 639 SCHN_STAT_CHN_CTRL_CHK   - channel control check
 640 SCHN_STAT_INTF_CTRL_CHK  - interface control check
 641 SCHN_STAT_CHAIN_CHECK    - chaining check
 642
 643 The dev_id->dstat field provides the (accumulated) device status :
 644
 645 DEV_STAT_ATTENTION   - attention
 646 DEV_STAT_STAT_MOD    - status modifier
 647 DEV_STAT_CU_END      - control unit end
 648 DEV_STAT_BUSY        - busy
 649 DEV_STAT_CHN_END     - channel end
 650 DEV_STAT_DEV_END     - device end
 651 DEV_STAT_UNIT_CHECK  - unit check
 652 DEV_STAT_UNIT_EXCEP  - unit exception
 653
 654 Please see the ESA/390 Principles of Operation manual for details on the
 655 individual flag meanings.
 656
 657 In rare error situations the device driver may require access to the original
 658 hardware interrupt data beyond the scope of above mentioned infromation. For
 659 those situations the Linux/390 common device support provides the interrupt
 660 response block (IRB) as part of the device status block in dev_id->ii.irb.
 661
 662 Usage Notes :
 663
 664 Prior to call do_IO() the device driver must
 665
 666 assure disabled state, i.e. the I/O mask value in the PSW must be disabled.
 667 This can be accomplished by calling __save_flags( flags). The current PSW
 668 flags are preserved and can be restored by __restore_flags( flags) at a
 669 later time.
 670
 671 If the device driver violates this rule while running in a uni-processor
 672 environment an interrupt might be presented prior to the do_IO() routine
 673 returning to the device driver main path. In this case we will end in a
 674 deadlock situation as the interrupt handler will try to obtain the irq
 675 lock the device driver still owns (see below) !
 676
 677 the driver must assure to hold the device specific lock. This can be
 678 accomplished by
 679
 680 (i)  s390irq_spin_lock( irq), or
 681 (ii) s390irq_spin_lock_irqsave(irq, flags)
 682
 683 Option (i) should be used if the calling routine is running disabled for
 684 I/O interrupts (see above) already. Option (ii) obtains the device gate und
 685 puts the CPU into I/O disabled state by preserving the current PSW flags.
 686 See the descriptions of s390irq_spin_lock() or s390irq_spin_lock_irqsave()
 687 for more details.
 688
 689 The device driver is allowed to issue the next do_IO() call from within its
 690 interrupt handler already. It is not required to schedule a bottom-half,
 691 unless an non deterministicly long running error recovery procedure or
 692 similar needs to be scheduled. During I/O processing the Linux/390 generic
 693 I/O device driver support has already obtained the IRQ lock, i.e. the handler
 694 must not try to obtain it again when calling do_IO() or we end in a deadlock
 695 situation ! Anyway, the device driver's interrupt handler must only call
 696 do_IO() if the handler itself can be entered recursively if do_IO() e.g. finds
 697 a status pending and needs to all the interrupt handler itself.
 698
 699 Device drivers shouldn't heavily rely on DOIO_WAIT_FOR_INTERRUPT synchronous
 700 I/O request processing. All I/O devices, but the console device are driven
 701 using a single shared interrupt subclass (ISC). For sync. processing the
 702 device is temporarily mapped to a special ISC while the calling CPU waits for
 703 I/O completion. As this special ISC is gated, all sync. requests in a SMP
 704 environment are serialized which may cause other CPUs to spin. This service
 705 is therewith primarily meant to be used during device driver initialization
 706 for ease of device setup.
 707
 708 The lpm input parameter might be used for multipath devices shared among
 709 multiple systems as the Linux/390 CDS isn't grouping channel paths. Therefore
 710 its use might be required if multiple access paths to a device are available
 711 and the device was reserved by means of a reserve device command (for devices
 712 supporting this technique). When issuing this command the device driver needs
 713 needs to extract the dev_id->lpum value and restrict all subsequent channel
 714 programs to this channel path until the device is released by a device release
 715 command. Otherwise a deadlock may occur.
 716
 717 If a device driver relies on an I/O request to be completed prior to start the
 718 next it can reduce I/O processing overhead by chaining a NoOp I/O command
 719 CCW_CMD_NOOP to the end of the submitted CCW chain. This will force Channel-End
 720 and Device-End status to be presented together, with a single interrupt.
 721 However, this should be used with care as it implies the channel will remain
 722 busy, not being able to process I/O requests for other devices on the same
 723 channel. Therefore e.g. read commands should never use this technique, as the
 724 result will be presented by a single interrupt anyway.
 725
 726 In order to minimize I/O overhead, a device driver should use the
 727 DOIO_REPORT_ALL  only if the device can report intermediate interrupt
 728 information prior to device-end the device driver urgently relies on. In this
 729 case all I/O interruptions are presented to the device driver until final
 730 status is recognized.
 731
 732 If a device is able to recover from asynchronosly presented I/O errors, it can
 733 perform overlapping I/O using the DOIO_EARLY_NOTIFICATION flag. While some
 734 devices always report channel-end and device-end together, with a single
 735 interrupt, others present primary status (channel-end) when the channel is
 736 ready for the next I/O request and secondary status (device-end) when the data
 737 transmission has been completed at the device.
 738
 739 Above flag allows to exploit this feature, e.g. for communication devices that
 740 can handle lost data on the network to allow for enhanced I/O processing.
 741
 742 Unless the channel subsystem at any time presents a secondary status interrupt,
 743 exploiting this feature will cause only primary status interrups to be
 744 presented to the device driver while overlapping I/O is performed. When a
 745 secondary status without error (alert status) is presented, this indicates
 746 successful completion for all overlapping do_IO() requests that have been
 747 issued since the last secondary (final) status.
 748
 749 During interrupt processing the device specific interrupt handler should avoid
 750 basing its processing decisions on the interruption response block (IRB) that
 751 is part of the dev_id buffer area. The IRB area represents the interruption
 752 parameters from the last interrupt received. Unless the device driver has
 753 specified DOIO_REPORT_ALL or is called with a pending status
 754 (DEVSTAT_STATUS_PENDING), the IRB information may or may not show the complete
 755 interruption status, but the last interrupt only. Therefore the device driver
 756 should usually base its processing decisions on the values of dev_id->cstat
 757 and dev_id->dstat that represent the accumulated subchannel and device status
 758 information gathered since do_IO() request initiation.
 759
 760
 761 halt_IO() - Halt I/O Request Processing
 762
 763 Sometimes a device driver might need a possibility to stop the processing of
 764 a long-running channel program or the device might require to initially issue
 765 a halt subchannel (HSCH) I/O command. For those purposes the halt_IO() command
 766 is provided.
 767
 768 int halt_IO( int          irq,     /* subchannel number */
 769              int          intparm, /* dummy intparm */
 770              unsigned int flag);   /* operation mode */
 771
 772 irq     : irq (subchannel) the halt operation is requested for
 773 intparm : interruption parameter; value is only used if no I/O
 774           is outstanding, otherwise the intparm associated with
 775           the I/O request is returned
 776 flag    : 0 (zero) or DOIO_WAIT_FOR_INTERRUPT
 777
 778 The halt_IO() function returns :
 779
 780       0 - successful completion or request successfully initiated
 781 -EBUSY  - the device is currently performing a synchronous I/O
 782           operation : do_IO() with flag DOIO_WAIT_FOR_INTERRUPT
 783           or an error was encountered and the device is currently
 784           be sensed
 785 -ENODEV - the irq specified doesn't specify a valid subchannel, the
 786           device is not operational (check dev_id.flags) or the irq
 787           is not owned.
 788
 789 Usage Notes :
 790
 791 A device driver may write a never-ending channel program by writing a channel
 792 program that at its end loops back to its beginning by means of a transfer in
 793 channel (TIC)   command (CCW_CMD_TIC). Usually this is performed by network
 794 device drivers by setting the PCI CCW flag (CCW_FLAG_PCI). Once this CCW is
 795 executed a program controlled interrupt (PCI) is generated. The device driver
 796 can then perform an appropriate action. Prior to interrupt of an outstanding
 797 read to a network device (with or   without PCI flag) a halt_IO() is required
 798 to end the pending operation.
 799
 800 We don't allow to stop sync. I/O requests by means of a halt_IO() call. The
 801 function will return -EBUSY instead.
 802
 803
 804 Miscellaneous Support Routines
 805
 806 This chapter describes various routines to be used in a Linux/390 device
 807 driver programming environment.
 808
 809 s390irq_spin_lock() / s390irq_spin_unlock()
 810
 811 Those two macro definitions are required to obtain the device specific IRQ
 812 lock. The lock needs to be obtained if the device driver intends to call
 813 do_IO() or halt_IO() from anywhere but the device interrupt handler (where
 814 the lock is already owned). Those routines must only be used if running
 815 disabled for interrupts already. Otherwise use s390irq_spin_lock_irqsave()
 816 and the corresponding unlock routine instead (see below).
 817
 818 s390irq_spin_lock( int irq);
 819 s390irq_spin_unlock( int irq);
 820
 821
 822 s390irq_spin_lock_irqsave() / s390_irq_spin_unlock_irqrestore()
 823
 824 Those two macro definitions are required to obtain the device specific IRQ
 825 lock. The lock needs to be obtained if the device driver intends to call
 826 do_IO() or halt_IO() from anywhere but the device interrupt handler (where
 827 the lock is already owned). Those routines should only be used if running
 828 enabled for interrupts. If running disabled already, the driver should use
 829 s390irq_spin_lock() and the corresponding unlock routine instead (see above).
 830
 831 s390irq_spin_lock_irqsave( int irq, unsigned long flags);
 832 s390irq_spin_unlock_irqrestore( int irq, unsigned long flags);
 833
 834
 835
 836
 837 Special Console Interface Routines
 838
 839 This chapter describes the special interface routines required for system
 840 console processing. Though they are an extension to the Linux/390 device
 841 driver interface concept, they base on the same principles. It was necessary
 842 to build those extensions to assure a deterministic behaviour in critical
 843 situations e.g. printk() messages by other device drivers running disabled
 844 for interrupts during I/O interrupt handling or in case of a panic() message
 845 being raised.
 846
 847 set_cons_dev - Set Console Device
 848
 849 This routine allows to specify the system console device. This is necessary
 850 as the console isn't driven by the same ESA/390 interrupt subclass as are
 851 other devices, but it is assigned ist own interrupt subclass. Only one device
 852 can act as system console. See wait_cons_dev() for details.
 853
 854 int set_cons_dev( int irq);
 855
 856 irq : subchannel identifying the system console device
 857
 858 The set_cons_dev() function returns
 859
 860       0 - successful completion
 861 -EIO    - an unhandled interrupt condition is pending for the
 862           specified subchannel (irq) - status pending
 863 -ENODEV - irq doesn't specify a valid subchannel or the devive is
 864           not operational
 865 -EBUSY  - the console device is already defined
 866
 867 reset_cons_dev - Reset Console Device
 868
 869 This routine allows for resetting the console device specification. See
 870 set_cons_dev() for details.
 871
 872 int reset_cons_dev( int irq);
 873
 874 irq : subchannel identifying the system console device
 875
 876 The reset_cons_dev() function returns
 877
 878       0 - successful completion
 879 -EIO    - an unhandled interrupt condition is pending for the
 880           specified subchannel (irq) - status pending
 881 -ENODEV - irq doesn't specify a valid subchannel or the devive is
 882           not operational
 883
 884 wait_cons_dev - Synchronously Wait for Console Processing
 885
 886 The wait_cons_dev() routine is used by the console device driver when its
 887 buffer pool for intermediate request queuing is exhausted and a new output
 888 request is received. In this case the console driver uses the wait_cons_dev()
 889 routine to synchronously wait until enough buffer space is gained to enqueue
 890 the current request. Any pending interrupt condition for the console device
 891 found during wait_cons_dev() processing causes its interrupt handler to be
 892 called.
 893
 894 int wait_cons_dev( int irq);
 895
 896 irq : subchannel identifying the system console device
 897
 898 The wait_cons_dev() function  returns :
 899
 900       0 - successful completion
 901 -EINVAL - the irq specified doesn't match the irq configured for
 902           the console device by set_cons_dev()
 903
 904 Usage Notes :
 905
 906 The function should be used carefully. Especially in a SMP environment the
 907 wait_cons_dev() processing requires that all but the special console ISC are
 908 disabled. In a SMP system this requires the other CPUs to be signaled to
 909 disable/enable those ISCs.
 910
 911
 912