________ /\ _____\ \ \ \____/ __ __ __ __ __ \ \ ___\ /'__`\ /\ `__\ /'__`\ /'__`\ \ \ \__//\ \_\ \\ \ \ /\ \_\ \ /\ \_\ \ \ \_\ \ \___/_\\ \_\ \ \____ \\ \____/ \/_/ \/___/_/ \/_/ \/____\ \\/___/ /\____/ \/___/ Fargo v0.2.7.1 Copyright (C) 1996-1998 David Ellsworth All rights reserved. ============================================================================== Table of contents ============================================================================== Part 1: Using Fargo ------------------- 1.1: Introduction 1.2: Requirements 1.3: Installing Fargo 1.3.1: Installing Fargo from DOS 1.3.2: Installing Fargo from Linux 1.3.3: Installing Fargo without FLink 1.4: Running Fargo programs 1.5: Using FBrowser 1.6: Running old Fargo programs 1.7: Troubleshooting Part 2: Programming for Fargo ---------------------------- 2.1: Introduction 2.2: Lists of helpful information 2.3: Programming overview 2.4: The Fargo source code format 2.5: The Fargo object code format Part 3: Other topics -------------------- 3.1: Legal stuff 3.2: Contacting the developer 3.3: New versions and information 3.4: Revision history 3.5: Known bugs 3.6: Planned features ============================================================================== Part 1: Using Fargo ============================================================================== ------------------------------------------------------------------------------ 1.1: Introduction ------------------------------------------------------------------------------ Fargo is a software extension for the TI-92 graphing calculator that enables the execution of machine language programs. These programs are stored on your calculator as PRGM variables. Fargo itself consists of two primary components: the kernel and the shell. The kernel contains low level bootstrap routines that are used to load and run Fargo programs. It is also the interface whereby Fargo programs can communicate with the TI-92's built-in ROM OS while maintaining compatibility across all supported ROM versions. The shell provides an simple and organized way to list and execute Fargo programs that are stored in the calculator's memory. Fargo lets you use any program as your shell. The default shell packaged with Fargo is FBrowser. Fargo also includes a development toolkit for creating Fargo software. For more information on it, see the Part 2 of this document. ------------------------------------------------------------------------------ 1.2: Requirements ------------------------------------------------------------------------------ You must have access to a Graph-Link cable if you have a Macintosh and/or want to use TI's software to transfer Fargo to your TI-92. A PC program is supplied with Fargo that will allow you to transfer group files and backups using a homemade link (both the parallel and serial cables are supported). Fargo currently supports the following ROMs: +---------+--------------------+ | Version | Date | +---------+--------------------+ | 1.0b1 | September 13, 1995 | | 1.2 | October 11, 1995 | | 1.3 | October 20, 1995 | /\ | 1.4 | November 17, 1995 | /\ older date format: Month DD, YYYY | 1.5 | 01/02/96 | \/ newer date format: MM/DD/YY | 1.7 | 01/18/96 | \/ | 1.8 | 02/28/96 | | 1.10 | 03/20/96 | \____ note that there are two | 1.10 | 03/26/96 | / ROMs designated as 1.10 | 1.11 | 04/11/96 | | 1.12 | 05/08/96 | | 2.1 | 08/19/96 | <--- TI-92 II (available in Europe only) +---------+--------------------+ If your ROM is not on the list, please contact me! (see section 3.2) To find out what ROM version your TI-92 has, press [Diamond] [(] from the PrgmIO screen. Then press [2nd] [QUIT] to go back. Note that "1.12" stands for "one point twelve" rather than "one point one two"; therefore ROM 1.12 is newer than, for example, ROM 1.7. ------------------------------------------------------------------------------ 1.3.1: Installing Fargo from DOS ------------------------------------------------------------------------------ The following procedure details the process of putting Fargo onto your TI-92. This process will preserve all the files that you currently have on your calculator. The first step is to unzip Fargo into a directory on hard disk. For discussion purposes, let's call that directory "F:\FARGO". Next, make sure you set the environment variable FARGO to F:\FARGO and make sure F:\FARGO\BIN is in your path. To make this permanent, add the following lines to the file C:\AUTOEXEC.BAT: SET FARGO=F:\FARGO SET PATH=%PATH%;%FARGO%\BIN After you have made these settings, you may install Fargo on your calculator. If you have a homemade parallel link cable, you may install Fargo by typing "autofarg" at the DOS prompt. Otherwise, move on to section 1.3.3. ------------------------------------------------------------------------------ 1.3.2: Installing Fargo from Linux ------------------------------------------------------------------------------ The first step is to untar Fargo into a directory in your filesystem. For discussion purposes, let's call that directory "/usr/fargo". Next, make sure you set the environment variable FARGO to "/usr/fargo" and make sure both $FARGO/bin and $FARGO/flink are in your path. To make this permanent, add the following lines to your global profile: export FARGO=/usr/fargo PATH=$PATH:$FARGO/bin:$FARGO/flink If you are using c-shell, use this instead: setenv FARGO /usr/fargo set path = ( $path $FARGO/bin $FARGO/flink ) If you have a homemade parallel or serial link cable, go to $FARGO/tidev, read the README there, and install tidev. You may then install Fargo on your TI-92 by typing "autofarg" at the shell prompt. Otherwise, you are out of luck. You will have to go to Windows to use TI-Graph Link. ------------------------------------------------------------------------------ 1.3.3: Installing Fargo without FLink ------------------------------------------------------------------------------ First, make sure you have read and followed section 1.3.1. Transfer a backup from your TI-92 to F:\FARGO. You can give the backup any name you want. From the DOS command line, execute the following command: F:\FARGO>putfargo where is the name of the backup file you made, including the .92b extension. This will load the Fargo core into the backup file. Now transfer this modified backup file to your TI-92. There is now one step remaining: transfer all the .92p files from F:\FARGO to your TI-92. You now have Fargo on your calculator. The following .92p files are required to run FBrowser: asm\prgm\flib.92p Fargolib. Contains useful routines not found in ROM. asm\prgm\shell.92p FBrowser; the listing of programs you will see by default when you press [Shift] [ON]. The remaining .92p files are sample Fargo programs and libraries. ------------------------------------------------------------------------------ 1.4: Running Fargo programs ------------------------------------------------------------------------------ To launch the Fargo shell, use the hotkey [Shift] [ON]. This works from anywhere, provided that your TI-92 becomes idle within 1/4 second after the hotkey was pressed. You may also start Fargo programs in the same way that TI-BASIC programs are called. For example, to directly start the Sierpinski Triangle demo, you would enter "sierpin()" from the home screen. The Fargo shell can be executed just like any other Fargo program. As an alternative to pressing Shift-ON, you may execute the TI-BASIC command "shell()". Any Fargo program renamed to "shell" will be triggered when you press [Shift] [ON]. If you press [Shift] [ON] and there is no variable called "shell" in your calculator's memory, Fargo will display the message "SHELL NOT FOUND" in the status line. If a program has been directly launched, and for some reason it cannot be executed, Fargo will display an error message on the status line at the bottom of the screen. The message briefly describes what went wrong. FBrowser requires the single library "flib". Different programs may require different libraries. If Fargo is not present on your TI-92, pressing [Shift] [ON] will have no effect, and Fargo programs launched from TI-BASIC will do absolutely nothing. To load Fargo into your TI-92, follow the instructions in Section 1.3. ------------------------------------------------------------------------------ 1.5: Using FBrowser (a.k.a. the Fargo shell) ------------------------------------------------------------------------------ When you start the FBrowser, it displays a menu of the folders on your TI-92. There are two modes of operation; one is the folder view, which is the default upon startup, and the second is the program view. Use the following keys to navigate through FBrowser: [Left] - switch to folder view [Right] - switch to program view (enter folder) [Up] - move cursor up [Down] - move cursor down [2nd] [Up] - page up [2nd] [Down] - page down [ENTER] - execute program / enter folder [space] - toggle file list filtering [F1] - display "about" dialog box [EXIT] - quit If a program you attempt to execute fails, FBrowser will display an error dialog box describing the error. You may bypass the Fargo shell by launching programs directly from TI-BASIC. Note that when you have file list filtering turned off, file types are no longer meaningful; therefore, Fargo programs will not have their comments displayed, and will not execute when you press [ENTER]. ------------------------------------------------------------------------------ 1.6: Running old Fargo programs ------------------------------------------------------------------------------ Before Fargo II was released, many programs had been written for the original Fargo. Since Fargo II used a completely redesigned program format, and even ran programs in a different processor mode, compatibility with older programs was broken. It was expected that all of the existing programs would need to be converted and recompiled in order to run under Fargo II. But with the release of Fargo 0.2.2, this changed. With the addition of the Fargo 0.1.x compatibility module, legacy Fargo programs could now be run under the same environment as Fargo II programs. The compatibility module is optional; you must specifically choose to install it. To do this, simply follow the same installation procedure outlined in Section 1.3, but use "pfcompat" instead of "putfargo". For an automatic installation, use "afcompat" instead of "autofarg". In a manual installation, make sure you send the files in "asm\oldfargo" to your TI-92 after the backup has been sent. The Fargo 0.1.x library "romlib" is integrated with the compatibility module. It does not need to be present on your calculator. All other Fargo 0.1.x libs will need to be put into the folder "OLDFARGO" in order to be recognized. This insures that they will not be confused with Fargo II libraries, which go in the folder "MAIN". However, programs themselves can be put into any folder, regardless. Note that if your TI-92's ROM version is not 1.x, most Fargo 0.1.x programs will need to be modified somewhat in order to run properly. ------------------------------------------------------------------------------ 1.7: Troubleshooting ------------------------------------------------------------------------------ Everything in this section is documented in the "In Case of Difficulty" section of the TI-92 manual, on page 498; however, since so many people post on the mailing lists asking about this, I've decided to include it here. If your TI-92 locks up, try holding down [2nd] and [HAND] and pressing [ON]. If that does not reset it, try removing a battery, holding down [)] and [(-)], and inserting the battery while continuing to hold down the two keys until the calculator resets. ============================================================================== Part 2: Programming for Fargo ============================================================================== ------------------------------------------------------------------------------ 2.1: Introduction ------------------------------------------------------------------------------ Part 2 explains the fundamentals of creating Fargo II programs, including pointers to sources of information and a description of the high level source code format recognized by the Fargo development kit. Also described is the low level object code format recognized by Fargo itself, and generated when you compile a program. Fargo, along with the development kit included with it, automatically handles relocation, library linking, and many platform technicalities, such as support for multiple ROM versions. In order to use these features properly, Fargo requires that you follow a certain format in your source code files. This format is streamlined; the development kit takes care of the details of converting source code into object code that Fargo can recognize. There are several impediments to running assembly language programs on the TI-92. Fargo deals with all of these, leaving the programmer to concentrate on what is most important. Here are the three most predominant issues: - Different versions of the ROM are very much alike, but differ slightly in the offset of most calls. The Fargo kernel solves this by providing a TIOS "pseudolibrary" of ROM calls and RAM addresses. This pseudolibrary uses a table of addresses. This table is chosen from a master table of ROM versions at the time the Fargo kernel is inserted into a backup file. - The calculator dynamically rearranges its memory, so there is never a sure way to pinpoint the location of a program in order to access data and do JMPs and JSRs. The Fargo kernel does not face this problem, since it is in a fixed location (the top of RAM). For programs, which do move around, Fargo solves this problem by automatically relocating programs before they are executed. - There is very little RAM (about 69K on a 128K calc, or 196K on a 256K calc) to work with, so routines should be optimized to work under low memory conditions. In order to work with this difficulty, the Fargo kernel and program format have been designed to take as little space as possible while still being efficient and modular. ------------------------------------------------------------------------------ 2.2: Lists of helpful information ------------------------------------------------------------------------------ The text files included in the distribution contain information that may be useful for writing Fargo programs. These files are nowhere near complete, so I welcome corrections and additions. If you have any, please refer to section 3.2. The files in this package are not meant teach you from scratch how to program in 68000 assembler; for this, please consult other sources. The text files are as follows: Fargo.txt Main documentation (this file) Convert.txt Describes how to convert Fargo 0.1.x programs and libraries to Fargo II. LowLevel.txt Describes the TI-92's memory map, and lists all the known I/O ports along with descriptions. Traps.txt Describes the TI-92's usage of the exception vector table. Types.txt Describes some of the data types used by the TI-92. Handles.txt Explains how memory handles are used by the TI-92. RAM-1_x.txt Lists some RAM addresses (low memory globals) along with descriptions. Theses addresses are for ROM 1.x only. They must be converted to be used with Fargo II. ROM-2_1.txt Contains lots of information gleaned from studying ROM 2.1. For all the text files, the following conventions apply: All numbers are in hexadecimal, except for bit indices or numbers ending with the suffix (d). In certain places, the prefix '$' will be used to clarify that a number is in hex. B = byte ( 8 bit integer) W = word (16 bit integer) L = long (32 bit integer) Brackets [] designate pointer indirection. This may be followed by ".B", ".W", or ".L" to designate the size of the integer being pointed to. Remember that the 68000 processor uses "Big Endian" to store integers in memory; the most significant byte (MSB) is stored first, and the least significant byte (LSB) is stored last. For example, the number $1234 is stored as 12 34 in memory. ------------------------------------------------------------------------------ 2.3: Programming overview ------------------------------------------------------------------------------ Fargo executables (PRGM variables) consist of two classes: programs and libraries. Programs can be executed directly, and are displayed in the Fargo shell. Libraries provide commonly used routines to programs; these routines can be used by simply linking the library to the program. This is an alternative to copying the source for each routine into the source for the program that uses the routines. Fargo source code is contained in .ASM files. Compiling a program or library consists of two steps: 1) Assembling the ASM source file(s) using A68k 2.71.F1. 2) Using the Fargo Linker to link the object file(s) generated by A68k. This generates a single .92p file. It is recommended that you use a makefile for compiling your Fargo programs and libraries. The way A68k and flinker work together makes this work very well. All you have to do is type "make" and everything that has changed is recompiled. (And everything that hasn't changed isn't recompiled.) However, you do not *need* one to compile Fargo programs. The file FARGO.BAT is supplied for development under DOS without the use of a makefile. In the Linux development kit, a sample makefile is included instead. If you're using DOS, you're on your own if you want to try using a makefile. ------------------------------------------------------------------------------ 2.4: The Fargo source code format ------------------------------------------------------------------------------ This section describes how to create an .ASM file that will be assembled into an object file that the Fargo Linker can then link into a working Fargo .92p file. This section precisely describes how to create Fargo source code. It might also be hard to understand, especially for beginners. To see it in practical use, please examine the sample source code that is included with Fargo. +-----------+ | Libraries | +-----------+ To generate a library, you must export a symbol named "_library", and all the library functions, using the template "libname@XXXX" where "XXXX" is a hex number signifying the function index. The symbol "_library" must point to a null-terminated string specifying the library name. This is done like so: ... xdef _library xdef testlib@0000 xdef testlib@0001 xdef testlib@0002 ... xdef testlib@XXXX testlib@0000: ; exported library symbol number $0000 ... testlib@0001: ; exported library symbol number $0001 ... testlib@0002: ; exported library symbol number $0002 ... testlib@XXXX: ; exported library symbol number $XXXX ... _library dc.b "testlib",0 +----------+ | Programs | +----------+ To generate a program, you must export a symbol named "_main". This symbol should point to the program entry point. If you want to give the program a comment/description, you must also export a symbol named "_comment", which should point to a null-terminated string. This is done like so: ... xdef _main xdef _comment ; include this only if you define _comment ... _main: ; program entry point ... rts ; return from program ... _comment dc.b "Space Goobers version 19.8",0 ... +-----------------+ | Using Libraries | +-----------------+ Library symbols are accessed as "libname@XXXX". However, each library should have its own include file which makes the names much more friendly. For example, "kernel@0000" is aliased to "kernel::find_var" and "flib@000C" is aliased to "flib::random". NOTE: Although exported library symbols are usually functions, they are not required to be so. They may just as easily point to data. +-----------+ | Compiling | +-----------+ To compile a Fargo .ASM file into a .92p file under DOS: F:\FARGO>fargo Where is the name of the .ASM file, without the extension. Using the Linux development kit, you may manually do this: $ a68k .asm $ flinker -o .92p .o Or you may simply type "make" if you have already written a proper makefile. ------------------------------------------------------------------------------ 2.5: The Fargo object code format ------------------------------------------------------------------------------ The section has been temporarily removed. ============================================================================== Part 3: Other topics ============================================================================== ------------------------------------------------------------------------------ 3.1: Legal stuff ------------------------------------------------------------------------------ The distribution of Fargo is encouraged, as long as all the companion files are kept together, unmodified from the form in which they were originally released. I take no liability for any damage caused directly or indirectly by using Fargo or any of its companion files. Keep in mind, though, that it is extremely unlikely (if not impossible) for your calculator to be damaged by software. You may NOT put Fargo up on any WWW site, FTP site, BBS, or any other form of mass distribution, without my agreement. This is NOT to stop the distribution of Fargo. It is to allow me to keep track of all the distribution sites out there, so I can make sure a bug-fix or upgrade is always available. See section 3.2 below. ------------------------------------------------------------------------------ 3.2: Contacting me ------------------------------------------------------------------------------ If you have a question that is about something very basic, that you think a normal user could handle, please use one of the mailing lists or newsgroups. See http://www.ticalc.org for FAQs and information on TI calculator mailing lists and newsgroups. However, if you have a comment, suggestion, bug report, or something advanced that would only be appropriately asked of the developer of Fargo, please contact me. I will try to respond to all mail sent to me that warrants a response, but please don't be disappointed if I don't -- I get a lot of mail; sometimes I don't answer all of it. You may email me at or . I also have an account on ICQ; my ID is 2300673. NOTE: The Fargo development team used to include two other people, Rob Taylor and Dan Eble. However, I (David Ellsworth) am currently the only one developing it. So please don't try to contact them about Fargo. ------------------------------------------------------------------------------ 3.3: New versions and information ------------------------------------------------------------------------------ New versions will always be available at http://www.ticalc.org. Updates will be announced on the "assembly-92" and "Calc-TI" mailing lists. The Calc-TI list echoes to the newsgroup "bit.listserv.calc-ti". You can download the latest version from: WEB: http://www.ticalc.org/pub/92/asm/shells FTP: ftp.ticalc.org in /pub/92/asm/shells However, the precise directory is subject to change. If you do not find it in one of the above locations, simply start from the top: WEB: http://www.ticalc.org FTP: ftp.ticalc.org in /pub ------------------------------------------------------------------------------ 3.4: Revision history ------------------------------------------------------------------------------ yyyy.mm.dd ---------- 1996.11.10: Fargo v1.0b12 First public release. This release was unofficial; in fact, it was leaked to the public by a beta tester. (It was leaked by the very first beta tester of Fargo. Rather ironic, isn't it?) 1996.12.09: Fargo v1.0b12 - fixed version of CORE.O * Fixed a single-instruction bug which caused programs and libraries to improperly unrelocate when required libraries were not found, resulting in a crash upon execution once all the required libraries were present. 1997.01.02: Fargo v0.1.13 First official public release. * Radically altered the directory organization scheme. It is now possible to compile a Fargo program in any directory. * Streamlined the Fargo distribution. Now only the necessary files, and some small sample programs, are included. * Ported the Fargo file manipulation programs (SUM92, PRGM92, ML92B) to C++ for greater portability. * Gave FLink a rudimentary scripting ability; created a new batch file called AUTOFARG.BAT that automates the task of receiving a backup, putting Fargo into it, and sending it back. * Changed the name of the Fargo shell to "FBrowser" to eliminate confusion between the shell and the core; they now have separate version numbering. * Modified FBrowser to allow folders other than MAIN to be browsed. This does not change the fact that the shell must be in the MAIN folder, though. * Changed the version numbering scheme. This release included the following utility versions: FBrowser v0.2.0 FLink v0.1.5 ML92B v1.0 PRGM92 v1.0 1997.02.26: Fargo v0.1.13 - masked ROM patch * Released patched versions of CORE.O and ROMLIB.92P that allowed Fargo to work on TI-92's with masked (internal) ROM. At the time, ROM 1.11 was the only ROM version being manufactured in masked format, so this patch was released as FIX111.ZIP. 1997.11.01: Fargo v0.1.14 * Fargo now works on any ROM 1.x TI-92 regardless of how much RAM it has. It will *not*, however, work under ROM 2.1. For that you will still need to wait for Fargo II. NOTE: Fargo programs that hook interrupts using the same method that Fargo 0.1.13 used will still need to be modified to work with 256K of RAM. * flib[idle_loop] now properly looks up the APD value. * Switched over to using DJGPP for all the DOS utilities. * ML92B v1.1.0: Can now patch backups using either of two methods, one which generates large backups (107K or 235K), and one which does not increase the size of a backup at all. * TRIM92B v1.0.0: New program. Trims a 92B backup file to its natural size. Can be used to "uninstall" Fargo from a backup if the wraparound method was used to install it. * PRGM92 v1.0.1: See below. * SUM92: Although all the Fargo utility programs now automatically fix the checksums of files generated or modified, this program is still included. You may use it to fix the checksum on any TI-92 Graph Link file. * FLink v0.1.6: The parallel port is now changable. Sound emulation has been added. Note that when Linux FLink is ported to DOS, this version of DOS FLink will become obsolete, which is why I haven't changed it much. 1997.11.02: Fargo v0.1.15 * Fixed some bugs in the 0.1.14 distribution. (I probably should have called this version 0.1.14.1.) 1998.01.09: Fargo v0.2.0.1 First alpha release of Fargo II. * ROM 2.1 support, plus a system that makes it easy for me to add support for any new ROM version that may come out (i.e., the TI-92 Plus module) I also added ROM 1.0b1 support. Not that anyone still has that ROM version. But, I thought I might as well. * The Linux development kit is now distributed. So is the DOS kit, of course. But Linux has been my primary (and only) Fargo development platform for quite some time. It is quite possible that you will find bugs in the DOS development utilities, since I have not tested them much. (This applied to Fargo 0.1.14 as well, though I didn't mention it.) * A true linker, replacing PRGM92. The Fargo Linker is called flinker for short, and can link multiple A68k-generated object files into one .92p file. It also replaces ML92B, as it can read the kernel object file and insert it into a backup file. It no longer supports the obsolete wraparound installation method. * Modified A68k 2.71 to work better with Fargo source code. I changed the version number to 2.71.F1. The "F1" stands for Fargo patch #1. * Because a linker is now used, libraries are accessed simply by including a header file and accessing the library functions by name. The way libraries are written is also different now. I also took the liberty of changing the library symbol convention from "libname@funcname" to "libname::funcname". See the included sample source files to see exactly how things have changed. * Another feature that the new linker allows is the use of one or more bss sections, which the kernel now supports. A bss section is a dynamically allocated, uninitialized block of memory that a program can use to store temporary variables. I use the word "temporary" because the bss block is freed when the program exits. * What used to be "romlib" is now integrated with the kernel. The kernel exports two pseudolibraries: "tios" and "kernel". "tios" contains both ROM and RAM addresses. I've added a fair number of new ROM calls. Where possible, I've used the genuine TI names for ROM symbols. * ROM addresses are now looked up from a table rather than looked up dynamically. It is now necessary for me to specifically add an entry in my table for each ROM version. So far, I've implemented tables for 1.0b1, 1.2, 1.3, 1.4, 1.7, 1.8, 1.10, 1.11, 1.12, and 2.1. The table lookup is done by flinker when it inserts the kernel into a backup file, so there is no overhead involved; the kernel itself never has to do any ROM version checking. * A totally new program/library file format that takes advantage of the new features provided by using a linker. This format contains both a type and a subtype. This type may be used to associate different file types with specific applications, allowing the application to use the subtype any way it pleases. * Fargo programs now run in User mode rather than Supervisor mode. This should have been done from the very start, but wasn't because Fargo beta was leaked before I finalized things. Therefore I felt obliged to keep backwards compatibility with it in later versions. Since Fargo II is completely new, I took the opportunity to finally switch to User mode. Programmers: you will need to get rid of all STOP and MOVE xx,SR instructions (unless they are used in trap handlers). MOVE xx,SR can be replaced with a MOVE xx,D0 / TRAP #1 sequence. * The TI-BASIC fork in a Fargo module now contains "Prgm:EndPrgm" rather than "Prgm:Pause:EndPrgm". The kernel hooks to intercept calls to programs from TI-BASIC are now much faster and cleaner. The same applies to the Shift-ON hook. Also, the kernel now displays a message on the status line rather than flashing the screen when an error is encountered. * The 4-shade and 7-shade grayscale libraries, and FTerm 1.0b7, have been packaged with Fargo. These were not included with Fargo 0.1.x. * Since this is an alpha release, nothing is absolutely guaranteed to stay the same in later releases. Although I can state with fair certainty that backwards binary compatibility will be maintained, even that is not an absolute certainty. * Note that, although the codename for this project is "Fargo II", it is still called Fargo. 1998.01.10: Fargo v0.2.0.2 * Fixed an odd checksum bug that occurred in the DOS version of flinker when patching a backup file (putfargo calls flinker). The same bug was also in sum92, which has been fixed as well. * Fixed an incompatibility bug in flinker that made it screw up when trying to patch certain backups * Improved flinker's name-guessing algorithm (which it uses on a program if you leave out the `-n' option). It now skips over directory names. * Added bin/fargo and bin/autofarg scripts and a sample Makefile to the Linux distribution * Removed trim92b from the distribution * Fixed a typo in flib.asm. In zap_screen, it had "d0-d7/a0-d6" instead of "d0-d7/a0-a6". * Made Linux FLink's put92 and get92b check if the calculator is ready before starting the transmission, and wait 5 seconds before giving up. Made get92b return an exit value of 2 if the user chose not to overwrite the file. Fixed a bug in get92 that was storing the wrong file size in the header (the value it should have been plus 6). Incremented Linux FLink's version to 1.2.1. * Decreased the value of TIMAXTIME in tidev's ti.c. Change this if it doesn't seem to work right for you. * Documented the [space] key feature of FBrowser 0.3.0. * Added a "known bugs" section to the documentation. * Slightly modified the list of planned features. 1998.01.10: Fargo v0.2.0.3 * Fixed a bug in the ROM 1.2 entry of the tios table (HeapFreeIndir was incorrect) 1998.01.13: Fargo v0.2.1 * Changed the executable file format. It now uses compressed relocation, bss, and import tables. Large programs will now be in fact smaller than they were in Fargo 0.1.x. Flinker can still generate files with the old format, mainly so you can see how much smaller they are with the new one. Note that the compressed tables take slightly longer to process, but I think it is worth it. * Restructured flinker to be cleaner and more modular. (The changes are pretty much invisible to the user, though.) Also added rudimentary support for recognizing XRef operand sizes. * Optimized the kernel. It is now a lot smaller. * Added an optional compatibility module. You may link this in with the kernel to make it compatible with Fargo II programs and libraries that were released before Fargo 0.2.1. If you don't link it in, the kernel will be smaller. Patching a backup with the compatibility module enabled is automated by "pfcompat" in DOS and "putfargo-compat" in Linux. Once you're sure you won't need to execute pre-0.2.1 executables anymore, you can go back to using "putfargo". * Fixed a bug in FBrowser where, if there were multiple files at the end of a list starting with the same letter, you couldn't cycle through them in a loop by pressing that letter repeatedly. Incremented its version number to 0.3.0.1. 1998.01.13: Fargo v0.2.2 * Added a Fargo 0.1.x compatibility module. It is named "compat1x.o". When executing Fargo 0.1.x programs, their required libraries must be in the folder "oldfargo". Note that Fargo 0.1.x programs still do *not* work on ROM 2.1; they still have all the limitations that "romlib" imposes. You may install this into a backup by using "putfargo-compat1x" in Linux or "pfcmpt1x" in DOS. If you want to combine both 0.1.x *and* pre-0.2.1 compatibility, you will need to run flinker manually. * Fixed a bug in FBrowser where, if you tried to enter a folder other than the first one listed, that had no Fargo programs in it, the cursor would get messed up when the error dialog box popped up. Incremented its version number to 0.3.0.2. 1998.01.14: Fargo v0.2.3 * Optimized the kernel compatibility modules. The pre-0.2.1 module is now much smaller. * Fixed an error in the shell script "fargo" in the Linux toolkit; it had the extra parameter `-p'. * Fixed a bug in flinker where it would sometimes return a garbage exit code even when there wasn't an error. * Improved flinker's recognition of operand sizes. * Improved the error reporting in flinker. It now shows both the section name and offset for each error encountered, where applicable. * Renamed "ROM_origin" to "ROM_base" in tios.h. 1998.01.16: Fargo v0.2.4 * Made some changes to various documentation files. * Added a "Troubleshooting" section to Fargo.txt. * Fixed a bug in the ROM 2.1 entry of the tios table (WinOpen was incorrect) * Added a new ROM call. I call it "vcbprintf", and it is a virtual callback printf function. This means you can do printf with any custom putchar routine, rather than having to use sprintf to print into a buffer. * Modified FBrowser to display comments and allow program execution even in no-filter mode. Incremented its version to 0.3.1. * Made flinker report the size of the kernel when installing it in a backup file, and the size of a variable when creating a 92p file. * Added a second level of verbosity to flinker. * Removed the '-C' compatibility option from flinker. It now only generates Fargo programs for the current version of Fargo. * Switched to a new directory scheme. There is now an "asm" directory under the Fargo root, and there are four subdirectories under it: "include", "kernel", "lib", and "prgm". All include files, including the ones for libraries, go in "include". Yes, I think this makes more sense than putting them in "lib". 1998.01.22: Fargo v0.2.5 * Fixed a bug in the Fargo 0.1.x compatibility module where modules that used the 0.1.x kernel pseudolibrary would not properly unrelocate; therefore they would crash upon being run a second time. * Fixed a bug that caused Fargo II programs to load whether or not their required libraries were found, often causing crashes. * Fixed a bug that caused LCD_MEM not to be saved and restored after a module failed to load. * Took the Fargo 0.2.0.x compatibility module out of the distribution. If anyone wants it back, please contact me. * Reworked the Fargo 0.1.x compatibility module so that it now has romlib integrated with itself. If romlib is present in the "oldfargo" folder, it will be ignored. Also removed the checking that caused the Fargo 0.1.x compatibility module to refuse to work on incompatible ROMs. WARNING: If you install the Fargo 0.1.x compatibility module on a TI-92 with a ROM version (such as 2.1) that was incompatible with Fargo 0.1.x, all the Fargo 0.1.x programs you run will have to have been specially patched to work with your ROM! Otherwise your calc will most likely crash. * Fixed the sprite test program so that the sprite is visible everywhere on the screen, without the compromise of flicker. * Added strlen(), strncmp(), strncpy(), strcat(), and strchr() to the tios pseudolibrary. Added ROM 1.5 support. * Did another major overhaul of flinker. It now handles operand sizes and error reporting even better (and more cleanly). * Made some more modifications to A68k. It now properly differentiates between PC-relative and absolute references to external symbols. Incremented its version to 2.71.F2. 1998.02.07: Fargo v0.2.6 * Added support for Fargo programs that interface with TI-BASIC. These can be either functions or programs. Functions return a value on the estack. Both functions and programs can take parameters. * Added a sample Fargo/TI-BASIC function to the distribution. It is called "testfunc", and takes a string as a parameter, returning the same string doubled, with an "=" in between the two copies of the string. * Fixed the ROM dumping programs so that they always dump memory in the correct range. * Fixed a bug in "ticat", the tidev-compatible version of "cat", where it was buffering outputted characters instead of outputting them immediately. One of the effects of this was that ROM dumps made using "ticat" would not be complete. * Fixed some bugs in FTerm. Now Diamond--. correctly outputs an ASCII character, and the cursor keys echo themselves if local echo is enabled. Changed FTerm's version number to 1.0.8. * Put the 0.2.0.x compatibility module back in the distribution. It wasn't requested, but I thought I might as well. If you want to use it, though, you'll have to run flinker manually. * Moved the tios tables to a kernel sourcefile, where they belong. Modified flinker to look for the appropriate tios table in the linked kernel object files, since the tables are no longer hardwired into flinker itself. * Improved the tios naming convention a bit. "main_lcd" has been renamed to "globals", and "kb_vars" has been renamed to "kb_globals". Both of the old names are still provided as aliases in tios.h. * Renamed the tios function ST_redraw to ST_eraseHelp, which is its real name; renamed ST_message to ST_showHelp, since it is the complement of ST_eraseHelp. ST_eraseHelp can be used to update the status line if you set the flag specifying that a help message is being displayed. * Added some functions to the tios pseudolibrary. Misc: push_quantum(), check_estack_size(), OSAlexOut(), ERD_dialog() C functions: memset(), memcmp(), memcpy(), memmove(), abs(), labs() Integer math: _du32u32(), _ds32s32(), _ds16u16(), _ru32u32(), _rs32s32(), _ru16u16(), _rs16u16() * Made many revisions to ROM-2_1.txt and a small revision to RAM-1_x.txt. 1998.04.09: Fargo v0.2.7 * Fixed a bug in the Linux distribution: autofarg was missing. * Fixed a bug in gray7lib. It was doing "add #4,sp" after pushing a word. * Removed the note from tidev's readme saying that the "$4" serial link code was untested. It has been tested and it works. * Made some optimizations to FTerm; it should be faster now. Incremented the version number to FTerm 1.0.9. * Added a function to the tios pseudolibrary: DerefSym() * Added support for an alternate version of ROM 1.10, which is dated 03/26/96 instead of 03/20/96. * Added a section to the documenation: "Running old Fargo programs". This describes how to install Fargo onto your calc in a configuration that will allow Fargo 0.1.x programs to be run. To further facilitate this, I've added an "afcompat" script, and an "asm/oldfargo" directory with three Fargo 0.1.x libraries in it: flib, graylib, and graylib7. 1998.04.09: Fargo v0.2.7.1 * Fixed some errors which made it into the distribution: - The "preinstalled backups" uploaded to ticalc.org did not in fact have Fargo installed in them; they were just clean backups. - FTerm, and possibly other .92P files, were not properly recompiled. - There was a small spelling mistake in the description for hexdump. ------------------------------------------------------------------------------ 3.5: Known bugs ------------------------------------------------------------------------------ The following is a list of bugs in Fargo that have been reported to me and may have not been fixed yet. * The Fargo ROM dumping programs sometimes insert an extraneous bit at the beginning of the transfer, causing the whole transfer to be shifted by one bit. This seems to happen only with homemade links, and only under certain environments (on the PC end). * The DOS version of flinker sometimes crashes, and/or generates corrupt output files. ------------------------------------------------------------------------------ 3.6: Planned features ------------------------------------------------------------------------------ The following features are planned for future releases of Fargo II. Once I'm satisfied with the feature list, it will go into the beta stage. Currently it is still in the alpha stage. Alpha releases will be numbered 0.2.x, 0.3.x, 0.4.x, etc.; beta releases will start with 1.0.0 and go up from there. I will not be so bold as to speculate about a "final" release. I would prefer to keep Fargo in beta indefinately. * TI-92 Plus and TI-89 support. Of course this will have to wait until the actual products are released by TI. ;-) * Static memory copying (TSR support and general heap reallocation support), overlays, and module decompression * Many more ROM calls, and documentation for more of the calls. * A bitplane graphics library. This library will provide calls to allocate and deallocate virtual screens (which will consist of 1, 2 or 3 bitplanes) and to switch between screens. It will automatically do page flipping to simulate grayscale. The LCD RAM at $4440 (or $4720 in ROM 2.1) will no longer be used by Fargo directly; programs will be required to allocate their own screens. This will not require any more memory than is used already, because earlier versions of Fargo save the TIOS screen in a temporary 3840 byte buffer and later restore it. It will also be possible to mark screens as overwritable, so that nested program calls won't waste memory allocating extra screens. * A graphics library with integrated bitplane support, so you will be able to (for example) paste a non-aligned sprite, or draw a line in any shade of gray. The library calls will of course also work for black and white (one bitplane). Grayscale will no longer need to be treated as a special case. * Toolkit ports to additional platforms. * A DOS port of Linux FLink. * I may write a utility that will load multiple files into a backup file, so that you won't have to send them separately. This may or may not be integrated with flinker. * I may write a Fargo program that will allow you to send the Fargo kernel to another TI-92 with a different ROM version. * FBrowser will support plugins, filtering by file type, and multiple views (such as icons, comments only, file stats, etc.). It will also allow itself to be called from another Fargo program (as a library) with the option of a callback filter. * I am considering releasing the kernel, shell, and development kit source code.