cds.txt
上传用户:lgb322
上传日期:2013-02-24
资源大小:30529k
文件大小:39k
源码类别:

嵌入式Linux

开发平台:

Unix_Linux

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