Documentation/powerpc/vas-api.rst

1 .. SPDX-License-Identifier: GPL-2.0
2 .. _VAS-API:
12 allows both userspace and kernel communicate to co-processor
14 unit comprises of one or more hardware engines or co-processor types
21 Requests to the GZIP engine must be formatted as a co-processor Request
37 Application access to the GZIP engine is provided through
38 /dev/crypto/nx-gzip device node implemented by the VAS/NX device driver.
39 An application must open the /dev/crypto/nx-gzip device to obtain a file
42 engine for this process. Once a connection is established, the application
44 request queue into the application's virtual address space.
46 The application can then submit one or more requests to the engine by
58 NX-GZIP Device Node
61 There is one /dev/crypto/nx-gzip node in the system and it provides
63 /dev/crypto/nx-gzip are:
67 	* mmap() the engine's request queue into application's virtual
68 	  address space (i.e. get a paste_address for the co-processor
78 Although a system may have several instances of the NX co-processor
80 /dev/crypto/nx-gzip device node in the system. When the nx-gzip device
86 Applications may chose a specific instance of the NX co-processor using
91 	 https://github.com/abalib/power-gzip
96 Open /dev/crypto/nx-gzip
99 The nx-gzip device should be opened for read and write. No special
111 a connection with NX co-processor engine:
117 			__s16   vas_id; /* specific instance of vas or -1
127 		If '-1' is passed, kernel will make a best-effort attempt
129 		select the specific VAS instance, refer
146 	returns -1 and sets the errno variable to indicate the error.
164 mmap() NX-GZIP device
167 The mmap() system call for a NX-GZIP device fd returns a paste_address
168 that the application can use to copy/paste its CRB to the hardware engines.
174 	Only restrictions on mmap for a NX-GZIP device fd are:
194 like /proc/device-tree/vas@* or /proc/device-tree/xscom@*/vas@*.
195 Determine the chip or VAS instance and use the corresponding ibm,vas-id
196 property value in this node to select specific VAS instance.
203 https://openpowerfoundation.org/?resource_lib=power-isa-version-3-0
208 Applications should format requests to the co-processor using the
209 co-processor Request Block (CRBs). Refer NX-GZIP user's manual for the format
217 co-processor Status Block (CSB) flags. NX updates status in CSB after each
218 request is processed. Refer NX-GZIP user's manual for the format of CSB and
223 fault. Page fault can happen if an application passes invalid addresses or
232 When an application receives translation error, it can touch or access
234 the application can resend this request to NX.
245 In the case of multi-thread applications, NX send windows can be shared
253 (tgid). It is up to the application whether to ignore or handle these
256 NX-GZIP User's Manual:
257 https://github.com/libnxz/power-gzip/blob/master/doc/power_nx_gzip_um.pdf
270 			fd = open("/dev/crypto/nx-gzip", O_RDWR);
272 				fprintf(stderr, "open nx-gzip failed\n");
273 				return -1;
277 			txattr.vas_id = -1
290 				return -errno;
304 	Refer https://github.com/libnxz/power-gzip for tests or more