Mainline:Broadcom Kona/Clocks - Revision history

Knuxify: /* Policies */

2025-02-15T19:56:28Z

Policies

← Older revision		Revision as of 21:56, 15 February 2025
Line 40:		Line 40:
	=== Policies ===		=== Policies ===

	Each CCU has 4 policies. Policies control whether specific clocks ~~are~~ enabled, as well as the frequencies of specific clocks and some voltages, as seen in the frequency/voltage control sections below.		Each CCU has 4 policies. Policies control whether specific clocks can be gated (enabled/disabled), as well as the frequencies of specific clocks and some voltages, as seen in the frequency/voltage control sections below.

	According to the mainline driver, these policies are: "Deep Sleep", "Economy", "Normal" and "Turbo", where policy 2 is the default (question is, is it 2 counting from 1 or 0?).		According to the mainline driver, these policies are: "Deep Sleep", "Economy", "Normal" and "Turbo", where policy 2 is the default (question is, is it 2 counting from 1 or 0?).

Knuxify: /* Core clocks and freq policy */

2025-01-21T17:26:26Z

Core clocks and freq policy

← Older revision		Revision as of 19:26, 21 January 2025
Line 111:		Line 111:
	=== Core clocks and freq policy ===		=== Core clocks and freq policy ===

	The second user of this is core clocks - in the core CCU, the frequency policy is used to determine which clock source is used for the CPU - see "Core clocks" section for details. ~~###~~ PI manager and freq policy		The second user of this is core clocks - in the core CCU, the frequency policy is used to determine which clock source is used for the CPU - see "Core clocks" section for details.

			=== PI manager and freq policy ===

	The PI manager is also able to set this through the <code>pi_set_ccu_freq</code> function, which is only used if <code>CONFIG_CHANGE_POLICY_FOR_DFS</code> is not defined (and it is not defined in the Grand Neo downstream kernel). See "Power Islands" section.		The PI manager is also able to set this through the <code>pi_set_ccu_freq</code> function, which is only used if <code>CONFIG_CHANGE_POLICY_FOR_DFS</code> is not defined (and it is not defined in the Grand Neo downstream kernel). See "Power Islands" section.

Knuxify at 17:01, 20 January 2025

2025-01-20T17:01:56Z

Knuxify: /* Policy engine */

2025-01-20T17:00:51Z

Policy engine

← Older revision		Revision as of 19:00, 20 January 2025
Line 49:		Line 49:
	Before making any changes to the policy or one of the controls below, the policy engine must first be stopped. Restarting the policy engine will apply the changes to it.		Before making any changes to the policy or one of the controls below, the policy engine must first be stopped. Restarting the policy engine will apply the changes to it.

	Starting the policy engine is done by writing to the policy control offset, either: * the ATL (active load) bit for synchronous requests (we wait for the frequency and voltage to stabilize); * or clearing it for asynchronous requests, going into target mode (where the voltage ramps in the background, then the target load is copied to the active load triggering a frequency change).		Starting the policy engine is done by writing to the policy control offset, either:

			* the ATL (active load) bit for synchronous requests (we wait for the frequency and voltage to stabilize);
			* or clearing it for asynchronous requests, going into target mode (where the voltage ramps in the background, then the target load is copied to the active load triggering a frequency change).

	The above is more or less abridged from the mainline driver's docs:		The above is more or less abridged from the mainline driver's docs:

Knuxify: import from my personal docs

2025-01-20T17:00:16Z

import from my personal docs

New page

The Broadcom Kona clock manager consists of multiple CCUs (clock control units), which each manage their own set of clocks - whether they're enabled/disabled, their frequencies and other per-clock settings - as well as some peripheral voltage settings (likely a DVFS configuration).

This doc will not explain much about the clocks themselves (gating, hyst, selectors, etc.) - for that, see the source code of the mainline driver, which explains these things much better than this doc ever could.

== TODOs ==

* Figure out how voltage and peripheral voltage settings work, and what they affect
* Document connection to the power/PI manager

-----

== Clock types ==

There are multiple types of clocks handled by the CCUs.

=== Reference clocks ===

Fixed clocks used as clock sources for other clocks.

=== Bus clocks ===

Presumably handle frequencies for internal buses. They must be initialized before any of the peripheral clocks can be used.

Some peripheral clocks have corresponding bus clocks (see <code>sdio1</code> (peripheral) and <code>sdio1_ahb</code> (bus), <code>uartb</code> (peri) and <code>uartb_apb</code> (bus)). Some bus clocks are used as the primary clock for specific blocks (see <code>usb_otg_ahb</code>).

