From 98b416a72f0e3d882ec80662b416b3650cc2515b Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Tue, 11 Jul 2023 07:04:43 -0400 Subject: [PATCH] Add docs --- README.md | 16 ++++++ doc/intro.txt | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/lcd.txt | 63 ++++++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 doc/intro.txt create mode 100644 doc/lcd.txt diff --git a/README.md b/README.md index 0802bd5..a437565 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/doc/intro.txt b/doc/intro.txt new file mode 100644 index 0000000..3da4b10 --- /dev/null +++ b/doc/intro.txt @@ -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 diff --git a/doc/lcd.txt b/doc/lcd.txt new file mode 100644 index 0000000..9c6214f --- /dev/null +++ b/doc/lcd.txt @@ -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. -- 2.45.2