;===============================================================================
;                               SPLat Controls.                                ;
;                          Product Development Group                           ;
;                            Melbourne,  AUSTRALIA                             ;
;                            http://www.splatco.com                            ;
;===============================================================================
;PURPOSE:
; A collection of file system routines for the SX10508 logger board.  This file
; exposes all file features that are available on the SX10508.
;
; SPLat would like to give credit to ChaN for the open source FAT filesystem
; that is used in the SX10508 logger board, see:
;     http://elm-chan.org/fsw/ff/00index_e.html
;
;===============================================================================
;===============================================================================
;           Copyright (c) 2013 SPLat Controls. All rights reserved.            ;
;                                                                              ;
;        THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF SPLat Controls.        ;
;               The copyright notice above does not evidence any               ;
;              actual or intended publication of such source code.             ;
;===============================================================================

;===============================================================================
;
;<INITSEG>
;
;===============================================================================


;===============================================================================
;
;<CONSTSEG>
;
;===============================================================================
;-- FileSystem SPx Address --
FSkSPxAddr                 EQU   '1000

;-- SPxChIn --
FSkChIn_FirstFile          EQU   0
FSkChIn_NextFile           EQU   1
FSkChIn_GetVolumeLabel     EQU   2

;-- SPxChOut --
FSkChOut_SetDir            EQU   0
FSkChOut_OpenFileNew       EQU   1
FSkChOut_OpenFileAppend    EQU   2
FSkChOut_WriteData         EQU   3
FSkChOut_DeleteFileOrDir   EQU   4
FSkChOut_OpenChannel       EQU   5

;-- SPxCmd0 --
FSkCmd0_Mount              EQU   0
FSkCmd0_CloseFile          EQU   1
FSkCmd0_FlushData          EQU   2
FSkCmd0_Format             EQU   3
FSkCmd0_CloseChannel       EQU   4

;-- SPxCmd1 --
FSkCmd1_WriteByte          EQU   0

;-- SPxPoll1 --
FSkPoll1_LastError         EQU   0

;-- SPxPoll4 --
FSkPoll4_FreeSpace         EQU   0
FSkPoll4_UsedSpace         EQU   1
FSkPoll4_CardSize          EQU   2
FSkPoll4_ChnlByteCount     EQU   3

;-- Result codes --
FR_OK                      EQU   0  ;Succeeded
FR_DISK_ERR                EQU   1  ;A hard error occurred in the low level disk I/O layer
FR_INT_ERR                 EQU   2  ;Assertion failed
FR_NOT_READY               EQU   3  ;The physical drive cannot work
FR_NO_FILE                 EQU   4  ;Could not find the file
FR_NO_PATH                 EQU   5  ;Could not find the path
FR_INVALID_NAME            EQU   6  ;The path name format is invalid
FR_DENIED                  EQU   7  ;Access denied due to prohibited access or directory full
FR_EXIST                   EQU   8  ;Access denied due to prohibited access
FR_INVALID_OBJECT          EQU   9  ;The file/directory object is invalid
FR_WRITE_PROTECTED         EQU   10 ;The physical drive is write protected
FR_INVALID_DRIVE           EQU   11 ;The logical drive number is invalid
FR_NOT_ENABLED             EQU   12 ;The volume has no work area
FR_NO_FILESYSTEM           EQU   13 ;There is no valid FAT volume
FR_MKFS_ABORTED            EQU   14 ;The f_mkfs() aborted due to any parameter error
FR_TIMEOUT                 EQU   15 ;Could not get a grant to access the volume within defined period
FR_LOCKED                  EQU   16 ;The operation is rejected according to the file sharing policy
FR_NOT_ENOUGH_CORE         EQU   17 ;LFN working buffer could not be allocated
FR_TOO_MANY_OPEN_FILES     EQU   18 ;Number of open files > _FS_SHARE
FR_INVALID_PARAMETER       EQU   19 ;Given parameter is invalid


