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.Dd May 18, 2016 33.Dt ZONECTL 8 34.Os 35.Sh NAME 36.Nm zonectl 37.Nd Shingled Magnetic Recording Zone Control utility 38.Sh SYNOPSIS 39.Nm 40.Aq Fl d Ar dev 41.Aq Fl c Ar cmd 42.Op Fl a 43.Op Fl l Ar LBA 44.Op Fl o Ar rep_opts 45.Op Fl P Ar print_opts 46.Sh DESCRIPTION 47Manage 48.Tn SCSI 49and 50.Tn ATA 51Zoned Block devices. 52This allows managing devices that conform to the 53.Tn SCSI 54Zoned Block Commands (ZBC) and 55.Tn ATA 56Zoned ATA Command Set (ZAC) 57specifications. 58Devices using these command sets are usually hard drives using Shingled 59Magnetic Recording (SMR). 60There are three types of SMR drives: 61.Bl -tag -width 13n 62.It Drive Managed 63Drive Managed drives look and act just like a standard random access block 64device, but underneath, the drive reads and writes the bulk of its capacity 65using SMR zones. 66Sequential writes will yield better performance, but writing sequentially 67is not required. 68.It Host Aware 69Host Aware drives expose the underlying zone layout via 70.Tn SCSI 71or 72.Tn ATA 73commands and allow the host to manage the zone conditions. 74The host is not required to manage the zones on the drive, though. 75Sequential writes will yield better performance in Sequential Write 76Preferred zones, but the host can write randomly in those zones. 77.It Host Managed 78Host Managed drives expose the underlying zone layout via 79.Tn SCSI 80or 81.Tn ATA 82commands. 83The host is required to access the zones according to the rules described 84by the zone layout. 85Any commands that violate the rules will be returned with an error. 86.El 87.Pp 88SMR drives are divided into zones (typically in the range of 256MB each) 89that fall into three general categories: 90.Bl -tag -width 20n 91.It Conventional 92These are also known as Non Write Pointer zones. 93These zones can be randomly written without an unexpected performance penalty. 94.It Sequential Preferred 95These zones should be written sequentially starting at the write pointer 96for the zone. 97They may be written randomly. 98Writes that do not conform to the zone layout may be significantly slower 99than expected. 100.It Sequential Required 101These zones must be written sequentially. 102If they are not written sequentially, starting at the write pointer, the 103command will fail. 104.El 105.Bl -tag -width 12n 106.It Fl c Ar cmd 107Specify the zone subcommand: 108.Bl -tag -width 6n 109.It params 110Display device parameters, including the type of device (Drive Managed, 111Host Aware, Host Managed, Not Zoned), the zone commands supported, and 112how many open zones it supports. 113.It rz 114Issue the Report Zones command. 115All zones are returned by default. 116Specify report options with 117.Fl o 118and printing options with 119.Fl P . 120Specify the starting LBA with 121.Fl l . 122Note that 123.Dq reportzones 124is also accepted as a command argument. 125.It open 126Explicitly open the zone specified by the starting LBA. 127.It close 128Close the zone specified by starting LBA. 129.It finish 130Finish the zone specified by the starting LBA. 131.It rwp 132Reset the write pointer for the zone specified by the starting LBA. 133.El 134.It Fl a 135For the Open, Close, Finish, and Reset Write Pointer operations, apply the 136operation to all zones on the drive. 137.It Fl l Ar lba 138Specify the starting LBA. 139For the Report Zones command, this tells the drive to report starting with 140the zone that starts at the given LBA. 141For the other commands, this allows the user to identify the zone requested 142by its starting LBA. 143The LBA may be specified in decimal, hexadecimal or octal notation. 144.It Fl o Ar rep_opt 145For the Report Zones command, specify a subset of zones to report. 146.Bl -tag -width 8n 147.It all 148Report all zones. 149This is the default. 150.It emtpy 151Report only empty zones. 152.It imp_open 153Report zones that are implicitly open. 154This means that the host has sent a write to the zone without explicitly 155opening the zone. 156.It exp_open 157Report zones that are explicitly open. 158.It closed 159Report zones that have been closed by the host. 160.It full 161Report zones that are full. 162.It ro 163Report zones that are in the read only state. 164Note that 165.Dq readonly 166is also accepted as an argument. 167.It offline 168Report zones that are in the offline state. 169.It reset 170Report zones that the device recommends should have their write pointers reset. 171.It nonseq 172Report zones that have the Non Sequential Resources Active flag set. 173These are zones that are Sequential Write Preferred, but have been written 174non-sequentially. 175.It nonwp 176Report Non Write Pointer zones, also known as Conventional zones. 177.El 178.It Fl P Ar print_opt 179Specify a printing option for Report Zones: 180.Bl -tag -width 7n 181.It normal 182Normal Report Zones output. 183This is the default. 184The summary and column headings are printed, fields are separated by spaces 185and the fields themselves may contain spaces. 186.It summary 187Just print the summary: the number of zones, the maximum LBA (LBA of the 188last logical block on the drive), and the value of the 189.Dq same 190field. 191The 192.Dq same 193field describes whether the zones on the drive are all identical, all 194different, or whether they are the same except for the last zone, etc. 195.It script 196Print the zones in a script friendly format. 197The summary and column headings are omitted, the fields are separated by 198commas, and the fields do not contain spaces. 199The fields contain underscores where spaces would normally be used. 200.El 201.El 202.Sh EXAMPLES 203.Bd -literal -offset indent 204zonectl -d /dev/da5 -c params 205.Ed 206.Pp 207Display basic zoning information for disk da5. 208.Bd -literal -offset indent 209zonectl -d /dev/da5 -c rz 210.Ed 211.Pp 212Issue the Report Zones command to disk da5, and print out all 213zones on the drive in the default format. 214.Bd -literal -offset indent 215zonectl -d /dev/da5 -c rz -o reset -P script 216.Ed 217.Pp 218Issue the Report Zones command to disk da5, and print out all 219of the zones that have the Reset Write Pointer Recommended bit set to true. 220Print the zones in a script friendly form. 221.Bd -literal -offset indent 222zonectl -d /dev/da5 -c rwp -l 0x2c80000 223.Ed 224.Pp 225Issue the Reset Write Pointer command to disk da5 for the zone 226that starts at LBA 0x2c80000. 227.Sh SEE ALSO 228.Xr camcontrol 8 229.Sh AUTHORS 230.An Kenneth Merry Aq ken@FreeBSD.org 231