[PCE] Add new platform. #121

asiekierka · 2023-06-18T13:07:21Z

The PCE platform corresponds to the NEC PC Engine, also known as the TurboGrafx-16 in the US. It is an interesting target for llvm-mos due to its particularly fast (7.16MHz) 6502 CPU, as well as large (up to 1MB; up to 8.5MB with extra mapper logic - not implemented here) ROM size and flexible banking.

The pull request will be marked as ready once I've collected enough feedback on it. Feel free to comment on what's already here, though - I'd be more than happy to receive feedback!

TODO (for this PR):

Provide a solution for banking.
Provide a solution for interrupt handling, modeled after the NES target.
Add just enough VDC/VCE functions to allow bringing up a screen. Maybe.

Prerequisite PRs:

Fix HuC6280-related assembler bugs in llvm-mos. => waiting on Fix ELF relocation and relaxation for multi-operand 65C02/HuC6280 opcodes. llvm-mos#304
Add custom output format bounds support. => waiting on Add bounds support to lld custom output formats. llvm-mos#306 (required for >8KB fixed bank)
Add llvm-mlb support. => waiting on Add PCE platform support to llvm-mlb. llvm-mos#305

Documentation: https://llvm-mos.org/wiki/PCE_target

Banking is not yet implemented, so limited to eight-kilobyte ROMs. This will be improved soon...

- Provide missing one-bank getters and setters. - Use C where using ASM provides no "bank chain" size advantage to allow for inlining opportunities.

…KB vbanks.

…SIZE define

mysterymath · 2023-06-21T02:43:15Z

The PCE platform corresponds to the NEC PC Engine, also known as the TurboGrafx-16 in the US. It is an interesting target for llvm-mos due to its particularly fast (7.16MHz) 6502 CPU, as well as large (up to 1MB; up to 8.5MB with extra mapper logic - not implemented here) ROM size and flexible banking.

The pull request will be marked as ready once I've collected enough feedback on it. Feel free to comment on what's already here, though - I'd be more than happy to receive feedback!

TODO (for this PR):

Provide a solution for banking.

Provide a solution for interrupt handling, modeled after the NES target.

Add just enough VDC/VCE functions to allow bringing up a screen. Maybe.

Prerequisite PRs:

Fix HuC6280-related assembler bugs in llvm-mos. => waiting on Fix ELF relocation and relaxation for multi-operand 65C02/HuC6280 opcodes. llvm-mos#304

Add custom output format bounds support. => waiting on Add bounds support to lld custom output formats. llvm-mos#306 (required for >8KB fixed bank)

Add llvm-mlb support. => waiting on Add PCE platform support to llvm-mlb. llvm-mos#305

LMA setup:

Bits Description
31 - 24 Group. 0x00 => base PCE address space; 0x01 => PCE card RAM address space (CD-ROM, Populous); 0x02 - 0x11 => "Street Fighter 2" mapper address space
23 - 16 Bank. For group 0x00: 0x00 - 0x7F => ROM, 0xF7 => CD backup RAM, 0xF8 => RAM, 0xF9 - 0xFB => SuperGrafx RAM, 0xFF => I/O. For group 0x01: 0x40 - 0x5F => RAM (Populous), 0x68 - 0x7F => RAM (Super System Card), 0x80 - 0x87 => RAM (PC Engine CD). For groups 0x02-0x11: 0x40 - 0x7F => ROM.
15 - 0 VMA

Is there a quick write-up I could read on the semantics of the vbank system? It would be useful to have documentation of the form avaiable on the Wiki for the NES targets; this would make it much easier to review this, and should help folks build a mental model of how the target works.

E.g. see https://llvm-mos.org/wiki/NES_targets

mysterymath · 2023-06-21T02:49:26Z

mos-platform/pce/libpce/src/memory.S

+.global pce_memmove
+.global pce_memset
+
+    .section .text.pce_rmemcpy, "ax", @progbits


