Twili Switch

Twili
General
Author	misson20000
Type	PC Utilities
Version	1.4.0
License	GPL-3.0
Last Updated	2021/06/14
Links
Download
Website
Source

Twili is a debug monitor/bridge for homebrew applications running on the Nintendo Switch.

The debug monitor aspect of it aims to provide a sane solution for stdio and logging, and to ease development by generating crash reports and allowing debugging of running applications. The debug bridge aspect aims to provide similar utilities to ADB, allowing fast and convenient sideloading.

Features

• Send and launch homebrew over USB (or TCP).
• If the homebrew is compatible, it lets you have stdin/stdout/stderr over USB, too, through the command line tool. This allows for a very fast development cycle.
• If you don't need your homebrew to be an applet (you're developing a background sysmodule), it can reduce iteration time even farther by preventing fatal errors when your sysmodule inevitably crashes.
• You can use GDB to debug your homebrew (applets, sysmodules, etc.) or even official software.
• When something crashes, you can generate an ELF core dump that you can load in a real man's debugger (aarch64-linux-gnu-elf) to help you figure out what went wrong instead of having to turn your console off, remove the SD card, find the crash log, and use addr2line to turn it into something meaningful.
• You can core dump any process, and not just homebrew.
• It lets you query overall RAM usage on your console.
• It lets you get a list of all the processes running on your console, and...
• It lets you kill them, too.
• If low-level debugging is your style, it lets you debug them too. As of 1.2.0, there's even a GDB stub.

Installation

See the installation instructions on the GitHub repo.

User guide

FAQ

Q. How do I use Twili's standard IO?

If you're using libtransistor, you get it for free. If you're using libnx, you can link against libtwili (found in my twili-libnx repo). If you launch your application through twib run, stdout/stderr will go to your console and stdin will come from that console. If you launch any other way, stdout/stderr will go to twibd logs and stdin will block.

Q. How is it different from nx-hbloader/nxlink?

Aside from having way more features, it runs each homebrew in its own process, which is a clean slate except for a small stub providing HBABI keys. This means that homebrew can manage its own memory and doesn't have to worry about cleaning up entirely behind itself for the next application.

Q. Does it have a GDB stub?

As of 1.2.0, yes - See the README on the github repo for instructions.

Q. What CFWs does it work on?

The only CFW that I can confirm functionality on and actively support is Atmosphère, and only somewhat recent versions of it (0.10.2+). Twili has been tested on Atmosphère 0.10.2. Twili might work on other CFWs with some tweaks. Don't run Twili on piracy firmware because you'll make me very sad.

Q. What should I know before I install it?

It replaces nx-hbloader. That means it replaces hbl.nsp. If you don't like Twili and want to remove it, don't forget to put back nx-hbloader's hbl.nsp.

Compatibility

Supported Firmware Versions
1.0.0	Tested working (limited functionality)
2.0.0	Expected working
2.1.0 - 2.3.0	Expected working
3.0.0	Tested working
3.0.1 - 4.0.0	Expected working
4.0.1	Tested working
4.1.0	Expected working
5.0.0	Tested working
5.0.1 - 5.1.0	Expected working
6.0.0	Expected working
6.0.1	Tested working
6.1.0	Tested working
6.2.0	Tested working
7.0.0	Expected working
7.0.1	Tested working
8.0.0	Tested working

Changelog

v1.4.0 2021/06/14

• Changes:
  • Now uses Exosphere for version inference instead of set:sys.
• Fixes:
  • Added support for TIPC pgl on 12.0.0+.

v1.4.0-pre2 2021/02/28

• Additions:
  • Added a watchdog to hopefully get some better insight into sysmodule deadlocks.
  • Added error code lookup to twib (twib err).
• Changes:
  • Core dumps do not include IO mappings anymore.
  • AppletTracker now defers reading hbmenu until it is needed, so you can run Twili without hbmenu and it won't crash.
  • Updated libtransistor.
• Fixes:
  • Fixed USBBridge on 11.0.0+.

v1.4.0-pre1 2020/08/12

• Additions:
  • Added launchd integration for twibd (thanks to @liuervehc).
  • Added SystemVersion class for tracking firmware versions.
  • Added firmware 10.0.0 (PGL) support.
  • Added more verbose output for ITwibDebugger calls.
  • Added 'none' to storage locations understood by twib launch (thanks to @averne).
  • Added twib-get-module-info command.
  • Added 'monitor get base' command to gdb stub.
• Removals:
  • Removed obsolete process_creation module.
  • Removed title 0100000000006482 ECS hack (no longer necessary).
• Changes:
  • Updated to c++20.
  • Moved most service code to Services.cpp, templated by firmware version.
  • Refactored error handling code to not use exceptions.
  • Made ECS confusion a critical error.
  • Added ShellTracker output to twib debug.
• Fixes:
  • Fixed 0-byte responses (thanks to @comex).
  • Fixed systemd unit file for twibd.
  • Fixed twib run command line issue ("Managed process has been removed.").
  • Fixed ShellTracker receiving process notifications on the wrong thread.
  • Fixed killing and terminating suspended launch processes.
  • Fixed LaunchProgram response.
  • Fixed ITwibDebugger wait_handle destruction order.
  • Fixed inverted reboot unsafe logic.

v1.3.0 2020/01/13

