Revision as of 11:11, 1 November 2023 (view source) TFM (Talk | contribs) (→‎Memory address &7FF8 (TCON8)) ← Older edit		Revision as of 11:14, 1 November 2023 (view source) TFM (Talk | contribs) (→‎Memory address &7FF8 (TCON8)) Newer edit →
Line 367:		Line 367:
	Bit 7: = 1 -> The system asks the Task to prepare for its saving. It is then restarted again at address &4000. (Save bit)		Bit 7: = 1 -> The system asks the Task to prepare for its saving. It is then restarted again at address &4000. (Save bit)
		+
		+	==== Memory address &7FF9 (TCON9) ====
		+	* Reserved for future expansions

---

Revision as of 11:14, 1 November 2023

Caruh - the Multitasking-Manager for FutureOS

Overview

General information

The 'Caruh' application is part of the FutureOS operating system. Caruh is a tasker, that's a multitasking manager. Or rather, a program to run several applications (tasks) at the same time on the CPC. The individual 'Tasks' can behave cooperatively.

What properties does Caruh have or do the Tasks have?

• The Caruh application is located in the lower RAM between &0000 and &37FF. The area from &4000 to &7FFF is used in addition (for buffers, tables)
• Caruh works in screen MODE 2, in the 80 character x 25 line format
• CBM is used as the user interface: So Caruh can be used like to operate most other FutureOS applications.
• In addition to the pull-down menus at the top of the screen, there is another Task-Bar at the bottom of the screen. The names of four tasks are displayed there in the middle. With the arrows all the way left and right you can scroll horizontally through the names of the tasks
• The surface of Caruh offers functions to load, save, terminate or change the priority of one or more tasks
• The maximum number of different tasks is 255 (with a 4 MB RAM expansion)
• A task can reach a maximum size of 15.75 KB
• The tasks are managed dynamically. Task numbers can therefore change. For example, when a task is deleted, the higher task numbers are adjusted
• Each task has its own 16 KB expansion RAM (E-RAM). These E-RAMs are banked in between &4000 and &7FFF. Accordingly a task is always assembled at the start address &4000.

Types of Tasks

There are foreground and background tasks. A background task can be switched to be a foreground task by the user - if the task allows this (is capable of).

Foreground Tasks

A foreground task is able to take over the entire screen and to write on it. In addition he can also scan the keyboard.

He has to respond to the 'ESCape' key. In case the key was pressed then the task must return control back to Caruh.

Every foreground task is always also a background task (as long as it has not taken over the output to the screen).

Only the user can switch a background task to the foreground! There can only be one foreground task at a time!

Background Tasks

A background task is only allowed to write on the common screen. There he can reserve screen areas.

Summary

1. A task can be a (pure) background task

• He may reserve parts of the general screen and write on it
• He is not allowed to take over the entire screen
• It's identified by a cleared bit #0 at address &7FF8 (TCON8) in its E-RAM

2. A task can be switched to the 'foreground' by Caruh.

• There is always only one foreground task
• When starting Caruh, Caruh itself is the foreground task
• If another task becomes the 'Foreground Task', it's allowed to use the entire screen area. And the keyboard and the joysticks.
• However, he must also be able to give control back to Caruh at 'ESC'
• It's identified by a set bit 0 at address &7FF8 (TCON8) in E-RAM

Attention: To be able to switch a task to the foreground, bit 1 at address &7FF8 (TCON8) must be set. This is done by the task itself.

Pressing the 'ESCape' key must switch the task back to the background! Caruh itself checks for ESC. But the task must / should do that too.

Using the Tasker Caruh

Submenu File

Load <T>ask - Hotkey: t or T - To load and start a Task

This function is to load a Task of a maximum file size of 16 KB. The Task will be started right away.

Save Tas<k> - Hotkey: k or K - To save a Task

This function provides a way to save a 16 KB sized memory dump of a Task to any kind of media. Saving works in cooperation with the Task, so the Task can get prepared to be saved. A saved Task can be used to continue it later or on another computer (also it can be used for debugging purposes).

Load all - Hotkey: a or A - Loads and starts all tagged files as Tasks

This function can load a bunch of files as Tasks. Usually you would first mark all the Task-files in the FutureOS Turbo Destiop you would like to use. Then use this function to load and start them all. This way you can start up with a selection of your favorite Tasks at once.

Save tabl - Hotkey: s or S - Saves 16 KB Task-Table (--> for debugging)

This function actually saves 16 KB of the main RAM from &4000 to &7FFF. This area contains Task variables, the Task Table and the VRAM Table. Yes, this is for debugging purposes :-)

Read DIRs - Hotkey: r or R - Reads the DIRs of all tagged drives

