{"id":18929169,"url":"https://github.com/jwillikers/openocd-image","last_synced_at":"2025-04-15T15:30:47.958Z","repository":{"id":104838788,"uuid":"388213853","full_name":"jwillikers/openocd-image","owner":"jwillikers","description":"A container image for OpenOCD","archived":true,"fork":false,"pushed_at":"2021-08-15T17:23:02.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T21:52:13.771Z","etag":null,"topics":["container","embedded","openocd","podman","quayio"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwillikers.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.adoc","code_of_conduct":"CODE_OF_CONDUCT.adoc","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-21T18:42:48.000Z","updated_at":"2024-10-01T12:27:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"1067b197-fb4a-4b84-821b-ed90eae2c13f","html_url":"https://github.com/jwillikers/openocd-image","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwillikers%2Fopenocd-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwillikers%2Fopenocd-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwillikers%2Fopenocd-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwillikers%2Fopenocd-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwillikers","download_url":"https://codeload.github.com/jwillikers/openocd-image/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249097781,"owners_count":21212351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","embedded","openocd","podman","quayio"],"created_at":"2024-11-08T11:30:40.299Z","updated_at":"2025-04-15T15:30:47.952Z","avatar_url":"https://github.com/jwillikers.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"= OpenOCD Image\nJordan Williams \u003cjordan@jwillikers.com\u003e\n:experimental:\n:icons: font\nifdef::env-github[]\n:tip-caption: :bulb:\n:note-caption: :information_source:\n:important-caption: :heavy_exclamation_mark:\n:caution-caption: :fire:\n:warning-caption: :warning:\nendif::[]\n:Buildah: https://buildah.io/[Buildah]\n:Fedora: https://getfedora.org/[Fedora]\n:Fedora-Silverblue: https://silverblue.fedoraproject.org/[Fedora Silverblue]\n:fish: https://fishshell.com/[fish]\n:GDB: https://www.gnu.org/software/gdb/[GDB]\n:Git: https://git-scm.com/[Git]\n:Podman: https://podman.io/[Podman]\n:pre-commit: https://pre-commit.com/[pre-commit]\n:SELinux: https://github.com/SELinuxProject/selinux[SELinux]\n:ST-LINK: https://www.st.com/en/development-tools/st-link-v2.html[ST-LINK]\n:udev: https://www.freedesktop.org/software/systemd/man/udev.html[udev]\n\nimage:https://img.shields.io/github/workflow/status/jwillikers/openocd-image/CI/main[GitHub Workflow Status]\nimage:https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white[pre-commit, link=https://github.com/pre-commit/pre-commit]\n\nA container image for {OpenOCD}.\n\n== Synopsis\n\nImage:: https://quay.io/repository/jwillikers/openocd[quay.io/jwillikers/openocd]\n\nTags::\n* `latest`\n\nSupported architectures::\n* `amd64` _(x86_64)_\n* `arm64` _(aarch64)_\n\nUser:: The default user inside the container is named `user`.\n\nEntrypoint:: `openocd`\n\nLabels::\n`io.containers.autoupdate=registry`::: Enables automatic updates when using {Podman} and the _fully-qualified_ image name.\n\n== Usage\n\nThe following instructions and examples will you get you up and running for using OpenOCD and {GDB} with your on-chip debugger.\nFor these examples, I'm using an {ST-LINK}, an ST-LINK/V2.1 to be exact, and targeting an STM32F7 microcontroller.\nAll examples and instructions are for rootless containers run with {Podman}.\n\n=== USB Device Access\n\nWhen running OpenOCD from within this container, make sure to provide the appropriate access to the on-chip debugger.\nTo run the container with as few privileges as possible, permit the user access to the on-chip debugger device and pass only this device to container.\n\n==== udev\n\nTo allow access to the on-chip debugger, a {udev} rule can be created on the host which permits access for unprivileged users.\nThis will allow an unprivileged container to access the device.\n\n. Connect the on-chip debugger to the host.\n\n. Use `lsusb` or `dmesg` to determine the vendor id and product id of the on-chip debugger.\n+\n--\n[source,sh]\n----\n$ lsusb | grep ST-LINK\nBus 001 Device 020: ID 0483:374b STMicroelectronics ST-LINK/V2.1\n----\n\nHere the vendor id is `0483` and the product id is `374b`.\n--\n\n. Create an appropriately named udev rule to permit access, substituting the vendor id and product id from the last step.\n+\n./etc/udev/rules.d/70-st-link.rules\n[source,udev]\n----\n# ST-LINK/V2-1\nATTRS{idVendor}==\"0483\", ATTRS{idProduct}==\"374b\", TAG+=\"uaccess\"\n----\n\n. Now reload the udev rules.\n+\n[source,sh]\n----\nsudo udevadm control --reload-rules\n----\n\nThis udev rule grant's access to the user on the host machine.\nIt's important to run rootless containers which run with a non-root user, such as this one, with the option `--userns keep-id`.\nThis ensures that the udev rule is applied to the user running inside the container.\n\n==== Find the USB Bus and Device Numbers\n\nIt's possible to permit access to the underlying device with by allowing the container to access `/dev/bus/usb`, but this allows the container access to all USB devices.\nTo restrict this further, it's necessary to find the device path for the on-chip debugger as shown below.\n\nUse `lsusb` to determine the USB bus and device numbers assigned to the on-chip debugger.\n\n[source,sh]\n----\n$ lsusb | grep ST-LINK\nBus 001 Device 020: ID 0483:374b STMicroelectronics ST-LINK/V2.1\n----\n\nThe USB bus number here is `001`, and the device number is `020`.\nUsing this information, the USB device's path is `/dev/bus/usb/001/020`.\nPass this device in to the container using the `--device` option like so, `--device /dev/bus/usb/001/020`.\n\n==== SELinux\n\nFor systems using {SELinux}, such as {Fedora}, there is the last hurdle.\nTo enable access to USB devices for rootless containers on systems running SELinux, pass the option `--security-opt label=disable` to Podman.\n\n=== Examples\n\nThe following examples assume you have allowed the necessary access to the USB devices.\nIn addition, they use the same device information such as the USB bus and device numbers.\nThe examples will enumerate a number of common scenarios when networking between {GDB} and OpenOCD.\nTo attach the GDB Server hosted by OpenOCD, you'll need to permit network access to port `3333` of the OpenOCD container.\nSome of the examples run GDB from within its own container.\nThese use my https://github.com/jwillikers/gdb-image/[GDB Image] available on https://quay.io[Quay].\n\n==== Flash\n\nThe following example flashes an ELF file executable in the current directory to an STM32F7 target board.\n\n[source,sh]\n----\npodman run \\\n    --rm \\\n    --userns keep-id \\\n    --security-opt label=disable \\\n    --device /dev/bus/usb/001/020 \\\n    --volume $PWD:/home/user:Z \\\n    --name openocd \\\n    -it quay.io/jwillikers/openocd:latest \\\n    -f interface/stlink.cfg \\\n    -f target/stm32f7x.cfg \\\n    -c \"program app.elf verify reset exit\"\n----\n\n==== Background\n\nTo run OpenOCD in the background, daemonize the container by using the `-d` flag in place of the `-i` flag used in the preceding example.\n\n[source,sh]\n----\npodman run \\\n    --rm \\\n    --userns keep-id \\\n    --security-opt label=disable \\\n    --device /dev/bus/usb/001/020 \\\n    --name openocd \\\n    -dt quay.io/jwillikers/openocd:latest \\\n    -f interface/stlink.cfg \\\n    -f target/stm32f7x.cfg\n----\n\n==== GDB From the Same Pod\n\nIf you wish to run GDB from another container, the easiest method is to place both rootless containers in the same pod and attach to port `3333` on `localhost`.\n\n. Create a pod.\n+\n[source,sh]\n----\npodman pod create --name openocd-and-gdb\n----\n\n. Create and start the OpenOCD container as part of the new pod.\n+\n[source,sh]\n----\npodman run \\\n    --rm \\\n    --pod openocd-and-gdb \\\n    --userns keep-id \\\n    --security-opt label=disable \\\n    --device /dev/bus/usb/001/020 \\\n    --name openocd \\\n    -dt quay.io/jwillikers/openocd:latest \\\n    -f interface/stlink.cfg -f target/stm32f7x.cfg\n----\n\n. Run GDB from a container within the same pod.\n+\n[source,sh]\n----\npodman run \\\n    --rm \\\n    --pod openocd-and-gdb \\\n    --volume $PWD:/home/user:Z \\\n    --name gdb \\\n    -it quay.io/jwillikers/gdb:latest \\\n    -q -ex \"target remote :3333\" app.elf\n----\n\n==== GDB on the Host\n\nIf you're using GDB on the host, then it's possible to access the GDB Server using the host's network.\n\n. Startup OpenOCD in a container using the host's network stack directly.\n+\n[source,sh]\n----\npodman run \\\n    --rm \\\n    --userns keep-id \\\n    --security-opt label=disable \\\n    --device /dev/bus/usb/001/020 \\\n    --network host \\\n    --name openocd \\\n    -dt quay.io/jwillikers/openocd:latest \\\n    -f interface/stlink.cfg -f target/stm32f7x.cfg\n----\n\n. Then just attach to the GDB Server as normal.\n+\n[source,sh]\n----\ngdb -q -ex \"target remote :3333\" app.elf\n----\n\n== Build\n\nThis project uses {Buildah} and {Podman} for building and testing the image.\nA set of {pre-commit} checks are readily available to ensure your code is up-to-spec at the time it is committed.\nInstructions for setting up a development environment, building the image, and testing the image follow.\nThese instructions are intended for users of {Fedora-Silverblue}, where the packages `buildah`, `git`, and `podman` are already available.\nMoreover, I use the {fish} shell.\n\n. Install the {fish} shell.\n+\n[source,sh]\n----\nsudo rpm-ostree install fish\n----\n\n. Reboot to finish the installation.\n+\n[source,sh]\n----\nsystemctl reboot\n----\n\n. Clone this repository.\n+\n[source,sh]\n----\ngit -C ~/Projects clone git@github.com:jwillikers/openocd-image.git\n----\n\n. Install {pre-commit}.\n+\n[source,sh]\n----\npip install pre-commit\n----\n\n. Change into the project directory.\n+\n[source,sh]\n----\ncd ~/Projects/openocd-image\n----\n\n. Install pre-commit's Git hooks.\n+\n[source,sh]\n----\npre-commit install\n----\n\n. Run the shell script to build the image.\n+\n[source,sh]\n----\nbuildah unshare ~/Projects/openocd-image/build.fish\n----\n\n. Test the image with the `test.fish` shell script.\n+\n[source,sh]\n----\n~/Projects/openocd-image/test.fish\n----\n\n== Contributing\n\nContributions in the form of issues, feedback, and even pull requests are welcome.\nMake sure to adhere to the project's link:CODE_OF_CONDUCT.adoc[Code of Conduct].\n\n== Open Source Software\n\nThis project is built on the hard work of countless open source contributors.\nSeveral of these projects are enumerated below.\n\n* https://asciidoctor.org/[Asciidoctor]\n* {Buildah}\n* {Fedora}\n* {Fedora-Silverblue}\n* {fish}\n* {GDB}\n* {Git}\n* https://www.linuxfoundation.org/[Linux]\n* {OpenOCD}\n* {Podman}\n* {pre-commit}\n* https://www.python.org/[Python]\n* https://rouge.jneen.net/[Rouge]\n* https://www.ruby-lang.org/en/[Ruby]\n\n== Code of Conduct\n\nRefer to the project's link:CODE_OF_CONDUCT.adoc[Code of Conduct] for details.\n\n== License\n\nThis repository is licensed under the https://www.gnu.org/licenses/gpl-3.0.html[GPLv3], a copy of which is provided in the link:LICENSE.adoc[license file].\n\n© 2021 Jordan Williams\n\n== Authors\n\nmailto:{email}[{author}]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwillikers%2Fopenocd-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwillikers%2Fopenocd-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwillikers%2Fopenocd-image/lists"}