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.Pp 108.Bl -tag -width 12n 109.It Fl c Ar cmd 110Specify the zone subcommand: 111.Bl -tag -width 6n 112.It params 113Display device parameters, including the type of device (Drive Managed, 114Host Aware, Host Managed, Not Zoned), the zone commands supported, and 115how many open zones it supports. 116.It rz 117Issue the Report Zones command. 118All zones are returned by default. 119Specify report options with 120.Fl o 121and printing options with 122.Fl P . 123Specify the starting LBA with 124.Fl l . 125Note that 126.Dq reportzones 127is also accepted as a command argument. 128.It open 129Explicitly open the zone specified by the starting LBA. 130.It close 131Close the zone specified by starting LBA. 132.It finish 133Finish the zone specified by the starting LBA. 134.It rwp 135Reset the write pointer for the zone specified by the starting LBA. 136.El 137.It Fl a 138For the Open, Close, Finish, and Reset Write Pointer operations, apply the 139operation to all zones on the drive. 140.It Fl l Ar lba 141Specify the starting LBA. 142For the Report Zones command, this tells the drive to report starting with 143the zone that starts at the given LBA. 144For the other commands, this allows the user to identify the zone requested 145by its starting LBA. 146The LBA may be specified in decimal, hexadecimal or octal notation. 147.It Fl o Ar rep_opt 148For the Report Zones command, specify a subset of zones to report. 149.Bl -tag -width 8n 150.It all 151Report all zones. 152This is the default. 153.It emtpy 154Report only empty zones. 155.It imp_open 156Report zones that are implicitly open. 157This means that the host has sent a write to the zone without explicitly 158opening the zone. 159.It exp_open 160Report zones that are explicitly open. 161.It closed 162Report zones that have been closed by the host. 163.It full 164Report zones that are full. 165.It ro 166Report zones that are in the read only state. 167Note that 168.Dq readonly 169is also accepted as an argument. 170.It offline 171Report zones that are in the offline state. 172.It reset 173Report zones that the device recommends should have their write pointers reset. 174.It nonseq 175Report zones that have the Non Sequential Resources Active flag set. 176These are zones that are Sequential Write Preferred, but have been written 177non-sequentially. 178.It nonwp 179Report Non Write Pointer zones, also known as Conventional zones. 180.El 181.It Fl P Ar print_opt 182Specify a printing option for Report Zones: 183.Bl -tag -width 7n 184.It normal 185Normal Report Zones output. 186This is the default. 187The summary and column headings are printed, fields are separated by spaces 188and the fields themselves may contain spaces. 189.It summary 190Just print the summary: the number of zones, the maximum LBA (LBA of the 191last logical block on the drive), and the value of the 192.Dq same 193field. 194The 195.Dq same 196field describes whether the zones on the drive are all identical, all 197different, or whether they are the same except for the last zone, etc. 198.It script 199Print the zones in a script friendly format. 200The summary and column headings are omitted, the fields are separated by 201commas, and the fields do not contain spaces. 202The fields contain underscores where spaces would normally be used. 203.El 204.El 205.Sh EXAMPLES 206.Bd -literal -offset indent 207zonectl -d /dev/da5 -c params 208.Ed 209.Pp 210Display basic zoning information for disk da5. 211.Pp 212.Bd -literal -offset indent 213zonectl -d /dev/da5 -c rz 214.Ed 215.Pp 216Issue the Report Zones command to disk da5, and print out all 217zones on the drive in the default format. 218.Pp 219.Bd -literal -offset indent 220zonectl -d /dev/da5 -c rz -o reset -P script 221.Ed 222.Pp 223Issue the Report Zones command to disk da5, and print out all 224of the zones that have the Reset Write Pointer Recommended bit set to true. 225Print the zones in a script friendly form. 226.Pp 227.Bd -literal -offset indent 228zonectl -d /dev/da5 -c rwp -l 0x2c80000 229.Ed 230.Pp 231Issue the Reset Write Pointer command to disk da5 for the zone 232that starts at LBA 0x2c80000. 233.Pp 234.Bd -literal -offset indent 235.Sh AUTHORS 236.An Kenneth Merry Aq ken@FreeBSD.org 237