npu2-opencapi: Add OpenCAPI OPAL API calls

Add three OPAL API calls that are required by the ocxl driver.

  - OPAL_NPU_SPA_SETUP

    The Shared Process Area (SPA) is a table containing one entry (a
    "Process Element") per memory context which can be accessed by the
    OpenCAPI device.

  - OPAL_NPU_SPA_CLEAR_CACHE

    The NPU keeps a cache of recently accessed memory contexts. When a
    Process Element is removed from the SPA, the cache for the link must be
    cleared.

  - OPAL_NPU_TL_SET

    The Transaction Layer specification defines several templates for
    messages to be exchanged on the link. During link setup, the host and
    device must negotiate what templates are supported on both sides and at
    what rates those messages can be sent.

Signed-off-by: Frederic Barrat <fbarrat@linux.vnet.ibm.com>
Signed-off-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

1 files changed, 126 insertions, 0 deletions

diff --git a/doc/opal-api/opal-npu2-opencapi-159-160-161.rst b/doc/opal-api/opal-npu2-opencapi-159-160-161.rst
new file mode 100644
index 0000000..4db3d3e
--- /dev/null
+++ b/doc/opal-api/opal-npu2-opencapi-159-160-161.rst
@@ -0,0 +1,126 @@
+.. _OPAL_NPU_SPA_SETUP:
+
+OPAL_NPU_SPA_SETUP
+==================
+
+OpenCAPI devices only.
+
+Sets up a Shared Process Area (SPA) with the Shared Process Area
+Pointer (SPAP) set to the provided address `addr`, and sets the OTL PE
+mask (used for PASID to PE handle conversion) to `PE_mask`.
+
+If `addr` is NULL, the SPA will be disabled. `addr` must be 4K aligned.
+
+Parameters
+----------
+::
+
+   uint64_t phb_id
+   int bdfn
+   uint64_t addr
+   uint64_t PE_mask
+
+``phb_id``
+   OPAL ID of PHB
+
+``bdfn``
+   Bus-Device-Function number of OpenCAPI AFU
+
+``addr``
+   Address of Shared Process Area, or NULL to disable SPA. Must be 4K aligned.
+
+``PE_mask``
+   Process Element mask for PASID to PE handle conversion
+
+Return Values
+-------------
+
+OPAL_SUCCESS
+   SPAP and PE mask were successfully set
+
+OPAL_PARAMETER
+   A provided parameter was invalid
+
+OPAL_BUSY
+   SPA is already enabled (or if addr is NULL, SPA is already disabled)
+
+.. _OPAL_NPU_SPA_CLEAR_CACHE:
+
+OPAL_NPU_SPA_CLEAR_CACHE
+========================
+
+OpenCAPI devices only.
+
+Invalidates the Process Element with the given `PE_handle` from the NPU's SPA cache.
+
+Parameters
+----------
+::
+
+   uint64_t phb_id
+   uint32_t bdfn
+   uint64_t PE_handle
+
+``phb_id``
+   OPAL ID of PHB
+
+``bdfn``
+   Bus-Device-Function number of OpenCAPI AFU
+
+``PE_handle``
+   Handle of Process Element being cleared from SPA cache
+
+Return Values
+-------------
+
+OPAL_SUCCESS
+   PE was successfully cleared from SPA cache
+
+OPAL_PARAMETER
+   A provided parameter was invalid
+
+OPAL_BUSY
+   XSLO is currently invalidating a previously requested entry
+
+.. _OPAL_NPU_TL_SET:
+
+OPAL_NPU_TL_SET
+===============
+
+OpenCAPI devices only.
+
+Update the NPU OTL configuration with device capabilities.
+
+Parameters
+----------
+::
+
+   uint64_t phb_id
+   uint32_t bdfn
+   long capabilities
+   uint64_t rate_phys
+   int rate_sz
+
+``phb_id``
+   OPAL ID of PHB
+
+``bdfn``
+   Bus-Device-Function number of OpenCAPI AFU
+
+``capabilities``
+   Bitmap of TL templates the device can receive
+
+``rate_phys``
+   Physical address of rates buffer
+
+``rate_sz``
+   Size of rates buffer (must be equal to 32)
+
+Return Values
+-------------
+
+OPAL_SUCCESS
+   OTL configuration was successfully updated
+
+OPAL_PARAMETER
+   A provided parameter was invalid