BitFields - added a few tests and improved javadoc

This commit is contained in:
ghidra1 2019-07-17 09:48:38 -04:00
parent 20000d42e5
commit 9280b696a9
9 changed files with 157 additions and 51 deletions

View file

@ -69,7 +69,7 @@ abstract class CompositeDB extends DataTypeDB implements Composite {
/**
* Get the preferred length for a new component. For Unions and internally aligned
* structures the preferred component length for a fixed-length dataType will be the
* length of that dataType. Otherwise the length returned will be no larger then the
* length of that dataType. Otherwise the length returned will be no larger than the
* specified length.
* @param dataType new component datatype
* @param length constrained length or -1 to force use of dataType size. Dynamic types

View file

@ -25,13 +25,15 @@ import ghidra.util.exception.AssertException;
/**
* <code>BitFieldDataType</code> provides a means of defining a minimally sized bit-field
* for use within data structures. The length (i.e., storage size) of this datatype
* less than or equal to the base datatype size and will always be the smallest possible size
* to contain the bitfield and offset within the least significant byte containing the
* lsb of the bitfield.
* for use within data structures. The length (i.e., storage size) of this bitfield datatype is
* the minimum number of bytes required to contain the bitfield at its specified offset.
* The effective bit-size of a bitfield will be limited by the size of the base
* datatype whose size may be controlled by its' associated datatype manager and data organization
* (e.g., {@link IntegerDataType}).
* <p>
* NOTE: This datatype implementation is intended for internal use only. Creating bitfields
* must be accomplished directly via a Structure or Union instance API method.
* NOTE: Instantiation of this datatype implementation is intended for internal use only.
* Creating and manipulating bitfields should be accomplished directly via Structure or Union
* bitfield methods.
*/
public class BitFieldDataType extends AbstractDataType {

View file

@ -62,7 +62,7 @@ public abstract class CompositeDataTypeImpl extends GenericDataType implements C
/**
* Get the preferred length for a new component. For Unions and internally aligned
* structures the preferred component length for a fixed-length dataType will be the
* length of that dataType. Otherwise the length returned will be no larger then the
* length of that dataType. Otherwise the length returned will be no larger than the
* specified length.
* @param dataType new component datatype
* @param length constrained length or -1 to force use of dataType size. Dynamic types

View file

@ -347,13 +347,30 @@ public interface Structure extends Composite {
public void pack(int maxAlignment) throws InvalidInputException;
/**
* <code>BitOffsetComparator</code> provides ability to compare an Integer bit offset
* with a DataTypeComponent object. The offset will be consider equal (0) if
* the component contains the offset. Bit offsets for this comparator number the
* msb of the first byte in the structure as 0 and the lsb of the last byte as
* (8 * structLength) - 1. Due to the storage order of bitfields within little-endian
* organization a normalized bit-offset must be used which corresponds to the msb getting
* filled first (in reality little-endian fills the lsb first).
* <code>BitOffsetComparator</code> provides ability to compare an normalized bit offset
* (see {@link #getNormalizedBitfieldOffset(int, int, int, int, boolean)} with a
* {@link DataTypeComponent} object. The offset will be considered equal (0) if the component
* contains the offset. A normalized component bit numbering is used to establish the footprint
* of each component with an ordinal-based ordering (assumes specific LE/BE allocation rules).
* Bit offsets for this comparator number the first allocated bit of the structure as 0 and the
* last allocated bit of the structure as (8 * structLength) - 1. For big-endian bitfields
* the msb of the bitfield will be assigned the lower bit-number (assumes msb-allocated-first),
* while little-endian will perform similar numbering assuming byte-swap and bit-reversal of the
* storage unit (assumes lsb-allocated-first). Both cases result in a normalized view where
* normalized bit-0 is allocated first.
*
* Example:
*
* Big-Endian (normalized view):
* | . . . . . . . 7 | 8 9 . . . . . . |
* |<--------------------------------->| storage-size (2-bytes)
* |<--------------| bit-offset (6, lsb position within storage unit)
* |<--->| bit-size (3)
*
* Little-Endian (normalized view, w/ storage byte-swap and bit-reversal):
* | . . . . . . 6 7 | 8 . . . . . . . |
* |------------>| bit-offset (6, lsb position within storage unit)
* |<--->| bit-size (3)
*/
public static class BitOffsetComparator implements Comparator<Object> {
@ -393,8 +410,12 @@ public interface Structure extends Composite {
}
/**
* Compute the normalize bit offset of a bitfield relative to the start of a structure where
* the lsb of a bit-field is assigned an offset smaller than the msb.
* Compute the normalized bit offset of a bitfield relative to the start of a structure.
*
* NOTE: This implementation currently relies only on endianess to dictate bit allocation
* ordering. If future support is added for alternate bitfield packing, this implementation will
* require modification.
*
* @param byteOffset byte offset within structure of storage unit
* @param storageSize storage unit size (i.e., component length)
* @param effectiveBitSize size of bitfield in bits

View file

@ -16,7 +16,11 @@
package ghidra.program.model.data;
/**
* The Union marker interface
* The union interface.
* <p>
* NOTE: The use of bitfields within all unions assumes a default packing where bit allocation
* always starts with byte-0 of the union. Bit allocation order is dictated by data organization
* endianess (byte-0 msb allocated first for big-endian, while byte-0 lsb allocated first for little-endian).
*/
public interface Union extends Composite {