dissonant.dev wiki - Recent changes [en]

Mainline:Broadcom Kona/Adding a new device

Uart — Sun, 23 Aug 2026 19:56:09 GMT

Getting the downstream kernel source

Mainline:Broadcom Kona/Adding a new device

Uart — Thu, 20 Aug 2026 21:54:58 GMT

start writing draft

New page

This page goes over the process of adding support for a Broadcom Kona device to the mainline Linux kernel.

General outline of the process:

* Get the downstream/vendor kernel source code
** Identify your device's board files
* Get the mainline kernel source code
* Add a DTS for your device based on values from downstream
* Build the kernel and flash it to the device
* Test it!

== Introduction ==

In the mainline kernel, a device's components are described in a structure known as the [https://wiki.mainlining.org/wiki/Devicetree device tree] (or devicetree, as is the official spelling). Device trees are compiled into DTBs (device tree blobs) from DTS (device tree source) files.

Adding support for a new device involves '''creating a DTS for that device''' - this is the process covered in this guide.

Device trees appeared in the kernel around version 3.4, and didn't see widespread use in vendor kernels until a few LTS versions later. Before device trees, each device usually had a ''board file'' - a C file that contained structs with driver data and initialization functions.

'''The downstream Kona kernels used board files.''' (They did have some partial DT support, but it was never used for any production devices.)

== Getting the kernel source ==

(WIP)

User:Uart/Draft:pmOS wiki admin processes

Uart — Tue, 18 Aug 2026 11:49:33 GMT

Created page with "{{todo|Not sure if this will be on the wiki itself or in a separate note...}} == Monitoring changes == Look through Special:RecentChanges and note: * New article creations. Make sure they are of good enough quality and usefulness to be in the main namespace, if not they should be moved under the user's userpage. * Redirects or page blanks. == Approving sign-ups == Sign-up approvals have historically been used to stop spambots. These are pretty much a non-issue n..."

New page

{{todo|Not sure if this will be on the wiki itself or in a separate note...}}

== Monitoring changes ==

Look through [[Special:RecentChanges]] and note:

* New article creations. Make sure they are of good enough quality and usefulness to be in the main namespace, if not they should be moved under the user's userpage.
* Redirects or page blanks.

== Approving sign-ups ==

Sign-up approvals have historically been used to stop spambots. These are pretty much a non-issue nowadays as they seem to have been completely stopped by Anubis, but it's still worth pre-screening potential editors.

When email-confirmed signups are pending, you will see a banner on the top of [[Special:RecentChanges]].

To approve accounts, go to [[Special:ConfirmAccounts]] and click on the "Open requests" tab. For each account:

* Open the "Review" tab.
* Look at the provided information.
** '''Things to look out for''' that might disqualify an account:
*** Presence of racist dogwhistles or slurs in username, bio, email or linked websites/socials: e.g. the number 1488 is used by Nazis. Deny with "Spam (do not send email)".
*** Nonsensical repeating phrases in bio.
**** Folks usually do this to get around the 6 words in bio requirement; check if they listed something in the Additional notes that might hint at what they actually want to do on the wiki. If not, feel free to deny the request and in the reason, politely ask them to explain why they want to sign up to the postmarketOS wiki (TODO write a template for this).
** '''Things that don't always disqualify candidates''':
*** Foreign language bios. (Make sure to translate them first in case they contain something inappropriate.)
*** People who mention running AI/agents, have vibecoded projects in their links, etc.
**** Exception - if you suspect an AI agent is attempting to create an account as part of a larger change plan (for example, there's a link to a code forge repo with AI-generated plans); in this case, deny the account and link to the AI policy in the reasoning.
** If you're unsure, you can leave the account request for another admin.
* Select "Approve" on the bottom, and click "Create account".
* You will be redirected to the CreateAccount page; click "Create account" there. This might take a few seconds.

If during either of these operations you get an error about expired session or cookies, just click the Approve/Create button again (it should remember the data).

== Renaming accounts ==

{{todo|Create a workflow for users to submit these requests privately; right now they have to go through public chats or guess who the admins are which is not ideal.}}

Admins can rename a user's account. To do so, go to [[Special:RenameUser]] and change the user's name.

Keep the "Move user and talk pages (and their subpages) to new name" option selected.

== Deleting accounts ==

If a user requests account deletion:

* Delete their user page and user talk page with the reason "Requested by user"
* Go to [[Special:BlockUser]] and block the user's account
** Block type: '''Sitewide'''
** Block details: '''Sending email, Editing their own talk page'''
** Expiration: '''indefinite'''
** Reason: '''Other''', "Requested by user"
** Additional options: '''Hide username from edits and lists'''
* Disable the account via [[Special:DisableAccount]]

TODO - if [https://www.mediawiki.org/wiki/Extension:UserMerge UserMerge] ever gets added: go to [[Special:UserMerge]] and merge the user, leaving the New User field empty (or write Anonymous)

== New admin onboarding ==

* Wiki admins should enable issue notifications on [https://gitlab.postmarketos.org/postmarketOS/wiki/-/work_items the wiki repo].
* Wiki admins should join and monitor the #postmarketOS-wiki IRC/Matrix channel.
* Go to the user's page and select "Change user groups" from the sidebar (or go to [[Special:UserRights]] and type in their username). Add them to the "administrators", "interface administrators", "bureaucrats", "suppressor" and "trusted" groups.

User:AltUart

AltUart — Sun, 09 Aug 2026 09:24:19 GMT

AltUart changed group membership for AltUart from bureaucrat and administrator to (none)

Main Page

AltUart — Sun, 09 Aug 2026 09:23:59 GMT

← Older revision		Revision as of 11:23, 9 August 2026
Line 5:		Line 5:
	* [[Mainline:BCM215xx]]		* [[Mainline:BCM215xx]]

	contact [~~[User~~:~~Knuxify]~~] for an account.		contact [https://uart.sh uart] for an account.

User:Knuxify/sidebartest

AltUart — Sun, 09 Aug 2026 09:23:32 GMT

AltUart moved page User:Knuxify/sidebartest to User:Uart/sidebartest Automatically moved page while renaming the user "Knuxify" to "Uart"

New page

This is an example page
[[Category:Sidebar test]]

User:Knuxify/Old BCM590xx regulator notes

AltUart — Sun, 09 Aug 2026 09:23:32 GMT

AltUart moved page User:Knuxify/Old BCM590xx regulator notes to User:Uart/Old BCM590xx regulator notes Automatically moved page while renaming the user "Knuxify" to "Uart"

New page

(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

User:Knuxify

AltUart — Sun, 09 Aug 2026 09:23:32 GMT

AltUart renamed user Knuxify (160 edits) to Uart rename

User:AltUart

Uart — Sun, 09 Aug 2026 09:04:03 GMT

Uart changed group membership for AltUart from (none) to administrator and bureaucrat

User:AltUart

Uart — Sun, 09 Aug 2026 09:03:41 GMT

User account AltUart was created by Uart