Needs better documentation

[oriansj]

No description provided.

[siraben]

What sort of things are missing?

[oriansj]

Answers to questions that a new person might have when they first find this git repo.

So the biggest thing I need help with is a list of questions people might have. (I am more than happy to provide the answers)

I am too familiar with the code to spot the sort of things that might trip up a new person and need to know the sorts of questions they might have and want clarified.

[Banyc]

@oriansj I do have some questions:

• What is the difference between the repo name "stage0" and the "Need to know information > stage0" in README.org?
• Why hex0, hex1, hex2, M0 are not part of stage0?
• What are the differences Hex0_monitor makes if we already has a hex0 compiler?
• What are the differences between hex0_riscv64.hex0, stage1/stage1_assembler-0.hex0, and stage0/stage0_monitor.hex0? Why?
• What is the purposes of stage0, stage1, ..., etc., respectively?
• If I'm the computer, what should I do to proceed the full process?
• What is the ISA of stage0_monitor.hex0? x86 or RISC-V?

[oriansj]

Hopefully this: https://github.com/oriansj/stage0/blob/master/questions_asked_by_new_people.org is sufficiently clear.
Please let me know what isn't completely clear and if you have any more questions and most of all thank you for sharing your questions. ^_^

[zakm]

Is there a guide for the comment syntax in, eg. the hex0_riscv64.hex0 file?
With some study the current format is mostly understandable but was not something I as an outsider was expecting. For example the first two instructions:

13 0A 00 00    # RD_S4 MV                 ; Initialize register
03 36 01 01    # RD_A2 RS1_SP !16 LD      ; Input file name

I would expect instead to be something similar to:

13 0A 00 00    # LI S4, 0                ; Initialize register
03 36 01 01    # LD A2, 16(SP)           ; Input file name

[oriansj]

well yes. https://github.com/oriansj/stage0-posix-riscv64/blob/master/riscv64_defs.M1 and https://github.com/oriansj/stage0-posix-riscv32/blob/master/riscv32_defs.M1
and the reason for the ordering, it is because of the order of bits in RISC-V instructions and we wrote the code in M1 macro assembly prior to writing the hex0 as it allows 1:1 mapping which we learned wouldn't be the case with GAS instructions.