Changes
/* Memory address &7FF9 (TCON9) */
==== Memory address &7FF9 (TCON9) ====
* Reserved for future expansions
= V. Programming a Task =
In order to program a task, certain conventions must be observed. Strict rules apply here, which must be observed in every case.
However, Caruh also provides the Tasks with helpful functions. See later
=== Task conventions: Requirements for Tasks ===
* Tasks must retain their expansion RAM (E-RAM) configuration. Each task can read its own RAM banking status from addresses &7FFA and &7FFB. E.g. by an LD BC,(TER16). If illegal banking is still to be carried out, the interrupts must be switched off.
* Tasks must maintain the ROM / RAM status (the upper ROM is always on). For example, if data has to be read from the screen memory, the interrupts must be temporarily switched off. Note the status of the lower ROM!
* A Task can be a maximum of 15.75 KB long, because the stack of the Task and the Task variables are located above (see above: 'Structure of a task')
* Tasks do not require a header, as they are always loaded at address &4000. Tasks that have a header, including the header, must not be larger than 16 KB
* Tasks / files larger than 16 KB are NOT loaded / started by Caruh!
* A Task is allowed to output on screen only if in Caruh's Variable CCON2. (at address &BE02) the bits 0 and 7 are both cleared to zero. Exception: A Task did set bit 0 by himself, so its the Foreground-Task now
* During the call of OS functions that use hardware directly, the interrupts must be switched OFF and then switched ON again. The same is true if a Task used direct I/O hardware access.
* During the call of OS functions that use the stack pointer SP, the interrupts must be switched OFF and then switched ON again. Example:
DI ;switch off interrupts
CALL CUR_CPY ;Call OS function that changes SP
EI ;then switch on interrupts
'''Corresponding OS functions are in ROM A:'''
CUR_CPY
B8DIN
B16DIN
and all TERM_2 (?) OS functions (because of the control characters!) -> See the following ...
* The text output uses the OS variable C_POS to define the Cursor POSition. If a Task wants to output text, this variable must first be saved, then it must be set for the current text output (then output the text). Then C_POS must be restored again. During this time the interrupts must be switched off. Here's an example:
C_POS EQU &B848
DI ;switch off interrupts
LD HL,(C_POS) ;Store old Cursor-POSition
LD (Buffer),HL
LD HL,&BFFF + (line * 80) + row ;Set new Cursor-POSition
LD (C_POS),HL
LD HL,Text ;Pointer to text
CALL TERM_2 ;Call OS function to print text on screen
LD HL,(Buffer) ;Restore old Cursor-POSition
LD (C_POS),HL
EI ;then switch on interrupts
* The OS ROM A must always be banked in / selected! If the ROM is changed or an OS function is called in the other OS ROMs B,C,D the interrupts must be switched OFF and then switched ON again. See example:
DI ;switch off interrupts
LD IX, LESC ;OS function is located in ROM C -> Load its name to IX
CALL ROM_A2C ;Call OS function in ROM C
EI ;then switch on interrupts again
* Cooperative Tasks can switch to the next task as long as they have nothing to do (e.g. waiting for an event, etc.) This is done through the commands:
DI ;disable interrupts
RST 7 ;call interrupt entry
The 'DI' command is required to counteract a simultaneous interrupt.
Without the 'DI' command the consequences could be fatal.
After processing the 'RST 7', the interrupts are switched on again.
The command sequence 'DI: RST 7' thus corresponds to a system interrupt.
* Each Task has to set some bits of the Action and Configuration bits itself. These are located in memory locations &7FF8 and &7FF9 (see above!).
* Tasks with full screen capability are able to use the entire screen. Such Tasks have set bit 1 (switch bit) of address &7FF8 in their E-RAM. All other tasks (e.g. without screen output) should delete this Switch bit. Every Foreground task should regularly check bit 0 (Foreground bit) ats &7FF8. Because if it's set, the entire screen is available to the Task. If the 'ESC' key is pressed, the Task should switch itself back to Background. This is done by deleting bit 0 at address &7FF8 in the E-RAM of the Task.
* If a Task wants to end itself and remove itself from the system, it sets the bit 3 (Kill bit). The system will delete the Task at times.
Specifically, this means that the task writes the value &08 to the address &7FF8 and can then call the task manager using 'DI: RST 7'. A jump to the previous 'DI' command should then follow. Example:
LOOP DI ;interrupts off, this is necessary before EVERY RST 7!
RST 7 ;Call Caruh (or next task) ...
JR LOOP ;waiting for the task to be terminated by Caruh
* Storable Tasks are Tasks that work together with the system to save a copy of themselves. To indicate to the system that it is a storable task, the Task independently sets bit 4 (Storable bit) at address &7FF8 in its own E-RAM.
Tasks that do not attach importance to being able to be saved should delete this bit 4 once when they are called the first time.
A storable Task should regularly check whether the system wants to save it now. This is the case when Caruh sets bit 0 (Save bit).
As soon as the Save bit has been set at address &7FF8, the task should take all necessary steps to prepare for saving.
If the task is ready to be saved, then it must set bit 6 (Hold bit) at the address &7FF8.
The Task is then saved, and Caruh takes care of this process.
As soon as the Task has been successfully saved by Caruh, Caruh sets bit 5 (Secured-Bit) at the Tasks E-RAM address &7FF8.
The Task now knows that it has been saved successfully. The Task now needs to reset the 'Secured Bit' and jump to address &4000.
Tasks saved by the Caruh system are loaded (like any other) to address &4000 and also started there.
