z80:The Application Header
This page goes into details about the flash application header. The Flash application header is 128 bytes long, and to be honest is a pain because TI thought someone might actually want to make a flash application someone would pay $7 to use. This dream has died a horrible and miserable death, and most application programming nowadays uses the free $0104 key, which still has the long 128 bytes header for sentimental value.
Contents
Components of the App Header
The app header consists of basically 13 or so different sections. They are program length, the type, app ID, build number, name, security signing data, and so on and so on.
The full header
This is the bare minimum for a full application header for a shareware program called "Name". We'll dissect this header to understand each component.
.db 080h,00Fh ;Field: Program length .db 00h,00h,00h,00h ;Length=0 .db 080h,012h ;Field: Program type .db 01h,04h ;Type= Shareware, TI-83Plus .db 080h,021h ;Field: App ID .db 01h ;Id = 1 .db 080h,048h ;Field: App Name .db "Name", 000h, 000h, 000h, 000h ;Name: "Name" .db 080h, 081h ;Field: Number of pages .db 001h ;Pages: 1 .db 080h, 090h ;Field: Security data .db 003h, 026h, 009h, 004h ;Start of security data used with signing .db 013h, 069h, 0DBh, 04Bh .db 002h, 00Dh, 040h, 0A1h, 06Bh, 099h, 0F6h, 059h, 0BCh, 067h .db 0F5h, 085h, 09Ch, 009h, 06Ch, 00Fh, 0B4h, 003h, 09Bh, 0C9h .db 003h, 032h, 02Ch, 0E0h, 003h, 020h, 0E3h, 02Ch, 0F4h, 02Dh .db 073h, 0B4h, 027h, 0C4h, 0A0h, 072h, 054h, 0B9h, 0EAh, 07Ch .db 03Bh, 0AAh, 016h, 0F6h, 077h, 083h, 07Ah, 0EEh, 01Ah, 0D4h .db 042h, 04Ch, 06Bh, 08Bh, 013h, 01Fh, 0BBh, 093h, 08Bh, 0FCh .db 019h, 01Ch, 03Ch, 0ECh, 04Dh, 0E5h, 075h ;End of security data used with signing .db 80h,7Fh ;Field: Program Image length .db 0,0,0,0 ;Length=0, N/A .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h
Workings of the Application Header
The application header works like this: A 2 byte field denotes what the next few bytes of data mean. Depending on the field, this will define how many bytes after is designated to that field. For example, the name field $8048 designates the next 8 bytes for the name of the application, and $800F designates only 4 bytes for the size of your program. This means you can arrange your fields in pretty much any order you want, but for simplicity sake this is the order that the Application Header generation program puts them in, so we'll leave it like this.
Program Length
.db 080h, 00Fh .db 00h,00h,00h,00h
Basically useless unless you want to submit your application to TI so you can sell it. The $800F denotes that this is a length field, and the next 4 bytes are for the actual length of the program. You can leave this at 0 bytes, or if you feel inclined, change it to the length of your program.
Program Type
.db 080h,012h ;Field: Program type .db 01h,04h ;Type= Shareware, TI-83Plus
Again, another archaic remnant of TI's long dead dream. Again, the first line denotes the field type is "Program type", and the next line is the developers key ($0104 is the shareware key, or you can "buy" a special key from TI to develop to let you charge people, which means no one will use your app). Best to leave this field as it is shown here.
App Build
.db 080h,021h ;Field: App ID .db 01h ;Id = 1
App build again is used if you want to sell your application. ID 1 is for shareware, and any other ID comes with the special key you can buy from TI.
Name
.db 080h,048h ;Field: App Name .db "Name", 000h, 000h, 000h, 000h ;Name: "Name"
Yeah, something really useful! Again, $8048 denotes the name field, and the next 8 bytes is the name of your flash application as it will show in the Apps menu on your calculator. Note that because of the way the app fields work, you must fill in exactly 8 bytes (fill the end with $00 or ' ' if you want a name shorter than 8) - no more, no less.
Number of pages
.db 080h, 081h ;Field: Number of pages .db 001h ;Pages: 1
Another useful field. This is for how many app pages you are going to use. remember, each app page is 16k, and whether you actually fill up that page or not, it will still take up the whole 16k to store the program.
Security Data
.db 080h, 090h ;Field: Security data .db 003h, 026h, 009h, 004h ;Start of security data used with signing .db 013h, 069h, 0DBh, 04Bh .db 002h, 00Dh, 040h, 0A1h, 06Bh, 099h, 0F6h, 059h, 0BCh, 067h .db 0F5h, 085h, 09Ch, 009h, 06Ch, 00Fh, 0B4h, 003h, 09Bh, 0C9h .db 003h, 032h, 02Ch, 0E0h, 003h, 020h, 0E3h, 02Ch, 0F4h, 02Dh .db 073h, 0B4h, 027h, 0C4h, 0A0h, 072h, 054h, 0B9h, 0EAh, 07Ch .db 03Bh, 0AAh, 016h, 0F6h, 077h, 083h, 07Ah, 0EEh, 01Ah, 0D4h .db 042h, 04Ch, 06Bh, 08Bh, 013h, 01Fh, 0BBh, 093h, 08Bh, 0FCh .db 019h, 01Ch, 03Ch, 0ECh, 04Dh, 0E5h, 075h ;End of security data used with signing
TI went through a lot of trouble to ensure that people don't "steal" non-shareware apps. This is used when signing an app, and it is best to leave it as is.
Program Image length
.db 80h,7Fh ;Field: Program Image length .db 0,0,0,0 ;Length=0, N/A
This is the length of the program image. It's value is determined at compile time, and is best to leave it as is. Or feel free to change it, it will be changed anyways and you would have wasted your time.
Padding
.db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h, 000h ;padding .db 000h, 000h, 000h
The padding is if you want to add any extra fields. Because the app header must be exactly 128 bytes, they are here.
Extra Fields
These fields don't have to be included in the application, but some of them are quite nice. Remember, for every field you add you must adjust the padding so your header is exactly 128 bytes long.
TI Default Splash Screen
db 080h,090h ;No default splash screen
TI has a default splash screen that displays some the name of your program, application build, and other stuff based on the data you supply. However, it is WAY slow and annoying, so if you include this line it won't be displayed.
"And there was much rejoicing in the land: Yay." - Monty Python and the Holy Grail
+=== App Build === Number
.db 080h,031h ;Field: App Build .db 01h ;Build = 1
This is the build number of your application ("ver 1.0 Build 1) It's value does not affect your application at all, but sometimes it might be nice to change, especially so users can keep up to date on the most recent build of your app.
Program Revision
.db 080h, 021h ;Field: Program Revision .db 001h ;Value: 1
This is the version of your program. Pretty sure it's the number to the left of the decimal (taking "ver 1.0 build 2", it is the 1)
Program Expiration Date
This is when your program expires. It is specified in number of seconds 1/1/1997. It can not be included in freeware apps, and since I didn't want to buy a special TI key, I don't know the code.
Program overuse count
Number of times your program can be run. Note that if you choose to include this field (which you can't for freeware apps) it's value must be at least 16. Couldn't find the code because I don't want to buy the special TI key...
Maximum Hardware Revision
.db 080h, 0A1h ;Field: Maximum hardware revision .db 000h ;value: 0
This is the maximum hardware revision your program will run on. Not exactly sure what this is for, so unless you do, probably best to leave it off...
Lowest Base code
.db 080h, 0C2h ;Field: Lowest Base Code .db 001h, 00Dh ;Value: 1.13
This is the lowest base code your flash application will run under. Another name for base code is OS version. The first byte is for the number to the left of the decimal (1 for 83+/SE, 2 for 84+/SE), and the second byte is for the number to the right of the decimal.
App Header Program
TI has created a Windows application that creates an app header for you. It is downloadable here. Type in the name, Developer Key(more on that in a sec), pages... etc. and it will spit out for you the required header, no fuss about it.
Conclusion
That's all there is to the application header.
