The following document describes suggested changes to the CF Conventions document to describe the proposed enhancement of the Flags definition to support bit field notation using a flag_masks attribute. There are five sections to be modified: (1) Table of Contents (2) Section 3.5, Flags (3) Appendix A, Attributes (4) Appendix C, Standard name Modifiers (5) Conformance Requirements and Recommendations document, Section 3.5 These changes are described in the following sections: ================================================================ (1) Table of Contents FROM: List of Examples 3.3 A flag variable TO: List of Examples 3.3 A flag variable, using flag_values 3.4 A flag variable, using flag_masks 3.5 A flag variable, using flag_values and flag_masks ================================================================ (2) Section 3.5, Flags FROM: 3.5. Flags The 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. Example 3.3. A flag variable byte current_speed_qc(time, depth, lat, lon) ; current_speed_qc:long_name = "Current Speed Quality" ; current_speed_qc:_FillValue = -128b ; current_speed_qc:valid_range = -127b, 127b ; current_speed_qc:flag_values = 0b, 1b, 2b ; current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional outside_valid_range" ; TO: 3.5. Flags The 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. The 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. Example 3.3. A flag variable, using flag_values byte current_speed_qc(time, depth, lat, lon) ; current_speed_qc:long_name = "Current Speed Quality" ; current_speed_qc:standard_name = "sea_water_speed status_flag" ; current_speed_qc:_FillValue = -128b ; current_speed_qc:valid_range = 0b, 2b ; current_speed_qc:flag_values = 0b, 1b, 2b ; current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional outside_valid_range" ; The 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: Example 3.4. A flag variable, using flag_masks byte sensor_status_qc(time, depth, lat, lon) ; sensor_status_qc:long_name = "Sensor Status" ; sensor_status_qc:_FillValue = 0b ; sensor_status_qc:valid_range = 1b, 63b ; sensor_status_qc:flag_masks = 1b, 2b, 4b, 8b, 16b, 32b ; sensor_status_qc:flag_meanings = "low_battery processor_fault memory_fault disk_fault software_fault maintenance_required" ; The 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. Example 3.5. A flag variable, using flag_masks and flag_values byte sensor_status_qc(time, depth, lat, lon) ; sensor_status_qc:long_name = "Sensor Status" ; sensor_status_qc:_FillValue = 0b ; sensor_status_qc:valid_range = 1b, 15b ; sensor_status_qc:flag_masks = 1b, 2b, 12b, 12b, 12b ; sensor_status_qc:flag_values = 1b, 2b, 4b, 8b, 12b ; sensor_status_qc:flag_meanings = "low_battery hardware_fault offline_mode calibration_mode maintenance_mode" ; In 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. 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. 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. +-------------------------------+ | Bit 3 . Bit 2 | Bit 1 | Bit 0 | | (MSB) . | | (LSB) | | . | | | | . | H/W | Low | | . | Fault | Batt | | . | | | +-------------------------------+ The remaining bits (Bit 2 & Bit 3) are decoded as follows: Bit3:0 Bit2:1 = offline_mode 1 0 = calibration_mode 1 1 = maintenance_mode The "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. ================================================================ (3) Appendix A, Attributes ADD: [flag_masks] [D] [D] [Section 3.5, "Flags"] [Provides a list of bit fields expressing Boolean or enumerated flags.] ================================================================ (4) Appendix C, Standard Name Modifiers FROM: [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”).] TO: [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”).] ================================================================ (5) Conformance Requirements and Recommendations document, Section 3.5 FROM: Requirements: * The flag_values attribute must have the same type as the variable to which it is attached. TO: Requirements: * The flag_values attribute must have the same type as the variable to which it is attached. + The number of flag_values attribute values must equal the number of words or phrases appearing in the flag_meanings string. + The number of flag_masks attribute values must equal the number of words or phrases appearing in the flag_meanings string. * The flag_values attribute must have the same type as the variable to which it is attached. + 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. + The flag_masks attribute values must be non-zero. + The flag_values attribute values must be mutually exclusive among the set of flag_values attribute values defined for that variable. + 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). Recommendations: + 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.