Metadata-Version: 2.4
Name: xvc-gpiod
Version: 0.1.1
Summary:  Xilinx Virtual Cable (XVC) implementation using gpiod
Author-email: Marc Schink <dev@zapb.de>
Maintainer-email: Marc Schink <dev@zapb.de>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.zapb.de/zapb/xvc-gpiod
Project-URL: Repository, https://gitlab.zapb.de/zapb/xvc-gpiod.git
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Embedded Systems
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gpiod
Dynamic: license-file

# xvc-gpiod

A small Linux GPIO-based implementation of the Xilinx Virtual Cable (XVC) protocol, meant as a simple reference for developing and testing XVC-compatible clients, not for production use.

The JTAG interface is implemented using GPIO bit-banging via the Linux [GPIO Character Device Userspace API](https://docs.kernel.org/userspace-api/gpio/chardev.html) and therefore runs only on Linux systems.

## Protocol Version

This software implements version 1.0 of the XVC protocol.
For more details on the protocol, see the official [documentation](https://github.com/Xilinx/XilinxVirtualCable).

## Requirements

- Python >= 3.10
- Linux system with a GPIO character device interface (e.g., `/dev/gpiochip0`)
- Client software with XVC support (for example, OpenOCD)

## Installation

This section explains how to install `xvc-gpiod`, either from PyPI or from source code.

### From PyPI

```bash
pip install xvc-gpiod
```

### From Source Code

```bash
git clone https://gitlab.zapb.de/zapb/xvc-gpiod.git
cd xvc-gpiod
pip install .
```

## Usage

This section describes how to set up and use `xvc-gpiod`: first wire the JTAG signals to GPIO pins, then start the `xvc-gpiod` daemon, and finally connect an XVC-compatible client.

### Hardware Setup

Any Linux device that exposes a GPIO character device interface should work.
The software has been tested on Raspberry Pi and BeagleBone Black boards.

The **GPIO line** column shows the GPIO line number as exposed by `/dev/gpiochipN`, not the physical header pin number.
Refer to your board's pinout to map header pins to GPIO lines.

#### Raspberry Pi

On Raspberry Pi, you can use the following JTAG pin mapping:

| JTAG signal |  Pin | GPIO line |
|-------------|------|-----------|
|         TDI |   10 |        10 |
|         TMS |   25 |        25 |
|         TCK |   11 |        11 |
|         TDO |    9 |         9 |

Then start the software with the following command:

```bash
xvc-gpiod --chip /dev/gpiochip0 --tms 25 --tdi 10 --tck 11 --tdo 9
```

#### BeagleBone Black

On BeagleBone Black, you can use the following JTAG pin mapping:

| JTAG signal |   Pin | GPIO line |
|-------------|-------|-----------|
| TDI         | P8.12 |        12 |
| TMS         | P8.16 |        14 |
| TCK         | P8.15 |        15 |
| TDO         | P8.11 |        13 |

Then start the software with the following command:

```bash
xvc-gpiod --chip /dev/gpiochip0 --tms 14 --tdi 12 --tck 15 --tdo 13
```

### Client Connection

After the target is connected to your device via GPIO and the `xvc-gpiod` daemon is running, you can connect your client.

In the example below, OpenOCD is used as the client with an APM32F407-series microcontroller from Geehy:

```bash
openocd -c "adapter driver xvc" -c "xvc host localhost" -c "xvc port 2542" -f target/geehy/apm32f4x.cfg
```

By default, `xvc-gpiod` listens on `localhost` and `2542`.

## Credits

The following projects served as inspiration:

- [Xilinx Virtual Cable Server for ESP32](https://github.com/kholia/xvc-esp32)
- [Xilinx Virtual Cable Server for Raspberry Pi](https://github.com/derekmulcahy/xvcpi)

## License

This project is licensed under the [GNU General Public License v3.0 or later](https://www.gnu.org/licenses/gpl-3.0.en.html).
See the [LICENSE](LICENSE) file for details.

## Support

If you appreciate the project, feel free to donate on Liberapay:

[![Liberapay donation link](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/zapb/donate)
