From 903244d22b66746b4781a035dbb73d01546d0c11 Mon Sep 17 00:00:00 2001 From: Rodrigo Arias Date: Mon, 5 Sep 2022 20:17:56 +0200 Subject: [PATCH] Update documentation --- doc/emulation/events.md | 37 ++-- doc/emulation/nanos6.md | 87 +++++----- doc/fig/palette.svg | 326 ++++++++++++++++++++++++++++++++++++ doc/fig/subsystem-stack.svg | 202 ++++++++++++++++++++++ 4 files changed, 593 insertions(+), 59 deletions(-) create mode 100644 doc/fig/palette.svg create mode 100644 doc/fig/subsystem-stack.svg diff --git a/doc/emulation/events.md b/doc/emulation/events.md index 01a0760..05e70cd 100644 --- a/doc/emulation/events.md +++ b/doc/emulation/events.md @@ -6,7 +6,7 @@ This file contains an exhaustive list of events supported by the emulator. - All events refer to the current thread. - Descriptions must be kept short. -``` +```txt ********************************************************** Please keep this list synchronized with the emulator code! ********************************************************** @@ -141,27 +141,27 @@ KCI Is back in the CPU due to a context switch 6TC Task creation ends 6Tx Task execute 6Te Task end -6Tb Task block -6Tu Task unblock +6Tp Task pause +6Tr Task resume 6Yc Task type create (punctual event) +6S[ Enters the scheduler serving mode +6S] Ends the scheduler serving mode +6Sa Begins to submit a ready task via addReadyTask() +6SA Ends submitting a ready task via addReadyTask() 6Sr Receives a task from another thread (punctual event) 6Ss Sends a task to another thread (punctual event) 6S@ Self-assigns itself a task (punctual event) -6Sh Enters the hungry state, waiting for a task -6Sf Is no longer hungry -6S[ Enters the scheduler server mode -6S] Ends the scheduler server mode -6Su Begins a ready task submission via addReadyTask() -6SU Ends a ready task submission via addReadyTask() + +6W[ Begins the worker body loop, looking for tasks +6W] Ends the worker body loop +6Wt Begins handling a task via handleTask() +6WT Ends handling a task via handleTask() 6U[ Starts to submit a task via submitTask() 6U] Ends the submission of a task via submitTask() -6Ha Attaches to Nanos6 as external thread -6HA Detaches from Nanos6 as external thread - 6F[ Begins to spawn a function via spawnFunction() 6F] Ends spawning a function @@ -170,12 +170,21 @@ KCI Is back in the CPU due to a context switch 6Du Begins the unregistration of a task's accesses 6DU Ends the unregistration of a task's accesses -6Bu Begins to unblock a task -6BU Ends unblocking a task 6Bb Begins to block the current task via blockCurrentTask() 6BB Ends blocking the current task via blockCurrentTask() +6Bu Begins to unblock a task +6BU Ends unblocking a task 6Bw Enters taskWait() 6BW Exits taskWait() 6Bf Enters taskFor() 6BF Exits taskFor() + +6He Sets itself as external thread +6HE Unsets itself as external thread +6Hw Sets itself as worker thread +6HW Unsets itself as worker thread +6Hl Sets itself as leader thread +6HL Unsets itself as leader thread +6Hm Sets itself as main thread +6HM Unsets itself as main thread ``` diff --git a/doc/emulation/nanos6.md b/doc/emulation/nanos6.md index 8d7c169..d34f0f9 100644 --- a/doc/emulation/nanos6.md +++ b/doc/emulation/nanos6.md @@ -89,59 +89,56 @@ presents that section as the current state of the execution, in this case the section $`S_3`$. Additionally, the runtime sections $`S_i`$ are grouped together in -subsystems, which form a closely related group of functions. The -complete list of subsystems and sections is shown below. +subsystems, which form a closely related group of functions. When there is no +instrumented section in the thread stack, the state is set to **No subsystem**. +The complete list of subsystems and sections is shown below. -When there is no instrumented section in the thread stack, the state is -set to **No subsystem**. +- **Task subsystem**: Controls the life cycle of tasks -Task subsystem -: The **Task** subsystem contains the code that controls the life cycle -of tasks. It contains the following sections: + - **Body**: Executing the body of the task (user defined code). + + - **Spawning function**: Spawning a function as task that will be submitted + for later execution. + + - **Creating**: Creating a new task via `nanos6_create_task` + + - **Submitting**: Submitting a recently created task via + `nanos6_submit_task` -- **Body**: Executing the body of the task (user defined code). +- **Scheduler subsystem**: Queueing and dequeueing ready tasks. -- **Spawning function**: Spawning a function as task (it will be - submitted to the scheduler for later execution). + - **Serving tasks**: Inside the scheduler lock, serving tasks + to other threads + + - **Adding ready tasks**: Adding tasks to the scheduler queues, + but outside of the scheduler lock. -- **Creating**: Creating a new task, through `nanos6_create_task` -- **Submitting**: Submitting a recently created task, through -`nanos6_submit_task` +- **Worker subsystem**: Actions that relate to worker threads, which + continuously try to execute new tasks. -Scheduler subsystem -: The **Scheduler** system groups the actions that relate to the queueing -and dequeueing of ready tasks. It contains the following sections: + - **Looking for work**: Actively requesting tasks from the scheduler, + registered but not holding the lock. + + - **Handling task**: Processing a recently assigned task. -- **Waiting for tasks**: Actively waiting for tasks inside the -scheduler subsystem, registered but not holding the scheduler lock +- **Dependency subsystem**: Manages the registration of task + dependencies. -- **Serving tasks**: Inside the scheduler lock, serving tasks -to other threads + - **Registering**: Registering dependencies of a task + + - **Unregistering**: Releasing dependencies of a task because + it has ended -- **Adding ready tasks**: Adding tasks to the scheduler queues, -but outside of the scheduler lock. +- **Blocking subsystem**: Code that stops the thread execution. -Dependency subsystem -: The **Dependency** system only contains the code that manages the -registration of task dependencies. It contains the following sections: - -- **Registering**: Registering a task's dependencies - -- **Unregistering**: Releasing a task's dependencies because -it has ended - -Blocking subsystem -: The **Blocking** subsystem deals with the code stops the thread -execution. It contains the following sections: - -- **Taskwait**: Task is blocked while inside a taskwait - -- **Blocking current task**: Task is blocked through the Nanos6 -blocking API - -- **Unblocking remote task**: Unblocking a different task using -the Nanos6 blocking API - -- **Wait For**: Blocking a deadline task, which will be -re-enqueued when a certain amount of time has passed + - **Taskwait**: Task is blocked due to a `taskwait` clause + + - **Blocking current task**: Task is blocked through the Nanos6 + blocking API + + - **Unblocking remote task**: Unblocking a different task using the + Nanos6 blocking API + + - **Wait for deadline**: Blocking a deadline task, which will be + re-enqueued when a certain amount of time has passed diff --git a/doc/fig/palette.svg b/doc/fig/palette.svg new file mode 100644 index 0000000..8435fe0 --- /dev/null +++ b/doc/fig/palette.svg @@ -0,0 +1,326 @@ + + + + + + + + + + + Task: Executing body + + Worker: Waiting for work + + Task: Creating + + Block: Taskwait + + Scheduler: Adding ready tasks + + Dependency: Registering + + Dependency: Unregistering + + Scheduler: Serving tasks + + Block: Taskfor + + Worker: handling task + + Task: Subtmitting + + + + + + + + + + + + + + + diff --git a/doc/fig/subsystem-stack.svg b/doc/fig/subsystem-stack.svg new file mode 100644 index 0000000..6a92c2a --- /dev/null +++ b/doc/fig/subsystem-stack.svg @@ -0,0 +1,202 @@ + + + + + + + + + + + + + + + + + + + + Creating new task + Unknown (app code) + Running task Body + Worker Body + Unknown (memory alloc) + Other frames ... + + Subsystem=Creating new task + Thread stack + +