Prologue and epilogue

[apt1002]

Allow code::Machines to define a "prologue" (code to execute on entry to Mijit) and an "epilogue" (code to execute on exit). I propose the following design:

• No, see comment Machine::Save is a type of the Machine's choosing, suitable for saving the state which persists when Mijit is not running.
• No, see comment Machine::values() is a list of up to 64 Values, which includes all those that are live at any Machine::State.
• Machine::get_code(State) returns (among other things) the live Values at the State using a 64-bit mask, with one bit for each of values().
• On entry to Mijit, the caller passes a pointer to the Save, and specifies the initial State. After saving the callee-saves registers, Mijit puts the pointer in Register(0) and runs the prologue, before entering the State. The prologue is expected to initialise all values().
• On exit, Mijit sets all dead values() to a dummy value (0xdeaddeaddeaddead) and runs the epilogue. It then reloads all the callee-saves registers and returns the final State to the caller.
• The prologue and epilogue are written in Mijit code, and must be straight-line code.

Having prologue and epilogue code is helpful for the following reasons:

• It allows the persistent state to be saved in a type of the Machines choosing, as opposed to one of Mijit's choosing. This plays better with other code.
• All Slots can be dead when Mijit is not running, just like the Registers. Therefore, we no longer need a global array of Slots, and can instead use the system stack. This saves a precious Register, and allows us to make use of push instructions.
• It allows Registers as well as Slots to be live, without fear that an exception will corrupt them.

In principle, the Machine could have a separate prologue and epilogue tailored for each State, but I think that would be more annoying than useful. It would also provide places for obscure bugs to lurk. Instead, I suggest that we have just one prologue and epilogue, shared by all States, as described above.

I am content to impose a limit of 64 values() because they are expensive; they are marshalled to/from the Save every time you enter or exit Mijit. Only one persistent Value is actually needed: the pointer to the Save. The others are just a Register-allocation hint, i.e. an optimisation. If you are using more than 64, you're not using them right.

[apt1002]

An analysis of goals:

1. We want the Slots (unbounded in number) to be on the stack.
2. We want the Registers and Slots to be dead when Mijit is not running.
3. We want some Registers and Slots to be live in the root Machine::States, and we want to specify the live set in an ergonomic way.
4. We want to allow the Machine to choose the Save data structure used to persist the state of the VM when Mijit is not running.
5. We want to minimise the marshalling code that gets run on entry to and exit from Mijit.

Goal 1 deserves an issue of its own (#26) which also covers goal 2.

The combination of goals 2 and 3 motivates the prologue and epilogue code, whose purpose it to marshal data between the persistent state and the live set.

Goal 4 does not require any support from Mijit beyond providing a single persistent pointer to the prologue and epilogue code. The Machine can use it as a pointer to a Save if it wants; Mijit does not need to understand. So Machine::Save is an unnecessary concept.

Goal 5 essentially boils down to sharing between the persistent state and the live set. This can be done by reference, e.g. via the pointer to the Save. However, it is cheap and probably useful to provide some state that is shared "by value" too. I propose a constant-sized array of words (Globals?) that can be accessed as Values (alongside Registers and Slots) but which are always live and which persist when Mijit is not running. This is a mild generalisation of the single persistent pointer required by goal 4.

In summary, I propose the following design:

• Add a case Global to code::Value, alongside Register and Slot, to represent a 64-bit word that persists when Mijit is not running. This deserves its own issue (#27).
• Machine::Save does not exist.
• Machine::values() does not exist. Instead Mijit defines a set of 64 Values: the first 12 Registers and the first 52 Slots. It is not necessary to include Globals, which are always live.
• Machine::num_globals() returns the number of Globals that the Machine would like to use. This resurrects an earlier Mijit feature, with the difference that the Globals are not considered to be a subset of the Slots.
• Machine::get_code(state) returns (among other things) a 64-bit mask indicating the Values that are live in state. The bitmask selects from the Mijit-defined set.
• Machine::prologue() returns a list of Mijit Actions to marshal data from the Globals to the live values. It is not passed anything on entry. On exit it must have initialised all Values that are live in any State.
• Machine::epilogue() returns a list of Mijit Actions to marshal data from the live values back to the Globals. On entry, it gets all Values that are live in any State; those that are dead are set to a dummy value (0xdeaddeaddeaddead). On exit nothing is live.