View source for Mainline:Broadcom Kona/Power Manager

* Base address: <code>0x35010000</code>

<span id="revisions"></span>
== Revisions ==

There exist two revisions of the Power Manager: REV0 (capri) and REV2 (hawaii, java). Here is a list of known differences:

* A second set of voltage controllers is introduced in REV02.
** To go with the second VO, a second sequencer command bank is introduced.
* A new i2c command, <code>PWRMGR_I2C_APB_READ_OFFSET</code>, is introduced in REV02. This register contains i2c data and i2c isr register… whatever those are.

<span id="components"></span>
== Components ==

* Some kind of interrupt controller?
* Power Island (mostly in separate pi_mgr driver)
* Sequencer (might be related to those sequences mentioned in PI driver)
* Some kind of PMU, or connection to the PMU
* Some kind of voltage controller?
* Event handler

<span id="initialization"></span>
== Initialization ==

The initialization is first called during early init, through a platform-specific function called <code>hawaii_pwr_mgr_init</code>, located in the mach- folders.

First, this function initializes some initialization parameters for the pwrmgr from <code>pm_params.c</code> through <code>pm_params_init</code>. These are stored in the <code>pwrmgr_init_param</code> struct in the aforementioned file.

Then, it uses a set of dummy pointers defined in <code>pwr_mgr</code> to initialize the power manager with:

<pre>/**
 * Load the dummy sequencer during power manager initialization
 * Actual sequencer will be loaded during pmu i2c driver
 * initialisation
 */</pre>
At this point, <code>pwr_mgr_init</code> is called. This function is defined in <code>plat-kona/pwr_mgr.c</code>, and marks the first time we enter the full platform driver.

The passed dummy struct we created earlier is a <code>pwr_mgr_info</code> struct. <code>pwr_mgr.info</code> is set to this value. This indicates to all further functions that the power manager has been initialized. <code>pwr_mgr.sem_locked</code> is set to <code>false</code>.

