fabrics.h

// SPDX-License-Identifier: LGPL-2.1-or-later
/*
 * This file is part of libnvme.
 * Copyright (c) 2020 Western Digital Corporation or its affiliates.
 *
 * Authors: Keith Busch <keith.busch@wdc.com>
 *	    Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
 */
#ifndef _LIBNVME_FABRICS_H
#define _LIBNVME_FABRICS_H

#include <stdbool.h>
#include <stdint.h>

#include <nvme/tree.h>

/**
 * DOC: fabrics.h
 *
 * Fabrics-specific definitions.
 */

/* default to 600 seconds of reconnect attempts before giving up */
#define NVMF_DEF_CTRL_LOSS_TMO		600

/**
 * struct nvme_fabrics_config - Defines all linux nvme fabrics initiator options
 * @queue_size:		Number of IO queue entries
 * @nr_io_queues:	Number of controller IO queues to establish
 * @reconnect_delay:	Time between two consecutive reconnect attempts.
 * @ctrl_loss_tmo:	Override the default controller reconnect attempt timeout in seconds
 * @fast_io_fail_tmo:	Set the fast I/O fail timeout in seconds.
 * @keep_alive_tmo:	Override the default keep-alive-timeout to this value in seconds
 * @nr_write_queues:	Number of queues to use for exclusively for writing
 * @nr_poll_queues:	Number of queues to reserve for polling completions
 * @tos:		Type of service
 * @keyring:		Keyring to store and lookup keys
 * @tls_key:		TLS PSK for the connection
 * @tls_configured_key: TLS PSK for connect command for the connection
 * @duplicate_connect:	Allow multiple connections to the same target
 * @disable_sqflow:	Disable controller sq flow control
 * @hdr_digest:		Generate/verify header digest (TCP)
 * @data_digest:	Generate/verify data digest (TCP)
 * @tls:		Start TLS on the connection (TCP)
 * @concat:		Enable secure concatenation (TCP)
 */
struct nvme_fabrics_config {
	int queue_size;
	int nr_io_queues;
	int reconnect_delay;
	int ctrl_loss_tmo;
	int fast_io_fail_tmo;
	int keep_alive_tmo;
	int nr_write_queues;
	int nr_poll_queues;
	int tos;
	long keyring;
	long tls_key;
	long tls_configured_key;

	bool duplicate_connect;
	bool disable_sqflow;
	bool hdr_digest;
	bool data_digest;
	bool tls;
	bool concat;
};

/**
 * struct nvme_fabrics_uri - Parsed URI structure
 * @scheme:		Scheme name (typically 'nvme')
 * @protocol:		Optional protocol/transport (e.g. 'tcp')
 * @userinfo:		Optional user information component of the URI authority
 * @host:		Host transport address
 * @port:		The port subcomponent or 0 if not specified
 * @path_segments:	NULL-terminated array of path segments
 * @query:		Optional query string component (separated by '?')
 * @fragment:		Optional fragment identifier component (separated by '#')
 */
struct nvme_fabrics_uri {
	char *scheme;
	char *protocol;
	char *userinfo;
	char *host;
	int port;
	char **path_segments;
	char *query;
	char *fragment;
};

/**
 * nvmf_trtype_str() - Decode TRTYPE field
 * @trtype: value to be decoded
 *
 * Decode the transport type field in the discovery
 * log page entry.
 *
 * Return: decoded string
 */
const char *nvmf_trtype_str(__u8 trtype);

/**
 * nvmf_adrfam_str() - Decode ADRFAM field
 * @adrfam: value to be decoded
 *
 * Decode the address family field in the discovery
 * log page entry.
 *
 * Return: decoded string
 */
const char *nvmf_adrfam_str(__u8 adrfam);

/**
 * nvmf_subtype_str() - Decode SUBTYPE field
 * @subtype: value to be decoded
 *
 * Decode the subsystem type field in the discovery
 * log page entry.
 *
 * Return: decoded string
 */
const char *nvmf_subtype_str(__u8 subtype);

/**
 * nvmf_treq_str() - Decode TREQ field
 * @treq: value to be decoded
 *
 * Decode the transport requirements field in the
 * discovery log page entry.
 *
 * Return: decoded string
 */
const char *nvmf_treq_str(__u8 treq);

