From 34146c3f9293db845c9cde2f38b3e9b02c92c2a3 Mon Sep 17 00:00:00 2001 From: Vineeth Vijayan Date: Mon, 12 Sep 2022 00:47:52 +0200 Subject: [PATCH] zdev: modify man-pages to update the site information MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the new site parameter help information in the man-pages of both chzdev and lszdev. Reviewed-by: Peter Oberparleiter Signed-off-by: Vineeth Vijayan Signed-off-by: Jan Höppner --- zdev/man/chzdev.8 | 64 +++++++++++++++++++++++++++++++++++++++++++++++ zdev/man/lszdev.8 | 55 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) diff --git a/zdev/man/chzdev.8 b/zdev/man/chzdev.8 index 92988649..da78ac81 100644 --- a/zdev/man/chzdev.8 +++ b/zdev/man/chzdev.8 @@ -82,6 +82,42 @@ when a device driver is loaded. .PP By default chzdev applies changes to both the active and the persistent configuration. +. +.SS "Site-specific configurations" +In some high-availability setups, root and boot disks of a Linux installation are +copied to remote sites that can take over execution of a Linux workload in case of +an outage of the original site. A +.B site +in this context is an execution environment such as an +.B LPAR or +.B z/VM guest. +Each site may provide a different set of devices, or require different parameters to be +applied per device. + +chzdev supports site-specific device configuration for up to +.B 10 +sites. Each site is identified by a number in the range 0 to 9. You can provide a separate +set of persistent device configuration for each site. The IPL Load Parameter value specified +during boot determines the currently active site. Only the device configuration of the active +site is applied during boot and when new devices become available. A common configuration can +be provided that is applied when no site-specific configuration is available for a device in +the active site. + +You can use the +.B --site +parameter to configure devices for a specific site only. Configuration actions without a site +parameter apply to the common configuration. + +Linux supports the following IPL Load Parameter values for selecting the active site: + +.B S + Site with number becomes the active site. Example: "S2" specifies site 2 as active site. + +.B SS + The Subchannel-Set ID (SSID) of the IPL device specifies the number of the active site. + +If no site is specified in the Load Parameter, only the common configuration is applied. + .PP . .SS "Tool actions" @@ -583,6 +619,34 @@ Apply changes to persistent configuration only. The persistent configuration is put into effect when the system boots, or when a device becomes available, or when a device driver is loaded. +.PP +. +.OD site "s" "SITE-ID" +Apply the persistent configuration to the specified site only. + +This option can be used to configure the device in such a way that, the +same configuration can be used on multiple different sites with different +device hardwares, without any modification. With the site information, we +can add different configurations which are specific to different sites. Where +each site represents different systems or different hardware devices which +are even located in different locations. +For example, having +the configuration of main-site or failover-site in the same place, but these +configurations used only on the respective sites. Currently a user can define +10 different configurations for 10 different sites with +.I SITE-ID +0 to 9. + +The configuration settings is put into effect only on the system with the +site number which is mentioned in +.I SITE-ID. + +This parameter is only effective only for persistent configurations and for +dasd device-types. + +.B Example: +.CL chzdev -ep 0.0.f001 --site 3 + .PP . .OD quiet "q" "" diff --git a/zdev/man/lszdev.8 b/zdev/man/lszdev.8 index 12f20efb..9d35a271 100644 --- a/zdev/man/lszdev.8 +++ b/zdev/man/lszdev.8 @@ -74,9 +74,43 @@ of the currently running system, the persistent configuration stored in configuration files, and the auto-configuration that is provided by some machine types to automatically enable I/O devices. .PP +Persistent configuration data is of two different types. Site-specific configuration +and common-configuration. Common configuration refers to the persistent configuration +which is not bound to any site. In many use cases, this configuration is being +used as a fallback configuration. +Refer the +.B site +section below to learn more about site-specific configuration. +.PP By default lszdev displays information from both the active and the persistent configuration, and, if available, from the auto-configuration. .PP +.SS Output Format +In list format, lszdev uses values with the following meaning for the persistent colums (PERS): + +.B yes +.CL A persistent, non-site specific configuration exists; No site specific configurations available. + +.B no +.CL No persistent configurations is available. + +.B auto +.CL Machine-provided auto-configuration is available. + +.B s +.CL A site-specific configuration is available for site-id n. + +.B s+ +.CL Site specific configurations are available for multiple sites. + +.B Example + +.CL TYPE ID ON PERS NAMES +.CL dasd-eckd 0.0.f001 no s+ dasda +.CL dasd-eckd 0.0.f002 no s4 dasdb +.CL dasd-eckd 0.0.f003 no no +.CL qeth 0.0.1200:0.0.1201:0.0.1202 no yes encbdf0 + . . .SH TYPE @@ -123,6 +157,7 @@ comma (,). .PP . . + .SH SELECTION In addition to specifying devices by their ID, you can also select devices by their state or by the Linux functions they provide. @@ -292,6 +327,7 @@ Display detailed information. Displays detailed information about the configuration of the selected device or device type. Specifying \-\-info twice will display additional device information. + .PP . .OD list-columns "l" "" @@ -392,6 +428,25 @@ escaped by placing a slash in front of it. List information from the persistent configuration only. Restricts output to information obtained from configuration files. +.PP +. +.OD site "s" "SITE-ID" +List the persistent configuration from the specified site only. + +The resulted persistent configuration details are filtered based on the +.ID SITE-ID +value. The site specific information can be found in a basic lszdev output. +For example, the PERS column may show "s+" which indicates that the device +has multiple configurations for multiple sites, and "sn" where 'n' is an +number between 0 to 9, which indicates that the persistent configuration +for the device is available only for site 'n'. + +.B Example: + +.CL lszdev --site 3 +.CL lszdev -i --site 2 +.CL lszdev f001 --site 9 + .PP . .OD quiet "q" ""