Mainline:Broadcom Kona/Introduction - Revision history

Knuxify at 00:07, 9 February 2025

2025-02-09T00:07:49Z

← Older revision		Revision as of 02:07, 9 February 2025
Line 12:		Line 12:
	Capri kernel sources also mention BCM28150/BCM28160 which are codenamed Island and appear to be similar to Capri; however, they do not seem to have been included in any consumer-available hardware.		Capri kernel sources also mention BCM28150/BCM28160 which are codenamed Island and appear to be similar to Capri; however, they do not seem to have been included in any consumer-available hardware.

	Similarily, mentions of chips codenamed Hera and Samoa appear in some kernel sources, but with no relevant kernel config options - it is unknown which SoCs, if any, they correspond to.		Similarily, mentions of chips codenamed Athena, Hera and Samoa appear in some kernel sources, but with no relevant kernel config options - it is unknown which SoCs, if any, they correspond to.

	These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.		These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.

Knuxify: /* Chip introduction */

2025-02-09T00:06:18Z

Chip introduction

← Older revision		Revision as of 02:06, 9 February 2025
Line 11:		Line 11:

	Capri kernel sources also mention BCM28150/BCM28160 which are codenamed Island and appear to be similar to Capri; however, they do not seem to have been included in any consumer-available hardware.		Capri kernel sources also mention BCM28150/BCM28160 which are codenamed Island and appear to be similar to Capri; however, they do not seem to have been included in any consumer-available hardware.

			Similarily, mentions of chips codenamed Hera and Samoa appear in some kernel sources, but with no relevant kernel config options - it is unknown which SoCs, if any, they correspond to.

	These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.		These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.

Knuxify: /* Using the RDB */

2025-02-05T17:09:12Z

Using the RDB

