usr.sbin/zonectl/zonectl.8

   1 .\"
   2 .\" Copyright (c) 2015 Spectra Logic Corporation
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions, and the following disclaimer,
  10 .\"    without modification.
  11 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  13 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  14 .\"    including a substantially similar Disclaimer requirement for further
  15 .\"    binary redistribution.
  16 .\"
  17 .\" NO WARRANTY
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGES.
  29 .\"
  30 .\" Authors: Ken Merry           (Spectra Logic Corporation)
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd May 18, 2016
  35 .Dt ZONECTL 8
  36 .Os
  37 .Sh NAME
  38 .Nm zonectl
  39 .Nd Shingled Magnetic Recording Zone Control utility
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Aq Fl d Ar dev
  43 .Aq Fl c Ar cmd
  44 .Op Fl a
  45 .Op Fl l Ar LBA
  46 .Op Fl o Ar rep_opts
  47 .Op Fl P Ar print_opts
  48 .Sh DESCRIPTION
  49 Manage
  50 .Tn SCSI
  51 and
  52 .Tn ATA
  53 Zoned Block devices.
  54 This allows managing devices that conform to the
  55 .Tn SCSI
  56 Zoned Block Commands (ZBC) and
  57 .Tn ATA
  58 Zoned ATA Command Set (ZAC)
  59 specifications.
  60 Devices using these command sets are usually hard drives using Shingled
  61 Magnetic Recording (SMR).
  62 There are three types of SMR drives:
  63 .Bl -tag -width 13n
  64 .It Drive Managed
  65 Drive Managed drives look and act just like a standard random access block
  66 device, but underneath, the drive reads and writes the bulk of its capacity
  67 using SMR zones.
  68 Sequential writes will yield better performance, but writing sequentially
  69 is not required.
  70 .It Host Aware
  71 Host Aware drives expose the underlying zone layout via
  72 .Tn SCSI
  73 or
  74 .Tn ATA
  75 commands and allow the host to manage the zone conditions.
  76 The host is not required to manage the zones on the drive, though.
  77 Sequential writes will yield better performance in Sequential Write
  78 Preferred zones, but the host can write randomly in those zones.
  79 .It Host Managed
  80 Host Managed drives expose the underlying zone layout via
  81 .Tn SCSI
  82 or
  83 .Tn ATA
  84 commands.
  85 The host is required to access the zones according to the rules described
  86 by the zone layout.
  87 Any commands that violate the rules will be returned with an error.
  88 .El
  89 .Pp
  90 SMR drives are divided into zones (typically in the range of 256MB each)
  91 that fall into three general categories:
  92 .Bl -tag -width 20n
  93 .It Conventional
  94 These are also known as Non Write Pointer zones.
  95 These zones can be randomly written without an unexpected performance penalty.
  96 .It Sequential Preferred
  97 These zones should be written sequentially starting at the write pointer
  98 for the zone.
  99 They may be written randomly.
 100 Writes that do not conform to the zone layout may be significantly slower
 101 than expected.
 102 .It Sequential Required
 103 These zones must be written sequentially.
 104 If they are not written sequentially, starting at the write pointer, the
 105 command will fail.
 106 .El
 107 .Pp
 108 .Bl -tag -width 12n
 109 .It Fl c Ar cmd
 110 Specify the zone subcommand:
 111 .Bl -tag -width 6n
 112 .It params
 113 Display device parameters, including the type of device (Drive Managed,
 114 Host Aware, Host Managed, Not Zoned), the zone commands supported, and
 115 how many open zones it supports.
 116 .It rz
 117 Issue the Report Zones command.
 118 All zones are returned by default.
 119 Specify report options with
 120 .Fl o
 121 and printing options with
 122 .Fl P .
 123 Specify the starting LBA with
 124 .Fl l .
 125 Note that
 126 .Dq reportzones
 127 is also accepted as a command argument.
 128 .It open
 129 Explicitly open the zone specified by the starting LBA.
 130 .It close
 131 Close the zone specified by starting LBA.
 132 .It finish
 133 Finish the zone specified by the starting LBA.
 134 .It rwp
 135 Reset the write pointer for the zone specified by the starting LBA.
 136 .El
 137 .It Fl a
 138 For the Open, Close, Finish, and Reset Write Pointer operations, apply the
 139 operation to all zones on the drive.
 140 .It Fl l Ar lba
 141 Specify the starting LBA.
 142 For the Report Zones command, this tells the drive to report starting with
 143 the zone that starts at the given LBA.
 144 For the other commands, this allows the user to identify the zone requested
 145 by its starting LBA.
 146 The LBA may be specified in decimal, hexadecimal or octal notation.
 147 .It Fl o Ar rep_opt
 148 For the Report Zones command, specify a subset of zones to report.
 149 .Bl -tag -width 8n
 150 .It all
 151 Report all zones.
 152 This is the default.
 153 .It emtpy
 154 Report only empty zones.
 155 .It imp_open
 156 Report zones that are implicitly open.
 157 This means that the host has sent a write to the zone without explicitly
 158 opening the zone.
 159 .It exp_open
 160 Report zones that are explicitly open.
 161 .It closed
 162 Report zones that have been closed by the host.
 163 .It full
 164 Report zones that are full.
 165 .It ro
 166 Report zones that are in the read only state.
 167 Note that
 168 .Dq readonly
 169 is also accepted as an argument.
 170 .It offline
 171 Report zones that are in the offline state.
 172 .It reset
 173 Report zones that the device recommends should have their write pointers reset.
 174 .It nonseq
 175 Report zones that have the Non Sequential Resources Active flag set.
 176 These are zones that are Sequential Write Preferred, but have been written
 177 non-sequentially.
 178 .It nonwp
 179 Report Non Write Pointer zones, also known as Conventional zones.
 180 .El
 181 .It Fl P Ar print_opt
 182 Specify a printing option for Report Zones:
 183 .Bl -tag -width 7n
 184 .It normal
 185 Normal Report Zones output.
 186 This is the default.
 187 The summary and column headings are printed, fields are separated by spaces
 188 and the fields themselves may contain spaces.
 189 .It summary
 190 Just print the summary:  the number of zones, the maximum LBA (LBA of the
 191 last logical block on the drive), and the value of the
 192 .Dq same
 193 field.
 194 The
 195 .Dq same
 196 field describes whether the zones on the drive are all identical, all
 197 different, or whether they are the same except for the last zone, etc.
 198 .It script
 199 Print the zones in a script friendly format.
 200 The summary and column headings are omitted, the fields are separated by
 201 commas, and the fields do not contain spaces.
 202 The fields contain underscores where spaces would normally be used.
 203 .El
 204 .El
 205 .Sh EXAMPLES
 206 .Bd -literal -offset indent
 207 zonectl -d /dev/da5 -c params
 208 .Ed
 209 .Pp
 210 Display basic zoning information for disk da5.
 211 .Pp
 212 .Bd -literal -offset indent
 213 zonectl -d /dev/da5 -c rz
 214 .Ed
 215 .Pp
 216 Issue the Report Zones command to disk da5, and print out all
 217 zones on the drive in the default format.
 218 .Pp
 219 .Bd -literal -offset indent
 220 zonectl -d /dev/da5 -c rz -o reset -P script
 221 .Ed
 222 .Pp
 223 Issue the Report Zones command to disk da5, and print out all
 224 of the zones that have the Reset Write Pointer Recommended bit set to true.
 225 Print the zones in a script friendly form.
 226 .Pp
 227 .Bd -literal -offset indent
 228 zonectl -d /dev/da5 -c rwp -l 0x2c80000
 229 .Ed
 230 .Pp
 231 Issue the Reset Write Pointer command to disk da5 for the zone
 232 that starts at LBA 0x2c80000.
 233 .Pp
 234 .Bd -literal -offset indent
 235 .Sh AUTHORS
 236 .An Kenneth Merry Aq ken@FreeBSD.org