Here you can select the drives / media / devices you want to use and load their DIRectories. This will make the devices accessible for Load and Save operations

Close - Hotkey: c or C - End all Tasks. Quit this application

This function will end and clear all Tasks, release the previously used E-RAM of the Tasks and end the Application Caruh.

Version - Hotkey: v or V - Shows version number of Caruh

This one will display the name of the application Caruh, its current version number and the date of the last major change of code.

Quit - Hotkey: q or Q - End all Tasks. Quit this application

See 'Close' above

Submenu Process

Clear - Hotkey: l or L - Clear task = '<E>nd Task' (see below)

This function will end and clear a Task. The E-RAM of the Task will be released

Go To - Hotkey: o or L - Go To a Task = 'Switch <t>o' (see below)

This function will switch a Task to the Foreground, if the Task is able to do.

Call OS - Hotkey: a or A - Call the Desktop, return with the OK icon

Here the user can call the Turbo Desktop of FutureOS temporarily. In the Desktop you can f.e. tag some files or what every you want. But you must use the 'OK' Icon to return to the Task Manager Caruh.

Submenu Options

Mode - Hotkey: m or M - Select the screen MODE 0-3 for Tasks

The user can select the screen mode for Tasks here. You can select MODEs 0-3. Yes, also MODE 3, which probably will not be used that often. However, the interface of Caruh will remain in MODE 2.

Colour - Hotkey: c or C - Select color for Pen, Paper or Border

The colors for BORDER, PAPER and PENs 0-15 can be selected here. This is valid for Caruh and all working Tasks.

Format - Hotkey: f or F - Select Task screen format (80x25, 64x32)

The screen format can be selected here for the Tasks. But it will not change the appearance of Caruh's interface itself.

Language - Hotkey: l or L - Select your language for Tasks

The language of FutureOS can be adjusted here. The selected language can be read from the configuration variable KF_CPC (at &B976) in bits 5, 4 and 3:

5,4,3	000	OS language set to German
5,4,3	001	OS language set to French
5,4,3	010	OS language set to Englisch
5,4,3	011	OS language set to Greek
5,4,3	100	OS language set to Spanish
5,4,3	101	OS language set to Dutch

Any Task can read which language was selected. But Caruh itself will not change its language texts, because this would waste too much main memory. Caruh can be obtained in any (of the above) languages. See downloads.

Submenu Tasks

Start Task - Hotkey: s or S - To load and Start a Task

See 'Load Task' above

End Task - Hotkey: s or S - To end and delete a Task

See 'Clear' above

Priority - Hotkey: s or S - Set the Priority of a Task 1-255

This function can set the priority of any Task. 1 is the highest and 255 is the slowest. Basically this number tells how big the waiting time is 1/300 seconds

Switch to - Hotkey: t or T - Switch a Task to Foreground

See 'Go To' above

Submenu Help

Help - Hotkey: h or H - Show a help screen

Just a little help screen.

Info - Hotkey: i or I - Shows version number of Caruh (meanwhile)

See 'Version' above

News - Hotkey: n or N - Shows version number of Caruh (meanwhile)

See 'Version' above

Menu - Hotkey: m or M - Shows help about the used surface

Some little help how to use the interface of Caruh. It's based on CBM framework

-$$$- - Hotkey: $ or 4 - Tells how to spend money for this project

Nobody ever did spend a Nickle for my work, so I'm not going into this here ;-)

.www. - Hotkey: w or W - Tells where to find you in the internet

Here is your gateway the the FutuerOS homepage which does support Caruh too :-)

Construction of Caruh

Memory allocation of the Caruh application in the lower RAM

Caruh's program code starts in the RAM at &0000 and currently extends to &2000. From address &3800 the character set is up to &3FFF (as usual). So there are still about 5-6 KB available for future extensions of Caruh.

There are few variables in the lower RAM, as it's planned to integrate Caruh in a lower ROM one day.

However, there are some entries of OS functions being of interest for the Tasks and their programmer.

Variables in Caruh

• Memory address &000E contains the screen MODE (0-3) which was set by the user with the help of Caruh. Each task can read the desired (user set) screen mode from this byte in case the task is switched to the Foreground.

• Memory address &000F contains the user defined screen format. The format was set by the user using Caruh (0 for 80x25, 1 for 68x30 and 3 for 64x32 format). Each task can read the desired screen format from this byte if the task is switched to the Foreground.

Entries in Caruh

• The 'SAOMS' function can be called at RAM address &0003. It allows the user to reserve a part of the multi-screen (regular view).

• The menu system 'M_DISP2' known from CBM can be called at address &0008 with the command 'RST 1'.

