리눅스 개발환경 설정 가이드

시스템 환경: Ubuntu 22.04.5 LTS / Efinity 2026.1

0. 전체 구성 한눈에 보기

설치 링크 : https://www.efinixinc.com/support/index.php

Efinix Support

회원가입 필요

구성요소	역할
Efinity 2026.1	FPGA 합성 · P&R · 비트스트림 · 프로그래머
Efinity RISC-V IDE	SapphireSoC(RISC-V) 펌웨어 개발 · 디버깅
USB 드라이버	JTAG/FTDI 프로그래밍 케이블

개발 흐름:

RTL 설계 → Efinity 합성/P&R/비트스트림 → 보드 프로그래밍
                        │
                        └→ (SoC 포함 시) RISC-V IDE로 펌웨어 빌드 → JTAG 디버깅

1. 사전 요구사항

1-1. 지원 OS

• Ubuntu 20.04 이상 (현재: 22.04.5 ✅) 또는 RHEL 8.8 이상

1-2. 필수 라이브러리 (GUI용)

# Ubuntu 22.04은 libxcb-cursor0 기본 포함 (현재 설치됨 ✅)
sudo apt update
sudo apt install libxcb-cursor0

Ubuntu 20.04이면 위 패키지를 반드시 수동 설치. VM/WSL 환경은 추가 라이브러리 필요(설치 가이드 PDF 참고).

1-3. Java (IP Manager / Sapphire SoC 설정용)

java -version    # 현재: OpenJDK 11.0.31 ✅
# 없으면: sudo apt install openjdk-11-jre

RISC-V IDE는 자체 JRE를 내장하고 있어 시스템 Java 없이도 동작함. Java는 Efinity의 IP Manager용.

2. Efinity 소프트웨어 설치

2-1. 압축 해제

cd /home/server/work/Efinix
tar -xjvf efinity-2026.1.132-linux-x64.tar.bz2

설치 최상위($EFINITY_HOME):

/home/server/work/Efinix/efinity-2026.1.132-linux-x64/efinity/2026.1

2-2. 실행 방법

# 방법 A) 환경설정 없이 바로 GUI 실행
/home/server/work/Efinix/efinity-2026.1.132-linux-x64/efinity/2026.1/bin/efinity_sh.sh

# 방법 B) 환경변수 등록 후 실행 (CLI 도구도 같이 쓸 때)
source /home/server/work/Efinix/efinity-2026.1.132-linux-x64/efinity/2026.1/bin/setup.sh
efinity &

setup.sh는 $EFINITY_HOME, PATH(efx_run.py 등), Qt 플러그인 경로를 자동 등록.

3. USB 프로그래머 드라이버 (보드 프로그래밍/디버깅 시 필수)

보드 연결을 먼저 해제한 뒤 실행:

cd /home/server/work/Efinix/efinity-2026.1.132-linux-x64/efinity/2026.1
sudo ./bin/install_usb_driver.sh
sudo udevadm control --reload-rules
sudo udevadm trigger

• /etc/udev/rules.d/80-efx-pgm.rules 설치됨
• 실행 전 보드가 연결돼 있었다면 뽑았다 다시 연결
• 대상: FTDI FT232H/FT2232H/FT4232H (개발보드 내장 또는 Mini Module, 3.3V I/O)

4. Efinity RISC-V IDE 설치 (SoC 펌웨어 개발 시)

4-1. 설치 (.run 자동 설치 파일)

cd /home/server/work/Efinix
chmod +x efinity-riscv-ide-2026.1.0.7-linux-x64.run
./efinity-riscv-ide-2026.1.0.7-linux-x64.run

설치 구성:

항목	경로
IDE 실행 파일 (Eclipse, JRE 내장)	efinity/Efinity-RISCV-IDE/efinity-riscv-ide
실행 심볼릭 링크	efinity/efinity-riscv-ide
RISC-V 툴체인(gcc)	efinity/toolchain/bin/riscv-none-elf-gcc
OpenOCD (JTAG 디버깅)	efinity/openocd/bin
QEMU (에뮬레이션)	efinity/qemu/
환경설정	efinity/setup_standalone.sh
사용 가이드	efinity/APB225-Efinix-IDE.pdf
기본 BSP	efinix/EfxSapphireSoC

4-2. IDE 실행

# GUI 실행 (workspace 선택 창 → 프로젝트의 embedded_sw 폴더 지정)
/home/server/work/Efinix/efinity/efinity-riscv-ide &

