cio_ignore - Manage the I/O exclusion list

Ubuntu 22.04 LTS LPAR mode z/VM guest KVM guest

Use the cio_ignore command to specify I/O devices that are to be ignored by Linux®.

When an instance of Linux on IBM® Z boots, it senses and analyzes all available I/O devices. You can use the cio_ignore kernel parameter to specify devices that are to be ignored. This exclusion list can cover all possible devices, even devices that do not actually exist.

The cio_ignore command manages this exclusion list on a running Linux instance. You can change the exclusion list and display it in different formats. Changes made with the cio_ignore command do not persist across reboots.

cio_ignore syntax

Where:

-a or --add

adds one or more device specifications to the exclusion list.

When you add specifications for a device that is already sensed and analyzed, there is no immediate effect of adding it to the exclusion list. For example, the device still appears in the output of the lscss command and can be set online. However, if the device subsequently becomes unavailable, it is ignored when it reappears. For example, if the device is detached in z/VM®, it is ignored when it is attached again.

See the -p option about making devices that are already sensed and analyzed unavailable to Linux.

-r or --remove

removes one or more device specifications from the exclusion list.

When you remove device specifications from the exclusion list, the corresponding devices are sensed and analyzed if they exist. Where possible, the corresponding device driver is informed, and the devices become available to Linux.

<device_bus_id>

identifies a single device.

Device bus-IDs are of the form 0.<n>.<devno>, where <n> is a subchannel set ID and <devno> is a device number. If the subchannel set ID is 0, you can abbreviate the specification to the device number, with or without a leading 0x.

Example: The specifications 0.0.0190, 190, 0190, and 0x190 are all equivalent. There is no short form of 0.1.0190.

<from_device_bus_id>-<to_device_bus_id>

identifies a range of devices. <from_device_bus_id> and <to_device_bus_id> have the same format as <device_bus_id>.

-A or --add-all

adds the entire range of possible devices to the exclusion list.

See the -p option about making devices that are already sensed and analyzed unavailable to Linux.

-R or --remove-all

removes all devices from the exclusion list.

-l or --list

displays the current exclusion list.

-i or --is-ignored

checks if the specified device is on the exclusion list. The command prints an information message and completes with exit code 0 if the device is on the exclusion list. The command completes with exit code 2 if the device is not on the exclusion list.

-L or --list-not-blacklisted

displays specifications for all devices that are not in the current exclusion list.

-k or --kernel-param

returns the current exclusion list in kernel parameter format.

You can make the current exclusion list persistent across rebooting Linux by using the output of the cio_ignore command with the -k option as part of the Linux kernel parameter.

-u or --unused

discards the current exclusion list and replaces it with a specification for all devices that are not online. This includes specification for possible devices that do not actually exist.

-p or --purge

makes all devices that are in the exclusion list and that are currently offline unavailable to Linux. This option does not make devices unavailable if they are online.

-h or --help

displays help information for the command. To view the man page, enter man cio_ignore.

-v or --version

displays version information.

Examples

These examples illustrate common uses for cio_ignore.

The following command shows the current exclusion list:

# cio_ignore -l
Ignored devices:
=================
0.0.0000-0.0.7e8e
0.0.7e94-0.0.f4ff
0.0.f503-0.0.ffff
0.1.0000-0.1.ffff
0.2.0000-0.2.ffff
0.3.0000-0.3.ffff

The following command shows specifications for the devices that are not on the exclusion list:
```
# cio_ignore -L
Accessible devices:
===================
0.0.7e8f-0.0.7e93
0.0.f500-0.0.f502
```
The following command checks if 0.0.7e8f is on the exclusion list:
```
# cio_ignore -i 0.0.7e8f
Device 0.0.7e8f is not ignored.
```

The following command adds, 0.0.7e8f, to the exclusion list:

# cio_ignore -a 0.0.7e8f

The previous example then becomes:

# cio_ignore -L
Accessible devices:
===================
0.0.7e90-0.0.7e93
0.0.f500-0.0.f502

And for 0.0.7e8f in particular:

# cio_ignore -i 0.0.7e8f
Device 0.0.7e8f is ignored.

The following command shows the current exclusion list in kernel parameter format:
```
# cio_ignore -k
cio_ignore=all,!7e90-7e93,!f500-f502
```