docs: s390: convert docs to ReST and rename to *.rst

			others).

	ccw_timeout_log	[S390]

			See Documentation/s390/CommonIO for details.

			See Documentation/s390/common_io.rst for details.

	cgroup_disable=	[KNL] Disable a particular controller

			Format: {name of the controller(s) to disable}

				/selinux/checkreqprot.

	cio_ignore=	[S390]

			See Documentation/s390/CommonIO for details.

			See Documentation/s390/common_io.rst for details.

	clk_ignore_unused

			[CLK]

			Prevents the clock framework from automatically gating

although they are not the focus of this document.

Some additional information can also be found in the kernel source under

Documentation/s390/driver-model.txt.

Documentation/s390/driver-model.rst.

The css bus

===========

* Standard I/O subchannels, for use by the system. They have a child

  device on the ccw bus and are described below.

* I/O subchannels bound to the vfio-ccw driver. See

  Documentation/s390/vfio-ccw.txt.

  Documentation/s390/vfio-ccw.rst.

* Message subchannels. No Linux driver currently exists.

* CHSC subchannels (at most one). The chsc subchannel driver can be used

  to send asynchronous chsc commands.

===============================

IBM 3270 Display System support

===============================

This file describes the driver that supports local channel attachment

of IBM 3270 devices.  It consists of three sections:

	* Introduction

	* Installation

	* Operation

INTRODUCTION.

Introduction

============

This paper describes installing and operating 3270 devices under

Linux/390.  A 3270 device is a block-mode rows-and-columns terminal of

You may have 3270s in-house and not know it.  If you're using the

VM-ESA operating system, define a 3270 to your virtual machine by using

the command "DEF GRAF <hex-address>"  This paper presumes you will be

defining four 3270s with the CP/CMS commands

defining four 3270s with the CP/CMS commands:

	DEF GRAF 620

	DEF GRAF 621

	DEF GRAF 622

	DEF GRAF 623

	- DEF GRAF 620

	- DEF GRAF 621

	- DEF GRAF 622

	- DEF GRAF 623

Your network connection from VM-ESA allows you to use x3270, tn3270, or

another 3270 emulator, started from an xterm window on your PC or

dialed-in x3270.

INSTALLATION.

Installation

============

You install the driver by installing a patch, doing a kernel build, and

running the configuration script (config3270.sh, in this directory).

at boot time to a 3270 if it is a 3215.

