ti/vars.h

#include <ti/vars.h>

The TI-84 Plus CE’s early-90s roots result in it managing files and data quite differently than how modern computers do. Some data in the OS, such as stat vars, are permanently allocated a fixed location in RAM; other data, such as user programs and strings, are not assigned a fixed location. The operating system’s equivalent to a “file” is called a variable, and they come in many types. The locations of dynamic variables are tracked in a structure called the VAT (Variable Allocation Table).

The VAT has the novel property that it is stored completely reversed and must be parsed backwards. This means that no C structs are available to represent VAT entires, because C can’t (easily) deal with backwards structs. As a further complication, archived variables store a copy of their VAT entry in the archive, and that copy is not reversed.

Every variable type deals with its size differently. The size is not stored in the VAT entry, but is instead stored with the variable’s data. But real_t has no explicit size; the OS infers the size. Meanwhile, lists store the number of elements and matrices store the number of rows and columns, so you have to compute the size. (Don’t forget that lists–but not matrices–can be either real or complex.) Most other types use a simple size word. The fileioc library masks all of this wackyness for you, but the OS also includes many helpful C functions.

API Documentation

TI CE OS user variables and memory.

This declares routines for low-level access to user variables (AppVars, programs, Str0-9, matrix, &c.), as well as other user-memory management routines (not the heap!), stat vars, and the RunPrgm interface.

Authors

Matt “MateoConLechuga” Waltz

Jacob “jacobly” Young

Defines

os_RamStart

Start of RAM.

Type: uint8_t[1024 * 256]

os_RclFlags

See also

<ti/flags.h>

os_AppData

Generally unused by the OS.

Type: uint8_t[256]

os_AsmPrgmSize

Current size of executing program.

Type: uint24_t

os_TempFreeArc

Set after asm_ArcChk call.

Type: uint24_t

os_RamCode

When writing to flash, the calculator’s hardware cannot read from flash.

So the flash writing code has to be copied to RAM first. It is copied here. You can use this as long as you don’t attempt any flash writes.

Type: uint8_t[1023]

OS_MATRIX_ELEMENT(matrix, row, col)

Gets an element from a matrix.

Parameters

  • matrix – Structure of matrix

  • row – Row in matrix

  • col – Column in matrix

Returns

real_t containing element data

OS_VAR_MAX_SIZE

Maximum size of OS variable.

OS_TYPE_REAL

Real variable.

OS_TYPE_REAL_LIST

Real variable list.

OS_TYPE_MATRIX

Matrix variable.

OS_TYPE_EQU

Equation.

OS_TYPE_STR

String.

OS_TYPE_PRGM

Unprotected program.

OS_TYPE_PROT_PRGM

Protected (uneditable) program.

OS_TYPE_CPLX

Complex variable.

OS_TYPE_CPLX_LIST

Complex variable list.

OS_TYPE_APPVAR

AppVar.

OS_TYPE_TMP_PRGM

Temporary program, deleted on homescreen.

OS_VAR_ANS

Name of Ans variable.

OS_VAR_STR1

Name of Str1 string variable.

Other Str variables follow the naming format OS_VAR_STR? where ? is the value [0-9].

OS_VAR_Y1

Name of Y1 equation variable.

Other Y variables follow the naming format OS_VAR_Y? where ? is [0-9].

OS_VAR_A

Name of A real variable.

Other real variables follow the naming format OS_VAR_? where ? is [A-Z] (and THETA).

OS_VAR_MAT_A

Name of A matrix variable.

Other matrix variables follow the naming format OS_VAR_MAT_? where ? is value [A-J].

OS_VAR_L1

Name of L1 list variable.

Other matrix variables follow the naming format OS_VAR_L? where ? is the value [1-6].

Typedefs

typedef struct list_t list_t

Structure of list variable type.

typedef struct cplx_list_t cplx_list_t

Structure of complex list variable type.

typedef struct matrix_t matrix_t

Structure of matrix variable type.

typedef struct string_t string_t

Structure of string variable type.

typedef struct equ_t equ_t

Structure of equation variable type.

typedef struct var_t var_t

Structure of miscellaneous variable type.

typedef int (*os_runprgm_callback_t)(void *data, int retval)

Callback function pointer type for os_RunPrgm.

See also

os_RunPrgm

Functions

size_t os_MemChk(void **free)

Returns the size in bytes of free RAM that the user isn’t using.

A pointer is also returned to the start of this region; you can use it for your own purposes but do not exceed the size returned. This function is useful if you are running out of space in the bss or heap and need a little extra memory.

Parameters

free – [out] Set to start of free available RAM

Returns

Size of available RAM

void os_ArcChk(void)

Routine checks the amount of free archive.

void *os_GetSymTablePtr(void)
Returns

A pointer to symtable of the OS

