diff options
Diffstat (limited to 'doc/rst')
| -rw-r--r-- | doc/rst/fabrics.rst | 24 | ||||
| -rw-r--r-- | doc/rst/linux.rst | 120 | ||||
| -rw-r--r-- | doc/rst/mi.rst | 33 | ||||
| -rw-r--r-- | doc/rst/types.rst | 101 |
4 files changed, 233 insertions, 45 deletions
diff --git a/doc/rst/fabrics.rst b/doc/rst/fabrics.rst index a7e0e60..bd4bd1d 100644 --- a/doc/rst/fabrics.rst +++ b/doc/rst/fabrics.rst @@ -27,6 +27,8 @@ Fabrics-specific definitions. int nr_write_queues; int nr_poll_queues; int tos; + int keyring; + int tls_key; bool duplicate_connect; bool disable_sqflow; bool hdr_digest; @@ -69,6 +71,12 @@ Fabrics-specific definitions. ``tos`` Type of service +``keyring`` + Keyring to store and lookup keys + +``tls_key`` + TLS PSK for the connection + ``duplicate_connect`` Allow multiple connections to the same target @@ -424,10 +432,16 @@ identifier, or NULL if not successful. .. c:function:: char * nvmf_hostnqn_from_file () - Reads the host nvm qualified name from the config default location in /usr/local/etc/nvme/ + Reads the host nvm qualified name from the config default location **Parameters** +**Description** + + +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 @@ -436,10 +450,16 @@ is responsible to free the string. .. c:function:: char * nvmf_hostid_from_file () - Reads the host identifier from the config default location in /usr/local/etc/nvme/. + Reads the host identifier from the config default location **Parameters** +**Description** + + +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 diff --git a/doc/rst/linux.rst b/doc/rst/linux.rst index 4f159f1..b437499 100644 --- a/doc/rst/linux.rst +++ b/doc/rst/linux.rst @@ -319,3 +319,123 @@ If key generation was successful the function returns 0 or -1 with errno set otherwise. +.. c:function:: long nvme_lookup_keyring (const char *keyring) + + Lookup keyring serial number + +**Parameters** + +``const char *keyring`` + Keyring name + +**Description** + +Looks up the serial number of the keyring **keyring**. + +**Return** + +The key serial number of the keyring +or 0 with errno set otherwise. + + +.. c:function:: char * nvme_describe_key_serial (long key_id) + + Return key description + +**Parameters** + +``long key_id`` + Key serial number + +**Description** + +Fetches the description of the key or keyring identified +by the serial number **key_id**. + +**Return** + +The description of **key_id** or NULL on failure. +The returned string needs to be freed by the caller. + + +.. c:function:: long nvme_lookup_key (const char *type, const char *identity) + + Lookup key serial number + +**Parameters** + +``const char *type`` + Key type + +``const char *identity`` + Key description + +**Description** + +Looks up the serial number of the key **identity** +with type ``type`` in the current session keyring. + +**Return** + +The key serial number of the key +or 0 with errno set otherwise. + + +.. c:function:: int nvme_set_keyring (long keyring_id) + + Link keyring for lookup + +**Parameters** + +``long keyring_id`` + Keyring id + +**Description** + +Links **keyring_id** into the session keyring such that +its keys are available for further key lookups. + +**Return** + +0 on success, a negative number on error +with errno set. + + +.. c:function:: long nvme_insert_tls_key (const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int hmac, unsigned char *configured_key, int key_len) + + Derive and insert TLS key + +**Parameters** + +``const char *keyring`` + Keyring to use + +``const char *key_type`` + Type of the resulting key + +``const char *hostnqn`` + Host NVMe Qualified Name + +``const char *subsysnqn`` + Subsystem NVMe Qualified Name + +``int hmac`` + HMAC algorithm + +``unsigned char *configured_key`` + Configured key data to derive the key from + +``int key_len`` + Length of **configured_key** + +**Description** + +Derives a 'retained' TLS key as specified in NVMe TCP 1.0a and +stores it as type **key_type** in the keyring specified by **keyring**. + +**Return** + +The key serial number if the key could be inserted into +the keyring or 0 with errno otherwise. + + diff --git a/doc/rst/mi.rst b/doc/rst/mi.rst index 7e82918..d43e3c6 100644 --- a/doc/rst/mi.rst +++ b/doc/rst/mi.rst @@ -1937,6 +1937,39 @@ See: :c:type:`struct nvme_secondary_ctrl_list <nvme_secondary_ctrl_list>` 0 on success, non-zero on failure +.. c:function:: int nvme_mi_admin_get_log_page (nvme_mi_ctrl_t ctrl, __u32 xfer_len, struct nvme_get_log_args *args) + + Retrieve log page data from controller + +**Parameters** + +``nvme_mi_ctrl_t ctrl`` + Controller to query + +``__u32 xfer_len`` + The chunk size of the read + +``struct nvme_get_log_args *args`` + Get Log Page command arguments + +**Description** + +Performs a Get Log Page Admin command as specified by **args**. Response data +is stored in **args->data**, which should be a buffer of **args->data_len** bytes. +Resulting data length is stored in **args->data_len** on successful +command completion. + +This request may be implemented as multiple log page commands, in order +to fit within MI message-size limits. + +See: :c:type:`struct nvme_get_log_args <nvme_get_log_args>` + +**Return** + +The nvme command status if a response was received (see +:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise. + + .. c:function:: int nvme_mi_admin_get_log (nvme_mi_ctrl_t ctrl, struct nvme_get_log_args *args) Retrieve log page data from controller diff --git a/doc/rst/types.rst b/doc/rst/types.rst index 0435c87..5262202 100644 --- a/doc/rst/types.rst +++ b/doc/rst/types.rst @@ -2756,8 +2756,8 @@ power scale value __u8 wzsl; __u8 wusl; __u8 dmrl; - __u32 dmrsl; - __u64 dmsl; + __le32 dmrsl; + __le64 dmsl; __u8 rsvd16[4080]; }; @@ -3148,7 +3148,7 @@ power scale value :: struct nvme_id_iocs { - __u64 iocsc[512]; + __le64 iocsc[512]; }; **Members** @@ -3298,10 +3298,12 @@ Supported Log Pages (Log Identifier 00h) __le32 nsid; __u8 vs; __u8 trtype; - __u8 rsvd[2]; + __u8 csi; + __u8 opcode; __le64 cs; __le16 trtype_spec_info; - __u8 rsvd2[22]; + __u8 rsvd[21]; + __u8 log_page_version; }; **Members** @@ -3377,8 +3379,14 @@ Supported Log Pages (Log Identifier 00h) is transport related, this field shall be set to the type of the transport - see :c:type:`enum nvme_trtype <nvme_trtype>`. -``rsvd`` - Reserved +``csi`` + Command Set Indicator: This field contains command set + indicator for the command that the error is associated + with. + +``opcode`` + Opcode: This field contains opcode for the command that + the error is associated with. ``cs`` Command Specific Information: This field contains command @@ -3388,8 +3396,12 @@ Supported Log Pages (Log Identifier 00h) ``trtype_spec_info`` Transport Type Specific Information -``rsvd2`` - Reserved +``rsvd`` + Reserved: [62:42] + +``log_page_version`` + This field shall be set to 1h. If set, **csi** and **opcode** + will have valid values. @@ -6286,15 +6298,15 @@ bytes, in size. This log captures the controller’s internal state. :: struct nvme_fdp_config_desc { - __u16 size; + __le16 size; __u8 fdpa; __u8 vss; - __u32 nrg; - __u16 nruh; - __u16 maxpids; - __u32 nnss; - __u64 runs; - __u32 erutl; + __le32 nrg; + __le16 nruh; + __le16 maxpids; + __le32 nnss; + __le64 runs; + __le32 erutl; __u8 rsvd28[36]; struct nvme_fdp_ruh_desc ruhs[]; }; @@ -6347,10 +6359,10 @@ bytes, in size. This log captures the controller’s internal state. :: struct nvme_fdp_config_log { - __u16 n; + __le16 n; __u8 version; __u8 rsvd3; - __u32 size; + __le32 size; __u8 rsvd8[8]; struct nvme_fdp_config_desc configs[]; }; @@ -6434,7 +6446,7 @@ bytes, in size. This log captures the controller’s internal state. :: struct nvme_fdp_ruhu_log { - __u16 nruh; + __le16 nruh; __u8 rsvd2[6]; struct nvme_fdp_ruhu_desc ruhus[]; }; @@ -6537,8 +6549,8 @@ bytes, in size. This log captures the controller’s internal state. struct nvme_fdp_event_realloc { __u8 flags; __u8 rsvd1; - __u16 nlbam; - __u64 lba; + __le16 nlbam; + __le64 lba; __u8 rsvd12[4]; }; @@ -6592,11 +6604,11 @@ bytes, in size. This log captures the controller’s internal state. struct nvme_fdp_event { __u8 type; __u8 flags; - __u16 pid; + __le16 pid; struct nvme_timestamp ts; - __u32 nsid; + __le32 nsid; __u8 type_specific[16]; - __u16 rgid; + __le16 rgid; __u8 ruhid; __u8 rsvd35[5]; __u8 vs[24]; @@ -6647,7 +6659,7 @@ bytes, in size. This log captures the controller’s internal state. :: struct nvme_fdp_events_log { - __u32 n; + __le32 n; __u8 rsvd4[60]; struct nvme_fdp_event events[63]; }; @@ -6676,7 +6688,7 @@ bytes, in size. This log captures the controller’s internal state. :: struct nvme_feat_fdp_events_cdw11 { - __u16 phndl; + __le16 phndl; __u8 noet; __u8 rsvd24; }; @@ -6745,10 +6757,10 @@ bytes, in size. This log captures the controller’s internal state. :: struct nvme_fdp_ruh_status_desc { - __u16 pid; - __u16 ruhid; - __u32 earutr; - __u64 ruamw; + __le16 pid; + __le16 ruhid; + __le32 earutr; + __le64 ruamw; __u8 rsvd16[16]; }; @@ -6783,7 +6795,7 @@ bytes, in size. This log captures the controller’s internal state. struct nvme_fdp_ruh_status { __u8 rsvd0[14]; - __u16 nruhsd; + __le16 nruhsd; struct nvme_fdp_ruh_status_desc ruhss[]; }; @@ -6925,7 +6937,7 @@ bytes, in size. This log captures the controller’s internal state. struct nvme_metadata_element_desc { __u8 type; __u8 rev; - __u16 len; + __le16 len; __u8 val[0]; }; @@ -7085,8 +7097,8 @@ bytes, in size. This log captures the controller’s internal state. __u8 type; __u8 attributes; __u8 rsvd2[14]; - __u64 slba; - __u64 nlb; + __le64 slba; + __le64 nlb; __u8 guid[16]; __u8 rsvd48[16]; }; @@ -7290,8 +7302,8 @@ bytes, in size. This log captures the controller’s internal state. __le16 nlb; __u8 rsvd18[6]; __le32 eilbrt; - __le16 elbatm; __le16 elbat; + __le16 elbatm; }; **Members** @@ -7312,12 +7324,12 @@ bytes, in size. This log captures the controller’s internal state. Expected Initial Logical Block Reference Tag / Expected Logical Block Storage Tag -``elbatm`` - Expected Logical Block Application Tag Mask - ``elbat`` Expected Logical Block Application Tag +``elbatm`` + Expected Logical Block Application Tag Mask + @@ -7336,8 +7348,8 @@ bytes, in size. This log captures the controller’s internal state. __le16 nlb; __u8 rsvd18[8]; __u8 elbt[10]; - __le16 elbatm; __le16 elbat; + __le16 elbatm; }; **Members** @@ -7358,12 +7370,12 @@ bytes, in size. This log captures the controller’s internal state. Expected Initial Logical Block Reference Tag / Expected Logical Block Storage Tag -``elbatm`` - Expected Logical Block Application Tag Mask - ``elbat`` Expected Logical Block Application Tag +``elbatm`` + Expected Logical Block Application Tag Mask + @@ -7632,6 +7644,9 @@ bytes, in size. This log captures the controller’s internal state. ``NVME_ID_DIR_SD_BIT`` Streams directive is supported +``NVME_ID_DIR_DP_BIT`` + Direct Placement directive is supported + @@ -7876,7 +7891,7 @@ bytes, in size. This log captures the controller’s internal state. __u8 prtype; __u8 cms; __u8 rsvd3[5]; - __u16 pkey; + __le16 pkey; __u8 rsvd10[246]; } rdma; struct tcp { |