feat(link): split radiotap's mixed bitmaps into value subfields (#2647)

docs/source/pcapkit/const/radiotap.rst

@@ -32,12 +32,22 @@ from radiotap.org [*]_. Available enumerations include:
      - VHT Coding Flags
    * - :class:`Radiotap_TimestampFlags <pcapkit.const.radiotap.timestamp_flags.TimestampFlags>`
      - Timestamp Flags
+   * - :class:`Radiotap_HEData1Known <pcapkit.const.radiotap.he_data1_known.HEData1Known>`
+     - HE Data1 Known Flags
+   * - :class:`Radiotap_HEData2Known <pcapkit.const.radiotap.he_data2_known.HEData2Known>`
+     - HE Data2 Known Flags
+   * - :class:`Radiotap_HEMUFlags1Known <pcapkit.const.radiotap.he_mu_flags1_known.HEMUFlags1Known>`
+     - HE-MU Flags1 Known Flags
+   * - :class:`Radiotap_HEMUFlags2Known <pcapkit.const.radiotap.he_mu_flags2_known.HEMUFlags2Known>`
+     - HE-MU Flags2 Known Flags
    * - :class:`Radiotap_HEMUOtherUserKnown <pcapkit.const.radiotap.he_mu_other_user_known.HEMUOtherUserKnown>`
      - HE-MU-other-user Known Flags
    * - :class:`Radiotap_LSIGData1 <pcapkit.const.radiotap.lsig_data1.LSIGData1>`
      - L-SIG Data1 Flags
    * - :class:`Radiotap_S1GKnown <pcapkit.const.radiotap.s1g_known.S1GKnown>`
      - S1G Known Flags
+   * - :class:`Radiotap_USIGCommonKnown <pcapkit.const.radiotap.usig_common_known.USIGCommonKnown>`
+     - U-SIG Common Known Flags
    * - :class:`Radiotap_EHTKnown <pcapkit.const.radiotap.eht_known.EHTKnown>`
      - EHT Known Flags
 
@@ -186,6 +196,58 @@ which is automatically generated from :class:`pcapkit.vendor.radiotap.timestamp_
    :undoc-members:
    :show-inheritance:
 
+HE Data1 Known Flags
+====================
+
+.. module:: pcapkit.const.radiotap.he_data1_known
+
+This module contains the constant enumeration for **Radiotap HE Data1 Known Flags**,
+which is automatically generated from :class:`pcapkit.vendor.radiotap.he_data1_known.HEData1Known`.
+
+.. autoclass:: pcapkit.const.radiotap.he_data1_known.HEData1Known
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HE Data2 Known Flags
+====================
+
+.. module:: pcapkit.const.radiotap.he_data2_known
+
+This module contains the constant enumeration for **Radiotap HE Data2 Known Flags**,
+which is automatically generated from :class:`pcapkit.vendor.radiotap.he_data2_known.HEData2Known`.
+
+.. autoclass:: pcapkit.const.radiotap.he_data2_known.HEData2Known
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HE-MU Flags1 Known Flags
+========================
+
+.. module:: pcapkit.const.radiotap.he_mu_flags1_known
+
+This module contains the constant enumeration for **Radiotap HE-MU Flags1 Known Flags**,
+which is automatically generated from :class:`pcapkit.vendor.radiotap.he_mu_flags1_known.HEMUFlags1Known`.
+
+.. autoclass:: pcapkit.const.radiotap.he_mu_flags1_known.HEMUFlags1Known
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+HE-MU Flags2 Known Flags
+========================
+
+.. module:: pcapkit.const.radiotap.he_mu_flags2_known
+
+This module contains the constant enumeration for **Radiotap HE-MU Flags2 Known Flags**,
+which is automatically generated from :class:`pcapkit.vendor.radiotap.he_mu_flags2_known.HEMUFlags2Known`.
+
+.. autoclass:: pcapkit.const.radiotap.he_mu_flags2_known.HEMUFlags2Known
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 HE-MU-other-user Known Flags
 ============================
 
@@ -225,6 +287,19 @@ which is automatically generated from :class:`pcapkit.vendor.radiotap.s1g_known.
    :undoc-members:
    :show-inheritance:
 
+U-SIG Common Known Flags
+========================
+
+.. module:: pcapkit.const.radiotap.usig_common_known
+
+This module contains the constant enumeration for **Radiotap U-SIG Common Known Flags**,
+which is automatically generated from :class:`pcapkit.vendor.radiotap.usig_common_known.USIGCommonKnown`.
+
+.. autoclass:: pcapkit.const.radiotap.usig_common_known.USIGCommonKnown
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 EHT Known Flags
 ===============
 

docs/source/pcapkit/corekit/fields/index.rst

@@ -36,6 +36,7 @@ hierarchy:
            NumberField --> Int8Field & UInt8Field
            NumberField --> EnumField
            EnumField --> PortEnumField
