# Introduction and Problem Statement

Due to the need to reinstall the OS on my FPGA development workstation,
I have lost the Xilinx Webpack/ISE FPGA development environment.
This implies I cannot refine the Kestrel-2DX
to function as I'd originally intended:
as a terminal or diagnostic tool for developing the Kestrel-3's I/O hardware.
I could attempt to reinstall it,
but it took me *months* last time to track down a missing dependency.
I'm not sure I want to go through that hassle again.

So, I've decided to bring the Kestrel-3 up in exactly the same way
that I brought up
the Kestrel-2DX,
the Kestrel-2, and
the Kestrel-1 before it:
**manually**.

As you've known from elsewhere on this site,
the Kestrel-3 has always been specified as a two-FPGA computer system.
One FPGA houses the main processor
while the other FPGA houses the video, audio, keyboard, mouse, et. al. hardware.
The two FPGAs would share minimal yet complimentary blocks of logic to allow
them to cooperate.

The original plan was to focus on the Kestrel-3 A/V hardware *first*,
and retrofit a kind of revised, bug-fixed Kestrel-2DX to drive that hardware.
Then, the plan changed due to practical matters:
the need to build the link between the two FPGAs
required that I work on a minimal computer *first*,
then getting the A/V hardware working second.

Although even more practical matters have intervened
so as to cause even the development of the [ByteLink](wiki/ByteLink) interface to be deferred,
it turns out that this second plan **is still** the right way to go.
However, the specific order of operations that implements that plan has changed.
(Consult the history of this wiki page to see previous plans if you're interested.)

## High-Level Development Plan

1.  *DONE*.  **Order a couple of USB/serial interfaces.**  Le sigh; I'm just going to pay the FTDI tax on this one.  This will let me talk to the FPGA boards from a host PC running a dumb terminal (operator's console on serial channel 0) as well as implement secondary storage (via serial channel 1).
1.  **Replace Kestrel-2DX with minimum configuration Kestrel-3.**  On the CPU FPGA, build a stripped down, yet streamlined, Kestrel-2DX.  Replace Wishbone B3 with TileLink TL/UL interconnects.  Upgrade 2DX's KCP53000 with the 3's KCP53010 CPU.  Talk to the outside world with (DMA-backed?) SIA cores, and via a GPIA-2 core for user I/O needs.  Kiss SD support goodbye (good riddance!).  Port DX-Forth to Kestrel-3.  (Update DX-Forth to use file-based I/O?  Maybe!)  First public release of Kestrel-3 technology.  *This step ensures I'll never run into either "can't port Kestrel because we don't make your FPGA boards anymore" and "we can't install your FPGA dev environment" again.*
1.  **Update Kestrel-3 User's Guide.**  Document the processor, the SIA core(s), the GPIA-2 cores (if any), and provide an introduction to and reference for DX-Forth.
1.  **Port Tripos as VertigOS.**  Due to inexplicably litigious behavior on the part of Cloanto and Hyperion Entertainment, and the relative ease with which one could port enough libraries to make VertigOS look like a clone of AmigaOS, I've decided to no longer consider porting the BOAR Project OS.  Instead, I'm going to focus my attention on *just* the Tripos kernel and runtime environment.
1.  **Design a System for Expansion.**  This is where I will design something akin to IBM PC's ISA bus.  Will it remain ByteLink, or will I go with something capable of supporting a backplane?  It's presently too early to tell, but at least I have ByteLink to fall back on if I can't come up with a good solution by then.
1.  **Design the A/V Hardware.**  Up until now, we've been doing everything on one FPGA, the CPU FPGA.  This is where the A/V FPGA now becomes important: the CGIA, native keyboard and mouse support, and audio are implemented.  Implemented as a second icoBoard Gamma, it should plug into the CPU board via the expansion mechanism designed previously.
1.  **Update Kestrel-3 User's Guide again.**  Include descriptions of new hardware and system software features.  (Include chapters on Tripos, or refer to external documentation by reference?)

## The Plan for Project Replacement

High-level step 1 is trivial:
place a few phone calls, and you're done.

The real work begins with step 2,
which is to replace the Kestrel-2DX with the smallest configuration Kestrel-3.

The steps I've come up with are as follows.
As usual, I reserve the right to change them at any time and without notice.

1.  ***DONE!***
Implement the flash ROM Adapter (`ROMA`) core.  Rig it to a simple
TileLink transaction generator to read out words starting at some
address.  The address generator is completely ignorant of the fact
that it's talking to a flash ROM, so whatever startup sequence the
flash needs ahead of time must be taken care of exclusively by the
ROMA core.  Data which is successfully delivered by the ROMA core is
then fed directly to a set of PMOD LEDs (I received a board with 8
LEDs as part of my icoBoard Gamma order).  Since I should know what
appears in flash at what addresses, and if I clock it slow enough, I
should be able to manually confirm it's reading the contents of the
ROM correctly.
1.  Implement the Serial Interface Adapter (SIA) core.  Default to
9600 baud (or whatever is most convenient to derive from the
clock).  Alter the ROM-fetch-and-store-to-LED circuit from step A to
stuff bytes instead to the SIA transmit buffer.  On a host PC, receive
the data transmitted, and use `xxd` to dump the binary file produced.
This should match the contents of the ROM, but more importantly, it
tells me I can depend on logging output from the host CPU when it is
implemented.
1.  Port my `KCP53000` processor to use TileLink instead of Wishbone
B3.  Replace the faux DMA engine with the RISC-V processor.  Confirm
that I can print "Hello world" to the console via software in ROM.
1.  Implement the RAM adapter (`RAMA`) core.  Confirm that I can copy
ROM into RAM, then read it back out via the SIA port.  Again, use `xxd`
to confirm that RAM is holding the desired contents.  (Alternatively:
implement some kind of RAM test logic.)
1.  Port Kestrel-2DX's DX-Forth to the Kestrel-3 firmware.  Confirm it
can do basic math and otherwise talk to low-level devices.  Confirm it
can compile new code interactively.  At this point, a host PC should
be able to talk to the Kestrel-3 via a serial/USB interface cable and
running a terminal program such as minicom.
1.  Update Kestrel-3's Forth to support block and/or file I/O via a second SIA core
dedicated to that purpose.  This will (eventually) require programming an Arduino
or some such to act as a file server on behalf of the Kestrel-3.
(Think of the relationship between the Commodore 64 and a Commodore
1541 disk drive.)  At this point, the Kestrel-3 becomes, insofar as
software is concerned, capable of self-hosted software development and
refinement (at least for RAM-resident system software).  First public
release!
1.  Commence work on building the KCP53010 to replace the KCP53000.  This processor should be a drop-in replacement with *no* changes to system software required to use.  The system should run faster and/or offer more instructions (e.g., multiply and perhaps some atomics).  Second public release!