Kestrel-3

In addition, each unit with a medium inserted can potentially have
more than one partition as well.  We know that partitions can come and
go at any time as well, as anyone who has used a partitioning tool
like ~fdisk~ can attest.

#+BEGIN_SRC
  TO Discover attached devices and volumes DO


R   Ask emulator for its complete unit list.
U   IF emulator responded THEN

O     DO WHILE not at end of unit list
U       Create a unit descriptor for the unit.
O       IF unit is mounted THEN
U         Create a mount-list descriptor.
        END
      END
U     Create device descriptor of type "Storage Emulator" as device 0.
    END
  END
#+END_SRC

Remark: I chose to build the unit list first, since that allows me to
create the device descriptor without having to go back and patch it up
later.  However, this might not be the best approach.
................................................................................

When booting, the Kestrel must learn how many storage units are
available, which ones have media installed on them, and their physical
characteristics.  This will provide the required information needed to
construct the boot menu.

#+BEGIN_SRC
  TO Ask emulator for its complete unit list DO
R   Send command (SSP_LIST_UNITS).
O   IF timed out or command rejected THEN RETURN END
U   Receive unit descriptor quantity.
O   IF timed out THEN RETURN END
O   FOR each unit pending DO
U     Process one unit descriptor.
    END
................................................................................
can't get a command through after so many tries, then we give up with
a timeout condition.

#+BEGIN_SRC
  TO Send command (x) DO
O   Begin with the first transmission attempt.
O   WHILE we have transmission attempts remaining DO
U     Start interval timer for 1 second.
U     Wait for sufficient transmission credits or for timeout.
O     IF NOT timeout THEN
U       Send the command bytes for (x).
U       Restart interval timer for 1 second.
U       Wait for command acceptance response or for timeout.
O       IF NOT timeout THEN
O         RETURN command acceptance result.
        END
      END
O     Count transmission attempt.
    END
O   RETURN timeout.
  END
#+END_SRC




























* Data Structures and Variables
** Global Data
| Description                                   | Type                                                 |
|-----------------------------------------------+------------------------------------------------------|
| Flag that determines if OK prompt is visible. | BOOLEAN                                              |
| Mount list                                    | Pointer to volume descriptor                         |
................................................................................
* 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.  These issues are /in addition/ to all steps which
need further refinement.

- Refine format of boot block format

In addition, each unit with a medium inserted can potentially have
more than one partition as well.  We know that partitions can come and
go at any time as well, as anyone who has used a partitioning tool
like ~fdisk~ can attest.

#+BEGIN_SRC
  TO Discover attached devices and volumes DO
U   Reset the secondary storage interface.
O   IF secondary storage device not connected THEN RETURN END
R   Ask storage device for its complete unit list.

U   IF storage device responded THEN
O     DO WHILE not at end of unit list
U       Create a unit descriptor for the unit.
O       IF unit is mounted THEN
U         Create a mount-list descriptor.
        END
      END
U     Create device descriptor as device 0.
    END
  END
#+END_SRC

Remark: I chose to build the unit list first, since that allows me to
create the device descriptor without having to go back and patch it up
later.  However, this might not be the best approach.
................................................................................

When booting, the Kestrel must learn how many storage units are
available, which ones have media installed on them, and their physical
characteristics.  This will provide the required information needed to
construct the boot menu.

#+BEGIN_SRC
  TO Ask storage device for its complete unit list DO
R   Send command (SSP_LIST_UNITS).
O   IF timed out or command rejected THEN RETURN END
U   Receive unit descriptor quantity.
O   IF timed out THEN RETURN END
O   FOR each unit pending DO
U     Process one unit descriptor.
    END
................................................................................
can't get a command through after so many tries, then we give up with
a timeout condition.

#+BEGIN_SRC
  TO Send command (x) DO
O   Begin with the first transmission attempt.
O   WHILE we have transmission attempts remaining DO
U     Start interval timer.
U     Wait for sufficient transmission credits or for timeout.
O     IF NOT timeout THEN
R       Send the command bytes for (x).
U       Restart interval timer.
U       Wait for command acceptance response or for timeout.
O       IF NOT timeout THEN
O         RETURN command acceptance result.
        END
      END
O     Count transmission attempt.
    END
O   RETURN timeout.
  END
#+END_SRC

Except for the link metadata, every byte we send will reduce our
available credit with the attached peripheral.  Note that we don't
need to worry about flow control during this operation, since we've
already established that the receiver has given us enough credit for
this operation above.

#+BEGIN_SRC
  TO send the command bytes for (x) DO
  PRECONDITION: credit >= length(x)
O   Decrement the credit counter by the length of (x).
R   Output the COMMAND header for (x)
    FOR each byte in (x) DO
O     Send the byte.
    END
  POSTCONDITION: credit-length(x) >= 0
  END
#+END_SRC

The command header just consists of two bytes.

#+BEGIN_SRC
  TO output the command header for (x) DO
O   Output the command frame header byte.
O   Output the length of (x) in bytes.
  END
#+END_SRC

* Data Structures and Variables
** Global Data
| Description                                   | Type                                                 |
|-----------------------------------------------+------------------------------------------------------|
| Flag that determines if OK prompt is visible. | BOOLEAN                                              |
| Mount list                                    | Pointer to volume descriptor                         |
................................................................................
* 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.  These issues are /in addition/ to all steps which
need further refinement.

- Refine format of boot block format
- Interval timers (needed for SSP driver to detect link timeouts)
- How does the SSP driver receive the initial credit?  How does the SSP device receive its initial credit?