+           NumberField --> BitmapField
        end
        C --> NumberField
 
@@ -90,6 +91,7 @@ hierarchy:
        click UInt8Field "numbers.html#pcapkit.corekit.fields.numbers.UInt8Field"
        click EnumField "numbers.html#pcapkit.corekit.fields.numbers.EnumField"
        click PortEnumField "numbers.html#pcapkit.corekit.fields.numbers.PortEnumField"
+       click BitmapField "numbers.html#pcapkit.corekit.fields.numbers.BitmapField"
 
        click _TextField "strings.html#pcapkit.corekit.fields.strings._TextField"
        click BytesField "strings.html#pcapkit.corekit.fields.strings.BytesField"

docs/source/pcapkit/corekit/fields/numbers.rst

@@ -49,6 +49,13 @@ Enumeration Fields
    :members:
    :show-inheritance:
 
+Bitmap Fields
+-------------
+
+.. autoclass:: pcapkit.corekit.fields.numbers.BitmapField
+   :members:
+   :show-inheritance:
+
 Internal Definitions
 --------------------
 

docs/source/pcapkit/protocols/link/radiotap.rst

@@ -72,7 +72,11 @@ retries, bits 16 and 17, from its unofficially used ones, which those three
 size alike; OpenBSD writes a 2-octet RSSI field at bit 16 instead, which is not
 read. A bitmap radiotap.org defines bit by bit is a member of its flag registry
 under :mod:`pcapkit.const.radiotap`, which keeps the bits it does not name. A
-field type registered through
+bitmap that mixes value subfields with known bits -- the MCS ``flags``, the HE
+``data1`` and ``data2``, the HE-MU ``flags1`` and ``flags2`` and the U-SIG
+``common`` -- is split: each value subfield is an integer, and its other bits,
+the undefined ones among them, a member of its known-bits registry. A field
+type registered through
 :func:`~pcapkit.foundation.registry.protocols.link.register_radiotap_field` is
 decoded the same way.
 
@@ -445,6 +449,10 @@ Data Models
    :members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.protocols.data.link.radiotap.MCSFlags
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.protocols.data.link.radiotap.AMPDUStatus
    :members:
    :show-inheritance:
@@ -461,10 +469,26 @@ Data Models
    :members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.protocols.data.link.radiotap.HEData1
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.link.radiotap.HEData2
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.protocols.data.link.radiotap.HEMU
    :members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.protocols.data.link.radiotap.HEMUFlags1
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.link.radiotap.HEMUFlags2
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.protocols.data.link.radiotap.HEMUOtherUser
    :members:
    :show-inheritance:
@@ -497,6 +521,10 @@ Data Models
    :members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.protocols.data.link.radiotap.USIGCommon
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.protocols.data.link.radiotap.EHT
    :members:
    :show-inheritance:

docs/source/pcapkit/vendor/radiotap.rst

@@ -32,12 +32,22 @@ radiotap.org [*]_. Available vendor crawlers include:
      - VHT Coding Flags
    * - :class:`Radiotap_TimestampFlags <pcapkit.vendor.radiotap.timestamp_flags.TimestampFlags>`
      - Timestamp Flags
+   * - :class:`Radiotap_HEData1Known <pcapkit.vendor.radiotap.he_data1_known.HEData1Known>`
+     - HE Data1 Known Flags
+   * - :class:`Radiotap_HEData2Known <pcapkit.vendor.radiotap.he_data2_known.HEData2Known>`
+     - HE Data2 Known Flags
+   * - :class:`Radiotap_HEMUFlags1Known <pcapkit.vendor.radiotap.he_mu_flags1_known.HEMUFlags1Known>`
+     - HE-MU Flags1 Known Flags
+   * - :class:`Radiotap_HEMUFlags2Known <pcapkit.vendor.radiotap.he_mu_flags2_known.HEMUFlags2Known>`
+     - HE-MU Flags2 Known Flags
    * - :class:`Radiotap_HEMUOtherUserKnown <pcapkit.vendor.radiotap.he_mu_other_user_known.HEMUOtherUserKnown>`
      - HE-MU-other-user Known Flags
    * - :class:`Radiotap_LSIGData1 <pcapkit.vendor.radiotap.lsig_data1.LSIGData1>`
      - L-SIG Data1 Flags
    * - :class:`Radiotap_S1GKnown <pcapkit.vendor.radiotap.s1g_known.S1GKnown>`
      - S1G Known Flags
+   * - :class:`Radiotap_USIGCommonKnown <pcapkit.vendor.radiotap.usig_common_known.USIGCommonKnown>`
+     - U-SIG Common Known Flags
    * - :class:`Radiotap_EHTKnown <pcapkit.vendor.radiotap.eht_known.EHTKnown>`
      - EHT Known Flags
 
