Ticket #26: flag_masks

File flag_masks, 9.9 KB (added by russ, 11 years ago)

Enhancement to Flags with addition of flag_masks attribute

Line 
1The following document describes suggested changes to the CF
2Conventions document to describe the proposed enhancement of
3the Flags definition to support bit field notation using a
4flag_masks attribute.
5
6There are five sections to be modified:
7  (1) Table of Contents
8  (2) Section 3.5, Flags
9  (3) Appendix A, Attributes
10  (4) Appendix C, Standard name Modifiers
11  (5) Conformance Requirements and Recommendations document,
12      Section 3.5
13
14These changes are described in the following sections:
15
16================================================================
17
18(1) Table of Contents
19
20FROM:
21
22  List of Examples
23    3.3 A flag variable
24
25TO:
26
27  List of Examples
28    3.3 A flag variable, using flag_values
29    3.4 A flag variable, using flag_masks
30    3.5 A flag variable, using flag_values and flag_masks
31
32================================================================
33
34(2) Section 3.5, Flags
35
36FROM:
37
383.5. Flags
39
40The attributes flag_values and flag_meanings are intended to make variables that contain flag values self describing. The flag_values attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values. The flag_meanings attribute is a string whose value is a blank separated list of descriptive words or phrases, one for each flag value. If multi-word phrases are used to describe the flag values, then the words within a phrase should be connected with underscores.
41
42Example 3.3. A flag variable
43
44  byte current_speed_qc(time, depth, lat, lon) ;
45    current_speed_qc:long_name = "Current Speed Quality" ;
46    current_speed_qc:_FillValue = -128b ;
47    current_speed_qc:valid_range = -127b, 127b ;
48    current_speed_qc:flag_values = 0b, 1b, 2b ;
49    current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
50                                                     outside_valid_range" ;
51
52TO:
53
543.5. Flags
55
56The attributes flag_values, flag_masks and flag_meanings are intended to make variables that contain flag values self describing. Status codes and Boolean (binary) condition flags may be expressed with different combinations of flag_values and flag_masks attribute definitions.
57
58The flag_values and flag_meanings attributes describe a status flag consisting of mutually exclusive coded values.  The flag_values attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values.  The flag_meanings attribute is a string whose value is a blank separated list of descriptive words or phrases, one for each flag value.  If multi-word phrases are used to describe the flag values, then the words within a phrase should be connected with underscores.  Example 3.3 illustrates the use of flag values to express a speed quality with an enumerated status code.
59
60Example 3.3.  A flag variable, using flag_values
61
62  byte current_speed_qc(time, depth, lat, lon) ;
63    current_speed_qc:long_name = "Current Speed Quality" ;
64    current_speed_qc:standard_name = "sea_water_speed status_flag" ;
65    current_speed_qc:_FillValue = -128b ;
66    current_speed_qc:valid_range = 0b, 2b ;
67    current_speed_qc:flag_values = 0b, 1b, 2b ;
68    current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
69                                      outside_valid_range" ;
70
71The flag_masks and flag_meanings attributes describe a number of independent Boolean conditions using bit field notation by setting unique bits in each flag_masks value.  The flag_masks attribute is the same type as the variable to which it is attached, and contains a list of values matching unique bit fields.  The flag_meanings attribute is defined as above, one for each flag_masks value.  A flagged condition is identified by performing a bitwise AND of the variable value and each flag_masks value; a non-zero result indicates a true condition.  Thus, any or all of the flagged conditions may be true, depending on the variable bit settings. Example 3.4 illustrates the use of flag_masks to express six sensor status conditions:
72
73Example 3.4.  A flag variable, using flag_masks
74
75byte sensor_status_qc(time, depth, lat, lon) ;
76     sensor_status_qc:long_name = "Sensor Status" ;
77     sensor_status_qc:_FillValue = 0b ;
78     sensor_status_qc:valid_range = 1b, 63b ;
79     sensor_status_qc:flag_masks = 1b, 2b, 4b, 8b, 16b, 32b ;
80     sensor_status_qc:flag_meanings = "low_battery processor_fault
81                                       memory_fault disk_fault
82                                       software_fault
83                                       maintenance_required" ;
84
85The flag_masks, flag_values and flag_meanings attributes, used together, describe a blend of independent Boolean conditions and enumerated status codes.  The flag_masks and flag_values attributes are both the same type as the variable to which they are attached.  A flagged condition is identified by a bitwise AND of the variable value and each flag_masks value; a result that matches the flag_values value indicates a true condition.  Repeated flag_masks define a bit field mask that identifies a number of status conditions with different flag_values.  The flag_meanings attribute is defined as above, one for each flag_masks bit field and flag_values definition.  Each flag_values and flag_masks value must coincide with a flag_meanings value.  Example 3.5 illustrates the use of flag_masks and flag_values to express two sensor status conditions and and one enumerated status code.
86
87Example 3.5.  A flag variable, using flag_masks and flag_values
88
89byte sensor_status_qc(time, depth, lat, lon) ;
90     sensor_status_qc:long_name = "Sensor Status" ;
91     sensor_status_qc:_FillValue = 0b ;
92     sensor_status_qc:valid_range = 1b, 15b ;
93     sensor_status_qc:flag_masks = 1b, 2b, 12b, 12b, 12b ;
94     sensor_status_qc:flag_values = 1b, 2b, 4b, 8b, 12b ;
95     sensor_status_qc:flag_meanings =
96         "low_battery
97          hardware_fault
98          offline_mode calibration_mode maintenance_mode" ;
99
100In this case, mutually exclusive values are blended with Boolean values to maximize use of the available bits in a flag value.  The table below represents the four binary digits (bits) expressed by the sensor_status_qc variable in Example 3.5.
101
102    Bit 0 and Bit 1 are Boolean values indicating a low battery condition and a hardware fault, respectively. The next two bits (Bit 2 & Bit 3) express an enumeration indicating abnormal sensor operating modes.
103
104    Thus, if Bit 0 is set, the battery is low and if Bit 1 is set, there is a hardware fault - independent of the current sensor operating mode.
105
106    +-------------------------------+
107    | Bit 3 . Bit 2 | Bit 1 | Bit 0 |
108    | (MSB) .       |       | (LSB) |
109    |       .       |       |       |
110    |       .       | H/W   | Low   |
111    |       .       | Fault | Batt  |
112    |       .       |       |       |
113    +-------------------------------+
114
115    The remaining bits (Bit 2 & Bit 3) are decoded as follows:
116
117        Bit3:0   Bit2:1  = offline_mode
118             1        0  = calibration_mode
119             1        1  = maintenance_mode
120
121The "12b" flag mask is repeated in the sensor_status_qc flag_masks definition to explicitly declare the recommended bit field masks to repeatedly AND with the variable value while searching for matching enumerated values. An application determines if any of the conditions declared in the flag_meanings list are true by simply iterating through each of the flag_masks and AND'ing them with the variable. When a result is equal to the corresponding flag_values element, that condition is true. The repeated flag_masks enable a simple mechanism for clients to detect all possible conditions.
122
123================================================================
124
125(3) Appendix A, Attributes
126
127ADD:
128
129[flag_masks] [D] [D] [Section 3.5, "Flags"] [Provides a list of bit fields expressing Boolean or enumerated flags.]
130
131================================================================
132
133(4) Appendix C, Standard Name Modifiers
134
135FROM:
136
137[status_flag] [ ] [Flag values indicating the quality or other status of the data values. The variable should have flag_values and flag_meanings attributes to show how it should be interpreted (Section 3.5, “Flags”).]
138
139TO:
140
141[status_flag] [ ] [Flag values indicating the quality or other status of the data values.  The variable should have flag_values or flag_masks (or both) and flag_meanings attributes to show how it should be interpreted (Section 3.5, “Flags”).]
142
143================================================================
144
145(5) Conformance Requirements and Recommendations document, Section 3.5
146
147FROM:
148
149Requirements:
150
151    * The flag_values attribute must have the same type as the variable to which it is attached.
152
153TO:
154
155Requirements:
156
157    * The flag_values attribute must have the same type as the variable to which it is attached.
158
159    + The number of flag_values attribute values must equal the number of words or phrases appearing in the flag_meanings string.
160
161    + The number of flag_masks attribute values must equal the number of words or phrases appearing in the flag_meanings string.
162
163    * The flag_values attribute must have the same type as the variable to which it is attached.
164
165    + Variables with a flag_masks attribute must have a type that is compatible with bit field expression (char, byte, short and int), not floating-point (float, real, double), and the flag_masks attribute must have the same type.
166
167    + The flag_masks attribute values must be non-zero.
168
169    + The flag_values attribute values must be mutually exclusive among the set of flag_values attribute values defined for that variable.
170
171    + When only flags_masks and flag_meanings attributes are defined (no flag_values), the bit fields of each flag_masks value must not be shared with any other flag_masks value defined for that variable. For example, a boolean AND of each flag_masks value with any other flag_masks value, must be false (zero).
172
173Recommendations:
174
175    + When flag_masks and flag_values are both defined, the Boolean AND of each entry in flag_values with its corresponding entry in flag_masks should equal the flag_values entry, ie, the mask selects all the bits required to express the value.