gbadoc
gbadoc copied to clipboard
gbadev-org
RFC: Naming Conventions
This was something discussed in the Discord yesterday, and there seemed to be a lot of differing opinions on it so I think it's good to decide on it ahead of time
What Naming Conventions (Registers, Functions, Hardware), Should We Use?
There's a couple options that were discussed
- Follow the "official" names, as used by GBAtek, libgba, etc.
- Create new names.
- What should the focus be?
- Can we ensure people who don't know the new names can find them using the old ones?
- Use anglicized names such as "Display Control", "Keypad Input", etc, and only use shortened names where brevity is required, i.e. links, or code.
Personally I don't have significant gripes with the official names, although there's a couple undescriptive names and misnomers.
Additionally, we would need to come up with new names for undocumented registers, although this can be decided on a case by case basis.
even if we use official names, there's no reason to not also spell out the pronounceable name
0x04000000 - DISPCNT - Display Control
However I think the main place where we can get an advantage in having a differing name is if we're splitting or combining registers from the way that GBATEK/CowBite/Whatever already describe them.
If we're simply going to use the same widths for each address that already exist in another document, we can just use what that document says.
More important than compatibility with other documentation is compatibility with existing header files, sdks, etc. like tonc and dkp.
It might be frustrating for people if that is strayed from.
Yes, I think it's entirely reasonable that if we provide alternate names that we'd require of ourselves to also provide a matching alternate header file to go with it.
even if we use official names, there's no reason to not also spell out the pronounceable name
0x04000000 - DISPCNT - Display Control
That's what I meant with the third point, although preferably in for example listings or table of contents, I would list them by their "full" name, i.e.
- LCD Screen 1.5 Display Control Register
However I think the main place where we can get an advantage in having a differing name is if we're splitting or combining registers from the way that GBATEK/CowBite/Whatever already describe them.
That's true, although I'm not sure how often this will come up other than fusing _L and _H registers
If we're simply going to use the same widths for each address that already exist in another document, we can just use what that document says.
I think that's slightly beyond the scope of this, but yes, register width will get its own discussion soon, since that was a similarly discussed topic
Yes, I think it's entirely reasonable that if we provide alternate names that we'd require of ourselves to also provide a matching alternate header file to go with it.
Unless dkp folks are on board, that would require people to drop the headers in themselves.
More important than compatibility with other documentation is compatibility with existing header files, sdks, etc. like tonc and dkp.
It might be frustrating for people if that is strayed from.
Sure, but tonc as an example already uses some different names.
That's true, although I'm not sure how often this will come up other than fusing _L and _H registers
I tried to visualize some of it today. There are some registers that you'd reasonably want to split into their individual bytes in some situations.
I think that's slightly beyond the scope of this, but yes, register width will get its own discussion soon, since that was a similarly discussed topic
I strongly disagree. You can't really talk about if the names should be kept / split / fused if you're not going to discuss the splitting / fusing part of things.
Unless dkp folks are on board, that would require people to drop the headers in themselves.
I genuinely have no knowledge of how hard that would make things for people. If it's it's just a 1 line fix that seems fine. If it's a huge honkin' deal then yeah we're basically stuck with what the DKP folks have decided on.
I think that the GBATEK names are the ones that should be used. In practice, they are the ones used everywhere. Not just documentation, but pretty much every project that has been created since GBATEK became a thing:
- https://github.com/mgba-emu/mgba/blob/d5138bf8854fb77b5998d4a6907a00b51b4ce269/src/gba/io.c#L15
- https://github.com/fleroviux/NanoBoyAdvance/blob/6299f4b571c27244fbb7503c614b745c2b67c79e/src/emulator/core/cpu-mmio.cpp#L18
- https://github.com/GValiente/butano/blob/3f6c05611ab1c3ca386cebc98f941988248620d3/butano/hw/3rd_party/libtonc/include/tonc_memmap.h#L278
And, while Tonc uses different names for the PSG sound channels, most people don't even use them, so that's not a real problem.
Also, the aim of devkitPro is "we want to unify everything and have the standard homebrew toolchains and libraries", so I really doubt they'd like this initiative of renaming everything when there is already a well-established convention. There's nothing stopping others from doing what they want in their own projects, but I am 100% sure that it would be impossible to get them to agree to change the names in the libgba and libtonc included in devkitPro.
This seems to be agreed upon pretty unanimously, will close this if there's nothing else anyone would like to add
everyone seemed to be largely on the side of "stick to gbatek/libgba names"
I guess the question of fusing/splitting remains but I didn't see much input on that aside from you :s
Yeah, and we also don't need to resolve it immediately. There's quite a bit to describe without mentioning a single IO register