• The window frame drawer 'DR_WIN' known from CBM can be called with using the command 'CALL &000B'.

• The function 'SEPRI' is called at address &0010 using the Z80 command 'RST 2'. Using 'SEPRI' a task can change its priority. Each task is started with the highest priority '1' after loading. Values from 1 to 255 are permitted. Smaller values have higher priority.

• The 'RFMSA' function is called at address &0013 using command 'CALL &0013'. 'RFMSA' is used to reserve a part of the shared screen for a Task. This means the view that can be seen after Caruh has started. The task is then allowed to write in this area.

Memory allocation of the Caruh application in the central RAM

The central RAM (main memory &7FC0) is occupied as follows from &4000 to &7FFF. There are three RAM sections that are used for Task management:

• Task variables: these are contained in the first element of the task table or in the upper RAM

• Task table: this table contains one element for each task from 1-255

• VRAM table: this table defines which task uses which part of the screen

Task variables

The Task variables are used by Caruh to manage the individual tasks, they show what's currently going on.

• &4000 (TASK_AKT): This byte points to the number of the current task that is currently active.

• &4001 (TASK_NUM): This byte contains the number of all existing tasks.

• &4002 (DIS_A_T): This byte contains the number of the first task in the Task bar in the lower line on screen. This means the left Task at the bottom line

• &400C/D (TA_ESEL): These 16 bits contain the I/O E-RAM select when a new task is loaded into the E-RAM of the computer.

• &400E/F (TA_OSEV): These 16 bits contain a pointer to one of the XRAM_?? variables when a new task is loaded into the E-RAM

• &4010: The first element of task #1 (16 bytes) starts at this address. In Caruh's source code this would be 'TT_START + T_T_E_L'. Whereby TT_START (= &4000) + T_T_E_L (= &0010) results in &4010!

