4 * Copyright (c) Intel Corporation.
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * * Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * * Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
17 * * Neither the name of Intel Corporation nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 * Zoned device public interface
38 #ifndef SPDK_BDEV_ZONE_H
39 #define SPDK_BDEV_ZONE_H
41 #include "spdk/stdinc.h"
42 #include "spdk/bdev.h"
45 * \brief SPDK block device.
47 * This is a virtual representation of a block device that is exported by the backend.
52 enum spdk_bdev_zone_action
{
54 SPDK_BDEV_ZONE_FINISH
,
59 enum spdk_bdev_zone_state
{
60 SPDK_BDEV_ZONE_STATE_EMPTY
,
61 SPDK_BDEV_ZONE_STATE_OPEN
,
62 SPDK_BDEV_ZONE_STATE_FULL
,
63 SPDK_BDEV_ZONE_STATE_CLOSED
,
64 SPDK_BDEV_ZONE_STATE_READ_ONLY
,
65 SPDK_BDEV_ZONE_STATE_OFFLINE
68 struct spdk_bdev_zone_info
{
70 uint64_t write_pointer
;
72 enum spdk_bdev_zone_state state
;
76 * Get device zone size in logical blocks.
78 * \param bdev Block device to query.
79 * \return Size of zone for this zoned device in logical blocks.
81 uint64_t spdk_bdev_get_zone_size(const struct spdk_bdev
*bdev
);
84 * Get device maximum number of open zones.
86 * If this value is 0, there is no limit.
88 * \param bdev Block device to query.
89 * \return Maximum number of open zones for this zoned device.
91 uint32_t spdk_bdev_get_max_open_zones(const struct spdk_bdev
*bdev
);
94 * Get device optimal number of open zones.
96 * \param bdev Block device to query.
97 * \return Optimal number of open zones for this zoned device.
99 uint32_t spdk_bdev_get_optimal_open_zones(const struct spdk_bdev
*bdev
);
102 * Submit a get_zone_info request to the bdev.
104 * \ingroup bdev_io_submit_functions
106 * \param desc Block device descriptor.
107 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
108 * \param zone_id First logical block of a zone.
109 * \param num_zones Number of consecutive zones info to retrieve.
110 * \param info Pointer to array capable of storing num_zones elements.
111 * \param cb Called when the request is complete.
112 * \param cb_arg Argument passed to cb.
114 * \return 0 on success. On success, the callback will always
115 * be called (even if the request ultimately failed). Return
116 * negated errno on failure, in which case the callback will not be called.
117 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
119 int spdk_bdev_get_zone_info(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
120 uint64_t zone_id
, size_t num_zones
, struct spdk_bdev_zone_info
*info
,
121 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
125 * Submit a zone_management request to the bdev.
127 * \ingroup bdev_io_submit_functions
129 * \param desc Block device descriptor.
130 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
131 * \param zone_id First logical block of a zone.
132 * \param action Action to perform on a zone (open, close, reset, finish).
133 * \param cb Called when the request is complete.
134 * \param cb_arg Argument passed to cb.
136 * \return 0 on success. On success, the callback will always
137 * be called (even if the request ultimately failed). Return
138 * negated errno on failure, in which case the callback will not be called.
139 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
141 int spdk_bdev_zone_management(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
142 uint64_t zone_id
, enum spdk_bdev_zone_action action
,
143 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
146 * Submit a zone_append request to the bdev.
148 * \ingroup bdev_io_submit_functions
150 * \param desc Block device descriptor.
151 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
152 * \param buf Data buffer to written from.
153 * \param zone_id First logical block of a zone.
154 * \param num_blocks The number of blocks to write. buf must be greater than or equal to this size.
155 * \param cb Called when the request is complete.
156 * \param cb_arg Argument passed to cb.
158 * \return 0 on success. On success, the callback will always
159 * be called (even if the request ultimately failed).
160 * Appended logical block address can be obtained with spdk_bdev_io_get_append_location().
161 * Return negated errno on failure, in which case the callback will not be called.
162 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
164 int spdk_bdev_zone_append(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
165 void *buf
, uint64_t zone_id
, uint64_t num_blocks
,
166 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
169 * Submit a zone_append request to the bdev. This differs from
170 * spdk_bdev_zone_append by allowing the data buffer to be described in a scatter
173 * \ingroup bdev_io_submit_functions
175 * \param desc Block device descriptor.
176 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
177 * \param iov A scatter gather list of buffers to be written from.
178 * \param iovcnt The number of elements in iov.
179 * \param zone_id First logical block of a zone.
180 * \param num_blocks The number of blocks to write. buf must be greater than or equal to this size.
181 * \param cb Called when the request is complete.
182 * \param cb_arg Argument passed to cb.
184 * \return 0 on success. On success, the callback will always
185 * be called (even if the request ultimately failed).
186 * Appended logical block address can be obtained with spdk_bdev_io_get_append_location().
187 * Return negated errno on failure, in which case the callback will not be called.
188 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
190 int spdk_bdev_zone_appendv(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
191 struct iovec
*iov
, int iovcnt
, uint64_t zone_id
, uint64_t num_blocks
,
192 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
195 * Submit a zone_append request with metadata to the bdev.
197 * This function uses separate buffer for metadata transfer (valid only if bdev supports this
200 * \ingroup bdev_io_submit_functions
202 * \param desc Block device descriptor.
203 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
204 * \param buf Data buffer to written from.
205 * \param md Metadata buffer.
206 * \param zone_id First logical block of a zone.
207 * \param num_blocks The number of blocks to write. buf must be greater than or equal to this size.
208 * \param cb Called when the request is complete.
209 * \param cb_arg Argument passed to cb.
211 * \return 0 on success. On success, the callback will always
212 * be called (even if the request ultimately failed).
213 * Appended logical block address can be obtained with spdk_bdev_io_get_append_location().
214 * Return negated errno on failure, in which case the callback will not be called.
215 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
217 int spdk_bdev_zone_append_with_md(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
218 void *buf
, void *md
, uint64_t zone_id
, uint64_t num_blocks
,
219 spdk_bdev_io_completion_cb cb
, void *cb_arg
);
222 * Submit a zone_append request with metadata to the bdev. This differs from
223 * spdk_bdev_zone_append by allowing the data buffer to be described in a scatter
226 * This function uses separate buffer for metadata transfer (valid only if bdev supports this
229 * \ingroup bdev_io_submit_functions
231 * \param desc Block device descriptor.
232 * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
233 * \param iov A scatter gather list of buffers to be written from.
234 * \param iovcnt The number of elements in iov.
235 * \param md Metadata buffer.
236 * \param zone_id First logical block of a zone.
237 * \param num_blocks The number of blocks to write. buf must be greater than or equal to this size.
238 * \param cb Called when the request is complete.
239 * \param cb_arg Argument passed to cb.
241 * \return 0 on success. On success, the callback will always
242 * be called (even if the request ultimately failed).
243 * Appended logical block address can be obtained with spdk_bdev_io_get_append_location().
244 * Return negated errno on failure, in which case the callback will not be called.
245 * * -ENOMEM - spdk_bdev_io buffer cannot be allocated
247 int spdk_bdev_zone_appendv_with_md(struct spdk_bdev_desc
*desc
, struct spdk_io_channel
*ch
,
248 struct iovec
*iov
, int iovcnt
, void *md
, uint64_t zone_id
,
249 uint64_t num_blocks
, spdk_bdev_io_completion_cb cb
,
253 * Get append location (offset in blocks of the bdev) for this I/O.
255 * \param bdev_io I/O to get append location from.
257 uint64_t spdk_bdev_io_get_append_location(struct spdk_bdev_io
*bdev_io
);
259 #endif /* SPDK_BDEV_ZONE_H */