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,

GerbilSoft

Well-Known Member
Member
Joined
Mar 8, 2012
Messages
2,395
Trophies
2
Age
34
XP
4,249
Country
United States

Traiver

Developer
Developer
Joined
Aug 1, 2014
Messages
1,326
Trophies
1
Location
???
XP
2,943
Country
United States

Duo8

Well-Known Member
Member
Joined
Jul 16, 2013
Messages
3,613
Trophies
2
XP
3,008
Country
Vietnam
IIRC Arch ARM sd images have the rootfs as the 2nd partition. So you could just take any armv8 image and flash to a SD and use that.
You could also write the compiled kernel to sd and have uboot boot from it.
 

Leonidas87

Well-Known Member
Member
Joined
Jul 15, 2014
Messages
651
Trophies
0
Location
Toronto, Ontario
Website
www.youtube.com
XP
960
Country
Canada
Would be nice to see someone come up with an all in one program to run and do all the commands. Something similar to a jailbreak method.

I think that would be really nice in the end to make things as simple as possible in the near future.
 

Duo8

Well-Known Member
Member
Joined
Jul 16, 2013
Messages
3,613
Trophies
2
XP
3,008
Country
Vietnam
Would be nice to see someone come up with an all in one program to run and do all the commands. Something similar to a jailbreak method.

I think that would be really nice in the end to make things as simple as possible in the near future.
Or just distribute prebuilt binaries.
Compiling linux takes forever.
 

Leonidas87

Well-Known Member
Member
Joined
Jul 15, 2014
Messages
651
Trophies
0
Location
Toronto, Ontario
Website
www.youtube.com
XP
960
Country
Canada
This tutorial seems more captured to installing Linux on a Linux system. Could we possibly get details on. Specifically installing Linux on the switch from mac?

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

I have apple high Sierra running on my surface pro 2017 so i would probably do this with that system.

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

Th install method does seem a bit complicated, should be simplified all in due time. Appreciate all the hard work by everyone. Things are developing so quickly. Just wondering can we not get homebrew running somehow with this instead of Linux or no?
 

realjumy

Woooosh!
Member
Joined
Apr 24, 2018
Messages
188
Trophies
0
XP
1,594
Country
United Kingdom
Anyone else is having the following error?

Code:
*** Your GCC is older than 6.0 and is not supported
arch/arm/config.mk:69: recipe for target 'checkgcc6' failed
make: *** [checkgcc6] Error 1


I tried installing gcc-7 but still having the same problem.

EDIT: I also installed with gcc-6, still same problem. There's something I'm doing wrong...
 
Last edited by realjumy,

Selim873

Nunnayobeesnes
Member
Joined
Jul 31, 2010
Messages
1,275
Trophies
0
Age
30
Location
Chillin' with Bob Ross
XP
1,112
Country
United States
I'm definitely going to try this in a few days when I have time. Thanks for writing this!! Though I hope Android gets ported with full support for all the hardware. I would never need homebrew on Switch, I could just switch between Horizon and Android depending on my needs. lol Though hopefully it can be possible to run the exploit from an Android phone eventually.
 

ehnoah

Well-Known Member
Member
Joined
Oct 9, 2012
Messages
918
Trophies
0
XP
781
Country
Netherlands
Code:
 make
arm-linux-gnueabi-gcc -march=armv4t -mthumb -Wall -Werror -Os -MMD -ffreestanding -fno-common    -fomit-frame-pointer -nostdlib -fno-builtin-printf -fno-asynchronous-unwind-tables -fPIE -fno-builtin -fno-exceptions -Wl,--no-dynamic-linker,--build-id=none,-T,romhax.ld -std=gnu11 -c -o obj/cbfs.o cbfs.c
make: arm-linux-gnueabi-gcc: Command not found
Makefile:23: recipe for target 'obj/cbfs.o' failed
make: *** [obj/cbfs.o] Error 127

My path: export PATH=$PATH:/home/pega/aarch64/lib:/home/pega/gnuabi/lib

Ubuntu 17.10
 

Duo8

Well-Known Member
Member
Joined
Jul 16, 2013
Messages
3,613
Trophies
2
XP
3,008
Country
Vietnam
Code:
 make
