Enhanced the documentation.

core/dev/radio.h

@@ -49,6 +49,9 @@
  *         Header file for the radio API
  * \author
  *         Adam Dunkels <adam@sics.se>
+ *         Joakim Eriksson <joakime@sics.se>
+ *         Niclas Finne <nfi@sics.se>
+ *         Nicolas Tsiftes <nvt@sics.se>
  */
 
 #ifndef RADIO_H_
@@ -56,28 +59,106 @@
 
 #include <stddef.h>
 
+/**
+ * Each radio has a set of parameters that designate the current
+ * configuration and state of the radio. Parameters can either have
+ * values of type radio_value_t, or, when this type is insufficient, a
+ * generic object that is specified by a memory pointer and the size
+ * of the object.
+ *
+ * The radio_value_t type is set to an integer type that can hold most
+ * values used to configure the radio, and is therefore the most
+ * common type used for a parameter. Certain parameters require
+ * objects of a considerably larger size than radio_value_t, however,
+ * and in these cases the documentation below for the parameter will
+ * indicate this.
+ *
+ * All radio parameters that can vary during runtime are prefixed by
+ * "RADIO_PARAM", whereas those "parameters" that are guaranteed to
+ * remain immutable are prefixed by "RADIO_CONST". Each mutable
+ * parameter has a set of valid parameter values. When attempting to
+ * set a parameter to an invalid value, the radio will return
+ * RADIO_RESULT_INVALID_VALUE.
+ *
+ * Some radios support only a subset of the defined radio parameters.
+ * When trying to set or get such an unsupported parameter, the radio
+ * will return RADIO_RESULT_NOT_SUPPORTED.
+ */
+
 typedef int radio_value_t;
 typedef unsigned radio_param_t;
 
 enum {
+
+  /* Radio power mode determines if the radio is on
+    (RADIO_POWER_MODE_ON) or off (RADIO_POWER_MODE_OFF). */
   RADIO_PARAM_POWER_MODE,
+
+  /*
+   * Channel used for radio communication. The channel depends on the
+   * communication standard used by the radio. The values can range
+   * from RADIO_CONST_CHANNEL_MIN to RADIO_CONST_CHANNEL_MAX.
+   */
   RADIO_PARAM_CHANNEL,
+
+  /* Personal area network identifier, which is used by the address filter. */
   RADIO_PARAM_PAN_ID,
+
+  /* Short address (16 bits) for the radio, which is used by the address
+     filter. */
   RADIO_PARAM_16BIT_ADDR,
-  /** Address handler take care of address filtering and sending autoack */
+
+  /* Address handler take care of address filtering and sending auto-ACK.
+    (See below for more information.) */
   RADIO_PARAM_ADDRESS_HANDLER,
-  /** Transmission power in dBm */
+
+  /*
+   * Transmission power in dBm. The values can range from
+   * RADIO_CONST_TXPOWER_MIN to RADIO_CONST_TXPOWER_MAX.
+   *
+   * Some radios restrict the available values to a subset of this
+   * range.  If an unavailable TXPOWER value is requested to be set,
+   * the radio may select another TXPOWER close to the requested
+   * one. When getting the value of this parameter, the actual value
+   * used by the radio will be returned.
+   */
   RADIO_PARAM_TXPOWER,
-  /** Received signal strength in dBm */
+
+  /*
+   * Clear channel assessment threshold in dBm. This threshold
+   * determines the minimum RSSI level at which the radio will assume
+   * that there is a packet in the air.
+   *
+   * The CCA threshold must be set to a level above the noise floor of
+   * the deployment. Otherwise mechanisms such as send-on-CCA and
+   * low-power-listening duty cycling protocols may not work
+   * correctly. Hence, the default value of the system may not be
+   * optimal for any given deployment.
+   */
+  RADIO_PARAM_CCA_THRESHOLD,
+
+  /* Received signal strength indicator in dBm. */
   RADIO_PARAM_RSSI,
 
-  /** 64 bit addresses need to be used with radio.get_object()/set_object() */
+  /*
+   * Long (64 bits) address for the radio, which is used by the address filter.
+   * The address is specified in network byte order.
+   *
+   * Because this parameter value is larger than what fits in radio_value_t,
+   * it needs to be used with radio.get_object()/set_object().
+   */
   RADIO_PARAM_64BIT_ADDR,
 
-  /** Constants (read only) */
+  /* Constants (read only) */
+
+  /* The lowest radio channel. */
   RADIO_CONST_CHANNEL_MIN,
+  /* The highest radio channel. */
   RADIO_CONST_CHANNEL_MAX,
+
+  /* The minimum transmission power in dBm. */
   RADIO_CONST_TXPOWER_MIN,
+  /* The maximum transmission power in dBm. */
   RADIO_CONST_TXPOWER_MAX
 };
 
