class documentation

class BitfieldInstance(_Generic[_ValueType]):

View In Hierarchy

A bitfield instance, the result of reading a bitfield from a StructInstance.

You can obtain the value of the field by calling the BitfieldInstance.read method. The returned value will be of the natural type produced by the type of the field, which will be an integer or an enumeration depending on the type sliced by the bitfield.

You can also always get the value of the bitfield as a bitarray with the BitfieldInstance.read_bitarray method.

Lastly, get the information about the field in its structure (name, type, offset) with the BitfieldInstance.info property, or link back to the StructInstance of origin with BitfieldInstance.parent_instance.

Method __eq__ Compares the instance for equality with an object.
Method __format__ Formats the value according to the specified options.
Method __hash__ Returns the hash for this value.
Method __init__ Initializes a new field instance from the struct instance of origin and the selected bitfield.
Method __ne__ Compares the instance for equality with an object.
Method __str__ Returns the nicely printable string representation of this instance.
Method assert_enum Asserts to the type system that the bitfield produces an enumeration value.
Method assert_int Asserts to the type system that the bitfield produces an integer value.
Method format Undocumented
Method read Reads the value produced by the bitfield.
Method read_bitarray Reads the bitfield as an array of bits of the size of the bitfield.
Method read_enum Reads the bitfield after asserting to the type system that it produces an enumeration value.
Method read_int Reads the bitfield after asserting to the type system that it produces an integer value.
Property info The information (offset, name, length, position) about the bitfield associated with this instance.
Property parent_instance The struct instance that this instance originates from.
Instance Variable _field Undocumented
Instance Variable _struct Undocumented
def __eq__(self, o):

Compares the instance for equality with an object.

  • if the object is of type bitarray, it will be considered equal to this instance if it is equal to the underlying bits that this instance is made of.
  • two BitfieldInstances are considered equal if they have the same underlying Struct, Field and bits.
  • if the object is neither bitarray nor BitfieldInstance, then it will never be considered equal.

Note

  • The context where this struct was spawned at is never taken into consideration for the purpose of equality. This means that two BitfieldInstances at different contexts with the same type and bits will be considered equal.
  • Similarly, the source from which the instance was read is never taken into consideration for the purpose of equality. This means that two BitfieldInstances coming from different addresses in memory or different registers can compare equal if they have the same type and bits.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __format__(self, format_spec):

Formats the value according to the specified options.

The options are expected to be in the format described by reven2.util.parse_colon_separated_key_values.

The options will be passed as argument to format.

See StructInstance.__format__ for examples.

Parameters
format_spec:strUndocumented
Returns
strUndocumented
def __hash__(self):

Returns the hash for this value.

Returns
intUndocumented
def __init__(self, struct_instance, field):

Initializes a new field instance from the struct instance of origin and the selected bitfield.

Warnings

At the moment, this object is not meant to be constructed directly. Use StructInstance.bitfield instead.

Parameters
struct_instance:StructInstanceUndocumented
field:BitfieldUndocumented
def __ne__(self, o):

Compares the instance for equality with an object.

  • if the object is of type bitarray, it will be considered equal to this instance if it is equal to the underlying bits that this instance is made of.
  • two BitfieldInstances are considered equal if they have the same underlying Struct, Field and bits.
  • if the object is neither bitarray nor BitfieldInstance, then it will never be considered equal.

Note

  • The context where this struct was spawned at is never taken into consideration for the purpose of equality. This means that two BitfieldInstances at different contexts with the same type and bits will be considered equal.
  • Similarly, the source from which the instance was read is never taken into consideration for the purpose of equality. This means that two BitfieldInstances coming from different addresses in memory or different registers can compare equal if they have the same type and bits.
Parameters
o:objectUndocumented
Returns
boolUndocumented
def __str__(self):

Returns the nicely printable string representation of this instance.

Returns
strUndocumented
def assert_enum(self):

Asserts to the type system that the bitfield produces an enumeration value.

Information

Returns
BitfieldInstance[EnumerationInstance]the same bitfield instance, but with the additional information for the type system that it returns a EnumerationInstance.
Raises
ValueErrorif the bitfield instance does not, in fact, produce an enumeration value, according to its runtime type.
def assert_int(self):

Asserts to the type system that the bitfield produces an integer value.

Information

Returns
BitfieldInstance[int]the same bitfield instance, but with the additional information for the type system that it returns an int.
Raises
ValueErrorif the bitfield instance does not, in fact, produce an integer value, according to its runtime type.
def format(self, max_depth=1, current_depth=1):

Undocumented

Parameters
max_depth:intUndocumented
current_depth:intUndocumented
def read(self):

Reads the value produced by the bitfield.

Bitfields can produce integer or enumeration type depending on the type they're slicing.

Returns
_ValueTypeUndocumented
def read_bitarray(self):

Reads the bitfield as an array of bits of the size of the bitfield.

Returns
_bitarrayUndocumented
def read_enum(self):

Reads the bitfield after asserting to the type system that it produces an enumeration value.

Calling this method is equivalent to self.assert_enum().read().

Information

Returns
EnumerationInstancethe same value as produced by read, but with the additional information for the type system that it is an EnumerationInstance.
Raises
ValueErrorif the bitfield instance does not, in fact, produce an enumeration value, according to its runtime type.
def read_int(self):

Reads the bitfield after asserting to the type system that it produces an integer value.

Calling this method is equivalent to self.assert_int().read().

Information

Returns
intthe same value as produced by read, but with the additional information for the type system that it is an int.
Raises
ValueErrorif the bitfield instance does not, in fact, produce an integer value, according to its runtime type.
@property
info: Bitfield =

The information (offset, name, length, position) about the bitfield associated with this instance.

@property
parent_instance: StructInstance =

The struct instance that this instance originates from.

_field =

Undocumented

_struct =

Undocumented