[Freemint-list] API proposal for online FATFS manipulation

[Adam Klobukowski]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.atariforge.org/pipermail/freemint-list/attachments/20170201/2982f437/attachment.html