1 (edited by WoS 2013-11-09 14:06:23)

Topic: Howto: writing INI files

This post explains the main functions of the config reader I implemented. It is not yet complete and thus work-in-progress (so there are already more things implemented not described yet).
I also kept the descriprions quite brief for now...


The ini setup has to be prepared by the developer of a Replay target core.
- As user, do NOT modify any settings until adviced to do so (e.g. famous "overclocking")
- Developers should think twice when using e.g. non-standard PLL settings

Especially bad timing setups may cause overheating or bus collisions which could (even slowly) damage board components. Feel free to contact me or Mike if special setups are needed.

Ok, you have been warned, let's get down to business...


Ini files are read by the Replay loader to set up the board. On power-up, the Replay loader looks for a file called "replay.ini" in the root directory of an inserted SD-card and processes it. It contains further information like what FPGA configuration file should be used and how the hardware has to be initialized. It can be also used to set up a menu system for the user to allow further settings once a design is set up on the FPGA.

Furthermore, the very same format is used to save user settings after modified in the OSD menu.

The INI file is a plain ASCII file and can be edited with any text editor. Please don't mix it with Windows ini files, although it uses a very similar syntax:

# this is a comment


keyword1 = value1 , value2 , ... 

keyword2 = "text value with blanks", 12345 , text_avoiding_blanks , ...

# another comment

# Supported decimal numbers:
# ----------------------------------
# 12345 decimal value (base 10)
# 0x123 hexadecimal value (base 16)
# 01234 octal value (base 8)
# *0101 binary value (base 2)

Section: [SETUP] (pre-FPGA-configuration)

BIN = fpga_config_file.bin

Points to the FPGA configuration file to load. It must be located in the same directory of the ini file.

INFO = "some information"

Allows to post some user information on the OSD status screen.

CLOCK = <clock_params>

Basic PLL setup. It allows to use pre-defined settings (for standard video modes) or a parameter setup.

<clock_params> can be one of this options:

  • PAL
    113.5MHz  for y0 (SYSCLK)
    17.73MHz  for y1 (Coder)
    49.152MHz for y2 (AUDCLK)
    disabled  y3 (Expansion Main)
    27MHz     for y4 (VIDCLK)
    disabled  y5 (Expansion Small)

  • NTSC
    114.5MHz  for y0 (SYSCLK)
    14.32MHz  for y1 (Coder)
    49.152MHz for y2 (AUDCLK)
    disabled  y3 (Expansion Main)
    27MHz     for y4 (VIDCLK)
    disabled  y5 (Expansion Small)

  • HD74
    114.5MHz  for y0 (SYSCLK)
    disabled  y1 (Coder)
    49.152MHz for y2 (AUDCLK)
    disabled  y3 (Expansion Main)
    74.25MHz  for y4 (VIDCLK)
    disabled  y5 (Expansion Small)

  • M1,N1,M2,N2,M3,N3,ps0,ps1,ps2,ps3,ps4,ps5,pd0,pd1,pd2,pd3,pd4,pd5,ys0,ys1,ys2,ys3,ys4,ys5
    M,N ... three PLL are setup by 27MHz * N / M (must be within 80...250MHz)
    ps ... selects one of the three PLL as source for the six outputs
    pd ... divider factor for each of the six outputs
    ys ... enable for each of the six outputs


Enables SVHS/composite video output coder (if fitted on the Replay board and if it
matches to the video mode generated by the loaded core).

<norm> can be one of this options:


  • PAL

  • NTSC



VFILTER=<p1>, <p2>, <p3>

Sets the analogue video filter bandwidth and DC level for all 3 channels.
(Relevant for DVI-A/VGA and Composite/SVHS).


Notifies that the FPGA configuration routes the i2c lines for further
video configuration by the ARM. <twi> has to be 0 or 1.


Notifies that the FPGA configuration uses the spi lines for further
configuration <cfg> and OSD video <osd> by the ARM. <cfg> and <osd> has to be 0 or 1.


Sets the SPI clock speed, be aware that SPI is also used for the SD-card, reducing it
slows file access, too fast may not allow to use the SD-card at all.
Details on <value> will follow...


