Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
flit committed May 7, 2023
2 parents 04eed76 + d3965a4 commit 1990a3d
Show file tree
Hide file tree
Showing 109 changed files with 96,603 additions and 1,307 deletions.
9 changes: 9 additions & 0 deletions .coveragerc
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,12 @@ equiv_source =
[report]
skip_empty = true
precision = 1
exclude_lines =
pragma: no cover
def __repr__
def [a-z_]*dump
assert False
raise AssertionError
raise NotImplementedError
if __name__ == .__main__.:
if TYPE_CHECKING:
4 changes: 2 additions & 2 deletions .github/workflows/basic_test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ jobs:
with:
python-version: ${{ matrix.python-version }}

# This requires pip 20.1+. The current ubuntu-latest as of 28 Feb 2021 has pip 21.0.1 by default
# for all Python versions 3.6-3.9.
# This requires pip 20.1+. As of 28 Feb 2021 this condition is met for all supported
# Python versions on all OSes.
- name: Get pip cache dir
id: pip-cache
run: |
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ Requirements
- Keil ULINKplus
- NXP LPC-LinkII
- NXP MCU-Link
- WCH-Link (1a86:8011, 2a86:8011 and others)
- [PE Micro](https://pemicro.com/) Cyclone and Multilink
- Raspberry Pi Picoprobe
- SEGGER J-Link
Expand Down
25 changes: 25 additions & 0 deletions docs/builtin-targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -461,6 +461,11 @@ title: Built-in targets
<td>LPC5526</td>
</tr>

<tr><td><code>lpc55s16</code></td>
<td>NXP</td>
<td>LPC55S16</td>
</tr>

<tr><td><code>lpc55s28</code></td>
<td>NXP</td>
<td>LPC55S28</td>
Expand Down Expand Up @@ -761,6 +766,26 @@ title: Built-in targets
<td>W7500</td>
</tr>

<tr><td><code>ytm32b1ld0</code></td>
<td>Yuntu Microelectronics</td>
<td>YTM32B1LD0</td>
</tr>

<tr><td><code>ytm32b1le0</code></td>
<td>Yuntu Microelectronics</td>
<td>YTM32B1LE0</td>
</tr>

<tr><td><code>ytm32b1md1</code></td>
<td>Yuntu Microelectronics</td>
<td>YTM32B1MD1</td>
</tr>

<tr><td><code>ytm32b1me0</code></td>
<td>YTMicro</td>
<td>YTM32B1ME0</td>
</tr>


</table>

109 changes: 102 additions & 7 deletions docs/command_reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,10 @@ that ambiguous because it matches multiple commands, an error will be reported s
command names. In addition, commonly used commands often have a short alias. The alias takes
precedence even when it is a prefix of multiple other commands.

<!-- Maintainer note: the following is auto-generated. Edit the command INFO source material. -->
<!--
Maintainer note: the following is auto-generated. Edit the command class INFO dict source material,
then run ./scripts/generate_command_help.py.
-->

All commands
------------
Expand Down Expand Up @@ -128,9 +131,9 @@ Resume execution of the target.
<tr><td>
<a href="#core"><tt>core</tt></a>
</td><td>
[NUM]
[NUMBER | NAME]
</td><td>
Select CPU core by number or print selected core.
Select CPU core by number or name, or print selected core.
</td></tr>

<tr><td>
Expand Down Expand Up @@ -195,7 +198,7 @@ Write DP register.
</td><td>
[halt|-halt|-h] [TYPE]
</td><td>
Reset the target, optionally specifying the reset type.
Reset the target, optionally with halt and/or specifying the reset type.
</td></tr>

<tr><td>
Expand Down Expand Up @@ -403,6 +406,16 @@ Print core or peripheral register(s).
Set the value of a core or peripheral register.
</td></tr>

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

<tr><td>
<a href="#rtt"><tt>rtt</tt></a>
</td><td>
rtt {setup,start,stop,channels,server}
</td><td>
Control SEGGER RTT compatible interface.
</td></tr>

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

<tr><td>
Expand Down Expand Up @@ -469,6 +482,16 @@ Show the target's current state.
Control thread awareness.
</td></tr>

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

<tr><td>
<a href="#sleep"><tt>sleep</tt></a>
</td><td>
MILLISECONDS
</td><td>
Sleep for a number of milliseconds before continuing.
</td></tr>

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

<tr><td>
Expand Down Expand Up @@ -502,6 +525,14 @@ command can be read, written, or both.

<tr><th>Value</th><th>Access</th><th>Description</th></tr>

<tr><td>
<a href="#accessible-pins"><tt>accessible-pins</tt></a>
</td><td>
read-write
</td><td>
Display which debug probe pins can be read and written with the 'pins' value.
</td></tr>

<tr><td>
<a href="#aps"><tt>aps</tt></a>
</td><td>
Expand All @@ -518,6 +549,14 @@ read-only
Information about CPU cores in the target.
</td></tr>

<tr><td>
<a href="#debug-sequences"><tt>debug-sequences</tt></a>
</td><td>
read-only
</td><td>
Show the available debug sequences from the target's DFP.
</td></tr>

<tr><td>
<a href="#fault"><tt>fault</tt></a>
</td><td>
Expand Down Expand Up @@ -615,6 +654,14 @@ read-only
List of target peripheral instances.
</td></tr>

<tr><td>
<a href="#pins"><tt>pins</tt></a>
</td><td>
read-write
</td><td>
Current debug probe protocol I/O pin states.
</td></tr>

<tr><td>
<a href="#probe-uid"><tt>probe-uid</tt></a>,
<a href="#probe-uid"><tt>uid</tt></a>
Expand All @@ -632,6 +679,14 @@ read-only
Display available register groups for the selected core.
</td></tr>

<tr><td>
<a href="#reset-type"><tt>reset-type</tt></a>
</td><td>
read-write
</td><td>
Show reset configuration and all available reset types for each core. Set current reset type.
</td></tr>

<tr><td>
<a href="#step-into-interrupts"><tt>step-into-interrupts</tt></a>,
<a href="#step-into-interrupts"><tt>si</tt></a>
Expand Down Expand Up @@ -750,8 +805,8 @@ Resume execution of the target. The target's state is read back after resuming.

##### `core`

**Usage**: core [NUM] \
Select CPU core by number or print selected core.
**Usage**: core [NUMBER | NAME] \
Select CPU core by number or name, or print selected core.


##### `halt`
Expand Down Expand Up @@ -803,7 +858,7 @@ Write DP register.
##### `reset`

**Usage**: reset [halt|-halt|-h] [TYPE] \
Reset the target, optionally specifying the reset type. The reset type must be one of 'default', 'hw', 'sw', 'hardware', 'software', 'sw_sysresetreq', 'sw_vectreset', 'sw_emulated', 'sysresetreq', 'vectreset', or 'emulated'.
Reset the target, optionally with halt and/or specifying the reset type. The reset type must be one of 'default', 'hw', 'sw', 'hardware', 'software', 'system', 'core', 'emulated', 'sw_system', 'sw_core', 'sw_sysresetreq', 'sw_vectreset', 'sw_emulated', 'sysresetreq', or 'vectreset'.


##### `unlock`
Expand Down Expand Up @@ -969,6 +1024,14 @@ Print core or peripheral register(s). If no arguments are provided, the 'general
Set the value of a core or peripheral register. The REG parameter must be a core register name or a peripheral.register. When a peripheral register is written, if the -r option is passed then it is read back and the updated value printed. The -p option forces evaluating the register name as a peripheral register name. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.


### Rtt

##### `rtt`

**Usage**: rtt rtt {setup,start,stop,channels,server} \
Control SEGGER RTT compatible interface.


### Semihosting

##### `arm`
Expand Down Expand Up @@ -1023,6 +1086,14 @@ Show the target's current state.
Control thread awareness.


### Utility

##### `sleep`

**Usage**: sleep MILLISECONDS \
Sleep for a number of milliseconds before continuing.


### Values

##### `set`
Expand All @@ -1041,6 +1112,12 @@ Display a value.
Value details
-------------

##### `accessible-pins`

**Access**: read-write \
**Usage**: show accessible-pins, set accessible-pins VALUE \
Display which debug probe pins can be read and written with the 'pins' value.

##### `aps`

**Access**: read-only \
Expand All @@ -1053,6 +1130,12 @@ List discovered Access Ports.
**Usage**: show cores \
Information about CPU cores in the target.

##### `debug-sequences`

**Access**: read-only \
**Usage**: show debug-sequences \
Show the available debug sequences from the target's DFP. Only available for CMSIS-Pack based targets.

##### `fault`

**Access**: read-only \
Expand Down Expand Up @@ -1130,6 +1213,12 @@ The current value of one or more session options. When setting, each argument sh
**Usage**: show peripherals \
List of target peripheral instances.

##### `pins`

**Access**: read-write \
**Usage**: show pins, set pins VALUE \
Current debug probe protocol I/O pin states. The pins value is a mask containing the state of all accessible protocol pins. See the `accessible-pins` value for protocol pins that can be read and written by the connected debug probe.

##### `probe-uid`

**Aliases**: `uid` \
Expand All @@ -1143,6 +1232,12 @@ Target's unique ID.
**Usage**: show register-groups \
Display available register groups for the selected core.

##### `reset-type`

**Access**: read-write \
**Usage**: show reset-type, set reset-type VALUE \
Show reset configuration and all available reset types for each core. Set current reset type.

##### `step-into-interrupts`

**Aliases**: `si` \
Expand Down
2 changes: 2 additions & 0 deletions docs/configuring_logging.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,8 @@ Trace logger | Trace output
`pyocd.coresight.ap.trace` | AP memory transfers
`pyocd.coresight.dap.trace` | AP and DP register accesses
`pyocd.debug.semihost.trace` | Semihost file operations
`pyocd.debug.sequences.scope.trace` | Open-CMSIS-Pack debug sequence variable read/write
`pyocd.debug.sequences.sequences.trace` | Open-CMSIS-Pack debug sequence statements
`pyocd.flash.flash.trace` | Flash algorithm operations
`pyocd.probe.cmsis_dap_probe.trace` | CMSIS-DAP probe API calls
`pyocd.probe.jlink_probe.trace` | Log output from JLink library
Expand Down
24 changes: 11 additions & 13 deletions docs/multicore_debug.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,27 @@ title: Multicore debug
---

pyOCD supports debugging multicore devices. It does this by serving one gdb server per core, to which
you connect independant gdb instances. This is the most reliable method of debugging multicore
embedded devices using gdb.
independent gdb instances are connected. This is the most reliable method of debugging asymmetric multicore
devices using gdb.

`pyocd gdbserver` automatically creates one `GDBServer` instance per core. The first core is given the
user-specified port number. Additional cores have port numbers incremented from there.
`pyocd gdbserver` automatically creates one gdb server instance per core by default. The primary core is given the user-specified port number. Additional cores have port numbers incremented from there. If a gdb server for only one or a subset of cores is desired, the `--core` command line argument can be used with a list of core numbers.

To prevent reset requests from multiple connected gdb instances causing havoc, secondary cores have
their default reset type set to core-only reset (VECTRESET), which will fall back to an emulated
reset for non-v7-M architectures. This feature can be disabled by setting the
`enable_multicore_debug` session option to false.
By default, the primary core is core number 0. For Arm CoreSight based devices, this will be the core with the lowest associated access port address. Use the `primary_core` session option to change the primary core.

When performing multicore debug where multiple gdb instances are connected simultaneously, it is important to set the `enable_multicore_debug` session option to true. This changes secondary cores to have their default reset type set to core-only reset (`sw_core`). This prevents competing reset requests from the multiple gdb instances causing havoc. On v7-M architecture cores, VECTRESET is used. However, VECTRESET is not supported on other core architecture, so non-v7-M architectures will fall back to an emulated core reset.

To debug a multicore device, run `pyocd gdbserver` as usual. This will connect to the device, detect
the cores, and create the gdb server instances on separate ports. Next, start up two gdb instances
and connect to the two gdb server ports. For instance, on a dual core device if you pass 3333 for
the port, connect to port 3333 for the first core and port 3334 for the second core.
the port (or leave it set to default), connect to port 3333 for the first core and port 3334 for the second core.

On many devices, secondary cores are by default held in reset until released by the primary core.
Because gdb does not have a concept of a core held in reset, pyOCD will report a core held in reset
by telling gdb that there is a single thread with the name "Reset". This is visible if you run the
show threads gdb command, and will appear in the Eclipe Debug view's list of threads. All register
by telling gdb that there is a single thread with the name Reset. This is visible if you run the
show threads gdb command, and will appear in the VSCode or Eclipse Debug view's list of threads. All register
values will be reported as 0 until the core is released from reset.

Usually you want to have the primary core load code for the secondary core, so configure the second
core's gdb to not load any code to the target. This is highly device-specific, though, and may
Usually you want to have the primary core load code and/or configure the reset vector for secondary cores prior to releasing those cores from reset. For this situation, configure the second
core's gdb to not load any code to the target. This usage is highly device-specific, though, and may
depend on whether the secondary core's code is running out of flash or RAM.

Loading

0 comments on commit 1990a3d

Please sign in to comment.