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.

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
  TO boot into Forth environment DO
O   IF user wants to perform auto-boot sequence DO
U     Find valid Forth auto-start block.
O     IF found THEN
O       Load Forth auto-start block.
      ELSE
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                                              |
|------------------------+---------------------------------------------------|
| Exception Frame List   | Pointer to a record or NIL                        |
| ~THROW~ handler vector | Execution token of run-time semantics for ~THROW~ |

** Records and Control Blocks
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.                           |