Re: [PATCH v17 1/7] firmware: arm_rmm: Add SMC definitions for calling the RMM

Hi Suzuki,

On 9/7/26 7:59 PM, Suzuki K Poulose wrote:

From: Steven Price <steven.price@arm.com>

The RMM (Realm Management Monitor) provides functionality that can be
accessed by SMC calls from the host.

The SMC definitions are based on DEN0137[1] version 2.0-bet3

[1] https://developer.arm.com/documentation/den0137/2-0bet3/

Signed-off-by: Steven Price <steven.price@arm.com>
Signed-off-by: Suzuki K Poulose <suzuki.poulose@arm.com>
---
  Changes since v16:
   * Updated definitions to RMM specification v2.0-bet3.
  Changes since v15:
   * Dropped unused symbols REC_MAX_GIC_NUM_LRS and RMI_PERMITTED_GICV3_HCR_BITS.
   * Output is now (partially) generated from the spec source.
  Changes since v14:
   * Updated to RMM spec v2.0-bet2 but without the changes to move
     metadata out of individual address range descriptors as this is
     expected to be reverted in a future spec release.
  Changes since v13:
   * Updated to RMM spec v2.0-bet1
  Changes since v12:
   * Updated to RMM spec v2.0-bet0
  Changes since v9:
   * Corrected size of 'ripas_value' in struct rec_exit. The spec states
     this is an 8-bit type with padding afterwards (rather than a u64).
  Changes since v8:
   * Added RMI_PERMITTED_GICV3_HCR_BITS to define which bits the RMM
     permits to be modified.
  Changes since v6:
   * Renamed REC_ENTER_xxx defines to include 'FLAG' to make it obvious
     these are flag values.
  Changes since v5:
   * Sorted the SMC #defines by value.
   * Renamed SMI_RxI_CALL to SMI_RMI_CALL since the macro is only used for
     RMI calls.
   * Renamed REC_GIC_NUM_LRS to REC_MAX_GIC_NUM_LRS since the actual
     number of available list registers could be lower.
   * Provided a define for the reserved fields of FeatureRegister0.
   * Fix inconsistent names for padding fields.
  Changes since v4:
   * Update to point to final released RMM spec.
   * Minor rearrangements.
  Changes since v3:
   * Update to match RMM spec v1.0-rel0-rc1.
  Changes since v2:
   * Fix specification link.
   * Rename rec_entry->rec_enter to match spec.
   * Fix size of pmu_ovf_status to match spec.
---
  include/linux/arm-smccc-rmi.h | 494 ++++++++++++++++++++++++++++++++++
  1 file changed, 494 insertions(+)
  create mode 100644 include/linux/arm-smccc-rmi.h

Some nitpicks below, please pick up the commits that look reasonable :)

If I'm correct enough, RMI_RETURN_{STATUS, INDEX, MEMREQ, CAN_CANEL}_MASK are used
for once in this header file. So we needn't explicitly expose them and combine their
definitions with users to fetch the corresponding fields, as below.

#define RMI_RETURN_STATUS(ret)		FIELD_GET(GENMASK(7, 0), ret)
#define RMI_RETURN_INDEX(ret)		FIELD_GET(GENMASK(15, 8), ret)
#define RMI_RETURN_MEMREQ(ret)		FIELD_GET(GENMASK(10, 8), ret)
#define RMI_RETURN_CAN_CANCEL(ret)	FIELD_GEt(GENMASK(10, 10), ret)

+#define RMI_SUCCESS			0
+#define RMI_ERROR_INPUT			1
+#define RMI_ERROR_REALM			2
+#define RMI_ERROR_REC			3
+#define RMI_ERROR_RTT			4
+#define RMI_ERROR_NOT_SUPPORTED		5
+#define RMI_ERROR_DEVICE		6
+#define RMI_ERROR_RTT_AUX		7
+#define RMI_ERROR_PSMMU_ST		8
+#define RMI_ERROR_DPT			9
+#define RMI_BUSY			10
+#define RMI_ERROR_GLOBAL		11
+#define RMI_ERROR_TRACKING		12
+#define RMI_INCOMPLETE			13
+#define RMI_BLOCKED			14
+#define RMI_ERROR_GPT			15
+#define RMI_ERROR_GRANULE		16
+
+#define RMI_CONTINUE_KEEP_GOING		0
+#define RMI_CONTINUE_STOP		1
+
+#define RMI_OP_MEM_REQ_NONE		0
+#define RMI_OP_MEM_REQ_DONATE		1
+#define RMI_OP_MEM_REQ_RECLAIM		2
+
+#define RMI_DONATE_SIZE_MASK		3UL
+#define RMI_DONATE_COUNT_MASK		GENMASK(15, 2)
+#define RMI_DONATE_CONTIG_MASK		BIT(16)
+#define RMI_DONATE_STATE_MASK		GENMASK(18, 17)
+
+#define RMI_DONATE_SIZE(req)		FIELD_GET(RMI_DONATE_SIZE_MASK, req)
+#define RMI_DONATE_COUNT(req)		FIELD_GET(RMI_DONATE_COUNT_MASK, req)
+#define RMI_DONATE_CONTIG(req)		FIELD_GET(RMI_DONATE_CONTIG_MASK, req)
+#define RMI_DONATE_STATE(req)		FIELD_GET(RMI_DONATE_STATE_MASK, req)
+