void *os_NextSymEntry(void *entry, uint24_t *type, uint24_t *nameLength, char *name, void **data)

Iterates over the OS symbol table.

This table stores the name and pointers to the variables (such as AppVars and programs) on the calculator. This function can be used to find all the variables on the calculator, to search for a specific variable the function os_ChkFindSym should be used instead.

Parameters

  • entry – [in] Current iterative entry, pass the output of os_GetSymTablePtr to start the search.

  • type – [in] Type of variable returned.

  • nameLength – [in] Length of variable name. The name may not be null-terminated.

  • name – [in] Variable name.

  • data – [in] Returns a pointer to the variable’s data, which may be in either RAM or flash.

Returns

next entry to pass to the entry argument on subsequent calls.

int os_DelSymEntry(void *entry)

Delete a var from RAM.

Parameters

entry – [in] An entry as returned from os_NextSymEntry().

Returns

TIOS System Error Code or 0 on success.

int os_CreateString(const char *name, const string_t *data)

Creates an TIOS Str.

Parameters

  • name – [in] Name of the Str to create.

  • data – [in] Initial contents of the created Str.

Returns

A TIOS error code, or 0 on success.

string_t *os_GetStringData(const char *name, int *archived)

Gets a pointer to an TIOS Str’s data, which may be in archive.

Note

Returns NULL if the Str doesn’t exist, otherwise a pointer to the size bytes.

Parameters

  • name – [in] Name of the Str to lookup.

  • archived – [in] Set to 1 if the Str is archived, otherwise 0, may be NULL if you don’t need it.

Returns

A pointer to the Str data

int os_CreateEquation(const char *name, const equ_t *data)

Creates a TIOS Equ.

Parameters

  • name – [in] Name of the Equ to create.

  • data – [in] Initial contents of the created Equ.

Returns

A TIOS error code, or 0 on success.

equ_t *os_GetEquationData(const char *name, int *archived)

Gets a pointer to an TIOS Equ’s data, which may be in archive.

Note

Returns NULL if the Equ doesn’t exist, otherwise a pointer to the size bytes.

Parameters

  • name – [in] Name of the Equ to lookup.

  • archived – [in] Set to 1 if the Equ is archived, otherwise 0, may be NULL if you don’t need it.

Returns

A pointer to the Equ data.

var_t *os_CreateAppVar(const char *name, uint16_t size)

Creates a TIOS AppVar.

Note

Returns NULL if creation failed for some reason, otherwise a pointer to the size bytes.

Note

If successful, the AppVar contents will be uninitialized, aka filled with random bytes.

Parameters

  • name – [in] Name of the AppVar to create.

  • size – [in] Size of AppVar to create.

Returns

A pointer to the AppVar data.

var_t *os_GetAppVarData(const char *name, int *archived)

Gets a pointer to a TIOS AppVar’s data, which may be in archive.

Note

Returns NULL if the AppVar doesn’t exist, otherwise a pointer to the size bytes.

Parameters

  • name – [in] Name of the AppVar to lookup.

  • archived – [in] Set to 1 if the AppVar is archived, otherwise 0, may be NULL if you don’t need it.

Returns

A pointer to the AppVar data.

void os_DelAppVar(const char *name)

Deletes an AppVar from RAM.

Parameters

name – [in] Name of the AppVar to delete.

int os_ChkFindSym(uint8_t type, const char *name, void **entry, void **data)

Locates a symbol in the symtable.

Parameters

  • type – [in] Type of symbol to find

  • name – [in] Pointer to name of symbol to find

  • entry – [out] Can be NULL if you don’t care

  • data – [out] Can be NULL if you don’t care

Returns

If file exists, returns 1 and sets entry and data, otherwise returns 0.

int os_GetVarSize(const char *name, size_t *size)

Gets the size of sized vars such as equations, string, programs, appvars, or the dimension of a list.

Parameters

  • name – [in] Name of the var to lookup.

  • size – [out] Pointer to store size of variable.

Returns

TIOS System Error Code or 0 on success.

int os_GetMatrixDims(const char *name, int *rows, int *cols)

Gets the dimensions of a matrix.

Parameters

  • name – [in] Name of the matrix to lookup.

  • rows – [in] Pointer to store number of rows.

  • cols – [in] Pointer to store number of columns.

Returns

TIOS System Error Code or 0 on success.

int os_GetRealListElement(const char *name, int index, real_t *value)

Gets a real value from a real list or a complex list where the selected element has no imaginary component.

Parameters

  • name – [in] Name of the list.

  • index – [in] Element index (1-based).

  • value – [out] Set to the value of the selected element.

Returns

TIOS System Error Code or 0 on success.

int os_GetMatrixElement(const char *name, int row, int col, real_t *value)

Gets a real value from a matrix.

