________ /\ _____\ \ \ \____/ __ __ __ __ __ \ \ ___\ /'__`\ /\ `__\ /'__`\ /'__`\ \ \ \__//\ \_\ \\ \ \ /\ \_\ \ /\ \_\ \ \ \_\ \ \___/_\\ \_\ \ \____ \\ \____/ \/_/ \/___/_/ \/_/ \/____\ \\/___/ /\____/ \/___/ Version 0.1.13 Copyright (C) 1996 David Ellsworth Rob Taylor Dan Eble All rights reserved. ============================================================================== TABLE OF CONTENTS ============================================================================== PART 1: FOR USERS ------------------- 1.1: INTRODUCTION 1.2: REQUIREMENTS 1.3: INSTALLING FARGO 1.4: INSTALLING FARGO WITHOUT FLINK 1.5: RUNNING FARGO PROGRAMS 1.6: USING FBROWSER PART 2: FOR PROGRAMMERS ------------------------- 2.1: DIFFICULTIES OF PROGRAMMING THE TI-92 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 DEVELOPERS 3.3: NEW VERSIONS AND INFORMATION 3.4: REVISION HISTORY ============================================================================== PART 1: FOR USERS ============================================================================== ------------------------------------------------------------------------------ 1.1: INTRODUCTION ------------------------------------------------------------------------------ Fargo is a program for the TI-92 graphing calculator that enables execution of 68000 machine language programs. These programs are stored on your calculator as PRGM variables. Fargo consists of four basic components: 1) the core 2) the shell (FBrowser) 3) ROMlib 4) Flib The core contains low level bootstrap routines that are used to load and run Fargo programs. The shell provides an simple and organized way to list and execute Fargo programs stored in the calculator's memory. ROMlib allows Fargo programs to use the TI-92's built-in ROM routines while maintaining compatibility across all ROM versions. Flib (Fargolib) is a library that contains routines useful for writing Fargo programs, but not included in the TI-92's ROM. ------------------------------------------------------------------------------ 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). This version of Fargo works on all known ROM versions starting from 1.2, and is designed to be compatible with future revisions. However, if you have a TI-92 with a ROM version later than 1.12, please contact us. TI may make drastic changes in the TI-92's ROM that will prevent the current version of Fargo from working; in that case we will work on releasing a new version of Fargo that will support the new ROM version. If you attempt to run Fargo on a TI-92 with a ROM version higher than 1.12, you do so at your own risk. Make sure you have everything on your calculator backed up. To find out what ROM version your TI-92 has, press [Diamond] [(] from the home screen. Then press [2nd] [QUIT] to go back. ------------------------------------------------------------------------------ 1.3: INSTALLING FARGO ------------------------------------------------------------------------------ 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 C:\FARGO. Next, make sure you set the environment variable FARGO to C:\FARGO and make sure C:\FARGO\BIN is in your path. To make this permanent, add the following lines to your AUTOEXEC.BAT: SET FARGO=C:\FARGO SET PATH=%PATH%;%FARGO%\BIN If you have a homemade parallel link cable, you may install Fargo with this command: AUTOFARG Otherwise, move on to section 1.4. ------------------------------------------------------------------------------ 1.4: INSTALLING FARGO WITHOUT FLINK ------------------------------------------------------------------------------ First, make sure you have read and followed section 1.3. Transfer a backup from your TI-92 to C:\FARGO. You can give the backup any name you want. From the DOS command line, execute the following command: C:\FARGO>putfargo where is the name of the backup file you made, without the extension .92B. This will put the Fargo core into the backup file. Now you can transfer this backup file back to your TI-92; it will time out at 99%. Don't worry, this is supposed to happen. There is now one step remaining: transfer all the .92P files from C:\FARGO to your TI-92. You now have Fargo on your calculator. The following .92P files are required to run FBrowser: LIB\ROMLIB.92P ROMlib. Provides a library interface to the ROM routines. LIB\FLIB.92P Fargolib. Contains useful routines not found in ROM. PROG\SHELL.92P FBrowser; the listing of programs you see by default when you press [Shift] [ON]. The remaining .92P files are sample Fargo programs. In this release the number of included sample programs and libraries have been minimized, due to the fact that they are in a state of flux. ------------------------------------------------------------------------------ 1.5: RUNNING FARGO PROGRAMS ------------------------------------------------------------------------------ To launch the Fargo shell, use the hotkey [Shift] [ON]. This works from anywhere, provided that your TI-92 is idle; at any given time, you can start Fargo with this hotkey if and only if you can turn your calculator off using [Diamond] [ON]. If this condition is not met 1/4 second after the hotkey is pressed, it will be ignored. You may also start Fargo programs in the same way that TI-BASIC programs are called. For example, to directly start FTris, you would enter "ftris()" from the home screen. Using this method bypasses the Fargo shell. 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 a program has been directly launched, and for some reason is cannot be executed, the screen will flash to signal the error. (This also happens when you try to execute a library.) The usual cause for this is a missing or invalid library required by the program you launched. The Fargo shell requires the libraries "romlib" and "flib" to run. Different programs may require different libraries. Also, a certain minimum amount of memory (approximately 4K) is required to run any Fargo program. If the Fargo core is not present on your TI-92, pressing [Shift] [ON] will have no effect. When Fargo programs are launched from TI-BASIC, they will simply pause the calculator and wait for [ENTER] to be pressed. To put the Fargo core on your TI-92, follow the instructions in Section 1.3. ------------------------------------------------------------------------------ 1.6: 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 [F1] - display "about" dialog box [EXIT] - quit If a program requires libraries that are not present, when you attempt to execute it, FBrowser will display an error dialog box. You may bypass the Fargo shell by launching programs directly from TI-BASIC. ============================================================================== PART 2: FOR PROGRAMMERS ============================================================================== ------------------------------------------------------------------------------ 2.1: DIFFICULTIES OF PROGRAMMING THE TI-92 ------------------------------------------------------------------------------ - There is no built-in hook in the TI-92's ROM to execute machine language; e.g., you cannot run machine language from the Custom menu like the TI-85 can. To see how Fargo circumvents this obstacle, read BACKUPS.TXT. - Different versions of the ROM are very much alike, but differ slightly in the offset of most calls. Take a look at ROMLIB.ASM to see how Fargo solves this problem. - 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 core 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 (this task is done by the Fargo core). - There is very little RAM (about 70 kb) to work with, so routines should be optimized to work even under low memory conditions. ------------------------------------------------------------------------------ 2.2: LISTS OF HELPFUL INFORMATION ------------------------------------------------------------------------------ All of the .TXT files included in the distribution contain useful and necessary information for writing good Fargo programs. These files are nowhere near complete, so we welcome corrections and additions. Please send these to . 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: BACKUPS.TXT Describes the .92B format, and explains the method Fargo uses to load the bootrap machine language code. FARGO.TXT Main documentation (this file) HANDLES.TXT Explains how memory handles are used by the TI-92. PORTS.TXT Explains how to access I/O ports on the TI-92. RAM.TXT Describes the TI-92's memory map, and lists some RAM addresses 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. For all the .TXT 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 modules (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. Since so much is involved in compiling a Fargo program with the correct format, this is automated by a set of macro and include files: @LIBRARY The standard macro file for Fargo libraries. @PROGRAM The standard macro file for Fargo programs. FARGO.INC Contains macros for constructing a Fargo header, including relocation and library linking info. LIBS.INC Contains macros for constructing libraries. Also contains the current Fargo header version. TI-92.INC Contains useful equates and macros specific to the TI-92, but not specific to Fargo. The information here is duplicated from some of the .TXT files. ------------------------------------------------------------------------------ 2.4: THE FARGO SOURCE CODE FORMAT ------------------------------------------------------------------------------ This section describes how to create an .ASM file that will compile to a Fargo .92P module in the correct format. The Fargo package uses a program called "A68K" to assemble source code; this program has many advanced features, including macros and include files. These features are used to their full potential in constructing Fargo source code. This section precisely describes how to create Fargo source code. To see this in practical use, please examine ROMLIB and the sample source code included with Fargo. The first source code line is the most important. For programs, it must be this: @program prog_code,prog_name and for libraries, this: @library For programs, both "prog_code" and "prog_name" are labels that must be found later in the program source code. The "prog_code" label marks the entry point of the program; it must exit with an RTS instruction. The "prog_name" label marks a null-terminated string containing the program comment, which is displayed in the Fargo shell menu. The names of both of these labels may be changed, as long they are changed in both places. For libraries, contains the name of the library; this must be the same as the file name. All libraries must have an accompanying .SYM file. This is a text file containing prototypes of all the public routines in a library. Each line in the .SYM file must begin with "\1," followed by the name of a routine. All the library routines must be enumerated in this way. You can also include comments in a .SYM file, useful for documenting routine parameters and return values. In the main .ASM source for a library, each routine must begin with: label this is all you need to do to write a library. It is recommended that you describe all your library's public functions in a separate file called .FN. This convention is followed by all the libraries included in the Fargo package. At the end of any Fargo module (either a program or a library), you must include the following lines: reloc_open reloc_close In between these two lines, you may link libraries to the module using this construction: add_library A68K also requires that you end a program with the directive "end", so the final line must always be this: end Libraries may be linked to other libraries. In a Fargo module, use the following construction to call a external library routine: jsr library_name[routine_name] A library may call its own internal routines without linking to itself. To do this, simply call the routine as you would any other internal routine: bsr routine_name There is one special library that is not stored as a program variable on your calculator. This is the Fargo core library, which is always linked with all Fargo modules. To see details on the routines in this library, read CORE.FN. To compile a Fargo .ASM file into a .92P file, execute this DOS command: C:\FARGO>fargo Where is the name of the .ASM file, without the extension. This will also create a file called LIST.TXT that you can use to debug source code. ------------------------------------------------------------------------------ 2.5: THE FARGO OBJECT CODE FORMAT ------------------------------------------------------------------------------ This section describes the header format for compiled Fargo modules. You do not need to know or understand this format to write Fargo modules, since it is created automatically by include files. It is listed here purely for reference. Note: A relative pointer is 2 bytes and is relative from the beginning of a Fargo module. A relative pointer of $0000 would point to the Fargo signature. Rel. Offset Description ------ ----------- 00 Fargo Signature ($0050='P'rogram, $004C='L'ibrary) 02 Version (Current=$3130='10') This version number will only be changed if the header format is changed, and in that case it will be changed to match the current version of Fargo. Fargo checks this version against its internal header version number. A program with the wrong version number will not be listed in the main menu. Linked libraries with the incorrect version will cause a relocation error. Also, if you mix and match a Fargo backup and a Fargo .92P file with different header versions, pressing Shift-ON will have no effect. 04 Relocation table (relative pointer) This points to a table of words, each of which is a relative pointer that table points to an absolute pointer in the program that needs to be relocated. The table is terminated by a zero. 06 Library linking table #1 (relative pointer) This points to a word indicating the number of libraries linked to a program when it is relocated. Following that word is a list of the variable names of each library. Each name is null-terminated (unless it has a length of 8 characters), then followed by the next library in the list, until all of them have been enumerated. 08 Library linking table #2 (relative pointer) This must point to an uninitialized array of absolute pointers, one for each library being linked to the program. These are used for storing the beginning address of each library during the relocation and unrelocation process. 0A Relocation (usage) count This is initialized to zero in a compiled Fargo program. When it is relocated, the value is incremented; when it is unrelocated, the value is decremented. If a program has already been relocated, and is relocated again, this count while be nonzero, and the relocation routine will do nothing. (Relocating a program twice would crash the TI-92.) The same applies for unrelocation; if unrelocating a program does not reduce the count to zero, it does not actually do any unrelocation. The count is primarily useful for libraries, if a program links to libraries that, in turn, link to each other. 0C Programs only: Program comment (relative pointer) This points to the zero-terminated string that will be displayed next to the program's variable name in the main Fargo menu. To prevent a Fargo module from being listed in the Fargo menu, make this field zero (the Fargo shell does this to prevent from being listed in itself, since it is not reentrant). 0C Libraries only: Library name This points to the zero-terminated string that is checked against the variable name of a library when it is linked to a program during the relocation process. This insures that simply renaming one library to another will not cause a crash. 0E Public Routine Table This table is inside the header itself; it is not a pointer to a table. It consists of relative pointers to the public routines in a Fargo module. This table comes at the end of the header because it can have a variable size, depending on how many public routines are in the module. The first routine has an ID of zero. Each routine pointed to must be preceded by a word specifying that routine's ID; this is used in the unrelocation process. In a program, there is only one public routine: the program entry point, which has an ID of zero. In a library, there can be any number of public routines. ============================================================================== PART 3: OTHER TOPICS ============================================================================== ------------------------------------------------------------------------------ 3.1: LEGAL STUFF ------------------------------------------------------------------------------ Fargo and all the companion files are our work. We encourage their distribution as long as they are kept together, unmodified from the form in which we originally distributed them. We take no liability for any damage caused directly or indirectly by running Fargo on your TI-92. 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-page, FTP-site or BBS without agreement with the developers. This is NOT to stop the distribution of Fargo. It is to allow us to keep track of the distribution sites out there, so we can make sure a bug-fix or upgrade is always available. Just mail the Fargo development team for an arrangement. ------------------------------------------------------------------------------ 3.2: CONTACTING THE DEVELOPERS ------------------------------------------------------------------------------ First of all - don't hesitate to contact us. If you have a question that is about something very basic, that you think a normal user could handle, use one of the mailing lists or newsgroups. However, if you have a comment or suggestion or something more advanced, please contact us. We will try to respond to all mail sent to us. If you want to contact the developers directly, please send email to . This is an alias for the three members of the Fargo development team, whose individual email addresses are listed at the beginning of this document. NOTE: fargo@ticalc.org is currently not forwarding messages to us. ------------------------------------------------------------------------------ 3.3: NEW VERSIONS AND INFORMATION ------------------------------------------------------------------------------ New versions will always be available at http://ticalc.org. Updates will be announced on list-fargo and on the newsgroup bit.listserv.calc-ti, which echos to the Calc-TI mailing list. ------------------------------------------------------------------------------ 3.4: REVISION HISTORY ------------------------------------------------------------------------------ yyyy.mm.dd ---------- 1996.11.10: Fargo v1.0 beta 12 First public release (unofficial) 1997.01.01: Fargo v0.1.13 / FBrowser v0.2.0 / FLink v0.1.5 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. :)