(cross post from omni)

For the Walnut shell all machine executable programs will use the gxp format which is named after the popular 8xp extension used on the 83+. The packet design was originally designed by Qwerty.55 for use in a Prizm shell and has it's advantages in a variable size header that can be modified in the future with ease. The layout is in packets with each holding a different category. All are optional except for the first one which holds important information such as the name of the program. Other data such as the icon and advanced start up options are available in different packets. This is the current packet layout for the first version of Walnut. It is not set in stone and also keep in mind that the Walnut SDK will fill out these fields.




Code:
//all packets must be long word aligned

packet 0: required
word: identifier 0x0000
word: SDK version
long: Walnut identifier "wnut"
long: file offset to main
long: checksum of entire file excluding this
long: size of entire file
long: size of main
char: null terminated program name
char: null terminated description
//end of packet 0

packet 1: start-up info
word: identifier 0x0001
word: execution mode (0x0000: from flash in virtual memory, 0x0001: from ram in virtual memory, 0x0002: from flash in the p1 sector, 0x0003: from ram in the p1 sector, 0x0004: from flash in the p2 sector, 0x0005: from ram in the p2 sector)
long: requested origin (should be set to 0xffffffff in most cases for the default origin based off the previous mode choice)
long: value to be written to the FRQCR  0xffffffff for don't modify
//end of packet 1

