n-popescu/Inkypaint / .claude/skills/snx-service
snx-service
VerifiedImplement or fix a high-level-emulated Switch service or device (IPC commands, nvdrv ioctls, shared memory) so it answers the way the console does, as the game's SDK code expects. Use when a log shows an unimplemented command, a game stalls waiting on a service, an svcBreak follows a service call, or when adding audio, input, video or system services.
Services
Where
- Interfaces are declared, not hand-dispatched: each service file has a
.swipcbeside it (insrc/nx/:hle/services/acc.candhle/services/acc.swipc,hle/services/network/bsd.swipc,hle/filesystem/fs.swipc), in SwIPC's language.docs/IPC.mdhas the language, the layout the generator applies and the C side.tools/swipc/swipc.cgenerates<file>.swipc.hand<file>.swipc.incintobuild/<preset>/src/nx/snx_hle-swipc/. The service's C file includes the.inc, which has each handler's exact prototype; other files include the.h. - A command's handler is
static int nn_ns_IFoo_Command(SvcObj* self, inputs..., outputs...): scalars by value, structs asconst T*, buffers asIpcBuf(address, size), objectsSvcObj*in andSvcObj**out, handlesu32in andu32*out. Outputs start zeroed. It returns 0 orRC(module, description), and a failure answers no outputs. I_new(data_size)makes an object of interfaceIwith zeroed state ino->data;I_register(ctor)registers a constructor under the.swipc'sisnames (services.c, or the service's own init).@stubanswers success and zeros without a handler;@unsortedkeeps a command's raw arguments in declaration order, for the few the SDK lays out that way;@fallback(fn)picks what answers undeclared commands (stub_ok, which logs, by default).types.swipccomes first in everysnx_swipclist of the runtime's files, and in a test's that uses its types.src/nx/hle/kernel/ipc.c: HIPC/CMIF parsing, replies, sessions, domains, the registry.services_int.hdeclares what the service files share.- In
services/:hid.c(input and its shared memory),vi.c(display, binder),nvdrv.c(nvhost devices),audren.c(audren_update),pl.c(shared fonts),misc.c(the small services).src/nx/hle/filesystem/fs.c, andsrc/nx/gpu/video/(host1x channels, NVDEC, VIC).
Procedure
- Find the command.
-vlogs every call:grep "IAudioOut cmd" run1.log | sort | uniq -c(the object's name is the interface's,nn::audio::detail::IAudioOut, but bsd's and ldr's carry the service's,bsd:uandldr:ro). An undeclared command is logged by the interface's fallback, the first three times:[undeclared] I cmd N -> okfromstub_ok(success with no outputs: for a command that gives an object or a handle the game ends up calling through null),[unknown]fromipc_unknown,[not implemented]from bsd's, nothing fromquiet_ok.[undeclared] NAME cmd N -> okalso comes from sm's stand-in for a service the runtime doesn't have. A[bad request] I cmd N: pid .., A .., ... -> InvalidCmifRequestmeans the declaration doesn't match what the SDK sends (step 2): the game gets an error, and often aborts on it.[bad request] ... -> InvalidNumInObjectsis the same for a domain request's objects, and... takes objects, on a session that isn't a domain -> NotSupporteda command declared with objects called on a plain session. Switchbrew's page for the service gives the command's name and layout; libnx's client struct shows the raw layout and buffer attributes. - Declare it in the
.swipcwith the console's full signature, inputs and outputs the runtime ignores included, and the exact buffer attributes (they decide the A/B/X/C list). Never write offsets by hand: the generator sorts raw arguments by alignment, ascending, as the SDK does (check a mixed-alignment command against the SDK'sInRawArgumentInfo<size, alignment, offset>templates: a few use declaration order,@unsorted).pidis one 8-byte slot (write SwIPC's(u64, pid)aspid),aruida command's ClientAppletResourceUserId slot. - Read the caller. The game's SDK wrapper (
nn::audio::...,nn::hid::...) shows what it reads from the reply and what it does with it.tools/symbols.pyandtools/disasm.pyon the wrapper, or thesdk-scoutagent. A field the SDK reads and the runtime never writes is a bug even when nothing crashes yet. - Answer like the console in the handler. Same result codes, same output values, same handle and event behavior. Where the console times something (audio buffers, vsync), keep the timing: games sync against it.
- Mind the threads. Service calls come from game threads, which run in parallel on the host. State shared
between calls takes a lock (
PMutex,pm_lock), events go throughkevent_signal. An object whose every command needs a lock gets a dispatcher of its own aroundI_dispatch(fs.c'sfile_disp,dir_dispandfs_disp, ldr.c'sro_dispatch), and is made withsvcobj_newand that dispatcher, notI_new. - Verify with the scene that uses it (
snx-run), and grep the-vlog to see the new answers. A test that includes a service's C file generates that service's dispatchers itself (snx_swipcintests/CMakeLists.txt).
References and licensing
Switchbrew documents commands and structures. Ryujinx (MIT) is the best behavioral reference and can be ported from with its notice. yuzu and its forks (GPL-2.0-or-later or GPL-3.0) can be ported too, ScarletNX being GPL-3.0-or-later: keep their copyright lines and say where the code came from. GPL-2.0-only code can't be (Atmosphère is read, never ported).
Known traps
- Reporting more than one npad style for a controller makes the SDK assert in
GetVibrationDeviceHandles. - An
IAudioOutthat never releases buffers stalls CRI movies after a few frames. The released-buffer array must be cleared first, because the SDK reads every slot. WaitSynchronizationwith zero handles is legal (a plain sleep).- nvhost syncpoint ids above 127 overflow NvRmStream's tables: allocate with
syncpt_alloc().
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |