Documentation rewording

Signed-off-by: TRodziewicz <tomasz.rodziewicz@mobica.com>

ChangeLog.d/issue4083.txt

@@ -1,5 +1,4 @@
-Changes
+Removals
-    * Remove the following functions: mbedtls_timing_self_test() and
+    * Remove the following functions: mbedtls_timing_self_test(),
-      mbedtls_hardclock_poll(). Move the following functions to the benchmark.c
+      mbedtls_hardclock_poll(), mbedtls_timing_hardclock() and
-      file and make them static: mbedtls_timing_hardclock() and
       mbedtls_set_alarm(). Fixes #4083.

docs/3.0-migration-guide.d/move_part_of_timing_module_out_of_the_library.md

@@ -5,8 +5,5 @@ The change affects users who use any of the following functions:
 `mbedtls_timing_self_test()`, `mbedtls_hardclock_poll()`,
 `mbedtls_timing_hardclock()` and `mbedtls_set_alarm()`.
 
-This change is the first step of a plan of removal of the `timing.c` from the
+If you were relying on these functions, you'll now need to change to using your
-library. The plan is to move all the timing functions to the `platform.c` file.
+platform's corresponding functions directly.
-
-For users who still need removed functions the migration path is to re-implement
-them as a platform support code.

include/mbedtls/config.h

@@ -1013,8 +1013,7 @@
 /**
  * \def MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES
  *
- * Do not add default entropy sources. These are the platform specific
+ * Do not add default entropy sources in mbedtls_entropy_init().
- * poll function.
  *
  * This is useful to have more control over the added entropy sources in an
  * application.

include/mbedtls/timing.h

@@ -63,25 +63,7 @@ typedef struct mbedtls_timing_delay_context
 
 extern volatile int mbedtls_timing_alarmed;
 
-/**
+/* Internal use */
- * \brief          Return the elapsed time in milliseconds
- *
- * \warning        May change without notice
- *
- * \param val      points to a timer structure
- * \param reset    If 0, query the elapsed time. Otherwise (re)start the timer.
- *
- * \return         Elapsed time since the previous reset in ms. When
- *                 restarting, this is always 0.
- *
- * \note           To initialize a timer, call this function with reset=1.
- *
- *                 Determining the elapsed time and resetting the timer is not
- *                 atomic on all platforms, so after the sequence
- *                 `{ get_timer(1); ...; time1 = get_timer(1); ...; time2 =
- *                 get_timer(0) }` the value time1+time2 is only approximately
- *                 the delay since the first reset.
- */
 unsigned long mbedtls_timing_get_timer( struct mbedtls_timing_hr_time *val, int reset );
 
 /**

library/timing.c

@@ -83,6 +83,25 @@ unsigned long mbedtls_timing_get_timer( struct mbedtls_timing_hr_time *val, int
 
 #else /* _WIN32 && !EFIX64 && !EFI32 */
 
+/**
+ * \brief          Return the elapsed time in milliseconds
+ *
+ * \warning        May change without notice
+ *
+ * \param val      points to a timer structure
+ * \param reset    If 0, query the elapsed time. Otherwise (re)start the timer.
+ *
+ * \return         Elapsed time since the previous reset in ms. When
+ *                 restarting, this is always 0.
+ *
+ * \note           To initialize a timer, call this function with reset=1.
+ *
+ *                 Determining the elapsed time and resetting the timer is not
+ *                 atomic on all platforms, so after the sequence
+ *                 `{ get_timer(1); ...; time1 = get_timer(1); ...; time2 =
+ *                 get_timer(0) }` the value time1+time2 is only approximately
+ *                 the delay since the first reset.
+ */
 unsigned long mbedtls_timing_get_timer( struct mbedtls_timing_hr_time *val, int reset )
 {
     struct _hr_time *t = (struct _hr_time *) val;