packet 2: author info
word: identifier 0x0002
word: blank for alignment
long: author's 4 initial identifier eg "z80m"
char: null terminated author name
char: author logo compression mode (0x00: no image, 0x01: monochrome, 0x02: 8 color, 0x03: 256 color using Walnut's palatte, 0x04: 256 color with included palatte, 0x05: 16 bit bitmap, 0x06: 16 bit dxt)
image data: all author icons are 16x16 pixels
char: null terminated author name
//end of packet 2

packet 3: program icon
word: identifier 0x0003
word: height
word: width
char: icon compression mode (0x00: no image, 0x01: monochrome, 0x02: 8 color, 0x03: 256 color using Walnut's palatte, 0x04: 256 color with included palatte, 0x05: 16 bit bitmap, 0x06: 16 bit dxt)
image data:
//end of packet 3
Can I assume that if I decide to make a Doors ZCS or something, that I could add my own types of packets overlapping or replacing packets 1-3? Do you intend to be able to recognize any other format with Walnut?
KermMartian wrote:
Can I assume that if I decide to make a Doors ZCS or something, that I could add my own types of packets overlapping or replacing packets 1-3? Do you intend to be able to recognize any other format with Walnut?
It shouldn't be that hard to recognize other formats even if Doors ZCS also uses the gxp extension. Just as long as Doors ZCS doesn't use the "wnut" identifier in the first packet Walnut will be able to recognize the different format. And the way I'm doing future extensions to the packet layout is based off the word field in the first packet that contains the SDK version. Based off the SDK version, Walnut will know how to parse the packet layout.
It seems like you're losing quite a bit of the flexibility that Qwerty.55's format was going to have. You have identifiers for which shell the program is for, and even what version of the SDK it was made with... These don't really have a purpose, unless you plan to treat programs that are for different shells/made with different versions of the SDK in separate ways. This is bad, because then old versions of shells won't be able to read those new files!

On the 8x calcs, programs from old shells work in new shells, but not vice-versa. Sometimes someone might want to use an older shell because they like it better, but they won't be able to do that. If we design this format in a good way, we might be able to avoid that problem completely on the Prizm. Programs should be made for all Prizm shells - not a specific shell on the Prizm. The format that Qwerty.55 suggested allowed new shells to add new features in files by adding new packages, while still allowing the files to work correctly with older shells, unless the packet was "critical", as indicated by a list.

There are also a few things with the packets that you currently have that I would like to be changed. (It's a good idea to split your packets a bit so that you don't have everything in one packet!)

1. Unlike Qwerty.55's format, the size of the packets don't seem to be stored anywhere. How is the shell supposed to know where they end in cases where the size of the packet isn't obvious?
2. Like I said before, I don't see the point in storing the SDK version and the program's shell.
3. The description of the program shouldn't be in the critical packet, because it's not necessary to include a description for every program.
4. The checksum should also be optional. Don't place it in the critical packet.
5. It's better to indicate main() by giving it a packet ID. "file offset to main" shouldn't be necessary.
6. Does "size of main" have a purpose?
7. Why do we need to include the first four characters of the author's name?
8. Please don't require programmers to include an author icon if they don't include an author name. The icon should be a separate packet.
9. Why is the author's name stored twice, once before the icon and once after?
Those questions answered here http://ourl.ca/11992/226692
Could you please copy over your reply? That way it is stored on both databases, and so some of us can see it (I can't).
No prob


Quote:

Based on what you've written in this post as well as the reply to Kerm's post on Cemetech, it seems like you're losing quite a bit of the flexibility that Qwerty.55's format was going to have. You have identifiers for which shell the program is for, and even what version of the SDK it was made with... These don't really have a purpose, unless you plan to treat programs that are for different shells/made with different versions of the SDK in separate ways. This is bad, because then old versions of shells won't be able to read those new files!

On the 8x calcs, programs from old shells work in new shells, but not vice-versa. Sometimes someone might want to use an older shell because they like it better, but they won't be able to do that. If we design this format in a good way, we might be able to avoid that problem completely on the Prizm. Programs should be made for all Prizm shells - not a specific shell on the Prizm. The format that Qwerty.55 suggested allowed new shells to add new features in files by adding new packages, while still allowing the files to work correctly with older shells, unless the packet was "critical", as indicated by a list.

There are also a few things with the packets that you currently have that I would like to be changed. (It's a good idea to split your packets a bit so that you don't have everything in one packet!)

1. Unlike Qwerty.55's format, the size of the packets don't seem to be stored anywhere. How is the shell supposed to know where they end in cases where the size of the packet isn't obvious?
2. Like I said before, I don't see the point in storing the SDK version and the program's shell.
3. The description of the program shouldn't be in the critical packet, because it's not necessary to include a description for every program.
4. The checksum should also be optional. Don't place it in the critical packet.
5. It's better to indicate main() by giving it a packet ID. "file offset to main" shouldn't be necessary.
6. Does "size of main" have a purpose?
7. Why do we need to include the first four characters of the author's name?
8. Please don't require programmers to include an author icon if they don't include an author name. The icon should be a separate packet.
9. Why is the author's name stored twice, once before the icon and once after?
Okay I'll try to answer these questions as best as I can

1. Thinking about it now, to allow for newer programs to run on older shells the size of a packet should be the second word included that way Walnut can skip past unfamiliar packets. Otherwise Walnut was going to rely on knowing the size of the packet based off the SDK version but that can now be fixed.
2. The SDK version number allows for Walnut to know which version of the packet layout is being used. Having an SDK version number higher than the shell number shouldn't prevent a program from running but may cause some errors in displaying data. The way each packet is arranged shouldn't change once Walnut is released so that is why I want to get all the issues out now by making this public. Also for the "wnut" that is just an identifier that the shell uses so it knows that the file was designed for Walnut and uses the Walnut packet layout. It is just like how java .class files start with 0xcafebabe as an identifier.
3. That can be moved easily to another packet but even if the developer doesn't want to include a description that field will only take 1 byte if blank. The description is like a subtext that can be displayed with the title.
4. The reason for the checksum being there was that if there was a binary error in the header or executable then there is a possibility that the calculator could crash or even brick. For example if the FRQCR field was corrupted Razz Don't forget that the SDK will calculate that on it's own when a project is built similar to what mkg3a already does.
5. A packet for main is also doable. The reason for having the offset was so that it could be quickly located and wouldn't have to be searched for.
6. Size of main just means the size of the executable. This is very important as it affects what Walnut will write to the MMU when the program begins.
7. The first 4 letters could also be more like their initials. This data will never be displayed to the user but is so that Walnut has the ability to organize programs by author if the user wishes to do so.
8. They don't have to include an icon. By setting the icon compression mode to 0 it means that there is no image and Walnut will not expect one.
9. Whoops Wink
z80man wrote:
1. Thinking about it now, to allow for newer programs to run on older shells the size of a packet should be the second word included that way Walnut can skip past unfamiliar packets. Otherwise Walnut was going to rely on knowing the size of the packet based off the SDK version but that can now be fixed.
Good.
z80man wrote:

2. The SDK version number allows for Walnut to know which version of the packet layout is being used. Having an SDK version number higher than the shell number shouldn't prevent a program from running but may cause some errors in displaying data. The way each packet is arranged shouldn't change once Walnut is released so that is why I want to get all the issues out now by making this public.
I don't see how it would be necessary to know the version if the packet layout if the packets aren't going to change...
z80man wrote:
Also for the "wnut" that is just an identifier that the shell uses so it knows that the file was designed for Walnut and uses the Walnut packet layout. It is just like how java .class files start with 0xcafebabe as an identifier.
So if future shells want to have backwards compatibility with Walnut, would they need to include the wnut string? Wouldn't it be better to use something that doesn't refer to the name of this shell?
z80man wrote:
3. That can be moved easily to another packet but even if the developer doesn't want to include a description that field will only take 1 byte if blank. The description is like a subtext that can be displayed with the title.
Moving it to another packet makes the layout a bit more flexible. If everything is going to be put in the same packet, the advantage with the packet layout is not being used.
z80man wrote:
4. The reason for the checksum being there was that if there was a binary error in the header or executable then there is a possibility that the calculator could crash or even brick. For example if the FRQCR field was corrupted Razz Don't forget that the SDK will calculate that on it's own when a project is built similar to what mkg3a already does.
But what if someone quickly wants to hack together a program without using the SDK? The file format is supposed to remove the limitations of the .g3a format, and the checksum is one of them.
z80man wrote:
5. A packet for main is also doable. The reason for having the offset was so that it could be quickly located and wouldn't have to be searched for.
6. Size of main just means the size of the executable. This is very important as it affects what Walnut will write to the MMU when the program begins.
This makes sense. I'm fine with having it the way it is now.
z80man wrote:
7. The first 4 letters could also be more like their initials. This data will never be displayed to the user but is so that Walnut has the ability to organize programs by author if the user wishes to do so.
Why can't authors be sorted based on their full name?
z80man wrote:
8. They don't have to include an icon. By setting the icon compression mode to 0 it means that there is no image and Walnut will not expect one.
Just like with 3., I think that splitting things up into multiple packets makes things more flexible.
What happened with Walnut? Is it still being worked on?
I believe his schedule overwhelmed him. I still plan to make a Door CZ at some point in the future, though. Smile
What does the "Z" stand for in "Door CZ"?
KermMartian wrote:
I believe his schedule overwhelmed him. I still plan to make a Door CZ at some point in the future, though. Smile


Indeed, last we've seen of z80man was last year, at latest in October or November. Perhaps he does indeed have some progress on this, and we're just all out of touch. My bets though are that it's probably dormant and will awaken when he does as well.

As for a shell, we really do need one (it's not imperative, but it'd be nice). Perhaps a team effort this time amongst cemetechians? If we push too many more demands onto Kerm's stack, I'm pretty sure we'll cause a rather nasty overflow.
Spenceboy98 wrote:
What does the "Z" stand for in "Door CZ"?

Pri_Z_m.
  
Register to Join the Conversation
Have your own thoughts to add to this or any other topic? Want to ask a question, offer a suggestion, share your own programs and projects, upload a file to the file archives, get help with calculator and computer programming, or simply chat with like-minded coders and tech and calculator enthusiasts via the site-wide AJAX SAX widget? Registration for a free Cemetech account only takes a minute.

» Go to Registration page
Page 1 of 1
» All times are UTC - 5 Hours
 
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum

 

Advertisement