@@ -78,7 +88,9 @@ which is automatically generating :class:`pcapkit.const.radiotap.flags.Flags`.
 
 Each flag crawler scrapes the table on its field's page, and subclasses this one.
 A row whose mask sets one bit is a member; a row that sets more bits, or that
-radiotap.org marks reserved or unused, is not, and its bits stay undefined. A
+radiotap.org marks reserved or unused, is not, and its bits stay undefined; nor
+is a row of a crawler's ``VALUES``, a value subfield of a bitmap that mixes them
+with flags, which its schema splits off. A
 member's name is the macro the crawler's ``NAMES`` gives its bit, less the
 ``IEEE80211_RADIOTAP_`` or ``IEEE80211_`` prefix: the Linux kernel's, from
 ``include/net/ieee80211_radiotap.h``, or Wireshark's where Linux names none.
@@ -196,6 +208,54 @@ which is automatically generating :class:`pcapkit.const.radiotap.timestamp_flags
    :members: FLAG, LINK, SUBFIELD, NAMES
    :show-inheritance:
 
+HE Data1 Known Flags
+====================
+
+.. module:: pcapkit.vendor.radiotap.he_data1_known
+
+This module contains the vendor crawler for **Radiotap HE Data1 Known Flags**,
+which is automatically generating :class:`pcapkit.const.radiotap.he_data1_known.HEData1Known`.
+
+.. autoclass:: pcapkit.vendor.radiotap.he_data1_known.HEData1Known
+   :members: FLAG, LINK, SUBFIELD, VALUES, NAMES
+   :show-inheritance:
+
+HE Data2 Known Flags
+====================
+
+.. module:: pcapkit.vendor.radiotap.he_data2_known
+
+This module contains the vendor crawler for **Radiotap HE Data2 Known Flags**,
+which is automatically generating :class:`pcapkit.const.radiotap.he_data2_known.HEData2Known`.
+
+.. autoclass:: pcapkit.vendor.radiotap.he_data2_known.HEData2Known
+   :members: FLAG, LINK, SUBFIELD, VALUES, NAMES
+   :show-inheritance:
+
+HE-MU Flags1 Known Flags
+========================
+
+.. module:: pcapkit.vendor.radiotap.he_mu_flags1_known
+
+This module contains the vendor crawler for **Radiotap HE-MU Flags1 Known Flags**,
+which is automatically generating :class:`pcapkit.const.radiotap.he_mu_flags1_known.HEMUFlags1Known`.
+
+.. autoclass:: pcapkit.vendor.radiotap.he_mu_flags1_known.HEMUFlags1Known
+   :members: FLAG, LINK, SUBFIELD, VALUES, NAMES
+   :show-inheritance:
+
+HE-MU Flags2 Known Flags
+========================
+
+.. module:: pcapkit.vendor.radiotap.he_mu_flags2_known
+
+This module contains the vendor crawler for **Radiotap HE-MU Flags2 Known Flags**,
+which is automatically generating :class:`pcapkit.const.radiotap.he_mu_flags2_known.HEMUFlags2Known`.
+
+.. autoclass:: pcapkit.vendor.radiotap.he_mu_flags2_known.HEMUFlags2Known
+   :members: FLAG, LINK, SUBFIELD, VALUES, NAMES
+   :show-inheritance:
+
 HE-MU-other-user Known Flags
 ============================
 
@@ -232,6 +292,18 @@ which is automatically generating :class:`pcapkit.const.radiotap.s1g_known.S1GKn
    :members: FLAG, LINK, SUBFIELD, NAMES
    :show-inheritance:
 
+U-SIG Common Known Flags
+========================
+
+.. module:: pcapkit.vendor.radiotap.usig_common_known
+
+This module contains the vendor crawler for **Radiotap U-SIG Common Known Flags**,
+which is automatically generating :class:`pcapkit.const.radiotap.usig_common_known.USIGCommonKnown`.
+
+.. autoclass:: pcapkit.vendor.radiotap.usig_common_known.USIGCommonKnown
+   :members: FLAG, LINK, SUBFIELD, VALUES, NAMES
+   :show-inheritance:
+
 EHT Known Flags
 ===============
 

examples/generators/option_families/radiotap.py

@@ -54,19 +54,28 @@ def _radiotap_field_overrides() -> 'dict[Any, dict[str, Any]]':
         Enum_FieldType.TX_flags: {'flags': 0x0008},
         Enum_FieldType.RTS_retries: {'retries': 3},
         Enum_FieldType.data_retries: {'retries': 1},