As above, RMI_DONATE_{SIZE, COUNT, CONTIG, STATE}_MASK are used for once in this
header file. So their definitions can be dropped by modifying the followup macros,
as below. Some enhancements are also applicable: (a) Use 'BLOCK' to indicate the
unit encoded in the request. (b) The macros are put into order from MSB to LSB.

#define RMI_DONATE_STATE(req)		FIELD_GET(GENMASK(18, 17), req)
#define RMI_DONATE_CONTIG(req)		FIELD_GET(GENMASK(16, 16), req)
#define RMI_DONATE_BLOCK_COUNT(req)	FIELD_GET(GENMASK(15, 2), req)
#define RMI_DONATE_BLOCK_SIZE(req)	FIELD_GET(GENMASK(1, 0), req)

+#define RMI_OP_MEM_DELEGATED		0
+#define RMI_OP_MEM_UNDELEGATED		1
+#define RMI_OP_MEM_CONDITIONAL		2
+

B4.6.40 RmiOpMemContig type is missed here and they should be used in the c code.

#define RMI_OP_MEM_NON_CONTIG	0
#define RMI_OP_MEM_CONTIG	1

In the c code, we shall have:

if (RMI_DONATE_CONTIG(req) == RMI_OP_MEM_CONTIG)) {
    ...
} else {
    ...
}

Similarly, B4.6.39 RmiOpCanCancel type is missed here and they should be used in
the c code.

#define RMI_OP_CANNOT_CANCEL	0
#define RMI_OP_CAN_CANCEL	1

In the c code, we shall have:

if (RMI_RETURN_CAN_CANCEL(ret) == RMI_OP_CAN_CANCEL) {
     ...
} else {
     ...
}

+#define RMI_ADDR_TYPE_NONE		0
+#define RMI_ADDR_TYPE_SINGLE		1
+#define RMI_ADDR_TYPE_LIST		2
+
+#define RMI_ADDR_RANGE_SIZE_MASK	GENMASK(1, 0)
+#define RMI_ADDR_RANGE_COUNT_MASK	GENMASK(PAGE_SHIFT - 1, 2)
+#define RMI_ADDR_RANGE_ADDR_MASK	(PAGE_MASK & GENMASK(51, 0))
+#define RMI_ADDR_RANGE_STATE_MASK	GENMASK(63, 62)
+
+#define RMI_ADDR_RANGE_SIZE(ar)		(FIELD_GET(RMI_ADDR_RANGE_SIZE_MASK, \
+						   (ar)))
+#define RMI_ADDR_RANGE_COUNT(ar)	(FIELD_GET(RMI_ADDR_RANGE_COUNT_MASK, \
+						   (ar)))
+#define RMI_ADDR_RANGE_ADDR(ar)		((ar) & RMI_ADDR_RANGE_ADDR_MASK)
+#define RMI_ADDR_RANGE_STATE(ar)	(FIELD_GET(RMI_ADDR_RANGE_STATE_MASK, \
+						   (ar)))
+

I guess it wouldn't a bad idea to explictly indicate 'BLOCK' in the definitions, as
below. Some improvements are applicated either: (a) 'ar' is renamed to 'r'; (b) The
excessive parentheses are dropped to follow the patterns we already had; (c) For
RMI_ADDR_RANGE_ADDR(r), FIELD_GET() is used.

