Revision as of 20:55, 2 February 2022

This page documents the N64 application available via Nintendo Switch Online.

The internal name is "Hovercraft".

This uses an updated version of the N64 emulator used by SM3DAS. Like SM3DAS, Vulkan is used for rendering.

This saves various PlayReports. This also uses bcat, the bcat data if available can specify a list of games which aren't allowed to be launched.

NPDM

Same as SM3DAS Mario64 (besides programId etc), except the following services are additionally accessible: audout:u, bcat:u, bsd:u, bsdcfg, friend:u, nifm:u, nsd:u, sfdnsres, ssl. Flags is 0x27.

Details

Like SM3DAS, this uses JIT for running the emulated executable. The game archives also contains an AOT NRO. A NRO does get loaded, however actual usage is currently not enabled. When the emu PC physical address is not located in DRAM (code prior to this will handle triggering a N64 exception if the PC vaddr is invalid), the code is interpreted instead of using JIT, with the code instruction being loaded with n64MemDefaultRead32 (handler funcptr is called from a table, mem-access with these use the non-WithDestLog funcs. TLB validation is done by those funcs before mem-access, triggering a N64 exception if needed). Patches are applied at runtime with the config/lua files from the game archives.

TLB validation for mem-access done by JIT'd code is only done if the corresponding flag in "g_nN64CpuCmpTLBCheckLevel" is set, see below. There are currently no games which set this config. Note that the various Read/Write funcs will do nothing if the specified address is invalid, with 0 being returned for the Read funcs.

A maximum of 0x1000-bytes are loaded from the launch-parameter, with buf[read_size]=0. Hence, this is a string. When available, this seems to be used to select which game to launch.

RomFs contains the following:

"/kc.dat", "/Pipeline.cache", "/shader_font_frag.spv", "/shader_p1_frag.spv", "/shader_p1_vert.spv", "/shader_p2_srgb_frag.spv", "/shader_vulkan_frag.spv", "/shader_vulkan_vert.spv".
"/.nrr/" contains:
- "l-classics-app.nrr"
- "libHovercraftJITPlugin.nrr"
- And NRRs for each game's AOT NRO.
"/bootapp/" contains "init.json", "resources.json", and "resources/" which contains:
- Various UI/graphics data is stored here under various sub-dirs. This also includes "scripts/", which contains Lua scripts in bytecode form.
  - One of these scripts at "/scripts/constants_nuse.lua" in the raw data, contains among various other data: "FirstDeliveryDate" "2019-09-01".
