TI-89 / TI-92 Plus Developer Guide
Beta Version .02
Important information
Texas Instruments makes no warranty, either expressed or implied, including but not
limited to any implied warranties of merchantability and fitness for a particular purpose,
regarding any programs or book materials and makes such materials available solely on
an “as-is” basis.
In no event shall Texas Instruments be liable to anyone for special, collateral, incidental,
or consequential damages in connection with or arising out of the purchase or use of
these materials, and the sole and exclusive liability of Texas Instruments, regardless of
the form of action, shall not exceed the purchase price of this product. Moreover, Texas
Instruments shall not be liable for any claim of any kind whatsoever against the use of
these materials by any other party.
The latest version of this Guide, along with all other up-to-date information for
developers, is available at www.ti.com/calc/developers/.
© 2000, 2001 Texas Instruments Incorporated
,
TI-GRAPH LINK, and TI
Sierra C is a trademark of Sierra Systems.
FLASH
Studio are trademarks of Texas Instruments Incorporated.
Table of Contents
1. Introduction ..............................................................................................1
1.1. Purpose of this Guide...........................................................................................1
1.2. Chapter Layout.....................................................................................................1
1.3. Conventions Used in this Guide...........................................................................3
2. The 68000 TI AMS Operating System Overview......................................5
3. The TI-89 / TI-92 Plus Hardware Overview..............................................7
3.1. Overview..............................................................................................................7
3.2. Memory Map........................................................................................................8
3.2.1. Vector Table...........................................................................................................9
i
3.3. ASIC registers....................................................................................................11
4. User Interface Overview.........................................................................15
4.1. Windows.............................................................................................................15
4.2. Menus ................................................................................................................16
4.2.1. Toolbars................................................................................................................17
4.2.2. Pop-ups................................................................................................................17
4.2.2.1. Static Pop-ups.........................................................................................17
4.2.2.2. Dynamic Pop-ups....................................................................................18
4.2.2.3. Dynamic Pop-ups with Menu Features....................................................18
4.3. Dialog Boxes......................................................................................................18
4.4. Fonts..................................................................................................................19
4.5. The Status Line..................................................................................................22
5. Flash Applications vs. ASM Programs...................................................23
6. Assembly Language Programming Overview ........................................25
6.1. What are ASM Programs? .................................................................................25
6.2. Hardware Stack..................................................................................................25
6.3. Register Usage ..................................................................................................25
6.4. Calling Flash-ROM-Resident Routines ..............................................................26
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
ii
Table of Contents
6.5. Subroutine Linkage............................................................................................27
6.6. Sample ASM Program .......................................................................................29
7. Flash Application Layout........................................................................31
7.1. File Format.........................................................................................................31
7.1.1. Flash Header........................................................................................................31
7.1.2. Certificate Header.................................................................................................32
7.1.3. Application Header...............................................................................................33
7.1.3.1. Magic Number.........................................................................................33
7.1.3.2. Internal Application Name .......................................................................33
7.1.3.3. Flags........................................................................................................34
7.1.3.4. Length of Data Segment..........................................................................34
7.1.3.5. Byte Offset to Code Segment..................................................................34
7.1.3.6. Byte Offset to Initial Data Table...............................................................34
7.1.3.7. Length of Initial Data Table......................................................................35
7.1.3.8. Optional Header ......................................................................................35
7.1.4. Relocation Map.....................................................................................................35
7.1.5. Application Code ..................................................................................................35
7.1.6. Initial Data Table...................................................................................................35
7.1.7. Signature..............................................................................................................36
7.2. Layout in Memory...............................................................................................36
7.3. Source Layout....................................................................................................38
7.3.1. Interactive Applications.........................................................................................38
7.3.1.1. FRAME....................................................................................................39
7.3.1.2. Pointer to FRAME....................................................................................40
7.3.1.3. Object Frame Attributes...........................................................................40
7.3.1.3.1. Attribute OO_APP_FLAGS (0x1).........................................................40
7.3.1.3.2. Attribute OO_APP_NAME (0x2)..........................................................41
7.3.1.3.3. Attribute OO_APP_TOK_NAME (0x3).................................................41
7.3.1.3.4. Method OO_APP_PROCESS_EVENT (0x4)......................................41
7.3.1.3.5. Attribute OO_APP_DEFAULT_MENU (0x5) .......................................42
7.3.1.3.6. Attribute OO_APP_DEFAULT_MENU_HANDLE (0x6).......................42
7.3.1.3.7. Attribute OO_APP_EXT_COUNT (0x7)...............................................42
7.3.1.3.8. Attribute OO_APP_EXTENSIONS (0x8).............................................42
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
7.3.1.3.9. Attribute OO_APP_EXT_ENTRIES (0x9)............................................42
7.3.1.3.10. Method OO_APP_LOCALIZE (0xA)..................................................43
7.3.1.3.11. Method OO_APP_UNLOCALIZE (0xB).............................................43
7.3.1.3.12. Method OO_APP_CAN_DELETE (0xC)............................................43
7.3.1.3.13. Method OO_APP_CAN_MOVE (0xD)...............................................43
7.3.1.3.14. Method OO_APP_VIEWER (0xE).....................................................44
7.3.1.3.15. Attribute OO_APP_ICON (0xF).........................................................44
7.3.1.3.16. Method OO_APP_EXT_HELP (0x10) ...............................................44
7.3.1.3.17. Method OO_APP_NOTICE_INSTALL (0x11)....................................44
7.3.1.3.18. Method OO_APP_ABOUT (0x12) .....................................................44
7.3.1.3.19. Attribute OO_APPSTRING (0x1000 and up).....................................45
7.3.1.4. Example...................................................................................................45
7.3.2. TI-BASIC Extensions............................................................................................48
7.3.3. Shared-Code Library............................................................................................51
iii
7.3.3.1. Creating the Library Interface..................................................................51
7.3.3.2. Accessing a Library.................................................................................53
7.3.3.3. Frame Description Language..................................................................53
7.3.4. Language Localization..........................................................................................56
7.3.4.1. Localizer Template..................................................................................56
7.3.4.2. How Localization Works ..........................................................................60
8. Integrating a Flash Application...............................................................63
8.1. Mode Settings....................................................................................................63
8.1.1. Mode Notification Flags........................................................................................63
8.1.1.1. Modifying Mode Settings Within an App..................................................64
8.1.1.2. MO_option Array and Settings ................................................................64
8.2. Switching to the Home Screen...........................................................................66
8.3. Catalog...............................................................................................................67
8.3.1. Built-in Functions and Commands........................................................................67
8.3.2. User-Defined Functions and Programs................................................................67
8.3.3. Flash App Extensions...........................................................................................69
8.4. Interfacing with TI-BASIC...................................................................................70
8.5. Verifying the OS Version....................................................................................74
8.6. Optimizing Code Space .....................................................................................75
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
iv
Table of Contents
8.7. VAR-LINK...........................................................................................................76
9. Application Control Flow.........................................................................77
9.1. Event-Driven Architecture ..................................................................................77
9.2. Event Structure Layout.......................................................................................78
9.3. Commands.........................................................................................................79
9.4. Starting and Stopping an Application.................................................................84
9.5. Keyboard Events................................................................................................85
9.6. Menu Processing ...............................................................................................85
9.6.1. Static Menus.........................................................................................................86
9.6.2. Dynamic Menus....................................................................................................87
9.7. Paint Events.......................................................................................................88
9.8. Background Events............................................................................................88
9.9. Default Event Handler........................................................................................88
9.9.1. CM_KEY_PRESS.................................................................................................88
9.9.2. CM_PASTE_STRING...........................................................................................91
9.9.3. CM_PASTE_HANDLE..........................................................................................92
9.9.4. CM_STO...............................................................................................................92
9.9.5. CM_RCL...............................................................................................................92
9.9.6. CM_DEACTIVATE ...............................................................................................92
9.9.7. CM_ACTIVATE ....................................................................................................92
9.10. Installing, Moving, and Deleting an Application................................................92
10. Error Handling......................................................................................95
10.1. Throwing an Error..........................................................................................95
10.2. Delayed Error Messages ...............................................................................95
10.3. Throwing Your Own Errors ............................................................................96
10.4. Catching Errors..............................................................................................97
10.5. Cleaning Up...................................................................................................97
10.6. Caveats..........................................................................................................98
10.6.1. Jumping Out of TRY Blocks..........................................................................98
10.6.2. Referencing Auto Variables in ONERR/FINALLY Blocks..............................99
10.6.3. Where Not to Throw Errors ...........................................................................99
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
11. Creating the User Interface................................................................101
11.1. Common Screen Components.....................................................................101
11.1.1. Screen/Window Regions and Coordinates..................................................101
11.1.2. BITMAP.......................................................................................................102
11.1.3. ICON ...........................................................................................................102
11.2. Windows ......................................................................................................102
11.2.1. Window Regions and Coordinates..............................................................103
11.2.2. Window Routines ........................................................................................104
11.3. Menus..........................................................................................................105
11.3.1. Menu-Draw Structure..................................................................................106
11.3.2. Menu IDs.....................................................................................................106
11.3.3. Menu Routines............................................................................................106
11.4. Dialog Boxes................................................................................................108
v
11.4.1. Dialog Routines...........................................................................................108
11.4.2. Dialog Fields................................................................................................109
11.4.2.1. Field Index ...............................................................................................109
11.4.2.2. DYNPOPUP.............................................................................................109
11.4.2.3. EDIT_FIELD.............................................................................................109
11.4.2.4. HEADER..................................................................................................110
11.4.2.5. HEDIT......................................................................................................110
11.4.2.6. HPOPUP..................................................................................................110
11.4.2.7. MENU ......................................................................................................110
11.4.2.8. POPUP ....................................................................................................111
11.4.2.9. SCROLL_REGION ..................................................................................111
11.4.2.10. TEXT......................................................................................................112
11.4.2.11. XFLAGS.................................................................................................112
11.4.3. Dialog Flags ................................................................................................113
11.4.4. Dialog Call-Backs........................................................................................114
11.5. Resource Compiler......................................................................................115
11.5.1. DIALOG Boxes............................................................................................117
11.5.2. MENUs........................................................................................................118
11.5.3. POPUPs......................................................................................................119
11.6. Example.......................................................................................................120
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
vi
Table of Contents
11.6.1. Files in Example and Explanation of Details...............................................123
12. Basic Text Editing Facility ..................................................................127
12.1. How to Edit Text...........................................................................................127
12.2. Simple Text Edit Example............................................................................128
12.3. Clipboard .....................................................................................................129
13. Memory Management ........................................................................131
13.1. The Heap (Dynamic RAM Storage).............................................................131
13.2. File System..................................................................................................132
13.2.1. Opening Multiple Files for WRITE Mode.....................................................133
13.3. Managing Variables.....................................................................................134
13.3.1. Normal Symbol Routines.............................................................................136
13.3.2. Storing and Retrieving Variable Data..........................................................137
13.3.2.1. Store and Recall Look-up Paths..............................................................138
13.3.2.2. Recall Look-up Path.................................................................................138
13.3.2.3. Store Look-up Path..................................................................................139
13.3.2.4. HSYM VarRecall (BYTE *
13.3.2.5. HSYM VarStore (BYTE *
WORD
13.3.2.6. General Data Storage..............................................................................142
13.3.2.7. System Functions ....................................................................................143
SourceSize
[,
parm1
, RECALL_FLAGS
Var
] [,
, WORD
parm2
DestVar
] [,
)..........................139
Flags
,
Flags
] . . . )..........................141
parm3
13.3.3. Low-Level Routines.....................................................................................143
13.3.3.1. Utilities .....................................................................................................144
13.3.3.2. Low-Level Folder Routines......................................................................144
13.3.3.3. Low-Level Symbol Routines ....................................................................144
14. Data Types.........................................................................................145
14.1. Expression...................................................................................................147
14.1.1. Non-Negative or Negative Integers.............................................................147
14.1.2. Positive or Negative Fractions.....................................................................147
14.1.3. Floating-Point Numbers...............................................................................148
14.1.4. All Other Tags Not Listed Here ...................................................................148
14.2. List ...............................................................................................................148
14.3. Matrix...........................................................................................................149
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
vii
14.4. Data Variable...............................................................................................150
14.5. Text Variable................................................................................................151
14.6. String Variable .............................................................................................151
14.7. Graph Database ..........................................................................................152
14.8. Bitmap PIC Images......................................................................................156
14.9. Tokenized Programs and Functions............................................................157
14.10. Programs and Functions in Text Format ...................................................159
14.11. Third Party Data.........................................................................................160
14.12. Assembly Program.....................................................................................160
15. Expressions and the Expression Stack..............................................161
15.1. Overview......................................................................................................161
15.2. Contiguous Tokenized Polish Representation.............................................161
15.2.1. Tags ............................................................................................................162
15.2.2. Numbers......................................................................................................163
15.2.3. Variables, Units and Physical Constants.....................................................165
15.2.4. Other Constants..........................................................................................166
15.2.5. One-argument Tags....................................................................................167
15.2.6. Two-argument Tags....................................................................................167
15.2.7. Tags That Take More Than Two or a Variable Number of Arguments ......168
15.2.8. Lists and Matrices .......................................................................................169
15.2.9. Primary, Secondary, and Command Tags..................................................169
15.2.10. User and Application Defined Functions and Programs............................170
15.3. External Versus Internal Tokenized Polish..................................................170
15.4. Most Main Ordering and Internal Representations of
Exponentiation, Multiplication, and Addition ................................................172
15.5. The Expression Stack..................................................................................174
15.6. An Example of Working on the EStack........................................................175
15.6.1. Estack Arguments and Results...................................................................176
15.6.2. Estack Calculations.....................................................................................177
15.7. Working With Lists.......................................................................................178
16. Working with Numbers.......................................................................181
16.1. Overview......................................................................................................181
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
viii
Table of Contents
16.2. Rational System vs. Float System...............................................................181
16.3. EXACT/APPROX/AUTO Modes..................................................................182
16.4. Floating Point Numbers ...............................................................................183
16.5. Rational Numbers........................................................................................185
16.6. EStack Arithmetic.........................................................................................185
16.7. Complex Numbers.......................................................................................186
17. Graphing ............................................................................................189
17.1. The Graph Screen .......................................................................................189
17.2. Working with the Graph Application.............................................................190
17.3. Two Graph Mode.........................................................................................192
17.4. Graphing Functions .....................................................................................193
17.5. Graph Application Memory Usage...............................................................194
17.6. Available Graph System Routines and Global Variables.............................195
18. TI FLASH Studio (IDE) Overview.......................................................199
18.1. Introduction..................................................................................................199
18.2. Development System...................................................................................199
18.2.1. Requirements..............................................................................................199
18.2.2. Installation...................................................................................................200
18.2.3. Compiler/Assembler/Linker.........................................................................201
18.2.4. Simulator/Debugger ....................................................................................201
18.2.5. IDE Overview ..............................................................................................201
18.2.6. Uninstalling..................................................................................................203
18.2.7. Support........................................................................................................203
18.2.8. References..................................................................................................203
18.3. TI FLASH Studio Interface...........................................................................204
18.3.1. File Menu.....................................................................................................205
18.3.2. Edit Menu....................................................................................................206
18.3.3. View Menu...................................................................................................207
18.3.4. Project Menu...............................................................................................211
18.3.5. Debug Menu................................................................................................212
18.3.6. Simulator Menu...........................................................................................214
18.3.7. Link Menu....................................................................................................215
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
18.3.8. Window Menu..............................................................................................215
18.3.9. Help Menu...................................................................................................216
ix
18.4. Example.......................................................................................................216
18.4.1. Creating a Flash Studio Project...................................................................216
18.4.2. Building the Application...............................................................................217
18.4.3. Loading the Application into the Simulator..................................................217
18.4.4. Debugging the Application ..........................................................................217
18.4.5. Terminating TI FLASH Studio .....................................................................217
18.4.6. Preparing the Application for Site Testing...................................................218
18.4.6.1. Educational and Professional Developers...............................................218
18.4.7. Preparing for Public Release.......................................................................219
Glossary...................................................................................................221
Appendix A: System Routines..................................................................225
Algebra Utilities .......................................................................................................227
are_expressions_identical............................................................................................231
compare_expressions ..................................................................................................232
did_push_lincf...............................................................................................................234
factor_base_index........................................................................................................235
factor_exponent_index.................................................................................................236
has_different_variable..................................................................................................237
im_index.......................................................................................................................238
index_if_pushed_binomial_info....................................................................................239
index_if_pushed_qquad_info........................................................................................240
index_numeric_term.....................................................................................................242
index_of_lead_base_of_lead_term ..............................................................................244
index_reductum_with_tag_base...................................................................................245
index_rmng_factor........................................................................................................246
index_rmng_fctrs_start_base.......................................................................................247
index_rmng_fctrs_start_base_tag................................................................................248
index_rmng_fctrs_start_fctr_tag...................................................................................249
is_free_of_tag...............................................................................................................250
is_independent_of........................................................................................................251
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
x
Table of Contents
is_independent_of_tail..................................................................................................252
is_polynomial_in_var_or_kern......................................................................................255
is_tail_independent_of..................................................................................................256
is_term_improper..........................................................................................................257
is_totally_polynomial ....................................................................................................258
lead_base_index ..........................................................................................................259
lead_factor_index.........................................................................................................260
lead_term_index...........................................................................................................262
linear_degree................................................................................................................264
main_gen_var_index....................................................................................................265
map_unary_over_comparison......................................................................................266
next_var_or_kernel_index............................................................................................267
numeric_factor_index...................................................................................................268
push_but_factor............................................................................................................270
push_but_term..............................................................................................................271
push_constant_factors .................................................................................................272
push_denominator........................................................................................................273
push_dependent_factors..............................................................................................274
push_dependent_terms................................................................................................275
push_desolve ...............................................................................................................276
push_div_dif_1c............................................................................................................277
push_div_dif_1f ............................................................................................................278
push_independent_factors...........................................................................................279
push_independent_terms.............................................................................................280
push_integer_gcd.........................................................................................................281
push_integer_lcm.........................................................................................................282
push_nonconstant_factors ...........................................................................................283
push_nonconstant_terms.............................................................................................284
push_nonnumeric_factors............................................................................................285
push_numerator ...........................................................................................................286
push_percent................................................................................................................287
push_poly_deg_in_var_or_kernel ................................................................................288
push_subst_no_simp....................................................................................................289
push_substitute_simplify ..............................................................................................290
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
push_substitute_using_such_that................................................................................291
push_var_kern_tail.......................................................................................................292
re_index........................................................................................................................293
reductum_index............................................................................................................294
remaining_factors_index ..............................................................................................296
replace_top2_with_imre ...............................................................................................298
Apps........................................................................................................................299
EV_getAppID................................................................................................................301
EV_quit.........................................................................................................................302
OO_appGetPublicStorage............................................................................................303
OO_appIsMarkedDelete...............................................................................................304
OO_appMarkDelete......................................................................................................305
OO_AppNameToACB ..................................................................................................306
OO_appSetPublicStorage............................................................................................307
xi
OO_CondGetAttr..........................................................................................................309
OO_Deref.....................................................................................................................310
OO_Destroy..................................................................................................................311
OO_DestroyAll..............................................................................................................312
OO_GetAppAttr............................................................................................................313
OO_GetAttr...................................................................................................................314
OO_HasAttr..................................................................................................................315
OO_InstallAppHook......................................................................................................316
OO_InstallAppHookByName........................................................................................318
OO_InstallSystemHook................................................................................................320
OO_New.......................................................................................................................322
OO_NextACB...............................................................................................................323
OO_PrevACB...............................................................................................................324
OO_SetAppAttr.............................................................................................................325
OO_SetAttr...................................................................................................................326
OO_UninstallAppHook .................................................................................................327
OO_UninstallAppHookByName....................................................................................328
OO_UninstallSystemHook............................................................................................329
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xii
Table of Contents
Certificates..............................................................................................................331
freeIdList.......................................................................................................................333
LIO_SendIdList.............................................................................................................334
Data Utilities............................................................................................................335
DataTypeNames...........................................................................................................337
gen_version..................................................................................................................338
GetDataType................................................................................................................339
GetFuncPrgmBodyPtr ..................................................................................................340
QSysProtected .............................................................................................................341
SmapTypeStrings.........................................................................................................342
Dialog......................................................................................................................343
Dialog ...........................................................................................................................345
DialogAdd.....................................................................................................................347
DialogDo.......................................................................................................................349
DialogNew....................................................................................................................350
DlgMessage..................................................................................................................353
DrawStaticButton..........................................................................................................354
ERD_dismissNotice......................................................................................................356
ERD_notice ..................................................................................................................357
VarNew.........................................................................................................................358
VarOpen.......................................................................................................................360
VarSaveAs....................................................................................................................362
Direct Floating Point Operations .............................................................................363
acos..............................................................................................................................367
acosh............................................................................................................................368
asin...............................................................................................................................369
asinh.............................................................................................................................370
atan...............................................................................................................................371
atan2.............................................................................................................................372
atanh.............................................................................................................................373
bcdadd..........................................................................................................................374
bcdbcd..........................................................................................................................375
bcdcmp.........................................................................................................................376
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
bcddiv...........................................................................................................................377
bcdlong.........................................................................................................................378
bcdmul..........................................................................................................................379
bcdneg..........................................................................................................................380
bcdsub..........................................................................................................................381
cacos............................................................................................................................382
cacosh..........................................................................................................................383
casin.............................................................................................................................384
casinh...........................................................................................................................385
catan.............................................................................................................................386
catanh...........................................................................................................................387
ccos..............................................................................................................................388
ccosh............................................................................................................................389
ceil................................................................................................................................390
xiii
cexp..............................................................................................................................391
ck_valid_float................................................................................................................392
cln.................................................................................................................................393
clog10...........................................................................................................................394
cos................................................................................................................................395
cosh..............................................................................................................................396
csin...............................................................................................................................397
csinh.............................................................................................................................398
csqrt..............................................................................................................................399
ctan...............................................................................................................................400
ctanh.............................................................................................................................401
estack_number_to_Float..............................................................................................402
estack_to_float .............................................................................................................403
exp................................................................................................................................404
fabs...............................................................................................................................405
floor...............................................................................................................................406
fmod..............................................................................................................................407
frexp10..........................................................................................................................408
is_float_infinity..............................................................................................................409
is_float_negative_zero..................................................................................................410
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xiv
Table of Contents
is_float_positive_zero...................................................................................................411
is_float_signed_infinity .................................................................................................412
is_float_transfinite.........................................................................................................413
is_float_unsigned_inf_or_nan.......................................................................................414
is_float_unsigned_zero.................................................................................................415
is_nan...........................................................................................................................416
log.................................................................................................................................417
log10.............................................................................................................................418
modf..............................................................................................................................419
pow...............................................................................................................................420
push_Float....................................................................................................................421
push_Float_to_nonneg_int...........................................................................................422
round12 ........................................................................................................................423
round12_err..................................................................................................................424
round14 ........................................................................................................................426
sin.................................................................................................................................427
sinh...............................................................................................................................428
sqrt................................................................................................................................429
tan.................................................................................................................................430
tanh...............................................................................................................................431
Display ....................................................................................................................433
ClientToScr...................................................................................................................435
display_statements.......................................................................................................436
DrawStrWidth ...............................................................................................................437
DrawStrWidthP.............................................................................................................438
Parms2D.......................................................................................................................439
Parse1DExpr................................................................................................................440
Parse2DExpr................................................................................................................442
Parse2DMultiExpr.........................................................................................................443
Print2DExpr..................................................................................................................444
sf_width ........................................................................................................................445
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
Error Handling.........................................................................................................447
clear_error_context.......................................................................................................449
ER_catch......................................................................................................................450
ER_success..................................................................................................................451
ER_throwFrame ...........................................................................................................452
ER_throwVar................................................................................................................454
ERD_dialog ..................................................................................................................455
find_error_message......................................................................................................456
EStack Arithmetic....................................................................................................457
add_to_top....................................................................................................................461
add1_to_top..................................................................................................................462
can_be_approxed.........................................................................................................463
compare_complex_magnitudes....................................................................................465
compare_Floats............................................................................................................466
xv
compare_numbers........................................................................................................467
did_push_cnvrt_Float_to_integer.................................................................................468
divide_top.....................................................................................................................469
get_lb............................................................................................................................470
get_ub...........................................................................................................................471
integer_non_unknown..................................................................................................472
is_cFloat_agg...............................................................................................................473
is_complex_Float..........................................................................................................475
is_complex0..................................................................................................................476
is_complex_number .....................................................................................................477
is_constant ...................................................................................................................478
is_Float_exact_whole_number.....................................................................................479
is_minus1 .....................................................................................................................480
is_pos_int_and_eq_quantum .......................................................................................481
is_reciprocal_of_quantum ............................................................................................482
is_whole_number .........................................................................................................483
is0.................................................................................................................................484
is1.................................................................................................................................485
negate_top....................................................................................................................486
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xvi
Table of Contents
push_arg_minus_1.......................................................................................................487
push_arg_plus_1..........................................................................................................488
push_difference............................................................................................................489
push_gcd_numbers......................................................................................................490
push_is_prime..............................................................................................................491
push_minus_recip_of_quantum ...................................................................................492
push_negate.................................................................................................................493
push_negate_quantum_as_negint...............................................................................494
push_pi.........................................................................................................................495
push_pi_on_quantum...................................................................................................496
push_product................................................................................................................497
push_quantum_as_nonnegative_int.............................................................................498
push_quantum_pair_as_pos_frac................................................................................499
push_ratio.....................................................................................................................500
push_reciprocal............................................................................................................501
push_reciprocal_of_quantum.......................................................................................502
push_sum.....................................................................................................................503
push0............................................................................................................................504
push1............................................................................................................................505
replace_top_with_reciprocal.........................................................................................506
replace_top2_with_difference.......................................................................................507
replace_top2_with_prod...............................................................................................508
replace_top2_with_ratio ...............................................................................................509
replace_top2_with_sum................................................................................................510
subtract_from_top.........................................................................................................511
subtract1_from_top.......................................................................................................512
times_top......................................................................................................................513
EStack Utilities ........................................................................................................515
check_estack_size .......................................................................................................517
delete_between............................................................................................................518
delete_expression ........................................................................................................519
deleted_between..........................................................................................................520
deleted_expression ......................................................................................................521
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
estack_to_short............................................................................................................522
estack_to_ushort..........................................................................................................523
GetValue.......................................................................................................................524
move_between_to_top.................................................................................................525
moved_between_to_top...............................................................................................526
next_expression_index.................................................................................................527
push_between..............................................................................................................528
push_expression ..........................................................................................................529
push_Float_to_rat.........................................................................................................530
push_long_to_integer...................................................................................................531
push_quantum..............................................................................................................532
push_ulong_to_integer.................................................................................................533
push_ushort_to_integer................................................................................................534
reset_estack_size.........................................................................................................535
xvii
Expression Evaluation / Algebraic Simplification.....................................................537
ForceFloat ....................................................................................................................539
NG_approxESI .............................................................................................................540
NG_execute..................................................................................................................541
NG_rationalESI.............................................................................................................542
push_approx.................................................................................................................543
push_equals.................................................................................................................544
push_greater_than .......................................................................................................545
push_greater_than_or_equals......................................................................................546
push_internal_simplify..................................................................................................547
push_less_than ............................................................................................................548
push_less_than_or_equals...........................................................................................549
push_not_equals..........................................................................................................550
push_simplify................................................................................................................551
push_simplify_statements............................................................................................552
replace_top_with_post_simplified.................................................................................553
Files.........................................................................................................................555
FAccess........................................................................................................................557
FClose..........................................................................................................................558
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xviii
Table of Contents
FCreate.........................................................................................................................559
FDelete.........................................................................................................................560
FEof..............................................................................................................................561
FFindFirst .....................................................................................................................562
FFindNext.....................................................................................................................563
FGetC...........................................................................................................................564
FGetPos .......................................................................................................................565
FGetSize.......................................................................................................................566
FOpen...........................................................................................................................567
FPutC ...........................................................................................................................570
FRead...........................................................................................................................571
FSetBufSize..................................................................................................................572
FSetPos........................................................................................................................573
FSetSize.......................................................................................................................574
FSetVer ........................................................................................................................575
FStatus.........................................................................................................................576
FType ...........................................................................................................................577
FWrite...........................................................................................................................578
TokenizeName .............................................................................................................579
Graphing .................................................................................................................581
CkValidDelta.................................................................................................................583
cmd_clrdraw.................................................................................................................584
cmd_clrgraph................................................................................................................585
cmd_rclgdb...................................................................................................................586
cmd_stogdb..................................................................................................................587
CptDeltax......................................................................................................................588
CptDeltay......................................................................................................................589
CptFuncX......................................................................................................................590
CptIndep.......................................................................................................................591
EQU_select ..................................................................................................................593
EQU_setStyle...............................................................................................................594
FindFunc.......................................................................................................................595
FindGrFunc...................................................................................................................596
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
gr_CptIndepInc.............................................................................................................597
gr_delete_fldpic............................................................................................................599
gr_DispLabels...............................................................................................................600
gr_xres_pixel................................................................................................................601
GraphActivate...............................................................................................................602
GrAxes..........................................................................................................................606
GrClipLine.....................................................................................................................607
GrLineFlt.......................................................................................................................609
GT_Regraph.................................................................................................................610
GT_Regraph_if_neccy..................................................................................................611
StepCk..........................................................................................................................612
XCvtFtoP......................................................................................................................613
XCvtPtoF......................................................................................................................614
YCvtFtoP......................................................................................................................615
xix
YCvtPtoF......................................................................................................................616
Home Screen..........................................................................................................617
cmd_clrhome................................................................................................................619
cmd_disphome.............................................................................................................620
HomeAlone...................................................................................................................621
HomeExecute...............................................................................................................622
HS_getAns ...................................................................................................................623
HS_getEntry.................................................................................................................624
HS_popEStack.............................................................................................................625
Interrupts.................................................................................................................627
idle................................................................................................................................629
off..................................................................................................................................631
OSSetSR......................................................................................................................632
Keyboard.................................................................................................................633
alphaLockOff ................................................................................................................635
alphaLockOn ................................................................................................................636
GetAlphaStatus ............................................................................................................637
GKeyFlush....................................................................................................................638
GKeyIn..........................................................................................................................639
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xx
Table of Contents
kbhit..............................................................................................................................641
KeyYesOrNo.................................................................................................................642
ngetchx.........................................................................................................................643
OSCheckBreak.............................................................................................................644
OSClearBreak ..............................................................................................................645
OSDisableBreak...........................................................................................................646
OSEnableBreak............................................................................................................647
OSInitBetweenKeyDelay..............................................................................................648
OSInitKeyInitDelay .......................................................................................................649
push_getkey.................................................................................................................650
pushkey........................................................................................................................651
QModeKey....................................................................................................................652
QSysKey.......................................................................................................................653
restoreAlphaLock..........................................................................................................654
Link..........................................................................................................................655
BatTooLowFlash...........................................................................................................657
LIO_RecvData..............................................................................................................658
LIO_SendData..............................................................................................................659
OSCheckLinkOpen.......................................................................................................660
OSLinkClose.................................................................................................................661
OSLinkOpen.................................................................................................................662
OSLinkReset ................................................................................................................663
Lists and Matrices...................................................................................................665
all_tail ...........................................................................................................................669
any_tail.........................................................................................................................670
cmd_sorta.....................................................................................................................671
cmd_sortd.....................................................................................................................672
did_map_aggregate_arg ..............................................................................................673
is_matrix.......................................................................................................................674
is_square_matrix..........................................................................................................675
last_element_index.......................................................................................................676
map_tail........................................................................................................................677
push_augment..............................................................................................................678
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
push_coldim .................................................................................................................679
push_colnorm...............................................................................................................680
push_cross_product.....................................................................................................681
push_cumsum..............................................................................................................682
push_determinant.........................................................................................................683
push_diag.....................................................................................................................684
push_dimension ...........................................................................................................685
push_dot_add...............................................................................................................686
push_dot_div................................................................................................................687
push_dot_mult..............................................................................................................688
push_dot_sub...............................................................................................................689
push_dotproduct...........................................................................................................690
push_eigvc ...................................................................................................................691
push_eigvl ....................................................................................................................692
xxi
push_identity_mat ........................................................................................................693
push_list_to_mat ..........................................................................................................694
push_mat_to_list ..........................................................................................................695
push_matnorm..............................................................................................................696
push_mean...................................................................................................................697
push_median................................................................................................................698
push_mrow...................................................................................................................700
push_mrowadd.............................................................................................................702
push_newlist.................................................................................................................703
push_newmat...............................................................................................................704
push_prodlist................................................................................................................705
push_randmat...............................................................................................................706
push_red_row_ech.......................................................................................................707
push_reversed_tail.......................................................................................................708
push_row_echelon .......................................................................................................709
push_rowadd................................................................................................................710
push_rowdim................................................................................................................711
push_rownorm..............................................................................................................712
push_rowswap..............................................................................................................713
push_sign.....................................................................................................................714
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxii
push_stddev.................................................................................................................715
push_submat................................................................................................................716
push_sumlist.................................................................................................................718
push_transpose_aux....................................................................................................719
push_unitv....................................................................................................................721
push_variance..............................................................................................................722
remaining_element_count............................................................................................723
Table of Contents
Logic........................................................................................................................725
and_onto_top................................................................................................................727
is_equivalent_to............................................................................................................728
is_negative ...................................................................................................................729
is_never0......................................................................................................................730
is_nonnegative .............................................................................................................731
is_nonpositive...............................................................................................................732
is_positive.....................................................................................................................733
is_real...........................................................................................................................734
is_undefined.................................................................................................................735
lead_conjunct_factor_index..........................................................................................736
lead_disjunct_term_index.............................................................................................737
or_onto_top ..................................................................................................................738
push_and......................................................................................................................739
push_but_conjunct_factor ............................................................................................740
push_not.......................................................................................................................741
push_or.........................................................................................................................742
push_when...................................................................................................................743
remaining_conjuncts_index..........................................................................................744
remaining_disjuncts_index...........................................................................................745
replace_top2_with_and ................................................................................................746
replace_top2_with_or...................................................................................................747
Math........................................................................................................................749
are_units_consistent.....................................................................................................755
did_push_anti_deriv .....................................................................................................756
did_push_approx_inflection_point................................................................................757
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
did_push_series ...........................................................................................................758
push_1st_derivative......................................................................................................760
push_abs......................................................................................................................761
push_acos....................................................................................................................762
push_acosh..................................................................................................................763
push_asin.....................................................................................................................764
push_asinh...................................................................................................................765
push_atan.....................................................................................................................766
push_atanh...................................................................................................................767
push_ceiling..................................................................................................................768
push_comb...................................................................................................................769
push_comdenom..........................................................................................................770
push_conj.....................................................................................................................771
push_constant_terms...................................................................................................772
xxiii
push_cos......................................................................................................................773
push_cosh....................................................................................................................774
push_def_int.................................................................................................................775
push_degrees...............................................................................................................776
push_dot_exponentiate................................................................................................777
push_exp......................................................................................................................778
push_expand................................................................................................................779
push_exponentiate.......................................................................................................780
push_extended_prod....................................................................................................781
push_factor...................................................................................................................782
push_factorial...............................................................................................................784
push_floor.....................................................................................................................785
push_fractional_part.....................................................................................................786
push_gcd_then_cofactors ............................................................................................787
push_im........................................................................................................................788
push_integer_part.........................................................................................................789
push_integer_quotient..................................................................................................790
push_integer_remainder...............................................................................................791
push_left.......................................................................................................................792
push_lim.......................................................................................................................794
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxiv
Table of Contents
push_ln.........................................................................................................................795
push_log10...................................................................................................................796
push_make_proper.......................................................................................................797
push_max.....................................................................................................................798
push_max1...................................................................................................................799
push_max2...................................................................................................................800
push_mid......................................................................................................................801
push_min......................................................................................................................803
push_min1....................................................................................................................804
push_min2....................................................................................................................805
push_mod.....................................................................................................................806
push_next_arb_int........................................................................................................807
push_next_arb_real......................................................................................................808
push_nint......................................................................................................................809
push_nth_derivative .....................................................................................................810
push_perm....................................................................................................................811
push_phase..................................................................................................................812
push_poly_qr................................................................................................................813
push_r_cis....................................................................................................................814
push_rand.....................................................................................................................815
push_radians................................................................................................................816
push_randpoly..............................................................................................................817
push_re.........................................................................................................................818
push_rec_to_angle.......................................................................................................819
push_right.....................................................................................................................820
push_rotate...................................................................................................................822
push_round...................................................................................................................824
push_sequence............................................................................................................825
push_shift.....................................................................................................................827
push_simult ..................................................................................................................829
push_sin.......................................................................................................................831
push_sin2.....................................................................................................................832
push_sinh.....................................................................................................................833
push_sqrt......................................................................................................................834
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
push_square.................................................................................................................835
push_standardize.........................................................................................................836
push_summation..........................................................................................................837
push_tan.......................................................................................................................838
push_tanh.....................................................................................................................839
push_trig.......................................................................................................................840
raise_to_top..................................................................................................................841
replace_top2_with_pow................................................................................................842
Memory Management.............................................................................................843
HeapAlloc.....................................................................................................................845
HeapAllocHigh..............................................................................................................846
HeapAllocHighThrow....................................................................................................847
HeapAllocThrow...........................................................................................................848
HeapAvail.....................................................................................................................849
xxv
HeapCompress.............................................................................................................850
HeapDeref....................................................................................................................851
HeapFree......................................................................................................................852
HeapFreeIndir...............................................................................................................853
HeapGetLock................................................................................................................854
HeapLock .....................................................................................................................855
HeapMax......................................................................................................................856
HeapMoveHigh.............................................................................................................857
HeapPtrToHandle.........................................................................................................858
HeapRealloc.................................................................................................................859
HeapShuffle..................................................................................................................860
HeapSize......................................................................................................................861
HeapUnlock..................................................................................................................862
HeapWalk.....................................................................................................................863
HLock ...........................................................................................................................865
memcpy........................................................................................................................866
memmove.....................................................................................................................867
memset.........................................................................................................................868
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxvi
Table of Contents
Menus .....................................................................................................................869
DynMenuAdd................................................................................................................871
DynMenuChange..........................................................................................................873
FKeyI_H........................................................................................................................874
MenuAddIcon ...............................................................................................................875
MenuAddText...............................................................................................................876
MenuBegin ...................................................................................................................878
MenuCheck ..................................................................................................................880
MenuEnd......................................................................................................................881
MenuFlags....................................................................................................................882
MenuGetTopRedef.......................................................................................................883
MenuItemDef................................................................................................................884
MenuKey ......................................................................................................................885
MenuLoad.....................................................................................................................886
MenuNew .....................................................................................................................888
MenuOff........................................................................................................................890
MenuOn........................................................................................................................891
MenuPopup..................................................................................................................892
MenuSubStat................................................................................................................893
MenuTopRedef.............................................................................................................894
MenuTopSelect ............................................................................................................897
MenuTopStat................................................................................................................898
PopupAddText..............................................................................................................899
PopupBegin..................................................................................................................900
PopupBeginDo .............................................................................................................902
PopupClear...................................................................................................................903
PopupDo.......................................................................................................................904
PopupNew....................................................................................................................905
PopupText....................................................................................................................906
QMenuTopSelect..........................................................................................................907
Mode Screen Settings............................................................................................909
MO_currentOptions......................................................................................................911
MO_digestOptions........................................................................................................912
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
Operating System ...................................................................................................913
EV_captureEvents........................................................................................................915
EV_defaultHandler .......................................................................................................918
EV_getc........................................................................................................................920
EV_restorePainting.......................................................................................................921
EV_sendEvent..............................................................................................................922
EV_setCmdCheck........................................................................................................923
EV_setCmdState..........................................................................................................924
EV_setFKeyState.........................................................................................................925
EV_startApp .................................................................................................................926
EV_suspendPainting....................................................................................................927
EV_switch.....................................................................................................................928
EX_getBasecodeParmBlock ........................................................................................929
FL_getHardwareParmBlock .........................................................................................930
xxvii
handleRclKey ...............................................................................................................932
handleVarLinkKey ........................................................................................................933
LOC_formatDate ..........................................................................................................934
LOC_getLocalDateFormat............................................................................................935
LOC_localVersionDate.................................................................................................936
Program I/O Screen................................................................................................937
cmd_clrio......................................................................................................................939
cmd_disp......................................................................................................................940
Solver......................................................................................................................941
push_csolve..................................................................................................................943
push_czeros.................................................................................................................944
push_nSolve.................................................................................................................945
push_solve ...................................................................................................................946
push_zeros...................................................................................................................947
Statistics..................................................................................................................949
cmd_showstat...............................................................................................................951
push_randnorm ............................................................................................................952
QstatRcl........................................................................................................................953
statEnd .........................................................................................................................954
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxviii
statFree ........................................................................................................................955
statStart........................................................................................................................956
Table of Contents
Status Line..............................................................................................................959
ST_angle......................................................................................................................961
ST_busy .......................................................................................................................962
ST_eraseHelp...............................................................................................................963
ST_folder......................................................................................................................964
ST_helpMsg .................................................................................................................965
ST_progressBar ...........................................................................................................966
ST_progressDismiss ....................................................................................................967
ST_progressIncrement.................................................................................................968
ST_progressUpdate .....................................................................................................969
ST_readOnly ................................................................................................................970
Strings.....................................................................................................................971
cmpstri..........................................................................................................................973
FirstNonblank ...............................................................................................................974
hStrAppend...................................................................................................................975
memchr.........................................................................................................................976
memcmp.......................................................................................................................977
memucmp.....................................................................................................................978
push_char.....................................................................................................................979
push_instring................................................................................................................980
push_ord.......................................................................................................................981
push_str_to_expr..........................................................................................................982
push_string...................................................................................................................984
push_zstr......................................................................................................................985
sprintf............................................................................................................................986
strcat.............................................................................................................................989
strchr.............................................................................................................................990
strcmp...........................................................................................................................991
strcpy............................................................................................................................992
strcspn..........................................................................................................................993
stricmp..........................................................................................................................994
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
strlen.............................................................................................................................995
strncat...........................................................................................................................996
strncmp.........................................................................................................................997
strncpy..........................................................................................................................998
strpbrk...........................................................................................................................999
strrchr .........................................................................................................................1000
strspn..........................................................................................................................1001
strstr............................................................................................................................1002
strtok...........................................................................................................................1003
XR_stringPtr...............................................................................................................1004
Symbol Table Utilities...........................................................................................1007
AddSymToFolder........................................................................................................1009
DerefSym....................................................................................................................1010
FindSymInFolder........................................................................................................1011
xxix
FolderAdd...................................................................................................................1012
FolderCount................................................................................................................1014
FolderCur....................................................................................................................1015
FolderDel....................................................................................................................1017
FolderFind ..................................................................................................................1018
FolderGetCur..............................................................................................................1019
FolderOp.....................................................................................................................1020
FolderRename............................................................................................................1021
HSymDel ....................................................................................................................1022
MakeHsym..................................................................................................................1024
push_getfold...............................................................................................................1025
push_setfold...............................................................................................................1026
ResetSymFlags..........................................................................................................1028
SetOK.........................................................................................................................1029
SymAdd......................................................................................................................1031
SymDel.......................................................................................................................1032
SymFind .....................................................................................................................1033
SymFindFirst ..............................................................................................................1034
SymFindFoldername..................................................................................................1036
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxx
SymFindHome............................................................................................................1038
SymFindMain..............................................................................................................1039
SymFindNext..............................................................................................................1041
SymFindPrev..............................................................................................................1042
VarCreateFolderPopup...............................................................................................1043
VarRecall....................................................................................................................1047
VarStore .....................................................................................................................1049
Table of Contents
Text Editing...........................................................................................................1051
CB_fetchTEXT............................................................................................................1053
CB_replaceTEXT........................................................................................................1054
TE_close.....................................................................................................................1055
TE_empty...................................................................................................................1056
TE_focus ....................................................................................................................1057
TE_handleEvent.........................................................................................................1058
TE_indicateReadOnly.................................................................................................1060
TE_isBlank .................................................................................................................1061
TE_open.....................................................................................................................1062
TE_openFixed............................................................................................................1065
TE_pasteText.............................................................................................................1067
TE_reopen..................................................................................................................1069
TE_reopenPlain..........................................................................................................1070
TE_select....................................................................................................................1071
TE_shrinkWrap...........................................................................................................1072
TE_unfocus ................................................................................................................1073
Timer.....................................................................................................................1075
OSFreeTimer..............................................................................................................1077
OSRegisterTimer........................................................................................................1078
OSTimerCurVal..........................................................................................................1079
OSTimerExpired.........................................................................................................1080
OSTimerRestart..........................................................................................................1081
Token Operations..................................................................................................1083
get_key_ptr.................................................................................................................1085
GetTagStr...................................................................................................................1087
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
NG_RPNToText .........................................................................................................1088
NG_tokenize...............................................................................................................1090
push_parse_text.........................................................................................................1091
Utilities...................................................................................................................1093
AB_getGateArrayVersion...........................................................................................1095
AB_prodid...................................................................................................................1096
AB_prodname.............................................................................................................1097
AB_serno....................................................................................................................1098
abs..............................................................................................................................1099
cmd_newprob.............................................................................................................1100
div...............................................................................................................................1101
EX_getArg..................................................................................................................1102
EX_getBCD................................................................................................................1103
HToESI.......................................................................................................................1104
xxxi
KB_89.........................................................................................................................1105
labs.............................................................................................................................1106
ldiv..............................................................................................................................1107
NeedStack..................................................................................................................1108
strtod...........................................................................................................................1109
strtol............................................................................................................................1111
WordInList ..................................................................................................................1113
Variable Name Utilities.........................................................................................1115
CheckReservedName ................................................................................................1117
CheckSysFunc ...........................................................................................................1118
HSYMtoName.............................................................................................................1120
is_variable ..................................................................................................................1121
StrToTokN..................................................................................................................1122
SymSysVar.................................................................................................................1123
TokenizeSymName....................................................................................................1124
TokToStrN..................................................................................................................1125
Variables...............................................................................................................1127
checkCurrent..............................................................................................................1129
cmd_archive...............................................................................................................1130
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxxii
cmd_copyvar..............................................................................................................1131
cmd_delfold................................................................................................................1132
cmd_delvar.................................................................................................................1133
cmd_lock ....................................................................................................................1134
cmd_movevar.............................................................................................................1135
cmd_newfold ..............................................................................................................1136
cmd_rename...............................................................................................................1137
cmd_unarchiv.............................................................................................................1139
cmd_unlock ................................................................................................................1140
EX_stoBCD ................................................................................................................1141
push_assignment .......................................................................................................1142
Table of Contents
Windows................................................................................................................1143
CalcBitmapSize..........................................................................................................1145
DrawWinBorder..........................................................................................................1146
MakeScrRect..............................................................................................................1147
MakeWinRect.............................................................................................................1148
ScrToWin....................................................................................................................1149
SetWinClip..................................................................................................................1150
WinActivate.................................................................................................................1151
WinAttr........................................................................................................................1152
WinBackground..........................................................................................................1153
WinBackupToScr........................................................................................................1154
WinBeginPaint............................................................................................................1155
WinBitmapGet ............................................................................................................1156
WinBitmapPut.............................................................................................................1158
WinBitmapSize...........................................................................................................1159
WinBitmapSizeExt......................................................................................................1160
WinChar......................................................................................................................1161
WinCharXY.................................................................................................................1162
WinClose....................................................................................................................1164
WinClr.........................................................................................................................1165
WinDeactivate ............................................................................................................1166
WinDupStat ................................................................................................................1167
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
WinEllipse...................................................................................................................1168
WinEndPaint...............................................................................................................1169
WinFill.........................................................................................................................1170
WinFillTriangle............................................................................................................1171
WinFont......................................................................................................................1172
WinHeight...................................................................................................................1173
WinHide......................................................................................................................1174
WinHome....................................................................................................................1175
WinLine.......................................................................................................................1176
WinLineExt .................................................................................................................1177
WinLineRel.................................................................................................................1179
WinLineTo ..................................................................................................................1180
WinMoveRel...............................................................................................................1181
WinMoveTo ................................................................................................................1182
xxxiii
WinOpen.....................................................................................................................1183
WinPixGet...................................................................................................................1185
WinPixSet...................................................................................................................1186
WinRect......................................................................................................................1187
WinRemove................................................................................................................1188
WinReOpen................................................................................................................1189
WinScrollH..................................................................................................................1190
WinScrollV..................................................................................................................1192
WinStr.........................................................................................................................1193
WinStrXY....................................................................................................................1195
WinStrXYWrap ...........................................................................................................1196
WinWidth....................................................................................................................1197
Appendix B: Global Variables.................................................................1199
Algebra Utilities .....................................................................................................1203
ARb_int_count............................................................................................................1203
ARb_real_count..........................................................................................................1204
NG_control .................................................................................................................1205
NG_such_that_index..................................................................................................1208
RAtionalize_tol............................................................................................................1209
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxxiv
Table of Contents
Apps......................................................................................................................1211
EV_appA ....................................................................................................................1211
EV_appB ....................................................................................................................1212
EV_appSide................................................................................................................1213
EV_currentApp...........................................................................................................1214
EV_runningApp ..........................................................................................................1215
OO_firstACB...............................................................................................................1216
OO_SuperFrame........................................................................................................1217
FLOATTAB.................................................................................................................1219
IM_re_tol.....................................................................................................................1220
Display ..................................................................................................................1221
CU_cursorState..........................................................................................................1221
ScrRect.......................................................................................................................1222
Error Handling.......................................................................................................1223
errno...........................................................................................................................1223
EV_errorCode.............................................................................................................1224
EStack Utilities ......................................................................................................1225
bottom_estack............................................................................................................1225
estack_max_index......................................................................................................1226
top_estack..................................................................................................................1227
Flash Memory .......................................................................................................1229
FlashMemoryEnd .......................................................................................................1229
Graphing ...............................................................................................................1231
gr_active, gr_other......................................................................................................1231
gr_flags.......................................................................................................................1241
Keyboard...............................................................................................................1243
OSFastArrows............................................................................................................1243
OSModKeyStatus.......................................................................................................1244
Logic......................................................................................................................1245
index_false .................................................................................................................1245
index_true...................................................................................................................1246
Math......................................................................................................................1247
Float0Index.................................................................................................................1247
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
Float1Index.................................................................................................................1248
FloatExp1Index...........................................................................................................1249
FloatHalfIndex ............................................................................................................1250
FloatMinus1Index.......................................................................................................1251
FloatPiIndex................................................................................................................1252
Integer0Index..............................................................................................................1253
Integer1Index..............................................................................................................1254
Integer2Index..............................................................................................................1255
IntegerMinus1Index....................................................................................................1256
Mode Screen Settings...........................................................................................1257
MO_option..................................................................................................................1257
Operating System .................................................................................................1261
EV_flags.....................................................................................................................1261
xxxv
Statistics................................................................................................................1263
RM_Type....................................................................................................................1263
Status Line............................................................................................................1265
ST_flags .....................................................................................................................1265
Strings...................................................................................................................1267
RF_ . . ........................................................................................................................1267
Timer.....................................................................................................................1269
FiftyMsecTic ...............................................................................................................1269
Utilities...................................................................................................................1271
ReleaseDate...............................................................................................................1271
ReleaseVersion..........................................................................................................1272
Appendix C: Macros...............................................................................1273
Character Classification / Conversion...................................................................1275
isalnum.......................................................................................................................1275
isalpha........................................................................................................................1276
isascii..........................................................................................................................1277
iscsym.........................................................................................................................1278
iscsymf........................................................................................................................1279
isdigit ..........................................................................................................................1280
isgreek........................................................................................................................1281
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxxvi
islower ........................................................................................................................1282
isprint..........................................................................................................................1283
isupper........................................................................................................................1284
toascii .........................................................................................................................1285
tolower........................................................................................................................1286
toupper .......................................................................................................................1287
Table of Contents
Dialog....................................................................................................................1289
DlgNotice....................................................................................................................1289
Error Handling.......................................................................................................1291
ENDFINAL..................................................................................................................1291
ENDTRY.....................................................................................................................1292
ER_throw.................................................................................................................... 1293
FINALLY.....................................................................................................................1294
ONERR.......................................................................................................................1295
TRY ............................................................................................................................1296
Operating System .................................................................................................1297
Access_AMS_Global_Variables.................................................................................1297
Appendix D: TI-89 / TI-92 Plus “Small” Character Font ........................1299
Appendix E: TI-89 / TI-92 Plus “Large” Character Font ........................1307
Appendix F: TI-89 / TI-92 Plus “Huge” Character Font .........................1317
Reference List — System Routines .......................................................1329
Reference List — Global Variables........................................................1351
Reference List — Macros.......................................................................1355
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
xxxvii
Figures
Figure 2.1: AMS Event Handler....................................................................................................5
Figure 2.2: Application/OS Interface.............................................................................................6
Figure 3.1: System Block Diagram ...............................................................................................7
Figure 4.1: MATH Menu..............................................................................................................16
Figure 4.2: CHAR Menu..............................................................................................................16
Figure 4.3: AddToMenu Screen Shot .........................................................................................17
Figure 4.4: mPop-upTest Screen Shot .......................................................................................17
Figure 4.5: OverwriteDlg Dialog Box from Example ...................................................................19
Figure 4.6: AMS Fonts................................................................................................................19
Figure 4.7: Example Using the A_REVERSE Attribute...............................................................20
Figure 4.8: Example Using the A_SHADED Attribute.................................................................20
Figure 6.1: Example of ASM Stack Memory...............................................................................28
Figure 7.1: Flash Application File Format...................................................................................31
Figure 7.2: Application RAM and Flash Usage...........................................................................38
Figure 7.3: Linked App Frames...................................................................................................60
Figure 7.4: Redirected App Frame..............................................................................................61
Figure 8.1: Catalog .....................................................................................................................67
Figure 8.2: Catalog Help Dialog..................................................................................................67
Figure 8.3: User Program ...........................................................................................................68
Figure 8.4: User-Defined Catalog...............................................................................................68
Figure 8.5: Help Dialog for User-Defined Catalog ......................................................................68
Figure 11.1: Window Regions...................................................................................................103
Figure 11.2: Screen Shot from Test Menu Example.................................................................117
Figure 13.1: Token Representation of VarName A23456.........................................................135
Figure 17.1: Upper Left Corner of Graph Screen......................................................................190
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xxxviii
Table of Contents
Figure 18.1: TI FLASH Studio Home Screen............................................................................202
Figure 18.2: TI FLASH Studio Menu Bar..................................................................................204
Figure 18.3: TI FLASH Studio Toolbar......................................................................................204
Figure 18.4: File Menu..............................................................................................................205
Figure 18.5: Edit Menu..............................................................................................................206
Figure 18.6: View Menu............................................................................................................207
Figure 18.7: Registers...............................................................................................................208
Figure 18.8: Status Register.....................................................................................................209
Figure 18.9: Watch....................................................................................................................210
Figure 18.10: Project Menu.......................................................................................................211
Figure 18.11: Debug Menu.......................................................................................................212
Figure 18.12: Breakpoints Submenu ........................................................................................213
Figure 18.13: Simulator Menu...................................................................................................214
Figure 18.14: Link Menu...........................................................................................................215
Figure 18.15: Window Menu.....................................................................................................215
Figure 18.16: Help Menu ..........................................................................................................216
Figure 18.17: New Project Screen............................................................................................216
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Table of Contents
xxxix
Tables
Table 3.5: DBus Configuration Register .....................................................................................12
Table 4.1: Available Character Attributes ...................................................................................20
Table 4.2: Character Set.............................................................................................................21
Table 6.1: AMS C Data Types....................................................................................................27
Table 7.1: Flash Header Format.................................................................................................32
Table 7.2: Application Header Format........................................................................................33
Table 7.3: Internal Names of Built-in Applications......................................................................34
Table 7.4: Relocation Map Format..............................................................................................35
Table 9.1: Keypress Translations ...............................................................................................89
Table 9.2 Keypress Actions........................................................................................................90
Table 11.1: Screen vs. Window Coordinates............................................................................101
Table 11.2: Dialog Flags and Corresponding Fields.................................................................113
Table 11.3: Call Back Function Return Values.........................................................................114
Table 14.1: Data Tag Values....................................................................................................146
Table 14.2: Data Object for a Non-Negative or Negative Integer.............................................147
Table 14.3: Data Object for a Positive or Negative Fraction.....................................................147
Table 14.4: Data Object for a Floating-Point Number...............................................................148
Table 14.5: Data Object for a List.............................................................................................148
Table 14.6: Data Object for a Matrix.........................................................................................149
Table 14.7: Data Object for a Data Variable.............................................................................150
Table 14.8: Data Object for a Text Variable..............................................................................151
Table 14.9: Valid first characters for a Text Variable Data Object............................................151
Table 14.10: Data Object for a String Variable.........................................................................151
Table 14.11: Data Object for a Graph Database ......................................................................152
Table 14.12: Data Object for a PIC...........................................................................................156
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
xl
Table of Contents
Table 14.13: Data Object for a Tokenized Program or Function ..............................................157
Table 14.14: Flag 1 Values.......................................................................................................158
Table 14.15: Data Object for a Program or Function Stored in Text.........................................159
Table 14.16: Data Object for Third Party Data..........................................................................160
Table 14.17: Data Object for an Assembly Program ................................................................160
Table 15.1: Examples of Polish Representations.....................................................................162
Table 15.2: Tagged Integer Examples......................................................................................164
Table 15.3: Tagged Fraction Examples....................................................................................164
Table 15.4: Variable Name Examples ......................................................................................165
Table 15.5: Symbolic Constants...............................................................................................166
Table 15.6: Examples of Single Argument Functions and Operators.......................................167
Table 15.7: Examples of Functions of Two Arguments ............................................................167
Table 15.8: Examples of Arithmetic Operations and the Store Operation................................168
Table 15.9: Examples of Other Binary Operations ...................................................................168
Table 15.10: Secondary Tag Examples....................................................................................169
Table 15.11: Command Tag Examples ....................................................................................170
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
1. Introduction
1.1. Purpose of this Guide
The purpose of this guide is to provide the application developer with a thorough
understanding of the ideas and concepts necessary for application design on the
TI-89 / TI-92 Plus Operating System (OS). This Operating System is referred to
as the Advanced Mathematics Software (AMS). Key components of the AMS
such as event-driven architecture, memory management, and the user interface
are discussed in detail. Sample code is provided for developers of both Assembly
Language Programs (ASM) and Flash applications.
1.2. Chapter Layout
1
Chapter 2,
event-driven architecture of the AMS. It also discusses the three types of
applications a user may develop: TI-BASIC programs, ASMs, and downloadable
Flash applications.
Chapter 3,
and tables that include information on memory, interrupt vectors, and ASIC
registers.
Chapter 4,
windows, menus, toolbars, pop-ups, dialog boxes, fonts, and the status line.
Chapter 5,
comparison of downloadable Flash applications and Assembly language
programs. The limitations and advantages of each are emphasized. This is a
good reference for ASM developers who are considering Flash application
development.
Chapter 6,
ideas and concepts necessary for ASM design. A sample ASM program is
provided.
Chapter 7,
components and physical layout of an application. Sample applications are
provided. Also included are instructions on how an application can take
advantage of TI-BASIC extensions, a shared-code library, and language
localization.
The 68000 TI AMS Operating System Overview
The TI-89 / TI-92 Plus Hardware Overview
User Interface Overview
Flash Applications vs. ASM Programs
Assembly Language Programming Overview
Flash Application Layout
, provides brief explanations and examples of
, presents a side-by-side
, contains detailed descriptions of the crucial
, introduces the
, provides block diagrams
, discusses the general
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
2
Chapter 1: Introduction
Chapter 8,
Integrating a Flash Application
, discusses areas of the operating
system that an application may choose to integrate itself with such as the
catalog, the mode screen, and VAR-LINK. More details are provided for
interfacing with TI-BASIC. This chapter also provides tips on optimizing code
space and identifying the active AMS version.
Chapter 9,
Application Control Flow
, contains vital information for the Flash
application developer. The AMS event-driven architecture is further explained,
complete with a detailed list of commands an application can expect to receive.
Information on keyboard events and menu processing can also be found in this
chapter.
Chapter 10,
Error Handling
, describes the AMS implementation of error handling.
It includes explanations of how an application can throw errors, catch errors, and
clean up when an error occurs.
Chapter 11,
Creating the User Interface
interface components introduced in Chapter 3,
, gives in-depth detail about the user
User Interface Overview
. A
sample application which illustrates the use of these components is provided.
The resource compiler is also discussed in this chapter.
Chapter 12,
Basic Text Editing Facility
, describes how an application can use text
records to get information from the application user. Sample code illustrating the
use of the text edit facility is provided.
Chapter 13,
Memory Management
, provides explanations of dynamic data
storage, application data storage, and variable management.
Chapter 14,
Data Types
, defines the structure of the twelve data types supported
by the AMS.
Chapter 15,
Expressions and the Expression Stack
, contains information
important for applications that use the math engine for numerical or symbolic
analysis. The internal representation of expressions is discussed in detail and
augmented with examples.
Chapter 16,
Working with Numbers
, describes the two separate number
subsystems that are built into the AMS operating system. It also discusses the
use of the expression stack for performing numeric operations.
Chapter 17,
Graphing
, contains a thorough explanation of the Graph application
as well as instructions on how graphing can be incorporated into a downloadable
application. Two graph mode, graphing functions, and its usage of screen and
memory are detailed.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 1: Introduction
3
Chapter 18,
TI
FLASH
TI FLASH Studio™ (IDE) Overview
Studio. It provides information on PC requirements, the installation
process, and the interface. It also contains an example that steps through the
application development process.
1.3. Conventions Used in this Guide
text indicates the name of a function, macro, or global variable that is
Bold
described in the System Routines (Entry Points) section.
Italicized
with a function prototype.
The
text indicates the name of an input parameter. It is usually associated
Courier
font is used to distinguish Assembly or C program text.
, is the users manual for
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
4
Chapter 1: Introduction
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
2. The 68000 TI AMS Operating System Overview
g
p
p
p
g
The AMS calculator Operating System (OS) implements a classic cooperative
event-driven architecture. The event manager interfaces with the device drivers
to determine when something important has happened such as a keypress or a
timer interrupt. This information is then packaged into an event message and
sent to the application currently active in the calculator screen. An application
reacts to event messages by performing some action such as moving its cursor
or repainting its window. After responding to an event message, the application
then returns to the event manager and awaits the next event. The event manager
puts the calculator into low power mode until another event occurs. This process
is illustrated in Figure 2.1.
com
leted
5
Event
Mana
er
Application
Decode
Handle
Idle
event occurs
com
leted
Figure 2.1: AMS Event Handler
and
ackage
event
event
Default
event
handlin
does not
know how
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
6
y
y
g
g
y
p
g
y
Chapter 2: The 68000 TI AMS Operating System Overview
Many operating system routines are available to the application as shown in
Figure 2.2. The address of the jump table, a table of Operating System entry
points and data structures, is stored in memory location 0xC8. Through the jump
table, applications, and ASM programs can access low-level device drivers, the
event manager, memory manager, symbol table manager, graphical user
interface library, computer algebra system, math package, and utility routines.
Applications
Event
Mana
Low-Level Drivers: Power, LCD,
Ke
er
Graphical
User Interface
Librar
board, Link Port, Timer
Symbol Table
Memory Manager Math Package
Mana
Jum
er
Table
Computer
ebra
Al
stem
S
Utilit
Routines
Figure 2.2: Application/OS Interface
TI-BASIC programming language provides ease of programming at the expense
of speed and control of every calculator feature. ASM programs are routines
written in C or 68000 assembly language, both of which give the software
developer much greater control over the calculator. ASM programs can be called
from TI-BASIC and executed from the Home screen author line.
ASM programs are generally small (≤ 8 K for AMS 2.03 and ≤ 24 K for AMS 2.04)
and execute in RAM. They are intended to offer the same speed and efficient
hardware access as Flash applications but as subroutines called from TI-BASIC
instead of fully integrated applications.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
3. The TI-89 / TI-92 Plus Hardware Overview
3.1. Overview
The TI-89 and TI-92 Plus Graphing calculators provide a platform for writing
interactive applications that utilize input, processing, storage, communication,
and presentation. When creating applications, understanding the capabilities and
limitations of the platform are important to creating a good interface to the user.
Pictured below is a block diagram of the TI-89 / TI-92 Plus from a programmer’s
perspective.
Application Specific
Application Specific
Integrated Circuit
Integrated Circuit
(ASIC)
(ASIC)
7
68000
68000
Central Processing Unit
Central Processing Unit
Random Access
Random Access
Memory (RAM)
Memory (RAM)
Flash
Flash
Read Only Memory (ROM)
Read Only Memory (ROM)
Figure 3.1: System Block Diagram
From the block diagram, the specific details of the components are:
An ASIC, which contains all of the “glue logic” that allows the different
•
components to communicate with each other, as well as specialized registers
for system control.
Liquid Cry s tal Display
Liquid Cry s tal Display
(LCD)
(LCD)
Keyboard
Keyboard
Dbus Serial Input/Output
Dbus Serial Input/Output
A Motorola 68000 CPU.
•
256 K bytes of RAM.
•
2 MB bytes of Flash ROM.
•
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
8
A black and white LCD display (100 lines of 160 pixels for the TI-89, 128 lines
•
of 240 pixels for the TI-92 Plus).
A set-line / scan-line style matrix keyboard.
•
A three line (D0, D1, and ground) serial IO interface.
•
This chapter describes in some detail the locations that an application may need
to access in order to accomplish a task. For the most part, interaction with the
hardware can be accomplished through the use of specific entry points. To
remain compatible with other applications and future revisions of the OS, the
developer should utilize entry points wherever possible.
3.2. Memory Map
Memory for the calculators consists of RAM memory, Flash memory, and
address space within the ASIC. Memory is limited and optimization is important
when developing for these platforms. Additionally, since Flash memory stores the
OS, certificates, applications, and does not have infinite life, more restrictions are
placed on its use.
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
The OS handles all memory allocation through the heap or file system. See
chapter
13. Memory Management
. For reference, the memory map is shown in
Table 3.1.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
TI-89 Contents TI-92 Plus
RAM
9
0x000000
0x0003FF
0x000400
0x0041FF
0x004200
0x004203
0x004204
0x004BFF
0x004C00
0x005AFF
0x005B00
(Border can vary)******
(Border can vary)******
0x3FFFF
0x200000
0x20FFFF
0x210000
0x211FFF
Vectors
See section
User Stack 0x000400
0xDEADDEAD
(Fence)
Supervisor Stack 0x004204
LCD Buffer 0x004C00
System bss and
data segments
Heap ****** (Border can vary)
3.2.1. Vector Table
0x000000
0x0003FF
0x0041FF
0x004200
0x004203
0x004BFF
0x005AFF
0x005B00
****** (Border can vary)
0x3FFFF
Flash ROM
Boot Sector 0x400000
0x40FFFF
Certificate Memory 0x410000
0x411FFF
0x212000
0x21FFFF
0x220000
(Border can vary)******
(Border can vary)******
0x3FFFFF
0x600000
0x7FFFFF
3.2.1. Vector Table
In order to modify the interrupt vectors, it is necessary to first enable writing to
this region by accessing the system configuration register at 0x600000 (see
Table 3.1).
System Privileged 0x412000
0x41FFFF
Operating System 0x420000
******(Border can vary)
Archive Memory ******(Border can vary)
0x5FFFFF
ASIC
See section
Table 3.1: Memory Map
3.2.1. Vector Table
0x600000
0x7FFFFF
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
10
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
Address 68000 CPU Vector TI-89 / TI-92 Plus Usage
0x000000 Initial supervisor stack pointer Initial supervisor stack pointer
0x000004 Poi n t e r t o operating system entry point Pointer to operating system entry point
0x000008 Bus error Not used
0x00000C Address error Not used
0x000010 Illegal instruction Not used
0x000014 Zero divide Not used
0x000018 CHK instruction Not used
0x00001C TRAPV instruction Not used
0x000020 Privilege violation Not used
0x000024 Trace Not used
0x000028 Line 1010 emulator Error handler
0x00002C Line 1111 emulator System jump table call interface
0x000030
0x00005F
0x000060 Spurious interrupt Not used
0x000064 Level 1 interrupt autovector Heartbeat timer (keyboard scan)
0x000068 Level 2 interrupt autovector Key press
0x00006C Level 3 interrupt autovector One second timer (not used)
0x000070 Level 4 interrupt autovector DBus IO
0x000074 Level 5 interrupt autovector System timer
0x000078 Level 6 interrupt autovector On key
0x00007C Level 7 interrupt autovector Stack overflow
0x000080
0x000093
0x000094
0x0000A3
0x0000A4
0x0000AC
0x0000B0
0x0000BB
0x0000BC Trap 15 System reserved
0x0000C0 Unassigned / reserved Simple ROM detect constant —
0x0000A8 Unassigned / reserved Address of system call jump table
0x0000AC
0x0003FF
(Unassigned, reserved) Not used
Trap 0 – 4 System reserved
Trap 5 – 8 Not used
Trap 9 – 11 System reserved
Trap 12 – 14 Not used
0xFF0055AA
Not used
TI-89 / TI-92 Plus Developer Guide
Table 3:2: Vector Table
Not for Distribution
Beta Version January 26, 2001
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
3.3. ASIC registers
When accessing the ASIC registers, it is important to modify only the intended
bits.
0x600000 System Configuration — Detect stack overflow.
876643 2 10
Table 3.3: System Configuration Register
When Bit 2 is set, logic is enabled that triggers a level 7 interrupt on any write to
addresses 0xE000000 through 0xFFFFFF and 0x000000 through 0x00003FF.
This mechanism is used to detect stack overflow without the penalty of a
software stack probe.
11
Stack protect
enable.
0x600004 System sleep / wake-up — Stop the system oscillator to preserve power.
Specify wake-up condition. Interrupt level
required for wake-up.
8765 4 3210
System
timer
Table 3.4: System Sleep Register
DBus IO Not used Key
interrupt
Heartbeat
timer
Writing to this register will stop the system oscillator. The system oscillator is
restarted by any interrupt whose corresponding bit is set to one. Interrupts level 6
and 7 always restart the oscillator.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
12
0x60000C DBus configuration / status (IE = Interrupt Enable)
Control Status
1514131211109876543210
AE LD LTO CLE CAIE CTX CRX SLE STX SRX SLI SA
AE Autostart enable
LD Link disable
LTO Link time-out disable
CLE Control Link error IE
CAIE Control Autostart IE
CTX Control TX buffer empty IE
CRX Control RX buffer full IE
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
Table 3.5: DBus Configuration Register
SLE Status Link error
STX Status TX buffer empty
SRX Status RX buffer full
SLI Status Link interrupt
SA Status Autostart
DBus is a three line serial IO interface; D0, D1 and ground. The following two
registers are used to send and receive data through the DBus port. Reading the
DBus status register resets that register.
0x60000E Link Data — Send / receive data through the link port.
Low High
15141312 11 10 9 8 76543210
D1 In D0 In D1 Out D0 Out RX / TX buffer
Table 3.6: Link Register
Autostart works in conjunction with the sleep/wake up register. If this bit is set
and bit three of the sleep/wake-up register is set, the system will wake on DBus
activity.
Link disable can be used to allow for direct monitoring of the DBus lines (see
next register). When this bit is set, the state machine and barrel shifter that
decode the DBus protocol and perform serial to parallel conversion are disabled.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
The DBus protocol specifies a maximum bit time of two seconds. Link time-out
occurs if D0 or D1 remains low for longer than this time. Bit 13, when set,
disables the link time-out. If this bit is enabled, and D0 or D1 remain low for
longer than two seconds after the state machine has started to decode a byte, a
link interrupt is triggered and bit 7 is set to data error.
Bits 8–11 allow for enabling or disabling their corresponding interrupts. Bits 2–7
allow monitoring of the link port. These registers are modeled on RS232
control/status registers; programming serial IO on the TI-89 / TI-92 Plus is
somewhat akin to writing an RS232 handler.
0x600014 Clock configuration — Clock / LCD control.
876543 2 1 0
13
One second
timer
Table 3.7: Clock Configuration Register
LCD On
Writing a 1 to Bit 2 of this register will trigger an autolevel 3 interrupt once per
second. Writing a 1 to Bit 0 of this register blanks the LCD.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
14
Chapter 3: The TI-89 / TI-92 Plus Hardware Overview
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
4. User Interface Overview
The TI-92 Plus has a display of 240 by 128 pixels. The TI-89 display size is 160
by 100 pixels. On both calculators, the display is divided into two regions: the
window region and the status line. The bottom seven lines of the display are
always used for the status line. The remaining lines constitute the window region
which is available to the app. The window region is shared with the app’s toolbar
(if it has one) which is normally in the top 18 pixels of the display of the
TI-92 Plus and the top 16 pixels of the TI-89. The window region will be different
if an app is running in split screen mode (an app is given the size of its window
region when it is started).
The user interface consists of windows, menus, dialog boxes, fonts, and the
status line. An overview of these is presented in the following sections.
4.1. Windows
15
All characters, lines, figures, and images that appear on the display must be
drawn to an open window. Note that menus and dialog boxes open and close
their own windows and that dialog box windows may overlap the app’s toolbar
(dialog boxes are modal so the app’s toolbar is inactive when a dialog box is
active). Window routines exist to:
Open, resize, and close windows
•
Draw characters, strings, lines, ellipses, rectangles, and pixels
•
Fill regions (rectangular or triangular)
•
Store and recall bitmaps
•
Scroll horizontally or vertically
•
If an app opens a window, that window must eventually be closed. All output to a
window is clipped and will not exceed the window boundaries. An app’s main
window normally has no border but if it is in split screen mode, then it has a
two-pixel border (one pixel thick if not active, two pixels thick if the active
window). Note that by convention, windows that are overlapped on-top of the
main window, such as dialog boxes, have single pixel borders and usually have
rounded borders unlike pop-ups.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
16
4.2. Menus
Menus allow the user to select an item from a hierarchical list of items. There are
two formats: toolbars and pop-ups. Toolbars normally are placed at the top of the
display and accessed with the function keys (even though they may be placed
anywhere including within dialog boxes). Pop-ups “pop-up” over the display and
are not attached to any toolbar. The MATH and CHAR keys bring up pop-ups as
shown in Figures 4.1 and 4.2.
Chapter 4: User Interface Overview
Figure 4.1: MATH Menu Figure 4.2: CHAR Menu
Menus can be defined with the resource compiler (static),
MenuNew
(dynamic)
or both (the core menu is defined with the resource compiler which is then loaded
into memory with the
MenuLoad
function so that it can be modified). The
following example shows how a menu is defined by the resource compiler (see
the
MenuLoad
function for an example using this menu as a core menu and
then adding to it). This menu is shown in Figure 4.3.
TOOLBAR AddToMenu, RC_NO_IDS, 0, 240 {
"TOP 1", 10 {
"SUB 1", 11
"SUB 2", 12
}
"TOP 2", 20 {
}
}
In the above example, the numbers 10, 11, 12, and 20 are menu IDs. A menu ID
is an integer in the range from 1 to 4095 (0xFFF) which can be explicitly
assigned by the creator of the menu or generated by the resource compiler. In
the following example, MID_1, MID_2 and MID_CORRECT will have the values
1, 2, and 3 respectively, as generated by the resource compiler. This menu is
shown in Figure 4.4.
POPUP mPopupTest, 0, 0 {
"POPUP 1", MID_1
"POPUP 2", MID_2
"SELECT THIS", MID_CORRECT
}
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 4: User Interface Overview
Figure 4.3: AddToMenu Screen Shot Figure 4.4: mPop-upTest Screen Shot
Menus are limited to three levels (level one being the toolbar or initial pop-up).
4.2.1. Toolbars
The function keys are normally used to select items from an app’s toolbar.
Toolbars are drawn with
structure to hold additional information about the menu — such as checkmark
and enable/disable status. If the user presses a function key, it is passed to
MenuKey
item selected is returned. Finally
to handle the entire menu selection process and the menu ID of the
MenuBegin. MenuBegin
MenuEnd
is called to close the menu.
17
also creates a heap-based
There are several functions for dealing with dynamic menus. Briefly they are:
MenuNew
DynMenuAdd,
DynMenuChange
MenuLoad
4.2.2. Pop-ups
There are three kinds of pop-ups which can be used depending on the features
needed: static pop-ups, dynamic pop-ups, and dynamic pop-ups with menu
features (checkmarks, grayed-out). Like toolbars, pop-ups are limited to three
levels with the initial pop-up being the first level.
4.2.2.1. Static Pop-ups
The simplest use of pop-ups is to define a static pop-up with the resource
compiler and then execute it with the
— Create an empty dynamic menu.
— Add to or change a dynamic menu item.
— Load a static menu created with the resource compiler so that
it can be modified with
MenuPopup
DynMenuChange
function.
and
DynMenuAdd
.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
18
4.2.2.2. Dynamic Pop-ups
Dynamic pop-ups can be created using the following functions:
Chapter 4: User Interface Overview
PopupNew
DynMenuAdd
DynMenuChange
PopupAddText
PopupChangeText
PopupClear
PopupDo
,
,
— Create an empty dynamic pop-up.
— Add to or change a dynamic pop-up.
— Basically do the same thing as
DynMenuChange
— Empty out a dynamic pop-up so the handle can at least be
reused in case there are other functions, like dialog boxes,
that need to keep the same handle.
— Execute a dynamic pop-up (do not use
returning the item selected by the user.
4.2.2.3. Dynamic Pop-ups with Menu Features
Static and dynamic pop-ups, as defined in the preceding two sections, do not
have menu features like checking (adding/removing checkmarks from individual
items) and the ability to gray-out individual items. In order to have those features,
there are two additional functions.
MenuBegin
MenuSubStat
PopupBeginDo
and returns an additional handle that can be passed to
and
MenuCheck
to actually execute the pop-up. If
new handle, both it and the handle returned from
PopupBegin
functions. This new handle is then passed to
DynMenuAdd
but for text only.
MenuPopup
creates a structure similar to
MenuEnd
PopupNew
is called with this
are freed.
and
),
4.3. Dialog Boxes
Dialog boxes provide a consistent method for inputting data from the user. A
dialog box may consist of headers with buttons, text fields, pop-ups or edit fields.
As with menus, dialog boxes can be built statically with the resource compiler or
dynamically. Unlike dynamic menus, dynamic dialog boxes cannot be modified
once they are created.
The routine to execute a dialog box and get back input from the user is called
Dialog
box, one for the pop-ups and another for the edit fields. Dynamic dialogs are
created with the
The following example shows how a dialog is defined for the resource compiler.
DIALOG OverwriteDlg, 0, 0, OverwriteCallBack {
TEXT, {DF_OWNER_DRAW, 8, 15}
POPUP, {DF_TAB_ELLIPSES, DLG_DEF_X0, 28}, “Overwrite?”, OverwritePopup, 0
EDIT, {DF_TAB_ELLIPSES, DLG_DEF_X0, 41}, “New name”, 0, 17, 18
HEADER, {0,0,0}, “Receive”, PDB_OK, PDB_CANCEL
}
TI-89 / TI-92 Plus Developer Guide
. It is passed two arrays that contain the initial and final input for the dialog
DialogNew
function and executed with the
Not for Distribution
DialogDo
Beta Version January 26, 2001
function.
Chapter 4: User Interface Overview
Figure 4.5: OverwriteDlg Dialog Box from
Example
This example dialog shown in Figure 4.5 contains text drawn by the caller of the
Dialog
resource file (
(which are always placed at the bottom of the dialog box). The symbol
OverwriteCallBack
routine and the user code.
routine (
OverwritePopup
DF_OWNER_DRAW
is a user supplied function that interfaces between the
19
), a pop-up defined elsewhere in the
), an edit field, and a header with two buttons
Dialog
4.4. Fonts
There are three fonts used in the AMS: Small (F_4x6), Large (F_6x8), and Huge
(F_8x10). The Small font is used in the status bar and dialog box headers. The
Small font is also used in the dialog boxes and toolbars on the TI-89. Some of
the Small font characters, especially the international characters, are difficult to
distinguish from each other and so care should be exercised when using the
Small font. The Large font is used almost everywhere else, except in authoring
lines on the TI-92 Plus, which uses the Huge font. Figure 4.6 displays the three
different fonts.
Figure 4.6: AMS Fonts
An app can control which of the three system fonts it uses in its own windows.
Characters are drawn to the display based on the character attribute selected.
The character attribute affects how the background and foreground pixels for a
character are handled. This is shown in the following table.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
20
Chapter 4: User Interface Overview
Attribute Background Foreground
A_NORMAL Unchanged ON
A_REPLACE OFF ON
A_REVERSE ON OFF
A_SHADED OFF Every other pixel on.
A_XOR Unchanged XOR’d with destination.
Table 4.1: Available Character Attributes
Reverse mode is usually used to denote highlighted or selected items, such as in
Figure 4.7.
Figure 4.7: Example Using the A_REVERSE Attribute
Shading is used to denote unselectable items. It is often used in menus, as
shown in Figure 4.8.
Figure 4.8: Example Using the A_SHADED Attribute
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 4: User Interface Overview
The character set is a modified ISO Latin set as shown in the following table.
AMS ASCII AMS AMS/ISO Latin Extensions
MSD0 1 2345678 9 A B C D E F
21
LSD 0
NULL
SOH
1
STX
2
ETX
3
EOT
4
ENQ
5
6
7
8
9
A
B
C
D
E
F
← %5 E U e u δ E¥µÅÕåõ
ACK
→ &6FVf v ε
BELL
↑ '7GWgwζ i§·Ç×ç÷
BS
↓ (8HXhxθ
TAB
LF
®
FF
∪ ,<L\l|π≤¬
CR
∩ - = M] m} ρ≠⊂ .>N^n~Σ≥® ∞ ÎÞîþ
∈ /?O_o
9
0@P` pατ …°ÀÐàð
SP
!1AQaqβφ¡
"2BRbrΓψ¢²ÂÒâò
#3CScsγΩ£³ÃÓãó
$4DTdt ∆ω¤
e
r
)9IYiyλ
*:JZjzξ
+; K[ k{Π
T
x
y
σ∠
±
ÁÑáñ
-1
ÄÔäô
¦¶ÆÖæö
+
√
©¹ ÉÙéù
ªºÊÚêú
«»ËÛëû
-
ÈØèø
d
ÌÜìü
ÍÝíý
ì
¿Ï ßï ÿ
Note:
Table 4.2: Character Set
For actual character representation of each font, see
“Small” Character Font, Appendix E: TI-89 / TI-92 Plus “Large” Character Font
Appendix F: TI-89 / TI-92 Plus “Huge” Character Font
Appendix D: TI-89 / TI-92 Plus
.
, or
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
22
4.5. The Status Line
An app can write messages to the status bar; but when modifier keys (2, ¤,
¥, j
cleared of any messages and the modifier status is displayed. The status bar is
also used to show things like the current directory, radian/degree mode, battery
status, and other calculator information as shown in Figure 4.9.
The following routines allow access to the status line:
, and ‚) are pressed or the battery level changes, the status bar is
Figure 4.9: Status Line
Chapter 4: User Interface Overview
ST_angle
ST_busy
ST_eraseHelp
ST_folder
ST_helpMsg
ST_readOnly
— Change the RAD/DEG indicator in the status line.
— Turn on/off the BUSY indicator.
— Clear the help status and restore the indicators.
— Change current folder in the status line.
— Temporarily display a help message in the status line.
— Turn on/off the lock symbol in the status line.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
5. Flash Applications vs. ASM Programs
Flash Application ASM Program
23
Resides in
Executes in
Size
Data segment
Copy protection
protected Flash memory
Flash memory occupied by the OS
and applications is protected from
inadvertent or malicious changes.
protected Flash memory
apps are executed in place, i.e., the
app does not need to be moved to
RAM before it can be executed.
— Flash apps are limited by
≤
4 MB
the amount of free Flash memory but
can be no bigger than 4 MB.
— The OS allocates a data
Yes
segment for each application.
Applications can define and reference
global and static variables any of
which may have an initial value.
— A Flash application can only
Yes
be installed in calculators that have a
license for the software. All
calculators come with a
freeware/shareware key which allow
freeware/shareware applications to
be installed without an additional
license.
— The
— Flash
RAM or archive Flash memory
ASM programs can be archived but
must execute in RAM.
— ASM programs can only be
RAM
executed in RAM. Calculator
hardware does not allow 68000
instructions to execute in archive
memory. The OS makes a temporary
RAM copy of an archived ASM
program before executing it.
≤
heap manager cannot allocate any
chunk of memory larger than 64 KB.
The lower 24 KB limit is part of the
antipiracy mechanism.
No
variables on the stack or within the
code segment. This is not difficult in
assembly language but C never
allocates static/global variables in the
code segment.
None
copied between calculators.
— The current version of the
24 KB
— ASM programs must allocate
— ASM programs can be freely
—
menu
O
User interaction
TI-89 / TI-92 Plus Developer Guide
— Interactive Flash applications
Yes
appear on the
Event driven
participate in cooperative multitasking
through the OS. The OS provides
default behavior for many of the
special keys such as
function keys.
Not for Distribution
menu.
O
— Flash applications
O, 3
and
— ASM programs are not
No
full-fledged applications. They can
only be called from TI-BASIC as
subprograms or from the Home
screen author line.
— ASM programs must poll
Polled
the keyboard to receive input from the
user. No other applications can run
until the ASM program returns to the
OS. ASM programs do not get any
automatic behavior for special keys
on the keyboard.
Beta Version January 26, 2001
24
Chapter 5: Flash Applications vs. ASM Programs
Flash Application ASM Program
System overrides
Localization
TI-BASIC
extensions
Shared code
Object-oriented
features
— Flash applications can
Yes
override many system features.
— Calculator language
Yes
localization is provided by Flash
applications.
— A single Flash application can
≥
0
provide many TI-BASIC extension
functions and subprograms.
— Flash applications have a
Yes
shared-code interface which can be
used as a library for other Flash
applications or ASM programs.
— Each Flash application has an
Yes
object frame which exposes its
attributes (data and methods). Object
frames can be arranged into a class
hierarchy for method and attribute
inheritance and class mix-ins.
— ASM programs may move
No
during heap garbage collect. Pointers
to overriding system code would
become invalid.
— The OS only looks at Flash
No
apps for language localizers.
— Each ASM program implements
1
one TI-BASIC subprogram.
— ASM programs have no
No
OS-supported shared-code interface.
No
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
6. Assembly Language Programming Overview
This chapter covers how to use assembly language to write programs for the
TI-89 / TI-92 Plus calculator. You should already know how to write programs in
assembly language and be familiar with Motorola 68000 architecture. See the
TI Web site and the TI-89 / TI-92 Plus Guidebook.
6.1. What are ASM Programs?
ASM programs are subroutines written in 68000 assembly language. Because
they appear as data type ASM in the VAR-LINK window, they are called ASM
programs. They can be called from TI-BASIC programs or from the Home screen
author line just like other TI-BASIC subroutines but with the advantage of speed
and direct control of calculator resources that TI-BASIC as an interpreted
language could never attain. ASM programs cannot, however, return function
values on the estack to TI-BASIC.
25
ASM programs are small (≤ 8 K for AMS 2.03 and ≤ 24 K for AMS 2.04) and
execute in RAM. They are easy to share with other calculators through the link
port. You should consider developing a Flash application if your assembly
language program is large. Because Flash applications are loaded into and
execute from Flash ROM, they do not take up precious RAM. Additionally, your
Flash applications enjoy a measure of copy protection that ASM programs do not
provide.
6.2. Hardware Stack
The user hardware stack is 15.5 KB in size located from 0x0400 to 0x4BFF in
memory. The stack serves four main purposes: it holds the return address from
subroutine calls, subroutine parameters are passed on the stack, subroutine local
variables are allocated on the stack, and register contents can be temporarily
pushed onto and popped from the stack.
There is special circuitry in the calculator which detects stack overflow. An
attempt to push a value or call a subroutine when the stack pointer is below
0x0400 causes level 7 auto-vector interrupt (address at memory location
0x007C) to occur. The level 7 auto-vector handler throws a protected memory
error. See chapter
10. Error Handling
to learn how to catch errors.
6.3. Register Usage
Register A7 is the stack pointer. Do not use A7 for anything else. The stack
contains the return address to the TI-BASIC interpreter when your ASM program
is called.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
26
Chapter 6: Assembly Language Programming Overview
Besides register A7, you can use the remaining registers as needed. But, if you
intend to call OS-resident routines or mix subroutines written in assembly
language and C, you should adhere to the Sierra C™ register usage
conventions.
Registers D0, D1, D2, A0, and A1 are scratch registers. You do not need to save
scratch register contents before using them. C uses register A6 as the subroutine
parameter and stack-based variables frame pointer.
Save and restore D3 – D7 and A2 – A6 whenever you use them in subroutines.
The following example saves registers D3 – D5 and A2 – A3.
movem.l d3-d5/a2-a3,-(sp) ; the assembler recognizes SP as
; an alternative to A7
Restore register values before returning from subroutine with:
movem.l (sp)+,d3-d5/a2-a3
For memory and speed efficiency, your subroutines should only save and restore
the registers you use. If you use only scratch registers, then you do not need to
save any registers.
Use the
link
and
instructions with register A6 to access subroutine
unlk
parameters and to allocate temporary local variables.
Sierra C expects function values to be returned in registers. Integer values are
returned in D0. Pointer values are returned in A0.
6.4. Calling Flash-ROM-Resident Routines
Memory address 0xC8 contains a pointer to a table of OS routines and data
structures. File tiams.inc contains jump table offsets which let you call OS
routines from assembly language.
For example, to call OS routine
the keyboard:
.include "tiams.inc"
.
.
.
move.l 0xC8,a2 ; a2 -> jump table
.
.
.
move.l kbhit(a2),a0 ; get address of kbhit routine
jsr (a0) ; call kbhit()
tst.w d0 ; zero = no keypress, nonzero = key waiting
to determine if a key has been pressed on
kbhit
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 6: Assembly Language Programming Overview
Arguments are passed to OS-resident routines on the hardware stack. Use the C
declaration of an OS routine to determine the type and order of arguments
required by the routine. Arguments are pushed onto the hardware stack in
right-to-left order described by the routine’s C prototype declaration.
27
For example, the program would call
C prototype for
int memcmp(const void *s1, const void *s2, size_t count);
memcmp
is:
memcmp
to compare two byte arrays. The
The Assembly language call is:
; if (memcmp(ID, myid, sizeof(myid)) == 0)
move.l #5,-(sp) ; push size of myid
pea myid(a6) ; push address of myid
pea id(a6) ; push address of ID
move.l memcmp(a2),a0 ; get address of memcmp
jsr (a0) ; call memcmp
add.w #12,sp ; pop arguments from stack
tst.w d0 ; test result from memcmp
bne notTheSame ; not equal --->
When you look at OS routine C prototypes, keep in mind the size and range of C
data types. In particular, note that int is two bytes in the AMS.
Type Size (bytes) Range
char 1
unsigned char 1 0 . . . 255
128 . . . 127
L
short 2
unsigned short 2 0 . . . 65535
int 2
unsigned int 2 0 . . . 65535
long 4
unsigned long 4 0 . . . 4294967295
pointer 4 0 . . . 0xFFFFFFFF
Table 6.1: AMS C Data Types
6.5. Subroutine Linkage
Use
to free stack space before returning from the subroutine. Use the
instruction to save and restore registers.
Example: subroutine linkage for subroutine mySubr with eight bytes of local
variables and two parameters.
to allocate space from the hardware stack for local variables. Use
link
32768 . . . 32767
L
32768 . . . 32767
L
2147483648 . . . 2147483647
L
unlk
movem.l
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
28
Chapter 6: Assembly Language Programming Overview
Its C prototype is:
short mySubr(short a, short b);
The Assembly language subroutine is:
;subroutine entry
mySubr:
link a6,#-8 ; allocate 8 bytes for local
movem.l d3-d4/a2,-(sp) ; save registers
.
.
.
move.w 8(a6),d0 ; get parameter
move.w d0,-8(a6) ; save in local variable storage
.
.
.
;subroutine exit
move.w -2(a6),d0 ; return function result in D0
movem.l (sp)+,d3-d4/a2 ; restore registers
unlk a6 ; free stack space
rts ; return from subroutine
; variables
a
from caller
Here is how stack memory looks in the above example after subroutine entry.
A7
12 bytes 8 bytes 4 bytes 4 bytes 2 bytes 2 bytes
20(a6)
L
saved D3, D4, and A2 local variables saved A6 return
8(a6) 0(a6) 4(a6) 8(a6) 10(a6)
L
Figure 6.1: Example of ASM Stack Memory
A6
ab
address
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 6: Assembly Language Programming Overview
6.6. Sample ASM Program
ASM programs do not have to be written in assembly language. Here is a sample
ASM written in C. ASM program
waitkey
turns on the PAUSE indicator in the status line and puts the calculator in low
power mode until a key is pressed. The key code for the pressed key is stored in
a variable of the programmer’s choosing.
/* ASM program to wait for a keypress. Go into idle mode until a
key is pressed. */
#include "tiams.h"
/* Entry point must be called main */
void main(void)
{
Access_AMS_Global_Variables;
Event e;
USHORT ch;
EStackIndex varname;
varname = top_estack;
accepts a keypress from the user. It
29
/* Argument must be string containing name of a variable */
if (ESTACK(varname) != STR_DATA_TAG)
ER_throw(ER_ARG_MUST_BE_STRING);
/* Get pointer to beginning of variable name */
varname = next_expression_index(varname-1) + 2;
/* Make sure name is legal and not reserved for something else */
if (TokenizeSymName(varname, TSF_PASS_ERRORS) == NULL)
ER_throw(ER_INDIR_STRING_NOT_VARNAME);
varname = top_estack;
/* Get a keypress */
while ((ch = EV_getc(ST_PAUSE, &e)) == 0)
;
/* Push character number onto estack */
push_ushort_to_integer(ch);
/* Pop character number into variable */
VarStore(varname, STOF_ESI, 0, top_estack);
}
To get a keypress code into, say, variable k, in your TI-BASIC program call
waitkey
(“k”).
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
30
Chapter 6: Assembly Language Programming Overview
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
7. Flash Application Layout
This chapter presents the physical layout of AMS Flash applications on disk and
in calculator memory. It also discusses what needs to be in your source code to
make a Flash app interface with the OS.
7.1. File Format
AMS application files are embedded within three layers of headers: the Flash
header used by TI-GRAPH LINK™ software, the certificate header needed for
license tracking, and the application header needed by the AMS OS.
Flash header
Certificate header
Application header
31
Relocation map
Application code
Initial data table
Signature
Figure 7.1: Flash Application File Format
7.1.1. Flash Header
The Flash header is used by TI-GRAPH LINK software. TI-GRAPH LINK
removes this header when it sends software to a calculator.
The following table describes the fields of the Flash header used by AMS
applications.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
32
Chapter 7: Flash Application Layout
Offset
(bytes)
0 8 “**TIFL**”
8 2 revision number
10 1 flags (0 = binary data)
11 1 object type (0)
12 1 revision day
13 1 revision month
14 2 revision year
16 1 length of internal application name
17 8 internal application name (zero-padded on the right end if length
25 23 filler (zeros)
48 1 device type (0x98 = TI-89, 0x88 = TI-92 Plus)
49 1 data type (0x24 = application)
50 24 filler (zeros)
74 4 length of data following header
Length
(bytes) Contents
➊
❶
➊
❶
< 8 bytes)
➋
Table 7.1: Flash Header Format
Binary-coded decimal, most significant digit first.
➊
Integer, least significant byte first.
➋
7.1.2. Certificate Header
The certificate header is used by the license tracking software in the calculator.
This header is kept with the application when it is downloaded into the calculator
and when it is transmitted from one calculator to another or uploaded to a
computer.
The certificate contains variable-length tagged fields. The application itself is
actually a tagged field of the certificate. Other fields include the application’s
product ID (a number which cross-references the certificate with a license in the
calculator’s unit certificate), revision number, build number, internal name, and
an embedded date certificate (the date the certificate was created).
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
7.1.3. Application Header
The OS keeps track of apps through the application header. The application
header contains information about the application itself. The header contains the
internal name of the application, flags, the length of the application’s data
segment, an offset to the beginning of application code, an offset to the
beginning of initial data, and the length of initial data.
Lengths and offsets are stored most significant byte first — the convention used
in the Motorola 68000 microprocessor.
This header is created by the MKAPPLET utility.
The following fields may be accessed through the AppHdr structure.
33
Offset
(bytes)
0 4 magic number (0x167B533D)
4 8 internal application name (padded with trailing zeros to eight
12 24 reserved (fill with zeros)
36 2 flags
38 4 length of data segment
42 4 byte offset to code segment
46 4 byte offset to initial data table
50 4 length of initial data table
54 4 length of optional header — additional information can be stored
58
Length
(bytes) Contents
n
7.1.3.1. Magic Number
bytes)
just after the application header.
optional header — this information is ignored by the OS.
Table 7.2: Application Header Format
The magic number marks the beginning of the app header.
7.1.3.2. Internal Application Name
Every application has a unique internal name.
Note:
TI-89 / TI-92 Plus Developer Guide
This field must match the internal application name in the Flash header. The internal
application names in the app header and Flash header are case sensitive and must be
identical.
Not for Distribution
Beta Version January 26, 2001
34
Chapter 7: Flash Application Layout
Even built-in applications have internal names. You can call
EV_getAppID
built-in app’s internal name to get its application ID. Your app can send
messages to a built-in app (see
Application Name Internal Name
Home TIHOME
Y= Editor TIEQUED
Window Editor TIWINDED
Graph TIGRAPH
Table TITABLED
Data/Matrix Editor TIDMED
Program Editor TIPRGMED
Text Editor TITEXTED
Numeric Solver TIINSLVR
Table 7.3: Internal Names of Built-in Applications
EV_sendEvent
) given its app ID.
with a
7.1.3.3. Flags
0x0001 APPHDR_LOCALIZER
The remaining flag bits are reserved and should be zero.
Application provides language localization for the AMS
Operating System (OS). The language setting pop-up
menu on page 3 of the calculator’s mode window is built
by scanning all the app headers for applications with this
flag set.
7.1.3.4. Length of Data Segment
The data segment length is the amount of static RAM to allocate to the
application when it is loaded into the calculator. It consists of the static initialized
(.data) and uninitialized (.bss) RAM sections.
7.1.3.5. Byte Offset to Code Segment
The byte offset to code is a header-relative pointer to the beginning of the
application code image.
7.1.3.6. Byte Offset to Initial Data Table
The contents of the application’s initialized RAM (.data section) are initialized by
copying the data from this table.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
7.1.3.7. Length of Initial Data Table
Number of bytes in initial data table.
7.1.3.8. Optional Header
Additional header information may be included after the required header section.
The optional header length specifies how many bytes are in the header
extension.
7.1.4. Relocation Map
The OS uses the relocation map to calculate absolute addresses when the
positions of the code and data segments are finally established. The relocation
map consists of a six-byte entry for each location which needs to be updated.
35
Offset
(bytes)
0 3 hole offset
3 3 base (2 bits) and relative value to place in hole (22 bits)
Length
(bytes) Contents
Table 7.4: Relocation Map Format
The hole offset specifies where in the application code or initial data table an
absolute address needs to be updated.
The value to store in the hole is calculated from the base and relative value. The
base is 00 for code-segment relative and 10 for data-segment relative. Base
values 01 and 11 are reserved for future implementations of AMS.
7.1.5. Application Code
The code segment contains executable application code and constant data.
7.1.6. Initial Data Table
When the OS installs an application, it allocates a data segment in RAM to hold
static and external variables. The initial data table provides their initial values.
Static/external variables which are not explicitly initialized are set to zero.
The application’s data segment is initialized when the application is installed and
reinitialized every time the application is moved in Flash memory because of
garbage collection.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
36
7.1.7. Signature
The signature protects everything from the beginning of the certificate header to
the end of the application from changes.
7.2. Layout in Memory
The OS creates an Application Control Block (ACB) for each app in the calculator
whether it is one of the built-in apps that come preinstalled from the factory or
installed later as a Flash app.
Chapter 7: Flash Application Layout
Routine
EV_getAppID
returns the ID of an app given its internal name. By
design, the app ID is also the handle to the app’s ACB. Dereference the handle
to get a pointer to the app’s ACB.
ACB * pacb = (ACB *)HeapDeref(EV_getAppID(name));
ACBs form a linked list in memory. Global OS variable OO_firstACB contains a
handle to the first ACB. Routines
OO_NextACB
and
OO_PrevACB
are used to
traverse the list of ACBs.
The Application Control Block contains information about the current state of the
app. Here is a description of the ACB structure.
USHORT
flags
— Application control flags:
0x0001 — ACB_BUILTIN, the app is a built-in
application.
0x0002 — ACB_INSTALLED, the OS sets this flag
when app installation is complete.
0x0004 — ACB_LOCALIZER, the app is a
language localizer, i. e. its name
appears in the MODE screen as a
language choice.
TI-89 / TI-92 Plus Developer Guide
0x0008 — ACB_LOCK, reserved.
0x0010 — ACB_JT_VERSION, jump table version
mismatch, do not show on the APPS
pop-up menu.
0x0020 — ACB_SELECTED, app is selected in
the VAR-LINK screen.
0x0800 — ACB_COLLAPSE, collapse view of
TI_BASIC extension functions and
commands in the VAR_LINK screen.
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
37
0x1000 — ACB_BG, app receives background
processing.
0x4000 — ACB_COMPRESS, app is being moved
during Flash memory compression.
0x8000 — ACB_DELETE, app is about to be
deleted.
AppID
AppID
AppID
ULONG
AppHdr const *
BYTE const *
pFrame
myID
nextID
prevID
publicStorage
appData
appHeader
certhdr
— ID of this app.
— ID of the next app in the linked list.
— ID of the previous app in the linked list.
— Temporary storage space for the app.
— Pointer to the AppHdr structure. An AppHdr resides
with the app in Flash memory and cannot be changed.
— Pointer to the certificate header.
— Handle to the app’s object frame. Use
convert it to a pointer.
OO_Deref
to
The OS allocates memory for applications from two pools. The executable code
and constant resources (.text and .const sections) are stored in Flash ROM.
Static variables (.data and .bss sections) are stored in RAM.
Applications are stored in Flash memory beginning at the first sector boundary
after OS code. The OS reapportions archive memory to application memory as
needed to make room for additional Flash applications. When an application is
deleted, applications after it in memory are moved up to fill the void. Flash
sectors vacated during this process are returned to archive memory.
One pad byte of 0xFF is added between apps if needed to make sure each app
begins on an even address boundary.
The OS allocates the application’s static data in high RAM. The handle to this
chunk of memory is locked to assure that it does not move during heap
compaction. The data segment contains the app’s Application Control Block,
initialized data (.data), and uninitialized data (.bss). The OS frees the data
segment when the application is deleted.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
38
ACB
.data
RAM
Figure 7.2: Application RAM and Flash Usage
The OS expects the first variable in the application’s initialized data (.data
section) to be a pointer to the app frame. The OS must be able to find the app
frame in order to get the app’s event processor entry point. To make this happen,
you must declare a variable of type
the address of your application’s frame. Furthermore, you need to make sure it is
the first initialized variable in your application.
7.3. Source Layout
Chapter 7: Flash Application Layout
.text
FRAME
Flash ROM
.const
pFrame
in your C source and initialize it with
An AMS application can serve several purposes. It can have an interactive user
interface through windows and the keyboard — the most common usage. It can
extend TI-BASIC with a library of functions and programs. It can implement a
shared-code library — routines which can be called from other applications. And,
it can override tables in the OS or another application to provide local language
customization. An app can provide a mix of any of these features.
This section looks at the source requirements your application needs to
implement each of these features.
7.3.1. Interactive Applications
Interactive applications need an object frame and an event handler. The object
frame provides a directory of attributes and methods in the application and
serves as an interface to the OS. It is in the object frame that the OS finds the
address of the app’s event handler.
This section covers the layout of the object frame with the help of
ENDFRAME
and
predefined frame attributes and methods. Finally, a simple example pulls the
pieces together into a complete application.
macros, how the OS finds the app’s frame, and details of
FRAME, ATTR
,
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
7.3.1.1. FRAME
Here is how a typical frame looks.
#define STRING1 (OO_FIRST_APP_STRING+0)
#define STRING2 (OO_FIRST_APP_STRING+1)
39
FRAME(
ATTR(
ATTR( . . . )
.
.
.
ATTR(OO_FIRST_STRING+STRING1, "a string")
ATTR(OO_FIRST_STRING+STRING2, "another string")
.
.
.
ENDFRAME
The
•
•
frameName, parent, prototype, firstAttr, count
attrSelector, value
macro defines the header of an object frame, an
FRAME
frameName
OO_Hdr
parent
— name of the object frame. This becomes the name of the
structure.
— pointer to another frame higher in the object hierarchy. This field
should contain
OO_SYSTEM_FRAME
)
, a pointer to the root of the object hierarchy
)
OO_Hdr
structure.
in the OS.
prototype
•
— pointer to another frame on the same level of the object
hierarchy, often another frame within the application. This value can be zero
(0) if the application has only one object frame. At any rate, this value must
be zero in the last prototype frame of a linked list.
firstAttr
•
must be the same value as the
frame.
count
•
The
FRAME
(
OO_Attr
•
structures).
attrSelector
frame must be unique and sorted into increasing order. The object frame
accessor functions (
their selector number.
Note:
TI-89 / TI-92 Plus Developer Guide
— number of the first attribute or method selector in the frame. This
attrSelector
of the first
macro in the
ATTR
— count of attributes and method selectors in the frame.
header is followed by
macros which define frame attributes
ATTR
— the selector number of the attribute. Every selector within a
OO_GetAttr
The OS does not check that attribute selectors are in increasing order. You must
make sure the attributes are in order when you create the frame. Attribute look-up
will fail if they are not.
Not for Distribution
and
OO_SetAttr
) look up frame attributes by
Beta Version January 26, 2001
40
Chapter 7: Flash Application Layout
— the value of a frame attribute. This can be a number, a pointer to a
value
•
string, a method entry point, or pointer to an application-defined structure —
anything which can fit in 32 bits.
The frame ends with an
FRAME
and
ATTR
The
ENDFRAME
macros create
memory in the .text section of the application. For this reason, the
also sets the read-only flag in the object frame header.
7.3.1.2. Pointer to FRAME
The OS must be able to find the object frame in the application. The OS expects
the first initialized variable in an application to be a pointer to the application’s
object frame.
For example, say an application has an object frame named
an initialized frame pointer:
pFrame pAppFrame = (pFrame)&myAppFrame;
By declaring
pAppFrame
before any other initialized static variables, the first
variable in the .data section will be a pointer to the app frame — just where the
OS expects to find it.
7.3.1.3. Object Frame Attributes
macro.
const
data structures which reside in Flash
macro
FRAME
myAppFrame
. Declare
Application object frames can contain many attributes and method entry points.
This section discusses the attributes and methods reserved by the OS.
Each attribute and method name is a C macro which defines a numeric selector
number. In addition, there are macros in tiams.h which fetch and set application
attributes and call application methods. The following slot descriptions state the
attribute or method name (slot number) and accessor prototypes.
Many application attributes are hard-coded in the source and are not meant to be
changed at run-time. The description of read-only attributes shows only the
macros to fetch their values.
7.3.1.3.1. Attribute OO_APP_FLAGS (0x1)
APP_Flags GetAppFlags(AppID)
0x0001 APP_INTERACTIVE
0x0002 APP_CON
Application has an interactive interface. Its name
appears on the app’s menu. This flag is zero for
libraries and language localization apps.
Attach Current/Open/New submenu to application
name on the app’s pop-up menu. This flag is ignored if
the app’s APP_INTERACTIVE flag is off.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
41
0x0004 APP_ACCESS_SYSVARS
0x0008 APP_BACKGROUND
Application can store to column variables of the data
matrix editor without causing a protected variable error
message.
Application wants CM_BACKGROUND events. This
allows applications, including noninteractive
applications, to get execution time even when the
application is not active.
The remaining flags are reserved and should be zero.
7.3.1.3.2. Attribute OO_APP_NAME (0x2)
UCHAR * GetAppName(AppID)
Pointer to the application’s name. This name is displayed in the app’s pop-up
menu if the application has an interactive interface. The length of the name
should be no more than 20 characters on the TI-89 and no more than 32
characters on the TI-92 Plus.
7.3.1.3.3. Attribute OO_APP_TOK_NAME (0x3)
UCHAR * GetAppTokName(AppID)
Pointer to application token name (≤ 8 characters). This is the name TI-BASIC
programs use to refer to functions and programs exported from the application.
For example, if application “Linear Algebra” has a token name of linalg and
exports its own implementation of the sin function, TI-BASIC programs can call
linalg.sin( . . . ) which will not be confused with the built-in sin function.
This attribute is optional. If your application defines no TI-BASIC extension
functions or programs, this attribute is unnecessary.
7.3.1.3.4. Method OO_APP_PROCESS_EVENT (0x4)
void AppProcessEvent(pFrame self, Event * event)
Pointer to the application’s event handler routine. The OS sends event messages
to the application by calling its event handler.
This method is optional. If the application is a library with no user interface, then
it can ignore event messages.
If the application needs to respond to any events, then this method must be
implemented. A library application may need to know, for example, when it is
being installed (CM_INSTALL), moved (CM_PACK/CM_UNPACK), or deleted
(CM_UNINSTALL).
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
42
Chapter 7: Flash Application Layout
7.3.1.3.5. Attribute OO_APP_DEFAULT_MENU (0x5)
MENU * GetAppDefaultMenu(AppID)
void SetAppDefaultMenu(AppID, MENU *)
Pointer to the application’s menu resource.
7.3.1.3.6. Attribute OO_APP_DEFAULT_MENU_HANDLE (0x6)
HANDLE GetAppDefaultMenuHandle(AppID)
void SetAppDefaultMenuHandle(AppID, HANDLE)
This attribute is managed automatically by the OS when your application uses a
single static menu. See section
9.6. Menu Processing
this attribute.
7.3.1.3.7. Attribute OO_APP_EXT_COUNT (0x7)
long GetAppExtCount(AppID)
The number of TI-BASIC extension functions and commands exported by this
application.
on when and how to set
This attribute is optional. This attribute should be defined only if the application
exports TI-BASIC extensions.
7.3.1.3.8. Attribute OO_APP_EXTENSIONS (0x8)
APP_EXTENSION const * GetAppExtensions(AppID)
Pointer to an array of
APP_EXTENSION
structures. There is one entry in the table for
each exported TI-BASIC function or program. An entry contains the name string
number, catalog help string number, and index of the function or program.
Names in the APP_EXTENSION table must be sorted in ASCII order.
This attribute is optional. This attribute should be defined only if the application
exports TI-BASIC extensions.
7.3.1.3.9. Attribute OO_APP_EXT_ENTRIES (0x9)
APP_EXT_ENTRY const * GetAppExtEntries(AppID)
Pointer to an array of
APP_EXT_ENTRY
structures. There is one entry in the table for
each exported TI-BASIC function or program. An entry contains a pointer to the
C routine which implements the extension, and a flag word which indicates
whether the extension is a function or program.
This attribute is optional. This attribute should be defined only if the application
exports TI-BASIC extensions.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
7.3.1.3.10. Method OO_APP_LOCALIZE (0xA)
BOOL AppLocalize(AppID self, UCHAR const * language)
Pointer to the application’s language localization routine. The OS calls this
method in each application when the user chooses a new language in the mode
window. This method returns TRUE if it switched the app to the given language.
How to localize an application for another language is covered in detail in section
7.3.4. Language Localization
This method is optional.
7.3.1.3.11. Method OO_APP_UNLOCALIZE (0xB)
void AppUnlocalize(AppID self)
Pointer to the application’s routine to remove language localization.
This method is optional but should be implemented if the above
OO_APP_LOCALIZE method is implemented.
.
43
7.3.1.3.12. Method OO_APP_CAN_DELETE (0xC)
BOOL AppCanDelete(AppID
self
)
Before the OS deletes an application, it calls this method to ask the application if
it can be deleted. This method returns TRUE if the application can be deleted.
This method is optional. Implement it only if you have special requirements for
when your app can be deleted.
7.3.1.3.13. Method OO_APP_CAN_MOVE (0xD)
BOOL AppCanMove(AppID
self
)
The application returns TRUE if it can be relocated to another address in Flash
memory. The OS uses this method to query applications while it is preparing to
garbage collect Flash memory.
This method is optional. Implement it only if you have special requirements for
when your app can be moved.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
44
7.3.1.3.14. Method OO_APP_VIEWER (0xE)
Chapter 7: Flash Application Layout
BOOL AppViewer(AppID
self
, BYTE *
vartype
The [F6: Contents] menu command of the VAR-LINK window calls this method of
each application in turn until one of them returns TRUE. If an application knows
how to display variables of type
symbol
in the given window and returns TRUE.
vartype
This method is optional. Applications which implement new data types may use
this method to display a variable it understands in the VAR-LINK contents
window. If no application returns TRUE, then the variable’s contents are not
displayed.
7.3.1.3.15. Attribute OO_APP_ICON (0xF)
BITMAP * GetAppIcon(AppID)
A pointer to a BITMAP which represents the application’s icon.
This attribute is optional.
7.3.1.3.16. Method OO_APP_EXT_HELP (0x10)
void AppExtHelp(AppID self, USHORT strnum)
, WINDOW *, HSYM
symbol
)
, it displays the contents of variable
The catalog screen calls this method when the users presses [F1: Help] for a
function or command extension implemented by the application.
This method is optional. It should only be implemented if the application exports
TI-BASIC extensions. The system implementation of this method displays the
extension’s help string if this method is not implemented.
7.3.1.3.17. Method OO_APP_NOTICE_INSTALL (0x11)
void AppNoticeInstall(AppID self, ACB const *)
The OS calls this method in every application when a new application is installed.
The app is passed a pointer to the new application’s ACB.
This method is optional.
7.3.1.3.18. Method OO_APP_ABOUT (0x12)
char const * AppAbout(AppID self)
The VAR-LINK screen calls this method when a user presses [F6: Contents] for a
Flash application. The application returns a pointer to a string containing version
and copyright information.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
This method is optional. The system implementation of this method displays the
application’s internal name, revision number, and date when its certificate was
signed.
7.3.1.3.19. Attribute OO_APPSTRING (0x1000 and up)
char const *
Applications store pointers to their strings beginning with selector number 0x1000
defined by macro
OO_APPSTRING
. The menu system and language localizers
expect application string numbers to be defined in the range 0x1000 – 0x17FF.
7.3.1.4. Example
C source file pipes.c:
#include "tiams.h"
#include "pipesr.h"
#include "pipes.h"
/* Prototypes of functions in this source file */
void main(pFrame, PEvent);
static short sabs(short);
static short random(short, short);
➊
45
FRAME(pipesFrame, OO_SYSTEM_FRAME, 0, OO_APP_FLAGS, 6)
ATTR(OO_APP_FLAGS, APP_INTERACTIVE) /* This is an interactive app */
ATTR(OO_APP_NAME, "Pipes") /* Name in [APPS] menu */
ATTR(OO_APP_PROCESS_EVENT, &main) /* Address of event handler */
ATTR(OO_APP_DEFAULT_MENU, &pipesMenu) /* Menu defined in pipesr.r */
/* Strings used in menu */
ATTR(OO_FIRST_STRING+P_Tools, "Tools")
ATTR(OO_FIRST_STRING+P_Clear, "Clear")
ENDFRAME
pFrame PipesFrame = (pFrame)&pipesFrame;/* Pointer to object frame */
#define BOX_DIMENSION (15)
#define MAX_BOX (25)
WINDOW w;
SCR_COORDS width, height;
WIN_RECT box;
/* Event handler - the OS calls this routine when an event has occurred
*/
void main(pFrame self, PEvent event)
{
static short deltaX = 1, deltaY = 1;
static short boxcount = -1;
➋
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
46
Chapter 7: Flash Application Layout
switch (event->command)
{
case CM_START:
WinOpen(&w, event->info.startInfo.startRect, WF_DUP_SCR);
DrawWinBorder(&w, &w.Window);
WinClr(&w);
width = w.Client.xy.x1 - w.Client.xy.x0;
height = w.Client.xy.y1 - w.Client.xy.y0;
/* Pick initial box location */
if (box.x0 == 0 && box.y0 == 0)
{
box.x0 = random(1, width - BOX_DIMENSION - 1);
box.x1 = box.x0 + BOX_DIMENSION;
box.y0 = random(1, height - BOX_DIMENSION - 1);
box.y1 = box.y0 + BOX_DIMENSION;
}
break;
/* User pressed [F1][1:Clear] */
case CM_CLEAR_ALL:
WinClr(&w);
break;
case CM_QUIT:
WinClose(&w);
break;
/* Draw pipes when system is not busy with anything else */
case CM_NULL:
if (boxcount <= 0)
{
// Choose new direction
deltaX = random(2, 4);
if (random(0,99) < 50)
deltaX = -deltaX;
deltaY = random(2, 4);
if (random(0,99) < 50)
deltaY = -deltaY;
boxcount = MAX_BOX;
}
if (box.x0 < 0)
deltaX = sabs(deltaX);
if (box.x1 > width)
deltaX = -sabs(deltaX);
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
if (box.y0 < 0)
deltaY = sabs(deltaY);
if (box.y1 > height)
deltaY = -sabs(deltaY);
WinFill(&w, &box, A_REVERSE);
WinRect(&w, &box, A_NORMAL);
box.x0 += deltaX;
box.x1 += deltaX;
box.y0 += deltaY;
box.y1 += deltaY;
boxcount -= 1;
break;
case CM_ACTIVATE:
DrawWinBorder(&w, &w.Window);
EV_defaultHandler(event);
break;
case CM_WPAINT:
WinBackupToScr(&w);
break;
47
default:
EV_defaultHandler(event);
break;
}
}
static short sabs(short n)
{
return n < 0 ? -n : n;
}
static short random(short low, short high)
{
short range;
static long seed = 29;
if (seed == 0)
seed = 1;
seed *= 16807;
if (seed < 0)
seed = -seed;
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
48
Chapter 7: Flash Application Layout
range = high - low + 1;
return low + seed % range;
}
C header file pipes.h:
#ifndef _PIPES_H
#define _PIPES_H
#define P_Tools OO_FIRST_APP_STRING
#define P_Clear OO_FIRST_APP_STRING+1
#endif
➋
Resource file pipesr.r:
#include "tiams.h"
#include "pipes.h"
TOOLBOX pipesMenu, RC_NO_IDS, 0, 160 {
P_Tools {
P_Clear, CM_CLEAR_ALL
}
}
Pipesr.h is generated by the resource compiler.
➊
The numbering of menu commands and application strings needs some explanation. The
➋
menu system requires all string numbers that it references to be in the range 0x000 – 0xFFF.
However, system string attributes begin at 0x800 and application string attributes begin at
0x1000. Consequently, when an app menu refers to string number 0x801, it fetches app
attribute 0x1001. The example code shows how to use macros
the header file and
and their corresponding text in the app frame.
➋
OO_FIRST_STRING
OO_FIRST_APP_STRING
in the object frame to define menu string numbers
in
7.3.2. TI-BASIC Extensions
Applications can extend TI-BASIC with functions and programs written in C or
assembly language. The TI-BASIC interpreter interfaces with apps through the
OO_APP_EXT_COUNT, OO_APP_EXTENSIONS
This example illustrates a simple application which implements a couple of
TI-BASIC extensions. The app has no user interface, hence, no event handler
entry point.
#include "tiams.h"
/* String numbers */
#define H_folders 0
#define H_vars 1
#define H_HELP 100
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
, and
OO_APP_EXT_ENTRIES
attributes.
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
void folders(void);
void vars(void);
49
APP_EXTENSION const extensions[] =
{
/* function name #, help string #, function index */
{OO_APPSTRING+H_folders, OO_APPSTRING+H_HELP+H_folders, H_folders },
{OO_APPSTRING+H_vars, OO_APPSTRING+H_HELP+H_vars, H_vars }
};
APP_EXT_ENTRY const extEntries[] =
{
{folders, APP_EXT_FUNCTION},
{vars, APP_EXT_FUNCTION}
};
FRAME(memutilFrame, OO_SYSTEM_FRAME, 0, OO_APP_FLAGS, 10)
ATTR(OO_APP_FLAGS, APP_NONE)
ATTR(OO_APP_NAME, "Memory Utilities")
ATTR(OO_APP_TOK_NAME, "memutil")
ATTR(OO_APP_EXT_COUNT, 2) /* export two extension functions */
ATTR(OO_APP_EXTENSIONS, extensions) /* address of extensions table */
ATTR(OO_APP_EXT_ENTRIES, extEntries) /* address of ext entries table
*/
ATTR(OO_APPSTRING+H_folders, "folders")
ATTR(OO_APPSTRING+H_vars, "vars")
ATTR(OO_APPSTRING+H_HELP+H_folders, "LIST OF FOLDERS")
ATTR(OO_APPSTRING+H_HELP+H_vars, "LIST OF VARIABLES IN FOLDER")
ENDFRAME
➊
➋
➌
pFrame MemutilFrame = (pFrame)&memutilFrame;
void folders(void)
/* Return a list of folders on the estack */
{
SYM_ENTRY *pSym;
static BYTE const HomeFolder[] = {0, 127, 0};
push_quantum (END_TAG);
pSym = SymFindFirst(&HomeFolder[2], FO_NONE);
while (pSym != NULL)
{
push_zstr((char *)pSym->Name);
pSym = SymFindNext();
}
push_quantum (LIST_TAG);
}
➍
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
50
Chapter 7: Flash Application Layout
void vars(void)
/* Return on the estack a list of variables in current or given folder */
{
Access_AMS_Global_Variables;
BYTE folder[SYM_LEN+1];
BYTE tfolder[MAX_SYM_LEN];
BYTE *fname;
SYM_ENTRY *pSym;
➎
EStackIndex e = top_estack;
/* Get folder name */
if (ESTACK(e) == END_TAG)
{
/* Use current folder */
FolderGetCur(folder);
fname = StrToTokN(folder, tfolder);
}
else
{
if (ESTACK(e) != STR_DATA_TAG)
ER_throw(ER_DOMAIN);
fname = e-1;
}
push_quantum (END_TAG);
pSym = SymFindFirst(fname, FO_NONE);
while (pSym != NULL)
{
push_zstr((char *)pSym->Name);
pSym = SymFindNext();
}
push_quantum (LIST_TAG);
}
➎
The
➊
➋
➌
➍
TI-89 / TI-92 Plus Developer Guide
extensions
each entry is the string number of the name of the function. The second field is the string
number of the function’s help message. The third entry is an index into the following
extEntries
Each entry in the
extensions
the same as its TI-BASIC name — a language localizer may, in fact, override the exported
name. The second field of each entry specifies whether the extension is a function
(APP_EXT_FUNCTION) which returns a value on the estack, or a program
(APP_EXT_PROGRAM) which does not return a value.
The
OO_APP_TOK_NAME
referencing its extension functions. In this example, TI-BASIC programs can call
memutil.folders() and memutil.vars().
The first initialized variable in your application must be a pointer to the app frame. Even
though
are declared const and are not allocated with variables in the .data section. You cannot see it,
but
memutilFrame
table has an entry for each extension function or program. The first field of
table. The entries in this table must be alphabetized by the function name.
extEntries
table with the function’s actual address. The C name of a function need not be
extensions
and
is also declared const by the
table cross-references a function number from the
attribute specifies the short name of the application to use when
extEntries
Not for Distribution
appear to be allocated before
macro.
FRAME
Beta Version January 26, 2001
MemutilFrame
, they
Chapter 7: Flash Application Layout
51
The
➎
Access_AMS_Global_Variables
to fetch or change AMS global variables.
algebra system.
7.3.3. Shared-Code Library
An application can make a library of its data structures and functions available as
attribute slots in its object frame. The app library interface should use attribute
slots 0x10000 (OO_FIRST_APP_ATTR) and up. Attribute slots 0x0000 – 0xFFFF
are reserved for the OS.
7.3.3.1. Creating the Library Interface
Say, for example, your library implements the following functions and data
structures:
int fileTableCount;
FILE fileTable[FILE_TABLE_SIZE];
int fileOpen(AppID self, char const *filename);
int fileRead(AppID self, int handle, char *buff, int size);
int fileWrite(AppID self, int handle, char const *buff, int size);
void fileClose(AppID self, int handle);
macro is required in every subroutine which needs
top_estack
is a global variable in the computer
Note:
The first parameter of each exported function must be an AppID variable even though it
will always be the ID of your library.
You can use Frame Description Language, FDL, to define an interface to these
data and functions.
fileio.fdl . . .
appvar 0x10000 PlayerFileTableCount: int *;
appvar PlayerFileTable: FILE *;
appfunc PlayerFileOpen(AppID, char const *): int;
appfunc PlayerFileRead(AppID, int, char *, int): int;
appfunc PlayerFileWrite(AppID, int, char const *, int): int;
appfunc PlayerFileClose(AppID, int): void;
Some things to note in the above example:
The first variable, PlayerFileTableCount, is numbered 0x10000, the first
•
attribute number available for applications. Subsequent attribute numbers are
automatically incremented unless a new value is supplied.
The variable type or function result is placed after the colon (:) much in the
•
style of Pascal.
Function parameters list only the order and type of arguments. Do
•
parameter names.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
include
not
Beta Version January 26, 2001
52
Chapter 7: Flash Application Layout
Run the FDL compiler to produce a header file suitable for defining your API call
macros and attribute names.
C>FDL fileio.fdl
Resulting header file fileio.h includes among other things:
/* Frame slot number assignments */
#define OO_PLAYER_FILE_TABLE_COUNT (65536)
#define OO_PLAYER_FILE_TABLE (65537)
#define OO_PLAYER_FILE_OPEN (65538)
#define OO_PLAYER_FILE_READ (65539)
#define OO_PLAYER_FILE_WRITE (65540)
#define OO_PLAYER_FILE_CLOSE (65541)
/* Accessor/mutator macros */
GetPlayerFileTableCount(appid)
SetPlayerFileTableCount(appid, int)
GetPlayerFileTable(appid)
SetPlayerFileTable(appid, FILE *)
/* Function call macros */
PlayerFileOpen(appid, name)
PlayerFileRead(appid, handle, buff, size)
PlayerFileWrite(appid, handle, buff, size)
PlayerFileClose(appid, handle)
➋
➌
➊
FDL creates names for attribute slots by converting your variable and method names to upper
➊
case and adding “OO_” prefix.
FDL creates a Set/Get pair of macros for each variable.
➋
These macros hide the details of method dispatch and better demonstrate in your source your
➌
intent to call a library function.
Include fileio.h in your app source so you can use the frame slot assignment
macros in your ATTR declarations.
FRAME(playerObj, OO_SYSTEM_FRAME, 0, OO_APP_FLAGS, . . .)
ATTR(OO_APP_FLAGS, . . .)
.
.
.
ATTR(OO_PLAYER_FILE_TABLE_COUNT, &fileTableCount)
ATTR(OO_PLAYER_FILE_TABLE, fileTable)
ATTR(OO_PLAYER_FILE_OPEN, fileOpen)
ATTR(OO_PLAYER_FILE_READ, fileRead)
ATTR(OO_PLAYER_FILE_WRITE, fileWrite)
ATTR(OO_PLAYER_FILE_CLOSE, fileClose)
ENDFRAME
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
7.3.3.2. Accessing a Library
53
HANDLE EV_getAppID(UCHAR const *
Get the ID of an application/shared-code library.
appname
)
appname
is the app’s internal
name.
Once you have obtained the ID of an application, you can use the function call
macros created by the FDL compiler to call routines in the app’s library.
#include "tiams.h"
#include "fileio.h"
HANDLE libid;
.
.
.
libid = EV_getAppID((UCHAR *)"TIPLAYER");
if (libid == H_NULL)
{
/* Could not find library */
}
.
.
.
n = *GetPlayerFileTableCount(libid);
fd = PlayerFileOpen(libid, "script");
Get a handle to the shared-code library.
➊
➋
➊
➌
EV_getAppID
➋
the calculator.
Macros defined in fileio.h can be used to access variables and call functions in the library.
➌
returns H_NULL if the requested library cannot be found, i.e., is not installed in
7.3.3.3. Frame Description Language
Frame Description Language is provided as a tool to simplify the process of
creating an interface to object frame variables and methods. FDL accepts an
input file of statements in the following forms:
appvar
func [
appfunc [
Comments begin with the pound sign (#) and extend to end of line.
var
[
slot-number
slot-number
slot-number
]
func-name
]
var-name
]
func-name
(pFrame [,
:
type
;
(AppID [,
type
type
. . . ]) :
. . . ]) :
type
type
;
;
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
54
Chapter 7: Flash Application Layout
The var and func keywords describe object frame variables and functions. FDL
creates macros which let you retrieve and change the values of attribute slots
and call functions in method slots. These created macros require the pointer to
an object frame as their first parameter.
Every application has an object frame interface to the OS. The app’s object
frame also serves as a shared-code library interface. As a convenience, so you
do not have to find the address of the app’s object frame, the keywords
and
appfunc
create macros which access an app’s object frame attributes given
its app ID.
appvar
Note:
The first parameter of a func declaration must be type pFrame, the first parameter of an
appfunc declaration must be type AppID.
The slot-number is an optional decimal (0 – 4294967295) or hexadecimal
(0x0 – 0xFFFFFFFF) number which identifies the slot which the variable or
method occupies. Subsequent slot-numbers are automatically incremented
unless a new value is supplied.
Since attribute slots are 32-bit values, types should declare values which fit in
32-bits, integers and pointers.
Note:
Functions which return nothing may declare a return type of void.
The FDL compiler accepts one command line parameter, the name of the file to
compile. It outputs a file of the same name with a .h extension. The output file
contains C macros for accessing object frame attributes and calling frame
methods. The resulting header file is suitable to include in your C source file.
Here is the actual header output file after running the FDL compiler on fileio.fdl in
section
/* FILE: fileio.h
CREATED: 2000.04.13 09:10
INPUT: fileio.fdl
GENERATOR: Frame Description Language compiler, version 2.000
*/
7.3.3.1. Creating the Library Interface
.
/* int * PlayerFileTableCount */
#define OO_PLAYER_FILE_TABLE_COUNT (65536)
#define GetPlayerFileTableCount(obj) \
(int *)OO_GetAppAttr(obj,65536)
#define SetPlayerFileTableCount(obj,value) \
OO_SetAppAttr(obj,65536,(void *)value)
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
➊
➋
➌
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
/* FILE * PlayerFileTable */
#define OO_PLAYER_FILE_TABLE (65537)
#define GetPlayerFileTable(obj) \
(FILE *)OO_GetAppAttr(obj,65537)
#define SetPlayerFileTable(obj,value) \
OO_SetAppAttr(obj,65537,(void *)value)
/* int PlayerFileOpen(AppID, char const *) */
#define OO_PLAYER_FILE_OPEN (65538)
#define PlayerFileOpen(obj,a) \
((int (* const)(AppID, char const *))OO_GetAppAttr(obj,65538))(obj,a)
/* int PlayerFileRead(AppID, int, char *, int) */
#define OO_PLAYER_FILE_READ (65539)
#define PlayerFileRead(obj,a,b,c) \
((int (* const)(AppID, int, char *,
int))OO_GetAppAttr(obj,65539))(obj,a,b,c)
/* int PlayerFileWrite(AppID, int, char const *, int) */
#define OO_PLAYER_FILE_WRITE (65540)
#define PlayerFileWrite(obj,a,b,c) \
((int (* const)(AppID, int, char const *,
int))OO_GetAppAttr(obj,65540))(obj,a,b,c)
55
➍
/* void PlayerFileClose(AppID, int) */
#define OO_PLAYER_FILE_CLOSE (65541)
#define PlayerFileClose(obj,a) \
((void (* const)(AppID, int))OO_GetAppAttr(obj,65541))(obj,a)
A symbolic name is created for each frame slot number. The name consists of “OO_” prefixed
➊
to the name of each variable or function converted to upper case letters and underscores.
A Get . . . macro is created for each variable attribute. It is used to get the value of an object
➋
attribute. It expands into a call to
retrieve. Note the return value is cast to the type of the variable.
A Set . . . macro is created for each variable attribute. It is used to change the value of an
➌
object attribute. It expands into a call to
A method call macro is created for each function attribute. It expands into a call to
➍
OO_GetAppAttr
with the arguments specified in the parameter list of the macro. All the arguments and the
routine return type are cast to the types in the original function definition so the C compiler will
correctly type-check arguments and function return value. Imagine trying to create that macro
manually!
to get the address of the routine to execute. The routine is called indirectly
OO_GetAppAttr
OO_SetAppAttr
with the slot number of the attribute to
.
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
56
7.3.4. Language Localization
Menu titles and item names, dialog text, help strings, error messages, TI-BASIC
extension names, the name of the application as it appears on the app’s pop-up
menu, any string which appears in the app’s object frame, can be overridden with
a localizer app to add language customization. By placing all strings in the frame
and using
XR_stringPtr
job of localizing an app for a different language becomes much easier.
An application is typically localized by installing a small companion app which
contains translations of all the app’s strings for one or more languages. When the
user chooses a different language on the MODE screen, all apps are notified of
the new language. Each localizer app which contains a matching language,
responds by overriding its target app’s strings.
7.3.4.1. Localizer Template
The following sample application is a template localizer app. It can be used to
customize a target app for a different language. There are places in the template
to supply the language, internal name, app’s menu name of the target
application, and the translated strings.
to cross-reference string numbers to string pointers, the
Chapter 7: Flash Application Layout
Strings in the localizer app override strings with the same attribute number in the
target app’s object frame. Therefore, it is important that translated strings in the
localizer use the same string numbers as the target app. A mismatch between
the localizer string numbers and the target string numbers will lead to confusing
menus and messages in the target when localization is applied.
/* Sample application localizer */
#include "tiams.h"
/**********************************************************************
Set MyLang to the name of the language which this localizer implements.
**********************************************************************/
char const MyLang[] = "Fran" RF_C_CEDILLA "ais";
/**********************************************************************
Set TargetApp to the internal name of the app which this localizer
will hook into. This is the same name described in section
7.1.3.2. Internal Application Name.
**********************************************************************/
unsigned char const TargetApp[] = "DEMOAPP";
/**********************************************************************
Set APPSname to the name Target app should have on the [APPS] menu key.
**********************************************************************/
char const APPSname[] = "Application de D" RF_E_ACUTE "monstration";
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Chapter 7: Flash Application Layout
/**********************************************************************
Set MY_APP_NAME to the name this localizer app should have in the
VAR-LINK [F7:APPS] screen.
**********************************************************************/
#define MY_APP_NAME “French Demo Localizer”
void main(pFrame self, PEvent e);
void observer(pFrame self, PEvent e);
BOOL localize(pFrame, char *lang);
void unlocalize(pFrame);
void noticeInstall(pFrame, ACB const *);
BOOL candelete(pFrame self);
static
FRAME(LocalizerFrame, OO_SYSTEM_FRAME, 0, OO_APP_FLAGS, 7)
/* This app does not appear on the [APPS] menu */
ATTR(OO_APP_FLAGS, APP_NONE)
ATTR(OO_APP_NAME, MY_APP_NAME)
/* It needs to respond to some events */
ATTR(OO_APP_PROCESS_EVENT, &main)
57
/* Export methods used in localization */
ATTR(OO_APP_LOCALIZE, &localize)
ATTR(OO_APP_UNLOCALIZE, &unlocalize)
ATTR(OO_APP_CAN_DELETE, &candelete)
ATTR(OO_APP_NOTICE_INSTALL, ¬iceInstall)
ENDFRAME
pFrame appframe = (pFrame)&LocalizerFrame;
/* This little FRAME is hooked ahead of the Target app's frame. It
accomplishes a couple of things:
1) It renames the Target app on the [APPS] menu, and
2) It redirects its event handler to this app so we can observe its
pack/unpack and uninstall messages. All events are forwarded to
their rightful owner.
*/
static
FRAME(TargetAppFrame, OO_SYSTEM_FRAME, NULL, OO_APP_NAME, 2)
/* Override the Target app's name in the [APPS] menu */
ATTR(OO_APP_NAME, APPSname)
/* Redirect Target app's events to me */
ATTR(OO_APP_PROCESS_EVENT, &observer)
ENDFRAME
/* Place the translated strings here. Keep the following OO_Hdr structure
and target strings array together. The OO_Hdr structure is an object
frame header for the following array of string attributes.
*/
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
58
Chapter 7: Flash Application Layout
static const OO_Hdr TargetStrings =
{
OO_SYSTEM_FRAME,
(pFrame)&TargetAppFrame,
OO_RO | OO_SEQ,
OO_FIRST_STRING + OO_FIRST_APP_STRING,
174 // <------------------------------ number of strings
};
static char * const targetstrings[] =
{
"first string", // <---------------- local translation of strings
"second string",
/* etc. */
};
/* Keep track of when this localizer is hooked into the Target app */
pFrame hook = 0;
/**********************************************************************
This app's event handler needs to unhook itself from the target app
when it is deleted or moved. It can reconnect to the Target app when
it has been reinstalled or has completed its move.
**********************************************************************/
void main(pFrame self, PEvent e)
{
switch (e->command)
{
case CM_UNINSTALL:
case CM_PACK:
unlocalize(self);
break;
case CM_INSTALL:
case CM_UNPACK:
localize(self, XR_stringPtr(XR_NativeLanguage));
break;
}
}
/**********************************************************************
This routine observes all events sent to Target app. It localizes the
Target after the app UNPACKs and unlocalizes the Target just before it
PACKs or UNINSTALLs.
**********************************************************************/
void observer(pFrame self, PEvent e)
{
Access_AMS_Global_Variables;
pFrame super = OO_SuperFrame;
switch (e->command)
{
TI-89 / TI-92 Plus Developer Guide
Not for Distribution
Beta Version January 26, 2001
Loading...