LTO Flash filesystem, wire protocol, and file format documentation

[intvnut]

Much like Xeno's paradox, I've been asymptotically approaching a release for these documents at an ever slowing rate.  I may as well push them over the line and unleash them to the world.

 

The Locutus File System and Wire Communication Protocol document describes how to talk to an LTO Flash! cartridge over its USB serial link.  If someone wants to build a 3rd party GUI or set of command line tools, this is the document that says how to do it.

 

The Locutus Universal Intellivision Game Image (LUIGI) document describes how LTO Flash! stores game images in its internal flash, and how it unifies the BIN+CFG and ROM formats.

 

Several folks have seen and reviewed earlier versions of these documents, including intvsteve, lathe26, Games For Your Intellivision, decle, nanochess, and others I'm sure I've forgotten.  I want to thank all of my reviewers for poring over this technical material in advance of its release.

 

Locutus_File_System_and_Wire_Communication_Protocol_V1_0_20190704A.pdf Locutus_Universal_Intellivision_Game_Image_(LUIGI)_V1_0_20190706A.pdf

[intvnut]

I'm curious whether anyone has any questions or comments on the material.  ?

[+Lathe26]

I hope to read the File System in a while, just a bit bogged down with other things at the moment.  At least I’ve already given feedback on the LUIGI doc when I had free time.

[+Lathe26]

Thanks for publishing this.  Here's my feedback:

1. Page 7: The big diagram could use some more explanation on the lines.  For example, if the green lines represent parent directories, shouldn't these point to GDNs instead of GFNs?  GFN #0 and GFN #2 both have directory fork links, do the other GFNs have these, too, but they were omitted for brevity?  Is it correct to assume that the green arrows point "from member to parent directory"?
   1. Ok, I see that this is better explained on page 9.  Maybe a brief explanation should include on page 6 or 7 that states something like "GDN is the list of GFN entries that the directory contains but GDNs do not define what type each entry.  Instead, GFN states what it is (i.e. a sub-directory or a file)."
   2. Maybe GFN 0 should have a different color and state that it has special meaning that is defined later (or that it is the root directory and contains "basic device data instead of typical GFN data")
2. Page 7: gdn_t can be 0-127 or 0xFF.  Was this supposed to say 0-126 instead or is the 0xFF not a special value?
3. Page 31: in Command 0x1D Delete File, should the specified entry be marked as 0xFFFF instead of 0xFF?  Or was this intended to mean that the entire struct is overwritten with bytes of 0xFF?
4. Page 32: Command 0x1E, similar question as previous
5. Page 32: Command 0x1E mentions that the GDN 0 has its parent directory set to 0x0000.  This should probably be mentioned on page 10 when the root directory is discussed (page 10 already covers GFN 0 but not GDN 0)

[intvnut]

2 hours ago, Lathe26 said:

Thanks for publishing this.  Here's my feedback: 

1. Page 7: The big diagram could use some more explanation on the lines.  For example, if the green lines represent parent directories, shouldn't these point to GDNs instead of GFNs?  GFN #0 and GFN #2 both have directory fork links, do the other GFNs have these, too, but they were omitted for brevity?  Is it correct to assume that the green arrows point "from member to parent directory"?
   1. Ok, I see that this is better explained on page 9.  Maybe a brief explanation should include on page 6 or 7 that states something like "GDN is the list of GFN entries that the directory contains but GDNs do not define what type each entry.  Instead, GFN states what it is (i.e. a sub-directory or a file)."
   2. Maybe GFN 0 should have a different color and state that it has special meaning that is defined later (or that it is the root directory and contains "basic device data instead of typical GFN data")
2. Page 7: gdn_t can be 0-127 or 0xFF.  Was this supposed to say 0-126 instead or is the 0xFF not a special value?
3. Page 31: in Command 0x1D Delete File, should the specified entry be marked as 0xFFFF instead of 0xFF?  Or was this intended to mean that the entire struct is overwritten with bytes of 0xFF?
4. Page 32: Command 0x1E, similar question as previous
5. Page 32: Command 0x1E mentions that the GDN 0 has its parent directory set to 0x0000.  This should probably be mentioned on page 10 when the root directory is discussed (page 10 already covers GFN 0 but not GDN 0)

 

Thanks for the detailed review!

 

#1:  I pretty much hate that diagram and I think it would benefit from being broken up into multiple diagrams.  I ran out of brain juice trying to come up with a clear way of expressing the relationship between GDT, GFT, and GKT.  You're absolutely right, this portion could stand to be clarified and expanded a bit.

 

#2:  I don't see the contradiction here.  127 is 0x7F, while 255 is 0xFF (the "not valid"/"not present" special value).

 

#3:  The entire record gets overwritten with 0xFFs.  Perhaps saying "0xFFs" would be clearer?  e.g. "Overwrites the entire specified entry ... with 0xFFs."  That 's' hopefully makes it clear that there's more than one 0xFF.

 

#4:  Ditto.

 

#5:  I see what you mean.  Originally, only GFN #0 was special.  GFN #0 could theoretically point to any GDN.  But, it must always point to a valid GDN, and so by convention, GDN #0 is reserved for the root directory, and its parent directory (unless set otherwise) is itself.  Yes, you could set up the "root" directory to have a parent directory "above" it.  Nothing stops you from creating an arbitrary graph structure here.

 

 

Out of curiosity, what do you think of the architecture?

[+Lathe26]

4 hours ago, intvnut said:

#2:  I don't see the contradiction here.  127 is 0x7F, while 255 is 0xFF (the "not valid"/"not present" special value).

 

Doh!  That's what I get for reviewing while drinking a club soda with Vikra vodka.  ?

 

4 hours ago, intvnut said:

Out of curiosity, what do you think of the architecture?

 

 

I think it looks great.  At first, I was wondering why not go with an existing file system (ex: FAT32 + VFAT) but the current architecture is far better at reducing FLASH memory wear.

 

 

[intvnut]

FWIW, I've integrated some changes to clear up #3, #4, and #5.  I still need to think about how I'm going to fix #1.   Again, thanks for the review.