RFC: Scope of the document

[avivace]

This RFC marks the start of a community initiated effort in researching and documenting the GBA architecture. Our goal is to produce something similar to Game Boy's Pan Docs.

• Open Source/Public Domain (https://github.com/gbdev/gbadoc/issues/3)
• Easily editable and improvable by anyone (Markdown, RST) (https://github.com/gbdev/gbadoc/issues/2)
• Easily navigable/searchable HTML as primary final render target

Some basic points to decide on:

1. What's the objective of the project? Which parts of the GBA hw/sw should be covered in a first minimal subset of essential topics?
2. What is the target? Emulator developers or Homebrew developers?
3. How are we gonna prove the stated facts?
4. Should we use another document as baseline? (E.g. ask nocash to release GBATEK under a permissive license)

[AntonioND]

1. I think that everything. We can split the documentation into folders and chapters as needed so that it's easier to navigate.
2. I think that both? I don't think we know the GBA to a deep enough level to make a big difference.
3. I guess we could have a folder with test ROMs for some things. However, this has the potential to become a problem if we end up having too many test ROMs.
4. I think there's no harm in asking, mostly so that we can start by copying register tables, address maps, and things like that. However, it's not a big loss if we don't get them.
5. We should see if we can have copies of useful documentation like the ARM ARM instead of having what essentially is a copy of the content (what GBATEK does).

[quentin-dev]

4. I think it'll be easier to have another document as a baseline from which we can "trim the fat": mark sections as unverified or wrong, clearly mark other sections as WiP, and others as "factually acturate" with links to the test roms and whatnot.

I agree with what's been said before on points 1-3.

[LunarLambda]

tl;dr I agree with everything said above.

My personal thoughts and hopes:

1. I think there are 3 main goals to strive for:

   • Accuracy: Make it clear what is definite, what needs further research, and what is unknown. I think a dedicated spot for things that fall in the latter 2 sections would be quite good.
   • Accessibility: Providing guides for the editing and review process, offline access, possibly even a way to get plain text? Also things like searchability, sectioning things sensibly.
   • Comprehensiveness: Cover as much useful information as possible while maintaining the above.

2. Both! I assume this point is roughly about being a technical reference versus being a programming guide. Ideally we would structure these such that they supplement one another. People should be able to go from one to another without hitting a wall because information is contradicting or oversimplified/overcomplicated.

3. We don't really have many options other than test/demo ROMs, I think. I assume that information gathered through reverse engineering / leaks will be a no-go if there is no other way to verify things.

4. Things like CowBite and GBATEK (if given permission) would be good starting points, however we should avoid copy-paste jobs. Even if information is already totally correct, rephrasing and better formatting cannot hurt. Copies of official documentation (like ARM manuals) would be good too. Maybe we can even ask Nintendo to open source the GBA SDK? :stuck_out_tongue_closed_eyes:

[fleroviux]

What's the objective of the project? Which parts of the GBA hw/sw should be covered in a first minimal subset of essential topics?

I think we should aim to document the GBA hardware with more clarity, depth and accuracy than existing docs like GBATEK or CowBite Spec in an easily accessible and editable format. To properly document the hardware, we should attempt to document the exact what and why of some behavior and not just the commonly observed behavior (see Reading from Unused Memory as a bad example).

For a first version I would suggest leaving the CPU out (link to the official data sheets instead) and focusing on memory layout, IRQ management, DMA, timers, PPU and APU. We should probably leave out any edge cases or special behavior for now and focus on a functional overview first. Details can be added later.

What is the target? Emulator developers or Homebrew developers?

Both. Maybe we can mark information in the document that is mostly relevant to emulator devs and generate a cutdown version for homebrew devs out of this?

How are we gonna prove the stated facts?

I think it's very important to prove what is being stated, but it will be virtually impossible to prove everything. I would therefore suggest that we provide test ROMs for non-trivial information only (example: alignment of timer ticks to the system clock, DMA latching / open bus behavior etc).

Should we use another document as baseline? (E.g. ask nocash to release GBATEK under a permissive license)

We can't really avoid referencing GBATEK I think, but to make sure the document is clean and up to our standards we will need to rephrase and filter the info nonetheless. So I'm not sure if using GBATEK as a direct base will benefit us a lot, but of course clearing out any licensing issues upfront is a good idea anyways.

[Lokathor]

In the first version it's fine to say "also these are edge cases here if you do it differently, but if you stick to this prescribed way of doing it like this then it works fine."

[quentin-dev]

Follow-up on 4, Tom Happ, creator of CowBite + CowBite spec has given us his permission to "do whatever we want" with CowBite spec.

[LunarLambda]

Is this RFC gonna stay open more long term since it's a very broad topic? Should we update the initial comment to list the remaining open questions?

[Lokathor]

we should update the first post with conclusions on what we can and move to follow-up issues for the parts we can't conclude on, which helps keep discussion focused.