Configures the behaviour of the button on the replay board.

<mode> can be one of this options:

  • OFF

  • MENU


Section: [SETUP] (post-FPGA-configuration)


Video DAC configuration settings (16 bytes). <twi> must be 1 on EN_TWI to use this keyword.


Initial setup of 32 static and 32 dynamic bits set in the FPGA syscon module. <cfg> must be set to 1
on EN_SPI to use this keyword. It can be changed later in the configurable menu system.

Section: [UPLOAD] (post-FPGA-configuration)


Enables verification feature, reads back and verifies any ROM/DATA upload when <ver> is set to 1. Otherwise
upload is done "blindly".


Defines a ROM upload. <cfg> must be set to 1 on EN_SPI to use this keyword.

Section: [MENU] (post-FPGA-configuration)


Define a new menu page with a given title.


Define a new menu entry with a given name and bitmask.

OPTION="string",<value>, default

Define an additional option for a menu entry which can be selected.

Special menu item: file stream upload

ITEM="string", loadselect, <startadr>

Define a new menu entry which allows the user to browse for a file with extension "EXT" and upload
to a given FPGA adress. Optionally, if <verify> is set to 1, it will also perform a second run reading the
FPGA data back and check it against the selected file again. The FPGA must handle the data properly,
so compute them byte by byte on upload and send the exact stream back (when verification is enabled).
The option string must be always "*." + extension, everything else will not show the menu item.


Re: Howto: writing INI files

Nicely done!

Re: Howto: writing INI files

Indeed,  well documented.
I suggest I lock just your post here and then weunlock if if you want to update it?
Or shall we allow comments?

Re: Howto: writing INI files

Thanks! I did want to write it down a while ago, especially as I also start to forget details smile

I think comments & questions are fine, as long as it is about the INI structure. If there is more discussion about a specific feature required, I suppose you can still shift it to the proper section, Mike?

I'll refine it in the next days when I do another walk through the code...


Re: Howto: writing INI files

Wolfgang, or Mike, can you please elaborate a bit where the "coder" clk is available in the replay_top? I'd like access to the NTSC 14.32Mhz clk to get a 3.58Mhz for the Atari2600.

6 (edited by WoS 2014-06-12 17:28:41)

Re: Howto: writing INI files

You should take a look at the "simple" block diagram I stored in the SVN at "<svn_root>/src/docs/Replay_Blockdiagram_1.02B.pdf", which gives you an overview of the board hardware.

The PAL/NTSC coder is an IC, it will only exist if you have a board with composite/SVS connector assembled. Has nothing at all to do with the FPGA part, it is controlled via ARM and just generated the composite signal out of the RGB values from the video DAC plus the sync signals from the FPGA. Furthermore, the color (burst) clock needs to be supplied by the PLL (its the y1 output directly set there), which is also controlled by the ARM.

On FPGA side, a proper "interlaced" video mode needs to be generated by the video generator of the replay_lib (e.g. c_Vidparam_720x576i_50 for PAL or c_Vidparam_720x480i_60 for NTSC). Or the core directly generates such a timing plus the RGB signals for the video DAC. You can check the replay loader video generator to see how this video DAC signals must look like. When done properly, you get HDMI support for "free" as well (see Galaga, Phoenix, VIC-20 and C64 core, which support all modes via the replay video generator and syncing the core to it).

If you want to use this 14.32MHz clock also for your core, you can't directly use the y1 pin from the PLL. You need to generate a multiple clock on y0 instead, which must be >25MHz when divided by four (as you need an internal FPGA clock higher than the SPI clock from ARM side). E.g. 14.32*8=114,56MHz, which corresponds to the "CLOCK=NTSC" setting.

Then you can use a clock-enable divider after the sysclk (which is :4 of PLL clock) by 8, which will be (114.56/4)/8 = 3.58MHz.


Re: Howto: writing INI files

Ah cool, thanks smile I didn't discover the x8 relation to the 114.56Mhz sysclk...

Re: Howto: writing INI files

Is there a way to tell the loader to load rom's to the top, or duplicate the data into a "chip select" area?
For the Atari 2600, the cartridge mem seems to start at 0xe000 (it has no internal boot rom), but the roms vary in sizes. Since smaller rom's gets duplicated to fill the whole chip select area, it would be nice to emulate that, cause the 6502 gets its boot vectors from the top.

