chore: Prepare release v0.5.4

CHANGELOG.md

@@ -7,13 +7,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [Unreleased]
+## [0.5.4] - 2025-09-06
 
-### Refactored
+### Fixed
 
- - Global constants fully shared among components through `sflc_constants.h`.
+ - Fixed erratic behavior and improved error handling of benchmark scripts.
+ - Fixed typos in CHANGELOG.md.
 
+### Added
 
+ - Working garbage collection of unused slices: these can now be recovered by doing a `fstrim` before a `shufflecake close` operation.
+ - Workqueue processing of READ and WRITE requests made optional by default, as this improves performance in most workloads. Queues can be re-enabled on `shufflecake open` with `--use-read-queue` and `--use-read-queue`.
+ - Added one external contributor.
+
+### Changed
+
+ - New content in README.md.
+ - Minor edits to CONTRIBUTING.md.
+ 
+ 
 ## [0.5.3] - 2025-07-05
 
 ### Fixed
@@ -37,6 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
  - Progress status during `init`.
  - Added `CONTRIBUTING.md`.
+ - Added one external contributor.
 
 ### Fixed
 
@@ -182,7 +195,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
- - Test routines available with `make install`, for now limited to low-level crypto operations.
+ - Test routines available with `make test`, for now limited to low-level crypto operations.
 
 ### Refactored
 
@@ -218,5 +231,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.0] - 2022-11-10
 
-This is the first release of `shufflecake-c`
+This is the first release of `shufflecake-c`.
 

README.md

