From 3aa071944d43bc3faa429bf81c429f7b161fdee9 Mon Sep 17 00:00:00 2001 From: crc Date: Fri, 8 Oct 2021 09:37:52 +0000 Subject: [PATCH] initial docs on multicore support FossilOrigin-Name: c28a8bedba4be3c9865b07b8b67cf4305ee6a244f9e1abb1fc7d2346b308576a --- doc/RETRO-Book.md | 106 ++++++++++++++ doc/book/techniques/multicore | 105 ++++++++++++++ doc/html/chapters/techniques/multicore.html | 152 ++++++++++++++++++++ doc/html/index.html | 2 +- tools/book-chapters.retro | 1 + 5 files changed, 365 insertions(+), 1 deletion(-) create mode 100644 doc/book/techniques/multicore create mode 100644 doc/html/chapters/techniques/multicore.html diff --git a/doc/RETRO-Book.md b/doc/RETRO-Book.md index 27e8c48..134438d 100644 --- a/doc/RETRO-Book.md +++ b/doc/RETRO-Book.md @@ -3316,6 +3316,112 @@ The standard system is configured with a very deep data stack In actual use, your programs are unlikely to ever need this, but if you do, keep the limits in mind. +# Multiple Cores + +Nga has optional support for multiple virtual cores. These +are not directly comparable to actual CPU cores, but do +allow for a degree of multitasking. + +Cores share a single address space for RAM, but each gets +its own data and address stacks, as well as 24 internal +registers for private data storage. The floating point stack +is shared across all cores. + +Execution is handled in a round-robin fashion. After an +instruction bundle is processed, Nga will pass control to the +next active core. Note that this means that execution will +stall when an I/O operation is running. + +## Enabling + +To make use of the multicore support, edit the `Makefile` and +uncomment the lines reading: + + # ENABLED += -DENABLE_MULTICORE + # DEVICES += interface/multicore.retro + +And rebuild. + +## Scheduling + +Nga switches to the next active core after execution of an +instruction bundle completes on the current core. + +## Initialization + +To initialize a core, pass the core identifier (0 through 7) +to `core:init`. This will zero out its internal registers and +set it to. + +Example: + + #4 core:init + +## Starting a Core + +Initialization does not activate a core. To do this, you need +to use `core:start`. Pass this the address of the word to +run and the core number. + +Example: + + :a [ $a c:put ] forever ; + &a #4 core:start + +## Pausing a Core + +Two words are provided for suspending a core. The first is +`core:pause`. Pass this the core number to pause. + +Example: + + #4 core:pause + +The second option is intended if you need the currently +active core to pause. This word is `core:pause-current`. + +Example: + + core:pause-current + +## Resuming a Core + +To reactive a core, use `core:resume`. This takes the core +number to activate. + +Example: + + #4 core:resume + +## Registers + +Each core has 24 internal memory spaces. You can read these +with `core:rr` and modify them with `core:wr`. (These are +used identically to `fetch` and `store`). Registers are +numbered as 0 through 23. + +A core can not access the registers in another core. + +## Napia + +The implementation here is based on the multicore model used +in Napia, the virtual machine being written for the Retro +on smaller targets. Code written to work with this will be +usable on Retro/Napia with minimal changes. + +The main differences are that under Nga, this is an optional +extension, but in Napia, it is part of the standard system. + +## Other Notes + +On startup, execution occurs on core 0, with only core 0 being +initialized. + +I/O is run on the currently active core. Since I/O is blocking, +waiting for an interaction to occur will prevent other cores +from running until the operation is complete. + + # Internals: Nga Virtual Machine ## Overview diff --git a/doc/book/techniques/multicore b/doc/book/techniques/multicore new file mode 100644 index 0000000..b5246c8 --- /dev/null +++ b/doc/book/techniques/multicore @@ -0,0 +1,105 @@ +# Multiple Cores + +Nga has optional support for multiple virtual cores. These +are not directly comparable to actual CPU cores, but do +allow for a degree of multitasking. + +Cores share a single address space for RAM, but each gets +its own data and address stacks, as well as 24 internal +registers for private data storage. The floating point stack +is shared across all cores. + +Execution is handled in a round-robin fashion. After an +instruction bundle is processed, Nga will pass control to the +next active core. Note that this means that execution will +stall when an I/O operation is running. + +## Enabling + +To make use of the multicore support, edit the `Makefile` and +uncomment the lines reading: + + # ENABLED += -DENABLE_MULTICORE + # DEVICES += interface/multicore.retro + +And rebuild. + +## Scheduling + +Nga switches to the next active core after execution of an +instruction bundle completes on the current core. + +## Initialization + +To initialize a core, pass the core identifier (0 through 7) +to `core:init`. This will zero out its internal registers and +set it to. + +Example: + + #4 core:init + +## Starting a Core + +Initialization does not activate a core. To do this, you need +to use `core:start`. Pass this the address of the word to +run and the core number. + +Example: + + :a [ $a c:put ] forever ; + &a #4 core:start + +## Pausing a Core + +Two words are provided for suspending a core. The first is +`core:pause`. Pass this the core number to pause. + +Example: + + #4 core:pause + +The second option is intended if you need the currently +active core to pause. This word is `core:pause-current`. + +Example: + + core:pause-current + +## Resuming a Core + +To reactive a core, use `core:resume`. This takes the core +number to activate. + +Example: + + #4 core:resume + +## Registers + +Each core has 24 internal memory spaces. You can read these +with `core:rr` and modify them with `core:wr`. (These are +used identically to `fetch` and `store`). Registers are +numbered as 0 through 23. + +A core can not access the registers in another core. + +## Napia + +The implementation here is based on the multicore model used +in Napia, the virtual machine being written for the Retro +on smaller targets. Code written to work with this will be +usable on Retro/Napia with minimal changes. + +The main differences are that under Nga, this is an optional +extension, but in Napia, it is part of the standard system. + +## Other Notes + +On startup, execution occurs on core 0, with only core 0 being +initialized. + +I/O is run on the currently active core. Since I/O is blocking, +waiting for an interaction to occur will prevent other cores +from running until the operation is complete. + diff --git a/doc/html/chapters/techniques/multicore.html b/doc/html/chapters/techniques/multicore.html new file mode 100644 index 0000000..7704837 --- /dev/null +++ b/doc/html/chapters/techniques/multicore.html @@ -0,0 +1,152 @@ + + + +. + + +