For the little self-modifying assembly I've written in llvm-mos, I just wrote an assembly language routine, and added labels to each instruction to be modified, but placed it in .data rather than .text. Then, another routine (or itself, I suppose) can use those labels to adjust the routine, then simply jump to it. This minimizes the overhead of calling the routine, since only the portions that change between calls are overwritten, and the result is very readable, being actual assembly.

Six of the eight bytes are caller-provided; as such, I believe the performance gain from doing so would be marginal (especially as the routine is laid out in such a way that - at least for memcpy() - two of the six caller-provided bytes are already in the right place at the moment of call), while the RAM use would increase by eight bytes (and we only have 8KB!).

rmemcpy() is a little more complicated as it has to set operands source + length - 1, destination + length - 1, length; rather than source, destination, length; likewise, memset() is a little more complicated as it has to set the first byte manually, then set operations destination, destination + 1, length - 1.

In addition, pce_memop() (which exists to allow access to the alternate transfer modes Increment Alternate and Alternate Increment - see memory.h) uses the opcode as a type operand (there are five variants total) - which would itself prohibit it being "very readable assembly".

The "ideal" way I'd like to resolve this is to emit the block copy instructions (TII/TDD) at the compilation stage if all the operands are known, minimizing the usage of these routines.

It could also be worthwhile to move some of the operand computation to C and rely more on pce_memop() itself, taking advantage of LLVM's optimization passes - but this is out of scope for this PR, which is meant to provide basic functionality.

asiekierka · 2023-06-21T14:28:54Z

Initial wiki page: https://llvm-mos.org/wiki/PCE_target

asiekierka · 2023-06-21T16:00:20Z

Okay, I'm done with this PR for now.

Note: While the target appears generally stable, I can't promise the lack of short-term API breakage as more veteran PC Engine developers look into it and provide their two cents. At the same time, I'd rather wait for the existence of some kind of binary builds to ask a wider audience to look into it, as to not ruin a first impression - I could provide my own, of course.

mos-platform/pce/libpce/include/pce/hardware.h

mos-platform/pce/libpce/include/pce/system.h

mysterymath · 2023-06-23T22:55:10Z

mos-platform/pce/libpce/include/pce/vdc.h

+ * @brief Set the VDC's copy method to copy every row.
+ * Alias for @ref pce_vdc_set_copy_word .
+ */
+#define pce_vdc_set_copy_row() pce_vdc_set_copy_word()


Was there a specific reason to use the function call version here? This will prevent taking the address of pce_vdc_set_copy_row, which is surprising, (but unlikely).

Similarly many of these might be better served by static inline functions; they'll almost certainly get inlined away, and if they aren't, then its likely because they've completely supplanted the thing they call, which saves space. That is, if a program only calls pce_vdc_set_width_tiles, then pce_vdc_set_width may get inlined into pce_vdc_set_width_tiles and deleted from the program. Then each use is just a JSR to set_width_tiles, rather then setting up the args for a call to pce_vdc_set_width.

Actually I can never keep the semantics of C inline in my head; I've no idea whether it'll actually de-dup static inline versions of these during LTO. I've been in the habit of just making these kinds of things real functions in the .c file; it's pretty reasonable to assume that if you want fast code on llvm-mos you're doing LTO.

Admittedly, I've been in the habit of doing weird things like this because most previous platforms I worked with either lacked LTO or had buggy LTO.

Do you think it's a good idea to just standardize on non-static/non-inline functions across the library, then?

Yeah, I think that's the best default policy. Numeric constants are one thing (no consternation in C), but the simplicity of semantics for regular functions is compelling, and it gives rhe inliner the most freedom.

mos-platform/pce/libpce/src/memory-c.c

mysterymath · 2023-06-24T17:31:29Z

mos-platform/pce/libpce/include/pce/vdc.h

+ * @brief Set the VDC's copy method to copy every row.
+ * Alias for @ref pce_vdc_set_copy_word .
+ */
+#define pce_vdc_set_copy_row() pce_vdc_set_copy_word()


