Debian Codegraph @

src/nvme/fabrics.h

raw
1 // SPDX-License-Identifier: LGPL-2.1-or-later
2 /*
3 * This file is part of libnvme.
4 * Copyright (c) 2020 Western Digital Corporation or its affiliates.
5 *
6 * Authors: Keith Busch <[email protected]>
7 * Chaitanya Kulkarni <[email protected]>
8 */
9 #ifndef _LIBNVME_FABRICS_H
10 #define _LIBNVME_FABRICS_H
11
12 #include <stdbool.h>
13 #include <stdint.h>
14
15 #include <nvme/tree.h>
16
17 /**
18 * DOC: fabrics.h
19 *
20 * Fabrics-specific definitions.
21 */
22
23 /* default to 600 seconds of reconnect attempts before giving up */
24 #define NVMF_DEF_CTRL_LOSS_TMO 600
25
26 /**
27 * struct nvme_fabrics_config - Defines all linux nvme fabrics initiator options
28 * @host_traddr: Host transport address
29 * @host_iface: Host interface name
30 * @queue_size: Number of IO queue entries
31 * @nr_io_queues: Number of controller IO queues to establish
32 * @reconnect_delay: Time between two consecutive reconnect attempts.
33 * @ctrl_loss_tmo: Override the default controller reconnect attempt timeout in seconds
34 * @fast_io_fail_tmo: Set the fast I/O fail timeout in seconds.
35 * @keep_alive_tmo: Override the default keep-alive-timeout to this value in seconds
36 * @nr_write_queues: Number of queues to use for exclusively for writing
37 * @nr_poll_queues: Number of queues to reserve for polling completions
38 * @tos: Type of service
39 * @keyring: Keyring to store and lookup keys
40 * @tls_key: TLS PSK for the connection
41 * @tls_configured_key: TLS PSK for connect command for the connection
42 * @duplicate_connect: Allow multiple connections to the same target
43 * @disable_sqflow: Disable controller sq flow control
44 * @hdr_digest: Generate/verify header digest (TCP)
45 * @data_digest: Generate/verify data digest (TCP)
46 * @tls: Start TLS on the connection (TCP)
47 * @concat: Enable secure concatenation (TCP)
48 */
49 struct nvme_fabrics_config {
50 char *host_traddr;
51 char *host_iface;
52 int queue_size;
53 int nr_io_queues;
54 int reconnect_delay;
55 int ctrl_loss_tmo;
56 int fast_io_fail_tmo;
57 int keep_alive_tmo;
58 int nr_write_queues;
59 int nr_poll_queues;
60 int tos;
61 long keyring;
62 long tls_key;
63 long tls_configured_key;
64
65 bool duplicate_connect;
66 bool disable_sqflow;
67 bool hdr_digest;
68 bool data_digest;
69 bool tls;
70 bool concat;
71 };
72
73 /**
74 * struct nvme_fabrics_uri - Parsed URI structure
75 * @scheme: Scheme name (typically 'nvme')
76 * @protocol: Optional protocol/transport (e.g. 'tcp')
77 * @userinfo: Optional user information component of the URI authority
78 * @host: Host transport address
79 * @port: The port subcomponent or 0 if not specified
80 * @path_segments: NULL-terminated array of path segments
81 * @query: Optional query string component (separated by '?')
82 * @fragment: Optional fragment identifier component (separated by '#')
83 */
84 struct nvme_fabrics_uri {
85 char *scheme;
86 char *protocol;
87 char *userinfo;
88 char *host;
89 int port;
90 char **path_segments;
91 char *query;
92 char *fragment;
93 };
94
95 /**
96 * nvmf_trtype_str() - Decode TRTYPE field
97 * @trtype: value to be decoded
98 *
99 * Decode the transport type field in the discovery
100 * log page entry.
101 *
102 * Return: decoded string
103 */
104 const char *nvmf_trtype_str(__u8 trtype);
105
106 /**
107 * nvmf_adrfam_str() - Decode ADRFAM field
108 * @adrfam: value to be decoded
109 *
110 * Decode the address family field in the discovery
111 * log page entry.
112 *
113 * Return: decoded string
114 */
115 const char *nvmf_adrfam_str(__u8 adrfam);
116
117 /**
118 * nvmf_subtype_str() - Decode SUBTYPE field
119 * @subtype: value to be decoded
120 *
121 * Decode the subsystem type field in the discovery
122 * log page entry.
123 *
124 * Return: decoded string
125 */
126 const char *nvmf_subtype_str(__u8 subtype);
127
128 /**
129 * nvmf_treq_str() - Decode TREQ field
130 * @treq: value to be decoded
131 *
132 * Decode the transport requirements field in the
133 * discovery log page entry.
134 *
135 * Return: decoded string
136 */
137 const char *nvmf_treq_str(__u8 treq);
138
139 /**
140 * nvmf_eflags_str() - Decode EFLAGS field
141 * @eflags: value to be decoded
142 *
143 * Decode the EFLAGS field in the discovery log page
144 * entry.
145 *
146 * Return: decoded string
147 */
148 const char *nvmf_eflags_str(__u16 eflags);
149
150 /**
151 * nvmf_sectype_str() - Decode SECTYPE field
152 * @sectype: value to be decoded
153 *
154 * Decode the SECTYPE field in the discovery log page
155 * entry.
156 *
157 * Return: decoded string
158 */
159 const char *nvmf_sectype_str(__u8 sectype);
160
161 /**
162 * nvmf_prtype_str() - Decode RDMA Provider type field
163 * @prtype: value to be decoded
164 *
165 * Decode the RDMA Provider type field in the discovery
166 * log page entry.
167 *
168 * Return: decoded string
169 */
170 const char *nvmf_prtype_str(__u8 prtype);
171
172 /**
173 * nvmf_qptype_str() - Decode RDMA QP Service type field
174 * @qptype: value to be decoded
175 *
176 * Decode the RDMA QP Service type field in the discovery log page
177 * entry.
178 *
179 * Return: decoded string
180 */
181 const char *nvmf_qptype_str(__u8 qptype);
182
183 /**
184 * nvmf_cms_str() - Decode RDMA connection management service field
185 * @cms: value to be decoded
186 *
187 * Decode the RDMA connection management service field in the discovery
188 * log page entry.
189 *
190 * Return: decoded string
191 */
192 const char *nvmf_cms_str(__u8 cms);
193
194 /**
195 * nvmf_default_config() - Default values for fabrics configuration
196 * @cfg: config values to set
197 *
198 * Initializes @cfg with default values.
199 */
200 void nvmf_default_config(struct nvme_fabrics_config *cfg);
201
202 /**
203 * nvmf_update_config() - Update fabrics configuration values
204 * @c: Controller to be modified
205 * @cfg: Updated configuration values
206 *
207 * Updates the values from @c with the configuration values from @cfg;
208 * all non-default values from @cfg will overwrite the values in @c.
209 */
210 void nvmf_update_config(nvme_ctrl_t c, const struct nvme_fabrics_config *cfg);
211
212 /**
213 * nvmf_add_ctrl() - Connect a controller and update topology
214 * @h: Host to which the controller should be attached
215 * @c: Controller to be connected
216 * @cfg: Default configuration for the controller
217 *
218 * Issues a 'connect' command to the NVMe-oF controller and inserts @c
219 * into the topology using @h as parent.
220 * @c must be initialized and not connected to the topology.
221 *
222 * Return: 0 on success; on failure errno is set and -1 is returned.
223 */
224 int nvmf_add_ctrl(nvme_host_t h, nvme_ctrl_t c,
225 const struct nvme_fabrics_config *cfg);
226
227 /**
228 * nvmf_connect_ctrl() - Connect a controller
229 * @c: Controller to be connected
230 *
231 * Issues a 'connect' command to the NVMe-oF controller.
232 * @c must be initialized and not connected to the topology.
233 *
234 * Return: 0 on success; on failure errno is set and -1 is returned.
235 */
236 int nvmf_connect_ctrl(nvme_ctrl_t c);
237
238 /**
239 * nvmf_get_discovery_log() - Return the discovery log page
240 * @c: Discovery controller to use
241 * @logp: Pointer to the log page to be returned
242 * @max_retries: Number of retries in case of failure
243 *
244 * The memory allocated for the log page and returned in @logp
245 * must be freed by the caller using free().
246 *
247 * Note: Consider using nvmf_get_discovery_wargs() instead.
248 *
249 * Return: 0 on success; on failure -1 is returned and errno is set
250 */
251 int nvmf_get_discovery_log(nvme_ctrl_t c, struct nvmf_discovery_log **logp,
252 int max_retries);
253
254 /**
255 * struct nvme_get_discovery_args - Arguments for nvmf_get_discovery_wargs()
256 * @c: Discovery controller
257 * @args_size: Length of the structure
258 * @max_retries: Number of retries in case of failure
259 * @result: The command completion result from CQE dword0
260 * @timeout: Timeout in ms (default: NVME_DEFAULT_IOCTL_TIMEOUT)
261 * @lsp: Log specific field (See enum nvmf_log_discovery_lsp)
262 */
263 struct nvme_get_discovery_args {
264 nvme_ctrl_t c;
265 int args_size;
266 int max_retries;
267 __u32 *result;
268 __u32 timeout;
269 __u8 lsp;
270 };
271
272 /**
273 * nvmf_get_discovery_wargs() - Get the discovery log page with args
274 * @args: Argument structure
275 *
276 * This function is similar to nvmf_get_discovery_log(), but
277 * takes an extensible @args parameter. @args provides more
278 * options than nvmf_get_discovery_log().
279 *
280 * This function performs a get discovery log page (DLP) command
281 * and returns the DLP. The memory allocated for the returned
282 * DLP must be freed by the caller using free().
283 *
284 * Return: Pointer to the discovery log page (to be freed). NULL
285 * on failure and errno is set.
286 */
287 struct nvmf_discovery_log *nvmf_get_discovery_wargs(struct nvme_get_discovery_args *args);
288
289 /**
290 * nvmf_hostnqn_generate() - Generate a machine specific host nqn
291 * Returns: An nvm namespace qualified name string based on the machine
292 * identifier, or NULL if not successful.
293 */
294 char *nvmf_hostnqn_generate();
295
296 /**
297 * nvmf_hostnqn_generate_from_hostid() - Generate a host nqn from host identifier
298 * @hostid: Host identifier
299 *
300 * If @hostid is NULL, the function generates it based on the machine
301 * identifier.
302 *
303 * Return: On success, an NVMe Qualified Name for host identification. This
304 * name is based on the given host identifier. On failure, NULL.
305 */
306 char *nvmf_hostnqn_generate_from_hostid(char *hostid);
307
308 /**
309 * nvmf_hostid_generate() - Generate a machine specific host identifier
310 *
311 * Return: On success, an identifier string based on the machine identifier to
312 * be used as NVMe Host Identifier, or NULL on failure.
313 */
314 char *nvmf_hostid_generate();
315
316 /**
317 * nvmf_hostnqn_from_file() - Reads the host nvm qualified name from the config
318 * default location
319 *
320 * Retrieve the qualified name from the config file located in $SYSCONFIDR/nvme.
321 * $SYSCONFDIR is usually /etc.
322 *
323 * Return: The host nqn, or NULL if unsuccessful. If found, the caller
324 * is responsible to free the string.
325 */
326 char *nvmf_hostnqn_from_file();
327
328 /**
329 * nvmf_hostid_from_file() - Reads the host identifier from the config default
330 * location
331 *
332 * Retrieve the host idenditifer from the config file located in $SYSCONFDIR/nvme/.
333 * $SYSCONFDIR is usually /etc.
334 *
335 * Return: The host identifier, or NULL if unsuccessful. If found, the caller
336 * is responsible to free the string.
337 */
338 char *nvmf_hostid_from_file();
339
340 /**
341 * nvmf_connect_disc_entry() - Connect controller based on the discovery log page entry
342 * @h: Host to which the controller should be connected
343 * @e: Discovery log page entry
344 * @defcfg: Default configuration to be used for the new controller
345 * @discover: Set to 'true' if the new controller is a discovery controller
346 *
347 * Return: Pointer to the new controller
348 */
349 nvme_ctrl_t nvmf_connect_disc_entry(nvme_host_t h,
350 struct nvmf_disc_log_entry *e,
351 const struct nvme_fabrics_config *defcfg, bool *discover);
352
353 /**
354 * nvmf_is_registration_supported - check whether registration can be performed.
355 * @c: Controller instance
356 *
357 * Only discovery controllers (DC) that comply with TP8010 support
358 * explicit registration with the DIM PDU. These can be identified by
359 * looking at the value of a dctype in the Identify command
360 * response. A value of 1 (DDC) or 2 (CDC) indicates that the DC
361 * supports explicit registration.
362 *
363 * Return: true if controller supports explicit registration. false
364 * otherwise.
365 */
366 bool nvmf_is_registration_supported(nvme_ctrl_t c);
367
368 /**
369 * nvmf_register_ctrl() - Perform registration task with a DC
370 * @c: Controller instance
371 * @tas: Task field of the Command Dword 10 (cdw10). Indicates whether to
372 * perform a Registration, Deregistration, or Registration-update.
373 * @result: The command-specific result returned by the DC upon command
374 * completion.
375 *
376 * Perform registration task with a Discovery Controller (DC). Three
377 * tasks are supported: register, deregister, and registration update.
378 *
379 * Return: 0 on success; on failure -1 is returned and errno is set
380 */
381 int nvmf_register_ctrl(nvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result);
382
383 /**
384 * nvme_parse_uri() - Parse the URI string
385 * @str: URI string
386 *
387 * Parse the URI string as defined in the NVM Express Boot Specification.
388 * Supported URI elements looks as follows:
389 *
390 * nvme+tcp://user@host:port/subsys_nqn/nid?query=val#fragment
391 *
392 * Return: &nvme_fabrics_uri structure on success; NULL on failure with errno
393 * set.
394 */
395 struct nvme_fabrics_uri *nvme_parse_uri(const char *str);
396
397 /**
398 * nvme_free_uri() - Free the URI structure
399 * @uri: &nvme_fabrics_uri structure
400 *
401 * Free an &nvme_fabrics_uri structure.
402 */
403 void nvme_free_uri(struct nvme_fabrics_uri *uri);
404
405 #endif /* _LIBNVME_FABRICS_H */