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