0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. _VAS-API:
0003
0004 ===================================================
0005 Virtual Accelerator Switchboard (VAS) userspace API
0006 ===================================================
0007
0008 Introduction
0009 ============
0010
0011 Power9 processor introduced Virtual Accelerator Switchboard (VAS) which
0012 allows both userspace and kernel communicate to co-processor
0013 (hardware accelerator) referred to as the Nest Accelerator (NX). The NX
0014 unit comprises of one or more hardware engines or co-processor types
0015 such as 842 compression, GZIP compression and encryption. On power9,
0016 userspace applications will have access to only GZIP Compression engine
0017 which supports ZLIB and GZIP compression algorithms in the hardware.
0018
0019 To communicate with NX, kernel has to establish a channel or window and
0020 then requests can be submitted directly without kernel involvement.
0021 Requests to the GZIP engine must be formatted as a co-processor Request
0022 Block (CRB) and these CRBs must be submitted to the NX using COPY/PASTE
0023 instructions to paste the CRB to hardware address that is associated with
0024 the engine's request queue.
0025
0026 The GZIP engine provides two priority levels of requests: Normal and
0027 High. Only Normal requests are supported from userspace right now.
0028
0029 This document explains userspace API that is used to interact with
0030 kernel to setup channel / window which can be used to send compression
0031 requests directly to NX accelerator.
0032
0033
0034 Overview
0035 ========
0036
0037 Application access to the GZIP engine is provided through
0038 /dev/crypto/nx-gzip device node implemented by the VAS/NX device driver.
0039 An application must open the /dev/crypto/nx-gzip device to obtain a file
0040 descriptor (fd). Then should issue VAS_TX_WIN_OPEN ioctl with this fd to
0041 establish connection to the engine. It means send window is opened on GZIP
0042 engine for this process. Once a connection is established, the application
0043 should use the mmap() system call to map the hardware address of engine's
0044 request queue into the application's virtual address space.
0045
0046 The application can then submit one or more requests to the engine by
0047 using copy/paste instructions and pasting the CRBs to the virtual address
0048 (aka paste_address) returned by mmap(). User space can close the
0049 established connection or send window by closing the file descriptior
0050 (close(fd)) or upon the process exit.
0051
0052 Note that applications can send several requests with the same window or
0053 can establish multiple windows, but one window for each file descriptor.
0054
0055 Following sections provide additional details and references about the
0056 individual steps.
0057
0058 NX-GZIP Device Node
0059 ===================
0060
0061 There is one /dev/crypto/nx-gzip node in the system and it provides
0062 access to all GZIP engines in the system. The only valid operations on
0063 /dev/crypto/nx-gzip are:
0064
0065 * open() the device for read and write.
0066 * issue VAS_TX_WIN_OPEN ioctl
0067 * mmap() the engine's request queue into application's virtual
0068 address space (i.e. get a paste_address for the co-processor
0069 engine).
0070 * close the device node.
0071
0072 Other file operations on this device node are undefined.
0073
0074 Note that the copy and paste operations go directly to the hardware and
0075 do not go through this device. Refer COPY/PASTE document for more
0076 details.
0077
0078 Although a system may have several instances of the NX co-processor
0079 engines (typically, one per P9 chip) there is just one
0080 /dev/crypto/nx-gzip device node in the system. When the nx-gzip device
0081 node is opened, Kernel opens send window on a suitable instance of NX
0082 accelerator. It finds CPU on which the user process is executing and
0083 determine the NX instance for the corresponding chip on which this CPU
0084 belongs.
0085
0086 Applications may chose a specific instance of the NX co-processor using
0087 the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below.
0088
0089 A userspace library libnxz is available here but still in development:
0090
0091 https://github.com/abalib/power-gzip
0092
0093 Applications that use inflate / deflate calls can link with libnxz
0094 instead of libz and use NX GZIP compression without any modification.
0095
0096 Open /dev/crypto/nx-gzip
0097 ========================
0098
0099 The nx-gzip device should be opened for read and write. No special
0100 privileges are needed to open the device. Each window corresponds to one
0101 file descriptor. So if the userspace process needs multiple windows,
0102 several open calls have to be issued.
0103
0104 See open(2) system call man pages for other details such as return values,
0105 error codes and restrictions.
0106
0107 VAS_TX_WIN_OPEN ioctl
0108 =====================
0109
0110 Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish
0111 a connection with NX co-processor engine:
0112
0113 ::
0114
0115 struct vas_tx_win_open_attr {
0116 __u32 version;
0117 __s16 vas_id; /* specific instance of vas or -1
0118 for default */
0119 __u16 reserved1;
0120 __u64 flags; /* For future use */
0121 __u64 reserved2[6];
0122 };
0123
0124 version:
0125 The version field must be currently set to 1.
0126 vas_id:
0127 If '-1' is passed, kernel will make a best-effort attempt
0128 to assign an optimal instance of NX for the process. To
0129 select the specific VAS instance, refer
0130 "Discovery of available VAS engines" section below.
0131
0132 flags, reserved1 and reserved2[6] fields are for future extension
0133 and must be set to 0.
0134
0135 The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as
0136 follows::
0137
0138 #define VAS_MAGIC 'v'
0139 #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1,
0140 struct vas_tx_win_open_attr)
0141
0142 struct vas_tx_win_open_attr attr;
0143 rc = ioctl(fd, VAS_TX_WIN_OPEN, &attr);
0144
0145 The VAS_TX_WIN_OPEN ioctl returns 0 on success. On errors, it
0146 returns -1 and sets the errno variable to indicate the error.
0147
0148 Error conditions:
0149
0150 ====== ================================================
0151 EINVAL fd does not refer to a valid VAS device.
0152 EINVAL Invalid vas ID
0153 EINVAL version is not set with proper value
0154 EEXIST Window is already opened for the given fd
0155 ENOMEM Memory is not available to allocate window
0156 ENOSPC System has too many active windows (connections)
0157 opened
0158 EINVAL reserved fields are not set to 0.
0159 ====== ================================================
0160
0161 See the ioctl(2) man page for more details, error codes and
0162 restrictions.
0163
0164 mmap() NX-GZIP device
0165 =====================
0166
0167 The mmap() system call for a NX-GZIP device fd returns a paste_address
0168 that the application can use to copy/paste its CRB to the hardware engines.
0169
0170 ::
0171
0172 paste_addr = mmap(addr, size, prot, flags, fd, offset);
0173
0174 Only restrictions on mmap for a NX-GZIP device fd are:
0175
0176 * size should be PAGE_SIZE
0177 * offset parameter should be 0ULL
0178
0179 Refer to mmap(2) man page for additional details/restrictions.
0180 In addition to the error conditions listed on the mmap(2) man
0181 page, can also fail with one of the following error codes:
0182
0183 ====== =============================================
0184 EINVAL fd is not associated with an open window
0185 (i.e mmap() does not follow a successful call
0186 to the VAS_TX_WIN_OPEN ioctl).
0187 EINVAL offset field is not 0ULL.
0188 ====== =============================================
0189
0190 Discovery of available VAS engines
0191 ==================================
0192
0193 Each available VAS instance in the system will have a device tree node
0194 like /proc/device-tree/vas@* or /proc/device-tree/xscom@*/vas@*.
0195 Determine the chip or VAS instance and use the corresponding ibm,vas-id
0196 property value in this node to select specific VAS instance.
0197
0198 Copy/Paste operations
0199 =====================
0200
0201 Applications should use the copy and paste instructions to send CRB to NX.
0202 Refer section 4.4 in PowerISA for Copy/Paste instructions:
0203 https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0
0204
0205 CRB Specification and use NX
0206 ============================
0207
0208 Applications should format requests to the co-processor using the
0209 co-processor Request Block (CRBs). Refer NX-GZIP user's manual for the format
0210 of CRB and use NX from userspace such as sending requests and checking
0211 request status.
0212
0213 NX Fault handling
0214 =================
0215
0216 Applications send requests to NX and wait for the status by polling on
0217 co-processor Status Block (CSB) flags. NX updates status in CSB after each
0218 request is processed. Refer NX-GZIP user's manual for the format of CSB and
0219 status flags.
0220
0221 In case if NX encounters translation error (called NX page fault) on CSB
0222 address or any request buffer, raises an interrupt on the CPU to handle the
0223 fault. Page fault can happen if an application passes invalid addresses or
0224 request buffers are not in memory. The operating system handles the fault by
0225 updating CSB with the following data::
0226
0227 csb.flags = CSB_V;
0228 csb.cc = CSB_CC_FAULT_ADDRESS;
0229 csb.ce = CSB_CE_TERMINATION;
0230 csb.address = fault_address;
0231
0232 When an application receives translation error, it can touch or access
0233 the page that has a fault address so that this page will be in memory. Then
0234 the application can resend this request to NX.
0235
0236 If the OS can not update CSB due to invalid CSB address, sends SEGV signal
0237 to the process who opened the send window on which the original request was
0238 issued. This signal returns with the following siginfo struct::
0239
0240 siginfo.si_signo = SIGSEGV;
0241 siginfo.si_errno = EFAULT;
0242 siginfo.si_code = SEGV_MAPERR;
0243 siginfo.si_addr = CSB adress;
0244
0245 In the case of multi-thread applications, NX send windows can be shared
0246 across all threads. For example, a child thread can open a send window,
0247 but other threads can send requests to NX using this window. These
0248 requests will be successful even in the case of OS handling faults as long
0249 as CSB address is valid. If the NX request contains an invalid CSB address,
0250 the signal will be sent to the child thread that opened the window. But if
0251 the thread is exited without closing the window and the request is issued
0252 using this window. the signal will be issued to the thread group leader
0253 (tgid). It is up to the application whether to ignore or handle these
0254 signals.
0255
0256 NX-GZIP User's Manual:
0257 https://github.com/libnxz/power-gzip/blob/master/doc/power_nx_gzip_um.pdf
0258
0259 Simple example
0260 ==============
0261
0262 ::
0263
0264 int use_nx_gzip()
0265 {
0266 int rc, fd;
0267 void *addr;
0268 struct vas_setup_attr txattr;
0269
0270 fd = open("/dev/crypto/nx-gzip", O_RDWR);
0271 if (fd < 0) {
0272 fprintf(stderr, "open nx-gzip failed\n");
0273 return -1;
0274 }
0275 memset(&txattr, 0, sizeof(txattr));
0276 txattr.version = 1;
0277 txattr.vas_id = -1
0278 rc = ioctl(fd, VAS_TX_WIN_OPEN,
0279 (unsigned long)&txattr);
0280 if (rc < 0) {
0281 fprintf(stderr, "ioctl() n %d, error %d\n",
0282 rc, errno);
0283 return rc;
0284 }
0285 addr = mmap(NULL, 4096, PROT_READ|PROT_WRITE,
0286 MAP_SHARED, fd, 0ULL);
0287 if (addr == MAP_FAILED) {
0288 fprintf(stderr, "mmap() failed, errno %d\n",
0289 errno);
0290 return -errno;
0291 }
0292 do {
0293 //Format CRB request with compression or
0294 //uncompression
0295 // Refer tests for vas_copy/vas_paste
0296 vas_copy((&crb, 0, 1);
0297 vas_paste(addr, 0, 1);
0298 // Poll on csb.flags with timeout
0299 // csb address is listed in CRB
0300 } while (true)
0301 close(fd) or window can be closed upon process exit
0302 }
0303
0304 Refer https://github.com/libnxz/power-gzip for tests or more
0305 use cases.
