FAT | XFS

vclean()

PROTOTYPE

#include <posix.h>

int vclean(const char *path);

DESCRIPTION

vclean() requests garbage collection from an underlying flash memory manager. It is applicable whenever a Flash Translation Layer (FTL) is being used for a volume’s backing store. This could be TargetFTL or any smart media layer that contains an FTL (eMMC, SD Card, etc.).

FTL garbage collection involves copying used pages off selected flash blocks and erasing flash blocks; often multiple pages and sometimes multiple blocks. It can be time consuming. vclean() is a tool for controlling when this necessary overhead is performed.

path specifies the volume to clean. It can be the volume name, the path to any file on the volume, or NULL to select the volume holding the CWD. Paths starting with ‘/’ are absolute. Otherwise they are relative to the CWD.

By default, garbage collection is done “just in time” when the FTL free page count reaches a low threshold. vclean() allows it to be scheduled by the application. vclean() can be called before a streaming write, to optimize its throughput, and periodically from a low priority task to implement background garbage collection.

To avoid ‘hogging’ access to the volume, each vclean() call erases at most one flash block before returning. The return code indicates if there is more garbage collection left to do. See Background Garbage Collection for more information.

vclean() returns 0 if the volume is clean, 1 if there is more garbage collection to do, or -1 if an error occurs.

ERROR CODES

ENAMETOOLONG	A name in path exceeds the effective maximum file name length.
ENOENT	path is the empty string or includes a name that was not found.
ENOTDIR	One of the non-leaf path components is not a directory.
EROFS	The volume is read-only.

EXAMPLE

static void cleaner(void)
{
  for (;;)
  {
    while (vclean("flash0") > 0) ;
    taskSleep(5 * OsTicksPerSec);
  }
}