In brief, these are the steps:

	1. Install the tub3270 patch

	2. (If a module) add a line to a file in /etc/modprobe.d/*.conf

	2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf`

	3. (If VM) define devices with DEF GRAF

	4. Reboot

	5. Configure

To test that everything works, assuming VM and x3270,

	1. Bring up an x3270 window.

	2. Use the DIAL command in that window.

	3. You should immediately see a Linux login screen.

	1.  The 3270 driver is a part of the official Linux kernel

	source.  Build a tree with the kernel source and any necessary

	patches.  Then do

	patches.  Then do::

		make oldconfig

		(If you wish to disable 3215 console support, edit

		.config; change CONFIG_TN3215's value to "n";

		make modules_install

	2. (Perform this step only if you have configured tub3270 as a

	module.)  Add a line to a file /etc/modprobe.d/*.conf to automatically

	module.)  Add a line to a file `/etc/modprobe.d/*.conf` to automatically

	load the driver when it's needed.  With this line added, you will see

	login prompts appear on your 3270s as soon as boot is complete (or

	with emulated 3270s, as soon as you dial into your vm guest using the

	command "DIAL <vmguestname>").  Since the line-mode major number is

	227, the line to add should be:

	227, the line to add should be::

		alias char-major-227 tub3270

	3. Define graphic devices to your vm guest machine, if you

	haven't already.  Define them before you reboot (reipl):

		DEFINE GRAF 620

		DEFINE GRAF 621

		DEFINE GRAF 622

		DEFINE GRAF 623

		- DEFINE GRAF 620

		- DEFINE GRAF 621

		- DEFINE GRAF 622

		- DEFINE GRAF 623

	4. Reboot.  The reboot process scans hardware devices, including

	3270s, and this enables the tub3270 driver once loaded to respond

	changes to /etc/inittab.

	Then notify /sbin/init that /etc/inittab has changed, by issuing

	the telinit command with the q operand:

	the telinit command with the q operand::

		cd Documentation/s390

		sh config3270.sh

		sh /tmp/mkdev3270

	This should be sufficient for your first time.  If your 3270

	configuration has changed and you're reusing config3270, you

	should follow these steps:

	should follow these steps::

		Change 3270 configuration

		Reboot

		Run config3270 and /tmp/mkdev3270

	1. Bring up an x3270 window, or use an actual hardware 3278 or

	3279, or use the 3270 emulator of your choice.  You would be

	running the emulator on your PC or workstation.  You would use

	the command, for example,

	the command, for example::

		x3270 vm-esa-domain-name &

	if you wanted a 3278 Model 4 with 43 rows of 80 columns, the

	default model number.  The driver does not take advantage of

	extended attributes.

	2. Use the DIAL command instead of the LOGIN command to connect

	to one of the virtual 3270s you defined with the DEF GRAF

	commands:

	commands::

		dial my-vm-guest-name

	3. You should immediately see a login prompt from your

	Wrong major number?  Wrong minor number?  There's your

	problem!

	D. Do you get the message

	D. Do you get the message::

		 "HCPDIA047E my-vm-guest-name 0620 does not exist"?

	If so, you must issue the command "DEF GRAF 620" from your VM

	3215 console and then reboot the system.

OPERATION.

==========

The driver defines three areas on the 3270 screen:  the log area, the

input area, and the status area.

Running" and nothing typed, the application receives a newline.)

You may change the scrolling timeout value.  For example, the following

command line:

command line::

	echo scrolltime=60 > /proc/tty/driver/tty3270

changes the scrolling timeout value to 60 sec.  Set scrolltime to 0 if

you wish to prevent scrolling entirely.

No PF key is preassigned to cause a job suspension, but you may cause a

job suspension by typing "^Z" and hitting ENTER.  You may wish to

assign this function to a PF key.  To make PF7 cause job suspension,

execute the command:

execute the command::

	echo pf7=^z > /proc/tty/driver/tty3270

If the input you type does not end with the two characters "^n", the

invisible (such as for password entry) and it is not identical to the

current top entry.  PF10 rotates backward through the command stack;

PF11 rotates forward.  You may assign the backward function to any PF

key (or PA key, for that matter), say, PA3, with the command:

key (or PA key, for that matter), say, PA3, with the command::

	echo -e pa3=\\033k > /proc/tty/driver/tty3270

This assigns the string ESC-k to PA3.  Similarly, the string ESC-j

performs the forward function.  (Rationale:  In bash with vi-mode line

editing, ESC-k and ESC-j retrieve backward and forward history.

Is a stack size of twenty commands not to your liking?  Change it on

the fly.  To change to saving the last 100 commands, execute the

command:

command::

	echo recallsize=100 > /proc/tty/driver/tty3270

Have a command you issue frequently?  Assign it to a PF or PA key!  Use

the command

the command::

	echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270

to execute the commands mkdir foobar and cd foobar immediately when you

hit PF24.  Want to see the command line first, before you execute it?

Use the -n option of the echo command:

Use the -n option of the echo command::

	echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270

===========================

Linux for S/390 and zSeries

===========================

Common Device Support (CDS)

Device Driver I/O Support Routines

Authors : Ingo Adlung

	  Cornelia Huck

Authors:

	- Ingo Adlung

	- Cornelia Huck

Copyright, IBM Corp. 1999-2002

Introduction

============

This document describes the common device support routines for Linux/390.

Different than other hardware architectures, ESA/390 has defined a unified

Note:

  In order to write a driver for S/390, you also need to look into the interface

described in Documentation/s390/driver-model.txt.

  described in Documentation/s390/driver-model.rst.

Note for porting drivers from 2.4:

The major changes are:

* The functions use a ccw_device instead of an irq (subchannel).

* All drivers must define a ccw_driver (see driver-model.txt) and the associated

  functions.

ccw_device_get_ciw()

   get commands from extended sense data.

ccw_device_start()	

ccw_device_start_timeout()

ccw_device_start_key()

ccw_device_start_key_timeout()

ccw_device_start(), ccw_device_start_timeout(), ccw_device_start_key(), ccw_device_start_key_timeout()

   initiate an I/O request.

ccw_device_resume()

callable interface. Instead, the functional description of do_IO() also

describes the input to the device specific interrupt handler.

Note: All explanations apply also to the 64 bit architecture s390x.

Note:

	All explanations apply also to the 64 bit architecture s390x.

Common Device Support (CDS) for Linux/390 Device Drivers

========================================================

General Information

-------------------

The following chapters describe the I/O related interface routines the

Linux/390 common device support (CDS) provides to allow for device specific

linux/arch/s390/include/asm/irq.h.

Overview of CDS interface concepts

----------------------------------

Different to other hardware platforms, the ESA/390 architecture doesn't define

interrupt lines managed by a specific interrupt controller and bus systems

This call enables a device driver to get information about supported commands

from the extended SenseID data.

::

  struct ciw *

  ccw_device_get_ciw(struct ccw_device *cdev, __u32 cmd);

cdev - The ccw_device for which the command is to be retrieved.

cmd  - The command type to be retrieved.

====  ========================================================

cdev  The ccw_device for which the command is to be retrieved.

cmd   The command type to be retrieved.

====  ========================================================

ccw_device_get_ciw() returns:

NULL    - No extended data available, invalid device or command not found.

!NULL   - The command requested.

=====  ================================================================

 NULL  No extended data available, invalid device or command not found.

!NULL  The command requested.

=====  ================================================================

::

  ccw_device_start() - Initiate I/O Request

driver's interrupt handler as this is related to the rules (flags) defined

with the associated I/O request when calling ccw_device_start().

::

  int ccw_device_start(struct ccw_device *cdev,

		       struct ccw1 *cpa,

		       unsigned long intparm,

				   unsigned long flags,

				   int expires);

cdev         : ccw_device the I/O is destined for

cpa          : logical start address of channel program

user_intparm : user specific interrupt information; will be presented

============= =============================================================

cdev          ccw_device the I/O is destined for

cpa           logical start address of channel program

user_intparm  user specific interrupt information; will be presented

	      back to the device driver's interrupt handler. Allows a

	      device driver to associate the interrupt with a

	      particular I/O request.

lpm          : defines the channel path to be used for a specific I/O

lpm           defines the channel path to be used for a specific I/O

	      request. A value of 0 will make cio use the opm.

key	     : the storage key to use for the I/O (useful for operating on a

key           the storage key to use for the I/O (useful for operating on a

	      storage with a storage key != default key)

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

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

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

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

	      the running program after this and call the interrupt handler

	      with ERR_PTR(-ETIMEDOUT) as irb.

============= =============================================================

Possible flag values are:

DOIO_ALLOW_SUSPEND       - channel program may become suspended

DOIO_DENY_PREFETCH       - don't allow for CCW prefetch; usually

========================= =============================================

DOIO_ALLOW_SUSPEND        channel program may become suspended

DOIO_DENY_PREFETCH        don't allow for CCW prefetch; usually

			  this implies the channel program might

			  become modified

DOIO_SUPPRESS_INTER     - don't call the handler on intermediate status

DOIO_SUPPRESS_INTER       don't call the handler on intermediate status

========================= =============================================

The cpa parameter points to the first format 1 CCW of a channel program :

The cpa parameter points to the first format 1 CCW of a channel program::

  struct ccw1 {

	__u8  cmd_code;/* command code */

