1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
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
35#ifndef _SYS_DISK_ZONE_H_
36#define _SYS_DISK_ZONE_H_
37
38/*
39 * Interface for Zone-based disks. This allows managing devices that
40 * conform to the SCSI Zoned Block Commands (ZBC) and ATA Zoned ATA Command
41 * Set (ZAC) specifications. Devices using these command sets are
42 * currently (October 2015) hard drives using Shingled Magnetic Recording
43 * (SMR).
44 */
45
46/*
47 * There are currently three types of zoned devices:
48 *
49 * Drive Managed:
50 * Drive Managed drives look and act just like a standard random access
51 * block device, but underneath, the drive reads and writes the bulk of
52 * its capacity using SMR zones. Sequential writes will yield better
53 * performance, but writing sequentially is not required.
54 *
55 * Host Aware:
56 * Host Aware drives expose the underlying zone layout via SCSI or ATA
57 * commands and allow the host to manage the zone conditions. The host
58 * is not required to manage the zones on the drive, though. Sequential
59 * writes will yield better performance in Sequential Write Preferred
60 * zones, but the host can write randomly in those zones.
61 *
62 * Host Managed:
63 * Host Managed drives expose the underlying zone layout via SCSI or ATA
64 * commands. The host is required to access the zones according to the
65 * rules described by the zone layout. Any commands that violate the
66 * rules will be returned with an error.
67 */
68struct disk_zone_disk_params {
69 uint32_t zone_mode;
70#define DISK_ZONE_MODE_NONE 0x00
71#define DISK_ZONE_MODE_HOST_AWARE 0x01
72#define DISK_ZONE_MODE_DRIVE_MANAGED 0x02
73#define DISK_ZONE_MODE_HOST_MANAGED 0x04
74 uint64_t flags;
75#define DISK_ZONE_DISK_URSWRZ 0x001
76#define DISK_ZONE_OPT_SEQ_SET 0x002
77#define DISK_ZONE_OPT_NONSEQ_SET 0x004
78#define DISK_ZONE_MAX_SEQ_SET 0x008
79#define DISK_ZONE_RZ_SUP 0x010
80#define DISK_ZONE_OPEN_SUP 0x020
81#define DISK_ZONE_CLOSE_SUP 0x040
82#define DISK_ZONE_FINISH_SUP 0x080
83#define DISK_ZONE_RWP_SUP 0x100
84#define DISK_ZONE_CMD_SUP_MASK 0x1f0
85 uint64_t optimal_seq_zones;
86 uint64_t optimal_nonseq_zones;
87 uint64_t max_seq_zones;
88};
89
90/*
91 * Used for reset write pointer, open, close and finish.
92 */
93struct disk_zone_rwp {
94 uint64_t id;
95 uint8_t flags;
96#define DISK_ZONE_RWP_FLAG_NONE 0x00
97#define DISK_ZONE_RWP_FLAG_ALL 0x01
98};
99
100/*
101 * Report Zones header. All of these values are passed out.
102 */
103struct disk_zone_rep_header {
104 uint8_t same;
105#define DISK_ZONE_SAME_ALL_DIFFERENT 0x0 /* Lengths and types vary */
106#define DISK_ZONE_SAME_ALL_SAME 0x1 /* Lengths and types the same */
107#define DISK_ZONE_SAME_LAST_DIFFERENT 0x2 /* Types same, last len varies */
108#define DISK_ZONE_SAME_TYPES_DIFFERENT 0x3 /* Types vary, length the same */
109 uint64_t maximum_lba;
110 /*
111 * XXX KDM padding space may not be a good idea inside the bio.
112 */
113 uint8_t reserved[64];
114};
115
116/*
117 * Report Zones entry. Note that the zone types, conditions, and flags
118 * are mapped directly from the SCSI/ATA flag values. Any additional
119 * SCSI/ATA zone types or conditions or flags that are defined in the
120 * future could result in additional values that are not yet defined here.
121 */
122struct disk_zone_rep_entry {
123 uint8_t zone_type;
124#define DISK_ZONE_TYPE_CONVENTIONAL 0x01
125#define DISK_ZONE_TYPE_SEQ_REQUIRED 0x02 /* Host Managed */
126#define DISK_ZONE_TYPE_SEQ_PREFERRED 0x03 /* Host Aware */
127 uint8_t zone_condition;
128#define DISK_ZONE_COND_NOT_WP 0x00
129#define DISK_ZONE_COND_EMPTY 0x01
130#define DISK_ZONE_COND_IMPLICIT_OPEN 0x02
131#define DISK_ZONE_COND_EXPLICIT_OPEN 0x03
132#define DISK_ZONE_COND_CLOSED 0x04
133#define DISK_ZONE_COND_READONLY 0x0D
134#define DISK_ZONE_COND_FULL 0x0E
135#define DISK_ZONE_COND_OFFLINE 0x0F
136 uint8_t zone_flags;
137#define DISK_ZONE_FLAG_RESET 0x01 /* Zone needs RWP */
138#define DISK_ZONE_FLAG_NON_SEQ 0x02 /* Zone accssessed nonseq */
139 uint64_t zone_length;
140 uint64_t zone_start_lba;
141 uint64_t write_pointer_lba;
142 /* XXX KDM padding space may not be a good idea inside the bio */
143 uint8_t reserved[32];
144};
145
146struct disk_zone_report {
147 uint64_t starting_id; /* Passed In */
148 uint8_t rep_options; /* Passed In */
149#define DISK_ZONE_REP_ALL 0x00
150#define DISK_ZONE_REP_EMPTY 0x01
151#define DISK_ZONE_REP_IMP_OPEN 0x02
152#define DISK_ZONE_REP_EXP_OPEN 0x03
153#define DISK_ZONE_REP_CLOSED 0x04
154#define DISK_ZONE_REP_FULL 0x05
155#define DISK_ZONE_REP_READONLY 0x06
156#define DISK_ZONE_REP_OFFLINE 0x07
157#define DISK_ZONE_REP_RWP 0x10
158#define DISK_ZONE_REP_NON_SEQ 0x11
159#define DISK_ZONE_REP_NON_WP 0x3F
160 struct disk_zone_rep_header header;
161 uint32_t entries_allocated; /* Passed In */
162 uint32_t entries_filled; /* Passed Out */
163 uint32_t entries_available; /* Passed Out */
164 struct disk_zone_rep_entry *entries;
165};
166
167union disk_zone_params {
168 struct disk_zone_disk_params disk_params;
169 struct disk_zone_rwp rwp;
170 struct disk_zone_report report;
171};
172
173struct disk_zone_args {
174 uint8_t zone_cmd;
175#define DISK_ZONE_OPEN 0x00
176#define DISK_ZONE_CLOSE 0x01
177#define DISK_ZONE_FINISH 0x02
178#define DISK_ZONE_REPORT_ZONES 0x03
179#define DISK_ZONE_RWP 0x04
180#define DISK_ZONE_GET_PARAMS 0x05
181 union disk_zone_params zone_params;
182};
183
184#endif /* _SYS_DISK_ZONE_H_ */