Re: [PATCH v4 01/19] dt-bindings: crypto: add Rambus CryptoManager Hub

[Conor Dooley <conor@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 10196 bytes --]

On Tue, Aug 25, 2026 at 03:15:20PM -0700, Alex Ousherovitch wrote:
> Add device tree binding schema for the Rambus CryptoManager Hub (CMH)
> hardware crypto accelerator.  The binding describes the parent
> SoC-level node with its SIC register region and one queue@N child
> node per mailbox the host owns, each carrying a reg (mailbox instance
> index), an optional interrupt, VCQ ring geometry (rambus,num-slots /
> rambus,slot-stride-bytes) and a rambus,cores affinity list.  Which crypto cores
> are present is discovered from the SIC CORE_ENABLE register at probe,
> not described in the device tree.
> 
> Register the 'rambus' vendor prefix for Rambus Inc.
> 
> Signed-off-by: Alex Ousherovitch <aousherovitch@rambus.com>
> Co-developed-by: Saravanakrishnan Krishnamoorthy <skrishnamoorthy@rambus.com>
> Signed-off-by: Saravanakrishnan Krishnamoorthy <skrishnamoorthy@rambus.com>
> ---
>  .../bindings/crypto/rambus,cmh-v1030.yaml     | 194 ++++++++++++++++++
>  .../devicetree/bindings/vendor-prefixes.yaml  |   2 +
>  2 files changed, 196 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/crypto/rambus,cmh-v1030.yaml
> 
> diff --git a/Documentation/devicetree/bindings/crypto/rambus,cmh-v1030.yaml b/Documentation/devicetree/bindings/crypto/rambus,cmh-v1030.yaml
> new file mode 100644
> index 000000000000..d9598b0f3bbc
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/crypto/rambus,cmh-v1030.yaml
> @@ -0,0 +1,194 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/crypto/rambus,cmh-v1030.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Rambus CryptoManager Hub (CMH) Hardware Crypto Accelerator
> +
> +maintainers:
> +  - Alex Ousherovitch <aousherovitch@rambus.com>
> +  - Saravanakrishnan Krishnamoorthy <skrishnamoorthy@rambus.com>
> +  - Joel Wittenauer <Joel.Wittenauer@cryptography.com>
> +
> +description: |
> +  The Rambus CryptoManager Hub (CMH) is a hardware cryptographic accelerator
> +  accessed via a mailbox-based VCQ (Virtual Command Queue) interface.  The
> +  host writes VCQ command sequences into per-mailbox DMA queue buffers and
> +  rings a doorbell; the CMH eSW processes them and signals completion via
> +  interrupt.
> +
> +  The management host statically partitions the hardware mailboxes across
> +  the SoC's host interfaces at integration time; the set of mailboxes a
> +  given host owns is therefore fixed and not runtime-discoverable (a
> +  mailbox locked to a host reads as unavailable in the SIC availability
> +  register).  Each owned mailbox is described by a child node.  Which
> +  crypto cores are present is a fixed silicon-build property indicated by
> +  the SIC CORE_ENABLE register, so cores are not described in the device
> +  tree.
> +
> +  CMH gates access to a locked mailbox by a hardware HOST ID presented on
> +  the bus with every access, permitting only the owning host's ID.  An
> +  integration must present a single, stable HOST ID for all accesses to a
> +  given mailbox, independent of the issuing CPU (relevant on SMP hosts
> +  whose interconnect encodes the issuing CPU in the HOST ID).
> +
> +properties:
> +  compatible:
> +    const: rambus,cmh-v1030
> +    description:
> +      Identifies the CryptoManager Hub v1.030 IP revision (register map and
> +      command ABI).  A specific SoC integration should list its own
> +      "<vendor>,<soc>-cmh" compatible first with "rambus,cmh-v1030" as a
> +      fallback; that extended form will be added when such a platform is
> +      upstreamed.

This commentary should just not be here.
Instead, do what's been done in sifive,clint.yaml for the clint2. I
don't feel great about suggesting that, and it feels like it's becoming
more common - although maybe that's a good thing because it means IP
vendors are being more proactive about upstreaming.