또는 Efinity GUI 툴바의 Open RISC-V IDE 버튼으로 연동 실행(BSP 자동 인식).

5. 경로 규칙

Efinity와 RISC-V(make 기반) 빌드는 경로에 한글·공백·특수문자가 있으면 실패합니다.

• Efinity 공식 경고: "프로젝트 경로에 비-영문 문자 금지"
• 주의: Efinity/IDE 실행 중에는 프로젝트 폴더 이름을 바꾸지 말 것.
  실행 중 경로가 바뀌면 열린 프로젝트 참조가 깨져 Synthesize 등 버튼이 비활성화됨
  → 이 경우 프로젝트를 닫고 새 경로에서 다시 열기.

6. 셸 편의 설정 (선택)

~/.bashrc 하단에 추가하면 매번 긴 경로를 안 쳐도 됨:

# --- Efinix ---
export EFINITY_HOME=/home/server/work/Efinix/efinity-2026.1.132-linux-x64/efinity/2026.1
alias efx-env='source $EFINITY_HOME/bin/setup.sh'      # Efinity CLI 환경
alias efinity='$EFINITY_HOME/bin/efinity_sh.sh'         # Efinity GUI
alias riscv-ide='/home/server/work/Efinix/efinity/efinity-riscv-ide'   # RISC-V IDE

적용: source ~/.bashrc

7. FPGA 프로젝트 실행 흐름 (일반)

아래 <프로젝트> / <프로젝트폴더>는 실제 프로젝트 이름·경로로 바꿔서 사용.프로젝트 폴더에는 보통 <프로젝트>.xml(메인), <프로젝트>.peri.xml(Interface Designer),RTL 소스, outflow/(빌드 산출물)가 들어 있음.

7-1. GUI에서

1. source $EFINITY_HOME/bin/setup.sh && efinity &
2. File > Open Project → <프로젝트폴더>/<프로젝트>.xml
3. 구버전에서 만든 프로젝트면 마이그레이션 안내 승인 (구버전 산출물은 재컴파일 권장)
4. Dashboard에서 Synthesize → Place & Route → Generate Bitstream 순서 실행
5. Programmer 탭 → outflow/<프로젝트>.bit(또는 .hex) 선택 → Start Program

7-2. RISC-V 펌웨어 (프로젝트에 SoC 포함 시)

riscv-ide &     # (alias, 없으면 전체 경로)

• Workspace: <프로젝트폴더>/embedded_sw/<SoC명> (예: embedded_sw/SapphireSoc, ASCII 경로 필수)
• 프로젝트 우클릭 → Build Project → .elf 생성
• Run > Debug → OpenOCD + JTAG로 보드에 다운로드/디버깅 (USB 드라이버 필요)

8. 검증 명령어

# Efinity CLI 동작 확인
source $EFINITY_HOME/bin/setup.sh && efx_run.py --help

# RISC-V 툴체인 확인
source /home/server/work/Efinix/efinity/setup_standalone.sh
riscv-none-elf-gcc --version

# USB 드라이버(udev 규칙) 확인
ls -l /etc/udev/rules.d/80-efx-pgm.rules

# 프로그래밍 케이블 인식 확인 (보드 연결 후)
lsusb | grep -i ftdi

9. 트러블슈팅

증상	원인 / 해결
Synthesize 버튼 회색	열린 프로젝트 없음/경로 무효(실행 중 폴더명 변경 등) → 프로젝트 닫고 새 경로에서 다시 열기. 플로우 실행 중에도 회색
GUI가 안 열림	sudo apt install libxcb-cursor0. Wayland면 export QT_QPA_PLATFORM=xcb
빌드/합성이 이상하게 실패	경로에 한글·공백 있는지 확인
보드 인식 안 됨	80-efx-pgm.rules 존재 확인, install_usb_driver.sh 재실행, 케이블 뽑았다 재연결
RISC-V make 에러(경로)	workspace/프로젝트 경로에 공백·한글 제거
디버그 로그 필요	$EFINITY_HOME/bin/lc.ini에서 debug logging false→true → 로그: ~/.local/share/efinity/log/

참고 문서

• Efinity 설치 가이드:
• RISC-V IDE 가이드: 

efinity-installation-v3.8.pdf

0.48MB

APB225-Efinix-IDE.pdf

1.63MB