Added conversion to/from little-endian on disk

Required to support big-endian processors, with the most notable being
the PowerPC architecture.

On little-endian architectures, these conversions can be optimized out
and have no code impact.

Initial patch provided by gmouchard

.travis.yml

@@ -9,6 +9,39 @@ script:
         -include stdio.h -Werror' make all size
 
     # run tests
-    - CFLAGS="-DLFS_READ_SIZE=16  -DLFS_PROG_SIZE=16"  make test
-    - CFLAGS="-DLFS_READ_SIZE=1   -DLFS_PROG_SIZE=1"   make test
-    - CFLAGS="-DLFS_READ_SIZE=512 -DLFS_PROG_SIZE=512" make test
+    - make test QUIET=1
+
+    # run tests with a few different configurations
+    - CFLAGS="-DLFS_READ_SIZE=1   -DLFS_PROG_SIZE=1"       make test QUIET=1
+    - CFLAGS="-DLFS_READ_SIZE=512 -DLFS_PROG_SIZE=512"     make test QUIET=1
+    - CFLAGS="-DLFS_BLOCK_COUNT=1023 -DLFS_LOOKAHEAD=2048" make test QUIET=1
+
+    # self-host with littlefs-fuse for fuzz test
+    - make -C littlefs-fuse
+
+    - littlefs-fuse/lfs --format /dev/loop0
+    - littlefs-fuse/lfs /dev/loop0 mount
+
+    - ls mount
+    - mkdir mount/littlefs
+    - cp -r $(git ls-tree --name-only HEAD) mount/littlefs
+    - cd mount/littlefs
+    - ls
+    - make -B test_dirs test_files QUIET=1
+
+before_install:
+    - fusermount -V
+    - gcc --version
+
+install:
+    - sudo apt-get install libfuse-dev
+    - git clone --depth 1 https://github.com/geky/littlefs-fuse
+
+before_script:
+    - rm -rf littlefs-fuse/littlefs/*
+    - cp -r $(git ls-tree --name-only HEAD) littlefs-fuse/littlefs
+
+    - mkdir mount
+    - sudo chmod a+rw /dev/loop0
+    - dd if=/dev/zero bs=512 count=2048 of=disk
+    - losetup /dev/loop0 disk

DESIGN.md

@@ -1,6 +1,6 @@
 ## The design of the little filesystem
 
-The littlefs is a little fail-safe filesystem designed for embedded systems.
+A little fail-safe filesystem designed for embedded systems.
 
 ```
    | | |     .---._____
@@ -16,9 +16,9 @@ more about filesystem design by tackling the relative unsolved problem of
 managing a robust filesystem resilient to power loss on devices
 with limited RAM and ROM.
 
-The embedded systems the littlefs is targeting are usually 32bit
-microcontrollers with around 32Kbytes of RAM and 512Kbytes of ROM. These are
-often paired with SPI NOR flash chips with about 4Mbytes of flash storage.
+The embedded systems the littlefs is targeting are usually 32 bit
+microcontrollers with around 32KB of RAM and 512KB of ROM. These are
+often paired with SPI NOR flash chips with about 4MB of flash storage.
 
 Flash itself is a very interesting piece of technology with quite a bit of
 nuance. Unlike most other forms of storage, writing to flash requires two
@@ -32,17 +32,17 @@ has more information if you are interesting in how this works.
 This leaves us with an interesting set of limitations that can be simplified
 to three strong requirements:
 
-1. **Fail-safe** - This is actually the main goal of the littlefs and the focus
-   of this project. Embedded systems are usually designed without a shutdown
-   routine and a notable lack of user interface for recovery, so filesystems
-   targeting embedded systems should be prepared to lose power an any given
-   time.
+1. **Power-loss resilient** - This is the main goal of the littlefs and the
+   focus of this project. Embedded systems are usually designed without a
+   shutdown routine and a notable lack of user interface for recovery, so
+   filesystems targeting embedded systems must be prepared to lose power an
+   any given time.
 
    Despite this state of things, there are very few embedded filesystems that
-   handle power loss in a reasonable manner, and can become corrupted if the
-   user is unlucky enough.
+   handle power loss in a reasonable manner, and most can become corrupted if
+   the user is unlucky enough.
 
-2. **Wear awareness** - Due to the destructive nature of flash, most flash
+2. **Wear leveling** - Due to the destructive nature of flash, most flash
    chips have a limited number of erase cycles, usually in the order of around
    100,000 erases per block for NOR flash. Filesystems that don't take wear
    into account can easily burn through blocks used to store frequently updated
@@ -78,9 +78,9 @@ summary of the general ideas behind some of them.
 Most of the existing filesystems fall into the one big category of filesystem
 designed in the early days of spinny magnet disks. While there is a vast amount
 of interesting technology and ideas in this area, the nature of spinny magnet
-disks encourage properties such as grouping writes near each other, that don't
+disks encourage properties, such as grouping writes near each other, that don't
 make as much sense on recent storage types. For instance, on flash, write
-locality is not as important and can actually increase wear destructively.
+locality is not important and can actually increase wear destructively.
 
 One of the most popular designs for flash filesystems is called the
 [logging filesystem](https://en.wikipedia.org/wiki/Log-structured_file_system).
@@ -97,8 +97,7 @@ scaling as the size of storage increases. And most filesystems compensate by
 caching large parts of the filesystem in RAM, a strategy that is unavailable
 for embedded systems.
 
-Another interesting filesystem design technique that the littlefs borrows the
-most from, is the [copy-on-write (COW)](https://en.wikipedia.org/wiki/Copy-on-write).
+Another interesting filesystem design technique is that of [copy-on-write (COW)](https://en.wikipedia.org/wiki/Copy-on-write).
 A good example of this is the [btrfs](https://en.wikipedia.org/wiki/Btrfs)
 filesystem. COW filesystems can easily recover from corrupted blocks and have
 natural protection against power loss. However, if they are not designed with
@@ -150,12 +149,12 @@ check our checksum we notice that block 1 was corrupted. So we fall back to
 block 2 and use the value 9.
 
 Using this concept, the littlefs is able to update metadata blocks atomically.
-There are a few other tweaks, such as using a 32bit crc and using sequence
+There are a few other tweaks, such as using a 32 bit crc and using sequence
 arithmetic to handle revision count overflow, but the basic concept
 is the same. These metadata pairs define the backbone of the littlefs, and the
 rest of the filesystem is built on top of these atomic updates.
 
-## Files
+## Non-meta data
 
 Now, the metadata pairs do come with some drawbacks. Most notably, each pair
 requires two blocks for each block of data. I'm sure users would be very
@@ -200,7 +199,7 @@ Now we could just leave files here, copying the entire file on write
 provides the synchronization without the duplicated memory requirements
 of the metadata blocks. However, we can do a bit better.
 
-## CTZ linked-lists
+## CTZ skip-lists
 
 There are many different data structures for representing the actual
 files in filesystems. Of these, the littlefs uses a rather unique [COW](https://upload.wikimedia.org/wikipedia/commons/0/0c/Cow_female_black_white.jpg)
@@ -224,12 +223,12 @@ Exhibit A: A linked-list
 
 To get around this, the littlefs, at its heart, stores files backwards. Each
 block points to its predecessor, with the first block containing no pointers.
-If you think about this, it makes a bit of sense. Appending blocks just point
-to their predecessor and no other blocks need to be updated. If we update
-a block in the middle, we will need to copy out the blocks that follow,
-but can reuse the blocks before the modified block. Since most file operations
-either reset the file each write or append to files, this design avoids
-copying the file in the most common cases.
+If you think about for a while, it starts to make a bit of sense. Appending
+blocks just point to their predecessor and no other blocks need to be updated.
+If we update a block in the middle, we will need to copy out the blocks that
+follow, but can reuse the blocks before the modified block. Since most file
+operations either reset the file each write or append to files, this design
+avoids copying the file in the most common cases.
 
 ```
 Exhibit B: A backwards linked-list
@@ -246,19 +245,19 @@ runtime to just _read_ a file? That's awful. Keep in mind reading files are
 usually the most common filesystem operation.
 
 To avoid this problem, the littlefs uses a multilayered linked-list. For
-every block that is divisible by a power of two, the block contains an
-additional pointer that points back by that power of two. Another way of
-thinking about this design is that there are actually many linked-lists
-threaded together, with each linked-lists skipping an increasing number
-of blocks. If you're familiar with data-structures, you may have also
-recognized that this is a deterministic skip-list.
+every nth block where n is divisible by 2^x, the block contains a pointer
+to block n-2^x. So each block contains anywhere from 1 to log2(n) pointers
+that skip to various sections of the preceding list. If you're familiar with
+data-structures, you may have recognized that this is a type of deterministic
+skip-list.
 
-To find the power of two factors efficiently, we can use the instruction
-[count trailing zeros (CTZ)](https://en.wikipedia.org/wiki/Count_trailing_zeros),
-which is where this linked-list's name comes from.
+The name comes from the use of the
+[count trailing zeros (CTZ)](https://en.wikipedia.org/wiki/Count_trailing_zeros)
+instruction, which allows us to calculate the power-of-two factors efficiently.
+For a given block n, the block contains ctz(n)+1 pointers.
 
 ```
-Exhibit C: A backwards CTZ linked-list
+Exhibit C: A backwards CTZ skip-list
 .--------.  .--------.  .--------.  .--------.  .--------.  .--------.
 | data 0 |<-| data 1 |<-| data 2 |<-| data 3 |<-| data 4 |<-| data 5 |
 |        |<-|        |--|        |<-|        |--|        |  |        |
@@ -266,6 +265,9 @@ Exhibit C: A backwards CTZ linked-list
 '--------'  '--------'  '--------'  '--------'  '--------'  '--------'
 ```
 
+The additional pointers allow us to navigate the data-structure on disk
+much more efficiently than in a single linked-list.
+
 Taking exhibit C for example, here is the path from data block 5 to data
 block 1. You can see how data block 3 was completely skipped:
 ```
@@ -285,15 +287,133 @@ The path to data block 0 is even more quick, requiring only two jumps:
 '--------'  '--------'  '--------'  '--------'  '--------'  '--------'
 ```
 
-The CTZ linked-list has quite a few interesting properties. All of the pointers
-in the block can be found by just knowing the index in the list of the current
-block, and, with a bit of math, the amortized overhead for the linked-list is
-only two pointers per block.  Most importantly, the CTZ linked-list has a
-worst case lookup runtime of O(logn), which brings the runtime of reading a
-file down to O(n logn). Given that the constant runtime is divided by the
-amount of data we can store in a block, this is pretty reasonable.
+We can find the runtime complexity by looking at the path to any block from
+the block containing the most pointers. Every step along the path divides
+the search space for the block in half. This gives us a runtime of O(logn).
+To get to the block with the most pointers, we can perform the same steps
+backwards, which puts the runtime at O(2logn) = O(logn). The interesting
+part about this data structure is that this optimal path occurs naturally
+if we greedily choose the pointer that covers the most distance without passing
+our target block.
 
-Here is what it might look like to update a file stored with a CTZ linked-list:
+So now we have a representation of files that can be appended trivially with
+a runtime of O(1), and can be read with a worst case runtime of O(nlogn).
+Given that the the runtime is also divided by the amount of data we can store
+in a block, this is pretty reasonable.
+
+Unfortunately, the CTZ skip-list comes with a few questions that aren't
+straightforward to answer. What is the overhead? How do we handle more
+pointers than we can store in a block? How do we store the skip-list in
+a directory entry?
+
+One way to find the overhead per block is to look at the data structure as
+multiple layers of linked-lists. Each linked-list skips twice as many blocks
+as the previous linked-list. Another way of looking at it is that each 
+linked-list uses half as much storage per block as the previous linked-list.
+As we approach infinity, the number of pointers per block forms a geometric
+series. Solving this geometric series gives us an average of only 2 pointers
+per block.
+
+![overhead_per_block](https://latex.codecogs.com/svg.latex?%5Clim_%7Bn%5Cto%5Cinfty%7D%5Cfrac%7B1%7D%7Bn%7D%5Csum_%7Bi%3D0%7D%5E%7Bn%7D%5Cleft%28%5Ctext%7Bctz%7D%28i%29&plus;1%5Cright%29%20%3D%20%5Csum_%7Bi%3D0%7D%5Cfrac%7B1%7D%7B2%5Ei%7D%20%3D%202)
+
+Finding the maximum number of pointers in a block is a bit more complicated,
+but since our file size is limited by the integer width we use to store the
+size, we can solve for it. Setting the overhead of the maximum pointers equal
+to the block size we get the following equation. Note that a smaller block size
+results in more pointers, and a larger word width results in larger pointers.
+
+![maximum overhead](https://latex.codecogs.com/svg.latex?B%20%3D%20%5Cfrac%7Bw%7D%7B8%7D%5Cleft%5Clceil%5Clog_2%5Cleft%28%5Cfrac%7B2%5Ew%7D%7BB-2%5Cfrac%7Bw%7D%7B8%7D%7D%5Cright%29%5Cright%5Crceil)
+
+where:  
+B = block size in bytes  
+w = word width in bits  
+
+Solving the equation for B gives us the minimum block size for various word
+widths:  
+32 bit CTZ skip-list = minimum block size of 104 bytes  
+64 bit CTZ skip-list = minimum block size of 448 bytes  
+
+Since littlefs uses a 32 bit word size, we are limited to a minimum block
+size of 104 bytes. This is a perfectly reasonable minimum block size, with most
+block sizes starting around 512 bytes. So we can avoid additional logic to
+avoid overflowing our block's capacity in the CTZ skip-list.
+
+So, how do we store the skip-list in a directory entry? A naive approach would
+be to store a pointer to the head of the skip-list, the length of the file
+in bytes, the index of the head block in the skip-list, and the offset in the
+head block in bytes. However this is a lot of information, and we can observe
+that a file size maps to only one block index + offset pair. So it should be
+sufficient to store only the pointer and file size.
+
+But there is one problem, calculating the block index + offset pair from a
+file size doesn't have an obvious implementation.
+
+We can start by just writing down an equation. The first idea that comes to
+mind is to just use a for loop to sum together blocks until we reach our
+file size. We can write this equation as a summation:
+
+![summation1](https://latex.codecogs.com/svg.latex?N%20%3D%20%5Csum_i%5En%5Cleft%5BB-%5Cfrac%7Bw%7D%7B8%7D%5Cleft%28%5Ctext%7Bctz%7D%28i%29&plus;1%5Cright%29%5Cright%5D)
+
+where:  
+B = block size in bytes  
+w = word width in bits  
+n = block index in skip-list  
+N = file size in bytes  
+
+And this works quite well, but is not trivial to calculate. This equation
+requires O(n) to compute, which brings the entire runtime of reading a file
+to O(n^2logn). Fortunately, the additional O(n) does not need to touch disk,
+so it is not completely unreasonable. But if we could solve this equation into
+a form that is easily computable, we can avoid a big slowdown.
+
+Unfortunately, the summation of the CTZ instruction presents a big challenge.
+How would you even begin to reason about integrating a bitwise instruction?
+Fortunately, there is a powerful tool I've found useful in these situations:
+The [On-Line Encyclopedia of Integer Sequences (OEIS)](https://oeis.org/).
+If we work out the first couple of values in our summation, we find that CTZ
+maps to [A001511](https://oeis.org/A001511), and its partial summation maps
+to [A005187](https://oeis.org/A005187), and surprisingly, both of these
+sequences have relatively trivial equations! This leads us to a rather
+unintuitive property:
+
+![mindblown](https://latex.codecogs.com/svg.latex?%5Csum_i%5En%5Cleft%28%5Ctext%7Bctz%7D%28i%29&plus;1%5Cright%29%20%3D%202n-%5Ctext%7Bpopcount%7D%28n%29)
+
+where:  
+ctz(i) = the number of trailing bits that are 0 in i  
+popcount(i) = the number of bits that are 1 in i  
+
+It's a bit bewildering that these two seemingly unrelated bitwise instructions
+are related by this property. But if we start to disect this equation we can
+see that it does hold. As n approaches infinity, we do end up with an average
+overhead of 2 pointers as we find earlier. And popcount seems to handle the
+error from this average as it accumulates in the CTZ skip-list.
+
+Now we can substitute into the original equation to get a trivial equation
+for a file size:
+
+![summation2](https://latex.codecogs.com/svg.latex?N%20%3D%20Bn%20-%20%5Cfrac%7Bw%7D%7B8%7D%5Cleft%282n-%5Ctext%7Bpopcount%7D%28n%29%5Cright%29)
+
+Unfortunately, we're not quite done. The popcount function is non-injective,
+so we can only find the file size from the block index, not the other way
+around. However, we can solve for an n' block index that is greater than n
+with an error bounded by the range of the popcount function. We can then
+repeatedly substitute this n' into the original equation until the error
+is smaller than the integer division. As it turns out, we only need to
+perform this substitution once. Now we directly calculate our block index:
+
+![formulaforn](https://latex.codecogs.com/svg.latex?n%20%3D%20%5Cleft%5Clfloor%5Cfrac%7BN-%5Cfrac%7Bw%7D%7B8%7D%5Cleft%28%5Ctext%7Bpopcount%7D%5Cleft%28%5Cfrac%7BN%7D%7BB-2%5Cfrac%7Bw%7D%7B8%7D%7D-1%5Cright%29&plus;2%5Cright%29%7D%7BB-2%5Cfrac%7Bw%7D%7B8%7D%7D%5Cright%5Crfloor)
+
+Now that we have our block index n, we can just plug it back into the above
+equation to find the offset. However, we do need to rearrange the equation
+a bit to avoid integer overflow:
+
+![formulaforoff](https://latex.codecogs.com/svg.latex?%5Cmathit%7Boff%7D%20%3D%20N%20-%20%5Cleft%28B-2%5Cfrac%7Bw%7D%7B8%7D%5Cright%29n%20-%20%5Cfrac%7Bw%7D%7B8%7D%5Ctext%7Bpopcount%7D%28n%29)
+
+The solution involves quite a bit of math, but computers are very good at math.
+We can now solve for the block index + offset while only needed to store the
+file size in O(1).
+
+Here is what it might look like to update a file stored with a CTZ skip-list:
 ```
                                       block 1   block 2
                                     .---------.---------.
@@ -367,7 +487,7 @@ v
 ## Block allocation
 
 So those two ideas provide the grounds for the filesystem. The metadata pairs
-give us directories, and the CTZ linked-lists give us files. But this leaves
+give us directories, and the CTZ skip-lists give us files. But this leaves
 one big [elephant](https://upload.wikimedia.org/wikipedia/commons/3/37/African_Bush_Elephant.jpg)
 of a question. How do we get those blocks in the first place?
 
@@ -653,9 +773,17 @@ deorphan step that simply iterates through every directory in the linked-list
 and checks it against every directory entry in the filesystem to see if it
 has a parent. The deorphan step occurs on the first block allocation after
 boot, so orphans should never cause the littlefs to run out of storage
-prematurely.
+prematurely. Note that the deorphan step never needs to run in a readonly
+filesystem.
 
-And for my final trick, moving a directory:
+## The move problem
+
+Now we have a real problem. How do we move things between directories while
+remaining power resilient? Even looking at the problem from a high level,
+it seems impossible. We can update directory blocks atomically, but atomically
+updating two independent directory blocks is not an atomic operation.
+
+Here's the steps the filesystem may go through to move a directory:
 ```
          .--------.
          |root dir|-.
@@ -716,18 +844,135 @@ v
      '--------'
 ```
 
-Note that once again we don't care about the ordering of directories in the
-linked-list, so we can simply leave directories in their old positions. This
-does make the diagrams a bit hard to draw, but the littlefs doesn't really
-care.
+We can leave any orphans up to the deorphan step to collect, but that doesn't
+help the case where dir A has both dir B and the root dir as parents if we
+lose power inconveniently.
 
-It's also worth noting that once again we have an operation that isn't actually
-atomic. After we add directory A to directory B, we could lose power, leaving
-directory A as a part of both the root directory and directory B. However,
-there isn't anything inherent to the littlefs that prevents a directory from
-having multiple parents, so in this case, we just allow that to happen. Extra
-care is taken to only remove a directory from the linked-list if there are
-no parents left in the filesystem.
+Initially, you might think this is fine. Dir A _might_ end up with two parents,
+but the filesystem will still work as intended. But then this raises the
+question of what do we do when the dir A wears out? For other directory blocks
+we can update the parent pointer, but for a dir with two parents we would need
+work out how to update both parents. And the check for multiple parents would
+need to be carried out for every directory, even if the directory has never
+been moved.
+
+It also presents a bad user-experience, since the condition of ending up with
+two parents is rare, it's unlikely user-level code will be prepared. Just think
+about how a user would recover from a multi-parented directory. They can't just
+remove one directory, since remove would report the directory as "not empty".
+
+Other atomic filesystems simple COW the entire directory tree. But this
+introduces a significant bit of complexity, which leads to code size, along
+with a surprisingly expensive runtime cost during what most users assume is
+a single pointer update.
+
+Another option is to update the directory block we're moving from to point
+to the destination with a sort of predicate that we have moved if the
+destination exists. Unfortunately, the omnipresent concern of wear could
+cause any of these directory entries to change blocks, and changing the
+entry size before a move introduces complications if it spills out of
+the current directory block.
+
+So how do we go about moving a directory atomically?
+
+We rely on the improbableness of power loss.
+
+Power loss during a move is certainly possible, but it's actually relatively
+rare. Unless a device is writing to a filesystem constantly, it's unlikely that
+a power loss will occur during filesystem activity. We still need to handle
+the condition, but runtime during a power loss takes a back seat to the runtime
+during normal operations.
+
+So what littlefs does is unelegantly simple. When littlefs moves a file, it
+marks the file as "moving". This is stored as a single bit in the directory
+entry and doesn't take up much space. Then littlefs moves the directory,
+finishing with the complete remove of the "moving" directory entry.
+
+```
+         .--------.
+         |root dir|-.
+         | pair 0 | |
+.--------|        |-'
+|        '--------'
+|        .-'    '-.
+|       v          v
+|  .--------.  .--------.
+'->| dir A  |->| dir B  |
+   | pair 0 |  | pair 0 |
+   |        |  |        |
+   '--------'  '--------'
+
+|  update root directory to mark directory A as moving
+v
+
+        .----------.
+        |root dir  |-.
+        | pair 0   | |
+.-------| moving A!|-'
+|       '----------'
+|        .-'    '-.
+|       v          v
+|  .--------.  .--------.
+'->| dir A  |->| dir B  |
+   | pair 0 |  | pair 0 |
+   |        |  |        |
+   '--------'  '--------'
+
+|  update directory B to point to directory A
+v
+
+        .----------.
+        |root dir  |-.
+        | pair 0   | |
+.-------| moving A!|-'
+|       '----------'
+|    .-----'    '-.
+|    |             v
+|    |           .--------.
+|    |        .->| dir B  |
+|    |        |  | pair 0 |
+|    |        |  |        |
+|    |        |  '--------'
+|    |     .-------'
+|    v    v   |
+|  .--------. |
+'->| dir A  |-'
+   | pair 0 |
+   |        |
+   '--------'
+
+|  update root to no longer contain directory A
+v
+     .--------.
+     |root dir|-.
+     | pair 0 | |
+.----|        |-'
+|    '--------'
+|        |
+|        v
+|    .--------.
+| .->| dir B  |
+| |  | pair 0 |
+| '--|        |-.
+|    '--------' |
+|        |      |
+|        v      |
+|    .--------. |
+'--->| dir A  |-'
+     | pair 0 |
+     |        |
+     '--------'
+```
+
+Now, if we run into a directory entry that has been marked as "moved", one
+of two things is possible. Either the directory entry exists elsewhere in the
+filesystem, or it doesn't. This is a O(n) operation, but only occurs in the
+unlikely case we lost power during a move.
+
+And we can easily fix the "moved" directory entry. Since we're already scanning
+the filesystem during the deorphan step, we can also check for moved entries.
+If we find one, we either remove the "moved" marking or remove the whole entry
+if it exists elsewhere in the filesystem.
 
 ## Wear awareness
 
@@ -908,21 +1153,26 @@ develops errors and needs to be moved.
 
 The second concern for the littlefs, is that blocks in the filesystem may wear
 unevenly. In this situation, a filesystem may meet an early demise where
-there are no more non-corrupted blocks that aren't in use. It may be entirely
-possible that files were written once and left unmodified, wasting the
-potential erase cycles of the blocks it sits on.
+there are no more non-corrupted blocks that aren't in use. It's common to
+have files that were written once and left unmodified, wasting the potential
+erase cycles of the blocks it sits on.
 
 Wear leveling is a term that describes distributing block writes evenly to
 avoid the early termination of a flash part. There are typically two levels
 of wear leveling:
-1. Dynamic wear leveling - Blocks are distributed evenly during blocks writes.
-   Note that the issue with write-once files still exists in this case.
-2. Static wear leveling - Unmodified blocks are evicted for new block writes.
-   This provides the longest lifetime for a flash device.
+1. Dynamic wear leveling - Wear is distributed evenly across all **dynamic**
+   blocks. Usually this is accomplished by simply choosing the unused block
+   with the lowest amount of wear. Note this does not solve the problem of
+   static data.
+2. Static wear leveling - Wear is distributed evenly across all **dynamic**
+   and **static** blocks. Unmodified blocks may be evicted for new block
+   writes. This does handle the problem of static data but may lead to
+   wear amplification.
 
-Now, it's possible to use the revision count on metadata pairs to approximate
-the wear of a metadata block. And combined with the COW nature of files, the
-littlefs could provide a form of dynamic wear leveling.
+In littlefs's case, it's possible to use the revision count on metadata pairs
+to approximate the wear of a metadata block. And combined with the COW nature
+of files, littlefs could provide your usually implementation of dynamic wear
+leveling.
 
 However, the littlefs does not. This is for a few reasons. Most notably, even
 if the littlefs did implement dynamic wear leveling, this would still not
@@ -933,19 +1183,20 @@ As a flash device reaches the end of its life, the metadata blocks will
 naturally be the first to go since they are updated most often. In this
 situation, the littlefs is designed to simply move on to another set of
 metadata blocks. This travelling means that at the end of a flash device's
-life, the filesystem will have worn the device down as evenly as a dynamic
-wear leveling filesystem could anyways. Simply put, if the lifetime of flash
-is a serious concern, static wear leveling is the only valid solution.
+life, the filesystem will have worn the device down nearly as evenly as the
+usual dynamic wear leveling could. More aggressive wear leveling would come
+with a code-size cost for marginal benefit.
 
-This is a very important takeaway to note. If your storage stack uses highly
-sensitive storage such as NAND flash. In most cases you are going to be better
-off just using a [flash translation layer (FTL)](https://en.wikipedia.org/wiki/Flash_translation_layer).
+
+One important takeaway to note, if your storage stack uses highly sensitive
+storage such as NAND flash, static wear leveling is the only valid solution.
+In most cases you are going to be better off using a full [flash translation layer (FTL)](https://en.wikipedia.org/wiki/Flash_translation_layer).
 NAND flash already has many limitations that make it poorly suited for an
 embedded system: low erase cycles, very large blocks, errors that can develop
 even during reads, errors that can develop during writes of neighboring blocks.
 Managing sensitive storage such as NAND flash is out of scope for the littlefs.
 The littlefs does have some properties that may be beneficial on top of a FTL,
-such as limiting the number of writes where possible. But if you have the
+such as limiting the number of writes where possible, but if you have the
 storage requirements that necessitate the need of NAND flash, you should have
 the RAM to match and just use an FTL or flash filesystem.
 
@@ -955,18 +1206,18 @@ So, to summarize:
 
 1. The littlefs is composed of directory blocks
 2. Each directory is a linked-list of metadata pairs
-3. These metadata pairs can be updated atomically by alternative which
+3. These metadata pairs can be updated atomically by alternating which
    metadata block is active
 4. Directory blocks contain either references to other directories or files
-5. Files are represented by copy-on-write CTZ linked-lists
-6. The CTZ linked-lists support appending in O(1) and reading in O(n logn)
-7. Blocks are allocated by scanning the filesystem for used blocks in a
+5. Files are represented by copy-on-write CTZ skip-lists which support O(1)
+   append and O(nlogn) reading
+6. Blocks are allocated by scanning the filesystem for used blocks in a
    fixed-size lookahead region is that stored in a bit-vector
-8. To facilitate scanning the filesystem, all directories are part of a
+7. To facilitate scanning the filesystem, all directories are part of a
    linked-list that is threaded through the entire filesystem
-9. If a block develops an error, the littlefs allocates a new block, and
+8. If a block develops an error, the littlefs allocates a new block, and
    moves the data and references of the old block to the new.
-10. Any case where an atomic operation is not possible, it is taken care of
+9. Any case where an atomic operation is not possible, mistakes are resolved
    by a deorphan step that occurs on the first allocation after boot
 
 That's the little filesystem. Thanks for reading!

Makefile

@@ -11,6 +11,8 @@ ASM := $(SRC:.c=.s)
 
 TEST := $(patsubst tests/%.sh,%,$(wildcard tests/test_*))
 
+SHELL = /bin/bash -o pipefail
+
 ifdef DEBUG
 CFLAGS += -O0 -g3
 else
@@ -31,10 +33,14 @@ size: $(OBJ)
 	$(SIZE) -t $^
 
 .SUFFIXES:
-test: test_format test_dirs test_files test_seek test_parallel \
-	test_alloc test_paths test_orphan test_corrupt
+test: test_format test_dirs test_files test_seek test_truncate test_parallel \
+	test_alloc test_paths test_orphan test_move test_corrupt
 test_%: tests/test_%.sh
+ifdef QUIET
+	./$< | sed -n '/^[-=]/p'
+else
 	./$<
+endif
 
 -include $(DEP)
 

README.md

@@ -11,23 +11,17 @@ A little fail-safe filesystem designed for embedded systems.
    | | |
 ```
 
-**Fail-safe** - The littlefs is designed to work consistently with random
-power failures. During filesystem operations the storage on disk is always
-kept in a valid state. The filesystem also has strong copy-on-write garuntees.
-When updating a file, the original file will remain unmodified until the
-file is closed, or sync is called.
+**Bounded RAM/ROM** - The littlefs is designed to work with a limited amount
+of memory. Recursion is avoided and dynamic memory is limited to configurable
+buffers that can be provided statically.
 
-**Wear awareness** - While the littlefs does not implement static wear
-leveling, the littlefs takes into account write errors reported by the
-underlying block device and uses a limited form of dynamic wear leveling
-to manage blocks that go bad during the lifetime of the filesystem.
+**Power-loss resilient** - The littlefs is designed for systems that may have
+random power failures. The littlefs has strong copy-on-write guaruntees and
+storage on disk is always kept in a valid state.
 
-**Bounded ram/rom** - The littlefs is designed to work in a
-limited amount of memory, recursion is avoided, and dynamic memory is kept
-to a minimum. The littlefs allocates two fixed-size buffers for general
-operations, and one fixed-size buffer per file. If there is only ever one file
-in use, all memory can be provided statically and the littlefs can be used
-in a system without dynamic memory.
+**Wear leveling** - Since the most common form of embedded storage is erodible
+flash memories, littlefs provides a form of dynamic wear leveling for systems
+that can not fit a full flash translation layer.
 
 ## Example
 
@@ -96,7 +90,7 @@ int main(void) {
 Detailed documentation (or at least as much detail as is currently available)
 can be cound in the comments in [lfs.h](lfs.h).
 
-As you may have noticed, the littlefs takes in a configuration structure that
+As you may have noticed, littlefs takes in a configuration structure that
 defines how the filesystem operates. The configuration struct provides the
 filesystem with the block device operations and dimensions, tweakable
 parameters that tradeoff memory usage for performance, and optional
@@ -104,14 +98,16 @@ static buffers if the user wants to avoid dynamic memory.
 
 The state of the littlefs is stored in the `lfs_t` type which is left up
 to the user to allocate, allowing multiple filesystems to be in use
-simultaneously. With the `lfs_t` and configuration struct, a user can either
+simultaneously. With the `lfs_t` and configuration struct, a user can
 format a block device or mount the filesystem.
 
 Once mounted, the littlefs provides a full set of posix-like file and
 directory functions, with the deviation that the allocation of filesystem
-structures must be provided by the user. An important addition is that
-no file updates will actually be written to disk until a sync or close
-is called.
+structures must be provided by the user.
+
+All posix operations, such as remove and rename, are atomic, even in event
+of power-loss. Additionally, no file updates are actually commited to the
+filesystem until sync or close is called on the file.
 
 ## Other notes
 
@@ -119,19 +115,19 @@ All littlefs have the potential to return a negative error code. The errors
 can be either one of those found in the `enum lfs_error` in [lfs.h](lfs.h),
 or an error returned by the user's block device operations.
 
-It should also be noted that the littlefs does not do anything to insure
-that the data written to disk is machine portable. It should be fine as
-long as the machines involved share endianness and don't have really
-strange padding requirements. If the question does come up, the littlefs
-metadata should be stored on disk in little-endian format.
+It should also be noted that the current implementation of littlefs doesn't
+really do anything to insure that the data written to disk is machine portable.
+This is fine as long as all of the involved machines share endianness
+(little-endian) and don't have strange padding requirements.
 
-## Design
+## Reference material
 
-the littlefs was developed with the goal of learning more about filesystem
-design by tackling the relative unsolved problem of managing a robust
-filesystem resilient to power loss on devices with limited RAM and ROM.
-More detail on the solutions and tradeoffs incorporated into this filesystem
-can be found in [DESIGN.md](DESIGN.md).
+[DESIGN.md](DESIGN.md) - DESIGN.md contains a fully detailed dive into how
+littlefs actually works. I would encourage you to read it since the
+solutions and tradeoffs at work here are quite interesting.
+
+[SPEC.md](SPEC.md) - SPEC.md contains the on-disk specification of littlefs
+with all the nitty-gritty details. Can be useful for developing tooling.
 
 ## Testing
 
@@ -142,3 +138,20 @@ The tests assume a linux environment and can be started with make:
 ``` bash
 make test
 ```
+
+## Related projects
+
+[Mbed OS](https://github.com/ARMmbed/mbed-os/tree/master/features/filesystem/littlefs) -
+The easiest way to get started with littlefs is to jump into [Mbed](https://os.mbed.com/),
+which already has block device drivers for most forms of embedded storage. The
+littlefs is available in Mbed OS as the [LittleFileSystem](https://os.mbed.com/docs/latest/reference/littlefilesystem.html)
+class.
+
+[littlefs-fuse](https://github.com/geky/littlefs-fuse) - A [FUSE](https://github.com/libfuse/libfuse)
+wrapper for littlefs. The project allows you to mount littlefs directly in a
+Linux machine. Can be useful for debugging littlefs if you have an SD card
+handy.
+
+[littlefs-js](https://github.com/geky/littlefs-js) - A javascript wrapper for
+littlefs. I'm not sure why you would want this, but it is handy for demos.
+You can see it in action [here](http://littlefs.geky.net/demo.html).

SPEC.md

@@ -0,0 +1,370 @@
+## The little filesystem technical specification
+
+This is the technical specification of the little filesystem. This document
+covers the technical details of how the littlefs is stored on disk for
+introspection and tooling development. This document assumes you are
+familiar with the design of the littlefs, for more info on how littlefs
+works check out [DESIGN.md](DESIGN.md).
+
+```
+   | | |     .---._____
+  .-----.   |          |
+--|o    |---| littlefs |
+--|     |---|          |
+  '-----'   '----------'
+   | | |
+```
+
+## Some important details
+
+- The littlefs is a block-based filesystem. This is, the disk is divided into
+  an array of evenly sized blocks that are used as the logical unit of storage
+  in littlefs. Block pointers are stored in 32 bits.
+
+- There is no explicit free-list stored on disk, the littlefs only knows what
+  is in use in the filesystem.
+
+- The littlefs uses the value of 0xffffffff to represent a null block-pointer.
+
+- All values in littlefs are stored in little-endian byte order.
+
+## Directories / Metadata pairs
+
+Metadata pairs form the backbone of the littlefs and provide a system for
+atomic updates. Even the superblock is stored in a metadata pair.
+
+As their name suggests, a metadata pair is stored in two blocks, with one block
+acting as a redundant backup in case the other is corrupted. These two blocks
+could be anywhere in the disk and may not be next to each other, so any
+pointers to directory pairs need to be stored as two block pointers.
+
+Here's the layout of metadata blocks on disk:
+
+| offset | size          | description    |
+|--------|---------------|----------------|
+| 0x00   | 32 bits       | revision count |
+| 0x04   | 32 bits       | dir size       |
+| 0x08   | 64 bits       | tail pointer   |
+| 0x10   | size-16 bytes | dir entries    |
+| 0x00+s | 32 bits       | crc            |
+
+**Revision count** - Incremented every update, only the uncorrupted
+metadata-block with the most recent revision count contains the valid metadata.
+Comparison between revision counts must use sequence comparison since the
+revision counts may overflow.
+
+**Dir size** - Size in bytes of the contents in the current metadata block,
+including the metadata-pair metadata. Additionally, the highest bit of the
+dir size may be set to indicate that the directory's contents continue on the
+next metadata-pair pointed to by the tail pointer.
+
+**Tail pointer** - Pointer to the next metadata-pair in the filesystem.
+A null pair-pointer (0xffffffff, 0xffffffff) indicates the end of the list.
+If the highest bit in the dir size is set, this points to the next
+metadata-pair in the current directory, otherwise it points to an arbitrary
+metadata-pair. Starting with the superblock, the tail-pointers form a
+linked-list containing all metadata-pairs in the filesystem.
+
+**CRC** - 32 bit CRC used to detect corruption from power-lost, from block
+end-of-life, or just from noise on the storage bus. The CRC is appended to
+the end of each metadata-block. The littlefs uses the standard CRC-32, which
+uses a polynomial of 0x04c11db7, initialized with 0xffffffff.
+
+Here's an example of a simple directory stored on disk:
+```
+(32 bits) revision count = 10                    (0x0000000a)
+(32 bits) dir size       = 154 bytes, end of dir (0x0000009a)
+(64 bits) tail pointer   = 37, 36                (0x00000025, 0x00000024)
+(32 bits) crc            = 0xc86e3106
+
+00000000: 0a 00 00 00 9a 00 00 00 25 00 00 00 24 00 00 00  ........%...$...
+00000010: 22 08 00 03 05 00 00 00 04 00 00 00 74 65 61 22  "...........tea"
+00000020: 08 00 06 07 00 00 00 06 00 00 00 63 6f 66 66 65  ...........coffe
+00000030: 65 22 08 00 04 09 00 00 00 08 00 00 00 73 6f 64  e"...........sod
+00000040: 61 22 08 00 05 1d 00 00 00 1c 00 00 00 6d 69 6c  a"...........mil
+00000050: 6b 31 22 08 00 05 1f 00 00 00 1e 00 00 00 6d 69  k1"...........mi
+00000060: 6c 6b 32 22 08 00 05 21 00 00 00 20 00 00 00 6d  lk2"...!... ...m
+00000070: 69 6c 6b 33 22 08 00 05 23 00 00 00 22 00 00 00  ilk3"...#..."...
+00000080: 6d 69 6c 6b 34 22 08 00 05 25 00 00 00 24 00 00  milk4"...%...$..
+00000090: 00 6d 69 6c 6b 35 06 31 6e c8                    .milk5.1n.
+```
+
+A note about the tail pointer linked-list: Normally, this linked-list is
+threaded through the entire filesystem. However, after power-loss this
+linked-list may become out of sync with the rest of the filesystem.
+- The linked-list may contain a directory that has actually been removed
+- The linked-list may contain a metadata pair that has not been updated after
+  a block in the pair has gone bad.
+
+The threaded linked-list must be checked for these errors before it can be
+used reliably. Fortunately, the threaded linked-list can simply be ignored
+if littlefs is mounted read-only.
+
+## Entries
+
+Each metadata block contains a series of entries that follow a standard
+layout. An entry contains the type of the entry, along with a section for
+entry-specific data, attributes, and a name.
+
+Here's the layout of entries on disk:
+
+| offset  | size                   | description                |
+|---------|------------------------|----------------------------|
+| 0x0     | 8 bits                 | entry type                 |
+| 0x1     | 8 bits                 | entry length               |
+| 0x2     | 8 bits                 | attribute length           |
+| 0x3     | 8 bits                 | name length                |
+| 0x4     | entry length bytes     | entry-specific data        |
+| 0x4+e   | attribute length bytes | system-specific attributes |
+| 0x4+e+a | name length bytes      | entry name                 |
+
+**Entry type** - Type of the entry, currently this is limited to the following:
+- 0x11 - file entry
+- 0x22 - directory entry
+- 0x2e - superblock entry
+
+Additionally, the type is broken into two 4 bit nibbles, with the upper nibble
+specifying the type's data structure used when scanning the filesystem. The
+lower nibble clarifies the type further when multiple entries share the same
+data structure.
+
+The highest bit is reserved for marking the entry as "moved". If an entry
+is marked as "moved", the entry may also exist somewhere else in the
+filesystem. If the entry exists elsewhere, this entry must be treated as
+though it does not exist.
+
+**Entry length** - Length in bytes of the entry-specific data. This does
+not include the entry type size, attributes, or name. The full size in bytes
+of the entry is 4 + entry length + attribute length + name length.
+
+**Attribute length** - Length of system-specific attributes in bytes. Since
+attributes are system specific, there is not much garuntee on the values in
+this section, and systems are expected to work even when it is empty. See the
+[attributes](#entry-attributes) section for more details.
+
+**Name length** - Length of the entry name. Entry names are stored as utf8,
+although most systems will probably only support ascii. Entry names can not
+contain '/' and can not be '.' or '..' as these are a part of the syntax of
+filesystem paths.
+
+Here's an example of a simple entry stored on disk:
+```
+(8 bits)   entry type       = file     (0x11)
+(8 bits)   entry length     = 8 bytes  (0x08)
+(8 bits)   attribute length = 0 bytes  (0x00)
+(8 bits)   name length      = 12 bytes (0x0c)
+(8 bytes)  entry data       = 05 00 00 00 20 00 00 00
+(12 bytes) entry name       = smallavacado
+
+00000000: 11 08 00 0c 05 00 00 00 20 00 00 00 73 6d 61 6c  ........ ...smal
+00000010: 6c 61 76 61 63 61 64 6f                          lavacado
+```
+
+## Superblock
+
+The superblock is the anchor for the littlefs. The superblock is stored as
+a metadata pair containing a single superblock entry. It is through the
+superblock that littlefs can access the rest of the filesystem.
+
+The superblock can always be found in blocks 0 and 1, however fetching the
+superblock requires knowing the block size. The block size can be guessed by
+searching the beginning of disk for the string "littlefs", although currently
+the filesystems relies on the user providing the correct block size.
+
+The superblock is the most valuable block in the filesystem. It is updated
+very rarely, only during format or when the root directory must be moved. It
+is encouraged to always write out both superblock pairs even though it is not
+required.
+
+Here's the layout of the superblock entry:
+
+| offset | size                   | description                            |
+|--------|------------------------|----------------------------------------|
+| 0x00   | 8 bits                 | entry type (0x2e for superblock entry) |
+| 0x01   | 8 bits                 | entry length (20 bytes)                |
+| 0x02   | 8 bits                 | attribute length                       |
+| 0x03   | 8 bits                 | name length (8 bytes)                  |
+| 0x04   | 64 bits                | root directory                         |
+| 0x0c   | 32 bits                | block size                             |
+| 0x10   | 32 bits                | block count                            |
+| 0x14   | 32 bits                | version                                |
+| 0x18   | attribute length bytes | system-specific attributes             |
+| 0x18+a | 8 bytes                | magic string ("littlefs")              |
+
+**Root directory** - Pointer to the root directory's metadata pair.
+
+**Block size** - Size of the logical block size used by the filesystem.
+
+**Block count** - Number of blocks in the filesystem.
+
+**Version** - The littlefs version encoded as a 32 bit value. The upper 16 bits
+encodes the major version, which is incremented when a breaking-change is
+introduced in the filesystem specification. The lower 16 bits encodes the
+minor version, which is incremented when a backwards-compatible change is
+introduced. Non-standard Attribute changes do not change the version. This
+specification describes version 1.1 (0x00010001), which is the first version
+of littlefs.
+
+**Magic string** - The magic string "littlefs" takes the place of an entry
+name.
+
+Here's an example of a complete superblock:
+```
+(32 bits) revision count   = 3                    (0x00000003)
+(32 bits) dir size         = 52 bytes, end of dir (0x00000034)
+(64 bits) tail pointer     = 3, 2                 (0x00000003, 0x00000002)
+(8 bits)  entry type       = superblock           (0x2e)
+(8 bits)  entry length     = 20 bytes             (0x14)
+(8 bits)  attribute length = 0 bytes              (0x00)
+(8 bits)  name length      = 8 bytes              (0x08)
+(64 bits) root directory   = 3, 2                 (0x00000003, 0x00000002)
+(32 bits) block size       = 512 bytes            (0x00000200)
+(32 bits) block count      = 1024 blocks          (0x00000400)
+(32 bits) version          = 1.1                  (0x00010001)
+(8 bytes) magic string     = littlefs
+(32 bits) crc              = 0xc50b74fa
+
+00000000: 03 00 00 00 34 00 00 00 03 00 00 00 02 00 00 00  ....4...........
+00000010: 2e 14 00 08 03 00 00 00 02 00 00 00 00 02 00 00  ................
+00000020: 00 04 00 00 01 00 01 00 6c 69 74 74 6c 65 66 73  ........littlefs
+00000030: fa 74 0b c5                                      .t..
+```
+
+## Directory entries
+
+Directories are stored in entries with a pointer to the first metadata pair
+in the directory. Keep in mind that a directory may be composed of multiple
+metadata pairs connected by the tail pointer when the highest bit in the dir
+size is set.
+
+Here's the layout of a directory entry:
+
+| offset | size                   | description                             |
+|--------|------------------------|-----------------------------------------|
+| 0x0    | 8 bits                 | entry type (0x22 for directory entries) |
+| 0x1    | 8 bits                 | entry length (8 bytes)                  |
+| 0x2    | 8 bits                 | attribute length                        |
+| 0x3    | 8 bits                 | name length                             |
+| 0x4    | 64 bits                | directory pointer                       |
+| 0xc    | attribute length bytes | system-specific attributes              |
+| 0xc+a  | name length bytes      | directory name                          |
+
+**Directory pointer** - Pointer to the first metadata pair in the directory.
+
+Here's an example of a directory entry:
+```
+(8 bits)  entry type        = directory (0x22)
+(8 bits)  entry length      = 8 bytes   (0x08)
+(8 bits)  attribute length  = 0 bytes   (0x00)
+(8 bits)  name length       = 3 bytes   (0x03)
+(64 bits) directory pointer = 5, 4      (0x00000005, 0x00000004)
+(3 bytes) name              = tea
+
+00000000: 22 08 00 03 05 00 00 00 04 00 00 00 74 65 61     "...........tea
+```
+
+## File entries
+
+Files are stored in entries with a pointer to the head of the file and the
+size of the file. This is enough information to determine the state of the
+CTZ skip-list that is being referenced.
+
+How files are actually stored on disk is a bit complicated. The full
+explanation of CTZ skip-lists can be found in [DESIGN.md](DESIGN.md#ctz-skip-lists).
+
+A terribly quick summary: For every nth block where n is divisible by 2^x,
+the block contains a pointer to block n-2^x. These pointers are stored in
+increasing order of x in each block of the file preceding the data in the
+block.
+
+The maximum number of pointers in a block is bounded by the maximum file size
+divided by the block size. With 32 bits for file size, this results in a
+minimum block size of 104 bytes.
+
+Here's the layout of a file entry:
+
+| offset | size                   | description                        |
+|--------|------------------------|------------------------------------|
+| 0x0    | 8 bits                 | entry type (0x11 for file entries) |
+| 0x1    | 8 bits                 | entry length (8 bytes)             |
+| 0x2    | 8 bits                 | attribute length                   |
+| 0x3    | 8 bits                 | name length                        |
+| 0x4    | 32 bits                | file head                          |
+| 0x8    | 32 bits                | file size                          |
+| 0xc    | attribute length bytes | system-specific attributes         |
+| 0xc+a  | name length bytes      | directory name                     |
+
+**File head** - Pointer to the block that is the head of the file's CTZ
+skip-list.
+
+**File size** - Size of file in bytes.
+
+Here's an example of a file entry:
+```
+(8 bits)   entry type       = file     (0x11)
+(8 bits)   entry length     = 8 bytes  (0x08)
+(8 bits)   attribute length = 0 bytes  (0x00)
+(8 bits)   name length      = 12 bytes (0x03)
+(32 bits)  file head        = 543      (0x0000021f)
+(32 bits)  file size        = 256 KB   (0x00040000)
+(12 bytes) name             = largeavacado
+
+00000000: 11 08 00 0c 1f 02 00 00 00 00 04 00 6c 61 72 67  ............larg
+00000010: 65 61 76 61 63 61 64 6f                          eavacado
+```
+
+## Entry attributes
+
+Each dir entry can have up to 256 bytes of system-specific attributes. Since
+these attributes are system-specific, they may not be portable between
+different systems. For this reason, all attributes must be optional. A minimal
+littlefs driver must be able to get away with supporting no attributes at all.
+
+For some level of portability, littlefs has a simple scheme for attributes.
+Each attribute is prefixes with an 8-bit type that indicates what the attribute
+is. The length of attributes may also be determined from this type. Attributes
+in an entry should be sorted based on portability, since attribute parsing
+will end when it hits the first attribute it does not understand.
+
+Each system should choose a 4-bit value to prefix all attribute types with to
+avoid conflicts with other systems. Additionally, littlefs drivers that support
+attributes should provide a "ignore attributes" flag to users in case attribute
+conflicts do occur.
+
+Attribute types prefixes with 0x0 and 0xf are currently reserved for future
+standard attributes. Standard attributes will be added to this document in
+that case.
+
+Here's an example of non-standard time attribute:
+```
+(8 bits)  attribute type  = time       (0xc1)
+(72 bits) time in seconds = 1506286115 (0x0059c81a23)
+
+00000000: c1 23 1a c8 59 00                                .#..Y.
+```
+
+Here's an example of non-standard permissions attribute:
+```
+(8 bits)  attribute type  = permissions (0xc2)
+(16 bits) permission bits = rw-rw-r--   (0x01b4)
+
+00000000: c2 b4 01                                         ...
+```
+
+Here's what a dir entry may look like with these attributes:
+```
+(8 bits)   entry type       = file         (0x11)
+(8 bits)   entry length     = 8 bytes      (0x08)
+(8 bits)   attribute length = 9 bytes      (0x09)
+(8 bits)   name length      = 12 bytes     (0x0c)
+(8 bytes)  entry data       = 05 00 00 00 20 00 00 00
+(8 bits)   attribute type   = time         (0xc1)
+(72 bits)  time in seconds  = 1506286115   (0x0059c81a23)
+(8 bits)   attribute type   = permissions  (0xc2)
+(16 bits)  permission bits  = rw-rw-r--    (0x01b4)
+(12 bytes) entry name       = smallavacado
+
+00000000: 11 08 09 0c 05 00 00 00 20 00 00 00 c1 23 1a c8  ........ ....#..
+00000010: 59 00 c2 b4 01 73 6d 61 6c 6c 61 76 61 63 61 64  Y....smallavacad
+00000020: 6f                                               o
+```

emubd/lfs_emubd.c

@@ -1,8 +1,19 @@
 /*
  * Block device emulated on standard files
  *
- * Copyright (c) 2017 Christopher Haster
- * Distributed under the Apache 2.0 license
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 #include "emubd/lfs_emubd.h"
 
@@ -127,8 +138,8 @@ int lfs_emubd_prog(const struct lfs_config *cfg, lfs_block_t block,
     snprintf(emu->child, LFS_NAME_MAX, "%x", block);
 
     FILE *f = fopen(emu->path, "r+b");
-    if (!f && errno != ENOENT) {
-        return -errno;
+    if (!f) {
+        return (errno == EACCES) ? 0 : -errno;
     }
 
     // Check that file was erased
@@ -178,14 +189,14 @@ int lfs_emubd_erase(const struct lfs_config *cfg, lfs_block_t block) {
         return -errno;
     }
 
-    if (!err && S_ISREG(st.st_mode)) {
+    if (!err && S_ISREG(st.st_mode) && (S_IWUSR & st.st_mode)) {
         int err = unlink(emu->path);
         if (err) {
             return -errno;
         }
     }
 
-    if (err || S_ISREG(st.st_mode)) {
+    if (errno == ENOENT || (S_ISREG(st.st_mode) && (S_IWUSR & st.st_mode))) {
         FILE *f = fopen(emu->path, "w");
         if (!f) {
             return -errno;

emubd/lfs_emubd.h

@@ -1,8 +1,19 @@
 /*
  * Block device emulated on standard files
  *
- * Copyright (c) 2017 Christopher Haster
- * Distributed under the Apache 2.0 license
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 #ifndef LFS_EMUBD_H
 #define LFS_EMUBD_H

lfs.h

@@ -1,8 +1,19 @@
 /*
  * The little filesystem
  *
- * Copyright (c) 2017 Christopher Haster
- * Distributed under the Apache 2.0 license
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 #ifndef LFS_H
 #define LFS_H
@@ -30,23 +41,24 @@ typedef uint32_t lfs_block_t;
 // Possible error codes, these are negative to allow
 // valid positive return values
 enum lfs_error {
-    LFS_ERR_OK      = 0,    // No error
-    LFS_ERR_IO      = -5,   // Error during device operation
-    LFS_ERR_CORRUPT = -52,  // Corrupted
-    LFS_ERR_NOENT   = -2,   // No directory entry
-    LFS_ERR_EXISTS  = -17,  // Entry already exists
-    LFS_ERR_NOTDIR  = -20,  // Entry is not a dir
-    LFS_ERR_ISDIR   = -21,  // Entry is a dir
-    LFS_ERR_INVAL   = -22,  // Invalid parameter
-    LFS_ERR_NOSPC   = -28,  // No space left on device
-    LFS_ERR_NOMEM   = -12,  // No more memory available
+    LFS_ERR_OK       = 0,    // No error
+    LFS_ERR_IO       = -5,   // Error during device operation
+    LFS_ERR_CORRUPT  = -52,  // Corrupted
+    LFS_ERR_NOENT    = -2,   // No directory entry
+    LFS_ERR_EXIST    = -17,  // Entry already exists
+    LFS_ERR_NOTDIR   = -20,  // Entry is not a dir
+    LFS_ERR_ISDIR    = -21,  // Entry is a dir
+    LFS_ERR_NOTEMPTY = -39,  // Dir is not empty
+    LFS_ERR_INVAL    = -22,  // Invalid parameter
+    LFS_ERR_NOSPC    = -28,  // No space left on device
+    LFS_ERR_NOMEM    = -12,  // No more memory available
 };
 
 // File types
 enum lfs_type {
     LFS_TYPE_REG        = 0x11,
     LFS_TYPE_DIR        = 0x22,
-    LFS_TYPE_SUPERBLOCK = 0xe2,
+    LFS_TYPE_SUPERBLOCK = 0x2e,
 };
 
 // File open flags
@@ -64,6 +76,7 @@ enum lfs_open_flags {
     LFS_F_DIRTY   = 0x10000, // File does not match storage
     LFS_F_WRITING = 0x20000, // File has been written since last flush
     LFS_F_READING = 0x40000, // File has been read since last flush
+    LFS_F_ERRED   = 0x80000, // An error occured during write
 };
 
 // File seek flags
@@ -87,14 +100,14 @@ struct lfs_config {
 
     // Program a region in a block. The block must have previously
     // been erased. Negative error codes are propogated to the user.
-    // The prog function must return LFS_ERR_CORRUPT if the block should
-    // be considered bad.
+    // May return LFS_ERR_CORRUPT if the block should be considered bad.
     int (*prog)(const struct lfs_config *c, lfs_block_t block,
             lfs_off_t off, const void *buffer, lfs_size_t size);
 
     // Erase a block. A block must be erased before being programmed.
     // The state of an erased block is undefined. Negative error codes
     // are propogated to the user.
+    // May return LFS_ERR_CORRUPT if the block should be considered bad.
     int (*erase)(const struct lfs_config *c, lfs_block_t block);
 
     // Sync the state of the underlying block device. Negative error codes
@@ -109,11 +122,13 @@ struct lfs_config {
     // Minimum size of a block program. This determines the size of program
     // buffers. This may be larger than the physical program size to improve
     // performance by caching more of the block device.
+    // Must be a multiple of the read size.
     lfs_size_t prog_size;
 
     // Size of an erasable block. This does not impact ram consumption and
     // may be larger than the physical erase size. However, this should be
-    // kept small as each file currently takes up an entire block .
+    // kept small as each file currently takes up an entire block.
+    // Must be a multiple of the program size.
     lfs_size_t block_size;
 
     // Number of erasable blocks on the device.
@@ -195,6 +210,7 @@ typedef struct lfs_file {
 } lfs_file_t;
 
 typedef struct lfs_dir {
+    struct lfs_dir *next;
     lfs_block_t pair[2];
     lfs_off_t off;
 
@@ -225,10 +241,10 @@ typedef struct lfs_superblock {
 } lfs_superblock_t;
 
 typedef struct lfs_free {
+    lfs_block_t begin;
     lfs_block_t end;
-    lfs_block_t start;
     lfs_block_t off;
-    uint32_t *lookahead;
+    uint32_t *buffer;
 } lfs_free_t;
 
 // The littlefs type
@@ -237,12 +253,13 @@ typedef struct lfs {
 
     lfs_block_t root[2];
     lfs_file_t *files;
-    bool deorphaned;
+    lfs_dir_t *dirs;
 
     lfs_cache_t rcache;
     lfs_cache_t pcache;
 
     lfs_free_t free;
+    bool deorphaned;
 } lfs_t;
 
 
@@ -347,6 +364,11 @@ lfs_ssize_t lfs_file_write(lfs_t *lfs, lfs_file_t *file,
 lfs_soff_t lfs_file_seek(lfs_t *lfs, lfs_file_t *file,
         lfs_soff_t off, int whence);
 
+// Truncates the size of the file to the specified size
+//
+// Returns a negative error code on failure.
+int lfs_file_truncate(lfs_t *lfs, lfs_file_t *file, lfs_off_t size);
+
 // Return the position of the file
 //
 // Equivalent to lfs_file_seek(lfs, file, 0, LFS_SEEK_CUR)

lfs_util.c

@@ -1,8 +1,19 @@
 /*
  * lfs util functions
  *
- * Copyright (c) 2017 Christopher Haster
- * Distributed under the Apache 2.0 license
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 #include "lfs_util.h"
 

lfs_util.h

@@ -1,8 +1,19 @@
 /*
  * lfs utility functions
  *
- * Copyright (c) 2017 Christopher Haster
- * Distributed under the Apache 2.0 license
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 #ifndef LFS_UTIL_H
 #define LFS_UTIL_H
@@ -12,7 +23,8 @@
 #include <stdio.h>
 
 
-// Builtin functions
+// Builtin functions, these may be replaced by more
+// efficient implementations in the system
 static inline uint32_t lfs_max(uint32_t a, uint32_t b) {
     return (a > b) ? a : b;
 }
@@ -29,14 +41,37 @@ static inline uint32_t lfs_npw2(uint32_t a) {
     return 32 - __builtin_clz(a-1);
 }
 
+static inline uint32_t lfs_popc(uint32_t a) {
+    return __builtin_popcount(a);
+}
+
 static inline int lfs_scmp(uint32_t a, uint32_t b) {
     return (int)(unsigned)(a - b);
 }
 
+static inline uint32_t lfs_fromle32(uint32_t a) {
+#if defined(__BYTE_ORDER__) && __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+    return a;
+#elif defined(__BYTE_ORDER__) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+    return __builtin_bswap32(a);
+#else
+    return (((uint8_t*)&a)[0] <<  0) |
+           (((uint8_t*)&a)[1] <<  8) |
+           (((uint8_t*)&a)[2] << 16) |
+           (((uint8_t*)&a)[3] << 24);
+#endif
+}
+
+static inline uint32_t lfs_tole32(uint32_t a) {
+    return lfs_fromle32(a);
+}
+
+// CRC-32 with polynomial = 0x04c11db7
 void lfs_crc(uint32_t *crc, const void *buffer, size_t size);
 
 
-// Logging functions
+// Logging functions, these may be replaced by system-specific
+// logging functions
 #define LFS_DEBUG(fmt, ...) printf("lfs debug: " fmt "\n", __VA_ARGS__)
 #define LFS_WARN(fmt, ...)  printf("lfs warn: " fmt "\n", __VA_ARGS__)
 #define LFS_ERROR(fmt, ...) printf("lfs error: " fmt "\n", __VA_ARGS__)

tests/template.fmt

@@ -27,8 +27,8 @@ void test_assert(const char *file, unsigned line,
     }}
 
     if (v != e) {{
-        printf("\033[31m%s:%u: assert %s failed, expected %jd\033[0m\n",
-                file, line, s, e);
+        fprintf(stderr, "\033[31m%s:%u: assert %s failed with %jd, "
+                "expected %jd\033[0m\n", file, line, s, v, e);
         exit(-2);
     }}
 }}

tests/test_alloc.sh

@@ -121,6 +121,7 @@ tests/test.py << TEST
     size = strlen("exhaustion");
     memcpy(buffer, "exhaustion", size);
     lfs_file_write(&lfs, &file[0], buffer, size) => size;
+    lfs_file_sync(&lfs, &file[0]) => 0;
 
     size = strlen("blahblahblahblah");
     memcpy(buffer, "blahblahblahblah", size);
@@ -142,6 +143,7 @@ tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
     lfs_file_open(&lfs, &file[0], "exhaustion", LFS_O_RDONLY);
     size = strlen("exhaustion");
+    lfs_file_size(&lfs, &file[0]) => size;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "exhaustion", size) => 0;
     lfs_file_close(&lfs, &file[0]) => 0;
@@ -166,6 +168,7 @@ tests/test.py << TEST
     size = strlen("exhaustion");
     memcpy(buffer, "exhaustion", size);
     lfs_file_write(&lfs, &file[0], buffer, size) => size;
+    lfs_file_sync(&lfs, &file[0]) => 0;
 
     size = strlen("blahblahblahblah");
     memcpy(buffer, "blahblahblahblah", size);
@@ -187,6 +190,7 @@ tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
     lfs_file_open(&lfs, &file[0], "exhaustion", LFS_O_RDONLY);
     size = strlen("exhaustion");
+    lfs_file_size(&lfs, &file[0]) => size;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "exhaustion", size) => 0;
     lfs_file_close(&lfs, &file[0]) => 0;
@@ -196,14 +200,14 @@ TEST
 echo "--- Dir exhaustion test ---"
 tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
-    lfs_stat(&lfs, "exhaustion", &info) => 0;
-    lfs_size_t fullsize = info.size;
     lfs_remove(&lfs, "exhaustion") => 0;
 
     lfs_file_open(&lfs, &file[0], "exhaustion", LFS_O_WRONLY | LFS_O_CREAT);
     size = strlen("blahblahblahblah");
     memcpy(buffer, "blahblahblahblah", size);
-    for (lfs_size_t i = 0; i < fullsize - 2*512; i += size) {
+    for (lfs_size_t i = 0;
+            i < (cfg.block_count-6)*(cfg.block_size-8);
+            i += size) {
         lfs_file_write(&lfs, &file[0], buffer, size) => size;
     }
     lfs_file_close(&lfs, &file[0]) => 0;
@@ -214,7 +218,11 @@ tests/test.py << TEST
     lfs_file_open(&lfs, &file[0], "exhaustion", LFS_O_WRONLY | LFS_O_APPEND);
     size = strlen("blahblahblahblah");
     memcpy(buffer, "blahblahblahblah", size);
-    lfs_file_write(&lfs, &file[0], buffer, size) => size;
+    for (lfs_size_t i = 0;
+            i < (cfg.block_size-8);
+            i += size) {
+        lfs_file_write(&lfs, &file[0], buffer, size) => size;
+    }
     lfs_file_close(&lfs, &file[0]) => 0;
 
     lfs_mkdir(&lfs, "exhaustiondir") => LFS_ERR_NOSPC;
@@ -224,14 +232,14 @@ TEST
 echo "--- Chained dir exhaustion test ---"
 tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
-    lfs_stat(&lfs, "exhaustion", &info) => 0;
-    lfs_size_t fullsize = info.size;
-
     lfs_remove(&lfs, "exhaustion") => 0;
+
     lfs_file_open(&lfs, &file[0], "exhaustion", LFS_O_WRONLY | LFS_O_CREAT);
     size = strlen("blahblahblahblah");
     memcpy(buffer, "blahblahblahblah", size);
-    for (lfs_size_t i = 0; i < fullsize - 19*512; i += size) {
+    for (lfs_size_t i = 0;
+            i < (cfg.block_count-24)*(cfg.block_size-8);
+            i += size) {
         lfs_file_write(&lfs, &file[0], buffer, size) => size;
     }
     lfs_file_close(&lfs, &file[0]) => 0;
@@ -247,7 +255,9 @@ tests/test.py << TEST
     lfs_file_open(&lfs, &file[0], "exhaustion", LFS_O_WRONLY | LFS_O_CREAT);
     size = strlen("blahblahblahblah");
     memcpy(buffer, "blahblahblahblah", size);
-    for (lfs_size_t i = 0; i < fullsize - 20*512; i += size) {
+    for (lfs_size_t i = 0;
+            i < (cfg.block_count-26)*(cfg.block_size-8);
+            i += size) {
         lfs_file_write(&lfs, &file[0], buffer, size) => size;
     }
     lfs_file_close(&lfs, &file[0]) => 0;

tests/test_corrupt.sh

@@ -82,6 +82,17 @@ do
     lfs_chktree
 done
 
+echo "--- Block persistance ---"
+for i in {0..33}
+do 
+    rm -rf blocks
+    mkdir blocks
+    lfs_mktree
+    chmod a-w blocks/$(printf '%x' $i)
+    lfs_mktree
+    lfs_chktree
+done
+
 echo "--- Big region corruption ---"
 rm -rf blocks
 mkdir blocks

tests/test_dirs.sh

@@ -56,7 +56,7 @@ TEST
 echo "--- Directory failures ---"
 tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
-    lfs_mkdir(&lfs, "potato") => LFS_ERR_EXISTS;
+    lfs_mkdir(&lfs, "potato") => LFS_ERR_EXIST;
     lfs_dir_open(&lfs, &dir[0], "tomato") => LFS_ERR_NOENT;
     lfs_dir_open(&lfs, &dir[0], "burito") => LFS_ERR_NOTDIR;
     lfs_file_open(&lfs, &file[0], "tomato", LFS_O_RDONLY) => LFS_ERR_NOENT;
@@ -124,10 +124,9 @@ tests/test.py << TEST
 TEST
 
 echo "--- Directory remove ---"
-# TESTING HERE
 tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
-    lfs_remove(&lfs, "potato") => LFS_ERR_INVAL;
+    lfs_remove(&lfs, "potato") => LFS_ERR_NOTEMPTY;
     lfs_remove(&lfs, "potato/sweet") => 0;
     lfs_remove(&lfs, "potato/baked") => 0;
     lfs_remove(&lfs, "potato/fried") => 0;
@@ -256,7 +255,7 @@ tests/test.py << TEST
     lfs_rename(&lfs, "warmpotato/baked", "coldpotato/baked") => 0;
     lfs_rename(&lfs, "warmpotato/sweet", "coldpotato/sweet") => 0;
     lfs_rename(&lfs, "warmpotato/fried", "coldpotato/fried") => 0;
-    lfs_remove(&lfs, "coldpotato") => LFS_ERR_INVAL;
+    lfs_remove(&lfs, "coldpotato") => LFS_ERR_NOTEMPTY;
     lfs_remove(&lfs, "warmpotato") => 0;
     lfs_unmount(&lfs) => 0;
 TEST
@@ -283,5 +282,78 @@ tests/test.py << TEST
     lfs_unmount(&lfs) => 0;
 TEST
 
+echo "--- Recursive remove ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_remove(&lfs, "coldpotato") => LFS_ERR_NOTEMPTY;
+
+    lfs_dir_open(&lfs, &dir[0], "coldpotato") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+
+    while (true) {
+        int err = lfs_dir_read(&lfs, &dir[0], &info);
+        err >= 0 => 1;
+        if (err == 0) {
+            break;
+        }
+
+        strcpy((char*)buffer, "coldpotato/");
+        strcat((char*)buffer, info.name);
+        lfs_remove(&lfs, (char*)buffer) => 0;
+    }
+
+    lfs_remove(&lfs, "coldpotato") => 0;
+TEST
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "/") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    info.type => LFS_TYPE_DIR;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    info.type => LFS_TYPE_DIR;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "burito") => 0;
+    info.type => LFS_TYPE_REG;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "cactus") => 0;
+    info.type => LFS_TYPE_DIR;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Multi-block remove ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_remove(&lfs, "cactus") => LFS_ERR_NOTEMPTY;
+
+    for (int i = 0; i < $LARGESIZE; i++) {
+        sprintf((char*)buffer, "cactus/test%d", i);
+        lfs_remove(&lfs, (char*)buffer) => 0;
+    }
+
+    lfs_remove(&lfs, "cactus") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "/") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    info.type => LFS_TYPE_DIR;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    info.type => LFS_TYPE_DIR;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "burito") => 0;
+    info.type => LFS_TYPE_REG;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
 echo "--- Results ---"
 tests/stats.py

tests/test_files.sh

@@ -34,7 +34,8 @@ tests/test.py << TEST
     lfs_size_t chunk = 31;
     srand(0);
     lfs_mount(&lfs, &cfg) => 0;
-    lfs_file_open(&lfs, &file[0], "$2", LFS_O_WRONLY | LFS_O_CREAT) => 0;
+    lfs_file_open(&lfs, &file[0], "$2",
+        ${3:-LFS_O_WRONLY | LFS_O_CREAT | LFS_O_TRUNC}) => 0;
     for (lfs_size_t i = 0; i < size; i += chunk) {
         chunk = (chunk < size - i) ? chunk : size - i;
         for (lfs_size_t b = 0; b < chunk; b++) {
@@ -53,7 +54,10 @@ tests/test.py << TEST
     lfs_size_t chunk = 29;
     srand(0);
     lfs_mount(&lfs, &cfg) => 0;
-    lfs_file_open(&lfs, &file[0], "$2", LFS_O_RDONLY) => 0;
+    lfs_stat(&lfs, "$2", &info) => 0;
+    info.type => LFS_TYPE_REG;
+    info.size => size;
+    lfs_file_open(&lfs, &file[0], "$2", ${3:-LFS_O_RDONLY}) => 0;
     for (lfs_size_t i = 0; i < size; i += chunk) {
         chunk = (chunk < size - i) ? chunk : size - i;
         lfs_file_read(&lfs, &file[0], buffer, chunk) => chunk;
@@ -78,10 +82,27 @@ echo "--- Large file test ---"
 w_test $LARGESIZE largeavacado
 r_test $LARGESIZE largeavacado
 
+echo "--- Zero file test ---"
+w_test 0 noavacado
+r_test 0 noavacado
+
+echo "--- Truncate small test ---"
+w_test $SMALLSIZE mediumavacado
+r_test $SMALLSIZE mediumavacado
+w_test $MEDIUMSIZE mediumavacado
+r_test $MEDIUMSIZE mediumavacado
+
+echo "--- Truncate zero test ---"
+w_test $SMALLSIZE noavacado
+r_test $SMALLSIZE noavacado
+w_test 0 noavacado
+r_test 0 noavacado
+
 echo "--- Non-overlap check ---"
 r_test $SMALLSIZE smallavacado
 r_test $MEDIUMSIZE mediumavacado
 r_test $LARGESIZE largeavacado
+r_test 0 noavacado
 
 echo "--- Dir check ---"
 tests/test.py << TEST
@@ -105,6 +126,10 @@ tests/test.py << TEST
     strcmp(info.name, "largeavacado") => 0;
     info.type => LFS_TYPE_REG;
     info.size => $LARGESIZE;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "noavacado") => 0;
+    info.type => LFS_TYPE_REG;
+    info.size => 0;
     lfs_dir_read(&lfs, &dir[0], &info) => 0;
     lfs_dir_close(&lfs, &dir[0]) => 0;
     lfs_unmount(&lfs) => 0;

tests/test_move.sh

@@ -0,0 +1,236 @@
+#!/bin/bash
+set -eu
+
+echo "=== Move tests ==="
+rm -rf blocks
+tests/test.py << TEST
+    lfs_format(&lfs, &cfg) => 0;
+
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_mkdir(&lfs, "a") => 0;
+    lfs_mkdir(&lfs, "b") => 0;
+    lfs_mkdir(&lfs, "c") => 0;
+    lfs_mkdir(&lfs, "d") => 0;
+
+    lfs_mkdir(&lfs, "a/hi") => 0;
+    lfs_mkdir(&lfs, "a/hi/hola") => 0;
+    lfs_mkdir(&lfs, "a/hi/bonjour") => 0;
+    lfs_mkdir(&lfs, "a/hi/ohayo") => 0;
+
+    lfs_file_open(&lfs, &file[0], "a/hello", LFS_O_CREAT | LFS_O_WRONLY) => 0;
+    lfs_file_write(&lfs, &file[0], "hola\n", 5) => 5;
+    lfs_file_write(&lfs, &file[0], "bonjour\n", 8) => 8;
+    lfs_file_write(&lfs, &file[0], "ohayo\n", 6) => 6;
+    lfs_file_close(&lfs, &file[0]) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move file ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_rename(&lfs, "a/hello", "b/hello") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "a") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hi") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_dir_open(&lfs, &dir[0], "b") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hello") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move file corrupt source ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_rename(&lfs, "b/hello", "c/hello") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+rm -v blocks/7
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "b") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_dir_open(&lfs, &dir[0], "c") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hello") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move file corrupt source and dest ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_rename(&lfs, "c/hello", "d/hello") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+rm -v blocks/8
+rm -v blocks/a
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "c") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hello") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_dir_open(&lfs, &dir[0], "d") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move dir ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_rename(&lfs, "a/hi", "b/hi") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "a") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_dir_open(&lfs, &dir[0], "b") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hi") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move dir corrupt source ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_rename(&lfs, "b/hi", "c/hi") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+rm -v blocks/7
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "b") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_dir_open(&lfs, &dir[0], "c") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hello") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hi") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move dir corrupt source and dest ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_rename(&lfs, "c/hi", "d/hi") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+rm -v blocks/9
+rm -v blocks/a
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_dir_open(&lfs, &dir[0], "c") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hello") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hi") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+    lfs_dir_open(&lfs, &dir[0], "d") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Move check ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+
+    lfs_dir_open(&lfs, &dir[0], "a/hi") => LFS_ERR_NOENT;
+    lfs_dir_open(&lfs, &dir[0], "b/hi") => LFS_ERR_NOENT;
+    lfs_dir_open(&lfs, &dir[0], "d/hi") => LFS_ERR_NOENT;
+
+    lfs_dir_open(&lfs, &dir[0], "c/hi") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, ".") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "..") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "hola") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "bonjour") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 1;
+    strcmp(info.name, "ohayo") => 0;
+    lfs_dir_read(&lfs, &dir[0], &info) => 0;
+    lfs_dir_close(&lfs, &dir[0]) => 0;
+
+    lfs_dir_open(&lfs, &dir[0], "a/hello") => LFS_ERR_NOENT;
+    lfs_dir_open(&lfs, &dir[0], "b/hello") => LFS_ERR_NOENT;
+    lfs_dir_open(&lfs, &dir[0], "d/hello") => LFS_ERR_NOENT;
+
+    lfs_file_open(&lfs, &file[0], "c/hello", LFS_O_RDONLY) => 0;
+    lfs_file_read(&lfs, &file[0], buffer, 5) => 5;
+    memcmp(buffer, "hola\n", 5) => 0;
+    lfs_file_read(&lfs, &file[0], buffer, 8) => 8;
+    memcmp(buffer, "bonjour\n", 8) => 0;
+    lfs_file_read(&lfs, &file[0], buffer, 6) => 6;
+    memcmp(buffer, "ohayo\n", 6) => 0;
+    lfs_file_close(&lfs, &file[0]) => 0;
+
+    lfs_unmount(&lfs) => 0;
+TEST
+
+
+echo "--- Results ---"
+tests/stats.py

tests/test_paths.sh

@@ -31,6 +31,10 @@ tests/test.py << TEST
     strcmp(info.name, "hottea") => 0;
     lfs_stat(&lfs, "/tea/hottea", &info) => 0;
     strcmp(info.name, "hottea") => 0;
+
+    lfs_mkdir(&lfs, "/milk1") => 0;
+    lfs_stat(&lfs, "/milk1", &info) => 0;
+    strcmp(info.name, "milk1") => 0;
     lfs_unmount(&lfs) => 0;
 TEST
 
@@ -43,6 +47,10 @@ tests/test.py << TEST
     strcmp(info.name, "hottea") => 0;
     lfs_stat(&lfs, "///tea///hottea", &info) => 0;
     strcmp(info.name, "hottea") => 0;
+
+    lfs_mkdir(&lfs, "///milk2") => 0;
+    lfs_stat(&lfs, "///milk2", &info) => 0;
+    strcmp(info.name, "milk2") => 0;
     lfs_unmount(&lfs) => 0;
 TEST
 
@@ -57,6 +65,10 @@ tests/test.py << TEST
     strcmp(info.name, "hottea") => 0;
     lfs_stat(&lfs, "/./tea/./hottea", &info) => 0;
     strcmp(info.name, "hottea") => 0;
+
+    lfs_mkdir(&lfs, "/./milk3") => 0;
+    lfs_stat(&lfs, "/./milk3", &info) => 0;
+    strcmp(info.name, "milk3") => 0;
     lfs_unmount(&lfs) => 0;
 TEST
 
@@ -71,6 +83,10 @@ tests/test.py << TEST
     strcmp(info.name, "hottea") => 0;
     lfs_stat(&lfs, "coffee/../soda/../tea/hottea", &info) => 0;
     strcmp(info.name, "hottea") => 0;
+
+    lfs_mkdir(&lfs, "coffee/../milk4") => 0;
+    lfs_stat(&lfs, "coffee/../milk4", &info) => 0;
+    strcmp(info.name, "milk4") => 0;
     lfs_unmount(&lfs) => 0;
 TEST
 
@@ -79,6 +95,27 @@ tests/test.py << TEST
     lfs_mount(&lfs, &cfg) => 0;
     lfs_stat(&lfs, "coffee/../../../../../../tea/hottea", &info) => 0;
     strcmp(info.name, "hottea") => 0;
+
+    lfs_mkdir(&lfs, "coffee/../../../../../../milk5") => 0;
+    lfs_stat(&lfs, "coffee/../../../../../../milk5", &info) => 0;
+    strcmp(info.name, "milk5") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Root tests ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_stat(&lfs, "/", &info) => 0;
+    info.type => LFS_TYPE_DIR;
+    strcmp(info.name, "/") => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Sketchy path tests ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_mkdir(&lfs, "dirt/ground") => LFS_ERR_NOENT;
+    lfs_mkdir(&lfs, "dirt/ground/earth") => LFS_ERR_NOENT;
     lfs_unmount(&lfs) => 0;
 TEST
 

tests/test_seek.sh

@@ -133,15 +133,23 @@ tests/test.py << TEST
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => size;
+    lfs_file_seek(&lfs, &file[0], 0, LFS_SEEK_CUR) => size;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_CUR) => pos+size;
+    lfs_file_seek(&lfs, &file[0], size, LFS_SEEK_CUR) => 3*size;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) => pos+size;
+    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
+    lfs_file_read(&lfs, &file[0], buffer, size) => size;
+    memcmp(buffer, "kittycatcat", size) => 0;
+
+    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_CUR) => pos;
+    lfs_file_read(&lfs, &file[0], buffer, size) => size;
+    memcmp(buffer, "kittycatcat", size) => 0;
+
+    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) >= 0 => 1;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
@@ -174,15 +182,23 @@ tests/test.py << TEST
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => size;
+    lfs_file_seek(&lfs, &file[0], 0, LFS_SEEK_CUR) => size;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_CUR) => pos+size;
+    lfs_file_seek(&lfs, &file[0], size, LFS_SEEK_CUR) => 3*size;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) => pos+size;
+    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
+    lfs_file_read(&lfs, &file[0], buffer, size) => size;
+    memcmp(buffer, "kittycatcat", size) => 0;
+
+    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_CUR) => pos;
+    lfs_file_read(&lfs, &file[0], buffer, size) => size;
+    memcmp(buffer, "kittycatcat", size) => 0;
+
+    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) >= 0 => 1;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
@@ -211,7 +227,7 @@ tests/test.py << TEST
     lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
     lfs_file_write(&lfs, &file[0], buffer, size) => size;
 
-    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos+size;
+    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "doggodogdog", size) => 0;
 
@@ -219,11 +235,11 @@ tests/test.py << TEST
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => size;
+    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "doggodogdog", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) => pos+size;
+    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) >= 0 => 1;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
@@ -254,7 +270,7 @@ tests/test.py << TEST
     lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
     lfs_file_write(&lfs, &file[0], buffer, size) => size;
 
-    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos+size;
+    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "doggodogdog", size) => 0;
 
@@ -262,11 +278,11 @@ tests/test.py << TEST
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => size;
+    lfs_file_seek(&lfs, &file[0], pos, LFS_SEEK_SET) => pos;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "doggodogdog", size) => 0;
 
-    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) => pos+size;
+    lfs_file_seek(&lfs, &file[0], -size, LFS_SEEK_END) >= 0 => 1;
     lfs_file_read(&lfs, &file[0], buffer, size) => size;
     memcmp(buffer, "kittycatcat", size) => 0;
 
@@ -277,5 +293,69 @@ tests/test.py << TEST
     lfs_unmount(&lfs) => 0;
 TEST
 
+echo "--- Boundary seek and write ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_file_open(&lfs, &file[0], "hello/kitty42", LFS_O_RDWR) => 0;
+
+    size = strlen("hedgehoghog");
+    const lfs_soff_t offsets[] = {512, 1020, 513, 1021, 511, 1019};
+
+    for (int i = 0; i < sizeof(offsets) / sizeof(offsets[0]); i++) {
+        lfs_soff_t off = offsets[i];
+        memcpy(buffer, "hedgehoghog", size);
+        lfs_file_seek(&lfs, &file[0], off, LFS_SEEK_SET) => off;
+        lfs_file_write(&lfs, &file[0], buffer, size) => size;
+        lfs_file_seek(&lfs, &file[0], off, LFS_SEEK_SET) => off;
+        lfs_file_read(&lfs, &file[0], buffer, size) => size;
+        memcmp(buffer, "hedgehoghog", size) => 0;
+
+        lfs_file_seek(&lfs, &file[0], 0, LFS_SEEK_SET) => 0;
+        lfs_file_read(&lfs, &file[0], buffer, size) => size;
+        memcmp(buffer, "kittycatcat", size) => 0;
+
+        lfs_file_sync(&lfs, &file[0]) => 0;
+    }
+
+    lfs_file_close(&lfs, &file[0]) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
+echo "--- Out-of-bounds seek ---"
+tests/test.py << TEST
+    lfs_mount(&lfs, &cfg) => 0;
+    lfs_file_open(&lfs, &file[0], "hello/kitty42", LFS_O_RDWR) => 0;
+
+    size = strlen("kittycatcat");
+    lfs_file_size(&lfs, &file[0]) => $LARGESIZE*size;
+    lfs_file_seek(&lfs, &file[0], ($LARGESIZE+$SMALLSIZE)*size,
+            LFS_SEEK_SET) => ($LARGESIZE+$SMALLSIZE)*size;
+    lfs_file_read(&lfs, &file[0], buffer, size) => 0;
+
+    memcpy(buffer, "porcupineee", size);
+    lfs_file_write(&lfs, &file[0], buffer, size) => size;
+
+    lfs_file_seek(&lfs, &file[0], ($LARGESIZE+$SMALLSIZE)*size,
+            LFS_SEEK_SET) => ($LARGESIZE+$SMALLSIZE)*size;
+    lfs_file_read(&lfs, &file[0], buffer, size) => size;
+    memcmp(buffer, "porcupineee", size) => 0;
+
+    lfs_file_seek(&lfs, &file[0], $LARGESIZE*size,
+            LFS_SEEK_SET) => $LARGESIZE*size;
+    lfs_file_read(&lfs, &file[0], buffer, size) => size;
+    memcmp(buffer, "\0\0\0\0\0\0\0\0\0\0\0", size) => 0;
+
+    lfs_file_seek(&lfs, &file[0], -(($LARGESIZE+$SMALLSIZE)*size),
+            LFS_SEEK_CUR) => LFS_ERR_INVAL;
+    lfs_file_tell(&lfs, &file[0]) => ($LARGESIZE+1)*size;
+
+    lfs_file_seek(&lfs, &file[0], -(($LARGESIZE+2*$SMALLSIZE)*size),
+            LFS_SEEK_END) => LFS_ERR_INVAL;
+    lfs_file_tell(&lfs, &file[0]) => ($LARGESIZE+1)*size;
+
+    lfs_file_close(&lfs, &file[0]) => 0;
+    lfs_unmount(&lfs) => 0;
+TEST
+
 echo "--- Results ---"
 tests/stats.py

tests/test_truncate.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+set -eu
+
+SMALLSIZE=32
+MEDIUMSIZE=2048
+LARGESIZE=8192
+
+echo "=== Truncate tests ==="
+rm -rf blocks
+tests/test.py << TEST
+    lfs_format(&lfs, &cfg) => 0;
+TEST
+
+truncate_test() {
+STARTSIZES="$1"
+HOTSIZES="$2"
+COLDSIZES="$3"
+tests/test.py << TEST
+    static const lfs_off_t startsizes[] = {$STARTSIZES};
+    static const lfs_off_t hotsizes[]   = {$HOTSIZES};
+
+    lfs_mount(&lfs, &cfg) => 0;
+
+    for (int i = 0; i < sizeof(startsizes)/sizeof(startsizes[0]); i++) {
+        sprintf((char*)buffer, "hairyhead%d", i);
+        lfs_file_open(&lfs, &file[0], (const char*)buffer,
+                LFS_O_WRONLY | LFS_O_CREAT | LFS_O_TRUNC) => 0;
+
+        strcpy((char*)buffer, "hair");
+        size = strlen((char*)buffer);
+        for (int j = 0; j < startsizes[i]; j += size) {
+            lfs_file_write(&lfs, &file[0], buffer, size) => size;
+        }
+        lfs_file_size(&lfs, &file[0]) => startsizes[i];
+
+        lfs_file_truncate(&lfs, &file[0], hotsizes[i]) => 0;
+        lfs_file_size(&lfs, &file[0]) => hotsizes[i];
+
+        lfs_file_close(&lfs, &file[0]) => 0;
+    }
+
+    lfs_unmount(&lfs) => 0;
+TEST
+tests/test.py << TEST
+    static const lfs_off_t startsizes[] = {$STARTSIZES};
+    static const lfs_off_t hotsizes[]   = {$HOTSIZES};
+    static const lfs_off_t coldsizes[]  = {$COLDSIZES};
+
+    lfs_mount(&lfs, &cfg) => 0;
+
+    for (int i = 0; i < sizeof(startsizes)/sizeof(startsizes[0]); i++) {
+        sprintf((char*)buffer, "hairyhead%d", i);
+        lfs_file_open(&lfs, &file[0], (const char*)buffer, LFS_O_RDWR) => 0;
+        lfs_file_size(&lfs, &file[0]) => hotsizes[i];
+
+        size = strlen("hair");
+        int j = 0;
+        for (; j < startsizes[i] && j < hotsizes[i]; j += size) {
+            lfs_file_read(&lfs, &file[0], buffer, size) => size;
+            memcmp(buffer, "hair", size) => 0;
+        }
+
+        for (; j < hotsizes[i]; j += size) {
+            lfs_file_read(&lfs, &file[0], buffer, size) => size;
+            memcmp(buffer, "\0\0\0\0", size) => 0;
+        }
+
+        lfs_file_truncate(&lfs, &file[0], coldsizes[i]) => 0;
+        lfs_file_size(&lfs, &file[0]) => coldsizes[i];
+
+        lfs_file_close(&lfs, &file[0]) => 0;
+    }
+
+    lfs_unmount(&lfs) => 0;
+TEST
+tests/test.py << TEST
+    static const lfs_off_t startsizes[] = {$STARTSIZES};
+    static const lfs_off_t hotsizes[]   = {$HOTSIZES};
+    static const lfs_off_t coldsizes[]  = {$COLDSIZES};
+
+    lfs_mount(&lfs, &cfg) => 0;
+
+    for (int i = 0; i < sizeof(startsizes)/sizeof(startsizes[0]); i++) {
+        sprintf((char*)buffer, "hairyhead%d", i);
+        lfs_file_open(&lfs, &file[0], (const char*)buffer, LFS_O_RDONLY) => 0;
+        lfs_file_size(&lfs, &file[0]) => coldsizes[i];
+
+        size = strlen("hair");
+        int j = 0;
+        for (; j < startsizes[i] && j < hotsizes[i] && j < coldsizes[i];
+                j += size) {
+            lfs_file_read(&lfs, &file[0], buffer, size) => size;
+            memcmp(buffer, "hair", size) => 0;
+        }
+
+        for (; j < coldsizes[i]; j += size) {
+            lfs_file_read(&lfs, &file[0], buffer, size) => size;
+            memcmp(buffer, "\0\0\0\0", size) => 0;
+        }
+
+        lfs_file_close(&lfs, &file[0]) => 0;
+    }
+
+    lfs_unmount(&lfs) => 0;
+TEST
+}
+
+echo "--- Cold shrinking truncate ---"
+truncate_test \
+    "2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE" \
+    "2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE" \
+    "           0,   $SMALLSIZE,  $MEDIUMSIZE,   $LARGESIZE, 2*$LARGESIZE"
+
+echo "--- Cold expanding truncate ---"
+truncate_test \
+    "           0,   $SMALLSIZE,  $MEDIUMSIZE,   $LARGESIZE, 2*$LARGESIZE" \
+    "           0,   $SMALLSIZE,  $MEDIUMSIZE,   $LARGESIZE, 2*$LARGESIZE" \
+    "2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE"
+
+echo "--- Warm shrinking truncate ---"
+truncate_test \
+    "2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE" \
+    "           0,   $SMALLSIZE,  $MEDIUMSIZE,   $LARGESIZE, 2*$LARGESIZE" \
+    "           0,            0,            0,            0,            0"
+
+echo "--- Warm expanding truncate ---"
+truncate_test \
+    "           0,   $SMALLSIZE,  $MEDIUMSIZE,   $LARGESIZE, 2*$LARGESIZE" \
+    "2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE" \
+    "2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE, 2*$LARGESIZE"
+
+echo "--- Results ---"
+tests/stats.py