Clarify timeout and RTT documentation

Fix #2904. Signed-off-by: Steven Bellock <[email protected]>
DMTF · Dec 2, 2024 · c0b2cbc · c0b2cbc
1 parent cb93d7a
commit c0b2cbc
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 42 deletions.
diff --git 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
@@ -473,69 +473,56 @@ 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,
                                                              const void *message,
                                                              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.