
             DISKFREE v1.11
             --------------
        for VSOS 3.66 or higher
       2023-02-14  VLSI Solution




DiskFree displays (or, when called from C, returns) the amount of free
space on a FAT device, or on all available devices.

To use, either compile the Solution, or simply copy DiskFree.dl3
to your VS1005 Evaluation Board's SYS/ folder.




The VSOS Shell command line options are:

Usage: DiskFree [-p x|-H|+H|-v|-h] [D:]
	There may be multiple drive parameters.
	Drive parameters must be after -p|-H options.
-p x	Store last result in KiB to X-memory 32-bit pointer pointed to by x
	(Usable for calling with RunLibraryFunction(); makes operation silent)
-f x	Stop looking after finding x MiB free memory
	Option muse be before drive name
-H|+H	Display sizes in human-readable form on/off
-v|+v	More/less verbose (twice makes even more/less verbose)
D:	Print results for drive D (:: means all drives)
-h	Show this help

Cluster printout:
#	All clusters used
+	Some clusters used
.	All clusters free

Without a parameter, DiskFree displays the status of the current directory
drive.

If the doubly verbose option is not on and -f option has been set, the free
cluster list is traversed backwards. In many cases, this makes finding the
required amount of free space significantly faster.

Example 1: Show free space of SD card:
S:>DiskFree d:
D:   28207040 KiB free, SD/SD Card

Example 2: Show size, used, and free space of SD card:
S:>DiskFree -v d:
Drv  Used/KiB   Free/KiB  Total/KiB  Use%  Name

Example 3: Show size, used, and free space of SD card in an easier,
human-readable form:
S:>diskfree -v -H d:
Drv Used  Free Total  Use%  Name
D:  2.3G   26G   29G    8%  SD/SD Card

Example 4: Show size, used, free space and cluster allocation map of SD card:
D:    2442304   28207040   30649344    8%  SD/SD Card
S:>DiskFree -v -v d:
Cluster  131072 KiB per symbol: # all used, + partially used, . all free
0x0000000 ################################################################
0x0010000 ##########+.....................................................
0x0020000 ................................................................
0x0030000 ................................................................
0x0040000 ................................................................
0x0050000 ................................................................
0x0060000 ................................................................
0x0070000 ................................................................
0x0080000 ................................................................
0x0090000 ................................................................
0x00a0000 ................................................................
0x00b0000 ................................................................
0x00c0000 ................................................................
0x00d0000 ................................................................
0x00e0000 .......................................
Drv  Used/KiB   Free/KiB  Total/KiB  Use%  Name
D:    2442304   28207040   30649344    8%  SD/SD Card

Example 4: Look if there is at least 128 MiB of free space on SD card:
S:>DiskFree -v -f 128 d:
Drv  Used/KiB   Free/KiB  Total/KiB  Use%  Name
D:         -1     131072   30649344   -1%  SD/SD Card
Answer: because Free/KiB = 131072 KiB = 128 MiB, there was at least 128 MiB
of free space. If enough space is not available, the amound (that is less
than 131072 KiB) is displayed (or returned to the caller).



From C code, the following calling convention may be used:

#include <apploader.h>

#define DRIVE 'S'
{
  char par[21];
  u_int32 spaceInKiB = 0;
#if 1
 /* Checks out total amount of free space on the device. */
 sprintf(par, "-p 0x%04x %c:", &spaceInKiB, DRIVE);
#else
 /*
    Checks out whether there is at least 128 MiB free space on the device.
    Returns 128*1024 = 131072 if there is, otherwise the amount of space
    found.
 */
 sprintf(par, "-p 0x%04x -m 128 %c:", &spaceInKiB, DRIVE);
#endif
  if (RunProgram("DiskFree", par) == S_OK) {
    printf("Drive %c: has at least %ld KiB free space\n", DRIVE, spaceInKiB);
  } else {
    printf("DiskFree failed for drive %c:\n", DRIVE);
  }
}




License:
This code may be used freely in any product containing one or more ICs
by VLSI Solution.




Disclaimer:
No guarantee is given for the usability of this code.




Version History:
2023-02-14 HH v1.11 - Changed formatting to allow for 1 TB SD cards.
2022-01-21 HH v1.10 - Added new -f option and backwards search if option is
                      selected without double verbose.
2021-03-11 HH v1.09 - Now survives if removable disk is removed / replaced,
                      but requires VSOS 3.63 or higher to do so.
2020-07-22 HH v1.08 - Human-readable "-H" option added. Removed -m option.
2018-01-31 HH v1.07 - New extra verbose "-v -v" option shows cluster map.
2018-01-24 HH v1.06 - Corrected results with -m option.
2017-12-05 HH v1.05 - Ported to VS1005h.
2017-04-24 HH v1.04 - totalSize corrected, compatible with VSOS 3.42 and newer.
                      Will give slightly incorrect info with older VSOS.
2017-03-22 HH v1.03 - Corrected documentation for C code call.
2015-10-01 HH v1.02 - Added -v option for additional information.
2015-09-22 HH v1.01 - Speed increased a lot for FAT32 (3-8x faster).
2015-09-22 HH v1.00 - First release.
