# pyOCD RemoteBitbang DebugProbe plugin
This pyOCD plugin provides a debug probe that allows connection to a remote bitbang interface
via a TCP socket. It is design to be used with targets running in simulation. The remote
end must provide a TCP server that accepts a socket connection. The debug probe sends an ASCII
encoding of the bitbang interface.
## Installation
```
$ pip install pyocd-bitbang
```
## Background
This plugin is designed to be used to connect, via SWD, to a Verilator model of a Cortex-M based MCU.
This is the pyOCD equivalent to the OpenOCD JTAG remote_bitbang interface, and in fact, uses the same
ASCII encoding.
## Implementation Detail
### DebugProbe
The class `bitbang_probe:RemoteBitbangProbe` implements the minimum subset required by the
pyOCD `pyocd.probe.debug_probe:DebugProbe` class. Any SWD commands are translated to a series of
read and write calls that drive the remote SWD interface via a TCP socket. The protocol used is the
same as defined in the OpenOCD [remote_bitbang](https://github.com/openocd-org/openocd/blob/master/doc/manual/jtag/drivers/remote_bitbang.txt) specification. Each character sent over the socket corresponds to a request
to set the bus to a particular state or to read the value currently being driven on SWDI.
Unlike debug probes connected via USB, pyOCD cannot auto-detect the probe. Instead, a unique ID must be
specified when launching pyOCD that specifies the probe to use and the IP address and port to use. See below.
### TCP Server and SV DPI
In addition to this plugin, the testbench must implement a TCP server to which the probe connects as well
as a DPI interface that drives the SWD pins of the DUT. A good example of such an implementation can be
found in the OpenTitan repository [here](https://github.com/lowRISC/opentitan/tree/master/hw/dv/dpi/jtagdpi).
Modifying the above example to drive a SWD interface is fairly simple. Instead of the 3 bit Write encoding
driving {tck, tms, tdi}, they should drive {swclk, swdoen, swdo}.
The following snippet shows the character decoding in the main loop of the DPI C function:
```c
// parse received command byte
if (cmd >= '0' && cmd <= '7') {
char cmd_bit = cmd - '0';
ctx->swclk = (cmd_bit >> 2) & 0x1;
ctx->swdoen = (cmd_bit >> 1) & 0x1;
ctx->swdo = (cmd_bit >> 0) & 0x1;
} else if (cmd == 'R') {
act_send_resp = true;
} else if (cmd == 'Q') {
act_quit = true;
} else {
fprintf(stderr,
"SWD DPI Protocol violation detected: unsupported command '%c'\n", cmd);
exit(1);
}
```
Inside the `remote_bitbang:BitBanger` class the character encoding for writing a zero or one
on the bus as well as a read is defined:
```python
ZERO = b'62'
ONE = b'73'
READ = b'40R'
```
## Usage
Assuming you have pip installed the pluggin, you should be able to connect to the target using:
```
$ pyocd commander -u remote_bitbang:localhost:5555
```
which would connect to TCP port 5555 on localhost. No further configuration is necessary.
Raw data
{
"_id": null,
"home_page": "https://github.com/idex-biometrics/pyocd-bitbang",
"name": "pyocd-bitbang",
"maintainer": "Shareef Jalloq",
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": "shareef.jalloq@idexbiometrics.com",
"keywords": "SWD Bitbang PyOCD Plugin",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/cf/5f/42cc2b804028e48e3a02acfbd49dfae012ee116f548360ed1a9d47fcdda9/pyocd-bitbang-1.0.2.tar.gz",
"platform": "Windows",
"description": "# pyOCD RemoteBitbang DebugProbe plugin\n\nThis pyOCD plugin provides a debug probe that allows connection to a remote bitbang interface\nvia a TCP socket. It is design to be used with targets running in simulation. The remote\nend must provide a TCP server that accepts a socket connection. The debug probe sends an ASCII\nencoding of the bitbang interface.\n\n## Installation\n\n```\n$ pip install pyocd-bitbang\n```\n\n## Background\n\nThis plugin is designed to be used to connect, via SWD, to a Verilator model of a Cortex-M based MCU.\nThis is the pyOCD equivalent to the OpenOCD JTAG remote_bitbang interface, and in fact, uses the same\nASCII encoding.\n\n## Implementation Detail\n\n### DebugProbe\n\nThe class `bitbang_probe:RemoteBitbangProbe` implements the minimum subset required by the\npyOCD `pyocd.probe.debug_probe:DebugProbe` class. Any SWD commands are translated to a series of\nread and write calls that drive the remote SWD interface via a TCP socket. The protocol used is the\nsame as defined in the OpenOCD [remote_bitbang](https://github.com/openocd-org/openocd/blob/master/doc/manual/jtag/drivers/remote_bitbang.txt) specification. Each character sent over the socket corresponds to a request\nto set the bus to a particular state or to read the value currently being driven on SWDI.\n\nUnlike debug probes connected via USB, pyOCD cannot auto-detect the probe. Instead, a unique ID must be\nspecified when launching pyOCD that specifies the probe to use and the IP address and port to use. See below.\n\n### TCP Server and SV DPI\n\nIn addition to this plugin, the testbench must implement a TCP server to which the probe connects as well\nas a DPI interface that drives the SWD pins of the DUT. A good example of such an implementation can be\nfound in the OpenTitan repository [here](https://github.com/lowRISC/opentitan/tree/master/hw/dv/dpi/jtagdpi).\n\nModifying the above example to drive a SWD interface is fairly simple. Instead of the 3 bit Write encoding\ndriving {tck, tms, tdi}, they should drive {swclk, swdoen, swdo}.\n\nThe following snippet shows the character decoding in the main loop of the DPI C function:\n\n```c\n // parse received command byte\n if (cmd >= '0' && cmd <= '7') {\n char cmd_bit = cmd - '0';\n ctx->swclk = (cmd_bit >> 2) & 0x1;\n ctx->swdoen = (cmd_bit >> 1) & 0x1;\n ctx->swdo = (cmd_bit >> 0) & 0x1;\n } else if (cmd == 'R') {\n act_send_resp = true;\n } else if (cmd == 'Q') {\n act_quit = true;\n } else {\n fprintf(stderr,\n \"SWD DPI Protocol violation detected: unsupported command '%c'\\n\", cmd);\n exit(1);\n }\n```\n\nInside the `remote_bitbang:BitBanger` class the character encoding for writing a zero or one\non the bus as well as a read is defined:\n\n```python\n ZERO = b'62'\n ONE = b'73'\n READ = b'40R'\n```\n\n## Usage\n\nAssuming you have pip installed the pluggin, you should be able to connect to the target using:\n\n```\n$ pyocd commander -u remote_bitbang:localhost:5555\n```\n\nwhich would connect to TCP port 5555 on localhost. No further configuration is necessary.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "PyOCD debug probe plugin for Bitbang debug probes",
"version": "1.0.2",
"split_keywords": [
"swd",
"bitbang",
"pyocd",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "400b18f22be0a20366cbd10db7c381f7",
"sha256": "8aaf55bcb49c05f7a0dbb450862ae766998d140694e16405f210a773a9fc2dae"
},
"downloads": -1,
"filename": "pyocd_bitbang-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "400b18f22be0a20366cbd10db7c381f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 10256,
"upload_time": "2022-12-06T22:35:30",
"upload_time_iso_8601": "2022-12-06T22:35:30.566654Z",
"url": "https://files.pythonhosted.org/packages/8d/8a/aa3df7a8a0e9006b514f0a92eca731c67260f371e7922192c84070a904f3/pyocd_bitbang-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "06c093a745d532326e20907fc34f726a",
"sha256": "0b2736e4d93a237bcf1392cc6bcfb6ae550fcaac445a3cb287088e050168162e"
},
"downloads": -1,
"filename": "pyocd-bitbang-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "06c093a745d532326e20907fc34f726a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 10684,
"upload_time": "2022-12-06T22:35:32",
"upload_time_iso_8601": "2022-12-06T22:35:32.054043Z",
"url": "https://files.pythonhosted.org/packages/cf/5f/42cc2b804028e48e3a02acfbd49dfae012ee116f548360ed1a9d47fcdda9/pyocd-bitbang-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-06 22:35:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "idex-biometrics",
"github_project": "pyocd-bitbang",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyocd-bitbang"
}
JSON
