Hiscores_MiSTer/docs/nvram.md

Hiscores_MiSTer

nvram.v

nvram.v is a generic module for MiSTer arcade cores which enables high score save/load for cores in which the original system had NVRAM (or similar) save support.

Created by Jim Gregory (JimmyStones)

Features

• Saves high score data in <MRA name>.nvm dump (defaults to ioctl index = 4)
• Configurable pause padding around game NVRAM access
• Pause signal to halt CPU for during multiplex with cores already using dual-port RAM
• Scores are extracted every time OSD is opened into temporary buffer, if changed then they are copied to saveable data and auto-save is triggered (optional)
• Optional change mask can be supplied to ignore NVRAM areas to avoid unnecessary autosave events

History

0001 - 2021-10-05

• First marked release

0002 - 2021-10-09

• Add change mask support

Implementation instructions

• Add nvram.v to rtl/ folder and files.qip
• Add the following code to the main core .sv file.

// HISCORE SYSTEM
// --------------
wire [7:0] hs_address;
wire [7:0] hs_data_out;
wire hs_pause;

nvram #(
	.DUMPWIDTH(8),
	.CONFIGINDEX(3),
	.DUMPINDEX(4),
	.PAUSEPAD(2)
) hi (
	.*,
	.clk(clk_sys),
	.paused(pause_cpu),
	.autosave(status[27]),
	.nvram_address(hs_address),
	.nvram_data_out(hs_data_out),
	.pause_cpu(hs_pause)
);

The module parameters in the example above are the bare minimum config required to customise behaviour for a core. See Module parameters for further details.

Core specific implementation

NOTE: It is advisable to implement a working pause system beforehand so the pause_cpu signal can be used to pause the core while reading/writing to game NVRAM to avoid instability/corruption.

Add code to link the high score signals into the relevant NVRAM instances.

In simple cases (see Phoenix core for an example) this will only involve converting a working RAM instance from single to dual port.

Module parameters

Parameters should be configured to allow the high score system to cope with all games supported by the core. Maximum dump size, maximum number of entries and largest individual entry length need to be collated for all MRAs before selecting values.

Parameter	Description
DUMPWIDTH	Set to the width of the NVRAM memory used by the core.
DUMPINDEX	Optional override of ioctl_index used for nvram dump download (default is 4)
PAUSEPAD	Number of cycles to pause CPU before and after RAM access attempts (usually 0)

Module ports

Port	Direction	Description
clk	in	System clock. Should match the HPS IO clock input
reset	in	Active-high reset signal from core
paused	in	Active-high signal from core confirming CPU is paused
autosave	in	Active-high flag to enable autosave
ioctl_upload	in	From HPS module
ioctl_upload_req	in	From HPS module
ioctl_download	in	From HPS module
ioctl_wr	in	From HPS module
ioctl_addr	in	From HPS module
ioctl_index	in	From HPS module
nvram_address	out	System RAM address for NVRAM read
nvram_data_out	out	Data from NVRAM
pause_cpu	out	Active-high signal used to pause CPU
configured	out	Active-high signal used to mask autosave menu item if game has no hiscore configuration

MRA data

To enable the high score module, add the <nvram> section to the MRA with an index matching that specified in the DUMPINDEX parameter

<nvram index="4" size="256"/>

To enable change mask support, add a rom section with an index matching that specified in the CONFIGINDEX parameter. The hex content should represent the bitmap of the check mask required.

<rom index="3">
	<part>
		FF FF FF FF FF FF FF FF FF FF FF ...
	</part>
</rom>

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.