RISC-V FPGA Workshop – Ubuntu on Docker Setup Manual (Arty A7-T100 Focused)

0. Beginner’s Guide: What is PowerShell and Prompts?

PowerShell is a command window on Windows (like Terminal on macOS). It allows you to type commands instead of using the mouse. You will use PowerShell to:

• Create folders
• Run Docker commands
• Work with Git and Ubuntu inside Docker

Understanding Prompts

Prompts are automatic indicators that show your current environment. You do not type the prompt itself; you only type the commands after it.

Example Commands:

• PowerShell:

PS C:\Users\YourName> mkdir riscv-edu
PS C:\Users\YourName> cd riscv-edu

• macOS Terminal:

$ mkdir riscv-edu
$ cd riscv-edu

• Ubuntu inside Docker:

root@container:/workspace# make
root@container:/workspace# ./hello_riscv

✅ Remember: Only type the command after the prompt. The prompt itself appears automatically.

How to Open PowerShell (Windows 10 or 11)

Method 1 – From Start Menu

1. Click the Start Menu (bottom-left corner).
2. Type PowerShell in the search box.
3. You will see Windows PowerShell appear.
4. Right-click it → select Run as administrator.
5. A blue window opens. The title bar should say: Administrator: Windows PowerShell.

Method 2 – Shortcut

• Press Windows key + X, then choose Windows PowerShell (Admin).

1. Key Concept: Ubuntu Inside Docker

• Ubuntu runs inside Docker, not directly on Windows/macOS.
• All RISC-V/FPGA tools are installed inside Ubuntu during the Docker build.
• FPGA board used in this workshop: Arty A7-T100
• Simple RISC-V exercises can be tested in software simulation only, without the FPGA board.

Visual:
Host (Windows/macOS)
└── Docker
└── Ubuntu
└── RISC-V & FPGA Tools

2. Lecturer Workflow: Preparing Ubuntu + Tools

? On Host (PowerShell for Windows / Terminal for macOS)

1. Create project folder:

PS C:\Users\YourName> mkdir riscv-edu
PS C:\Users\YourName> cd riscv-edu

2. Create Dockerfile (with tools installation) — use a text editor. Include all necessary RISC-V and FPGA tools for Arty A7-T100:

FROM ubuntu:22.04
ENV DEBIAN_FRONTEND=noninteractive

# Utilities
RUN apt update && apt install -y build-essential git make python3 python3-pip wget curl

# RISC-V compiler & simulator
RUN apt install -y gcc-riscv64-unknown-elf gdb-multiarch spike

# Optional RTL simulation tool
RUN apt install -y yosys gtkwave

WORKDIR /workspace
COPY samples/ /workspace/samples/

Note: iCE40-specific tools (nextpnr-ice40, icestorm) are removed because Arty A7-T100 uses Vivado for bitstream generation.

3. Build Docker image (tools installed inside Ubuntu automatically):

PS C:\Users\YourName\riscv-edu> docker build -t riscv-edu:latest .

? Inside Ubuntu on Docker

4. Run container:

root@container:/workspace# docker run -it riscv-edu:latest /bin/bash

5. Test RISC-V and simulation tools:

root@container:/workspace# cd /workspace/samples
root@container:/workspace# make
root@container:/workspace# ./hello_riscv
root@container:/workspace# yosys -V   # check Yosys installation

Tools are pre-installed; students do not install them manually.

? Back on Host (PowerShell / Terminal)

6. Push to GitHub:

PS C:\Users\YourName\riscv-edu> git init
PS C:\Users\YourName\riscv-edu> git add .
PS C:\Users\YourName\riscv-edu> git commit -m "RISC-V FPGA environment"
PS C:\Users\YourName\riscv-edu> git remote add origin https://github.com/lecturer-repo/riscv-edu.git
PS C:\Users\YourName\riscv-edu> git push -u origin main

3. Student Workflow: Using Ubuntu on Docker

? On Host Terminal / PowerShell

1. Clone repository:

PS C:\Users\YourName> git clone https://github.com/lecturer-repo/riscv-edu.git
PS C:\Users\YourName> cd riscv-edu

2. Build Docker image (Ubuntu + tools):

PS C:\Users\YourName\riscv-edu> docker build -t riscv-edu:latest .