Yeah, I think that's the best default policy. Numeric constants are one thing (no consternation in C), but the simplicity of semantics for regular functions is compelling, and it gives rhe inliner the most freedom.

mos-platform/pce/libpce/src/memory.S

mos-platform/pce/libpce/src/psg.c

mos-platform/pce/link.ld

…ank offset mapping system.

…ions. They are not suitable as a general replacement for memcpy/memmove/memset, as they stall interrupts while they are being executed. These can be reinstated in a separate PR, once the best way to expose this to the end user is evaluated.

asiekierka · 2023-06-24T20:58:26Z

Done. I've also removed the following features (in separate commits, in case we want to revert those in the future):

pce_memcpy/pce_memmove/pce_memset - useful as they are, they currently block interrupts for the duration of executing the block transfer; this is good enough for a low-level function like pce_memop, but might need to be reconsidered for higher-level wrappers that replace C memcpy/memmove/memset.
the virtual bank system - as per a lengthy discussion on Discord, it's better to add a feature in the future than to remove one, and virtual banks have the following two problems:
- they are likely to be wholly superseded by automatic bank layouting,
- mos24bank(vbank_symbol) wouldn't always return the expected physical bank - if the virtual bank was over 8KB, and the symbol was more than 8KB into the virtual bank, it would still return the first physical bank of the virtual bank, not the one the symbol actually resides in. This is a minor issue, but frustrating if far pointers were to be implemented.

asiekierka added 2 commits June 18, 2023 12:41

Initial pce (PC Engine) platform.

9543cdb

Banking is not yet implemented, so limited to eight-kilobyte ROMs. This will be improved soon...

[PCE] Introduce banking system.

4b4fbc7

asiekierka force-pushed the upstream/pce branch 2 times, most recently from c417b2f to fba0866 Compare June 18, 2023 13:26

[PCE] Banking improvements.

6690434

- Provide missing one-bank getters and setters. - Use C where using ASM provides no "bank chain" size advantage to allow for inlining opportunities.

asiekierka force-pushed the upstream/pce branch 2 times, most recently from 12a1df2 to 6690434 Compare June 18, 2023 13:28

asiekierka added 4 commits June 18, 2023 15:41

[PCE] Optimize vbank_set for 8KB vbanks, fix PCE_VBANK_DECLARE for >8…

7828595

…KB vbanks.

[PCE] Clean up bank.h/.c/.S after figuring out the banking system.

4cecc27

[PCE] Add pce_vbank_call helper routines.

fcf5c11

[PCE] Adjust linkscript symbols for llvm-mlb.

1646972

asiekierka mentioned this pull request Jun 18, 2023

Add PCE platform support to llvm-mlb. llvm-mos/llvm-mos#305

Merged

asiekierka added 5 commits June 18, 2023 21:51

[PCE] Adjust linkscript symbol convention to match NES target

bfd5b38

[PCE] Fix soft stack location.

b906fe2

[PCE] Initial interrupt implementation.

0cd1b04

[PCE] vbank system refactors, add support for SGX RAM

9e0db39

[PCE] Fix banking example.

2d781cf

asiekierka changed the title ~~Add PCE platform.~~ [PCE] Add new platform. Jun 19, 2023

asiekierka added 10 commits June 19, 2023 19:54

[PCE] Add to README.

4528450

[PCE] Add Arcade Card and Super System Card hardware defines.

ab76485

[PCE] Document libpce functions.

6da81b4

[PCE] Add optimized memcpy/memmove/memset implementations.

e8c63f3

[PCE] Support changing the size of virtual bank 0.

d08d07b

[PCE] Implement optimized zero-bss handlers.

a4a8fdd

[PCE] Fix hardware stack init regression.

5f89232

[PCE] Add VDC resolution configuration functions, PCE_ROM_FIXED_BANK_…

a5cc7f0

…SIZE define

[PCE] Add pce_memop, minor cleanup.

d62fd96

[PCE] Implement VDC/VCE copy routines.

2e55deb

