CrunchyOS 0.6 Manual

I. Introduction

CrunchyOS is an assembly shell for the TI83+ and TI83+SE calculators that allows you to run assembly language programs on your TI83+. ASM programs are faster, and usually have better graphics and game mechanics than TI-Basic games. Examples of other TI83+ ASM shells include Ion, MirageOS, and TSE.

CrunchyOS is a step above the other shells in that it supports compressed programs. Compressed programs are far smaller then their uncompressed equivalents, at the cost of short decompression time. Many large programs can be compressed down by factors around 50%, but most smaller games can get 10-30% size savings.

Savings Table

Here is an example of the size differences between compressed and uncompressed programs: (program sizes may be off by up to 10 bytes)

Program Name	Ion/MirageOS Size:	>>	CrunchyOS Size:	Savings
Joltima 1.9	22242	>>	11288	10954	(49.2%)
Dying Eyes 1.0	22305	>>	13881	8424	(37.8%)
Gemini	23872	>>	13459	10413	(43.6%)
Phoenix 2.11	7953	>>	5774	2179	(27.3%)
Lotus Turbo Challenge 1.0	10161	>>	7116	3045	(30.0%)
Total:	86533	>>	51518	35015	(40.4%)

II. Features

CrunchyOS has the following features:

Build ASM programs inside the app using CrunchyOS Builder!
Supports Pucrunch compressed programs, which have far smaller sizes than uncompressed ion programs.
CrunchyOS automatically creates, loads, and saves appvars, so compressed programs can save data, like highscores or savegames.
Runs all Ion and CrunchyOS programs.
Runs almost all MirageOS programs.
Runs programs located in RAM as well as Archive.
Memory leak free, unlike Ion. All allocated memory is deletable in case a program fails to TIOS. Feel free to shut off the calc during that buggy ion program that uses Getkey and not worry about corrupted memory.
The shell will automatically clean up temporary programs, and also repair ion programs in the event of a program failure to TIOS.
Writeback for archived programs is implemented by creating and loading small patch files, and archiving those instead of the complete program. This takes up more memory, but the calc will perform garbage collects far less often.
Compressed levels for all programs that support external levels (program must use Iondetect)
If there is not enough RAM to run a program, it will be marked with a * symbol.
Detects Ion programs with incorrect headers, unlike MirageOS.

III. Using CrunchyOS

First, you must install the flash application, crnchyos.8xk onto your TI83+ or TI83+ silver edition graphing calculator. Please consult the TI-Graphlink or TI-Connect documentation for more information on sending flash applications.

Disclaimer: Some ASM programs contain bugs that may freeze, crash, or reset the RAM of the calculator. If you are working on any important TI-Basic projects, make sure you group or archive all your files before running an assembly program.

To start the shell, press the APPS button, then select CrnchyOS from the application list and press Enter, as shown below:
APPLICATIONS 1:Finance... 2:Bubble *3:CrnchyOS* 4:MirageOS

APPLICATIONS 1:Finance... 2:Bubble *3:CrnchyOS* 4:MirageOS

The program menu will appear. CrunchyOS, Ion, MirageOS, and TI-Basic programs that begin with a colon will appear on the program list.

Use the arrow keys to move the cursor. Up and Down move the cursor, while Left and Right advance by page. 2nd and Enter keys run the selected program. Use Mode or Clear to quit the shell.

Programs without enough free RAM to run will be marked with an asterisk * symbol. You will receive an error message when you attempt to run a program without enough RAM to hold the unarchived or uncompressed copy. Delete, archive, or group programs to free up RAM space for the programs to run.

CrunchyOS 0.5b by Dwedit Not enough free RAM to load the program. Mem Needed: 22393 Mem Available: 15632

If you run the shell with no compatible programs on the calc, you will get the No Programs screen. Press Clear or Mode to quit the shell, then go install some programs.
CrunchyOS 0.5b by Dwedit No Programs!

If your program fails, gives a TIOS error, or is turned off during a getkey, don't panic. Your memory is safe, since the shell features memory leak protection.
For example, the calc has been shut down with 2nd+Off while running the program Afrodance, and weird symbols have appeared on the homescreen text! Your memory is safe. The garbage text is normal, and not an indication that your memory is corrupt. The next time you start the shell, the temporary program "CruEXEC" that was created will be deleted (if the program was archived), or the Ion program will be repaired (if the program was in ram).

