Quick links
===========
Git repository web frontend:
    http://git.yoctoproject.org/cgit/cgit.cgi/meta-raspberrypi/
Mailing list (yocto mailing list):
    yocto@yoctoproject.org
Issues management (redmine):
    http://redmine.gherzan.ro/projects/meta-raspberrypi
Change review (gerrit):
    https://review.gherzan.ro:8443/#/q/project:meta-raspberrypi


Contents:
=========
1. Description
2. Yocto BSP Layer - Raspberry Pi
    2.A. Compressed deployed files
    2.B. GPU memory
    2.C. Add purchased license codecs
    2.D. Disable overscan
    2.E. Set overclocking options
    2.F. Optional - Video camera support with V4L2 drivers
    2.G. Optional - Enable offline compositing support
    2.H. Images
    2.I. Boot to U-Boot
    2.J. Image with Initramfs
3. Extra apps
    3.A. omxplayer
4. Source code and mirrors
5. Contribution
    5.A. Mailing List
    5.B. Gerrit Review Server
    5.C. Redmine
6. Maintainers


1. Description
==============

This is the general hardware specific BSP overlay for the RaspberryPi device.

More information can be found at:
                   http://www.raspberrypi.org/ (Official Site)

The core BSP part of meta-raspberrypi should work with different
OpenEmbedded/Yocto distributions and layer stacks, such as:
* Distro-less (only with OE-Core).
* Angstrom.
* Yocto/Poky (main focus of testing).

2. Yocto BSP Layer - RaspberryPi
================================

This layer depends on:

URI: git://git.yoctoproject.org/poky
branch: master
revision: HEAD

URI: git://git.openembedded.org/meta-openembedded
layers: meta-multimedia
branch: master
revision: HEAD

How to use it:

1. source poky/oe-init-build-env rpi-build
2. Add needed layer to bblayers.conf:
    - meta-raspberrypi
3  Set MACHINE to raspberrypi in local.conf
4. bitbake rpi-hwup-image
5. dd to a SD card the generated sdimg file (use xzcat if rpi-sdimg.xz is used)
6. Boot your RPI.

2.A. Optional - compressed deployed files:
==========================================
1. Overwrite IMAGE_FSTYPES in local.conf
    IMAGE_FSTYPES = "tar.bz2 ext3.xz"
2. Overwrite SDIMG_ROOTFS_TYPE in local.conf
    SDIMG_ROOTFS_TYPE = "ext3.xz"
3. Overwrite SDIMG_COMPRESSION in local.conf
    SDIMG_COMPRESSION = "xz"
*Accommodate the values above to your own needs (ex: ext3 / ext4).

2.B. Optional - GPU memory:
===========================
Variable    : Details
GPU_MEM     : GPU memory in megabyte. Sets the memory split between the ARM and
              GPU. ARM gets the remaining memory. Min 16. Default 64.
GPU_MEM_256 : GPU memory in megabyte for the 256MB Raspberry Pi. Ignored by the
              512MB RP. Overrides gpu_mem. Max 192. Default not set.
GPU_MEM_512 : GPU memory in megabyte for the 512MB Raspberry Pi. Ignored by the
              256MB RP. Overrides gpu_mem. Max 448. Default not set.

2.C.Optional - Add purchased license codecs:
============================================
To add you own licenses use variables KEY_DECODE_MPG2 and KEY_DECODE_WVC1 in
local.conf. Example:
KEY_DECODE_MPG2 = "12345678"
KEY_DECODE_WVC1 = "12345678"
You can supply more licenses separated by comma. Example:
KEY_DECODE_WVC1 = "0x12345678,0xabcdabcd,0x87654321"

2.D. Optional - Disable overscan:
=================================
By default the GPU adds a black border around the video output to compensate for
TVs which cut off part of the image. To disable this set this variable in
local.conf:
DISABLE_OVERSCAN = "0"

2.E. Optional - Set overclocking options:
=========================================
The Raspberry PI can be overclocked. As of now overclocking up to the "Turbo
Mode" is officially supported by the raspbery and does not void warranty.
Check the config.txt for a detailed description of options and modes. Example:
# Turbo mode
ARM_FREQ = "1000"
CORE_FREQ = "500"
SDRAM_FREQ = "500"
OVER_VOLTAGE = "6"

2.F. Optional - Video camera support with V4L2 drivers
======================================================
Set this variable to enable support for the video camera (Linux 3.12.4+ required)
VIDEO_CAMERA = "1"

