gint/README.md

126 lines
4.8 KiB
Markdown
Raw Normal View History

# gint project
2016-05-05 12:12:42 +02:00
2021-01-25 21:52:42 +01:00
gint (pronounce “guin”) is an add-in unikernel for CASIO calculators of the
fx-9860G II and fx-CG 50 families. It provides a mostly free-standing runtime
and is used to develop add-ins under Linux, along with specialized GCC
toolchains and the [fxSDK](/Lephenixnoir/fxsdk).
2016-05-05 12:12:42 +02:00
2021-01-25 21:52:42 +01:00
When running in an add-in, gint takes control of the calculator's hardware
from the operating system, and manages it with its own drivers. It exposes a
new, richer API that takes advantage of the full capabilities of the machine.
2021-01-25 21:52:42 +01:00
This is free software: you may use it for any purpose, share it, modify it, and
share your changes. Credit is not required, but please let me know!
2016-05-05 12:12:42 +02:00
gint also includes third-party code that is distributed under its own license.
Currently, this only includes:
* A stripped-down version of the [TinyMT random number generator](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/TINYMT/index.html)
([GitHub repository](https://github.com/MersenneTwister-Lab/TinyMT)) by
Mutsuo Saito and Makoto Matsumoto. See `src/std/tinymt32/LICENSE.txt`.
## Programming interface
2016-05-05 12:12:42 +02:00
2016-12-25 11:45:05 +01:00
Because of its free-standing design, gint's API provides direct and efficient
2021-01-25 21:52:42 +01:00
access to low-level MPU features, which includes:
* Multi-key management with event systems suitable for games
* Hardware timers with sub-millisecond and sub-microsecond resolution
* Fast screen drivers with DMAC on fx-CG 50
* Efficient and user-extendable interrupt management
2021-01-25 21:52:42 +01:00
* Safe access to on-chip and DSP memory areas
* Hardware-driven memory primitives (DMA, DSP)
2016-05-05 12:12:42 +02:00
2016-12-25 11:45:05 +01:00
The library also offers powerful higher-level features:
2016-05-05 12:12:42 +02:00
* An enhanced version of the system's GetKey() and GetKeyWait()
* A gray engine that works by rapidly swapping monochrome images on fx-9860G II
2021-01-25 21:52:42 +01:00
* Blazingly fast rendering functions (image rendering is 10 times faster tha
MonochromeLib)
* Integrated font management
2016-05-05 12:12:42 +02:00
2021-01-25 21:52:42 +01:00
A couple of libraries extend these features, including:
2021-01-25 21:52:42 +01:00
* [libprof](/Lephenixnoir/libprof): Profiling and performance evaluation
* [libimg](/Lephenixnoir/libimg): Versatile image transformations
* [OpenLibm](/Lephenixnoir/OpenLibm): A port of the standard math library
* Integration with [a Newlib port by Memallox](/PlaneteCasio/libc) (unstable)
## Basic use with GiteaPC and the fxSDK
gint can be installed automatically with [GiteaPC](/Lephenixnoir/GiteaPC).
```bash
% giteapc install Lephenixnoir/gint
```
Normally you don't use it directly, instead the fxSDK provides project
templates that are set up to use gint. Please see the
[fxSDK README file](/Lephenixnoir/fxsdk) for details.
## Building and installing manually
You will need a couple of tools:
2019-05-03 17:12:22 +02:00
* A suitable GCC toolchain in the `PATH`. You can absolutely *not* build gint
with your system compiler!
2019-11-13 19:31:37 +01:00
* The tutorial on Planète Casio builds an `sh-elf` that works everywhere
* For fx-9860G II, `sh3eb-elf` is strongly advised
* For fx-CG 50, `sh4eb-elf` (with `-m4-nofpu`) is slightly better but
`sh3eb-elf` is completely fine
2021-01-25 21:52:42 +01:00
* The [fxSDK](/Lephenixnoir/fxsdk) installed and available in the PATH.
fx-CG 50 developers probably want a g3a wrapper as well; the reference
implementation is Tari's [mkg3a](https://gitlab.com/taricorp/mkg3a). This is
needed at the very last compilation step to create the g3a file. On Arch Linux,
you can use the [AUR/mkg3a](https://aur.archlinux.org/packages/mkg3a) package
maintained directly by Tari.
2021-01-25 21:52:42 +01:00
gint is built with CMake; the fxSDK provides CMake modules to target the
calculator, as well as a couple of utilities. gint is always installed in the
compiler's install path (as given by `sh-elf-gcc --print-search-dirs`) which is
detected automatically, so normally you don't need to set the install prefix.
2021-01-25 21:52:42 +01:00
**Building for fx-9860G II**
2021-01-25 21:52:42 +01:00
`fxsdk build-fx` will invoke CMake and make. If you have specific configuration
options, run once with `-c` to configure.
2021-01-25 21:52:42 +01:00
```
% fxsdk build-fx -c <OPTIONS...>
```
2021-01-25 21:52:42 +01:00
Run without `-c` to build. This configures automatically.
2021-01-25 21:52:42 +01:00
```
% fxsdk build-fx
```
2021-01-25 21:52:42 +01:00
The available options are:
2021-01-25 21:52:42 +01:00
* `-DGINT_STATIC_GRAY=1`: Put the gray engine's VRAMs in static RAM instead of
using `malloc()`
2021-01-25 21:52:42 +01:00
**Building for fx-CG 50**
2021-01-25 21:52:42 +01:00
Same as fx-9860G II, except the command is `fxsdk build-cg` instead of `fxsdk
build-fx`.
2021-01-25 21:52:42 +01:00
The available options are:
2021-01-25 21:52:42 +01:00
* `-DGINT_USER_VRAM=1`: Store all VRAMs in the user stack (takes up 350k/512k)
2021-01-25 21:52:42 +01:00
## Linking with gint manually
2021-01-25 21:52:42 +01:00
Projects created with the fxSDK link with gint out-of-the-box. If you're not
using the fxSDK, you will need to:
2021-01-25 21:52:42 +01:00
* Build with `-ffreestanding -fstrict-volatile-bitfields`;
* Link with `-T fx9860g.ld` and `-lgint-fx` on fx-9860G;
* Link with `-T fxcg50.ld` and `-lgint-cg` on fx-CG 50.
If you don't have a standard library such as
[Memallox's port of newlib](/PlaneteCasio/libc), you also need `-nostdlib`. I
typically use `-m3 -mb` or `-m4-nofpu -mb` to specify the platform, but that
may not even be necessary.