Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

target: add xc2xx device support for XHSC #1687

Open
wants to merge 29 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
4a8cbb7
commands: reset: fall back to reset via probe if context has no selec…
flit May 22, 2023
73b9ce9
cortex-m: reset_halt: just warn about invalid T-bit, don't fix (#1559)
flit May 22, 2023
574359c
target: family: psoc6: remove unnecessary sleep during reset. (#1562)
te-johan May 23, 2023
b995d84
docs: move outline to be colocated with source
flit May 26, 2023
035f81b
debug: sequences: assignment expressions (#1564)
flit May 28, 2023
0f53af6
flash: fix some type errors, sort imports (#1566)
flit May 30, 2023
3ea6ec0
core: session: only create one session to access options when there's…
flit May 30, 2023
d09fd5f
docs: board_ids: alert, D0xx range, other small updates
flit May 28, 2023
f3c9c80
docs: outline changes to rename User guide, move API arch location
flit May 28, 2023
89fd4f2
docs: add faq
flit May 28, 2023
c72b949
docs: add gdbserver
flit May 28, 2023
4033cd0
docs: developer guide: add section on debugging pyocd
flit Jun 11, 2023
376d3f4
Use correct flash address for MAX32670
ozersa Jun 16, 2023
dc9f2c0
docs: fix missing import of time in api example (#1582)
liux-pro Jul 11, 2023
0189b2f
flash: loader: fix missing import of RamRegion (#1588)
flit Jul 20, 2023
fdaf08a
target: hc32l130: fix 32k+ flash error (#1590)
kaidegit Jul 21, 2023
e662365
probe: cmsis-dap: use test binary from builtin board data for v2.1 ba…
flit Jul 23, 2023
94f1860
coresight: adiv5 discovery: increment invalid AP count on exception (…
flit Jul 23, 2023
401a01c
target: family: remove part number match for NXP MIMXRTxxxx series fa…
flit Jul 23, 2023
37c8efb
probe: cmsis-dap: usb backends: windows performance fix and more (#1595)
flit Jul 30, 2023
6dcd439
rtt: fix cb not found (#1583)
tdasika Aug 5, 2023
9253740
target: fix HC32L13x size and enable double buffering (#1609)
kaidegit Aug 13, 2023
0e3742a
target: add s32k344 support (#1627)
PetervdPerk-NXP Sep 26, 2023
fba00fb
target: added target Realtek RTL8762C (#1624)
suphammer Sep 26, 2023
cb97846
Merge branch 'develop'
flit Oct 8, 2023
975fe95
docs: update builtin targets and commands, XDS110 note
flit Oct 8, 2023
6dc261a
Add mps2 an521, reset on loading to Ram and soft-bkpt-as-hard (#1638)
ithinuel Oct 19, 2023
5ab5c32
target: add Ambiq Apollo3 target and NM180410 board support (#1632)
joshua-nmi Oct 19, 2023
48a0976
target: add xc2xx device support for XHSC
Apr 16, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/api_examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ This example shows basic connection, loading a firmware binary, and some simple
#!/usr/bin/env python3
from pyocd.core.helpers import ConnectHelper
from pyocd.flash.file_programmer import FileProgrammer
import time

import logging
logging.basicConfig(level=logging.INFO)
Expand Down
82 changes: 81 additions & 1 deletion docs/builtin-targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,36 @@ title: Built-in targets

<tr><th>Target Type Name</th><th>Vendor</th><th>Name</th></tr>

<tr><td><code>air001</code></td>
<td>AirM2M</td>
<td>Air001</td>
</tr>

<tr><td><code>air32f103xb</code></td>
<td>AirM2M</td>
<td>Air32F103xB</td>
</tr>

<tr><td><code>air32f103xc</code></td>
<td>AirM2M</td>
<td>Air32F103xC</td>
</tr>

<tr><td><code>air32f103xe</code></td>
<td>AirM2M</td>
<td>Air32F103xE</td>
</tr>

<tr><td><code>air32f103xg</code></td>
<td>AirM2M</td>
<td>Air32F103xG</td>
</tr>

<tr><td><code>air32f103xp</code></td>
<td>AirM2M</td>
<td>Air32F103xP</td>
</tr>

<tr><td><code>cc3220sf</code></td>
<td>Texas Instruments</td>
<td>CC3220SF</td>
Expand Down Expand Up @@ -126,6 +156,16 @@ title: Built-in targets
<td>CY8C6xxA</td>
</tr>

<tr><td><code>hc32a460xe</code></td>
<td>HDSC</td>
<td>HC32F460xE</td>
</tr>

<tr><td><code>hc32a4a0xi</code></td>
<td>HDSC</td>
<td>HC32F4A0xI</td>
</tr>

<tr><td><code>hc32f003</code></td>
<td>HDSC</td>
<td>HC32F003</td>
Expand Down Expand Up @@ -176,6 +216,16 @@ title: Built-in targets
<td>HC32F196</td>
</tr>

<tr><td><code>hc32f448xa</code></td>
<td>HDSC</td>
<td>HC32F448xA</td>
</tr>

<tr><td><code>hc32f448xc</code></td>
<td>HDSC</td>
<td>HC32F448xC</td>
</tr>

<tr><td><code>hc32f451xc</code></td>
<td>HDSC</td>
<td>HC32F451xC</td>
Expand Down Expand Up @@ -546,6 +596,11 @@ title: Built-in targets
<td>MAX32660</td>
</tr>

<tr><td><code>max32666</code></td>
<td>Maxim</td>
<td>MAX32666</td>
</tr>

<tr><td><code>max32670</code></td>
<td>Maxim</td>
<td>MAX32670</td>
Expand Down Expand Up @@ -668,7 +723,7 @@ title: Built-in targets

<tr><td><code>nrf91</code></td>
<td>Nordic Semiconductor</td>
<td>NRF9160</td>
<td>NRF91XX</td>
</tr>

<tr><td><code>rp2040</code></td>
Expand All @@ -691,6 +746,16 @@ title: Built-in targets
<td>RTL8195AM</td>
</tr>

<tr><td><code>rtl8762c</code></td>
<td>Realtek Semiconductor</td>
<td>RTL8762C</td>
</tr>

<tr><td><code>s32k344</code></td>
<td>NXP</td>
<td>S32K344</td>
</tr>

<tr><td><code>s5js100</code></td>
<td>Samsung</td>
<td>S5JS100</td>
Expand Down Expand Up @@ -741,6 +806,21 @@ title: Built-in targets
<td>STM32F767xx</td>
</tr>

<tr><td><code>stm32h723xx</code></td>
<td>STMicroelectronics</td>
<td>STM32H723xx</td>
</tr>

<tr><td><code>stm32h743xx</code></td>
<td>STMicroelectronics</td>
<td>STM32H743xx</td>
</tr>

<tr><td><code>stm32h7b0xx</code></td>
<td>STMicroelectronics</td>
<td>STM32H7B0xx</td>
</tr>

<tr><td><code>stm32l031x6</code></td>
<td>STMicroelectronics</td>
<td>STM32L031x6</td>
Expand Down
18 changes: 18 additions & 0 deletions docs/command_reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,16 @@ ADDR DATA+
Write 8-bit bytes to memory.
</td></tr>

<tr><td colspan="3"><b>Nrf91</b></td></tr>

<tr><td>
<a href="#nrf91-update-modem-fw"><tt>nrf91-update-modem-fw</tt></a>
</td><td>
[-f] mfw_nrf91xx_x.x.x.zip
</td><td>
Update modem firmware for an nRF91 target.
</td></tr>

<tr><td colspan="3"><b>Openocd_compatibility</b></td></tr>

<tr><td>
Expand Down Expand Up @@ -992,6 +1002,14 @@ Write 64-bit double-words to memory. The data arguments are 64-bit words in big-
Write 8-bit bytes to memory. The data arguments are 8-bit bytes. Can write to both RAM and flash. Flash writes are subject to minimum write size and alignment, and the flash page must have been previously erased.


### Nrf91

##### `nrf91-update-modem-fw`

**Usage**: nrf91-update-modem-fw [-f] mfw_nrf91xx_x.x.x.zip \
Update modem firmware for an nRF91 target. If -f is specified, modem firmware is written to the device, even if the correct version is already present.


### Openocd compatibility

##### `init`
Expand Down
4 changes: 4 additions & 0 deletions docs/debug_probes.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,10 @@ DAPLink firmware updates are available on the [daplink.io](https://daplink.io/)
The Microchip (previously Atmel) EDBG probe firmware, at the time of this writing, provides a CMSIS-DAP v1 interface.
On macOS, reading command responses always times out. The probe works on other OSes, however.

### TI XDS110

XDS110 firmware version 03.00.00.25 is known to have an issue when using multiple outstanding packets (the default setting). To work around this, set the `cmsis_dap.limit_packets` session option, e.g. `-Ocmsis_dap.limit_packets=1` on the command line. Earlier firmware versions most likely exhibit the issue; it is unknown whether it is fixed in more recent versions.


### PE Micro Cyclone and Multilink

Expand Down
17 changes: 15 additions & 2 deletions docs/developer/board_ids.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
title: Board IDs
---

<div class="alert alert-warning">
New CMSIS-DAP firmware releases should use the CMSIS-DAP v2.1 board and target identification features
rather than board IDs.
</div>

This page documents the board IDs reported by certain [debug probes]({% link _docs/debug_probes.md %}) with which pyOCD can automatically identify a board and its target type.

## Introduction
Expand All @@ -20,11 +25,12 @@ Board ID definition:
- There are multiple cases of boards from different vendors being incorrectly allocated in another vendor's namespace, so this cannot solely be relied upon. It's only really useful for grouping of IDs.
- Reserved values::
- "C0xx" is reserved for "community" boards, i.e. open source hardware and non-commercial projects.
- "D0xx" is reserved for boards that are not also Mbed platforms, mostly DAPLink firmware.
- "0000" is reserved to mean "no on-board target". That is, the debug probe is standalone must be connected to the target with a cable.

Currently these debug probe firmware support board IDs:
- [DAPLink](https://daplink.io/), via the first 4 chars of the USB serial number
- STLinkV2-1 and V3, via an `.htm` file on the associated USB mass storage volume.
- STLinkV2-1 and V3, via an `.htm` file on the associated USB mass storage volume and an STLink protocol command.

## Lists

Expand All @@ -34,10 +40,17 @@ You can see the full list of public Mbed platforms at [https://os.mbed.com/api/v

## Getting a new ID

To request a new board ID, fill out the form here: [https://os.mbed.com/request-board-id](https://os.mbed.com/request-board-id)
There are two ways to get new board IDs:

1. Post a request to the #daplink channel on the [pyOCD Slack workspace](https://pyocd.slack.com/) ([Join](https://join.slack.com/t/pyocd/shared_invite/zt-zqjv6zr5-ZfGAXl_mFCGGmFlB_8riHA)). We can allocate you a 0xDxxx board ID.

2. For new Mbed OS platforms, request a new board ID by filling out the form here: [https://os.mbed.com/request-board-id](https://os.mbed.com/request-board-id)

## Moving forward

Version 2.1 of the [CMSIS-DAP](https://arm-software.github.io/CMSIS_5/DAP/html/index.html) specification adds support for new [DAP_Info](https://arm-software.github.io/CMSIS_5/DAP/html/group__DAP__Info.html) selectors that identify the board and target. The values returned by these selectors are required to match board and target identifiers in CMSIS-Packs.

PyOCD supports the new CMSIS-DAP v2.1 info selectors and will use them in preference to a board ID if available. This works with any debug probe firmware compatible with CMSIS-DAP. Thus, any new CMSIS-DAP firmware projects should support v2.1 and the new DAP_Info selectors rather than implementing board IDs.

The DAPLink open source CMSIS-DAP firmware has support for the v2.1 identifiers. We recommend using these identifiers rather than a board ID for any new DAPLink based firmware.

65 changes: 64 additions & 1 deletion docs/developers_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ If you switch branches, you may need to reinstall.

Because the `develop` branch doesn't have version tags except older tags from the `develop` branch point,
the version number of pyOCD might be significantly out of date. If this is an issue, you can override the
version by setting the `SETUPTOOLS_SCM_PRETEND_VERSION` environmment variable to the desired version number
version by setting the `SETUPTOOLS_SCM_PRETEND_VERSION` environment variable to the desired version number
(without a "v" prefix).

**Step 4.** Develop
Expand Down Expand Up @@ -122,3 +122,66 @@ Maintainers will cherry-pick commits between `main` and `develop` as necessary t
If you have any questions about how best to submit changes or the branch policy, please ask in the
[Slack](https://join.slack.com/t/pyocd/shared_invite/zt-zqjv6zr5-ZfGAXl_mFCGGmFlB_8riHA) workspace or
[GitHub Discussions](https://github.com/pyocd/pyOCD/discussions). We'll be happy to help.


## Debugging pyOCD

### VS Code

Debugging pyOCD launched by VS Code is straightforward, and is much like debugging any package.

1. First, set up the pyOCD development and virtualenv as described above.

2. Set up the launch config as follows.

- Set `pythonPath` to the python executable in the virtualenv.

- Set `module` to `pyocd.__main__`, to debug pyOCD entry point as a module. This works better than trying to debug the script `.../pyocd/__main__.py` as it ensures the relative module references inside pyOCD work correctly..

For instance, here is a VS Code launch config for pyOCD's gdbserver:

{
"name": "pyocd gdbserver",
"type": "python",
"request": "launch",
"module": "pyocd.__main__",
"console": "integratedTerminal",
"stopOnEntry": true,
"pythonPath": "/Users/username/projects/pyOCD/venv/bin/python3",
"showReturnValue": true,
"args": ["gdb", "-v"]
}


It's also possible to debug pyOCD remotely. This is useful either for cases where it is launched by another tool and you cannot directly control the command line , or is on another machine.

For remote debug, use a launch config like this:

{
"name": "Python: Attach using port",
"type": "python",
"request": "attach",
"port": 5678,
}

If the pyOCD process is on another machine, add a `host` key to the launch config with the host name. (This defaults to localhost.)

Install [debugpy](https://github.com/microsoft/debugpy/) with pip into your virtual environment.

To remotely debug pyOCD from the command line, run it with the `debugpy` module. For instance, `python -m debugpy --listen 5678 -m pyocd gdb -v`. Additionally, `--wait-for-client` can be added after the port number to wait for the debug client to connect before running pyOCD.

If you don't control pyOCD's launch, then `debugpy` can be called directly from pyOCD's code. Add the following code to pyocd. Inside `pyocd.__main__.PyOCDTool.run()` is a good location, though it can be done at module level in `__main__.py`.

```py
import debugpy
debugpy.listen(5678)
```

To pause pyOCD's execution and wait for the debug client to connect, add this line as well:
```py
debugpy.wait_for_client()
```




46 changes: 46 additions & 0 deletions docs/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
- title: Getting started
docs:
- installing
- installing_on_non_x86
- gdb_setup
- title: User guide
docs:
- target_support
- debug_probes
- configuration
- open_cmsis_pack_support
- gdbserver
- user_scripts
- remote_probe_access
- configuring_logging
- security
- multicore_debug
- semihosting
- swo_swv
- memory_attributes
- target_family_notes
- faq
- title: Reference
docs:
- terminology
- builtin-targets
- options
- command_reference
- env_vars
- title: Python API
docs:
- api/architecture
- python_api
- api_examples
- api/using_session_options
- title: Developers
docs:
- developers_guide
- adding_new_targets
# - how_to_build
- automated_tests
- title: Internal design
docs:
- architecture
- developer/board_ids
- remote_probe_protocol
20 changes: 20 additions & 0 deletions docs/faq.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
title: FAQ
---

### Common issues

##### Debug probe is not available

- Linux: Make sure udev is configured correctly to allow access to USB debug probes. PyOCD includes a set of predefined [udev config files](https://github.com/pyocd/pyOCD/tree/main/udev) for common probe. Alternatively, you can run pyocd using sudo, but this is strongly recommended against.
- MacOS: Make sure another process hasn't taken ownership of the USB device.

##### Getting "No ACK" errors when attempting to connect

- A "No ACK" error means the target is not responding at all to SWD/JTAG transfers. This can be for a few reasons:
- The target is not powered on. Either the board isn't power up or the target is in a deep sleep mode.
- The SWD/JTAG pins haved been pinmuxed to different peripherals.
- The SWD or JTAG wire protocol being used isn't supported by the device.
- A target-specific reason, such as a proprietary connection procedure that hasn't been performed.
- The method to gain debug control of a powered down or sleeping device is target dependent. However, it generally involves first waking the device, then halting the CPU before the resident firmware can place the device in a low power state. For many MCUs, these steps can be accomplished by telling pyOCD to connect while the reset pin is held asserted, eg connecting under reset. To use this mode, pass `--connect=under-reset`. On certain devices this won't work because the reset pin performs a cold reset that also resets debug logic. For these devices, please refer to the vendor's reference manual or programming manual.
- A similar method to waking a sleeping device is needed to gain control of a device whose firmware changes the SWD/JTAG pinmux after it starts running. Connecting under reset also works in this case, if the device support it.
Loading