AP_Filesystem: added README on VFS interface

Author: tridge

libraries/AP_Filesystem/README.md

@@ -0,0 +1,98 @@
+# AP_Filesystem: The ArduPilot virtual filesystem layer
+
+AP_Filesystem is a filesystem abstraction for ArduPilot that gives
+ArduPilot access to both local filesystems on the flight controller
+and a set of virtual filesystem abstractions.
+
+This document is primarily intended to document the VFS interfaces
+available to ground station authors via the MAVLink FTP transport.
+
+## MAVLink FTP
+
+ArduPilot implements the FILE_TRANSFER_PROTOCOL MAVLink message to
+allow for remote file operations. This protocol allows a GCS to
+transfer files to and from a flight controller. It also allows the GCS
+to access some special purpose VFS interfaces for efficient access to
+flight controller data using a file API.
+
+The VFS interfaces that don't represent local filesystem objects on
+the flight controller are prefixed with an '@' symbol. Currently there
+are two interfaces, the @PARAM interface and the @SYS interface.
+
+## The @PARAM VFS
+
+The @PARAM VFS allows a GCS to very efficiently download full or
+partial parameter list from the flight controller. Currently the
+@PARAM filesystem offers only a single file, called @PARAM/param.pck,
+which is a packed representation of the full parameter
+list. Downloading the full parameter list via this interface is a lot
+faster than using the traditional mavlink parameter messages.
+
+The file format of the @PARAM/param.pck file is as follows
+
+### File header
+
+There is a 6 byte header, consisting of 3 uint16_t values
+```
+  uint16_t magic # 0x671b
+  uint16_t num_params
+  uint16_t total_params
+```
+The magic value is used to give the version of the packing format. It
+should have a value of 0x671b. The num_params is how many parameters
+will be sent (may be less than total if client requests a subset, see
+query strings below). The total_params is the total number of
+parameters the flight controller has.
+
+The header is little-endian.
+
+### Parameter Block
+
+After the header comes a series of variable length parameter blocks, one per
+parameter. The format is:
+
+```
+    uint8_t type:4;         // AP_Param type NONE=0, INT8=1, INT16=2, INT32=3, FLOAT=4
+    uint8_t flags:4;        // for future use
+    uint8_t common_len:4;   // number of name bytes in common with previous entry, 0..15
+    uint8_t name_len:4;     // non-common length of param name -1 (0..15)
+    uint8_t name[name_len]; // name
+    uint8_t data[];         // value, length given by variable type
+```
+
+There may be any number of leading zero pad bytes before the start of
+the parameter block. The pad bytes are added to ensure that a
+parameter value does not cross a MAVLink FTP block boundary. This
+padding prevents a re-fetch of a missing block from potentially
+leading to a corrupt value.
+
+The packing format avoids sending common leading characters of
+parameter names from the previous parameter. It does this by sending a
+common_len field which says how many characters should be copied from
+the previous parameter. This is always zero in the first block in the
+file.
+
+The name_len field is the number of non-common characters, minus one.
+
+### Query Strings
+
+The file name @PARAM/param.pck can optionally be extended with query
+string elements to change the result. For example:
+
+ - @PARAM/param.pck?start=50&count=10
+
+that means to download 10 parameters starting with parameter number
+50.
+
+### Parameter Client Examples
+
+The script Tools/scripts/param_unpack.py can be used to unpack a
+param.pck file. Additionally the MAVProxy mavproxy_param.py module
+implements parameter download via ftp.
+
+## The @SYS VFS
+
+The @SYS VFS gives access to flight controller internals. For now the
+only file that is accessible is @SYS/threads.txt which gives
+information on the remaining stack space for all threads. This file is
+only accessible for ChibiOS builds.