View source for User:Knuxify/Old BCM590xx regulator notes

(note: this article has not been cleaned up ''at all'', it is imported from my local notes as-is.)

== Revisions ==

BCMPMU_59054_ID is ID for 59054

BCMPMU_59054A1_ANA_REV refers to A1 which has ACLD, A0 does not

== Downstream driver notes ==

* The downstream driver used is BCM59xxx, which despite the name is only for the BCM59054
** In the tree there are also drivers for BCM59056, a handful of other PMUs including BCM59055, and BCM590xx (which confusingly is '''not''' the same as BCM59xxx).
* The whole driver is fragmented as it's an MFD device, but the most important files are:
** <code>arch/arm/mach-{codename}/board-bcm59xxx_{device}.c</code> - contains PMU setup data, including voltages, regulator modes, battery values, etc.
** various files in <code>drivers/mfd/</code> starting from <code>bcmpmu59xxx-</code>
** <code>drivers/regulator/bcmpmu-rgltr-bcm59xxx.c</code> and <code>drivers/regulator/bcmpmu59xxx-regulator.c</code>
** there's some OTG related driver in <code>drivers/usb/otg/</code>? investigate
** <code>drivers/misc/bcmpmu59xxx_audio.c</code>
** <code>include/linux/mfd/bcmpmu59xxx_reg.h</code> and <code>include/linux/mfd/bcmpmu59054_reg.h</code>
** and others not mentioned here. todo

== Regulators ==

SR apparently means "switcher" (drivers/regulator/bcmpmu-regulator-56.c line 249). Rest is LDOs.

== Modes ==

''(see <code>drivers/regulator/bcmpmu59xxx-regulator.c</code>, <code>include/linux/mfd/bcmpmu59xxx.h</code>)''

There are two mode settings: 3bit (GPLDOs only) and 2bit (everything else, including all regs in bcm59056).

A standard regulator can have 3 modes: * ON (<code>REGULATOR_MODE_FAST</code>, <code>REGULATOR_MODE_NORMAL</code>) (0) * LPM (<code>REGULATOR_MODE_IDLE</code>) (1) * OFF (<code>REGULATOR_MODE_STANDBY</code>) (2)

* 2-bit mode regulators have 4 PM values in the PMMODE registers, at offsets 0, 2, 4 and 6 respectively (PM0, PM1, PM2, PM3), and '''2 PMMODE registers'''. (PMCTRL1 and PMCTRL2)
* 3-bit mode regulators have 2 PM values in the PMMODE registers, at offsets 0 and 3 respectively, and '''4 PMMODE registers'''. (PMCTRL1->4)

Each PM value corresponds to a different mode.

== BCM59056 and modes ==

''(see <code>drivers/regulator/bcmpmu-regulator-56.c</code>)''

<strike>Unlike BCM59054, there's only one PMMODE register</strike> (this is completely wrong! BCM59056 also has multiple PMMODE regs), and it has values PM0 to PM3. DSM (deep sleep) is pins PM0 and PM2. Regular value is written to PM1 and PM3.

I have a sneaking suspicion, based on the mainline driver, and the fact that the function described in the "Enabling the regulator" part will gleefuly ignore PM0 mostly, that PM0 may be some sort of "perma-override"

<syntaxhighlight lang="c">
/*State of enabled regualtor in deep sleep     
Used to program PC2PC1 = 0b10 & 0b00 case     
when the regulator is enabled*/     
enum {     
        BCMPMU_REGL_ON_IN_DSM = 1,     
        BCMPMU_REGL_LPM_IN_DSM,     
        BCMPMU_REGL_OFF_IN_DSM     
};   
</syntaxhighlight>

...a PC reference? You'll see these in the next section.

=== BCM59054 and modes ===

Here, the situation is a bit more complicated because there are multiple PMMODE regs. (Actually BCM59056 seems to have these as well? weird.)

=== Enabling a regulator ===

In theory, enabling a regulator can be done by setting all of its modes to <code>PMMODE_ON</code>. In practice, however, each regulator has specific "pins" which, when enabled, will enable the regulator. The pins used are stored in <code>arch/arm/mach-java/board-bcm59xxx_*</code>, under <code>pc_pins_map</code>.

This has a value created with the "PCPIN_MAP_ENC" macro, which effectively packs two "sets":

* '''Set 1''', which is the first parameter - if this is set, then '''all pins in this set must be enabled''' to enable this regulator.
* '''Set 0''', which is the second parameter - if this is set, then '''one of the pins in this set must be enabled''' to enable this regulator.

The functions <code>__is_2bit_pmmode_regl_enabled</code> and <code>__is_3bit_pmmode_regl_enabled</code> check if a regulator is enabled based on those pin maps, and the <code>pmmode</code> value as read out from the PMMODE registers.

For every <code>i</code> from 0 to 7 (<code>REGL_PMMODE_VAL_MAX</code>):