IV. Level Packer Tool

CrunchyOS includes a tool to compress external data (level) files for Ion programs. You will need the Visual Basic 6.0 runtime libraries and ActiveX controls installed to use the program.
Level packs compressed by this program will work for any Ion or MirageOS program that uses Iondetect, but you must be using the CrunchyOS shell.

Run the program, IonLevelCompressor.exe
First, you will need to select which level sets your want to compress. They must all be from the same game. Click Next >>.

Then the ionDetect string length selector window displays the current IonDetect string, which may be incorrect. Press the up and down buttons until the string is the correct IonDetect string. If you selected multiple levels, the string should be properly autodetected, with higher accuracy for more levels selected.

Finally, the program may ask for the path to pucrunch.exe, which is included with the shell. If it does, locate the file.
Click the Compress button to compress the selected ion levels. Programs will not be overwritten, new programs named like LEVELc.8xp will be created. This only renames the filename, not the on-calc name. The c at the end of the filename is short for compressed or crunchy.

V. Developer Information

To take advantage of the compression and other features offered by CrunchyOS, you will need to write programs for the shell.

You should upgrade to TASM 3.2 final if you have not done so already. The program is available on ticalc.org or my website. It is a Win32 console program with lots of improvments over the old dos versions, like less limits on labels, and long file names.

The way I recommend to program for CrunchyOS (and all other shells) is to use the universal "dwedit.inc" file. This file handles all the calcs (TI82,83,83+) and all shells for each calc. To compile for a different calc/shell combination, use a different batch file. Get the set of batch files for use with dwedit.inc at http://dwedit.tk/.

Rules of CrunchyOS programming

The start address is usermem+2 (progstart+2). This is because of the leak-free program loader, the first two bytes at progstart are the sizebytes for the program.
The first line of code of the program should be executable. There are no descriptions, headers, BB,6D's, or anything like that inside the program. (you can still put equates above the code of course)
The program is compiled and compressed, then a header is added after the program is compressed.
Use asm_cru.bat to compile the program. It handles all the complex steps to compile, compress, and build the header automatically.
You must create a .name file, which is a separate file that contains the description of the program. Name the file "progname.name", where progname is the base filename of the file you compile, so "myprog.z80" would need "myprog.name". The format for the line is just like in the code, .db "File Description",0
You must define the labels SAVE_START and SAVE_LENGTH to mark where the appvar data starts and stops. If you don't use saves, equate them to 0.
Any data that isn't part of a save block is reset on program start.
Do not touch cmdshadow, especially not the first 10 bytes.

Converting an Ion program to use Dwedit.inc

The easiest way to program for CrunchyOS is to use the universal "dwedit.inc" include file, since it supports all the shells, including CrunchyOS.
You include "dwedit.inc" instead of the shell specific include file. No surprise there.
First remove all executable code before the program description. Dwedit.inc itself generates the shell-specific start code depending on which shell you compile for. Name the start code of the program lblStart:, since dwedit.inc looks for a line with that name.

For CrunchyOS compatibilty, the program description must be added conditionally. First make the necessary .name file. Then create a new line:
#ifndef CRUNCHY\tTitle: #include "progname.name"\#endif
Dwedit.inc needs the program name label to be defined as tTitle:. Only CrunchyOS needs the .name file.

Here's an example:
This is the original beginning of the source code of 7G:

#include "ion.inc"
#ifdef TI83P
  .org progstart-2
  .db $BB,$6D
#else
  .org progstart
#endif
  ret
  jr nc,start
  .db "--==7G==-- v3.0", 0
start:
  ;start of prorgam

Make the changes... First replace ion.inc with dwedit.inc, then remove the shell-specific start code. Create the .name file, make the program description not show up on CunchyOS, Rename the program start label, create the conditional description.

#include "dwedit.inc"
#ifndef CRUNCHY\tTitle: #include "7g.name"\#endif
lblStart:
  ;start of program

There's more. The saved data must be marked, and the length known. Here's the original 7G hiscore memory:

