From 36d9d4a84661418e0f088d3ab91c369a536459c6 Mon Sep 17 00:00:00 2001
From: Simon Duquennoy <simon.duquennoy@yanzinetworks.com>
Date: Sun, 24 Feb 2019 16:05:21 +0100
Subject: [PATCH] Radio API: document TSCH-related radio constants

---
 arch/cpu/cc2538/dev/cc2538-rf.c |  1 +
 arch/dev/cc1200/cc1200.c        |  1 +
 arch/platform/zoul/platform.c   |  1 +
 os/dev/radio.h                  | 15 +++++++++++++++
 4 files changed, 18 insertions(+)

diff --git a/arch/cpu/cc2538/dev/cc2538-rf.c b/arch/cpu/cc2538/dev/cc2538-rf.c
index e3a548067..7fd40afdc 100644
--- a/arch/cpu/cc2538/dev/cc2538-rf.c
+++ b/arch/cpu/cc2538/dev/cc2538-rf.c
@@ -1031,6 +1031,7 @@ get_object(radio_param_t param, void *dest, size_t size)
     if(size != sizeof(uint16_t *) || !dest) {
       return RADIO_RESULT_INVALID_VALUE;
     }
+    /* Assigned value: a pointer to the TSCH timing in usec */
     *(const uint16_t **)dest = tsch_timeslot_timing_us_10000;
     return RADIO_RESULT_OK;
   }
diff --git a/arch/dev/cc1200/cc1200.c b/arch/dev/cc1200/cc1200.c
index dd90fdda7..50babb93d 100644
--- a/arch/dev/cc1200/cc1200.c
+++ b/arch/dev/cc1200/cc1200.c
@@ -1449,6 +1449,7 @@ get_object(radio_param_t param, void *dest, size_t size)
     if(size != sizeof(uint16_t *) || !dest) {
       return RADIO_RESULT_INVALID_VALUE;
     }
+    /* Assigned value: a pointer to the TSCH timing in usec */
     *(const uint16_t **)dest = CC1200_RF_CFG.tsch_timing;
     return RADIO_RESULT_OK;
   }
diff --git a/arch/platform/zoul/platform.c b/arch/platform/zoul/platform.c
index bed948829..49158b5b4 100644
--- a/arch/platform/zoul/platform.c
+++ b/arch/platform/zoul/platform.c
@@ -295,6 +295,7 @@ radio_delay_before_detect(void) {
 uint16_t *
 radio_tsch_timeslot_timing(void) {
   uint16_t *ret;
+  /* Get and return pointer to TSCH timings in usec */
   NETSTACK_RADIO.get_object(RADIO_CONST_TSCH_TIMING, &ret, sizeof(ret));
   return ret;
 }
diff --git a/os/dev/radio.h b/os/dev/radio.h
index e279e9efe..4cb266608 100644
--- a/os/dev/radio.h
+++ b/os/dev/radio.h
@@ -185,11 +185,26 @@ enum {
   /* The maximum transmission power in dBm. */
   RADIO_CONST_TXPOWER_MAX,
 
+  /* A pointer to TSCH timings in micro-seconds (tsch_timeslot_timing_usec *) */
   RADIO_CONST_TSCH_TIMING,
+
+  /* The physical layer header+footer overhead in bytes, after SFD.
+   * On IEEE 802.15.4 at 2.4 GHz: 1 byte for len + 2 for CRC => 3 */
   RADIO_CONST_PHY_OVERHEAD,
+
+  /* The air time of one byte in usec, e.g. 32 for IEEE 802.15.4 at 2.4 GHz */
   RADIO_CONST_BYTE_AIR_TIME,
+
+  /* The delay in usec between a call to the radio API's transmit function and
+   * the end of SFD transmission */
   RADIO_CONST_DELAY_BEFORE_TX,
+
+  /* The delay in usec between turning on the radio and it being actually
+   * listening (able to hear a preamble) */
   RADIO_CONST_DELAY_BEFORE_RX,
+
+  /* The delay in usec between the end of SFD reception for an incoming frame
+   * and the radio API starting to return receiving_packet() != 0 */
   RADIO_CONST_DELAY_BEFORE_DETECT,
 };