--- wireless.17.h.bak 2005-02-04 20:28:03.000000000 -0500 +++ wireless.17.h 2005-02-04 21:29:26.000000000 -0500 @@ -184,6 +184,108 @@ * - Add support for relative TxPower (yick !) */ +/* + * Explanation of WIRELESS QUALITY + * ------------------------------- + * + * Wireless quality is may be measured in two methods, drivers must PICK ONE + * and use it consistently throughout the driver->userspace API: + * + * 1) The first, required by the 802.11b specification, is Relative Signal + * Strength Indicator (RSSI), which is number between 0 and MAX_RSSI + * inclusive. Manufacturers use different numbers for MAX_RSSI, though MAX_RSSI + * cannot be larger than 255. For qualities measured in RSSI, the lower bound + * is _always_ 0, and the upper bound is _always_ MAX_RSSI. + * + * 2) The second measure is decibel millivolts, or dBm. This is calculated from + * the RSSI of each packet based on lookup tables or conversion constants + * specified by each manufacturer. dBm is an absolute measurement of electrical + * power generated by the radio signals in the receive circuitry of the card. + * It is expressed in _negative_ numbers, where 0dBm = 1mV. The upper bound + * is _always_ 0, and the lower bound is determined by the receiver sensitivity + * of the electrical equipment on the card. + * + * If the driver does not know what value to put in a field, it MUST indicate + * that the field is invalid by bitwise-OR-ing the .updated field with the + * appropriate IW_QUAL_*_INVALID constant specified below. Simply setting the + * field to 0 is not sufficient to specify that the value is unknown. + * + * + * The 'qual' fields are method independent, and are specified as follows: + * + * max_qual.qual: (range is 0 -> 255) upper bound of subjective quality + * levels. Other .qual fields MUST be less than this number. + * + * qual.qual: (range is 0 -> max_qual.qual) Quality of the received packet + * as determined by the driver. The only restriction is that + * user applications MUST be able to derive a percentage value + * by doing the following calculation: + * percent = 100 * (qual.qual / max_qual.qual) + * Drivers may factor other statistics, such as receive packet + * errors, # collisions, noise levels, etc, into the value. + * + * Once a driver has PICKED ONE method of measurement, the quality fields must + * be filled as follows. Remember, all fields are 8-bits wide and are treated + * as signed or unsigned based on the method of quality measurement above. + * + * + * RSSI METHOD (set max_qual.level > 0 as explained below) + *-------------------------------------------------------- + * max_qual.level: (range is 1 -> 255) upper bound of the RSSI of any received + * packet, determined by the card's hardware. Usually + * specified in technical literature from manufacturer, or + * provided by registers on the card. + * NOTE: to specify that values are in RSSI, max_qual.level + * MUST be larger than 0. + * + * max_qual.noise: (range is 0 -> 255) lower bound of noise, ie the received + * signal must not drop below this level or it cannot be + * distinguished. Usually specified by the manufacturer. If + * hardware does not provide per-packet noise information, then + * there MUST be a value in this field. + * + * qual.level: (range is 0 -> max_qual.level) actual RSSI taken from + * the receiver hardware for each packet. + * + * qual.noise: (range is 0 -> max_qual.level) noise RSSI value taken from + * the receive hardware in RSSI for each packet. If hardware + * does not provide this value for each packet, set to 0 and + * set 'qual.updated |= IW_QUAL_NOISE_INVALID'. You must then + * provide a value in max_qual.noise instead. + * + * In the RSSI method, values are _always_ positive numbers. + * + * + * dBm METHOD (set max_qual.level = 0) + *------------------------------------ + * max_qual.level MUST be set to 0 to specify dBm method + * + * max_qual.noise (range is -255 -> 0) lower bound of noise in dBm, signal dBm + * may not drop below this level or the signal cannot be + * distinguished from background noise by the receiver. + * Usually specified by the manufacturer. If hardware does not + * provide per-packet noise information, then there MUST be a + * value in this field. + * + * qual.level (range is max_qual.noise -> 0) signal level in dBm taken + * from the receiver hardware for each packet. + * + * qual.noise (range is max_qual.noise -> 0) noise level in dBm taken from + * the receiver hardware for each packet. If hardware + * does not provide this value for each packet, set to 0 and + * set 'qual.updated |= IW_QUAL_NOISE_INVALID'. You must then + * provide a value in max_qual.noise instead. + * + * In the dBm METHOD, values are _always_ negative numbers (or 0). Even though + * the actual fields themselves are 8-bit unsigned, the numbers are treated as + * negative, where 0x100 == 256 == 0. Values are passed to user applications + * after being added to 256 in the _driver_. For example: + * + * -54 dBm = 202 (-54 dBm + 256 = 202) + * -104 dBm = 152 (-104 dBm + 256 = 152) + * + */ + /**************************** CONSTANTS ****************************/ /* -------------------------- IOCTL LIST -------------------------- */ @@ -360,6 +462,7 @@ #define IW_MODE_MONITOR 6 /* Passive monitor (listen only) */ /* Statistics flags (bitmask in updated) */ +/* See also WIRELESS QUALITY above */ #define IW_QUAL_QUAL_UPDATED 0x1 /* Value was updated since last read */ #define IW_QUAL_LEVEL_UPDATED 0x2 #define IW_QUAL_NOISE_UPDATED 0x4 @@ -500,6 +603,8 @@ /* * Quality of the link + * + * See WIRELESS QUALITY above. */ struct iw_quality { @@ -658,10 +763,10 @@ /* Quality of link & SNR stuff */ /* Quality range (link, level, noise) - * If the quality is absolute, it will be in the range [0 ; max_qual], - * if the quality is dBm, it will be in the range [max_qual ; 0]. - * Don't forget that we use 8 bit arithmetics... */ + * + * See WIRELESS QUALITY above. */ struct iw_quality max_qual; /* Quality of the link */ + /* This should contain the average/typical values of the quality * indicator. This should be the threshold between a "good" and * a "bad" link (example : monitor going from green to orange).