Parameters

  • name – [in] Name of the matrix.

  • row – [in] Element row (1-based).

  • col – [in] Element col (1-based).

  • value – [out] Set to the value of the selected element.

Returns

TIOS System Error Code or 0 on success.

int os_GetRealVar(const char *name, real_t *value)

Gets the real value of a real variable or a complex variable with no imaginary component.

Parameters

  • name – [in] Name of TIOS variable.

  • value – [out] Set to the value of the variable.

Returns

TIOS System Error Code or 0 on success.

int os_SetListDim(const char *name, int dim)

If list name doesn’t exist, create it with dim elements, otherwise resize the list, with new elements being set to 0.

Parameters

  • name – [in] Name of the list to resize.

  • dim – [in] New list dimension.

Returns

TIOS System Error Code or 0 on success.

int os_SetMatrixDims(const char *name, int rows, int cols)

If matrix name doesn’t exist, create it with dimensions rows and cols, otherwise resize the matrix, with new elements being set to 0.

Parameters

  • name – [in] Name of the matrix to resize.

  • rows – [in] New row dimension.

  • cols – [in] New col dimension.

Returns

TIOS System Error Code or 0 on success.

int os_SetRealListElement(const char *name, int index, const real_t *value)

Sets a list element to a real value.

If the list doesn’t exist, then index must be 1 and it creates a 1 element list.

Parameters

  • name – [in] Name of the list.

  • index – [in] Element index (1-based).

  • value – [in] The value to set to the selected element.

Returns

TIOS System Error Code or 0 on success.

int os_SetMatrixElement(const char *name, int row, int col, const real_t *value)

Sets a matrix element to a real value.

Parameters

  • name – [in] Name of the matrix.

  • row – [in] Element row (1-based).

  • col – [in] Element col (1-based).

  • value – [in] The value to set to the selected element.

Returns

TIOS System Error Code or 0 on success.

int os_SetRealVar(const char *name, const real_t *value)

Sets a variable to a real value, creating it if it doesn’t exist.

Parameters

  • name – [in] Name of variable to lookup.

  • value – [in] The value to set the variable to.

Returns

TIOS System Error Code or 0 on success.

void *os_GetAnsData(uint8_t *type)

Gets the Ans variable.

Note

Returns NULL if Ans doesn’t exist or type is NULL

Parameters

type – [in] This is set to the current variable type in ANS

Returns

Pointer to the data

void os_DelRes(void)

Invalidate and clear stat variables.

int os_RunPrgm(const char *prgm, void *data, size_t size, os_runprgm_callback_t callback)

Runs a program that exists on the calculator.

Note that this will destroy the currently running program. The function has an optional callback entry point for when a program finishes, which can be used to rebuild the program context. Additional program context information can be safely stored by using the extra data argument, which is delivered to the callback entry point.

Note

The integer return of the callback acts the same as the integer return of the main function, and is returned to the parent caller (either the OS or a shell).

Parameters

  • prgm – [in] Name of program to execute.

  • data – [in] User data that will be available in the callback function. May be NULL.

  • size – [in] Size of user data (keep this small, it is stored on the stack!)

  • callback – [in] This callback is used as the entry point to the program rather than main when the called program finishes. The argument data will contain the data argument, and retval will contain the error code if a TI-BASIC program, or the exit code if a C program. Other types of programs may have an undefined retval. This argument may be left NULL if execution should not return to the calling program.

Returns

This function should not return, but if it does, -1 indicates the program could not be found, -2 if not enough memory, and < 0 if some other error occurred.

int os_Eval(const void *data, size_t len)

Evalutes a tokenized expression.

Parameters

  • data – [in] Tokenized expression to evaluate.

  • len – [in] Length of tokenized data.

Returns

TIOS System Error Code or 0 on success, with the result stored in the Ans variable.

int os_EvalVar(const char *name)

Evalutes a tokenized equation or string variable.

Parameters

name – [in] Name of variable to evaluate.

Returns

TIOS System Error Code or 0 on success, with the result stored in the Ans variable.

struct list_t
#include <vars.h>

Structure of list variable type.

Public Members

uint16_t dim
real_t items[1]
struct cplx_list_t
#include <vars.h>

Structure of complex list variable type.

Public Members

uint16_t dim
cplx_t items[1]
struct matrix_t
#include <vars.h>

Structure of matrix variable type.

Public Members

uint8_t cols
uint8_t rows
real_t items[1]
struct string_t
#include <vars.h>

Structure of string variable type.

Public Members

uint16_t len
char data[1]
struct equ_t
#include <vars.h>

Structure of equation variable type.

Public Members

uint16_t len
char data[1]
struct var_t
#include <vars.h>

Structure of miscellaneous variable type.

Public Members

uint16_t size
uint8_t data[1]