Merge pull request #21 from lftan/update-spec

Update RPMI spec

riscv-rpmi.adoc

@@ -20,7 +20,7 @@
 :imagesoutdir: docs-resources/images
 :bibtex-file: src/rpmi.bib
 :bibtex-order: alphabetical
-:bibtex-style: apa
+:bibtex-style: ieee
 :icons: font
 :lang: en
 :listing-caption: Listing
@@ -72,5 +72,5 @@ include::src/srvgrp-performance.adoc[]
 include::src/srvgrp-management.adoc[]
 
 // The index must precede the bibliography
-include::src/index.adoc[]
+//include::src/index.adoc[]
 include::src/bibliography.adoc[]

src/intro.adoc

@@ -54,5 +54,5 @@ image::transport-topologies.png[width=800,height=800]
 RPMI is designed to work with a single or multi-tenant topology as depicted
 above.
 
-NOTE: The discovery of the transport itself is out of scope for this document. Which can either be described in firmware through DT or ACPI.
+NOTE: The discovery of the transport itself is out of scope for this document. Which can either be described in firmware through DT cite:[DT] or ACPI cite:[ACPI].
 

src/rpmi.bib

@@ -1 +1,12 @@
-
+@electronic{SBI,
+  title = {RISC-V Supervisor Binary Interface Specification},
+  url = {https://github.com/riscv-non-isa/riscv-sbi-doc}
+}
+@electronic{ACPI,
+  title = {Advanced Configuration and Power Interface Specification},
+  url = {https://uefi.org/specifications}
+}
+@electronic{DT,
+  title = {DeviceTree},
+  url = {https://www.devicetree.org/}
+}

src/srvgrp-clock.adoc

@@ -3,21 +3,20 @@
 This service group is for the management of system clocks. Services defined in 
 this group are used to enable or disable clocks, and to set/get clock rates.
 
-Each clock in the system is identified by the clock id which is an integer 
-identifier assigned to each clock. The mapping of clock_id and clock is known to
-both AP and Platform Microcontroller. Clock ID identifiers are sequential and 
-start from `0`.
+Each clock in the system is identified by the clock ID, which is an integer
+identifier assigned to each clock. The mapping of CLOCK_ID and clock is known
+to both the AP and the Platform Microcontroller. Clock ID identifiers are
+sequential and starting from `0`.
 
-The device or the group of devices which share the same clock source becomes a 
-single clock domain, which is identified by the clock_id. Any change in the 
-clock source affects the whole domain which can contain multiple devices.  
+The device or the group of devices sharing the same clock source form a
+single clock domain, which is identified by the CLOCK_ID. Any change to the
+clock source affects the entire domain which may contain multiple devices.
 
-This topology of devices and clock source is dependent on how the system is 
-designed and implementation specific. OS can discover this topology through 
-firmware tables (DT/ACPI). 
+The topology of the devices and the clock source is dependent on how the system
+is designed and implementation specific. The OS can discover this topology
+through firmware tables (DT cite:[DT] / ACPI cite:[ACPI]).
 
-
-==== Clock rate format
+*Clock Rate Format*::
 Each clock rate is a tuple of two `32 bits` values `(uint32, uint32)` represented
 as `(clock_rate_low, clock_rate_high)` and packed in the same order where
 `clock_rate_low` is at the lower index than the `clock_rate_high`.
@@ -42,9 +41,11 @@ Below table lists the services in this group:
 This service group does not support any event for notification
 
 ==== Service: *ENABLE_NOTIFICATION*
-This service allows AP to subscribe to clock service group notifications.
-Platform can optionally support notifications of events which might occur in the platform. PuC can send these notification messages to AP if they are implemented
-and AP has subscribed to these. Events supported are described above in Clock Notifications. 
+This service allows the AP to subscribe to clock service group notifications.
+The platform can optionally support notifications of events which might occur in
+the platform. The PuC can send these notification messages to AP if they are
+implemented and the AP has subscribed to these. The supported events are described
+above in Clock Notifications.
 
 [#table_clock_ennotification_request_data]
 .Request Data
@@ -72,8 +73,9 @@ notification.
 |===
 
 ==== Service: *GET_NUM_CLOCKS*
-Request for number of clocks available in the system. All supported clocks in 
-the system are designated by an integer identifier called clock_id. Clock_id are sequential starting from `0`.
+This service is used to query the number of clocks available in the system.
+All supported clocks in the system are designated by an integer identifier
+called CLOCK_ID. CLOCK_ID are sequential starting from `0`.
 
 [#table_clock_getnumclocks_request_data]
 .Request Data
@@ -95,16 +97,17 @@ the system are designated by an integer identifier called clock_id. Clock_id are
 |===
 
 ==== Service: *GET_ATTRIBUTES*
-This service returns the attributes of a clock like name of the clock which is 
-an array ASCII string of `16 byte`. Transition latency which is the worst case 
-latency for the clock to return to a stable state once clock configuration is 
-changed. Number of Clock rates supported by the requested clock. 
-FLAGS field encode the clock format supported by the clock.
-
-Current supported clock formats are discrete, which is an array of discrete 
-values where each value represents a clock rate. Another format is linear range 
-which is represented by `(min_Hz, max_Hz, step_Hz)`. In future more clock formats 
-can be supported if required.
+This service provides detailed attributes of a clock, including its name,
+represented as a 16-byte array of ASCII strings. It also specifies the
+transition latency, which denotes the maximum time for the clock to stabilize
+after a configuration change. Moreover, it indicates the number of clock rates
+supported by the requested clock. The FLAGS field encodes the clock formats
+supported by the clock.
+
+Currently supported clock formats include `discrete` format, represented as an
+array where each value represents a clock rate, and `linear` format represented
+as `(min_Hz, max_Hz, step_Hz)`. Additional clock formats may be supported in
+the future, as needed.
 
 [#table_clock_getattrs_request_data]
 .Request Data
@@ -134,8 +137,7 @@ can be supported if required.
 ! [31:30]	! CLOCK_FORMAT
 
 	0b00: Discrete Format
-	Each element in the CLOCK_RATE array is a supported discrete clock rate 
-	value packed in ascending order. Each rate is in Hertz.
+	Each element in the CLOCK_RATE array is a supported discrete clock rate value packed in ascending order. Each rate is in Hertz.
 
 	0b01: Linear Range
 	The CLOCK_RATE array contains the triplet (min_Hz, max_Hz, step_Hz). 
@@ -145,28 +147,28 @@ can be supported if required.
 	CLOCK_RATE[2] = step_Hz   (Step between two successive rates)
 ! [29:0]	! _Reserved_
 !===
-| 2	|NUM_RATESS	 	| uint32	| Number of Clock rates of type depending on CLOCK_FORMAT.
-| 3	| TRANSITION_LATENCY	| uint32	| Transition Latency
+| 2	|NUM_RATESS	 	| uint32	| Number of clock rates of type depending on CLOCK_FORMAT.
+| 3	| TRANSITION_LATENCY	| uint32	| Transition latency, in microseconds (us)
 | 4:7	| CLOCK_NAME		| uint8[16]	| Clock name
 |===
 
 ==== Service: *GET_SUPPORTED_RATES*
 Each domain may support multiple clock rate values which are allowed by the 
-domain to operate. Message can also pass the `clock_rate_index` which is the index
+domain to operate. Message can also pass the `CLOCK_RATE_INDEX` which is the index
 to the first rate value to be described in the return rate array. If all 
 supported rate values are required then this index value can be `0`. 
 
 If the CLOCK_FORMAT is discrete then the clock rate in the received data is an 
-array of supported discrete rate values  packed in ascending order starting from
+array of supported discrete rate values packed in ascending order starting from
 the lower index in the CLOCK_RATE field. If the CLOCK_FORMAT is a linear range, 
 then the CLOCK_RATE array contains a triplet of `(min_Hz, max_Hz, step_Hz)` where
 each item in the triplet is a clock rate value. 
 
 Total words required for the number of clock rates according to the format in 
 one message cannot exceed the total words available in one message DATA field. 
-If they exceed then PuC will return the number of clock rates which can be 
-accommodated in one message and set the REMAINING field accordingly. AP, when 
-REMAINING field is not `0` must call this service again with appropriate 
+If they exceed then the PuC will return the number of clock rates which can be
+accommodated in one message and set the REMAINING field accordingly. The AP,
+when REMAINING field is not `0` must call this service again with appropriate
 CLOCK_RATE_INDEX set to get the remaining clock rates. It's possible that 
 multiple service calls may be required to get all the clock rates. 
 In case the CLOCK_FORMAT is a linear range the RETURNED field will be set to `3`.

src/srvgrp-cppc.adoc

@@ -1,5 +1,5 @@
 === Service Group - *CPPC* (servicegroup_id: 0x00005)
-This service group defines the services to control CPU performance by managing a set of registers and a dedicated physical memory block, which will define fast channel access to each hart in the system. Hart writes a specific 32 bits desired performance number in fast channel memory. PuC decodes the request and performs the corresponding CPPC operations.
+This service group defines the services to control CPU performance by managing a set of registers and a dedicated physical memory block, which will define Fast-channel access to each hart in the system. Hart writes a specific 32 bits desired performance number in Fast-channel memory. PuC decodes the request and performs the corresponding CPPC operations.
 
 CPPC physical memory will have enough space to accommodate all available harts. Hart can send an RPMI message GET_CPPC_PERF_CHAN_ADDR to query the physical address of that particular hart.
 
@@ -9,11 +9,11 @@ PROBE_CPPC_REG service can be used to check if a particular CPPC register is imp
 
 For extra debugging, Hart can send a GET_CPPC_PERF_POKE message to exclusively request PuC to process the pending CPPC requests, if any. 
 
-For more information on CPPC, refer https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/index.html[ACPI] and https://github.com/riscv-non-isa/riscv-sbi-doc/[CPPC].
+For more information on CPPC, please refer to the ACPI Specification cite:[ACPI] and the CPPC Extension in the RISC-V SBI Specification cite:[SBI].
 
-CPPC Fast Channel REQ-ACK Memory Entry per Hart:
+CPPC Fast-channel REQ-ACK Memory Entry per Hart:
 [#table_cppc_fastchan_mem]
-.CPPC Fast Channel Memory Entry
+.CPPC Fast-Channel Memory Entry
 [cols="1, 3, 2", width=100%, align="center", options="header"]
 |===
 | Word	| Description 			| Entity which writes the word
@@ -28,14 +28,14 @@ Below table lists the services in this group:
 .CPPC Services
 [cols="1, 3, 2", width=100%, align="center", options="header"]
 |===
-| Service ID	| Service Name 		| Request Type
-| 0x01		| ENABLE_NOTIFICATION	| NORMAL_REQUEST
-| 0x02		| PROBE_REG		| NORMAL_REQUEST
-| 0x03		| READ_REG		| NORMAL_REQUEST
-| 0x04		| WRITE_REG		| NORMAL_REQUEST
-| 0x05		| GET_FAST_CHANNEL_ADDR	| NORMAL_REQUEST
-| 0x06		| POKE_FAST_CHANNEL	| NORMAL_REQUEST
-| 0x07		| GET_HART_LIST		| NORMAL_REQUEST
+| Service ID	| Service Name 			| Request Type
+| 0x01		| ENABLE_NOTIFICATION		| NORMAL_REQUEST
+| 0x02		| PROBE_REG			| NORMAL_REQUEST
+| 0x03		| READ_REG			| NORMAL_REQUEST
+| 0x04		| WRITE_REG			| NORMAL_REQUEST
+| 0x05		| GET_FAST_CHANNEL_ATTRIBUTES	| NORMAL_REQUEST
+| 0x06		| POKE_FAST_CHANNEL		| NORMAL_REQUEST
+| 0x07		| GET_HART_LIST			| NORMAL_REQUEST
 |===
 
 ==== CPPC Notifications
@@ -175,9 +175,9 @@ probe the REG_ID before reading.
 
 
 
-==== Service: *GET_FAST_CHANNEL_ADDR*
-Request for physical address of CPPC fast channel for the hart ID specified, 
-this physical address shall be used to write the value of https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/08_Processor_Configuration_and_Control/declaring-processors.html?highlight=cppc#desired-performance-register[CPPC Desired 
+==== Service: *GET_FAST_CHANNEL_ATTRIBUTES*
+This request retrieves attributes of the Fast-channel for a specified hart ID.
+The physical address from this request shall be used to write the value of the https://uefi.org/htmlspecs/ACPI_Spec_6_4_html/08_Processor_Configuration_and_Control/declaring-processors.html?highlight=desired-performance-register#desired-performance-register[CPPC Desired 
 Performance Register].
 
 [#table_cppc_getfastchanaddr_request_data]
@@ -199,7 +199,7 @@ Performance Register].
 ! *Error Code* 	!  *Description*
 ! RPMI_SUCCESS	! Service completed successfully.
 ! RPMI_ERROR_NOT_FOUND ! HART_ID not found
-! RPMI_ERROR_NOT_SUPPORTED ! Fast channel not implemented
+! RPMI_ERROR_NOT_SUPPORTED ! Fast-channel not implemented
 !===
 - Other errors <<table_error_codes>>
 | 1	| FLAGS		| uint32	| 
@@ -246,7 +246,7 @@ any.
 [cols="2,5"]
 !===
 ! *Error Code* 	!  *Description*
-! RPMI_SUCCESS	! Fast channel poked and service completed successfully.
+! RPMI_SUCCESS	! Fast-channel poked and service completed successfully.
 !===
 - Other errors <<table_error_codes>>
 |===

src/srvgrp-device-power.adoc

@@ -1,26 +1,27 @@
 
 ===  Service Group - *DEVICE_POWER* (servicegroup_id: 0x00008)
-This device power service group provides messages to manage the power states of 
-a device power domain. This service group is only used for device power 
+This Device Power service group provides messages to manage the power states of
+a device power domain. This service group is used only for device power
 management since System and CPU power management is handled by already defined 
-service groups like SYSTEM_RESET, SYSTEM_SUSPEND and HART_STATE_MANAGEMENT. 
+service groups such as SYSTEM_RESET, SYSTEM_SUSPEND and HART_STATE_MANAGEMENT.
 
 A domain can consist of one device if its power states can be controlled 
 independently or it may also have multiple devices if they all share the same 
-power control lines and power state can only be changed collectively. 
+power control lines and power states can only be changed collectively.
 Each domain must support ON and OFF states along with custom power states which 
 are discoverable.  Domains may also have power states which may preserve the 
-context. Level of context preserved will depend on the level of power state.
+context. The level of context preserved will depends on the level of power state.
 
-Power states for domains will be discovered via DT or ACPI where the values for
-ON and OFF are already fixed and known. Power state encodes both the power state
-value and the context preserved or lost information corresponding to that state.
+Power states for domains will be discovered via DT cite:[DT] or ACPI cite:[ACPI],
+where the values for ON and OFF are already fixed and known. The power state encodes
+both the power state value and the context preserved or lost information
+corresponding to that state.
 
 [#table_devpower_powerstate_data]
 .Power States Encoding
 [cols="2, 2, 5a", width=100%, align="center", options="header"]
 |===
-| POWER_STATE(uint32)	| Field 	| Description
+| POWER_STATE (uint32)	| Field 	| Description
 | POWER_STATE[31]	| CONTEXT	|
 
 	0b0: Context is preserved
@@ -55,9 +56,10 @@ value and the context preserved or lost information corresponding to that state.
 This service group does not support any event for notification.
 
 ==== Service: *ENABLE_NOTIFICATION*
-This service allows AP to subscribe to device power service group notifications.
-Platform can optionally support notifications of events which might occur in the platform. PuC can send these notification messages to AP if they are implemented
-and AP has subscribed to these. Events supported are described above in Device 
+This service allows the AP to subscribe to Device Power service group notifications.
+The platform can optionally support notifications of events that may occur in the platform.
+The PuC can send these notification messages to the AP if they are implemented
+and the AP has subscribed to them. The supported events are described above in Device
 Power Notifications.  
 
 [#table_devpower_ennotification_request_data]
@@ -88,8 +90,7 @@ notification.
 ==== Service: *GET_NUM_DOMAINS*
 This service is used to query the number of device power domains available which
 can be controlled by the client. The number of domains returned can be less than
-the actual number of domains present with the platform. The number of domains 
-returned are allowed to be managed by the client.
+the actual number of domains present with the platform.
 
 [#table_devpower_getdomains_request_data]
 .Request Data
@@ -107,7 +108,7 @@ returned are allowed to be managed by the client.
 ! RPMI_SUCCESS	! Service completed successfully.
 !===
 - Other errors <<table_error_codes>>
-| 1	| NUM_DOMAINS	| uint32 	| Number of domains
+| 1	| NUM_DOMAINS	| uint32 	| Number of device power domains
 |===
 
 
@@ -137,9 +138,9 @@ This service is used to query the attributes of a device power domain.
 - Other errors <<table_error_codes>>
 | 1	| FLAGS			| uint32	| _Reserved_
 | 2	| TRANSITION_LATENCY	| uint32 	| Worst case transition latency 
-of domain from one power state to another
+of domain from one power state to another, in microseconds (us)
 | 3:6	| DEVICE_POWER_DOMAIN_NAME | uint8[16]	| Device power domain
-name
+name, a NULL-terminated ASCII string up to 16-bytes.
 |===
 
 
@@ -155,7 +156,7 @@ This service is used to change the power state of a device power domain.
 | 1	| POWER_STATE	| uint32	| This field indicates the power state to which the power domain should transition. The specific power states and their 
 meanings may vary depending on the implementation, but generally, they include 
 values such as "ON", "OFF" and vendor specific power state. +
-See Power States table in the service group description
+See Power States description in the <<table_devpower_powerstate_data>>.
 |===
 
 [#table_devpower_setstate_response_data]
@@ -201,8 +202,8 @@ This service is used to get the current power state of a device power domain.
 ! RPMI_ERROR_DENIED ! Client does not have permissions to change the Device power domain power state.
 !===
 - Other errors <<table_error_codes>>
-| 1	| POWER_STATE	| uint32	| This field indicates the power state to which the power domain should transition. The specific power states and their 
-meanings may vary depending on the implementation, but generally, they include 
-values such as "ON", "OFF" and vendor specific power state. +
-See Power States table in the service group description
-|===
+| 1	| POWER_STATE	| uint32	| This field indicates the current power state
+of the specified domain. The power state can be one of several predefined values,
+such as ON, OFF, or vendor specific implementation.
+See Power States description in the <<table_devpower_powerstate_data>>.
+|===

src/srvgrp-hart-state-management.adoc

@@ -1,7 +1,7 @@
 
 === Service Group - *HART_STATE_MANAGEMENT* (servicegroup_id: 0x00004)
 The Hart State Management (HSM) service group defines a set of Hart states and 
-functionality equivalent to the RISC-V SBI HSM extension.
+functionality equivalent to the HSM extension in RISC-V SBI Specification cite:[SBI].
 
 Below table lists the services in this group:
 [#table_hsm_services]
@@ -131,7 +131,7 @@ success, the calling hart is suspended only after it executes WFI instruction.
 | Word	| Name 		| Type		| Description
 | 0	| HART_ID	| uint32	| Hart ID of the calling hart.
 | 1	| SUSPEND_TYPE	| uint32	| Hart suspend type as defined by RISC-V
-SBI Extension[[TODO LINK HERE]]
+SBI Specification cite:[SBI].
 | 2	| RESUME_ADDR_LOW | uint32	| Lower `32 bits` of resume address. +
 _Only used for non-retentive suspend types._
 | 3	| RESUME_ADDR_HIGH | uint32	| Upper `32 bits` of resume address. +