1# Optional build configuration 2 3There are a set of ways in which a user can influence different parameters of 4the build. We list here the ones that are closely related to this BSP or 5specific to it. For the rest please check: 6<http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html> 7 8## Compressed deployed files 9 101. Overwrite IMAGE_FSTYPES in local.conf 11 * `IMAGE_FSTYPES = "tar.bz2 ext3.xz"` 12 132. Overwrite SDIMG_ROOTFS_TYPE in local.conf 14 * `SDIMG_ROOTFS_TYPE = "ext3.xz"` 15 16Accommodate the values above to your own needs (ex: ext3 / ext4). 17 18## GPU memory 19 20* `GPU_MEM`: GPU memory in megabyte. Sets the memory split between the ARM and 21 GPU. ARM gets the remaining memory. Min 16. Default 64. 22 23* `GPU_MEM_256`: GPU memory in megabyte for the 256MB Raspberry Pi. Ignored by 24 the 512MB RP. Overrides gpu_mem. Max 192. Default not set. 25 26* `GPU_MEM_512`: GPU memory in megabyte for the 512MB Raspberry Pi. Ignored by 27 the 256MB RP. Overrides gpu_mem. Max 448. Default not set. 28 29* `GPU_MEM_1024`: GPU memory in megabyte for the 1024MB Raspberry Pi. Ignored by 30 the 256MB/512MB RP. Overrides gpu_mem. Max 944. Default not set. 31 32See: <https://www.raspberrypi.com/documentation/computers/config_txt.html#memory-options> 33 34## VC4 35 36By default, each machine uses `vc4` for graphics. This will in turn sets mesa as provider for `gl` libraries. `DISABLE_VC4GRAPHICS` can be set to `1` to disable this behaviour falling back to using `userland`. Be aware that `userland` has not support for 64-bit arch. If you disable `vc4` on a 64-bit Raspberry Pi machine, expect build breakage. 37 38## Add purchased license codecs 39 40To add your own licenses use variables `KEY_DECODE_MPG2` and `KEY_DECODE_WVC1` in 41local.conf. Example: 42 43 KEY_DECODE_MPG2 = "12345678" 44 KEY_DECODE_WVC1 = "12345678" 45 46You can supply more licenses separated by comma. Example: 47 48 KEY_DECODE_WVC1 = "0x12345678,0xabcdabcd,0x87654321" 49 50See: <https://www.raspberrypi.com/documentation/computers/config_txt.html#licence-key-and-codec-options> 51 52## Disable overscan 53 54By default the GPU adds a black border around the video output to compensate for 55TVs which cut off part of the image. To disable this set this variable in 56local.conf: 57 58 DISABLE_OVERSCAN = "1" 59 60## Disable splash screen 61 62By default a rainbow splash screen is shown after the GPU firmware is loaded. 63To disable this set this variable in local.conf: 64 65 DISABLE_SPLASH = "1" 66 67## Boot delay 68 69The Raspberry Pi waits a number of seconds after loading the GPU firmware and 70before loading the kernel. By default it is one second. This is useful if your 71SD card needs a while to get ready before Linux is able to boot from it. 72To remove (or adjust) this delay set these variables in local.conf: 73 74 BOOT_DELAY = "0" 75 BOOT_DELAY_MS = "0" 76 77## Set overclocking options 78 79The Raspberry Pi can be overclocked. As of now overclocking up to the "Turbo 80Mode" is officially supported by the Raspberry Pi and does not void warranty. Check 81the config.txt for a detailed description of options and modes. The following 82variables are supported in local.conf: `ARM_FREQ`, `GPU_FREQ`, `CORE_FREQ`, 83`SDRAM_FREQ` and `OVER_VOLTAGE`. 84 85Example official settings for Turbo Mode in Raspberry Pi 2: 86 87 ARM_FREQ = "1000" 88 CORE_FREQ = "500" 89 SDRAM_FREQ = "500" 90 OVER_VOLTAGE = "6" 91 92See: <https://www.raspberrypi.com/documentation/computers/config_txt.html#overclocking-options> 93 94## HDMI and composite video options 95 96The Raspberry Pi can output video over HDMI or SDTV composite (the RCA connector). 97By default the video mode for these is autodetected on boot: the HDMI mode is 98selected according to the connected monitor's EDID information and the composite 99mode is defaulted to NTSC using a 4:3 aspect ratio. Check the config.txt for a 100detailed description of options and modes. The following variables are supported in 101local.conf: `HDMI_FORCE_HOTPLUG`, `HDMI_DRIVE`, `HDMI_GROUP`, `HDMI_MODE`, 102`HDMI_CVT`, `CONFIG_HDMI_BOOST`, `SDTV_MODE`, `SDTV_ASPECT` and `DISPLAY_ROTATE`. 103 104Example to force HDMI output to 720p in CEA mode: 105 106 HDMI_GROUP = "1" 107 HDMI_MODE = "4" 108 109See: <https://www.raspberrypi.com/documentation/computers/configuration.html#hdmi-configuration> 110 111## Video camera support with V4L2 drivers 112 113Set this variable to enable support for the video camera (Linux 3.12.4+ 114required): 115 116 VIDEO_CAMERA = "1" 117 118## Enable offline compositing support 119 120Set this variable to enable support for dispmanx offline compositing: 121 122 DISPMANX_OFFLINE = "1" 123 124This will enable the firmware to fall back to off-line compositing of Dispmanx 125elements. Normally the compositing is done on-line, during scanout, but cannot 126handle too many elements. With off-line enabled, an off-screen buffer is 127allocated for compositing. When scene complexity (number and sizes 128of elements) is high, compositing will happen off-line into the buffer. 129 130Heavily recommended for Wayland/Weston. 131 132See: <http://wayland.freedesktop.org/raspberrypi.html> 133 134## Enable kgdb over console support 135 136To add the kdbg over console (kgdboc) parameter to the kernel command line, set 137this variable in local.conf: 138 139 ENABLE_KGDB = "1" 140 141## Disable rpi boot logo 142 143To disable rpi boot logo, set this variable in local.conf: 144 145 DISABLE_RPI_BOOT_LOGO = "1" 146 147## Boot to U-Boot 148 149To have u-boot load kernel image, set in your local.conf: 150 151 RPI_USE_U_BOOT = "1" 152 153This will select the appropriate image format for use with u-boot automatically. 154For further customisation the KERNEL_IMAGETYPE and KERNEL_BOOTCMD variables can 155be overridden to select the exact kernel image type (eg. zImage) and u-boot 156command (eg. bootz) to be used. 157 158## Image with Initramfs 159 160To build an initramfs image: 161 162* Set this 3 kernel variables (in kernel's do_configure:prepend in linux-raspberrypi.inc after the line kernel_configure_variable LOCALVERSION "\"\"" 163) 164 - kernel_configure_variable BLK_DEV_INITRD y 165 - kernel_configure_variable INITRAMFS_SOURCE "" 166 - kernel_configure_variable RD_GZIP y 167 168* Set the yocto variables (e.g. in local.conf) 169 - `INITRAMFS_IMAGE = "<name for your initramfs image>"` 170 - `INITRAMFS_IMAGE_BUNDLE = "1"` 171 - `BOOT_SPACE = "1073741"` 172 - `INITRAMFS_MAXSIZE = "315400"` 173 - `IMAGE_FSTYPES_pn-${INITRAMFS_IMAGE} = "${INITRAMFS_FSTYPES}"` 174 175## Including additional files in the SD card image boot partition 176 177The SD card image class supports adding extra files into the boot 178partition, where the files are copied from either the image root 179partition or from the build image deploy directory. 180 181To copy files that are present in the root partition into boot, 182FATPAYLOAD is a simple space-separated list of files to be copied: 183 184 FATPAYLOAD = "/boot/example1 /boot/example2" 185 186To copy files from the image deploy directory, the files should be 187listed in the DEPLOYPAYLOAD as a space-separated list of entries. 188Each entry lists a file to be copied, and an optional destination 189filename can be specified by supplying it after a colon separator. 190 191 DEPLOYPAYLOAD = "example1-${MACHINE}:example1 example2" 192 193Files that are to be included from the deploy directory will be produced 194by tasks that image building task must depend upon, to ensure that the 195files are available when they are needed, so these component deploy 196tasks must be added to: RPI_SDIMG_EXTRA_DEPENDS. 197 198 RPI_SDIMG_EXTRA_DEPENDS:append = " example:do_deploy" 199 200## Enable SPI bus 201 202When using device tree kernels, set this variable to enable the SPI bus: 203 204 ENABLE_SPI_BUS = "1" 205 206## Enable I2C 207 208When using device tree kernels, set this variable to enable I2C: 209 210 ENABLE_I2C = "1" 211 212Furthermore, to auto-load I2C kernel modules set: 213 214 KERNEL_MODULE_AUTOLOAD:rpi += "i2c-dev i2c-bcm2708" 215 216## Enable PiTFT support 217 218Basic support for using PiTFT screens can be enabled by adding below in 219local.conf: 220 221* `MACHINE_FEATURES += "pitft"` 222 - This will enable SPI bus and i2c device-trees, it will also setup 223 framebuffer for console and x server on PiTFT. 224 225NOTE: To get this working the overlay for the PiTFT model must be build, added 226and specified as well (dtoverlay=<driver> in config.txt). 227 228Below is a list of currently supported PiTFT models in meta-raspberrypi, the 229modelname should be added as a MACHINE_FEATURES in local.conf like below: 230 231 MACHINE_FEATURES += "pitft <modelname>" 232 233List of currently supported models: 234* pitft22 235* pitft28r 236* pitft28c 237* pitft35r 238 239## Misc. display 240 241If you would like to use the Waveshare "C" 1024×600, 7 inch Capacitive Touch 242Screen LCD, HDMI interface (<http://www.waveshare.com/7inch-HDMI-LCD-C.htm>) Rev 2432.1, please set the following in your local.conf: 244 245 WAVESHARE_1024X600_C_2_1 = "1" 246 247## Enable UART 248 249RaspberryPi 0, 1, 2 and CM will have UART console enabled by default. 250 251RaspberryPi 0 WiFi and 3 does not have the UART enabled by default because this 252needs a fixed core frequency and enable_uart will set it to the minimum. Certain 253operations - 60fps h264 decode, high quality deinterlace - which aren't 254performed on the ARM may be affected, and we wouldn't want to do that to users 255who don't want to use the serial port. Users who want serial console support on 256RaspberryPi 0 Wifi or 3 will have to explicitly set in local.conf: 257 258 ENABLE_UART = "1" 259 260Ref.: 261* <https://github.com/raspberrypi/firmware/issues/553> 262* <https://github.com/RPi-Distro/repo/issues/22> 263 264## Enable USB Peripheral (Gadget) support 265 266The standard USB driver only supports host mode operations. Users who 267want to use gadget modules like g_ether should set the following in 268local.conf: 269 270 ENABLE_DWC2_PERIPHERAL = "1" 271 272## Enable USB host support 273 274By default in case of the Compute Module 4 IO Board the standard USB driver 275that usually supports host mode operations is disabled for power saving reasons. 276Users who want to use the 2 USB built-in ports or the other ports provided via 277the header extension should set the following in local.conf: 278 279 ENABLE_DWC2_HOST = "1" 280 281## Set CPUs to be isolated from the standard Linux scheduler 282 283By default Linux will use all available CPUs for scheduling tasks. For real time 284purposes there can be an advantage to isolating one or more CPUs from the 285standard scheduler. It should be noted that CPU 0 is special, it is the only CPU 286available during the early stages of the boot process and cannot be isolated. 287 288The string assigned to this variable may be a single CPU number, a comma 289separated list ("1,2"), a range("1-3"), or a mixture of these ("1,3-5") 290 291 ISOLATED_CPUS = "1-2" 292 293## Enable Openlabs 802.15.4 radio module 294 295When using device tree kernels, set this variable to enable the 802.15.4 hat: 296 297 ENABLE_AT86RF = "1" 298 299See: <https://openlabs.co/OSHW/Raspberry-Pi-802.15.4-radio> 300 301## Enable CAN 302 303In order to use CAN with an MCP2515-based module, set the following variables: 304 305 ENABLE_SPI_BUS = "1" 306 ENABLE_CAN = "1" 307 308In case of dual CAN module (e.g. PiCAN2 Duo), set following variables instead: 309 310 ENABLE_SPI_BUS = "1" 311 ENABLE_DUAL_CAN = "1" 312 313Some modules may require setting the frequency of the crystal oscillator used on the particular board. The frequency is usually marked on the package of the crystal. By default, it is set to 16 MHz. To change that to 8 MHz, the following variable also has to be set: 314 315 CAN_OSCILLATOR="8000000" 316 317Tested modules: 318 319* PiCAN2 (16 MHz crystal): <http://skpang.co.uk/catalog/pican2-canbus-board-for-raspberry-pi-23-p-1475.html> 320* WaveShare RS485 CAN HAT (8 MHz or 12 MHz crystal): <https://www.waveshare.com/rs485-can-hat.htm> 321* PiCAN2 Duo (16 MHz crystal): <http://skpang.co.uk/catalog/pican2-duo-canbus-board-for-raspberry-pi-23-p-1480.html> 322 323## Enable infrared 324 325Users who want to enable infrared support, for example for using LIRC (Linux 326Infrared Remote Control), have to explicitly set in local.conf: 327 328 ENABLE_IR = "1" 329 330This will add device tree overlays gpio-ir and gpio-ir-tx to config.txt. 331Appropriate kernel modules will be also included in the image. By default the 332GPIO pin for gpio-ir is set to 18 and the pin for gpio-ir-tx is 17. Both pins 333can be easily changed by modifying variables `GPIO_IR` and `GPIO_IR_TX`. 334 335## Enable gpio-shutdown 336 337When using device tree kernels, set this variable to enable gpio-shutdown: 338 339 ENABLE_GPIO_SHUTDOWN = "1" 340 341This will add the corresponding device tree overlay to config.txt and include 342the gpio-keys kernel module in the image. If System V init is used, additional 343mapping is applied to bind the button event to shutdown command. Systemd init 344should handle the event out of the box. 345 346By default the feature uses gpio pin 3 (except RPi 1 Model B rev 1 enumerates 347the pin as gpio 1). This conflicts with the I2C bus. If you set `ENABLE_I2C` 348to `1` or enabled `PiTFT` support, or otherwise want to use another pin, use 349`GPIO_SHUTDOWN_PIN` to assign another pin. Example using gpio pin 25: 350 351 GPIO_SHUTDOWN_PIN = "25" 352 353## Manual additions to config.txt 354 355The `RPI_EXTRA_CONFIG` variable can be used to manually add additional lines to 356the `config.txt` file if there is not a specific option above for the 357configuration you need. To add multiple lines you must include `\n` separators. 358If double-quotes are needed in the lines you are adding you can use single 359quotes around the whole string. 360 361For example, to add a comment containing a double-quote and a configuration 362option: 363 364 RPI_EXTRA_CONFIG = ' \n \ 365 # Raspberry Pi 7\" display/touch screen \n \ 366 lcd_rotate=2 \n \ 367 ' 368## Enable Raspberrypi Camera V2 369 370RaspberryPi does not have the unicam device ( RaspberryPi Camera ) enabled by default. 371Because this unicam device ( bcm2835-unicam ) as of now is used by libcamera opensource. 372So we have to explicitly set in local.conf. 373 374 RASPBERRYPI_CAMERA_V2 = "1" 375 376This will add the device tree overlays imx219 ( RaspberryPi Camera sensor V2 driver ) to config.txt. 377Also, this will enable adding Contiguous Memory Allocation value in the cmdline.txt. 378 379Ref.: 380* <https://github.com/raspberrypi/documentation/blob/master/linux/software/libcamera/README.md> 381* <https://www.raspberrypi.org/blog/an-open-source-camera-stack-for-raspberry-pi-using-libcamera/> 382 383## WM8960 soundcard support 384 385Support for WM8960 based sound cards such as the WM8960 Hi-Fi Sound Card HAT for Raspberry Pi from Waveshare, and ReSpeaker 2 / 4 / 6 Mics Pi HAT from Seeed Studio, can be enabled in `local.conf` 386 387 ```conf 388 MACHINE_FEATURES += "wm8960" 389 ``` 390 391You may need to adjust volume and toggle switches that are off by default 392 393 ```bash 394 amixer -c1 sset 'Headphone',0 80%,80% 395 amixer -c1 sset 'Speaker',0 80%,80% 396 amixer -c1 sset 'Left Input Mixer Boost' toggle 397 amixer -c1 sset 'Left Output Mixer PCM' toggle 398 amixer -c1 sset 'Right Input Mixer Boost' toggle 399 amixer -c1 sset 'Right Output Mixer PCM' toggle 400 ``` 401 402Audio capture on ReSpeaker 2 / 4 / 6 Mics Pi HAT from Seeed Studio is very noisy. 403 404## Support for RTC devices 405 406The RaspberryPi boards don't feature an RTC module and the machine 407configurations provided in this BSP layer have this assumption (until, if at 408all, some later boards will come with one). 409 410`rtc` is handled as a `MACHINE_FEATURES` in the context of the build system 411which means that if an attached device is provided for which support is needed, 412the recommended way forward is to write a new machine configuration based on an 413existing one. Check the documentation for 414`MACHINE_FEATURES_BACKFILL_CONSIDERED` for how this is disabled for the 415relevant machines. 416 417Even when `MACHINE_FEATURES` is tweaked to include the needed `rtc` string, 418make sure that your kernel configuration is supporting the attached device and 419the device tree is properly tweaked. Also, mind the runtime components that 420take advantage of your RTC device. You can do that by checking what is 421included/configured in the build system based on the inclusion of `rtc` in 422`MACHINE_FEATURES`. 423