Sphinx‎ > ‎Documentation‎ > ‎Reference‎ > ‎

sxfs

Sxfs is the Sphinx file system. It implements a barebones FAT16 file system on SD cards. It occupies three cogs and requires 139 longs of hub memory, most of which is a 512-byte metadata buffer. Sxfs supports multiple open files. Every open file requires 134 longs for a sector buffer and housekeeping variables. Sxfs can read a file, write a file, and load a file into hub memory and execute it.
 
Programs that want to use sxfs's functionality should use the sxfs interface object, isxfs, or a higher level file object such as sxfile. Only programs that need to install the sxfs driver, such as sphinx.bin, should use the sxfs object itself.

Spin interface method

  • pub Start( sdPin ) -- starts the three sxfs cogs if they are not already running. Returns true if the cogs needed to be started, false if they were already running.

Implementation notes

Communication to and from sxfs is done through a rendezvous of four longs. (The three sxfs cogs communicate with each other through their own private rendezvous locations.) The four longs are command, param0, param1, and param2 (starting at hub address $7fcc). To perform a file operation, set up the parameters and then set command to a command value. Wait until command becomes 0, indicating that the operation has completed, and exmine param0 for a return code. A negative return code indicates that an error has occurred.
 
Instead of waiting, one could arrange to continue doing something else while the file operation completes asynchronously. Sphinx does not take advantage of this capability.
 
The commands and their parameters are as follows:
 command  param0  param1  param2  Description 
 "?"    Does nothing but acknowledge to indicate that sxfs cog is active.
 "O" filestuff filename mode Open a file, populate filestuff fields. mode is "R" or "W".
 "R" filestuff buffer num Reads num bytes into buffer from file specified by filestuff.
 "W" filestuff buffer num Writes num bytes from buffer to file specified by filestuff.
 "C" filestuff   Closes file specified by filestuff.
 "X" filestuff execmode cog Executes file. See below.
 
filestuff is a pointer to a 134-long area of hub memory. Each open file requires its own filestuff area.
 
The execute command reads 63 contiguous sectors from the SD card into hub memory. It does not read 64 sectors because the 64th sector would overwrite the rendezvous locations for the various Sphinx drivers. This could conceivably cause some files not to run properly.
 
Because sxfs assumes that a 32k file occupies 64 contiguous sectors on the SD card, the card must be formatted with a cluster size of at least 32k.
 
Of course, .bin files do not necessarily take up all 32k. Sxfs reads 63 sectors but then clears memory above the actual extent of the file.
 
If execmode is 0, sxfs starts up a Spin interpreter in cog cog. If execmode is non-0, sxfs shuts down all cogs except cog cog; it also resets the system clock if necessary.
 
The isxfs object takes care of all those details. The sxfile object additionally encapsulates a filestuff area.
 
One of the sxfs cogs runs a slightly modified version of sdspiqasm.spin by Tomas Rokicki.