-        Enum_FieldType.MCS: {'known': 0x27, 'flags': 0x25, 'mcs': 7},
+        Enum_FieldType.MCS: {'known': 0x27, 'flags': {'bandwidth': 1, 'guard_interval': 1, 'ht_format': 0,
+                                                      'fec_type': 0, 'stbc_streams': 1, 'ness_bit0': 0},
+                             'mcs': 7},
         Enum_FieldType.A_MPDU_status: {'reference': 7, 'flags': 0x0105, 'delimiter_crc': 0xAB, 'reserved': 0},
         Enum_FieldType.VHT: {'known': 0x0244, 'flags': 0x05, 'bandwidth': 4, 'mcs_nss': (0x91, 0, 0, 0),
                              'coding': 0x01, 'group_id': 2, 'partial_aid': 0x1234},
         Enum_FieldType.timestamp: {'timestamp': 1, 'accuracy': 2, 'unit_position': 0x11, 'flags': 0x02},
-        Enum_FieldType.HE: {'data1': 1, 'data2': 2, 'data3': 3, 'data4': 4, 'data5': 5, 'data6': 6},
-        Enum_FieldType.HE_MU: {'flags1': 1, 'flags2': 2, 'ru_channel1': (1, 2, 3, 4), 'ru_channel2': (5, 6, 7, 8)},
+        Enum_FieldType.HE: {'data1': {'ppdu_format': 1, 'known': 0x0004},
+                            'data2': {'ru_offset': 5, 'pri_sec_80mhz': 1, 'known': 0x4001},
+                            'data3': 3, 'data4': 4, 'data5': 5, 'data6': 6},
+        Enum_FieldType.HE_MU: {'flags1': {'sig_b_mcs': 3, 'sig_b_dcm': 1, 'ch1_center_26_tone_ru': 1, 'known': 0x0010},
+                               'flags2': {'bandwidth': 2, 'sig_b_compression': 1, 'sig_b_symbols_users': 4,
+                                          'preamble_puncturing': 1, 'ch2_center_26_tone_ru': 1, 'known': 0x0404},
+                               'ru_channel1': (1, 2, 3, 4), 'ru_channel2': (5, 6, 7, 8)},
         Enum_FieldType.HE_MU_other_user: {'per_user_1': 1, 'per_user_2': 2, 'per_user_position': 3,
                                           'per_user_known': 0x23},
         Enum_FieldType.FieldType_0_length_PSDU: {'psdu_type': 1},
         Enum_FieldType.L_SIG: {'data1': 0x0007, 'data2': 0x1234},
         Enum_FieldType.S1G: {'known': 0x0103, 'data1': 2, 'data2': 3},
-        Enum_FieldType.U_SIG: {'common': 0x11, 'value': 0x22, 'mask': 0x33},
+        Enum_FieldType.U_SIG: {'common': {'phy_version': 0, 'bandwidth': 4, 'ul_dl': 1, 'bss_color': 9, 'txop': 3,
+                                          'known': 0x1F},
+                               'value': 0x22, 'mask': 0x33},
         Enum_FieldType.EHT: {'known': 3, 'data': tuple(range(9)), 'user_info': (0xA1, 0xA2)},
     }
 

pcapkit/all.py

@@ -59,6 +59,7 @@
     'NumberField', 'Int32Field', 'UInt32Field',             # numeric protocol fields
     'Int16Field', 'UInt16Field', 'Int64Field', 'UInt64Field',
     'Int8Field', 'UInt8Field', 'EnumField', 'PortEnumField',
+    'BitmapField',
     'BytesField', 'StringField', 'BitField',                # text protocol fields
     'PaddingField',
     'ConditionalField', 'PayloadField', 'SchemaField',      # misc protocol fields

pcapkit/const/__init__.py

@@ -104,8 +104,10 @@
     # Radiotap
     'Radiotap_FieldType', 'Radiotap_Flags', 'Radiotap_ChannelFlags', 'Radiotap_RXFlags',
     'Radiotap_TXFlags', 'Radiotap_MCSKnown', 'Radiotap_AMPDUFlags', 'Radiotap_VHTKnown',
-    'Radiotap_VHTFlags', 'Radiotap_VHTCoding', 'Radiotap_TimestampFlags',
-    'Radiotap_HEMUOtherUserKnown', 'Radiotap_LSIGData1', 'Radiotap_S1GKnown', 'Radiotap_EHTKnown',
+    'Radiotap_VHTFlags', 'Radiotap_VHTCoding', 'Radiotap_TimestampFlags', 'Radiotap_HEData1Known',
+    'Radiotap_HEData2Known', 'Radiotap_HEMUFlags1Known', 'Radiotap_HEMUFlags2Known',
+    'Radiotap_HEMUOtherUserKnown', 'Radiotap_LSIGData1', 'Radiotap_S1GKnown',
+    'Radiotap_USIGCommonKnown', 'Radiotap_EHTKnown',
     # SCTP
     'SCTP_Chunk', 'SCTP_Parameter', 'SCTP_CauseCode', 'SCTP_PayloadProtocolIdentifier',
     # SSLv2