3. Run Ubuntu container:

PS C:\Users\YourName\riscv-edu> docker run -it --name riscv-container -v "$PWD":/workspace riscv-edu:latest /bin/bash

? Inside Ubuntu on Docker

4. Work on projects and test tools:

root@container:/workspace# cd /workspace/samples
root@container:/workspace# make
root@container:/workspace# ./hello_riscv
root@container:/workspace# yosys -V

5. FPGA Bitstream Workflow for Arty A7-T100

Option 1 – Pre-generated Bitstream (Backup)

• Lecturer provides pre-generated .bit files.
• Students load .bit file to FPGA to test their RISC-V design.

root@container:/workspace# vivado -mode batch -source load_prebuilt_bitstream.tcl

Option 2 – Student-Generated Bitstream (Advanced)

• Students modify RISC-V cores or peripherals and generate a new bitstream using Vivado WebPACK.

Flow Steps:

1. Launch Vivado GUI

root@container:/workspace# vivado &

• GUI opens via X11 forwarding or VNC in Docker.

2. Open Project / Design

• Load RISC-V project folder and make modifications.

3. Synthesis & Implementation

• Run synthesis → check for errors.
• Run implementation → verify timing constraints.

4. Generate Bitstream

• Vivado creates .bit file in impl_1 directory.

5. Load Bitstream to FPGA

root@container:/workspace# vivado -mode batch -source load_new_bitstream.tcl

• Verify LEDs, switches, or other peripherals.

6. Backup Option

• If synthesis fails, revert to pre-generated .bit from Option 1.

7. Save & Commit Changes

root@container:/workspace# git add .
root@container:/workspace# git commit -m "Modified RISC-V core"
root@container:/workspace# git push

6. Exit:

root@container:/workspace# exit

7. Resume later:

PS C:\Users\YourName\riscv-edu> docker start -ai riscv-container

Notes

• All tools are now fully Arty A7-T100 focused.
• iCE40-specific tools are removed to avoid confusion.
• Students can still do full simulation and modification inside Ubuntu on Docker.

RISC-V FPGA Workshop – Ubuntu on Docker Setup Manual (Arty A7-T100 Focused)

——————————————————————–

0. Beginner’s Guide: What is PowerShell and Prompts?

PowerShell is a command window on Windows (like Terminal on macOS). It allows you to type commands instead of using the mouse. You will use PowerShell to:

• Create folders
• Run Docker commands
• Work with Git and Ubuntu inside Docker

Understanding Prompts

Prompts are automatic indicators that show your current environment. You do not type the prompt itself; you only type the commands after it.

Example Commands:

• PowerShell:

PS C:\Users\YourName> mkdir riscv-edu
PS C:\Users\YourName> cd riscv-edu

• macOS Terminal:

$ mkdir riscv-edu
$ cd riscv-edu

• Ubuntu inside Docker:

root@container:/workspace# make
root@container:/workspace# ./hello_riscv

Remember: Only type the command after the prompt. The prompt itself appears automatically.

How to Open PowerShell (Windows 10 or 11)

Method 1 – From Start Menu

1. Click the Start Menu (bottom-left corner).
2. Type PowerShell in the search box.
3. You will see Windows PowerShell appear.
4. Right-click it → select Run as administrator.
5. A blue window opens. The title bar should say: Administrator: Windows PowerShell.

Method 2 – Shortcut

• Press Windows key + X, then choose Windows PowerShell (Admin).

1. Key Concept: Ubuntu Inside Docker

• Ubuntu runs inside Docker, not directly on Windows/macOS.
• All RISC-V/FPGA tools are installed inside Ubuntu during the Docker build.
• FPGA board used in this workshop: Arty A7-T100
• Simple RISC-V exercises can be tested in software simulation only, without the FPGA board.

Visual:
Host (Windows/macOS)
└── Docker
└── Ubuntu
└── RISC-V & FPGA Tools

2. Lecturer Workflow: Preparing Ubuntu + Tools

On Host (PowerShell for Windows / Terminal for macOS)

1. Create project folder:

PS C:\Users\YourName> mkdir riscv-edu
PS C:\Users\YourName> cd riscv-edu

2. Create Dockerfile (with tools installation) — use a text editor. Include all necessary RISC-V and FPGA tools for Arty A7-T100:

