sys/sys/disk_zone.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3  *
   4  * Copyright (c) 2015 Spectra Logic Corporation
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions, and the following disclaimer,
  12  *    without modification.
  13  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
  14  *    substantially similar to the "NO WARRANTY" disclaimer below
  15  *    ("Disclaimer") and any redistribution must be conditioned upon
  16  *    including a substantially similar Disclaimer requirement for further
  17  *    binary redistribution.
  18  *
  19  * NO WARRANTY
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  28  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  29  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30  * POSSIBILITY OF SUCH DAMAGES.
  31  *
  32  * Authors: Ken Merry           (Spectra Logic Corporation)
  33  *
  34  * $FreeBSD$
  35  */
  36
  37 #ifndef _SYS_DISK_ZONE_H_
  38 #define _SYS_DISK_ZONE_H_
  39
  40 /*
  41  * Interface for Zone-based disks.  This allows managing devices that
  42  * conform to the SCSI Zoned Block Commands (ZBC) and ATA Zoned ATA Command
  43  * Set (ZAC) specifications.  Devices using these command sets are
  44  * currently (October 2015) hard drives using Shingled Magnetic Recording
  45  * (SMR).
  46  */
  47
  48 /*
  49  * There are currently three types of zoned devices:
  50  *
  51  * Drive Managed:
  52  * Drive Managed drives look and act just like a standard random access
  53  * block device, but underneath, the drive reads and writes the bulk of
  54  * its capacity using SMR zones.  Sequential writes will yield better
  55  * performance, but writing sequentially is not required.
  56  *
  57  * Host Aware:
  58  * Host Aware drives expose the underlying zone layout via SCSI or ATA
  59  * commands and allow the host to manage the zone conditions.  The host
  60  * is not required to manage the zones on the drive, though.  Sequential
  61  * writes will yield better performance in Sequential Write Preferred
  62  * zones, but the host can write randomly in those zones.
  63  *
  64  * Host Managed:
  65  * Host Managed drives expose the underlying zone layout via SCSI or ATA
  66  * commands.  The host is required to access the zones according to the
  67  * rules described by the zone layout.  Any commands that violate the
  68  * rules will be returned with an error.
  69  */
  70 struct disk_zone_disk_params {
  71         uint32_t zone_mode;
  72 #define DISK_ZONE_MODE_NONE             0x00
  73 #define DISK_ZONE_MODE_HOST_AWARE       0x01
  74 #define DISK_ZONE_MODE_DRIVE_MANAGED    0x02
  75 #define DISK_ZONE_MODE_HOST_MANAGED     0x04
  76         uint64_t flags;
  77 #define DISK_ZONE_DISK_URSWRZ           0x001
  78 #define DISK_ZONE_OPT_SEQ_SET           0x002
  79 #define DISK_ZONE_OPT_NONSEQ_SET        0x004
  80 #define DISK_ZONE_MAX_SEQ_SET           0x008
  81 #define DISK_ZONE_RZ_SUP                0x010
  82 #define DISK_ZONE_OPEN_SUP              0x020
  83 #define DISK_ZONE_CLOSE_SUP             0x040
  84 #define DISK_ZONE_FINISH_SUP            0x080
  85 #define DISK_ZONE_RWP_SUP               0x100
  86 #define DISK_ZONE_CMD_SUP_MASK          0x1f0
  87         uint64_t optimal_seq_zones;
  88         uint64_t optimal_nonseq_zones;
  89         uint64_t max_seq_zones;
  90 };
  91
  92 /*
  93  * Used for reset write pointer, open, close and finish.
  94  */
  95 struct disk_zone_rwp {
  96         uint64_t        id;
  97         uint8_t         flags;
  98 #define DISK_ZONE_RWP_FLAG_NONE 0x00
  99 #define DISK_ZONE_RWP_FLAG_ALL  0x01
 100 };
 101
 102 /*
 103  * Report Zones header.  All of these values are passed out.
 104  */
 105 struct disk_zone_rep_header {
 106         uint8_t         same;
 107 #define DISK_ZONE_SAME_ALL_DIFFERENT    0x0 /* Lengths and types vary */
 108 #define DISK_ZONE_SAME_ALL_SAME         0x1 /* Lengths and types the same */
 109 #define DISK_ZONE_SAME_LAST_DIFFERENT   0x2 /* Types same, last len varies */
 110 #define DISK_ZONE_SAME_TYPES_DIFFERENT  0x3 /* Types vary, length the same */
 111         uint64_t        maximum_lba;
 112         /*
 113          * XXX KDM padding space may not be a good idea inside the bio.
 114          */
 115         uint8_t         reserved[64];
 116 };
 117
 118 /*
 119  * Report Zones entry.  Note that the zone types, conditions, and flags
 120  * are mapped directly from the SCSI/ATA flag values.  Any additional
 121  * SCSI/ATA zone types or conditions or flags that are defined in the
 122  * future could result in additional values that are not yet defined here.
 123  */
 124 struct disk_zone_rep_entry {
 125         uint8_t         zone_type;
 126 #define DISK_ZONE_TYPE_CONVENTIONAL     0x01
 127 #define DISK_ZONE_TYPE_SEQ_REQUIRED     0x02 /* Host Managed */
 128 #define DISK_ZONE_TYPE_SEQ_PREFERRED    0x03 /* Host Aware */
 129         uint8_t         zone_condition;
 130 #define DISK_ZONE_COND_NOT_WP           0x00
 131 #define DISK_ZONE_COND_EMPTY            0x01
 132 #define DISK_ZONE_COND_IMPLICIT_OPEN    0x02
 133 #define DISK_ZONE_COND_EXPLICIT_OPEN    0x03
 134 #define DISK_ZONE_COND_CLOSED           0x04
 135 #define DISK_ZONE_COND_READONLY         0x0D
 136 #define DISK_ZONE_COND_FULL             0x0E
 137 #define DISK_ZONE_COND_OFFLINE          0x0F
 138         uint8_t         zone_flags;
 139 #define DISK_ZONE_FLAG_RESET            0x01 /* Zone needs RWP */
 140 #define DISK_ZONE_FLAG_NON_SEQ          0x02 /* Zone accssessed nonseq */
 141         uint64_t        zone_length;
 142         uint64_t        zone_start_lba;
 143         uint64_t        write_pointer_lba;
 144         /* XXX KDM padding space may not be a good idea inside the bio */
 145         uint8_t         reserved[32];
 146 };
 147
 148 struct disk_zone_report {
 149         uint64_t                        starting_id;      /* Passed In */
 150         uint8_t                         rep_options;      /* Passed In */
 151 #define DISK_ZONE_REP_ALL       0x00
 152 #define DISK_ZONE_REP_EMPTY     0x01
 153 #define DISK_ZONE_REP_IMP_OPEN  0x02
 154 #define DISK_ZONE_REP_EXP_OPEN  0x03
 155 #define DISK_ZONE_REP_CLOSED    0x04
 156 #define DISK_ZONE_REP_FULL      0x05
 157 #define DISK_ZONE_REP_READONLY  0x06
 158 #define DISK_ZONE_REP_OFFLINE   0x07
 159 #define DISK_ZONE_REP_RWP       0x10
 160 #define DISK_ZONE_REP_NON_SEQ   0x11
 161 #define DISK_ZONE_REP_NON_WP    0x3F
 162         struct disk_zone_rep_header     header;
 163         uint32_t                        entries_allocated; /* Passed In */
 164         uint32_t                        entries_filled;    /* Passed Out */
 165         uint32_t                        entries_available; /* Passed Out */
 166         struct disk_zone_rep_entry      *entries;
 167 };
 168
 169 union disk_zone_params {
 170         struct disk_zone_disk_params    disk_params;
 171         struct disk_zone_rwp            rwp;
 172         struct disk_zone_report         report;
 173 };
 174
 175 struct disk_zone_args {
 176         uint8_t                 zone_cmd;
 177 #define DISK_ZONE_OPEN          0x00
 178 #define DISK_ZONE_CLOSE         0x01
 179 #define DISK_ZONE_FINISH        0x02
 180 #define DISK_ZONE_REPORT_ZONES  0x03
 181 #define DISK_ZONE_RWP           0x04
 182 #define DISK_ZONE_GET_PARAMS    0x05
 183         union disk_zone_params  zone_params;
 184 };
 185
 186 #endif /* _SYS_DISK_ZONE_H_ */