;===============================================================================
;
;<MEQUSEG>
;RAM storage
;
;===============================================================================


;===============================================================================
;
;<IOSEG>
;I/O Assignments
;
;===============================================================================


;===============================================================================
;
;AUTOMATIC RAM
;
;===============================================================================
;=== public ===
;<DEF_SEM>

;<DEF_BYTE>

;<DEF_WORD>

;<DEF_FLOAT>

;<DEF_BLOCK>


;===============================================================================
;
;<CODESEG>
;
;===============================================================================

;===============================================================================
;DESCRIPTION:
; This routine configures the file system to start fetching the names of files
; in the current directory.  Use FSsubSetDir to set the directory before calling
; this routine.  This routine returns the name of the first file in the current
; directory.  Use FSsubGetNextFile to fetch each subsequent name of the
; remaining files in the directory.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  UV: When V != 0, U holds the name of the first file or directory in 8.3
;  format.  Directories have a "/" appended to the name.
; <-  X: error result which may be one of:
;  FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME,
;  FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT,
;  FR_NOT_ENOUGH_CORE 
;===============================================================================
FSsubGetFirstFile:
   SPxChIn        FSkChIn_FirstFile,FSkSPxAddr
   LoadX          FR_OK                               ;assume success
   PushV                                              ;get the length
   RetIfNZ                                            ;return if we got a name
   PushU          0                                   ;otherwise, return the error
   Return


;===============================================================================
;DESCRIPTION:
; This routine gets the name of the next file within the current directory.
; Before calling this function first call FSsubGetFirstFile once.  This routine
; may then be called repeatedly to get the names of all files in the current
; directory.  FSsubSetDir may be called to switch to a different directory.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  UV: When V != 0, U holds the name of the first file or directory in 8.3
;  format.  Directories have a "/" appended to the name.
; <-  X: error result which may be one of:
;  FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME,
;  FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT,
;  FR_NOT_ENOUGH_CORE 
;===============================================================================
FSsubGetNextFile:
   SPxChIn        FSkChIn_NextFile,FSkSPxAddr
   LoadX          FR_OK                               ;assume success
   PushV                                              ;get the length
   RetIfNZ                                            ;return if we got a name
   PushU          0                                   ;otherwise, return the error
   Return


;===============================================================================
;DESCRIPTION:
; This routine gets SD card the volume label if it exists.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  UV: U holds the volume name (up to 12 characters long), V holds the name
;  length.
; <-  X: error result which may be one of:
;  FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_DRIVE,
;  FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT 
;===============================================================================
FSsubGetVolumeLabel:
   SPxChIn        FSkChIn_GetVolumeLabel,FSkSPxAddr
   LoadX          FR_OK                               ;assume success
   PushV                                              ;get the length
   RetIfNZ                                            ;return if we got a name
   PushU          0                                   ;otherwise, return the error
   Return


;===============================================================================
;DESCRIPTION:
; Sets the new working directory, relative to the current directory.  Some
; useful strings include:
;  "\" go straight to the root directory
;  ".." go to the parent of the current directory
; To move down several directories, simply call this routine multiple times,
; each time with the name of the next subdirectory.
;PARAMETERS:
;  -> UV: U holds the name of the new directory to switch to, V holds the length
;  of the name.
;RETURNS:
; <-  X: the success of the move, may be one of: FR_OK, FR_DISK_ERR, 
; FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_DRIVE, 
; FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE 
;===============================================================================
FSsubSetDir:
   SPxChOut       FSkChOut_SetDir,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; This routine creates a new file using the string in UV as the name.  If a file
; exists with the same name, it will be erased.
;PARAMETERS:
;  -> UV: U holds the name of the new file, V holds the length of the file name.
;  Keep within the 8.3 naming limits.
;RETURNS:
; <-  X: the success of the create, ref FR_XXX
;===============================================================================
FSsubOpenFileNew:
   SPxChOut       FSkChOut_OpenFileNew,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; This routine opens an existing file ready to append data.  The file will be
