Added documentation on the file format

Signed-off-by: Benoit PAPILLAULT <benoit.papillault@free.fr>
Signed-off-by: Luis R. Rodriguez <lrodriguez@atheros.com>

diff --git a/regdb.h b/regdb.h
index e658f8a..09cc403 100644 (file)
--- a/regdb.h
+++ b/regdb.h
@@ -21,6 +21,8 @@
  * SHA-1 hash of the file.
  */
 
+/* db file starts with a struct regdb_file_header */
+
 struct regdb_file_header {
        /* must be REGDB_MAGIC */
        __be32  magic;
@@ -30,7 +32,8 @@ struct regdb_file_header {
         * Pointer (offset) into file where country list starts
         * and number of countries. The country list is sorted
         * alphabetically to allow binary searching (should it
-        * become really huge.)
+        * become really huge). Each country is described by a
+        * struct regdb_file_reg_country.
         */
        __be32  reg_country_ptr;
        __be32  reg_country_num;
@@ -39,9 +42,9 @@ struct regdb_file_header {
 };
 
 struct regdb_file_freq_range {
-       __be32  start_freq,
-               end_freq,
-               max_bandwidth;
+       __be32  start_freq,     /* in kHz */
+               end_freq,       /* in kHz */
+               max_bandwidth;  /* in kHz */
 };
 
 /*
@@ -55,36 +58,44 @@ struct regdb_file_power_rule {
        __be32  max_eirp;
 };
 
+/* must match <linux/nl80211.h> enum nl80211_reg_rule_flags */
+
 enum reg_rule_flags {
-       RRF_NO_OFDM             = 1<<0,
-       RRF_NO_CCK              = 1<<1,
-       RRF_NO_INDOOR           = 1<<2,
-       RRF_NO_OUTDOOR          = 1<<3,
-       RRF_DFS                 = 1<<4,
-       RRF_PTP_ONLY            = 1<<5,
-       RRF_PTMP_ONLY           = 1<<6,
-       RRF_PASSIVE_SCAN        = 1<<7,
-       RRF_NO_IBSS             = 1<<8,
+       RRF_NO_OFDM             = 1<<0, /* OFDM modulation not allowed */
+       RRF_NO_CCK              = 1<<1, /* CCK modulation not allowed */
+       RRF_NO_INDOOR           = 1<<2, /* indoor operation not allowed */
+       RRF_NO_OUTDOOR          = 1<<3, /* outdoor operation not allowed */
+       RRF_DFS                 = 1<<4, /* DFS support is required to be
+                                        * used */
+       RRF_PTP_ONLY            = 1<<5, /* this is only for Point To Point
+                                        * links */
+       RRF_PTMP_ONLY           = 1<<6, /* this is only for Point To Multi
+                                        * Point links */
+       RRF_PASSIVE_SCAN        = 1<<7, /* passive scan is required */
+       RRF_NO_IBSS             = 1<<8, /* IBSS is not allowed */
 };
 
 struct regdb_file_reg_rule {
        /* pointers (offsets) into the file */
-       __be32  freq_range_ptr,
-               power_rule_ptr;
-       /* rule flags */
+       __be32  freq_range_ptr; /* pointer to a struct regdb_file_freq_range */
+       __be32  power_rule_ptr; /* pointer to a struct regdb_file_power_rule */
+       /* rule flags using enum reg_rule_flags */
        __be32 flags;
 };
 
 struct regdb_file_reg_rules_collection {
        __be32  reg_rule_num;
-       /* pointers (offsets) into the file */
+       /* pointers (offsets) into the file. There are reg_rule_num elements
+        * in the reg_rule_ptrs array pointing to struct
+        * regdb_file_reg_rule */
        __be32  reg_rule_ptrs[];
 };
 
 struct regdb_file_reg_country {
        __u8    alpha2[2];
        __u8    PAD[2];
-       /* pointer (offset) into the file */
+       /* pointer (offset) into the file to a struct
+        * regdb_file_reg_rules_collection */
        __be32  reg_collection_ptr;
 };