diff --git a/docs/development/licenses.md b/docs/development/licenses.md index 78e548edb8..a9cf14b4d1 100644 --- a/docs/development/licenses.md +++ b/docs/development/licenses.md @@ -193,6 +193,7 @@ See below for a summary of the licenses behind RetroArch and its cores: | [PCSX ReARMed](../library/pcsx_rearmed.md) | [GPLv2](https://github.com/libretro/pcsx_rearmed/blob/master/COPYING) | | | PCSX ReARMed [Interpreter] | [GPLv2](https://github.com/libretro/pcsx_rearmed/blob/master/COPYING) | | | [PD777](../library/pd777.md) | [MIT](https://github.com/mittonk/PD777/blob/main/LICENSE) | | +| [piece-emu](../library/piece.md) | [MIT](https://github.com/autch/piece-emu/blob/main/LICENSE) | | | [Picocomputer 6502](../library/rp6502.md) | [BSD-3-Clause](https://github.com/picocomputer/rp6502/blob/main/LICENSE) | | | [PicoDrive](../library/picodrive.md) | [MAME (Non-commercial)](https://github.com/libretro/picodrive/blob/master/COPYING) | Non-commercial | | [PocketCDG](../library/pocketcdg.md) | [MIT](https://github.com/libretro/libretro-pocketcdg/blob/master/LICENSE) | | diff --git a/docs/guides/core-list.md b/docs/guides/core-list.md index da4d8de301..7d93496016 100644 --- a/docs/guides/core-list.md +++ b/docs/guides/core-list.md @@ -192,6 +192,7 @@ | [PCem](../library/pcem.md) | IBM PC | | | [PCSX ReARMed](https://docs.libretro.com/library/pcsx_rearmed/) | Sony PlayStation | | | [PD777](../library/pd777.md) | Epoch Cassette Vision | | +| [piece-emu](../library/piece.md) | Aquaplus P/ECE | An emulator for the Aquaplus P/ECE, a Japanese homebrew-oriented handheld | | [Picocomputer 6502](../library/rp6502.md) | Picocomputer 6502 | An open source 8-bit computer you can build | | [PicoDrive](../library/picodrive.md) | Sega MS/GG/MD/CD/32X | | | [Play!](../library/play.md) | Sony PlayStation 2 | | diff --git a/docs/library/piece.md b/docs/library/piece.md new file mode 100644 index 0000000000..7772212e0a --- /dev/null +++ b/docs/library/piece.md @@ -0,0 +1,168 @@ +--- +title: "piece-emu – Aquaplus P/ECE core for RetroArch" +description: "RetroArch piece-emu core (Aquaplus P/ECE): how to prepare .pfi content, save data, core options and controls. piece-emu emulates the Aquaplus P/ECE handheld, a Japanese homebrew-oriented portable from 2001." +--- + +# Aquaplus - P/ECE (piece-emu) + +## Background + +The [P/ECE](https://aquaplus.jp/piece/) (pronounced "piece") is a handheld game console released by Aquaplus in Japan in 2001. It is built around the EPSON S1C33209 SoC (S1C33000 32-bit RISC CPU core) and has a 128×88 four-level grayscale LCD, a D-pad, A/B/START/SELECT buttons, PWM sound and a USB connection to a PC. Aquaplus published the development kit and the kernel source, so most P/ECE software is homebrew distributed by its authors as `.pex` application files. + +piece-emu is a P/ECE emulator written in C++. It emulates the S1C33000 CPU, the S1C33209 on-chip peripherals, the LCD controller and the NOR flash, and boots the real P/ECE kernel from a flash image. The libretro core is part of the piece-emu project. + +The piece-emu core has been authored by: + +- Autch + +The piece-emu core is licensed under: + +- [MIT](https://github.com/autch/piece-emu/blob/main/LICENSE) + +A summary of the licenses behind RetroArch and its cores can be found [here](../development/licenses.md). + +## Requirements + +None. + +## How to start the piece-emu core: + +The content for this core is a `.pfi` (P/ECE Flash Image) file: a complete image of the P/ECE flash memory that contains the kernel (system software) and the applications installed in the on-flash file system (PFFS). There is no separate BIOS. + +A `.pfi` is not a per-title ROM. It is closer to the hard disk image of a computer core: the user assembles it, and a single image holds the system plus any number of applications. P/ECE applications (`.pex`) cannot be loaded as content directly; add them to a `.pfi` and start them from the P/ECE launcher. Everything RetroArch handles per content, such as the save file, playlists, and per-game remaps and option overrides, therefore applies to the whole image rather than to each application. + +A `.pfi` can be made from a real P/ECE with the `ripper` tool, or built without the hardware from Aquaplus's official system updater: + +1. Download [update120.exe](https://aquaplus.jp/piece/dl/update120.exe) from the [official PieceSystem 1.20 download page](https://aquaplus.jp/piece/dl/update120.html). It is an LHA self-extracting archive: run it on Windows, or extract it with `lha x update120.exe` elsewhere. +2. Build the image with the `mkpfi` tool from the [piece-emu repository](https://github.com/autch/piece-emu): + ``` + mkpfi -512kb piece/update/all.bin piece.pfi + ``` + Use `mkpfi -2mb piece/update/2mb/all.bin piece.pfi` for units modded to 2 MB flash. +3. Add applications (`.pex`) to the content with the `pfar` tool, for example `pfar piece.pfi -a mygame.pex`. + +Then, in RetroArch, select 'Load Content', choose the `.pfi` file and, if asked which core to use, choose 'Aquaplus - P/ECE (piece-emu)'. The P/ECE launcher (menu) starts; pick an application from it. + +## BIOS + +Not required. The P/ECE kernel is part of the `.pfi` content. + +## Extensions + +Content that can be loaded by the piece-emu core have the following file extensions: + +- .pfi + +RetroArch database(s) that are associated with the piece-emu core: + +- None + +## Features + +Frontend-level settings or features that the piece-emu core respects: + +| Feature | Supported | +|-------------------|:---------:| +| Restart | ✔ | +| Saves | ✔ | +| States | ✕ | +| Rewind | ✕ | +| Netplay | ✕ | +| Core Options | ✔ | +| [Memory Monitoring (achievements)](../guides/memorymonitoring.md) | ✕ | +| RetroArch Cheats | ✕ | +| Native Cheats | ✕ | +| Controls | ✔ | +| Remapping | ✔ | +| Multi-Mouse | ✕ | +| Rumble | ✕ | +| Sensors | ✕ | +| Camera | ✕ | +| Location | ✕ | +| Subsystem | ✕ | +| [Softpatching](../guides/softpatching.md) | ✕ | +| Disk Control | ✕ | +| Username | ✕ | +| Language | ✕ | +| Crop Overscan | ✕ | +| LEDs | ✕ | + +## Directories + +The piece-emu core's library name is 'piece-emu' + +The piece-emu core saves/loads to/from these directories. + +**Frontend's Save directory** + +| File | Description | +|:----------:|:-----------:| +| *.srm | Flash memory contents (PFFS save data of every application in the image) | + +The loaded content (`.pfi`) itself is never modified. Everything the kernel and applications write to flash (high scores, settings, user data) goes to the `.srm` file instead, which is itself a complete PFI image: it can be inspected with `pfar` (`pfar piece.srm -l`), or renamed to `.pfi` to boot it as standalone content. + +Once a `.srm` exists, the core restores the entire flash from it when the content is loaded, so the `.srm`, not the `.pfi`, becomes the live image. Applications added to the `.pfi` afterwards do not appear. To add an application at that point, close the content and either add it to the `.srm` (`pfar piece.srm -a newgame.pex`), or rename the `.srm` to `.pfi` and use it as new content. + +## Geometry and timing + +- The piece-emu core's core provided FPS is 60 +- The piece-emu core's core provided sample rate is 32000 Hz +- The piece-emu core's base width is 128 +- The piece-emu core's base height is 88 +- The piece-emu core's max width is 128 +- The piece-emu core's max height is 88 +- The piece-emu core's core provided aspect ratio is 16:11 (128:88) + +## Usage + +By default RetroArch writes the `.srm` only when the content is closed, so exit with 'Close Content' rather than killing RetroArch. Setting 'Settings → Saving → SaveRAM Autosave Interval' to a non-zero value also protects against losing data when RetroArch is killed. + +## Core options + +The piece-emu core has the following option(s) that can be tweaked from the core options menu. The default setting is bolded. + +- **Swap A/B Buttons** [piece_swap_ab] (**Off (RetroArch standard)**|On (Swapped)) + + Off: RetroPad A is the P/ECE A button and RetroPad B is the P/ECE B button. On: the two are swapped. + +- **Timer Tick Granularity** [piece_tick_burst] (2000|3000|**4000**|6000|8000|12000|16000) + + How often the emulated peripheral timers and interrupts are serviced, in CPU cycles. Larger values reduce the per-frame cost (raising the frame rate on slow hosts, such as RetroArch Web) but deliver interrupts more coarsely; if set too large, audio goes silent. 4000 runs at roughly the speed of the real P/ECE. + +## User 1 device types + +The piece-emu core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s): + +- **RetroPad** - Joypad + +## Joypad + +| RetroPad Inputs | User 1 input descriptors | +|------------------------------------------------|--------------------------| +| ![](../image/retropad/retro_b.png) | B Button | +| ![](../image/retropad/retro_select.png) | Select | +| ![](../image/retropad/retro_start.png) | Start | +| ![](../image/retropad/retro_dpad_up.png) | D-Pad Up | +| ![](../image/retropad/retro_dpad_down.png) | D-Pad Down | +| ![](../image/retropad/retro_dpad_left.png) | D-Pad Left | +| ![](../image/retropad/retro_dpad_right.png) | D-Pad Right | +| ![](../image/retropad/retro_a.png) | A Button | + +With the 'Swap A/B Buttons' core option enabled, RetroPad A and B are exchanged. + +## Compatibility + +The kernel boots and applications run with display, input, sound and flash saves. The following P/ECE hardware is not emulated yet, so applications that depend on it do not work or have reduced functionality: + +- USB +- IrDA (infrared communication) +- MMC card interface +- ADC +- IDMA + +## External links + +- [Official Aquaplus P/ECE Website (Japanese)](https://aquaplus.jp/piece/) +- [piece-emu GitHub Repository](https://github.com/autch/piece-emu) +- [Libretro piece-emu Core info file](https://github.com/libretro/libretro-core-info/blob/master/piece_libretro.info) +- [Report Libretro piece-emu Core Issues Here](https://github.com/autch/piece-emu/issues) diff --git a/mkdocs.yml b/mkdocs.yml index 42ac8bef02..a18d3481c9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -124,6 +124,8 @@ nav: - 'Apple': - 'Apple - II (AppleWin)': 'library/applewin.md' - 'Apple - Macintosh (minivmac)': 'library/minivmac.md' + - 'Aquaplus': + - 'Aquaplus - P/ECE (piece-emu)': 'library/piece.md' - 'Arcade Emulation': - 'Arcade (Daphne HypseusHW)': 'library/hypseushw.md' - 'Arcade (DICE)': 'library/dice.md'