=== Peripheral clocks ===

The primary clocks used for various elements of the SoC.

=== PLL clocks and PLL channels clocks ===

These work completely differently from bus/peri clocks. Their primary use is as a configurable clock source - notably, they're used to power the CPU's clock.

=== Core clock ===

The CPU's clock.

== CCUs ==

=== Policies ===

Each CCU has 4 policies. Policies control whether specific clocks are enabled, as well as the frequencies of specific clocks and some voltages, as seen in the frequency/voltage control sections below.

According to the mainline driver, these policies are: "Deep Sleep", "Economy", "Normal" and "Turbo", where policy 2 is the default (question is, is it 2 counting from 1 or 0?).

=== Policy engine ===

Before making any changes to the policy or one of the controls below, the policy engine must first be stopped. Restarting the policy engine will apply the changes to it.

Starting the policy engine is done by writing to the policy control offset, either: * the ATL (active load) bit for synchronous requests (we wait for the frequency and voltage to stabilize); * or clearing it for asynchronous requests, going into target mode (where the voltage ramps in the background, then the target load is copied to the active load triggering a frequency change).

The above is more or less abridged from the mainline driver's docs:

<source lang="c"> /*
* If it's a synchronous request, we'll wait for the voltage
* and frequency of the active load to stabilize before
* returning. To do this we select the active load by
* setting the ATL bit.
*
* An asynchronous request instead ramps the voltage in the
* background, and when that process stabilizes, the target
* load is copied to the active load and the CCU frequency
* is switched. We do this by selecting the target load
* (ATL bit clear) and setting the request auto-copy (AC bit
* set).
*
* Note, we do NOT read-modify-write this register.
*/ </source>
and is somewhat related to downstream's <code>ccu_set_policy_ctrl</code>.

=== Getting the active policy ===

There's a way to use the policy debug registers to get the active policy, as seen in <code>ccu_policy_dbg_get_act_policy</code>, which is called through <code>ccu_get_active_policy</code>. This is used to get the frequency ID to use for the bus clocks, as seen below.

TODO: How do you set the policy? My guess is that it's managed by the policy engine based on some kind of dependency; either that, or it's dictated by the power manager. TODO.

=== Frequency control ===

<code>ccu_set_freq_policy</code> / <code>ccu_get_freq_policy</code>, <code>ccu_clk->freq_tbl[freq_id][freq_tbl_index]</code>

Each CCU with a policy has a "policy_freq" register, which stores the IDs of the frequency policies to use for each CCU policy - this is written in <code>ccu_set_freq_policy</code>. On init, it reads the first 4 members of <code>ccu_clk->freq_policy</code> and writes them as the defaults to the registers.

Every frequency policy has an ID from 0 to 7. The downstream driver has tables representing what frequencies each policy entails.

==== Frequency tables ====

The selected frequency policy controls which set of frequencies is used in the CCU. It acts as an index to a second table, <code>.freq_tbl</code>, which in turn contains the frequencies that that specific frequency policy sets up. Each CCU has a specific number of frequencies in these tables.

Effectively, a frequency table looks sort of like this (written in a simplified, Python-like syntax for easier understanding):

<source lang="python">ccu_freq_list0 = [26000000,26000000,26000000,26000000]
ccu_freq_list1 = [52000000,52000000,52000000,5200000]
...
ccu_freq_list6 = [208000000,104000000,104000000,1040000000]

ccu.freq_tbl = [
ccu_freq_list0, ccu_freq_list1, ..., ccu_freq_list6
]
# actual number of frequencies in table is specific to each CCU</source>
This is used by bus clocks - which frequencies correspond to which clocks is shown by the <code>.freq_tbl_index</code> member of the clock info struct. Clocks that have this value set to >= 0 specify that they're connected to that specific frequency; clocks with a value of -1 use a source clock or internal dividers instead.

<source lang="python"># A bus clock will perform an operation like so:

current_policy = ccu.get_active_policy() # CCU policy ID, from 0 to 3
freq_id = ccu.get_freq_policy(current_policy) # read frequency ID (aka which table to use) for the current policy
ccu.freq_table[freq_id][bus_clk.freq_tbl_index]</source>
=== Core clocks and freq policy ===

The second user of this is core clocks - in the core CCU, the frequency policy is used to determine which clock source is used for the CPU - see "Core clocks" section for details. ### PI manager and freq policy

