Kestrel-3

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
  Discover the operator's console.
  Configure the Forth bootmenu items.
  Show startup banner.
  Discover available bootable volumes.

  DO FOREVER
    Present menu to the operator.
    Wait for a key.
    IF selection made identifies a boot option THEN
      Attempt to boot from the selected source.
      Notify the user of the failed boot attempt.




    ELSE
      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
automatically when the computer comes out of reset.  (Still, when
media hardware is later contributed to the computer's configuration,
somehow choosing between the debug console and the VGA/keyboard
interface will need to happen.)

Discovery and configuration of mass storage devices will need to

happen as well; however, I'll defer the details of this step until
later in this document.




















































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
................................................................................
idea of how I'd like the system software to be structured.

The interpreter is entered via the word called ~QUIT~.

#+BEGIN_SRC
TO Quit into the Forth interpreter DO
  Reset the return stack pointer.
  Set input source to the operator's console.
  DO FOREVER
    Read one line of text.
    Interpret the line of text received.
    IF OK prompt is enabled THEN Print "OK" END
  END
END
#+END_SRC
................................................................................
Note that this "outer interpreter" (as it's known formally in the
Forth community) resets the return stack pointer, but not the data
stack pointer.  When something produces an error, however, the data
stack does get reset.

#+BEGIN_SRC
TO Handle uncaught exception DO
  Direct output to operator's console.
  Print error code of current exception.
  IF error code is a valid system exception code THEN
    Print descriptive error message.
  END
  Reset data stack.
  Quit into the Forth interpreter.
END
................................................................................
/volume/ in the Forth environment.

This behavior can be changed in the future with no known impact to
software not explicitly designed to manage storage devices.

* 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. |


** 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                                              |
................................................................................
| ~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.









*** Exception Handler Frame
| Field                                       | Purpose                                                                          |
|---------------------------------------------+----------------------------------------------------------------------------------|
| next                                        | Links to the next oldest exception handler; 0 if none.                           |
| throw vector                                | Preserves the throw vector that was in effect at the time the frame was created. |
| input source parameters                     | Preserves the caller's input source.                                             |
| data stack pointer                          | Preserves the caller's data stack.                                               |
................................................................................
| Name      | A human-readable name for the bootable software.  This text would appear in the boot menu, for instance. |

* Unresolved Issues
These are design issues that either need resolution prior to further
refinement, or I know how to refine them but just haven't gotten
around to it yet.

- How to relocate ROM image into RAM?
  - Load from hunk-format image (does not require statically linked or PIC image)
  - Copy directly from ROM address space into RAM (assumes statically linked and/or PIC image)?
- "Initialize the Forth Binary Interface"
  - Devise register conventions, memory layouts, etc.
  - Sounds like an assembly language/intrinsic level function.
- "Discover the operator's console"
- "Configure the Forth bootmenu items."
- "Present menu to the operator."
- "Attempt to boot from the selected source."
- "Find valid Forth auto-start block."
- "Set input source to the operator's console."
- "Read one line of text."
- "Interpret the line of text received."
  - This one is going to be a heavy-weight item, since this gets into the internals of the dictionary, etc.
  - The above will necessarily be very tightly bound to the implementation of the compiler.
  - So, in a sense, we'll need to decide how the compiler will work before deciding how the outer interpreter is going to work.
- "Direct output to operator's console."
- "Create an exception handling frame with the current return stack pointer and system variables."
- "Restore system variables."
- Refine format of boot block format
- Create device descriptor of type "Storage Emulator" as device 0.
- Ask emulator for its complete unit list.
- Create a unit descriptor for the unit.
- Create a mount-list record for the unit.

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
  Direct console I/O to the operator's console.
  Configure the Forth bootmenu items.
  Show startup banner.
  Discover available bootable volumes.
  Start at first page of menu items.
  DO FOREVER
    Present menu to the operator.
    Wait for a key.
    IF selection made identifies a boot option THEN
      Attempt to boot from the selected source.
      Notify the user of the failed boot attempt.
    ELSIF operator wants to page the list down THEN
      Advance to next page of items.
    ELSIF operator wants to page the list up THEN
      Retreat to previous page of items.
    ELSE
      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