FROM ubuntu:22.04
ENV DEBIAN_FRONTEND=noninteractive

# Utilities
RUN apt update && apt install -y build-essential git make python3 python3-pip wget curl

# RISC-V compiler & simulator
RUN apt install -y gcc-riscv64-unknown-elf gdb-multiarch spike

# Optional RTL simulation tool
RUN apt install -y yosys gtkwave

WORKDIR /workspace
COPY samples/ /workspace/samples/

Note: iCE40-specific tools (nextpnr-ice40, icestorm) are removed because Arty A7-T100 uses Vivado for bitstream generation.

3. Build Docker image (tools installed inside Ubuntu automatically):

PS C:\Users\YourName\riscv-edu> docker build -t riscv-edu:latest .

Inside Ubuntu on Docker

4. Run container:

root@container:/workspace# docker run -it riscv-edu:latest /bin/bash

5. Test RISC-V and simulation tools:

root@container:/workspace# cd /workspace/samples
root@container:/workspace# make
root@container:/workspace# ./hello_riscv
root@container:/workspace# yosys -V   # check Yosys installation

Tools are pre-installed; students do not install them manually.

Back on Host (PowerShell / Terminal)

6. Push to GitHub:

PS C:\Users\YourName\riscv-edu> git init
PS C:\Users\YourName\riscv-edu> git add .
PS C:\Users\YourName\riscv-edu> git commit -m "RISC-V FPGA environment"
PS C:\Users\YourName\riscv-edu> git remote add origin https://github.com/lecturer-repo/riscv-edu.git
PS C:\Users\YourName\riscv-edu> git push -u origin main

3. Student Workflow: Using Ubuntu on Docker

On Host Terminal / PowerShell

1. Clone repository:

PS C:\Users\YourName> git clone https://github.com/lecturer-repo/riscv-edu.git
PS C:\Users\YourName> cd riscv-edu

2. Build Docker image (Ubuntu + tools):

PS C:\Users\YourName\riscv-edu> docker build -t riscv-edu:latest .

3. Run Ubuntu container:

PS C:\Users\YourName\riscv-edu> docker run -it --name riscv-container -v "$PWD":/workspace riscv-edu:latest /bin/bash

Inside Ubuntu on Docker

4. Work on projects and test tools:

root@container:/workspace# cd /workspace/samples
root@container:/workspace# make
root@container:/workspace# ./hello_riscv
root@container:/workspace# yosys -V

5. FPGA Bitstream Workflow for Arty A7-T100

Option 1 – Pre-generated Bitstream (Backup)

• Lecturer provides pre-generated .bit files.
• Students load .bit file to FPGA to test their RISC-V design.

root@container:/workspace# vivado -mode batch -source load_prebuilt_bitstream.tcl

Option 2 – Student-Generated Bitstream (Advanced)

• Students modify RISC-V cores or peripherals and generate a new bitstream using Vivado WebPACK.

Flow Steps:

1. Launch Vivado GUI

root@container:/workspace# vivado &

• GUI opens via X11 forwarding or VNC in Docker.

2. Open Project / Design

• Load RISC-V project folder and make modifications.

3. Synthesis & Implementation

• Run synthesis → check for errors.
• Run implementation → verify timing constraints.

4. Generate Bitstream

• Vivado creates .bit file in impl_1 directory.

5. Load Bitstream to FPGA

root@container:/workspace# vivado -mode batch -source load_new_bitstream.tcl

• Verify LEDs, switches, or other peripherals.

6. Backup Option

• If synthesis fails, revert to pre-generated .bit from Option 1.

7. Save & Commit Changes

root@container:/workspace# git add .
root@container:/workspace# git commit -m "Modified RISC-V core"
root@container:/workspace# git push

6. Exit:

root@container:/workspace# exit

7. Resume later:

PS C:\Users\YourName\riscv-edu> docker start -ai riscv-container

Notes

• All tools are now fully Arty A7-T100 focused.
• iCE40-specific tools are removed to avoid confusion.
• Students can still do full simulation and modification inside Ubuntu on Docker.

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Comprehensive Seminar Environment Setup Manual (English Edition)

Overview