; created if it doesn't exist.  Calling FSsubWriteData after this function will
; immediately see data being appended to the file.
;PARAMETERS:
;  -> UV: U holds the name of the existing file, V holds the length of the file
;  name.  Keep within the 8.3 naming limits.
;RETURNS:
; <-  X: the success of the create, ref FR_XXX
;===============================================================================
FSsubOpenFileAppend:
   SPxChOut       FSkChOut_OpenFileAppend,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; This routine writes the byte in the X register to the SD card.  The file must have been
; opened prior to calling this function.  Call FSsubFlushData periodically to
; minimise the risk of data loss.  Call FSsubCloseFile prior to ejecting the
; card or creating a new file.
;PARAMETERS:
;  -> X: the byte to write.
;RETURNS:
; <-  X: the success of the write, may be one of  FR_OK, FR_DISK_ERR,
;  FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT 
;===============================================================================
FSsubWriteX:
   PopU           0                                   ;put the byte in U
   SPxCmd1        FSkCmd1_WriteByte,FSkSPxAddr
   PushU          0                                   ;result back in X
   Return


;===============================================================================
;DESCRIPTION:
; This routine writes data held in UV to the SD card.  The file must have been
; opened prior to calling this function.  Call FSsubFlushData periodically to
; minimise the risk of data loss.  Call FSsubCloseFile prior to ejecting the
; card or creating a new file.
;PARAMETERS:
;  -> UV: U holds the data to write to the card, V is the number of bytes to
;  write.
;RETURNS:
; <-  V: the number of bytes actually written
; <-  X: the success of the write, may be one of  FR_OK, FR_DISK_ERR,
;  FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT 
;===============================================================================
FSsubWriteData:
   SPxChOut       FSkChOut_WriteData,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; For a hands off approach and for handling high speed data, this routine opens
; a direct channel from the specified serial port to the SD card.  Data received
; on the serial port will be routed direct to the currently open file.
;PARAMETERS:
;  -> X: port to use
;  -> W: the baud rate
;RETURNS:
; <-  Nil
;===============================================================================
FSsubOpenChannel:
   PopU           0                                   ;com port in U[0]
   WtoU           1                                   ;baud rate as float in U[1-4]
   SetV           5                                   ;byte + float = 5 bytes
   SPxChOut       FSkChOut_OpenChannel,FSkSPxAddr
   Return


;===============================================================================
;DESCRIPTION:
; Closes a previously opened channel.  Must be done before most other card
; operations.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  Nil
;===============================================================================
FSsubCloseChannel:
   SPxCmd0        FSkCmd0_CloseChannel,FSkSPxAddr
   Return


;===============================================================================
;DESCRIPTION:
; This routine can be called to either empty the currently open file, or to
; deleted a specific file or a specific subdirectory.  To truncate the currently
; open file, simply set V to 0.  Otherwise to delete a specific file or
; subdirectory, load UV with the name.
;PARAMETERS:
;  -> UV: U holds the name of the new file, V holds the length of the file name.
;  Keep within the 8.3 naming limits.  V may be 0 to truncate the currently open
; file.
;RETURNS:
; <-  X: the success of the deletion.
;===============================================================================
FSsubDeleteFileOrDir:
   SPxChOut       FSkChOut_DeleteFileOrDir,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; Must be called to initialise the file system whenever a new card is inserted.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  X: the result of the mount, may be one of  FR_OK, FR_INVALID_DRIVE.
;===============================================================================
FSsubMount:
;<=IF DEBUG> OBLCD_Text "m"
;<=IF DEBUG> iiPrintText COM0,"FSMount...",13,10
;<=IF DEBUG> Pause 10
   SPxCmd0        FSkCmd0_Mount,FSkSPxAddr
   PushU          0
