srvgrp-clock.adoc

Service Group - CLOCK (servicegroup_id: 0x00007)

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.

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.

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).

Clock rate format

Each clock rate is a tuple of two 32 bit 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.

Below table lists the services in this group:

Table 1. Clock Services

Service ID	Service Name	Request Type
0x01	ENABLE_NOTIFICATION	NORMAL_REQUEST
0x02	GET_NUM_CLOCKS	NORMAL_REQUEST
0x03	GET_ATTRIBUTES	NORMAL_REQUEST
0x04	GET_SUPPORTED_RATES	NORMAL_REQUEST
0x05	SET_CONFIG	NORMAL_REQUEST
0x06	GET_CONFIG	NORMAL_REQUEST
0x07	SET_RATE	NORMAL_REQUEST
0x08	GET_RATE	NORMAL_REQUEST

Clock Notifications

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.

Table 2. Request Data

Word	Name	Type	Description
0	EVENT_ID	uint32	Event to be subscribed for notification.

Table 3. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Notifications are subscribed successfully. RPMI_ERROR_NOT_FOUND EVENT_ID is not supported or invalid. RPMI_ERROR_NOT_SUPPORTED Notifications not supported. Other errors [table_error_codes]

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.

Request Data

• NA

Table 4. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. Other errors [table_error_codes]
1	NUM_CLOCKS	uint32	Number of Clocks

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.

Table 5. Request Data

Word	Name	Type	Description
0	CLOCK_ID	uint32	Clock ID

Table 6. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERROR_NOT_FOUND Clock not found Other errors [table_error_codes]
1	FLAGS	uint32	Bits Description [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. 0b01: Linear Range The CLOCK_RATE array contains the triplet (min_Hz, max_Hz, step_Hz). Each item in the triplet is a clock rate value. CLOCK_RATE[0] = min_Hz (lowest physical rate that the clock can synthesize) CLOCK_RATE[1] = max_Hz (highest physical rate that the clock can synthesize) 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
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 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 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 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.

Table 7. Request Data

Word	Name	Type	Description
0	CLOCK_ID	uint32	Clock ID
1	CLOCK_RATE_INDEX	uint32	Clock rate index

Table 8. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERROR_NOT_FOUND CLOCK_ID not found. RPMI_ERROR_INVALID_PARAM CLOCK_RATE_INDEX is not in valid range. Other errors [table_error_codes]
1	FLAGS	uint32	Reserved and must be 0.
2	REMAINING	uint32	Remaining number of clock rates.
3	RETURNED	uint32	Number of clock rates returned so far.
4	CLOCK_RATE[0]	(uint32, uint32)	Clock rate value.
5	CLOCK_RATE[1]	(uint32, uint32)	Clock rate value.
…​	CLOCK_RATE[N-1]	(uint32, uint32)	Clock rate value.

Service: SET_CONFIG

Set clock config, enable or disable the clock.

Table 9. Request Data

Word	Name	Type	Description
0	CLOCK_ID	uint32	Clock ID
1	CONFIG	uint32	Clock config Bits Description [31:1] Reserved [0] 0b0: Disable clock 0b1: Enable clock

Table 10. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERROR_NOT_FOUND CLOCK_ID not found. RPMI_ERROR_INVALID_PARAMETER CONFIG is not supported by the clock. Other errors [table_error_codes]

Service: GET_CONFIG

Get the current status of a clock, if it’s enabled or disabled.

Table 11. Request Data

Word	Name	Type	Description
0	CLOCK_ID	uint32	Clock ID

Table 12. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERROR_NOT_FOUND CLOCK_ID not found. Other errors [table_error_codes]
1	CONFIG	uint32	Clock config Value Description 0x0 Disabled 0x1 Enabled

Service: SET_RATE

Set clock rate.

Table 13. Request Data

Word	Name	Type	Description
0	CLOCK_ID	uint32	Clock ID
1	FLAGS	uint32	Bits Description [31:30] Clock rate roundup/rounddown 0b00: Round down 0b01: Round up 0b10: Auto. Platform autonomously choose rate closest to the requested rate. [29:0] Reserved
2	CLOCK_RATE_LOW	uint32

Table 14. Response Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERROR_NOT_FOUND CLOCK_ID not found. RPMI_ERROR_INVALID_PARAMETER Clock rate is not supported. Other errors [table_error_codes]

Service: GET_RATE

Get the current clock rate value.

Table 15. Request Data

Word	Name	Type	Description
0	CLOCK_ID	uint32	Clock ID

Table 16. Request Data

Word	Name	Type	Description
0	STATUS	int32	Return Status Code Error Code Description RPMI_SUCCESS Service completed successfully. RPMI_ERROR_NOT_FOUND CLOCK_ID not found. Other errors [table_error_codes]
1	CLOCK_RATE_LOW	uint32
2	CLOCK_RATE_HIGH	uint32