From c0b2cbce24451dc9e2aa150b91e91b961e23992b Mon Sep 17 00:00:00 2001 From: Steven Bellock Date: Tue, 26 Nov 2024 09:14:28 -0800 Subject: [PATCH] Clarify timeout and RTT documentation Fix #2904. Signed-off-by: Steven Bellock --- doc/api/common_api.md | 12 ++++-- include/library/spdm_common_lib.h | 65 +++++++++++++------------------ 2 files changed, 35 insertions(+), 42 deletions(-) diff --git a/doc/api/common_api.md b/doc/api/common_api.md index 2a94c019284..188d2ab2eac 100644 --- a/doc/api/common_api.md +++ b/doc/api/common_api.md @@ -113,11 +113,17 @@ Enumeration value used for the `libspdm_set_data` and/or `libspdm_get_data` func - The `CTExponent` value of the peer endpoint. - `LIBSPDM_DATA_LOCATION_LOCAL` - The `CTExponent` value of the local endpoint. -- `LIBSPDM_DATA_CAPABILITY_RTT` +- `LIBSPDM_DATA_CAPABILITY_RTT_US` - The SPDM specification defines this value (`RTT`) as "the worst-case round-trip transport - timing." and is in units of microseconds. This value is only used by a Requester. + timing." and is in units of microseconds. This value is only used by a Requester and is used + in the following scenarios. + - It is the value of the `timeout` argument in `libspdm_device_send_message_func`. When + sending a message this is a worst-case value, and the implementor of the function is free + to reduce the timeout value based on knowledge of the underlying transport. + - It is added to the Responder's `CT` or `ST1` value and passed via the `timeout` argument + in `libspdm_device_receive_message_func`. - `LIBSPDM_DATA_LOCATION_LOCAL` - - The `RTT` of the Requester endpoint. + - The `RTT` value as measured by the Requester endpoint. - `LIBSPDM_DATA_MEASUREMENT_SPEC` - This value specifies the measurement specification(s) supported by an endpoint. These are are communicated through the `NEGOTIATE_ALGORITHMS / ALGORITHMS` messages. However the SPDM diff --git a/include/library/spdm_common_lib.h b/include/library/spdm_common_lib.h index 687d57d46c6..48116e1e220 100644 --- a/include/library/spdm_common_lib.h +++ b/include/library/spdm_common_lib.h @@ -473,31 +473,24 @@ size_t libspdm_get_context_size(void); size_t libspdm_get_context_size_without_secured_context(void); /** - * Send an SPDM transport layer message to a device. + * Send an SPDM transport layer message to an endpoint. * - * The message is an SPDM message with transport layer wrapper, - * or a secured SPDM message with transport layer wrapper. + * The message is an SPDM message with transport layer wrapper, or a secured SPDM message with + * transport layer wrapper. * - * For requester, the message is a transport layer SPDM request. - * For responder, the message is a transport layer SPDM response. + * For Requester, the message is a transport layer SPDM request. + * For Responder, the message is a transport layer SPDM response. * * @param spdm_context A pointer to the SPDM context. - * @param message_size Size in bytes of the message data buffer. + * @param message_size Size, in bytes, of the message data buffer. * @param message A pointer to a destination buffer to store the message. * The caller is responsible for having either implicit or explicit ownership * of the buffer. The message pointer shall be inside of * [msg_buf_ptr, msg_buf_ptr + max_msg_size] from acquired sender_buffer. - * @param timeout The timeout, in us units, to use for the execution of the message. A - * timeout value of 0 means that this function will wait indefinitely for the - * message to execute. If timeout is greater than zero, then this function - * will return RETURN_TIMEOUT if the time required to execute the message is - * greater than timeout. - * - * @retval RETURN_SUCCESS The SPDM message is sent successfully. - * @retval RETURN_DEVICE_ERROR A device error occurs when the SPDM message is sent to the device. - * @retval RETURN_INVALID_PARAMETER The message is NULL or the message_size is zero. - * @retval RETURN_TIMEOUT A timeout occurred while waiting for the SPDM message - * to execute. + * @param timeout The timeout, in microsends, to use for the execution of the message. + * If called in a Requester context then timeout is equal to RTT. + * If called in a Responder context then timeout is equal to 0 and Responder + * should not timeout when sending the message. **/ typedef libspdm_return_t (*libspdm_device_send_message_func)(void *spdm_context, size_t message_size, @@ -505,37 +498,31 @@ typedef libspdm_return_t (*libspdm_device_send_message_func)(void *spdm_context, uint64_t timeout); /** - * Receive an SPDM transport layer message from a device. + * Receive an SPDM transport layer message from an endpoint. * - * The message is an SPDM message with transport layer wrapper, - * or a secured SPDM message with transport layer wrapper. + * The message is an SPDM message with transport layer wrapper or a secured SPDM message with + * transport layer wrapper. * - * For requester, the message is a transport layer SPDM response. - * For responder, the message is a transport layer SPDM request. + * For Requester, the message is a transport layer SPDM response. + * For Responder, the message is a transport layer SPDM request. * * @param spdm_context A pointer to the SPDM context. - * @param message_size Size in bytes of the message data buffer. + * @param message_size Size, in bytes, of the message data buffer. * @param message A pointer to a destination buffer to store the message. * The caller is responsible for having either implicit or explicit ownership * of the buffer. On input, the message pointer shall be msg_buf_ptr from * acquired receiver_buffer. On output, the message pointer shall be inside of * [msg_buf_ptr, msg_buf_ptr + max_msg_size] from acquired receiver_buffer. - * @param timeout The timeout, in us units, to use for the execution of the message. A - * timeout value of 0 means that this function will wait indefinitely for the - * message to execute. If timeout is greater than zero, then this function - * will return RETURN_TIMEOUT if the time required to execute the message is - * greater than timeout. - * - * @retval RETURN_SUCCESS The SPDM message is received successfully. - * @retval RETURN_DEVICE_ERROR A device error occurs when the SPDM message is received from the device. - * @retval RETURN_INVALID_PARAMETER The message is NULL, message_size is NULL or - * the *message_size is zero. - * @retval RETURN_TIMEOUT A timeout occurred while waiting for the SPDM message - * to execute. - **/ -typedef libspdm_return_t (*libspdm_device_receive_message_func)( - void *spdm_context, size_t *message_size, void **message, - uint64_t timeout); + * @param timeout The timeout, in microsends, to use for the execution of the message. + * If called in a Requester context then timeout is equal to RTT plus either + * CT or ST1. + * If called in a Responder context then timeout is equal to 0 and Responder + * should not timeout when receiving the message. + **/ +typedef libspdm_return_t (*libspdm_device_receive_message_func)(void *spdm_context, + size_t *message_size, + void **message, + uint64_t timeout); /** * Register SPDM device input/output functions.