• &7FE4-&7FFF: This area is required for Caruh itself (as task #1)!

In the upper RAM, two more bytes are used by Caruh! They are used for communication between Caruh and the Tasks:

• &BE02 (CCON2): Central communication byte between Caruh and the Tasks

Structure of memory address &BE02 (CCON2)

Bit 0: = 0 -> All tasks are in the background (this is the normal state). In this case Caruh works as Foreground Task

Bit 0: = 1 -> A task is active in the foreground, i.e. takes over the screen, keyboard query, etc. This bit is switched on by the Task itself as soon as it has actively taken control of the complete screen etc. This bit MUST also be cleared by the Task itself as soon as it returns control of the screen (and keyboard) to Caruh. When you press the ESC key, the Task must return the control of screen and keyboard to Caruh. To do this, clear bit 0 at &BE02!

Bit 1: -> reserved

Bit 2: -> reserved

Bit 3: -> reserved

Bit 4: -> reserved

Bit 5: -> reserved

Bit 6: -> reserved

Bit 7: = 0 -> Caruh does not print on screen right now -> Tasks run as usual

Bit 7: = 1 -> Caruh prints text on the screen. For example it displays menus, provides selectors for files or options and so on. -> Tasks shall NOT use the screen as long as this bit is set!

• &BE03 (TTNS3): Temporary buffer for a Task number memory at &BE03. Stores the number of a task (2-255) for subroutines

The Task Table

The Task Table starts mathematically at &4000 in the main memory. An entry in the Task Table is 16 bytes long. Accordingly, it extends from &4000 to &4FFF in the central RAM (&7FC0).

However, the first element of the task table with number '0' has a special assignment: Since there is no task with the number &00, the bytes &4000-&400F are available for the task variables (see above under 'Task variables').

The first real element therefore starts at &4010 for the first task (#1).

Each element consists of 16 bytes:

• 0: Task number (= number of the task managed by this entry)
• 1: Priority: How many 1/300 seconds are waited until the task will be called again. The value 0 is interpreted as 256. The smaller the value, the higher the task priority.
• 2: Reload value for the Priority byte, used as soon as the Priority byte has reached the value &00 (see previous byte 1)
• 3-4: These 16 bits contain the E-RAM select in which the task is located (16 bit, physical I/O address: &7FC4-&78FF, covers 4 MB)
• 5-15: The name of the Task, it corresponds to the file name (11 letters)

The data for Task #2 follows at address &4020, on &4030 for task #3, to &4040 for task #4 and so on ...

The VRAM / multi-screen table

As long as Caruh is active as a Foreground Task, other tasks can only use parts of the general screen. That's the screen that appears after starting Caruh with its menu system.

As long as the 'General Screen' is used, the following is possible:

• Each Task can reserve parts of the VRAM / general screen or itself.
• Each Task may write, draw or output data in any way on parts of the general screen (previously) reserved for it.
• No chaotic, overlapping windows are used!

This way it's possible for all Tasks to output data on the main screen. This is the multi-screen mode.

The VRAM or multi-screen table is used to divide the screen (80 characters on 25 lines). This table comprises 2000 bytes (= 80 * 25).

The Table is located in the main memory from &7800 to &7FCF. The bytes from &7FD0 to &7FFF are therefore NOT part of the Task Table.

Each byte of the VRAM (multi-screen) table corresponds to one character on the screen.

The VRAM Table begins with the first character in the top line on the far left. That's followed by 'character by character' on the first line (left to right). This is followed by 'line by line' from 'top to bottom'.

What's the meaning of the bytes in the VRAM table?

A zero byte in the VRAM Table defines an available/free screen position and is therefore available for Tasks.

If a byte in the Table is occupied by a value (1-255), then the corresponding position on the screen is already occupied by a Task.

Caruh occupies the top four lines and the bottom line of the screen for his own menu system and the lower Task Bar.

Structure of a Task

The entry / start / load address of each task is always at address &4000 The file length may not exceed 16 KB (including a potential header!)

Each task occupies a 16 KB block (E-RAM block) from &4000 to &7EFF The first 512 KB of expansion memory are currently being used for this. However, the full 4 MB E-RAM should soon be used (-> Update2025)

Structure of any Task within its 16 KB block

• &4000-&7EFF: Program area -> Application length maximum 15.75 KB
• &7F00-&7FF7: Stack (each Task has its own Stack). Contains 124 elements
• &7FF8-&7FF9: (TCON8 and TCON9) 16 Action and Configuration bits. Please have a look at the following section :-)
• &7FFA-&7FFB: (TER16) 16 bit E-RAM selection of the Task (&7FC4-&78FF)
• &7FFC: (TAPRI) Value that is copied from the parttime/priority variable of the Task Table (if the priority is changed). (So how many 1/300 seconds is waited before the task is called.) It is the priority byte
• &7FFD: (TNUME) Number of this Task &01-&FF (255 Tasks are possible). The tasks are dynamic! (Variable name in Caruh: TNUME)
• &7FFE-&7FFF: (TSPSE) Buffer for the stack pointer SP of this Task. When switching Tasks, the register SP is also backed up

 -> The program to be loaded (without header) is a maximum of &3F00 bytes long
 -> The program to be loaded (with header) is a maximum of &3F80 bytes long

When a Task is started for the first time, its stack pointer SP is set to &7FF8. This is how the first 16-bit stack element is written to addresses &7FF6 and &7FF7. This is usually the return address when switching Tasks

The action and configuration bits

Memory locations &7FF8 / &7FF9 of each task contain 16 Action and Configuration bits. In addition there are Reaction bits that are set by the task:

Memory address &7FF8 (TCON8)

• Bits 1, 3, 4 and 6 are set by the task and
• Bits 2 and 7 are set by Caruh
• Bits 0 and 5 are manipulated by both Caruh and the task itself.

Bit 0: = 0 -> Task is in the Background (this is the regular state)

Bit 0: = 1 -> Task is active in the Foreground, i.e. takes over the screen, keyboard query etc. This bit is switched on by Caruh. It is / can be cleared by the task. (Foreground bit)

Bit 1: = 0 -> Task cannot become a Foreground Task

Bit 1: = 1 -> Task can be switched as a Foreground Task. This bit must be set by the Task itself! (Switch bit)

Bit 2: -> reserved

Bit 3: = 0 -> Regular function -> Task continues to work normally ...

Bit 3: = 1 -> Setting this bit determines the Task to be deleted! This bit is set by the Task itself! (Kill bit)

Bit 4: = 0 -> The Task cannot be saved or does not have to be specially prepared for it using 'Save Bit 7'.

Bit 4: = 1 -> This Task can be saved and should be prepared using bit 7. This bit is set by the Task itself! (Storable bit)

Bit 5: = 0 -> The Task has not yet been saved.

Bit 5: = 1 -> The Task was saved after the save bit was set. This bit 5 is set by the Caruh system after saving. (Hold bit 6 was previously set by the task itself). This bit 5 must be reset by the task itself if the task is to be saved several times. (Secured bit)

Bit 6: = 0 -> Task is still in progress -> do not save right now! Wait!

Bit 6: = 1 -> Task can now be saved by the system at any time! This bit must be set by the Task itself! (Hold bit)

Bit 7: = 0 -> Regular sequence. Task is running...

Bit 7: = 1 -> The system asks the Task to prepare for its saving. It is then restarted again at address &4000. (Save bit)

Memory address &7FF9 (TCON9)

• Reserved for future expansions