dumpling.Drivers package

Submodules

dumpling.Drivers.JTAG module

class dumpling.Drivers.JTAG.JTAGDriver(vector_builder: VectorBuilder)[source]

Bases: object

The JTAGDriver class provides convenience functions to interact with a specific JTAG chain.

The driver instance requires a VectorBuilder instance in order generate vector in the required format.

The JTAGDriver expects the VectorBuilder to contain pin declarations with the following logical name (the physical name is not relevant for the driver):

  • ‘tck’: The jtag clock pin

  • ‘trst’: The test logic reset pin

  • ‘tms’: The test mode select pin

  • ‘tdi’: The test data in pin

  • ‘tdo’: The test data out pin

For the tck, tms, trst and tms pins the driver will write vectors containing the ‘0’ and ‘1’ on state character to denote application of logic low and logic high (or no-clk and clk in the case of TCK). The state character for the tdo pin can either be ‘0’ for sampling and comparison with logic low, ‘1’ for sampling and comparison with logic high or ‘X’ if the output of TDO should be ‘don’t care’ for the current vector.

After instantiation of the driver, the JTAG chain configuration needs to be configured by adding JTAGTap instances in the order they are hooked up the JTAG chain. This enables the JTAGDriver class and the JTAGTap instances that interact with this driver to provide high-level functions for JTAG interaction without needing to now the number of additional TAPs on the same chain.

E.g.:

driver = JTAGDriver(my_vector_builder)
riscv_debug_tap = RISCVDebugTap(driver)
driver.add_tap(risc_debug_tap)
driver.add_tap(JTAGTap(ir_size=5, driver=driver)) #Add some dummy tap

#Start using the taps or the driver driver directly
vectors = risc_debug_tap.halt_harts(...)
vectors += driver.jtag_set_dr(...)
writer.write_vectors(vectors)

For TAPs that we don’t need to interact with you can just add instantiations of the JTAGTap base class as a dummy tap to make sure the driver accounts for the additional flip-flops in the chains IR and DR path. Unless otherwise stated, the high-level functions provided by the individual taps will always select the BYPASS register for all other taps except the one that should be currently used.

Parameters:

vector_builder (VectorBuilder) – A handle to a configured vector builder.

add_tap(jtag_tap: JTAGTap)[source]

Adds a new JTAG TAP to the chain controlled by this driver instance.

The TAPs are supposed to be added in the same order that the TDI signal passes through them. E.g. if the TDI enters the chip, passes TAP1, leaves TAP1 through it’s TDO, enters TAP2 through the TDI and finally leaves the chip through TDO, register the TAPs in the following order:

self.add_tap(TAP1)
self.add_tap(TAP2)
Parameters:

jtag_tap – The JTAG TAP to add to the chain.

Returns:

jtag_goto_shift_dr(comment='')[source]

Return vectors to enter the Shifr DR state.

Parameters:

comment (str) – An optional comment with which to annotate the generated vectors.

Returns:

A list of vectors

Return type:

List[Mapping]

jtag_goto_shift_ir(comment='')[source]

Return vectors to enter the Shifr IR state.

Parameters:

comment (str) – An optional comment with which to annotate the generated vectors.

Returns:

A list of vectors

Return type:

List[Mapping]

jtag_idle_vector(repeat=1, comment=None)[source]

Returns a single vector with the given ‘repeat’ value to keep the JTAG interface idle.

The vector will turn off the JTAG clock and keep the TMS pin low.

Parameters:

  • repeat – The number of cycles to repeat the idle vector

  • comment (str) – An optional comment to annotate the generated vector with

Returns:

A single vector

Return type:

Mapping

jtag_idle_vectors(count=1)[source]

Returns a list of JTAG idle vectors of the given length.

This function does basically the same as jtag_idle_vector but will just return a list with the required number of jtag idle vectors as element instead of making us of the repeat value of the vector.

Parameters:

count – The number of jtag idle vectors to return

Returns:

A list of vectors

Return type:

List[Mapping]

jtag_reset()[source]

Returns vectors to reset the jtag interface.

Returns:

A list of vectors

Return type:

List[Mapping]

jtag_set_dr(tap: JTAGTap, dr_value, expected_dr_value=None, comment='', noexit=False)[source]

Writes the given dr_value into the chosen JTAG tap’s data register (DR).

The dr_value is written LSB first and must only contain the bits that should actually end up in the DR of the tap. The driver assumes that all taps except of the targeted one have been brought into bypass mode (as is the behavior of the jtag_set_ir function). The driver will take care of padding the desired dr_value with the appropriate number of ‘0’s to account for the additional flip-flops of the additional TAPs before and/or after the targeted TAP in the chain. The data shifted out of the target DR is compared with the optional expected_dr_vaue. After the shift operation, the JTAG FSM is brought back into “Run Test Idle” state unless noexit is True.