← Older revision		Revision as of 19:09, 5 February 2025
Line 55:		Line 55:
	[[File:Generate-dump-diff output example.png\|thumb\|Example screenshot showing the output of generate-dump-diff.py]]		[[File:Generate-dump-diff output example.png\|thumb\|Example screenshot showing the output of generate-dump-diff.py]]

	~~I maintain~~ a set of relevant reverse-engineering tools at [https://github.com/refractionware/reveng github.com/refractionware/reveng]. The most directly useful ones are:		[[User:Knuxify\|knuxify]] maintains a set of relevant reverse-engineering tools at [https://github.com/refractionware/reveng github.com/refractionware/reveng]. The most directly useful ones are:

	* <code>tools/devmem-read-block.sh</code> - given a start address and the offset of the last register (inclusive), dumps all of the registers.		* <code>tools/devmem-read-block.sh</code> - given a start address and the offset of the last register (inclusive), dumps all of the registers.

Knuxify: /* Chip introduction */

2025-02-04T08:11:54Z

Chip introduction

← Older revision		Revision as of 10:11, 4 February 2025
Line 9:		Line 9:
	* BCM21663/BCM21664 (Hawaii)		* BCM21663/BCM21664 (Hawaii)
	* BCM23550 (Java)		* BCM23550 (Java)

			Capri kernel sources also mention BCM28150/BCM28160 which are codenamed Island and appear to be similar to Capri; however, they do not seem to have been included in any consumer-available hardware.

	These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.		These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.

Knuxify: link to some kernels

2025-02-04T07:46:07Z

link to some kernels

← Older revision		Revision as of 09:46, 4 February 2025
Line 18:		Line 18:
	Two downstream kernels exist for these chips:		Two downstream kernels exist for these chips:

	* An older 3.0 kernel for the BCM281x5, and another variant for the BCM21654.		* An older 3.0 kernel for the BCM281x5, and another variant for the BCM21654. ([https://github.com/ghsr/android_kernel_samsung_i9152 BCM28155 (Samsung Galaxy Mega 5.8/crater)], [https://github.com/wulsic/android_kernel_samsung_nevisp BCM21654 (Samsung Galaxy Fame/nevisp)])
	* A newer 3.4 kernel (later updated to 3.10), with support for the BCM21664 and BCM23550, as well as partial support for the BCM21654.		* A newer 3.4 kernel (later updated to 3.10), with support for the BCM21664 and BCM23550, as well as partial support for the BCM21654. ([https://github.com/knuxdroid/android_kernel_samsung_baffinlite 3.4 kernel (Samsung Galaxy Grand Neo/baffinlite)], [https://android.googlesource.com/kernel/bcm/+/refs/heads/android-bcm-tetra-3.10-marshmallow-dr1-wear-release 3.10 kernel (Sony Smartwatch 3/tetra)])

	In both kernels, most of the relevant downstream drivers for the Kona platform are stored in <code>arch/arm/plat-kona</code>; the individual board files for each device and chip-specific info is stored in <code>arch/arm/mach-(codename)</code> (where <code>(codename)</code> is one of <code>capri</code>, <code>rhea</code>, <code>hawaii</code> or <code>java</code>).		In both kernels, most of the relevant downstream drivers for the Kona platform are stored in <code>arch/arm/plat-kona</code>; the individual board files for each device and chip-specific info is stored in <code>arch/arm/mach-(codename)</code> (where <code>(codename)</code> is one of <code>capri</code>, <code>rhea</code>, <code>hawaii</code> or <code>java</code>).

Knuxify: /* Porting drivers from downstream to mainline */

2025-02-04T06:51:47Z

Porting drivers from downstream to mainline

← Older revision		Revision as of 08:51, 4 February 2025
Line 63:		Line 63:
	* Copy <code>devmem-read-block.sh</code> to the device and dump the relevant registers; save the files in two separate directories, to make sure you don't mistake downstream for mainline		* Copy <code>devmem-read-block.sh</code> to the device and dump the relevant registers; save the files in two separate directories, to make sure you don't mistake downstream for mainline
	* Run <code>generate-dump-diff.py</code> on the generated dumps and look at differences in the browser		* Run <code>generate-dump-diff.py</code> on the generated dumps and look at differences in the browser

			=== Porting board files to DTS ===

			New kernels use device trees to describe components. The Kona downstream kernels are too old to use it; rather, while they have some DTS support and files, they don't seem to actually be used in any of the production devices.

			Instead, the relevant device info is stored in board files in <code>arch/arm/mach-(codename)</code> directories. These files contain the relevant setup for all componenets. There's usually a separate "board-bcm590xx" file that contains BCM590xx PMIC settings.

			Note that board files contain configuration for lots of possible components that may not actually be present on your device; these are usually commented out with <code>#ifdef</code> statements referencing defconfig options. Make sure to have your device's defconfig handy for reference.

			(todo: add more info here)

	== See also ==		== See also ==

	* [https://wiki.postmarketos.org/wiki/Mainlining Mainlining on the postmarketOS wiki]		* [https://wiki.postmarketos.org/wiki/Mainlining Mainlining on the postmarketOS wiki]

Knuxify: Created page with "The following page is a general introduction to the Broadcom Kona platform and getting started with mainlining. == Chip introduction == '''Broadcom Kona''' is a series of chips primarily marketed for mobile use, released between 2012 and 2013. It comprises of the following chips: * BCM28145/BCM28155 (Capri) * BCM21654 (Rhea) * BCM21663/BCM21664 (Hawaii) * BCM23550 (Java) These chips all share similar components, with a similar internal register layout. They can be gr..."

2025-02-04T06:47:38Z

Created page with "The following page is a general introduction to the Broadcom Kona platform and getting started with mainlining. == Chip introduction == '''Broadcom Kona''' is a series of chips primarily marketed for mobile use, released between 2012 and 2013. It comprises of the following chips: * BCM28145/BCM28155 (Capri) * BCM21654 (Rhea) * BCM21663/BCM21664 (Hawaii) * BCM23550 (Java) These chips all share similar components, with a similar internal register layout. They can be gr..."

New page

The following page is a general introduction to the Broadcom Kona platform and getting started with mainlining.

== Chip introduction ==

'''Broadcom Kona''' is a series of chips primarily marketed for mobile use, released between 2012 and 2013. It comprises of the following chips:

* BCM28145/BCM28155 (Capri)
* BCM21654 (Rhea)
* BCM21663/BCM21664 (Hawaii)
* BCM23550 (Java)

These chips all share similar components, with a similar internal register layout. They can be grouped into three "generations": the BCM281x5 is first, the BCM21654 is second, and the BCM2166x/BCM23550 is third.

The BCM2166x and BCM23550 are nearly identical - the BCM23550 has 4 Cortex A7 CPUs instead of 2 Cortex A9 CPUs, and an extra ISP block, but is otherwise identical to the BCM21664.

== Downstream kernel ==

Two downstream kernels exist for these chips:

* An older 3.0 kernel for the BCM281x5, and another variant for the BCM21654.
* A newer 3.4 kernel (later updated to 3.10), with support for the BCM21664 and BCM23550, as well as partial support for the BCM21654.

In both kernels, most of the relevant downstream drivers for the Kona platform are stored in <code>arch/arm/plat-kona</code>; the individual board files for each device and chip-specific info is stored in <code>arch/arm/mach-(codename)</code> (where <code>(codename)</code> is one of <code>capri</code>, <code>rhea</code>, <code>hawaii</code> or <code>java</code>).

Both of these kernels predate DTS being used for most devices; while the 3.4/3.10 kernel supports DT, and there are some DTS files, this support is very partial and it's not used on any of Samsung's phones with the relevant chips.

=== RDB ===

Other than the drivers, the kernels contain a very useful resource for reverse-engineering: the RDB (which presumably stands for "register database").

The RDB is a series of header files containing the internal register layout of all blocks on the SoC. Each SoC has its own RDB headers; they are located in <code>arch/arm/mach-(codename)/include/mach/rdb</code> (usually there are a few RDB directories named <code>rdb_A</code>, <code>rdb_Bx</code> - these appear to be chip revisions, and the <code>rdb</code> path should symlink to the latest one).

Each RDB folder contains a '''sysmap''' header (example: {{downstream|baffinlite|arch/arm/mach-java/include/mach/rdb/brcm_rdb_sysmap.h}}); this header contains the offsets for each block on the SoC, and a comment with the location of the relevant RDB header. This is useful for knowing the locations of blocks in register space, and for connecting a location to a register layout header.

The individual blocks each have their own RDB header, following the <code>brcm_rdb_(name).h</code> convention (example: {{downstream|baffinlite|arch/arm/mach-java/include/mach/rdb/brcm_rdb_khub_clk_mgr_reg.h}}. These headers contain the offsets and names of each register within the block, as well as the names and shifts/masks of each bit within those registers.

== Porting drivers from downstream to mainline ==

This section contains hints for figuring out how to port a component from downstream to mainline, or debug a non-working driver.

=== Finding the downstream driver ===

Nowadays, most drivers in the Linux kernel are stored in the <code>drivers/</code> folder and its subdirectories. In the case of the Kona downstream kernel, however, all platform drivers (with a handful of exceptions, like SDHCI) are stored in <code>arch/arm/plat-kona</code>, with some SoC-specific initialization code in the <code>arch/arm/mach-(codename)</code> directories.

The easiest way to find relevant info is to do a <code>grep -iR "phrase"</code> in the downstream kernel (which is why it's handy to have it downloaded).

=== Using the RDB ===

The aforementioned RDB can also be used for figuring stuff out; the platform drivers use register info from the RDB pretty extensively, so you may have some luck grepping for the register names.

For a quick overview of differences between downstream and mainline driver behavior, one can dump the relevant registers from downstream and mainline using <code>devmem2</code> and compare the two. Combined with RDB data as documentation, this can give you a pretty good idea of what to add/modify to get the component working.

[[File:Generate-dump-diff output example.png|thumb|Example screenshot showing the output of generate-dump-diff.py]]

I maintain a set of relevant reverse-engineering tools at [https://github.com/refractionware/reveng github.com/refractionware/reveng]. The most directly useful ones are:

* <code>tools/devmem-read-block.sh</code> - given a start address and the offset of the last register (inclusive), dumps all of the registers.
* <code>generate-dump-diff.py</code> creates a HTML representation of the diff of two dumps, which also lists names of all registers and shows you the bit names on hover. You will have to modify this file to point to your downstream kernel location; once you do, it should automatically find the relevant RDB files to parse as documentation.

Usually, the process looks something like this:

* Open the RDB sysmap (see "RDB" section above) and locate the entries for all possibly relevant blocks (e.g. for storage: SDIO, PAD_CTRL, etc.); open the header files for those and get the offset of the last component (at the end of the file)
* Copy <code>devmem-read-block.sh</code> to the device and dump the relevant registers; save the files in two separate directories, to make sure you don't mistake downstream for mainline
* Run <code>generate-dump-diff.py</code> on the generated dumps and look at differences in the browser

== See also ==

* [https://wiki.postmarketos.org/wiki/Mainlining Mainlining on the postmarketOS wiki]