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,
  • Like
Reactions: Deleted member 518148, globalc, MissingNo._ and 49 others
Click to expand...
natinusala

natinusala

Win32 error 31 is not an error
OP
Member
Level 12
Joined
Dec 1, 2012
Messages
1,032
Trophies
0
Age
44
XP
2,914
Country
France
@Gigaa would it be hard for you to release your GPU power management service to a standalone package so that we can install it on LXDE and GNOME images ? I personally prefer GNOME as it's much more touch-friendly, and I guess others may do to. Thanks !
 
00Cancer

00Cancer

Well-Known Member
Newcomer
Level 1
Joined
Feb 1, 2017
Messages
67
Trophies
0
Age
20
XP
103
Country
United States
If anyone was wondering, this is how to change your username on any of the rootfs tarballs compiled by @Gigaa or I:

NOTE: I will use <> to indicate something that you have to type in
First install qemu-user-static on your PC with Linux. Put the following in /etc/binfmt.d/qemu-arm64.conf
Code: 
:qemu-arm64:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\xb7:\xff\xff\xff\xff\xff\xff\xff\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff:/usr/bin/qemu-aarch64-static:OC
Then run
Code: 
systemctl start systemd-binfmt
Next you will need to chroot into the device as you cannot change any of the user settings if you are logged on.
Plug in your sdcard into your Linux machine and type this set of commands.
Code: 
$ sudo mount /dev/sd<put the letter of your drive here>2 /mnt/root
If /mnt/root does not exist, create it
Before you chroot, you must copy the qemu-aarch64-static onto your sdcard
Code: 
$ sudo cp /usr/bin/qemu-aarch64-static /mnt/root/usr/bin
Then type these commands
Code: 
$ cd /mnt
$ sudo mount --bind /sys root/sys
$ sudo mount --bind /proc root/proc
$ sudo mount --bind /dev root/dev
$ sudo mount --bind /dev/pts root/dev/pts
$ sudo chroot root /bin/bash
Once you are chrooted into the sdcard, type
Code: 
$ sudo usermod -l <newUsername> <oldUsername>
$ sudo usermod -d /home/<newHomeDir> -m <newUsername>
Once you do this, type
Code: 
$ sudo <your editor of choice> /etc/silm.conf
Scroll down until you see the line that reads
Code: 
default_user       alarm
Change alarm to the username you set earlier and save the file.
NOTE2: If you have sudo installed you will need to edit visudo. To do this type
Code: 
$ EDITOR=<your editor of choice> visudo
Scroll down until you see
Code: 
alarm ALL=(ALL) ALL
and change it to
Code: 
<your username> ALL=(ALL) ALL
To exit chroot type
Code: 
$ exit
Now that you are out you chroot type
Code: 
$ sudo umount -R /mnt/root
You can now put your sdcard back into your switch and and relaunch Linux with your new username
NOTE3: If anyone happens to do this on the gnome rootfs, could you please post the warning you receive on startup as I do not remember what it was, but I would like to put thu fix in this post
 
Last edited by 00Cancer,
Gigaa

Gigaa

Well-Known Member
Member
Level 1
Joined
Apr 25, 2018
Messages
108
Trophies
0
Age
26
Location
Norway
Website
giga.is
XP
130
Country
Norway
natinusala said:
@Gigaa would it be hard for you to release your GPU power management service to a standalone package so that we can install it on LXDE and GNOME images ? I personally prefer GNOME as it's much more touch-friendly, and I guess others may do to. Thanks !
Click to expand...
Sure, it's just a simple bash script that gets symbolically linked to /usr/bin. I'm just going to release the script as the rest is quite easy (and also not necessary) to do.
https://0w0.st/power.sh

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

00Cancer said:
If anyone was wondering, this is how to change your username on any of the rootfs tarballs compiled by @Gigaa or I:

First you need to chroot into the device as you cannot change any of the user settings if you are logged on.
Plug in your sdcard into your Linux machine and type this set of commands.
NOTE: I will use <> to indicate something that you have to type in
Code: 
$ sudo mount /dev/sd<put the letter of your drive here>2 /mnt/root
If /mnt/root does not exist, create it
Code: 
$ cd /mnt
$ sudo mount --bind /sys root/sys
$ sudo mount --bind /proc root/proc
$ sudo mount --bind /dev root/dev
$ sudo mount --bind /dev/pts root/dev/pts
$ sudo chroot root /bin/bash
Once you are chrooted into the sdcard, type
Code: 
$ sudo usermod -l <newUsername> <oldUsername>
$ sudo usermod -d /home/<newHomeDir> -m <newUsername>
Once you do this, type
Code: 
$ sudo <your editor of choice> /etc/silm.conf
Scroll down until you see the line that reads
Code: 
default_user       alarm
Change alarm to the username you set earlier and save the file.
To exit chroot type
Code: 
$ exit
Now that you are out you chroot type
Code: 
$ sudo umount -R /mnt/root
You can now put your sdcard back into your switch and and relaunch Linux with your new username
Click to expand...
Maybe you should mention that you have to use qemu-aarch64-static aswell
 
