=== main
=== all
The following commands are available:

cleandir		Clean FFS directory
cpout			Copy content out of device FFS to host file system
cpout-file		Copy out a single file
dieid			Retrieve Calypso die ID via ETM query
exec			Execute a command script
exit			Exit from fc-fsio
fd			Low level file descriptor operations
ffs2ver			TMFFS2 version query
format			Format FFS on device (dangerous!)
fwrite			Write a file into device FFS
hd			Hex dump of a file in FFS
ls			Directory listing
ll			Shorthand for ls -l
memdump			Dump a target memory region via ETM command
omemdump		Dump a target memory region via TM3 command
mkdir			Create a directory in device FFS
mk-std-dirs		Create standard set of FFS directories
pirelli-get-imei	Retrieve factory IMEI on Pirelli DP-L10
pirelli-magnetite-init	Initialize FFS for FC Magnetite fw on Pirelli target
preformat		Preformat FFS on device (dangerous!)
readlink		Raw interface to ffs_readlink() API call
rm			Delete FFS object
rm-subtree		Delete FFS directory subtree
set-imeisv		Write /etc/IMEISV or /pcm/IMEI file
set-pcm-string		Write /pcm/CGxx files
set-rfcap		Write /gsm/com/rfcap file
stat			Raw interface to ffs_xlstat() API call
symlink			Create a symlink in device FFS
upload-file		Upload a file into device FFS
upload-fs		Upload a complete file system tree into device FFS
upload-rf-table		Upload an RF calibration table into device FFS
upload-subtree		Upload a subtree into device FFS
write-battery-table-v1	Upload table of battery thresholds into device FFS (v1)
write-battery-table-v2	Upload table of battery thresholds into device FFS (v2)
write-bsim-config	Create Battery Simulation configuration file
write-charging-config	Upload FCHG configuration into device FFS

To get help on any command, type help and the command keyword.

The RTOS environment inside GSM device firmwares with which this utility
communicates has no notion of a current directory, hence all target side
FFS pathnames must be absolute.

=== cleandir
cleandir ffs-pathname

This command deletes all files and subdirectories contained in the named FFS
directory, leaving an empty directory; the named FFS directory must exist.

This command is primarily intended for cleaning out the /mmi directory when
experimenting with different UI firmware versions, or after loading AT command
modem firmware into a device which previously ran some fw version with UI layers
included.

=== cpout
cpout target-pathname host-pathname

This command copies a single file, a directory subtree or the complete device
file system tree from the target device FFS to your Unix host file system.

=== cpout-file
cpout-file target-pathname host-pathname

This command is like regular cpout, but assumes that the target pathname refers
to a single file and not a directory, and skips the pathname validation and
xlstat query steps toward that end.

=== dieid
This command sends an ETM query for the Calypso die ID to the running firmware
on the target and displays the returned result.

=== exec
exec script-filename

This command executes an fc-fsio command script; each line in the script file
is interpreted and executed as an fc-fsio command.

If the execution of any command in the script file encounters an error, the
processing of the script is stopped and the following commands won't be
executed.

=== exit
This command is self-explanatory.

=== fd
fd open ffs-pathname flags
fd read tfd nbytes
fd close tfd

These low-level debug commands provide a raw interface to FFS file descriptor
operations ffs_open(), ffs_read() and ffs_close(); they are intended for deep
developers only.

=== ffs2ver
This command sends a TMFFS2 version query ETM packet to the running firmware
on the target and displays the returned result.

=== format
format format-name

This command requests the GSM device firmware to format its flash file system.
The "format name" argument must begin with a forward slash and will be stored
in the root inode of the newly created FFS; it can also contain some FFS tuning
settings - see the FFS firmware component source code for the details.  It is
usually sufficient to set the "format name" aka the root inode name to just /,
although some production lines (TI and Openmoko) have set it to /ffs-root.

The FFS component in the firmware will normally accept this command only when
the FFS is in the unformatted state; if instead you wish to blow away an
existing format, see the preformat command.

=== fwrite
fwrite ffs-pathname ascii "ASCII string content"
fwrite ffs-pathname hex "xx xx xx xx ..."
fwrite ffs-pathname file host-filename

This command creates a file or overwrites an existing file in the device FFS,
using an ASCII string, a binary string given as hex bytes or a host file as the
content to be written.

