Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Capture Information Block (CIB) addition #51

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Open

Capture Information Block (CIB) addition #51

Changes from 2 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ef54275
Initial Capture Information Block (CIB) concept.
ryankurte Jun 14, 2018
7608aa6
Copy edits
ryankurte Jun 17, 2018
e73d4bc
Added local_location, updated descriptions
ryankurte Jun 17, 2018
2e0bb98
Simplified proposal
ryankurte Aug 18, 2018
c91863c
Added example
ryankurte Aug 18, 2018
4e89195
Added note on CIB persistence
ryankurte Aug 18, 2018
dac8670
Fixed CIB block type, cib_options collision
ryankurte Jan 23, 2019
da11baa
Merge branch 'master' into proposed-wireless-fields
ryankurte Feb 12, 2019
7820a51
Fixing comments from review
ryankurte Feb 13, 2019
5df4b9d
add CIB option examples, fix CIB block number
ryankurte Feb 13, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 177 additions & 0 deletions draft-tuexen-opsawg-pcapng.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@
<t hangText='EPB:'>Enhanced Packet Block</t>
<t hangText='SPB:'>Simple Packet Block</t>
<t hangText='NRB:'>Name Resolution Block</t>
<t hangText='CIB:'>Capture Information Block</t>
<t hangText='CB:'>Custom Block</t>
</list>

Expand Down Expand Up @@ -267,6 +268,11 @@
capture has been made. If this appears in a file, an Interface
Description Block is also required, before this block.</t>

<t><xref target="section_cib">Capture Information Block</xref>: it
defines how to store some capture information such as location,
orientation, velocity and associated errors, as well as Radio Frequency
(RF) information.</t>

<t><xref target="section_custom_block">Custom Block</xref>: it
contains vendor-specific data in a portable fashion.</t>

Expand Down Expand Up @@ -1269,6 +1275,11 @@ Section Header
<c>4</c>
<c>8</c>
<c>no</c>

guyharris marked this conversation as resolved.
Show resolved Hide resolved
<c>epb_cib</c>
<c>4</c>
<c>4</c>
<c>no</c>
</texttable>

<t>
Expand Down Expand Up @@ -1306,6 +1317,10 @@ Section Header

<t>Example: '0'.</t>

<t hangText="epb_cib:"><vspace blankLines="0"/>The epb_cib
option indicates the Capture Information Block ID to be associated
with this packet, allowing the addition of capture related metadata.</t>

</list>
</t>

Expand Down Expand Up @@ -1828,6 +1843,168 @@ Section Header

</section>

<section anchor="section_cib" title="Capture Information Block">

<t>The Capture Information Block (CIB) is used to support the addition
of metadata associated with capture interfaces or packets, including
location, orientation, velocity and related errors, as well as wireless
channel and medium options.
This block can be associated with a specific interface and applied to all
packets received on this interface, or to (a) specific packet(s).
If applied to an interface, this block affects all capture blocks following
until it is superseded by a new CIB applied to the same interface.
</t>

<t>
Tools that write / read the capture file associate an incrementing 32-bit
number (starting from '0') to each Capture Information Block, called
the CIB ID for the CIB in question. This number is unique within each Section
and identifies the CIB that is referred to in an epb_cip option; it is only
unique inside the current section, so, two Sections can have different
CIBs identified by the same CIB ID values. This unique identifier
is referenced by other blocks, such as Enhanced Packet Blocks, to indicate the
CIB to which the block refers.
</t>

<t>The format of the Capture Information Block is shown in <xref
target="format_cib"/>.</t>

<figure anchor="format_cib" title="Capture Information Block Format">
<artwork xml:space="preserve" name="" type="" align="center" alt="" width="" height="">
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------------------------------------------------------+
0 | Block Type = 0x00000006 |
+---------------------------------------------------------------+
4 | Block Total Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
8 / /
/ Options (variable) /
/ /
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Block Total Length |
+---------------------------------------------------------------+
</artwork>
</figure>
<t>The fields have the following meaning:
<list style="symbols">

<t>Block Type: The block type of the Capture Information Block is
6.</t>

<t>Block Total Length: total size of this block, as described in
<xref target="section_block"/>.</t>

<t>Options: optionally, a list of options (formatted according to
the rules defined in <xref target="section_opt"/>) can be present.</t>

</list>
</t>

<t>All the statistic fields are defined as options in order to deal
with systems that do not have a complete set of statistics. Therefore,
In addition to the options defined in <xref target="section_opt"/>,
the following options are valid within this block:</t>

<texttable anchor="options_cib" title="Capture Information Block Options">
<ttcol align="left">Name</ttcol>
<ttcol align="left">Code</ttcol>
<ttcol align="left">Length</ttcol>
<ttcol align="left">Multiple allowed?</ttcol>

<c>interface_id</c>
<c>1</c>
<c>4</c>
<c>no</c>

<c>global_location</c>
<c>2</c>
<c>12</c>
<c>no</c>

<c>global_location_error</c>
<c>3</c>
<c>12</c>
<c>no</c>

<c>orientation</c>
<c>4</c>
<c>12</c>
<c>no</c>

<c>orientation_error</c>
<c>5</c>
<c>12</c>
<c>no</c>

<c>velocity</c>
<c>6</c>
<c>12</c>
<c>no</c>

<c>velocity_error</c>
<c>7</c>
<c>12</c>
<c>no</c>
</texttable>

<t>
<list hangIndent="8" style="hanging">

<t hangText="cib_interface_id:"><vspace blankLines="0"/>The
interface_id option specifies the interface these statistics refers
to; the correct interface will be the one whose Interface
Description Block (within the current Section of the file) is
identified by same number (see <xref target="section_idb"/>) of
this field.</t>

<t hangText="cib_global_location"><vspace blankLines="0"/>The
guyharris marked this conversation as resolved.
Show resolved Hide resolved
cib_global_location option specifies the location of the packet
capture or interface; location is stored as three 32-bit floats
representing latitude and longitude in degrees, and altitude in
metres.</t>

<t>Example: TODO</t>

<t hangText="cib_global_location_error"><vspace blankLines="0"/>The
global_location_error option specifies the error in location capture;
this is stored as three 32-bit floats in the same order and
representation as cib_location.</t>

<t>Example: TODO</t>

<t hangText="cib_orientation"><vspace blankLines="0"/>The
cib_orientation option specifies the location of the packet
ryankurte marked this conversation as resolved.
Show resolved Hide resolved
capture or interface; location is stored as three 32-bit floats
ryankurte marked this conversation as resolved.
Show resolved Hide resolved
representing yaw, pitch, and roll in radians.</t>
ryankurte marked this conversation as resolved.
Show resolved Hide resolved

<t>Example: TODO</t>

<t hangText="cib_orientation_error"><vspace blankLines="0"/>The
orientation_error option specifies the error in orientation capture;
this is stored as three 32-bit floats in the same order and
representation as cib_orientation.</t>

<t>Example: TODO</t>

<t hangText="cib_velocity"><vspace blankLines="0"/>The
cib_velocity option specifies the location of the packet
ryankurte marked this conversation as resolved.
Show resolved Hide resolved
capture or interface; location is stored as three 32-bit floats
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"velocity is stored as three 32-bit floats representing the rates of change of latitude and longitude in degrees per second, and the rate of change of altitude in metres/second."

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it makes more sense for velocity to be in meters per second against a global reference frame (orientation zero, Y facing north, -Z down). It's easier to compare and use in calculations, and works for non-global locations (see PR update introducing local locations too).

representing yaw, pitch, and roll in radians.</t>

<t>Example: TODO</t>

<t hangText="cib_velocity_error"><vspace blankLines="0"/>The
cib_velocity_error option specifies the error in velocity capture;
this is stored as three 32-bit floats in the same order and
representation as cib_velocity.</t>

<t>Example: TODO</t>

</list>
</t>

</section>

<section anchor="section_custom_block" title="Custom Block">

Expand Down