This manual provides a step-by-step guide for instructors to prepare and manage a complete RISC-V SoC FPGA seminar environment using Docker. It integrates all prior feedback and corrections for smooth setup, testing, and distribution across participant PCs.

Seminar System Overview

Objective

To ensure all seminar participants can work in a uniform, reproducible, and isolated environment that includes all necessary tools for RISC-V SoC FPGA design, simulation, and HW/SW co-design.

Key Technologies

• Ubuntu or Windows 11 host environment
• Docker Desktop or Docker Engine
• VSCode with Remote Containers plugin (optional but recommended)
• RISC-V toolchain, FPGA synthesis tools, and supporting scripts

Folder and File Structure

Base Directory Example

C:\Seminar\RISC-V-Workshop\
 ├─ Dockerfile
 ├─ setup.sh
 ├─ tools\
 ├─ examples\
 ├─ scripts\
 ├─ docs\
 └─ vscode\

Folder Description

File Description

Dockerfile and Image Relationship

Example Command Sequence

# 1. Navigate to the seminar folder
cd C:\Seminar\RISC-V-Workshop

# 2. Build Docker image
docker build -t riscv-seminar:latest .

# 3. Run and test the environment
docker run -it riscv-seminar:latest /bin/bash

# 4. Export the image for student distribution
docker save -o riscv-seminar.tar riscv-seminar:latest

Student-Side Import and Use

# Load the seminar image
docker load -i riscv-seminar.tar

# Create a container from the image
docker run -it --name student01 -v C:\Users\Student01\work:/work riscv-seminar:latest

Tip: The folder mounted to /work allows persistence between container runs.

Example Dockerfile

# Base Ubuntu image
FROM ubuntu:22.04

# Set working directory
WORKDIR /workspace