=== hd
hd ffs-pathname

This command displays a hex dump of the named file in FFS, which must be a
regular file.  It will only work if the size of the file is 254 bytes or less;
to examine larger FFS files, you will need to read them out with the cpout or
cpout-file command.

=== ls
ls [-l] ffs-pathname

This command works much like the classic UNIX ls command, but on the flash file
system of a GSM device.  In the basic form (without -l) the named FFS object
must be a directory, and the operation of the ls command is limited to ETM
packet exchanges corresponding to ffs_opendir() and ffs_readdir() API calls.
In the long form (with -l) the named FFS object may be of any type (file,
directory or symlink), and the operation of the ls command involves additional
ETM packet exchanges corresponding to the ffs_xlstat() API call, as well as some
FFS pathname validation and manipulation inside the fc-fsio utility itself.

=== ll
ll ffs-pathname

This command is a shorthand for ls -l on the given FFS pathname.

=== memdump
memdump addr length

This command requests a read of a target memory address range via the ETM
memory read command, and displays the returned bytes as a hex dump.
Both arguments are always interpreted as hexadecimal, and the length may not
exceed 0xEE (238 decimal) - the limit for the ETM memory read command.

=== omemdump
omemdump addr length

This command requests a read of a target memory address range via the TM3
memory read command, and displays the returned bytes as a hex dump.
Both arguments are always interpreted as hexadecimal, and the length may not
exceed 0x7C (124 decimal) - the limit for the TM3 memory read command.

=== mkdir
mkdir ffs-pathname

This command creates a directory object in the target device FFS at the
specified pathname.  If the named directory already exists, it is not an error,
but it is an error if a non-directory object exists at that pathname.

=== mk-std-dirs
This command creates the standard set of FFS directories, or rather the set
deemed as standard for our FreeCalypso firmware projects based on or inspired
by TI's TCS211.  This set currently consists of:

/gsm
/gsm/com
/gsm/rf
/gsm/rf/rx
/gsm/rf/tx
/pcm
/sys
/mmi
/var
/var/dbg
/aud
/etc

Each directory is created as if by our mkdir command, i.e., it is not an error
if that directory already exists, but it is an error if a non-directory object
exists at that pathname.

=== pirelli-get-imei
This command works only if the GSM device with whose firmware fc-fsio is
communicating is a Pirelli DP-L10, and only if that fw is either one of
Foxconn/Pirelli's official versions or FC Magnetite - it will not work against
FC Citrine firmware.  When run against a Pirelli phone with a compatible fw
version, this command will retrieve and display Pirelli's factory IMEI.

=== pirelli-magnetite-init
This command may only be run against FC Magnetite firmware running on the
Pirelli DP-L10 target, and never against any other target/firmware combination.
See FreeCalypso Magnetite firmware documentation for the details.

=== preformat
This command requests the GSM device firmware to blow away its flash file system
and prepare for a new format.  DO NOT issue this command unless you really wish
to blow away your FFS, and if you really do wish to perform this drastic
operation, the firmware should be fully quiescent with GSM off as in AT+CFUN=0.

=== readlink
readlink ffs-pathname

This command provides raw access to the ffs_readlink() API call and displays
the returned response as a hex dump.  Use ls -l (or ll) as a more user-friendly
interface.

=== rm
rm [-f] ffs-pathname

This command deletes the named object in the device FFS, which must be a regular
file, an empty directory or a symlink.

Note that in classic UNIX there are two different "delete file system object"
elementary operations: unlink for regular files or symlinks and rmdir for empty
directories, but TI's FFS implementation provides a single ffs_remove() API call
instead for deleting all 3 object types; our rm command is the interface to
this ffs_remove() API call.

If the -f option is given, the condition where the object to be deleted does not
exist is treated as not-an-error; all other errors are still reported.

=== rm-subtree
rm-subtree [-f] ffs-pathname

This command deletes an entire subtree of directories and files in the target
device FFS, starting with the specified pathname which must be a directory, not
a regular file or symlink.  It is an approximate equivalent of rm -r in UNIX.

If the -f option is given, the condition where the top directory to be deleted
does not exist is treated as not-an-error; all other errors are still reported.

=== set-imeisv
set-imeisv fc  XXXXXXXX-YYYYYY-ZZ	# write /etc/IMEISV
set-imeisv pcm XXXXXXXX-YYYYYY-ZZ	# write /pcm/IMEI

