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 given value. 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 packed value.

Raises:

ValueError – if value < 0 and nbits is None or nbits <= 0.
TypeError – if nbits or value 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 – if value < 0.
TypeError – if value 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 – if func is not callable

Registers¶

This submodule provides ctypes bindings for different registers.

class pylink.registers.AbortRegisterBits¶

Bases: 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 the STICKYCMP sticky compare flag (only supported on SW-DP).

STKERRCLR¶: write 1 to clear the STICKYERR sticky error flag (only supported on SW-DP).

WDERRCLR¶: write 1 to clear the WDATAERR write data error flag (only supported on SW-DP).

ORUNERRCLR¶: write 1 to clear the STICKYORUN 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: 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: 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 was OK.

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: 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: 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: 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: 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: 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: 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, otherwise 0.

mass_erase_enabled¶: 1 if MCU can be mass erased, otherwise 0.

low_power_enabled¶: 1 if low power stop mode is enabled, otherwise 0.

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 if core_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: 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: 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: 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: Thread

Implementation of a thread with a return value.

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, otherwise 0.

Parameters:: n (int) – the number whose parity to calculate
Returns:: 1 if the number has an odd number of ones, otherwise 0.
Raises:: ValueError – if n is less than 0.

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, otherwise False.

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, otherwise False.

pylink.util.is_os_64bit()¶

Returns whether the current running platform is 64bit.

Returns:: True if the platform is 64bit, otherwise False.

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