# IPC Datatypes for Users

There are a number of classes used within the IPC-CLI, but there are only a few that are recommended/needed by users of the IPC-CLI. Those classes/types will be documented here

> - `BitData()`

> - `Address()`

## BitData

class BitData(*args, **kwargs)

  This BitData provides numerous functions to help with displaying numbers as hex, setting/retrieving only certain bits, and lots of other bit granularity functions.

  Parameters

    - length (int, optional) – the bit length of the data being passed in

    - value (int, string) – the value to be stored in the BitData object

  If length is not specified, then the value must be passed in as a string. Then the length will be guessed based on the number of bits.

  There are many ways to access the data after a new bit data object has been created. However, the fastest/most-efficient is to use array style syntax.

  Some Examples of BKMS for usage:

      >>> bits = ipccli.BitData(32,0xAA55)
      >>> bits[0:7]
      [8b] 0x55
      >>> bits[0]
      0x1L
      >>> bits[0:7] = 0xAA
      >>> bits
      [32b] 0x0000AAAA
      >>>

  And of course, the bitdata can also be treated as a number most of the time:

      >>> bits = ipccli.BitData(32,1)
      >>> bits = bits + 1
      >>> bits
      [32b] 0x00000002
      >>> bits = bits << 2
      >>> bits
      [32b] 0x00000008
      >>> bits / 2
      [32b] 0x00000004

  As you can tell from the examples above, the default display for a bitdata is in hex.

  Bit Data Operation Queuing

  There are additional arguments that provide the ability to queue up operations instead of applying them immediately. These queueing operations should ONLY be used during state representations. When used with simple numbers, there is no benefit to delaying the operations. The primary use case for queuing is to use with Operation Receipts. However, for simplicity’s sake, the examples use standard numbers. In the example you can see that the bitdata in queue mode can pretty much be treated like a standard bitdata:

      >>> bdata = ipc.BitData(32,0x5A,queue=True)
      >>> bdata = ipc.BitData(32,0x5A,queue=True)
      >>> bdata2 = bdata[7:4]
      >>> bdata2
      [4b] 0x5
      >>> bdata3 = bdata2 + 1
      >>> bdata3
      [4b] 0x6
      >>> bdata4 = ~bdata2
      >>> bdata4
      [4b] 0xA

  If you already have a bit data, and want to enable the queuing, that can be done via:

      >>> bdata.Queue()

  “Slicing” (treating the bitdata object like an array) is the recommended way to do operations on portions of bitdata objects (keeping in mind that the bitsize of the result is kept consistent with the slice requested).

  Builtin math operations are supported, as well as the following functions that are specific to the queuing mode:

  - AddErrorCheck - see below for more examples of this function.

  Most all of the other BitData functions for extracting or displaying data shoud be avoided if a flush is not desired. Only the following can be executed without causing a flush:

  - Reverse

  All of the following functions will implictily force a flush. Again, most of these can directly be replaced by using slicing:

  - Append, Concatenate, Extract functions, Copy, To___ functions, IsBitOn, IsBitOff

  There are certain BitData functions that are only valid while Queuing is enabled. Currently those are:

  > - AddErrorCheck

  AddErrorCheck(lowerbit, numbits, check_value, message='')

    Queue up a check that will be done. If the specified bits do not match check_value, then an exception will be thrown with the message that is given.

    Parameters

      - lowerbit (int) – bottom bit to begin compare to.

      - numbits (int) – number of bits to compare against.

      - check_value (int) – value to check against.

      - message (str) – optional string to give for the exception that should display if the compare fails.

    Example

        >>> bdata = ipccli.BitData(32,0x1,queue=True)
        >>> bdata.AddErrorCheck(0,4,0,"compare to 0 will fail, causing an exception")
        >>> print bdata
        Traceback (most recent call last):
          File "<stdin>", line 1, in <module>
          File "C:\Python27\lib\site-packages\ipccli\bitdata.py", line 570, in __repr__
            if self._q_enabled: self._q_flush() # make sure we are not queuing first
          File "C:\Python27\lib\site-packages\ipccli\bitdata.py", line 362, in _q_flush
            exp_value,checkval))
        ValueError: compare to 0 will fail, causing an exception Expected: 0, Actual 1

    Raises

      RuntimeError – if queuing is not enabled for the BitData object.

  Append(bitdata)

    Takes a bitdata and adds the value to the upper bits of this bitdata.

    This is the same as: bitdata_orig = (bitdata << len(bitdata_orig)) | bitdata_orig

    Parameters

      bitdata – must be a bitdata object

    Returns

      returns this same object (not a new one) so that operatoins can be chained if needed

    Example

        >>> b1 = ipc.BitData(4,0x5)
        >>> b2 = ipc.BitData(4,0xA)
        >>> b1.Append(b2)
        >>> b1
        [8b] 0xA5
        >>>

  property BitSize

    Returns the number of bits (or length) that represent the number stored here.

  Concatenate(bitdata)

    This is the equivalent of Append, but returns a new bitdata object.

    This is the same as: bitdata_new = (bitdata << len(bitdata_orig)) | bitdata_orig

    Parameters

      bitdata – must be a bitdata object.

    Example

        >>> bitdata_orig.Concatenate( bitdata )

  Copy(startbit=None, length=None)

    Copies the requested bits in to a new bitdata object and returns it.

    Parameters

      - startbit (int) – where to begin copying to new bitdata.

      - length (int) – number of bits to copy to new bitdata.

    Returns

      New BitData object

    This is similar to the Extract function but it returns a bitdata instead of a just the number. If no args are specified, then a copy of this BitData is returned.

  classmethod CreateFromInt(length, int_value, truncate=False, verify=True)

    Create using exactly two arguments.

    Parameters

      - length (int) – Bit length of this bitdata.

      - int_value (int) – number or object that behaves as an integer.

      - truncate (bool) – whether to truncate data when it grows beyond bitsize (default: False)

      - verify (bool) – whether to verify length is correct for the given int_value

    Note

    This function is aimed at improving performance and no bounds or type checking is done. If checking is desired, use the standard constructor.

  classmethod CreateFromLong(length, int_value, truncate=False, verify=True)

    Create using exactly two arguments.

    Parameters

      - length (int) – Bit length of this bitdata.

      - int_value (int) – number or object that behaves as an integer.

      - truncate (bool) – whether to truncate data when it grows beyond bitsize (default: False)

      - verify (bool) – whether to verify length is correct for the given int_value

    Note

    This function is aimed at improving performance and no bounds or type checking is done. If checking is desired, use the standard constructor.

  Deposit(startbit, length, value)

    Changes the specified bits within this bitdata to have the new value.

    Parameters

      - startbit (int) – bit to begin depositing the new value (default=0).

      - length (int) – number of bits in this bitdata to change (default=all bits).

      - value (int) – value to insert.

    Note

    This is very similar to using the slicing capabilities.

    Returns

      This bitdata object is returned (not a new one).

    Raises

      IndexError – if the starting bit plus the length is greater than the size of the BitData object.

  Extract(startbit=None, length=None)
    Parameters

      - startbit (int) – bit to begin extracting (default=0).

      - length (int) – number of bits in this bitdata to extract (default=all bits).

    Returns

      A Python long.

    Note

    This is very similar to using the slicing capabilities, but it returns a long instead of a BitData.

    Example

        >>> bdata = BitData(32,0)
        >>> long(bdata[startbit:startbit+length-1]) == bdata.Extract(startbit,length)

    Raises

      IndexError – if the starting bit plus the length is greater than the size of the BitData object.

  Extract32(startbit)

    This is the same as calling Extract(startbit, 32). See Extract help for detailed info on extract.

  Extract64(startbit)

    This is the same as calling Extract(startbit, 64). See Extract help for detailed info on extract.

  Invert(*args)

    In-place invert of the bits using the given bit mask. Optionally, lowerbit and numbits can be specified. Returns itself.

    Example

        >>> bdata.Invert(mask)
        >>> bdata.Invert(lowerbit, numbits, mask)

    Raises

      Exception – if an invalid number of arguments are passed

  IsBitOff(bit_num)

    Returns a boolean value that reports whether bit_num was clear.

    Parameters

      bitnum (int) – bit to check if == 0.

    Example

        >>> bit2set = BitData(32,0x4)
        >>> bit2set.IsBitOff(2)
        False
        >>> bit2set.IsBitOff(0)
        True

  IsBitOn(bit_num)

    Returns a boolean value that reports whether bit_num was set.

    Parameters

      bitnum (int) – bit to check if == 1.

    Example

        >>> bit2set = BitData(32,0x4)
        >>> bit2set.IsBitOn(2)
        True
        >>> bit2set.IsBitOn(0)
        False

  PopCount(startbit=0, length=None)

    Count the number of set bits in this bitdata.

    Parameters

      - startbit (int) – bit to begin counting (default=0).

      - length (int) – number of bits in this bitdata to count (default=all bits).

    Example

        >>> bdata = ipc.BitData(8,0xF0)
        >>> bdata.PopCount()
        0x4
        >>> bdata.PopCount(5)
        0x3
        >>> bdata.PopCount(0,6)
        0x2

  Queue(operations=None)

    Turns on operations Queuing for this BitData. Future operations will be Queued instead of being applied immediately

    Parameters

      operations (list) – (optional) list of queued operations.

    The operations list should not be built by hand. It is used by the BitData class to build the queued list of operations that should be executed when we finally evaluate the object.

    Raises

      Exception – if queuing is already enabled.

  ReadByteArray(bitOffset=0, byteCount=None)

    Return a list where each entry is one byte worth of data.

    Parameters

      - bitOffset – starting bit to begin creating array (default=0).

      - byteCount – number of bytes to convert (default= use BitSize to calculate).

  Reverse(bitOffset=0, bitSize=None)

    Returns a new bitdata object with the specified bits reversed.

    Parameters

      - bitOffset (int) – Offset to first bit in bitfield to reverse.

      - bitSize (int) – Size of bitfield to reverse.

    Returns

      A new BitData containing the reversed value.

    Example

        >>> myBitData = BitData(16, 0xAAAA)
        >>> rbitdata = myBitData.Reverse()
        >>> myBitData
        [16b] 0xAAAA
        >>> rbitdata
        [16b] 0x5555

  SetBit(bit_num, value)

    Change the specified bit to a new value.

    Parameters

      - bitnum (int) – bit to change.

      - value (int) – new value.

    Example

        >>> bitset = ipccli.BitData(32,4)
        >>> bitset.SetBit(3,1)
        >>> bitset
        [32b] 0x0000000C

  ToBinary()

    Display value as a binary string.

  ToDecimal()

    Display value as a decimal string.

  ToHex()

    Display value as a hex string.

  ToRawBytes(bitOffset=0, byteCount=None)

    Return as a list where each entry is one byte worth of data.

    Parameters

      - bitOffset – starting bit to begin creating array (default=0).

      - byteCount – number of bytes to convert (default= use BitSize to calculate).

    This function was created to return an array of bytes. It has additional parameters in order to provide backwards compatibility for the ReadByteArray function (which was discovered after this function was created).

  ToString()

    Return string version that is the same as repr(bitdata).

  ToUInt32()

    Return raw integer value…same as int(bitdata).

  ToUInt64()

    Return raw integer value…same as long(bitdata).

  __apply_numeric_operation__(num_op, other, rightside=False)

    Used for generic numeric operations where our bitdata is on the left

  __getslice__(start, end)

    BitData supports different indexing options than python list. Indices are inclusive, and can be given as [start:end] or [end:start]

  append(bitdata)

    Takes a bitdata and adds the value to the upper bits of this bitdata.

    This is the same as: bitdata_orig = (bitdata << len(bitdata_orig)) | bitdata_orig

    Parameters

      bitdata – must be a bitdata object

    Returns

      returns this same object (not a new one) so that operatoins can be chained if needed

    Example

        >>> b1 = ipc.BitData(4,0x5)
        >>> b2 = ipc.BitData(4,0xA)
        >>> b1.Append(b2)
        >>> b1
        [8b] 0xA5
        >>>

  invert(*args)

    In-place invert of the bits using the given bit mask. Optionally, lowerbit and numbits can be specified. Returns itself.

    Example

        >>> bdata.Invert(mask)
        >>> bdata.Invert(lowerbit, numbits, mask)

    Raises

      Exception – if an invalid number of arguments are passed

  property value

    The value property exists for backwards compatibility, but it is not recommended to use directly. Use: long(bitdata_object) to get the value.

  verify(value, mask=None, compare_type='==', msg='')

    Compares the value of this BitData with the value given when the bundle is executed. If the compare is False then a BundleVerifyFailed is raised.

    value is the numeric value to compare to. mask is the bit mask to apply to the BundleMap before the compare, defaults is no mask. compare_type is the compare operation to perform, defaults to equality. msg is the message to be raised with the exception if compare is False.

    Valid compare_type values are: “==”, “!=”, “<”, “<=”, “>”, “>=”.

    Example evaluation would be:

      long(self) & mask < value == raise ValueError if this is false

  verify_delayed(value, mask=None, compare_type='==', msg='')

    Stores the verify-instructions so they get executed later Supports the same format as traditional verify: value is the numeric value to compare to. mask is the bit mask to apply to the BundleMap before the compare, defaults is no mask. compare_type is the compare operation to perform, defaults to equality. msg is the message to be raised with the exception if compare is False.

    Valid compare_type values are: “==”, “!=”, “<”, “<=”, “>”, “>=”.

  verify_other(the_other)

    Joins the list of delayed verification operations from the_other and adds it to current (self)

## Address

class Address(*args, **kwargs)

  Used to create an address object that can be passed to various cli functions. The address can be initialized using a string that supports multiple forms.

  Linear addresses:

    - “36L” == interpreted as 36 decimal or 0x20 hexadecimal linear address

    - “0x20L” == interpreted as 36 decimal or 0x20 hexadecimal linear address

  Physical addresses:

    - “36P” == interpreted as 36 decimal or 0x20 hexadecimal physical address

    - “0x20P” == interpreted as 36 decimal or 0x20 hexadecimal physical address

  Two field virtual (both are assumed hex):

    - “10:000” == segment: 0x10, offset: 0

  Thread field virtual (both are assumed hex):

    - “B0:10:000” == table: 0xB0, segment: 0x10, offset: 0

class AddressType

  This is an enumlike class that provides some backwards compatibility with legacy tools