docs/README-raspberrypi.md
author Ryan C. Gordon <icculus@icculus.org>
Wed, 31 Oct 2018 15:03:41 -0400
changeset 12381 dc9108cd4340
parent 11992 08c415f14810
permissions -rw-r--r--
Merge SDL-ryan-batching-renderer branch to default.
     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 ================================================================================
    32  NEON
    33 ================================================================================
    34 
    35 If your Pi has NEON support, make sure you add -mfpu=neon to your CFLAGS so
    36 that SDL will select some otherwise-disabled highly-optimized code. The
    37 original Pi units don't have NEON, the Pi2 probably does, and the Pi3
    38 definitely does.
    39 
    40 ================================================================================
    41  Cross compiling from x86 Linux
    42 ================================================================================
    43 
    44 To cross compile SDL for Raspbian from your desktop machine, you'll need a
    45 Raspbian system root and the cross compilation tools. We'll assume these tools
    46 will be placed in /opt/rpi-tools
    47 
    48     sudo git clone --depth 1 https://github.com/raspberrypi/tools /opt/rpi-tools
    49 
    50 You'll also need a Raspbian binary image.
    51 Get it from: http://downloads.raspberrypi.org/raspbian_latest 
    52 After unzipping, you'll get file with a name like: "<date>-wheezy-raspbian.img"
    53 Let's assume the sysroot will be built in /opt/rpi-sysroot.
    54 
    55     export SYSROOT=/opt/rpi-sysroot
    56     sudo kpartx -a -v <path_to_raspbian_image>.img
    57     sudo mount -o loop /dev/mapper/loop0p2 /mnt
    58     sudo cp -r /mnt $SYSROOT
    59     sudo apt-get install qemu binfmt-support qemu-user-static
    60     sudo cp /usr/bin/qemu-arm-static $SYSROOT/usr/bin
    61     sudo mount --bind /dev $SYSROOT/dev
    62     sudo mount --bind /proc $SYSROOT/proc
    63     sudo mount --bind /sys $SYSROOT/sys
    64 
    65 Now, before chrooting into the ARM sysroot, you'll need to apply a workaround,
    66 edit $SYSROOT/etc/ld.so.preload and comment out all lines in it.
    67 
    68     sudo chroot $SYSROOT
    69     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
    70     exit
    71     sudo umount $SYSROOT/dev
    72     sudo umount $SYSROOT/proc
    73     sudo umount $SYSROOT/sys
    74     sudo umount /mnt
    75     
    76 There's one more fix required, as the libdl.so symlink uses an absolute path 
    77 which doesn't quite work in our setup.
    78 
    79     sudo rm -rf $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
    80     sudo ln -s ../../../lib/arm-linux-gnueabihf/libdl.so.2 $SYSROOT/usr/lib/arm-linux-gnueabihf/libdl.so
    81 
    82 The final step is compiling SDL itself.
    83 
    84     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"
    85     cd <SDL SOURCE>
    86     mkdir -p build;cd build
    87     LDFLAGS="-L$SYSROOT/opt/vc/lib" ../configure --with-sysroot=$SYSROOT --host=arm-raspberry-linux-gnueabihf --prefix=$PWD/rpi-sdl2-installed --disable-pulseaudio --disable-esd
    88     make
    89     make install
    90 
    91 To be able to deploy this to /usr/local in the Raspbian system you need to fix up a few paths:
    92     
    93     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
    94     
    95 ================================================================================
    96  Apps don't work or poor video/audio performance
    97 ================================================================================
    98 
    99 If you get sound problems, buffer underruns, etc, run "sudo rpi-update" to 
   100 update the RPi's firmware. Note that doing so will fix these problems, but it
   101 will also render the CMA - Dynamic Memory Split functionality useless.
   102 
   103 Also, by default the Raspbian distro configures the GPU RAM at 64MB, this is too
   104 low in general, specially if a 1080p TV is hooked up.
   105 
   106 See here how to configure this setting: http://elinux.org/RPiconfig
   107 
   108 Using a fixed gpu_mem=128 is the best option (specially if you updated the 
   109 firmware, using CMA probably won't work, at least it's the current case).
   110 
   111 ================================================================================
   112  No input
   113 ================================================================================
   114 
   115 Make sure you belong to the "input" group.
   116 
   117     sudo usermod -aG input `whoami`
   118 
   119 ================================================================================
   120  No HDMI Audio
   121 ================================================================================
   122 
   123 If you notice that ALSA works but there's no audio over HDMI, try adding:
   124     
   125     hdmi_drive=2
   126     
   127 to your config.txt file and reboot.
   128 
   129 Reference: http://www.raspberrypi.org/phpBB3/viewtopic.php?t=5062
   130 
   131 ================================================================================
   132  Text Input API support
   133 ================================================================================
   134 
   135 The Text Input API is supported, with translation of scan codes done via the
   136 kernel symbol tables. For this to work, SDL needs access to a valid console.
   137 If you notice there's no SDL_TEXTINPUT message being emitted, double check that
   138 your app has read access to one of the following:
   139     
   140 * /proc/self/fd/0
   141 * /dev/tty
   142 * /dev/tty[0...6]
   143 * /dev/vc/0
   144 * /dev/console
   145 
   146 This is usually not a problem if you run from the physical terminal (as opposed
   147 to running from a pseudo terminal, such as via SSH). If running from a PTS, a 
   148 quick workaround is to run your app as root or add yourself to the tty group,
   149 then re-login to the system.
   150 
   151     sudo usermod -aG tty `whoami`
   152     
   153 The keyboard layout used by SDL is the same as the one the kernel uses.
   154 To configure the layout on Raspbian:
   155     
   156     sudo dpkg-reconfigure keyboard-configuration
   157     
   158 To configure the locale, which controls which keys are interpreted as letters,
   159 this determining the CAPS LOCK behavior:
   160 
   161     sudo dpkg-reconfigure locales
   162 
   163 ================================================================================
   164  OpenGL problems
   165 ================================================================================
   166 
   167 If you have desktop OpenGL headers installed at build time in your RPi or cross 
   168 compilation environment, support for it will be built in. However, the chipset 
   169 does not actually have support for it, which causes issues in certain SDL apps 
   170 since the presence of OpenGL support supersedes the ES/ES2 variants.
   171 The workaround is to disable OpenGL at configuration time:
   172 
   173     ./configure --disable-video-opengl
   174 
   175 Or if the application uses the Render functions, you can use the SDL_RENDER_DRIVER
   176 environment variable:
   177 
   178     export SDL_RENDER_DRIVER=opengles2
   179 
   180 ================================================================================
   181  Notes
   182 ================================================================================
   183 
   184 * When launching apps remotely (via SSH), SDL can prevent local keystrokes from
   185   leaking into the console only if it has root privileges. Launching apps locally
   186   does not suffer from this issue.
   187   
   188