Table of Contents
|
Intro
In order for the TI-OS to recognize your application, it has to start with a special header. This header is comprised of various fields, some of which are optional. Most applications can get by with a minimal header.
The Minimal Header
The following is an example of a minimal header for an application named "AppName".
.org $4000
.db $80,$0F, 0,0,0,0 ;This is the master field, 0x800
.db $80,$12, $01,$04 ;signing key ID. This is $01,$05 for the 84+CSE
.db $80,$47, "AppName" ;change the $47 according to name len (last nibble is the length).
.db $80,$81, 1 ;num pages
.db $80,$90 ;disable splash
.db $03,$22,$09,$00 ;null date stamp
.db $02,$00 ;null date stamp signature
.db $80,$70 ;final field
appstart:
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 a maximal header for a full application header for a shareware program called "Name". Many apps will still have this format as it was at one point erroneously believed that this much bloat was necessary. 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: Revision Number
.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: Disable Splash Screen
.db 003h, 026h, 009h, 004h ;Field: Date Stamp
.db 013h, 069h, 0DBh, 04Bh ;I'll be honest, I ain't got a clue, but it's the data for the date field, so probably epoch time -- Zeda. WikiTI probably has the answer :P
.db 002h, 00Dh, 040h, 0A1h, 06Bh, 099h, 0F6h, 059h, 0BCh, 067h ;Field: App signature
.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 App Signature
.db 80h,7Fh ;Field: Program length
.db 0,0,0,0 ;Length=0, N/A
.db 000h, 000h, 000h, 000h ;Unnecessary padding, not required.
.db 000h, 000h, 000h, 000h ;padding
.db 000h, 000h, 000h, 000h ;padding
.db 000h, 000h, 000h, 000h ;padding
.db 000h, 000h, 000h
The name field can be structured so that it doesn't need padding (change the size to 4 instead of 8), the datestamp and its signature, while required, can instead be structured to be empty.
The 807 field (final field) is not necessary. Use 8070 and start your app immediately after, with no weird padding.
Workings of the Application Header
The application header works like this: A 2 byte field denotes what the next few bytes of data mean. The first three nibbles act as a field ID, the last nibble is field-specific, often being the size in bytes of the subsequent data. 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: Developer Key
.db 01h,04h ;Key ID= 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.
Note: For the 84+CSE, the shareware key is $0105.
Revision Number (Optional)
.db 080h,021h ;Field: Revision Number
.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,044h ;Field: App Name
.db "Name" ;Name: "Name"
Yeah, something really useful! Again, $804 denotes the name field, $8044 means it is a name field of 4 bytes. In this example, the next 4 bytes is the name of your flash application as it will show in the Apps menu on your calculator.
Number of pages
.db 080h, 081h ;Field: Number of pages
.db 1 ;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.
Disable Splash Screen
.db 080h, 090h ;Field: Disable TI Splash Screen
Including this field automatically disables TI's splash screen. Pretty please do us all a favor and disable it in your app.
Date Stamp
.db 003h, 026h, 009h, 004h
.db 013h, 069h, 0DBh, 04Bh
This is the datestamp, usually when the app was made. It is a necessary field, but can be made null.
Signature
.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
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 while it is a required field, the data can be empty.
Program Image length
.db 80h,7Fh ;Field: Program Image length
.db 0,0,0,0 ;Length=0, N/A
The field is necessary, but can be made empty. Change the size of the field to 0 instead of F, then you don't need those subsequent 4 bytes. Regardless, program execution starts immediately after the field data.
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
100% unnecessary. In fact, this will all be executed as code anyways, so just lose the padding, and start your code there instead.
Extra Fields
These fields don't have to be included in the application, but some of them are quite nice. Remember that the app header shouldn't extend past 128 bytes. Or else.
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.
Also, you can resize the field if you need more bytes. Truthfully, while convenient, you can save some bytes by keeping your own internal variable.
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 download-able 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. You could utilize the app header to it's fullest by getting a special developers key, but then you would have to go here.