blob: bfc3e2ed11c3999efc0b2323860e799bfe3816d3 [file] [log] [blame]
Patrick Williams8b8bc412016-08-17 15:02:23 -05001Quick links
2===========
3Git repository web frontend:
4 http://git.yoctoproject.org/cgit/cgit.cgi/meta-raspberrypi/
5Mailing list (yocto mailing list):
6 yocto@yoctoproject.org
Patrick Williamsb2e6a9b2017-02-23 20:31:26 -06007Issues management (Github Issues):
8 https://github.com/agherzan/meta-raspberrypi/issues
Patrick Williams8b8bc412016-08-17 15:02:23 -05009
10
11Contents:
12=========
131. Description
142. Yocto BSP Layer - Raspberry Pi
15 2.A. How to use it
16 2.B. Images
173. Optional build configuration
18 3.A. Compressed deployed files
19 3.B. GPU memory
20 3.C. Add purchased license codecs
21 3.D. Disable overscan
22 3.E. Set overclocking options
23 3.F. Video camera support with V4L2 drivers
24 3.G. Enable offline compositing support
25 3.H. Enable kgdb over console support
26 3.I. Boot to U-Boot
27 3.J. Image with Initramfs
28 3.K. Device tree support
29 3.L. Enable SPI bus
30 3.M. Enable I2C
31 3.N. Enable PiTFT support
32 3.O. Enable UART support
334. Extra apps
34 4.A. omxplayer
355. Board Configuration
36 5.A. Audio Routing
376. Source code and mirrors
387. Contribution
39 7.A. Mailing List
Patrick Williamsb2e6a9b2017-02-23 20:31:26 -060040 7.B. Github Issues
Patrick Williams8b8bc412016-08-17 15:02:23 -0500418. Maintainers
42
43
441. Description
45==============
46
47This is the general hardware specific BSP overlay for the RaspberryPi device.
48
49More information can be found at:
50 http://www.raspberrypi.org/ (Official Site)
51
52The core BSP part of meta-raspberrypi should work with different
53OpenEmbedded/Yocto distributions and layer stacks, such as:
54* Distro-less (only with OE-Core).
55* Angstrom.
56* Yocto/Poky (main focus of testing).
57
582. Yocto BSP Layer - RaspberryPi
59================================
60
61This layer depends on:
62
63URI: git://git.yoctoproject.org/poky
64branch: master
65revision: HEAD
66
67URI: git://git.openembedded.org/meta-openembedded
Brad Bishop3a5fbf52017-12-04 02:17:07 -050068layers: meta-oe, meta-multimedia, meta-networking, meta-python
Patrick Williams8b8bc412016-08-17 15:02:23 -050069branch: master
70revision: HEAD
71
722.A. How to use it
73==================
74a. source poky/oe-init-build-env rpi-build
75b. Add needed layer to bblayers.conf:
76 - meta-raspberrypi
77c. Set MACHINE in local.conf to one of the supported boards:
78 - raspberrypi
79 - raspberrypi0
Brad Bishop3a5fbf52017-12-04 02:17:07 -050080 - raspberrypi0-wifi
Patrick Williams8b8bc412016-08-17 15:02:23 -050081 - raspberrypi2
82 - raspberrypi3
Patrick Williamsb2e6a9b2017-02-23 20:31:26 -060083 - raspberrypi-cm (dummy alias for raspberrypi)
84 - raspberrypi-cm3 (dummy alias for raspberrypi2)
Patrick Williams8b8bc412016-08-17 15:02:23 -050085d. bitbake rpi-hwup-image
86e. dd to a SD card the generated sdimg file (use xzcat if rpi-sdimg.xz is used)
87f. Boot your RPI.
88
892.B. Images
90-===========
91* rpi-hwup-image
92 Hardware up image
93* rpi-basic-image
94 Based on rpi-hwup-image with some added features (ex: splash)
95* rpi-test-image
96 Image based on rpi-basic-image which includes most of the packages in this
97 layer and some media samples.
98
993. Optional build configuration
100===============================
101
102There are a set of ways in which a user can influence different paramenters of the build.
103We list here the ones that are closely related to this BSP or specific to it. For the rest
104please check: http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html
105
1063.A. Compressed deployed files
107==============================
1081. Overwrite IMAGE_FSTYPES in local.conf
109 IMAGE_FSTYPES = "tar.bz2 ext3.xz"
1102. Overwrite SDIMG_ROOTFS_TYPE in local.conf
111 SDIMG_ROOTFS_TYPE = "ext3.xz"
1123. Overwrite SDIMG_COMPRESSION in local.conf
113 SDIMG_COMPRESSION = "xz"
114*Accommodate the values above to your own needs (ex: ext3 / ext4).
115
1163.B. GPU memory
117===============
118Variable : Details
119GPU_MEM : GPU memory in megabyte. Sets the memory split between the ARM and
120 GPU. ARM gets the remaining memory. Min 16. Default 64.
121GPU_MEM_256 : GPU memory in megabyte for the 256MB Raspberry Pi. Ignored by the
122 512MB RP. Overrides gpu_mem. Max 192. Default not set.
123GPU_MEM_512 : GPU memory in megabyte for the 512MB Raspberry Pi. Ignored by the
124 256MB RP. Overrides gpu_mem. Max 448. Default not set.
125GPU_MEM_1024: GPU memory in megabyte for the 1024MB Raspberry Pi. Ignored by the
126 256MB/512MB RP. Overrides gpu_mem. Max 944. Default not set.
127
1283.C. Add purchased license codecs
129=================================
130To add you own licenses use variables KEY_DECODE_MPG2 and KEY_DECODE_WVC1 in
131local.conf. Example:
132KEY_DECODE_MPG2 = "12345678"
133KEY_DECODE_WVC1 = "12345678"
134You can supply more licenses separated by comma. Example:
135KEY_DECODE_WVC1 = "0x12345678,0xabcdabcd,0x87654321"
136
1373.D. Disable overscan
138=====================
139By default the GPU adds a black border around the video output to compensate for
140TVs which cut off part of the image. To disable this set this variable in
141local.conf:
142DISABLE_OVERSCAN = "1"
143
1443.E. Set overclocking options
145=============================
146The Raspberry PI can be overclocked. As of now overclocking up to the "Turbo
147Mode" is officially supported by the raspbery and does not void warranty.
148Check the config.txt for a detailed description of options and modes. Example:
149# Turbo mode
150ARM_FREQ = "1000"
151CORE_FREQ = "500"
152SDRAM_FREQ = "500"
153OVER_VOLTAGE = "6"
154
1553.F. Video camera support with V4L2 drivers
156===========================================
157Set this variable to enable support for the video camera (Linux 3.12.4+ required)
158VIDEO_CAMERA = "1"
159
1603.G. Enable offline compositing support
161=======================================
162Set this variable to enable support for dispmanx offline compositing
Patrick Williamsb2e6a9b2017-02-23 20:31:26 -0600163DISPMANX_OFFLINE = "1"
Patrick Williams8b8bc412016-08-17 15:02:23 -0500164
165This will enable the firmware to fall back to off-line compositing of
166Dispmanx elements. Normally the compositing is done on-line, during scanout,
167but cannot handle too many elements. With off-line enabled, an off-screen
168buffer is allocated for compositing. When scene complexity (number and sizes
169of elements) is high, compositing will happen off-line into the buffer.
170
171Heavily recommended for Wayland/Weston.
172
173See: http://wayland.freedesktop.org/raspberrypi.html
174
1753.H. Enable kgdb over console support
176=====================================
177To add the kdbg over console (kgdboc) parameter to the kernel command line,
178set this variable in local.conf:
179ENABLE_KGDB = "1"
180
1813.I. Boot to U-Boot
182===================
183To have u-boot load kernel image, set in your local.conf
184KERNEL_IMAGETYPE = "uImage"
185
186This will make kernel.img be u-boot image which will load uImage.
187By default, kernel.img is the actual kernel image (ex. Image).
188
1893.J. Image with Initramfs
190=========================
191To build an initramfs image :
192 * Set this 3 kernel variables (in linux-raspberrypi.inc for example)
193 - kernel_configure_variable BLK_DEV_INITRD y
194 - kernel_configure_variable INITRAMFS_SOURCE ""
195 - kernel_configure_variable RD_GZIP y
196 * Set the yocto variables (in linux-raspberrypi.inc for example)
197 - INITRAMFS_IMAGE = "<a name for your initramfs image>"
198 - INITRAMFS_IMAGE_BUNDLE = "1"
199 * Set the meta-rasberrypi variable (in raspberrypi.conf for example)
200 - KERNEL_INITRAMFS = "-initramfs"
201
2023.K. Device tree support
203=========================
204Device tree for RPi is only supported when using linux-raspberrypi 3.18+
205kernels.
206
207 * Set KERNEL_DEVICETREE (in conf/machine/raspberrypi.conf)
208 - the trailer is added to the kernel image before kernel install task.
209 While creating the SDCard image, this modified kernel is put on
210 boot partition (as kernel.img) as well as DeviceTree blobs (.dtb files).
211
212NOTE: KERNEL_DEVICETREE is default enabled for kernel >= 3.18 and always disabled for
213 older kernel versions.
214
2153.L. Enable SPI bus
216====================
217When using device tree kernels, set this variable to enable the SPI bus
218ENABLE_SPI_BUS = "1"
219
2203.M. Enable I2C
221===============
222When using device tree kernels, set this variable to enable I2C
223ENABLE_I2C = "1"
224
2253.N. Enable PiTFT support
226=========================
227Basic support for using PiTFT screens can be enabled by adding
228below in local.conf:
229
230MACHINE_FEATURES += "pitft"
231 - This will enable SPI bus and i2c device-trees, it will also setup
232 framebuffer for console and x server on PiTFT.
233
234NOTE: To get this working the overlay for the PiTFT model must be build,
235 added and specified as well (dtoverlay=<driver> in config.txt)
236
237Below is a list of currently supported PiTFT models in meta-raspberrypi,
238the modelname should be added as a MACHINE_FEATURES in local.conf like below:
239 - MACHINE_FEATURES += "pitft <modelname>"
240
241List of currently supported models:
242 - pitft22
243 - pitft28r
244
2453.O. Enable UART
246===============
Brad Bishop3a5fbf52017-12-04 02:17:07 -0500247RaspberryPi 0, 1, 2 and CM will have UART console enabled by default.
Patrick Williams8b8bc412016-08-17 15:02:23 -0500248
Brad Bishop3a5fbf52017-12-04 02:17:07 -0500249RaspberryPi 0 WiFi and 3 does not have the UART enabled by default because this
250needs a fixed core frequency and enable_uart wil set it to the minimum. Certain
Patrick Williams8b8bc412016-08-17 15:02:23 -0500251operations - 60fps h264 decode, high quality deinterlace - which aren't
252performed on the ARM may be affected, and we wouldn't want to do that to users
253who don't want to use the serial port. Users who want serial console support on
254RaspberryPi3 will have to explicitely set in local.conf: ENABLE_UART = "1".
255
256Ref.: https://github.com/raspberrypi/firmware/issues/553
257 https://github.com/RPi-Distro/repo/issues/22
258
2594. Extra apps
260=============
261
2624.A. omxplayer
263==============
264omxplayer depends on libav which has a commercial license. So in order to be
265able to compile omxplayer you will need to whiteflag the commercial license
266adding to you local.conf:
267LICENSE_FLAGS_WHITELIST = "commercial"
268
2695. Board Configuration
270======================
271
2725.A. Audio Routing
273==================
274To load audio driver
275
276 modprobe snd-bcm2835
277
278To test audio playback
279
280 e.g. aplay test.wav
281
282Note that without HDMI connected this emits audio from the 3.5in jack connector
283as expected. However With an HDMI display connected there is no audio output from
284the jack connector.
285
286To force the audio routing via the 3.5in jack connector use
287
288 amixer cset numid=3 1
289
290Options to amixer cset are:
291
292 0=auto
293 1=headphones
294 2=hdmi
295
2966. Source code and mirrors
297==========================
298
299Main repo:
300 git://git.yoctoproject.org/meta-raspberrypi
301 http://git.yoctoproject.org/git/meta-raspberrypi
302
303Github mirror:
304 https://github.com/agherzan/meta-raspberrypi
305
306Bitbucket mirror:
307 https://bitbucket.org/agherzan/meta-raspberrypi
308
309
3107. Contributing
311===============
312
3137.A. Mailing list
314=================
315The main communication tool we use is a mailing list:
316 yocto@yoctoproject.org
317 https://lists.yoctoproject.org/listinfo/yocto
318
319Feel free to ask any kind of questions but always prepend your email subject
320with "[meta-raspberrypi]". This is because we use the 'yocto' mailing list and
321not a perticular 'meta-raspberrypi' mailing list.
322
Brad Bishop3a5fbf52017-12-04 02:17:07 -05003237.B. Patches and pull requests
324==============================
Patrick Williams8b8bc412016-08-17 15:02:23 -0500325
Brad Bishop3a5fbf52017-12-04 02:17:07 -0500326To contribute to this project you should send pull requests to the github mirror
327(<https://github.com/agherzan/meta-raspberrypi>). **Additionally** you can send
328the patches for review to the above specified mailing list.
Patrick Williams8b8bc412016-08-17 15:02:23 -0500329
330When creating patches, please use something like:
331
332 git format-patch -s --subject-prefix='meta-raspberrypi][PATCH' origin
333
334When sending patches to mailing list, please use something like:
335
336 git send-email --to yocto@yoctoproject.org <generated patch>
337
Brad Bishop3a5fbf52017-12-04 02:17:07 -05003387.C. Github issues
Patrick Williams8b8bc412016-08-17 15:02:23 -0500339==================
340In order to manage and trace the meta-raspberrypi issues, we use github issues:
341 https://github.com/agherzan/meta-raspberrypi/issues
342
343If you push patches which have a github issue associated, please provide the
344issue number in the commit log just before "Signed-off-by" line(s). Example line
345for a bug:
346 [Issue #13]
347
348
3498. Maintainers
350==============
351
352 Andrei Gherzan <andrei at gherzan.ro>