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

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