1 .. SPDX-License-Identifier: GPL-2.0+
2
3 ==============================================
4 IBM Virtual Management Channel Kernel Driver (
5 ==============================================
6
7 :Authors:
8 Dave Engebretsen <engebret@us.ibm.com>,
9 Adam Reznechek <adreznec@linux.vnet.ibm
10 Steven Royer <seroyer@linux.vnet.ibm.co
11 Bryant G. Ly <bryantly@linux.vnet.ibm.c
12
13 Introduction
14 ============
15
16 Note: Knowledge of virtualization technology i
17 this document.
18
19 A good reference document would be:
20
21 https://openpowerfoundation.org/wp-content/upl
22
23 The Virtual Management Channel (VMC) is a logi
24 interface between the hypervisor and a managem
25 is like a message passing interface. This mana
26 to provide an alternative to systems that use
27 Console (HMC) - based system management.
28
29 The primary hardware management solution that
30 on an appliance server named the Hardware Mana
31 packaged as an external tower or rack-mounted
32 Power Systems environment, a single HMC can ma
33 processor-based systems.
34
35 Management Application
36 ----------------------
37
38 In the management partition, a management appl
39 a system administrator to configure the system
40 characteristics via a command line interface (
41 State Transfer Application (REST API's).
42
43 The management application runs on a Linux log
44 POWER8 or newer processor-based server that is
45 System configuration, maintenance, and control
46 traditionally require an HMC can be implemente
47 application using a combination of HMC to hype
48 existing operating system methods. This tool p
49 functions implemented by the HMC and enables b
50 The set of HMC to hypervisor messages supporte
51 application component are passed to the hyperv
52 which is defined below.
53
54 The VMC enables the management partition to pr
55 functions:
56
57 - Logical Partitioning Configuration
58 - Start, and stop actions for individual parti
59 - Display of partition status
60 - Management of virtual Ethernet
61 - Management of virtual Storage
62 - Basic system management
63
64 Virtual Management Channel (VMC)
65 --------------------------------
66
67 A logical device, called the Virtual Managemen
68 for communicating between the management appli
69 basically creates the pipes that enable virtua
70 software. This device is presented to a design
71 a virtual device.
72
73 This communication device uses Command/Respons
74 Remote Direct Memory Access (RDMA) interfaces.
75 defined that must take place to establish that
76 management partition sides of the channel are
77 sending/receiving any of the protocol messages
78
79 This driver also utilizes Transport Event CRQs
80 when the hypervisor detects one of the peer pa
81 terminated, or one side has called H_FREE_CRQ
82 Two new classes of CRQ messages are introduced
83 Administrative messages are used for each part
84 communicate capabilities to their partner. HMC
85 for the actual flow of HMC messages between th
86 the hypervisor. As most HMC messages far excee
87 a virtual DMA (RMDA) of the HMC message data i
88 Interface CRQ message. Only the management par
89 operations; hypervisors never directly cause t
90
91
92 Terminology
93 -----------
94 RDMA
95 Remote Direct Memory Access is DMA tra
96 client or from the server to its partn
97 to both physical I/O to and from memor
98 to memory move operations.
99 CRQ
100 Command/Response Queue a facility whic
101 between partner partitions. Transport
102 from the hypervisor to partition are a
103
104 Example Management Partition VMC Driver Interf
105 ==============================================
106
107 This section provides an example for the manag
108 implementation where a device driver is used t
109 device. This driver consists of a new device,
110 which provides interfaces to open, close, read
111 ioctl’s against the VMC device.
112
113 VMC Interface Initialization
114 ----------------------------
115
116 The device driver is responsible for initializ
117 is loaded. It first creates and initializes th
118 VMC capabilities is performed to indicate the
119 resources available in both the management par
120 Finally, the hypervisor requests that the mana
121 initial pool of VMC buffers, one buffer for ea
122 which will be used for management application
123 Prior to completion of this initialization seq
124 EBUSY to open() calls. EIO is returned for all
125
126 ::
127
128 Management Partition Hyperv
129 CRQ INIT
130 --------------------------------------
131 CRQ INIT COMPLETE
132 <-------------------------------------
133 CAPABILITIES
134 --------------------------------------
135 CAPABILITIES RESPONSE
136 <-------------------------------------
137 ADD BUFFER (HMC IDX=0,1,..)
138 <-------------------------------------
139 ADD BUFFER RESPONSE
140 --------------------------------------
141
142 VMC Interface Open
143 ------------------
144
145 After the basic VMC channel has been initializ
146 connection can be established. The application
147 the VMC device and executes an ioctl() against
148 (32 bytes of data) for this session. If the VM
149 state, EIO will be returned for the ioctl(). T
150 new HMC session value (ranging from 1 to 255)
151 at index 0 and ranging to 254) for this HMC ID
152 RDMA of the HMC ID to the hypervisor, and then
153 message to the hypervisor to establish the ses
154 hypervisor receives this information, it sends
155 management partition to seed an initial pool o
156 connection. Finally, the hypervisor sends an I
157 message, to indicate that it is ready for norm
158 following illustrates this VMC flow:
159
160 ::
161
162 Management Partition Hyper
163 RDMA HMC ID
164 --------------------------------------
165 Interface Open
166 --------------------------------------
167 Add Buffer
168 <-------------------------------------
169 Add Buffer Response
170 --------------------------------------
171 Interface Open Response
172 <-------------------------------------
173
174 VMC Interface Runtime
175 ---------------------
176
177 During normal runtime, the management applicat
178 exchange HMC messages via the Signal VMC messa
179 sending data to the hypervisor, the management
180 write() to the VMC device, and the driver RDMA
181 and then sends a Signal Message. If a write()
182 device buffers have been made available by the
183 are currently available, EBUSY is returned in
184 write() will return EIO for all other errors,
185 state. When the hypervisor sends a message to
186 put into a VMC buffer and an Signal Message is
187 the management partition. The driver RDMA’s
188 and passes the data up to the appropriate mana
189 read() to the VMC device. The read() request b
190 available to read. The management application
191 the VMC device to become ready with data to re
192
193 ::
194
195 Management Partition Hyper
196 MSG RDMA
197 --------------------------------------
198 SIGNAL MSG
199 --------------------------------------
200 SIGNAL MSG
201 <-------------------------------------
202 MSG RDMA
203 <-------------------------------------
204
205 VMC Interface Close
206 -------------------
207
208 HMC session level connections are closed by th
209 the application layer performs a close() again
210 results in an Interface Close message flowing
211 causes the session to be terminated. The devic
212 storage allocated for buffers for this HMC con
213
214 ::
215
216 Management Partition Hyper
217 INTERFACE CLOSE
218 --------------------------------------
219 INTERFACE CLOSE RESPONSE
220 <-------------------------------------
221
222 Additional Information
223 ======================
224
225 For more information on the documentation for
226 HMC interface Buffers, and signal messages ple
227 Power Architecture Platform Reference. Section
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.