#define RMI_ADDR_RANGE_BLOCK_SIZE_MASK		GENMASK(1, 0)
#define RMI_ADDR_RANGE_BLOCK_COUNT_MASK		GENMASK(PAGE_SHIFT - 1, 2)
#define RMI_ADDR_RANGE_ADDR_MASK		(PAGE_MASK & GENMASK(51, 0))
#define RMI_ADDR_RANGE_STATE_MASK		GENMASK(63, 62)

#define RMI_ADDR_RANGE_BLOCK_SIZE(r)		FIELD_GET(RMI_ADDR_RANGE_SIZE_MASK, r)
#define RMI_ADDR_RANGE_BLOCK_COUNT(r)		FIELD_GET(RMI_ADDR_RANGE_COUNT_MASK, r)
#define RMI_ADDR_RANGE_ADDR(r)		        FIELD_GET(RMI_ADDR_RANGE_ADDR_MASK, r)
#define RMI_ADDR_RANGE_STATE(r)		        FIELD_GET(RMI_ADDR_RANGE_STATE_MASK, r)

+enum rmi_ripas {
+	RMI_EMPTY = 0,
+	RMI_RAM = 1,
+	RMI_DESTROYED = 2,
+	RMI_DEV = 3,
+};
+
+#define RMI_NO_MEASURE_CONTENT	0
+#define RMI_MEASURE_CONTENT	1
+
+#define RMI_FEATURE_REGISTER_0_S2SZ		GENMASK(7, 0)
+#define RMI_FEATURE_REGISTER_0_LPA2		BIT(8)
+#define RMI_FEATURE_REGISTER_0_SVE		BIT(9)
+#define RMI_FEATURE_REGISTER_0_SVE_VL		GENMASK(13, 10)
+#define RMI_FEATURE_REGISTER_0_NUM_BPS		GENMASK(19, 14)
+#define RMI_FEATURE_REGISTER_0_NUM_WPS		GENMASK(25, 20)
+#define RMI_FEATURE_REGISTER_0_PMU		BIT(26)
+#define RMI_FEATURE_REGISTER_0_PMU_NUM_CTRS	GENMASK(31, 27)
+#define RMI_FEATURE_REGISTER_0_L0GPT_BLOCK_DELEGATE	BIT(32)
+#define RMI_FEATURE_REGISTER_0_S2OASZ		GENMASK(40, 33)
+
+#define RMI_FEATURE_REGISTER_1_RMI_GRAN_SZ_4KB	BIT(0)
+#define RMI_FEATURE_REGISTER_1_RMI_GRAN_SZ_16KB	BIT(1)
+#define RMI_FEATURE_REGISTER_1_RMI_GRAN_SZ_64KB	BIT(2)
+#define RMI_FEATURE_REGISTER_1_HASH_SHA_256	BIT(3)
+#define RMI_FEATURE_REGISTER_1_HASH_SHA_384	BIT(4)
+#define RMI_FEATURE_REGISTER_1_HASH_SHA_512	BIT(5)
+#define RMI_FEATURE_REGISTER_1_MAX_RECS_ORDER	GENMASK(9, 6)
+#define RMI_FEATURE_REGISTER_1_L0GPTSZ		GENMASK(13, 10)
+#define RMI_FEATURE_REGISTER_1_PPS		GENMASK(16, 14)
+
+#define RMI_FEATURE_REGISTER_2_DA		BIT(0)
+#define RMI_FEATURE_REGISTER_2_DA_COH		BIT(1)
+#define RMI_FEATURE_REGISTER_2_VSMMU		BIT(2)
+#define RMI_FEATURE_REGISTER_2_ATS		BIT(3)
+#define RMI_FEATURE_REGISTER_2_PDEV_MAX_VDEVS_ORDER	GENMASK(7, 4)
+#define RMI_FEATURE_REGISTER_2_VDEV_KROU	BIT(8)
+#define RMI_FEATURE_REGISTER_2_NON_TEE_STREAM	BIT(9)
+#define RMI_FEATURE_REGISTER_2_REALM_MAX_VDEVS_ORDER	GENMASK(14, 10)
+
+#define RMI_FEATURE_REGISTER_3_MAX_NUM_AUX_PLANES	GENMASK(3, 0)
+#define RMI_FEATURE_REGISTER_3_RTT_PLANE		GENMASK(5, 4)
+#define RMI_FEATURE_REGISTER_3_RTT_S2AP_INDIRECT	BIT(6)
+
+#define RMI_FEATURE_REGISTER_4_MEC_COUNT		GENMASK(63, 0)
+

