dissonant.dev wiki - User contributions [en]

Mainline:Broadcom Kona/Adding a new device

2026-08-23T19:56:09Z

Uart: /* Getting the downstream kernel source */

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

== Kernel compilation toolchain ==

To compile the kernel for the device, we will need a compiler toolchain for the ARM architecture.

For convenience, we will use pmbootstrap (the postmarketOS build tool) with its envkernel.sh script, which handles toolchain setup automatically (everything is installed in a chroot managed by pmbootstrap, so no manual work needs to be done on the host system), and gives us the extra benefit of building a ready initramfs and rootfs image to boot with.

=== mainline-tools setup ===

[https://uart.sh serialuart] uses a convenience script that wraps around envkernel.sh and automates the setup process and most commonly used commands: [https://github.com/refractionware/linux/tree/meta/mt mainline-tools].

This script sets up a couple of aliases, including:

* <code>mb</code> (<code>mainline-build</code>) - shorthand for <code>make -j$(nproc)</code>, used to build the kernel.
* <code>mp</code> (<code>mainline-package</code>) - creates a boot.img image for the built kernel.
* <code>mf</code> (<code>mainline-flash</code>) - flashes the boot.img generated with <code>mp</code>.
* <code>mbp</code> (<code>mainline-build-package</code>) - updates the postmarketOS kernel package (<code>linux-postmarketos-brcm-kona</code>) based on the build done with <code>mb</code>.
* <code>msp</code> (<code>mainline-sideload-pkg</code>) - sideloads the latest kernel package (needed to update modules).

{{note|A note about kernel packaging:

* boot.img only contains the kernel and built-in drivers (Y in defconfig).
* The kernel package (linux-postmarketos-brcm-kona) contains modules (M in defconfig).

Flashing boot.img (<code>mp</code> and <code>mf</code>) will only update built-in modules; to update non-built-in modules on the device, use <code>mbp</code> and <code>msp</code> to sideload over USB (or regenerate the image with <code>pmbootstrap install</code>).}}

To set up that script, run the following commands:

<syntaxhighlight lang="shell-session">
$ mkdir ~/code
$ cd ~/code
$ git clone https://gitlab.postmarketos.org/postmarketOS/pmbootstrap # git clone is needed for envkernel.sh, even if you already have pmbootstrap installed
$ wget https://raw.githubusercontent.com/refractionware/linux/refs/heads/meta/mt/mt.sh
$ source ~/code/mt.sh
</syntaxhighlight>

When you start a session, run <code>source ~/code/mt.sh</code> to enable mainline-tools.

== Getting the mainline kernel source ==

Broadcom Kona development happens in a close-to-mainline fork hosted on GitHub: [https://github.com/bcm-kona-mainline/linux bcm-kona-mainline/linux]

Clone the kernel from GitHub:

<syntaxhighlight lang="shell-session">
$ cd ~/code
$ git clone https://github.com/bcm-kona-mainline/linux
</syntaxhighlight>

== Getting the downstream kernel source ==

You will need to reference the downstream kernel for your device for the porting process; most likely someone has uploaded it to GitHub (look for android_kernel_(vendor)_(codename) repos).

Once you have the kernel downloaded, find the '''defconfig''' and '''board file''' for your device.

* The defconfig is in <code>arch/arm/configs</code>; if you got a CyanogenMod/LineageOS kernel, look for a <code>cyanogenmod_XXX_defconfig</code>; otherwise, there should be a config with a name like <code>bcmXXXXX_codename_revXX_defconfig</code> (pick the highest revision number).
* The board file is in <code>arch/arm/mach-PLATFORM/board-ss_CODENAME.c</code> (or just <code>board-CODENAME.c</code>), where PLATFORM is <code>capri</code> for BCM218xx, <code>rhea</code> for BCM21654, <code>hawaii</code> for BCM21664 and <code>java</code> for BCM23550.

== Adding a device package in postmarketOS ==

Run <code>pmbootstrap init</code>. When asked for the device, provide the vendor and codename.

* If you're asked to create a new device, follow the [https://wiki.postmarketos.org/wiki/Porting_to_a_new_device Porting Guide], using the <code>linux-postmarketos-brcm-kona</code> mainline kernel package.
* If this ends up selecting an existing downstream/archived device, you'll need to update the device package - see [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/8981/diffs?commit_id=fc2eb16282fe1b9dea7fb010533568899fad1bcb the commit doing this for samsung-baffinlite] as an example.

== Adding a DTS for your device ==

The DTS describes the hardware of the device. DTS files for Broadcom-based devices are located in <code>arch/arm/boot/dts/broadcom</code>.

{{hint|<code>[https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/arch/arm/boot/dts/broadcom/bcm23550-samsung-baffinlite.dts bcm23550-samsung-baffinlite.dts]</code> is a good reference point for DTSes for all Kona chips.}}

Create a new file in <code>arch/arm/boot/dts/broadcom</code> for your device with the filename <code>(soc)-(vendor)-(codename).dts</code> - for example, for a BCM21664 device with the codename samsung-kylepro, the filename will be <code>bcm21664-samsung-kylepro.dts</code>. Start from the following template (remove the comments when you're done):

<syntaxhighlight lang="devicetree">
// SPDX-License-Identifier: GPL-2.0-only
/*
* Common device tree for Samsung Galaxy Trend Plus/S Duos 2
* (kylepro/kyleprods).
*
* Copyright (c) 2026 Your Name <youremail@example.com>
*/

/dts-v1/;

#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/input/input.h>
#include <dt-bindings/leds/common.h>

// Depending on which SoC your device uses, change the following to:
// BCM2166x - "bcm21664.dtsi"
// BCM23550 - "bcm23550.dtsi"
// BCM281x5 - "bcm11351.dtsi"
#include "bcm21664.dtsi"

/ {
model = "Vendor Codename (MODEL-NUMBER)";
compatible = "vendor,codename", "brcm,bcm21664"; // remember to change the SoC compatible
chassis-type = "handset"; // usually "handset" (smartphone) or "tablet"

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x30000000>; /* 768 MB; CHANGEME */
};

reserved-memory {
#address-cells = <1>;
#size-cells = <1>;
ranges;

coprocessor_mem: coprocessor-mem@80000000 {
reg = <0x80000000 0x1e00000>;
no-map;
};

secure_mem: secure-mem@9d800000 {
reg = <0x9d800000 0x100000>;
no-map;
};

mobicore: mobicore@9d900000 {
reg = <0x9d900000 0x300000>;
no-map;
};
};
};
</syntaxhighlight>

Then, open <code>arch/arm/boot/dts/broadcom/Makefile</code>, and locate the following section:

<syntaxhighlight lang="makefile">
dtb-$(CONFIG_ARCH_BCM_MOBILE) += \
bcm28155-ap.dtb \
bcm21664-garnet.dtb \
bcm21664-samsung-kylepro.dtb \
bcm23550-samsung-baffinlite.dtb \
bcm23550-sparrow.dtb
</syntaxhighlight>

Add your DTS to the list, changing <code>.dts</code> to <code>.dtb</code>.

=== Filling out the memory node ===

To get the memory size, as well as reserved regions, run the following command under a downstream kernel (e.g. under TWRP):

<syntaxhighlight lang="shell-session">
$ cat /proc/iomem
81e00000-afffffff : System RAM
81e08000-823ec57b : Kernel code
8251c000-826d72ff : Kernel data
</syntaxhighlight>

From the above, the RAM would begin at <code>81e00000</code> and have a size of <code>(0xafffffff+1) - 0x81e00000 = 0x2e200000</code>.

{{todo|A lot of Samsung device kernels seem to be configured with a mem base of 0x81e00000, but in ATAG_MEM the 0x80000000 - 0x81e00000 chunk is also reported as a separate memory block as well.

This memory region is likely used for storing coprocessor firmware blobs and communication with the modem and other coprocessors (see {{downstream|baffinlite|arch/arm/mach-java/include/mach/comms/platform_mconfig_hawaii.h}}).

While from initial testing it seems safe to use with the modem disabled, I have included a <code>coprocessor_mem</code> block in the DTS snippet above to block out this region.

TODO - figure out how to print ATAGs without serial. Typically they get printed over UART by the bootloader right before loading the kernel.}}

=== UART ===

UART/serial is most notably used for sending debug logs over USB, but is also used for talking to the Bluetooth and GPS chip.

Check the downstream board file; look for a struct of type <code>plat_serial8250_port</code>. It should look something like this:

<syntaxhighlight lang="c">
static struct plat_serial8250_port hawaii_uart_platform_data[] = {
HAWAII_8250PORT(UART0, UARTB_PERI_CLK_NAME_STR, 48000000,
"bluetooth", NULL),
HAWAII_8250PORT(UART1, UARTB2_PERI_CLK_NAME_STR, 26000000,
"gps", &power_save_enable),
HAWAII_8250PORT(UART2, UARTB3_PERI_CLK_NAME_STR, 26000000,
"console", NULL),
{
.flags = 0,
},
}
</syntaxhighlight>

Note the numbers in the XXX_8250PORT macros; these represent the clock frequency.

Also note the names given to the ports; there are a hint for what the ports are used for. As seen above, the layout is usually - uartb for Bluetooth, uartb2 for GPS and uartb3 for serial console.

At the bottom of your DTS, add (change clock frequencies to match board file):

<syntaxhighlight lang="devicetree">
&uartb {
status = "okay";
clock-frequency = <48000000>;
};

&uartb2 {
status = "okay";
clock-frequency = <26000000>;
};

&uartb3 {
status = "okay";
clock-frequency = <26000000>;
};
</syntaxhighlight>

=== PMIC ===

Most Kona devices use BCM590xx series PMICs: BCM59054 for BCM21664/BCM23550, BCM59056 for BCM281xx and BCM59039 for BCM21654. The only known exceptions are the GT-I9150 (BCM281xx device with a BCM59054 and SMB358 for charging) and the GT-S6810 (Dialog DA2083).

The PMIC is connected to a separate PMIC I2C bus (or BSC, as Broadcom calls their "I2C-compatible" bus):

<syntaxhighlight lang="devicetree">

&pmu_bsc {
clock-frequency = <3400000>; /* 3.2mhz? Downstream refers to this as a HS bus, but it doesn't give any speed information other than that. */

pinctrl-0 = <&pmbsc_pins>;
pinctrl-names = "default";

status = "okay";

pmu: pmu@8 {
compatible = "brcm,bcm59054";
reg = <0x08>;
interrupt-parent = <&gpio>;
interrupts = <29 IRQ_TYPE_EDGE_FALLING>;

regulators {
/* ... */
};
};
};
</syntaxhighlight>

PMIC configuration is stored in a separate file in downstream, beginning with <code>board-bcm59xxx-(...).c</code> (same directory as the board file). Every regulator is described in this file, in <code>regulator_init_data</code> structs:

<syntaxhighlight lang="c">

__weak struct regulator_consumer_supply rf_supply[] = {
{.supply = "rf"},
};
static struct regulator_init_data bcm59xxx_rfldo_data = {
.constraints = {
.name = "rfldo",
.min_uV = 1300000,
.max_uV = 3300000,
.valid_ops_mask = REGULATOR_CHANGE_STATUS |
REGULATOR_CHANGE_VOLTAGE | REGULATOR_CHANGE_MODE,
.valid_modes_mask = REGULATOR_MODE_NORMAL |
REGULATOR_MODE_IDLE |
REGULATOR_MODE_STANDBY,
.always_on = 0,
.initial_mode = REGULATOR_MODE_STANDBY,
},
.num_consumer_supplies = ARRAY_SIZE(rf_supply),
.consumer_supplies = rf_supply,
};
</syntaxhighlight>

Equivalent DTS fragment:

<syntaxhighlight lang="devicetree">
rfldo_reg: rfldo {
regulator-min-microvolt = <1300000>;
regulator-max-microvolt = <3300000>;
regulator-always-on;
/* regulator-allowed-modes = <0x2 0x4 0x8>; */ /* NORMAL, IDLE, STANDBY */
/* regulator-initial-mode = <0x8>; */ /* REGULATOR_MODE_STANDBY */
};
</syntaxhighlight>

Repeat for all regulator types; see DT bindings for reference ([https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/Documentation/devicetree/bindings/regulator/brcm%2Cbcm59054.yaml BCM59054], [https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/Documentation/devicetree/bindings/regulator/brcm%2Cbcm59056.yaml BCM59056]).

=== SDIO/Storage ===

SDIO is used for internal storage, the SD card and WiFi.

In the downstream board file, look for <code>sdio_platform_cfg</code> structs. Here's an example:

<syntaxhighlight lang="c">

static struct sdio_platform_cfg hawaii_sdio_param[] = {
{
.id = 0,
.data_pullup = 0,
.cd_gpio = SD_CARDDET_GPIO_PIN,
.devtype = SDIO_DEV_TYPE_SDMMC,
.flags = KONA_SDIO_FLAGS_DEVICE_REMOVABLE,
.peri_clk_name = "sdio1_clk",
.ahb_clk_name = "sdio1_ahb_clk",
.sleep_clk_name = "sdio1_sleep_clk",
.peri_clk_rate = 48000000,
/*The SD card regulator*/
.vddo_regulator_name = "vdd_sdio",
/*The SD controller regulator*/
.vddsdxc_regulator_name = "vdd_sdxc",
.configure_sdio_pullup = configure_sdio_pullup,
},
{
.id = 1,
.data_pullup = 0,
.is_8bit = 1,
.devtype = SDIO_DEV_TYPE_EMMC,
.flags = KONA_SDIO_FLAGS_DEVICE_NON_REMOVABLE ,
.peri_clk_name = "sdio2_clk",
.ahb_clk_name = "sdio2_ahb_clk",
.sleep_clk_name = "sdio2_sleep_clk",
.peri_clk_rate = 52000000,
},
{
.id = 2,
.data_pullup = 0,
.devtype = SDIO_DEV_TYPE_WIFI,
.flags = KONA_SDIO_FLAGS_DEVICE_REMOVABLE,
.peri_clk_name = "sdio3_clk",
.ahb_clk_name = "sdio3_ahb_clk",
.sleep_clk_name = "sdio3_sleep_clk",
.peri_clk_rate = 48000000,
#ifdef CONFIG_BRCM_UNIFIED_DHD_SUPPORT
.wifi_gpio = {
.reset = 3,
.reg = -1,
.host_wake = 74,
.shutdown = -1,
},
.register_status_notify = hawaii_wifi_status_register,
#endif
},
};
</syntaxhighlight>

Things of note:

* <code>.peri_clk_rate</code> is equivalent to <code>max-frequency</code> in DT;
* <code>.is_8bit = 1</code> is equivalent to <code>bus-width = <8></code>;
* <code>.cd_gpio</code> contains the card detect GPIO for the SD card slot. It is usually defined as a macro, the value is defined earlier in the board file. Here it's <code>91</code>.
* <code>.vddo_regulator_name</code> and <code>.vddsdxc_regulator_name</code> become <code>vmmc-supply</code> and <code>vqmmc-supply</code> respectively. To find which regulator they are attached to, look up the names in your board file; you might find a struct like such: <syntaxhighlight lang="c">struct regulator_consumer_supply sd_supply[] = {
{.supply = "sdldo_uc"},
REGULATOR_SUPPLY("vddmmc", "sdhci.3"), /* 0x3f1b0000.sdhci */
{.supply = "vdd_sdio"},
};

struct regulator_consumer_supply sdx_supply[] = {
{.supply = "sdxldo_uc"},
REGULATOR_SUPPLY("vddo", "sdhci.3"), /* 0x3f1b0000.sdhci */
{.supply = "vdd_sdxc"},
};</syntaxhighlight>
The first listed supply should show you the name of the BCM59xxx supply - in this case, <code>sdldo</code> and <code>sdxldo</code>.

Equivalent mainline DTS:

<syntaxhighlight lang="devicetree">

/* SD card */
&sdio1 {
max-frequency = <48000000>;

cd-gpios = <&gpio 91 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
vmmc-supply = <&sdldo_reg>;
vqmmc-supply = <&sdxldo_reg>;

/* NOTE: skip pinctrl here and in the other nodes for BCM28155, we don't have ready-made pinctrl definitions for it yet */
pinctrl-0 = <&sd_width4_pins>;
pinctrl-names = "default";

status = "okay";
};

/* Internal storage */
&sdio2 {
max-frequency = <52000000>;

keep-power-in-suspend;
non-removable;
bus-width = <8>;

pinctrl-0 = <&mmc0_width8_pins>;
pinctrl-names = "default";

status = "okay";
};

/* WiFi */
&sdio3 {
max-frequency = <48000000>;

#address-cells = <1>;
#size-cells = <0>;

pinctrl-0 = <&mmc1_width4_pins>;
pinctrl-names = "default";

// NOTE: Non-removable is hardcoded for the WiFi SDIO in the downstream driver, even if the board file claims it's removable.
keep-power-in-suspend;
non-removable;

status = "okay";
};
</syntaxhighlight>

=== I2C/BSC ===

Most sensors, as well as the touchscreen, are connected over I2C. Broadcom SoCs actually have an I2C-compatible bus called BSC.

Finding exactly which sensors are used is a bit difficult, because board files tend to have data for a lot of sensors that is unused. You will need to look for sections guarded with <code>#ifdef CONFIG_...</code>; for the config option values, reference the downstream defconfig file for your device.

In general, it's best to look through the defconfig first and find all the relevant options for sensors (look up keywords like SENSOR, PROXIMITY, ACCEL, MAG, LIGHT, TOUCH, INPUT...).

(Alternatively, if you have a Samsung device, reference [https://docs.google.com/spreadsheets/d/1NioX9a2vgbEcO_Zs9COUFO-n3a2Rqf1JWWU1cfsktLM/edit?gid=0#gid=0 the spreadsheet].)

In the board file, look for <code>i2c_board_info</code> structs:

<syntaxhighlight lang="c">
#if defined(CONFIG_SENSORS_BMM050)
#define BMA2X2_SLAVE_ADDR 0x10
#else
#define BMA2X2_SLAVE_ADDR 0x18
#endif

static struct i2c_board_info __initdata bsc3_i2c_boardinfo[] =
{

#if defined(CONFIG_SENSORS_BMC150)
#if defined(CONFIG_SENSORS_BMA2X2)
{
I2C_BOARD_INFO("bma2x2", BMA2X2_SLAVE_ADDR),
.platform_data = &bss_bma2x2,
},
#endif
#if defined(CONFIG_SENSORS_BMM050)
{
I2C_BOARD_INFO("bmm050", 0x12),
.platform_data = &bss_bmm050,
},
#endif
#endif

#if defined (CONFIG_SENSORS_HSCDTD006A) || defined(CONFIG_SENSORS_HSCDTD008A)
{
I2C_BOARD_INFO("hscd_i2c", 0x0c),
.platform_data = &hscd_i2c_platform_data,
},
#endif

#if defined(CONFIG_SENSORS_GP2AP002)
{
I2C_BOARD_INFO("gp2ap002",0x44),
.platform_data = &gp2ap002_platform_data,
}
#endif
}
</syntaxhighlight>

Do a <code>grep -iR</code> with the codename in <code>drivers</code> in mainline to see if you can spot a driver for the sensor you want to add. Many sensors from that era are already supported in mainline. You can look at other device trees (<code>arch/arm/boot/dts</code> and <code>arch/arm64/boot/dts</code>) as well as DT bindings (<code>Documentation/devicetree/bindings</code>) to figure out how to add them to your DTS.

For the exact values to use in DT, you'll have to look at the <code>platform_data</code> struct, and sometimes at the driver for the peripheral (which you can usually find by grepping the downstream source code for the model number/driver name).

<syntaxhighlight lang="devicetree">
&bsc3 {
clock-frequency = <400000>;

// NOTE: again, pinctrl only applies to BCM21664/BCM23550 at the moment
pinctrl-0 = <&bsc3_pins>;
pinctrl-names = "default";

status = "okay";

magnetometer@c {
compatible = "alps,hscdtd008a";
reg = <0x0c>;
};

accel@18 {
compatible = "bosch,bma254";
reg = <0x18>;

/* ... */
};

proximity@44 {
compatible = "sharp,gp2ap002s00f";
reg = <0x44>;

/* ... */
};
};
</syntaxhighlight>

=== USB ===

USB comprises of 3 parts:

* The USB OTG controller (usbotg node);
* The USB PHY (usbphy node);
* The USB mode switch (not all devices - BCM59039 devices don't seem to be paired with a switch).

Commonly used switches include the FSA9480/9485, TSUxxxx and RTxxxx. Look them up in your defconfig (keywords: FSA, TSU, RT).

On Samsung devices, the switches are often connected over I2C-GPIO (which is an I2C bus bitbanged over GPIO pins). Example from baffinlite:

<syntaxhighlight lang="c">
#define GPIO_FSA9485_I2C_SDA 113
#define GPIO_FSA9485_I2C_SCL 114
#define GPIO_FSA9485_INT 56

/* ... */

static struct i2c_board_info __initdata micro_usb_i2c_devices_info[] = {
{
I2C_BOARD_INFO("fsa9485", 0x4A >> 1),
.platform_data = &fsa9485_pdata,
.irq = gpio_to_irq(GPIO_FSA9485_INT),
},
};

static struct i2c_gpio_platform_data fsa_i2c_gpio_data={
.sda_pin = GPIO_FSA9485_I2C_SDA,
.scl_pin = GPIO_FSA9485_I2C_SCL,
.udelay = 2,
};
</syntaxhighlight>

Note - <code>0x4A >> 1</code> means a bit shift, you can paste it into the Python interpreter and it will give you the value (<code>hex(0x4A >> 1)</code> gives <code>0x25</code>).

In mainline, this becomes:

<syntaxhighlight lang="devicetree">
/ {
/* (add this under the / node ) */

/* ... */

/* USB switch */
i2c-musb {
#address-cells = <1>;
#size-cells = <0>;
compatible = "i2c-gpio";
sda-gpios = <&gpio 113 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
scl-gpios = <&gpio 114 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
i2c-gpio,delay-us = <2>;

musb@25 {
compatible = "fcs,fsa9480";
reg = <0x25>;
interrupt-parent = <&gpio>;
interrupts = <56 IRQ_TYPE_LEVEL_HIGH>;

connector {
compatible = "samsung,usb-connector-11pin",
"usb-b-connector";
label = "micro-USB";
type = "micro";

ports {
#address-cells = <1>;
#size-cells = <0>;

port@0 {
reg = <0>;

muic_to_usb: endpoint {
remote-endpoint = <&usb_to_muic>;
};
};
};
};

};
};
/* ... */
};
</syntaxhighlight>

Once you have the switch, you can add the remaining USB nodes:

<syntaxhighlight lang="devicetree">
&usbotg {
vusb_d-supply = <&usbldo_reg>;
vusb_a-supply = <&iosr1_reg>;
vbus-supply = <&vbus_reg>;
dr_mode = "otg";
role-switch-default-mode = "peripheral";
usb-role-switch;
status = "okay";

// if your device has no switch, drop the port node below
port {
usb_to_muic: endpoint {
remote-endpoint = <&muic_to_usb>;
};
};
};

&usbphy {
status = "okay";
};
</syntaxhighlight>

=== WiFi and Bluetooth ===

Most Broadcom devices use Broadcom WiFi/Bluetooth chips from the BCM43xx series. (Look up BCM43 in your defconfig, or reference downstream kernel dmesg for the exact model.)

The below examples are for BCM4330. If you have another chip, you can grep for it in the mainline kernel (<code>arch/arm/boot/dts</code>) and see what compatibles are used by other devices.

The Bluetooth chip goes under the UART bus that was labeled as "bluetooth":

<syntaxhighlight lang="devicetree">
&uartb {
status = "okay";
clock-frequency = <48000000>;

bluetooth {
compatible = "brcm,bcm4330-bt";

shutdown-gpios = <&gpio 28 GPIO_ACTIVE_HIGH>;
device-wakeup-gpios = <&gpio 32 GPIO_ACTIVE_HIGH>;
host-wakeup-gpios = <&gpio 72 GPIO_ACTIVE_HIGH>;
reset-gpios = <&gpio 71 GPIO_ACTIVE_LOW>;
interrupt-parent = <&gpio>;
interrupts = <72 IRQ_TYPE_EDGE_FALLING>;
};
};
</syntaxhighlight>

To get the GPIOs:

* Look for <code>bcmbt_platform_data</code>; <code>.bt_wake_gpio</code> becomes <code>device-wakeup-gpios</code>, and <code>.host_wake_gpio</code> becomes <code>host-wakeup-gpios</code>.
* Look for <code>bcmbt_rfkill_platform_data</code>; <code>.vreg_gpio</code> becomes <code>shutdown-gpios</code>, and <code>.n_reset_gpio</code> becomes <code>reset-gpios</code>.

For WiFi, add the following under the <code>/</code> node:

<syntaxhighlight lang="devicetree">
/ {
/* ... */

/* GPIO regulator for WiFi */
wl_reg: regulator-gpio-wlan {
compatible = "regulator-fixed";
regulator-name = "WL_REG_ON";
regulator-min-microvolt = <3000000>;
regulator-max-microvolt = <3000000>;
startup-delay-us = <100000>;
gpio = <&gpio 3 GPIO_ACTIVE_HIGH>;
enable-active-high;
};

/* ... */
};
</syntaxhighlight>

(Get the GPIO from <code>board_wifi_info</code>, member <code>.wl_reset_gpio</code>).

Then, update the SDIO node for WiFi:

<syntaxhighlight lang="devicetree">
/* WiFi */
&sdio3 {
max-frequency = <48000000>;

/* Actually a regulator for the WiFi chip */
vmmc-supply = <&wl_reg>;

#address-cells = <1>;
#size-cells = <0>;

pinctrl-0 = <&mmc1_width4_pins>;
pinctrl-names = "default";

keep-power-in-suspend;
non-removable;

status = "okay";

wifi@1 {
compatible = "brcm,bcm4330-fmac", "brcm,bcm4329-fmac";
reg = <1>;

interrupt-parent = <&gpio>;
interrupts = <74 IRQ_TYPE_EDGE_FALLING>;
interrupt-names = "host-wake";
};
};
</syntaxhighlight>

(Get the interrupt from <code>board_wifi_info</code>, member <code>.host_wake_gpio</code>).

=== GPIO keys ===

Many Samsung devices use GPIO-based keys for the volume up/down and home keys. (The power button is handled by the PMIC, and the touchkeys (menu/back next to home button) are usually handled by the touchscreen).

<syntaxhighlight lang="c">
#define GPIO_KEYS_SETTINGS { \
{ KEY_VOLUMEUP,9, 1, "VOLUMEUP", EV_KEY, 0, 64}, \
{ KEY_HOME, 10, 1, "HOME", EV_KEY, 0, 64}, \
{ KEY_VOLUMEDOWN,11, 1, "VOLUMEDOWN", EV_KEY, 0, 64}, \
}

#if defined(CONFIG_KEYBOARD_GPIO) || defined(CONFIG_KEYBOARD_GPIO_MODULE)
static struct gpio_keys_button board_gpio_keys[] = GPIO_KEYS_SETTINGS;
/* ... */
#endif
</syntaxhighlight>

Equivalent DT fragment:

<syntaxhighlight lang="devicetree">
/ {
/* ... */

/* Buttons */
gpio-keys {
compatible = "gpio-keys";

key-volume-up {
label = "Volume Up";
gpios = <&gpio 9 GPIO_ACTIVE_LOW>;
linux,code = <KEY_VOLUMEUP>;
};

key-home {
label = "Home";
gpios = <&gpio 10 GPIO_ACTIVE_LOW>;
linux,code = <KEY_HOMEPAGE>;
};

key-volume-down {
label = "Volume Down";
gpios = <&gpio 11 GPIO_ACTIVE_LOW>;
linux,code = <KEY_VOLUMEDOWN>;
};
};

/* ... */
};
</syntaxhighlight>

=== Keypad ===

{{note|Keypad is only added for BCM21664/BCM23550 at the moment; it's most likely the same for BCM28155, just a matter of adding the right node like [https://github.com/bcm-kona-mainline/linux/commit/86a15664bdfe457bcd994b2ae72f722509259b53 in the equivalent bcm21664-common.dtsi commit].}}

Some devices use the built-in keypad peripheral for volume up/down keys. If you have <code>CONFIG_KEYBOARD_BCM</code> enabled in downstream defconfig, look for <code>bcm_keymap</code> in your board file:

<syntaxhighlight lang="c">
#ifdef CONFIG_KEYBOARD_BCM
static struct bcm_keymap hawaii_keymap[] = {
{BCM_KEY_ROW_0, BCM_KEY_COL_0, "unused", 0},
{BCM_KEY_ROW_0, BCM_KEY_COL_1, "Vol Down Key", KEY_VOLUMEDOWN},
{BCM_KEY_ROW_0, BCM_KEY_COL_2, "unused", 0},
{BCM_KEY_ROW_0, BCM_KEY_COL_3, "Vol Up Key", KEY_VOLUMEUP},
{BCM_KEY_ROW_0, BCM_KEY_COL_4, "unused", 0},
{BCM_KEY_ROW_0, BCM_KEY_COL_5, "unused", 0},
/* ... */
};

static struct bcm_keypad_platform_info hawaii_keypad_data = {
.row_num = 1,
.col_num = 5,
.keymap = hawaii_keymap,
.bcm_keypad_base = (void *)__iomem HW_IO_PHYS_TO_VIRT(KEYPAD_BASE_ADDR),
};

#endif
</syntaxhighlight>

Equivalent DTS:

<syntaxhighlight lang="devicetree">
&keypad {
keypad,num-rows = <1>;
keypad,num-columns = <5>;

linux,keymap = <MATRIX_KEY(0x00, 0x01, KEY_VOLUMEDOWN)>,
<MATRIX_KEY(0x00, 0x03, KEY_VOLUMEUP)>;

status = "okay";
};
</syntaxhighlight>

== Building the kernel ==

To apply the pmOS Broadcom Kona defconfig:

<syntaxhighlight lang="shell-session">
$ make bcmkona_pmos_defconfig
</syntaxhighlight>

To build the kernel:

<syntaxhighlight lang="shell-session">
$ make -j$(nproc)
-- or, with mainline-tools: --
$ mb
</syntaxhighlight>

If you have mainline-tools, you can flash the kernel with:

<syntaxhighlight lang="shell-session">
$ mp
$ mf
</syntaxhighlight>

Mainline:Broadcom Kona/Adding a new device

2026-08-23T19:52:19Z

Uart:

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

== Kernel compilation toolchain ==

To compile the kernel for the device, we will need a compiler toolchain for the ARM architecture.

For convenience, we will use pmbootstrap (the postmarketOS build tool) with its envkernel.sh script, which handles toolchain setup automatically (everything is installed in a chroot managed by pmbootstrap, so no manual work needs to be done on the host system), and gives us the extra benefit of building a ready initramfs and rootfs image to boot with.

=== mainline-tools setup ===

[https://uart.sh serialuart] uses a convenience script that wraps around envkernel.sh and automates the setup process and most commonly used commands: [https://github.com/refractionware/linux/tree/meta/mt mainline-tools].

This script sets up a couple of aliases, including:

* <code>mb</code> (<code>mainline-build</code>) - shorthand for <code>make -j$(nproc)</code>, used to build the kernel.
* <code>mp</code> (<code>mainline-package</code>) - creates a boot.img image for the built kernel.
* <code>mf</code> (<code>mainline-flash</code>) - flashes the boot.img generated with <code>mp</code>.
* <code>mbp</code> (<code>mainline-build-package</code>) - updates the postmarketOS kernel package (<code>linux-postmarketos-brcm-kona</code>) based on the build done with <code>mb</code>.
* <code>msp</code> (<code>mainline-sideload-pkg</code>) - sideloads the latest kernel package (needed to update modules).

{{note|A note about kernel packaging:

* boot.img only contains the kernel and built-in drivers (Y in defconfig).
* The kernel package (linux-postmarketos-brcm-kona) contains modules (M in defconfig).

Flashing boot.img (<code>mp</code> and <code>mf</code>) will only update built-in modules; to update non-built-in modules on the device, use <code>mbp</code> and <code>msp</code> to sideload over USB (or regenerate the image with <code>pmbootstrap install</code>).}}

To set up that script, run the following commands:

<syntaxhighlight lang="shell-session">
$ mkdir ~/code
$ cd ~/code
$ git clone https://gitlab.postmarketos.org/postmarketOS/pmbootstrap # git clone is needed for envkernel.sh, even if you already have pmbootstrap installed
$ wget https://raw.githubusercontent.com/refractionware/linux/refs/heads/meta/mt/mt.sh
$ source ~/code/mt.sh
</syntaxhighlight>

When you start a session, run <code>source ~/code/mt.sh</code> to enable mainline-tools.

== Getting the mainline kernel source ==

Broadcom Kona development happens in a close-to-mainline fork hosted on GitHub: [https://github.com/bcm-kona-mainline/linux bcm-kona-mainline/linux]

Clone the kernel from GitHub:

<syntaxhighlight lang="shell-session">
$ cd ~/code
$ git clone https://github.com/bcm-kona-mainline/linux
</syntaxhighlight>

== Getting the downstream kernel source ==

You will need to reference the downstream kernel for your device for the porting process; most likely someone has uploaded it to GitHub (look for android_kernel_(vendor)_(codename) repos).

Once you have the kernel downloaded, find the '''defconfig''' and '''board file''' for your device.

* The defconfig is in <code>arch/arm/configs</code>; if you got a CyanogenMod/LineageOS kernel, look for a <code>cyanogenmod_XXX_defconfig</code>; otherwise, there should be a config with a name like <code>bcmXXXXX_codename_revXX_defconfig</code> (pick the highest revision number).
* The board config is in <code>arch/arm/mach-PLATFORM/board-ss_CODENAME.c</code> (or just <code>board-CODENAME.c</code>), where PLATFORM is <code>capri</code> for BCM218xx, <code>rhea</code> for BCM21654, <code>hawaii</code> for BCM21664 and <code>java</code> for BCM23550.

== Adding a device package in postmarketOS ==

Run <code>pmbootstrap init</code>. When asked for the device, provide the vendor and codename.

* If you're asked to create a new device, follow the [https://wiki.postmarketos.org/wiki/Porting_to_a_new_device Porting Guide], using the <code>linux-postmarketos-brcm-kona</code> mainline kernel package.
* If this ends up selecting an existing downstream/archived device, you'll need to update the device package - see [https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/8981/diffs?commit_id=fc2eb16282fe1b9dea7fb010533568899fad1bcb the commit doing this for samsung-baffinlite] as an example.

== Adding a DTS for your device ==

The DTS describes the hardware of the device. DTS files for Broadcom-based devices are located in <code>arch/arm/boot/dts/broadcom</code>.

{{hint|<code>[https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/arch/arm/boot/dts/broadcom/bcm23550-samsung-baffinlite.dts bcm23550-samsung-baffinlite.dts]</code> is a good reference point for DTSes for all Kona chips.}}

Create a new file in <code>arch/arm/boot/dts/broadcom</code> for your device with the filename <code>(soc)-(vendor)-(codename).dts</code> - for example, for a BCM21664 device with the codename samsung-kylepro, the filename will be <code>bcm21664-samsung-kylepro.dts</code>. Start from the following template (remove the comments when you're done):

<syntaxhighlight lang="devicetree">
// SPDX-License-Identifier: GPL-2.0-only
/*
* Common device tree for Samsung Galaxy Trend Plus/S Duos 2
* (kylepro/kyleprods).
*
* Copyright (c) 2026 Your Name <youremail@example.com>
*/

/dts-v1/;

#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/input/input.h>
#include <dt-bindings/leds/common.h>

// Depending on which SoC your device uses, change the following to:
// BCM2166x - "bcm21664.dtsi"
// BCM23550 - "bcm23550.dtsi"
// BCM281x5 - "bcm11351.dtsi"
#include "bcm21664.dtsi"

/ {
model = "Vendor Codename (MODEL-NUMBER)";
compatible = "vendor,codename", "brcm,bcm21664"; // remember to change the SoC compatible
chassis-type = "handset"; // usually "handset" (smartphone) or "tablet"

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x30000000>; /* 768 MB; CHANGEME */
};

reserved-memory {
#address-cells = <1>;
#size-cells = <1>;
ranges;

coprocessor_mem: coprocessor-mem@80000000 {
reg = <0x80000000 0x1e00000>;
no-map;
};

secure_mem: secure-mem@9d800000 {
reg = <0x9d800000 0x100000>;
no-map;
};

mobicore: mobicore@9d900000 {
reg = <0x9d900000 0x300000>;
no-map;
};
};
};
</syntaxhighlight>

Then, open <code>arch/arm/boot/dts/broadcom/Makefile</code>, and locate the following section:

<syntaxhighlight lang="makefile">
dtb-$(CONFIG_ARCH_BCM_MOBILE) += \
bcm28155-ap.dtb \
bcm21664-garnet.dtb \
bcm21664-samsung-kylepro.dtb \
bcm23550-samsung-baffinlite.dtb \
bcm23550-sparrow.dtb
</syntaxhighlight>

Add your DTS to the list, changing <code>.dts</code> to <code>.dtb</code>.

=== Filling out the memory node ===

To get the memory size, as well as reserved regions, run the following command under a downstream kernel (e.g. under TWRP):

<syntaxhighlight lang="shell-session">
$ cat /proc/iomem
81e00000-afffffff : System RAM
81e08000-823ec57b : Kernel code
8251c000-826d72ff : Kernel data
</syntaxhighlight>

From the above, the RAM would begin at <code>81e00000</code> and have a size of <code>(0xafffffff+1) - 0x81e00000 = 0x2e200000</code>.

{{todo|A lot of Samsung device kernels seem to be configured with a mem base of 0x81e00000, but in ATAG_MEM the 0x80000000 - 0x81e00000 chunk is also reported as a separate memory block as well.

This memory region is likely used for storing coprocessor firmware blobs and communication with the modem and other coprocessors (see {{downstream|baffinlite|arch/arm/mach-java/include/mach/comms/platform_mconfig_hawaii.h}}).

While from initial testing it seems safe to use with the modem disabled, I have included a <code>coprocessor_mem</code> block in the DTS snippet above to block out this region.

TODO - figure out how to print ATAGs without serial. Typically they get printed over UART by the bootloader right before loading the kernel.}}

=== UART ===

UART/serial is most notably used for sending debug logs over USB, but is also used for talking to the Bluetooth and GPS chip.

Check the downstream board file; look for a struct of type <code>plat_serial8250_port</code>. It should look something like this:

<syntaxhighlight lang="c">
static struct plat_serial8250_port hawaii_uart_platform_data[] = {
HAWAII_8250PORT(UART0, UARTB_PERI_CLK_NAME_STR, 48000000,
"bluetooth", NULL),
HAWAII_8250PORT(UART1, UARTB2_PERI_CLK_NAME_STR, 26000000,
"gps", &power_save_enable),
HAWAII_8250PORT(UART2, UARTB3_PERI_CLK_NAME_STR, 26000000,
"console", NULL),
{
.flags = 0,
},
}
</syntaxhighlight>

Note the numbers in the XXX_8250PORT macros; these represent the clock frequency.

Also note the names given to the ports; there are a hint for what the ports are used for. As seen above, the layout is usually - uartb for Bluetooth, uartb2 for GPS and uartb3 for serial console.

At the bottom of your DTS, add (change clock frequencies to match board file):

<syntaxhighlight lang="devicetree">
&uartb {
status = "okay";
clock-frequency = <48000000>;
};

&uartb2 {
status = "okay";
clock-frequency = <26000000>;
};

&uartb3 {
status = "okay";
clock-frequency = <26000000>;
};
</syntaxhighlight>

=== PMIC ===

Most Kona devices use BCM590xx series PMICs: BCM59054 for BCM21664/BCM23550, BCM59056 for BCM281xx and BCM59039 for BCM21654. The only known exceptions are the GT-I9150 (BCM281xx device with a BCM59054 and SMB358 for charging) and the GT-S6810 (Dialog DA2083).

The PMIC is connected to a separate PMIC I2C bus (or BSC, as Broadcom calls their "I2C-compatible" bus):

<syntaxhighlight lang="devicetree">

&pmu_bsc {
clock-frequency = <3400000>; /* 3.2mhz? Downstream refers to this as a HS bus, but it doesn't give any speed information other than that. */

pinctrl-0 = <&pmbsc_pins>;
pinctrl-names = "default";

status = "okay";

pmu: pmu@8 {
compatible = "brcm,bcm59054";
reg = <0x08>;
interrupt-parent = <&gpio>;
interrupts = <29 IRQ_TYPE_EDGE_FALLING>;

regulators {
/* ... */
};
};
};
</syntaxhighlight>

PMIC configuration is stored in a separate file in downstream, beginning with <code>board-bcm59xxx-(...).c</code> (same directory as the board file). Every regulator is described in this file, in <code>regulator_init_data</code> structs:

<syntaxhighlight lang="c">

__weak struct regulator_consumer_supply rf_supply[] = {
{.supply = "rf"},
};
static struct regulator_init_data bcm59xxx_rfldo_data = {
.constraints = {
.name = "rfldo",
.min_uV = 1300000,
.max_uV = 3300000,
.valid_ops_mask = REGULATOR_CHANGE_STATUS |
REGULATOR_CHANGE_VOLTAGE | REGULATOR_CHANGE_MODE,
.valid_modes_mask = REGULATOR_MODE_NORMAL |
REGULATOR_MODE_IDLE |
REGULATOR_MODE_STANDBY,
.always_on = 0,
.initial_mode = REGULATOR_MODE_STANDBY,
},
.num_consumer_supplies = ARRAY_SIZE(rf_supply),
.consumer_supplies = rf_supply,
};
</syntaxhighlight>

Equivalent DTS fragment:

<syntaxhighlight lang="devicetree">
rfldo_reg: rfldo {
regulator-min-microvolt = <1300000>;
regulator-max-microvolt = <3300000>;
regulator-always-on;
/* regulator-allowed-modes = <0x2 0x4 0x8>; */ /* NORMAL, IDLE, STANDBY */
/* regulator-initial-mode = <0x8>; */ /* REGULATOR_MODE_STANDBY */
};
</syntaxhighlight>

Repeat for all regulator types; see DT bindings for reference ([https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/Documentation/devicetree/bindings/regulator/brcm%2Cbcm59054.yaml BCM59054], [https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/Documentation/devicetree/bindings/regulator/brcm%2Cbcm59056.yaml BCM59056]).

=== SDIO/Storage ===

SDIO is used for internal storage, the SD card and WiFi.

In the downstream board file, look for <code>sdio_platform_cfg</code> structs. Here's an example:

<syntaxhighlight lang="c">

static struct sdio_platform_cfg hawaii_sdio_param[] = {
{
.id = 0,
.data_pullup = 0,
.cd_gpio = SD_CARDDET_GPIO_PIN,
.devtype = SDIO_DEV_TYPE_SDMMC,
.flags = KONA_SDIO_FLAGS_DEVICE_REMOVABLE,
.peri_clk_name = "sdio1_clk",
.ahb_clk_name = "sdio1_ahb_clk",
.sleep_clk_name = "sdio1_sleep_clk",
.peri_clk_rate = 48000000,
/*The SD card regulator*/
.vddo_regulator_name = "vdd_sdio",
/*The SD controller regulator*/
.vddsdxc_regulator_name = "vdd_sdxc",
.configure_sdio_pullup = configure_sdio_pullup,
},
{
.id = 1,
.data_pullup = 0,
.is_8bit = 1,
.devtype = SDIO_DEV_TYPE_EMMC,
.flags = KONA_SDIO_FLAGS_DEVICE_NON_REMOVABLE ,
.peri_clk_name = "sdio2_clk",
.ahb_clk_name = "sdio2_ahb_clk",
.sleep_clk_name = "sdio2_sleep_clk",
.peri_clk_rate = 52000000,
},
{
.id = 2,
.data_pullup = 0,
.devtype = SDIO_DEV_TYPE_WIFI,
.flags = KONA_SDIO_FLAGS_DEVICE_REMOVABLE,
.peri_clk_name = "sdio3_clk",
.ahb_clk_name = "sdio3_ahb_clk",
.sleep_clk_name = "sdio3_sleep_clk",
.peri_clk_rate = 48000000,
#ifdef CONFIG_BRCM_UNIFIED_DHD_SUPPORT
.wifi_gpio = {
.reset = 3,
.reg = -1,
.host_wake = 74,
.shutdown = -1,
},
.register_status_notify = hawaii_wifi_status_register,
#endif
},
};
</syntaxhighlight>

Things of note:

* <code>.peri_clk_rate</code> is equivalent to <code>max-frequency</code> in DT;
* <code>.is_8bit = 1</code> is equivalent to <code>bus-width = <8></code>;
* <code>.cd_gpio</code> contains the card detect GPIO for the SD card slot. It is usually defined as a macro, the value is defined earlier in the board file. Here it's <code>91</code>.
* <code>.vddo_regulator_name</code> and <code>.vddsdxc_regulator_name</code> become <code>vmmc-supply</code> and <code>vqmmc-supply</code> respectively. To find which regulator they are attached to, look up the names in your board file; you might find a struct like such: <syntaxhighlight lang="c">struct regulator_consumer_supply sd_supply[] = {
{.supply = "sdldo_uc"},
REGULATOR_SUPPLY("vddmmc", "sdhci.3"), /* 0x3f1b0000.sdhci */
{.supply = "vdd_sdio"},
};

struct regulator_consumer_supply sdx_supply[] = {
{.supply = "sdxldo_uc"},
REGULATOR_SUPPLY("vddo", "sdhci.3"), /* 0x3f1b0000.sdhci */
{.supply = "vdd_sdxc"},
};</syntaxhighlight>
The first listed supply should show you the name of the BCM59xxx supply - in this case, <code>sdldo</code> and <code>sdxldo</code>.

Equivalent mainline DTS:

<syntaxhighlight lang="devicetree">

/* SD card */
&sdio1 {
max-frequency = <48000000>;

cd-gpios = <&gpio 91 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
vmmc-supply = <&sdldo_reg>;
vqmmc-supply = <&sdxldo_reg>;

/* NOTE: skip pinctrl here and in the other nodes for BCM28155, we don't have ready-made pinctrl definitions for it yet */
pinctrl-0 = <&sd_width4_pins>;
pinctrl-names = "default";

status = "okay";
};

/* Internal storage */
&sdio2 {
max-frequency = <52000000>;

keep-power-in-suspend;
non-removable;
bus-width = <8>;

pinctrl-0 = <&mmc0_width8_pins>;
pinctrl-names = "default";

status = "okay";
};

/* WiFi */
&sdio3 {
max-frequency = <48000000>;

#address-cells = <1>;
#size-cells = <0>;

pinctrl-0 = <&mmc1_width4_pins>;
pinctrl-names = "default";

// NOTE: Non-removable is hardcoded for the WiFi SDIO in the downstream driver, even if the board file claims it's removable.
keep-power-in-suspend;
non-removable;

status = "okay";
};
</syntaxhighlight>

=== I2C/BSC ===

Most sensors, as well as the touchscreen, are connected over I2C. Broadcom SoCs actually have an I2C-compatible bus called BSC.

Finding exactly which sensors are used is a bit difficult, because board files tend to have data for a lot of sensors that is unused. You will need to look for sections guarded with <code>#ifdef CONFIG_...</code>; for the config option values, reference the downstream defconfig file for your device.

In general, it's best to look through the defconfig first and find all the relevant options for sensors (look up keywords like SENSOR, PROXIMITY, ACCEL, MAG, LIGHT, TOUCH, INPUT...).

(Alternatively, if you have a Samsung device, reference [https://docs.google.com/spreadsheets/d/1NioX9a2vgbEcO_Zs9COUFO-n3a2Rqf1JWWU1cfsktLM/edit?gid=0#gid=0 the spreadsheet].)

In the board file, look for <code>i2c_board_info</code> structs:

<syntaxhighlight lang="c">
#if defined(CONFIG_SENSORS_BMM050)
#define BMA2X2_SLAVE_ADDR 0x10
#else
#define BMA2X2_SLAVE_ADDR 0x18
#endif

static struct i2c_board_info __initdata bsc3_i2c_boardinfo[] =
{

#if defined(CONFIG_SENSORS_BMC150)
#if defined(CONFIG_SENSORS_BMA2X2)
{
I2C_BOARD_INFO("bma2x2", BMA2X2_SLAVE_ADDR),
.platform_data = &bss_bma2x2,
},
#endif
#if defined(CONFIG_SENSORS_BMM050)
{
I2C_BOARD_INFO("bmm050", 0x12),
.platform_data = &bss_bmm050,
},
#endif
#endif

#if defined (CONFIG_SENSORS_HSCDTD006A) || defined(CONFIG_SENSORS_HSCDTD008A)
{
I2C_BOARD_INFO("hscd_i2c", 0x0c),
.platform_data = &hscd_i2c_platform_data,
},
#endif

#if defined(CONFIG_SENSORS_GP2AP002)
{
I2C_BOARD_INFO("gp2ap002",0x44),
.platform_data = &gp2ap002_platform_data,
}
#endif
}
</syntaxhighlight>

Do a <code>grep -iR</code> with the codename in <code>drivers</code> in mainline to see if you can spot a driver for the sensor you want to add. Many sensors from that era are already supported in mainline. You can look at other device trees (<code>arch/arm/boot/dts</code> and <code>arch/arm64/boot/dts</code>) as well as DT bindings (<code>Documentation/devicetree/bindings</code>) to figure out how to add them to your DTS.

For the exact values to use in DT, you'll have to look at the <code>platform_data</code> struct, and sometimes at the driver for the peripheral (which you can usually find by grepping the downstream source code for the model number/driver name).

<syntaxhighlight lang="devicetree">
&bsc3 {
clock-frequency = <400000>;

// NOTE: again, pinctrl only applies to BCM21664/BCM23550 at the moment
pinctrl-0 = <&bsc3_pins>;
pinctrl-names = "default";

status = "okay";

magnetometer@c {
compatible = "alps,hscdtd008a";
reg = <0x0c>;
};

accel@18 {
compatible = "bosch,bma254";
reg = <0x18>;

/* ... */
};

proximity@44 {
compatible = "sharp,gp2ap002s00f";
reg = <0x44>;

/* ... */
};
};
</syntaxhighlight>

=== USB ===

USB comprises of 3 parts:

* The USB OTG controller (usbotg node);
* The USB PHY (usbphy node);
* The USB mode switch (not all devices - BCM59039 devices don't seem to be paired with a switch).

Commonly used switches include the FSA9480/9485, TSUxxxx and RTxxxx. Look them up in your defconfig (keywords: FSA, TSU, RT).

On Samsung devices, the switches are often connected over I2C-GPIO (which is an I2C bus bitbanged over GPIO pins). Example from baffinlite:

<syntaxhighlight lang="c">
#define GPIO_FSA9485_I2C_SDA 113
#define GPIO_FSA9485_I2C_SCL 114
#define GPIO_FSA9485_INT 56

/* ... */

static struct i2c_board_info __initdata micro_usb_i2c_devices_info[] = {
{
I2C_BOARD_INFO("fsa9485", 0x4A >> 1),
.platform_data = &fsa9485_pdata,
.irq = gpio_to_irq(GPIO_FSA9485_INT),
},
};

static struct i2c_gpio_platform_data fsa_i2c_gpio_data={
.sda_pin = GPIO_FSA9485_I2C_SDA,
.scl_pin = GPIO_FSA9485_I2C_SCL,
.udelay = 2,
};
</syntaxhighlight>

Note - <code>0x4A >> 1</code> means a bit shift, you can paste it into the Python interpreter and it will give you the value (<code>hex(0x4A >> 1)</code> gives <code>0x25</code>).

In mainline, this becomes:

<syntaxhighlight lang="devicetree">
/ {
/* (add this under the / node ) */

/* ... */

/* USB switch */
i2c-musb {
#address-cells = <1>;
#size-cells = <0>;
compatible = "i2c-gpio";
sda-gpios = <&gpio 113 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
scl-gpios = <&gpio 114 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
i2c-gpio,delay-us = <2>;

musb@25 {
compatible = "fcs,fsa9480";
reg = <0x25>;
interrupt-parent = <&gpio>;
interrupts = <56 IRQ_TYPE_LEVEL_HIGH>;

connector {
compatible = "samsung,usb-connector-11pin",
"usb-b-connector";
label = "micro-USB";
type = "micro";

ports {
#address-cells = <1>;
#size-cells = <0>;

port@0 {
reg = <0>;

muic_to_usb: endpoint {
remote-endpoint = <&usb_to_muic>;
};
};
};
};

};
};
/* ... */
};
</syntaxhighlight>

Once you have the switch, you can add the remaining USB nodes:

<syntaxhighlight lang="devicetree">
&usbotg {
vusb_d-supply = <&usbldo_reg>;
vusb_a-supply = <&iosr1_reg>;
vbus-supply = <&vbus_reg>;
dr_mode = "otg";
role-switch-default-mode = "peripheral";
usb-role-switch;
status = "okay";

// if your device has no switch, drop the port node below
port {
usb_to_muic: endpoint {
remote-endpoint = <&muic_to_usb>;
};
};
};

&usbphy {
status = "okay";
};
</syntaxhighlight>

=== WiFi and Bluetooth ===

Most Broadcom devices use Broadcom WiFi/Bluetooth chips from the BCM43xx series. (Look up BCM43 in your defconfig, or reference downstream kernel dmesg for the exact model.)

The below examples are for BCM4330. If you have another chip, you can grep for it in the mainline kernel (<code>arch/arm/boot/dts</code>) and see what compatibles are used by other devices.

The Bluetooth chip goes under the UART bus that was labeled as "bluetooth":

<syntaxhighlight lang="devicetree">
&uartb {
status = "okay";
clock-frequency = <48000000>;

bluetooth {
compatible = "brcm,bcm4330-bt";

shutdown-gpios = <&gpio 28 GPIO_ACTIVE_HIGH>;
device-wakeup-gpios = <&gpio 32 GPIO_ACTIVE_HIGH>;
host-wakeup-gpios = <&gpio 72 GPIO_ACTIVE_HIGH>;
reset-gpios = <&gpio 71 GPIO_ACTIVE_LOW>;
interrupt-parent = <&gpio>;
interrupts = <72 IRQ_TYPE_EDGE_FALLING>;
};
};
</syntaxhighlight>

To get the GPIOs:

* Look for <code>bcmbt_platform_data</code>; <code>.bt_wake_gpio</code> becomes <code>device-wakeup-gpios</code>, and <code>.host_wake_gpio</code> becomes <code>host-wakeup-gpios</code>.
* Look for <code>bcmbt_rfkill_platform_data</code>; <code>.vreg_gpio</code> becomes <code>shutdown-gpios</code>, and <code>.n_reset_gpio</code> becomes <code>reset-gpios</code>.

For WiFi, add the following under the <code>/</code> node:

<syntaxhighlight lang="devicetree">
/ {
/* ... */

/* GPIO regulator for WiFi */
wl_reg: regulator-gpio-wlan {
compatible = "regulator-fixed";
regulator-name = "WL_REG_ON";
regulator-min-microvolt = <3000000>;
regulator-max-microvolt = <3000000>;
startup-delay-us = <100000>;
gpio = <&gpio 3 GPIO_ACTIVE_HIGH>;
enable-active-high;
};

/* ... */
};
</syntaxhighlight>

(Get the GPIO from <code>board_wifi_info</code>, member <code>.wl_reset_gpio</code>).

Then, update the SDIO node for WiFi:

<syntaxhighlight lang="devicetree">
/* WiFi */
&sdio3 {
max-frequency = <48000000>;

/* Actually a regulator for the WiFi chip */
vmmc-supply = <&wl_reg>;

#address-cells = <1>;
#size-cells = <0>;

pinctrl-0 = <&mmc1_width4_pins>;
pinctrl-names = "default";

keep-power-in-suspend;
non-removable;

status = "okay";

wifi@1 {
compatible = "brcm,bcm4330-fmac", "brcm,bcm4329-fmac";
reg = <1>;

interrupt-parent = <&gpio>;
interrupts = <74 IRQ_TYPE_EDGE_FALLING>;
interrupt-names = "host-wake";
};
};
</syntaxhighlight>

(Get the interrupt from <code>board_wifi_info</code>, member <code>.host_wake_gpio</code>).

=== GPIO keys ===

Many Samsung devices use GPIO-based keys for the volume up/down and home keys. (The power button is handled by the PMIC, and the touchkeys (menu/back next to home button) are usually handled by the touchscreen).

<syntaxhighlight lang="c">
#define GPIO_KEYS_SETTINGS { \
{ KEY_VOLUMEUP,9, 1, "VOLUMEUP", EV_KEY, 0, 64}, \
{ KEY_HOME, 10, 1, "HOME", EV_KEY, 0, 64}, \
{ KEY_VOLUMEDOWN,11, 1, "VOLUMEDOWN", EV_KEY, 0, 64}, \
}

#if defined(CONFIG_KEYBOARD_GPIO) || defined(CONFIG_KEYBOARD_GPIO_MODULE)
static struct gpio_keys_button board_gpio_keys[] = GPIO_KEYS_SETTINGS;
/* ... */
#endif
</syntaxhighlight>

Equivalent DT fragment:

<syntaxhighlight lang="devicetree">
/ {
/* ... */

/* Buttons */
gpio-keys {
compatible = "gpio-keys";

key-volume-up {
label = "Volume Up";
gpios = <&gpio 9 GPIO_ACTIVE_LOW>;
linux,code = <KEY_VOLUMEUP>;
};

key-home {
label = "Home";
gpios = <&gpio 10 GPIO_ACTIVE_LOW>;
linux,code = <KEY_HOMEPAGE>;
};

key-volume-down {
label = "Volume Down";
gpios = <&gpio 11 GPIO_ACTIVE_LOW>;
linux,code = <KEY_VOLUMEDOWN>;
};
};

/* ... */
};
</syntaxhighlight>

=== Keypad ===

{{note|Keypad is only added for BCM21664/BCM23550 at the moment; it's most likely the same for BCM28155, just a matter of adding the right node like [https://github.com/bcm-kona-mainline/linux/commit/86a15664bdfe457bcd994b2ae72f722509259b53 in the equivalent bcm21664-common.dtsi commit].}}

Some devices use the built-in keypad peripheral for volume up/down keys. If you have <code>CONFIG_KEYBOARD_BCM</code> enabled in downstream defconfig, look for <code>bcm_keymap</code> in your board file:

<syntaxhighlight lang="c">
#ifdef CONFIG_KEYBOARD_BCM
static struct bcm_keymap hawaii_keymap[] = {
{BCM_KEY_ROW_0, BCM_KEY_COL_0, "unused", 0},
{BCM_KEY_ROW_0, BCM_KEY_COL_1, "Vol Down Key", KEY_VOLUMEDOWN},
{BCM_KEY_ROW_0, BCM_KEY_COL_2, "unused", 0},
{BCM_KEY_ROW_0, BCM_KEY_COL_3, "Vol Up Key", KEY_VOLUMEUP},
{BCM_KEY_ROW_0, BCM_KEY_COL_4, "unused", 0},
{BCM_KEY_ROW_0, BCM_KEY_COL_5, "unused", 0},
/* ... */
};

static struct bcm_keypad_platform_info hawaii_keypad_data = {
.row_num = 1,
.col_num = 5,
.keymap = hawaii_keymap,
.bcm_keypad_base = (void *)__iomem HW_IO_PHYS_TO_VIRT(KEYPAD_BASE_ADDR),
};

#endif
</syntaxhighlight>

Equivalent DTS:

<syntaxhighlight lang="devicetree">
&keypad {
keypad,num-rows = <1>;
keypad,num-columns = <5>;

linux,keymap = <MATRIX_KEY(0x00, 0x01, KEY_VOLUMEDOWN)>,
<MATRIX_KEY(0x00, 0x03, KEY_VOLUMEUP)>;

status = "okay";
};
</syntaxhighlight>

== Building the kernel ==

To apply the pmOS Broadcom Kona defconfig:

<syntaxhighlight lang="shell-session">
$ make bcmkona_pmos_defconfig
</syntaxhighlight>

To build the kernel:

<syntaxhighlight lang="shell-session">
$ make -j$(nproc)
-- or, with mainline-tools: --
$ mb
</syntaxhighlight>

If you have mainline-tools, you can flash the kernel with:

<syntaxhighlight lang="shell-session">
$ mp
$ mf
</syntaxhighlight>

Mainline:Broadcom Kona/Adding a new device

2026-08-23T14:10:52Z

Uart:

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

== Kernel compilation toolchain ==

To compile the kernel for the device, we will need a compiler toolchain for the ARM architecture.

For convenience, we will use pmbootstrap (the postmarketOS build tool) with its envkernel.sh script, which handles toolchain setup automatically (everything is installed in a chroot managed by pmbootstrap, so no manual work needs to be done on the host system), and gives us the extra benefit of building a ready initramfs and rootfs image to boot with.

=== mainline-tools setup ===

[https://uart.sh serialuart] uses a convenience script that wraps around envkernel.sh and automates the setup process and most commonly used commands: [https://github.com/refractionware/linux/tree/meta/mt mainline-tools].

This script sets up a couple of aliases, including:

* <code>mb</code> (<code>mainline-build</code>) - shorthand for <code>make -j$(nproc)</code>, used to build the kernel.
* <code>mp</code> (<code>mainline-package</code>) - creates a boot.img image for the built kernel.
* <code>mf</code> (<code>mainline-flash</code>) - flashes the boot.img generated with <code>mp</code>.
* <code>mbp</code> (<code>mainline-build-package</code>) - updates the postmarketOS kernel package (<code>linux-postmarketos-brcm-kona</code>) based on the build done with <code>mb</code>.
* <code>msp</code> (<code>mainline-sideload-pkg</code>) - sideloads the latest kernel package (needed to update modules).

{{note|A note about kernel packaging:

* boot.img only contains the kernel and built-in drivers (Y in defconfig).
* The kernel package (linux-postmarketos-brcm-kona) contains modules (M in defconfig).

Flashing boot.img (<code>mp</code> and <code>mf</code>) will only update built-in modules; to update non-built-in modules on the device, use <code>mbp</code> and <code>msp</code> to sideload over USB (or regenerate the image with <code>pmbootstrap install</code>).}}

To set up that script, run the following commands:

<syntaxhighlight lang="shell-session">
$ mkdir ~/code
$ cd ~/code
$ git clone https://gitlab.postmarketos.org/postmarketOS/pmbootstrap # git clone is needed for envkernel.sh, even if you already have pmbootstrap installed
$ wget https://raw.githubusercontent.com/refractionware/linux/refs/heads/meta/mt/mt.sh
$ source ~/code/mt.sh
</syntaxhighlight>

When you start a session, run <code>source ~/code/mt.sh</code> to enable mainline-tools.

== Getting the mainline kernel source ==

Broadcom Kona development happens in a close-to-mainline fork hosted on GitHub: [https://github.com/bcm-kona-mainline/linux bcm-kona-mainline/linux]

Clone the kernel from GitHub:

<syntaxhighlight lang="shell-session">
$ cd ~/code
$ git clone https://github.com/bcm-kona-mainline/linux
</syntaxhighlight>

== Getting the downstream kernel source ==

You will need to reference the downstream kernel for your device for the porting process; most likely someone has uploaded it to GitHub (look for android_kernel_(vendor)_(codename) repos).

Once you have the kernel downloaded, find the '''defconfig''' and '''board file''' for your device.

* The defconfig is in <code>arch/arm/configs</code>; if you got a CyanogenMod/LineageOS kernel, look for a <code>cyanogenmod_XXX_defconfig</code>; otherwise, there should be a config with a name like <code>bcmXXXXX_codename_revXX_defconfig</code> (pick the highest revision number).
* The board config is in <code>arch/arm/mach-PLATFORM/board-ss_CODENAME.c</code> (or just <code>board-CODENAME.c</code>), where PLATFORM is <code>capri</code> for BCM218xx, <code>rhea</code> for BCM21654, <code>hawaii</code> for BCM21664 and <code>java</code> for BCM23550.

== Adding a DTS for your device ==

The DTS describes the hardware of the device. DTS files for Broadcom-based devices are located in <code>arch/arm/boot/dts/broadcom</code>.

{{hint|<code>[https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/arch/arm/boot/dts/broadcom/bcm23550-samsung-baffinlite.dts bcm23550-samsung-baffinlite.dts]</code> is a good reference point for DTSes for all Kona chips.}}

Create a new file in <code>arch/arm/boot/dts/broadcom</code> for your device with the filename <code>(soc)-(vendor)-(codename).dts</code> - for example, for a BCM21664 device with the codename samsung-kylepro, the filename will be <code>bcm21664-samsung-kylepro.dts</code>. Start from the following template (remove the comments when you're done):

<syntaxhighlight lang="devicetree">
// SPDX-License-Identifier: GPL-2.0-only
/*
* Common device tree for Samsung Galaxy Trend Plus/S Duos 2
* (kylepro/kyleprods).
*
* Copyright (c) 2026 Your Name <youremail@example.com>
*/

/dts-v1/;

#include <dt-bindings/gpio/gpio.h>
#include <dt-bindings/input/input.h>
#include <dt-bindings/leds/common.h>

// Depending on which SoC your device uses, change the following to:
// BCM2166x - "bcm21664.dtsi"
// BCM23550 - "bcm23550.dtsi"
// BCM281x5 - "bcm11351.dtsi"
#include "bcm21664.dtsi"

/ {
model = "Vendor Codename (MODEL-NUMBER)";
compatible = "vendor,codename", "brcm,bcm21664"; // remember to change the SoC compatible
chassis-type = "handset"; // usually "handset" (smartphone) or "tablet"

memory@80000000 {
device_type = "memory";
reg = <0x80000000 0x30000000>; /* 768 MB; CHANGEME */
};

reserved-memory {
#address-cells = <1>;
#size-cells = <1>;
ranges;

coprocessor_mem: coprocessor-mem@80000000 {
reg = <0x80000000 0x1e00000>;
no-map;
};

secure_mem: secure-mem@9d800000 {
reg = <0x9d800000 0x100000>;
no-map;
};

mobicore: mobicore@9d900000 {
reg = <0x9d900000 0x300000>;
no-map;
};
};
};
</syntaxhighlight>

Then, open <code>arch/arm/boot/dts/broadcom/Makefile</code>, and locate the following section:

<syntaxhighlight lang="makefile">
dtb-$(CONFIG_ARCH_BCM_MOBILE) += \
bcm28155-ap.dtb \
bcm21664-garnet.dtb \
bcm21664-samsung-kylepro.dtb \
bcm23550-samsung-baffinlite.dtb \
bcm23550-sparrow.dtb
</syntaxhighlight>

Add your DTS to the list, changing <code>.dts</code> to <code>.dtb</code>.

=== Filling out the memory node ===

To get the memory size, as well as reserved regions, run the following command under a downstream kernel (e.g. under TWRP):

<syntaxhighlight lang="shell-session">
$ cat /proc/iomem
81e00000-afffffff : System RAM
81e08000-823ec57b : Kernel code
8251c000-826d72ff : Kernel data
</syntaxhighlight>

From the above, the RAM would begin at <code>81e00000</code> and have a size of <code>(0xafffffff+1) - 0x81e00000 = 0x2e200000</code>.

{{todo|A lot of Samsung device kernels seem to be configured with a mem base of 0x81e00000, but in ATAG_MEM the 0x80000000 - 0x81e00000 chunk is also reported as a separate memory block as well.

This memory region is likely used for storing coprocessor firmware blobs and communication with the modem and other coprocessors (see {{downstream|baffinlite|arch/arm/mach-java/include/mach/comms/platform_mconfig_hawaii.h}}).

While from initial testing it seems safe to use with the modem disabled, I have included a <code>coprocessor_mem</code> block in the DTS snippet above to block out this region.

TODO - figure out how to print ATAGs without serial. Typically they get printed over UART by the bootloader right before loading the kernel.}}

=== UART ===

UART/serial is most notably used for sending debug logs over USB, but is also used for talking to the Bluetooth and GPS chip.

Check the downstream board file; look for a struct of type <code>plat_serial8250_port</code>. It should look something like this:

<syntaxhighlight lang="c">
static struct plat_serial8250_port hawaii_uart_platform_data[] = {
HAWAII_8250PORT(UART0, UARTB_PERI_CLK_NAME_STR, 48000000,
"bluetooth", NULL),
HAWAII_8250PORT(UART1, UARTB2_PERI_CLK_NAME_STR, 26000000,
"gps", &power_save_enable),
HAWAII_8250PORT(UART2, UARTB3_PERI_CLK_NAME_STR, 26000000,
"console", NULL),
{
.flags = 0,
},
}
</syntaxhighlight>

Note the numbers in the XXX_8250PORT macros; these represent the clock frequency.

Also note the names given to the ports; there are a hint for what the ports are used for. As seen above, the layout is usually - uartb for Bluetooth, uartb2 for GPS and uartb3 for serial console.

At the bottom of your DTS, add (change clock frequencies to match board file):

<syntaxhighlight lang="devicetree">
&uartb {
status = "okay";
clock-frequency = <48000000>;
};

&uartb2 {
status = "okay";
clock-frequency = <26000000>;
};

&uartb3 {
status = "okay";
clock-frequency = <26000000>;
};
</syntaxhighlight>

=== PMIC ===

Most Kona devices use BCM590xx series PMICs: BCM59054 for BCM21664/BCM23550, BCM59056 for BCM281xx and BCM59039 for BCM21654. The only known exceptions are the GT-I9150 (BCM281xx device with a BCM59054 and SMB358 for charging) and the GT-S6810 (Dialog DA2083).

The PMIC is connected to a separate PMIC I2C bus (or BSC, as Broadcom calls their "I2C-compatible" bus):

<syntaxhighlight lang="devicetree">

&pmu_bsc {
clock-frequency = <3400000>; /* 3.2mhz? Downstream refers to this as a HS bus, but it doesn't give any speed information other than that. */

pinctrl-0 = <&pmbsc_pins>;
pinctrl-names = "default";

status = "okay";

pmu: pmu@8 {
compatible = "brcm,bcm59054";
reg = <0x08>;
interrupt-parent = <&gpio>;
interrupts = <29 IRQ_TYPE_EDGE_FALLING>;

regulators {
/* ... */
};
};
};
</syntaxhighlight>

PMIC configuration is stored in a separate file in downstream, beginning with <code>board-bcm59xxx-(...).c</code> (same directory as the board file). Every regulator is described in this file, in <code>regulator_init_data</code> structs:

<syntaxhighlight lang="c">

__weak struct regulator_consumer_supply rf_supply[] = {
{.supply = "rf"},
};
static struct regulator_init_data bcm59xxx_rfldo_data = {
.constraints = {
.name = "rfldo",
.min_uV = 1300000,
.max_uV = 3300000,
.valid_ops_mask = REGULATOR_CHANGE_STATUS |
REGULATOR_CHANGE_VOLTAGE | REGULATOR_CHANGE_MODE,
.valid_modes_mask = REGULATOR_MODE_NORMAL |
REGULATOR_MODE_IDLE |
REGULATOR_MODE_STANDBY,
.always_on = 0,
.initial_mode = REGULATOR_MODE_STANDBY,
},
.num_consumer_supplies = ARRAY_SIZE(rf_supply),
.consumer_supplies = rf_supply,
};
</syntaxhighlight>

Equivalent DTS fragment:

<syntaxhighlight lang="devicetree">
rfldo_reg: rfldo {
regulator-min-microvolt = <1300000>;
regulator-max-microvolt = <3300000>;
regulator-always-on;
/* regulator-allowed-modes = <0x2 0x4 0x8>; */ /* NORMAL, IDLE, STANDBY */
/* regulator-initial-mode = <0x8>; */ /* REGULATOR_MODE_STANDBY */
};
</syntaxhighlight>

Repeat for all regulator types; see DT bindings for reference ([https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/Documentation/devicetree/bindings/regulator/brcm%2Cbcm59054.yaml BCM59054], [https://github.com/bcm-kona-mainline/linux/blob/kona/7.1/Documentation/devicetree/bindings/regulator/brcm%2Cbcm59056.yaml BCM59056]).

=== SDIO/Storage ===

SDIO is used for internal storage, the SD card and WiFi.

In the downstream board file, look for <code>sdio_platform_cfg</code> structs. Here's an example:

<syntaxhighlight lang="c">

static struct sdio_platform_cfg hawaii_sdio_param[] = {
{
.id = 0,
.data_pullup = 0,
.cd_gpio = SD_CARDDET_GPIO_PIN,
.devtype = SDIO_DEV_TYPE_SDMMC,
.flags = KONA_SDIO_FLAGS_DEVICE_REMOVABLE,
.peri_clk_name = "sdio1_clk",
.ahb_clk_name = "sdio1_ahb_clk",
.sleep_clk_name = "sdio1_sleep_clk",
.peri_clk_rate = 48000000,
/*The SD card regulator*/
.vddo_regulator_name = "vdd_sdio",
/*The SD controller regulator*/
.vddsdxc_regulator_name = "vdd_sdxc",
.configure_sdio_pullup = configure_sdio_pullup,
},
{
.id = 1,
.data_pullup = 0,
.is_8bit = 1,
.devtype = SDIO_DEV_TYPE_EMMC,
.flags = KONA_SDIO_FLAGS_DEVICE_NON_REMOVABLE ,
.peri_clk_name = "sdio2_clk",
.ahb_clk_name = "sdio2_ahb_clk",
.sleep_clk_name = "sdio2_sleep_clk",
.peri_clk_rate = 52000000,
},
{
.id = 2,
.data_pullup = 0,
.devtype = SDIO_DEV_TYPE_WIFI,
.flags = KONA_SDIO_FLAGS_DEVICE_REMOVABLE,
.peri_clk_name = "sdio3_clk",
.ahb_clk_name = "sdio3_ahb_clk",
.sleep_clk_name = "sdio3_sleep_clk",
.peri_clk_rate = 48000000,
#ifdef CONFIG_BRCM_UNIFIED_DHD_SUPPORT
.wifi_gpio = {
.reset = 3,
.reg = -1,
.host_wake = 74,
.shutdown = -1,
},
.register_status_notify = hawaii_wifi_status_register,
#endif
},
};
</syntaxhighlight>

Things of note:

* <code>.peri_clk_rate</code> is equivalent to <code>max-frequency</code> in DT;
* <code>.is_8bit = 1</code> is equivalent to <code>bus-width = <8></code>;
* <code>.cd_gpio</code> contains the card detect GPIO for the SD card slot. It is usually defined as a macro, the value is defined earlier in the board file. Here it's <code>91</code>.
* <code>.vddo_regulator_name</code> and <code>.vddsdxc_regulator_name</code> become <code>vmmc-supply</code> and <code>vqmmc-supply</code> respectively. To find which regulator they are attached to, look up the names in your board file; you might find a struct like such: <syntaxhighlight lang="c">struct regulator_consumer_supply sd_supply[] = {
{.supply = "sdldo_uc"},
REGULATOR_SUPPLY("vddmmc", "sdhci.3"), /* 0x3f1b0000.sdhci */
{.supply = "vdd_sdio"},
};

struct regulator_consumer_supply sdx_supply[] = {
{.supply = "sdxldo_uc"},
REGULATOR_SUPPLY("vddo", "sdhci.3"), /* 0x3f1b0000.sdhci */
{.supply = "vdd_sdxc"},
};</syntaxhighlight>
The first listed supply should show you the name of the BCM59xxx supply - in this case, <code>sdldo</code> and <code>sdxldo</code>.

Equivalent mainline DTS:

<syntaxhighlight lang="devicetree">

/* SD card */
&sdio1 {
max-frequency = <48000000>;

cd-gpios = <&gpio 91 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
vmmc-supply = <&sdldo_reg>;
vqmmc-supply = <&sdxldo_reg>;

/* NOTE: skip pinctrl here and in the other nodes for BCM28155, we don't have ready-made pinctrl definitions for it yet */
pinctrl-0 = <&sd_width4_pins>;
pinctrl-names = "default";

status = "okay";
};

/* Internal storage */
&sdio2 {
max-frequency = <52000000>;

keep-power-in-suspend;
non-removable;
bus-width = <8>;

pinctrl-0 = <&mmc0_width8_pins>;
pinctrl-names = "default";

status = "okay";
};

/* WiFi */
&sdio3 {
max-frequency = <48000000>;

#address-cells = <1>;
#size-cells = <0>;

pinctrl-0 = <&mmc1_width4_pins>;
pinctrl-names = "default";

// NOTE: Non-removable is hardcoded for the WiFi SDIO in the downstream driver, even if the board file claims it's removable.
keep-power-in-suspend;
non-removable;

status = "okay";
};
</syntaxhighlight>

=== I2C/BSC ===

Most sensors, as well as the touchscreen, are connected over I2C. Broadcom SoCs actually have an I2C-compatible bus called BSC.

Finding exactly which sensors are used is a bit difficult, because board files tend to have data for a lot of sensors that is unused. You will need to look for sections guarded with <code>#ifdef CONFIG_...</code>; for the config option values, reference the downstream defconfig file for your device.

In general, it's best to look through the defconfig first and find all the relevant options for sensors (look up keywords like SENSOR, PROXIMITY, ACCEL, MAG, LIGHT, TOUCH, INPUT...).

(Alternatively, if you have a Samsung device, reference [https://docs.google.com/spreadsheets/d/1NioX9a2vgbEcO_Zs9COUFO-n3a2Rqf1JWWU1cfsktLM/edit?gid=0#gid=0 the spreadsheet].)

In the board file, look for <code>i2c_board_info</code> structs:

<syntaxhighlight lang="c">
#if defined(CONFIG_SENSORS_BMM050)
#define BMA2X2_SLAVE_ADDR 0x10
#else
#define BMA2X2_SLAVE_ADDR 0x18
#endif

static struct i2c_board_info __initdata bsc3_i2c_boardinfo[] =
{

#if defined(CONFIG_SENSORS_BMC150)
#if defined(CONFIG_SENSORS_BMA2X2)
{
I2C_BOARD_INFO("bma2x2", BMA2X2_SLAVE_ADDR),
.platform_data = &bss_bma2x2,
},
#endif
#if defined(CONFIG_SENSORS_BMM050)
{
I2C_BOARD_INFO("bmm050", 0x12),
.platform_data = &bss_bmm050,
},
#endif
#endif

#if defined (CONFIG_SENSORS_HSCDTD006A) || defined(CONFIG_SENSORS_HSCDTD008A)
{
I2C_BOARD_INFO("hscd_i2c", 0x0c),
.platform_data = &hscd_i2c_platform_data,
},
#endif

#if defined(CONFIG_SENSORS_GP2AP002)
{
I2C_BOARD_INFO("gp2ap002",0x44),
.platform_data = &gp2ap002_platform_data,
}
#endif
}
</syntaxhighlight>

Do a <code>grep -iR</code> with the codename in <code>drivers</code> in mainline to see if you can spot a driver for the sensor you want to add. Many sensors from that era are already supported in mainline. You can look at other device trees (<code>arch/arm/boot/dts</code> and <code>arch/arm64/boot/dts</code>) as well as DT bindings (<code>Documentation/devicetree/bindings</code>) to figure out how to add them to your DTS.

For the exact values to use in DT, you'll have to look at the <code>platform_data</code> struct, and sometimes at the driver for the peripheral (which you can usually find by grepping the downstream source code for the model number/driver name).

<syntaxhighlight lang="devicetree">
&bsc3 {
clock-frequency = <400000>;

// NOTE: again, pinctrl only applies to BCM21664/BCM23550 at the moment
pinctrl-0 = <&bsc3_pins>;
pinctrl-names = "default";

status = "okay";

magnetometer@c {
compatible = "alps,hscdtd008a";
reg = <0x0c>;
};

accel@18 {
compatible = "bosch,bma254";
reg = <0x18>;

/* ... */
};

proximity@44 {
compatible = "sharp,gp2ap002s00f";
reg = <0x44>;

/* ... */
};
};
</syntaxhighlight>

=== USB ===

USB comprises of 3 parts:

* The USB OTG controller (usbotg node);
* The USB PHY (usbphy node);
* The USB mode switch (not all devices - BCM59039 devices don't seem to be paired with a switch).

Commonly used switches include the FSA9480/9485, TSUxxxx and RTxxxx. Look them up in your defconfig (keywords: FSA, TSU, RT).

On Samsung devices, the switches are often connected over I2C-GPIO (which is an I2C bus bitbanged over GPIO pins). Example from baffinlite:

<syntaxhighlight lang="c">
#define GPIO_FSA9485_I2C_SDA 113
#define GPIO_FSA9485_I2C_SCL 114
#define GPIO_FSA9485_INT 56

/* ... */

static struct i2c_board_info __initdata micro_usb_i2c_devices_info[] = {
{
I2C_BOARD_INFO("fsa9485", 0x4A >> 1),
.platform_data = &fsa9485_pdata,
.irq = gpio_to_irq(GPIO_FSA9485_INT),
},
};

static struct i2c_gpio_platform_data fsa_i2c_gpio_data={
.sda_pin = GPIO_FSA9485_I2C_SDA,
.scl_pin = GPIO_FSA9485_I2C_SCL,
.udelay = 2,
};
</syntaxhighlight>

Note - <code>0x4A >> 1</code> means a bit shift, you can paste it into the Python interpreter and it will give you the value (<code>hex(0x4A >> 1)</code> gives <code>0x25</code>).

In mainline, this becomes:

<syntaxhighlight lang="devicetree">
/ {
/* (add this under the / node ) */

/* ... */

/* USB switch */
i2c-musb {
#address-cells = <1>;
#size-cells = <0>;
compatible = "i2c-gpio";
sda-gpios = <&gpio 113 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
scl-gpios = <&gpio 114 (GPIO_ACTIVE_HIGH | GPIO_OPEN_DRAIN)>;
i2c-gpio,delay-us = <2>;

musb@25 {
compatible = "fcs,fsa9480";
reg = <0x25>;
interrupt-parent = <&gpio>;
interrupts = <56 IRQ_TYPE_LEVEL_HIGH>;

connector {
compatible = "samsung,usb-connector-11pin",
"usb-b-connector";
label = "micro-USB";
type = "micro";

ports {
#address-cells = <1>;
#size-cells = <0>;

port@0 {
reg = <0>;

muic_to_usb: endpoint {
remote-endpoint = <&usb_to_muic>;
};
};
};
};

};
};
/* ... */
};
</syntaxhighlight>

Once you have the switch, you can add the remaining USB nodes:

<syntaxhighlight lang="devicetree">
&usbotg {
vusb_d-supply = <&usbldo_reg>;
vusb_a-supply = <&iosr1_reg>;
vbus-supply = <&vbus_reg>;
dr_mode = "otg";
role-switch-default-mode = "peripheral";
usb-role-switch;
status = "okay";

// if your device has no switch, drop the port node below
port {
usb_to_muic: endpoint {
remote-endpoint = <&muic_to_usb>;
};
};
};

&usbphy {
status = "okay";
};
</syntaxhighlight>

== WiFi and Bluetooth ==

Most Broadcom devices use Broadcom WiFi/Bluetooth chips from the BCM43xx series. (Look up BCM43 in your defconfig, or reference downstream kernel dmesg for the exact model.)

The below examples are for BCM4330. If you have another chip, you can grep for it in the mainline kernel (<code>arch/arm/boot/dts</code>) and see what compatibles are used by other devices.

The Bluetooth chip goes under the UART bus that was labeled as "bluetooth":

<syntaxhighlight lang="devicetree">
&uartb {
status = "okay";
clock-frequency = <48000000>;

bluetooth {
compatible = "brcm,bcm4330-bt";

shutdown-gpios = <&gpio 28 GPIO_ACTIVE_HIGH>;
device-wakeup-gpios = <&gpio 32 GPIO_ACTIVE_HIGH>;
host-wakeup-gpios = <&gpio 72 GPIO_ACTIVE_HIGH>;
reset-gpios = <&gpio 71 GPIO_ACTIVE_LOW>;
interrupt-parent = <&gpio>;
interrupts = <72 IRQ_TYPE_EDGE_FALLING>;
};
};
</syntaxhighlight>

To get the GPIOs:

* Look for <code>bcmbt_platform_data</code>; <code>.bt_wake_gpio</code> becomes <code>device-wakeup-gpios</code>, and <code>.host_wake_gpio</code> becomes <code>host-wakeup-gpios</code>.
* Look for <code>bcmbt_rfkill_platform_data</code>; <code>.vreg_gpio</code> becomes <code>shutdown-gpios</code>, and <code>.n_reset_gpio</code> becomes <code>reset-gpios</code>.

For WiFi, add the following under the <code>/</code> node:

<syntaxhighlight lang="devicetree">
/ {
/* ... */

/* GPIO regulator for WiFi */
wl_reg: regulator-gpio-wlan {
compatible = "regulator-fixed";
regulator-name = "WL_REG_ON";
regulator-min-microvolt = <3000000>;
regulator-max-microvolt = <3000000>;
startup-delay-us = <100000>;
gpio = <&gpio 3 GPIO_ACTIVE_HIGH>;
enable-active-high;
};

/* ... */
};
</syntaxhighlight>

(Get the GPIO from <code>board_wifi_info</code>, member <code>.wl_reset_gpio</code>).

Then, update the SDIO node for WiFi:

<syntaxhighlight lang="devicetree">
/* WiFi */
&sdio3 {
max-frequency = <48000000>;

/* Actually a regulator for the WiFi chip */
vmmc-supply = <&wl_reg>;

#address-cells = <1>;
#size-cells = <0>;

pinctrl-0 = <&mmc1_width4_pins>;
pinctrl-names = "default";

keep-power-in-suspend;
non-removable;

status = "okay";

wifi@1 {
compatible = "brcm,bcm4330-fmac", "brcm,bcm4329-fmac";
reg = <1>;

interrupt-parent = <&gpio>;
interrupts = <74 IRQ_TYPE_EDGE_FALLING>;
interrupt-names = "host-wake";
};
};
</syntaxhighlight>

(Get the interrupt from <code>board_wifi_info</code>, member <code>.host_wake_gpio</code>).

Mainline:Broadcom Kona/Adding a new device

2026-08-20T21:54:58Z

Uart: start writing draft

User:Uart/Draft:pmOS wiki admin processes

2026-08-18T11:49:33Z

Uart: 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..."

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

Mainline:Broadcom Kona/USB PHY (HSOTGCTRL)

2026-07-07T05:48:38Z

Uart:

'''HSOTGCTRL''' is the USB2 PHY used in Broadcom Kona chips.

== Drivers ==

=== Downstream ===

Split into two parts:

* {{downstream|baffinlite|arch/arm/plat-kona/bcm-hsotgctrl.c}} which handles all HSOTGCTRL functions;
** {{downstream|baffinlite|arch/arm/plat-kona/bcm-hsotgctrl-phy-mdio.c}} which specifically has [[#MDIO]] setup
* {{downstream|baffinlite|drivers/usb/otg/bcmpmu59xxx_otg_xceiv.c}} which hooks into Linux's USB PHY API, calls the HSOTGCTRL functions and also handles some PMU-related bits of the process (mostly related to VBUS control)

=== Mainline ===

The mainline driver uses the generic PHY framework; it is located in <code>drivers/phy/broadcom/phy-bcm-kona-usb2.c</code>.

== MDIO ==

MDIO most likely stands for [https://en.wikipedia.org/wiki/Management_Data_Input/Output Management Data Input/Output], a PHY management interface used primarily for Ethernet PHYs. While there is a standard for Ethernet MDIO registers, the USB MDIO does not appear to follow it, instead using its own values. Like the Ethernet MDIO, however, both the addresses and values are 16-bit.

MDIO read/write registers are located in CHIPREGS. There is a single read and write register - which internal MDIO device/address to read is selected by first writing the ID/address to the upper bits of the write register (TODO: write down full sequence). USB MDIO has an ID of 9, and 6 registers are written in downstream (docs taken mostly from <code>arch/arm/plat-kona/bcm_hsotgctrl.c</code> in Rhea downstream):

* MDIO0 - current reference adjustment ("afe_pll_tst lower 16 bits")
* MDIO1 - voltage reference adjustment ("afe_pll_tst upper 16 bits")
* MDIO2 - ???; not set in Rhea driver, set to 0x0000 in Hawaii driver
* MDIO3 - transmitter current; valid values are documented in Hawaii driver. Set to 0x2600 on most devices, 0x0400 on Garnet board; TX current value has mask <code>0x07e0</code>, what the upper bit does is unknown.
* MDIO4 - USB PHY receiver sensitivity/squelch (valid values are documented in aforementioned Rhea driver and Hawaii driver).
* MDIO5 - ???; only set in Hawaii driver, set to 0x0000 on all devices. Might have been included by mistake.

{{todo|Write down MDIO3/4 valid values}}

On at least the Samsung Galaxy Grand Neo, the correct MDIO values are already written by the bootloader.

== USB PHY regs ==

'''Main offset:''' 0x????

=== USBOTGCONTROL (<code>0x00</code>) ===

Called <code>OTGCTL</code> in mainline driver. Controls various settings related to USB handling.

{|class="wikitable"
!Name
!Bit
!Description
|-
| OTGSTAT2, OTGSTAT1
| 31:30
| ???; mainline driver clears these bits when powering on.
|-
| REG_OTGSTAT2, REG_OTGSTAT1
| 29:28
| Controls VBUS valid state; a value of 1 indicates VBUS on, a value of 0 indicates VBUS off. (<code>bcm_hsotgctrl_phy_set_vbus_stat</code> in downstream)
|-
|
|}

Main Page

2026-04-28T19:07:03Z

Uart:

* [[Meta:Infrastructure]]
* [[Mainline:Onyx Go 6]]
* [[Mainline:Broadcom Kona]]
* [[Mainline:Exynos 4]]
* [[Mainline:BCM215xx]]

contact [[User:Knuxify]] for an account.

Mainline:BCM215xx/Introduction

2026-04-25T06:40:28Z

Uart: Created page with "BCM215xx is a family of ARMv6 SoCs/APs from Broadcom, released around 2010. The BCM21552/BCM21553 appears to be codenamed Athena. The kernel also contains support for the BCM1160, which appears to be closely related. The following development boards and devices are found in the Samsung release of the BCM215xx kernel: * AthenaRay (which follows Broadcom's tradition of having development boards named <Platform>Ray, see Broadcom Kona kernels) (variants: EDN10, EDN20) * Th..."

BCM215xx is a family of ARMv6 SoCs/APs from Broadcom, released around 2010. The BCM21552/BCM21553 appears to be codenamed Athena. The kernel also contains support for the BCM1160, which appears to be closely related.

The following development boards and devices are found in the Samsung release of the BCM215xx kernel:

* AthenaRay (which follows Broadcom's tradition of having development boards named <Platform>Ray, see Broadcom Kona kernels) (variants: EDN10, EDN20)
* Thunderbird (variants: EDN31, EDN5x)
* Samsung-specific:
** '''totoro''' (Galaxy Y, GT-S5360)
** '''tassve''' (Galaxy Mini Plus/Pop Plus/Mini Turbo, GT-S5570i)
** '''cooperve''' (Galaxy Ace i, GT-S5830i)
** '''luisa''' (Samsung Galaxy Y Pro, GT-B5510)

Mainline:BCM215xx

2026-04-25T06:25:54Z

Uart:

This '''root page''' connects pages for reverse-engineering of BCM215xx ("Athena"?) SoCs (notably the BCM21552/BCM21553 used in the Samsung Galaxy Y (GT-S5360) and some other Samsung budget phones).

It appears to be similar to the BCM116X (notably the I2C driver in downstream is named after it), which is an SoC for VoIP phones<ref>http://www.datasheet.hk/download.php?id=1537788&pdfid=863799B80309819F85E3CF80C6F1C111&file=0270%5Cbcm1160_318075.pdf</ref>.

[[Category:Mainline]] [[Category:SoC]]

== Subpages ==

{{Subpages|stripprefix=true}}

== References ==

<references />

Template:Downstream

2026-04-25T06:13:03Z

Uart:

<noinclude>
<templatedata>
{
"params": {
"repo": {
"aliases": [
"1"
],
"label": "Repository to link to",
"type": "string",
"suggestedvalues": [
"baffinlite",
"totoro"
],
"required": true
},
"file": {
"aliases": [
"2"
],
"label": "File to link to",
"type": "string",
"required": true
}
},
"description": "Link to file in downstream kernel repo",
"format": "inline",
"paramOrder": [
"repo",
"file"
]
}
</templatedata>
</noinclude><includeonly>[{{#switch: {{{repo|{{{1|}}}}}}
|baffinlite=https://github.com/knuxdroid/android_kernel_samsung_baffinlite/blob/cm-12.1/{{{file|{{{2|}}}}}}
|totoro=https://github.com/androidarmv6/android_kernel_samsung_bcm21553-common/blob/cm-11.0/{{{file|{{{2|}}}}}}}} {{{file|{{{2|}}}}}}]</includeonly>

Template:Downstream

2026-04-25T06:11:48Z

Uart:

<noinclude>
<templatedata>
{
"params": {
"repo": {
"aliases": [
"1"
],
"label": "Repository to link to",
"type": "string",
"suggestedvalues": [
"baffinlite",
"totoro"
],
"required": true
},
"file": {
"aliases": [
"2"
],
"label": "File to link to",
"type": "string",
"required": true
}
},
"description": "Link to file in downstream kernel repo",
"format": "inline",
"paramOrder": [
"repo",
"file"
]
}
</templatedata>
</noinclude><includeonly>[{{#switch: {{{repo|{{{1|}}}}}}
|baffinlite=https://github.com/knuxdroid/android_kernel_samsung_baffinlite/blob/cm-12.1/{{{file|{{{2|}}}}}}
|totoro=github.com/androidarmv6/android_kernel_samsung_bcm21553-common/blob/cm-11.0/{{{file|{{{2|}}}}}}}} {{{file|{{{2|}}}}}}]</includeonly>

Mainline:BCM215xx

2026-04-25T06:02:35Z

Uart: Created page with "This '''root page''' connects pages for reverse-engineering of BCM215xx ("Athena"?) SoCs (notably the BCM21552/BCM21553 used in the Samsung Galaxy Y (GT-S5360) and some other Samsung budget phones). Category:Mainline Category:SoC == Subpages == {{Subpages|stripprefix=true}}"

MediaWiki:Sidebar/Category:Sidebar test

2026-03-10T15:27:00Z

Uart:

** https://dissonant.dev | Test
*** https://wiki.dissonant.dev | Test 2

MediaWiki:Sidebar/Category:Sidebar test

2026-03-10T15:22:45Z

Uart:

** https://dissonant.dev | Test

MediaWiki:Sidebar/Category:Sidebar test

2026-03-10T14:52:39Z

Uart:

* https://dissonant.dev | Test

Category:Sidebar test

2026-03-10T14:48:20Z

Uart: Created page with "(test page)"

(test page)

Meta:Infrastructure

2026-03-10T14:44:36Z

Uart:

This page acts as an overview of dissonant.dev's infrastructure.

== Servers ==

dissonant.dev currently operates on two servers:

* '''<code>franky</code>''' - the main VPS, a [https://www.hetzner.com/ Hetzner] CX22 node. (2x2.1GHz, 4GB RAM, 40GB storage)
* '''<code>pandemonica</code>''' (a.k.a ''pandy'') - tiny VPS hosting fxtumblr/tpmblr.com; kindly provided by [https://sdomi.pl/ sdomi]. (1x4.2GHz, 2GB RAM, 10GB storage)

Decomissioned servers:

* '''<code>arisu</code>''' - the previous main VPS, a [https://homecloud.pl/ homecloud.pl] Cloud VPS M node. They stopped offering Cloud VPS nodes, and moved them to their main offering at a marked-up price, which forced me to reconsider my hosting options. (2x2GHz, 4GB RAM, 80GB storage)

<code>franky</code> is named after Franky from ''Flying Saucer Video''. <code>pandemonica</code> is named after Pandemonica from ''Helltaker'' (I don't even know what that game's about I just thought she was neat). <code>arisu</code> was a Lain reference. I am cringe but I am free.

== Expansion possibilities ==

I would like to look into self-hosting some services from home; the main issue is getting a static IPv4 address, but my ISP provides public IPv6 addresses so that would leave us with having to find a proxy of some sort.

[[Category:Sidebar test]]

MediaWiki:Sidebar

2026-03-10T14:44:01Z

Uart:

User:Uart/sidebartest

2026-03-10T14:42:43Z

Uart: Created page with "This is an example page Category:Sidebar test"

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

MediaWiki:Sidebar/Category:Sidebar test

2026-03-10T14:42:11Z

MediaWiki:Editnotice-notext

2025-10-04T05:48:38Z

Uart:

test

MediaWiki:Edittools

2025-10-04T05:48:13Z

Uart:

MediaWiki:Edittools

2025-10-04T05:48:05Z

Uart:

a

Mainline:Broadcom Kona/BCM590xx

2025-09-15T19:46:32Z

Uart:

This '''root page''' connects all pages related to the BCM590xx series of PMICs, in particular the BCM59054 and BCM59056.

The BCM590xx PMICs comprise of the following parts:

* Internal interrupt controller ([[/Interrupts]])
* Regulators ([[/Regulators]])
* Power-on key controller/PONKEY ([[/PONKEY]])
* RTC ([[/RTC]])
* Charger [[/Charger]])
* Fuel gauge ([[/Fuel gauge]])
* USB OTG control ([[/USB]])
* Audio amplifier (?)
* PWM LED controller
* ADC used e.g. for thermal monitoring ([[/ADC]])

== Subpages ==

{{Subpages|stripprefix=true}}

Mainline:Broadcom Kona/BCM590xx/Regulators

2025-09-15T19:46:20Z

Uart: Created page with "{{hatnote|Relevant downstream drivers: {{downstream|baffinlite|drivers/regulator/bcmpmu59xxx-regulator.c}}; {{downstream|baffinlite|bcmpmu-regulator.c}}; {{downstream|baffinlite|drivers/regulator/bcm590xx-regulator.c}} and {{downstream|baffinlite|drivers/regulator/bcm59055_regulator.c}} for BCM59055.}} The BCM590xx PMUs have configurable voltage regulators. == Regulator types == There are two types of regulators: '''LDO''' (low dropout) and '''SR''' (switcher). Regula..."

{{hatnote|Relevant downstream drivers: {{downstream|baffinlite|drivers/regulator/bcmpmu59xxx-regulator.c}}; {{downstream|baffinlite|bcmpmu-regulator.c}}; {{downstream|baffinlite|drivers/regulator/bcm590xx-regulator.c}} and {{downstream|baffinlite|drivers/regulator/bcm59055_regulator.c}} for BCM59055.}}

The BCM590xx PMUs have configurable voltage regulators.

== Regulator types ==

There are two types of regulators: '''LDO''' (low dropout) and '''SR''' (switcher). Regulator names are suffixed with these shortcuts to indicate their type (e.g. ''LVLDO1'' is an LDO, ''CSR'' is an SR).

== Operating modes ==

The operating modes for each regulator are stored in <code>PMMODE</code> registers. These registers are used to store operating modes for various '''PC''' (pin control) configurations. The mode that ends up being used is determined based on the state of PC1 and PC2 pins (and optionally the GPIO1 pin, if it's configured to the PC3 function in GPIOCTRL).

'''LDOs''' have '''2-bit modes'''. The available modes are <code>ON</code> (0), <code>LPM</code> (low power mode; 1) and <code>OFF</code> (2). {{speculation|Mode 3 is presumably invalid, but hasn't been tested.}}

'''SRs''' have '''3-bit modes'''. The exact function of each mode is unknown; the vendor kernel does not bother with the distinction and applies the LDO modes described above.

LDOs get 2 PMMODE registers each; SRs get 4 PMMODE registers. This is to accomodate the different mode sizes.

There is no known way to query the state of PC pins from the BCM590xx itself; instead, the SoC's pinmux interface could be used.

== See also ==

* [[User:Knuxify/Old BCM590xx regulator notes|Old BCM590xx regulator notes]], very messy.

User:Uart/Old BCM590xx regulator notes

2025-09-15T19:18:25Z

Uart: Knuxify moved page Mainline:Broadcom Kona/BCM590xx/Regulators to User:Knuxify/Old BCM590xx regulator notes without leaving a redirect

(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

Template:Todo/style.css

2025-09-15T18:56:31Z

Uart: Created page with "html.skin-theme-clientpref-night .box-todo { color: #fff !important; background-color: #5c1e1e !important; border-color: #c64242 !important; } @media (prefers-color-scheme: dark) { html.skin-theme-clientpref-os .box-todo { color: #fff !important; background-color: #5c1e1e !important; border-color: #c64242 !important; } }"

html.skin-theme-clientpref-night .box-todo {
color: #fff !important;
background-color: #5c1e1e !important;
border-color: #c64242 !important;
}

@media (prefers-color-scheme: dark) {
html.skin-theme-clientpref-os .box-todo {
color: #fff !important;
background-color: #5c1e1e !important;
border-color: #c64242 !important;
}
}

Template:Note/style.css

2025-09-15T18:56:03Z

Uart: Created page with "html.skin-theme-clientpref-night .box-note { color: #fff !important; background-color: #261c09 !important; border-color: #6a481c !important; } @media (prefers-color-scheme: dark) { html.skin-theme-clientpref-os .box-note { color: #fff !important; background-color: #261c09 !important; border-color: #6a481c !important; } }"

html.skin-theme-clientpref-night .box-note {
color: #fff !important;
background-color: #261c09 !important;
border-color: #6a481c !important;
}

@media (prefers-color-scheme: dark) {
html.skin-theme-clientpref-os .box-note {
color: #fff !important;
background-color: #261c09 !important;
border-color: #6a481c !important;
}
}

Template:Note

2025-09-15T18:45:42Z

Uart: Created page with "<templatestyles src="Note/style.css"/><includeonly>{{Icon box | box-icons = Note | box-text = {{{1}}} | border-color = #ac6600 | border-width = 1px | background = #f6efe5 | class = box-note }}</includeonly><noinclude> <templatedata> { "params": { "1": { "label": "Text", "description": "Text to place in the box", "type": "unbalanced-wikitext",..."

<templatestyles src="Note/style.css"/><includeonly>{{Icon box
| box-icons = [[File:Reference icon.svg|20px|link=|Note]]
| box-text = {{{1}}}
| border-color = #ac6600
| border-width = 1px
| background = #f6efe5
| class = box-note
}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"label": "Text",
"description": "Text to place in the box",
"type": "unbalanced-wikitext",
"required": true
}
},
"description": "Note box containing a note.",
"format": "inline"
}
</templatedata>

== Example ==

<nowiki>{{note|This is quite '''note-worthy'''.}}</nowiki>

{{note|This is quite '''note-worthy'''.}}
</noinclude>

Mainline:Broadcom Kona/BCM590xx/ADC

2025-08-31T15:37:26Z

Uart: /* RTM (Real-Time Measurment) */

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/hwmon/bcmpmu59xxx-hwmon.c}}, {{downstream|baffinlite|drivers/misc/bcm59055-adc.c}} (for BCM59055 but very well commented, and seems to be about the same as other models).}}

The BCM590xx PMUs provide a 10-bit SAR (Successive Approximation) ADC.

== Reading the ADC data ==

Each ADC channel has two registers which immediately succeed each other. These registers follow the layout outlined below.

To read the ADC data, one needs to combine the DATA_MSB bits (upper 2 bits, first two bits of the first register) with the DATA_LSB (lower 8 bits, entire value of the second register). An additional value at bit 2 is available to check the validity of the read data.

<syntaxhighlight lang="c">
data = ((reg1 & 0x3) << 8) | reg2;
</syntaxhighlight>

=== ADCCTRLx ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:3
| Reserved/unknown
|-
| <code>READ_INVALID</code>
| 2
| If 1, the read is invalid; 0 otherwise.
|-
| <code>DATA_MSB</code>
| 1:0
| Upper (most significant) 2 bits of the ADC data.
|}

=== ADCCTRLx+1 ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>DATA_LSB</code>
| 7:0
| Lower (least significant) 8 bits of the ADC data.
|}

== RTM (Real-Time Measurment) ==

The last ADC channel, RTM, is reserved for RTM (Real-Time Measurment) mode.

The process for performing an RTM read is as follows:

* In <code>ADCCTRL1</code>: (these can all be performed in one write)
** Set the the <code>RTM_CONVERSION</code> bit to enable RTM mode
** Write the channel number to read to the <code>RTM_CHANN</code> offset
** Write the <code>RTM_START</code> bit to start the RTM read
* Wait for the <code>ADC_RTM_DATA_READY</code> interrupt.
* Perform a standard data read from the RTM ADC channel registers (see [[#Reading the ADC data]]).
* Clear the <code>RTM_CONVERSION</code> bit to disable RTM mode.

== Register layout ==

Values given here are for the BCM59054. These registers are located on map 1.

=== ADCCTRL1 (0x20) ===

Contains settings for RTM mode.

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>RTM_CHANN</code>
| 7:4
| Channel to read in RTM mode.
|-
| <code>RTM_CONVERSION</code>
| 3
| Enable (0) or disable (1) RTM mode. Prerequisite for performing an RTM read.
|-
| <code>RTM_START</code>
| 2
| When set to 1, starts the RTM reading.
|-
| <code>RTM_MAX_RST_CNT</code>
| 1:0
| Max reset count for RTM mode. Valid values are:
* 0 (0b00) - 1
* 1 (0b01) - 3
* 2 (0b10) - 5
* 3 (0b11) - 7
|}

=== ADCCTRL2 (0x21) ===

{{note|These are taken from the BCM59055 driver, and haven't been tested on the BCM59054 yet. {{Speculation|Still, given that the ADCCTRL1 layout is the same, I suspect this one should be the same as well...}}}}

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:6
| Reserved/unknown
|-
| <code>GSM_DEBOUNCE</code>
| 5
| If set to 1, enables ADC burst mode (todo, how does it work?).
|-
| <code>RTM_DLY</code>
| 4:0
| RTM read delay. Valid values:
* 0 (0b00000) - 0ns
* 1 (0b00001) - 31.25ns
* 2 (0b00010) - 62.50ns
* 3 (0b00011) - 93.75ns
* 4 (0b00100) - 125ns
* 5 (0b00101) - 156.25ns
* 6 (0b00110) - 187.50ns
* 7 (0b00111) - 218.75ns
* 8 (0b01000) - 250ns
* 9 (0b01001) - 281.25ns
* 10 (0b01010) - 312.50ns
* 11 (0b01011) - 343.75ns
* 12 (0b01100) - 375ns
* 13 (0b01101) - 406.25ns
* 14 (0b01110) - 437.50ns
* 15 (0b01111) - 468.75ns
* 16 (0b10000) - 500ns
* 17 (0b10001) - 531.25ns
* 18 (0b10010) - 562.50ns
* 19 (0b10011) - 593.75ns
* 20 (0b10100) - 625ns
* 21 (0b10101) - 656.25ns
* 22 (0b10110) - 687.50ns
* 23 (0b10111) - 718.75ns
* 24 (0b11000) - 750ns
* 25 (0b11001) - 781.25ns
* 26 (0b11010) - 812.50ns
* 27 (0b11011) - 843.75ns
* 28 (0b11100) - 875ns
* 29 (0b11101) - 906.25ns
* 30 (0b11110) - 937.50ns
* 31 (0b11111) - 968.75ns
|}

=== ADCCTRL3 - ADCCTRL28 ===

ADC channel registers; see layout above.

=== ADCCTRL29 and ADCCTRL30 ===

Unknown.

Mainline:Broadcom Kona/BCM590xx/ADC

2025-08-31T15:34:27Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/hwmon/bcmpmu59xxx-hwmon.c}}, {{downstream|baffinlite|drivers/misc/bcm59055-adc.c}} (for BCM59055 but very well commented, and seems to be about the same as other models).}}

The BCM590xx PMUs provide a 10-bit SAR (Successive Approximation) ADC.

== Reading the ADC data ==

Each ADC channel has two registers which immediately succeed each other. These registers follow the layout outlined below.

To read the ADC data, one needs to combine the DATA_MSB bits (upper 2 bits, first two bits of the first register) with the DATA_LSB (lower 8 bits, entire value of the second register). An additional value at bit 2 is available to check the validity of the read data.

<syntaxhighlight lang="c">
data = ((reg1 & 0x3) << 8) | reg2;
</syntaxhighlight>

=== ADCCTRLx ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:3
| Reserved/unknown
|-
| <code>READ_INVALID</code>
| 2
| If 1, the read is invalid; 0 otherwise.
|-
| <code>DATA_MSB</code>
| 1:0
| Upper (most significant) 2 bits of the ADC data.
|}

=== ADCCTRLx+1 ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>DATA_LSB</code>
| 7:0
| Lower (least significant) 8 bits of the ADC data.
|}

== RTM (Real-Time Measurment) ==

The last ADC channel, RTM, is reserved for RTM (Real-Time Measurment) mode.

The process for performing an RTM read is as follows:

* In <code>ADCCTRL1</code>: (these can all be performed in one write)
** Set the the <code>RTM_CONVERSION</code> bit to enable RTM mode
** Write the channel number to read to the <code>RTM_CHAN</code> offset
** Write the <code>RTM_START</code> bit to start the RTM read
* Wait for the <code>ADC_RTM_DATA_READY</code> interrupt.
* Perform a standard data read from the RTM ADC channel registers (see [[#Reading the data]]).
* Clear the <code>RTM_CONVERSION</code> bit to disable RTM mode.

== Register layout ==

Values given here are for the BCM59054. These registers are located on map 1.

=== ADCCTRL1 (0x20) ===

Contains settings for RTM mode.

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>RTM_CHANN</code>
| 7:4
| Channel to read in RTM mode.
|-
| <code>RTM_CONVERSION</code>
| 3
| Enable (0) or disable (1) RTM mode. Prerequisite for performing an RTM read.
|-
| <code>RTM_START</code>
| 2
| When set to 1, starts the RTM reading.
|-
| <code>RTM_MAX_RST_CNT</code>
| 1:0
| Max reset count for RTM mode. Valid values are:
* 0 (0b00) - 1
* 1 (0b01) - 3
* 2 (0b10) - 5
* 3 (0b11) - 7
|}

=== ADCCTRL2 (0x21) ===

{{note|These are taken from the BCM59055 driver, and haven't been tested on the BCM59054 yet. {{Speculation|Still, given that the ADCCTRL1 layout is the same, I suspect this one should be the same as well...}}}}

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:6
| Reserved/unknown
|-
| <code>GSM_DEBOUNCE</code>
| 5
| If set to 1, enables ADC burst mode (todo, how does it work?).
|-
| <code>RTM_DLY</code>
| 4:0
| RTM read delay. Valid values:
* 0 (0b00000) - 0ns
* 1 (0b00001) - 31.25ns
* 2 (0b00010) - 62.50ns
* 3 (0b00011) - 93.75ns
* 4 (0b00100) - 125ns
* 5 (0b00101) - 156.25ns
* 6 (0b00110) - 187.50ns
* 7 (0b00111) - 218.75ns
* 8 (0b01000) - 250ns
* 9 (0b01001) - 281.25ns
* 10 (0b01010) - 312.50ns
* 11 (0b01011) - 343.75ns
* 12 (0b01100) - 375ns
* 13 (0b01101) - 406.25ns
* 14 (0b01110) - 437.50ns
* 15 (0b01111) - 468.75ns
* 16 (0b10000) - 500ns
* 17 (0b10001) - 531.25ns
* 18 (0b10010) - 562.50ns
* 19 (0b10011) - 593.75ns
* 20 (0b10100) - 625ns
* 21 (0b10101) - 656.25ns
* 22 (0b10110) - 687.50ns
* 23 (0b10111) - 718.75ns
* 24 (0b11000) - 750ns
* 25 (0b11001) - 781.25ns
* 26 (0b11010) - 812.50ns
* 27 (0b11011) - 843.75ns
* 28 (0b11100) - 875ns
* 29 (0b11101) - 906.25ns
* 30 (0b11110) - 937.50ns
* 31 (0b11111) - 968.75ns
|}

=== ADCCTRL3 - ADCCTRL28 ===

ADC channel registers; see layout above.

=== ADCCTRL29 and ADCCTRL30 ===

Unknown.

Mainline:Broadcom Kona/BCM590xx/ADC

2025-08-31T15:26:40Z

Uart: /* RTM (Real-Time Measurment) */

Mainline:Broadcom Kona/BCM590xx/ADC

2025-08-31T14:58:15Z

Uart:

Mainline:Broadcom Kona/BCM590xx/ADC

2025-08-31T14:56:28Z

Uart: Created page with "{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/hwmon/bcmpmu59xxx-hwmon.c}}, {{downstream|baffinlite|drivers/misc/bcm59055-adc.}} (for BCM59055 but very well commented, and seems to be about the same as other models).}} The BCM590xx PMUs provide a 10-bit SAR (Successive Approximation) ADC. == Reading the ADC data == Each ADC channel has two registers which immediately succeed each other. These registers follow the layout outlined below. To read the ADC d..."

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/hwmon/bcmpmu59xxx-hwmon.c}}, {{downstream|baffinlite|drivers/misc/bcm59055-adc.}} (for BCM59055 but very well commented, and seems to be about the same as other models).}}

The BCM590xx PMUs provide a 10-bit SAR (Successive Approximation) ADC.

== Reading the ADC data ==

Each ADC channel has two registers which immediately succeed each other. These registers follow the layout outlined below.

To read the ADC data, one needs to combine the DATA_MSB bits (upper 2 bits, first two bits of the first register) with the DATA_LSB (lower 8 bits, entire value of the second register). An additional value at bit 2 is available to check the validity of the read data.

<syntaxhighlight lang="c">
data = ((reg1 & 0x3) << 8) | reg2;
</syntaxhighlight>

=== ADCCTRLx ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:3
| Reserved/unknown
|-
| <code>READ_INVALID</code>
| 2
| If 1, the read is invalid; 0 otherwise.
|-
| <code>DATA_MSB</code>
| 1:0
| Upper (most significant) 2 bits of the ADC data.
|}

=== ADCCTRLx+1 ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>DATA_LSB</code>
| 7:0
| Lower (least significant) 8 bits of the ADC data.
|}

== RTM (Real-Time Measurment) ==

The last ADC channel, RTM, is reserved for RTM (Real-Time Measurment) mode.

Mainline:Broadcom Kona/BCM590xx

2025-08-31T14:45:25Z

Uart:

This '''root page''' connects all pages related to the BCM590xx series of PMICs, in particular the BCM59054 and BCM59056.

The BCM590xx PMICs comprise of the following parts:

* Internal interrupt controller ([[/Interrupts]])
* Regulators ([[/Regulators]] - WIP article, needs updates)
* Power-on key controller/PONKEY ([[/PONKEY]])
* RTC ([[/RTC]])
* Charger [[/Charger]])
* Fuel gauge ([[/Fuel gauge]])
* USB OTG control ([[/USB]])
* Audio amplifier (?)
* PWM LED controller
* ADC used e.g. for thermal monitoring ([[/ADC]])

== Subpages ==

{{Subpages|stripprefix=true}}

Mainline:Broadcom Kona/BCM590xx/USB

2025-08-27T13:11:27Z

Uart:

{{Hatnote|Downstream drivers: {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy-core.c}}, {{downstream|baffinlite|bcmpmu59xxx-accy-detect.c}}, {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy.c}} which is unused?, {{downstream|baffinlite|drivers/mfd/bcm590xx-usb.c}} for the BCM59055; {{downstream|baffinlite|drivers/usb/otg/bcm_otg_adp.c}}, {{downstream|baffinlite|drivers/usb/otg/bcmpmu59xxx_otg_xceiv.c}}, and to some extent external MUIC drivers which hook into the BCM59xxx drivers:}}

The BCM590xx PMUs are capable of USB port management and cable detection.

== Glossary ==

Some terms get mentioned repeatedly in USB OTG code. These are common terms related to either the USB 2.0 spec or the USB OTG spec, and appear often in other drivers as well.

* '''VBUS''' - the 5V power rail in an USB cable. When the device is charging or plugged in as a peripheral (e.g. to a computer), the voltage is provided by the charger; when an USB OTG dongle is plugged in (the device operates in host mode), it needs to provide its own voltage. Most PMUs, the BCM590xx included, provide a "VBUS boost" (''VBUSB'') mode to enable VBUS from the device for host mode and disable it for peripheral mode/charging.
* '''ID''' - The ID pin on the microUSB connector. A floating (not connected to ground) ID pin indicates that the device is to be connected as a peripheral; a grounded ID pin indicates the device should act as the host, and different resistance values between GND and ID can be used to switch between different device types (per the USB Carkit standard).
* '''ADP''' - From USB OTG docs: "The Attach Detection Protocol (ADP) allows an SRP-capable Targeted Host or peripheral-only B-device to detect when a remote device has been attached or detached when VBUS is not present."<ref>https://ia601605.us.archive.org/7/items/usb_20_202303/USB_OTG_and_EH_2-0-version%201_1a.pdf section 5.4.</ref>
* '''SRP''' - Stands for ''Session Request Protocol''. An SRP request can be sent by an USB peripheral to the host device to enable VBUS.
* '''BC1.2''' - the [https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement USB Battery Charging 1.2 specification]. (Code might use "BC" or "BC12" to refer to it.)

Mainline:Broadcom Kona/BCM590xx/USB

2025-08-27T13:01:33Z

Uart:

Mainline:Broadcom Kona/BCM590xx/USB

2025-08-27T08:07:28Z

Uart: /* Glossary */

{{Hatnote|Downstream drivers: {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy-core.c}}, {{downstream|baffinlite|bcmpmu59xxx-accy-detect.c}}, {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy.c}} which is unused?, {{downstream|baffinlite|drivers/mfd/bcm590xx-usb.c}} for the BCM59055.}}

The BCM590xx PMUs are capable of USB port management and cable detection.

== Glossary ==

Some terms get mentioned repeatedly in USB OTG code. These are common terms related to either the USB 2.0 spec or the USB OTG spec, and appear often in other drivers as well.

* '''VBUS''' - the 5V power rail in an USB cable. When the device is charging or plugged in as a peripheral (e.g. to a computer), the voltage is provided by the charger; when an USB OTG dongle is plugged in (the device operates in host mode), it needs to provide its own voltage. Most PMUs, the BCM590xx included, provide a "VBUS boost" (''VBUSB'') mode to enable VBUS from the device for host mode and disable it for peripheral mode/charging.
* '''ID''' - The ID pin on the microUSB connector. A floating (not connected to ground) ID pin indicates that the device is to be connected as a peripheral; a grounded ID pin indicates the device should act as the host, and different resistance values between GND and ID can be used to switch between different device types (per the USB Carkit standard).
* '''ADP''' - From USB OTG docs: "The Attach Detection Protocol (ADP) allows an SRP-capable Targeted Host or peripheral-only B-device to detect when a remote device has been attached or detached when VBUS is not present."<ref>https://ia601605.us.archive.org/7/items/usb_20_202303/USB_OTG_and_EH_2-0-version%201_1a.pdf section 5.4.</ref>
* '''SRP''' - Stands for ''Session Request Protocol''. An SRP request can be sent by an USB peripheral to the host device to enable VBUS.

Mainline:Broadcom Kona/BCM590xx/USB

2025-08-27T06:22:11Z

Uart: Created page with "{{Hatnote|Downstream drivers: {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy-core.c}}, {{downstream|baffinlite|bcmpmu59xxx-accy-detect.c}}, {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy.c}} which is unused?, {{downstream|baffinlite|drivers/mfd/bcm590xx-usb.c}} for the BCM59055.}} The BCM590xx PMUs are capable of USB port management and cable detection. == Glossary == Some terms get mentioned repeatedly in USB OTG code. These are common terms related to ei..."

{{Hatnote|Downstream drivers: {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy-core.c}}, {{downstream|baffinlite|bcmpmu59xxx-accy-detect.c}}, {{downstream|baffinlite|drivers/mfd/bcmpmu59xxx-accy.c}} which is unused?, {{downstream|baffinlite|drivers/mfd/bcm590xx-usb.c}} for the BCM59055.}}

The BCM590xx PMUs are capable of USB port management and cable detection.

== Glossary ==

Some terms get mentioned repeatedly in USB OTG code. These are common terms related to either the USB 2.0 spec or the USB OTG spec, and appear often in other drivers as well.

* '''VBUS''' - the 5V power rail in an USB cable. When the device is charging or plugged in as a peripheral (e.g. to a computer), the voltage is provided by the charger; when an USB OTG dongle is plugged in (the device operates in host mode), it needs to provide its own voltage. Most PMUs, the BCM590xx included, provide a "VBUS boost" (''VBUSB'') mode to enable VBUS from the device for host mode and disable it for peripheral mode/charging.
* '''ID''' - The ID pin on the microUSB connector. A floating (not connected to ground) ID pin indicates that the device is to be connected as a peripheral; a grounded ID pin indicates the device should act as the host, and different resistance values between GND and ID can be used to switch between different device types (per the USB Carkit standard).
* '''ADP''' - From USB OTG docs: "The Attach Detection Protocol (ADP) allows an SRP-capable Targeted Host or peripheral-only B-device to detect when a remote device has been attached or detached when VBUS is not present."<ref>https://ia601605.us.archive.org/7/items/usb_20_202303/USB_OTG_and_EH_2-0-version%201_1a.pdf section 5.4.</ref>
* '''SRP''' - Stands for ''Session Request Protocol''.

Mainline:Broadcom Kona/BCM590xx/PONKEY

2025-08-17T09:56:37Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/input/misc/bcmpmu59xxx_ponkey.c}}}}

The BCM590XX PMU can handle a power-on key (the responsible section is nicknamed PONKEY).

== Key press detection ==

When a key is pressed, the internal IRQ for a key press (BCM59054_IRQ_POK_PRESSED/BCM59056_IRQ_PONKEYB_F) is raised; when it is released, the internal IRQ for a key release (BCM59054_IRQ_POK_RELEASED/BCM59056_IRQ_PONKEYB_R) is raised. A driver can interpret these IRQs to toggle a key on/off (in downstream, it's wired up to <code>KEY_POWER</code> by default.

=== Debounce interval ===

A debounce interval can be configured independently for button press and release. The debounce values are 3 bits wide and stored in <code>PONKEYCTRL1</code>.

For the BCM59054/BCM59056, the allowed values are 330ns, 1.2ms, 10ms, 50ms, 100ms, 500ms, 1000ms and 2000ms. For the BCM59039/BCM59042/BCM59055, the allowed values are undocumented, but different from BCM59054/56 - <code>3</code> is equal to 100ms (whereas it's 50ms on 54/56).

== Timer ==

TODO. Seems like it might be possible to control long-press function using a timer (one of "poweroff", "restart" or "smart reset"). [https://github.com/knuxdroid/android_kernel_samsung_baffinlite/blob/cm-12.1/drivers/input/misc/bcmpmu59xxx_ponkey.c#L204-L277 Relevant kernel sources], notably commented out.

== Registers (BCM59054) ==

{{hatnote|See {{downstream|baffinlite|include/linux/mfd/bcmpmu59054_reg.h}}.}}

All of them are on MAP0.

=== PONKEYCTRL1 (0x08) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7
| Reserved/unknown
|-
| <code>RELEASE_DEB</code>
| 5:3
| Represents the release debounce.
|-
| <code>PRESS_DEB</code>
| 2:0
| Represents the press debounce.
|}

=== PONKEYCTRL2 (0x09) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>TX1_ACTION</code>
| 7:6
| TODO
|-
| <code>TX1_DLY</code>
| 5:3
| TODO
|-
| <code>TX1_DEB</code>
| 2:0
| TODO
|}

=== PONKEYCTRL3 (0x0A) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>TX2_ACTION</code>
| 7:6
| TODO
|-
| <code>TX2_DLY</code>
| 5:3
| TODO
|-
| <code>TX2_DEB</code>
| 2:0
| TODO
|}

=== PONKEYCTRL4 (0x0B) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7
| Reserved/unknown
|-
| <code>KEY_PAD_LOCK_MODE</code>
| 6
| TODO
|-
| <code>KEY_PAD_LOCK</code>
| 5
| TODO
|-
| <code>POK_RESTART_EN</code>
| 4
| TODO
|-
| Reserved/unknown
| 3
| Reserved/unknown
|-
| <code>POK_WAKUP_DEB</code>
| 2:0
| TODO
|}

=== PONKEYCTRL5 (0x0C) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:0
| Reserved/unknown
|}

=== PONKEYCTRL6 (0x0D) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:5
| Reserved/unknown
|-
| <code>SMART_RST_DLY</code>
| 4:3
| TODO
|-
| <code>SMART_RST_STATUS</code>
| 2
| TODO
|-
| <code>SMART_RST_PWR_EN</code>
| 1
| TODO
|-
| <code>SMART_RST_EN</code>
| 0
| TODO
|}

=== PONKEYCTRL7 (0x0E) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:0
| Reserved/unknown
|}

=== PONKEYCTRL8 (0x0F) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>TX3_ACTION</code>
| 7:6
| TODO
|-
| <code>TX3_DLY</code>
| 5:3
| TODO
|-
| <code>TX3_DEB</code>
| 2:0
| TODO
|}

Template:Todo

2025-08-17T09:39:41Z

Uart: Created page with "<templatestyles src="Todo/style.css"/><includeonly>{{Icon box | box-icons = TODO | box-text = TODO: {{{1}}} | border-color = #b60000 | border-width = 1px | background = #fdd1d1 | class = box-todo }}{{#if: {{{nocategory|}}}||Category:To-do items}}</includeonly><noinclude> <templatedata> { "params": { "1": { "label": "Text"..."

<templatestyles src="Todo/style.css"/><includeonly>{{Icon box
| box-icons = [[File:Red warning icon.svg|20px|link=|TODO]]
| box-text = TODO: {{{1}}}
| border-color = #b60000
| border-width = 1px
| background = #fdd1d1
| class = box-todo
}}{{#if: {{{nocategory|}}}||[[Category:To-do items]]}}</includeonly><noinclude>
<templatedata>
{
"params": {
"1": {
"label": "Text",
"description": "Text to place in the box",
"type": "unbalanced-wikitext",
"required": true
},
"nocategory": {
"label": "No category",
"description": "If true/yes, do not add this page to the \"To-do items\" category.",
"type": "boolean"
}
},
"description": "TODO box containing a to-do item. Also adds the page to the \"To-do items\" category; this behavior can be disabled with the \"nocategory\" parameter.",
"format": "inline"
}
</templatedata>

== Example ==

<nowiki>{{todo|This is '''yet to be done'''.}}</nowiki>

{{todo|This is '''yet to be done'''.|nocategory=yes}}
</noinclude>

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T17:41:04Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|0x07
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers. The masks are enforced by hardware - any bit written outside of the mask gets ignored.

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0).

If the date overflows (1 second after 2255-12-31 23:59:59), the clock returns to 2255-12-01 00:00:00.

=== Adjustment IRQ ===

There is an RTCADJ IRQ that is supposed to fire when the RTC value is invalid (at least according to the comments of the downstream driver, and the downstream BCM59055 RTC driver). However, I haven't been able to get it to fire in my testing.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}

Mainline:Broadcom Kona/BCM590xx/PONKEY

2025-08-15T17:32:35Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/input/misc/bcmpmu59xxx_ponkey.c}}}}

The BCM590XX PMU can handle a power-on key (the responsible section is nicknamed PONKEY).

== Key press detection ==

When a key is pressed, the internal IRQ for a key press (BCM59054_IRQ_POK_PRESSED/BCM59056_IRQ_PONKEYB_F) is raised; when it is released, the internal IRQ for a key release (BCM59054_IRQ_POK_RELEASED/BCM59056_IRQ_PONKEYB_R) is raised. A driver can interpret these IRQs to toggle a key on/off (in downstream, it's wired up to <code>KEY_POWER</code> by default.

=== Debounce interval ===

A debounce interval can be configured independently for button press and release. The debounce values are 3 bits wide and stored in <code>PONKEYCTRL1</code>.

For the BCM59054/BCM59056, the allowed values are 330ns, 1.2ms, 10ms, 50ms, 100ms, 500ms, 1000ms and 2000ms. For the BCM59039/BCM59042/BCM59055, the allowed values are undocumented, but different from BCM59054/56 - <code>3</code> is equal to 100ms (whereas it's 50ms on 54/56).

== Timer ==

TODO. Seems like it might be possible to control long-press function using a timer (one of "poweroff", "restart" or "smart reset"). [https://github.com/knuxdroid/android_kernel_samsung_baffinlite/blob/cm-12.1/drivers/input/misc/bcmpmu59xxx_ponkey.c#L204-L277 Relevant kernel sources], notably commented out.

== Registers (BCM59054) ==

{{hatnote|See {{downstream|baffinlite|include/linux/mfd/bcmpmu59054_reg.h}}.}}

All of them are on MAP0.

=== PONKEYCTRL1 (0x08) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7
| Reserved/unknown
|-
| <code>RELEASE_DEB</code>
| 5:3
| Represents the release debounce.
|-
| <code>PRESS_DEB</code>
| 2:0
| Represents the press debounce.
|}

=== PONKEYCTRL2 (0x09) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>TX_ACTION</code>
| 7:6
| TODO
|-
| <code>TX_DLY</code>
| 5:3
| TODO
|-
| <code>TX_DEB</code>
| 2:0
| TODO
|}

=== PONKEYCTRL3 (0x0A) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:0
| Reserved/unknown
|}

=== PONKEYCTRL4 (0x0B) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7
| Reserved/unknown
|-
| <code>KEY_PAD_LOCK_MODE</code>
| 6
| TODO
|-
| <code>KEY_PAD_LOCK</code>
| 5
| TODO
|-
| <code>POK_RESTART_EN</code>
| 4
| TODO
|-
| Reserved/unknown
| 3
| Reserved/unknown
|-
| <code>POK_WAKUP_DEB</code>
| 2:0
| TODO
|}

