Vivado Docker Environment

This repository provides a Docker-based Vivado build and simulation environment. It is designed for:

• Running Vivado without polluting the host system
• Simulating HDL with ghdl, and cocotb
• Automatically cloning the project repository inside the container (Not yet working, we still need to handle the SSH key properly)
• Handling private Git access securely (via SSH key mount or agent forwarding)

📚 Documentation & References

• Vivado Installation Notes (UG973)
• Vivado Silent Install Guide
• Vivado Known Issues
• Vivado Implementation Crash Debug Guide

⚙️ Prerequisites

1. Docker and Docker Compose installed.
2. Access to:
   • Vivado installer files (xsetup, install_config.txt)
   • Git repository
3. A deploy SSH key with read-only access to your repo.
   • Store it as deploy_key in the project root.
   • Ensure proper permissions:

     chmod 600 deploy_key
     

🏗 Build the Container

To build without cache (recommended after Dockerfile changes):

docker compose build --no-cache

To rebuild normally:

docker compose build

📦 Vivado Installation in Docker

Vivado is installed inside the container in /opt/Xilinx.

1. Prepare the Vivado installer folder
   Place xsetup and install_config.txt in the directory specified by .env:

   Example .env:

   VIVADO_INSTALLER_PATH=/path/to/vivado/installer
   

   Note that this is inside the host.

2. Run Vivado installer in container:

   docker compose run --user=root vivado_installer /usr/local/bin/install_vivado.sh
   

   This uses:

   ./xsetup -a XilinxEULA,3rdPartyEULA -b Install -c ./install_config.txt
   

3. Vivado installation is cached in a named Docker volume (vivado_opt) so it persists across container rebuilds.

🔑 Cloning Private Repos in Docker

Option 1 – Deploy Key (recommended)

Mount a deploy key into /run/secrets/deploy_key (read-only):

docker-compose.yml:

    volumes:
      - ./deploy_key:/run/secrets/deploy_key:ro

The clone_repo.sh script will:

• Install the key into /home/vivado/.ssh/id_ed25519
• Add github.com / gitlab.com / corporate host to known_hosts
• Clone or update the repo

Run:

docker compose run --rm vivado_installer

Option 2 – SSH Agent Forwarding

If running from Linux/WSL2, forward your SSH agent:

export SSH_AUTH_SOCK=$(ssh-agent -s)
docker compose run -e SSH_AUTH_SOCK=$SSH_AUTH_SOCK -v $SSH_AUTH_SOCK:$SSH_AUTH_SOCK vivado_installer

🖥 Running the Environment

Start a container (Zsh shell):

docker compose run --rm vivado_installer

This will:

• Install Vivado if needed
• Clone/update your project repo
• Drop you into /home/vivado as vivado user

🧪 Example: Running a Simulation

Inside the container:

cd ~/tich/sim/cocotb/tests
python test_i2c_sniffer.py

🧹 Cleanup

Remove volumes (Vivado install + repo):

docker compose down -v

📌 Notes

• Never bake private keys into the Docker image; always mount them at runtime.
• To avoid Zsh new-user prompts, a minimal .zshrc is provided in the image:

  export PATH="$PATH"
  

• Vivado install is large; ensure enough space in your Docker volumes.