We would reorder those feature register definitions from MSB ro LSB :-)

+#define RMI_MEM_CATEGORY_CONVENTIONAL		0
+#define RMI_MEM_CATEGORY_DEV_NCOH		1
+#define RMI_MEM_CATEGORY_DEV_COH		2
+#define RMI_MEM_CATEGORY_NONE			3
+
+#define RMI_TRACKING_RESERVED			0
+#define RMI_TRACKING_NONE			1
+#define RMI_TRACKING_FINE			2
+#define RMI_TRACKING_COARSE			3
+#define RMI_TRACKING_INTERMEDIATE		4
+
+#define RMI_GRANULE_SIZE_4KB	0
+#define RMI_GRANULE_SIZE_16KB	1
+#define RMI_GRANULE_SIZE_64KB	2
+
+#define RMI_GPT_PAR_RESERVED           0U
+#define RMI_GPT_PAR_PLAT               1U
+#define RMI_GPT_PAR_HOST_NOT_CREATED   2U
+#define RMI_GPT_PAR_HOST_CREATED       3U
+
+/*
+ * Note many of these fields are smaller than u64 but all fields have u64
+ * alignment, so use u64 to ensure correct alignment.
+ */
+struct rmm_config {
+	union { /* 0x0 */
+		struct {
+			u64 tracking_region_size;
+			u64 rmi_granule_size;
+		};
+		u8 sizer[SZ_4K];
+	};
+};
+
+static_assert(sizeof(struct rmm_config) == SZ_4K);
+
+#define RMI_REALM_PARAM_FLAG_SVE		BIT(1)
+#define RMI_REALM_PARAM_FLAG_PMU		BIT(2)
+#define RMI_REALM_PARAM_FLAG_DA			BIT(3)
+#define RMI_REALM_PARAM_FLAG_LFA_POLICY		GENMASK(6, 5)
+#define RMI_REALM_PARAM_FLAG_MEC_POLICY		GENMASK(8, 7)
+
+#define RMI_HASH_SHA_256			0
+#define RMI_HASH_SHA_512			1
+#define RMI_HASH_SHA_384			2
+
+struct realm_params {
+	union { /* 0x0 */
+		struct {
+			u64 flags0;
+			u64 s2sz;
+			u64 sve_vl;
+			u64 num_bps;
+			u64 num_wps;
+			u64 pmu_num_ctrs;
+			u64 hash_algo;
+			u64 num_aux_planes;
+		};
+		u8 padding0[0x400];
+	};
+	union { /* 0x400 */
+		struct {
+			u8 rpv[64];
+			u64 ats_plane;
+		};
+		u8 padding1[0x400];
+	};
+	union { /* 0x800 */
+		struct {
+			u64 padding2;
+			u64 rtt_base;
+			s64 rtt_level_start;
+			u64 rtt_num_start;
+			u64 flags1;
+			u64 max_num_vdevs;
+		};
+		u8 padding3[0x700];
+	};
+	union { /* 0xf00 */
+		struct {
+			u8 padding4[0x80];
+			u64 aux_rtt_base[3];
+		};
+		u8 padding5[0x100];
+	};
+};
+
+static_assert(sizeof(struct realm_params) == SZ_4K);
+
+/*
+ * The number of GPRs (starting from X0) that are
+ * configured by the host when a REC is created.
+ */
+#define REC_CREATE_NR_GPRS		8
+
+#define REC_PARAMS_FLAG_RUNNABLE	BIT(0)
+
+struct rec_params {
+	union { /* 0x0 */
+		u64 flags;
+		u8 padding0[0x100];
+	};
+	union { /* 0x100 */
+		u64 mpidr;
+		u8 padding1[0x100];
+	};
+	union { /* 0x200 */
+		u64 pc;
+		u8 padding2[0x100];
+	};
+	union { /* 0x300 */
+		u64 gprs[REC_CREATE_NR_GPRS];
+		u8 padding3[0xd00];
+	};
+};
+
+static_assert(sizeof(struct rec_params) == SZ_4K);
+
+#define REC_ENTER_FLAG_EMULATED_MMIO	BIT(0)
+#define REC_ENTER_FLAG_INJECT_SEA	BIT(1)
+#define REC_ENTER_FLAG_TRAP_WFI		BIT(2)
+#define REC_ENTER_FLAG_TRAP_WFE		BIT(3)
+#define REC_ENTER_FLAG_RIPAS_RESPONSE	BIT(4)
+#define REC_ENTER_FLAG_S2AP_RESPONSE	BIT(5)
+#define REC_ENTER_FLAG_DEV_MEM_RESPONSE	BIT(6)
+#define REC_ENTER_FLAG_FORCE_P0		BIT(7)
+
+#define REC_RUN_GPRS			31
+
+struct rec_enter {
+	union { /* 0x000 */
+		u64 flags;
+		u8 padding0[0x200];
+	};
+	union { /* 0x200 */
+		u64 gprs[REC_RUN_GPRS];
+		u8 padding1[0x600];
+	};
+};
+
+static_assert(sizeof(struct rec_enter) == SZ_2K);
+
+#define RMI_EXIT_SYNC			0x00
+#define RMI_EXIT_IRQ			0x01
+#define RMI_EXIT_FIQ			0x02
+#define RMI_EXIT_PSCI			0x03
+#define RMI_EXIT_RIPAS_CHANGE		0x04
+#define RMI_EXIT_HOST_CALL		0x05
+#define RMI_EXIT_SERROR			0x06
+#define RMI_EXIT_S2AP_CHANGE		0x07
+#define RMI_EXIT_VDEV_VALIDATE_MAPPING	0x08
+#define RMI_EXIT_VSMMU_COMMAND		0x0a
+
+struct rec_exit {
+	union { /* 0x000 */
+		u8 exit_reason;
+		u8 padding0[0x100];
+	};
+	union { /* 0x100 */
+		struct {
+			u64 esr;
+			u64 far;
+			u64 hpfar;
+			u64 rtt_tree;
+		};
+		u8 padding1[0x100];
+	};
+	union { /* 0x200 */
+		u64 gprs[REC_RUN_GPRS];
+		u8 padding2[0x100];
+	};
+	union { /* 0x300 */
+		u8 padding3[0x100];
+	};
+	union { /* 0x400 */
+		struct {
+			u64 cntp_ctl;
+			u64 cntp_cval;
+			u64 cntv_ctl;
+			u64 cntv_cval;
+		};
+		u8 padding4[0x100];
+	};
+	union { /* 0x500 */
+		struct {
+			u64 ripas_base;
+			u64 ripas_top;
+			u8 ripas_value;
+			u8 padding5[0xf];
+			u64 s2ap_base;
+			u64 s2ap_top;
+			u64 vdev_id_1;
+			u64 vdev_id_2;
+			u64 dev_mem_base;
+			u64 dev_mem_top;
+			u64 dev_mem_pa;
+		};
+		u8 padding6[0x100];
+	};
+	union { /* 0x600 */
+		struct {
+			u16 imm;
+			u8 padding7[0x6];
+			u64 plane;
+		};
+		u8 padding8[0x100];
+	};
+	union { /* 0x700 */
+		struct {
+			u8 pmu_ovf_status;
+			u8 padding9[0xf];
+			u64 vsmmu;
+		};
+		u8 padding10[0x100];
+	};
+};
+
+static_assert(sizeof(struct rec_exit) == SZ_2K);
+
+struct rec_run {
+	struct rec_enter enter;
+	struct rec_exit exit;
+};
+
+static_assert(sizeof(struct rec_run) == SZ_4K);
+
+/* RMI_RTT_UNPROT_MAP_FLAGS definitions */
+#define RMI_RTT_UNPROT_MAP_FLAGS_OADDR_TYPE	GENMASK(1, 0)
+#define RMI_RTT_UNPROT_MAP_FLAGS_LIST_COUNT	GENMASK(15, 2)
+#define RMI_RTT_UNPROT_MAP_FLAGS_MEMATTR	GENMASK(18, 16)
+#define RMI_RTT_UNPROT_MAP_FLAGS_S2AP		GENMASK(22, 19)
+
+/* RMI_RTT_PROT_MAP_FLAGS definitions */
+#define RMI_RTT_PROT_MAP_FLAGS_OADDR_TYPE	GENMASK(1, 0)
+#define RMI_RTT_PROT_MAP_FLAGS_LIST_COUNT	GENMASK(15, 2)
+
+/* S2AP Direct Encodings, used in RMI_RTT_UNPROT_MAP_FLAGS_S2AP */
+#define RMI_S2AP_DIRECT_WRITE			BIT(0)
+#define RMI_S2AP_DIRECT_READ			BIT(1)
+
+#endif /* __LINUX_ARM_SMCCC_RMI_H_ */

Thanks,
Gavin