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 }