gint/README.md

132 lines
4.6 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 used to include third-party code that has now been moved to the FxLibc. If
you stumble upon it in the history, check the README file at that time for
license details.
## 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
2022-11-11 17:46:27 +01:00
* Blazingly fast rendering functions (image rendering is 10 times faster than
2021-01-25 21:52:42 +01:00
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
(actually needed by gint)
* [fxlibc](/Vhex-Kernel-Core/fxlibc/): A community standard library with
dedicated SuperH optimizations (in progress; needed by gint unless you're
trying out Newlib)
2021-01-25 21:52:42 +01:00
* Integration with [a Newlib port by Memallox](/PlaneteCasio/libc) (unstable)
2021-01-29 18:22:55 +01:00
## Installing with GiteaPC
2021-01-25 21:52:42 +01:00
gint can be installed automatically with [GiteaPC](/Lephenixnoir/GiteaPC).
```bash
% giteapc install Lephenixnoir/gint
```
2021-01-29 18:22:55 +01:00
Normally you don't use gint directly, instead the fxSDK provides project
2021-01-25 21:52:42 +01:00
templates that are set up to use gint. Please see the
[fxSDK README file](/Lephenixnoir/fxsdk) for details.
## Building and installing manually
2021-01-29 18:22:55 +01:00
gint is built using the [fxSDK](/Lephenixnoir/fxsdk), which provides a suitable
CMake environment for the calculator. 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.
gint depends on OpenLibm and fxlibc (linked above). Both can be installed
easily (essentially copy-paste the command from the respective READMEs). You
can technically use another libc but there be dragons.
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-08-26 10:49:34 +02:00
% fxsdk build-fx install
2021-01-25 21:52:42 +01:00
```
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-08-26 10:49:34 +02:00
```
% fxsdk build-cg
% fxsdk build-cg install
```
2021-01-29 18:22:55 +01:00
## Using in CMake-based add-ins
Find the `Gint` module and link against `Gint::Gint`. gint declares the include
and library paths needed to link with OpenLibm and the libc, and will
automatically link both.
2021-01-29 18:22:55 +01:00
```cmake
find_module(Gint 2.1 REQUIRED)
target_link_libraries(<target_name> Gint::Gint)
```
## Using in Makefile-based add-ins
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 -lgint-fx -lopenlibm -lc` on fx-9860G;
* Link with `-T fxcg50.ld -lgint-cg -lopenlibm -lc` 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.