/**
 * nvmf_eflags_str() - Decode EFLAGS field
 * @eflags: value to be decoded
 *
 * Decode the EFLAGS field in the discovery log page
 * entry.
 *
 * Return: decoded string
 */
const char *nvmf_eflags_str(__u16 eflags);

/**
 * nvmf_sectype_str() - Decode SECTYPE field
 * @sectype: value to be decoded
 *
 * Decode the SECTYPE field in the discovery log page
 * entry.
 *
 * Return: decoded string
 */
const char *nvmf_sectype_str(__u8 sectype);

/**
 * nvmf_prtype_str() - Decode RDMA Provider type field
 * @prtype: value to be decoded
 *
 * Decode the RDMA Provider type field in the discovery
 * log page entry.
 *
 * Return: decoded string
 */
const char *nvmf_prtype_str(__u8 prtype);

/**
 * nvmf_qptype_str() - Decode RDMA QP Service type field
 * @qptype: value to be decoded
 *
 * Decode the RDMA QP Service type field in the discovery log page
 * entry.
 *
 * Return: decoded string
 */
const char *nvmf_qptype_str(__u8 qptype);

/**
 * nvmf_cms_str() - Decode RDMA connection management service field
 * @cms: value to be decoded
 *
 * Decode the RDMA connection management service field in the discovery
 * log page entry.
 *
 * Return: decoded string
 */
const char *nvmf_cms_str(__u8 cms);

/**
 * nvmf_default_config() - Default values for fabrics configuration
 * @cfg: config values to set
 *
 * Initializes @cfg with default values.
 */
void nvmf_default_config(struct nvme_fabrics_config *cfg);

/**
 * nvmf_update_config() - Update fabrics configuration values
 * @c:          Controller to be modified
 * @cfg:        Updated configuration values
 *
 * Updates the values from @c with the configuration values from @cfg;
 * all non-default values from @cfg will overwrite the values in @c.
 */
void nvmf_update_config(nvme_ctrl_t c, const struct nvme_fabrics_config *cfg);

/**
 * nvmf_add_ctrl() - Connect a controller and update topology
 * @h:		Host to which the controller should be attached
 * @c:		Controller to be connected
 * @cfg:	Default configuration for the controller
 *
 * Issues a 'connect' command to the NVMe-oF controller and inserts @c
 * into the topology using @h as parent.
 * @c must be initialized and not connected to the topology.
 *
 * Return: 0 on success, or an error code on failure.
 */
int nvmf_add_ctrl(nvme_host_t h, nvme_ctrl_t c,
		  const struct nvme_fabrics_config *cfg);

/**
 * nvmf_connect_ctrl() - Connect a controller
 * @c:		Controller to be connected
 *
 * Issues a 'connect' command to the NVMe-oF controller.
 * @c must be initialized and not connected to the topology.
 *
 * Return: 0 on success, or an error code on failure.
 */
int nvmf_connect_ctrl(nvme_ctrl_t c);

/**
 * nvmf_get_discovery_log() - Return the discovery log page
 * @c:			Discovery controller to use
 * @logp:		Log page object to return
 * @max_retries:	Number of retries in case of failure
 *
 * The memory allocated for the log page and returned in @logp
 * must be freed by the caller using free().
 *
 * Note: Consider using nvmf_get_discovery_wargs() instead.
 *
 * Return: 0 on success, or an error code on failure.
 */
int nvmf_get_discovery_log(nvme_ctrl_t c, struct nvmf_discovery_log **logp,
			   int max_retries);

/**
 * struct nvme_get_discovery_args - Arguments for nvmf_get_discovery_wargs()
 * @c:			Discovery controller
 * @args_size:		Length of the structure
 * @max_retries:	Number of retries in case of failure
 * @result:		The command completion result from CQE dword0
 * @timeout:		Timeout in ms (default: NVME_DEFAULT_IOCTL_TIMEOUT)
 * @lsp:		Log specific field (See enum nvmf_log_discovery_lsp)
 */
struct nvme_get_discovery_args {
	nvme_ctrl_t c;
	int args_size;
	int max_retries;
	__u32 *result;
	__u32 timeout;
	__u8 lsp;
};

