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