Actions

EmSys

Difference between revisions of "Running OpenOCD on Linux"

From EdWiki

m (Running Commands on Startup: the -c Flag)
 
m
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
__NOTOC__
 
__NOTOC__
'''This guide contains general information on running OpenOCD, but all examples use the [[EmSys:STM32L Discovery | STM32L-Discovery]] board'''.
+
This guide contains general information on running OpenOCD, but all examples use the [[EmSys:STM32L Discovery | STM32L-Discovery]] board.
 
<!-- For examples using the {{BEAGLEBOARD_PRODUCTLINK}}, see [[Running OpenOCD on Linux with the Beagleboard]].'' -->
 
<!-- For examples using the {{BEAGLEBOARD_PRODUCTLINK}}, see [[Running OpenOCD on Linux with the Beagleboard]].'' -->
  
Line 16: Line 16:
 
Navigate to the directory containing your openocd executable. In the folder with the executable, make sure you also see three directories called '''interface/''', '''board/''', and '''target/'''. If you don't see these directories, create a new folder somewhere on your computer containing '''openocd''', '''interface/''', '''board/''', and '''target/'''. (If you have just compiled OpenOCD yourself, you can find the executable in '''openocd-/src''' or '''openocd-{{OPENOCD_VERNUM}}/src''', and the three directories you need in '''openocd/tcl''' or '''openocd-{{OPENOCD_VERNUM}}/tcl'''.
 
Navigate to the directory containing your openocd executable. In the folder with the executable, make sure you also see three directories called '''interface/''', '''board/''', and '''target/'''. If you don't see these directories, create a new folder somewhere on your computer containing '''openocd''', '''interface/''', '''board/''', and '''target/'''. (If you have just compiled OpenOCD yourself, you can find the executable in '''openocd-/src''' or '''openocd-{{OPENOCD_VERNUM}}/src''', and the three directories you need in '''openocd/tcl''' or '''openocd-{{OPENOCD_VERNUM}}/tcl'''.
  
In the directory containing the openocd executable, type...
+
In the directory containing the openocd executable, type...<br /><br />
  
  sudo openocd -f path_to/cfg_file [-f path_to/other_cfg_file]
+
  sudo openocd -f path_to/cfg_file [-f path_to/other_cfg_file]<br /><br />
  
Replace ''path_to/cfg_file'' and so on with the .cfg files for your hardware devices. For example, to run OpenOCD for the STM32L-Discovery board, you would use:
+
Replace ''path_to/cfg_file'' and so on with the .cfg files for your hardware devices. For example, to run OpenOCD for the STM32L-Discovery board, you would use:<br /><br />
  
 
  cd /home/USERNAME/{{OPENOCD_VERNUM}}-bin
 
  cd /home/USERNAME/{{OPENOCD_VERNUM}}-bin
  sudo ./openocd -f board/stm32ldiscovery.cfg
+
  sudo ./openocd -f board/stm32ldiscovery.cfg<br />
  
 
==Telnet Connection==
 
==Telnet Connection==
Line 29: Line 29:
 
[[EmSys:OpenOCD |OpenOCD]] runs as a daemon. It accepts connections from other programs, but does not provide any means for you to give it commands directly. Once [[EmSys:OpenOCD |OpenOCD]] is running on your computer you will need to connect to it through another program, such as '''telnet'''.
 
[[EmSys:OpenOCD |OpenOCD]] runs as a daemon. It accepts connections from other programs, but does not provide any means for you to give it commands directly. Once [[EmSys:OpenOCD |OpenOCD]] is running on your computer you will need to connect to it through another program, such as '''telnet'''.
  
To run telnet and connect to [[EmSys:OpenOCD |OpenOCD]], open a new command prompt. From any directory, type:
+
To run telnet and connect to [[EmSys:OpenOCD |OpenOCD]], open a new command prompt. From any directory, type:<br /><br />
  
  telnet localhost 4444
+
  telnet localhost 4444<br /><br />
  
You may need to run telnet as root:
+
You may need to run telnet as root:<br /><br />
  
  sudo telnet localhost 4444
+
  sudo telnet localhost 4444<br /><br />
  
 
You should see a simple prompt ('''>'''). From this prompt you will be able to send commands to [[EmSys:OpenOCD |OpenOCD]]. To exit the telnet prompt, type '''shutdown'''.
 
You should see a simple prompt ('''>'''). From this prompt you will be able to send commands to [[EmSys:OpenOCD |OpenOCD]]. To exit the telnet prompt, type '''shutdown'''.
Line 41: Line 41:
 
==OpenOCD and Permissions==
 
==OpenOCD and Permissions==
  
[[EmSys:OpenOCD |OpenOCD]] needs administrator privileges to interact with your USB drivers. Even Linux users with administrator privileges do not typically log on with those privileges active. However, Linux provides commands to run another command as the root user. On Ubuntu, this command is ''sudo''. To run a program as root, type ''sudo'', then a space, then the name of the program. For example...
+
[[EmSys:OpenOCD |OpenOCD]] needs administrator privileges to interact with your USB drivers. Even Linux users with administrator privileges do not typically log on with those privileges active. However, Linux provides commands to run another command as the root user. On Ubuntu, this command is ''sudo''. To run a program as root, type ''sudo'', then a space, then the name of the program. For example...<br /><br />
  
  ./openocd -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg
+
  ./openocd -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg<br /><br />
  
...runs [[EmSys:OpenOCD |OpenOCD]] with your user permissions, and likely prevents [[EmSys:OpenOCD |OpenOCD]] from interacting with libUSB. However...
+
...runs [[EmSys:OpenOCD |OpenOCD]] with your user permissions, and likely prevents [[EmSys:OpenOCD |OpenOCD]] from interacting with libUSB. However...<br /><br />
  
  sudo ./openocd -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg
+
  sudo ./openocd -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg<br /><br />
  
 
...runs [[EmSys:OpenOCD |OpenOCD]] as root, with full permission to access your USB drivers.
 
...runs [[EmSys:OpenOCD |OpenOCD]] as root, with full permission to access your USB drivers.
Line 55: Line 55:
 
==Search Path==
 
==Search Path==
  
[[EmSys:OpenOCD |OpenOCD]] searches in its own directory first for config files. This guide assumes that the '''openocd''' binary is in a directory containing three folders, called '''interface/''', '''board/''', and '''target/'''. If you have just compiled OpenOCD yourself, you will need to move the '''openocd''' executable somewhere where it can find '''interface/''', '''board/''', and '''target''', as described in the [[EmSys:Compiling_OpenOCD_v0.8.0_Linux#Preparing to Run_OpenOCD | Preparing to Run OpenOCD]].
+
[[EmSys:OpenOCD |OpenOCD]] searches in its own directory first for config files. This guide assumes that the '''openocd''' binary is in a directory containing three folders, called '''interface/''', '''board/''', and '''target/'''. If you have just compiled OpenOCD yourself, you will need to move the '''openocd''' executable somewhere where it can find '''interface/''', '''board/''', and '''target''', as described in the [[EmSys:Compiling_OpenOCD_v0.8.0_Linux#Preparing to Run_OpenOCD | Preparing to Run OpenOCD]].<br /><br />
  
You can also tell OpenOCD where to look for '''interface/''', '''board/''', and '''target/''' with the ''-s'' flag, like this:
+
You can also tell OpenOCD where to look for '''interface/''', '''board/''', and '''target/''' with the ''-s'' flag, like this:<br /><br />
  
  sudo openocd -s ../tcl -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg
+
  sudo openocd -s ../tcl -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg<br /><br />
  
This would tell OpenOCD to look for '''interface/''' and '''target/''' one level up in a directory called '''tcl/'''. For more information, see [[EmSys:OpenOCD Config File Paths |OpenOCD Config File Paths]].
+
This would tell OpenOCD to look for '''interface/''' and '''target/''' one level up in a directory called '''tcl/'''. For more information, see [[EmSys:OpenOCD Config File Paths |OpenOCD Config File Paths]].<br /><br />
  
 
==OpenOCD Config Files==
 
==OpenOCD Config Files==
Line 67: Line 67:
 
Each time you use [[EmSys:OpenOCD |OpenOCD]] you will need to configure it by passing it paths to configuration files. In the [[EmSys:OpenOCD |OpenOCD]] {{OPENOCD_VERNUM}} release, these files are found in '''openocd-{{OPENOCD_VERNUM}}/tcl''' and its subdirectories. From the '''tcl''' directory, the configuration file for the STLink/V2 is at '''interface/stlink-v2.cfg'''. The file for the STM32L-Discoveryboard is at '''target/interface/stlink-v2.cfg'''.  
 
Each time you use [[EmSys:OpenOCD |OpenOCD]] you will need to configure it by passing it paths to configuration files. In the [[EmSys:OpenOCD |OpenOCD]] {{OPENOCD_VERNUM}} release, these files are found in '''openocd-{{OPENOCD_VERNUM}}/tcl''' and its subdirectories. From the '''tcl''' directory, the configuration file for the STLink/V2 is at '''interface/stlink-v2.cfg'''. The file for the STM32L-Discoveryboard is at '''target/interface/stlink-v2.cfg'''.  
  
When you start [[EmSys:OpenOCD |OpenOCD]], you tell it to use the config files for your hardware with the '''-f''' switch, like this:
+
When you start [[EmSys:OpenOCD |OpenOCD]], you tell it to use the config files for your hardware with the '''-f''' switch, like this:<br /><br />
  
  sudo openocd -f path_to/cfg_file [-f path_to/other_cfg_file]
+
  sudo openocd -f path_to/cfg_file [-f path_to/other_cfg_file]<br /><br />
  
For example, suppose you want to run [[EmSys:OpenOCD |OpenOCD]] for the STM32L-Discovery board. The current directory contains the [[EmSys:OpenOCD |OpenOCD]] executable and the '''board''', '''interface''', and '''target''' directories provided with the OpenOCD source. You would type:
+
For example, suppose you want to run [[EmSys:OpenOCD |OpenOCD]] for the STM32L-Discovery board. The current directory contains the [[EmSys:OpenOCD |OpenOCD]] executable and the '''board''', '''interface''', and '''target''' directories provided with the OpenOCD source. You would type:<br /><br />
  
  sudo ./openocd -f interface/stlink-v2.cfg -f interface/stlink-v2.cfg
+
  sudo ./openocd -f interface/stlink-v2.cfg -f interface/stlink-v2.cfg<br /><br />
  
Be aware that config files may contain paths to other config files. For example ''board/stm32ldiscovery.cfg.cfg''', the config file for the STM32L-Discovery board, contains this line:
+
Be aware that config files may contain paths to other config files. For example ''board/stm32ldiscovery.cfg.cfg''', the config file for the STM32L-Discovery board, contains this line:<br /><br />
  
 
  source [find interface/stlink-v2.cfg]
 
  source [find interface/stlink-v2.cfg]
  source [find target/stm32lx_stlink.cfg]
+
  source [find target/stm32lx_stlink.cfg]<br /><br />
  
 
When you run [[EmSys:OpenOCD |OpenOCD]] with the '''board/stm32ldiscovery.cfg''' file, [[EmSys:OpenOCD |OpenOCD]] searches from the current directory for '''interface/stlink-v2.cfg'''. If the current directory does not contain [[EmSys:OpenOCD |OpenOCD]]'s '''interface''' directory, it may not find the '''stlink-v2.cfg''' file, or it may find a different '''stlink-v2.cfg''' file elsewhere on your system. You can avoid this by giving OpenOCD the path to your config files. For more information, see [[EmSys:OpenOCD Config File Paths |OpenOCD Config File Paths]].
 
When you run [[EmSys:OpenOCD |OpenOCD]] with the '''board/stm32ldiscovery.cfg''' file, [[EmSys:OpenOCD |OpenOCD]] searches from the current directory for '''interface/stlink-v2.cfg'''. If the current directory does not contain [[EmSys:OpenOCD |OpenOCD]]'s '''interface''' directory, it may not find the '''stlink-v2.cfg''' file, or it may find a different '''stlink-v2.cfg''' file elsewhere on your system. You can avoid this by giving OpenOCD the path to your config files. For more information, see [[EmSys:OpenOCD Config File Paths |OpenOCD Config File Paths]].
Line 86: Line 86:
 
==Running Commands on Startup: the ''-c'' Flag==
 
==Running Commands on Startup: the ''-c'' Flag==
  
You can instruct OpenOCD to run a command on startup with the ''-c'' flag. For example:
+
You can instruct OpenOCD to run a command on startup with the ''-c'' flag. For example:<br /><br />
  
  sudo openocd -f interface/stlink-v2.cfg -c "jtag_khz 6000" -f target/stm32lx_stlink.cfg
+
  sudo openocd -f interface/stlink-v2.cfg -c "jtag_khz 6000" -f target/stm32lx_stlink.cfg<br /><br />
The ''jtag_khz'' command sets the STLink/V2 clock speed. Starting OpenOCD like this does the following, in order:
+
 
 +
The ''jtag_khz'' command sets the STLink/V2 clock speed. Starting OpenOCD like this does the following, in order:<br /><br />
  
 
*run commands in ''stlink-v2.cfg''
 
*run commands in ''stlink-v2.cfg''
 
*run the OpenOCD command to set the stm32lx_stlink's clock speed
 
*run the OpenOCD command to set the stm32lx_stlink's clock speed
*run commands in ''stm32lx_stlink.cfg''.
+
*run commands in ''stm32lx_stlink.cfg''.<br />
  
 
==See Also==
 
==See Also==
 
#[[EmSys:Accessing Devices without Sudo |Accessing Devices without sudo]]
 
#[[EmSys:Accessing Devices without Sudo |Accessing Devices without sudo]]
 
#[[EmSys:OpenOCD Config File Paths |OpenOCD Config File Paths]]
 
#[[EmSys:OpenOCD Config File Paths |OpenOCD Config File Paths]]

Latest revision as of 04:20, 9 April 2022

This guide contains general information on running OpenOCD, but all examples use the STM32L-Discovery board.

OpenOCD provides a command line interface for interacting with embedded devices. To use OpenOCD you will need to run it from the command line. This guide includes basic information about using the Ubuntu command line interface, the terminal window.

Opening the Command Prompt

Open the Applications menu from the menu bar on your desktop, and choose Accessories > Terminal. Ubuntu should open blank window with white text and a prompt.

Running OpenOCD

Navigate to the directory containing your openocd executable. In the folder with the executable, make sure you also see three directories called interface/, board/, and target/. If you don't see these directories, create a new folder somewhere on your computer containing openocd, interface/, board/, and target/. (If you have just compiled OpenOCD yourself, you can find the executable in openocd-/src or openocd-0.9.0/src, and the three directories you need in openocd/tcl or openocd-0.9.0/tcl.

In the directory containing the openocd executable, type...

sudo openocd -f path_to/cfg_file [-f path_to/other_cfg_file]

Replace path_to/cfg_file and so on with the .cfg files for your hardware devices. For example, to run OpenOCD for the STM32L-Discovery board, you would use:

cd /home/USERNAME/0.9.0-bin
sudo ./openocd -f board/stm32ldiscovery.cfg

Telnet Connection

OpenOCD runs as a daemon. It accepts connections from other programs, but does not provide any means for you to give it commands directly. Once OpenOCD is running on your computer you will need to connect to it through another program, such as telnet.

To run telnet and connect to OpenOCD, open a new command prompt. From any directory, type:

telnet localhost 4444

You may need to run telnet as root:

sudo telnet localhost 4444

You should see a simple prompt (>). From this prompt you will be able to send commands to OpenOCD. To exit the telnet prompt, type shutdown.

OpenOCD and Permissions

OpenOCD needs administrator privileges to interact with your USB drivers. Even Linux users with administrator privileges do not typically log on with those privileges active. However, Linux provides commands to run another command as the root user. On Ubuntu, this command is sudo. To run a program as root, type sudo, then a space, then the name of the program. For example...

./openocd -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg

...runs OpenOCD with your user permissions, and likely prevents OpenOCD from interacting with libUSB. However...

sudo ./openocd -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg

...runs OpenOCD as root, with full permission to access your USB drivers.

When you use the sudo command, Linux will prompt you for the root user's password. You can also configure Linux to allow OpenOCD to access specific hardware devices without sudo. See Accessing Devices without Sudo.

Search Path

OpenOCD searches in its own directory first for config files. This guide assumes that the openocd binary is in a directory containing three folders, called interface/, board/, and target/. If you have just compiled OpenOCD yourself, you will need to move the openocd executable somewhere where it can find interface/, board/, and target, as described in the Preparing to Run OpenOCD.

You can also tell OpenOCD where to look for interface/, board/, and target/ with the -s flag, like this:

sudo openocd -s ../tcl -f interface/stlink-v2.cfg -f target/stm32lx_stlink.cfg

This would tell OpenOCD to look for interface/ and target/ one level up in a directory called tcl/. For more information, see OpenOCD Config File Paths.

OpenOCD Config Files

Each time you use OpenOCD you will need to configure it by passing it paths to configuration files. In the OpenOCD 0.9.0 release, these files are found in openocd-0.9.0/tcl and its subdirectories. From the tcl directory, the configuration file for the STLink/V2 is at interface/stlink-v2.cfg. The file for the STM32L-Discoveryboard is at target/interface/stlink-v2.cfg.

When you start OpenOCD, you tell it to use the config files for your hardware with the -f switch, like this:

sudo openocd -f path_to/cfg_file [-f path_to/other_cfg_file]

For example, suppose you want to run OpenOCD for the STM32L-Discovery board. The current directory contains the OpenOCD executable and the board, interface, and target directories provided with the OpenOCD source. You would type:

sudo ./openocd -f interface/stlink-v2.cfg -f interface/stlink-v2.cfg

Be aware that config files may contain paths to other config files. For example board/stm32ldiscovery.cfg.cfg', the config file for the STM32L-Discovery board, contains this line:

source [find interface/stlink-v2.cfg]
source [find target/stm32lx_stlink.cfg]

When you run OpenOCD with the board/stm32ldiscovery.cfg file, OpenOCD searches from the current directory for interface/stlink-v2.cfg. If the current directory does not contain OpenOCD's interface directory, it may not find the stlink-v2.cfg file, or it may find a different stlink-v2.cfg file elsewhere on your system. You can avoid this by giving OpenOCD the path to your config files. For more information, see OpenOCD Config File Paths.

If you have compiled OpenOCD yourself, the easiest way to avoid these issues is to copy the openocd binary from your openocd-0.9.0/src directory to your openocd-0.9.0/tcl directory. To run OpenOCD, navigate to openocd-0.9.0/tcl in the command terminal and run OpenOCD as above. You can also create a new directory anywhere on your system, and copy the openocd binary and the contents of openocd-0.9.0/tcl to the new directory.

Running Commands on Startup: the -c Flag

You can instruct OpenOCD to run a command on startup with the -c flag. For example:

sudo openocd -f interface/stlink-v2.cfg -c "jtag_khz 6000" -f target/stm32lx_stlink.cfg

The jtag_khz command sets the STLink/V2 clock speed. Starting OpenOCD like this does the following, in order:

  • run commands in stlink-v2.cfg
  • run the OpenOCD command to set the stm32lx_stlink's clock speed
  • run commands in stm32lx_stlink.cfg.

See Also

  1. Accessing Devices without sudo
  2. OpenOCD Config File Paths