/**
 * nvmf_get_discovery_wargs() - Get the discovery log page with args
 * @args:	Argument structure
 * @log:	Discovery log page object to return
 *
 * This function is similar to nvmf_get_discovery_log(), but
 * takes an extensible @args parameter. @args provides more
 * options than nvmf_get_discovery_log().
 *
 * This function performs a get discovery log page (DLP) command
 * and returns the DLP. The memory allocated for the returned
 * DLP must be freed by the caller using free().
 *
 * Return: 0 on success, or an error code on failure.
 */
int nvmf_get_discovery_wargs(struct nvme_get_discovery_args *args,
			     struct nvmf_discovery_log **log);

/**
 * nvmf_hostnqn_generate() - Generate a machine specific host nqn
 * Returns: An nvm namespace qualified name string based on the machine
 * identifier, or NULL if not successful.
 */
char *nvmf_hostnqn_generate();

/**
 * nvmf_hostnqn_generate_from_hostid() - Generate a host nqn from host identifier
 * @hostid:		Host identifier
 *
 * If @hostid is NULL, the function generates it based on the machine
 * identifier.
 *
 * Return: On success, an NVMe Qualified Name for host identification. This
 * name is based on the given host identifier. On failure, NULL.
 */
char *nvmf_hostnqn_generate_from_hostid(char *hostid);

/**
 * nvmf_hostid_generate() - Generate a machine specific host identifier
 *
 * Return: On success, an identifier string based on the machine identifier to
 * be used as NVMe Host Identifier, or NULL on failure.
 */
char *nvmf_hostid_generate();

/**
 * nvmf_hostnqn_from_file() - Reads the host nvm qualified name from the config
 *			      default location
 *
 * Retrieve the qualified name from the config file located in $SYSCONFIDR/nvme.
 * $SYSCONFDIR is usually /etc.
 *
 * Return: The host nqn, or NULL if unsuccessful. If found, the caller
 * is responsible to free the string.
 */
char *nvmf_hostnqn_from_file();

/**
 * nvmf_hostid_from_file() - Reads the host identifier from the config default
 *			     location
 *
 * Retrieve the host idenditifer from the config file located in $SYSCONFDIR/nvme/.
 * $SYSCONFDIR is usually /etc.
 *
 * Return: The host identifier, or NULL if unsuccessful. If found, the caller
 *	   is responsible to free the string.
 */
char *nvmf_hostid_from_file();

/**
 * nvmf_is_registration_supported - check whether registration can be performed.
 * @c:	Controller instance
 *
 * Only discovery controllers (DC) that comply with TP8010 support
 * explicit registration with the DIM PDU. These can be identified by
 * looking at the value of a dctype in the Identify command
 * response. A value of 1 (DDC) or 2 (CDC) indicates that the DC
 * supports explicit registration.
 *
 * Return: true if controller supports explicit registration. false
 * otherwise.
 */
bool nvmf_is_registration_supported(nvme_ctrl_t c);

/**
 * nvmf_register_ctrl() - Perform registration task with a DC
 * @c:		Controller instance
 * @tas:	Task field of the Command Dword 10 (cdw10). Indicates whether to
 *		perform a Registration, Deregistration, or Registration-update.
 * @result:	The command-specific result returned by the DC upon command
 *		completion.
 *
 * Perform registration task with a Discovery Controller (DC). Three
 * tasks are supported: register, deregister, and registration update.
 *
 * Return: 0 on success, or an error code on failure.
 */
int nvmf_register_ctrl(nvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result);

/**
 * nvme_parse_uri() - Parse the URI string
 * @str:	URI string
 * @uri:	URI object to return
 *
 * Parse the URI string as defined in the NVM Express Boot Specification.
 * Supported URI elements looks as follows:
 *
 *   nvme+tcp://user@host:port/subsys_nqn/nid?query=val#fragment
 *
 * Return: &nvme_fabrics_uri structure on success; NULL on failure with errno
 * set.
 */
int nvme_parse_uri(const char *str, struct nvme_fabrics_uri **uri);

/**
 * nvme_free_uri() - Free the URI structure
 * @uri:	&nvme_fabrics_uri structure
 *
 * Free an &nvme_fabrics_uri structure.
 */
void nvme_free_uri(struct nvme_fabrics_uri *uri);

/**
 * nvmf_get_default_trsvcid() - Get default transport service ID
 * @transport: Transport type string (e.g., "tcp", "rdma")
 * @discovery_ctrl: True if for discovery controller, false otherwise
 *
 * Returns the default trsvcid (port) for the given transport and controller
 * type.
 *
 * Return: Allocated string with default trsvcid, or NULL on failure.
 */