"/nro/" contains "libHovercraftJITPlugin.nro", the NRO for the JitPlugin.
"/sysdata/shaders/mesh.spirv", "/sysdata/shaders/sprite.spirv"
"/titles/" contains the data for the emulated games:
- "lclassics.titlesdb"
- There's a sub-dir for each game containing:
  - "{dirname}-details.png"
  - "{dirname}.bnz": ROM-image compressed directly with zlib.
  - "{dirname}.dtz": cpio archive compressed directly with zlib, containing the following (these are under "metapack_temp\"):
    - The data here has mostly the same structure/format as SM3DAS rom/{subdir}, without the unused NRR. Filenames have the same "{fileid}_{TitleCode}.ext" format. When any texture data is present, it's included directly in this directory.
      - The .meta no longer contains "DataSection", which in SM3DAS specified what files to load from here.
      - The .lua file is optional. Compared to SM3DAS, Mario64 here (regions E/P at least) no longer has a .lua file, and the only remaining patches in config are for "Idle" and "BreakLoop". There's also various config differences compared to SM3DAS. Also unlike SM3DAS, the ROM-image uses the ROM for each respective region, instead of Shindou for non-JPN.
  - "{dirname}.png"

libHovercraftJITPlugin

This section documents the JIT plugin.

This is an updated version of the plugin used by SM3DAS. Besides compiler-version differences / funcs being moved around, there were actual code changes.

The struct passed as the InBuffer to Control is now 0xE00-bytes instead of 0xEB0-bytes. The internal workmem offsets / layout changed. Various funcs were updated etc.

The 0xE00-byte controldata struct has the following structure (all addrs/data are from the emulator user-process):

Offset	Size	Description
0x0	0x8	Data addr: g_pGPR
0x8	0x8	Data addr: g_pFPR
0x10	0x8	Data addr: g_pCP0
0x18	0x8	Data addr: g_nRegHi
0x20	0x8	Data addr: g_nRegLo
0x28	0x8	Data addr.
0x30	0x8	Data addr: g_nFCSR
0x38	0x8	Data addr: g_bN64CpuCmpEndCheck
0x40	0x8	Data addr: g_nN64CpuPC
0x48	0x8	Data addr: g_nN64CpuJmpPC. s32, normally -1. When not -1 this is a value which can be copied into g_nN64CpuJmpPC by the generated code, with g_nN64CpuJmpPC being reset to -1 afterwards regardless of the original value.
0x50	0x8	Data addr.
0x58	0x8	Data addr: g_nN64CpuHaveExp
0x60	0x6A8	Array of funcptrs. Called with w0=instruction_value from generated code for handling instructions' implementation, when the plugin itself doesn't handle it.
0x708	0x8	Funcptr: `n64CPUProcInstCOP1Check()`
0x710	0x8	Funcptr.
0x718	0x8	Funcptr.
0x720	0x8	Funcptr: `n64CPUSetRegisterCP0(int, unsigned int)`
0x728	0x8	Funcptr: `n64CPUGetRegisterCP0(int)`
0x730	0x20	Funcptrs for reading data: `n64MemDefaultRead{bitsize}(unsigned int)`, where bitsize is {8, 16, 32, 64} (32 uses `n64MemDefaultRead32WithDestLog`). Unused by the plugin.
0x750	0x20	Funcptrs for reading Special data: `n64MemDefaultReadSpecial{bitsize}(unsigned int)`, where bitsize is {8, 16, 32, 64}.
0x770	0x20	Funcptrs for writing data: `n64MemDefaultWrite{bitsize}(unsigned int, ...)`, where bitsize is {8, 16, 32, 64} (32 uses `n64MemDefaultWrite32WithDestLog`). Unused by the plugin.
0x790	0x20	Funcptrs for reading data via the WithDestLog version: `n64MemDefaultRead{bitsize}WithDestLog(unsigned int)`, where bitsize is {8, 16, 32, 64}.
0x7B0	0x20	Funcptrs for writing data via the WithDestLog version: `n64MemDefaultWrite{bitsize}WithDestLog(unsigned int, ...)`, where bitsize is {8, 16, 32, 64}.
0x7D0	0x8	Funcptr: `n64CPU_CallLuaAfterInst(unsigned int, unsigned int)`
0x7D8	0x8	Funcptr: `n64CPU_CallLuaBeforeInst(unsigned int, unsigned int)`
0x7E0	0x8	Funcptr.
0x7E8	0x4	Array count for the the following array.
0x7EC	0x180 (0x20*0xC)	Array data with the above count, each entry is 0xC-bytes. The emulator loads this from config array "Idle". +0 = u32 emu_pc_addr (config "JmpAddr"), +4 = u32 instruction_value (config "JmpInst"), +8 = u32 is_idle (config "IsIdle", 0x1 = enabled).
0x96C	0x4	Array count for the the following array.
0x970	0x280 (0x20*0x14)	Array data with the above count, each entry is 0x14-bytes. The emulator loads this from config array "SpecialInst". +0 = u32 emu_pc_addr (config "Addr"), +4 = u32 instruction_value (config "Inst"), +8 = u32 flags. The emulator sets the flags to 0 by default, then compares config "Type" with various strings to determine the value. Flags: bit0 = Type "BreakLoop", bit5 = Type "LoadFrameBuffer", bit6 = Type "Lua_BeforeInst", bit7 = Type "Lua_AfterInst". When the config for {any of the previously mentioned Type strings} is set to value 1, the emulator will also enable the corresponding flags bit mentioned above. Likewise with config "Return", which sets flags bit8. When the plugin loads a funcptr from +0x790, it will load a funcptr from +0x750 instead if there's a matching entry here which has bit5 set.
0xBF0	0x4	Array count for the the following array. The plugin doesn't use this.
0xBF4	0x80 (0x10*0x8)	Array data with the above count, each entry is 0x8-bytes. The emulator loads this from config array "FrameBuffer". +0 = u32 (config "Addr"), +4 = u32 (config "Length"). The plugin doesn't use this.
0xC74	0x4	Array count for the the following array.
0xC78	0x180 (0x20*0xC)	Array data with the above count, each entry is 0xC-bytes. The emulator loads this from config array "SpecialBlock". +0 = u32 (config "BeginAddr"), +4 = u32 (config "BeginInst"), +8 = u32 flags. Flags defaults to 0. If config for "NoRunTime" is value 1, flags bit0 is set.
0xDF8	0x4	Set to 0 by default, then if available the emulator sets bit flags here depending on the content of the config for `"Cmp", "g_nN64CpuCmpTLBCheckLevel"`. Each bit corresponds to a mem-access instruction, when handling an instruction with a bit set TLB validation is done by generating code which calls the funcptr at controldata+0x710.
0xDFC	0x4	Set to 0 by default by the emulator. With config `"Cmp", "CodeMultiAddr"` this is set to 1. Config `"Cmp", "BlockDynamicPC"` from SM3DAS is not supported. The plugin doesn't use this field, since support for "BlockDynamicPC" was removed. All code which used to use this now assumes val!=2, with code for ==2 being removed.

SaveData

Account savedata has the following layout:

"/system-save.json": .json Emulator settings/etc, padded to size 0x10000 with 0x00-bytes.
"/saves/", containing sub-dirs with the same dirnames as romfs:/titles/, for games with savedata stored. These sub-dirs contain:
- "cartridge.sram": Savedata image for the emulated game.
- "suspendpoint{N}/": When a suspend-point exists, it has this dirname, where {N} starts with 1. This contains:
  - "state": #SuspendPoint
  - "state.png": Screenshot of the emulated game.

There's also TemporaryStorage savedata, which is used for storing #SuspendPoints used with network-transfers.

SuspendPoint

The SuspendPoint is stored in a mostly standard cpio archive with a modified cpio entry header:

Offset	Size	Description
0x0	0x2	Magic (070707 in little-endian octal)
0x2	0x2	Dev (0x3E16 or 0x0000 if trailer block)
0x4	0x2	Flags (0x1 means file data is zlib compressed)
0x6	0x2	Mode (unused)
0x8	0x2	Checksum
0xA	0x2	DecompFileSize1 (lower half of decompressed file size)
0xC	0x2	DecompFileSize2 (higher half of decompressed file size)
0xE	0x2	Rdev (unused)
0x10	0x2	Mtime1 (unused)
0x12	0x2	Mtime2 (unused)
0x14	0x2	NameSize (size of file name)
0x16	0x2	FileSize1 (lower half of file size)
0x18	0x2	FileSize2 (higher half of file size)
0x1A	NameSize	FileName
0x1A + NameSize	FileSize	FileData

Normally the file data is used raw, but it can also be zlib compressed if flags is 0x1. The cpio parser code calculates a checksum over each file (decompressed data when compression is enabled) by XORing each u16 in the file, then comparing it with checksum. The result is stored as a flag in the output cpio file entry structure. This checksum is only set for SuspendPoints, not RomFs data - none of the cpio parser callers currently validate the checksum flag.

This archive is stored in #SaveData, and is also transferred over the network with online-play-friends when the user loads a suspend-point in the GUI. This is also done automatically when a network session is created, for emu-sync-state. Emu-sync-state only used with session-creation, after that the only way to trigger suspend-point usage is via the suspend-menu GUI.

The SuspendPoint loader code loops through the file entries, comparing the entry file extension (following '.' in the filename) with various supported extensions and handling it as needed. No files are mandatory, there are no errors thrown for missing files. The order of the files in the archive doesn't matter either. The saved files have filename ".{extension}". The following extensions are handled:

"json": Contains various emulator state, including CPU/IO registers etc. "g_nN64CpuPC" is used with the g_nN64CpuPC global var. IO regs are copied to/from global state directly, without calling any IO handler funcs.
"bin": N64 DRAM. This has the field set for enabling zlib compression in the cpio file entry.
"sav": Savedata image for the emulated game.
"imem"
"dmem"
"cpk": Data for "Controller Pak", only exists for games which have config "SIDevice_PakType" set to "Controller Pak". The code loading this will skip it if the config wasn't set to "Controller Pak".
"gbin"

Versions

This section documents the game-update changes. Note that the below is for the non-JPN build of N64-NSO.

v1.1.0

ExeFs:

NPDM only had the usual ACID pubkey/signature update.
main: updated

RomFs:

"/bootapp/init.json": updated
"/resources/fonts/l-ko.fnt", "/bootapp/resources/fonts/l-zh-hans.fnt": updated
"/bootapp/resources/scripts/states/network/statesessionstartup.lua": updated
"/bootapp/resources/scripts/states/ui/stateingame.lua": updated
"/bootapp/resources/scripts/states/ui/statepause.lua": updated
"/bootapp/resources/scripts/sys/sysgamedetails.lua": updated
"/bootapp/resources/scripts/system/playreport.lua": updated
"/bootapp/resources/scripts/system/titlelistmanager.lua": updated
The localization data under "/bootapp/resources/strings/" was updated.
"/nro/libHovercraftJITPlugin.nro": Rebuilt, only changes were the buildid and the path in the .nrs had a string for "build" changed to "patch".
"/.nrr/": NRRs were updated/added.
"/Pipeline.cache": updated
"/shader_font_frag.spv": removed
"/titles/":
- "lclassics.titlesdb": Updated, entries were added for Paper Mario.
- Added directories "N-2992_e" and "N-2992_p", for Paper Mario.
- Updated "N-3030_e/N-3030_e.dtz" / "N-3030_p/N-3030_p.dtz" (Star Fox): the .cfg had a "VertexHack" entry added. Additionally for P-region, a new entry was added under .cfg "Idle" and the AOT NRO was updated.
- Updated "N-3038_e/N-3038_e.dtz" (E-region-only OOT): the .meta had a field for "NerdStreamFillRatio" added, following the line for "SndSampleRate".

v1.2.0