{"id":120,"date":"2018-02-05T15:36:25","date_gmt":"2018-02-05T23:36:25","guid":{"rendered":"https:\/\/sysprogs.com\/tutorials\/?p=120"},"modified":"2023-06-06T09:05:50","modified_gmt":"2023-06-06T16:05:50","slug":"preparing-raspberry-pi-for-jtag-debugging","status":"publish","type":"post","link":"https:\/\/sysprogs.com\/VisualKernel\/tutorials\/raspberry\/jtagsetup\/","title":{"rendered":"Preparing Raspberry PI for JTAG Debugging"},"content":{"rendered":"

This tutorial shows how to prepare your\u00a0Raspberry PI\u00a0<\/a>board for debugging with JTAG (we have tested this with Raspberry Pi 1, 2, 3 and 4). Using JTAG will allow debugging the Linux kernel using hardware like\u00a0Segger J-Link<\/a>. As Raspberry PI board does not have a connector with a normal JTAG layout, preparing the board for JTAG debugging involves finding the correct pins and wiring them in the correct order. Follow the steps below for a complete walkthrough:<\/p>\n

    \n
  1. Determine the revision of your Raspberry PI board. Connect to it using SSH and run the following command:\n
    cat \/proc\/cpuinfo<\/pre>\n
    <\/li>\n
  2. Use the\u00a0revision table\u00a0<\/a>to look up the board revision. In this tutorial we will use Model B v2.0 (revision 0xe), however\u00a0the same schematics also works for Raspberry Pi 3 and Raspberry Pi 4.<\/li>\n
  3. In order to find which pins on the board are JTAG pins we need to first find the GPIO numbers that correspond to them. JTAG requires 4 pins: TDI<\/strong>, TDO<\/strong>, TMS<\/strong> and TCK<\/strong> plus TRST<\/strong> and RTCK<\/strong> pins. You can find the GPIO pins corresponding to these in the datasheet for BCM2835<\/a> (Raspberry Pi 1-3) or BCM2711<\/a> (Raspberry Pi 4). Search for “_TCK” to find the GPIO number table:\"\"<\/a><\/li>\n
  4. Here are the GPIO numbers for the current revision:\n
    \n\n\n\n\n\n\n\n\n\n
    JTAG pin<\/td>\n“ALT4” mode<\/td>\n“ALT5” mode
    \n(Raspberry Pi 1-3 only)<\/span><\/td>\n<\/tr>\n
    TDI<\/td>\nGPIO26<\/td>\nGPIO4<\/td>\n<\/tr>\n
    TDO<\/td>\nGPIO24<\/td>\nGPIO5<\/td>\n<\/tr>\n
    TMS<\/td>\nGPIO27<\/td>\nGPIO12<\/td>\n<\/tr>\n
    TCK<\/td>\nGPIO25<\/td>\nGPIO13<\/td>\n<\/tr>\n
    RTCK<\/td>\nGPIO23<\/td>\nGPIO6<\/td>\n<\/tr>\n
    TRST<\/td>\nGPIO22<\/td>\nN\/A<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/li>\n
  5. Download Raspberry PI schematics PDF for the board revision you found out in step 2. Each JTAG pin (except TRST) can be routed to one of 2 GPIO pins. Use the schematics to find GPIO pins that are connected to the GPIO connector:\"\"<\/a><\/li>\n
  6. We will now need to wire the selected pins from the P1 connector to a 20-pin JTAG connector. Use the\u00a0JTAG-20 pinout<\/a> to map the P1 pins to the JTAG-20 pins:\n
    \n\n\n\n\n\n\n\n\n\n\n\n
    JTAG-20 pin<\/td>\nJTAG signal<\/td>\nGPIO pin<\/td>\nALT mode<\/td>\nP1 pin<\/td>\n<\/tr>\n
    1<\/td>\nVREF<\/td>\nN\/A<\/td>\nN\/A<\/td>\n1<\/td>\n<\/tr>\n
    3<\/td>\nnTRST<\/td>\nGPIO22<\/td>\nALT4<\/td>\n15<\/td>\n<\/tr>\n
    4<\/td>\nGND<\/td>\nN\/A<\/td>\nN\/A<\/td>\n9<\/td>\n<\/tr>\n
    5<\/td>\nTDI<\/td>\nGPIO4 (Rpi 1-3)<\/span>
    \nGPIO26 (Rpi Pi 4)<\/span><\/td>\n    		ALT5 (Rpi Pi 1-3)<\/span>
    \nALT4 (Rpi Pi 4)<\/span><\/td>\n    		7 (Rpi 1-3)<\/span>
    \n37 (Rpi 4)<\/span><\/td>\n<\/tr>\n
    7<\/td>\nTMS<\/td>\nGPIO27<\/td>\nALT4<\/td>\n13<\/td>\n<\/tr>\n
    9<\/td>\nTCK<\/td>\nGPIO25<\/td>\nALT4<\/td>\n22<\/td>\n<\/tr>\n
    11<\/td>\nRTCK<\/td>\nGPIO23<\/td>\nALT4<\/td>\n16<\/td>\n<\/tr>\n
    13<\/td>\nTDO<\/td>\nGPIO24<\/td>\nALT4<\/td>\n18<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/li>\n
  7. Now we can make an adapter cable that will connect the pins from the 26-pin P1 connector on Raspberry PI to the 20-pin JTAG connector. This can be done by carefully opening and detaching the 26-pin connector from a 26-pin cable and attaching the wires from the 14-pin cable to it ordered according to the table above:<\/li>\n
  8. Each wire can be carefully pushed into the correct position using a pincette:<\/li>\n
  9. Double-triple check your wiring. Wrong wiring\/cable orientation can permanently damage your Raspberry PI, your JTAG programmer and even your PC connected to it!<\/span>\u00a0Test the correctness of each pin. E.g. we can test JTAG pin 3 (nTRST = GPIO22) by connecting a LED between pins 3 and 4 (4 is GND) and running the following commands in your Raspberry PI terminal over SSH:\n
    cd \/sys\/class\/gpio\r\necho 22 > export\r\ncd gpio22\r\necho out > direction\r\necho 1 > value<\/pre>\n
    This will turn on the LED until we run ‘echo 0 > value’:<\/li>\n
  10. The easiest way to\u00a0test out the JTAG connection is to create a\u00a0kernel module project with VisualKernel<\/a>\u00a0that can configure and\u00a0verify\u00a0the JTAG setup\u00a0automatically:\"\"Alternatively you can follow the steps below to\u00a0check your\u00a0JTAG connection manually.<\/li>\n<\/ol>\n
    Checking the JTAG connection manually<\/h2>\n
      \n
    1. Now that we have verified that the GPIO pins are connected to correct JTAG pins we need to switch them from the GPIO mode to JTAG mode. The table above summarized the alternative function numbers that we need to select for each pin. On Raspberry Pi 1-3<\/strong>, this is done by accessing the GPFSELx<\/strong> registers of the BCM2835 chip. The easiest way to access them from a user-mode Linux program is by using the\u00a0\/dev\/mem<\/strong>\u00a0device (note that the 0x7E20xxxx addresses mentioned in the BCM2835 reference are the physical addresses. the corresponding virtual addresses are 0x2020xxxx). To do this, upload, the\u00a0JtagEnabler.cpp<\/a>\u00a0file to your Raspberry Pi 1-3 (not 4!)<\/strong>, compile and run it:\n
      g++ -o JtagEnabler JtagEnabler.cpp\r\nsudo .\/JtagEnabler<\/pre>\n
      Below is the code responsible for setting the alternative functions for all affected pins:<\/p>\n
      GpioFunctionSelector selector;\r\nselector.SetGPIOFunction(22, GPIO_ALT_FUNCTION_4);\r\nselector.SetGPIOFunction(4,\u00a0 GPIO_ALT_FUNCTION_5);\r\nselector.SetGPIOFunction(27, GPIO_ALT_FUNCTION_4);\r\nselector.SetGPIOFunction(25, GPIO_ALT_FUNCTION_4);\r\nselector.SetGPIOFunction(23, GPIO_ALT_FUNCTION_4);\r\nselector.SetGPIOFunction(24, GPIO_ALT_FUNCTION_4);<\/pre>\n
      Note that if you are using Raspberry Pi 3<\/strong>, you would need to change the peripheral base address from 0x20000000<\/strong> to\u00a00x3f000000<\/strong>.
      \nOn Raspberry Pi 4 <\/strong>(BCM2711 chip), setting the GPFSELx<\/strong> registers is not sufficient to enable JTAG debugging. Instead, you need to add the following line to the \/boot\/config.txt<\/strong> file:<\/p>\n
      enable_jtag_gpio=1<\/pre>\n
      This will both configure the pins, and enable the JTAG module on the BCM2711 chip. Make sure it is added before the model-specific sections (e.g. [pi4]<\/strong>) or inside the [all]<\/strong> section. You can also add model-specific sections to use GPIO4 for TDI on Raspberry Pi 1-3 and GPIO26 on Raspberry Pi 4:<\/p>\n
      [all]\r\nenable_jtag_gpio=1\r\ngpio=22-27=a4\r\n\r\n[pi1]\r\ngpio=4=a5\r\n\r\n[pi2]\r\ngpio=4=a5\r\n\r\n[pi3]\r\ngpio=4=a5<\/pre>\n<\/li>\n
    2. Now we are ready to start debugging. In this tutorial we will use a Segger J-Link programmer with the OpenOCD tool, however you can use any other supported programmer instead.\u00a0Download our OpenOCD package<\/a>\u00a0and theUSBDriverTool<\/a>. Connect the J-Link programmer, launch USBDriverTool, select the J-Link device and install the WinUSB drivers for it:<\/li>\n
    3. We’re almost ready. Before we can start debugging our Raspberry PI we need to create a target configuration file for OpenOCD. The target configuration file should specify the correct ARM core, set the the JTAG ID and configure multi-core debugging so that GDB doesn’t break the target. You download configuration files for Raspberry Pi 1-4 boards tested with Linux kernel debugging here:\n