When writing data to an SSD, the process of erasing the existing data on the target block before overwriting it introduces performance overhead. To overcome this, a discard command can be sent to the SSD’s controller, proactively erasing unused blocks and making them immediately available for write operations. As a result, the time required to write new data to the device is reduced.

To streamline the discard process, the Btrfs filesystem provides an option to enable automatic trimming of unused data on the SSD. By simply adding the “discard” option when mounting the filesystem, Btrfs takes care of automatically discarding the unused data.

Btrfs offers both synchronous and asynchronous discard options. Synchronous discard issues the discard command when the blocks are freed, and it can be enabled using the following mount options:

mount -o discard
mount -o discard=sync

On the other hand, asynchronous discard tracks the discardable blocks and periodically issues the discard command. This option is enabled by default since Btrfs version 6.2 and can be used with the following mount option:

mount -o discard=async

Additionally, the “nodiscard” option can be used to disable discard:

mount -o nodiscard

Starting with kernel version 6.1, Btrfs introduced several discard controls that can be accessed through the sysfs interface files located in /sys/fs/btrfs/<UUID>/discard/. These controls provide further fine-tuning options for discard operations, particularly when using asynchronous discard.

Available discard IOPs controls in Btrfs:

Disard IOPS controls:

These parameters help to tune the discard intensity typically when async discard is used.

  • kbps_limit (RW): Tunable limit of kilobytes per second issued as discard IO in the async discard mode.
  • iops_limit (RW): Tunable limit of number of discard IO operations to be issued in the async discard mode.
  • max_discard_size (RW): Tunable limit for size of one IO discard request.

Discard statistics:

  • discardable_bytes (RO): Shows amount of bytes that can be discarded in the async discard and nodiscard mode.
  • discardable_extents (RO): Shows number of extents to be discarded in the async discard and nodiscard mode.
  • discard_bitmap_bytes (RO): Shows amount of discarded bytes from data tracked as bitmaps.
  • discard_extent_bytes (RO): Shows amount of discarded extents from data tracked as bitmaps.
  • discard_bytes_saved (RO): Shows the amount of bytes that were reallocated without being discarded.

By leveraging these discard controls and monitoring the corresponding statistics, administrators can fine-tune the discard intensity and efficiently manage the discard process on their Btrfs filesystem.