• Additions:
  • Added library list to gdb stub.
  • Added more filesystem commands (#84, #81).
  • Added support for reading and writing FPU registers in GDB stub.
  • Added ShellProcess.
• Removals:
  • Removed ManagedProcess.
• Changes:
  • Applet process can now be requested to exit before they launch.
  • Raised applet process stack size.
  • Updated for Atmosphere changes.
  • Refactored a lot of AppletProcess functionality into ECSProcess and TrackedProcess.
  • Disabled USB logging by default, since it confuses people.
  • Reboot command now uses spsm and reboots to payload.
  • Twili aborts now show better information on the fatal error screen.
• Fixes:
  • Fixed USB objects being closed when TCP connects (#70).
  • Worked around LIBUSB_ERROR_ACCESS when udev is slow to change permissions.
  • Fixed HandleReadMemory not returning after error (#74).
  • Fixed GDB multiprocessing thread reporting (supposedly improves IDA compatibility).
  • Fixed Xcode clang asan build error.
  • Fixed systemd service file to use absolute path.
  • Fixed libusb_claim_interface failure path.
  • Fixed gdb stub 'ENN`' error reporting.
  • Fixed blockingconcurrentqueue on macOS.
  • Fixed several twibd deadlocks.
  • Fixed MonitoredProcess swallowing unknown errors.
  • Fixed leaking twili.ini file handle (this lets you twib sd push twili.ini).
  • Worked around debugging PID 0.

v1.2.1 2019/04/03

• Fixed nullptr deref in service when debugging non-monitored processes.
• Improved threading support and stop reasons for gdb.
• Improved set current thread to 0.
• Improved thread name reading.
• Improved qOffsets for non-monitored processes (picks main instead of rtld and searches on-device now).

v1.2.0 2019/03/31

• Added GDB stub (Linux/OSX only).
• Added twib push and twib pull.
• Added suspended launch for twib run.
• Fixed AppletTracker hbmenu null pointer dereference.
• Thread handles for libnx managed processes need to be 64-bit for some reason.
• Vastly reduced memory usage (~29MiB -> 9MiB).
• Added buffering for TwibPipe (should improve performance for short/frequent writes by avoiding round trip over USB).
• Refactored platform-specific code in twib/twibd.
• Made twib daemon exit cleanly on SIGINT.
• Made twib daemon block list-devices until it's done probing (fixes race condition on startup).
• Fixed TCPBackend for Windows.
• Fixed MessageConnection out_buffer synchronization on Windows.
• Fixed twib run on Windows.
• Fixed twib for cygwin/msys2.
• Made PostBufferSync timeout infinite (fixes random fatals).
• Improved device unplug error handling.

v1.1.0 2019/01/25

• Additions:
  • Added libusbK-based contrib driver package.
  • Added support for libnx applications that use romfs.
  • Improved support for NextLoadPath.
  • Added configuration system.
  • Added twib launch command.
• Changes:
  • Refactored request handling to support streaming.
  • Changed some packets for consistency.
  • twib run now streams NROs into files, allowing them to be much bigger.
  • Refactored TwibPipe.
• Fixes:
  • Fixed compatiblity with Atmosphere-loader compiled with new versions of libnx by stubbing IFileSystem#GetFileTimeStampRaw.
  • Fixed thread handles for HBABI.
  • Fixed regression in TCPBackend::AddDevice caused by Windows changes.
  • Fixed IAppletController premature closing.
  • Fixed applet launch failures breaking ECS and causing confusion.
  • Fixed TCP device ID calculation.
  • Fixed RequestForAppletToGetForeground errors.
  • Fixed 2000-0000 in USB.

v1.1.0-pre1 2019/01/10

• Beware of breaking protocol changes; make sure you update twib and twibd, and, if you're using lanayru, you will need to install ruby-twib from git since I'm not pushing a new version until the protocol changes are part of an actual release.

v1.0.1 2018/12/26

• Additions:
  • Added PrintDebugInfo command.
  • AppletHost has more SVC permissions now.
• Changes:
  • Twili is now distributed as exefs.nsp.
  • We use the new npdm-json format now.
  • Twib should no longer be quite as exit() happy.
  • USBBridge catches std::bad_alloc and returns LIBTRANSISTOR_ERR_OUT_OF_MEMORY responses instead of blowing up.
  • Use upstream switch-tools (don't need my elf2kip fork anymore).
• Fixes:
  • Managed processes now register service access control (rip sm:h on new versions of Atmosphere).
  • AppletTracker now clears created process queue when control applet is lost.
  • Use applet memory instead of application memory so games can launch on 5.0.0+ with Twili running in background.
• Notable Known Issues:
  • #55: Crash with 2000-000 while sitting on home menu: This crash doesn't seem to happen when twibd is running and is connected.
  • #56: LibusbK (Windows) driver association is bad: Will be addressed in the next release.

v1.0.0 2018/11/07

• It's about time we had a proper release.

Test Build 6 2018/07/20

• Experimental Windows support.
• Refactor of UNIXFrontend, TCPFrontend into unified SocketFrontend.
• Renamed log macro to avoid collisions with logarithm.
• Refactor of networking code into MessageConnection.
• systemd integration for twibd.
• cmake improvements.
• Add twili-stdio driver to twibd.

Test Build 4 2018/0/12

• This is the first build of TwiliLauncher to run as a KIP, but, more importantly for the purposes of these release notes, the first to be released on GitHub.

External links

• GitHub - https://github.com/misson20000/twili
• GBAtemp - https://gbatemp.net/threads/twili-homebrew-debug-monitor.522673/