automatically when the computer comes out of reset.  (Still, when
media hardware is later contributed to the computer's configuration,
somehow choosing between the debug console and the VGA/keyboard
interface will need to happen.)


#+BEGIN_SRC
TO Direct console I/O to the operator's console DO
  Set default vectors for EMIT, EMIT?, KEY, KEY?, AT-XY, AT-XY?, CR, PAGE, and TYPE.
END
#+END_SRC

Displaying the Forth logo on the screen happens before enumerating
storage devices, since the latter can potentially take a long time to
complete.  The banner at least lets the operator know that Forth is
running.

#+BEGIN_SRC
TO show startup banner DO
  Type the following message:

    Kestrel-3 ROM Forth System 2 Release 1
    Copyright (c) 2019 Samuel A. Falvo II
END
#+END_SRC

See the secondary storage section in the Forth Interpreter chapter for
mass storage discovery information.

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
  Create a menu item descriptor that binds key 0 to Forth w/out Auto-Load.
  Create a menu item descriptor that binds key 1 to Forth 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
  Clear the screen.
  Show startup banner.
  Skip to the item which is to appear first.
  Start menu item counter at 0.
  DO WHILE fewer than 16 items have been shown AND more items are left to print
    Print the menu key and item description.
    Count the menu item.
  END
  Print page up/down menu items.
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
................................................................................
idea of how I'd like the system software to be structured.

The interpreter is entered via the word called ~QUIT~.

#+BEGIN_SRC
TO Quit into the Forth interpreter DO
  Reset the return stack pointer.
  Direct console I/O to the operator's console.
  DO FOREVER
    Read one line of text.
    Interpret the line of text received.
    IF OK prompt is enabled THEN Print "OK" END
  END
END
#+END_SRC
................................................................................
Note that this "outer interpreter" (as it's known formally in the
Forth community) resets the return stack pointer, but not the data
stack pointer.  When something produces an error, however, the data
stack does get reset.

#+BEGIN_SRC
TO Handle uncaught exception DO
  Direct console I/O to operator's console.
  Print error code of current exception.
  IF error code is a valid system exception code THEN
    Print descriptive error message.
  END
  Reset data stack.
  Quit into the Forth interpreter.
END
................................................................................
/volume/ in the Forth environment.

This behavior can be changed in the future with no known impact to
software not explicitly designed to manage storage devices.

* 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                                              |
................................................................................
| ~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                                                        |
|---------+----------------------------------------------------------------|
| 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.                           |
| throw vector                                | Preserves the throw vector that was in effect at the time the frame was created. |
| input source parameters                     | Preserves the caller's input source.                                             |
| data stack pointer                          | Preserves the caller's data stack.                                               |
................................................................................
| Name      | A human-readable name for the bootable software.  This text would appear in the boot menu, for instance. |

* Unresolved Issues
These are design issues that either need resolution prior to further
refinement, or I know how to refine them but just haven't gotten
around to it yet.










- "Attempt to boot from the selected source."
- "Find valid Forth auto-start block."

- "Read one line of text."
- "Interpret the line of text received."
  - This one is going to be a heavy-weight item, since this gets into the internals of the dictionary, etc.
  - The above will necessarily be very tightly bound to the implementation of the compiler.
  - So, in a sense, we'll need to decide how the compiler will work before deciding how the outer interpreter is going to work.

- "Create an exception handling frame with the current return stack pointer and system variables."
- "Restore system variables."
- Refine format of boot block format
- Create device descriptor of type "Storage Emulator" as device 0.
- Ask emulator for its complete unit list.
- Create a unit descriptor for the unit.
- Create a mount-list record for the unit.
- "Initialize the Forth Binary Interface"
  - Devise register conventions, memory layouts, etc.
  - Sounds like an assembly language/intrinsic level function.
- How to relocate ROM image into RAM?
  - Load from hunk-format image (does not require statically linked or PIC image)
  - Copy directly from ROM address space into RAM (assumes statically linked and/or PIC image)?