> +
> +  reg:
> +    maxItems: 1
> +    description:
> +      SIC (System Interface Controller) MMIO region.  The registers of
> +      mailbox instance N are at offset N * 0x1000 within this region.
> +
> +  clocks:
> +    minItems: 1
> +    items:
> +      - description: Main functional clock ("core").
> +      - description:
> +          Half-rate "core-div2" clock (present only on configurations with
> +          side-channel-protected cores) or the "rt" real-time tick clock.
> +      - description: Real-time tick clock ("rt") for the internal timer.
> +
> +  clock-names:
> +    oneOf:
> +      - items:
> +          - const: core
> +      - items:
> +          - const: core
> +          - const: core-div2
> +      - items:
> +          - const: core
> +          - const: rt
> +      - items:
> +          - const: core
> +          - const: core-div2
> +          - const: rt
> +
> +  reset-gpios:
> +    maxItems: 1
> +    description:
> +      Host-controlled reset for the CryptoManager Hub.  The hub has two
> +      external, active-low reset inputs -- a power-on reset and a hard
> +      reset; where a board routes one of them to a host GPIO, that line is
> +      described here.
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 0
> +
> +patternProperties:
> +  "^queue@[0-9a-f]+$":
> +    type: object
> +    description:
> +      One node per hardware mailbox (VCQ command queue) this host owns.
> +      The set of owned mailboxes is fixed by the management host at
> +      integration time and enumerated here.
> +    properties:
> +      reg:
> +        maxItems: 1
> +        description:
> +          0-based mailbox instance index.  The instance's registers are
> +          at reg * 0x1000 within the SIC region.
> +
> +      interrupts:
> +        maxItems: 1
> +        description: Completion/error interrupt for this mailbox.
> +
> +      rambus,num-slots:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        enum: [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192,
> +               16384, 32768]
> +        default: 64
> +        description:
> +          Number of VCQ ring slots for this mailbox's command queue in
> +          host DMA memory.  This is a per-board, per-mailbox host-memory
> +          ring geometry -- boards built around the same SoC (hence the
> +          same compatible) may use different ring sizes, so it is
> +          described per mailbox rather than derived from the compatible.
> +
> +      rambus,slot-stride-bytes:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        enum: [128, 256, 512, 1024]
> +        default: 512
> +        description:
> +          Stride in bytes between consecutive VCQ ring slots for this
> +          mailbox's command queue.  Like rambus,num-slots this is a
> +          per-board host-memory ring geometry, not derived from the
> +          compatible.
> +
> +      rambus,cores:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        items:
> +          enum: [0x02, 0x03, 0x04, 0x05, 0x08, 0x09, 0x0a, 0x18]
> +        description: |
> +          Core-affinity list: the hardware core IDs whose work is
> +          dispatched to this mailbox.  A core ID may appear on at most one
> +          mailbox.  Cores not listed on any mailbox are load-balanced
> +          across all mailboxes.  Optional (default: none -- the mailbox
> +          only serves the load-balanced pool).
> +
> +          Because each core instance has a distinct ID, separate
> +          instances of the same core type can be pinned to different
> +          mailboxes.
> +
> +          Core IDs:
> +            0x02 HC, 0x03 AES, 0x04 SM4, 0x05 SM3,
> +            0x08 HCQ, 0x09 QSE, 0x0a PKE, 0x18 CCP.

You could just make this a string array, and then you'd not need this
mapping of unintelligible hex values. Of course then your driver has to
do it, but I'd rather see understandable (and portable, since a new
revision could change the IDs) values in DT.

> +
> +    required:
> +      - reg
> +
> +    additionalProperties: false
> +
> +required:
> +  - compatible
> +  - reg
> +  - "#address-cells"
> +  - "#size-cells"

Surely clocks are also mandatory?

pw-bot: changes-requested

Cheers,
Conor.

> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    soc {
> +        #address-cells = <2>;
> +        #size-cells = <2>;
> +
> +        crypto@a4800000 {
> +            compatible = "rambus,cmh-v1030";
> +            reg = <0x0 0xa4800000 0x0 0x41000>;
> +            clocks = <&cmh_core_clk>;
> +            clock-names = "core";
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            /* Fast symmetric cores dedicated to mailbox 0:
> +             * HC 0x02, AES 0x03, SM4 0x04, SM3 0x05, CCP 0x18 */
> +            queue@0 {
> +                reg = <0>;
> +                interrupts = <1>;
> +                rambus,cores = <0x02 0x03 0x04 0x05 0x18>;
> +            };
> +
> +            /* Slow asymmetric/PQC cores dedicated to mailbox 1:
> +             * HCQ 0x08, QSE 0x09, PKE 0x0a */
> +            queue@1 {
> +                reg = <1>;
> +                interrupts = <2>;
> +                rambus,cores = <0x08 0x09 0x0a>;
> +                rambus,num-slots = <64>;
> +                rambus,slot-stride-bytes = <512>;
> +            };
> +        };
> +    };
> diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml
> index 396044f368e7..8b1a8f0a673d 100644
> --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml
> +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml
> @@ -1371,6 +1371,8 @@ patternProperties:
>      description: RaidSonic Technology GmbH
>    "^ralink,.*":
>      description: Mediatek/Ralink Technology Corp.
> +  "^rambus,.*":
> +    description: Rambus Inc.
>    "^ramtron,.*":
>      description: Ramtron International
>    "^raspberrypi,.*":
> -- 
> 2.43.7
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]