From 0d2c4c5d30c7266190cf99b6cccd2588fa88a727 Mon Sep 17 00:00:00 2001
From: Joshua Yeong <joshua.yeong@starfivetech.com>
Date: Thu, 12 Dec 2024 13:52:41 +0800
Subject: [PATCH] rpmi: performance: Add memory region service

Add 'PERF_GET_FAST_CHANNEL_REGION' service to
get a continuous block of physical memory region
for fast channel access.

Signed-off-by: Joshua Yeong <joshua.yeong@starfivetech.com>
---
 src/srvgrp-performance.adoc | 90 ++++++++++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 5 deletions(-)

diff --git a/src/srvgrp-performance.adoc b/src/srvgrp-performance.adoc
index d1f0517..572b8d3 100644
--- a/src/srvgrp-performance.adoc
+++ b/src/srvgrp-performance.adoc
@@ -49,6 +49,7 @@ The following table lists the services in the PERFORMANCE service group:
 | 0x07		| PERF_GET_LIMIT			| NORMAL_REQUEST
 | 0x08		| PERF_SET_LIMIT			| NORMAL_REQUEST
 | 0x09		| PERF_GET_FAST_CHANNEL_ATTRIBUTES	| NORMAL_REQUEST
+| 0x0A		| PERF_GET_FAST_CHANNEL_REGION		| NORMAL_REQUEST
 |===
 
 [#section-perf-level]
@@ -95,6 +96,17 @@ The fast-channel currently supports only the following PERFORMANCE services:
 * Support for fast-channel depends on the platform implementation.
 
 
+*Performance Fast-channel Shared Memory Region*::
+* In the memory region designated by the platform for fast-channel, it is
+  essential that the Performance Request fast-channels are organized in a
+  continuous memory block.
+* The shared memory region designated for fast-channel across performance
+  service group m must be a `power-of-two` in size. The base address and
+  size (in bytes) of this shared memory region can be obtained through the
+  service `PERF_GET_FAST_CHANNEL_REGION`. The base address of the
+  shared memory region must be aligned to 8 bytes.
+
+
 *Discovering Fast-channel*::
 * Fast-channels support are discoverable through PERFORMANCE service calls.
 * To determine if a platform supports fast-channel for a specific performance
@@ -102,6 +114,11 @@ The fast-channel currently supports only the following PERFORMANCE services:
 * If fast-channel support is available, retrieve fast-channel attributes for
   specific PERFORMANCE service call using the `PERF_GET_FAST_CHANNEL_ATTRIBUTES`
   service call.
+* The `PERF_GET_FAST_CHANNEL_REGION` provides physical memory for Performance
+  Service Group. The offset of the physical address retrieve in
+  `PERF_GET_FAST_CHANNEL_ATTRIBUTES` of the 'Performance Domain /
+  Service ID' paired is based on the starting address in
+  `PERF_GET_FAST_CHANNEL_REGION` service.
 
 
 *Doorbell Support*::
@@ -661,7 +678,7 @@ performance domain in the system.
 ! RPMI_ERR_INVALID_PARAM
 ! `DOMAIN_ID` or `LEVEL` is invalid.
 
-! RPMI_ERR_DENIED	
+! RPMI_ERR_DENIED
 ! Denied due to no permission.
 
 ! RPMI_ERR_HW_FAULT
@@ -881,14 +898,14 @@ specific performance domain and performance service.
 !===
 
 | 2
-|PHYS_ADDR_LOW
+| PHYS_ADDR_OFFSET_LOW
 | uint32
-| Lower 32-bit of physical address.
+| Lower 32-bit offset of fast-channel physical address region.
 
 | 3
-| PHYS_ADDR_HIGH
+| PHYS_ADDR_OFFSET_HIGH
 | uint32
-| Upper 32-bit of physical address.
+| Upper 32-bit offset of fast-channel physical address region.
 
 | 4
 | DB_ADDR_LOW
@@ -922,4 +939,67 @@ ringing the doorbell. This field is unused if the doorbell is not supported.
 | An upper 32-bit doorbell preserved mask to apply for this service before
 ringing the doorbell. This field is only valid if the doorbell register width
 is 64-bit. This field is unused if the doorbell is not supported.
+
+|===
+
+==== Service: PERF_GET_FAST_CHANNEL_REGION (SERVICE_ID: 0x0A)
+This service retrieves the physical address of the fast-channel region used in
+the performance service group. The fast-channel region is grouped in a continuous
+block of memory to ease the configuration of memory region protection.
+
+[#table_perf_getfastchanregion_request_data]
+.Request Data
+[cols="1", width=100%, align="center", options="header"]
+|===
+| NA
+|===
+
+[#table_perf_getfastchanregion_response_data]
+.Response Data
+[cols="1, 3, 1, 7a", width=100%, align="center", options="header"]
+|===
+| Word
+| Name
+| Type
+| Description
+
+| 0
+| STATUS
+| int32
+| Return error code
+
+[cols="6,5", options="header"]
+!===
+! Error Code
+! Description
+
+! RPMI_SUCCESS
+! Service completed successfully.
+
+! RPMI_ERR_NOT_SUPPORTED
+! Fast-channel is not implemented.
+
+!===
+- Other errors <<table_error_codes>>
+
+| 1
+| PHYS_ADDR_LOW
+| uint32
+| Lower 32-bit of the fast-channels shared memory region physical address.
+
+| 2
+| PHYS_ADDR_HIGH
+| uint32
+| Upper 32-bit of the fast-channels shared memory region physical address.
+
+| 3
+| REGION_SIZE_LOW
+| uint32
+| Lower 32-bit of the fast-channels shared memory region size.
+
+| 4
+| REGION_SIZE_HIGH
+| uint32
+| Upper 32-bit of the fast-channels shared memory region size.
+
 |===