libocxl
README.md
Go to the documentation of this file.
1 # Introduction
2 LibOCXL provides an access library which allows the user to implement a userspace
3 driver for an [OpenCAPI](http://opencapi.org/about/) accelerator.
4 
5 # Features
6 ## Initialization
7 AFUs may be opened using the device path or AFU name. If an multiple AFU instances
8 with the same name are available, the first AFU found with available contexts will
9 be used.
10 
11 ## Operation
12 LibOCXL provides functions to attach to an AFU and transfer data to & from the MMIO areas
13 on the AFU. AFU IRQs can be queried either by IRQ handles, or by associating a callback
14 to the IRQ.
15 
16 ## MMIO
17 Functions are provide to allow 32 & 64 bit access to the global and per-PASID MMIO
18 areas on the the AFU. Endian conversion is handled automatically.
19 
20 # Building
21 ## Prerequisites
22 1. A GCC toolchain with libc (if cross compiling), crosstool-ng can build a suitable toolchain
23  if your cross compiler does not include libc.
24 2. [Doxygen](http://www.stack.nl/~dimitri/doxygen/) 1.8.14 or later. Earlier versions will work, but don't generate enums in the man
25  pages correctly.
26 3. [Astyle](http://astyle.sourceforge.net/), if you plan on submitting patches.
27 4. [CPPCheck](http://cppcheck.sourceforge.net/), if you plan on submitting patches.
28 5. [libFUSE](https://github.com/libfuse/libfuse), to run tests
29 
30 ## Included Dependencies
31 - OCXL headers from the [Linux kernel](https://www.kernel.org/)
32 
33 ## Build Instructions (Local build)
34 - `make`
35 - `PREFIX=/usr/local make install`
36 
37 ## Build Instructions (Cross compilation)
38 - `export CROSS_COMPILE=/path/to/compiler/bin/powerpc64le-unknown-linux-gnu-`
39 - `make`
40 
41 
42 # Usage
43 A typical use of libocxl will follow this pattern:
44 
45 1. **Setup:** optionally turn on error reporting for the open calls: ocxl\_enable\_messages().
46 2. **Open the device:** ocxl\_afu\_open() if an AFU name is used, or ocxl\_afu\_open\_from\_dev() if
47  a device path is used. Optionally turn on error reporting for the AFU: ocxl\_afu\_enable\_messages().
48 3. **Allocate IRQs:** ocxl\_irq\_alloc(). This returns a sequential per-AFU IRQ number.
49  An opaque pointer is associated with the
50  handle in which the caller can store additional information. This is not used by OpenCAPI,
51  but is passed as part of the event information to provide additional context to the IRQ handler.
52 4. **Configure global MMIO:** Some AFUs may have a global MMIO area, which will contain configuration
53  information that will affect all PASIDs on the AFU. Use ocxl\_mmio\_map() to make the area available,
54  then use ocxl\_mmio\_write32() and ocxl\_mmio\_write64() to write the information.
55 5. **Configure the per-PASID MMIO:** Some AFUs support multiple contexts, and each context will
56  get it's own MMIO area for configuration and communication. Typical information that may
57  be communicated across the MMIO interface include IRQ handles (obtained with
58  ocxl\_irq\_get\_handle()), and pointers to AFU-specific
59  data structures. Use ocxl\_mmio\_map to make the area available, then use
60  ocxl\_mmio\_write32() and ocxl\_mmio\_write64() to write the information.
61 6. **Attach the AFU context to the process:** Use ocxl\_afu\_attach() to make the process's address space available
62  to the AFU context, allowing it to read & write to the process's memory.
63 7. **Signal the AFU to do some work:** This is typically done via a write into the per-PASID MMIO area.
64 8. **Handle AFU IRQs:** Pending IRQs can be queried using ocxl\_afu\_event\_check(). An IRQ event
65  contains the IRQ number, the info pointer assigned when activated, the 64 bit IRQ handle, and
66  the number of times the IRQ has been triggered since last checked.
67 9. **Read results:** Work completion may be signalled by the AFU via an IRQ, or by writing to
68  the MMIO area. Typically, bulk data should be written to a pointer passed to the AFU, however,
69  small quantities of data may be read from an MMIO area using ocxl\_mmio\_read32() and
70  ocxl\_mmio\_read64().
71 10. **Termination:** ocxl\_afu\_close() will free all resources associated with an AFU handle.
72 
73 # Development
74 Patches may be submitted via Github pull requests. Please prepare your patches
75 by running `make precommit` before committing your work, and addressing any warnings & errors reported.
76 Patches must compile cleanly with the latest stable version of GCC to be accepted.