* get the PM reg shift by <code>PMMODE_2BIT_PMx_MASK & i</code> (PMMODE_2BIT_PMx_MASK == 3)
* if this <code>i</code> gives a value through <code>setval & i</code> in set0 or set1, then the value of whether the regulator is enabled is calculated using <code>PMMODE_2BIT_PMx_MASK & (pmmode[inx] >> shift)</code>, where <code>inx</code> is increased for every value where <code>PMMODE_2BIT_PMx_MASK & i</code> == 3.

In normal words: if the mode corresponding to the pin in ''any'' of the PMMODE registers is ON, then the regulator is on.

Here's a table of what that looks like:

(i - i iterator, s - pm offset, x - pmmode register no., set0 - matches against joined set0; pc1, pc2, pc3 - the result of the check for each of the possible pins in set0)

<syntaxhighlight lang="python">i s x set0   pc1   pc2   pc3
0 0 0 False [False, False, False]
1 2 0 True [True, False, False]
2 4 0 True [False, True, False]
3 6 0 True [True, True, False]
4 0 1 True [False, False, True]
5 2 1 True [True, False, True]
6 4 1 True [False, True, True]
7 6 1 True [True, True, True]</syntaxhighlight>
One thing of note - PC1 matches exactly the same configuration as the non-deep-sleep pins from the BCM59056 driver mentioned earlier. PC2 matches offsets 4 and 6, and PC3 matches everything in the second register, but not the first one.

So, how can the BCM59056 driver ignore that second register? Maybe I just didn't read something right? (probably...) (update: I think it's just BCM59054 that pokes multiple regs?)

Update: I found this a little later, in the bcm59'''0xx''' driver (actually for the BCM59055).

<syntaxhighlight lang="c">#define PC2_IS_0_PC1_IS_0                       0    
#define PC2_IS_0_PC1_IS_1                       2    
#define PC2_IS_1_PC1_IS_0                       4    
#define PC2_IS_1_PC1_IS_1                       6    </syntaxhighlight>
I suppose this should match the table above?

In any case - what I think is happening here is that which registers are read from to determine the notes are controlled by some kind of pins. Each PMMODE offset represents a different combination of pins to set.

=== The actual function called to prepare the enable value ===

Now that we know how these pins work, we can analyze the second function, <code>__2bit_pmmode_frm_map</code>.

This one's similar to the previous function:

For every <code>i</code> from 0 to 7 (<code>REGL_PMMODE_VAL_MAX</code>):

* If the value is in set0 or set1, set the value to <code>PMMODE_ON</code>; otherwise, use '''<code>dsm_pmmode</code>''' (a variable passed at init time). Oooh, DSM again!
* Figure out the shift and register like before.
* Add the value to a temp variable by ORing <code>val << shift</code> to it.

Here's the thing: <code>dsm_pmmode</code>... is the mode value provided in <code>__bcmpmuldo_set_mode</code>.

The mode is set in a few places in the code, and next to one of them, I found this:

<syntaxhighlight lang="c">                        /* We need to set mode here as regulator framework     
                        (set_machine_constraints) set the mode first and     
                        then call enable. We have updated enable function     
                        to set ON for all states based on customer request     
                        set_mode function sets PMMODE as needed*/     
</syntaxhighlight>

==== TL;DR, summary ====

Regulators can be enabled by setting specific offsets at the PMMODE registers to PMMODE_ON. A combination of PC pins can be used to select which offsets and PMMODE registers actually apply - by default, only offsets in PMCTRL1 is used, but the others can be used as well if PC3 is present - see below.

As a gross oversimplification, you can simply set ''every'' register to PMMODE_ON and it should work.

PM0 and PM2 (offsets 0 and 4) may or may not be related to deep sleep mode.

== A note about PC pins ==

According to schematics, on the Grand Neo, PC1 and PC2 are connected to the accordingly named PC1 and PC2 pinctrl pins. PC3 is an alternative function of LCDCS0 - and it's connected, as PMU_PC3, to the GPIO1 pin on the PMIC.

Turns out, the function of the GPIO pins can be programmed by writing to the GPIOCTRL registers. Here's the relevant downstream code:

(arch/arm/mach-java/board-bcm59xxx_ss_baffinlite.c)

<syntaxhighlight lang="c"> 121         /*  enable PC3 function */
 122         {.addr = PMU_REG_GPIOCTRL2, .val = 0x0E, .mask = 0xFF},</syntaxhighlight>
Sadly, these regs are completely undocumented, so we can't know for sure which exact bit enables this function. We also don't know what happens if it's ''not'' enabled.

== What about the regulator modes? ==

Somehow, <code>__2bit_pmmode_frm_map</code> ''doesn't'' set all of the PMMODE offsets! For the offsets matching the PC pin map, it actually ''leaves them on'', and only sets the requested mode for the remaining ones! Given that the variable name for the provided mode is <code>dsm_pmmode</code>, I suspect that Broadcom might've abused the mode system to provide the ''deep sleep regulator mode'' instead.

Still, this doesn't explain how the PC pins are controlled. I can't find any place in the downstream code that would do it. I suspect I should look at the suspend code...

Note to self: CHIPREG seems interesting. Has a whole bunch of stuff.

Another unrelated note: looks like i2c sets up slew rate for its pins in the driver, investigate