docs/README-raspberrypi.md
author Ryan C. Gordon <icculus@icculus.org>
Mon, 29 Oct 2018 20:00:03 -0400
changeset 12369 68c87b40b434
parent 11992 08c415f14810
permissions -rw-r--r--
winmain: Don't use SDL_malloc (or SDL_stack_alloc, which might be malloc).

Otherwise, we are using the allocator before the app can set up its own hooks.

Now we use VirtualAlloc, and WideCharToMultiByte (because SDL_iconv uses
SDL_malloc, too!) to get ready to call into SDL_main.

This also makes console_wmain() call into the same routines as everything
else, so we don't have to deal with those allocations, too. Hopefully we
end up with the same results from GetCommandLine() as we do in wargv.

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