Kestrel-3

The boot menu itself can be implemented in Forth, before the user ever
sees an OK prompt.  Selecting option 1 simply exits the menu, clears
the dictionary and stacks, and invokes ~LOAD~ on a well-defined block.
When that's done, it drops to the OK prompt.  Selecting option 2 exits
the menu, clears the dictionary and stacks, but just drops to an OK
prompt.  No attempt is made to auto-load any blocks.








The user may re-enter the boot menu at any time by invoking the word
~BYE~, so as to exit from the Forth environment.

I anticipate that this is what the firmware should perform upon
cold-boot:













#+BEGIN_SRC
  TO cold-boot the Kestrel-3 DO
U   Relocate the ROM image into RAM for faster performance.
U   Initialize the Forth binary interface.
R   Cold-boot the Forth interpreter.
  END
#+END_SRC

Since the system's flash ROM is a serial device, the processor will
need to wait hundreds of clock cycles for each instruction it executes
out of ROM.  This is why we relocate the software image in ROM into
RAM before executing the rest of the bootstrap process.

Initializing the Forth binary interface involves determining
(statically or dynamically) where to place the data and return stacks,
any user and global variables, and of course the dictionary itself.

Once the VM has been established, we can then "cold boot" the Forth
environment.  It is here that the boot menu is built and presented to
the user.

#+BEGIN_SRC
  TO cold-boot the Forth interpreter DO
R   Direct console I/O to the operator's console.

R   Configure the Forth bootmenu items.
R   Show startup banner.
R   Discover available bootable volumes.
O   Start at first page of menu items.
    DO FOREVER
R     Present menu to the operator.
O     Wait for a key.
U     IF selection made identifies a boot option THEN
R       Attempt to boot from the selected source.
O       Notify the user of the failed boot attempt.
O     ELSIF operator wants to page the list down THEN
U       Advance to next page of items.
O     ELSIF operator wants to page the list up THEN
U       Retreat to previous page of items.
      ELSE
O       Notify the user of the erroneous selection.
      END
    END
  END
#+END_SRC

Device discovery necessarily implies device configuration as well.  In
the case of the operator's console, this should be configured
................................................................................

Boot menu items are described using a collection of menu item
descriptors.  Each descriptor binds a key that a user can press on the
keyboard to a particular boot action.  See the data structures chapter
for a complete description.

#+BEGIN_SRC
  TO Configure the Forth bootmenu items DO
U   Create a menu item descriptor that binds key 0 to boot into Forth environment w/out Auto-Load.
U   Create a menu item descriptor that binds key 1 to boot into Forth environment with Auto-Load.
  END
#+END_SRC












Assuming that the user's console is 80x25 characters in size, we can
reasonably display up to 16 items on a single screen.  If there are
more than 16 items to display, we'll need a mechanism for paging the
display.  Up to 36 items should be easily supported, being keyed to
'0'..'9', then 'A'..'Z'.


#+BEGIN_SRC
  TO Present menu to the operator DO


U   Clear the screen.
R   Show startup banner.
U   Skip to the item which is to appear first.
O   Start menu item counter at 0.
O   DO WHILE fewer than 16 items have been shown AND more items are left to print
O     Print the menu key and item description.
O     Count the menu item.
    END
O   Print page up/down menu items.
O   Prompt user for which action to take.
  END
#+END_SRC






















































When booting into the Forth environment, the following sequence of
code can be performed.  Note that the decision of whether or not to
auto-load was made when the user selected the appropriate menu
selection in the boot screen.

#+BEGIN_SRC
................................................................................
O        Report that no auto-start block was found.
      END
    ELSE
O     Report that auto-start was skipped on user request.
    END
O   Quit into Forth interpreter.
  END
#+END_SRC

We attempt to boot into a particular selection by invoking its custom
handler.  If the handler ever returns, then we can safely assume the
boot attempt failed.  It's expected that software which is
bootstrapped into will generally not return.

#+BEGIN_SRC
  TO attempt to boot from the selected source DO
O   Delegate control to handler specified by the selected menu item, passing the provided parameter as an argument.
  END
#+END_SRC

* Forth Interpreter
** Interpreter
I probably won't delve as deeply into the innards of the Forth
environment as I will other components of the firmware, if only
because of how fluid Forth's implementation details can be.  However,
................................................................................
* Data Structures and Variables
** Global Data
| Description                                   | Type                                                 |
|-----------------------------------------------+------------------------------------------------------|
| Flag that determines if OK prompt is visible. | BOOLEAN                                              |
| Mount list                                    | Pointer to volume descriptor                         |
| Device vector                                 | Maps device ID to device driver entry points, etc.   |