asiekierka force-pushed the upstream/pce branch from b1bdbda to 2e55deb Compare June 20, 2023 22:25

[PCE] Implement VDC enable/disable routines, fixes.

431d630

mysterymath reviewed Jun 21, 2023

View reviewed changes

asiekierka added 3 commits June 21, 2023 16:48

[PCE] Further unify VBank naming conventions.

1243200

[PCE] Bugfixes, add VDC/VCE/PSG reset routines.

aa87895

[PCE] Finish writing initial VDC functions.

8ae253c

asiekierka marked this pull request as ready for review June 21, 2023 15:39

asiekierka added 6 commits June 21, 2023 18:10

[PCE] Adjust color-cycle.c example to use interrupts.

776ca38

[PCE] Add SuperGrafx MMIO defines.

ae8eea4

[PCE] Add support for two VDCs in vdc.c.

5e036b2

[PCE] Fix set_resolution optimization regression, add pce_sgx_vdc_init

0aaeff3

[PCE] Add pce_rom_vbankN_bank getter

fe4ace5

[PCE] Fix pce_rom_vbankN_call safety.

a453392

mysterymath reviewed Jun 23, 2023

View reviewed changes

asiekierka added 2 commits June 24, 2023 11:04

[PCE] Add missing newlines.

e4b76a5

[PCE] Add PCE_FREQ_TO_TIMER define, fully derive its origin.

17db44a

asiekierka force-pushed the upstream/pce branch from a5b88f1 to 17db44a Compare June 24, 2023 09:17

[PCE] Add pce_sgx_detect().

e119376

asiekierka force-pushed the upstream/pce branch from 15fb319 to e119376 Compare June 24, 2023 12:26

[PCE] Fix typo.

1f7f26e

mysterymath approved these changes Jun 24, 2023

View reviewed changes

asiekierka added 3 commits June 24, 2023 22:28

[PCE] Downgrade virtual bank system to a much less complex physical b…

6ecf4b7

…ank offset mapping system.

[PCE] Fix issues.

fba4e75

mysterymath approved these changes Jun 25, 2023

View reviewed changes

mysterymath merged commit d3caa19 into llvm-mos:main Jun 25, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PCE] Add new platform. #121

[PCE] Add new platform. #121

asiekierka commented Jun 18, 2023 •

edited

mysterymath commented Jun 21, 2023

mysterymath Jun 21, 2023 •

edited

asiekierka Jun 21, 2023 •

edited

asiekierka commented Jun 21, 2023

asiekierka commented Jun 21, 2023 •

edited

mysterymath Jun 23, 2023

mysterymath Jun 23, 2023

mysterymath Jun 23, 2023 •

edited

asiekierka Jun 24, 2023

mysterymath Jun 24, 2023

mysterymath Jun 24, 2023

asiekierka commented Jun 24, 2023

[PCE] Add new platform. #121

[PCE] Add new platform. #121

Conversation

asiekierka commented Jun 18, 2023 • edited

mysterymath commented Jun 21, 2023

mysterymath Jun 21, 2023 • edited

Choose a reason for hiding this comment

asiekierka Jun 21, 2023 • edited

Choose a reason for hiding this comment

asiekierka commented Jun 21, 2023

asiekierka commented Jun 21, 2023 • edited

mysterymath Jun 23, 2023

Choose a reason for hiding this comment

mysterymath Jun 23, 2023

Choose a reason for hiding this comment

mysterymath Jun 23, 2023 • edited

Choose a reason for hiding this comment

asiekierka Jun 24, 2023

Choose a reason for hiding this comment

mysterymath Jun 24, 2023

Choose a reason for hiding this comment

mysterymath Jun 24, 2023

Choose a reason for hiding this comment

asiekierka commented Jun 24, 2023

asiekierka commented Jun 18, 2023 •

edited

mysterymath Jun 21, 2023 •

edited

asiekierka Jun 21, 2023 •

edited

asiekierka commented Jun 21, 2023 •

edited

mysterymath Jun 23, 2023 •

edited