]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
4 | * Copyright (c) Intel 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 | * | |
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 | |
16 | * distribution. | |
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. | |
20 | * | |
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. | |
32 | */ | |
33 | ||
34 | /** \file | |
35 | * Zoned device public interface | |
36 | */ | |
37 | ||
38 | #ifndef SPDK_BDEV_ZONE_H | |
39 | #define SPDK_BDEV_ZONE_H | |
40 | ||
41 | #include "spdk/stdinc.h" | |
42 | #include "spdk/bdev.h" | |
43 | ||
44 | /** | |
45 | * \brief SPDK block device. | |
46 | * | |
47 | * This is a virtual representation of a block device that is exported by the backend. | |
48 | */ | |
49 | ||
50 | struct spdk_bdev; | |
51 | ||
52 | enum spdk_bdev_zone_action { | |
53 | SPDK_BDEV_ZONE_CLOSE, | |
54 | SPDK_BDEV_ZONE_FINISH, | |
55 | SPDK_BDEV_ZONE_OPEN, | |
56 | SPDK_BDEV_ZONE_RESET | |
57 | }; | |
58 | ||
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 | |
66 | }; | |
67 | ||
68 | struct spdk_bdev_zone_info { | |
69 | uint64_t zone_id; | |
70 | uint64_t write_pointer; | |
71 | uint64_t capacity; | |
72 | enum spdk_bdev_zone_state state; | |
73 | }; | |
74 | ||
75 | /** | |
76 | * Get device zone size in logical blocks. | |
77 | * | |
78 | * \param bdev Block device to query. | |
79 | * \return Size of zone for this zoned device in logical blocks. | |
80 | */ | |
81 | uint64_t spdk_bdev_get_zone_size(const struct spdk_bdev *bdev); | |
82 | ||
83 | /** | |
84 | * Get device maximum number of open zones. | |
85 | * | |
86 | * If this value is 0, there is no limit. | |
87 | * | |
88 | * \param bdev Block device to query. | |
89 | * \return Maximum number of open zones for this zoned device. | |
90 | */ | |
91 | uint32_t spdk_bdev_get_max_open_zones(const struct spdk_bdev *bdev); | |
92 | ||
93 | /** | |
94 | * Get device optimal number of open zones. | |
95 | * | |
96 | * \param bdev Block device to query. | |
97 | * \return Optimal number of open zones for this zoned device. | |
98 | */ | |
99 | uint32_t spdk_bdev_get_optimal_open_zones(const struct spdk_bdev *bdev); | |
100 | ||
101 | /** | |
102 | * Submit a get_zone_info request to the bdev. | |
103 | * | |
104 | * \ingroup bdev_io_submit_functions | |
105 | * | |
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. | |
113 | * | |
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 | |
118 | */ | |
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); | |
122 | ||
123 | ||
124 | /** | |
125 | * Submit a zone_management request to the bdev. | |
126 | * | |
127 | * \ingroup bdev_io_submit_functions | |
128 | * | |
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. | |
135 | * | |
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 | |
140 | */ | |
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); | |
144 | ||
145 | /** | |
146 | * Submit a zone_append request to the bdev. | |
147 | * | |
148 | * \ingroup bdev_io_submit_functions | |
149 | * | |
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. | |
157 | * | |
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 | |
163 | */ | |
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); | |
167 | ||
168 | /** | |
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 | |
171 | * gather list. | |
172 | * | |
173 | * \ingroup bdev_io_submit_functions | |
174 | * | |
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. | |
183 | * | |
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 | |
189 | */ | |
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); | |
193 | ||
194 | /** | |
195 | * Submit a zone_append request with metadata to the bdev. | |
196 | * | |
197 | * This function uses separate buffer for metadata transfer (valid only if bdev supports this | |
198 | * mode). | |
199 | * | |
200 | * \ingroup bdev_io_submit_functions | |
201 | * | |
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. | |
210 | * | |
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 | |
216 | */ | |
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); | |
220 | ||
221 | /** | |
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 | |
224 | * gather list. | |
225 | * | |
226 | * This function uses separate buffer for metadata transfer (valid only if bdev supports this | |
227 | * mode). | |
228 | * | |
229 | * \ingroup bdev_io_submit_functions | |
230 | * | |
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. | |
240 | * | |
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 | |
246 | */ | |
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, | |
250 | void *cb_arg); | |
251 | ||
252 | /** | |
253 | * Get append location (offset in blocks of the bdev) for this I/O. | |
254 | * | |
255 | * \param bdev_io I/O to get append location from. | |
256 | */ | |
257 | uint64_t spdk_bdev_io_get_append_location(struct spdk_bdev_io *bdev_io); | |
258 | ||
259 | #endif /* SPDK_BDEV_ZONE_H */ |