| Boot menu item vector                         | Array of 36 pointers to a boot menu item descriptor. |


** Forth USER Variables
These variables refer back to values deemed to be necessary in
previous sections of this document.  This list is not meant to be
exhaustive.

| Description            | Type                                              |
................................................................................
Some of the material presented here will be duplicates from earlier
sections.  Where the two definitions differ, the version presented
with the specific section is to be taken to be normative.

*** Boot Menu Item Descriptor
| Field   | Purpose                                                        |
|---------+----------------------------------------------------------------|
| Key     | The key the user must press to activate this menu selection.   |
| Title   | The title of the menu selection.                               |
| Handler | The Forth word responsible for performing the item's action.   |
| Param   | A parameter passed to the handler (allows classes of handlers) |

*** Exception Handler Frame
| Field                                       | Purpose                                                                          |
|---------------------------------------------+----------------------------------------------------------------------------------|
| next                                        | Links to the next oldest exception handler; 0 if none.                           |

The boot menu itself can be implemented in Forth, before the user ever
sees an OK prompt.  Selecting option 1 simply exits the menu, clears
the dictionary and stacks, and invokes ~LOAD~ on a well-defined block.
When that's done, it drops to the OK prompt.  Selecting option 2 exits
the menu, clears the dictionary and stacks, but just drops to an OK
prompt.  No attempt is made to auto-load any blocks.

Because only a single key press is sufficient to make a boot menu
selection, we restrict the set of keys capable of making a valid
selection.  These keys include ~0~ to ~9~, and ~A~ to ~Z~.  Lowercase
letters are converted to uppercase for operator convenience.  Thus,
our boot menu is restricted to 36 items maximum, two of which are
reserved for booting into the ROM-resident Forth system.

The user may re-enter the boot menu at any time by invoking the word
~BYE~, so as to exit from the Forth environment.

Upon power-on, the first thing the computer must do is establish its
runtime environment.  Since the system's flash ROM is a serial device,
the processor will need to wait hundreds of clock cycles for each
instruction it executes out of ROM.  To eliminate this waste, we first
copy the contents of ROM into RAM before executing Forth's main entry
point.

Initializing the Forth binary interface involves determining
(statically or dynamically) where to place the data and return stacks,
any user and global variables, and of course the dictionary itself.
Since this is only a small handful of instructions, we can perform
these steps in ROM without concern for efficiency.  This also allows
us to only copy the Forth software into RAM, and not the entire
contents of ROM, which will conserve RAM resources.

#+BEGIN_SRC
  TO cold-boot the Kestrel-3 DO
U   Relocate the ROM image into RAM for faster performance.
U   Initialize the Forth binary interface.
R   Cold-boot the Forth interpreter.
  END
#+END_SRC










Once the VM has been established, we can then "cold boot" the Forth
environment.  It is here that the boot menu is built and presented to
the user.

#+BEGIN_SRC
  TO cold-boot the Forth interpreter DO
R   Direct console I/O to the operator's console.
O   Zero the boot menu item vector.
R   Configure the Forth boot menu items.
R   Show startup banner.
R   Discover available bootable volumes.

    DO FOREVER
R     Present menu to the operator.
O     Wait for a key.
O     Convert letter to uppercase.
O     IF key in set {'0'..'9', 'A'..'Z'} THEN
O       Convert key to a candidate menu item number (0 <= i < 36).
O       IF menu item (key) has non-nil handler THEN
O         Delegate control to menu item (key)'s handler with corresponding parameter.
O         Notify the user of the failed boot attempt.
        ELSE
O         Notify the user of the erroneous selection.
        END
      END
    END
  END
#+END_SRC

Device discovery necessarily implies device configuration as well.  In
the case of the operator's console, this should be configured
................................................................................

Boot menu items are described using a collection of menu item
descriptors.  Each descriptor binds a key that a user can press on the
keyboard to a particular boot action.  See the data structures chapter
for a complete description.

#+BEGIN_SRC
  TO Configure the Forth boot menu items DO
R   Bind menu item (0) to (boot into Forth environment) with (no auto-load) named (Kestrel Forth (Debug)).
R   Bind menu item (1) to (boot into Forth environment) with (auto-load) named (Kestrel Forth).
  END
#+END_SRC

Menu items can be created by filling in appropriate fields.

#+BEGIN_SRC
  TO Bind menu item (i) to (f) with (param) named (name) DO
O   Set menu item (i) field handler to (f).
O   Set menu item (i) field parameter to (param).
O   Set menu item (i) name to (name).
  END
