[PATCH v2 1/3] dt-bindings: accel: add device tree for AMD PKI accelerator

[Nipun Gupta]

Add binding documentation for AMD PKI accelerator supported for AMD
versal-net SoC.

AMD PKI accelerator is a device on AMD versa-net SoC to execute public key
asymmetric crypto operations like ECDSA, ECDH, RSA etc. with high performance.
The driver provides accel interface to applications for configuring the device
and performing the required operations. AMD PKI device comprises of multiple
Barco Silex ba414 PKI engines bundled together, and providing a queue based
interface to interact with the device.

 +------------------+
 |    Software      |
 +------------------+
     |          |
     |          v
     |     +-----------------------------------------------------------+
     |     |                     RAM                                   |
     |     |  +----------------------------+   +---------------------+ |
     |     |  |           RQ pages         |   |       CQ pages      | |
     |     |  | +------------------------+ |   | +-----------------+ | |
     |     |  | |   START (cmd)          | |   | | req_id | status | | |
     |     |  | |   TFRI (addr, sz)---+  | |   | | req_id | status | | |
     |     |  | | +-TFRO (addr, sz)   |  | |   | | ...             | | |
     |     |  | | | NTFY (req_id)     |  | |   | +-----------------+ | |
     |     |  | +-|-------------------|--+ |   |                     | |
     |     |  |   |                   v    |   +---------------------+ |
     |     |  |   |         +-----------+  |                           |
     |     |  |   |         | input     |  |                           |
     |     |  |   |         | data      |  |                           |
     |     |  |   v         +-----------+  |                           |
     |     |  |  +----------------+        |                           |
     |     |  |  |  output data   |        |                           |
     |     |  |  +----------------+        |                           |
     |     |  +----------------------------+                           |
     |     |                                                           |
     |     +-----------------------------------------------------------+
     |
     |
 +---|----------------------------------------------------+
 |   v                AMD PKI device                      |
 |  +-------------------+     +------------------------+  |
 |  | New request FIFO  | --> |       PK engines       |  |
 |  +-------------------+     +------------------------+  |
 +--------------------------------------------------------+

To perform a crypto operation, the software writes a sequence of descriptors,
into the RQ memory. This includes input data and designated location for the
output data. After preparing the request, request offset (from the RQ memory
region) is written into the NEW_REQUEST register. Request is then stored in a
common hardware FIFO shared among all RQs.

When a PK engine becomes available, device pops the request from the FIFO and
fetches the descriptors. It DMAs the input data from RQ memory and executes
the necessary computations. After computation is complete, the device writes
output data back to RAM via DMA. Device then writes a new entry in CQ ring
buffer in RAM, indicating completion of the request. Device also generates
an interrupt for notifying completion to the software.

Signed-off-by: Nipun Gupta <nipun.gupta@xxxxxxx>
---

The patch series was originally submitted as misc driver:
https://lore.kernel.org/all/20250312095421.1839220-1-nipun.gupta@xxxxxxx/

As suggested by Greg, the driver does not fit in misc and should be part
of accel or crypto. Accel is well suited for AMD PKI Crypto Accelerator,
and thus the driver is updated as an accel driver and yaml moved to
newly created accel folder.

Changes RFC->v2:
- updated device tree documentation to be the first patch
- fixed subject
- added documentation in commit log
- fixed compatible string providing correct prefix and SoC
- updated description to be more elaborative, providing datasheet link
- fixed the example

 .../bindings/accel/amd,versal-net-pki.yaml    | 58 +++++++++++++++++++
 MAINTAINERS                                   |  8 +++
 2 files changed, 66 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/accel/amd,versal-net-pki.yaml

diff --git a/Documentation/devicetree/bindings/accel/amd,versal-net-pki.yaml b/Documentation/devicetree/bindings/accel/amd,versal-net-pki.yaml
new file mode 100644
index 000000000000..2dca7458f845
--- /dev/null
+++ b/Documentation/devicetree/bindings/accel/amd,versal-net-pki.yaml
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/accel/amd,versal-net-pki.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AMD PKI accelerator device
+
+maintainers:
+  - Nipun Gupta <nipun.gupta@xxxxxxx>
+  - Praveen Jain <praveen.jain@xxxxxxx>
+
+description: |
+  AMD PKI accelerator handles the public key asymmetric crypto operations.
+  The driver provides accel interface to the application for configuring the
+  device and performing the required operations. AMD PKI device comprises of
+  multiple Barco Silex ba414 PKI engines bundled together, and providing a
+  queue based interface to interact with these devices on AMD versal-net SoC.
+
+  Link to ba414 datasheet:
+  https://datasheet.datasheetarchive.com/originals/crawler/barco-silex.com/34b540b9dc5db40c5bc01999401cf1e4.pdf
+
+properties:
+  compatible:
+    const: amd,versal-net-pki
+
+  reg:
+    description: AMD PKI register space
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  iommus: true
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - iommus
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    bus {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        amdpk@20400000000 {
+            compatible = "amd,versal-net-pki";
+            interrupts = <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>;
+            reg = <0x204 0x00000000 0x0 0x10000>;
+            iommus = <&smmu 0x25b>;
+        };
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index 96b827049501..11f8815daa77 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1154,6 +1154,14 @@ F:	Documentation/networking/device_drivers/ethernet/amd/pds_core.rst
 F:	drivers/net/ethernet/amd/pds_core/
 F:	include/linux/pds/

+AMD PKI DRIVER
+M:	Nipun Gupta <nipun.gupta@xxxxxxx>
+M:	Praveen Jain <praveen.jain@xxxxxxx>
+L:	dri-devel@xxxxxxxxxxxxxxxxxxxxx
+S:	Maintained
+T:	git https://gitlab.freedesktop.org/drm/misc/kernel.git
+F:	Documentation/devicetree/bindings/accel/amd,versal-net-pki.yaml
+
 AMD PMC DRIVER
 M:	Shyam Sundar S K <Shyam-sundar.S-k@xxxxxxx>
 L:	platform-driver-x86@xxxxxxxxxxxxxxx
--
2.34.1