Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
flit committed Jan 23, 2022
2 parents ef01536 + bade0ae commit 75c846f
Show file tree
Hide file tree
Showing 251 changed files with 19,979 additions and 5,990 deletions.
125 changes: 125 additions & 0 deletions .azure/functional-test-pipeline.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# pyocd functional test pipeline

trigger:
branches:
include:
- '*'
paths:
include:
- '.azure'
- 'pyocd'
- 'test'
- 'pyproject.toml'
- 'setup.cfg'
- 'setup.py'

pr:
branches:
include:
- '*'
paths:
include:
- '.azure'
- 'pyocd'
- 'test'
- 'pyproject.toml'
- 'setup.cfg'
- 'setup.py'

jobs:
- job: functional_tests
displayName: "Functional tests"
timeoutInMinutes: 200

# Fully clean workspaces before testing.
workspace:
clean: all

# Matrix.
strategy:
matrix:
Mac:
test_os: Darwin
Linux:
test_os: Linux
Win:
test_os: Windows_NT

# Agent pool and requirements.
pool:
name: functional-test
demands:
- Agent.OS -equals $(test_os)

steps:
# Configure shallow checkout.
- checkout: self
fetchDepth: 1

# Linux/Mac: Activate venv and install dependencies.
- script: |
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install .[test]
name: install_dependencies_posix
displayName: 'Install dependencies (Posix)'
condition: and(in(variables['agent.os'], 'Darwin', 'Linux'), succeeded())
# Windows: Activate venv and install dependencies.
- script: |
python -m venv .venv
call .venv\Scripts\activate.bat
python -m pip install --upgrade pip setuptools wheel
pip install .[test]
name: install_dependencies_win
displayName: 'Install dependencies (Win)'
condition: and(eq(variables['agent.os'], 'Windows_NT'), succeeded())
# Download pyocd.yaml config file into test directory.
- task: UniversalPackages@0
name: install_test_config
inputs:
command: download
vstsFeed: 'pyocd/config'
vstsFeedPackage: 'pyocd-test-config'
vstsPackageVersion: '*'
downloadDirectory: 'test'
verbosity: 'debug'
displayName: 'Install test config'

