[Request]: Guest agent API call for returning freed disk blocks to macOS.

[jglogan]

Feature or enhancement request details

The virtioblk device and the hypervisor are capable of returning trimmed/discarded blocks back to the host, but at present the guest agent does not issue FITRIM for read-write filesystems, so regardless of what is removed in the guest, the host block file will only grow in size as reported by ls -ls or du -s.

The enhancement should allow freed disk blocks to be returned to macOS.

Please do not just yolo a PR for this. Let's settle on the requirements and API design here in the issue first, and from there the PR should not be too difficult.

At the very least the API should allow implementation of a container command such as (the verb is a placeholder, we can come up with something more succinct):

container reclaim-disk-blocks [mount-path...]

where if no mount paths are specified, the command initiates reclamation on all read-write mounts for the running container.

I'll paste a pseudocode implementation of the reclamation mechanism in the discussion.

Open issues:

• API name?
• Reclamation policy? One or more of (we should start simple but the policy API should follow open-closed principle):
  • One time request from caller (we could defer all other policy, except continuous, to the caller, though threshold based would require the caller to be able to monitor utilization on filesystems)
  • Periodic
  • Threshold based
  • Continuous
  • Other?
• One filesystem per request, or multiple?

Code of Conduct

• I agree to follow this project's Code of Conduct

[jglogan]

// Example implementation of mechanism for Linux
// #define FITRIM _IOWR('X', 121, struct fstrim_range)
const FITRIM uint32 = 0xc0185879

func fstrim(path):
    if not is_absolute(path):
        throw "filesystem trim requires an absolute path"

    info, err = lstat(path)
    if err != 0:
        throw "filesystem trim stat failed: {err}"

    if info.mode & MODE_SYMLINK:
        throw "mount path cannot be a symlink"

    fd, err = open(path)
    if err != 0:
        throw "cannot open mount path"

    defer:
        close(fd)

    trange = TrimRange(start: 0, len: uint64.max, minlen: 0)

    _, _, err = syscall(SYS_IOCTL, fd, FITRIM, trange)
    if err != 0:
        throw "filesystem trim failed: {err}"

[saehejkang]

API name?

discardBlocks - if we want to follow something that is based off a description from the linux man pages
trimFilesystem - it is more generic and closer to semantics in the SandboxContext

Reclamation policy?

Not 100% sure on this, but like you stated about following an "open-closed principle", it might be worthwhile to start with a one time request. At least then, adding other reclamation policies will/should be simple.

One filesystem per request, or multiple?

If we’re already thinking about deferring some of the reclamation policy to the caller, couldn’t we do the same here?