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