Parameters:

  • tap (JTAGTap) – The TAP for which the DR value should be

  • dr_value (str) – A binary string to shift into the target TAP LSB first

  • expected_dr_value (str) – An optional binary string with which to compare the DR_Value that was shifted out of the chain.

  • comment (str) – An optional comment with which to annotate the generated vectors

  • noexit (bool) – If True, don’t exit the shift state, otherwise the last few vectors returned by this function put the JTAG FSM back into “Run Test Idle”

Returns:

A list of vectors

Return type:

List[Mapping]

jtag_set_ir(tap: JTAGTap, ir_value, comment='')[source]

Sets the IR value LSB first of the given JTAG tap while putting all other taps of the chain into BYPASS mode.

The ir_value is a binary string and shifted LSB first (thus right to left) as oposed to the jtag_shift function. Since the driver is aware of the additional TAPs besided the targeted TAP, the IR length of additional JTAG TAPs in the chain do not have to be accounted for when chosing the IR_VALUE. The driver will automatically pad the ir_value with the appropriate bits to put all other TAPs before and/or after the target TAP into bypass mode.

Parameters:

  • tap (JTAGTap) – The TAP for which the ir_value should be set.

  • ir_value (str) – The IR value as a binary string containing ‘0’s and ‘1’s. The value is shifted LSB first.

  • comment (str) – An optional comment with which to annotate the generated vectors

Returns:

A list of vectors

Return type:

List[Mapping]

jtag_shift(chain, expected_chain=None, comment='', noexit=False)[source]

Shift the given value into the JTAG chain optionally matching with an expected value during readout.

This function expects the JTAG chain to already be in either the shift IR or the shift DR state. The binary string supplied with the chain argument is shifted into the jtag chain while the shift output is optionally compared with the expected_chain value. Unless noexit is True, after all the data in chain, thus after len(chain) JTAG cycles has been shifted into the chain, the shift IR/shift DR state is left and the chain is brought into “Run Test Idle” state.

The data is shifted in the order they appear in the chain and expected_chain string (thus left to right).

Parameters:

  • chain (str) – A string containing ‘0’ and ‘1’ that should be shifted into the chain.

  • expected_chain (str) – None, or a string containing ‘0’, ‘1’ and ‘X’ that should be compared with the data

  • chain. (shifted out of the) –

  • comment (str) – An optional comment with which to annotate the generated vectors

  • noexit (bool) – If True, don’t exit the shift state, otherwise the last few vectors returned by this function put the JTAG FSM back into “Run Test Idle”

Returns:

A list of vectors

Return type:

List[Mapping]

read_reg(tap: JTAGTap, reg: JTAGRegister, reg_length, expected_value=None, comment='')[source]

Read a given JTAG register from a targeted tap and match the value with an expected one.

This function generates the vectors to read from a specific jtag register of a TAP. An all zeros string is shifted into the chain while reading the DR value of length reg_length. The expected_value is compared with the data from the JTAG chain LSB first. The function takes care of selecting the desired register by shifting the correct IR value and putting all other taps in the same chain in BYPASS mode. The expected_value must only contain bits that should actually match the bits of the desired register. Additional zero padding for the bypassed TAPs is already accounted for internally.

Parameters:

  • tap (JTAGTap) – The tap from which to read.

  • reg (JTAGRegister) – An JTAG register within the specified tap from which to read.

  • reg_length (int) – The number of bits to read from the JTAG register.

  • expected_value (str) – An optionial expected DR_value whith which the DR value read is compared.

  • comment (str) – An optional comment with which to annotate the generated vectors

Returns:

A list of vectors

Return type:

List[Mapping]

set_jtag_default_values()[source]

Apply default (idle) values to the jtag pins.

This function will only alter the state of the jtag pins in the underlying vector builder without generating any vectors yet. It will not affect any non-jtag pin that might be present in the vector_builder instance.

Returns:

write_reg(tap, reg, value, comment='')[source]

Write the desired value to a given JTAG register of a targeted tap.

This function generates the vectors to write to a specific jtag register of a TAP. The data is shifted LSB first (the value string is thus shifted right to left). The function takes care of selecting the desired register by shifting the correct IR value and putting all other taps in the same chain in BYPASS mode. The value must only contain bits that should actually be written to the desired register. Additional zero padding for the bypassed TAPs is already performed internally.

Parameters:

  • tap (JTAGTap) – The tap from which to read.

  • reg (JTAGRegister) – An JTAG register within the specified tap from which to read.

  • value (str) – The value to be shifted into the chosen JTAG register, LSB (right) first to MSB (left).

  • comment (str) – An optional comment with which to annotate the generated vectors

Returns:

A list of vectors

Return type:

List[Mapping]

Module contents