lib: add bit array field class and field types
This patch adds the bit array field class (FC) and field to the
available library types.
A bit array field is a simple array of bits. As opposed to integer
fields, a bit array field has no sign: it does not contain a quantity.
Such a field can be used to hold CPU register values, for example, or an
array of flags which is typically read and written as a (small) unsigned
integer.
CTF 2 will very likely have such a type, so Babeltrace 2.0 will be
ready.
You create a bit array FC with bt_field_class_bit_array_create(). This
function expects a length parameter which must be in the [1, 64] range
as of this version. The length is the number of bits in the array. You
can get the length of a bit array with
bt_field_class_bit_array_get_length().
You can set the value of a bit array field with
bt_field_bit_array_set_value_as_integer(). This function accepts an
unsigned integer and conceptually sets all the bits of the array
accordingly, where the _first_ bit of the array is the LSB of the value.
In other words, should there be a bit accessor (by index), getting the
value of bit 0 would return the LSB of that unsigned integer:
0 1 1 0 1 1 0 1
^ MSB: bit 7 ^ LSB: bit 0
Unsigned integer value: 0x6d
As such, you can get the value of the bit array with
bt_field_bit_array_get_value_as_integer(). Again, the value of bit 0 is
the LSB of the returned unsigned integer.
I chose to apply a mask to the received value in
bt_field_bit_array_set_value_as_integer() to ensure that there's no set
bit outside the bit array's range. This is to lessen the user's burden
instead of a having a precondition assertion. This in turns guarantees
that bt_field_bit_array_get_value_as_integer() always returns a value
without superfluous set bit. If this automatic masking becomes a
performance issue in the future, then we can add another function which
expects the user to do it (with a precondition assertion).
This patch does not adapt existing plugins and the Python bindings to
use and wrap the new bit array FC and field; this work is reserved for
subsequent patches.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I8ba4d111df275962cfa9f2c4f754f83a1de40e29
Reviewed-on: https://review.lttng.org/c/babeltrace/+/1907
Tested-by: jenkins <jenkins@lttng.org>
Reviewed-by: Francis Deslauriers <francis.deslauriers@efficios.com>
This page took 0.025766 seconds and 4 git commands to generate.