Improve SSL doc about I/O and timeouts
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index f9bf8df..4d717e5 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -1195,7 +1195,8 @@
*
* \note For DTLS, you must either provide a recv callback that
* doesn't block, or one that handles timeouts, see
- * mbedtls_ssl_conf_bio()
+ * \c mbedtls_ssl_set_bio(). You also need to provide timer
+ * callbacks with \c mbedtls_ssl_set_timer_cb().
*
* \param conf SSL configuration
* \param transport transport type:
@@ -1279,12 +1280,18 @@
* \param f_send write callback
* \param f_recv read callback
* \param f_recv_timeout blocking read callback with timeout.
- * The last argument of the callback is the timeout in seconds
+ * The last argument is the timeout in milliseconds
*
- * \note f_recv_timeout is required for DTLS, unless f_recv performs
- * non-blocking reads.
+ * \note One of f_recv or f_recv_timeout can be NULL, in which case
+ * the other is used. If both are non-NULL, f_recv_timeout is
+ * used and f_recv is ignored (as if it were NULL).
*
- * \note TODO: timeout not supported with TLS yet
+ * \note The two most common use cases are:
+ * - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
+ * - blocking I/O, f_recv == NULL, f_recv_timout != NULL
+ *
+ * \note For DTLS, you need to provide either a non-NULL
+ * f_recv_timeout callback, or a f_recv that doesn't block.
*/
void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
void *p_bio,
@@ -1302,6 +1309,11 @@
*
* \note With blocking I/O, this will only work if a non-NULL
* \c f_recv_timeout was set with \c mbedtls_ssl_set_bio().
+ * With non-blocking I/O, this will only work if timer
+ * callbacks were set with \c mbedtls_ssl_set_timer_cb().
+ *
+ * \note With non-blocking I/O, you may also skip this function
+ * altogether and handle timeouts at the application layer.
*/
void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout );