The (Less-Than Complete)

Hitchhiker's Guide to the Avigo OS

By Randy Gill - Last updated 11/19/99

 NEW: 11/21/99: Download the updated  AVGUI Avigo GUI Library (version 1.01, with a fix for the PNUMBERFIELD problem)

Contents

Forward
Acknowledgments
Memory Overview
Base Memory Contents
Banked ROM Memory Contents
Base Function List (system, file, graphics, I/O, sound functions)
Base Function List (math functions)
Banked Functions Overview
Banked Function List
I/O Ports
 

Forward

The Hitchhiker's Guide to the Galaxy is a small, handheld electronic "book" loaded with lots of useful information. The Hitchhiker's Guide to the Avigo OS is loaded with lots of (hopefully) useful information about a small, handheld electronic "book".

Through this list, I will attempt to compile a comprehensive reference of function calls and memory locations used by the Avigo OS. This is not a tutorial, and at this early stage the usage and parameters of the various functions are not listed. It is my hope that this information will allow application developers to expand the capabilities of tools such as the Freeware SDK, and Z80 assemblers. I believe I've located most of the functions of the official SDK. Please contact me (rdgill@earthlink.net) if there's something you don't see and I'll attempt to locate it.
 

Acknowledgments

Special thanks to Hans B. Pufal, upon whose tireless work much of this information is based; Ollivier Civiol, whose wonderful disassembler made this possible; Ray Broniak, for his pioneering work in cracking mysteries of the OS; and Gerard Vermeulen, for developing an alternative to the official SDK, and releasing it to the Avigo developer community.
 

Memory Overview

The Avigo handheld PDA is based on a modified Z80 microprocessor, which has a 16-bit memory address bus. That means it can directly access up to 64k bytes. The Avigo OS is able to access multiple megabytes of memory using a technique known as "banking" or "paging", selecting 16k banks of extended memory to appear in 2 memory regions as needed. Like most other computers, Avigo memory is designated as RAM and ROM. The ROM however, is EEPROM (electrically erasable ROM), and the operating system and applications can - and do -routinely alter its contents.

The 64k of base memory contains four 16k regions as follows:
 
 
$0000 - $3FFF System ROM region
$4000 - $7FFF ROM bank access region
$8000 - $BFFF RAM bank access region
$C000 - $FFFF System RAM region

 

Base memory contents

Location Description
$0000 - $0008 System start-up code
$0009 - $01C2 Jump table: memory, I/O, string, graphics functions
$01C3 - $2764 System function code
$2765 - $2E99 Empty (all $FF)
$2F00 - $2FFF Unknown (some type of table?)
$3000 - $3125 Jump table: math library, banked call functions
$3126 - $3E2E System function code
$3E2F - $3FFF Empty (all $FF)
$4000 - $7FFF RAM bank access area (see above)
$8000 - $BFFF ROM bank access area (see above)
$C000 - $C005 Unknown
$C006 - $C007 Pointer to library temporary storage region
  Pointer + $0008 Oper1 temp storage location
  Pointer + $0010 Oper2 temp storage location
  Pointer + $0018 Oper1 storage location (for conversion)
  Pointer + $0020 Oper2 storage location (for conversion)
  Pointer + $0028 Math param1 storage?
  Pointer + $0030 Math param2 storage?
  Pointer + $0038 Oper1 temp storage location (for strings)
  Pointer + $004D Field start
  Pointer + $004E Field size
  Pointer + $004F Indirect back number
  Pointer + $0051 Banked address store
  Pointer + $0057 Library data size
$C008 Value of I/O port $01
$C009 Value of I/O port $02
$C00A Value of I/O port $03
$C00B Value of I/O port $09
$C00C Value of I/O port $2D
$C00D Value of I/O port $28
$C00E Value of I/O port $2E
$C00F - $C063 Unknown
$C018 - $C019 Some offset used by the resource memory pool
$C01A - $C01B Another offset used by the resource memory pool
$C01C - $C063 Unknown
$C064 Power-on-graphic flag
$C065 Alarm tone flag
$C066 - $C1C9 Unknown
$C1CA SysSoundFlag
$C1CF Input buffer get index 
$C1D0 Input buffer put index 
$C1D1 - $C200 Input buffer
$C207 Countdown timer value
$C210 - $C215 Unknown
$C216 Current text font
$C217 - $C357 Unknown
$C357 Active screen (real, virtual)
$C358 - $C35E Unknown
$C35F Dot size
$C360 - $C362 Unknown
$C363 Screen orientation
$C364 - $D740 Unknown
$D741 - $ED0B(?) Resource memory pool
$ED0C - $F600 Unknown
$F600 - $F8CC Library temporary storage area
$F8CD Limit of stack?
$FFF0 Base of processor stack (stack grows downward)
$FFF1 - $FFFF Unknown

 

