Extras¶
PyLink makes use of a number of different submodules as a part of its implementation. These submdules are extras, and the user should not need to use them explicitly.
Binpacker¶
This submodule provides functions for creating arrays of bytes from an integer.
-
pylink.binpacker.
pack
(value, nbits=None)¶ Packs a given value into an array of 8-bit unsigned integers.
If
nbits
is not present, calculates the minimal number of bits required to represent the givenvalue
. The result is little endian.Parameters: - value (int) – the integer value to pack
- nbits (int) – optional number of bits to use to represent the value
Returns: An array of
ctypes.c_uint8
representing the packedvalue
.Raises: ValueError
– ifvalue < 0
andnbits
isNone
ornbits <= 0
.TypeError
– ifnbits
orvalue
are not numbers.
-
pylink.binpacker.
pack_size
(value)¶ Returns the number of bytes required to represent a given value.
Parameters: value (int) – the natural number whose size to get
Returns: The minimal number of bytes required to represent the given integer.
Raises: ValueError
– ifvalue < 0
.TypeError
– ifvalue
is not a number.
Decorators¶
This submodule provides different decorator functions.
-
pylink.decorators.
async_decorator
(func)¶ Asynchronous function decorator. Interprets the function as being asynchronous, so returns a function that will handle calling the Function asynchronously.
Parameters: func (function) – function to be called asynchronously Returns: The wrapped function. Raises: AttributeError
– iffunc
is not callable
Registers¶
This submodule provides ctypes bindings for different registers.
-
class
pylink.registers.
AbortRegisterBits
¶ Bases:
_ctypes.Structure
This class holds the different bit mask for the Abort Register.
-
DAPABORT
¶ write
1
to trigger a DAP abort.
-
STKCMPCLR
¶ write
1
to clear theSTICKYCMP
sticky compare flag (only supported on SW-DP).
-
STKERRCLR
¶ write
1
to clear theSTICKYERR
sticky error flag (only supported on SW-DP).
-
WDERRCLR
¶ write
1
to clear theWDATAERR
write data error flag (only supported on SW-DP).
-
ORUNERRCLR
¶ write
1
to clear theSTICKYORUN
overrun error flag (only supported on SW-DP).
-
DAPABORT
Structure/Union member
-
ORUNERRCLR
Structure/Union member
-
RESERVED
¶ Structure/Union member
-
STKCMPCLR
Structure/Union member
-
STKERRCLR
Structure/Union member
-
WDERRCLR
Structure/Union member
-
-
class
pylink.registers.
AbortRegisterFlags
¶ Bases:
_ctypes.Union
Mask for the abort register bits.
-
value
¶ the value stored in the mask.
-
DAPABORT
¶ Structure/Union member
-
ORUNERRCLR
¶ Structure/Union member
-
RESERVED
¶ Structure/Union member
-
STKCMPCLR
¶ Structure/Union member
-
STKERRCLR
¶ Structure/Union member
-
WDERRCLR
¶ Structure/Union member
-
bit
¶ Structure/Union member
-
value
Structure/Union member
-
-
class
pylink.registers.
ControlStatusRegisterBits
¶ Bases:
_ctypes.Structure
This class holds the different bit masks for the DP Control / Status Register bit assignments.
-
ORUNDETECT
¶ if set, enables overrun detection.
-
STICKYORUN
¶ if overrun is enabled, is set when overrun occurs.
-
TRNMODE
¶ transfer mode for acess port operations.
-
STICKYCMP
¶ is set when a match occurs on a pushed compare or verify operation.
-
STICKYERR
¶ is set when an error is returned by an access port transaction.
-
READOK
¶ is set when the response to a previous access port or
RDBUFF
wasOK
.
-
WDATAERR
¶ set to
1
if a Write Data Error occurs.
-
MASKLANE
¶ bytes to be masked in pushed compare and verify operations.
-
TRNCNT
¶ transaction counter.
-
RESERVED
¶ reserved.
-
CDBGRSTREQ
¶ debug reset request.
-
CDBGRSTACK
¶ debug reset acknowledge.
-
CDBGPWRUPREQ
¶ debug power-up request.
-
CDBGPWRUPACK
¶ debug power-up acknowledge.
-
CSYSPWRUPREQ
¶ system power-up request
-
CSYSPWRUPACK
¶ system power-up acknowledge.
See also
See the ARM documentation on the significance of these masks here.
-
CDBGPWRUPACK
Structure/Union member
-
CDBGPWRUPREQ
Structure/Union member
-
CDBGRSTACK
Structure/Union member
-
CDBGRSTREQ
Structure/Union member
-
CSYSPWRUPACK
Structure/Union member
-
CSYSPWRUPREQ
Structure/Union member
-
MASKLANE
Structure/Union member
-
ORUNDETECT
Structure/Union member
-
READOK
Structure/Union member
-
RESERVED
Structure/Union member
-
STICKYCMP
Structure/Union member
-
STICKYERR
Structure/Union member
-
STICKYORUN
Structure/Union member
-
TRNCNT
Structure/Union member
-
TRNMODE
Structure/Union member
-
WDATAERR
Structure/Union member
-
-
class
pylink.registers.
ControlStatusRegisterFlags
¶ Bases:
_ctypes.Union
Mask for the control/status register bits.
-
value
¶ the value stored in the mask.
-
CDBGPWRUPACK
¶ Structure/Union member
-
CDBGPWRUPREQ
¶ Structure/Union member
-
CDBGRSTACK
¶ Structure/Union member
-
CDBGRSTREQ
¶ Structure/Union member
-
CSYSPWRUPACK
¶ Structure/Union member
-
CSYSPWRUPREQ
¶ Structure/Union member
-
MASKLANE
¶ Structure/Union member
-
ORUNDETECT
¶ Structure/Union member
-
READOK
¶ Structure/Union member
-
RESERVED
¶ Structure/Union member
-
STICKYCMP
¶ Structure/Union member
-
STICKYERR
¶ Structure/Union member
-
STICKYORUN
¶ Structure/Union member
-
TRNCNT
¶ Structure/Union member
-
TRNMODE
¶ Structure/Union member
-
WDATAERR
¶ Structure/Union member
-
bit
¶ Structure/Union member
-
value
Structure/Union member
-
-
class
pylink.registers.
IDCodeRegisterBits
¶ Bases:
_ctypes.Structure
This class holds the different bit masks for the IDCode register.
-
valid
¶ validity bit, should always be
0
.
-
manufactuer
¶ the JEDEC Manufacturer ID.
-
part_no
¶ the part number defined by the manufacturer.
-
version_code
¶ the version code.
-
manufacturer
¶ Structure/Union member
-
part_no
Structure/Union member
-
valid
Structure/Union member
-
version_code
Structure/Union member
-
-
class
pylink.registers.
IDCodeRegisterFlags
¶ Bases:
_ctypes.Union
Mask for the IDCode register bits.
-
value
¶ the value stored in the mask.
-
bit
¶ Structure/Union member
-
manufacturer
¶ Structure/Union member
-
part_no
¶ Structure/Union member
-
valid
¶ Structure/Union member
-
value
Structure/Union member
-
version_code
¶ Structure/Union member
-
-
class
pylink.registers.
MDMAPControlRegisterBits
¶ Bases:
_ctypes.Structure
This class holds the different bit masks for the MDM-AP Control Register.
-
flash_mass_erase
¶ set to cause a mass erase, this is cleared automatically when a mass erase finishes.
-
debug_disable
¶ set to disable debug, clear to allow debug.
-
debug_request
¶ set to force the core to halt.
-
sys_reset_request
¶ set to force a system reset.
-
core_hold_reset
¶ set to suspend the core in reset at the end of reset sequencing.
-
VLLDBGREQ
¶ set to hold the system in reset after the next recovery from VLLSx (Very Low Leakage Stop).
-
VLLDBGACK
¶ set to release a system held in reset following a VLLSx (Very Low Leakage Stop) recovery.
-
VLLSTATACK
¶ set to acknowledge that the DAP LLS (Low Leakage Stop) and VLLS (Very Low Leakage Stop) status bits have read.
-
VLLDBGACK
Structure/Union member
-
VLLDBGREQ
Structure/Union member
-
VLLSTATACK
Structure/Union member
-
core_hold_reset
Structure/Union member
-
debug_disable
Structure/Union member
-
debug_request
Structure/Union member
-
flash_mass_erase
Structure/Union member
-
sys_reset_request
Structure/Union member
-
-
class
pylink.registers.
MDMAPControlRegisterFlags
¶ Bases:
_ctypes.Union
Mask for the MDM-AP control register bits.
-
value
¶ the value stored in the mask.
-
VLLDBGACK
¶ Structure/Union member
-
VLLDBGREQ
¶ Structure/Union member
-
VLLSTATACK
¶ Structure/Union member
-
bit
¶ Structure/Union member
-
core_hold_reset
¶ Structure/Union member
-
debug_disable
¶ Structure/Union member
-
debug_request
¶ Structure/Union member
-
flash_mass_erase
¶ Structure/Union member
-
sys_reset_request
¶ Structure/Union member
-
value
Structure/Union member
-
-
class
pylink.registers.
MDMAPStatusRegisterBits
¶ Bases:
_ctypes.Structure
Holds the bit masks for the MDM-AP Status Register.
-
flash_mass_erase_ack
¶ cleared after a system reset, indicates that a flash mass erase was acknowledged.
-
flash_ready
¶ indicates that flash has been initialized and can be configured.
-
system_security
¶ if set, system is secure and debugger cannot access the memory or system bus.
-
system_reset
¶ 1
if system is in reset, otherwise0
.
-
mass_erase_enabled
¶ 1
if MCU can be mass erased, otherwise0
.
-
low_power_enabled
¶ 1
if low power stop mode is enabled, otherwise0
.
-
very_low_power_mode
¶ 1
if device is in very low power mode.
-
LLSMODEEXIT
¶ indicates an exit from LLS mode has occurred.
-
VLLSxMODEEXIT
¶ indicates an exit from VLLSx mode has occured.
-
core_halted; indicates core has entered debug halt mode.
-
core_deep_sleep
¶ indicates core has entered a low power mode.
-
core_sleeping
¶ indicates the core has entered a low power mode.
Note
if
core_sleeping & !core_deep_sleep
, then the core is in VLPW (very low power wait) mode, otherwise ifcore_sleeping & core_deep_sleep
, then it is in VLPS (very low power stop) mode.-
LLSMODEEXIT
Structure/Union member
-
RESERVED_A
¶ Structure/Union member
-
RESERVED_B
¶ Structure/Union member
-
RESERVED_C
¶ Structure/Union member
-
VLLSxMODEEXIT
Structure/Union member
-
backdoor_access_enabled
¶ Structure/Union member
-
core_deep_sleep
Structure/Union member
-
core_halted
¶ Structure/Union member
-
core_sleeping
Structure/Union member
-
flash_mass_erase_ack
Structure/Union member
-
flash_ready
Structure/Union member
-
low_power_enabled
Structure/Union member
-
mass_erase_enabled
Structure/Union member
-
system_reset
Structure/Union member
-
system_security
Structure/Union member
-
very_low_power_mode
Structure/Union member
-
-
class
pylink.registers.
MDMAPStatusRegisterFlags
¶ Bases:
_ctypes.Union
Mask for the MDM-AP status register bits.
-
value
¶ the value stored in the mask.
-
LLSMODEEXIT
¶ Structure/Union member
-
RESERVED_A
¶ Structure/Union member
-
RESERVED_B
¶ Structure/Union member
-
RESERVED_C
¶ Structure/Union member
-
VLLSxMODEEXIT
¶ Structure/Union member
-
backdoor_access_enabled
¶ Structure/Union member
-
bit
¶ Structure/Union member
-
core_deep_sleep
¶ Structure/Union member
-
core_halted
¶ Structure/Union member
-
core_sleeping
¶ Structure/Union member
-
flash_mass_erase_ack
¶ Structure/Union member
-
flash_ready
¶ Structure/Union member
-
low_power_enabled
¶ Structure/Union member
-
mass_erase_enabled
¶ Structure/Union member
-
system_reset
¶ Structure/Union member
-
system_security
¶ Structure/Union member
-
value
Structure/Union member
-
very_low_power_mode
¶ Structure/Union member
-
-
class
pylink.registers.
SelectRegisterBits
¶ Bases:
_ctypes.Structure
This class holds the different bit masks for the AP Select Register.
-
CTRLSEL
¶ SW-DP debug port address bank select.
-
RESERVED_A
¶ reserved.
-
APBANKSEL
¶ selects the active four-word register window on the current access port.
-
RESERVED_B
¶ reserved.
-
APSEL
¶ selects the current access port.
-
APBANKSEL
Structure/Union member
-
APSEL
Structure/Union member
-
CTRLSEL
Structure/Union member
-
RESERVED_A
Structure/Union member
-
RESERVED_B
Structure/Union member
-
-
class
pylink.registers.
SelectRegisterFlags
¶ Bases:
_ctypes.Union
Mask for the select register bits.
-
value
¶ the value stored in the mask.
-
APBANKSEL
¶ Structure/Union member
-
APSEL
¶ Structure/Union member
-
CTRLSEL
¶ Structure/Union member
-
RESERVED_A
¶ Structure/Union member
-
RESERVED_B
¶ Structure/Union member
-
bit
¶ Structure/Union member
-
value
Structure/Union member
-
Threads¶
This submodule provides custom threading.Thread types.
-
class
pylink.threads.
ThreadReturn
(daemon=False, *args, **kwargs)¶ Bases:
threading.Thread
Implementation of a thread with a return value.
See also
-
join
(*args, **kwargs)¶ Joins the thread.
Parameters: - self (ThreadReturn) – the
ThreadReturn
instance - args – optional list of arguments
- kwargs – optional key-word arguments
Returns: The return value of the exited thread.
- self (ThreadReturn) – the
-
run
()¶ Runs the thread.
Parameters: self (ThreadReturn) – the ThreadReturn
instanceReturns: None
-
Util¶
This submodule provides different utility functions.
-
pylink.util.
calculate_parity
(n)¶ Calculates and returns the parity of a number.
The parity of a number is
1
if the number has an odd number of ones in its binary representation, otherwise0
.Parameters: n (int) – the number whose parity to calculate Returns: 1
if the number has an odd number of ones, otherwise0
.Raises: ValueError
– ifn
is less than0
.
-
pylink.util.
flash_progress_callback
(action, progress_string, percentage)¶ Callback that can be used with
JLink.flash()
.This callback generates a progress bar in the console to show the progress of each of the steps of the flash.
Parameters: - action (str) – the current action being invoked
- progress_string (str) – the current step in the progress
- percentage (int) – the percent to which the current step has been done
Returns: None
Note
This function ignores the compare action.
-
pylink.util.
is_integer
(val)¶ Returns whether the given value is an integer.
Parameters: val (object) – value to check Returns: True
if the given value is an integer, otherwiseFalse
.
-
pylink.util.
is_natural
(val)¶ Returns whether the given value is a natrual number.
Parameters: val (object) – value to check Returns: True
if the given value is a natural number, otherwiseFalse
.
-
pylink.util.
is_os_64bit
()¶ Returns whether the current running platform is 64bit.
Returns: True
if the platform is 64bit, otherwiseFalse
.
-
pylink.util.
noop
(*args, **kwargs)¶ No-op. Does nothing.
Parameters: - args – list of arguments
- kwargs – keyword arguments dictionary
Returns: None
-
pylink.util.
progress_bar
(iteration, total, prefix=None, suffix=None, decs=1, length=100)¶ Creates a console progress bar.
This should be called in a loop to create a progress bar.
See StackOverflow.
Parameters: - iteration (int) – current iteration
- total (int) – total iterations
- prefix (str) – prefix string
- suffix (str) – suffix string
- decs (int) – positive number of decimals in percent complete
- length (int) – character length of the bar
Returns: None
Note
This function assumes that nothing else is printed to the console in the interim.
-
pylink.util.
unsecure_hook_dialog
(title, msg, flags)¶ No-op that ignores the dialog.
Parameters: - title (str) – title of the unsecure dialog
- msg (str) – text of the unsecure dialog
- flags (int) – flags specifying which values can be returned
Returns: enums.JLinkFlags.DLG_BUTTON_NO