Multiple Cores +

+Nga has optional support for multiple virtual cores. These +are not directly comparable to actual CPU cores, but do +allow for a degree of multitasking. +

+Cores share a single address space for RAM, but each gets +its own data and address stacks, as well as 24 internal +registers for private data storage. The floating point stack +is shared across all cores. +

+Execution is handled in a round-robin fashion. After an +instruction bundle is processed, Nga will pass control to the +next active core. Note that this means that execution will +stall when an I/O operation is running. +

+Enabling +

+To make use of the multicore support, edit the Makefile and +uncomment the lines reading: +

+# ENABLED += -DENABLE_MULTICORE +# DEVICES += interface/multicore.retro +

+And rebuild. +

+Scheduling +

+Nga switches to the next active core after execution of an +instruction bundle completes on the current core. +

+Initialization +

+To initialize a core, pass the core identifier (0 through 7) +to core:init. This will zero out its internal registers and +set it to. +

+Example: +

+#4 core:init +

+Starting a Core +

+Initialization does not activate a core. To do this, you need +to use core:start. Pass this the address of the word to +run and the core number. +

+Example: +

+:a [ $a c:put ] forever ; +&a #4 core:start +

+Pausing a Core +

+Two words are provided for suspending a core. The first is +core:pause. Pass this the core number to pause. +

+Example: +

+#4 core:pause +

+The second option is intended if you need the currently +active core to pause. This word is core:pause-current. +

+Example: +

+core:pause-current +

+Resuming a Core +

+To reactive a core, use core:resume. This takes the core +number to activate. +

+Example: +

+#4 core:resume +

+Registers +

+Each core has 24 internal memory spaces. You can read these +with core:rr and modify them with core:wr. (These are +used identically to fetch and store). Registers are +numbered as 0 through 23. +