@@ -1,5 +1,5 @@
 [![Status](resources/images/badges/badge_status_active.png)](https://codeberg.org/shufflecake/shufflecake-c) 
-[![Version](resources/images/badges/badge_version_0.5.3.png)](https://codeberg.org/shufflecake/shufflecake-c/releases/tag/v0.5.3) 
+[![Version](resources/images/badges/badge_version_0.5.4.png)](https://codeberg.org/shufflecake/shufflecake-c/releases/tag/v0.5.4) 
 [![License](resources/images/badges/badge_license_gplv2plus.png)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) 
 [![Docs researchpaper](resources/images/badges/badge_docs_researchpaper.png)](https://eprint.iacr.org/2023/1529) 
 [![Website](resources/images/badges/badge_web_shufflecakedotnet.png)](https://shufflecake.net/) 
@@ -12,7 +12,7 @@
 
 
 
-# Shufflecake - Full C Implementation - v0.5.3
+# Shufflecake - Full C Implementation - v0.5.4
 
 _Shufflecake_ is a plausible deniability (hidden storage) layer for Linux. You can consider Shufflecake a spiritual successor of tools like TrueCrypt and VeraCrypt, but vastly improved, both in terms of security and functionality. Official website: <https://www.shufflecake.net>.
 
@@ -36,6 +36,8 @@ __WARNING__: Shufflecake is a strong encryption and plausible deniability soluti
       - [Shufflecake Legacy](#legacy)
       - [Shufflecake Full](#full)
     - [Advanced Usage](#advanced)
+      - [Recovering Unused Slices](#recoverslices)
+      - [Enabling R/W Workqueues](#workqueues)
       - [Volume Corruption Mitigation](#mitigcorr)
       - [Providing Passwords Non-Interactively](#passwordnonint)
 - [Changelog](#changelog)
@@ -220,7 +222,21 @@ This is a planned, but not yet implemented future mode of Shufflecake, which ext
 
 ### Advanced Usage <a id="user-content-advanced"></a>
 
-Certain features of Shufflecake are not yet implemented, but sometimes a workaround is possible. Consider all the instructions in this sections as experimental, use them at your own risk.
+This section documents advanced use cases and features of Shufflecake.
+
+
+#### Recovering Unused Slices <a id="user-content-recoverslices"></a>
+
+Once a new slice is assigned to a Shufflecake volume, that assignment is static: that slice stays in the position map of that volume even if all its content (i.e. the files in the filesystem area mapped onto the slice) is deleted. On the long run, this can lead to a situation where there are no free available slices left for Shufflecake volume allocation, even if the filesystems of the volumes show plenty of available virtual space. In order to avoid this, Shufflecake implements slice garbage collection on `close`: all slices that only contain sectors unused by the filesystem on top are marked as free and removed from the slice mapping.
+
+Usually, filesystems do not mark unused sectors automatically. To force this, call `fstrim` inside the filesystems of the open volumes, and then `close` the underlying device. Once the device is `open`ed again, those slices will be newly available for allocation. This should be done once in a while, especially after deleting large amount of data from the volumes.
+
+
+#### Enabling R/W Workqueues <a id="user-content-workqueues"></a>
+
+According to benchmarks, workqueue processing of READ and WRITE requests decreases I/O performances for most typical workloads, at least on SSDs. Since this is a very common situation on laptops nowadays, Shufflecake disables R/W workqueues by default. However, some WRITE workloads might actually enjoy a speed-up with workqueues. Moreover, workqueues might improve performance on HDDs (although this is untested).
+
+Read and write queues can be optionally enabled on `shufflecake open` with the options `--use-read-queue` and `--use-write-queue`, respectively.
 
 
 #### Volume Corruption Mitigation <a id="user-content-mitigcorr"></a>
@@ -271,6 +287,12 @@ Both methods works with the `init` and `open` action, and we do not have current
 
 Please see the file `CHANGELOG.md` for a detailed history of changes.
 
+## [0.5.4] - 2025-09-06
+
+ - Working garbage collection of unused slices.
+ - Workqueue processing of READ and WRITE requests made optional by default.
+ - Fixed benchmark scripts.
+
 ## [0.5.3] - 2025-07-05
 
  - Fixed GCC compilation error.
@@ -290,11 +312,6 @@ Please see the file `CHANGELOG.md` for a detailed history of changes.
 ### [0.5.0] - 2024-09-01
 
  - BREAKING CHANGE: major rewrite, bugfixes, introduced Shufflecake "Lite" as a default mode of operation.
- 
-### [0.4.5] - 2024-06-03
-
- - Fixed a compile error on some versions of LTS kernels.
- - Fixed segmentation fault when opening an already opened device.
 
 
 
@@ -306,6 +323,8 @@ Bugs and other issues are tracked at <https://codeberg.org/shufflecake/shuffleca
 
 Outstanding known bugs and/or limitations:
 
+ - Opening volumes does not work on certain architectures (see issue <https://codeberg.org/shufflecake/shufflecake-c/issues/143>).
+ - Crash consistency is currently not guaranteed (see issue <https://codeberg.org/shufflecake/shufflecake-c/issues/136>).
  - Only a maximum of 15 volumes per device is supported.
  - There is (currently) no protection against multi-snapshot attacks.
 

dm-sflc/src/sflc_constants.h

@@ -33,7 +33,7 @@
 
 #define SFLC_VER_MAJOR 0
 #define SFLC_VER_MINOR 5
-#define SFLC_VER_REVISION 3
+#define SFLC_VER_REVISION 4
 #define SFLC_VER_SPECIAL ""
 
 #define STRINGIFY0(s) # s

resources/images/badges/badges.svg

@@ -9,7 +9,7 @@
    id="svg2909"
    inkscape:version="1.2.2 (b0a8486541, 2022-12-01)"
    sodipodi:docname="badges.svg"
-   inkscape:export-filename="badge_version_0.4.5.png"
+   inkscape:export-filename="badge_version_0.5.4.png"
    inkscape:export-xdpi="150"
    inkscape:export-ydpi="150"
    xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
@@ -29,10 +29,10 @@
      inkscape:document-units="mm"
      showgrid="false"
      inkscape:zoom="2.7438272"
-     inkscape:cx="235.25534"
-     inkscape:cy="227.96625"
-     inkscape:window-width="1920"
-     inkscape:window-height="1017"
+     inkscape:cx="235.98425"
+     inkscape:cy="228.69516"
+     inkscape:window-width="2560"
+     inkscape:window-height="1377"
      inkscape:window-x="0"
      inkscape:window-y="0"
      inkscape:window-maximized="1"
@@ -333,7 +333,7 @@
        height="5.2916675"
        x="61.548569"
        y="79.569435"
-       inkscape:export-filename="badge_version_0.5.3.png"
+       inkscape:export-filename="badge_version_0.5.4.png"
        inkscape:export-xdpi="96"
        inkscape:export-ydpi="96" />
     <text
@@ -364,7 +364,7 @@
          id="tspan462"
          style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-family:FreeSans;-inkscape-font-specification:'FreeSans Semi-Bold';fill:#ffffff;fill-opacity:1;stroke-width:0.183262"
          x="79.882088"
-         y="83.4077">0.5.3</tspan></text>
+         y="83.4077">0.5.4</tspan></text>
     <rect
        style="fill:#951b89;fill-opacity:1;stroke:none;stroke-width:0.245683;stroke-linecap:round;stroke-linejoin:round;stroke-dasharray:none;stroke-opacity:1"
        id="rect358"