Banked ROM Memory Contents

Bank Description
$0000 Mirror of base memory $0000 - $3FFF
$0001 System function code, address table for bank $00,01 calls
$0002 System function code - OS update code, system reset code
$0003 Font 0 ($4000), 2 ($6000) data in portrait mode
$0004 Font 1 ($4000) data in portrait mode
$0005 Font 0 ($4000), 2 ($6000) data in landscape mode
$0006 Font 1 ($4000) data in landscape mode
$0007 Font 4 data in portrait ($4000) and landscape ($6000) mode
$0008 - $0009 Diagnostic functions
$000A - $003D Banked function code
$003E Blank (all $FF)
$003F Banked function index tables: internal ($4000 - $4D0A), library ($6800 - $6C91)
$0040 System icon index; system message index
$0041 - $0043 System icons
$8000 - $8004 Unknown
$8005 System strings ($4000 - $6017); Menu items ($6800 - $7B44)
$8006 Lists (default) ($6A00 - $6BAF); categories ($6C46 - $6F36); field names ($6F3D -$766C)
$8007 - $8009 T9 program and data?
$800A - $8010 Unknown
$8011 - $8013 Empty (all $FF) (T9 user dictionary expansion area?)
$8014 T9 user dictionary
$8015 - $807F Installed applet area (bottom), data table storage (top)

 

Base Function List (system, file, graphics, I/O, sound functions)

Category Name Address
File File Close $0159
  File Open $0150
  File Read $0153
  File Seek $0156
Graphics Clear Region $0096
  Clear Screen $0093
  Draw Bitmap $00C3
  Draw Circle $00B7
  Draw Filled Circle $00E1
  Draw Filled Rectangle $00AE
  Draw Icon $00BA
  Draw Line $00B1
  Draw Pixel $00B4
  Draw Rectangle $00AB
  Get Active LCD $0081
  Get / Set Power-On Graphic Flag $0027
  Draw System Icon $0168
  Get Display Orient $0072
  Get Dot Size $006C
  Get Font $00D8
  Get Line Size $0078
  Get String Width $00DE
  Gray Region $009C
  Invert Region $0099
  LCD Copy $0084
  Restore Region $00C9
  Save Region $00C6
  Scroll Region Down $00A2
  Scroll Region Left $00A5
  Scroll Region Right $00A8
  Scroll Region Up $009F
  Set Display Orient $006F
  Set Dot Size $0069
  Set Draw Area $015C
  Set Font $00D5
  Set Line Size $0075
  Set Real LCD $007E
  Set Virtual LCD $007B
  Swap LCD $00BD
  Write Character $00CC
  Write Aligned String $0138
  Write String $00CF
  Write System String $00D2
Input/Output Clear Input Buffer $01AA
  Close Comm Port $018F
  Get Input (pen, button) $00E7
  Init Comm Port $018C
  Send Comm Char $0192
Memory Far (Bank) Memcpy $011D
  Get Banked Address $3123
  Get RAM Bank $0015
  Get ROM Bank $000F
  Load Bank $311A
  Memcmp $0129
  Memcpy $0120
  Memmove $0126
  Memset $0123
  Read Memory $01BF
  Set RAM Bank $0012
  Set ROM Bank $000C
  Store Banked Address $311D
Sound Get / Set Alarm Tone Flag $002A
  Get / Set SysSoundFlag $001B
  Pen Click $01A4
  Play Sound $0144
  Warning Beep $01A7
String Strcat $010E
  Strcmp $00F9
  Strcpy $0108
  Strcpy $0105
  Stricmp $00FF
  Strlen $00F6
  Strncat? $0111
  Strncmp $00FC
  Strncpy $010B
  Strnicmp $0102
  Strstr $0114
System Auto Power-Off control $0018
  Backlight Control $0021
  Banked Function Call $3003
  Get Battery State $0141
  Get Calculator Menu $014D
  Get Language Code $01AD
  Indirect Call $3018
  Initialize Relative Banked Call $3117
  Power Down Mode $002D
  Processor Reset $0000
  Run Application $0165
  System Call $3000
  System Restart $0009
Time Delay 10ms $0030
  Delay 20ms $0033
  Enable / Disable Alarm $0056
  Enable / Disable Timer $0053
  Get Date $004A
  Get Time $0044
  Set Alarm Time $004D
  Set Date $0047
  Set Time $0041

 
 

Base Function List (math functions)

Category Name Address
Char Clear sign $30C6
  Divide $3006
  Get sign $30D2
  Modulus $3021
  Multiply $3027
  Shift Left $302D
  Shift Right $3033
  Zero or One $3054
Unsigned Char Divide $303C
  Modulus $3042
  Multiply $3048
  Shift Right $304E
