The Undocumented Pi

From eLinux.org
Revision as of 05:35, 10 August 2021 by Elijah (talk | contribs) (Abbreviations: Add TXP)
Jump to: navigation, search

Contents

Back to the Hub.


Resources:

Hardware & Peripherals:

Hardware and Hardware History.

Low-level Peripherals and Expansion Boards.

Screens, Cases and Other Peripherals.

Software & OS Distributions:

Software and Distributions

Documentation:

Documentation Page

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:

Clock diagram

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 A2W_PLLx_CTRL register; the fractional part is stored in A2W_PLLx_FRAC. The M refers to the PDIV field of A2W_PLLx_CTRL. There is also a prescaler in the feedback path, which is controlled by a bit in the A2W_PLLx_ANA1 register:

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

PLL block diagram

The loop filter is controlled by three parameters: KA, KI and KP (cf. A2W_PLLx_ANA_KAIP). It is most likely some sort of a PID controller, but it is not clear why the first coefficient is called KA and not KD. It may have some significance, though.

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 SELPLLD bit in the DSI0HSCK register.

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

name address type width mask reset description
CM_HEVCCTL 0x7e1011c8 RW 20 ??? 0000000000
CM_HEVCDIV 0x7e1011cc RW 24 0x00ffffff 0000000000
CM_EMMC2CTL 0x7e1011d0 RW 20 ??? 0000000000
CM_EMMC2DIV 0x7e1011d4 RW 24 0x00ffffff 0000000000
CM_GENET250CTL 0x7e1011e8 RW 20 ??? 0000000000
CM_GENET250DIV 0x7e1011ec RW 24 0x00ffffff 0000000000
CM_STB27CTL 0x7e1011f0 RW 20 ??? 0000000000
CM_STB27DIV 0x7e1011f4 RW 24 0x00ffffff 0000000000
CM_STB108CTL 0x7e101200 RW 20 ??? 0000000000
CM_STB108DIV 0x7e101204 RW 24 0x00ffffff 0000000000
CM_PIXBVBCTL 0x7e101208 RW 20 ??? 0000000000
CM_PIXBVBDIV 0x7e10120c RW 24 0x00ffffff 0000000000
CM_GENET125CTL 0x7e101210 RW 20 ??? 0000000000
CM_GENET125DIV 0x7e101214 RW 24 0x00ffffff 0000000000
CM_M2MCCTL 0x7e10122c RW 20 ??? 0000000000
CM_M2MCDIV 0x7e101230 RW 24 0x00ffffff 0000000000
CM_USBXHCICTL 0x7e10123c RW 20 ??? 0000000000
CM_USBXHCIDIV 0x7e101240 RW 24 0x00ffffff 0000000000

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

name address type width mask reset description
ID_CHIPREV 0x7c404000 RW 24 0xffffffff 2711xxxxxx

Bits 16..31 always contain the value 0x2711. Bits 0..7 contain the stepping, apparently encoded as two nibbles: ((letter - 'A') << 4) | digit, for example B0 gets encoded as 0x10.

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.

aphy_params

aphy_params_current

audio_pwm_mode

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

avoid_edid_fuzzy_match

avs_disable

boot_partition

boot_signing_key0, boot_signing_key1, boot_signing_key2, boot_signing_key3

config_hdmi_preemphasis

decode_0001

decode_DDP

decode_DTS

desired_osc_freq, desired_osc_freq2

desired_osc_freq_boost

disable_poe_fan

Disable fan on the PoE HAT. Mentioned here:

dispmanx_lbm_max

dphy_params

dphy_params_current

enable_hdmi_status

Mentioned here:

enable_l2cache_writealloc

Mentioned here:

extra_transpose_buffer

Mentioned here:

fake_vsync_isr

Mentioned here:

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:

force_core

force_hdmi_open

Mentioned here:

force_pvt

Mentioned here:

force_pwm_open

Mentioned here:

force_serial_number

framebuffer_align

Mentioned here:

framebuffer_aspect

Mentioned here:

framebuffer_swap

Mentioned here:

hdmi_audio_config

Mentioned here:

hdmi_channel_map

hdmi_clock_change_limit

hdmi_clock_change_rate

hdmi_deep_color

hdmi_dma_waits

hdmi_force_cec_address

hdmi_force_rb2

hdmi_ignore_edid_3d

hdmi_mai_thresh

Mentioned here:

hdmi_muting

Mentioned here:

hdmi_pixel_clock_type

hdmi_pixel_freq_limit, hdmi_pixel_freq_limit_min

hdmi_preferred_port

hdmi_samples_limit

hdmi_stream_channels

hdmi_test

hdmi_wifi_pixel_freq_adj

hvs_gamma_test

hvs_priority

Mentioned here:

hvs_set_dither

Mentioned here:

hvs_swap_red_blue

Mentioned here:

legacy_mapping

mask_gpu_interrupt0, mask_gpu_interrupt1

Mentioned in the VC4 driver documentation:

Apparently no longer needed:

max_clock_drift

max_clock_drift_rate

max_pll_freq

num_stream_blocks

osc_debug

Output oscillator/N to GPCLK1.

Mentioned here:

otg_mode

Mentioned here:

ov5647_acls

Mentioned here:

over_voltage_avs

over_voltage_avs_boost

pause_burst_frames

pin_test

pmic_override

program_batch_num

Set the value of OTP register 31.

Mentioned here:

program_board_rev

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

Mentioned here:

program_emmc_boot

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

Mentioned here:

program_mac_address

Mentioned here:

program_mfgtest_fail

program_serial_number

program_serial_random

pwm_mode_pwm

recovery_mode

reduced_axi

refresh_change

Mentioned here:

remote_gpu_mem

safe_mode_gpio

Apparently obsoleted by max_usb_current.

Mentioned here:

scaling_kernel

Mentioned here:

sdram_schmoo

second_boot

usb_mdio

Mentioned here:

v3d_limiter

Mentioned here:

vcos_logging_level

vd_min_images

Mentioned here:

vl805_hub2_file

vl805_mcu_file

vl805_no_spi

xosc_bias

Abbreviations

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