This command sets the IMEISV to be used for GSM operation and stores it either
in /etc/IMEISV (one format) or /pcm/IMEI (a different format) depending on the
"fc" or "pcm" keyword argument.  Please refer to the doc/IMEI article in the
FreeCalypso host tools source package for the explanation as to when you should
use which.

For the IMEISV argument 16 decimal digits must always be given; punctuation is
optional and may be placed anywhere.

=== set-pcm-string
set-pcm-string CGxx "ASCII string content"

This command writes the /pcm/CGxx files whose content is displayed by AT+CGxx
commands; CGxx must be one of CGMI, CGMM, CGMR or CGSN.  The length of these
ASCII string files is limited to 20 characters by TI's firmware design.

=== set-rfcap
This command writes the /gsm/com/rfcap file to communicate the hardware RF band
configuration to the firmware as follows:

set-rfcap dual-eu	# 900/1800 MHz single-region dual-band
set-rfcap dual-us	# 850/1900 MHz single-region dual-band
set-rfcap tri900	# 900/1800/1900 MHz triband
set-rfcap tri850	# 850/1800/1900 MHz triband
set-rfcap quad		# All 4 bands

=== stat
stat ffs-pathname

This command provides raw access to the ffs_xlstat() API call; the information
returned by this call and displayed by this command is similar to what you would
get with the lstat system call in classic UNIX.

Use ls -l (or ll) as a more user-friendly interface.

=== symlink
symlink link-target-pathname link-object-pathname

This command creates a symlink object in the FFS; the 2nd argument is the
pathname at which the object is to be created and the 1st argument is the link
target string to be written into this symlink object - the order of the
arguments matches the classic UNIX symlink system call.

Note that although TI's FFS implementation supports symlinks, it appears that
no production configuration has ever used them.

=== upload-file
upload-file host-file target-file

This command uploads a single regular file from your Unix host file system into
the target device FFS.

=== upload-fs
upload-fs host-dir

This command uploads an entire file system tree from the given host location
into the target device FFS at the root level.

=== upload-rf-table
upload-rf-table host-table-file [band]

This command uploads an RF calibration or configuration table into the target
device FFS.  The table is read from a source file in FreeCalypso ASCII format,
the type (meaning) of the table is indicated in its header, and the FFS
pathname into which the bits of this table should be written after conversion
to binary is known from this table type.

Some RF tables are global while others are instantiated for each supported
frequency band.  If the table being uploaded is of the per-band variety, the
band argument must be given (the name of the band as used in the FFS pathnames
of that band's calibration/config files); if the table is of the global variety,
no band argument is allowed.

=== upload-subtree
upload-subtree host-dir target-dir

This command uploads a directory subtree from your Unix host file system into
the given non-root directory in the target device FFS.

=== write-battery-table
=== write-battery-table-v1
=== write-battery-table-v2
write-battery-table-v1 src-file
write-battery-table-v2 src-file

This command (which now exists in two versions) provides the mechanism for
uploading FreeCalypso-invented battery discharge threshold tables to target
devices.  The argument is the name of the table source file on the host; this
source file is read and compiled into the corresponding binary representation,
and the latter is then written into /etc/batterytab or /etc/batterytab2 on the
target.

write-battery-table-v1 writes /etc/batterytab as needed for the original
Magnetite and Selenite version of FCHG, write-battery-table-v2 writes
/etc/batterytab2 (a different binary format) as needed for the new Tourmaline
version of FCHG.  Both accept the same table source files; conversion to v1
binary format made by write-battery-table-v1 discards the battery bars icon
thresholds that were added in v2.

=== write-bsim-config
write-bsim-config init-percent start-enable

This command writes a /etc/batterysim file into target device FFS, enabling and
configuring the battery simulation (BSIM) mode in FC Tourmaline firmware.
init-percent and start-enable are BSIM configuration parameters.

To disable BSIM, do 'rm /etc/batterysim'.

=== write-charging-config
write-charging-config src-file

This command provides the mechanism for uploading FreeCalypso-invented battery
charging configuration files (configuration for the FreeCalypso battery charging
driver FCHG) to target devices.  The argument is the name of the config source
file on the host; this source file is read and compiled into the corresponding
binary representation, and the latter is then written into /etc/charging on the
target.