The PI manager is also able to set this through the <code>pi_set_ccu_freq</code> function, which is only used if <code>CONFIG_CHANGE_POLICY_FOR_DFS</code> is not defined (and it is not defined in the Grand Neo downstream kernel). See "Power Islands" section.

=== Voltage control ===

<code>ccu_set_voltage</code> / <code>ccu_get_voltage</code>

This is a DVFS (dynamic voltage/frequency scaling) setup that connects a specific frequency ID to a specific voltage ID.

Every frequency ID has a corresponding voltage ID in the voltage table, which are defined in the <code>.freq_volt</code> member of the CCU clock struct in downstream, and are written at initialization time to the CCU VLT registers (VLT0_3 and VLT4_7). Which voltage is selected depends on which frequency ID is selected.

No code in downstream appears to set/get these voltage tables after init, except for the debug code. Most likely, the default values are fine.

=== Peripheral voltage control ===

<code>ccu_set_peri_voltage</code> / no get function

Actually completely different from the voltage control, though they share the same voltage IDs in downstream.

There are two modes - NORMAL and HIGH. The voltage ID to use is written to the <code>.vlt_peri_offset</code> register.

As the name suggests, the peripheral voltage setting is used by peripheral clocks, which can select the voltage level - NORMAL or HIGH - to use by writing a bit using the <code>.volt_lvl_mask</code>, as done in the <code>peri_clk_set_voltage_lvl</code> function in downstream.

== Relation to Power Islands ==

The Power Islands, besides being controlled mostly by the power manager, also have connections to the CCUs:

* Every PI has one or more CCUs assigned to it (<code>.ccu_id</code> and <code>.num_ccu_id</code> in pi_mgr)
* Every PI also has its own OPPs which get converted to CCU frequency IDs as per the <code>.opp_info</code> tables
* PI reset offsets are located in the root CCU

-----

== Porting downstream clock struct to mainline ==

In downstream, look for a struct of type <code>peri_clk</code> for your clock. In mainline, open <code>clk-bcm21664.c</code>.

Here's a list of mainline clock struct members, and their downstream counterparts (<code>(->bit)</code> signifies that this mask must be converted to a bit shift first - see the RDB, there's a "shift" value next to the mask)

* <code>.clocks</code>: <code>CLOCKS()</code>, fill with names of source clocks as seen in <code>clock_source</code> struct above your clock struct; put each name between double quotes.
* <code>.gate</code>: depends on the gate type:
** <code>HW_SW_GATE[_AUTO]</code> - these have a <code>gating_sel_mask</code>; use the <code>_AUTO</code> if <code>AUTO_GATE</code> is present in the <code>.flags</code>; in order: <code>.clk_gate_offset</code>, <code>.stprsts_mask</code> (->bit), <code>.gating_sel_mask</code> (->bit), <code>.clk_en_mask</code> (->bit)
** <code>{HW,SW}_ONLY_GATE</code> - these have no <code>gating_sel_mask</code>; if <code>.flags</code> contains <code>AUTO_GATE</code>, then <code>HW</code>, else <code>SW</code>; in order: <code>.clk_gate_offset</code>, <code>.stprsts_mask</code> (->bit), <code>.clk_en_mask</code> (->bit)
* <code>.hyst</code>: <code>HYST()</code>, in order: <code>.clk_gate_offset</code>, <code>.hyst_val_mask</code> (->bit), <code>.hyst_en_mask</code> (->bit)
* <code>.sel</code>: <code>SELECTOR()</code>, in order: <code>.clk_div.pll_select_offset</code>, <code>.pll_select_shift</code>, width of <code>.pll_select_mask</code>
* <code>.div</code>: <code>DIVIDER()</code>, in order: <code>.clk_div.div_offset</code>, <code>.div_shift</code>, width of <code>.div_mask</code>
* <code>.trig</code>: <code>TRIGGER()</code>, in order: <code>.clk_div.div_trig_offset</code>, <code>.div_trig_mask</code> (->bit)
* <code>.policy</code>: <code>POLICY()</code>, in order: the CCU's <code>policy_mask{1/2}_offset</code> (depending on <code>.mask_set</code>), <code>.policy_bit_mask</code> (->bit)

-----

TPIU is some CoreSight thing. PTI is likely MIPS PTI (''Parallel Trace Interface'').

← Older revision		Revision as of 19:01, 20 January 2025
Line 7:		Line 7:
	* Figure out how voltage and peripheral voltage settings work, and what they affect		* Figure out how voltage and peripheral voltage settings work, and what they affect
	* Document connection to the power/PI manager		* Document connection to the power/PI manager


	-----		-----
