306 lines
14 KiB
Markdown
306 lines
14 KiB
Markdown
# taskswitch -- Cooperative Task Switching Library for DJGPP
|
|
|
|
A lightweight cooperative multitasking library targeting DJGPP (i386 protected
|
|
mode DOS). Tasks voluntarily yield the CPU with `tsYield()`. A credit-based
|
|
weighted round-robin scheduler ensures every task runs while giving
|
|
higher-priority tasks proportionally more CPU time.
|
|
|
|
The task array grows dynamically using stb_ds and terminated task slots are
|
|
recycled, so there is no fixed upper limit on the number of tasks created
|
|
over the lifetime of the application.
|
|
|
|
## Files
|
|
|
|
| File | Description |
|
|
|-----------------------|------------------------------------------|
|
|
| `taskswitch.h` | Public API -- types, constants, functions |
|
|
| `taskswitch.c` | Implementation |
|
|
| `demo.c` | Example program exercising every feature |
|
|
| `thirdparty/stb_ds.h` | Dynamic array/hashmap library (stb) |
|
|
| `Makefile` | DJGPP cross-compilation build rules |
|
|
|
|
## Building
|
|
|
|
Cross-compiling from Linux:
|
|
|
|
```
|
|
make
|
|
```
|
|
|
|
Clean:
|
|
|
|
```
|
|
make clean
|
|
```
|
|
|
|
Output:
|
|
|
|
| Path | Description |
|
|
|-------------------|----------------------------|
|
|
| `../lib/libtasks.a` | Static library |
|
|
| `../obj/tasks/` | Object files |
|
|
| `../bin/tsdemo.exe` | Demo executable |
|
|
|
|
## Quick Start
|
|
|
|
```c
|
|
#include <stdio.h>
|
|
#include "taskswitch.h"
|
|
|
|
void myTask(void *arg) {
|
|
const char *name = (const char *)arg;
|
|
for (int i = 0; i < 3; i++) {
|
|
printf("[%s] working...\n", name);
|
|
tsYield();
|
|
}
|
|
}
|
|
|
|
int main(void) {
|
|
tsInit();
|
|
tsCreate("alpha", myTask, "alpha", 0, TS_PRIORITY_NORMAL);
|
|
tsCreate("beta", myTask, "beta", 0, TS_PRIORITY_HIGH);
|
|
|
|
while (tsActiveCount() > 1) {
|
|
tsYield();
|
|
}
|
|
|
|
tsShutdown();
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
## Lifecycle
|
|
|
|
1. **`tsInit()`** -- Initialize the task system. The calling context
|
|
(typically `main`) becomes task 0 with `TS_PRIORITY_NORMAL`.
|
|
|
|
2. **`tsCreate(...)`** -- Create tasks. Each gets a name, entry function,
|
|
argument pointer, stack size (0 for the 8 KB default), and a priority.
|
|
Returns the task ID (>= 0) or a negative error code. Terminated task
|
|
slots are reused automatically.
|
|
|
|
3. **`tsYield()`** -- Call from any task (including main) to hand the CPU to
|
|
the next eligible task.
|
|
|
|
4. **`tsShutdown()`** -- Free all task stacks and the task array.
|
|
|
|
Tasks terminate by returning from their entry function or by calling
|
|
`tsExit()`. The main task (id 0) must never call `tsExit()`. When a task
|
|
terminates, its stack is freed immediately and its slot becomes available
|
|
for reuse by the next `tsCreate()` call.
|
|
|
|
## API Reference
|
|
|
|
### Initialisation and Teardown
|
|
|
|
| Function | Signature | Description |
|
|
|----------------|------------------------------|--------------------------------------------------------------------------------------|
|
|
| `tsInit` | `int32_t tsInit(void)` | Initialise the library. Returns `TS_OK` or a negative error code. |
|
|
| `tsShutdown` | `void tsShutdown(void)` | Free all resources. Safe to call even if `tsInit` was never called. |
|
|
|
|
### Task Creation and Termination
|
|
|
|
| Function | Signature | Description |
|
|
|------------|----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
|
|
| `tsCreate` | `int32_t tsCreate(const char *name, TaskEntryT entry, void *arg, uint32_t ss, int32_t pri)` | Create a ready task. Returns the task ID (>= 0) or a negative error code. Pass 0 for `ss` to use `TS_DEFAULT_STACK_SIZE` (8 KB). Reuses terminated task slots when available. |
|
|
| `tsExit` | `void tsExit(void)` | Terminate the calling task. Must not be called from the main task. |
|
|
| `tsKill` | `int32_t tsKill(uint32_t taskId)` | Forcibly terminate another task. Frees its stack and marks the slot for reuse. Cannot kill the main task (id 0) or the calling task (use `tsExit` instead). |
|
|
|
|
### Scheduling
|
|
|
|
| Function | Signature | Description |
|
|
|-----------|-----------------------|--------------------------------------------------------------------------|
|
|
| `tsYield` | `void tsYield(void)` | Voluntarily relinquish the CPU to the next eligible ready task. |
|
|
|
|
### Pausing and Resuming
|
|
|
|
| Function | Signature | Description |
|
|
|------------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------|
|
|
| `tsPause` | `int32_t tsPause(uint32_t id)` | Pause a task. The main task (id 0) cannot be paused. If a task pauses itself, an implicit yield occurs. |
|
|
| `tsResume` | `int32_t tsResume(uint32_t id)` | Resume a paused task. Its credits are refilled to `priority + 1` so it is not penalised for having been paused. |
|
|
|
|
### Priority
|
|
|
|
| Function | Signature | Description |
|
|
|-----------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------|
|
|
| `tsSetPriority` | `int32_t tsSetPriority(uint32_t id, int32_t pri)`| Change a task's priority. Credits are reset to `pri + 1` so the change takes effect immediately. |
|
|
| `tsGetPriority` | `int32_t tsGetPriority(uint32_t id)` | Return the task's priority, or `TS_ERR_PARAM` on an invalid ID. |
|
|
|
|
### Crash Recovery
|
|
|
|
| Function | Signature | Description |
|
|
|-------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------|
|
|
| `tsRecoverToMain` | `void tsRecoverToMain(void)` | Reset scheduler state to the main task (id 0) after a `longjmp` from a signal handler. Call before `tsKill` on the crashed task. This fixes the scheduler's bookkeeping when a non-main task crashes and execution is transferred back to main via `longjmp`. |
|
|
|
|
### Query
|
|
|
|
| Function | Signature | Description |
|
|
|-----------------|-----------------------------------------|---------------------------------------------------------------|
|
|
| `tsGetState` | `TaskStateE tsGetState(uint32_t id)` | Return the task's state enum value. |
|
|
| `tsCurrentId` | `uint32_t tsCurrentId(void)` | Return the ID of the currently running task. |
|
|
| `tsGetName` | `const char *tsGetName(uint32_t id)` | Return the task's name string, or `NULL` on invalid ID. |
|
|
| `tsActiveCount` | `uint32_t tsActiveCount(void)` | Return the number of non-terminated tasks. |
|
|
|
|
## Constants
|
|
|
|
### Error Codes
|
|
|
|
| Name | Value | Meaning |
|
|
|----------------|-------|--------------------------------------|
|
|
| `TS_OK` | 0 | Success |
|
|
| `TS_ERR_INIT` | -1 | Library not initialised |
|
|
| `TS_ERR_PARAM` | -2 | Invalid parameter |
|
|
| `TS_ERR_FULL` | -3 | Task table full (unused, kept for compatibility) |
|
|
| `TS_ERR_NOMEM` | -4 | Memory allocation failed |
|
|
| `TS_ERR_STATE` | -5 | Invalid state transition |
|
|
|
|
### Priority Presets
|
|
|
|
| Name | Value | Credits per Round |
|
|
|----------------------|-------|-------------------|
|
|
| `TS_PRIORITY_LOW` | 0 | 1 |
|
|
| `TS_PRIORITY_NORMAL` | 5 | 6 |
|
|
| `TS_PRIORITY_HIGH` | 10 | 11 |
|
|
|
|
Any non-negative `int32_t` may be used as a priority. The presets are
|
|
provided for convenience.
|
|
|
|
### Defaults
|
|
|
|
| Name | Value | Description |
|
|
|-------------------------|-------|-------------------------|
|
|
| `TS_DEFAULT_STACK_SIZE` | 8192 | Default stack per task |
|
|
| `TS_NAME_MAX` | 32 | Max task name length |
|
|
|
|
## Types
|
|
|
|
### `TaskStateE`
|
|
|
|
```c
|
|
typedef enum {
|
|
TaskStateReady = 0, // Eligible for scheduling
|
|
TaskStateRunning = 1, // Currently executing
|
|
TaskStatePaused = 2, // Suspended until tsResume()
|
|
TaskStateTerminated = 3 // Finished; slot will be recycled
|
|
} TaskStateE;
|
|
```
|
|
|
|
### `TaskEntryT`
|
|
|
|
```c
|
|
typedef void (*TaskEntryT)(void *arg);
|
|
```
|
|
|
|
The signature every task entry function must follow. `arg` is the pointer
|
|
passed to `tsCreate`.
|
|
|
|
## Scheduler Details
|
|
|
|
The scheduler is a **credit-based weighted round-robin**.
|
|
|
|
1. Every ready task holds a credit counter initialised to `priority + 1`.
|
|
2. When `tsYield()` is called, the scheduler scans tasks starting one past
|
|
the current task (wrapping around) looking for a ready task with
|
|
credits > 0. When found, that task's credits are decremented and it
|
|
becomes the running task.
|
|
3. When **no** ready task has credits remaining, every ready task is
|
|
refilled to `priority + 1` and the scan repeats.
|
|
|
|
This means a priority-10 task receives 11 turns for every 1 turn a
|
|
priority-0 task receives, but the low-priority task still runs -- it is
|
|
never starved.
|
|
|
|
Credits are also refilled when:
|
|
|
|
- A task is **created** (`tsCreate`) -- starts with `priority + 1`.
|
|
- A task is **resumed** (`tsResume`) -- refilled so it is not penalised.
|
|
- A task's **priority changes** (`tsSetPriority`) -- reset to `new + 1`.
|
|
|
|
## Task Slot Management
|
|
|
|
The task array is a stb_ds dynamic array that grows automatically as needed.
|
|
Each slot has an `allocated` flag:
|
|
|
|
- **`tsCreate()`** scans for the first unallocated slot (starting at index 1,
|
|
since slot 0 is always the main task). If no free slot exists, the array
|
|
is extended with `arrput()`.
|
|
- **`tsExit()`** frees the terminated task's stack immediately and marks the
|
|
slot as unallocated, making it available for the next `tsCreate()` call.
|
|
- Task IDs are stable array indices. Slots are never removed or reordered,
|
|
so a task ID remains valid for queries until the slot is recycled.
|
|
|
|
This design supports long-running applications that create and destroy
|
|
many tasks over their lifetime without unbounded memory growth.
|
|
|
|
## Context Switch Internals
|
|
|
|
Context switching is performed entirely in inline assembly with both i386
|
|
and x86_64 code paths.
|
|
|
|
### i386 (DJGPP target)
|
|
|
|
Six callee-saved values are saved and restored per switch:
|
|
|
|
| Register | Offset | Purpose |
|
|
|----------|--------|-----------------------------------------|
|
|
| EBX | 0 | Callee-saved general purpose |
|
|
| ESI | 4 | Callee-saved general purpose |
|
|
| EDI | 8 | Callee-saved general purpose |
|
|
| EBP | 12 | Frame pointer |
|
|
| ESP | 16 | Stack pointer |
|
|
| EIP | 20 | Resume address (captured as local label)|
|
|
|
|
### x86_64 (for native testing)
|
|
|
|
Eight callee-saved values are saved and restored per switch:
|
|
|
|
| Register | Offset | Purpose |
|
|
|----------|--------|-----------------------------------------|
|
|
| RBX | 0 | Callee-saved general purpose |
|
|
| R12 | 8 | Callee-saved general purpose |
|
|
| R13 | 16 | Callee-saved general purpose |
|
|
| R14 | 24 | Callee-saved general purpose |
|
|
| R15 | 32 | Callee-saved general purpose |
|
|
| RBP | 40 | Frame pointer |
|
|
| RSP | 48 | Stack pointer |
|
|
| RIP | 56 | Resume address (RIP-relative lea) |
|
|
|
|
The save and restore pointers are passed into the assembly block via GCC
|
|
register constraints. Segment registers are not saved because DJGPP runs
|
|
in a flat protected-mode environment where CS, DS, ES, and SS share the
|
|
same base.
|
|
|
|
New tasks have their initial stack pointer set to a 16-byte-aligned region
|
|
at the top of a `malloc`'d stack, with the instruction pointer set to an
|
|
internal trampoline that calls the user's entry function and then `tsExit()`.
|
|
|
|
## Limitations
|
|
|
|
- **Cooperative only** -- tasks must call `tsYield()` (or `tsPause`/`tsExit`)
|
|
to allow other tasks to run. A task that never yields blocks everything.
|
|
- **Not interrupt-safe** -- the library uses no locking or `volatile` module
|
|
state. Do not call library functions from interrupt handlers.
|
|
- **Single-threaded** -- designed for one CPU under DOS protected mode.
|
|
- **Stack overflow is not detected** -- size the stack appropriately for each
|
|
task's needs.
|
|
|
|
## Demo
|
|
|
|
`demo.c` exercises five phases:
|
|
|
|
1. **Priority scheduling** -- creates tasks at low, normal, and high priority.
|
|
All tasks run, but the high-priority task gets significantly more turns.
|
|
2. **Pause** -- pauses one task mid-run and shows it stops being scheduled.
|
|
3. **Resume** -- resumes the paused task and shows it picks up where it
|
|
left off.
|
|
4. **Priority boost** -- raises the low-priority task above all others and
|
|
shows it immediately gets more turns.
|
|
5. **Slot reuse** -- creates three waves of short-lived tasks that terminate
|
|
and shows subsequent waves reuse the same task IDs.
|
|
|
|
Build and run:
|
|
|
|
```
|
|
make
|
|
tsdemo
|
|
```
|