=== PONKEYCTRL5 (0x0C) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:0
| Reserved/unknown
|}

=== PONKEYCTRL6 (0x0D) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:5
| Reserved/unknown
|-
| <code>SMART_RST_DLY</code>
| 4:3
| TODO
|-
| <code>SMART_RST_STATUS</code>
| 2
| TODO
|-
| <code>SMART_RST_PWR_EN</code>
| 1
| TODO
|-
| <code>SMART_RST_EN</code>
| 0
| TODO
|}

=== PONKEYCTRL7 (0x0E) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:0
| Reserved/unknown
|}

=== PONKEYCTRL8 (0x0F) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| Reserved/unknown
| 7:0
| Reserved/unknown
|}

Mainline:Broadcom Kona/BCM590xx/PONKEY

2025-08-15T17:16:30Z

Uart:

The BCM590XX PMU can handle a power-on key (the responsible section is nicknamed PONKEY).

== Key press detection ==

When a key is pressed, the internal IRQ for a key press (BCM59054_IRQ_POK_PRESSED/BCM59056_IRQ_PONKEYB_F) is raised; when it is released, the internal IRQ for a key release (BCM59054_IRQ_POK_RELEASED/BCM59056_IRQ_PONKEYB_R) is raised. A driver can interpret these IRQs to toggle a key on/off (in downstream, it's wired up to <code>KEY_POWER</code> by default.

=== Debounce interval ===

A debounce interval can be configured independently for button press and release. The debounce values are 3 bits wide and stored in <code>PONKEYCTRL1</code>.

For the BCM59054/BCM59056, the allowed values are 330ns, 1.2ms, 10ms, 50ms, 100ms, 500ms, 1000ms and 2000ms. For the BCM59039/BCM59042/BCM59055, the allowed values are undocumented, but different from BCM59054/56 - <code>3</code> is equal to 100ms (whereas it's 50ms on 54/56).

== Timer ==

TODO. Seems like it might be possible to control long-press function using a timer (one of "poweroff", "restart" or "smart reset"). [https://github.com/knuxdroid/android_kernel_samsung_baffinlite/blob/cm-12.1/drivers/input/misc/bcmpmu59xxx_ponkey.c#L204-L277 Relevant kernel sources], notably commented out.

{{Subpages}}

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T12:57:56Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|0x07
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers. The masks are enforced by hardware - any bit written outside of the mask gets ignored.

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

If the date overflows (1 second after 2255-12-31 23:59:59), the clock returns to 2255-12-01 00:00:00.

=== Adjustment IRQ ===

There is an RTCADJ IRQ that is supposed to fire when the RTC value is invalid (at least according to the comments of the downstream driver, and the downstream BCM59055 RTC driver). However, I haven't been able to get it to fire in my testing.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T12:47:29Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|0x07
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers. In the time registers, the masks are enforced by hardware - any bit written outside of the mask gets ignored.

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

If the date overflows (1 second after 2255-12-31 23:59:59), the clock returns to 2255-12-01 00:00:00.

=== Adjustment IRQ ===

There is an RTCADJ IRQ that is supposed to fire when the RTC value is invalid (at least according to the comments of the downstream driver, and the downstream BCM59055 RTC driver). However, I haven't been able to get it to fire in my testing.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T12:45:20Z

Uart: /* Getting the time */

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|0x07
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers. In the time registers, the masks are enforced by hardware - any bit written outside of the mask gets ignored.

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

If the date overflows (1 second after 2255-12-31 23:59:59), the clock returns to 2255-12-01 00:00:00.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T12:44:06Z

Uart: /* Time data */

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|0x07
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers. In the time registers, the masks are enforced by hardware - any bit written outside of the mask gets ignored.

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T12:38:57Z

Uart: /* Time data */

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|0x0F
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers. In the time registers, the masks are enforced by hardware - any bit written outside of the mask gets ignored.

TODO: What happens on year overflow? Is there a reason as to why the downstream driver limits the values it gets?

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}

Mainline:Broadcom Kona/BCM590xx/RTC

2025-08-15T12:21:16Z

Uart:

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/rtc/rtc-bcmpmu59xxx.c}}}}

