🛠️ Xcelium 시뮬레이션 파일 리스트 작성법 — SystemVerilog 컴파일 에러를 막는 5가지 골든 룰
SoC 검증 엔지니어를 위한 실전 가이드 | Cadence Xcelium · SystemVerilog · UVM
Xcelium 시뮬레이션 환경에서 SystemVerilog 파일 리스트(f-list)를 올바르게 구성하는 것은 컴파일 에러의 80% 이상을 사전에 차단하는 핵심 스킬입니다. 특히 ARM Cortex 시리즈나 Synopsys DesignWare 같은 대형 IP를 통합할 때, "모든 파일이 리스트에 있는데 왜 에러가 나지?"라는 상황을 자주 만나게 됩니다.
이 문제의 근본 원인은 SystemVerilog의 컴파일 단위(Compilation Unit) 메커니즘과 선언-참조 간의 의존성 구조에 있습니다. Cadence 공식 가이드와 업계에서 검증된 골든 룰(Golden Rule)을 바탕으로, 에러 없는 시뮬레이션 환경 구축 전략을 정리했습니다.
💡 핵심 요약: Xcelium(xrun)은 파일 리스트를 위에서 아래로 순차 컴파일합니다. "참조 대상은 참조 시점 이전에 컴파일되어 있어야 한다"는 원칙만 확실히 지키면 대부분의 에러를 예방할 수 있습니다.
📌 1. SystemVerilog 컴파일 메커니즘: 선(先) 선언, 후(後) 참조
SystemVerilog 시뮬레이터는 파일 리스트의 첫 줄부터 마지막 줄까지 순차적으로 파싱합니다. 이 과정에서 가장 중요한 규칙은 단 하나입니다.
⚠️ "사용하기 전에 먼저 정의하라" (Define Before Use)
예를 들어 Module A가 Package P에 정의된 typedef를 사용한다면, f-list에서 Package P는 반드시 Module A보다 앞에 위치해야 합니다. 순서가 뒤바뀌면 컴파일러는 해당 타입을 인식하지 못해 에러를 발생시킵니다.
2026년 현재 Xcelium 24.09 이후 버전에서는 병렬 컴파일 최적화가 강화되었지만, 패키지와 매크로의 선행 선언 원칙은 여전히 동일하게 적용됩니다. 오히려 멀티코어 컴파일 환경에서는 의존성 순서가 더욱 중요해졌습니다.
🏆 2. 파일 리스트 구성을 위한 5가지 골든 룰
① Global Defines 및 Macros — 최상단 배치
프로젝트 전체에서 사용되는 +define+이나 전역 매크로 파일(.vh, .svh)을 가장 먼저 선언합니다. 조건부 컴파일(`ifdef, `ifndef)이 이후 파일들의 로직에 직접 영향을 미치기 때문입니다.
✅ 실무 팁: Bit width, Memory size, Feature enable/disable 등 하드웨어 구성을 결정하는 파라미터성 매크로가 여기에 해당합니다. 팀 내에서 project_defines.svh로 통일하여 관리하면 효율적입니다.
② Package 파일의 우선 배치 (Package-First)
SystemVerilog의 package는 클래스, 함수, 사용자 정의 타입의 컨테이너입니다. RTL과 Testbench가 이를 import하여 사용하므로, 모든 패키지는 일반 모듈보다 반드시 먼저 나열되어야 합니다.
패키지 간에도 의존성이 존재할 수 있습니다. pkg_B가 pkg_A를 참조한다면, 반드시 pkg_A → pkg_B 순서를 지켜야 합니다.
③ Base Class 및 Interface 선언
UVM 기반 검증 환경이나 클래스 상속 구조를 사용할 경우, 상속 계층의 최상위에 있는 Base Class와 모듈 간 신호 연결을 담당하는 Interface 파일을 모듈보다 먼저 배치합니다. UVM 2.0에서는 uvm_pkg의 선행 컴파일이 필수이며, 이는 Xcelium의 -uvm 옵션으로 자동 처리할 수 있습니다.
④ 하향식(Bottom-Up) 의존성 정렬
일반 RTL 모듈은 하위 모듈(Leaf)을 상위 모듈(Top)보다 먼저 나열하는 것이 정석입니다. 현대 시뮬레이터가 전방 참조(Forward reference)를 어느 정도 지원하지만, 패키지나 커스텀 타입이 섞인 복합 설계에서는 Bottom-Up 정렬이 컴파일 속도와 안정성 모두에서 유리합니다.
⑤ Include Guard 활용 — 중복 정의 방지
ARM IP처럼 동일 파일이 여러 번 include되는 구조에서는 중복 정의(Redefinition) 에러가 빈번합니다. 이를 방지하려면 반드시 Include Guard를 적용해야 합니다.
// example_pkg.svh
`ifndef EXAMPLE_PKG_SVH
`define EXAMPLE_PKG_SVH
package example_pkg;
// typedef, class, function 정의
endpackage
`endif
⚠️ 주의: Include Guard 없이 동일 패키지가 두 번 컴파일되면 duplicate definition 에러가 발생합니다. 특히 서드파티 IP 통합 시 가장 흔히 만나는 에러입니다.
🎯 3. 이상적인 파일 리스트 구조
위 골든 룰을 종합하면 다음과 같은 계층 구조가 완성됩니다. 실무에서 바로 적용할 수 있는 템플릿입니다.
1️⃣
Definitions — 전역 매크로, 타임스케일 정의 (.vh, .svh)
2️⃣
Interfaces — 하드웨어 인터페이스 파일
3️⃣
Packages — 데이터 타입 및 클래스 패키지 (의존성 순서)
4️⃣
Low-level RTL — 최하위 단품 모듈 (Primitives, Leaf cells)
5️⃣
Mid-level RTL — 서브 시스템, 컨트롤러
6️⃣
Top-level RTL — SoC Top, Chip Top
7️⃣
Testbench — 시나리오, 드라이버, 모니터, Scoreboard
⚙️ 4. Cadence Xcelium 실무 팁
Cadence는 파일 리스트 관리의 복잡성을 해소하기 위해 다양한 옵션을 제공합니다. 실무에서 즉시 활용 가능한 핵심 사항을 정리했습니다.
▶ -makelib / -endlib 활용
거대 IP나 공용 라이브러리를 별도의 라이브러리 단위로 컴파일하면 순서 문제를 독립된 단위 내로 격리할 수 있습니다. ARM Cortex IP나 AMBA AXI/AHB 버스 모듈 통합 시 특히 유용합니다.
▶ -uvm 옵션
Xcelium은 UVM 환경에 최적화된 내장 옵션을 제공합니다. -uvm 플래그 하나로 UVM 라이브러리의 컴파일 순서와 경로 설정이 자동 처리됩니다.
▶ 파일 확장자 명확화
.v는 Verilog, .sv는 SystemVerilog, .svh는 패키지 헤더로 구분하여 컴파일러의 문법 혼동을 방지합니다. 혼재 시 -sv 옵션으로 전체를 SystemVerilog로 강제할 수도 있습니다.
▶ -incdir 경로 설정
include 경로를 명시적으로 지정하면 파일 탐색 범위를 제한하여 컴파일 속도를 높일 수 있습니다. 프로젝트가 커질수록 -incdir을 세밀하게 관리하는 것이 필수입니다.
🔍 5. ARM IP는 왜 순서가 복잡할까?
ARM이나 Synopsys 같은 대형 벤더들은 IP를 제공할 때, 사용자가 어떤 모듈을 선택적으로 사용할지 예측할 수 없습니다. 따라서 각 컴파일 단위가 자급자족(Self-contained)할 수 있도록 설계합니다.
이로 인해 동일한 헤더 파일이 여러 곳에서 중복 include되는 구조가 만들어집니다. 이때 핵심 원칙은 다음과 같습니다.
→ 파일 리스트에 직접 모든 파일을 나열하기보다, 벤더가 제공한 스크립트나 최상위 래퍼(Wrapper)의 순서를 엄격히 준수하세요.
→ ARM의 경우 logical/ 디렉토리 아래의 filelist.f를 그대로 사용하는 것이 가장 안전합니다.
📋 6. 흔한 실수와 디버깅 체크리스트
컴파일 에러가 발생했을 때, 아래 항목을 순서대로 점검하면 대부분의 문제를 빠르게 해결할 수 있습니다.
| 에러 유형 |
원인 |
해결 방법 |
unknown type |
패키지가 사용처보다 뒤에 위치 |
패키지 파일을 f-list 상단으로 이동 |
duplicate definition |
Include Guard 누락 |
`ifndef / `define 가드 추가 |
undefined macro |
매크로 정의 파일 누락 또는 순서 문제 |
defines 파일을 최상단에 배치 |
module not found |
하위 모듈이 상위보다 뒤에 위치 |
Bottom-Up 순서로 재배치 |
syntax error (특정 파일) |
파일 확장자와 실제 문법 불일치 |
.v ↔ .sv 확장자 확인 또는 -sv 옵션 사용 |
💡 7. 실전 예시: f-list 템플릿
아래는 실제 프로젝트에서 바로 활용할 수 있는 f-list 구성 예시입니다.
// ===== 1. Global Defines =====
+define+SIMULATION
+define+AXI_DATA_WIDTH=128
-incdir ./include
./include/project_defines.svh
./include/timescale.svh
// ===== 2. Interfaces =====
./rtl/interfaces/axi_if.sv
./rtl/interfaces/apb_if.sv
// ===== 3. Packages (의존성 순서) =====
./rtl/packages/common_pkg.sv
./rtl/packages/config_pkg.sv
./rtl/packages/bus_pkg.sv
// ===== 4. Low-level RTL =====
./rtl/primitives/sync_fifo.sv
./rtl/primitives/arbiter.sv
// ===== 5. Mid-level RTL =====
./rtl/subsystem/dma_ctrl.sv
./rtl/subsystem/mem_ctrl.sv
// ===== 6. Top-level RTL =====
./rtl/soc_top.sv
// ===== 7. Testbench =====
-uvm
./tb/env/tb_pkg.sv
./tb/env/tb_top.sv
./tb/tests/basic_test.sv
✅ 핵심 정리
→ 파일 리스트의 순서만 올바르게 지켜도 컴파일 에러의 80% 이상을 예방할 수 있습니다.
→ 에러 메시지가 모호할 때는 항상 f-list 상단부터 "선언이 누락되었는지" 확인하세요.
→ 서드파티 IP 통합 시에는 벤더 제공 스크립트의 순서를 최우선으로 존중하세요.
References
→ Cadence Design Systems — Xcelium Simulation User Guide
→ IEEE Standard for SystemVerilog (1800-2017)
본 게시물에 포함된 정보는 참고용이며, 특정 도구나 기술의 사용에 대한 최종 판단은 독자의 책임입니다.
📄 Raw Data
Xcelium 시뮬레이션을 활용한 검증 환경에서 SystemVerilog 파일 리스트(File List, f-list)를 구성하는 것은 단순히 파일 경로를 나열하는 것 이상의 의미를 갖습니다. 특히 복잡한 SoC 설계나 ARM과 같은 거대 IP를 다룰 때, 파일의 나열 순서가 맞지 않아 발생하는 컴파일 에러는 디버깅이 매우 까다롭습니다. "모든 파일이 리스트에 있는데 왜 에러가 날까?"라는 의문은 대개 SystemVerilog의 **컴파일 단위(Compilation Unit)** 이해와 선언 및 참조의 순환 구조에서 기인합니다.
Cadence Xcelium의 가이드와 업계에서 통용되는 **'Golden Rule'**을 바탕으로, 에러 없는 시뮬레이션 환경 구축을 위한 파일 리스트 작성 규칙을 정리해 드립니다.
### 1. SystemVerilog의 컴파일 메커니즘 이해: 선(先) 선언, 후(後) 참조
SystemVerilog 시뮬레이터인 Xcelium(xrun)은 기본적으로 파일 리스트를 위에서 아래로 읽으며 컴파일을 진행합니다. 이 과정에서 가장 중요한 원칙은 **"참조하려는 대상은 참조하기 전에 이미 컴파일되어 있어야 한다"**는 것입니다.
예를 들어, `Module A`가 `Package P`에 정의된 `typedef`를 사용한다면, 파일 리스트에서 `Package P`는 반드시 `Module A`보다 앞선 라인에 위치해야 합니다. 만약 이 순서가 뒤바뀌면, 컴파일러는 `Module A`를 처리하는 시점에 해당 타입을 알지 못하므로 에러를 뱉게 됩니다.
### 2. 효율적인 파일 리스트 구성을 위한 5가지 골든 룰
#### ① Global Defines 및 Macros 최상단 배치
프로젝트 전체에서 공통으로 사용되는 `+define+`이나 전역 매크로 파일(`.vh`, `.svh`)을 가장 먼저 선언해야 합니다. 이는 조건부 컴파일(`ifdef`, `ifndef`)이 파일 리스트 하단의 로직에 영향을 미치기 때문입니다.
* **Tip:** 하드웨어 구성(Bit width, Memory size 등)을 결정하는 파라미터성 매크로 파일이 여기에 해당합니다.
#### ② Package 파일의 우선 배치 (Package-First)
SystemVerilog의 `package`는 클래스, 함수, 사용자 정의 타입 등을 담고 있습니다. RTL이나 Testbench 파일들이 이 패키지를 `import`하여 사용하기 때문에, 모든 패키지 파일은 일반 모듈 파일보다 먼저 리스트에 등장해야 합니다.
* **의존성 순서:** 만약 `pkg_B`가 `pkg_A`를 참조한다면, 리스트 순서는 `pkg_A` -> `pkg_B`가 되어야 합니다.
#### ③ Base Class 및 Interface 선언
UVM(Universal Verification Methodology) 환경을 사용하거나 클래스 기반 검증을 할 경우, 상속 구조의 최상위에 있는 **Base Class**와 모듈 간 신호 연결을 담당하는 **Interface** 파일을 모듈보다 먼저 나열합니다.
#### ④ 하향식(Bottom-Up) 의존성 정렬
일반 RTL 모듈의 경우, 하위 모듈(Leaf module)을 상위 모듈(Top module)보다 먼저 나열하는 것이 정석입니다. 비록 현대의 시뮬레이터들이 모듈 간의 전방 참조(Forward reference)를 어느 정도 지원하긴 하지만, 패키지나 특수한 타입이 섞여 있을 때는 하향식으로 정렬하는 것이 컴파일 속도와 안정성 면에서 유리합니다.
#### ⑤ ARM IP 등 복잡한 구조에서의 Include Guard 활용
질문자님께서 언급하신 ARM IP의 사례처럼 동일한 파일이 여러 번 include되는 이유는, 각 서브 모듈이 독립적으로 컴파일될 수 있도록 의존성을 보장하기 위함입니다. 이때 발생할 수 있는 '중복 정의(Redefinition) 에러'를 막기 위해 **Include Guard**를 반드시 사용해야 합니다.
```systemverilog
// example_pkg.svh
`ifndef EXAMPLE_PKG_SVH
`define EXAMPLE_PKG_SVH
package example_pkg;
// ... logic ...
endpackage
`endif
```
### 3. Cadence Xcelium 사용자들을 위한 실무 팁
Cadence는 파일 리스트 관리의 어려움을 해결하기 위해 몇 가지 옵션을 권장합니다. 직접 파일 리스트를 관리해야 하는 상황이라면 아래 사항을 고려하십시오.
* **`-makelib` 활용:** 거대 IP나 공용 라이브러리는 별도의 라이브러리 단위로 컴파일하여 관리하는 것이 좋습니다. 이는 순서 문제를 독립된 단위 내로 격리시켜 줍니다.
* **`-parse_only`와 `-uvm` 옵션:** Xcelium은 UVM 환경에 최적화된 옵션을 제공합니다. 파일 리스트가 복잡해질수록 표준 가이드를 따르는 것이 디버깅 로그를 명확하게 만듭니다.
* **파일 확장자의 명확화:** `.v`는 Verilog, `.sv`는 SystemVerilog로 인식하게 하여 컴파일러가 문법을 혼동하지 않게 합니다. 패키지 헤더 등은 `.svh`를 사용하여 의도를 명확히 합니다.
### 4. 왜 ARM IP는 순서가 복잡할까? (Reference 가이드의 비밀)
ARM과 같은 대형 벤더들은 IP를 제공할 때 사용자가 어떤 파일을 선택적으로 사용할지 모르기 때문에, 각 컴파일 단위가 자급자족(Self-contained)할 수 있도록 설계합니다. 그래서 동일한 헤더를 여러 곳에서 중복 include하게 됩니다. 이때 사용자는 **파일 리스트에 직접 모든 파일을 나열하기보다, 최상위 래퍼(Wrapper)나 벤더가 제공한 스크립트가 정의한 순서를 엄격히 준수**해야 합니다.
### 결론: 이상적인 파일 리스트 구조 예시
1. **Definitions:** 전역 매크로, 타임스케일 정의
2. **Interfaces:** 하드웨어 인터페이스 파일
3. **Packages:** 데이터 타입 및 클래스 정의 패키지 (의존성 순서대로)
4. **Low-level RTL:** 최하위 단품 모듈 (Primitives, Leaf cells)
5. **Mid-level RTL:** 서브 시스템, 컨트롤러
6. **Top-level RTL:** SoC Top, Chip Top
7. **Testbench:** 시나리오, 드라이버, 모니터 등 검증 컴포넌트
이 순서를 지키는 것만으로도 Xcelium 시뮬레이션의 컴파일 에러 중 80% 이상을 사전에 방지할 수 있습니다. 에러 메시지가 모호할 때는 항상 리스트의 상단에 위치한 파일부터 '선언이 누락되었는지'를 확인하는 습관이 디버깅 시간을 단축하는 핵심입니다.
---
## References
- [Cadence Design Systems - Xcelium Simulation User Guide](https://www.cadence.com/en_US/home/tools/system-design-and-verification/simulation-and-testbench-verification/xcelium-parallel-simulator.html)
- [IEEE Standard for SystemVerilog (1800-2017)](https://ieeexplore.ieee.org/document/8299595)
댓글
댓글 쓰기