00Cancer

00Cancer

Well-Known Member
Newcomer
Level 1
Joined
Feb 1, 2017
Messages
67
Trophies
0
Age
20
XP
103
Country
United States
Gigaa said:
Sure, it's just a simple bash script that gets symbolically linked to /usr/bin. I'm just going to release the script as the rest is quite easy (and also not necessary) to do.
https://0w0.st/power.sh

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


Maybe you should mention that you have to use qemu-aarch64-static aswell
Click to expand...

Fixed
 
  • Like
Reactions: Gigaa
D

Deleted User

Guest
OkazakiTheOtaku said:
It doesn't work on a VM on MacOS out of the box. It never will work, unless Parallels or VMWare adds in passthrough. You either need to recompile the linux kernel with the patch or run linux on bare metal and use the dangerous RAM manipulation script.
Click to expand...

just patched the kernel will reply if it works
 
Gigaa

Gigaa

Well-Known Member
Member
Level 1
Joined
Apr 25, 2018
Messages
108
Trophies
0
Age
26
Location
Norway
Website
giga.is
XP
130
Country
Norway
MiniCheese27 said:
Is there any way I could get multilib to work with this? Wanted to see if wine would work. It's not in pacman.conf.
Click to expand...
Windows applications are compiled mostly to x86, getting them to work on arm with wine will not work.
There might be some clever solution out there to emulate them but i dunno.
EDIT: Scratch that, you might find this interesting. https://wiki.winehq.org/ARM
 
Last edited by Gigaa,
RHOPKINS13

RHOPKINS13

Geek
Member
Level 11
Joined
Jan 31, 2009
Messages
1,354
Trophies
2
XP
2,622
Country
United States
Gigaa said:
You might have a better result if you try to compile it yourself.
Click to expand...

Tried compiling it myself, still no luck on wifi with KDE image. I might try one of the other images later.

One of the last lines output before the GUI starts is:
brcmfmmc 0000:01:00.0 wlp1s0: renamed from wlan0

Am I correct that I should be able to see something besides loopback in ifconfig, at least after rebooting?
 
Gigaa

Gigaa

Well-Known Member
Member
Level 1
Joined
Apr 25, 2018
Messages
108
Trophies
0
Age
26
Location
Norway
Website
giga.is
XP
130
Country
Norway
RHOPKINS13 said:
Tried compiling it myself, still no luck on wifi with KDE image. I might try one of the other images later.

One of the last lines output before the GUI starts is:
brcmfmmc 0000:01:00.0 wlp1s0: renamed from wlan0

Am I correct that I should be able to see something besides loopback in ifconfig, at least after rebooting?
Click to expand...
If no other errors comes up then yea essentially you should.
 
LarBob

LarBob

Well-Known Member
Member
Level 4
Joined
Dec 29, 2013
Messages
370
Trophies
0
Age
23
XP
563
Country
United States
Is it just me or does it take about an hour of tries to get 2 boots in a row so I get wifi for everyone else? My success rate of boots is very low.
 
cmsj

cmsj

Well-Known Member
Newcomer
Level 2
Joined
Apr 25, 2018
Messages
61
Trophies
0
Age
46
XP
223
Country
United Kingdom
natinusala said:
I added the link to the GitHub repo to build it, is it the same ?
Click to expand...

The github repo is for people who want to build it themselves, but the repo now has a build of the tarball, which is the link in my previous post. Ideally I would have both linked, but it's up to you :)
 

Site & Scene News

Go to forum More news

Popular threads in this forum

Homebrew Tutorial  Building Pagascape from source to running Self Hosted mode on Windows and MSYS

Hacking Misc  Getting the MIG Switch to load an XCI dump without its original Initial Data

mig switch not working/updating??

Hacking Homebrew Tutorial  Portable PegaScape (Win32)

Fusee.bin with the new Pre-release of Atmoshere 1.7.0

DBI language error

Homebrew Tutorial  Setup a DevKitPro environment on Windows.

Homebrew  I accidentally updated to fw 18.0 on my switch in cfw and now I am getting an error that says unknown pkg1 version. please help me find a solution

General chit-chat
Help Users
    Xdqwerty @ Xdqwerty: