← 에세이 /Post · 26 of 27 · Methods

LLM에 하드웨어 문서 주입: grep으로 돌아온 이유

RAG는 하드웨어 문서를 쓸모 있게 만드는 교차 참조를 끊어 놓았다. 파이프라인을 붙들고 있다가, SVD와 PDF를 파일 도구로 LLM에게 직접 건네는 쪽으로 돌아왔다.

·6 min read · · · #rag#ai-agents#embedded-systems#stm32#datasheets
LLM에 하드웨어 문서 주입: grep으로 돌아온 이유
On this page

Claude에게 STM32F407의 USART2를 9600bps로 설정해 달라고 했다. 코드는 문제없이 컴파일됐다. 그런데 시리얼 터미널에는 알아볼 수 없는 글자만 찍혔다.

문제는 검색이었다. USART 보레이트 공식은 주변 장치 클록 주파수를 가져다 쓰는데, 그 값은 USART 레지스터와 한참 떨어진 다른 챕터에 적혀 있다. RAG 파이프라인은 한쪽 챕터만 가져오고 다른 쪽을 놓쳤다. 비어 있는 자리는 LLM이 클록 주파수를 지어내서 채웠다.

나는 RM0090 하나를 다루려고 RAG 시스템을 2주 동안 붙들고 있었다. Docling으로 PDF를 파싱하고, ChromaDB로 하이브리드 검색을 짜고, 그 위에 라우팅 레이어까지 얹었다. 그러다 조금 허탈하게 깨달았다. LLM에게 파일 경로만 알려 주고 grep을 시키면 되는 일이었다.

grep이 이기는 자리, RAG가 이기는 자리

하드웨어 문서에 RAG를 쓰지 않는 편이 낫다는 것은 “RAG는 나쁘다”보다 훨씬 좁은 이야기다.

상황쓸 것
문서 몇 개, 클라우드 LLM, 넉넉한 컨텍스트grep과 read를 파일 도구로
망 분리 환경이거나 컨텍스트가 좁은 로컬 모델문서 구조에 맞춰 다시 짠 검색
데이터시트 수십 개, “어느 MCU가 X를 지원하나” 류 질의인덱스. 꼭 RAG일 필요는 없다

첫 줄이 대부분의 펌웨어 작업이고, 이 글은 그 경우를 다룬다. 둘째 줄은 나중에 망 분리된 공장 네트워크에서 내가 실제로 부딪힌 제약이다. 거기서는 검색 파이프라인을 데이터시트에 맞게 다시 짜야 했다. 둘을 가르는 것은 페이지를 모델 앞에 올려놓을 수 있느냐였다.

RAG가 하드웨어 문서에서 깨지는 이유

RAG 연구는 대부분 처음부터 다른 종류의 문서로 시험한다. LaRA(2025년 2월, 2,326개 테스트 케이스)가 다룬 것은 소설, 학술 논문, 재무제표다. Self-Route(2024년 7월)는 NLP 논문과 여러 분야의 문서, 다중 홉 QA 벤치마크를 썼다. Databricks 연구는 제품 문서와 금융, 일반 QA 데이터셋으로 2,000개 실험을 돌렸다. 하드웨어 문서로 시험한 연구는 하나도 없었다. 그런데 하드웨어 문서에서는 실패하는 방식이 구조부터 다르다.

청킹은 교차 참조를 끊어 놓는다. RM0090 Section 30.3.4에 보레이트 공식이 있다. 그런데 이 공식에 필요한 클록 주파수는 수백 페이지 떨어진 Section 7.2에 따로 있다. 일반적인 RAG는 청크를 하나하나 따로 검색한다. Late Chunking 논문(2024년 9월)이 바로 이 문제를 짚었다. 앞 문맥에 기대는 구절은 청크로 잘리고 나면 임베딩 품질이 크게 떨어진다. 하드웨어 문서에서 “이 레지스터”가 3챕터 앞의 정의를 가리키는 일은 흔하다.

임베딩 모델은 레지스터 테이블을 인덱싱하지 못한다. RCC_CFGR[SWS]: bits 3:2, read-only 같은 설명은 15 토큰 안에 아주 많은 뜻을 담고 있다. 자연어로 학습한 임베딩 모델은 이런 항목에 낮은 유사도를 준다. “MCU가 어떤 클록 소스를 쓰지?”라고 물어도 코사인 유사도로는 SWS 필드가 걸리지 않는다.

비트 위치가 틀리면 “얼추 맞다” 같은 건 없다. bit 12가 와야 할 자리에 bit 13을 돌려주면 코드는 엉뚱한 레지스터 필드에 값을 쓰고, 주변 장치는 그냥 움직이지 않는다. RespCode(2026)는 LLM 4개로 이 현상을 기록했다. Gemini는 LPC55S69의 SYSCON_BASE를 0x50000000이라고 지어냈다(정답은 0x40000000). 4개 중 3개 모델은 CTIMER2 클록 활성화 비트를 틀렸다. 넷 모두 arm-none-eabi-gcc로 아무 문제 없이 컴파일됐다. 그리고 실제 하드웨어에서는 하나도 돌지 않았다.

LlamaIndex 벤치마크는 이 격차를 대놓고 측정했다. 작은 연구 논문 묶음(문서 5개, 22에서 52페이지)에서 파일시스템 에이전트(grep + read)는 정확도 8.4/10을 받았고, RAG는 6.4/10에 머물렀다. 그들의 설명으로는, RAG는 청킹과 최적이 아닌 검색 호출 때문에 컨텍스트를 잃고, 그래서 최종 답을 만드는 LLM이 제한적이고 때로는 부정확한 컨텍스트만 보게 된다.

하드웨어 문서에서는 이 모든 문제가 더 나빠진다. 정보는 더 빽빽하고, 교차 참조가 문서의 구조를 떠받치고 있고, 오류를 받아 줄 여유는 0이다.

USART 보레이트 버그

나는 168MHz STM32F407에서 USART2를 9600bps, 8N1, RX 인터럽트로 설정해 달라고 했다. RAG는 RM0090 Section 30.3.4에서 USARTDIV 공식이 붙은 보레이트 레지스터 설명을 가져왔다. 그러나 Section 7.2에 있는 RCC 설정은 놓쳤다. USART2가 APB1에 걸려 있고 SYSCLK/4 = 42MHz라는 내용이다. LLM은 공식에서 f_CK를 보기는 했지만, USART2의 f_CK가 얼마인지 알려 주는 청크가 없었다. 그래서 짐작으로 채웠다.

// What RAG generated (WRONG - assumes f_CK = 168MHz)
USART2->BRR = 168000000 / 9600;  // BRR = 17500

// Correct (f_CK = 42MHz for APB1 peripherals)
USART2->BRR = 42000000 / 9600;   // BRR = 4375
// Simplified formula for 16x oversampling (OVER8=0, default).
// Full: Baud = f_CK / (8 * (2 - OVER8) * USARTDIV). RM0090 Section 30.3.4.

컴파일된다. 실행도 된다. 그런데 9600bps로 연결하면 알아볼 수 없는 글자가 쏟아진다. 코드가 멀쩡해 보이기 때문에 몇 시간씩 잡아먹는 종류의 버그다.

청크 크기를 아무리 바꿔도 이 버그는 고쳐지지 않는다. 보레이트 공식과 클록 트리가 서로 다른 챕터에 흩어져 있기 때문이다. 코사인 유사도로는 “USART 보레이트”와 “RCC APB1 프리스케일러”를 함께 가져올 수 없다. 두 글은 뜻으로 보면 서로 아무 관계가 없어 보인다. 나는 이것을 구조의 문제로 본다.

RAG 대신 파일 접근

내가 도달한 답은 LLM이 문서 파일을 직접 열어 볼 수 있게 해 두고, 필요할 때 스스로 찾게 두는 것이었다.

도구 기반 MCU 문서 접근 아키텍처: 프로젝트 파일과 로컬 문서(SVD, PDF)가 도구 호출(grep, read)을 통해 LLM 에이전트에 연결되어 검증된 레지스터 코드를 생성

아키텍처: 에이전트가 사전 청킹된 임베딩을 검색하는 대신 SVD와 PDF 파일을 필요할 때 grep한다.

펌웨어 엔지니어에게 필요한 것은 대개 파일 두 개로 거의 다 채워진다.

SVD(System View Description)는 ARM Cortex-M 실리콘 벤더라면 어디나 내놓는 XML 파일이다. 특정 MCU의 주변 장치 레지스터, 베이스 주소, 비트 필드, 리셋 값, 열거형 값이 모두 들어 있다. STM32F407 SVD 하나만 해도 58개 주변 장치에 걸쳐 레지스터 정의가 1,000개를 넘는다. cmsis-svd-data 저장소에 여러 벤더의 SVD가 모여 있다. RespCode는 SVD 파일 2,177개를 파싱했는데, SVD를 넣어 주자 테스트한 필드에서 LLM의 레지스터 값 정확도가 약 25% 기준선에서 100%로 올라갔다.

다른 하나는 PDF 레퍼런스 매뉴얼이다. STM32F407용 RM0090은 1,700페이지가 넘는다. 클록 트리부터 주변 장치 동작, 타이밍 다이어그램, 초기화 순서, 전기적 특성까지 담겨 있다. 절차에 관한 지식은 모두 여기 있다. DMA를 어떻게 세우는지, 프리스케일러를 건드리면 무엇이 깨지는지, 어떤 GPIO 대체 기능이 어떤 주변 장치로 이어지는지.

이 파일들을 통째로 컨텍스트 윈도우에 넣을 필요는 없다. 필요한 것은 도구 접근이다. grep으로 찾고 read로 필요한 섹션만 읽으면 된다. Claude Code(임베디드 리눅스 워크플로우는 임베디드 리눅스 AI 에이전트 포스트에서 다뤘다)나 Cursor 같은 도구에는 이 기능이 이미 들어 있다. 파일이 어디 있는지만 알려 주면 된다.

도구 접근이 전체 컨텍스트보다 나은 이유

레퍼런스 매뉴얼 전체를 컨텍스트 윈도우에 넣는 방법도 있기는 하다. 다만 비용이 너무 크다. RM0090은 약 1.5M 토큰이다. Gemini 2.5 Pro 가격(장문 컨텍스트 $2.50/M 입력 토큰)으로 계산하면 쿼리 한 번에 약 $3.75가 든다. Gemini 2.5 Flash-Lite($0.10/M)로 낮춰도 쿼리당 $0.15이고, O(n^2) 어텐션 계산 때문에 30초에서 60초를 기다려야 한다.

도구 기반 접근은 필요한 만큼만 읽는다. 보통 쿼리 하나에 SVD 데이터와 PDF 섹션에서 20에서 50K 토큰쯤을 쓴다. 쿼리당 토큰이 30배에서 75배 적다. 거대한 컨텍스트 하나를 한꺼번에 넘기는 대신 LLM이 작은 읽기를 여러 번 하고, 무엇을 읽을지는 LLM이 그때그때 정한다.

아래 표는 Claude Sonnet 4.6 가격($3/M 입력, 2026년 3월 기준)으로 맞춰 비교한 것이다. 실제로 전체 컨텍스트를 올리려면 Gemini의 1M에서 2M 컨텍스트 윈도우가 있어야 한다.

접근법쿼리당 토큰추정 비용레이턴시정확도
RAG (청킹)약 3K약 $0.011에서 2초주변 장치 간 낮음
전체 컨텍스트약 1,500K약 $4.5030에서 60초높지만 비쌈
도구 접근 (grep+read)약 20K에서 50K약 $0.06에서 0.1510에서 20초높음

비용 추정치는 공개된 API 가격과 대략의 토큰 수로 잡았다. 도구 접근 수치는 쿼리 하나에 read/grep을 3회에서 5회 돈다고 가정한 값이다.

LlamaIndex 벤치마크도 같은 쪽을 가리킨다. 작은 문서에서는 에이전트가 파일을 직접 찾는 방식이 RAG보다 정확도에서 2점 앞섰다(8.4 vs 6.4). 연구 논문으로 낸 수치라 하드웨어 문서는 아니다. 그래도 방향은 같고, 교차 참조가 촘촘한 하드웨어 문서라면 격차는 더 벌어질 거라고 나는 생각한다.

에이전트가 보레이트 버그를 해결하는 방법

도구 접근이 있으면 같은 USART2 질문이 전혀 다르게 풀린다. 에이전트는 SVD에서 USART2와 BRR을 grep한다.

<!-- grep result from STM32F407.svd -->
<peripheral>
  <name>USART2</name>
  <baseAddress>0x40004400</baseAddress>
  ...
  <register>
    <name>BRR</name>
    <addressOffset>0x08</addressOffset>
    <size>0x20</size>
    <fields>
      <field><name>DIV_Mantissa</name><bitOffset>4</bitOffset><bitWidth>12</bitWidth></field>
      <field><name>DIV_Fraction</name><bitOffset>0</bitOffset><bitWidth>4</bitWidth></field>
    </fields>
  </register>
</peripheral>

이것으로 정확한 레지스터 주소와 필드 배치가 손에 들어온다. 에이전트는 PDF의 USART 보레이트 섹션을 읽고 공식에서 f_CK를 본다. 여기서 짐작하지 않는다. PDF에서 “APB1”과 “USART2”를 grep해서 Section 7.2의 APB1 = SYSCLK/4 = 42MHz를 찾아낸다. 도구 호출 3번으로 정답에 닿는다.

RAG는 이렇게 하지 못한다. 코사인 유사도는 교차 참조를 따라가지 못한다. 에이전트는 방금 찾은 것을 근거로 다음에 무엇을 찾을지 판단하기 때문에, 그 참조를 끝까지 따라간다.

설정 방법

기본 설정

cmsis-svd-data에서 쓰는 MCU의 SVD 파일을 내려받고, 레퍼런스 매뉴얼 PDF는 벤더 사이트에서 받는다. 둘 다 프로젝트의 docs/ 폴더에 넣는다. 그리고 CLAUDE.md(또는 그에 해당하는 프로젝트 컨텍스트 파일)에 이렇게 적어 둔다.

## Hardware Reference
- Target: STM32F407VG (Cortex-M4, 168MHz)
- SVD: docs/STM32F407.svd (register definitions, bit fields, addresses)
- Reference Manual: docs/RM0090.pdf (peripheral behavior, clock tree, init sequences)
- Datasheet: docs/DS8626.pdf (pinout, electrical characteristics, absolute max ratings)

When writing register-level code, always grep the SVD file for exact
register addresses and bit field definitions. Do not guess register values.
For clock configuration, read RM0090 Section 7 (RCC).

설정은 이것으로 끝이다. 에이전트는 내가 PDF 뷰어에 띄워 놓고 보던 바로 그 문서를 읽는다. 다른 점은 프로그램으로 검색까지 한다는 것뿐이다.

에이전트가 여전히 틀리는 것

STM32, ESP32, nRF52처럼 널리 쓰이는 MCU라면 LLM은 학습 데이터에서 관련 문서를 이미 거의 다 보았다. 문서를 주지 않아도 레지스터 설정을 맞히는 일이 흔하다. 이럴 때 SVD 파일은 주된 출처라기보다 확인용에 가깝다.

문서 접근이 정말 결과를 가르는 경우는 따로 있다. LLM이 본 적 없는 잘 알려지지 않은 MCU, 레지스터 배치가 크게 바뀐 최신 실리콘 리비전, 벤더마다 다른 에라타. 이런 경우라면 RAG도 결국 문서를 받아들여야 한다. 도구 접근은 전처리 파이프라인 없이 그대로 처리한다.

다루지 않는 것

대규모 다중 문서 검색은 다루지 않는다. 데이터시트 50개를 펼쳐 놓고 “메시지 버퍼가 64개 넘는 CAN-FD 주변 장치를 가진 MCU가 뭐냐”고 물으면 도구 기반 grep은 확실히 느려진다. 이럴 때는 가벼운 인덱스(꼭 RAG일 필요는 없다)가 도움이 된다. 다만 이것은 MCU를 고르는 질문이다. 펌웨어를 개발하는 일과는 다른 문제다.

다이어그램과 회로도는 도구 기반 PDF 접근이 생각보다 잘 해낸다. Claude와 Gemini가 PDF 페이지를 이미지로 처리하기 때문이다. 그래서 에이전트는 특정 페이지를 읽고 블록 다이어그램이나 클록 트리 그림, 핀 배치 테이블을 눈으로 보듯 읽어 낸다. 도구를 쓰는 방식은 똑같다. PDF에서 “Figure 23”을 grep하고, 그 페이지를 읽고, 필요한 정보를 뽑는다.

타이밍 다이어그램은 사정이 다르다. 범용 VLM은 여러 신호가 겹친 파형을 읽는 데 아직 서툴다. TD-Interpreter(2025년 7월)처럼 타이밍 다이어그램만을 위해 파인튜닝한 모델이 따로 나올 정도다. setup/hold 시간이나 프로토콜 타이밍은 지금도 데이터시트에서 숫자를 직접 읽는 수밖에 없다.

검증도 이 글의 범위 밖이다. 올바른 문서를 넣어 준다고 올바른 코드가 나오지는 않는다. RespCode처럼 생성이 끝난 뒤 SVD 데이터베이스와 대조해 검증하면, 완벽한 컨텍스트에서도 LLM이 저지르는 오류를 잡을 수 있다. 이것은 검색과는 다른 문제다.

RAG를 건너뛰고 파일을 쓴다

그렇게 돌아서 내가 다시 서게 된 곳은 가장 단순한 방법이었다. SVD와 PDF 파일을 프로젝트에 넣고, LLM에게 위치만 알려 준 다음, grep하게 둔다. 임베딩 파이프라인은 필요 없었다. 파일이 곧 ground truth다. 에이전트에게는 그 파일을 읽으라고 하면 된다.

ecro
글쓴이 ecro

LLM 펌웨어 벤치마크를 만들었습니다. EmbedEval →

프로젝트에 맞는 Claude Code / Cursor / Codex 하네스를 생성하는 도구를 만듭니다. harness-maker →

에이전트와 같은 보드를 함께 다루는 시리얼, SSH 터미널을 만들고 있습니다. NeuroTerm →

댓글

댓글 불러오는 중...