3 files changed, 224 insertions(+), 0 deletions(-)

M README.md
A doc/intro.txt
A doc/lcd.txt

@@ 6,3 6,19 @@ To build, run `make` in this directory.
 
 This repository has a TI-84+ emulator, you can launch the built ROM through
 that emulator with `make emul`.
+
+For more details, see docs in `doc`.
+
+## Emulator usage
+
+This will show a window with the LCD screen's content on it. Most applications,
+upon boot, halt after initialization and stay halted until the ON key is
+pressed. The ON key is mapped to the tilde (~) key.
+
+Press ESC to quit.
+
+As for the rest of the mappings, they map at the key level. For example, the 'Y'
+key maps to '1' (which yields 'y' when in alpha mode). Therefore, '1' and 'Y'
+map to the same calculator key. Backspace maps to DEL.
+
+Left Shift maps to 2nd. Left Ctrl maps to Alpha.

@@ 0,0 1,145 @@
+# TI-84+
+
+The TI-84+ is a machine with many advantages, one being that
+it's very popular.  It also has a lot of flash memory and RAM.
+
+Its builtin keyboard and screen, however, are hard to use,
+especially the screen. With a tiny font, the best we can get is
+a 24x10 console.
+
+There is, however, a built-in USB controller that might prove
+very handy.
+
+I haven't opened one up yet, but apparently, they have limited
+scavenging value because its z80 CPU is packaged in a
+TI-specific chip. Due to its sturdy design, and its ample RAM
+and flash, we could imagine it becoming a valuable piece of
+equipment if found intact.
+
+The best pre-collapse ressource about it is WikiTI[1].
+
+As it is now, with its tiny screen and cumbersome keyboard,
+Collapse OS is not really usable on the TI-84+. One could
+imagine a scenario where one has a terminal and uses the TI-84+
+through the link for its large amount of flash and RAM. But
+using it standalone? Nah, not even post-collapse.
+
+Therefore, this recipe is more of a "look, I run!" demo.
+
+# Gathering parts
+
+* A TI-84+
+* A USB cable
+* tilp[2]
+* mktiupgrade[3]
+
+# Build the ROM
+
+Running "make" in /arc/z80/ti84 will result in "os.rom" being
+created.
+
+# Emulate
+
+Collapse OS has a builtin TI-84+ emulator using XCB for display
+in emul/hw/ti. You can invoke it with "make emul".
+
+You will start with a blank screen, it's normal, you haven't
+pressed the "ON" key yet. This key is mapped to tilde (~) in the
+emulator. Once you press it, the Collapse OS prompt will appear.
+See emul/hw/ti/README.md for details.
+
+# Upload to the calculator
+
+# Background notes
+
+Getting software to run on it is a bit tricky because it needs
+to be signed with TI-issued private keys. Those keys have long
+been found and are included in keys/. With the help of the
+mktiupgrade, an upgrade file can be prepared and then sent
+through the USB port with the help of tilp.
+
+That, however, requires a modern computing environment. As of
+now, there is no way of installing Collapse OS on a TI-8X+
+calculator from another Collapse OS system.
+
+Because it is not on the roadmap to implement complex
+cryptography in Collapse OS, the plan is to build a series of
+pre-signed bootloader images. The bootloader would then receive
+data through either the Link jack or the USB port and write that
+to flash (I haven't verified that yet, but I hope that data
+written to flash this way isn't verified cryptographically by
+the calculator).
+
+As modern computing fades away, those pre-signed binaries would
+become opaque, but at least, would allow bootstrapping from
+post-modern computers.
+
+# Instructions
+
+WARNING: the instructions below will wipe all the contents of
+your calculator, including TI-OS.
+
+To send your ROM to the calculator, you'll need two more tools:
+mktiupgrade and tilp.
+
+Once you have them, you need to place your calculator in
+"bootloader mode", that is, in a mode where it's ready to
+receive a new binary from its USB cable.  To do that you need
+to:
+
+1. Shut down the calculator by removing one of the battery.
+2. Hold the DEL key
+3. But the battery back.
+4. A "Waiting... Please install operating system now" message\
+   will appear.
+
+Once this is done, you can plug the USB cable in your computer
+and run "make send". This will create an "upgrade file" with
+mktiupgrade and then push that upgrade file with tilp. tilp will
+prompt you at some point.  Press "1" to continue.
+
+When this is done, you can press the ON button to see Collapse
+OS' prompt!
+
+# Validation errors
+
+Sometimes, when uploading an upgrade file to your calculator,
+you'll get a validation error. You can always try again, but in
+my own experience, some specific binaries will simply always be
+refused by the calculator. Adding random "nop" or reordering
+lines (when it makes sense, of course) should fix the problem.
+
+I'm not sure whether it's a bug with the calculator or with
+mktiupgrade.
+
+# Usage
+
+The shell works like a normal BASIC shell, but with very tight
+screen space.
+
+When pressing a "normal" key, it spits the symbol associated to
+it depending on the current mode. In normal mode, it spits the
+digit/symbol. In Alpha mode, it spits the letter. In Alpha+2nd,
+it spits the uppercase letter.
+
+Special keys are Alpha and 2nd. Pressing them toggles the
+associated mode.  Alpha and 2nd mode don't persist for more than
+one character. After the character is spit, mode reset to
+normal.
+
+Pressing 2nd then Alpha will toggle the A-Lock mode, which is a
+persistent mode.  The A-Lock mode makes Alpha enabled all the
+time. While A-Lock mode is enabled, you have to enable Alpha to
+spit a digit/symbol.
+
+Simultaneous keypresses have undefined behavior. One of the keys
+will be registered as pressed. Mode key don't work by
+simultaneously pressing them with a "normal" key. The presses
+must be sequential.
+
+Keys that aren't a digit, a letter, a symbol that is part of
+7-bit ASCII or one of the two mode key have no effect.
+
+[1]: http://wikiti.brandonw.net/index.php
+[2]: http://lpg.ticalc.org/prj_tilp/
+[3]: https://github.com/KnightOS/mktiupgrade

@@ 0,0 1,63 @@
+# TI-84+ LCD driver
+
+Implement (emit) on TI-84+ (for now)'s LCD screen. Lives at
+B350.
+
+Required config:
+
+* LCD_MEM: 2b area where a that will point to an area allocated
+  to LCD driver memory during LCD$ init.
+
+The screen is 96x64 pixels. The 64 rows are addressed directly
+with CMD_ROW but columns are addressed in chunks of 6 or 8 bits
+(there are two modes).
+
+In 6-bit mode, there are 16 visible columns. In 8-bit mode,
+there are 12.
+
+Note that "X-increment" and "Y-increment" work in the opposite
+way than what most people expect. Y moves left and right, X
+moves up and down.
+
+# Z-Offset
+
+This LCD has a "Z-Offset" parameter, allowing to offset rows on
+the screen however we wish. This is handy because it allows us
+to scroll more efficiently. Instead of having to copy the LCD
+ram around at each linefeed (or instead of having to maintain
+an in-memory buffer), we can use this feature.
+
+The Z-Offset goes upwards, with wrapping. For example, if we
+have an 8 pixels high line at row 0 and if our offset is 8,
+that line will go up 8 pixels, wrapping itself to the bottom of
+the screen.
+
+The principle is this: The active line is always the bottom
+one. Therefore, when active row is 0, Z is FNTH+1, when row is
+1, Z is (FNTH+1)*2, When row is 8, Z is 0.
+
+# 6/8 bit columns and smaller fonts
+
+If your glyphs, including padding, are 6 or 8 pixels wide,
+you're in luck because pushing them to the LCD can be done in a
+very efficient manner.  Unfortunately, this makes the LCD
+unsuitable for a Collapse OS shell: 6 pixels per glyph gives us
+only 16 characters per line, which is hardly usable.
+
+This is why we have this buffering system. How it works is that
+we're always in 8-bit mode and we hold the whole area (8 pixels
+wide by FNTH high) in memory. When we want to put a glyph to
+screen, we first read the contents of that area, then add our
+new glyph, offsetted and masked, to that buffer, then push the
+buffer back to the LCD. If the glyph is split, move to the next
+area and finish the job.
+
+That being said, it's important to define clearly what CURX and
+CURY variable mean. Those variable keep track of the current
+position *in pixels*, in both axes.
+
+# Words descriptions
+
+LCD_BUF: two pixel buffers that are 8 pixels wide (1b) by FNTH
+pixels high. This is where we compose our resulting pixels
+blocks when spitting a glyph.