Ctrlk
HomepageGitLabDownloads
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Contributing

Open source software -> contributions welcome! Switchroot is a great place to get started with open source.

Background

Switchroot Android is based on the LineageOS Project, an open-source Android distribution focused on simplicity, stability, device support, common sense features, and upstream adherence. We use Lineage because it has platform-level support for the NVIDIA Shield, which shares the Tegra X1/X1+ processor with the Switch.

Lineage is in turn based on the Android Open-Source Project (AOSP), which is effectively just mainline Android from Google. AOSP is meant as a platform baseline, and is not a great experience by itself (even Google uses their own private internal fork for Pixel etc.), and it's up to distributions like Lineage to provide a more OEM-like experience.

Basics

To contribute to upstream Lineage, you'll need ~350GB free space, a decently powerful PC, a Linux distribution (instructions assume Ubuntu but you can figure out most others), and a lot of time--some of us got our starts with mediocre old PCs chucked in a closet, so if you've got a 2018 Optiplex in your basement, might want to dig it out.

Gerrit

Lineage (like upstream AOSP) uses Gerrit as a code review platform. The flow is basically:

Push to Gerrit -> Get comments and criticisms -> Respond -> Obtain +2 Code Review from repo owner -> Repo owner will merge. makinbacon and npjohnson can merge most Switch-related stuff, but you might need to reach out further for common Tegra (Steel01) or Lineage (Lineage project directors).

More Lineage contributing instructions can be found here: https://wiki.lineageos.org/contributing.

Switch-Specific Code

Follow https://wiki.lineageos.org/devices/nx_tab/build/variant1/ to get a LineageOS tree for nx_tab (tablet Android).

Main repos:

  • Android device repo (and Switch Configuration app): https://github.com/LineageOS/android_device_nintendo_nx

    • This is where the bulk of our device-specific Android configuration lives, including default config props (Android properties read by apps and system services), init rc scripts, power configs, system service tuning, overlays for system packages, and more.

  • Shim device repo for tablet (very little content): https://github.com/LineageOS/android_device_nintendo_nx_tab

    • Small subset, mostly just includes nx stuff and sets tablet characteristics.

  • Kernel & kernel drivers: https://github.com/LineageOS/android_kernel_nvidia_kernel-nx, https://github.com/LineageOS/android_kernel_nvidia_nvidia-nx, https://github.com/LineageOS/android_kernel_nvidia_cypress-fmac-upstream

    • Linux is the kernel used by the Android operating system. An OS kernel is essentially a layer of software running directly on the hardware, whose job it is to abstract that hardware for use by userspace, which is where system services and apps live--in this case everything that makes Android...Android.

    • Linux is generally just one repository, including tons of drivers, device descriptions, and build infrastructure, to support a common denominator of devices (and allow customization to tune builds for your hardware), but here we have a few repos. This comes from NVIDIA's downstream Linux 4.9 kernel used in Jetson Linux, Shield, etc.--a main kernel repo holds stuff considered to be "upstreamable" (this or an equivalent could go to mainline Linux), a nvidia repo holds stuff that couldn't possibly be upstreamed, and some other drivers get their own repos (nvgpu, the Tegra GPU driver, for example).

    • We use kernel-nx, nvidia-nx, common nvgpu and exfat (not linked), and additionally a newer, backported, standalone release of the brcmfmac Wi-Fi driver for better performance and wider compatibility.

  • Kernel devicetree: https://github.com/LineageOS/android_hardware_nvidia_platform_t210_nx\

    • Devicetree is one of a couple ways for bootloaders to provide the Linux kernel with a map of how to talk to different pieces of hardware--ACPI is a more OS-agnostic, desktop-friendly alternative, but devicetree is more common in embedded systems and single-purpose devices.

  • Hardware Abstraction Layers (HALs): AIDL Joycond HAL (Joycond rework for modern Android): https://github.com/LineageOS/android_hardware_nintendo_joycond, Sensor HAL (generic IIO): https://github.com/LineageOS/android_hardware_intel_sensors-iio

    • Android has further hardware abstractions within the OS from what Linux provides on its own. This is advantageous for a couple reasons--stuff like sensors and display drivers have different interfaces Android needs to understand, and Android has core logic and applications written in Java, which makes it difficult to directly interface with the kernel in a performant or spec-compliant manner. HALs fill this gap.

    • HALs are generally written in native code (C, C++, Rust), and communicate over the Binder IPC (inter-process communication) system. They expose a function-like interface over HIDL (Hardware Interface Definition Language, legacy) or AIDL (Android Interface Definition Language, modern, more strict versioning).

AI Policy

We welcome contributions from humans only, but this includes humans assisted by AI. Large language models are fantastic tools for aiding in coding and debugging, but they lack context for systems they are working on. However, in the hands of a qualified human who can provide that context, interpret the output, and clean up mistakes, these tools can exponentially speed up development and assist in contributions.

For those using AI tools to assist in development, we request following the same guidelines as the Linux kernel: https://docs.kernel.org/process/coding-assistants.html. As implied by the signoff requirement, we require the human author to take full responsibility for the change, and we supplement this by requiring the author to respond to and interact with code review on Gerrit. Translation: you must understand the code you are submitting, and responses on Gerrit cannot be authored by chatbots.

TL;DR: AI agents cannot author or sign off on changes, code review requires human responses, and agent-assisted commits should include Assisted-by and Signed-off-by attributions in the commit message:

Signoff can be auto added via --signoff flag on git commit ...

Example commit:

Last updated