;<=IF DEBUG> iiPrintText COM0,"...done",13,10
;<=IF DEBUG> OBLCD_Text "n"
;<=IF DEBUG> Pause 10
   Return


;===============================================================================
;DESCRIPTION:
; This function closes the file, thereby ensuring any cached data is written to
; the card.  This must be called prior to ejecting the card, otherwise the
; filesystem may be corrupted.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  X: result of the operation.  May be one of   FR_OK, FR_DISK_ERR,
;  FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT  
;===============================================================================
FSsubCloseFile:
   SPxCmd0        FSkCmd0_CloseFile,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; Call this routine periodically to ensure the last block of data written to the
; file is actually committed to the SD card.  This ensures it is not lost if
; power fails.  To improve performace and longevity of the SD card be aware
; FSsubWriteData may not write data immediately and instead will leave it in a
; cache.  This routine ensures any cached data is actually written.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  X: result of the operation.  May be one of  FR_OK, FR_DISK_ERR,
; FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT 
;===============================================================================
FSsubFlushData:
   SPxCmd0        FSkCmd0_FlushData,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; This routine will format the card with the FAT32 filesystem.  FAT32 can be
; used on cards up to 2TB (with the standard 512 byte sector size).  Files on
; FAT32 are limited 4GB each.
; Be aware calling this routine will erase all data on the card.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  X: result of the operation.  May be one of   FR_OK, FR_DISK_ERR,
;  FR_NOT_READY, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED,
;  FR_MKFS_ABORTED, FR_INVALID_PARAMETER 
;===============================================================================
FSsubFormat:
   SPxCmd0        FSkCmd0_Format,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; This routine may be called after any file system operation to get the last
; error result.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  X: The last error code, refer to FR_XXX
;===============================================================================
FSsubGetLastError:
   SPxPoll1       FSkPoll1_LastError,FSkSPxAddr
   PushU          0
   Return


;===============================================================================
;DESCRIPTION:
; Obtains the remaining free space on the card in kB.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  W: Free space in kB.  For example, W = 1400000 means there is 1.4GB free.
; <-  X: Error code, could be one of  FR_OK, FR_DISK_ERR, FR_INT_ERR,
;  FR_NOT_READY, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT 
;===============================================================================
FSsubFreeSpace:
   SPxPoll4       FSkPoll4_FreeSpace,FSkSPxAddr
   UtoW           0
   Goto           FSsubGetLastError


;===============================================================================
;DESCRIPTION:
; Obtains the amount of space that has been used on the card in kB.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  W: Used space in kB.  For example, W = 6600000 means 6.6GB has been used.
; <-  X: Error code, could be one of  FR_OK, FR_DISK_ERR, FR_INT_ERR,
;  FR_NOT_READY, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT 
;===============================================================================
FSsubUsedSpace:
   SPxPoll4       FSkPoll4_UsedSpace,FSkSPxAddr
   UtoW           0
   Goto           FSsubGetLastError


;===============================================================================
;DESCRIPTION:
; Obtains the storage size of the card in kB.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  W: Storage size in kB.  For example, W = 8000000 means the card can hold
;  8GB.
; <-  X: Error code, could be one of  FR_OK, FR_DISK_ERR, FR_INT_ERR,
;  FR_NOT_READY, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT 
;===============================================================================
FSsubCardSize:
   SPxPoll4       FSkPoll4_CardSize,FSkSPxAddr
   UtoW           0
   Goto           FSsubGetLastError


;===============================================================================
;DESCRIPTION:
; This function returns the nof of bytes that have been written via the channel.
;PARAMETERS:
;  -> Nil
;RETURNS:
; <-  W: nof bytes written by the channel
;===============================================================================
FSsubChannelByteCount:
   SPxPoll4       FSkPoll4_ChnlByteCount,FSkSPxAddr
   UtoW           0
   Goto           FSsubGetLastError