k2/mantle [ Modules ]
NAME
mantle
FUNCTION
This module is intended to emulate a future event-driven OS kernel named Mantle. It exposes various services of the GUI and runtime environment to the software running under emulation, as well as dispatching event handlers.
From the point of view of user-mode software running on the RISC-V processor, Mantle is the native operating system of the Kestrel-2EX. It runs in supervisor-mode or possibly even machine-mode. Thus, to invoke its services, applications must first load register A7 with a function code (see also ecall_t) prior to invoking an ECALL instruction. Unless otherwise specified, parameters are provided in registers A0-A6, with results in A0-A1.
The hardware (physical or virtualized/emulated) is generally referred to as the "core". The user-mode environment is generally referred to as the "crust".
BUGS
There are a number of functions in this module which are prefixed with
rose_ instead of with mantle_. These will be fixed in a later release.
Right now, they're all static functions, so nobody but us will call
them, so there's no harm in leaving this confusion for now.
mantle/ecall_id_e, mantle/ecall_id_t [ Types ]
NAME
enum ecall_id_e
ecall_id_t
FUNCTION
Provides constants for various services offered by Mantle.
MEMBERS
ecNextEvent
After an event handler has processed its event,
it must invoke ecNextEvent to return control
back to Mantle so that additional events may be
processed.
ecGetScreenConfig
Retrieves the current display configuration,
including its width in pixels, height in pixels,
and the base address of the frame buffer.
ecDumpRegs
A debugging aid; this system call produces a dump
of the RISC-V processor's user-mode registers to
a separate debugging channel. This channel, if it
exists at all, is "core" specific.
ecSetEventsDesired
Informs Mantle which input events the application is
interested in. An event flag corresponds with each
event message type (see message_type_t); bit 0 maps
to mtInit, bit 1 to mtKeyDown, and so forth.
ecSetEvProcPC
A program running under Mantle consists of at least one
event handling procedure (aka "evproc"). For small enough
applications, one is all you need. For larger applications
that may run in one or more different "modes" of operation,
having multiple procedures for each mode you can switch
between becomes an advantage. This system call can be
used to select which evproc is currently active.
ecSetEvProcSP
Every time the event procedure is invoked, the stack is
reset to a known good value. This procedure can be used
to change that value.
ecBeginPaint
ecEndPaint
These system calls always exist in pairs. ecBeginPaint
informs Mantle that you're about to begin redrawing the
screen. ecEndPaint tells Mantle that you've completed
painting, and that the buffer is free to be used by the
video system.
ecStartTimer
This service lets you schedule a (potentially periodic)
event to trigger in the future.
ecStopTimer
This service disposes of Mantle resources related to a
timer created with ecStartTimer. (And it terminates the
timer if it's still active.)
ecQuitVM
If the core is an emulated environment, this asks the
emulator to cleanly exit. If the core is physical
hardware, this will cleanly terminate the currently
running application and return to the OS shell.
mantle/message_type_e, mantle/message_type_t [ Types ]
NAME
enum message_type_e
message_type_t
FUNCTION
Each message type indicates a reason for an event callback.
MEMBERS
mtInit
Initialization messages are sent to the current event
procedure of a program, and signals when a new instance
of the program is run and needs initialization for the
first time.
mtKeyDown
mtKeyUp
These events are sent when the user presses or releases
a key on the keyboard.
mtTimerTick
Assuming a timer is configured with the ecStartTimer
system call, this event is triggered when one or more
timers expire.
BUGS
The following message types are not yet implemented, but are
planned for a future release of Mantle.
mtMouseMove
This event is triggered when the mouse or other pointing
device is moved.
mtMouseDown
mtMouseUp
Similar to mtKeyDown and mtKeyUp, these events are
generated when the user presses or releases (resp.)
one or more pointing device buttons.
mtMousePresence
Some input devices, like pens, can be lifted far enough
from their surfaces that they appear to "disappear".
Or, a regular mouse can appear to just "disappear" as
well if the user is running Mantle in an emulator in a
windowing environment. Presence events are generated
whenever a pointing device disappears or re-appears.