docs/README-raspberrypi.md

   1 Raspberry Pi
   2 ================================================================================
   3
   4 Requirements:
   5
   6 Raspbian (other Linux distros may work as well).
   7
   8 ================================================================================
   9  Features
  10 ================================================================================
  11
  12 * Works without X11
  13 * Hardware accelerated OpenGL ES 2.x
  14 * Sound via ALSA
  15 * Input (mouse/keyboard/joystick) via EVDEV
  16 * Hotplugging of input devices via UDEV
  17
  18
  19 ================================================================================
  20  Raspbian Build Dependencies
  21 ================================================================================
  22
  23 sudo apt-get install libudev-dev libasound2-dev libdbus-1-dev
  24
  25 You also need the VideoCore binary stuff that ships in /opt/vc for EGL and
  26 OpenGL ES 2.x, it usually comes pre installed, but in any case:
  27
  28 sudo apt-get install libraspberrypi0 libraspberrypi-bin libraspberrypi-dev
  29
  30 ================================================================================
  31  Cross compiling from x86 Linux
  32 ================================================================================
  33
  34 To cross compile SDL for Raspbian from your desktop machine, you'll need a
  35 Raspbian system root and the cross compilation tools. We'll assume these tools
  36 will be placed in /opt/rpi-tools
  37
  38     sudo git clone --depth 1 https://github.com/raspberrypi/tools /opt/rpi-tools
  39
  40 You'll also need a Rasbian binary image.
  41 Get it from: http://downloads.raspberrypi.org/raspbian_latest
  42 After unzipping, you'll get file with a name like: <date>-wheezy-raspbian.img
  43 Let's assume the sysroot will be built in /opt/rpi-sysroot.
  44
  45     export SYSROOT=/opt/rpi-sysroot
  46     sudo kpartx -a -v <path_to_raspbian_image>.img
  47     sudo mount -o loop /dev/mapper/loop0p2 /mnt
  48     sudo cp -r /mnt $SYSROOT
  49     sudo apt-get install qemu binfmt-support qemu-user-static
  50     sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
  51     sudo mount --bind /dev $SYSROOT/dev
  52     sudo mount --bind /proc $SYSROOT/proc
  53     sudo mount --bind /sys $SYSROOT/sys
  54
  55 Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
  56 edit $SYSROOT/etc/ld.so.preload and comment out all lines in it.
  57
  58     sudo chroot $SYSROOT
  59     apt-get install libudev-dev libasound2-dev libdbus-1-dev libraspberrypi0 libraspberrypi-bin libraspberrypi-dev libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev libxxf86vm-dev libxss-dev
  60     exit
  61     sudo umount $SYSROOT/dev
  62     sudo umount $SYSROOT/proc
  63     sudo umount $SYSROOT/sys
  64     sudo umount /mnt
  65
  66 There's one more fix required, as the libdl.so symlink uses an absolute path
  67 which doesn't quite work in our setup.
  68
  69     sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
  70     sudo ln -s ../../../lib/arm-linux-gnueabihf/libdl.so.2 $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
  71
  72 The final step is compiling SDL itself.
  73
  74     export CC="/opt/rpi-tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-gcc --sysroot=$SYSROOT -I$SYSROOT/opt/vc/include -I$SYSROOT/usr/include -I$SYSROOT/opt/vc/include/interface/vcos/pthreads -I$SYSROOT/opt/vc/include/interface/vmcs_host/linux"
  75     cd <SDL SOURCE>
  76     mkdir -p build;cd build
  77     LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl2-installed --disable-pulseaudio --disable-esd
  78     make
  79     make install
  80
  81 To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
  82
  83     perl -w -pi -e "s#$PWD/rpi-sdl2-installed#/usr/local#g;" ./rpi-sdl2-installed/lib/libSDL2.la ./rpi-sdl2-installed/lib/pkgconfig/sdl2.pc ./rpi-sdl2-installed/bin/sdl2-config
  84
  85 ================================================================================
  86  Apps don't work or poor video/audio performance
  87 ================================================================================
  88
  89 If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to
  90 update the RPi's firmware. Note that doing so will fix these problems, but it
  91 will also render the CMA - Dynamic Memory Split functionality useless.
  92
  93 Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
  94 low in general, specially if a 1080p TV is hooked up.
  95
  96 See here how to configure this setting: http://elinux.org/RPiconfig
  97
  98 Using a fixed gpu_mem=128 is the best option (specially if you updated the
  99 firmware, using CMA probably won't work, at least it's the current case).
 100
 101 ================================================================================
 102  No input
 103 ================================================================================
 104
 105 Make sure you belong to the "input" group.
 106
 107     sudo usermod -aG input `whoami`
 108
 109 ================================================================================
 110  No HDMI Audio
 111 ================================================================================
 112
 113 If you notice that ALSA works but there's no audio over HDMI, try adding:
 114
 115     hdmi_drive=2
 116
 117 to your config.txt file and reboot.
 118
 119 Reference: http://www.raspberrypi.org/phpBB3/viewtopic.php?t=5062
 120
 121 ================================================================================
 122  Text Input API support
 123 ================================================================================
 124
 125 The Text Input API is supported, with translation of scan codes done via the
 126 kernel symbol tables. For this to work, SDL needs access to a valid console.
 127 If you notice there's no SDL_TEXTINPUT message being emitted, double check that
 128 your app has read access to one of the following:
 129
 130 * /proc/self/fd/0
 131 * /dev/tty
 132 * /dev/tty[0...6]
 133 * /dev/vc/0
 134 * /dev/console
 135
 136 This is usually not a problem if you run from the physical terminal (as opposed
 137 to running from a pseudo terminal, such as via SSH). If running from a PTS, a
 138 quick workaround is to run your app as root or add yourself to the tty group,
 139 then re login to the system.
 140
 141    sudo usermod -aG tty `whoami`
 142
 143 The keyboard layout used by SDL is the same as the one the kernel uses.
 144 To configure the layout on Raspbian:
 145
 146     sudo dpkg-reconfigure keyboard-configuration
 147
 148 To configure the locale, which controls which keys are interpreted as letters,
 149 this determining the CAPS LOCK behavior:
 150
 151     sudo dpkg-reconfigure locales
 152
 153 ================================================================================
 154  OpenGL problems
 155 ================================================================================
 156
 157 If you have desktop OpenGL headers installed at build time in your RPi or cross
 158 compilation environment, support for it will be built in. However, the chipset
 159 does not actually have support for it, which causes issues in certain SDL apps
 160 since the presence of OpenGL support supersedes the ES/ES2 variants.
 161 The workaround is to disable OpenGL at configuration time:
 162
 163     ./configure --disable-video-opengl
 164
 165 Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
 166 environment variable:
 167
 168     export SDL_RENDER_DRIVER=opengles2
 169
 170 ================================================================================
 171  Notes
 172 ================================================================================
 173
 174 * When launching apps remotely (via SSH), SDL can prevent local keystrokes from
 175   leaking into the console only if it has root privileges. Launching apps locally
 176   does not suffer from this issue.
 177
 178