Hightooeasynb:   .dw $0000 Higheasynb:   .dw $0000 Highnormalnb:   .dw $0000 Highhardnb:   .dw $0000 Highimpnb:   .dw $0000
To get writeback working properly in CunrchyOS, you need to mark the start of the perminent data with a SAVE_START label, then define the length. Subtracting the SAVE_START from current address $ is the easiest way to get the SAVE_LENGTH, as shown below:

SAVE_START Hightooeasynb:   .dw $0000 Higheasynb:   .dw $0000 Highnormalnb:   .dw $0000 Highhardnb:   .dw $0000 Highimpnb:   .dw $0000 SAVE_LENGTH = $ - SAVE_START
If your program has multiple regions of data that needs to be saved, you should move the lines around so that the entire savegame is one big contiguous block. The shell supports split savedata, but the batch file that builds the program does not.
If your program needs to perminently save self modifying code that is scattered all over the place, you should design your program differently. CrunchyOS won't support the excessive number of short saveblocks necessary for those situations. Redesign your program so the self-modify code can be stored to and rebuilt from a table of bytes for example.
If your program does not need to save, set SAVE_START = 0 and SAVE_LENGTH = 0.

TI82 Compatiblity

This section has nothing to do with CrunchyOS, just with porting your programs to the TI82.

For TI82 compatibilty, there are certain romcalls that need to be called with bcall(), and certain romcalls that need be called with icall().
All these romcalls should be called with icall(_romcallname) instead of bcall(_romcallname):
_getkey _ldhlind _cphlde _divhlby10 _divhlbya _getcsc _lcdbusy
Use bcall() for the rest of the available romcalls: (yes... that's it. TI82 assembly is more limited due to lack of a complete romcall list)
_DispHL _Puts _NewLine _PutC _Vputs _Vputmap _ClrLCDFull _ClrLCDF _GRBUFCPY ;should be using fastcopy instead _GRBUFCPY_VThe TI82 ACE shell also provide these additional romcalls:
_lcdbusy _chkfindsym _createprog _memfree
If you need any of the ion functions other than ionFastcopy, you can find the code for them in "ionf.z80" that comes with ion, or "cru_ionf2.z80" that comes with this shell. Put #IFDEF TI82 and #ENDIF around the missing ion functions, since you will not need to include them again when compiling for Ion.

Programming for CrunchyOS without using Dwedit.inc

If you don't want to bother with full range shell compatibility, then you can just modifiy your existing ion header like this:
.org progstart+2 ;changed from -2 to +2!
Remove the BB 6D, remove the ret, jr nc lines, and remove the program description. Move any code or data that appears before the program start further down the file. Make the necessary .name file described previously.

Using ion.inc or mirage.inc will work fine, just not automatically for all the calcs and shells like dwedit.inc does.

Still not clear?

Contact me by sending me an email or IM. My AIM screenname is Dwedit403, so contact me about CrunchyOS development issues there.

VI. Technical Info about the shell

Supported MirageOS routines:

Almost all MirageOS routines are implemented currently.

Header for CrunchyOS programs:

"cRu",progsize,savesize,[save1_address,save1_size],[...],description,0,raw compressed data

"cRu" (3 byte string)
Program Size (word). Program size is used by the shell for memory allocation, pucrunch doesn't need it.
Total Save Size (word). This is the total size of the appvar that will be created by the shell. A size of 0 indicates that an appvar should not be created, and there are no save blocks defined next.

For each save block:
Address of block (word). The address is inside the program, starting at $9D97.
Size of block (word).
The total sizes of the blocks must add up to the Total Size. All the sample programs have one save block. Multiple save blocks are only necessary for when the savegame split accross multiple places in the file, and you have no access to the source code to fix that.

After the save blocks:
Program Description + null terminator.

After the description:
Raw pucrunch compressed program.

The Program (that gets compressed) starts at origin $9D97 instead of $9D95, and has no description or header there, it begins with the executable code. It can use any ion function, or supported MirageOS function (MirageOS support is not yet complete).

The save blocks are all the information necessary to implement "writeback". The shell manages an appvar (with the same name as the program). On program load, it copies savegames from the appvar to the program. On program quit, it creates an appvar if it doesn't exist, then copies savegames from the program to the appvar.

The current system requires you to define labels SAVE_START, and SAVE_LENGTH. The batch file to build the program, asmcru.bat, adds .export directives, so it puts SAVE_START, SAVE_LENGTH, and PROG_SIZE into a temp.sym file. The program is compressed, then a separate header is built based on the contents of the temp.sym file. The header and compressed program are merged to a new .bin file, then that .bin file gets devpac8xed.

Format for Pucrunched Ion Levels

"pu",detectstring,size,raw compressed data

"pu" - 2 byte string literal
detectstring - This is the string that is passed to IonDetect when looking for the program
size - This is the uncompressed size of the file.
raw compressed data - Take the source file after the detection string, compress the rest, then it goes here

Converting Ion binaries to CrunchyOS format by hand

In case you need to port a closed source ION program to the shell, just do this:
First open the .8xp file in a hex editor, and select everything AFTER BB 6D, and exclude the last 2 bytes. Save it as a .bin file. Replace the ion header with 0's, then remove the first 2 bytes. This sets the execution address, and pucrunch's rle will take care of the zeroes.

Compress the thing, run Pucrunch.exe file.bin file.pu
Copy file.pu to a new .bin file

Slap on a new header:
"cRu" (3 bytes), program size (word), $0000 (word), Program Description, $00 (byte)

If you want to support save games, and know the address of the data in ram:
"cRu" (3 bytes), program size (word), savegame size (word), savegame address (word), savegame size (again), Program Description, $00 (byte)

Finally, for split savegames, you can about 7 different save blocks...
"cRu" (3 bytes), program size (word), savegame size (word), savegame part 1 address (word), savegame part 1 size (word), savegame part 2 address (word), savegame part 2 size (word)... Program Description, $00 (byte)
The sum of the saveblocks must add up the the total savegame size

VII. Version History

Version 0.1, Dec. 17, 2003

Initial release
Ran CrunchyOS programs only
Writeback save data to appvars for CrunchyOS programs.
Bad menu system.

Version 0.2, Dec. 24, 2003

Rewrote the program load menu, still bad.

Version 0.3, Dec. 30, 2003

Fixed the menu, now perfect.
Added Ion and limited MirageOS support. No writeback yet.

Version 0.4a, Jan. 4, 2004

Added leak free program loader
Added support for compressed external levels for ALL GAMES.

Version 0.4b, Jan. 5, 2004

Fixed a really stupid bug where it executed the description of MirageOS programs :)

