document DKIOCFREE

*** 15,27 ****
  .\" 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.
  .\"
! .Dd October 23, 2017
  .Dt DKIO 7I
  .Os
  .Sh NAME
  .Nm dkio
  .Nd disk control operations
--- 15,27 ----
  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  .\"
  .\"
  .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
  .\" Copyright 2016 Nexenta Systems, Inc.
! .\" Copyright 2020 Joyent, Inc.
  .\"
! .Dd February 14, 2020
  .Dt DKIO 7I
  .Os
  .Sh NAME
  .Nm dkio
  .Nd disk control operations
*** 691,701 ****
--- 691,789 ----
                  } 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