2 LibOCXL provides an access library which allows the user to implement a userspace
3 driver for an [OpenCAPI](http://opencapi.org/about/) accelerator.
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
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
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.
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
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
30 ## Included Dependencies
31 - OCXL headers from the [Linux kernel](https://www.kernel.org/)
33 ## Build Instructions (Local build)
35 - `PREFIX=/usr/local make install`
37 ## Build Instructions (Cross compilation)
38 - `export CROSS_COMPILE=/path/to/compiler/bin/powerpc64le-unknown-linux-gnu-`
43 A typical use of libocxl will follow this pattern:
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
71 10. **Termination:** ocxl\_afu\_close() will free all resources associated with an AFU handle.
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.