MicrOS 12 October 2011 ====== Contents ================================================================ I. Introduction II. Usage 1. Execute a. Erase Certificate 2. Port I/O 3. Hex Editor 4. Link Port I/O 5. Quit/Suspend a. Suspend b. Quit c. Reboot III. Usage of the Hex Editor 1. Editor Function a. Editor b. Find c. Options d. Block Move 2. Disassembler Function 3. General Work Flow for Flash Editing 4. Copy Function a. Copying when Running from RAM b. Copying when Running from Flash 5. Flash Erase Function 6. Flash Write Function 7. Flash Utility Functions a. Erase Suspend & Resume b. Reset c. Autoselect d. Lock Flash e. Unlock Flash IV. About & Legal 1. Change Log 2. Stuff ====== Introduction ============================================================ MicrOS is, at the core, just a bunch of routines that happen not to need the EOS or boot sector operate. Anything that uses these routines can be said to be based on MicrOS. However, the builds of MicrOS that are distributed include a user interface and important functionality. When running, MicrOS has no need to rely on EOS or boot code routines. In fact, the RAM version can back up the boot sector(s) to RAM, erase the entire flash chip, and restore the boot sector(s). With some modifications, MicrOS could be a complete replacement to TI's boot sector code, but is unlikely to be actually done, especially since it would require a few changes for the replacement to be compatibile with EOS. MicrOS now comes in several forms: there is a RAM-program version, a Flash Application version, and a version that can be written directly to the USB boot sector and launched from BrandonW's modified boot sector. MicrOS is now larger than the 8 K limit EOS imposes on RAM program, so the RAM version requires a loader called MICROLDR. (It is not recommended that MicrOS be run from a shell.) Helpfully, the loader will automatically archive itself if it is not already archived. ====== Usage =================================================================== MicrOS has no interrupts, so it cannot easily implement key debouncing the way the EOS does. Instead, it inserts a short delay after every key press. Additionally, it cannot HALT to save power. However, MicrOS now has an automatic suspend feature. Whenever GetKey is used, MicrOS will suspend itself after several minutes of nothing happening. The primary exception to this is the port monitor, which does not call GetKey. MicrOS is mostly menu-based. Each menu presents a list of numbered options. Press the number key for an option to go to it. Press CLEAR to return to the previous menu from a submenu. In any place that MicrOS expects you to enter a value in hexadecimal, you do not need to press alpha to enter the digits A-F. ------ Execute ----------------------------------------------------------------- The Execute menu allows you to run additional code. MicrOS has support for carrying a built-in payload, although the program build of it has none. To run this payload, press 1, Payload. MicrOS will confirm that you want to run the code. Press 9 to do so. You can also just write or upload your own code using the hex editor. In that case, select option 3, Custom, and enter in the address you have loaded the code into. a. ERASE CERTIFICATE MicrOS has the pre-packaged ability to erase just the certificate. Select option 2, Erase Cert, to do this. If this does not appear to work, you can erase the certificate manually with the erase flash function. Consult the following chart for what to enter for the page: Model Page TI-83+ 1E 83+SE 7E 84+ 3E 84+SE 7E Run it twice, once using 4000h as the address, and once using 6000h as the address. ------ Port I/O ---------------------------------------------------------------- MicrOS has a port monitor which can be used for debugging. It continually rereads the value found in the port shown. Please be aware that the automatic suspend feature does not work here. Consequently, it will happily run until your batteries die. Keys: - Right: Go forward one port - Left: Go back one port - +: Go forward 10h ports - -: Go back 10h ports - TAN (G): Go to a specific port - Enter: Write a value to the port - Clear: Return to the main menu ------ Hex Editor -------------------------------------------------------------- The hex and flash editor is the primary feature of MicrOS. See the section entitled Usage of the Hex Editor, below. ------ Link Port I/O ----------------------------------------------------------- I'm not sure how this feature is supposed to function. Ask BrandonW. ------ Quit/Suspend ------------------------------------------------------------ a. SUSPEND The suspend feature is pretty much identical to the automatic suspend. When running from flash, MicrOS will draw about 16 mA; when running from RAM, it will draw about 6 mA. For comparison, the EOS, when idle, draws 2 mA. The suspend feature implements a soft power-down that saves a lot of power. However, removing any batteries while MicrOS is suspended will hard reboot the calculator. b. QUIT If you have not corrupted any memory the EOS requires to operately properly, you can return to it without losing any data in RAM using this option. HOWEVER, if you have no boot sector and select this option, the calculator will probably be bricked. c. REBOOT If you have finished reprogramming the boot sector or OS, select this option to reboot the unit. ====== Hex Editor ============================================================== ------ 1. Editor Function ------------------------------------------------------ a. EDITOR The hex editor functions much like most PC hex editors. On the upper left, the current page swapped into the 4000h bank will appear if the top address is within the 4000h to 7FFFh range. Or, if you are running from flash, the range for swapping is 8000h-0BFFFh. If the top address is outside that range, the current page will not be printed. To the right, the first address on screen is shown. On the far right, the current address under the cursor is shown. An R will appear between the two address displays if an offset (see below) is set. An S will appear if you are currently in the swappable bank. Keys: Navigation: Arrow keys: move the cursor F4 and F5: jump backward/forward 10h bytes / and *: Jump +/-1000h bytes +/-: Jump +/- 100h bytes ( and ): Shift backward/forward one byte TAN (G): Go to an address ^: Set the page swapped into the 4000h bank (or 8000h, when applicable) Editing: MODE: Switch between hex and text mode ENTER: Edit the byte under the cursor. In text mode, you can type as you normally do in the EOS. STO: Perform a flash write. This function will appear on a separate screen. Only hex input works for this function. Press ENTER to confirm the write. The flash write will fail if you try to write a 0 over a 1. Probably won't hang if you try to write to RAM. Probably. CLEAR: Return to the Edit menu F1: Options (press F1 again to return to editing) ALPHA: Set offset to logical value ON+ALPHA: Directly set offset DEL: Redraw screen Quick Find: COS (F): Quick-find a single byte SIN: Quick-find a single word. Contrary to normal Z80 situations, you enter the word in big-endian format and it seaches in big-endian format. So if you enter 1F3C, it will only find matches where 3C is AFTER 1F. ,: Repeat last quick search Note: If your cursor does not move, it means there were no (more) matches. String Find: F2: Find options (press F2 again to return to editing) MATH: Run string find PRGM: Set current address & page to be the search string ON+PRGM: Go back to string source XTn: Set string length/Set to auto STAT: Set/disable wildcard DEL: Stop the search Bookmarks: 1-9: Jump to bookmark ON+1-9: Save bookmark 0: Toggle between here and last address Disassembler: x^-1 (D): Enter/exit disassembler b. FIND FEATURE MicrOS now has two nice find features. The first is the quick find, which functions exactly like Calcsys's find featre. However, there is the additional option pressing comma to repeat the last quick find. Also, be aware that this will scan the currently selected swappable flash/RAM page, but will not wrap, unlike the string find feature. MicrOS also has a string find feature, with several options. To use this feature, you first need to enter the string into free RAM. (Press VARS on the options menu to go some. MicrOS now defaults to that address being the location of the search string.) Then you need to tell MicrOS where to find the query string. Press PRGM to use the current cursor location. Or, press F2 to bring up the find options and manually set the page and address. Next, MicrOS needs to know how long the string is. The default is "Auto Length", where MicrOS assumes the string is zero-terminated. Or, you can manually specify a length. Finally, MicrOS supports using a wildcard in the query, which is turned off by default. c. EDITOR OPTIONS There are three special functions for the editor. The first, offset, sets an offset added to the DISPLAYED (not actual) address. This is useful if you need to allocate a RAM buffer in main RAM. For example, if the buffer is located at 0A000h, setting the offset to 6000h would make address 0A000h, the start of the buffer, display in the editor as 4000h, the start of a page of flash. shown address = offset + physical The second function, sets the page displayed as the current page in the hex editor. This is just like using F3. An unlisted option, VARS, will take you to the address where there should be some free scrap RAM for entering in strings to search for. Specifically, it goes to the area after MicrOS's internal variables. There should at least 100 bytes there before you run into the stack. The third function, RAM Buffer, lets you allocate space in main memory for editing. +------------------------------------------------------------------+ | WARNING: DO NOT ATTEMPT TO ALLOCATE A RAM BUFFER IF NO OPERATING | | SYSTEM EXISTS. This functionality specifically exists to allow | | RAM editing without corrupting data in RAM. If no OS is loaded, | | or you intend to reboot the unit when you are finished, there is | | no need to use this function. IF NO BOOT SECTOR EXISTS AND YOU | | ATTEMPT TO USE THIS FUNCTION, YOUR CALCULATOR IS LIKELY TO BE | | BRICKED. Instead, just select any random memory for buffering. | +------------------------------------------------------------------+ The buffer is simply an appvar located in RAM with an arbitrary name. If no buffer has been previously set, it will display the amount of free memory (in hex), and ask for a name for the variable. Then, it will ask for the size, in hex, for the variable. EOS will throw an ERR:MEMORY if you enter in a size too big. You will then be shown the address of the variable. If a buffer has already been created, this will show the address and name of the buffer. You may press ENTER to change it. The older buffer will not be deleted, so the new one must reside in the remaining free RAM. If you enter in the name of an existing appvar, and it is not archived, the program will display the address off the variable and ask you if you want to use it. Press ENTER to confirm, or any other key to return the menu. If the variable is archived, you will not be able to use it. d. BLOCK MOVE The Block Move function can be used to perform block memory moves in a RAM buffer. This function simply uses the LDIR or LDDR instruction. Enter in the arguments for HL, DE, and BC (source, destination, and size) and select whether to use LDIR or LDDR. Which you use matters if you are performing a move and not a copy. You may find out more about these two instructions online. This function does not perform page wrapping. This function does not take into account the offset used by the hex editor. ------ 2. Disassembler --------------------------------------------------------- MicrOS has a complete disassembler function. It supports all officially supported Z80 instructions, as well as the autocopy instructions, SLL, and index half registers. The disassembler supports three main options: lowercase or uppercase, displaying the current address, and decoding RST 28h as either a BCALL or as RST 28h. If you configure an offset in the hex editor, the disassembler will also show offset addresses, even for JR. However, JP and CALL will be unaffected. The disassembler is 99% bug free as of this time. If you find any instructions are incorrectly decoded or cause a crash, please contact me. Keys: x^-1 (D): Enter/exit disassembler TAN (G): Go to address ^: Set page F1: Toggle case F2: Toggle displaying addresses F3: Toggle BCALLs ALPHA: Set offset to logical value ON+ALPHA: Directly set offset 0-9: Bookmarks, just like in the hex editor ------ 3. General Work Flow for Flash Editing ---------------------------------- The Flash Editor is designed to buffer a sector of flash memory in RAM before writing any changes to flash. (However, you can write directly to flash from within the hex editor; see below.) The Flash Editor does not provide a structured editing environment. You are required to manage memory on your own. For units that have the full 128 K RAM chip, this is easy: RAM pages 84h through 87h can be used to buffer a whole sector. All TI-83+SEs and older TI-84+(SE)s have the 128 K RAM chip; newer TI-84+(SE)s and all TI-83+s do not. For units that do not have the 128 K RAM chip, you must allocate memory in main RAM. There is not enough main RAM to buffer an entire flash sector. Instead, you will only be able to buffer a small portion of flash at a time. Use the OS Memory Management screen to make sure you have enough free RAM to do what you need to do, and then use the RAM Buffer option to create an appvar for buffering flash. The hex editor provides an offset function to make editing from main RAM easier. ------ 4. Copy Function -------------------------------------------------------- This function will copy data from one page to another. It is intended for copying data to RAM from either flash or RAM. It functions slightly differently depending on whether MicrOS is located in flash or RAM. a. COPYING WHEN RUNNING FROM RAM MicrOS uses the 4000h memory bank for paging when running from RAM. Enter in the source page and address, data size, and destination page and address. Press ENTER to confirm the command. It will wrap to next page when the address counter increments from 7FFFh to 8000h. You can also use the copy function to copy to main RAM (8000h to FFFFh). In this case, enter the destination address in RAM for the destination address, and enter garbage for the destination page. b. COPYING WHEN RUNNING FROM FLASH When running from flash, MicrOS uses the 8000h bank for paging. Enter the source page first, then the source address. Keep in mind that the data will be copied from the 8000h range, so normal flash addresses will need to have 4000h added to them. Be aware that since paging is being done in the 8000h range, if you wish to copy to or from RAM in the 8000h-0BFFFh range, you must enter in 81h for the page. ------ 5. Erase Flash Function ------------------------------------------------- This function will issue a flash erase command to the given address. Enter in the page to be swapped into the 4000h bank, and the address to write the command to. This should generally be 4000h, though if you want to erase the certificate, you may need to use 6000h. This function does not take into account the offset used by the hex editor. You may abort the erase operation by pressing CLEAR. Be aware, however, that doing so will leave the sector being erased in a scrambled state. Entering in an address in the range 0000h to 3FFFh will erase the first sector of the operating system. Entering in an address in the range 8000h to 0FFFFh will fail. ------ 6. Write Flash Function ------------------------------------------------- This functions much like the copy flash function. The inputs are the same. Functionally, the only difference is that you must select this to write to flash. You may press CLEAR to abort the write. There is one important difference in the write function if you are running MicrOS from flash. In this case, although paging for the SOURCE is done in the 8000h range, the paging for the DESTINATION is still done in the 4000h range. ------ 7. Utility Functions ---------------------------------------------------- a. ERASE SUSPEND, ERASE RESUME MicrOS has several flash utility functions. The first two are erase suspend and erase resume. These can be used during an erase operation to allow reading from the flash chip again. To prevent MicrOS from waiting for the erase to complete, press the / (divide) key during the erase. These are only available if MicrOS is in RAM. b. RESET This issues a reset command to the flash chip. This can be used to abort an erase. c. AUTOSELECT This asks the flash chip what its manufacturer ID and device ID are. The TI-83+ should report 23 or 0B9h for its device ID; the TI-84+ should report DA, and the TI-83+SE and TI-84+SE should report C4. d. LOCK FLASH In the RAM program version, this will call the OS routine to lock flash. This can be helpful for seeing which ports are protected. This will not work without an OS. In the flash version of MicrOS, this will directly lock flash. e. UNLOCK FLASH This function is only available if MicrOS is located in a privileged sector. It unlocks flash, of course. ====== About & Legal =========================================================== ------ Change Log -------------------------------------------------------------- 26 June 2011: Initial alpha Implemented core routines 27 June 2011: Inital beta Removed almost all B_CALLs from code that doesn't need them Added port monitor Size: 6 K 28 June 2011: Beta 1.1 Fixed the flash editor so ASCII editing doesn't use any B_CALLs Implemented some interrupt code Moved MicrOS variables to saveSScreen Renamed a few things and moved a few things Made some port numbers constants for the benefit of readers Added Suspend function Added a default payload that tests the autoselect commands Size: 6.2 K 29 June 2011: Beta 1.2 Added autoselect command tests Added flash commands erase suspend, erase resume, and reset Going to the main menu now always resets the stack (safety measure) Added compile-time options Size: 6.7 K 30 June 2011: Beta 1.3 Fixed reboot code Correct errors in font Added more #ifdefs 7 July 2011: Beta 1.4 Added support (in theory) for compiling for running from flash Fixed LCD initialization Hopefully fixed rebooting Size: 6-7 K depending on build configuration 13 July 2011: Beta 1.5 Fixed all known bugs in flash version, mainly concerning flash routines - Hex editor's write-a-byte works - Block copy-to-RAM works - Erase flash works - Block write-to-flash works Fixed bug where the R indicator would appear when it shouldn't. Added certificate erase function Size: 6.7 K for flash version, 7.2 K for program version 15 July 2011: Beta 1.6 BrandonW added inital linking code Added a couple device IDs No additional builds today 16 July 2011: Beta 1.6 Improved MicrOS logo on About screen Moved Suspend into the Quit menu Added UnlockAllRAM and GetVersion calls Assembling now shows some statistics 18 July 2011: Beta 1.7 Added Quick Find feature Added string find feature Fixed a bug in the hex editor's single-byte write-to-flash when running from flash. 19 July 2011: Beta 1.7 Little changes Size: 10.2 K for flash version, 11.0 K for RAM version. 20 July 2011: Beta 1.7 Moved Interrupt Vector Table into flash when running from flash Implemented automatic suspend feature Changed cursor blink rate so it's not really fast in fast mode Added support for building for applications 21 July 2011: Beta 1.7 Fixed bug when quitting from an applications Finally added support for running from RAM again by loading with the MICROLDR program. Improved the consistency of when the offset applies in the hex editor 24 July 2011: Beta 1.8 Changed a few keys in the hex editor Added bookmark functionality 9 August 2011: Beta 1.8 Adding disassembler! 7 October 2011: Beta 1.8 Resumed work on disassembler 9 October 2011: Beta 1.8 Finished disassembler, hopefully Removed ability to browse all 256 characters of ASCII chart since MicrOS mostly only uses the standard 127. Shuffled a few menus around Fixed a potential bug with the TI-83+ Fixed bug in hex editor S indicator More sanity checks for the PutS and PutC routines To do: Rewrite large portions of readme, add BCALL lookup function 12 October 2011: Beta 1.8 Fixed minor typos in instructions Fixed index half registers crashing Fixed bug with garbage bookmarks New keys for disassembler Bookmark 0 now exchanges Size: 14.3 K for Flash, 13.7 for RAM ------ Stuff ------------------------------------------------------------------- This program uses the flash unlock exploit developed by Brandon Wilson. The flash unlock code is not provided with the source to this program. This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See http://sam.zoy.org/wtfpl/COPYING for more details. Improper use of this program could easily damage your calculator, bricking it. Also, proper use of this program could easily damage your calculator, bricking it. You have been warned.