Int Divide $3009
  Modulus $3024
  Multiply $302A
  Shift Left $3030
  Shift Right $3036
  Zero or One $3057
Unsigned Int Divide $303F
  Modulus $3045
  Multiply $304B
  Shift Right $3051
Long  Add $305A
  AND $305D
  Compare $3060
  Decrement $3063
  Decrement Oper1 $3066
  Decrement Oper2 $3069
  Divide $306C
  Increment $307B
  Increment Oper1 $307E
  Increment Oper2 $3081
  Modulus $3084
  Multiply $3087
  Neg $308A
  NOT $308D
  OR $3090
  Shift Left $3093
  Shift Right $30A2
  Store $3096
  Store Function Arg $3099
  Store Oper2 Indirect $309C
  Subtract $309F
  XOR $30BD
  Zero or One $30C0
Unsigned Long  Divide $30A5
  Modulus $30A8
  Multiply $30AB
  Shift Right $30BA
Double (Floating Pt.) Absolute value (fabs) $30CF
  Add $30D8
  Compare $30DB
  Decrement Oper1 $30E1
  Divide $30DE
  Increment Oper1 $30F3
  Integer value (dint) $30C9
  Multiply $30F6
  Square root (sqrt) $30D5
  Store $30FF
  Store Function Arg $3102
  Store Oper2 Indirect $3105
  Subtract $3108
Field Extract signed field indirect $300C
  Extract unsigned field indirect $300F
  Insert field indirect $301E
Random Get Random Number $0186
  Randomize $0189
Conversion ASCII to double (atod) $30C3
  Char to double oper1 $30E4
  Char to int oper1 $3012
  Char to int oper2 $3015
  Char to long oper1 $306F
  Char to long oper2 $3075
  Unsigned char to long oper1 $30AE
  Unsigned char to long oper2 $30B4
  Int to double oper1 $30E7
  Int to double oper2 $30ED
  Int to long oper1 $3072
  Int to long oper2 $3078
  Unsigned int to double oper1 $310B
  Unsigned int to double oper2 $3111
  Unsigned int to long oper1 $30B1
  Unsigned int to long oper2 $30B7
  Long to double oper1 $30EA
  Long to double oper2 $30F0
  Unsigned long to double oper1 $310E
  Unsigned long to double oper2 $3114
  Double to ASCII (dtoa) $30CC
  Double to int oper1 $30F9
  Double to long oper1 $30FC
Unknown Unscale Oper1 Ptr3 $3039
  db2dblong $301B

 
 

Banked Functions Overview

The base memory functions listed above are executed simply by "CALL"ing the corresponding address. To ensure compatibility of future OS versions, the code at that address causes a jump to the true "home" of the function.

Most of the GUI-related and data table functions are banked memory functions. Banked functions are accessed quite differently from those in base memory. They are invoked by calling a common function ($3003, Banked Function Call), after loading the BC register pair with a 16-bit index. The Banked Function Call routine then looks up the bank and address of the desired function (indicated by the index) in a table in ROM, and executes it. It is important to remember that these banked functions (listed below) are accessed using the index and function $3003. The index is not the function address, and you would therefore never CALL it.

For those who want more technical detail - there are actually two tables of addresses used to look up function addresses by function $3003. Both are located in ROM bank $3F; the first starting at $4000, and the second at $6800. Both contain 3-byte records, stored as: Low Address Byte, High Address Byte, Bank Number.

The first table contains addresses of functions that appear to be used internally by the OS - they are completely undocumented. The second table contains the addresses of most of the functions in the Avigo SDK. If the routine is in the range of $4000 - $7FFF, it looks it up the first table. If the index is in the range of $0000 - $3FFF, it adds $6800 to it and looks in the second table. Function $3003 is apparently also used to call an application's functions that are declared 'banked'.
 
 

Banked Function List

Category Name Index
BoolField Create $0174
  Draw $011D
  Handle Event $0120
Button Change $0147
  Create $0144
  Draw $00BD
  Draw Status $00C3
  Handle Event $00C0
  Insert $014A
  Press at $01E3
  Press at Invert $01E6
Conversion Numeric to Str $0318
  Str To Numeric $031B
Data Alloc PIM Record Space $038D
  Change Record $0252
  Create Record $0249
  dapReadFieldInfo $04A1
  dapReadTableName $0492
  dapSaveFieldInfo $04A4
  dapSaveTableName $0495
  Delete Record $024C
  Get Data Size $0369
  Get Free Table ID $04A7
  Get Full Record Quantity $048F
  Get Record Quantity $023A
  Get Record Size $023D
  Get Record Status $02F1
  Get Table Count $049E
  Insert Record $0246
  Is Alive Record $048C
  Is Over Filled $0486
  Load Index Table $0234
  Modify Record $024F
  Read Category Info $02D0
  Read Field Info $02E5
  Read Field Item $02DF
  Read Record $0243
  Read Table Name $03A2
  Save Category Info $02D3
  Save Field Info $02E8
  Save Index Table $0237