Line 56:		Line 55:
	The above is more or less abridged from the mainline driver's docs:		The above is more or less abridged from the mainline driver's docs:

	<~~source~~ lang="c"> /*		<syntaxhighlight lang="c"> /*
	* If it's a synchronous request, we'll wait for the voltage		* If it's a synchronous request, we'll wait for the voltage
	* and frequency of the active load to stabilize before		* and frequency of the active load to stabilize before
Line 70:		Line 69:
	*		*
	* Note, we do NOT read-modify-write this register.		* Note, we do NOT read-modify-write this register.
	*/ </~~source~~>		*/ </syntaxhighlight>
	and is somewhat related to downstream's <code>ccu_set_policy_ctrl</code>.		and is somewhat related to downstream's <code>ccu_set_policy_ctrl</code>.

Line 93:		Line 92:
	Effectively, a frequency table looks sort of like this (written in a simplified, Python-like syntax for easier understanding):		Effectively, a frequency table looks sort of like this (written in a simplified, Python-like syntax for easier understanding):

	<~~source~~ lang="python">ccu_freq_list0 = [26000000,26000000,26000000,26000000]		<syntaxhighlight lang="python">ccu_freq_list0 = [26000000,26000000,26000000,26000000]
	ccu_freq_list1 = [52000000,52000000,52000000,5200000]		ccu_freq_list1 = [52000000,52000000,52000000,5200000]
	...		...
Line 101:		Line 100:
	ccu_freq_list0, ccu_freq_list1, ..., ccu_freq_list6		ccu_freq_list0, ccu_freq_list1, ..., ccu_freq_list6
	]		]
	# actual number of frequencies in table is specific to each CCU</~~source~~>		# actual number of frequencies in table is specific to each CCU</syntaxhighlight>
	This is used by bus clocks - which frequencies correspond to which clocks is shown by the <code>.freq_tbl_index</code> member of the clock info struct. Clocks that have this value set to >= 0 specify that they're connected to that specific frequency; clocks with a value of -1 use a source clock or internal dividers instead.		This is used by bus clocks - which frequencies correspond to which clocks is shown by the <code>.freq_tbl_index</code> member of the clock info struct. Clocks that have this value set to >= 0 specify that they're connected to that specific frequency; clocks with a value of -1 use a source clock or internal dividers instead.

	<~~source~~ lang="python"># A bus clock will perform an operation like so:		<syntaxhighlight lang="python"># A bus clock will perform an operation like so:

	current_policy = ccu.get_active_policy() # CCU policy ID, from 0 to 3		current_policy = ccu.get_active_policy() # CCU policy ID, from 0 to 3
	freq_id = ccu.get_freq_policy(current_policy) # read frequency ID (aka which table to use) for the current policy		freq_id = ccu.get_freq_policy(current_policy) # read frequency ID (aka which table to use) for the current policy
	ccu.freq_table[freq_id][bus_clk.freq_tbl_index]</~~source~~>		ccu.freq_table[freq_id][bus_clk.freq_tbl_index]</syntaxhighlight>

	=== Core clocks and freq policy ===		=== Core clocks and freq policy ===

Line 142:		Line 142:
	* Every PI also has its own OPPs which get converted to CCU frequency IDs as per the <code>.opp_info</code> tables		* Every PI also has its own OPPs which get converted to CCU frequency IDs as per the <code>.opp_info</code> tables
	* PI reset offsets are located in the root CCU		* PI reset offsets are located in the root CCU


	-----		-----
Line 161:		Line 160:
	* <code>.trig</code>: <code>TRIGGER()</code>, in order: <code>.clk_div.div_trig_offset</code>, <code>.div_trig_mask</code> (->bit)		* <code>.trig</code>: <code>TRIGGER()</code>, in order: <code>.clk_div.div_trig_offset</code>, <code>.div_trig_mask</code> (->bit)
	* <code>.policy</code>: <code>POLICY()</code>, in order: the CCU's <code>policy_mask{1/2}_offset</code> (depending on <code>.mask_set</code>), <code>.policy_bit_mask</code> (->bit)		* <code>.policy</code>: <code>POLICY()</code>, in order: the CCU's <code>policy_mask{1/2}_offset</code> (depending on <code>.mask_set</code>), <code>.policy_bit_mask</code> (->bit)


	-----		-----

	TPIU is some CoreSight thing. PTI is likely MIPS PTI (''Parallel Trace Interface'').		TPIU is some CoreSight thing. PTI is likely MIPS PTI (''Parallel Trace Interface'').