Version 0.5, Jan. 9, 2004

Added writeback for Ion and MirageOS programs by creating patches that are applied to the program on load.

Version 0.5a, Jan. 9, 2004

Now the patches are applied even when the programs are unarchived

Version 0.5b, Jan 13, 2004 (5 days in the submission queue at ticalc.org...)

First ticalc.org release
Re-enabled basic with a better loader by Dan Englender

Version 0.6, Jan 18, 2004

Better MirageOS support, plays almost all MirageOS games!
MirageOS style fastcopy that keeps interrupts enabled for MirageOS programs.
CrunchyOS Builder!

VIII. Credits

CrunchyOS Shell written by Dan Weiss (Dwedit) in 2003-2004. Web: http://dwedit.tk/, Email: crunchyos@dwedit.cjb.net
Fast program sorter by Martin Warmer.
MirageOS routines have been disassembled from the shell, and integrated into CrunchyOS. Their code is owned by the MirageOS team. A couple routines were disassembled by Kristopher Root.
Ion function routines by Joe Wingbermuehle. Web: http://joewing.net/index.shtml
Pucrunch compression technology created by Pasi 'Albert' Ojala. Long rambling page about how pucrunch works: http://www.cs.tut.fi/~albert/Dev/pucrunch/
Original Gameboy Z80 Pucrunch decompressor created by Jeff Frohwein in 1999.
The decompression routine is modified from the original GBZ80 version. First it was ported to be TASM compatible, and for a real Z80 rather than the gameboy Z80. I also modified it to run from saferam1, and to test for ROM page boundaries.

IX. Contact

You can email me at crunchyos@dwedit.cjb.net, or send an AIM instant message to Dwedit403. I only chat about TI-calc releated stuff usually.