The BCM590XX PMUs provide a real-time clock.

== Time data ==

The RTC stores the time in the following format:

{|class="wikitable bittable"
!Offset
!Purpose
!Mask
!Value
|-
|0
|Second (<code>SC</code>)
|0x3F
|Current second, from 0 to 59.
|-
|1
|Minute (<code>MN</code>)
|0x3F
|Current minute of the hour, from 0 to 59.
|-
|2
|Hour (<code>HR</code>)
|0x1F
|Current hour of the day, from 0 to 23.
|-
|3
|Weekday (<code>WD</code>)
|{{speculation|0x0F}}
|Day of week, from 0 to 6. Appears to roll over whenever the day changes; {{speculation|the hardware does not enforce a specific start.}} Sets itself to 0 on reset. '''Not used in downstream.''' {{speculation|The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.}}
|-
|4
|Day of month (<code>DT</code>)
|0x1F
|Day of month, starting from 1. Sets itself to 0 on reset.
|-
|5
|Month (<code>MT_WD</code>)
|0x0F
|Number of the month. 1 to 12 represent January-December.
|-
|6
|Year (<code>YR</code>)
|0xFF
|Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)
|}

This exact format is used for both the time and alarm registers.

TODO: What happens on year overflow? Is there a reason as to why the downstream driver limits the values it gets?