const char *nvmf_get_default_trsvcid(const char *transport,
		bool discovery_ctrl);
/*
 * struct nvmf_context - Opaque context for fabrics operations
 *
 * Used to manage state and configuration for fabrics discovery and connect
 * operations.
 */
struct nvmf_context;

/**
 * nvmf_context_create() - Create a new fabrics context for discovery/connect
 * @ctx: Global context
 * @decide_retry: Callback to decide if a retry should be attempted
 * @connected: Callback invoked when a connection is established
 * @already_connected: Callback invoked if already connected
 * @user_data: User data passed to callbacks
 * @fctxp: Pointer to store the created context
 *
 * Allocates and initializes a new fabrics context for discovery/connect
 * operations.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_create(struct nvme_global_ctx *ctx,
		bool (*decide_retry)(struct nvmf_context *fctx, int err,
			void *user_data),
		void (*connected)(struct nvmf_context *fctx,
			struct nvme_ctrl *c, void *user_data),
		void (*already_connected)(struct nvmf_context *fctx,
			struct nvme_host *host, const char *subsysnqn,
			const char *transport, const char *traddr,
			const char *trsvcid, void *user_data),
		void *user_data, struct nvmf_context **fctxp);

/**
 * nvmf_context_set_discovery_cbs() - Set discovery callbacks for context
 * @fctx: Fabrics context
 * @discovery_log: Callback for discovery log events
 * @parser_init: Callback to initialize parser
 * @parser_cleanup: Callback to cleanup parser
 * @parser_next_line: Callback to parse next line
 *
 * Sets the callbacks used during discovery operations for the given context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_discovery_cbs(struct nvmf_context *fctx,
		void (*discovery_log)(struct nvmf_context *fctx,
			bool connect, struct nvmf_discovery_log *log,
			uint64_t numrec, void *user_data),
		int (*parser_init)(struct nvmf_context *fctx,
			void *user_data),
		void (*parser_cleanup)(struct nvmf_context *fctx,
			void *user_data),
		int (*parser_next_line)(struct nvmf_context *fctx,
			void *user_data));

/**
 * nvmf_context_set_discovery_defaults() - Set default discovery parameters
 * @fctx: Fabrics context
 * @max_discovery_retries: Maximum number of discovery retries
 * @keep_alive_timeout: Keep-alive timeout in seconds
 *
 * Sets default values for discovery retries and keep-alive timeout.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_discovery_defaults(struct nvmf_context *fctx,
		int max_discovery_retries, int keep_alive_timeout);

/**
 * nvmf_context_set_fabrics_config() - Set fabrics configuration for context
 * @fctx: Fabrics context
 * @cfg: Fabrics configuration to apply
 *
 * Applies the given fabrics configuration to the context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_fabrics_config(struct nvmf_context *fctx,
		struct nvme_fabrics_config *cfg);

/**
 * nvmf_context_set_connection() - Set connection parameters for context
 * @fctx: Fabrics context
 * @subsysnqn: Subsystem NQN
 * @transport: Transport type
 * @traddr: Transport address
 * @trsvcid: Transport service ID
 * @host_traddr: Host transport address
 * @host_iface: Host interface
 *
 * Sets the connection parameters for the context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_connection(struct nvmf_context *fctx,
		const char *subsysnqn, const char *transport,
		const char *traddr, const char *trsvcid,
		const char *host_traddr, const char *host_iface);

/**
 * nvmf_context_set_hostnqn() - Set host NQN and host ID for context
 * @fctx: Fabrics context
 * @hostnqn: Host NQN
 * @hostid: Host identifier
 *
 * Sets the host NQN and host ID for the context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_hostnqn(struct nvmf_context *fctx,
		const char *hostnqn, const char *hostid);

/**
 * nvmf_context_set_crypto() - Set cryptographic parameters for context
 * @fctx: Fabrics context
 * @hostkey: Host key
 * @ctrlkey: Controller key
 * @keyring: Keyring identifier
 * @tls_key: TLS key
 * @tls_key_identity: TLS key identity
 *
 * Sets cryptographic and TLS parameters for the context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_crypto(struct nvmf_context *fctx,
		const char *hostkey, const char *ctrlkey,
		const char *keyring, const char *tls_key,
		const char *tls_key_identity);

/**
 * nvmf_context_set_persistent() - Set persistence for context
 * @fctx: Fabrics context
 * @persistent: Whether to enable persistent connections
 *
 * Sets whether the context should use persistent connections.
 *
 * Return: 0 on success, or a negative error code on failure.
 */

