KLayout 读取 GDS/OASIS 失败:截断 EOF 与 unknown format 的分流排查
更新时间:2026-11-20。报错排查篇,属于 EDA 报错排查系列。批处理脚本里一句
layout.read(path)抛出RuntimeError,背后可能是两种完全不同的故障:文件本身残缺,或者文件内容根本不是版图流格式。本篇用同一个最小 GDS2 文件做对照——健康读取退出码 0,切尾之后报Unexpected end-of-file,纯文本改名后报Stream has unknown format,再用一次 OASIS 往返证明格式转换链路本身可靠。更多开源工具的报错定位入口见 开源 EDA 报错导航。
首屏答案:KLayout 读取 GDS 失败先按报错文本分流。Unexpected end-of-file 属于文件完整性问题——解析器期待下一条记录时碰到文件结尾,查传输截断、写盘不完整和磁盘空间;Stream has unknown format 属于格式识别问题——特征字节对不上任何已知流格式,查文件伪装与压缩 OASIS。修完用一次 GDS→OASIS 写出再回读做闭环,几何数量一致才算好。
先用一张分诊漏斗把排查路径收窄:读取失败不需要急着开 GUI 翻版图,第一步永远是把报错归到「完整性」或「格式识别」其中一条线。
读这张漏斗抓住一个判据:报错文本决定排查方向。带 end-of-file 是解析走到一半没东西可读,带 unknown format 是刚打开文件就认不出格式;前者已进入逐条记录解析,后者卡在格式嗅探阶段,排查清单不必两条线都跑。
本文要回答的问题
Unexpected end-of-file (position=66, record number=4, cell=)括号里的三个字段各是什么意思,为什么能据此判定文件被截断?Stream has unknown format是扩展名错了还是文件内容错了,KLayout 靠什么识别流格式?- 为什么
klayout -r read_gds.rb demo.gds在脚本里拿不到文件名,环境变量INPUT传路径为什么就好使? - layer/datatype 冲突、压缩 OASIS 不识别这两类同族问题,为什么通常不会以读取异常的形式暴露?
- 修完之后用什么命令序列自证,退出码和几何计数分别要看哪一行?
一、报错原文:KLayout 读取流文件时的两份失败判决
实验先用 KLayout 自带的 RBA(Ruby API,KLayout 的脚本接口)生成一个最小合法 GDS2:一个名为 TOP 的单元,layer 1/datatype 0 上一个 1000×2000 纳米的矩形,数据库单位 dbu=0.001 微米,文件只有 170 字节。随后制造两个坏样本:head -c 80 切掉健康文件的尾部得到截断版;把一行纯文本写进 fake.gds 得到伪装版。三份文件依次交给同一个读取脚本:
先读截断案的 Unexpected end-of-file (position=66, record number=4, cell=)。GDS2 流由带定长头部的二进制记录串联,合法文件必须以 ENDLIB 记录收尾;切尾把结尾记录连同 ENDLIB 一起抹掉,解析器读完前 66 个字节、正要解析第 4 条记录时碰到文件结尾。cell= 为空佐证失败位置很早——解析还停在文件头区域,尚未进入任何单元(cell)上下文。
再读伪装案的 Stream has unknown format: fake.gds。Layout::read 并不信任扩展名,而是拿文件头特征字节与 GDS2、OASIS 等已知签名比对;纯文本没有合法签名,嗅探直接失败。两行栈都指向 read_gds.rb:10:in 'read'——同一个 layout.read(path) 调用、两种病因,这正是要分流的原因。商用工具的同族表现见 Calibre 截断流文件报错。
二、谁在判错:KLayout 批处理、RBA 与流文件格式三层角色
这条报错链路涉及三层,职责分清才不会把修法使错地方:
| 层 | 组件与版本 | 在本次读取里的角色 |
|---|---|---|
| 脚本宿主 | KLayout 0.28.16 批处理模式(-b -r) | 无头执行 Ruby 脚本,提供 RBA 接口,解析失败时进程退出码置 1 |
| 编程接口 | RBA:RBA::Layout 的 read/write | 统一入口,内部按特征字节分流到 GDS2/OASIS 等具体 reader |
| 数据对象 | GDS2 二进制流 / OASIS 流(本次 demo.oas) | 记录式版图格式,几何按 layer 与 datatype 编址,详见 GDS 与 OASIS 格式差异 |
关键认知:KLayout 按文件内容而不是扩展名分流 reader。OASIS 内容改名成 .gds 仍可能正确读入,纯文本即使叫 .gds 也照样被判 unknown format。排查格式问题时,file <文件名> 看真实类型比 ls 看扩展名有用。
另一个必须先排除的环境坑是脚本传参。KLayout 启动器会自行消费位置参数里的 .gds(默认装进图形界面的文档视图),不原样传进 Ruby 的 ARGV,脚本里 ARGV[0] 拿到的是 nil。读取脚本改用环境变量传路径绕开吞参:
# read_gds.rb:路径走 INPUT 环境变量,而不是 Ruby ARGV
path = ENV["INPUT"] || raise("usage: INPUT=<stream-file> klayout -b -r read_gds.rb")
layout = RBA::Layout.new
layout.read(path)
top = layout.top_cell || raise("no top cell in #{path}")
li = layout.layer(RBA::LayerInfo.new(1, 0))
count = li >= 0 ? top.shapes(li).size : 0
puts "READ OK #{path} top=#{top.name} boxes_on_L1D0=#{count}"调用形态因此固定为 INPUT=demo.gds klayout -b -r read_gds.rb。脚本还顺手做了第二件事:读出 TOP 单元后统计 layer 1/datatype 0 上的图形数,给后续修复验证留一个可比较的量化锚点。
三、根因拆解:记录流截断、特征字节嗅探与两个同族变种
把五组实验的机理摊开,核心是两个解析阶段、外加两个容易混淆的同族问题。
截断案的机理是记录流失去闭合。 GDS2 每条记录以 2 字节头部标注长度与类型,reader 按长度逐条前进,健康文件靠 ENDLIB 告知正常结束。head -c 80 之后文件在记录中间断掉,reader 前进到 position=66 再取头部时读到 0 字节,EOF 异常因此带位置和记录序号。工程上先怀疑三处:传输或 rsync 中断、生成进程被信号杀死没写完、磁盘空间不足丢了尾部。校验靠比对文件大小与校验和,不要反复重读坏文件。
伪装案的机理是格式签名对不上。 嗅探发生在读取最早期,第一条几何记录都还没解析,所以报错里没有 position、record number 这类上下文,只有文件名。真实工程里还有两个来源:压缩形态的 OASIS——写出端启用了读取端不支持的压缩方案时,识别或解压阶段失败;流水线里上游误把日志、报告写成 .gds 后缀。修法都是回到写出端确认格式与压缩选项,让上游重写一份不压缩的流文件。
layer/datatype 冲突是另一个家族。 GDS 几何靠(layer,datatype)二元组编址,两套工艺层表把不同语义的几何写进同一编号时,读出本身通常成功——read 不报错、退出码也是 0——毛病出在归层解释上,图形跑到错误网层或被错误合并。这类问题靠层映射表在读写两端对齐,见 GDS layer 与 datatype 映射。分界记住:读取抛异常查完整性与格式,读取成功但归层错查 layer/datatype。
四、排查清单:按报错文本对号入座的六个动作
把分流结论落成一份可照做的清单,顺序就是漏斗从宽到窄的顺序:
| 步骤 | 动作 | 判据与预期 |
|---|---|---|
| 1 | 原样读一遍报错文本 | 含 end-of-file 走完整性线,含 unknown format 走格式线 |
| 2 | 确认脚本传参 | 批处理脚本用 INPUT=<file> klayout -b -r,不要依赖位置参数进 ARGV |
| 3 | 完整性线:核对文件大小 | 与上游清单或同批文件比大小,明显偏小即截断;重传后比对校验和 |
| 4 | 格式线:查真实文件类型 | 用 file 看特征字节,排除文本伪装、误写后缀与压缩 OASIS |
| 5 | 隔离变量 | 用一份已知健康的最小 GDS2 跑同一读取脚本,确认工具链本身无损 |
| 6 | 闭环验证 | GDS→OASIS 写出再回读,比对单元名与图形计数,退出码全 0 |
第三步和第四步不要互换。截断文件的文件头往往完好,格式嗅探仍能认出 GDS 签名,会把人误导到格式线;伪装文件则根本没有完整性可言。先用报错文本定线再取证,是这份清单省时间的关键。
五、修复与复跑:健康基线与 OASIS 往返两个通过态
修复的前提是有一条可信的健康基线。同一份 170 字节的 demo.gds 未经破坏时,读取脚本输出一行摘要并以退出码 0 收工:
===== 2. healthy GDS read (reference) =====
READ OK demo.gds top=TOP boxes_on_L1D0=1
CASE_EXIT healthy=0这行 READ OK 有三个字段要会读:top=TOP 是顶层单元名与生成脚本一致,boxes_on_L1D0=1 是 layer 1/datatype 0 上数到一个矩形,与写入数量对得上,退出码 0 说明全程无异常。任何修复之后都回到这一行做基线对比。
截断案的修复是重新获取完整文件,伪装案是回上游取真正的流文件;文件救不活而手里还有同设计的健康流时,格式转换是另一条出路。本次用 to_oasis.rb 把健康 GDS2 写成 OASIS 再立刻回读,验证转换不丢几何:
过关信号是两行输出配一个退出码:OASIS WROTE demo.oas 确认写出成功,OASIS READ OK top=TOP boxes_on_L1D0=1 确认回读后单元名与图形计数和 GDS 基线一致,CASE_EXIT oasis=0 收尾。几何数量转换前后守恒,说明问题出在坏文件而不是工具链,分流排查到此闭环。
实验环境
- 机器/系统:Docker 容器
geek-eda:0.5-asic(Ubuntu 24.04),无头批处理模式运行 KLayout - 工具版本:KLayout 0.28.16(版本照抄 log 头部
TOOL_VERSION行) - 日期:2026-11-20
- 完整命令:
klayout -b -r make_gds.rb(生成健康 GDS2,170 字节);INPUT=demo.gds klayout -b -r read_gds.rb(健康基线,退出码 0);head -c 80 demo.gds > demo_truncated.gds后INPUT=demo_truncated.gds klayout -b -r read_gds.rb(截断案,退出码 1);echo 'this is not a gds file' > fake.gds后INPUT=fake.gds klayout -b -r read_gds.rb(伪装案,退出码 1);klayout -b -r to_oasis.rb(OASIS 往返,退出码 0)
代码获取
复现用的三个 Ruby 脚本(make_gds.rb / read_gds.rb / to_oasis.rb)与五组 case 的编排脚本 run.sh 在公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/klayout-gds-read-fail。按目录内 README 执行 docker run --rm -v "$PWD":/work -w /work geek-eda:0.5-asic bash -lc 'bash run.sh',即可依次重现健康读取、截断 EOF、unknown format 与 OASIS 往返的完整对照,每组 case 的退出码由脚本统一打印。
这一篇在知识体系里的位置
本篇是 EDA 报错排查系列 中「流文件读写」簇的一员,处理版图数据在工具间交接环节的失败。格式背景读 GDS 与 OASIS 格式差异,理解两种格式签名与压缩形态的不同;读出成功但归层错误转 GDS layer 与 datatype 映射;商用工具链的同族截断故障对照 Calibre 截断流文件报错,可见「完整性先于格式」的判据在不同工具上同样成立;更多入口见 开源 EDA 报错导航。
总结
KLayout 读取 GDS 失败的核心是按报错文本分流:Unexpected end-of-file 是记录流被截断、解析中途失去闭合,查传输、写盘与磁盘空间并重新获取完整文件;Stream has unknown format 是特征字节嗅探失败,查文件伪装与压缩 OASIS、回写出端重修。脚本侧记住 KLayout 会吞掉位置参数中的 .gds,批处理统一用 INPUT=<file> klayout -b -r 经环境变量传路径;layer/datatype 冲突是读出之后的归层问题,不与读取异常混谈。修复以健康基线的 READ OK 为锚,再用 GDS→OASIS 写出回读、几何计数守恒加退出码 0 完成闭环。