JTAGenum Open Source Project (2024)

JTAGenum is an open source Arduino JTAGenum.ino or RaspbberyPiJTAGenum.sh (experimental) scanner. This code was built with three primarygoals:

1. Given a large set of pins on a device determine which are JTAG lines
2. Enumerate the Instruction Register to find undocumented functionality
3. be easy to build and apply

JTAGenum is a more Arduino'y fork ofArduinull by Sébastien Bourdeauducq(lekernel), which is inspired by Benedikt Heinz'sJTAG scanner.JTAGenum also includes instruction scanning functionality best describedby Felix Domke (tmbinc) in his26c3 paper.The initial version of this branch was built for personal research and whileworking on various projects at Recurity Labs.

Please feel free to contact me with any questions, problems, targets orupdates. I would be more than happy if you fork and take the code inwhatever direction you choose.

• Embedded Analysis wiki: http://github.com/cyphunk/JTAGenum/wiki
• JTAGenum blog post: http://deadhacker.com/2010/02/03/jtag-enumeration/
• JTAGenum video tutorial "Ghetto Tools for Embedded Analysis REcon 2011":https://www.youtube.com/watch?v=ZmBfahwV3ss

• cyphunk http://github.com/cyphunk/JTAGenum/
• jal2 http://github.com/jal2/JTAGenum/
• zoobab http://hackerspace.be/JTAG_pinout_detector
• z1Y2x https://github.com/z1Y2x/JTAGenum/

Similar tools or branches:

• gremwell's https://github.com/gremwell/go-jtagenum (RaspberryPi go rewrite + improvements)
• joegrands's http://www.grandideastudio.com/jtagulator/ (purpose built hardware with improvements and added voltage range)
• szymonh's https://github.com/szymonh/SWDscan (arduino based SWD finder)
• szymonh's https://github.com/szymonh/JTAGscan (arduino based with logic similar to jtagulator)
• dxa4481's https://github.com/dxa4481/inputProtectionShield (1.8-5v voltage shifting shield)
• dipusone's https://github.com/dipusone/inputShieldProtection (fork of dxa4481's shield)
• commercial products MiracleBox, JTAGfinder, EasyJtag (GUI based, some limitations)

JTAGenum has been tested on the following hardware:

• RaspberryPi (3.3V) with mixed results
• standard Arduino (5V)
• Arduino on Teensy (3.3V) (http://www.pjrc.com/teensy/index.html)
• Arduino on Texas Instruments Tiva C / Stellaris (3.3V) (https://github.com/cyphunk/JTAGenum/issues/4)
• Arduino on STM32 Bluepill board (3.3V) (https://wiki.stm32duino.com/index.php?title=Blue_Pill and http://www.zoobab.com/bluepill-arduinoide)

When picking your micro-controller platform consider two issues:

1. How many pins do you want to check on your target.
2. what voltage level does your target device require.

Concerning voltage RaspberryPi's I/O operate at 3.3v, many Arduinoswork at 5 volts. Some are switchable but even those that are not couldbe modified. Alternatively voltage shifting Arduino shields orvoltage shifting gadgets can be used. See the Voltage Shifting Appendixdiscussion on the Embedded Analysis wiki for more details.https://github.com/cyphunk/JTAGenum/wiki/Embedded-Analysis#Voltage_Shifting

When connecting the micro-controller to the pins of your target onething to be aware of is possible cross-talk between wires. Theloopback check function in JTAGenum cab help you determine which wiresmay produce cross talk.

For use on Raspberry Pi use and consult the JTAGenum.sh. TheRaspberry Pi pins being used for scanning should be specified inside the scriptfile. This script is experimental and only provides the functions for finding JTAG.To use the script should be sourc'ed on the console the user should executethe desired scan. See the comments in the header of the script for further details.

For use on a Arduino the JTAGenum.ino sketch is loaded. The Arduino pinsbeing used for scanning should first be specified at the top of the sketch. Thisis all that is required for basic JTAG scanning functionality. Once thecorrect JTAG pins on the target have been determined they can be specified inthe script and along with the defining the proper IR_LENGTH the user can thenexecute the search for hidden instructions or print the boundary scan register.

Before loading the sketch first define the pins[] and pinnames[] arrays. Afterloadin the sketch open a serial console at baud of 115200 to access theuser interface. Sending a h to the console will print usage information thatdescribes each function. Each function is enacted by sending the defined onecharacter code:

v > verbose

Toggles verbose output. At times verbose might present too muchinformation or without it too little.

l > loopback check

Find loopback pairs that will generate false-positives for othertests. After running you should remove any loopback pairs from yourpins[]/pinnames[]. Looback pairs are found by sending a predeterminedpattern[] to all possible pins while checking all pins for matchingoutput. Because the JTAG clock (TCK) and state (TMS) pins are NOTbeing stimulated the input/output pairs where the pattern is foundrepresent loopbacks. NOTE: you should probably run this once withand without internal pull-up resistors set (r) to avoid problemsof cross-talk which is discussed in detail later.

s > scan

This routine is used to check all possible pins and find JTAG clock,state, input and output pins lines (TCK,TMS,TDI,TDO). This is doneby setting the JTAG state (TMS) into Shift_IR mode and then sendingpattern[] to TDI and checking for it on TDO while clocking TCK.This check is run for every possible pin combination and it isimportant that you remove loopback pins before running. While thisscan is meant to determine all of the JTAG pins required it ispossible that the TMS pin found is incorrect. This depends on ifthe target uses the bypass register by default (described later).If an IDCODE register is present then bypass mode is not the defaultand you can assume that the pin this scan defines as TMS is correct.Otherwise, only the TCK, TDI and TDO pins can be determined. NOTE:run with pull-ups on (r) as any cross-talk might result infalse-positives.

y > brute force IR search

This will set the instruction register (IR) to all possible valuesand check the output. This can be used to find undocumentedinstructions and examine their results via the data register (DR).To run this scan you should have already determined the 4 JTAG pinsand define pins[] as such: [0]=TCK [1]=TMS [2]=TDO [3]=TDI. NOTE:run with pull-ups on (r) as any cross-talk might result infalse-positives.

x > boundary scan

This will return the state of all the pins on the target. Actuallyit is not just the pins but the contents of the scan/sample register.This should be a rather large register and is defined in the codeby SCAN_LEN+100. You can check your targets documentation and specifythis or just leave it as a large number (currently 1800). To runthis scan you should have already determined the 4 JTAG pins anddefine pins[] as such: [0]=TCK [1]=TMS [2]=TDO [3]=TDI. NOTE: runwith pull-ups on (r) as any cross-talk might result in false-positives.

i > idcode scan

The JTAG standards specify that if an idcode register is presentit should be set as the default data register (DR) and attached tooutput (TDO) by default. Meaning, regardless of the state of theJTAG chip (set with TMS line) and regardless of input being sentto the chip (TDI) by clocking the chip (TCK) it should return thecontents of the idcode to the output (TDO). Hence, this routineiterates through all possible TCK,TDO pairs of pins and prints theoutput when it changes (we assume an idcode will not be all 0s or1s). You should examine the documentation of your target(s) to seeif the idcode matches. NOTE: run with pull-ups on (r) as anycross-talk might result in false-positives.

b > shift_bypass

Broken atm (need to add TCK enumeration). The JTAG standards specifythat if and idcode register is NOT present on the chip then thebypass register (length of 1) should be the default DR. Essentiallythis means what is sent to the input (TDI) should come out on theoutput (TDI) with a one clock delay (TCK). It is important that youremove loopbacks before running this test otherwise the loopbackpins will look like valid JTAG lines. NOTE: run with pull-ups on(r) as any cross-talk might result in false-positives.

r > set pull-up resistors & cross-talk

If like me the cables you use to connect between JTAGenum to yourtargets are flimsy or uninsulated you might run into issues ofcross-talk whereby when one pin is transmitting a nearby pin picksup the transmission even though they are not connected. To avoidthis you can turn on the internal pull-up resistors which will forcethe pin to a default state. If for some reason you continue to havesporadic issues run the following in sequence to check if the problemis the cable, target or other:

1. Disconnect the cables between your target and JTAGenum. Disconnected thementirely from JTAGenum as well.

2. Run a loopback check (l) with pull-ups off. In this state the pins are inopen mode and might fluctuate. Youll notice that as you move themicrocontroller around, turn lights on and off or move other devices closeto or away from it that the results change.

3. Turn on pull-ups (r) and run the test again. The results should now beconsistent. If they arent, then let me know.

4. Now attach your cables to JTAGenum but not the target. Run steps 2 and 3again. Step 2 will give you a feel for how much inconsistency the cable mayadd. If the loopback check results in actual pattern matches then your cablehas cross-talk. Step 3 should still result in a consistent state of eitherall high (1s) or all low (0s) and if it doesnt then your cross-talk issuesare such that all JTAGenum tests are going to be buggy at best. Feel free togive me an email and I will happily try to help solve the problem.

Basic understanding of how JTAG works will be helpful when usingJTAGenum. There are 4 lines/pins: TDO=output, TDI=input, TCK=clock,TMS=state machine control. Say you want to read the ID of the chip.First you would send the IDCODE instruction to the instructionregister (IR). The JTAG controller then places the actual id codevalue of the chip in a data register which you could then read out.You would think that it would be enough to have one input line goingto the IR and one output coming from the DR but JTAG also supportswriting to the DR. As apposed to adding another input line specificto the DR instead JTAG works by moving the input and output linesbetween IR and DR. The TMS line is used to switch TDI/TDO to IRwhen you want to place an instruction and back to DR when you wantto read or write data. With all operations, be it state change (TMS)reading (TDI) or writing (TDO), the clock line must be cycled once(TCK) for every bit or change. This was a brutal and drasticsimplification but with that understood reading the Usage sectionshould be comprehensible.

For a more detailed discussion of JTAG seehttps://github.com/cyphunk/JTAGenum/wiki

1. upload pictures of the hardware setups
2. add ESP32 support
3. BusPirate bitbang support