Added some line breaks in BOOTPROTO section.
[opensuse:chkpnts-sysconfig.git] / doc / README.s390
1  Configuration notes for hwcfg-files on S/390:
2 ===============================================
3
4 The directory /etc/sysconfig/hardware contains configuration files for
5 all configured devices. These configuration files contain variables
6 which control the loading of the required modules for this device as
7 well as the parameter necessary for configuration.
8
9
10  Configuration names
11 ---------------------
12
13 The file name of the hwcfg-* files determines the type and the
14 location/bus-id of the device uniquely. Only those devices for which a
15 matching hwcfg-* file is found will be configured.
16 The naming is as following:
17
18        <config file>:=hwcfg-<config name>
19        <config name>:=<device type>-<device description>
20 <device description>:={id-<identifier>|bus-<bus location>|event-<event type>}
21       <bus location>:=<bus name>[-<bus id>]
22             <bus id>:={<bus number>[.<bus id>]|<device id>[:<lun>]}
23         <event type>:= Any valid string except "id", "bus" and "type"
24         <identifier>:= Any string valid as a filename
25           <bus name>:= Any valid string
26         <bus number>:= Any valid string
27          <device id>:= Any valid string
28                <lun>:= Any valid string
29
30 Currently supported on S/390:
31
32 - <device description>:={bus-<bus location>|id-<identifier>}
33 - <bus name>:=ccw
34 - <device type>:={ctc|lcs|qeth|zfcp|dasd}
35 - <bus id>:=%1x.%1x.%04x
36
37 As an example a CTC device with Channel-IDs 0x0600 and 0x0601 would be
38 configured by a matching configuration file
39
40 hwcfg-ctc-bus-ccw-0.0.0600
41
42 Please note that the bus location _must_ be a four-characters
43 hexadecimal number.
44
45  Configuration variables
46 -------------------------
47
48 The configuration information for a device is stored in variables. The
49 variables and their meaning depend on the architecture.
50
51 Common variables are:
52
53 STARTMODE        'auto' or 'manual'
54                  Selects whether this device should be configured
55                  automatically or manually
56 MODULE           The name of the module to be loaded
57 MODULE_OPTIONS   Options to be passed to the module, if any
58 MODULE_UNLOAD    'yes' or 'no'
59                  Set to yes if this module can be unloaded
60
61 Configuration script selection:
62 SCRIPTUP         Script to be called if hwup was invoked manually
63                  (or with events which have no event specific script)
64 SCRIPTUP_<event> Script to be called if hwup has been invoked
65                  from hotplug event handler for event <event>
66 SCRIPTDOWN       Script to be called if hwdown was invoked manually
67                  (or with events which have no event specific script)
68 SCRIPTDOWN_<event> Script to be called if hwdown has been invoked
69                   from hotplug event handler for event <event>
70
71 S390-specific variables are:
72 CCW_CHAN_NUM    number of channels for this device
73 CCW_CHAN_IDS    Channels to use for this device, separated by spaces.
74                 Total number of channels must match CCW_CHAN_NUM.
75 CCW_CHAN_MODE   Mode for this device;
76                 - protocol for CTC/ESCON
77                 - port for LCS
78                 - portname for OSA/Express
79 DASD_USE_DIAG   Enable DIAG access for this device (if available)
80 ZFCP_LUNS       Configured zfcp devices, specified as <wwpn>:<lun>
81 QETH_OPTIONS    Additional options for OSA/Express or HiperSockets
82 QETH_IPA_TAKEOVER Enable IP address takeover for OSA/Express or HiperSockets
83
84  Interface to hotplug events
85 -----------------------------
86
87 The device configuration may react on hotplug events. Each hotplug
88 event upon which the configuration should be invoked is select by a
89 variable SCRIPT{UP|DOWN}_<event>, which contains the script to be called for
90 this event.
91
92 On S/390, the following events are handled:
93
94 ccw:       Send upon detecting a new CCW device.
95            Should be set to
96            SCRIPTUP_ccw="hwup-ccw"
97
98 ccwgroup:  Send after a device has been grouped (CTC, QETH).
99            Setting depends on the device:
100            for CTC:
101                SCRIPTUP_ccwgroup="hwup-ctc"
102            for QETH:
103                SCRIPTUP_ccwgroup="hwup-qeth"
104
105 scsi_host: Send after a zfcp device has been activated.
106            Setting for the zfcp device:
107                SCRIPT_scsi_host="hwup-zfcp"
108
109
110  Helper scripts
111 ----------------
112 The scripts call via SCRIPT{UP|DOWN}_<event> are located in
113
114 /etc/sysconfig/hardware/scripts
115
116 They will be called /sbin/hw{up|down}.
117
118 The calling sequence for hwup is:
119 - Read configuration file
120 - Load any specified module
121 - Call any event specific script
122 - Call the generic script if no event specific script was specified.
123
124 The calling sequence for hwdown is:
125 - Read configuration file
126 - Call any event specific script
127 - Call any generic script if no event specific script was specified.
128 - Unload the specified module if MODULE_UNLOAD="yes"
129
130  Example configuration files
131 -------------------------------
132
133 Example configuration files for the currently recognized
134 devices can be found in
135
136 /etc/sysconfig/hardware/skel
137
138 They are meant to be used as templates for the local configuration.
139
140 Device-specific configuration files:
141 -LCS devices:
142     The default configuration file is in
143     /etc/sysconfig/hardware/skel/hwcfg-lcs; 
144     the name of the configuration file should be
145     hwcfg-lcs-bus-ccw-0.0.<devid>
146     where <devid> is the start id for the device 
147     (read channel). The write channel should be 
148     <devid + 1>; other configurations are not supported.
149
150     The channels for this device should be stored in
151     CCW_CHAN_IDS="<devid> <devid + 1>"
152
153     The port number for LCS can be set with
154     CCW_CHAN_MODE=<port>
155
156 -CTC devices:
157     The default configuration file is in
158     /etc/sysconfig/hardware/skel/hwcfg-ctc; 
159     the name of the configuration file should be
160     hwcfg-ctc-bus-ccw-0.0.<devid>
161     where <devid> is the start id for the device 
162     (read channel). The write channel should be 
163     <devid + 1>; other configurations are not supported.
164
165     The channels for this device should be stored in
166     CCW_CHAN_IDS="<devid> <devid + 1>"
167
168     The protocol mode for CTC can be set with
169     CCW_CHAN_MODE=<protocol>
170
171 -QETH devices:
172     The default configuration file is in
173     /etc/sysconfig/hardware/skel/hwcfg-qeth;
174     the name of the configuration file should be
175     hwcfg-qeth-bus-ccw-0.0.<devid>
176     where <devid> is the channel id of the first (read) channel.
177     The other channels (write and data) are assumed at channel ids
178     <devid + 1> and <devid + 2>. Other configurations are not
179     supported.
180
181     The channels for this device should be stored in
182     CCW_CHAN_IDS="<devid> <devid + 1> <devid + 2>"
183
184     For OSA-Express devices the port name should be added
185     to the configuration file with the line
186     CCW_CHAN_MODE=<port name>
187
188     Additional options can be set with the QETH_OPTIONS variable,
189     the format is QETH_OPTIONS="opt1=val1 opt2=val2". Valid options
190     are
191     - add_hhlen
192     - broadcast_mode
193     - buffer_count
194     - canonical_macaddr
195     - checksumming
196     - fake_broadcast
197     - fake_ll
198     - priority_queueing
199     - route4
200     - route6
201     The value always has be set, so to enable fake_ll and hardware
202     checksumming the corresponding QETH_OPTIONS line would be
203     QETH_OPTIONS="fake_ll=1 checksumming=hw_checksumming"
204
205     IP address takeover can be enabled with the line
206     QETH_IPA_TAKEOVER=1
207
208     Further configuration of the qeth adapter should be done with
209     qethconf(8).
210
211 -IUCV devices:
212     The default configuration file is in 
213     /etc/sysconfig/hardware/skel/hwcfg-iucv;
214     the name of the configuration file should be
215     hwcfg-iucv-id-<Link name>
216     No further configuration is needed.
217
218 - DASD devices:
219     The default configuration file is in
220     /etc/sysconfig/hardware/skel/hwcfg-dasd-eckd;
221     the name of the configuration file should be
222     hwcfg-dasd-bus-ccw-0.0.<devid>
223     For DIAG access set the parameter
224     DASD_USE_DIAG=1
225
226 - zfcp devices:
227     The default configuration file is in
228     /etc/sysconfig/hardware/skel/hwcfg-zfcp;
229     the name of the configuration file should be
230     hwcfg-zfcp-bus-ccw-0.0.<devid>
231     The zfcp WWPNs and LUNs for this device are
232     set with the ZFCP_LUNS parameter. It has the syntax
233     ZFCP_LUNS="0x<wwpn1>:0x<lun1>
234     0x<wwpn2>:0x<lun2>
235     ...
236     0x<wwpnN>:0x<lunN>"
237     where <wwpnX> and <lunX> is a 64-bit hexadecimal number.
238
239 Please note:
240 On creating your own configuration files it is imperative that the
241 configuration scripts specified are identical to those in the default
242 configuration. As the device configuration on S/390 is done
243 exclusively via those configuration scripts, omitting or
244 changing the configuration scripts might result in an unbootable
245 system.
246 Before changing or adapting any of those scripts, be sure to be
247 familiar with the manual configuration of those devices.
248 Also it is adviseable to test the configuration with running
249 hwup/hwdown manually before rebooting the system.
250 If any disk devices have been configured which should be available at
251 boot-time, be sure to run 'mkinitrd' and 'zipl' prior to
252 reboot. Otherwise those disks will only be available after the start
253 of the hotplug subsystem, not at boot-time.
254