== Getting the time ==

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is <code>0 0 0 0 0 1 7</code> (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

== Alarm ==

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

== Calibration ==

{{hatnote|Downstream driver: {{downstream|baffinlite|drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c}}}}

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

{{todo|Figure out how the calibration process works, this is just my initial idea}}

{{speculation|Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio".}} The ratio value is then compared against <code>RTCCAL_Ratio</code> (taken from <code>rtccal_data.nom_ratio</code>, <code>8666667</code>); if <code>ratio > RTCCAL_Ratio</code>, then direction is 1, otherwise it's 0.

The <code>clk_val</code> value is then calculated based on the difference between the new and old ratio (<code>diff = abs(ratio - RTCCAL_Ratio)</code>): <code>clk_val = RTCCAL_Ratio / diff</code>.

TODO - what is the ratio value?

=== CALIB1 (0xF4) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (1)
| 7:0
| Lower 8 bits of the calibration offset.
|}

=== CALIB2 (0xF5) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>clk_val</code> (2)
| 7:0
| Upper 8 bits of the calibration offset.
|}

=== CALIB3 (0xF6) ===

{|class="wikitable bittable"
!Name
!Bit
!Description
|-
| <code>???</code>
| 7
| Set to 1 during calibration.
|-
| <code>direction</code>
| 6
|
|-
| Unknown/reserved
| 5:0
| Unknown/reserved.
|}