Editing File Formats (section)

== KUP - Kernel User Program ==
KUPs are very simple and can contain 40 KiB code/data when run from flash, or 32 KiB when run from disk. Contained in their header is an entry point address, and the slot number of where they should be mapped into, the first possible slot being #1 ($2000).

DOS expands on the KUP header defined by the MicroKernel in a backwards compatible way.

The header is very simple:

<pre>
Byte  0    signature: $F2
Byte  1    signature: $56
Byte  2    the size of program in 8k blocks
Byte  3    the starting slot of the program (i.e. where to map it)
Bytes 4-5  the start address of the program
Byte  6    header structure version (indicates version of header, current 0 or 1)
Bytes 7-9  reserved
Bytes 10-?  zero-terminated name of the program.
Bytes ?-?  zero-terminated string describing the arguments. (in version >= 1)
Bytes ?-?  zero-terminated string describing the program's function. (in version >= 1)
</pre>

Example of a header block definition:

<pre>
        EXEC  = __STARTUP_LOAD__
        SLOT  = __STARTUP_LOAD__ >> 13
        COUNT = __END_LOAD__ >> 13   ; Assumes code starts at $2000.

        .byte   $f2,$56     ; signature
        .byte   <COUNT      ; block count
        .byte   <SLOT       ; start slot
        .word   EXEC        ; exec addr
        .byte   1                 ; CHANGED, structure version
        .byte   0                 ; reserved
        .byte   0                 ; reserved
        .byte   0                 ; reserved
        .asciiz "cwrite"     ; name
        .asciiz "  "  
        .asciiz "App to program the Flash Cartridge"  

        .segment    "END"
</pre>

The MicroKernel ignores the "argument" and "function" header entries. These are printed by DOS' <code>lsf</code> command, and only if the header version is greater or equal to 1.

When instructed to start a named KUP, the kernel will search through memory to find a match. First the expansion memory is searched, this could be either RAM or ROM. Then the on-board flash memory is searched. If DIP switch #1 is in the "on" position, the kernel will search memory banks 1-5 before the expansion blocks.

This sequence is also performed when the kernel starts up, for instance when the machine is reset or is first powered on.

Testing a KUP is therefore as easy as uploading it to a block of memory, and is an excellent choice for testing a program that interacts with the kernel. Though you should remember that this program will stay in memory as long as the machine is powered on, and may also survive a short power cut. Such a program should therefore, when testing, destroy its own header by overwriting the first two bytes with some values that are not the magic signature, to avoid being started again and again.

A KUP residing in flash does not "return" in the common sense of the word. If it has to terminate, it can either reset the machine, or use `RunNamed` to start another KUP.

On the other hand, when running a KUP from disk, it is able to return to DOS in a controlled manner. Distributing software intended to be run from disk as KUP is usually discouraged, as the program can only be started from DOS and not from SuperBASIC. It can, however, be appropriate for small utility programs mostly intended for maintenance tasks and so forth. When distributing software, you should prefer using one of the PGX or PGZ formats.

A KUP loaded from disk may exit back to DOS by issuing an RTS instruction. Additionally, the carry may be set if the machine should be reset, or carry clear to continue running DOS. Be aware that you must leave the MMU configuration in the state you found it for this to work properly. You should also keep away from the $0200-$07FF range completely.

When a KUP is started from flash, LUT #3 slots 0-5 is mapped to RAM banks 0-5, *except* where the KUP's header specifies where into should be mapped.

A KUP started from disk has LUT #3 slots 0-4 mapped to RAM, some of which will be the program itself.

In both cases the kernel is intact and available for use straight away.