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 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 descriptior 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 https://github.com/abalib/power-gzip 91 92Applications that use inflate / deflate calls can link with libnxz 93instead of libz and use NX GZIP compression without any modification. 94 95Open /dev/crypto/nx-gzip 96======================== 97 98The nx-gzip device should be opened for read and write. No special 99privileges are needed to open the device. Each window corresponds to one 100file descriptor. So if the userspace process needs multiple windows, 101several open calls have to be issued. 102 103See open(2) system call man pages for other details such as return values, 104error codes and restrictions. 105 106VAS_TX_WIN_OPEN ioctl 107===================== 108 109Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish 110a connection with NX co-processor engine: 111 112 :: 113 struct vas_tx_win_open_attr { 114 __u32 version; 115 __s16 vas_id; /* specific instance of vas or -1 116 for default */ 117 __u16 reserved1; 118 __u64 flags; /* For future use */ 119 __u64 reserved2[6]; 120 }; 121 122 version: The version field must be currently set to 1. 123 vas_id: If '-1' is passed, kernel will make a best-effort attempt 124 to assign an optimal instance of NX for the process. To 125 select the specific VAS instance, refer 126 "Discovery of available VAS engines" section below. 127 128 flags, reserved1 and reserved2[6] fields are for future extension 129 and must be set to 0. 130 131 The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as 132 follows: 133 #define VAS_MAGIC 'v' 134 #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, 135 struct vas_tx_win_open_attr) 136 137 struct vas_tx_win_open_attr attr; 138 rc = ioctl(fd, VAS_TX_WIN_OPEN, &attr); 139 140 The VAS_TX_WIN_OPEN ioctl returns 0 on success. On errors, it 141 returns -1 and sets the errno variable to indicate the error. 142 143 Error conditions: 144 EINVAL fd does not refer to a valid VAS device. 145 EINVAL Invalid vas ID 146 EINVAL version is not set with proper value 147 EEXIST Window is already opened for the given fd 148 ENOMEM Memory is not available to allocate window 149 ENOSPC System has too many active windows (connections) 150 opened 151 EINVAL reserved fields are not set to 0. 152 153 See the ioctl(2) man page for more details, error codes and 154 restrictions. 155 156mmap() NX-GZIP device 157===================== 158 159The mmap() system call for a NX-GZIP device fd returns a paste_address 160that the application can use to copy/paste its CRB to the hardware engines. 161 :: 162 163 paste_addr = mmap(addr, size, prot, flags, fd, offset); 164 165 Only restrictions on mmap for a NX-GZIP device fd are: 166 * size should be PAGE_SIZE 167 * offset parameter should be 0ULL 168 169 Refer to mmap(2) man page for additional details/restrictions. 170 In addition to the error conditions listed on the mmap(2) man 171 page, can also fail with one of the following error codes: 172 173 EINVAL fd is not associated with an open window 174 (i.e mmap() does not follow a successful call 175 to the VAS_TX_WIN_OPEN ioctl). 176 EINVAL offset field is not 0ULL. 177 178Discovery of available VAS engines 179================================== 180 181Each available VAS instance in the system will have a device tree node 182like /proc/device-tree/vas@* or /proc/device-tree/xscom@*/vas@*. 183Determine the chip or VAS instance and use the corresponding ibm,vas-id 184property value in this node to select specific VAS instance. 185 186Copy/Paste operations 187===================== 188 189Applications should use the copy and paste instructions to send CRB to NX. 190Refer section 4.4 in PowerISA for Copy/Paste instructions: 191https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0 192 193CRB Specification and use NX 194============================ 195 196Applications should format requests to the co-processor using the 197co-processor Request Block (CRBs). Refer NX-GZIP user's manual for the format 198of CRB and use NX from userspace such as sending requests and checking 199request status. 200 201NX Fault handling 202================= 203 204Applications send requests to NX and wait for the status by polling on 205co-processor Status Block (CSB) flags. NX updates status in CSB after each 206request is processed. Refer NX-GZIP user's manual for the format of CSB and 207status flags. 208 209In case if NX encounters translation error (called NX page fault) on CSB 210address or any request buffer, raises an interrupt on the CPU to handle the 211fault. Page fault can happen if an application passes invalid addresses or 212request buffers are not in memory. The operating system handles the fault by 213updating CSB with the following data: 214 215 csb.flags = CSB_V; 216 csb.cc = CSB_CC_TRANSLATION; 217 csb.ce = CSB_CE_TERMINATION; 218 csb.address = fault_address; 219 220When an application receives translation error, it can touch or access 221the page that has a fault address so that this page will be in memory. Then 222the application can resend this request to NX. 223 224If the OS can not update CSB due to invalid CSB address, sends SEGV signal 225to the process who opened the send window on which the original request was 226issued. This signal returns with the following siginfo struct: 227 228 siginfo.si_signo = SIGSEGV; 229 siginfo.si_errno = EFAULT; 230 siginfo.si_code = SEGV_MAPERR; 231 siginfo.si_addr = CSB adress; 232 233In the case of multi-thread applications, NX send windows can be shared 234across all threads. For example, a child thread can open a send window, 235but other threads can send requests to NX using this window. These 236requests will be successful even in the case of OS handling faults as long 237as CSB address is valid. If the NX request contains an invalid CSB address, 238the signal will be sent to the child thread that opened the window. But if 239the thread is exited without closing the window and the request is issued 240using this window. the signal will be issued to the thread group leader 241(tgid). It is up to the application whether to ignore or handle these 242signals. 243 244NX-GZIP User's Manual: 245https://github.com/libnxz/power-gzip/blob/master/power_nx_gzip_um.pdf 246 247Simple example 248============== 249 250 :: 251 int use_nx_gzip() 252 { 253 int rc, fd; 254 void *addr; 255 struct vas_setup_attr txattr; 256 257 fd = open("/dev/crypto/nx-gzip", O_RDWR); 258 if (fd < 0) { 259 fprintf(stderr, "open nx-gzip failed\n"); 260 return -1; 261 } 262 memset(&txattr, 0, sizeof(txattr)); 263 txattr.version = 1; 264 txattr.vas_id = -1 265 rc = ioctl(fd, VAS_TX_WIN_OPEN, 266 (unsigned long)&txattr); 267 if (rc < 0) { 268 fprintf(stderr, "ioctl() n %d, error %d\n", 269 rc, errno); 270 return rc; 271 } 272 addr = mmap(NULL, 4096, PROT_READ|PROT_WRITE, 273 MAP_SHARED, fd, 0ULL); 274 if (addr == MAP_FAILED) { 275 fprintf(stderr, "mmap() failed, errno %d\n", 276 errno); 277 return -errno; 278 } 279 do { 280 //Format CRB request with compression or 281 //uncompression 282 // Refer tests for vas_copy/vas_paste 283 vas_copy((&crb, 0, 1); 284 vas_paste(addr, 0, 1); 285 // Poll on csb.flags with timeout 286 // csb address is listed in CRB 287 } while (true) 288 close(fd) or window can be closed upon process exit 289 } 290 291 Refer https://github.com/abalib/power-gzip for tests or more 292 use cases. 293