MicrOS 21 July 2011 ====== Contents ================================================================ I. Introduction II. Usage 1. Execute 2. Port I/O 3. Flash Editing 4. Link Port I/O 5. Quit/Suspend III. Usage of the flash editor 1. General Work Flow 2. Copy Function 3. Editor Function 4. Flash Erase Function 5. Flash Write Function 6. Utility Functions 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 pre-loader called MICROLDR. (It is not recommended that MicrOS be run from a shell.) Helpfully, the pre-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 insert 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. 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 ------ Flash Editing ----------------------------------------------------------- The flash editor is the primary feature of MicrOS. See the section entitled Flash Editing, below. ------ Link Port I/O ----------------------------------------------------------- I'm not sure how this feature is supposed to function. Ask BrandonW. ------ Quit/Suspend ------------------------------------------------------------ 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. 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. Reboot If you have finished reprogramming the boot sector or OS, select this option to reboot the unit. ====== Flash Editing =========================================================== ------ 1. General Work Flow ---------------------------------------------------- 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. ------ 2. 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 81 for the page. ------ 3. 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. 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) F3: 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 XTthetan: Set string length/Set to auto STAT: Set/disable wildcard DEL: Stop the search 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 can be turned off. 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 ^. 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. ------ 4. 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. ------ 5. 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. ------ 6. 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. 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. 3. 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 ------ 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.