Tutorial  Updated

How to boot Linux on your Switch

THIS GUIDE IS DEPRECATED
THIS IS BETTER https://github.com/natinusala/painless-linux


I've successfully booted ArchLinux using ShofEL2. Here is a quick guide on how to do it - I'll assume you're computer literate and know how to use a terminal / Linux commands / git.
Everything is taken from the README of the ShofEL2 repo so if you want to go even faster, go read that instead.

Thanks to NightHammer1000 and Y2K-x for the help !

There is a simplified and faster version of this tutorial available here, with precompiled binaries so you don't have to build everything : https://github.com/SoulCipher/shofel2_linux

The result

Without a SD card ("waiting for root device mmcblk0p2") : https://photos.app.goo.gl/7y6ut5ObuHMUIMZg2
Stock Arch Linux : https://photos.app.goo.gl/yALqe3zMZRe2dSQf1
Arch Linux with LXDE : https://photos.app.goo.gl/xaEgRqeSi8jvAwpz5
RetroArch running : https://photos.app.goo.gl/vBLPo5wiBto1qiUH3
Arch Linux with GNOME : https://gbatemp.net/attachments/img_0005-jpg.121608/
Arch Linux with KDE : https://gbatemp.net/attachments/img_20180427_121605-jpg.121666/

What works / what doesn't
  • Desktop environment : Gnome, LXDE, KDE
  • Wi-Fi : works
    • You will need to reboot your Switch and run the exploit again to make the Wi-Fi work (it never works on the first boot)
    • Then enter the Network Manager Application and add your network from there
    • If it doesn't work, you will need to edit the configuration on the host computer (see the additional notes at the end of this post)
    • With LXDE : Can cause a kernel panic if used at the same time as Bluetooth
  • Bluetooth : works but Joy-Cons can't be paired
  • Touch screen : works, although LXDE is not very touch-friendly
  • Audio : doesn't work yet
  • GPU acceleration : works (via mesa), with OpenGL (and maybe Vulkan too ?)
  • Joy-Cons : not recognized
  • Volume buttons : working with Gnome but not doing anything since there is no audio device
  • Power button : doesn't do anything, no sleep mode, no graceful shutdown
  • USB : doesn't work
  • Dock : not tested yet, but I bet it doesn't do anything besides charging the battery
  • Power management / battery level : working with Gnome