+A core can not access the registers in another core. +

+Napia +

+The implementation here is based on the multicore model used +in Napia, the virtual machine being written for the Retro +on smaller targets. Code written to work with this will be +usable on Retro/Napia with minimal changes. +

+The main differences are that under Nga, this is an optional +extension, but in Napia, it is part of the standard system. +

+Other Notes +

+On startup, execution occurs on core 0, with only core 0 being +initialized. +

+I/O is run on the currently active core. Since I/O is blocking, +waiting for an interaction to occur will prevent other cores +from running until the operation is complete. +

+

+ diff --git a/doc/html/index.html b/doc/html/index.html index 8a4f14b..20decab 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -1 +1 @@ - Retro Forth: Manual

Retro Forth

Introduction
Obtaining RETRO
Building on Unix
Building on Windows
Building Alternative Implementations
Advanced and Custom Builds
Starting RETRO
Basic User Interactions
Literate Source With Unu
Markdown
A Quick Tutorial
Syntax
Toolchain: Additional Tools
Toolchain: retro-compiler
Manpage: retro(1)
Manpage: retro-describe(1)
Manpage: retro-document(1)
Manpage: retro-embedimage(1)
Manpage: retro-extend(1)
Manpage: retro-locate(1)
Manpage: retro-muri(1)
Manpage: retro-tags(1)
Naming Conventions
The Return Stack
Stack Diagrams
Arrays
Assembly
Buffer
Characters
Defining Words
The Dictionary
Floating Point
Working With Files
Loops
Numbers
Pointers
Quotes
Sockets
Scripting
Strings
Using Combinators
Word Classes
Checking the Version
Errors
Lexical Scope
The Stacks
The Nga Virtual Machine
Interface Layers
Basic I/O
Detailed I/O
Image
Calling Retro From C
Historical Papers
Metacompiling
Self-Hosting
Sigils
Kernel Words
Ngaro to Nga
RETRO11 Retrospective
Security
Underscores in Names
Code It Yourself Manifesto
Deprecation Policy
Copyrights
\ No newline at end of file + Retro Forth: Manual

Retro Forth

Introduction
Obtaining RETRO
Building on Unix
Building on Windows
Building Alternative Implementations
Advanced and Custom Builds
Starting RETRO
Basic User Interactions
Literate Source With Unu
Markdown
A Quick Tutorial
Syntax
Toolchain: Additional Tools
Toolchain: retro-compiler
Manpage: retro(1)
Manpage: retro-describe(1)
Manpage: retro-document(1)
Manpage: retro-embedimage(1)
Manpage: retro-extend(1)
Manpage: retro-locate(1)
Manpage: retro-muri(1)
Manpage: retro-tags(1)
Naming Conventions
The Return Stack
Stack Diagrams
Arrays
Assembly
Buffer
Characters
Defining Words
The Dictionary
Floating Point
Working With Files
Loops
Numbers
Pointers
Quotes
Sockets
Scripting
Strings
Using Combinators
Word Classes
Checking the Version
Errors
Lexical Scope
The Stacks
Multicore Support
The Nga Virtual Machine
Interface Layers
Basic I/O
Detailed I/O
Image
Calling Retro From C
Historical Papers
Metacompiling
Self-Hosting
Sigils
Kernel Words
Ngaro to Nga
RETRO11 Retrospective
Security
Underscores in Names
Code It Yourself Manifesto
Deprecation Policy
Copyrights
\ No newline at end of file diff --git a/tools/book-chapters.retro b/tools/book-chapters.retro index 4bc2b46..95bb2ce 100755 --- a/tools/book-chapters.retro +++ b/tools/book-chapters.retro @@ -47,6 +47,7 @@ This contains the list of files for the chapters in the book. { 'Errors 'techniques/errors } { 'Lexical_Scope 'techniques/lexical-scope } { 'The_Stacks 'techniques/the-stacks } + { 'Multicore_Support 'techniques/multicore } { 'The_Nga_Virtual_Machine 'internals/nga } { 'Interface_Layers 'internals/interface-layers } { 'Basic_I/O 'internals/io }