Developer Starter Guide

[SerErris]

Hi all,

after trying to get into Mister Development I believe it is time to create a Development Guide. We also would need a System Guide (how everything works) and a API/Implementation guide (which signals end up where and what they are used for).

Currently to my awareness non of that is available. So I decided I can help the most by now by creating such documentation step by step.

Step 1: Create a learning core based on Nand2Tetris Hack Computer. The benefit of the Hack Computer is, that it is very simple in terms of components (actually only has a CPU, Memory, ROM, Keyboard Input and Video output). At the same time it can use all of the functions on the DE10-Nano available for Mister Projects including the SDRAM, the ROM from SD-Card, Input/Output and of cause the CPU itself. It will be good to explain how to implement everything with a fully commented source code.

Step 2: From that derive the Development documentation for MISTER that describes everything in both worlds (e.g. how the framebuffer works, how the ROM loading process works), how the overall implementation is going to work.

Step 3: A API/System Documentation that describes all the signals and chips with its naming convention and what they are used for (kind of a firmware handbook for any normal computer with all call addresses etc. but now for hardware obviously).

I am looking for some people to support on that:

1. Someone who is willing to help me on Step 1 on implementing the Hack Computer and understanding all the required parts, so that I will be able to write a guide for that.
2. Someone to proof read/test
3. Anyone else who want to collaborate on this Step 1.

Step 2 and Step 3 will come later if I was successful in Step 1.

Please reach out to me if you want to help with this endeavour.

[SerErris]

One question for the beginning:

I will do this in VHDL. Is there any reason why the top file is verilog? Is it just because no one found the need to translate it into vhdl? In other words could I use a hack.vhd instead of the hack.sv (templated version)?

Has any core already a vhd implementation of the main file?

[Grabulosaure]

@SerErris

Here is a core with a top-level in VHDL :
https://github.com/Grabulosaure/Intv_MiSTer

ENTITY emu :
https://github.com/Grabulosaure/Intv_Mi ... v/intv.vhd

It needs to be updated with latest framework though.

[ethern0t]

I was asking similar questions a few days ago. Some things I've been able to figure out that might not be obvious to a newcomer:

1. Everything under sys/ is intended to be the same across all emu cores. Stuff in here is the OSD, dealing with inputs, and VGA and HDMI output.

2. sys/sys_top,v is actually part of this code. It controls several things like whether DDRAM or SDRAM are used by the core or not. It instantiates the 'emu' module and is essentially the high level glue code for MiSTer.

3. The 'emu' module is generally in an .sv file (like Arcade_Bagman,sv). That's where the high level logic unique to the core goes. This often contains a lot of glue if the core was originally ported from some other fpga board. It declares things like DIP switch settings and default filenames in CONF_STR.

3a. The 'emu' module also reads controller/keyboard inputs from the sys/ code and turns it into inputs appropriate for that emu core.

3b. The 'emu' module also instantiates generic video output. It seems like this level of the code still needs to know whether it's generating VGA (which is a direct signal) or it's generating HDMI (which I believe is written to the ARM shared RAM where the linux side scales it appropriately for display somehow).

[ethern0t]

Something I'd love to see, for the sake of understanding, is something super basic like composite or VGA video output to some GPIO pins and direct connection to a PS/2 style keyboard, but I think that's more of a "DE10 Nano" issue than a "MiSTer" issue.

What the MiSTer codebase gives us is a consistent, abstracted framework where people can implement a platform without having to manually implement HDMI, VGA, composite, PS/2 keyboard, USB keyboard, NES controller, SNES controller, generic USB controller, bluetooth controller, etc.