What you'll need
  • A computer running Linux with a blue USB SuperSpeed port, or a Mac
    • A Linux VM can work in theory, but it depends on how the USB passthrough is implemented (apparently VMWare works, VirtualBox doesn't)
  • A USB A-to-C cable (with data support, obviously)
    • be careful as cheap cables were reported to work randomly / not work at all
  • Some time (you know, Linux is kinda large)

Prep work

First, you'll need to install the required toolchains. Open this link and download the tar.gz binaries for
  • aarch64-linux-gnu
  • arm-linux-gnueabi
Be careful to choose the right architecture for your PC (for me it was x86_64 so "gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi.tar.xz").

Once you have them, extract them somewhere nice and add the "bin" (not "lib" as I previously stated) folder of both toolchains to your PATH ("$ export PATH=$PATH:/path/to/toolchain1/lib:/path/to/toolchain2/lib"). The building process won't work otherwise.

Then, install those dependencies (how to install them and their name might depend on your distribution) :
  • build-essential (sorry I didn't add it it was obvious to me)
  • libssl-dev
  • swig
  • bison
  • pkg-config
  • flex
  • zlib1g-dev
  • python3
  • python-dev
  • python3-pip
  • pyusb 1.0.0 : "$ sudo pip3 install pyusb==1.0.0"
  • libusb-1.0-0-dev

Compiling

Clone each required repository :

Code:
$ git clone https://github.com/fail0verflow/shofel2.git
$ git clone --recursive --depth=1 https://github.com/fail0verflow/switch-coreboot.git coreboot
$ git clone https://github.com/fail0verflow/switch-u-boot.git u-boot
$ git clone --depth=1 https://github.com/fail0verflow/switch-linux.git linux
$ git clone https://github.com/boundarydevices/imx_usb_loader.git

You can grab a coffee or two because Linux has more than 5 million files to download.

Then, build everything :

Code:
$ cd shofel2/exploit
$ make

Code:
$ cd u-boot
$ export CROSS_COMPILE=aarch64-linux-gnu-
$ make nintendo-switch_defconfig
$ make

Code:
$ cd coreboot
$ make nintendo_switch_defconfig
$ make iasl
$ make

If you have a tegra_mtc.bin file error, you'll have to extract it from a Pixel C stock image :
"$ ./build/util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin"

Or you can download it directly from here : https://0w0.st/tegra_mtc.bin (thanks to @CptPotato for uploading this)

You'll have to put it in the "coreboot/src/soc/nvidia/tegra210" directory.

Code:
$ cd imx_usb_loader
$ git reset --hard 0a322b01cacf03e3be727e3e4c3d46d69f2e343e
$ make

The big one :

Code:
$ cd linux
$ export ARCH=arm64
$ export CROSS_COMPILE=aarch64-linux-gnu-
$ make nintendo-switch_defconfig
$ make

If you encounter issues about a missing rule "/lib/firmware/nvidia/tegra210/vic04_ucode.bin" for the target "firmware" you'll have to :
  • install the firmware-misc-nonfree package
  • if you can't install it, or if it still doesn't work, download the package manually from debian sid and extract the file "/lib/firmware/nvidia/tegra210/vic04_ucode.bin" (from the root of your PC, not on the cloned repo) from the DEB (and chmod it if needed)
If you encounter issues about a missing rule "/lib/firmware/brcm/brcmfmac4356-pcie.txt", download this file and put it in "/lib/firmware/brcm/" (from the root of your PC, not on the cloned repo)

Building the rootfs

This is the annoying part. Download the archive / image corresponding to the distribution you want to use :
If it's a tarball you just downloaded

While it's downloading, you'll have to take a microSD card and, using the software of your choice (I used GParted) :
  • remove every existing partition to only have unallocated space on it (do I need to tell you that you're going to loose everything on the card ?)
  • create a tiny FAT32 partition (I chose 200mb but it doesn't matter) - that'll be mmcbkl0p1, you can label it "garbage"
  • create an ext4 partition on the remaining part of the card - that'll be mmcblk0p2, you can label it "rootfs"
  • it's important that the FAT32 partition comes first and the ext4 one comes after - on the Switch, Linux will look for mmcblk0p2, the second partition, if you have scrolling boot logs and then back to RCM it means you did it wrong
Once the rootfs tarball is downloaded, you can simple extract it to the mounting point of the ext4 partition you just created :

Code:
$ tar xvf ArchLinuxARM-aarch64-latest.tar.gz -C /mounting/point/of/ext4/partition && sync
$ cp ArchLinuxARM-aarch64-latest.tar.gz /mounting/point/of/ext4/partition/root && sync

("/mounting/point/of/ext4/partition/root" is the "root" directory on the partition)

Don't forget to properly eject the SD Card !

If "tar xvf" doesn't work for you you can install "bsdtar" and use "bsdtar -xpf" instead

Then you can put the SD card in the console.

If it's a img / bin file you just downloaded

You can simply write it on your SD card using :
  • If you're on Windows, Ether or Win32DiskImager
  • If you're on Linux / Mac OS : "sudo dd if=yourimage.img of=/dev/sdX && sync" where /dev/sdX is the device of your SD card (unmounted)
You will probably want to open a partition manager to resize the ext4 partition once it's flashed, so that it fits your SD card.

Then you can put the SD card in the console.

Booting linux

Run the exploit :

Code:
$ cd shofel2/exploit
$ sudo ./shofel2.py cbfs.bin ../../coreboot/build/coreboot.rom

Your terminal should now be waiting for the Switch to enter RCM mode.

To do so : (I don't have pictures but that's the same method as fusée gelée, just look at some video tutorials)
  • plug the Switch on your PC using the USB A-to-C cable - use a blue SuperSpeed port if you have one
  • shut it down
  • remove the right joy-con
  • using a method of your choice, short the 10th pin of the right joy-con (the last pin on the right, away from the screen, closer to the back) with the ground : that can be pin 1, 2 or 7, that can also be a screw on the joy-con rack or the console's fan - I personnaly stick a RPi jumper wire in the fan and touch the 10th pin on the other side, works everytime (like this)
  • keep the pins shorted and power the Switch while pressing the volume UP button
If it worked, the console will show a black screen and you'll see the exploit running on your terminal. If you see the Nintendo logo, it has failed. You can power off the console and try again.

Then, run those last commands :

Code:
$ cd shofel2/usb_loader
$ ../../u-boot/tools/mkimage -A arm64 -T script -C none -n "boot.scr" -d switch.scr switch.scr.img
$ sudo ../../imx_usb_loader/imx_usb -c .

Linux should then boot on your console - first the boot logs with the penguins, and then an ArchLinux login prompt. Voilà !
Again, if you have the boot logs and then a black screen, it means you did the SD card part wrong.

Additional notes

Hardware graphics acceleration


The most recents image already contain this fix.

To add mesa drivers install this package using pacman :
https://0w0.st/mesa-full-tegra-r101876.bf5e0276b6-1-aarch64.pkg.tar.xz

You will need a working internet connection to do so.

Then, use this script to choose your power profile : https://0w0.st/power.sh

Full speed RAM


According to the blog post ("Linux on Switch boot chain" section), you need to extract a file from a Pixel C factory image in order to have the RAM working at full speed. I didn't do it so I won't cover it here.

Fixing calibration issues of the touch screen (thanks to @Wizardy)

To fix calibration issues of the touch screen, edit the file /usr/share/X11/xorg.conf.d/10-evdev.confg (of the rootfs)

And change the InputClass section to :

Code:
Section "InputClass"
        Identifier "evdev touchscreen catchall"
        MatchIsTouchscreen "on"
        MatchDevicePath "/dev/input/event*"
        Driver "evdev"
        Option "InvertX" "no"
        Option "InvertY" "yes"
        Option "SwapAxes" "yes"
        Option "Calibration" "0 1279 0 719"
EndSection

Wi-Fi

To setup Wi-Fi, mount the rootfs partition on your host PC and edit the configuration for your network in the file "/etc/NetworkManager/system-connections" (if it doesn't exist, take Gigaspot).

To have a working Wi-Fi you must reboot your Switch and run the exploit again each time you power it off

Moving the rootfs to another partition

If you want to move the rootfs to another partition on your SD card, edit the "shofel2/usb_loader/switch.scr" file and replace "/dev/mmcblk0p2" by the partition you want to use.
 
Last edited by natinusala,

00Cancer

Well-Known Member
Newcomer
Joined
Feb 1, 2017
Messages
67
Trophies
0
Age
20
XP
103
Country
United States
How is your Gnome image running ? Is it any good ? I'll add your link, just let me know if you update it (to remove the subfolder for example :D)

I'll also add a link to the Ubuntu Builder.
Yeah, my gnome image works fine, but I just need to get rid of the subfolders. I'll have the new link in an hour or so, uploading 2 gb takes an hour for me. Actually if anyone has a faster upload speed (> 5mbps) and is willing to delete subfolders and upload it, that be pretty cool.

--------------------- MERGED ---------------------------

i tried to run the gnome image. when it gets to the alarm login tty, it just loops that and can't get into the GUI
Can you chroot into it and post the contents of your /etc/slim.conf file?
 

Rainbowfied Pokemaster

Well-Known Member
Newcomer
Joined
Jun 28, 2016
Messages
47
Trophies
0
XP
191
Country
United States
I can't extract tegra_mtc.bin, it seems to be a problem with cbfstool or my installation:

Code:
./build/util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin
bash: ./build/util/cbfstool/cbfstool: No such file or directory

When ran with sudo:

Code:
sudo ./build/util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin
sudo: ./build/util/cbfstool/cbfstool: command not found
 

benjy3gg

Member
Newcomer
Joined
Apr 25, 2018
Messages
6
Trophies
0
Age
33
XP
423
Country
Germany
Yeah, my gnome image works fine, but I just need to get rid of the subfolders. I'll have the new link in an hour or so, uploading 2 gb takes an hour for me. Actually if anyone has a faster upload speed (> 5mbps) and is willing to delete subfolders and upload it, that be pretty cool.

--------------------- MERGED ---------------------------


Can you chroot into it and post the contents of your /etc/slim.conf file?

Code:
# Path, X server and arguments (if needed)
# Note: -xauth $authfile is automatically appended
default_path        /usr/local/bin:/usr/local/sbin:/usr/bin
default_xserver     /usr/bin/X
xserver_arguments -nolisten tcp vt07

# Commands for halt, login, etc.
halt_cmd            /sbin/shutdown -h now
reboot_cmd          /sbin/shutdown -r now
console_cmd         /usr/bin/xterm -C -fg white -bg black +sb -T "Console login" -e /bin/sh -c "/bin/cat /etc/issue; exec /bin/login"
#suspend_cmd        /usr/sbin/suspend

# Full path to the xauth binary
xauth_path         /usr/bin/xauth

# Xauth file for server
authfile           /var/run/slim.auth


# Activate numlock when slim starts. Valid values: on|off
# numlock             on

# Hide the mouse cursor (note: does not work with some WMs).
# Valid values: true|false
# hidecursor          false

# This command is executed after a succesful login.
# you can place the %session and %theme variables
# to handle launching of specific commands in .xinitrc
# depending of chosen session and slim theme
#
# NOTE: if your system does not have bash you need
# to adjust the command according to your preferred shell,
# i.e. for freebsd use:
# login_cmd           exec /bin/sh - ~/.xinitrc %session
login_cmd           exec /bin/bash -login ~/.xinitrc %session

# Commands executed when starting and exiting a session.
# They can be used for registering a X11 session with
# sessreg. You can use the %user variable
#
# sessionstart_cmd    some command
# sessionstop_cmd    some command

# Start in daemon mode. Valid values: yes | no
# Note that this can be overriden by the command line
# options "-d" and "-nodaemon"
# daemon    yes

# Set directory that contains the xsessions.
# slim reads xsesion from this directory, and be able to select.
sessiondir            /usr/share/xsessions/

# Executed when pressing F11 (requires imagemagick)
screenshot_cmd      import -window root /slim.png

# welcome message. Available variables: %host, %domain
welcome_msg         Welcome to %host

# Session message. Prepended to the session name when pressing F1
# session_msg         Session:

# shutdown / reboot messages
shutdown_msg       The system is halting...
reboot_msg         The system is rebooting...

# default user, leave blank or remove this line
# for avoid pre-loading the username.
default_user        alarm

# Focus the password field on start when default_user is set
# Set to "yes" to enable this feature
#focus_password      no

# Automatically login the default user (without entering
# the password. Set to "yes" to enable this feature
auto_login          yes


# current theme, use comma separated list to specify a set to
# randomly choose from
current_theme       default

# Lock file
lockfile            /var/lock/slim.lock

# Log file
logfile             /var/log/slim.log
 

00Cancer

Well-Known Member
Newcomer
Joined
Feb 1, 2017
Messages
67
Trophies
0
Age
20
XP
103
Country
United States
I can't extract tegra_mtc.bin, it seems to be a problem with cbfstool or my installation:

Code:
./build/util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin
bash: ./build/util/cbfstool/cbfstool: No such file or directory

When ran with sudo:

Code:
sudo ./build/util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin
sudo: ./build/util/cbfstool/cbfstool: command not found
cd into coreboot/util/cbfstool, run make, cd back to the coreboot, then run this command:
./util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin
make sure your downloaded bootloader-dragon-google... it is the coreboot folder

--------------------- MERGED ---------------------------

Code:
# Path, X server and arguments (if needed)
# Note: -xauth $authfile is automatically appended
default_path        /usr/local/bin:/usr/local/sbin:/usr/bin
default_xserver     /usr/bin/X
xserver_arguments -nolisten tcp vt07

# Commands for halt, login, etc.
halt_cmd            /sbin/shutdown -h now
reboot_cmd          /sbin/shutdown -r now
console_cmd         /usr/bin/xterm -C -fg white -bg black +sb -T "Console login" -e /bin/sh -c "/bin/cat /etc/issue; exec /bin/login"
#suspend_cmd        /usr/sbin/suspend

# Full path to the xauth binary
xauth_path         /usr/bin/xauth

# Xauth file for server
authfile           /var/run/slim.auth


# Activate numlock when slim starts. Valid values: on|off
# numlock             on

# Hide the mouse cursor (note: does not work with some WMs).
# Valid values: true|false
# hidecursor          false

# This command is executed after a succesful login.
# you can place the %session and %theme variables
# to handle launching of specific commands in .xinitrc
# depending of chosen session and slim theme
#
# NOTE: if your system does not have bash you need
# to adjust the command according to your preferred shell,
# i.e. for freebsd use:
# login_cmd           exec /bin/sh - ~/.xinitrc %session
login_cmd           exec /bin/bash -login ~/.xinitrc %session

# Commands executed when starting and exiting a session.
# They can be used for registering a X11 session with
# sessreg. You can use the %user variable
#
# sessionstart_cmd    some command
# sessionstop_cmd    some command

# Start in daemon mode. Valid values: yes | no
# Note that this can be overriden by the command line
# options "-d" and "-nodaemon"
# daemon    yes

# Set directory that contains the xsessions.
# slim reads xsesion from this directory, and be able to select.
sessiondir            /usr/share/xsessions/

# Executed when pressing F11 (requires imagemagick)
screenshot_cmd      import -window root /slim.png

# welcome message. Available variables: %host, %domain
welcome_msg         Welcome to %host

# Session message. Prepended to the session name when pressing F1
# session_msg         Session:

# shutdown / reboot messages
shutdown_msg       The system is halting...
reboot_msg         The system is rebooting...

# default user, leave blank or remove this line
# for avoid pre-loading the username.
default_user        alarm

# Focus the password field on start when default_user is set
# Set to "yes" to enable this feature
#focus_password      no

# Automatically login the default user (without entering
# the password. Set to "yes" to enable this feature
auto_login          yes


# current theme, use comma separated list to specify a set to
# randomly choose from
current_theme       default

# Lock file
lockfile            /var/lock/slim.lock

# Log file
logfile             /var/log/slim.log
did you by any chance create a new user, or did it just start doing this when you first loaded it up?
 

Gigaa

Well-Known Member
Member
Joined
Apr 25, 2018
Messages
108
Trophies
0
Age
26
Location
Norway
Website
giga.is
XP
130
Country
Norway
Yeah, my gnome image works fine, but I just need to get rid of the subfolders. I'll have the new link in an hour or so, uploading 2 gb takes an hour for me. Actually if anyone has a faster upload speed (> 5mbps) and is willing to delete subfolders and upload it, that be pretty cool.

--------------------- MERGED ---------------------------


Can you chroot into it and post the contents of your /etc/slim.conf file?
Got 300 mbps so i can do it for you.
 

Rainbowfied Pokemaster

Well-Known Member
Newcomer
Joined
Jun 28, 2016
Messages
47
Trophies
0
XP
191
Country
United States
cd into coreboot/util/cbfstool, run make, cd back to the coreboot, then run this command:
./util/cbfstool/cbfstool bootloader-dragon-google_smaug.7900.97.0.img extract -n fallback/tegra_mtc -f tegra_mtc.bin
make sure your downloaded bootloader-dragon-google... it is the coreboot folder

Thanks! Is it supposed to end with:

Code:
Found file fallback/tegra_mtc at 0x15a140, type raw, size 220864
 

masterclimby

Member
Newcomer
Joined
Nov 21, 2013
Messages
19
Trophies
0
XP
260
Country
United States
I just confirmed that @00Cancer's GNOME image is working. @benjy3gg make sure you are still doing the following:
Code:
tar xvf gnome_rootfs.tar.gz -C /mounting/point/of/ext4/partition; sync
and then just navigate to the rootfs folder from within and move everything into the root of the ext4 partition and delete the media folder.

@Gigaa are you still going to upload a KDE image? I'd be curious to try that as well.
 
  • Like
Reactions: natinusala

Gigaa

Well-Known Member
Member
Joined
Apr 25, 2018
Messages
108
Trophies
0
Age
26
Location
Norway
Website
giga.is
XP
130
Country
Norway
I just confirmed that @00Cancer's GNOME image is working. @benjy3gg make sure you are still doing the following:
Code:
tar xvf gnome_rootfs.tar.gz -C /mounting/point/of/ext4/partition; sync
and then just navigate to the rootfs folder from within and move everything into the root of the ext4 partition and delete the media folder.

@Gigaa are you still going to upload a KDE image? I'd be curious to try that as well.
I can make it in a few hours.
 
Last edited by Gigaa,

00Cancer

Well-Known Member
Newcomer
Joined
Feb 1, 2017
Messages
67
Trophies
0
Age
20
XP
103
Country
United States
I just confirmed that @00Cancer's GNOME image is working. @benjy3gg make sure you are still doing the following:
Code:
tar xvf gnome_rootfs.tar.gz -C /mounting/point/of/ext4/partition; sync
and then just navigate to the rootfs folder from within and move everything into the root of the ext4 partition and delete the media folder.

@Gigaa are you still going to upload a KDE image? I'd be curious to try that as well.
Yeah I really messed when I packaged the tar. However, thanks for checking if it works.
 

00Cancer

Well-Known Member
Newcomer
Joined
Feb 1, 2017
Messages
67
Trophies
0
Age
20
XP
103
Country
United States
Qcr2r4s.jpg

So much battery, what the hell.
-Vnc'd from my switch
 

Kekshandra

Member
Newcomer
Joined
Jun 8, 2017
Messages
5
Trophies
0
Age
22
XP
43
Country
I'd just like to throw in the suggestion to edit in a warning about using cheap usb-c cables into the original post!

In my case the terminal would throw no errors and all would look well but my switch would simply stay at its black screen and boot nothing.
While i was trying to solve this, i read through all of the posts in this thread and i am not the only one who has had the issue. So, putting in a warning might save some other people who are just starting a lot of pain and hours of trying to trouble shoot a non-existing error.
Notably, after what must have been over a dozen different attempts, it just randomly worked.

It's now 6 am and i'm going to sleep :) but thanks to everyone who is working on this! The pre-compiled build was especially helpful!
 
  • Like
Reactions: CptPotato

OkazakiTheOtaku

no thanks, I don't want a custom title
Member
Joined
Jul 20, 2016
Messages
1,461
Trophies
1
Location
127.0.0.1
XP
3,114
Country
Japan
Strange as Parallels is configured to use as a USB 3 port in the VM.

Do you have the script to try and make it run over usb2, willing to give it a try :)
I wouldn't run it in a VM. It directly edits memory so there is a risk of damage to the host. I don't even know if it works in a VM.
 

natinusala

Win32 error 31 is not an error
OP
Member
Joined
Dec 1, 2012
Messages
1,032
Trophies
0
Age
44
XP
2,914
Country
France
@00Cancer do your Gnome image has working Wi-Fi ? I was able to boot it, reboot and run the exploit again (to make wifi work) however I was greeted by a black screen (but not the black screen from the RCM mode).
 

masterclimby

Member
Newcomer
Joined
Nov 21, 2013
Messages
19
Trophies
0
XP
260
Country
United States
I've figured out how to get the gpu running at fullspeed as F0F did! Turns out it's a power management issue with the nouveau drivers, and all you have to do is run this command as root:
Code:
echo 0d > /sys/kernel/debug/dri/0/pstate

This will force the GPU clock to run at 998mhz.

Attached are the old and new results of glxspheres.

@natinusala I can confirm that the gnome image does have working Wi-Fi
 

Attachments

  • old.png
    old.png
    276.1 KB · Views: 340
  • new.png
    new.png
    55.7 KB · Views: 327
Last edited by masterclimby,

Site & Scene News

Popular threads in this forum

General chit-chat
Help Users
    Psionic Roshambo @ Psionic Roshambo: https://www.youtube.com/watch?v=pkYA4rALqEE