document DKIOCFREE

@@ -15,13 +15,13 @@
 .\" information: Portions Copyright [yyyy] [name of copyright owner]
 .\"
 .\"
 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
 .\" Copyright 2016 Nexenta Systems, Inc.
-.\" Copyright (c) 2017, Joyent, Inc.
+.\" Copyright 2020 Joyent, Inc.
 .\"
-.Dd October 23, 2017
+.Dd February 14, 2020
 .Dt DKIO 7I
 .Os
 .Sh NAME
 .Nm dkio
 .Nd disk control operations

@@ -691,11 +691,99 @@
                 } while (rval != EINVAL || dr->vdr_flags &
                     (DKV_DMR_DONE | DKV_DMR_ERROR | DKV_DMR_SHORT)
         }
 }
 .Ed
+.It Dv DKIOCFREE
+.Pp
+The argument is a pointer to a
+.Vt dkioc_free_list_t
+structure (described below).
+The structure consists of a header followed by one or more
+.Vt dkioc_free_list_ext_t
+strctures (described below) that list the extents that the device should free.
+.Bd -literal -offset 2n
+typedef struct dkioc_free_list_ext_s {
+        uint64_t                dfle_start;
+        uint64_t                dfle_length;
+} dkioc_free_list_ext_t;
+
+typedef struct dkioc_free_list_s {
+        uint64_t                dfl_flags;
+        uint64_t                dfl_num_exts;
+        uint64_t                dfl_offset;
+        dkioc_free_list_ext_t   dfl_exts[1];
+} dkioc_free_list_t;
+.Ed
+.Pp
+The
+.Fa dfle_start ,
+.Fa dfle_length ,
+and
+.Fa dfl_offset
+fields are in units of bytes (not blocks).
+.Pp
+The values for
+.Fa dfl_flags
+are:
+.Bl -tag -width Dv
+.It Dv DF_WAIT_SYNC
+Wait for the device to complete freeing the space before returning.
 .El
+.Pp
+The
+.Fa dfl_num_exts
+field indicates the number of
+.Vt dkioc_free_list_ext_t
+structures follow the
+.Vt dkioc_free_list_t
+structure (including the first entry in
+.Fa dfl_exts ) .
+There must be at least one
+.Vt dkioc_free_list_ext_t
+in the
+.Xr ioctl 2
+request (i.e\&.
+.Fa dfl_num_exts
+must be \(>= 1).
+.Pp
+The
+.Fa dfl_offset
+field is added to all of the values of
+.Fa dfle_start
+when processed by the device.
+.Pp
+The
+.Fa dfl_exts
+field contains the first extent to free, immediately followed by any
+additional
+.Vt dkioc_free_list_ext_t
+structures if there are more than one extent to free.
+.Pp
+The
+.Dv DFL_SZ(num_exts)
+macro can be used to calculate the amount of memory required to hold
+.Fa num_exts
+extents.
+.It Dv DKIOC_CANFREE
+The argument is a pointer to an
+.Vt int
+that is populated by the
+.Xr ioctl 2
+request.
+Upon a successful return, if a non-zero value has been set in the
+.Vt int
+parameter, it indicates that the device supports the
+.Dv DKIOCFREE
+.Xr ioctl 2 .
+If the
+.Vt int
+parameter has been set to zero, the
+.Dv DKIOCFREE
+.Xr ioctl 2
+is not supported by the device.
+.El
 .Ss "RETURN VALUES"
 Upon successful completion, the value returned is
 .Sy 0 .
 Otherwise,
 .Sy -1