DateField Clear Date $0342
  Draw $0123
  Handle Event $0126
DeskBox Create $013B
  Draw $00B1
  Draw Title $00B7
  Handle Event $00B4
  Redraw $00BA
Event Clear Event $0201
  Get Event $01F8
  Get Event Mask $0207
  Put Event  $01FB
  Set Event Mask $0204
  Test Put Event $01FE
Group Draw $009C
  Execute $00A2
  Handle Event $009F
  Insert $00AE
  Pre View $00A8
  Redraw $00A5
  Set Current $00AB
  Set State $0099
Input Press at Range $01E0
  Read List Info $02BE
  Read List Name $02BB
  Save List Info $02C1
Lister Create $0159
  Draw $00D2
  Handle Event $00D5
  Pen Down Act $00DB
  Write Item $00D8
Math atod $003C
  dtoa $0039
  sqrt $0036
Menu Change Command Menu $013E
  Create Control Menu $0156
  Disable Command $0189
  Enable Command $018C
MenuField Create $015F
  Draw $00EA
  Handle Event $00ED
Message Send Message $0186
Messagebox Memory Error MessageBox $000C
  Create $018F
NumberField Create $0177
  Draw $0135
  Handle Event $0138
NumberSet Create $0162
  Draw $00F3
  Draw Number $00F6
  Handle Event $00FC
  Set State $00F0
PageArrow Create PageArrow $0150
  Draw $00C6
  Handle Event $00C9
  Insert $0153
Picker ExecPicker (get input w/on-screen keyboard) $0192
Preference Delete App Preference $0006
  Get App Preference Length $0390
  Read App Preference $0000
  Save App Preference $0003
Resource Alloc Block $01EF
  Delete $0183
  Destroy $017D
  Free Block $01F2
  Resource Rotate $0030
SquareField Set State $0108
StackedList Create Stacked List $0165
  Draw $00FF
  Draw Example $0105
  Handle Event $0102
System Get Avigo Version $003F
  Get Flash Password $0258
  Get Private State $0498
  Get Program ID $0009
  Get Sys Data Address $0480
  Get Sys Format $000F
  Set Private State $049B
TextField Draw $03AE
  Handle Event $03B1
Time Add Date $01CB
  Date Difference $01D1
  Get Month Days $01D4
  Get Weekday $01B3
  Write Date $01BC
  Write Time $01BF
TimeField Clear Time $0345
  Draw $0129
  Handle Event $012C
View Draw $0093
  Exec View $0180
  Handle Event $0096
  Set State $0090
Unknown Is Application $0273
  TFD Scan Text $03B7
  TFD Set State $03AB

 
 

I/O Ports

 

 
Port Description
$00 Unknown
$01 Keyboard scan register
$02 Battery select for A/D converter; backlight control
$03 Unknown
$04 Unknown
$05 ROM bank number - low byte
$06 ROM bank number - high byte
$07 RAM bank number - low byte
$08 RAM bank number - high byte
$09 A/D converter select (battery, pen), status
$10 TC8521 Timer 1 sec digit
$11 TC8521 Timer 10 sec digit
$12 TC8521 Timer / Alarm 1 min digit
$13 TC8521 Timer / Alarm 10 min digit
$14 TC8521 Timer / Alarm 1 hr digit
$15 TC8521 Timer / Alarm 10 hr digit
$16 TC8521 Timer / Alarm week digit
$17 TC8521 Timer / Alarm 1 day digit
$18 TC8521 Timer / Alarm 10 day digit
$19 TC8521 Timer 1 month digit
$1A TC8521 Timer 10 month digit; 24 hr select bit
$1B TC8521 Timer 1 year digit; leap year digit 
$1C TC8521 Timer 10 year digit
$1D TC8521 Page register
$1E TC8521 Test register
$1F TC8521 Reset register
$20 Unknown
$21 Unknown
$22 Unknown
$23 Unknown
$24 Unknown
$25 Unknown
$26 Unknown
$27 Unknown
$28 Sound output bit (bit #3)
$29 Unknown
$2A Unknown
$2B Unknown
$2C Unknown
$2D A/D conversion value
$2E Unknown
$2F Unknown
$30 UART Receiver Buffer/Transmitter Holding/Divisor latch (ls)
$31 UART Interrupt Enable/Divisor latch (ms)
$32 UART Interrupt Id/FIFO control
$33 UART Line control
$34 UART MODEM control
$35 UART Line status
$36 UART Modem status
$37 UART Scratch register
$38 Unknown
$39 Unknown
$3A Unknown
$3B Unknown