with the following CCW flags values defined:

CCW_FLAG_DC        - data chaining

CCW_FLAG_CC        - command chaining

CCW_FLAG_SLI       - suppress incorrect length

CCW_FLAG_SKIP      - skip

CCW_FLAG_PCI       - PCI

CCW_FLAG_IDA       - indirect addressing

CCW_FLAG_SUSPEND   - suspend

=================== =========================

CCW_FLAG_DC         data chaining

CCW_FLAG_CC         command chaining

CCW_FLAG_SLI        suppress incorrect length

CCW_FLAG_SKIP       skip

CCW_FLAG_PCI        PCI

CCW_FLAG_IDA        indirect addressing

CCW_FLAG_SUSPEND    suspend

=================== =========================

Via ccw_device_set_options(), the device driver may specify the following

options for the device:

DOIO_EARLY_NOTIFICATION  - allow for early interrupt notification

DOIO_REPORT_ALL          - report all interrupt conditions

========================= ======================================

DOIO_EARLY_NOTIFICATION   allow for early interrupt notification

DOIO_REPORT_ALL           report all interrupt conditions

========================= ======================================

The ccw_device_start() function returns:

      0 - successful completion or request successfully initiated

-EBUSY	- The device is currently processing a previous I/O request, or there is

======== ======================================================================

      0  successful completion or request successfully initiated

 -EBUSY  The device is currently processing a previous I/O request, or there is

	 a status pending at the device.