@@ -87,9 +168,22 @@ enum {
   RADIO_POWER_MODE_ON
 };
 
-/* Bit flags for the address handler */
+/**
-#define RADIO_ADDRESS_HANDLER_FILTER  1
+ * The address handler is an abstraction responsible for address
-#define RADIO_ADDRESS_HANDLER_AUTOACK 2
+ * filtering and automatic transmission of acknowledgements in the
+ * radio (if such operations are supported by the radio).
+ *
+ * There are different options that can be used like address filter
+ * on/off, autoack on/off. A single parameter is used to set them
+ * simultaneous as an atomic operation.
+ *
+ * To enable both address filter and transmissions of autoack:
+ *
+ * NETSTACK_RADIO.set_value(RADIO_PARAM_ADDRESS_HANDLER,
+ *       RADIO_ADDRESS_HANDLER_FILTER | RADIO_ADDRESS_HANDLER_AUTOACK);
+ */
+#define RADIO_ADDRESS_HANDLER_FILTER  (1 << 0)
+#define RADIO_ADDRESS_HANDLER_AUTOACK (1 << 1)
 
 /* Radio return values when setting or getting radio parameters. */
 typedef enum {
@@ -99,6 +193,14 @@ typedef enum {
   RADIO_RESULT_ERROR
 } radio_result_t;
 
+/* Radio return values for transmissions. */
+enum {
+  RADIO_TX_OK,
+  RADIO_TX_ERR,
+  RADIO_TX_COLLISION,
+  RADIO_TX_NOACK,
+};
+
 /**
  * The structure of a device driver for a radio in Contiki.
  */
@@ -134,31 +236,28 @@ struct radio_driver {
   /** Turn the radio off. */
   int (* off)(void);
 
-  /** Get a radio parameter */
+  /** Get a radio parameter value. */
   radio_result_t (* get_value)(radio_param_t param, radio_value_t *value);
 
-  /** Set a radio parameter */
+  /** Set a radio parameter value. */
   radio_result_t (* set_value)(radio_param_t param, radio_value_t value);
 
-  /** Get a radio object (for example a 64 bit address) */
+  /**
+   * Get a radio parameter object. The argument 'dest' must point to a
+   * memory area of at least 'size' bytes, and this memory area will
+   * contain the parameter object if the function succeeds.
+   */
   radio_result_t (* get_object)(radio_param_t param, void *dest, size_t size);
 
-  /** Set a radio object (for example a 64 bit address). The data
+  /**
-      is copied and the object memory will not be accessed after the call.
+   * Set a radio parameter object. The memory area referred to by the
+   * argument 'src' will not be accessed after the function returns.
    */
   radio_result_t (* set_object)(radio_param_t param, const void *src,
                                 size_t size);
 
 };
 
-/* Generic radio return values. */
-enum {
-  RADIO_TX_OK,
-  RADIO_TX_ERR,
-  RADIO_TX_COLLISION,
-  RADIO_TX_NOACK,
-};
-
 #endif /* RADIO_H_ */