int nvmf_context_set_persistent(struct nvmf_context *fctx, bool persistent);

/**
 * nvmf_context_set_device() - Set device for context
 * @fctx: Fabrics context
 * @device: Device path or identifier
 *
 * Sets the device to be used by the context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_context_set_device(struct nvmf_context *fctx, const char *device);

/**
 * nvmf_discovery() - Perform fabrics discovery
 * @ctx: Global context
 * @fctx: Fabrics context
 * @connect: Whether to connect discovered subsystems
 * @force: Force discovery even if already connected
 *
 * Performs discovery for fabrics subsystems and optionally connects.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_discovery(struct nvme_global_ctx *ctx,
		struct nvmf_context *fctx, bool connect, bool force);

/**
 * nvmf_discovery_config_json() - Perform discovery using JSON config
 * @ctx: Global context
 * @fctx: Fabrics context
 * @connect: Whether to connect discovered subsystems
 * @force: Force discovery even if already connected
 *
 * Performs discovery using a JSON configuration.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_discovery_config_json(struct nvme_global_ctx *ctx,
		struct nvmf_context *fctx, bool connect, bool force);

/**
 * nvmf_discovery_config_file() - Perform discovery using config file
 * @ctx: Global context
 * @fctx: Fabrics context
 * @connect: Whether to connect discovered subsystems
 * @force: Force discovery even if already connected
 *
 * Performs discovery using a configuration file.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_discovery_config_file(struct nvme_global_ctx *ctx,
		struct nvmf_context *fctx, bool connect, bool force);

/**
 * nvmf_discovery_nbft() - Perform discovery using NBFT
 * @ctx: Global context
 * @fctx: Fabrics context
 * @connect: Whether to connect discovered subsystems
 * @nbft_path: Path to NBFT file
 *
 * Performs discovery using the specified NBFT file.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_discovery_nbft(struct nvme_global_ctx *ctx,
		struct nvmf_context *fctx, bool connect, char *nbft_path);

/**
 * nvmf_connect() - Connect to fabrics subsystem
 * @ctx: Global context
 * @fctx: Fabrics context
 *
 * Connects to the fabrics subsystem using the provided context.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_connect(struct nvme_global_ctx *ctx, struct nvmf_context *fctx);

/**
 * nvmf_connect_config_json() - Connect using JSON config
 * @ctx: Global context
 * @fctx: Fabrics context
 *
 * Connects to the fabrics subsystem using a JSON configuration.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_connect_config_json(struct nvme_global_ctx *ctx,
		struct nvmf_context *fctx);

/**
 * nvmf_config_modify() - Modify and update the configurtion
 * @ctx: Global context
 * @fctx: Fabrics context
 *
 * Update the current configuration by adding the crypto
 * information.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_config_modify(struct nvme_global_ctx *ctx,
		struct nvmf_context *fctx);

/**
 * struct nbft_file_entry - Linked list entry for NBFT files
 * @next: Pointer to next entry
 * @nbft: Pointer to NBFT info structure
 */
struct nbft_file_entry {
	struct nbft_file_entry *next;
	struct nbft_info *nbft;
};

/**
 * nvmf_nbft_read_files() - Read NBFT files from path
 * @ctx: struct nvme_global_ctx object
 * @path: Path to NBFT files
 * @head: Pointer to store linked list of NBFT file entries
 *
 * Reads NBFT files from the specified path and populates a linked list.
 *
 * Return: 0 on success, or a negative error code on failure.
 */
int nvmf_nbft_read_files(struct nvme_global_ctx *ctx, char *path,
		struct nbft_file_entry **head);

/**
 * nvmf_nbft_free() - Free NBFT file entry list
 * @ctx: struct nvme_global_ctx object
 * @head: Head of the NBFT file entry list
 *
 * Frees all memory associated with the NBFT file entry list.
 */
void nvmf_nbft_free(struct nvme_global_ctx *ctx, struct nbft_file_entry *head);

#endif /* _LIBNVME_FABRICS_H */