-ENODEV - cdev is invalid, the device is not operational or the ccw_device is

-ENODEV  cdev is invalid, the device is not operational or the ccw_device is

	 not online.

======== ======================================================================

When the I/O request completes, the CDS first level interrupt handler will

accumulate the status in a struct irb and then call the device interrupt handler.

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

first:

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

========== =================================================================

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

	   timeout value

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

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

========== =================================================================

If the concurrent sense flag in the extended status word (esw) in the irb is

set, the field erw.scnt in the esw describes the number of device specific

The device interrupt handler can use the following definitions to investigate

the primary unit check source coded in sense byte 0 :

======================= ====

SNS0_CMD_REJECT         0x80

SNS0_INTERVENTION_REQ   0x40

SNS0_BUS_OUT_CHECK      0x20

SNS0_DATA_CHECK         0x08

SNS0_OVERRUN            0x04

SNS0_INCOMPL_DOMAIN     0x01

======================= ====

Depending on the device status, multiple of those values may be set together.

Please refer to the device specific documentation for details.

The irb->scsw.cstat field provides the (accumulated) subchannel status :

SCHN_STAT_PCI            - program controlled interrupt

SCHN_STAT_INCORR_LEN     - incorrect length

SCHN_STAT_PROG_CHECK     - program check

SCHN_STAT_PROT_CHECK     - protection check

SCHN_STAT_CHN_DATA_CHK   - channel data check

SCHN_STAT_CHN_CTRL_CHK   - channel control check

SCHN_STAT_INTF_CTRL_CHK  - interface control check

SCHN_STAT_CHAIN_CHECK    - chaining check

========================= ============================

SCHN_STAT_PCI             program controlled interrupt

SCHN_STAT_INCORR_LEN      incorrect length

SCHN_STAT_PROG_CHECK      program check

SCHN_STAT_PROT_CHECK      protection check

SCHN_STAT_CHN_DATA_CHK    channel data check

SCHN_STAT_CHN_CTRL_CHK    channel control check

SCHN_STAT_INTF_CTRL_CHK   interface control check

SCHN_STAT_CHAIN_CHECK     chaining check

========================= ============================

The irb->scsw.dstat field provides the (accumulated) device status :

DEV_STAT_ATTENTION   - attention

DEV_STAT_STAT_MOD    - status modifier

DEV_STAT_CU_END      - control unit end

DEV_STAT_BUSY        - busy

DEV_STAT_CHN_END     - channel end

DEV_STAT_DEV_END     - device end

DEV_STAT_UNIT_CHECK  - unit check

DEV_STAT_UNIT_EXCEP  - unit exception

===================== =================

DEV_STAT_ATTENTION    attention

DEV_STAT_STAT_MOD     status modifier

DEV_STAT_CU_END       control unit end

DEV_STAT_BUSY         busy

DEV_STAT_CHN_END      channel end

DEV_STAT_DEV_END      device end

DEV_STAT_UNIT_CHECK   unit check

DEV_STAT_UNIT_EXCEP   unit exception

===================== =================

Please see the ESA/390 Principles of Operation manual for details on the

individual flag meanings.

is suspended. In order to resume channel program execution the CIO layer

provides the ccw_device_resume() routine.

::

  int ccw_device_resume(struct ccw_device *cdev);

cdev - ccw_device the resume operation is requested for

====  ================================================

cdev  ccw_device the resume operation is requested for

====  ================================================

The ccw_device_resume() function returns:

        0  - suspended channel program is resumed

-EBUSY     - status pending

-ENODEV    - cdev invalid or not-operational subchannel 

-EINVAL    - resume function not applicable  

-ENOTCONN  - there is no I/O request pending for completion 

=========   ==============================================

	0   suspended channel program is resumed

   -EBUSY   status pending

  -ENODEV   cdev invalid or not-operational subchannel

  -EINVAL   resume function not applicable

-ENOTCONN   there is no I/O request pending for completion

=========   ==============================================

Usage Notes:

Please have a look at the ccw_device_start() usage notes for more details on

suspended channel programs.

ccw_device_halt() must be called disabled and with the ccw device lock held.

::

  int ccw_device_halt(struct ccw_device *cdev,

		      unsigned long intparm);

