Difference between revisions of "Nintendo 64 - Nintendo Switch Online"

From Nintendo Switch Brew
Jump to navigation Jump to search
Line 147: Line 147:
  
 
= SuspendPoint =
 
= SuspendPoint =
The SuspendPoint is stored in a mostly standard cpio archive. The magic is little-endian octal 070707. Normally the file data is used raw, however when u8 cpio_entry_header+0x4 (c_ino) is 0x1 and +0x5 is 0x0, the file data is zlib compressed. 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 u16 cpio_entry_header+0x8 (c_uid). 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.
+
The SuspendPoint is stored in a mostly standard cpio archive with a modified cpio entry header:
 +
{| class="wikitable" border="1"
 +
|-
 +
! 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.
 
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.

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

ExeFs:

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

RomFs:

  • "/bootapp/init.json": updated
  • "/bootapp/resources/fonts/": "l-dynamic.fnt", "l.fnt", "l-ko.fnt", "l-zh-hans.fnt", "l-zh-hant.fnt" updated
  • The localization data under "/bootapp/resources/strings/" was updated.
  • "/nro/libHovercraftJITPlugin.nro": updated
    • A func was stubbed to just "return;". The func immediately after that had code checking the instruction_id adjusted.
  • "/.nrr/": NRRs were updated/added.
  • "/Pipeline.cache" and "/shader_p1_frag.spv" updated
  • "/titles/":
    • Updated "lclassics.titlesdb" and added "N-4868_e/" + "N-4868_p/".