From 932dbc7ede0a91699e93f3897df93dad51af6d17 Mon Sep 17 00:00:00 2001 From: crc Date: Tue, 2 Jul 2024 19:14:18 +0200 Subject: [PATCH] add documents on the hardware project & graphica extension --- unsorted/graphica.txt | 220 ++++++++++++++++++++++++++++++++++++++++++ unsorted/hardware.txt | 172 +++++++++++++++++++++++++++++++++ 2 files changed, 392 insertions(+) create mode 100644 unsorted/graphica.txt create mode 100644 unsorted/hardware.txt diff --git a/unsorted/graphica.txt b/unsorted/graphica.txt new file mode 100644 index 0000000..d56e6ad --- /dev/null +++ b/unsorted/graphica.txt @@ -0,0 +1,220 @@ +Notes on Graphica (June 30 2024) + +Graphica is the name of the graphics extension for ilo. In the +Konilo system, this is in the `g:` namespace, and can be loaded +with either: + + * g + +or: + + '(g) needs + + +Status: + +- Level 0: is functional on ilo+x11 in an internal, unreleased + build. This is projected to be published in early July. +- Level 1: we've implemented the functions (for 1bpp) but have + not tied them all into the ilo+x11 vm yet. Work on the 2, 4, + and 8bpp modes has been done. We expect to have this by the + end of July. +- Level 2: parts of this have been implemented in test code. It + is expected to follow shortly after level 1 is complete (and + may be merged into level 1 prior to that?) +- Level 3: no timeline for starting this yet, though some + preliminary experiments towards it have been written. + + +Architectural Notes + +- graphics memory is separate from the addressable ilo memory. +- the functionality is divided into a few general levels, with + increasing host requirements & complexity +- drawing operations take in points, which pack the x,y + coordinates into a single value +- Level 0 is slow due to routing all drawing through the pixel + draw word. Level 1 will have VM support for more optimal + drawing and will be significantly faster. +- display resolutions being targetted initially are: + + - 320x240 + - 640x384 (* this is the res. I am mostly using internally) + - 640x480 + - 800x600 + - 360x360 + - 720x720 + + +Level 0 + +- 1 bit per pixel (black/white) +- Konilo vocabulary: + + g:query/level (-n) + g:query/colors (-n) + g:query/font (-hw) + g:query/screen (-hw) + g:set-color (n-) + g:point (xy-p) + g:unpoint (p-xy) + g:pixel (p-) + g:get-pixel (p-n) + g:clear (-) + g:hline (pw-) + g:vline (ph-) + g:line (pp-) + g:rect (pp-) + g:circle (pr-) + g:triangle (ppp-) + +Level 1 + +- 2, 4, and 8 bit per pixel (4, 16, and 256 color) +- user defined color palette (using RRGGBB values) +- Konilo words: + + g:set-palette (a-) + g:get-palette (a-) + +- VM support for: + + g:clear (-) + g:hline (pw-) + g:vline (ph-) + g:line (pp-) + g:rect (pp-) + g:circle (pr-) + g:triangle (ppp-) + +- Notes: + - Palettes + - Konilo array, with 1 entry per color + - default palette will be setup to emulate CGA (2bpp) or + VGA (4 or 8bpp; colors outside the first 16 will be set + to 0 by default) + - Arland expects to provide several loadable palettes + +Level 2 + +- Konilo words: + + g:set-foreground (n-) (alias to g:set-color) + g:set-background (n-) (for fill operations) + g:fill (p) + g:rect/filled (pp-) + g:circle/filled (pr-) + g:triangle/filled (ppp-) + +Level 3: + +- Konilo words: + + g:polygon (ap-) + g:polygon/filled (ap-) + g:scene (ap-) + +- Notes: + + - scenes are stored as an array of points and drawing + commands, with the drawing being done relative to a + provided starting point. the exact format is still being + designed. + - polygons are arrays of points, with lines being drawn + between each point + - the polygon portion of this might get folded into level 2 + +Notes: + +- the loading process will probably use `g:query/level` to + select between level 0 & level 1 implementations at load time. + + +Future: + +- To be determined. +- We are looking at 3D, non-palette based colors, and sprites +- 3D references: + - https://www.cs.drexel.edu/~deb39/ + Classes/Papers/comp175-06-pineda.pdf + - https://www.drdobbs.com/architecture-and-design/ + optimizing-pixomatic-for-x86-processors/184405765 + + +Implementation Details: + +The Graphica extension is assigned to device id #12. Pass the +required parameters, operation id, and device number to the +`io` instruction. + ++------+-------+-----------+-----------------------------------+ +| ID # | Level | Stack Use | Action | ++======+=======+===========+===================================+ +| 0 | 0 | -n | return graphica level | +| 1 | 0 | -n | return num of supported colors | +| 2 | 0 | -hw | return font height, width | +| 3 | 0 | -hw | return display height, width | +| 4 | 0 | n- | set the pixel color for drawing | +| 5 | 0 | p- | draw a pixel at p | +| 6 | 0 | p-n | return the color of pixel at p | +| 7 | 1 | - | clear the display | +| 8 | 1 | pw- | draw a horizontal line w wide | +| 9 | 1 | ph- | draw a vertical line h high | +| 10 | 1 | pp- | draw a line between two points | +| 11 | 1 | pp- | draw a rectangle | +| 12 | 1 | pr- | draw a radius r circle at center p| +| 13 | 1 | ppp- | draw a triangle | +| 14 | 1 | a- | set palette to colors in array a | +| 15 | 1 | a- | store current palette in array a | +| 16 | 2 | n- | set foreground color | +| 17 | 2 | n- | set background color | +| 18 | 2 | p- | fill area around p w/background, | +| | | | stopping when foreground is found | +| 19 | 2 | pp- | draw a filled rectangle | +| 20 | 2 | pr- | draw a filled circle | +| 21 | 2 | ppp- | draw a filled triangle | +| 22 | 3 | a- | draw a polygon. a is an array of | +| | | | points | +| 23 | 3 | a- | draw a filled polygon. a is an | +| | | | array of points | +| 24 | 3 | ap- | draw a scene using point p as the | +| | | | origin (top left) | ++------+-------+-----------+-----------------------------------+ + +Points: + + The x, y coordinates are packed into a single cell to + keep overall stack structure cleaner. These can be unpacked + as needed by the drawing words (level 0) or graphica device + (levels 1+) + + :g:point (xy-p) [ #16 shift-left ] dip or ; + :g:unpoint (p-xy) [ #16 shift-right ] [ #65535 and ] bi ; + + Consider: adding a sigil for defining points as something like + <100,200> + may be useful? will be discussing this w/Arland soon + + Note: we've explored leaving just the coordinates on the stack + in the prototypes, but ultimately decided that using a + point structure was better for our needs. + + Note: it might be worth looking at changing the points to + also pack in a z coordinate for future 3D support? (this + would be ignored/unused for 2D operations) + +Other: + +- a simple turtle style drawing vocabulary has been written + using this, as has a vocabulary for formula generated art +- in the prior experiments we have also implemented a few + visual programs (paint, conway's life, a mandebrot viewer, + and dice simulator) which we plan to update to work with + the final implementation. This will likely be in the fall of + 2024 + + +Related, but external parts to be covered by other extensions: + + - realtime keyboard state + - mouse / pointer state diff --git a/unsorted/hardware.txt b/unsorted/hardware.txt new file mode 100644 index 0000000..1565075 --- /dev/null +++ b/unsorted/hardware.txt @@ -0,0 +1,172 @@ +Konilo Hardware Project + +Arland & I would like to eventually have a computer running our +Forth system with as few intermediate layers as possible. + +This will be a lengthy project, in part due to a lack of real +experience with hardware designs. We are hoping in the short +term to make use of existing designs. Longer term, Arland wants +to learn enough to create a dedicated CPU for the ilo & arks +instruction sets, and have a fully custom system. + +We are running Konilo initially, and later plan to support +Arland's ARKS system as well. + +Basic Requirements + +The ilo design calls for: + +* 64kw of RAM (262,144 bytes) +* 32 words of data stack (128 bytes) +* 256 words of address stack (1,024 bytes) +* IP, SP, RP registers (12 bytes) +* Serial or keyboard input +* Serial or text display for output + +Optionally: + +* a bitmap display (via the graphica extension) +* a pointing device (via the pointer extension) + +Additional memory will be needed for a display (if not using +serial i/o), and possibly emulated devices. I've found that it +runs fine under host operating systems with around 384k of +actual RAM. + +ARKS basically doubles the memory usage. + +Target Hardware + +We've evaluated a number of boards. + + RP2040 (Raspberry Pi Pico) + + We like this, but it's a lttle too light on RAM for our + needs. We are looking at using it, with a reduced memory + version of ilo, as a controller for a keyboard & mouse. + + Lilygo TTGO VGA Controller + + This is a nice little ESP32 board with PS2 keyboard & mouse, + VGA output, an SD card slot, audio, and onboard wifi. It has + 520 kB of RAM, which is enough for ilo, but light for ARKS. + + We are currently evaluating using this for I/O purposes. + + Teensy4.1 + + This is an ARM board with 1MB RAM, 55 I/O pins, an SD card, + and support for serial, ethernet, and USB host. Additional + SRAM can be soldered to add more RAM. + + We have a working ilo system running on this. We still need + to implement non-serial keyboard & display, but are working + on this. (We'll be using a 320x240 bitmap display for the + non-serial build) + + This is currently my primary target. As noted, we are looking + at using other systems for I/O purposes, but have not yet + (June 2024) made any final decisions on this aspect. + + Rapsberry Pi + + We have a RPi 0 and an RPi 3. Running a small Linux install + and using a framebuffer for the display, Konilo is working on + this. + + It's not my preferred option. While easy to setup, I dislike + needing a full OS under my code, and have not been able to + pursue a native system on this yet. + + Others + + There are a variety of other possible boards we could use. The + Milk-V DUO S is a RISC-V system which might be usable. I'm + interested in this, but have not yet obtained one. The Ox64 + boards from Pine64 also look interesting. + + GeDaMo has suggested looking at PIC32, which does have some + through hole variations. This looks to be a MIPS architecture + and may be useful for a display/io controller? The largest of + the DIP packages seems to have 256KB RAM, which I think is + enough to the 720x720 resolution Arland would like to use for + his clamshell model. + +Form Factor + +We are currently working towards three models. + +The first is a small system, with a port for serial I/O, slots +for memory cards for the rom & blocks, a power switch, and USB-C +input for power. We also plan to expose at least some I/O pins. + +The second is a slab, similar to the Cambridge Z88, TRS-80 Model +100, or Amstrad NC 100. This is expected to be around the size +of a sheet of A4 paper, and probably around 1" - 1.25" thick. +It'll have an integral keyboard, a visual display, and the same +card slots for storage. It may also have an audio jack or a +small speaker, and will have an internal battery. We are aiming +to have this provide at least 24 hours of usage on a charge. + +The third model is a more traditional clamshell. It'll be based +on the slab design, but we are hoping to use a higher resolution +display in this model. Arland intends for this model to fully +support his ARKS system. + +Software + +The computer will run Konilo. The basic environment is complete, +and has been in daily use for over a year. I am continuing to +write programs (mostly for my own use), and Arland has also +written few. He intends to do more with this once the graphics +support is complete. + +Recognizing that non-programmers might find this useful, we are +discussing writing interfaces that would allow using it without +directly interacting with the Forth listener. (Two text based +program launchers have been written, but Arland is considering +writing something that make use of the graphical abilities for +this). + +Interacting With The World + +I'm not overly concerned with this. Our current plan is to +eventually provide a limited ethernet or wifi access. For me, +I think it'll mostly be small periods of connectivity where I +send off messages, receive bundles of things, and then +disconnect. + +We do not plan to support always on internet connectivity. + +But: we are interested in low power local mesh networks between +devices. This is likely to be used w/embedded systems (a +separate topic) that our main computers can interact with as +needed. + +Timeline + +Two prototypes have been built. We have constructed one slab +style unit out of wood, cardboard, a Raspberry Pi 3, an LCD, +batteries, and a USB keyboard. It's been used a little, but is +quite flimsy and is falling apart. + +I also have a system running on a Teensy 4.1. This doesn't yet +have an enclosure, and has various bits loosely attached. + +In the summer of 2024 I'm trying to complete the initial serial +based Teensy build (along with a serial + ps/2 + vga device +using the TTGO VGA CONTROLLER). I'm also sourcing the components +for the first full slab build. + +We are going to try to have two of the slabs complete by the end +of 2024, and want to start building the more complex clamshell +devices in early 2025. + +Beyond this, if we stick with the process of using the Teensy as +a core, the board design is open, so we might be able to design +custom boards adding in whatever additional components are used. +Discussions on this are ongoing. + +Once we have functional systems, we do plan to produce a number +of them for our use and backup purposes. Arland is interested in +potentially offering them for sale if there's interest in them.