cdd0b64570
Instead of expecting a `USER_CODE` symbol to be set, we expect `.org` to be set in all userspace glue code. This gives us more flexibility with regards to how we manage that. Moreover, instead of making `USER_RAMSTART` mandatory, we make it default to the end of the binary, which is adequate in a majority of cases. Will be useful for my upcoming mega-commit... :)
41 lines
1.7 KiB
Markdown
41 lines
1.7 KiB
Markdown
# User applications
|
|
|
|
This folder contains code designed to be "userspace" application. Unlike the
|
|
kernel, which always stay in memory. Those apps here will more likely be loaded
|
|
in RAM from storage, ran, then discarded so that another userspace program can
|
|
be run.
|
|
|
|
That doesn't mean that you can't include that code in your kernel though, but
|
|
you will typically not want to do that.
|
|
|
|
## Userspace convention
|
|
|
|
We execute a userspace application by calling the address it's loaded into.
|
|
|
|
This means that userspace applications must be assembled with a proper `.org`,
|
|
otherwise labels in its code will be wrong.
|
|
|
|
The `.org`, it is not specified by glue code of the apps themselves. It is
|
|
expected to be set either in the `user.h` file to through `zasm` 3rd argument.
|
|
|
|
That a userspace is called also means that an application, when finished
|
|
running, is expected to return with a regular `ret` and a clean stack.
|
|
|
|
Whatever calls the userspace app (usually, it will be the shell), should set
|
|
HL to a pointer to unparsed arguments in string form, null terminated.
|
|
|
|
The userspace application is expected to set A on return. 0 means success,
|
|
non-zero means error.
|
|
|
|
A userspace application can expect the `SP` pointer to be properly set. If it
|
|
moves it, it should take care of returning it where it was before returning
|
|
because otherwise, it will break the kernel.
|
|
|
|
Apps in Collapse OS are design to be ROM-compatible, that is, they don't write
|
|
to addresses that are part of the code's address space.
|
|
|
|
By default, apps set their RAM to begin at the end of the binary because in
|
|
most cases, these apps will be ran from RAM. If they're ran from ROM, make sure
|
|
to set `USER_RAMSTART` properly in your `user.h` to ensure that the RAM is
|
|
placed properly.
|