I also don't see why MiSTer couldn't be ported to a completely different fpga development board, either (well, switching to Xilinx might be tricky) -- extra logic and `ifdef checks would detect the new platform and none of the higher level core code would really know the difference other than maybe some clock rate adjustments?

(But the I'm not sure there's a real competitor to the DE10 Nano board in its price range with its feature set)

-Dave

[SerErris]

Okay, thanks guys, that is really helpful.

As said I am not looking to rework anything in sys ... and appreciate the input. that is a very good starting point.

Also consideration on porting mister to the next (maybe bigger platform) is just out of any reachable scope for me for now. I am happy if I start to understand how everything fits together and then documenting, what we have.

So @ethern0t are you coding in verliog or VHDL?

[ethern0t]

I was planning on coding in verilog (I've been programming professionally in C/C++ for 30 years) and the Steven Hugg book uses verilog... but most of the MiSTer cores are written predominantly in VHDL, so... haven't decided yet I guess.

Interestingly, the sample core, Template_MiSTer-master, is written in Verilog/System Verilog. That's actually the best place to start that I've seen, because as long as you stay out of the 'sys' directory it's very very simple but still demonstrates basic display capabilities. The nand2tetris example core somebody else posted yesterday is pretty easy to follow as well.

[Sorgelig]

One question for the beginning:

I will do this in VHDL. Is there any reason why the top file is verilog? Is it just because no one found the need to translate it into vhdl? In other words could I use a hack.vhd instead of the hack.sv (templated version)?

Has any core already a vhd implementation of the main file?

Weird question. Why it should be in VHDL? Not everyone likes the weird VHDL language. A lot of strange requirements. Weird syntax with logic values written as strings. Working with low level logic or arrays is a nightmare. You can't even add/subtract values without proper library. And if you decided to use math for unsigned vectors then you are out of luck to use math for std_logic as libraries conflict to each other. Pretty much cluttered unintuitive language.

[dshadoff]

A couple more things to watch out for:

VHDL:
- effectively no 'ifdef'
- shifting left or right is possible, but by the time you figure out which function and data types to use, you will prefer to brute force it another way

Verilog:
- assigning a smaller data value to a large data value (ie. a 4-bit value into a 6-bit register) may not give you a warning, but also won't likely align as you expected. Beware.

[Sorgelig]

- assigning a smaller data value to a large data value (ie. a 4-bit value into a 6-bit register) may not give you a warning, but also won't likely align as you expected. Beware.

It always assign to lower bits with extending 0 to unassigned bits. There is no other cases.
But verilog won't think for you - that's right

[SerErris]

I did not wanted to start a „which one is better“ it is to much objection and preference, than anything else.

But it answers my question somehow. As Sorgelig would not write anything in VHDL he never thought about doing it in VHDL.

From my perspective having more or less no knowledge about Verilog it looks to me very hard to read and difficult to understand.

Therefore having a VHDL template could remove a lot of friction in it as it will have no disruption in between.

Or should I consider to restart (MYSELF) in Verilog?

[Sorgelig]

I worked on many VHDL cores and modules. I have no problem to fix and improve them. Just i'm not going to develop core/module in VHDL myself.
It's not a problem to write the core in VHDL, but i strongly suggest to keep emu module in SystemVerilog. You don't have to learn Verilog in deep, but you need to understand it in general. Basic HDL concepts are common in different languages. One thing is preferred language, but you need to understand both if you want to develop in HDL.

[macro]

I like the fact that you can just mix them together (as long as you do it at the module level)

As pointed out verilog seems to be much easier to do math in, but it seems clunkier with some of the bit manipulation (all of the 1'd0 stuff originally confused me, but think I have it sorted now) and I prefer the if then conditional stuff in VHDL

basically I refer to other projects / opencores / google and use whatever they are written in, after a while you can think in both and it's just like switching between C++ / VB / Pascal / jquery etc. (that I have to do for the day job)

[SerErris]

Thanks for your input on this. I ordered a copy of Verilog by Example ... that should get me inside of it deep enough

You are right, the 1'd0 stuff confused me (now understood) and also that nothing is written out (e.g. Term ? option1 : option 2 ...) nice for typing bad for reading.

I also do not see any difference in the if then things. That exists pretty much the same in VHDL. VHDL just makes it automatically readable as it has no shortcuts of anything.

However we are no getting into a discussion I never wanted to do (in this thread) ... so I stop now

[Sorgelig]

HDL language needs some sort of size marking as traditional byte/word/dword is not enough. HDL operates by bits, not bytes. So 1'd0 is basically a single bit. Verilog unlike VHDL is more flexible and in many cases you can simply write 0 (or other number). It will be extended (if not ambiguous) to either 1 bit or 10 or 32 - depending on case.
Bit manipulations in Verilog is much simpler than in VHDL. I would say a miles simpler. Module with intense bit manipulation easier (and shorter) to write in Verilog/SystemVerilog than in VHDL.

[tacertain]

Did anything ever happen here? I'd be happy to help out - I'm just ramping up and looking for tasks to get into it.

If nothing happened with this, is there any documentation other than what's in the wiki? I thought I would tackle https://github.com/MiSTer-devel/Main_MiSTer/issues/403 as a way to do something small to start. I'm making my way through the OSD menu state machine code, and would love any overview that might make that journey shorter. I will write something up when I'm through it if there isn't already anything.

Thanks.

Andrew

[SerErris]

No nothing happend with it. I am now coming back to this myself.

What i am missing the most is good commented code, esp. for the mister framework.

For instance, there is a ready to use arcade_video.v file. But without the comments I do not understand what it does.

And I could also not find any other documentation on what it does. So I have issues to correctly understand and use it.