Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .github/workflows/blue.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ jobs:

- name: Run Blue format check
run: |
blue --check .
blue --check main.py core
24 changes: 24 additions & 0 deletions .github/workflows/protocol-hardware-clk-divider.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Protocol Hardware ClkDivider Test

on: [push, pull_request]

jobs:
test:
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Install Icarus Verilog
run: sudo apt update && sudo apt install -y iverilog

- name: Run clock divider testbench
working-directory: protocol/hardware
run: make clk_divider

- name: Save waveform artifact
uses: actions/upload-artifact@v4
with:
name: clk_divider_waveform
path: protocol/hardware/build/ClkDivider_tb.vcd
24 changes: 24 additions & 0 deletions .github/workflows/protocol-hardware-fifo.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Protocol Hardware FIFO Test

on: [push, pull_request]

jobs:
test:
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Install Icarus Verilog
run: sudo apt update && sudo apt install -y iverilog

- name: Run FIFO testbench
working-directory: protocol/hardware
run: make fifo

- name: Save waveform artifact
uses: actions/upload-artifact@v4
with:
name: fifo_waveform
path: protocol/hardware/build/fifo_tb.vcd
2 changes: 1 addition & 1 deletion .github/workflows/pylint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,5 +21,5 @@ jobs:
pip install -r requirements.txt
- name: Analysing the code with pylint
run: |
pylint $(git ls-files '*.py') --max-public-methods=30 \
pylint main.py core --max-public-methods=30 \
--disable=duplicate-code,import-error
21 changes: 20 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -166,4 +166,23 @@ out/
*.bit
teste.py
temp/
arquivos.txt
arquivos.txt

# HDL / FPGA build outputs
protocol/hardware/build/
protocol/hardware/**/impl/
protocol/hardware/**/x.*
protocol/hardware/**/*.fs
protocol/hardware/**/*.jou
protocol/hardware/**/*.log
protocol/hardware/**/*.dcp
protocol/hardware/**/*.rpt
protocol/hardware/**/webtalk*.jou
protocol/hardware/**/webtalk*.log
protocol/hardware/**/usage_statistics_webtalk.*
protocol/hardware/**/clockInfo.txt
protocol/hardware/**/reports/
protocol/hardware/**/slpp_all

# Documentation build output
site/
9 changes: 9 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[submodule "protocol/hardware/modules/SPI-Slave"]
path = protocol/hardware/modules/SPI-Slave
url = https://github.com/Unicamp-Odhin/SPI-Slave
[submodule "protocol/hardware/modules/UART"]
path = protocol/hardware/modules/UART
url = https://github.com/ben-marshall/uart
[submodule "protocol/hardware/modules/Grande-Risco-5"]
path = protocol/hardware/modules/Grande-Risco-5
url = https://github.com/JN513/Grande-Risco-5.git
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Thank you for considering contributing to the project! We’re happy to welcome

- **Blue**:
```bash
blue --check .
blue --check main.py core
```
- **Pylint**:
```bash
Expand All @@ -83,4 +83,4 @@ Thank you for considering contributing to the project! We’re happy to welcome

## License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project. See the [license](https://github.com/LSC-Unicamp/processor_ci_communication/blob/main/LICENSE) for details.
By contributing to the communication software, you agree that your contributions will be licensed under MIT. Hardware contributions under `protocol/hardware` follow CERN-OHL-P, and documentation follows CC BY-SA 4.0.
116 changes: 52 additions & 64 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,110 +1,98 @@
# ProcessorCI Communication

[![Pylint](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/pylint.yml/badge.svg)](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/pylint.yml)
[![Python Code Format Check](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/blue.yml/badge.svg)](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/blue.yml)
[![Pylint](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/pylint.yml/badge.svg)](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/pylint.yml)
[![Python Code Format Check](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/blue.yml/badge.svg)](https://github.com/LSC-Unicamp/processor_ci_communication/actions/workflows/blue.yml)

- **Não fala Inglês? [clique aqui](./README.pt.md)**
- **Nao fala Ingles? [clique aqui](./README.pt.md)**

Welcome to ProcessorCI!
ProcessorCI Communication provides the host-side Python tools used to communicate
with ProcessorCI hardware. It also keeps the protocol hardware reference under
`protocol/hardware` so host and FPGA protocol changes can evolve together.

**ProcessorCI** is a project aimed at modernizing the processor verification process by integrating well-established verification techniques, continuous integration, and FPGA usage.
## Repository Layout

## About this module

This repository provides scripts and tools to facilitate communication between the components involved in ProcessorCI (Hardware and Software), enabling control, command execution, and integration with different protocols.

## Installation

1. **Clone the repository**
Clone the repository to your local development environment.

```bash
git clone https://github.com/LSC-Unicamp/processor_ci_communication.git
cd processor_ci_communication
```text
core/ Python communication API and shell helpers
docs/ MkDocs documentation for communication and protocol use
protocol/hardware/ FPGA protocol controller HDL and board/test assets
main.py CLI entrypoint
mkdocs.yml Documentation site configuration
requirements.txt Python runtime/development dependencies
setup.py Packaging metadata
```

