The Undocumented Pi

=Hardware=

SoC
There is a nicely ordered table with all BCM2835_registers as found in the GPU code published by Broadcom. Unfortunately, the table does not quite match the SoC in the Raspberry Pi, but it's a good start. The sections below should serve as a companion to that table.

Clocks
All SoC clocks are derived from a crystal oscillator (54.0 MHz for RPi4, 19.2 MHz for all other models). RPi4 has one more oscillator (25.0 MHz), which is used by the VIA VL805 USB 3.0 host controller. A diagram of the clock hierarchy:



Each PLL is a fractional N frequency synthesizer that can generate N/M times the crystal oscillator frequency (XOSC). The integer part of N is controlled by the NDIV field of the  register; the fractional part is stored in. The M refers to the PDIV field of. There is also a prescaler in the feedback path, which is controlled by a bit in the register:


 * bit 11 for PLLH
 * bit 14 for all other PLLs



The loop filter is controlled by three parameters: KA, KI and KP (cf. ). It is most likely some sort of a PIDA (proportional-integral-derivative-accelerated) controller, but it is not clear why there is no KD coefficient.

A PLL can have up to 4 output channels, each with an independent divider. These PLL channels can be used as clock sources by the individual muxes. There are different kinds of muxes:


 * Oscillator muxes cannot use any PLL channels.
 * Core muxes can use PLL CORE channels.
 * Peripheral muxes can use PLL PER channels.
 * DSIx muxes can use PLL DSIx channels. DSI0 clock source can be taken either from PLLA, or from PLLD, depending on the  bit in the   register.

The frequency of some clocks can be set in config.txt:

BCM283x
There is a VCE block to accelerate video encoding/decoding. No documentation AFAIK.

BCM2711
This chip may not have PLLH, or it works differently.

There is no prescaler in the feedback loop. The corresponding bit in ANA1 can still be set, but it does not have any effect on the PLL frequency.

It also lacks the following clock muxes:


 * GNRIC
 * CCP2
 * HSM (controlled through other registers?)
 * SLIM
 * SDC (secondary SDRAM clock)
 * ARM (controlled through other registers?)
 * AVEO

It has the following extra clock mux registers (their names are just made up, because there is no official documentation):

There is a hardware register which contains the chip version and revision (name made up again):

The VCE block was apparently removed, but there is now a HEVC block.

PMIC
The BCM2835 chip has an on-chip SMPS and an LDO for the LPDDR2 memory chip. RPi2 and RPi3 B use custom circuitry to do the power-up sequencing; it is made of discrete components, including an NCP6343 chip (datasheet) at I²C address 0x1c. The RPi 3B+ and RPi 4B boards contain a MaxLinear MxL7704 (datasheet) at address 0x1d.

The PMIC is always on the system I²C bus (I2C8 on RPi4, I2C0 on all other devices).

See also this very informative blog post by James Adams.

=Boot ROM=

=Firmware=

There are multiple firmware variants available. First, the firmware binaries with a '4' in the name are intended for Raspberry Pi 4. They should also work with earlier Raspberry Pi models, but they are not tested for that use case. Second, the suffix refers to available features:


 * start.elf' / start4.elf: Standard version.
 * start_x.elf / start4x.elf: Extra features (AFAIK only the camera stack).
 * start_db.elf / start4db.elf: Debugging version (with additional logging).
 * start_cd.elf / start4cd.elf: Cut down version (to reduce memory footprint).

The firmware reads options from config.txt. Most options are officially documented, but there are additional undocumented options. Note that this is a growing list.

audio_pwm_mode
Select Sigma-Delta Modulation mode. This parameter is in fact somewhat documented. Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=136445
 * https://www.raspberrypi.org/forums/viewtopic.php?t=195178

disable_poe_fan
Disable fan on the PoE HAT. Mentioned here:


 * https://github.com/raspberrypi/linux/issues/2715#issuecomment-429407931
 * https://www.raspberrypi.org/forums/viewtopic.php?t=219050&start=25#p1354556

enable_hdmi_status
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/287#issuecomment-46027483

enable_l2cache_writealloc
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?p=253306#p255679

extra_transpose_buffer
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/837#issuecomment-353619118

fake_vsync_isr
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?p=568591#p568586

force_mac_address
Use this option to set a non-default MAC address for the on-board Ethernet. For example:

force_mac_address=12:34:56:78:9a:bc

force_board_rev
Force a board revision code. This works only if OTP register 30 is currently unprogrammed.

Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/758#issuecomment-287548927

force_hdmi_open
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?p=514292#p514960

force_pvt
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/684#issuecomment-263264803

force_pwm_open
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?p=548859#p548859

framebuffer_align
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/22#issuecomment-6018546

framebuffer_aspect
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/638#issuecomment-238987999

framebuffer_swap
Mentioned here:


 * https://github.com/raspberrypi/linux/issues/514#issuecomment-34805537

hdmi_audio_config
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/561#issuecomment-194440209

hdmi_mai_thresh
Mentioned here:


 * https://forum.kodi.tv/archive/index.php?thread-222061-5.html

hdmi_muting
Mentioned here:


 * https://forum.kodi.tv/showthread.php?pid=2434683#pid2434683

hvs_priority
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=79330#p584389

hvs_set_dither
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=45290#p363475

hvs_swap_red_blue
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/22#issuecomment-6018546

mask_gpu_interrupt0, mask_gpu_interrupt1
Mentioned in the VC4 driver documentation:


 * http://web.archive.org/web/20150205035712/https://dri.freedesktop.org/wiki/VC4/

Apparently no longer needed:


 * https://github.com/raspberrypi/linux/issues/1455#issuecomment-217300757

osc_debug
Output oscillator/N to GPCLK1.

Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=22274#p211120

otg_mode
Mentioned here:


 * https://github.com/raspberrypi/documentation/issues/1217#issuecomment-536932640

ov5647_acls
Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=73998&p=971956#p959022

program_batch_num
Set the value of OTP register 31.

Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/974#issuecomment-383408904

program_board_rev
Set the board revision code (OTP register 30). This only works if you currently have a zero board rev.

Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=12007&start=25#p227069

program_emmc_boot
Used for CM3 just to help get around a bug in the boot ROM.

Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/974#issuecomment-383513758

program_mac_address
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/974#issuecomment-383513758

refresh_change
Mentioned here:


 * https://forum.kodi.tv/showthread.php?tid=176043&pid=1682550#pid1682550

safe_mode_gpio
Apparently obsoleted by.

Mentioned here:


 * https://www.raspberrypi.org/forums/viewtopic.php?t=105502#p738311

scaling_kernel
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/104#issuecomment-9585095

usb_mdio
Mentioned here:


 * https://github.com/asb/firmware/commit/e6b21d6a62c9a29d4e2dece0452908449b434400

v3d_limiter
Mentioned here:


 * https://forum.kodi.tv/showthread.php?tid=269814&pid=2373475#pid2373475

vd_min_images
Mentioned here:


 * https://github.com/raspberrypi/firmware/issues/337#issuecomment-72948149

xosc_bias
=Abbreviations=


 * APB
 * Advanced Peripheral Bus


 * ASB
 * APB Sync Bridge


 * CCP2
 * Compact Camera Port 2


 * CM
 * Clock Manager


 * HSM
 * HDMI State Machine


 * HVS
 * Hardware Video Scaler


 * ISP
 * Image Sensor Pipeline


 * OTP
 * One-Time Programmable (memory)


 * TXP
 * Transposer


 * VEC
 * Video Encoder