Support the concept of SYSINFO

[sy2002]

Portability is one of the initial and big goals of QNICE-FPGA.

When thinking about porting QNICE-FPGA to multiple hardware platforms such as the following, then it becomes clear, that not every platform is as powerful (or as "weak") as the Artix-7 based platforms:

• Nexys 4 DDR
• MEGA65
• A silicon QNICE processor (which might have less than 256 register banks)
• DE-10 board, because it is a cheap starter kit which might inrease our fan-base at universities and the likes
• Bernd's mini FPGA boards for university and breadboard usage

Therefore at various places, we need to support the concept of SYSINFO:

• Constant definitions for "everything" (**) in env1_globals.vhd: When tackling this isse we should rename this and have only one globals file for all officially supported platforms (right now: Nexys, MEGA65) were we use a generic variable to tell the globals file which platform is active. This helps to reduce the "zoo" of files (as described in issue #41)

• Hardware register(s) to ask for the hardware's capability

• Constants and bit masks in sysdef.asm

• Convenient monitor function that prints everything it in human readable form and monitor command to use this function

• Unification of the PORE boot message files because the boot message per platform would also be part of the new globals file (this also helps in the sense of issue #41)

about (**) "everything": There are a lot of these things and we need to invest a bit more brainpower to identify them all:

• Identifier of the hardware we are running on, so that software can change its behavior accordingly: Nexys, MEGA65 - but also: "Running on emulator right now" (the latter one is quite important for features, that are currently missing in the emulator, such as scanline interrupts)
• Amount of register banks (256 by default)
• Amount of RAM
• Amount of ROM
• Amount of pages in scroll back buffer (20 by default)
• Amount of sprites (128 by default)
• MMU present
• Range of supported UART baud rates
• etc.

[MJoergen]

Since the amount of information to be provided can potentially grow very large, I propose an indirect addressing scheme. In other words, a simple I/O module with the registers:

SYSINFO$ADDR .EQU 0xFFE8  (R/W)
SYSINFO$DATA .EQU 0xFFE9  (RO)

The user writes the desired address into 0xFFE8 and then reads the value from 0xFFE9.

Suggested contents:	Address	Name	Description	Example (Nexys4DDR)
0x0000	SYSINFO_HW_PLATFORM	Hardware platform enumeration	SYSINFO_HW_NEXYS4DDR
0x0001	SYSINFO_CPU_SPEED	Main clock frequency (in MHz)	50
0x0002	SYSINFO_CPU_BANKS	Number of register banks	256
0x0003	SYSINFO_RAM_START	Start address of first word in RAM	0x8000
0x0004	SYSINFO_RAM_SIZE	Amount of RAM (in kilo-words)	32
0x0005	SYSINFO_GPU_SPRITES	Number of sprites supported	128
0x0006	SYSINFO_GPU_LINES	Number of lines in GPU screen buffer	800
0x0007	SYSINFO_UART_MAX	Maximum baudrate supported by UART (in kb/s)	1000
0x0100	SYSINFO_CAP_MMU	Nonzero if a built-in MMU is present	0
0x0101	SYSINFO_CAP_EAE	Nonzero if a built-in EAE is present	1
0x0102	SYSINFO_CAP_FPU	Nonzero if a built-in FPU is present	0

Suggested values for SYSINFO_HW_PLATFORM	Value	Name	Description
0x0000	SYSINFO_HW_EMU_CONSOLE	Emulator (no VGA)
0x0001	SYSINFO_HW_EMU_VGA	Emulator with VGA
0x0002	SYSINFO_HW_EMU_WASM	Emulator on Web Assembly
0x0010	SYSINFO_HW_NEXYS4DDR	Nexys4DDR board
0x0020	SYSINFO_HW_MEGA65	MEGA65 board
0x0030	SYSINFO_HW_DE10NANO	DE 10 Nano board

[sy2002]

Sounds great! I suggest to differentiate the board revisions: Nexys4DDR - "our board" is already deprecated, this is the successor: Nexys A7-100T: https://store.digilentinc.com/nexys-a7-fpga-trainer-board-recommended-for-ece-curriculum/ There is also a 50T, but I guess the 50T FPGA is "too small" for us?

And about MEGA65: There are different board revisions out there. I am owning a R2 (that does have a certain HDMI chip) and R3 will be different. So here is my proposal for a slightly adjusted table for SYSINFO_HW_PLATFORM

Value	Name	Description
0x0000	SYSINFO_HW_EMU_CONSOLE	Emulator (no VGA)
0x0001	SYSINFO_HW_EMU_VGA	Emulator with VGA
0x0002	SYSINFO_HW_EMU_WASM	Emulator on Web Assembly
0x0010	SYSINFO_HW_NEXYS	Digilent Nexys board
0x0011	SYSINFO_HW_NEXYS4DDR	Nexys 4 DDR
0x0012	SYSINFO_HW_NEXYSA7100T	Nexys A7-100T
0x0020	SYSINFO_HW_MEGA65	MEGA65 board
0x0021	SYSINFO_HW_MEGA65R2	Revision 2
0x0022	SYSINFO_HW_MEGA65R3	Revision 3
0x0030	SYSINFO_HW_DE10NANO	DE 10 Nano board

The basic idea is: There is a generic info that it is a Digilent Nexys board, so that software that is supposed to run on both boards does not need to check for 0x0021 and 0x0022 but only for 0x002*. The same for the MEGA65. Same for emulator: If you check for 0x000* then you know you're on the emulator.

[MJoergen]

@sy2002 : Excellent idea!

[MJoergen]

I've now added support for SYSINFO to the hardware and to the emulator.

I've made a small test program sysinfo.c that prints the contents in a user-friendly style.

This should be documented somewhere. Any suggestions where?

[sy2002]

@MJoergen This is cool stuff! Thank you! 😃

• Added a documentation stub: file doc/sysinfo.md: Please turn the stub into a documentation and fill in all your info.
• Added a bullet point in the "Basics" sectiopn of doc/README.md with an @MJoergen please fill this stub. so that readers who read about the basics of QNICE-FPGA at least can read a few sentences of a summary.
• Added a link from our "list of all documentation" that goes to the newly made doc/sysinfo.md (just fyi, no TODO for you)
• A a sentence to our best-practices documentation that it is a best practice to check SYSINFO in your software. (just fyi no TODO for you)

One more thing: At least in the emulator it can happen (and maybe also in future "smaller" hardware boards) it might happen, that there is no VGA at all present and no USB keyboard. You might want to add the checks for that to SYSINFO and your test program, too.

[MJoergen]

Done!

[sy2002]

@MJoergen Truly great job! Love it! ❤️ 👍

I outsourced some smaller left over TODOs from https://github.com/sy2002/QNICE-FPGA/issues/101#issue-690860200 to issue #41, so we can close this one now.