1.. SPDX-License-Identifier: GPL-2.0
2.. _VAS-API:
3
4===================================================
5Virtual Accelerator Switchboard (VAS) userspace API
6===================================================
7
8Introduction
9============
10
11Power9 processor introduced Virtual Accelerator Switchboard (VAS) which
12allows both userspace and kernel communicate to co-processor
13(hardware accelerator) referred to as the Nest Accelerator (NX). The NX
14unit comprises of one or more hardware engines or co-processor types
15such as 842 compression, GZIP compression and encryption. On power9,
16userspace applications will have access to only GZIP Compression engine
17which supports ZLIB and GZIP compression algorithms in the hardware.
18
19To communicate with NX, kernel has to establish a channel or window and
20then requests can be submitted directly without kernel involvement.
21Requests to the GZIP engine must be formatted as a co-processor Request
22Block (CRB) and these CRBs must be submitted to the NX using COPY/PASTE
23instructions to paste the CRB to hardware address that is associated with
24the engine's request queue.
25
26The GZIP engine provides two priority levels of requests: Normal and
27High. Only Normal requests are supported from userspace right now.
28
29This document explains userspace API that is used to interact with
30kernel to setup channel / window which can be used to send compression
31requests directly to NX accelerator.
32
33
34Overview
35========
36
37Application access to the GZIP engine is provided through
38/dev/crypto/nx-gzip device node implemented by the VAS/NX device driver.
39An application must open the /dev/crypto/nx-gzip device to obtain a file
40descriptor (fd). Then should issue VAS_TX_WIN_OPEN ioctl with this fd to
41establish connection to the engine. It means send window is opened on GZIP
42engine for this process. Once a connection is established, the application
43should use the mmap() system call to map the hardware address of engine's
44request queue into the application's virtual address space.
45
46The application can then submit one or more requests to the engine by
47using copy/paste instructions and pasting the CRBs to the virtual address
48(aka paste_address) returned by mmap(). User space can close the
49established connection or send window by closing the file descriptor
50(close(fd)) or upon the process exit.
51
52Note that applications can send several requests with the same window or
53can establish multiple windows, but one window for each file descriptor.
54
55Following sections provide additional details and references about the
56individual steps.
57
58NX-GZIP Device Node
59===================
60
61There is one /dev/crypto/nx-gzip node in the system and it provides
62access to all GZIP engines in the system. The only valid operations on
63/dev/crypto/nx-gzip are:
64
65	* open() the device for read and write.
66	* issue VAS_TX_WIN_OPEN ioctl
67	* mmap() the engine's request queue into application's virtual
68	  address space (i.e. get a paste_address for the co-processor
69	  engine).
70	* close the device node.
71
72Other file operations on this device node are undefined.
73
74Note that the copy and paste operations go directly to the hardware and
75do not go through this device. Refer COPY/PASTE document for more
76details.
77
78Although a system may have several instances of the NX co-processor
79engines (typically, one per P9 chip) there is just one
80/dev/crypto/nx-gzip device node in the system. When the nx-gzip device
81node is opened, Kernel opens send window on a suitable instance of NX
82accelerator. It finds CPU on which the user process is executing and
83determine the NX instance for the corresponding chip on which this CPU
84belongs.
85
86Applications may chose a specific instance of the NX co-processor using
87the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below.
88
89A userspace library libnxz is available here but still in development:
90
91	 https://github.com/abalib/power-gzip
92
93Applications that use inflate / deflate calls can link with libnxz
94instead of libz and use NX GZIP compression without any modification.
95
96Open /dev/crypto/nx-gzip
97========================
98
99The nx-gzip device should be opened for read and write. No special
100privileges are needed to open the device. Each window corresponds to one
101file descriptor. So if the userspace process needs multiple windows,
102several open calls have to be issued.
103
104See open(2) system call man pages for other details such as return values,
105error codes and restrictions.
106
107VAS_TX_WIN_OPEN ioctl
108=====================
109
110Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish
111a connection with NX co-processor engine:
112
113	::
114
115		struct vas_tx_win_open_attr {
116			__u32   version;
117			__s16   vas_id; /* specific instance of vas or -1
118						for default */
119			__u16   reserved1;
120			__u64   flags;	/* For future use */
121			__u64   reserved2[6];
122		};
123
124	version:
125		The version field must be currently set to 1.
126	vas_id:
127		If '-1' is passed, kernel will make a best-effort attempt
128		to assign an optimal instance of NX for the process. To
129		select the specific VAS instance, refer
130		"Discovery of available VAS engines" section below.
131
132	flags, reserved1 and reserved2[6] fields are for future extension
133	and must be set to 0.
134
135	The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as
136	follows::
137
138		#define VAS_MAGIC 'v'
139		#define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1,
140						struct vas_tx_win_open_attr)
141
142		struct vas_tx_win_open_attr attr;
143		rc = ioctl(fd, VAS_TX_WIN_OPEN, &attr);
144
145	The VAS_TX_WIN_OPEN ioctl returns 0 on success. On errors, it
146	returns -1 and sets the errno variable to indicate the error.
147
148	Error conditions:
149
150		======	================================================
151		EINVAL	fd does not refer to a valid VAS device.
152		EINVAL	Invalid vas ID
153		EINVAL	version is not set with proper value
154		EEXIST	Window is already opened for the given fd
155		ENOMEM	Memory is not available to allocate window
156		ENOSPC	System has too many active windows (connections)
157			opened
158		EINVAL	reserved fields are not set to 0.
159		======	================================================
160
161	See the ioctl(2) man page for more details, error codes and
162	restrictions.
163
164mmap() NX-GZIP device
165=====================
166
167The mmap() system call for a NX-GZIP device fd returns a paste_address
168that the application can use to copy/paste its CRB to the hardware engines.
169
170	::
171
172		paste_addr = mmap(addr, size, prot, flags, fd, offset);
173
174	Only restrictions on mmap for a NX-GZIP device fd are:
175
176		* size should be PAGE_SIZE
177		* offset parameter should be 0ULL
178
179	Refer to mmap(2) man page for additional details/restrictions.
180	In addition to the error conditions listed on the mmap(2) man
181	page, can also fail with one of the following error codes:
182
183		======	=============================================
184		EINVAL	fd is not associated with an open window
185			(i.e mmap() does not follow a successful call
186			to the VAS_TX_WIN_OPEN ioctl).
187		EINVAL	offset field is not 0ULL.
188		======	=============================================
189
190Discovery of available VAS engines
191==================================
192
193Each available VAS instance in the system will have a device tree node
194like /proc/device-tree/vas@* or /proc/device-tree/xscom@*/vas@*.
195Determine the chip or VAS instance and use the corresponding ibm,vas-id
196property value in this node to select specific VAS instance.
197
198Copy/Paste operations
199=====================
200
201Applications should use the copy and paste instructions to send CRB to NX.
202Refer section 4.4 in PowerISA for Copy/Paste instructions:
203https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0
204
205CRB Specification and use NX
206============================
207
208Applications should format requests to the co-processor using the
209co-processor Request Block (CRBs). Refer NX-GZIP user's manual for the format
210of CRB and use NX from userspace such as sending requests and checking
211request status.
212
213NX Fault handling
214=================
215
216Applications send requests to NX and wait for the status by polling on
217co-processor Status Block (CSB) flags. NX updates status in CSB after each
218request is processed. Refer NX-GZIP user's manual for the format of CSB and
219status flags.
220
221In case if NX encounters translation error (called NX page fault) on CSB
222address or any request buffer, raises an interrupt on the CPU to handle the
223fault. Page fault can happen if an application passes invalid addresses or
224request buffers are not in memory. The operating system handles the fault by
225updating CSB with the following data::
226
227	csb.flags = CSB_V;
228	csb.cc = CSB_CC_FAULT_ADDRESS;
229	csb.ce = CSB_CE_TERMINATION;
230	csb.address = fault_address;
231
232When an application receives translation error, it can touch or access
233the page that has a fault address so that this page will be in memory. Then
234the application can resend this request to NX.
235
236If the OS can not update CSB due to invalid CSB address, sends SEGV signal
237to the process who opened the send window on which the original request was
238issued. This signal returns with the following siginfo struct::
239
240	siginfo.si_signo = SIGSEGV;
241	siginfo.si_errno = EFAULT;
242	siginfo.si_code = SEGV_MAPERR;
243	siginfo.si_addr = CSB address;
244
245In the case of multi-thread applications, NX send windows can be shared
246across all threads. For example, a child thread can open a send window,
247but other threads can send requests to NX using this window. These
248requests will be successful even in the case of OS handling faults as long
249as CSB address is valid. If the NX request contains an invalid CSB address,
250the signal will be sent to the child thread that opened the window. But if
251the thread is exited without closing the window and the request is issued
252using this window. the signal will be issued to the thread group leader
253(tgid). It is up to the application whether to ignore or handle these
254signals.
255
256NX-GZIP User's Manual:
257https://github.com/libnxz/power-gzip/blob/master/doc/power_nx_gzip_um.pdf
258
259Simple example
260==============
261
262	::
263
264		int use_nx_gzip()
265		{
266			int rc, fd;
267			void *addr;
268			struct vas_setup_attr txattr;
269
270			fd = open("/dev/crypto/nx-gzip", O_RDWR);
271			if (fd < 0) {
272				fprintf(stderr, "open nx-gzip failed\n");
273				return -1;
274			}
275			memset(&txattr, 0, sizeof(txattr));
276			txattr.version = 1;
277			txattr.vas_id = -1
278			rc = ioctl(fd, VAS_TX_WIN_OPEN,
279					(unsigned long)&txattr);
280			if (rc < 0) {
281				fprintf(stderr, "ioctl() n %d, error %d\n",
282						rc, errno);
283				return rc;
284			}
285			addr = mmap(NULL, 4096, PROT_READ|PROT_WRITE,
286					MAP_SHARED, fd, 0ULL);
287			if (addr == MAP_FAILED) {
288				fprintf(stderr, "mmap() failed, errno %d\n",
289						errno);
290				return -errno;
291			}
292			do {
293				//Format CRB request with compression or
294				//uncompression
295				// Refer tests for vas_copy/vas_paste
296				vas_copy((&crb, 0, 1);
297				vas_paste(addr, 0, 1);
298				// Poll on csb.flags with timeout
299				// csb address is listed in CRB
300			} while (true)
301			close(fd) or window can be closed upon process exit
302		}
303
304	Refer https://github.com/libnxz/power-gzip for tests or more
305	use cases.
306