The <flash.h> header file
This header file contains the following functions:
EM_abandon EM_findEmptySlot EM_GC
EM_survey EM_write FL_addCert
FL_download FL_getCert FL_getHardwareParmBlock
FL_getVerNum FL_write
and the following predefined types:
Bool HANDLE NULL
size_t
NOTE: Functions EM_blockErase, EM_blockVerifyErase,
EM_delete, EM_writeToExtMem, EM_open and
EM_put which were present in the AMS 1.xx TIOS jump table, don't more exist
in AMS 2.xx TIOS jump table. This is a pity, some of them were useful (especially last three of them).
In addition to functions defined here, yet three functions which works with archive memory are defined
in vat.h header
file: EM_moveSymFromExtMem,
EM_moveSymToExtMem and
EM_twinSymFromExtMem. Maybe these functions are the
most useful functions for working with the archive memory. They are defined in
vat.h because they are related to other functions and data structures
defined in this header file.
Functions
Adds a certificate.
FL_addCert adds size bytes long certificate pointed to by src to the
Flash ROM (see cert.h for more info). Returns certificate error
code (I don't know too much about its meaning). It is unlikely that this routine may
be efficiently used without the cooperation with TI.
Installs the product code.
FL_download installs the product code (there is no exit from this routine). It calls
startup base code, reinstates vector table then enters a receiving loop. It seems
that parameter dummy is ignored.
void FL_getCert (HANDLE *hDest, unsigned long *len, short decrypt);
Gets a certificate.
FL_getCert allocates a space in the RAM and stores in it all relevant information which can
be collected from the certificate area of Flash ROM (which is read-protected). It stores a handle of allocated
space to a variable pointed to by hDest, and stores the length of it in the
variable pointed to by len. decrypt is a Boolean parameter, which
determines whether the crypted part of the certificate will be stored or not (it will be decrypted
before storing, so crypted parts of the certificate are always invisible).
See cert.h header file for more info.
Gets a hardware parameters block.
FL_getHardwareParmBlock returns the address of the hardware parameters block from boot
code if found, else returns address of the default parameters block. The first word
of this block is a size of the block in bytes (20 on HW1 calculators, 42 on HW2
calculators so far). Then, a sequence of long words follows: so far, this sequence is
{3, 0, 1, 1, 0} on HW1 and {3, 1, 1, 1, 0, 2, 240, 128, 160, 100} on HW2 (these data are
for TI-89; replace 3 with 1, 160 with 240 and 100 with 128 on TI-92 Plus). The exact
meaning of this longwords is (respectively): hardware ID number (3 for TI-89, 1 for TI-92 Plus),
hardware revision number, boot code version number, boot code revision number, boot code
built number, hardware gate array version (HW1 or HW2), display width, display height,
visible display width and visible display width. So, if the length of the parameter block is
greater than 20, then the longword at offset 22 contains a hardware version number
(HW1 or HW2). Else, the calculator is surely a HW1 calculator.
NOTE: Julien Muchembled points to me that this function does not exist on oldest versions
of AMS 1.00 on TI-92 Plus calculators, so in the most general detection programs it should
be avoided. If you need this function only for testing a hardware version number, it is
more robust to use the following routine:
unsigned long GetHardwareVersion ()
{
unsigned long hwpb, *rombase;
rombase = (unsigned long *)((*(unsigned long *)0xC8) & 0x600000);
hwpb = rombase[65];
return (hwpb - (unsigned long)rombase < 0x10000 &&
*(unsigned short *)hwpb > 22 ? *(unsigned long *)(hwpb + 22) : 1);
}
Gets a Flash ROM verification number.
FL_getVerNum returns encrypted Flash ROM verification number from the Flash ROM certificate.
Writes a block into the Flash ROM.
FL_write writes a size bytes long block which begins at address pointed to by src
into the Flash ROM at the address dest. Writting is allowed only to the user portion
of the Flash ROM (also known as "archive memory"), which on HW1 calculators starts at 0x390000
(TI-89) or 0x590000 (TI-92 Plus)
and on HW2 calculators starts just at the end of the ROM code. User portion of the Flash ROM
ends on 0x400000 (TI-89) or 0x600000 (TI-92 Plus). Any attempt to write something out of this
region will be ignored.
NOTE: Using extremely dirty hacks it is possible to write into the Flash ROM even in the areas
out of user portion of the Flash ROM. However, I don't want to write such routine. If I include
such routine in TIGCCLIB, then any fool will be able to make a program which can destroy the
content of the Flash ROM. I really don't want this.
Writes a block into the extended memory.
EM_write is mostly identical as FL_write, except an error will be
thrown if dest points out of the archive memory (i.e. user portion of the Flash ROM).
NOTE: For anybody who wants to write something into the archive memory, the following
information may be useful:
- Blocks in the archive memory are kept in the linked list, but the organization of the
list is AMS-dependent (see compat.h header file to see how to
check which AMS version is present on the machine). If you don't want problems, you should
not write any data to the archive memory which are not organized as described below.
- Archive memory is divided on sectors which are 64K long. The first word of each sector
is the status word, and it can not be used for storage purposes
(-2 means "sector in use", -4
means "full sector", and -1 means "unused sector").
Each block must completely
belong to one sector, i.e. it can not cross over sector boundaries.
- Before each block is a header. It starts with a flag which may be -4
for deleted blocks, -2 for used blocks and
-1 for free blocks (AMS 2.xx uses
-32 and -64
instead of -2 and -4, I don't
know why; maybe old flags may be used for "noname" files, see below).
So, if you need to keep some data in the archive memory for a longer time, it must be
marked with -2
(or -32 on AMS 2.xx), else it may be treated by TIOS as a
"free space".
- After the flag word, on AMS 2.xx the name of the folder (8 bytes) and the name of the
stored file (8 bytes) are stored (both of them are zero padded). After this, yet one word
follows (usually set to zero), exact meaning is unknown to me. This extra information
(18 bytes) is not present on AMS 1.xx.
- After this, the next stored word is the size of the block in words increased
by 1 and with the topmost bit set. This word is used as a link to the next block. This concludes
the block header. Its size is 4 bytes on AMS 1.xx and 22 bytes on AMS 2.xx.
- Finally, the actual content of the block follows. If a handle is associated with the
block, the handle points just here, i.e. to the first byte of the actual content.
Function EM_findEmptySlot may be used for finding an
empty space in the archive memory of a given size.
Of course, if you are not an experienced programmer, avoid direct writing in the archive
memory. Use safe high-level functions like
EM_moveSymToExtMem instead.
void EM_abandon (HANDLE h);
Abandon an archive memory block.
EM_abandon abandons an archive memory block associated with handle h. More precise,
it frees the handle by clearing the entry in the heap table, and precedes memory block with
flag which indicate that the block is free.
NOTE: Functions like EM_blockErase are removed in AMS 2.xx to increase the
life of the Flash ROM. Really, it is not necessary to erase a block psyhically. It is
quite enough to mark it as "deleted", and it will be eventually simply rewritten later.
Performs garbage collection in the archive memory.
EM_GC performs garbage collection, i.e. rearranges blocks in the archive memory on such way
that all used blocks become contiguous, without free blocks between them. If allowDialog
is TRUE, a confirmation dialog will be displayed, and if it is
FALSE, the garbage collection will be performed without asking user for
the confirmation. EM_GC returns TRUE if garbage collection occured, else
returns FALSE.
Finds an empty space in the archive memory of the given size.
EM_findEmptySlot returns a pointer to the place in the archive memory which is large enough
to store block which is Size bytes long. It returns NULL if
the requirement cannot be satisfied. In such case, a garbage collection (see
EM_GC) is recommended, and there is a chance that a next call of
EM_findEmptySlot will be successful. If not, there is really no enough space in the archive
memory for a block of the given size. Thanks to Johan Eilert for information how this function
should be defined to work on both AMS 1.xx and AMS 2.xx.
NOTE: The pointer returned by EM_findEmptySlot points to the place where the actual block
need to be stored (see EM_write), not to the place where the header
of the block should be stored. The header begins 4 bytes before returned value on AMS 1.xx
and 22 bytes before returned value on AMS 2.xx. Note that you need to write a header for
each stored block if you don't want problems.
See EM_write for more info.
Collects some useful information about the archive memory.
EM_survey collects some useful information about the archive memory and stores them
in six variables pointed to by arguments. *inUse is the number of used bytes.
*freeAfterGC is the number of bytes which will be free after performing
garbage collection (see EM_GC). free is the number of
free bytes (not counting bytes occupied by "deleted" blocks, which will become
"free" only after the garbage collection). *unusedSectors is the number of
bytes in "unused" sectors. I don't know why the archive memory contains usually
one unused sector (i.e. sector which is never used for archiving purposes). The
program called "MoreMem" just marks such unused sectors as "sectors in use" to
get more archive memory (?). *badSectors is the number of bytes in bad
sectors, but I am not so sure what "bad sectors" really means.
*allExceptBaseCode is the number of all bytes in the Flash ROM which are not
occupied by TIOS. This argument is new in AMS 2.xx, but you must use six arguments
even on AMS 1.xx. If you don't need a particular information, you may pass
NULL as the argument. TIOS will see it's a null pointer and will
not save anything in it.
TIOS uses only freeAfterGC and free and always passes
NULL to everything else. *freeAfterGC + *free
is used to tell the user how much archive memory is available. Thanks to Johan Eilert for
information how EM_survey should be used correctly on both AMS 1.xx and AMS 2.xx.
Predefined types
Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};
size_t is a type proposed in ANSI C for defining size of strings and
memory blocks. It is defined here as
typedef unsigned long size_t;
NULL is a null-pointer value, defined as (void *) 0.
HANDLE is a type which represents handles associated to allocated memory
blocks. It is defined as
typedef unsigned short HANDLE;