1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
.\" Copyright IBM Corp. 2022
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\"
.\" Macro for inserting an option description prologue.
.\" .OD <long> [<short>] [args]
.de OD
. ds args "
. if !'\\$3'' .as args \fI\\$3\fP
. if !'\\$4'' .as args \\$4
. if !'\\$5'' .as args \fI\\$5\fP
. if !'\\$6'' .as args \\$6
. if !'\\$7'' .as args \fI\\$7\fP
. PD 0
. if !'\\$2'' .IP "\fB\-\\$2\fP \\*[args]" 4
. if !'\\$1'' .IP "\fB\-\-\\$1\fP \\*[args]" 4
. PD
..
.
.TH zpcictl 8 "Mar 2022" s390-tools zpcictl
.
.SH NAME
zpcictl - Manage PCI devices on IBM Z
.
.
.SH SYNOPSIS
.B "zpcictl"
.I "OPTIONS"
.I "DEVICE"
.
.
.SH DESCRIPTION
Use
.B zpcictl
to manage PCI devices on the IBM Z platform. In particular,
use this command to report defective PCI devices to the Support Element (SE).
.B Note:
For NVMe devices additional data (such as S.M.A.R.T. data) is collected and sent
with any error handling action. For this extendend data collection, the
smartmontools must be installed.
.PP
.
.
.SH DEVICE
A PCI slot address (e.g. 0000:00:00.0) or the main device node of an NVMe
device (e.g.
.I /dev/nvme0
).
.
.
.SH OPTIONS
.SS Error Handling Options
.OD reset "" "DEVICE"
Reset and re-initialize the PCI device and report a device error to the Support
Element (SE). The reset consists of a controlled shutdown and a subsequent
re-enabling of the device from the shut off state. This process destroys and
then re-creates higher level interfaces such as network interfaces and block
devices. This reset is disruptive and often requires manual intervention on
multiple layers. In particular, network interfaces that are part of a bonded
interface must be re-added to the bond after the reset. Similarly, block
devices backed by an NVMe that are part of a software RAID must be re-synced by
re-adding to the RAID after resetting the NVMe.
Use this reset option only if the less disruptive automatic recovery mechanism
is not supported by your kernel or it failed to restore the device's
functionality. Unsuccessful automatic recovery can result in kernel messages
indicating required manual intervention. If the device is malfunctioning
without automatic recovery being triggered, consider using the \fB--reset-fw\fR
option to trigger a less disruptive automatic recovery through
a firmware-driven reset.
.PP
.
.OD reset-fw "" "DEVICE"
Reset the PCI device using a firmware-driven reset that also reports a device
error on the Support Element (SE). If supported by your kernel, automatic recovery
re-initializes the device after the firmware reports a successful device reset.
Use this option if the device is malfunctioning and automatic recovery is
supported by the kernel but was not triggered. This condition can occur if the
error is not detected by the low level PCI interfaces. A successful automatic
recovery after the firmware-driven reset, is less disruptive than the full
reset that is performed by the \fB--reset\fR option. Other than the full reset,
the automatic recovery does not completely shut down the device and re-create
it from the shut down state. Instead, it works with the device driver to
restore the device in place. Thus, higher level interfaces such as network
interfaces and block devices remain intact. In particular, with this type of
reset high availability mechanisms like a bonded network interface or
a software RAID can transparently re-integrate the recovered device. For
example, after a failure and recovery, a software RAID can resync a stroage
device or a network interface can be re-integrated in a bond. In contrast to
a complete shut down, the device driver remains active and informs higher
layers of both the occurrence of an error state and the eventual recovery.
.PP
.
.OD deconfigure "" "DEVICE"
Deconfigure the PCI device and prepare for any repair action. This action
changes the status of the PCI device from configured to reserved.
.PP
.
.OD report-error "" "DEVICE"
Report any device error for the PCI device.
The device is marked as defective but no further action is taken.
.PP
.
.SS General Options
.OD help "h" ""
Print usage information, then exit.
.PP
.
.OD version "v" ""
Print version information, then exit.
.PP
|