arm-linux-gnueabi-gcc -march=armv4t -mthumb -Wall -Werror -Os -MMD -ffreestanding -fno-common    -fomit-frame-pointer -nostdlib -fno-builtin-printf -fno-asynchronous-unwind-tables -fPIE -fno-builtin -fno-exceptions -Wl,--no-dynamic-linker,--build-id=none,-T,romhax.ld -std=gnu11 -c -o obj/cbfs.o cbfs.c
make: arm-linux-gnueabi-gcc: Command not found
Makefile:23: recipe for target 'obj/cbfs.o' failed
make: *** [obj/cbfs.o] Error 127

My path: export PATH=$PATH:/home/pega/aarch64/lib:/home/pega/gnuabi/lib

Ubuntu 17.10
PATH needs to point to the bin folder, not lib
 

Site & Scene News

Popular threads in this forum

General chit-chat
Help Users
  • K3Nv2 @ K3Nv2:
    Alot of manufactures do care about older consoles they just want to whine about piracy
    +2
  • S @ salazarcosplay:
    @BigOnYa I had 4.89 hfw on super slim that was great, but when I got a new hard disk I forgot where the guide was and could only find a guide for 4.90 and its resources
  • S @ salazarcosplay:
    @BigOnYa I think another reason to want to update is if the hfw is at the level of the fw
  • S @ salazarcosplay:
    you can sync trophies
  • BigOnYa @ BigOnYa:
    Yea that's what I'm sitting on now- 4.9, and it seems fine, have had no issues at all
  • S @ salazarcosplay:
    I don't know if people play online or such
  • K3Nv2 @ K3Nv2:
    My ps3 short circuited during a deep clean still salty about it after downloading 2tbs worth but SteamDeck okay with emulation still just can't run mgs4 worth shit
  • BigOnYa @ BigOnYa:
    Yea forgot bout trophies. They just silly to me. Just like the xbox achievements. Hey, to each they own tho.
  • K3Nv2 @ K3Nv2:
    It keeps players in touch with the game like a check list of things to do after they beat it
  • S @ salazarcosplay:
    @BigOnYa they ruined the gaming experience for me to be honest
  • S @ salazarcosplay:
    @BigOnYa Im not crazy about getting all of them, i feel like I have something to show for for the time put in
  • S @ salazarcosplay:
    @BigOnYa If you want to do rgh or 360 mod
  • S @ salazarcosplay:
    does it matter if you update your 360 or not before trying is it advisable or not
  • BigOnYa @ BigOnYa:
    Yea I don't pay attention to them really. Or do I try to 100% a game. I just play till story ends/ or I get the girl!
  • K3Nv2 @ K3Nv2:
    Bigonya uses his wiener to mod 360s
    +1
  • Xdqwerty @ Xdqwerty:
    Going to the water park, see ya
  • BigOnYa @ BigOnYa:
    You should update the 360 to newest dash before RGHing it yes. But not a big deal if you don't, you can install new dash/avatar updates after. It's just easier to do it auto online before, instead manual offline after.
  • BigOnYa @ BigOnYa:
    Have fun @Xdqwerty. If you see a chocolate candy bar floating in the water, don't eat it!
  • AncientBoi @ AncientBoi:
    :O:ohnoes: Y didn't U Tell ME that ALSO? @BigOnYa :ohnoes: 🤢🤮
    +1
  • BigOnYa @ BigOnYa:
    Does it taste like... chicken?
    +1
  • S @ salazarcosplay:
    @BigOnYa I wanted to ask you about your experience with seeing south park. Most of the people a bit younger like my younger brother and cousins that are a few younger than me that saw kids found south park funny because of the curse words, kids at school, that seemed like liking the show on a very basic level.

    I could not quite have a in depth discussion of the show.

    How was it for you? As an adult. What did you find the most interesting part about it. Did you relate to the parents of the kids and their situations. Was it satires, the commentary on society. The references on celebrities' and pop culture.
  • BigOnYa @ BigOnYa:
    I remember seeing the very first episode back in the day, and have watched every episode since. I used to set my VCR to record them even, shows how long ago.
  • BigOnYa @ BigOnYa:
    I just like any comedies really, and cartoons have always been a favorite of mine. Family guy, American Dad, Futurama, Cleveland Show, Simpsons - I like them all.
  • BigOnYa @ BigOnYa:
    South Park is great cause they always touch on relavent issues going on today, and make something funny out of it.
    +1
    BigOnYa @ BigOnYa: South Park is great cause they always touch on relavent issues going on today, and make... +1