# Linux/Mac: Activate venv and run automated test suite.
- script: |
source .venv/bin/activate
cd test
python ./automated_test.py --quiet
name: run_tests_posix
displayName: 'Run tests (Posix)'
condition: and(in(variables['agent.os'], 'Darwin', 'Linux'), succeeded())
# Windows: Activate venv and run automated test suite.
- script: |
call .venv\Scripts\activate.bat
cd test
python automated_test.py --quiet
name: run_tests_win
displayName: 'Run tests (Win)'
condition: and(eq(variables['agent.os'], 'Windows_NT'), succeeded())
# Publish JUnit-format test results.
- task: PublishTestResults@2
inputs:
testResultsFiles: test/output/*.xml
testRunTitle: "$(Agent.OS) functional tests"
platform: "$(Agent.OS)" # Doesn't show up anywhere in Azure UI.
condition: succeededOrFailed()
displayName: "Publish test results"

# Publish test outputs.
- task: PublishPipelineArtifact@1
inputs:
targetPath: "test/output"
artifactName: outputs_$(test_os)
condition: succeededOrFailed()
displayName: "Publish test output files"

25 changes: 19 additions & 6 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -1,14 +1,27 @@
# EditorConfig: https://editorconfig.org/

# top-most EditorConfig file
root = true

# Unix-style newlines with a newline ending every file
# 4 space indentation for all files
# No trailing whitespace
[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8

# 4 space indentation for Python
[*.py]
indent_style = space
indent_size = 4
trim_trailing_whitespace = false
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
max_line_length = 120

# Exceptions to the rule...

[Makefile]
indent_style = tab

[*.bat]
end_of_line = crlf

[*.{yaml,yml,xml,svd}]
indent_size = 2
32 changes: 30 additions & 2 deletions .lgtm.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ path_classifiers:
- scripts/generate_command_help.py
test:
# Mark all code under the src/ directory as test related.
# Really, the crc analyzer is not for test, but LGTL can't build embedded.
# Really, the crc analyzer is not for test, but LGTM can't build embedded.
- src
- exclude: src/analyzer

Expand All @@ -21,4 +21,32 @@ queries:
#
# In some cases the 'while' block will exit with only a 'return', so the 'else' isn't really
# necessary, but retaining it maintains the expected pattern.
- exclude: py/redundant-else
- exclude: "py/redundant-else"

# Exclude cases where there is an import of the same module via 'import foo' and 'from foo import ...'.
# The query for this is too general and catches a lot of cases that are not really errors, especially
# with includes of types for annotations.
#
# Example 1:
#
# import pyocd
# from pyocd import debug
#
# These two imports trigger this query, even though it's pretty clearly a reasonable usage.
#
# Example 2:
#
# if TYPE_CHECKING:
# import types
#
# def foo():
# import types
#
# In this case, types is only needed within foo() at runtime and is not imported globally to reduce
# namespace pollution and import times. But when type checking it's types is also imported. The query
# doesn't see the TYPE_CHECKING predicate and triggers.
- exclude: "py/import-and-import-from"

# This query triggers on logging of the probe's UID as specified on the command line in cleartext.
# Clearly the UID is not sensitive data, at least in the traditional sense.
- exclude: "py/clear-text-logging-sensitive-data"
28 changes: 7 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
pyOCD
=====

[\[pyocd.io\]](https://pyocd.io/) [\[Docs\]](https://pyocd.io/docs) [\[Slack\]](https://join.slack.com/t/pyocd/shared_invite/zt-wmy3zvg5-nRLj1GBWYh708TVfIx9Llg) [\[Mailing list\]](https://groups.google.com/g/pyocd)
[\[pyocd.io\]](https://pyocd.io/) [\[Docs\]](https://pyocd.io/docs) [\[Slack\]](https://join.slack.com/t/pyocd/shared_invite/zt-wmy3zvg5-nRLj1GBWYh708TVfIx9Llg) [\[Mailing list\]](https://groups.google.com/g/pyocd) [\[CI results\]](https://dev.azure.com/pyocd/pyocd/_build?definitionId=1&_a=summary)

<table><tr><td>

### News

- A new CI pipeline for functional tests is now running on a new test farm. Full results are [publicly
accessible](https://dev.azure.com/pyocd/pyocd/_build?definitionId=1&_a=summary) on Azure Pipelines.
- pyOCD has several new community resources: the [pyocd.io](https://pyocd.io/) website,
a [Slack workspace](https://join.slack.com/t/pyocd/shared_invite/zt-zqjv6zr5-ZfGAXl_mFCGGmFlB_8riHA),
and a [mailing list](https://groups.google.com/g/pyocd) for announcements.
Expand All @@ -16,12 +18,11 @@ See the [wiki news page](https://github.com/pyocd/pyOCD/wiki/News) for all recen

</td></tr></table>

pyOCD is an open source Python package for programming and debugging Arm Cortex-M microcontrollers
using multiple supported types of USB debug probes. It is fully cross-platform, with support for
Linux, macOS, Windows, and FreeBSD.
pyOCD is an open source Python based tool and package for programming and debugging Arm Cortex-M microcontrollers
with a wide range of debug probes. It is fully cross-platform, with support for Linux, macOS, Windows, and FreeBSD.

A command line tool is provided that covers most use cases, or you can make use of the Python
API to enable low-level target control. A common use for the Python API is to run and control CI
API to facilitate custom target control. A common use for the Python API is to run and control CI
tests.

Support for more than 70 popular MCUs is built-in. In addition, through the use of CMSIS Device
Expand All @@ -38,6 +39,7 @@ The `pyocd` command line tool gives you total control over your device with thes
- `commander`: Interactive REPL control and inspection of the MCU.
- `server`: Share a debug probe with a TCP/IP server.
- `reset`: Hardware or software reset of a device.
- `rtt`: Stream Segger RTT IO with _any_ debug probe.
- `list`: Show connected devices.

The API and tools provide these features:
Expand Down Expand Up @@ -141,22 +143,6 @@ You have a few options here:
4. Run the command in a [virtualenv](https://virtualenv.pypa.io/en/latest/)
local to a specific project working set.

### libusb installation

[pyusb](https://github.com/pyusb/pyusb) and its backend library [libusb](https://libusb.info/) are
dependencies on all supported operating systems. pyusb is a regular Python package and will be
installed along with pyOCD. However, libusb is a binary shared library that does not get installed
automatically via pip dependency management.

How to install libusb depends on your OS:

- macOS: use Homebrew: `brew install libusb`
- Linux and BSD: should already be installed.
- Windows: download libusb from [libusb.info](https://libusb.info/) and place the .dll file in your Python
installation folder next to python.exe. Make sure to use the same 32- or 64-bit architecture as
your Python installation. The latest release is [available on GitHub](https://github.com/libusb/libusb/releases);
download the .7z archive under Assets. Use the library from the VS2019 folder in the archive.

### udev rules on Linux

On Linux, particularly Ubuntu 16.04+, you must configure udev rules to allow pyOCD to access debug
Expand Down
38 changes: 18 additions & 20 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,47 @@
---
title: Contents
---

## Table of Contents

### User documentation
### Getting started

- [Installing](installing.md)
- [Installing on non-x86](installing_on_non_x86.md)
- [GDB setup](gdb_setup.md)

#### Topics
### User documentation

- [Terminology](terminology.md)
- [Target support](target_support.md)
- [Debug probes](debug_probes.md)
- [Configuration](configuration.md)
- [User scripts](user_scripts.md)
- [Remote probe access](remote_probe_access.md)
- [Configuring logging](configuring_logging.md)
- [Debugging multicore devices](multicore_debug.md)
- [Target security features](security.md)
- [Debugging multicore devices](multicore_debug.md)
- [Semihosting](semihosting.md)
- [SWO/SWV](swo_swv.md)
- [Target family usage notes](target_notes.md)

#### Reference
### Reference

- [Built-in targets](builtin-targets.md)
- [Session options reference](options.md)
- [Command reference](command_reference.md)
- [Environment variables](env_vars.md)

#### Python API
### Python API

- [Introduction to the pyOCD Python API](python_api.md)
- [Python API examples](api_examples.md)

#### Miscellaneous

- [Installing on non-x86 platforms](installing_on_non_x86.md)

### Developer documentation

#### How-tos

- [Developers’ guide](developers_guide.md)
- [How to add new targets](adding_new_targets.md)
- [Building a standalone gdb server executable](how_to_build.md)
- [Running the automated tests](automated_tests.md)

#### Architecture and Design

- [Architecture overview](architecture.md)
- [Remote probe protocol](remote_probe_protocol.md)
- Internal design
- [Architecture overview](architecture.md)
- [Remote probe protocol](remote_probe_protocol.md)



Expand Down
23 changes: 21 additions & 2 deletions docs/automated_tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,17 +37,36 @@ Functional tests:

- `basic_test.py`: a simple test that checks a range of basic functionality, from flash programming to accessing memory and core registers.
- `blank_test.py`: tests ability to connect to devices with with blank flash. (Not run by `automated_test.py`.)
- `commander_test.py`: tests the `pyocd commander` functionality.
- `commands_test.py`: tests commands supported by commander and gdb monitor commands.
- `concurrency_test.py`: verify multiple threads can simultaneously access a debug probe, specifically for memory
transfers.
- `connect_test.py`: tests all combinations of the halt on connect and disconnect resume options.
- `cortex_test.py`: validates CPU control operations and memory accesses.
- `debug_context_test.py`: tests some `DebugContext` classes.
- `flash_test.py`: comprehensive test of flash programming.
- `flash_loader_test.py`: test the classes in the `pyocd.flash.loader` module.
- `gdb_server_json_test.py`: validates the JSON output from pyocd-gdbserver used by tools like the GNU MCU Eclipse pyOCD plugin.
- `flash_test.py`: comprehensive test of flash programming.
- `import_all.py`: imports all pyocd modules. (Not run by `automated_test.py`.)
- `gdb_test.py`: tests the gdbserver by running a script in a gdb process. Note that on Windows,
the 32-bit Python 2.7 must be installed for the Python-enabled gdb to work properly and for
this test to pass.
- `json_lists_test.py`: validates the JSON output from `pyocd json`.
- `parallel_test.py`: checks for issues with accessing debug probes from multiple processes and threads simultaneously. (Not run by `automated_test.py`.)
- `probeserver_test.py`: verify remote probe server and client.
- `speed_test.py`: performance test for memory reads and writes.
- `user_script_test.py`: verify loading of user scripts.

## Azure Pipelines

PyOCD uses Azure Pipelines to run the CI tests for commits and pull requests. The pipeline runs the functional tests on
a set of test machines, called self-hosted test agents in Azure Pipelines parlance. There is one each of Mac, Linux, and
Windows test agents.

The complete results from pipeline runs are [publicly
accessible](https://dev.azure.com/pyocd/pyocd/_build?definitionId=1&_a=summary).

For pull requests, a pyOCD team member or collaborator must manually initiate the pipeline run by entering a special
comment of the form "/azp run" or "/AzurePipelines run".


## Testing with tox
Expand Down
Loading

0 comments on commit 75c846f

Please sign in to comment.