Next, the sequencer is disabled (<code>pwr_mgr_pm_i2c_enable(false)</code> - [[#I2C_ENABLE_OFFSET - 0x4100]]) and initialized with the provided data (<code>pwr_mgr_init_sequencer(info);</code>).

<code>pwr_mgr_init_sequencer</code>:

* writes the I2C commands from <code>info-&gt;i2c_cmds</code> using <code>pwr_mgr_pm_i2c_cmd_write</code>
* writes the data from <code>info-&gt;i2c_var_data</code> using <code>pwr_mgr_pm_i2c_var_data_write</code>
* writes command pointers for each volt ??? from <code>info-&gt;i2c_cmd_ptr</code> using <code>pwr_mgr_set_v0x_specific_i2c_cmd_ptr</code>

Back to <code>pwr_mgr_init</code>, it sets <code>pwr_mgr.i2c_seq_trg = 0</code> and calls the following:

* <code>init_completion(&amp;pwr_mgr.i2c_seq_done);</code> - this sets up a [https://embetronicx.com/tutorials/linux/device-drivers/completion-in-linux/ completion handler] (<code>include/linux/completion.h</code>)
* <code>INIT_WORK(&amp;pwr_mgr.pwrmgr_work, pwr_mgr_work_handler);</code> - this sets up a [https://www.oreilly.com/library/view/understanding-the-linux/0596005652/ch04s08.html work queue] (<code>kernel/workqueue.c</code>).

Then, it runs <code>pwr_mgr_mask_intr(PWRMGR_INTR_ALL, true);</code> to mask all interrupts by default.

Lastly, it requests an IRQ using <code>request_irq</code>, using <code>info-&gt;pwrmgr_intr</code> as the interrupt number, with the handler set to <code>pwr_mgr_irq_handler</code> ([https://embetronicx.com/tutorials/linux/device-drivers/linux-device-driver-tutorial-part-13-interrupt-example-program-in-linux-kernel/ ref]).

This is the end of the <code>pwr_mgr_init</code> function.

We return to the <code>mach-{}/pwr_mgr.c</code> file.

The next things that happen:

* <code>hawaii_pi_mgr_init</code> is called. This is described in the PI section.
* Some erratum stuff happens. Check later.
* A wakeup override is set for the MM (multimedia) CCU (core clock, handles stuff like camera, DSI, GPU) using <code>pwr_mgr_pi_set_wakeup_override(PI_MGR_PI_ID_MM, false /*clear */);</code>. This might be related to the workarounds in <code>pwr_mgr_init_sequencer</code>?
* <code>pwr_mgr_event_clear_events</code> is called on all events.
* <code>pwr_mgr_event_set</code> sets <code>SOFTWARE_2_EVENT</code> and <code>SOFTWARE_0_EVENT</code> to 1.

Then some pin control stuff happens:

<syntaxhighlight lang="c">    pwr_mgr_set_pc_sw_override(PC0, false, 0);
    pwr_mgr_set_pc_clkreq_override(PC0, true, 1);

    /* make sure that PC1, PC2 software override
     * is cleared so that sequencer can toggle these
     * pins during retention/off/wakeup
     */
    pwr_mgr_set_pc_sw_override(PC1, false, 0);
    pwr_mgr_set_pc_sw_override(PC2, false, 0);
    pwr_mgr_set_pc_sw_override(PC3, false, 0);
    pwr_mgr_set_pc_clkreq_override(PC1, false, 0);
    pwr_mgr_set_pc_clkreq_override(PC2, false, 0);</syntaxhighlight>
Then we call <code>pwr_mgr_pm_i2c_enable(true);</code>.

Then, the event table is initialized:

<syntaxhighlight lang="c">    /*Init event table */
    for (i = 0; i < ARRAY_SIZE(__event_table); i++) {
        pwr_mgr_event_trg_enable(__event_table[i].event_id,
                     __event_table[i].trig_type);

        cfg.policy = __event_table[i].policy_modem;
        pwr_mgr_event_set_pi_policy(__event_table[i].event_id,
                        PI_MGR_PI_ID_MODEM, &cfg);

        cfg.policy = __event_table[i].policy_arm;
        pwr_mgr_event_set_pi_policy(__event_table[i].event_id,
                        PI_MGR_PI_ID_ARM_CORE, &cfg);

        cfg.policy = __event_table[i].policy_arm_sub;
        pwr_mgr_event_set_pi_policy(__event_table[i].event_id,
                        PI_MGR_PI_ID_ARM_SUB_SYSTEM, &cfg);

        cfg.policy = __event_table[i].policy_aon;
        pwr_mgr_event_set_pi_policy(__event_table[i].event_id,
                        PI_MGR_PI_ID_HUB_AON, &cfg);

        cfg.policy = __event_table[i].policy_hub;
        pwr_mgr_event_set_pi_policy(__event_table[i].event_id,
                        PI_MGR_PI_ID_HUB_SWITCHABLE, &cfg);

        cfg.policy = __event_table[i].policy_mm;
        pwr_mgr_event_set_pi_policy(__event_table[i].event_id,
                        PI_MGR_PI_ID_MM, &cfg);
</syntaxhighlight>
The following sets up some kind of event triggers… not that they seem to do much that the others don’t. Only happens on java. Might be related to the 4 CPU cores as opposed to hawaii’s 2?

<syntaxhighlight lang="c">    /*Map core timer interrupts to COMMON_TIMER_3_EVENT and
    *COMMON_TIMER_4_EVENT events.
    *Set timer_wu_event_sel to 0x3 to map both slave and core timer
    *interrupts to these events*/
    reg_val = readl(KONA_CHIPREG_VA + CHIPREG_PERIPH_SPARE_CONTROL1_OFFSET);
    reg_val |= 0x3 <<
        CHIPREG_PERIPH_SPARE_CONTROL1_TIMER_WU_EVENT_SEL_SHIFT;
    writel(reg_val,
</syntaxhighlight>
Then we init all PIs using <code>pi_init</code> on the PI recieved with <code>pi_mgr_get</code> on every ID.

Finally, we call <code>__clock_init()</code>. Then clock setup happens for CPU speed (only used on Hawaii chips with lower clocks.)

This is the end of the <code>hawaii_pwr_mgr_init</code> function.

There are two more late init functions:

* <code>hawaii_pwr_mgr_late_init</code> which runs <code>hawaii_pwr_mgr_delayed_init</code>, which in turn runs <code>pi_init_state</code> on every PI;
* <code>mach_init_sequencer</code> which initializes the sequencer with real values and “on return PWRMGR I2C block will be enabled”.

<span id="events"></span>

== Events ==

Events are called on specific actions in the system. When they occur, they set the PI policies. There are multiple types of trigger mechanisms for events.

A full list of events is present at <code>arch/arm/mach-java/include/mach/pwr_mgr.h</code>. Not all of them trigger policy changes; the ones that do are defined in <code>arch/arm/mach-java/pwr_mgr.c</code>.

<span id="sequencer"></span>
== Sequencer ==

There is code for both a HW sequencer and a SW sequencer. As evidenced by the comments, they cannot both run at once or timeouts will happen.

Downstream driver defines multiple erratas for these. In our case:

* <code>CONFIG_KONA_PWRMGR_SWSEQ_FAKE_TRG_ERRATUM=y</code>
* <code>CONFIG_KONA_PWRMGR_SWSEQ_RETRY_WORKAROUND=y</code>

This sequencer can control voltage requests and PC pin status.

<span id="sequencer-commands"></span>
=== Sequencer commands ===

The sequencer has 2 command banks, each of which stores 64 commands. Each command consists of a 4-bit command number and an 8-bit value.

REV02 has 2 command banks, REV00 only has one.

{| class="wikitable"
|-
! Address
! Name
! Description (as found in downstream kernel)
! Used?
|-
| 0x0
| REG_ADDR
| sets the next address for read/write data
| Y
|-
| 0x1
| REG_DATA
| executes a write to I2C controller via APB
| F
|-
| 0x2
| I2C_DATA
| data to be written to PMU via I2C
| F
|-
| 0x3
| I2C_VAR
| data returned for voltage lookup (payload is the index to table)
| F
|-
| 0x4
| WAIT_I2C_RETX
| wait for retry from I2C control register
| N
|-
| 0x5
| WAIT_I2C_STAT
| wait for good status (loop until good)
| N
|-
| 0x6
| WAIT_TIMER
| wait for the number of clocks in the payload
| Y
|-
| 0x7
| END
| stop and wait for new voltage request change
| Y
|-
| 0x8
| SET_PC_PINS
| pc pins are set based on value and mask
| Y
|-
| 0x9
| SET_UPPER_DATA
| sets the data in the upper byte of apb data bus
| N
|-
| 0xA
| READ_FIFO
| read i2c fifo
| F
|-
| 0xB
| SET_READ_DATA
| copy I2C read data to PWRMGR register
| F
|-
| 0xE
| JUMP_VOLTAGE
| jump to address based on current voltage request
| Y
|-
| 0xF
| JUMP
| jump to address defined in payload
| F
|}

(Y - yes in dummy, F - yes in full table, N - not at all)

<span id="power-island"></span>

== Power Island ==

The Power Islands are power domains managed by the Power Manager.

<span id="what-makes-a-power-island"></span>
=== What makes a Power Island ===

There are 6 [[#Power Islands]] as defined in the code. Each power island has a '''policy''', and has a controllable frequency and wake-up latency.

Power islands are pretty closely tied to the CCU. Both the DFS and QoS requests are sent to the CCU, and managed the frequency policy and voltage policy respectively.

<span id="dfs-and-qos"></span>
=== DFS and QoS ===

ref: Documentation/Broadcom/Kona_PM_DFS_and_QOS_API.txt in downstream kernel

DFS APIs are used to control the '''frequency''', or to be exact, '''OPP mode''' (see [[#OPP types]]), of a specific PI. QoS APIs are used to control the '''maximum wake-up latency'''.

Both of these APIs work through a system of “requests”; clients can make requests by using <code>add_request</code> (this creates a “node” which is usually stored somewhere in the client’s driver), change their value using <code>request_update</code> or remove the request by using <code>request_remove</code>.

<span id="initialization-1"></span>
=== Initialization ===

Initialization begins in <code>mach-{}/pi_mgr.c</code>., where <code>hawaii_pi_mgr_init</code> is called. This does some errata stuff, runs <code>pi_mgr_init</code> and finally calls <code>pi_mgr_register</code> on every PI. This file defines the default settings for each PI.

<code>pi_mgr_init</code> is defined in <code>arch/arm/plat-kona/pi_mgr.c</code>. It does two things: * Initializes memory for the pi_mgr data: <code>memset(&amp;pi_mgr, 0, sizeof(pi_mgr));</code> * Sets <code>pi_mgr.init = 1;</code>.

Most of the actual PI initialization is actually done in the power manager initialization sequence.

<span id="policies"></span>
=== Policies ===

From <code>arch/arm/mach-java/include/mach/pwr_mgr.h</code>:

<syntaxhighlight lang="c">#define PM_OFF      0  /* Shutdown policy */
#define PM_RET      1  /* Retention policy */
#define PM_ECO      4  /* Economy */
#define PM_DFS      5  /* also RUN_POLICY; see [[#DFS and QoS]] */
#define PM_WKP      7  /* wakeup? */</syntaxhighlight>
<code>pwr_mgr_pi_set_wakeup_override</code> needs to be called before policies can be changed.

<span id="raw-data"></span>
=== Raw data ===

<span id="nodes"></span>
==== Nodes ====

* DFS (Dynamic Frequency Scaling?) and QOS (Quality of Service?)
* Both have some kind of requests (add_request, update_request in plat-kona/pi_mgr.c)

<span id="opp-types"></span>
==== OPP types ====

\:src: arch/arm/mach-java/include/mach/pi_mgr.h

OPP stands for “operating frequency”. See [[#DFS and QoS]].

* 0 - XTAL
* 1 - ECONOMY
* 2 - NORMAL
* 3 - TURBO
* 4 - SUPER_TURBO

<span id="power-islands"></span>
==== Power Islands ====

\:src: arch/arm/mach-java/include/mach/pi_mgr.h

* MM
* HUB_SWITCHABLE
* HUB_AON
* ARM_CORE
* ARM_SUB_SYSTEM
* MODEM

Each has 3 states: ACTIVE, RETENTION, and SHUTDOWN; ARM cores have ACTIVE, SUSPEND, RETENTION and DORMANT.

<span id="raw-data-1"></span>
== Raw data ==

<span id="i2c-value-offsets"></span>
=== I2C value offsets ===

<span id="intr_status---0x40a0"></span>
==== INTR_STATUS - 0x40A0 ====

<span id="intr_mask---0x40a4"></span>
==== INTR_MASK - 0x40A4 ====

<span id="event_bank1_offset---0x40a8"></span>
==== EVENT_BANK1_OFFSET - 0x40A8 ====

<span id="i2c_enable_offset---0x4100"></span>
==== I2C_ENABLE_OFFSET - 0x4100 ====

Writing 0x0000001 enables the sequencer, 0x00000000 disables it. See <code>pwr_mgr_pm_i2c_enable</code>.

<span id="i2c_cmd_bank0_offset---0x4104"></span>
==== I2C_CMD_BANK0_OFFSET - 0x4104 ====

<span id="i2c_cmd_bank1_offset---0x4280"></span>
==== I2C_CMD_BANK1_OFFSET - 0x4280 ====

<span id="i2c_sw_cmd_ctrl---0x41b8"></span>
==== I2C_SW_CMD_CTRL - 0x41B8 ====

<code>PWRMGR_I2C_REQ_TRG_MASK</code> - enables/disables software sequencer

<span id="i2c_apb_read"></span>
==== I2C_APB_READ ====

'''REV02 only'''. 0x41CC, mask 0xFF, shift 0.