Re: Howto: writing INI files

Not sure if I understood the question. The ARM loader does not care about addresses, it just takes what it finds in the ini and sends the content of the file using this adress as start point (and increments it with each byte from the file).

Decoding is done on the FPGA using the memory bus from the fileio block, so decoding can be done in any way you like. By default (in the loader "reference design"), it is connected to the DRAM controller LP channel, so it loads eveything there up to 16MB.

Basically I'd say it is more the issue of the core, which leaves out the addresses not used generating automatically this mirror effect during access. This is more efficient than using twice the real memory and doubling the upload...?

The core could also detect by itself if an upload did stop on e.g. a 4k or 8k boundary and enable mirroring (which means ignoring a certain cpu address line from core side) automatically.

E.g. the range is "$e000 to $e7ff" and "$e800 to $efff"; Then the core will enable mirroring with a fileio upload (write) to exactly address $e000 and disabling mirroring as the fileio upload (write) access is exactly $e800 (which would not happen if upload stopped at $e7ff or less, which means a smaller cartridge). This is much more flexible and robust than a ARM specific setup...



Re: Howto: writing INI files

I was thinking of doing that size detection but it sounded so easy to do in the loader. Then again, I have no overview of the loader code smile


Re: Howto: writing INI files

Will be complicated to specify (and also parse by the ARM) in a "generic way" for an INI entry using the OSD-based uploader. What I could think of is to specify the start address and the length to load in the ini for the upload menu feature and the ARM starts over the upload of the very same file until the given length in byte is finally transferred to the FPGA.

This would require that e.g. files to upload must be exactly 4k if the given size is 8k to load the file twice, one after the other. This would be an easy to implement option. Otherwise it won't be so easy to cover all possible (and impossible) scenarios I (maybe can't) think of...

In case you just want to use fixed loader lines in the ini (of given files, w/o OSD selection), you can set it up as Mike did in the Amiga core (just specify the loader lines twice with the same filename and the two start addresses which should be mirrored).



Re: Howto: writing INI files

I came up with this neat solution to the issue mentioned above:
if(CONF_WR='1') then
    if(CONF_AI=0) then
        cart_mask<=cart_mask or CONF_AI(13 downto 0);
    end if;
end if;
This will mask out the mem adress bits not ever written to by the loader. Any mem size will be at the top, with copies under it in binart sized chunks of course.


Re: Howto: writing INI files

Yes, that's nice!

I use a similar mechanism when downloading d64 files to RAM to notify the floppy hardware that a disk change happened. It also invalidates the media as long as not the whole d64 data was uploaded by additionally checking the last write address (as absolute value).


Re: Howto: writing INI files

How to setup the PLL when I need SYSCLK to be n*14.000MHz exactly?

Re: Howto: writing INI files

Are you using the video converter or you just need the system clock xx? I would suggest 28MHz then use 1 in 2 enable?
You can always do something along the lines of 27 x 28/27 to get 28MHz. The PLL has to be in it's comfort zone, so probably run at 4x28 then use a /4 on the output of the pll.

n1 = 4 x 28, m1 = 27, d0=4

Re: Howto: writing INI files

Long time no Wolfgang, where are you at?

17 (edited by JimDrew 2014-09-02 22:37:03)

Re: Howto: writing INI files

I think he is on vacation.

Re: Howto: writing INI files

aha ok, i thought he lost interest, let's hope not!

Re: Howto: writing INI files

He is all fired up again having received a whole box of retro ICs from China wink


Re: Howto: writing INI files

I came back from vacation and caught something, currently in bed sad
When I am back alive, I'll have to catch up with my regular office work first, then I'll of course continue here as well.

Still a lot of tasks on my list and even new Replay projects (e.g. a Beeb core). Just bought a JAMMA cocktail table I want to see the Replay in. O yes, and I really would like to rework the whole ARM setup as well (which includes improving the INI setup and include wishes/requirements I catched in all the posts) wink


Re: Howto: writing INI files

I hope you feel better soon!