lco/HACKING

Copyright (C) 2018 Ariadne Devos

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

-----

See process/patches.md for how to send patches upstream.
See process/bugs.md for a list of known bugs to hack upon.
See process/bug-reporting.md for how to report bugs.

# Support a new architecture

(BUG: unportable)
See README for a list of supported architectures.

(This assumes an architecture with a stack. You can do things differently, this
is only a proposal.)

Create a file lco-$ARCH.S (replace $ARCH with your architecture). Export two
functions: _lco_switch and _lco_call. _lco_switch is a two-argument function,
declared in lco.c. It switches from one coroutine to another.

> extern void
> _lco_switch(void *next_sp, void **current_sp);

This function must save all registers that might be clobbered by the next
coroutine on the stack, that must remain intact according to the ABI if this
function would be a normal C function, except the stack pointer.
(Probably, save all callee-saved registers except the stack pointer).

The stack pointer must be saved in *current_sp.

Then change stack pointer to next_sp, restore saved registers and return.

_lco_call is the starting point for a coroutine.

_lco_call is a function with a non-standard ABI. Let it take an argument from
a normally callee-saved register. This is a lco_coroutine co. Do a tail-call
into co->entry(co).