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


unsigned short FL_addCert (void *src, unsigned long size);

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.

void FL_download (unsigned long dummy);

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.

void *FL_getHardwareParmBlock (void);

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);
}

unsigned short FL_getVerNum (void);

Gets a Flash ROM verification number.

FL_getVerNum returns encrypted Flash ROM verification number from the Flash ROM certificate.

void FL_write (const void *src, void *dest, unsigned short size);

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.

void EM_write (const void *src, void *dest, unsigned long size);

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: 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.

short EM_GC (short allowDialog);

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.

void *EM_findEmptySlot (unsigned long Size);

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.

void EM_survey (unsigned long *inUse, unsigned long *freeAfterGC, unsigned long *free, unsigned long *unusedSectors, unsigned long *badSectors, ulong *allExceptBaseCode);

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


enum Bool

Bool is enumerated type for describing true or false values. It is defined as
enum Bool {FALSE, TRUE};

type size_t

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;

const NULL

NULL is a null-pointer value, defined as (void *) 0.

type HANDLE

HANDLE is a type which represents handles associated to allocated memory blocks. It is defined as
typedef unsigned short HANDLE;

Return to the main index