Radio API: document TSCH-related radio constants

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;
   }

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;
   }

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;
 }

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,
 };