cdev    : ccw_device the halt operation is requested for

intparm : interruption parameter; value is only used if no I/O

=======  =====================================================

cdev     ccw_device the halt operation is requested for

intparm  interruption parameter; value is only used if no I/O

	 is outstanding, otherwise the intparm associated with

	 the I/O request is returned

=======  =====================================================

The ccw_device_halt() function returns:

      0 - request successfully initiated

-EBUSY  - the device is currently busy, or status pending.

-ENODEV - cdev invalid.

-EINVAL - The device is not operational or the ccw device is not online.

=======  ==============================================================

      0  request successfully initiated

-EBUSY   the device is currently busy, or status pending.

-ENODEV  cdev invalid.

-EINVAL  The device is not operational or the ccw device is not online.

=======  ==============================================================

Usage Notes:

read to a network device (with or without PCI flag) a ccw_device_halt()

is required to end the pending operation.

::

  ccw_device_clear() - Terminage I/O Request Processing

In order to terminate all I/O processing at the subchannel, the clear subchannel

ccw_device_clear() must be called disabled and with the ccw device lock held.

::

  int ccw_device_clear(struct ccw_device *cdev, unsigned long intparm);

cdev:	 ccw_device the clear operation is requested for

intparm: interruption parameter (see ccw_device_halt())

======= ===============================================

cdev    ccw_device the clear operation is requested for

intparm interruption parameter (see ccw_device_halt())

======= ===============================================

The ccw_device_clear() function returns:

      0 - request successfully initiated

-ENODEV - cdev invalid

-EINVAL - The device is not operational or the ccw device is not online.

=======  ==============================================================

      0  request successfully initiated

-ENODEV  cdev invalid

-EINVAL  The device is not operational or the ccw device is not online.

=======  ==============================================================

Miscellaneous Support Routines

------------------------------

This chapter describes various routines to be used in a Linux/390 device

driver programming environment.

Get the address of the device specific lock. This is then used in

spin_lock() / spin_unlock() calls.

::

  __u8 ccw_device_get_path_mask(struct ccw_device *cdev);

S/390 common I/O-Layer - command line parameters, procfs and debugfs entries

============================================================================

======================

S/390 common I/O-Layer

======================

command line parameters, procfs and debugfs entries

===================================================

Command line parameters

-----------------------

  keywords can be used to refer to the CCW based boot device and CCW console

  device respectively (these are probably useful only when combined with the '!'

  operator). The '!' operator will cause the I/O-layer to _not_ ignore a device.

  The command line is parsed from left to right.

  The command line

  is parsed from left to right.

  For example::

  For example, 

	cio_ignore=0.0.0023-0.0.0042,0.0.4711

  will ignore all devices ranging from 0.0.0023 to 0.0.0042 and the device

  0.0.4711, if detected.

  As another example,

  As another example::

	cio_ignore=all,!0.0.4711,!0.0.fd00-0.0.fd02

  will ignore all devices but 0.0.4711, 0.0.fd00, 0.0.fd01, 0.0.fd02.

  By default, no devices are ignored.

  devices.

  For example, if devices 0.0.0023 to 0.0.0042 and 0.0.4711 are ignored,

  - echo free 0.0.0030-0.0.0032 > /proc/cio_ignore

    will un-ignore devices 0.0.0030 to 0.0.0032 and will leave devices 0.0.0023

    to 0.0.002f, 0.0.0033 to 0.0.0042 and 0.0.4711 ignored;

	disappears and then reappears, it will then be ignored. To make

	known devices go away, you need the "purge" command (see below).

  For example,

  For example::

	"echo add 0.0.a000-0.0.accc, 0.0.af00-0.0.afff > /proc/cio_ignore"

  will add 0.0.a000-0.0.accc and 0.0.af00-0.0.afff to the list of ignored

  devices.

  You can remove already known but now ignored devices via

  You can remove already known but now ignored devices via::

	"echo purge > /proc/cio_ignore"

  All devices ignored but still registered and not online (= not in use)

  will be deregistered and thus removed from the system.

  The level of logging can be changed to be more or less verbose by piping to

  /sys/kernel/debug/s390dbf/cio_*/level a number between 0 and 6; see the

  documentation on the S/390 debug feature (Documentation/s390/s390dbf.txt)

  documentation on the S/390 debug feature (Documentation/s390/s390dbf.rst)

  for details.