2.G. Optional - Enable offline compositing support
==================================================

Set this variable to enable support for dispmanx offline compositing
DISMANX_OFFLINE = "1"

This will enable the firmware to fall back to off-line compositing of
Dispmanx elements. Normally the compositing is done on-line, during scanout,
but cannot handle too many elements. With off-line enabled, an off-screen
buffer is allocated for compositing. When scene complexity (number and sizes
of elements) is high, compositing will happen off-line into the buffer.

Heavily recommended for Wayland/Weston.

See: http://wayland.freedesktop.org/raspberrypi.html

2.H. Images
===========
* rpi-hwup-image
    Hardware up image
* rpi-basic-image
    Based on rpi-hwup-image with some added features (ex: splash)
* rpi-test-image
    Image based on rpi-basic-image which includes most of the packages in this
    layer and some media samples.

2.I. Boot to U-Boot
===================
To have u-boot load kernel image, set in your local.conf
KERNEL_IMAGETYPE = "uImage"

This will make kernel.img be u-boot image which will load uImage.
By default, kernel.img is the actual kernel image (ex. Image).

2.J. Image with Initramfs
=========================
To build an initramfs image :
    * Set this 3 kernel variables (in linux-raspberrypi.inc for example)
        - kernel_configure_variable BLK_DEV_INITRD y
        - kernel_configure_variable INITRAMFS_SOURCE ""
        - kernel_configure_variable RD_GZIP y
    * Set the yocto variables (in linux-raspberrypi.inc for example)
        - INITRAMFS_IMAGE = "<a name for your initramfs image>"
        - INITRAMFS_IMAGE_BUNDLE = "1"
    * Set the meta-rasberrypi variable (in raspberrypi.conf for example)
        - KERNEL_INITRAMFS = "-initramfs"

3. Extra apps
=============

3.A. omxplayer
==============
omxplayer depends on libav which has a commercial license. So in order to be
able to compile omxplayer you will need to whiteflag the commercial license
adding to you local.conf:
LICENSE_FLAGS_WHITELIST = "commercial"


4. Source code and mirrors
==========================

Main repo:
    git://git.yoctoproject.org/meta-raspberrypi
    http://git.yoctoproject.org/git/meta-raspberrypi

Github mirror:
    https://github.com/djwillis/meta-raspberrypi

Gerrit review repo:
    https://review.gherzan.ro:8443/meta-raspberrypi


5. Contributing
===============

5.A. Mailing list
=================
The main communication tool we use is a mailing list:
    yocto@yoctoproject.org
    https://lists.yoctoproject.org/listinfo/yocto

Feel free to ask any kind of questions but always prepend your email subject
with "[meta-raspberrypi]". This is because we use the 'yocto' mailing list and
not a perticular 'meta-raspberrypi' mailing list.

To contribute to this layer you should send the patches for review to the
above specified mailing list.
The patches should be compliant with the openembedded patch guidelines:
http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines

To send changes to mailing list use something like:
    git send-email --to yocto@yoctoproject.org \
    --subject-prefix='meta-raspberrypi][PATCH'

OPTIONALLY push changes to gerrit (help maintainers merge and review patches
easier in this way).
    git push ssh://<username>@review.gherzan.ro:29418/meta-raspberrypi
    <local-branch>:refs/for/master
    See 5.B. Gerrit Review Server.

5.B. Gerrit Review Server
=========================
We have a gerrit server configured at review.gherzan.ro. Changes made in gerrit
are merged in git.yoctoproject.org/meta-raspberrypi.

You can setup a gerrit account in less than 2 minutes:
A) Login / Register on https://review.gherzan.ro:8443.
B) Add your PUBLIC key in Settings/SSH Public Keys.
C) Add remote in your local repo:
    git remote add gherzan ssh://<username>@review.gherzan.ro:29418/meta-raspberrypi
D) Push changes to gerrit using:
    git push gherzan <local-branch>:refs/for/master

Please check your spam folder for gerrit messages. Sometimes they end up there.

5.C. Redmine
============
In order to manage and trace the meta-raspberrypi issues, we use redmine:
    http://redmine.gherzan.ro/projects/meta-raspberrypi

Here we report, trace and develop bugs, features or support tickets for this
yocto BSP later.

If you push patches which have a remine issue associated, please provide the
issue number in the commit log just before "Signed-off-by" line(s). Example line
for a bug:
    [Bug #13]


6. Maintainers
==============

    Andrei Gherzan <andrei at gherzan.ro>