Kestrel-3

Check-in [a903a4c39f]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:More stepwise refinements to flesh out more boot loader behavioral details, menu item structure, etc.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:a903a4c39fc03215892d7ec9954c8c02e5a4bcbb3000f2b8687a8ba0cc90f805
User & Date: kc5tja 2019-09-09 04:35:52
Context
2019-09-09
05:06
More refinements; done for this evening though. check-in: 985c171204 user: kc5tja tags: trunk
04:35
More stepwise refinements to flesh out more boot loader behavioral details, menu item structure, etc. check-in: a903a4c39f user: kc5tja tags: trunk
00:34
Missing word radically alters intended meaning of a sentence. check-in: 2c2434a794 user: kc5tja tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to REPORT.org.

119
120
121
122
123
124
125
126
127
128
129

130
131
132
133
134
135




136
137
138
139
140
141
142
...
143
144
145
146
147
148
149
150

151
152



















































153
154
155
156
157
158
159
...
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
...
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
...
688
689
690
691
692
693
694
695
696
697
698
699

700
701
702
703
704
705
706
...
709
710
711
712
713
714
715








716
717
718
719
720
721
722
...
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778







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.













|



>






>
>
>
>







 







<
>
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|







 







|







 







|
|
|
|
|
>







 







>
>
>
>
>
>
>
>







 







<
<
<
<
<
<
<
<
<


<





<







>
>
>
>
>
>
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
...
148
149
150
151
152
153
154

155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
...
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
...
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
...
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
...
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
...
812
813
814
815
816
817
818









819
820

821
822
823
824
825

826
827
828
829
830
831
832
833
834
835
836
837
838

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)?