#+END_SRC

Recall that our boot menu is restricted to 36 items.  Assuming that
the user's console is 80x25 characters in size, we can reasonably




display up to two columns of selections across 18 rows.

#+BEGIN_SRC
  TO Present menu to the operator DO
    PRECONDITION: len(formatting buffer) >= 80
    PRECONDITION: menu item vector initialized.
R   Clear the screen.
R   Show startup banner.


    FOR i = 0 TO 17 DO
R     Format left and right columns for row (i).
O     Print formatting buffer.
    END

O   Prompt user for which action to take.
  END
#+END_SRC

As a matter of simplification, we constrain boot menu items to 35 or
fewer characters.  In order to fit two columns on the screen, no
single column can exceed 38 characters (giving 2 characters of padding
in between them).  The key is expected to take three characters, since
it'll be formatted with something like ~X._~ (where the underscore is
a stand-in for a blank).  That leaves 35 characters for the item
description.  If the boot image names are constrained to 35 characters
or less (or, equally viable, if we truncate after 35 characters in
length), then can render the menu without excessive complexity in
display formatting logic.

To minimize complexity, we pre-render each row in the menu into a
formatting buffer wide enough to handle a full screen width.

#+BEGIN_SRC
  TO format left and right columns for row (i) DO
  PRECONDITION: 0 <= i < len(vector of menu items)
  PRECONDITION: len(formatting buffer) >= 80
O   Clear formatting buffer.
O   IF menu item i exists THEN
O     Set format margin to start of left column.
R     Format key and description for menu item (i).
    END
O   IF menu item i+18 exists THEN
O     Set format margin to start of right column.
R     Format key and description for menu item (i+18).
    END
  END
#+END_SRC

Each column is formatted uniformly.

#+BEGIN_SRC
  TO format key and description for menu item (i) DO
  PRECONDITION: 0 <= formatting offset < len(formatting buffer)-len(menu item description)-3
R   Write out key selector for item (i).
O   Write out menu item (i) description.
  POSTCONDITION: formatting offset <= len(formatting buffer)
  END
#+END_SRC

The key selector for a boot menu item should come from the set of
valid characters, discussed above.

#+BEGIN_SRC
  TO write out key selector for item (i) DO
  PRECONDITION: 0 <= formatting offset <= len(formatting buffer)-3
O   Emit the number (i) in base-36.
O   Emit ". "
  POSTCONDITION: 3 <= formatting offset <= len(formatting buffer)
  END
#+END_SRC

When booting into the Forth environment, the following sequence of
code can be performed.  Note that the decision of whether or not to
auto-load was made when the user selected the appropriate menu
selection in the boot screen.

#+BEGIN_SRC
................................................................................
O        Report that no auto-start block was found.
      END
    ELSE
O     Report that auto-start was skipped on user request.
    END
O   Quit into Forth interpreter.
  END











#+END_SRC

* Forth Interpreter
** Interpreter
I probably won't delve as deeply into the innards of the Forth
environment as I will other components of the firmware, if only
because of how fluid Forth's implementation details can be.  However,
................................................................................
* Data Structures and Variables
** Global Data
| Description                                   | Type                                                 |
|-----------------------------------------------+------------------------------------------------------|
| Flag that determines if OK prompt is visible. | BOOLEAN                                              |
| Mount list                                    | Pointer to volume descriptor                         |
| Device vector                                 | Maps device ID to device driver entry points, etc.   |

** Boot Menu Variables
| Description           | Type                                                 |
|-----------------------+------------------------------------------------------|
| Boot menu item vector | Array of 36 pointers to a boot menu item descriptor. |
| Formatting Buffer     | Array of >= 80 bytes                                 |

** Forth USER Variables
These variables refer back to values deemed to be necessary in
previous sections of this document.  This list is not meant to be
exhaustive.

| Description            | Type                                              |
................................................................................
Some of the material presented here will be duplicates from earlier
sections.  Where the two definitions differ, the version presented
with the specific section is to be taken to be normative.

*** Boot Menu Item Descriptor
| Field   | Purpose                                                        |
|---------+----------------------------------------------------------------|

| Title   | The title of the menu selection (typ 32 chars; 35 chars max).  |
| Handler | The Forth word responsible for performing the item's action.   |
| Param   | A parameter passed to the handler (allows classes of handlers) |

*** Exception Handler Frame
| Field                                       | Purpose                                                                          |
|---------------------------------------------+----------------------------------------------------------------------------------|
| next                                        | Links to the next oldest exception handler; 0 if none.                           |