# Install essential packages
RUN apt-get update && apt-get install -y \
    git make gcc g++ wget vim python3 curl && \
    rm -rf /var/lib/apt/lists/*

# Install RISC-V toolchain
RUN git clone https://github.com/riscv/riscv-gnu-toolchain.git && \
    cd riscv-gnu-toolchain && \
    ./configure --prefix=/opt/riscv && make

# Copy seminar materials
COPY tools/ /opt/tools/
COPY examples/ /workspace/examples/
COPY scripts/ /workspace/scripts/

# Set environment variables
ENV PATH="/opt/riscv/bin:$PATH"

# Default shell
CMD ["/bin/bash"]

Note: The above example may require several hours to build depending on host performance.

Workflow Summary for Instructors

PowerShell ISE and Docker Integration

Using PowerShell ISE

1. Open PowerShell ISE as Administrator.
2. Use cd to navigate to the seminar folder.
3. Execute build or run commands, for example:

   docker build -t riscv-seminar:latest .
   docker run -it riscv-seminar:latest
   

4. If the context menu does not show Run as Administrator, manually open PowerShell (Start → type PowerShell → right-click → Run as Administrator).

Troubleshooting

• If Administrator prompt changes unexpectedly, confirm user privileges.
• Check Docker Desktop is running and WSL2 backend is enabled.
• Use docker ps to list running containers.

Recommended Lecture Schedule

Best Practices

• Pre-test your Docker image on both Windows and Ubuntu hosts.
• Keep the Dockerfile modular for easy updates.
• Use version tags for each iteration (e.g., riscv-seminar:v1.1).
• Store large tool archives in tools/ and copy them locally to speed up build time.
• Encourage students to use VSCode Remote Containers for seamless access.

Conclusion

By following this detailed workflow, all seminar participants will have a consistent, reliable, and reproducible environment. Docker ensures that software versions remain synchronized across systems, minimizing setup difficulties and maximizing productive learning time.

Prepared by: RISC-V SoC FPGA Training Team
Author: Prof. Hiroaki Kunieda (EICOT Electronic Co., Tokyo Institute of Technology, Japan)
Version: October 2025
Language: English

Ah — I understand your issue clearly: you want to automatically generate a correctly named Dockerfile using PowerShell or another editor (like VS Code / ISE / Notepad), without accidentally creating a file with a “wrong” extension or encoding, which causes Docker to report “no identifier” or cannot find Dockerfile.

Here’s a beginner-friendly explanation and method.

? Problem

Common mistakes that make Docker unable to recognize the Dockerfile:

✅ Correct Method 1: PowerShell Out-File (Automatic)

This method guarantees a correctly named Dockerfile.

1. Open PowerShell

2. Go to your project folder:

3. Create the Dockerfile with correct encoding:

✅ This produces a plain Dockerfile that Docker can read.

• No .txt

• UTF-8 without BOM

• Exactly the name Dockerfile

✅ Correct Method 2: Notepad / VS Code (Manual)

1. Open Notepad:

2. Paste your Dockerfile content.

3. Save As:

   • File name: Dockerfile

   • Save as type: All Files

   • Encoding: UTF-8

   • Folder: C:\Users\<yourname>\Documents\RISC-V-Workshop\

If you see .txt added automatically, rename the file and remove .txt extension.

✅ Correct Method 3: VS Code / ISE

• Open VS Code or PowerShell ISE

• Create a new file

• Paste the Dockerfile content

• Save As → Dockerfile → All Files → UTF-8

Avoid saving as .ps1 (PowerShell script) — Docker will ignore it.

? Verify File

After creation, run in PowerShell:

Expected output:

• If the file is exactly Dockerfile and not .txt or .ps1, Docker will recognize it.

? Build Docker Image

Finally, to test:

• The dot . at the end tells Docker to look in the current folder for Dockerfile.

If you want, I can create a one-click PowerShell script that:

1. Checks your folder

2. Generates the Dockerfile

3. Automatically builds the Docker image

This guarantees no “identifier missing” errors even for beginners.

Do you want me to make that?

RISC-V SoC FPGA Workshop — Instructor Guide (English Edition)

Overview

This guide provides instructors and assistants with a detailed workflow for setting up and managing the RISC-V SoC FPGA Workshop environment. It covers safe folder setup, Docker usage, and guidance for assisting students.

1️⃣ Objectives

• Ensure all instructors can prepare and verify the workshop environment.
• Provide clear steps to guide students in building, testing, and running exercises.
• Include detailed explanations of PowerShell prompts and safe folder locations.

2️⃣ System Requirements

• Windows 11 or Ubuntu 22.04 host
• Docker Desktop or Docker Engine
• Optional: VSCode with Remote Containers plugin
• Hardware: ≥16GB RAM, ≥50GB free disk space

3️⃣ Understanding PowerShell Prompts and Safe Folder Locations

3.1 Default Prompt in Administrator PowerShell

• When opening PowerShell as administrator, the default prompt is:

PS C:\WINDOWS\system32>

• This is the Windows system folder. Avoid using this location for workshop files to prevent accidental system changes.

3.2 Recommended Folder for Workshop Files

• Safe and accessible locations for instructors and students:
  1. User Documents folder:

     C:\Users\<Username>\Documents\RISC-V-Workshop
     

  2. Directly under C: drive (shorter path):

     C:\RISC-V-Workshop
     

• Documents folder is standard for user files and safe to write to without admin permissions.

3.3 Creating the Workshop Folder

# Navigate to user's Documents folder
cd $env:USERPROFILE\Documents

# Create the main workshop folder
mkdir RISC-V-Workshop
cd RISC-V-Workshop

# Create subfolders
mkdir tools examples scripts docs workspace

• Resulting folder structure:

C:\Users\<Username>\Documents\RISC-V-Workshop\
 ├─ tools\
 ├─ examples\
 ├─ scripts\
 ├─ docs\
 └─ workspace\

3.4 Moving to the Workshop Folder

cd $env:USERPROFILE\Documents\RISC-V-Workshop

• PowerShell prompt becomes:

PS C:\Users\<Username>\Documents\RISC-V-Workshop>

• All Docker commands should be run from this location.

3.5 Docker Volume Mount Example

docker run -it -v C:\Users\<Username>\Documents\RISC-V-Workshop\workspace:/workspace riscv-workshop:latest

• Maps the host’s workspace folder to the container’s /workspace directory
• Work done in the container persists on the host

3.6 Key Points for Instructors

1. Do not use C:\WINDOWS\system32 for workshop files.
2. Safe folder should be under user account.
3. The Documents folder is recommended for ease and safety.
4. Docker volume mounts should point to this folder to persist files.
5. Instructors should ensure students understand this mapping before exercises.

4️⃣ Folder Structure for Workshop

C:\RISC-V-Workshop\
 ├─ Dockerfile
 ├─ tools\
 ├─ examples\
 ├─ scripts\
 ├─ docs\
 └─ workspace\

• tools/: pre-installed binaries and toolchain files
• examples/: sample projects for exercises
• scripts/: helper scripts for building and running
• docs/: manuals and lecture notes
• workspace/: student working folder mapped to Docker container

5️⃣ Docker Workflow for Instructors

Build Docker Image

cd C:\RISC-V-Workshop
docker build -t riscv-workshop:latest .

Run Container

docker run -it --name instructor01 -v C:\RISC-V-Workshop\workspace:/workspace riscv-workshop:latest

• All work in /workspace persists between sessions

Verify Setup

Inside container:

riscv64-unknown-elf-gcc --version
ls /workspace/examples

• Ensure all tools are accessible and examples are correctly mounted

6️⃣ Tips for Supporting Students

• Keep each student’s workspace organized and isolated using Docker container names
• Verify students are using the correct folder and Docker volume mapping
• Assist with troubleshooting Docker images, builds, or container errors
• Encourage students to work inside the mounted /workspace to avoid data loss

7️⃣ Daily Workshop Schedule for Instructors

8️⃣ Summary

By following this guide, instructors will:

• Prepare and verify a safe, reproducible environment
• Guide students effectively through Docker, toolchain, and FPGA exercises
• Ensure students understand safe folder usage and volume mapping

Instructor support is critical during all sessions to help students with environment or build issues.

# — 設定: 作業ディレクトリを指定（必要なら変更） —
$workDir = “C:\RISC-V-Workshop”
if (-not (Test-Path $workDir)) { New-Item -ItemType Directory -Path $workDir | Out-Null }
Set-Location $workDir

# — 既存 Dockerfile を削除（存在する場合） —
if (Test-Path Dockerfile) {
Write-Host “既存の Dockerfile を削除します…”
Remove-Item -Force Dockerfile
}

# — Dockerfile の中身（ここを必要に応じて編集） —
$dockerfileContent = @”
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
build-essential \
git \
make \
python3 \
python3-pip \
wget \
curl

WORKDIR /workspace
“@

# — BOMなし UTF-8 で書き出す（識別子を付けない） —
Write-Host “Dockerfile を作成しています（UTF-8 no BOM）…”
$utf8NoBom = New-Object System.Text.UTF8Encoding($false) # $false = emitIdentifier (BOM) を出さない
[System.IO.File]::WriteAllText((Join-Path $workDir “Dockerfile”), $dockerfileContent, $utf8NoBom)

# — 作成ファイルの存在確認と先頭行表示 —
Write-Host “`n=== ファイル一覧 ===”
Get-ChildItem -Force -Name

Write-Host “`n=== Dockerfile 先頭（1行目） ===”
Get-Content Dockerfile -TotalCount 1 | ForEach-Object { Write-Host $_ }

# — バイナリ先頭のチェック: BOM (EF BB BF) が無いことを確認 —
$bytes = [System.IO.File]::ReadAllBytes((Join-Path $workDir “Dockerfile”))
if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
Write-Host “`n警告: ファイル先頭に UTF-8 BOM (EF BB BF) が検出されました。” -ForegroundColor Red
} else {
Write-Host “`nOK: UTF-8 BOM は付属していません（no BOM）。” -ForegroundColor Green
}

# — （任意）ファイルサイズ表示 —
Write-Host (“Dockerfile サイズ: {0} bytes” -f $bytes.Length)

# — Docker ビルド実行 —
Write-Host “`n=== docker build を実行します ===” -ForegroundColor Cyan
# イメージ名は小文字にすること
$imageTag = “risc-v-workshop:latest”

try {
docker build -t $imageTag . 2>&1 | ForEach-Object { Write-Host $_ }
Write-Host “`nビルドが終了しました。イメージ一覧を表示します：” -ForegroundColor Green
docker images –format “table {{.Repository}}\t{{.Tag}}\t{{.Size}}”
} catch {
Write-Host “`ndocker ビルド中にエラーが発生しました：” -ForegroundColor Red
Write-Host $_.Exception.Message
}

ホーム（申込）へ戻る