2. **Set up a virtual environment and install dependencies**
## Installation

```bash
git clone https://github.com/LSC-Unicamp/processor_ci_communication.git
cd processor_ci_communication
python3 -m venv env
. env/bin/activate
pip install -r requirements.txt
```

**Note**: Every time you use the project, you need to activate the virtual environment with:
Activate the virtual environment before using the shell in a new terminal:

```bash
. env/bin/activate
```

## Usage

### Operating modes

This module can be used in two main ways:
## Quick Start

1. **Python API**: Importing the modules directly into your Python project.
2. **Interactive Shell**: Using the integrated shell for direct communication with the hardware infrastructure.

### Starting the Shell

To start the integrated shell:

```bash
python3 main.py -s -p PORT
```

**Example:**
Start the interactive communication shell:

```bash
python3 main.py -s -p /dev/ttyUSB0
```

## ProcessorCI Shell
Useful options:

The integrated shell allows direct interaction with the hardware infrastructure. Through it, you can execute the commands defined by the [ProcessorCI Interface](https://lsc-unicamp.github.io/processor-ci-controller/instructions/).
- `-s`, `--shell`: start the integrated shell.
- `-p`, `--port`: serial port, for example `/dev/ttyUSB0`.
- `-b`, `--baudrate`: serial baud rate. Defaults to `115200`.
- `-t`, `--timeout`: serial timeout in seconds. Defaults to `1`.

Additionally, it supports various configurations, such as:
The shell executes the protocol commands documented in
`docs/protocol/instructions.md`.

- **Serial Port**: Specify the communication port using `-p`.
- **Baudrate**: Customize the transmission speed using `-b`.
- **Communication Protocol**: The shell will soon support additional protocols like SPI and PCIe.
## Protocol Hardware

**Example usage:**
The reference FPGA protocol controller lives in `protocol/hardware`. It includes
RTL modules, board targets, examples, and testbenches. Initialize submodules only
when working on optional hardware integrations:

```bash
python3 main.py -s -p /dev/ttyUSB0 -b 115200 -t 2
git submodule update --init --recursive
```

> In the example above:
> - `-p`: Specifies the serial port `/dev/ttyUSB0`.
> - `-b`: Sets the baud rate to `115200`.
> - `-t`: Sets the timeout to 2s.

## Available Flags
Run self-contained protocol hardware tests with:

Below are some useful flags for using the shell:
```bash
make -C protocol/hardware fifo
make -C protocol/hardware clk_divider
```

- **`-s`**: Starts the integrated shell.
- **`-p`**: Specifies the communication port (e.g., `/dev/ttyUSB0`).
- **`-b`**: Sets the baud rate (e.g., `115200`).
- **`-t`**: Sets the timeout (e.g., `1`).
## Documentation

**Full example:**
Serve the documentation site locally:

```bash
python3 main.py -s -p /dev/ttyUSB0 -b 115200 -t 1
pip install -r docs/requirements.txt
mkdocs serve
```

## Questions and Suggestions
The MkDocs site is the canonical protocol documentation surface.

The official documentation is available at: [processorci.ic.unicamp.br](https://processorci.ic.unicamp.br/).
Questions and suggestions can be submitted in the GitHub Issues section. Contributions are welcome, and all Pull Requests will be reviewed and merged whenever possible.
## Development

## Contributing to the project
Keep protocol changes synchronized between the Python communication API and the
hardware interpreter. Document new commands in `docs/protocol/instructions.md`
before relying on them from another ProcessorCI repository.

**Contributions**: If you want to contribute improvements, check the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
## Licenses

## License
This repository keeps license boundaries explicit:

This project is licensed under the [MIT](./LICENSE) license, granting full freedom of use.
- Host communication software: [MIT](LICENSE).
- Protocol hardware sources: `protocol/hardware/LICENSE.CERN-OHL-P`.
- Documentation: `docs/LICENSE.CC-BY-SA-4.0.md`.
Loading
Loading