[Freemint-list] API proposal for online FATFS manipulation

[Mark Duckworth]

Nobody else really said anything but I thought it sounds nice.  A little
scary for your data, but nice :)

Thanks,
Mark


On 02/01/2017 02:52 AM, Adam Klobukowski wrote:
> Hello
> 
> Recent release of Diamond Back/Edge inspired me to design a system API
> for online FATFS manipulation (and finally pushed me into getting back
> into FreeMiNT development).
> 
> The purpose of this API is to allow online (filesystem remains fully
> accessible all the time) moving data (optimization/defragmentation)
> between clusters on FATFS.
> 
> I already scouted FATFS code, and thanks to how it is structured, it
> would require only very limited changes to existing code, mostly
> concerning locking. Also, thanks for FATFS code, we do not need to
> concern ourselves with what kind of FAT (12,16,32) it is.
> 
> I'm not sure if it is possible, but I'd like it to be a single syscall.
> 
> All calls in this API require root level access privileges, and return
> error if not so (not mentioned in calls description). All calls assume
> that the filesystem is healthy, do this on unhealthy one and you're on
> your own.
> 
> I assume you know the basic inner machinery of FAT filesystem (clusters,
> fat, etc)
> 
> Calls: (FFM = FATFS Manipulation)
> 
> 1. FFM_WWLOCK (deviceId)
> 
> Gives process a weak write lock. This lock is required for the process
> for all other operations to happen.
> 
> The lock weak, and that means that any write to the device (on
> filesystem level) by another source then this API releases this lock,
> and other functions of this lock will fail. If they do, process has to
> assume that all knowledge about the filesystem (like fat) is invalid.
> Only cluster locks remain valid.
> 
> Possible errors:
> 
> E_DLOCKED - device is already locked via Dlock() by another process.
> Current process can have Dlock() on the drive, and we assume it knows
> what it is doing. The use case for that is following:
> 
> process Dlock's the device
> process does health check (and repair if necessary) on the device filesystem
> process FFM_WLOCK's the device
> process drops Dlock on the device
> optimization begins
> profit! ;)
> 
> E_NOT_FATFS
> obviously ;)
> 
> This way, only the part that really needs to lock device, does it.
> 
> 2. FFM_WWUNLOCK (deviceId)
> 
> Obvious. All cluster locks are dropped.
> 
> Possible errors:
> 
> E_NOT_FFM_LOCKED
> 
> 3. FFM_CLOCK (cluster)
> 
> Locks the cluster for writing by FATFS. This ensures, that the FATFS
> will not write data to the clusters we want for ourselves for the time
> of our work.
> 
> This lock does not prohibit functions of this API to write to the
> cluster. If they do, lock is dropped.
> 
> Possible errors:
> E_NOT_FFM_LOCKED
> 
> E_NOT_FREE_CLUSTER
> We can lock only free clusters.
> 
> E_WRONG_CLUSTER
> cluster does not exits (to big cluster number)
> 
> 4. FFM_CLUSTER_UNLOCK (cluster)
> 
> Drops the cluster lock
> 
> Possible errors:
> 
> E_NOT_FFM_LOCKED
> 
> E_NOT_LOCKED
> This cluster is not locked
> 
> E_WRONG_CLUSTER
> cluster does not exits (to big cluster number)
> 
> 5. FFM_MOVE_CLUSTER (source, destination, buffer, lock)
> 
> Moves the data from one cluster to another, and fixes cluster chains, so
> concerning file is correct.
> 
> source - source cluster, must be data cluster
> destination - destination cluster, must be free cluster. We do not allow
> swapping two data clusters, because it may lead to data loss in case of
> power (or other) failure. The drawback of this, is we can't do anything
> on filesystems with no free clusters.
> buffer - pointer to a allocated buffer that is cluster sized. This
> buffer will be used for reading/writing data, and the reason process has
> to provide it is so kernel does not have to allocate it over and over
> again, leading to the memory fragmentation. Process can reuse this
> buffer between calls, obviously.
> lock - if 1, source cluster will be locked (equivalent of calling
> FFM_CLOCK), after the call finishes.
> 
> Possible errors:
> 
> Plenty. E_NOT_FFM_LOCKED, E_NOT_FREE_CLUSTER, E_NOT_DATA_CLUSTER,
> E_WRONG_SOURCE_CLUSTER, E_WRONG_DESTINATION_CLUSTER,  E_WRITE_ERROR,
> E_READ_ERROR,  E_FAT_WRITE_ERROR, E_FAT_READ_ERROR and all I did not
> think about at this time.
> 
> This is the whole API, 5 calls.
> 
> If the process ends without calling FFM_WWUNLOCK, it is called for him.
> 
> -- 
> Semper Fidelis
> 
> Adam Klobukowski
> adamklobukowski at gmail.com <mailto:adamklobukowski at gmail.com>
> 
> 
> _______________________________________________
> Freemint-list mailing list
> Freemint-list at mail.atariforge.org
> http://mail.atariforge.org/mailman/listinfo/freemint-list
>