diff options
Diffstat (limited to 'Documentation/powerpc/vas-api.rst')
| -rw-r--r-- | Documentation/powerpc/vas-api.rst | 305 |
1 files changed, 0 insertions, 305 deletions
diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst deleted file mode 100644 index a9625a2fa0..0000000000 --- a/Documentation/powerpc/vas-api.rst +++ /dev/null @@ -1,305 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. _VAS-API: - -=================================================== -Virtual Accelerator Switchboard (VAS) userspace API -=================================================== - -Introduction -============ - -Power9 processor introduced Virtual Accelerator Switchboard (VAS) which -allows both userspace and kernel communicate to co-processor -(hardware accelerator) referred to as the Nest Accelerator (NX). The NX -unit comprises of one or more hardware engines or co-processor types -such as 842 compression, GZIP compression and encryption. On power9, -userspace applications will have access to only GZIP Compression engine -which supports ZLIB and GZIP compression algorithms in the hardware. - -To communicate with NX, kernel has to establish a channel or window and -then requests can be submitted directly without kernel involvement. -Requests to the GZIP engine must be formatted as a co-processor Request -Block (CRB) and these CRBs must be submitted to the NX using COPY/PASTE -instructions to paste the CRB to hardware address that is associated with -the engine's request queue. - -The GZIP engine provides two priority levels of requests: Normal and -High. Only Normal requests are supported from userspace right now. - -This document explains userspace API that is used to interact with -kernel to setup channel / window which can be used to send compression -requests directly to NX accelerator. - - -Overview -======== - -Application access to the GZIP engine is provided through -/dev/crypto/nx-gzip device node implemented by the VAS/NX device driver. -An application must open the /dev/crypto/nx-gzip device to obtain a file -descriptor (fd). Then should issue VAS_TX_WIN_OPEN ioctl with this fd to -establish connection to the engine. It means send window is opened on GZIP -engine for this process. Once a connection is established, the application -should use the mmap() system call to map the hardware address of engine's -request queue into the application's virtual address space. - -The application can then submit one or more requests to the engine by -using copy/paste instructions and pasting the CRBs to the virtual address -(aka paste_address) returned by mmap(). User space can close the -established connection or send window by closing the file descriptor -(close(fd)) or upon the process exit. - -Note that applications can send several requests with the same window or -can establish multiple windows, but one window for each file descriptor. - -Following sections provide additional details and references about the -individual steps. - -NX-GZIP Device Node -=================== - -There is one /dev/crypto/nx-gzip node in the system and it provides -access to all GZIP engines in the system. The only valid operations on -/dev/crypto/nx-gzip are: - - * open() the device for read and write. - * issue VAS_TX_WIN_OPEN ioctl - * mmap() the engine's request queue into application's virtual - address space (i.e. get a paste_address for the co-processor - engine). - * close the device node. - -Other file operations on this device node are undefined. - -Note that the copy and paste operations go directly to the hardware and -do not go through this device. Refer COPY/PASTE document for more -details. - -Although a system may have several instances of the NX co-processor -engines (typically, one per P9 chip) there is just one -/dev/crypto/nx-gzip device node in the system. When the nx-gzip device -node is opened, Kernel opens send window on a suitable instance of NX -accelerator. It finds CPU on which the user process is executing and -determine the NX instance for the corresponding chip on which this CPU -belongs. - -Applications may chose a specific instance of the NX co-processor using -the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below. - -A userspace library libnxz is available here but still in development: - - https://github.com/abalib/power-gzip - -Applications that use inflate / deflate calls can link with libnxz -instead of libz and use NX GZIP compression without any modification. - -Open /dev/crypto/nx-gzip -======================== - -The nx-gzip device should be opened for read and write. No special -privileges are needed to open the device. Each window corresponds to one -file descriptor. So if the userspace process needs multiple windows, -several open calls have to be issued. - -See open(2) system call man pages for other details such as return values, -error codes and restrictions. - -VAS_TX_WIN_OPEN ioctl -===================== - -Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish -a connection with NX co-processor engine: - - :: - - struct vas_tx_win_open_attr { - __u32 version; - __s16 vas_id; /* specific instance of vas or -1 - for default */ - __u16 reserved1; - __u64 flags; /* For future use */ - __u64 reserved2[6]; - }; - - version: - The version field must be currently set to 1. - vas_id: - If '-1' is passed, kernel will make a best-effort attempt - to assign an optimal instance of NX for the process. To - select the specific VAS instance, refer - "Discovery of available VAS engines" section below. - - flags, reserved1 and reserved2[6] fields are for future extension - and must be set to 0. - - The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as - follows:: - - #define VAS_MAGIC 'v' - #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, - struct vas_tx_win_open_attr) - - struct vas_tx_win_open_attr attr; - rc = ioctl(fd, VAS_TX_WIN_OPEN, &attr); - - The VAS_TX_WIN_OPEN ioctl returns 0 on success. On errors, it - returns -1 and sets the errno variable to indicate the error. - - Error conditions: - - ====== ================================================ - EINVAL fd does not refer to a valid VAS device. - EINVAL Invalid vas ID - EINVAL version is not set with proper value - EEXIST Window is already opened for the given fd - ENOMEM Memory is not available to allocate window - ENOSPC System has too many active windows (connections) - opened - EINVAL reserved fields are not set to 0. - ====== ================================================ - - See the ioctl(2) man page for more details, error codes and - restrictions. - -mmap() NX-GZIP device -===================== - -The mmap() system call for a NX-GZIP device fd returns a paste_address -that the application can use to copy/paste its CRB to the hardware engines. - - :: - - paste_addr = mmap(addr, size, prot, flags, fd, offset); - - Only restrictions on mmap for a NX-GZIP device fd are: - - * size should be PAGE_SIZE - * offset parameter should be 0ULL - - Refer to mmap(2) man page for additional details/restrictions. - In addition to the error conditions listed on the mmap(2) man - page, can also fail with one of the following error codes: - - ====== ============================================= - EINVAL fd is not associated with an open window - (i.e mmap() does not follow a successful call - to the VAS_TX_WIN_OPEN ioctl). - EINVAL offset field is not 0ULL. - ====== ============================================= - -Discovery of available VAS engines -================================== - -Each available VAS instance in the system will have a device tree node -like /proc/device-tree/vas@* or /proc/device-tree/xscom@*/vas@*. -Determine the chip or VAS instance and use the corresponding ibm,vas-id -property value in this node to select specific VAS instance. - -Copy/Paste operations -===================== - -Applications should use the copy and paste instructions to send CRB to NX. -Refer section 4.4 in PowerISA for Copy/Paste instructions: -https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0 - -CRB Specification and use NX -============================ - -Applications should format requests to the co-processor using the -co-processor Request Block (CRBs). Refer NX-GZIP user's manual for the format -of CRB and use NX from userspace such as sending requests and checking -request status. - -NX Fault handling -================= - -Applications send requests to NX and wait for the status by polling on -co-processor Status Block (CSB) flags. NX updates status in CSB after each -request is processed. Refer NX-GZIP user's manual for the format of CSB and -status flags. - -In case if NX encounters translation error (called NX page fault) on CSB -address or any request buffer, raises an interrupt on the CPU to handle the -fault. Page fault can happen if an application passes invalid addresses or -request buffers are not in memory. The operating system handles the fault by -updating CSB with the following data:: - - csb.flags = CSB_V; - csb.cc = CSB_CC_FAULT_ADDRESS; - csb.ce = CSB_CE_TERMINATION; - csb.address = fault_address; - -When an application receives translation error, it can touch or access -the page that has a fault address so that this page will be in memory. Then -the application can resend this request to NX. - -If the OS can not update CSB due to invalid CSB address, sends SEGV signal -to the process who opened the send window on which the original request was -issued. This signal returns with the following siginfo struct:: - - siginfo.si_signo = SIGSEGV; - siginfo.si_errno = EFAULT; - siginfo.si_code = SEGV_MAPERR; - siginfo.si_addr = CSB address; - -In the case of multi-thread applications, NX send windows can be shared -across all threads. For example, a child thread can open a send window, -but other threads can send requests to NX using this window. These -requests will be successful even in the case of OS handling faults as long -as CSB address is valid. If the NX request contains an invalid CSB address, -the signal will be sent to the child thread that opened the window. But if -the thread is exited without closing the window and the request is issued -using this window. the signal will be issued to the thread group leader -(tgid). It is up to the application whether to ignore or handle these -signals. - -NX-GZIP User's Manual: -https://github.com/libnxz/power-gzip/blob/master/doc/power_nx_gzip_um.pdf - -Simple example -============== - - :: - - int use_nx_gzip() - { - int rc, fd; - void *addr; - struct vas_setup_attr txattr; - - fd = open("/dev/crypto/nx-gzip", O_RDWR); - if (fd < 0) { - fprintf(stderr, "open nx-gzip failed\n"); - return -1; - } - memset(&txattr, 0, sizeof(txattr)); - txattr.version = 1; - txattr.vas_id = -1 - rc = ioctl(fd, VAS_TX_WIN_OPEN, - (unsigned long)&txattr); - if (rc < 0) { - fprintf(stderr, "ioctl() n %d, error %d\n", - rc, errno); - return rc; - } - addr = mmap(NULL, 4096, PROT_READ|PROT_WRITE, - MAP_SHARED, fd, 0ULL); - if (addr == MAP_FAILED) { - fprintf(stderr, "mmap() failed, errno %d\n", - errno); - return -errno; - } - do { - //Format CRB request with compression or - //uncompression - // Refer tests for vas_copy/vas_paste - vas_copy((&crb, 0, 1); - vas_paste(addr, 0, 1); - // Poll on csb.flags with timeout - // csb address is listed in CRB - } while (true) - close(fd) or window can be closed upon process exit - } - - Refer https://github.com/libnxz/power-gzip for tests or more - use cases. |