Skip to content

Commit 01a676f

Browse files
committed
docs: README 说明 board.ld 与裸机 conformance —— 第二轮 review 的发现
⚠️ 一个现在向每个使用者供给内存布局的包,而它的 README 一个字都没提。 新增一节说明:board.ld 陈述固件把控制权交到哪里、C++ 程序需要布局包含什么、镜像 预留多少栈和堆,并经本包的构建程序到达使用者的链接线 —— 与 kal_* 定义到达使用者 对象的方式相同。程序因此什么都不用陈述。 ⚠️ 并写明「程序自己也陈述一份会陈述两遍」:这个事实可传递地到达使用者,两份链接 脚本都会被应用,失败形式是输出段重叠,而诊断一个字都没提有两份。 ⚠️ 尺寸是宽裕而非最小,这是文件里唯一的判断,连同理由一起写明。 「Verified」一节补上:conformance 套件在同一段固件下、core 集上跑过,12 条成立、 0 条不成立。
1 parent d7e323d commit 01a676f

1 file changed

Lines changed: 37 additions & 2 deletions

File tree

README.md

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,36 @@ The region is 64 KiB by default. A project that needs another figure overrides
7676
allocation pattern needs reuse should place a real allocator above this one;
7777
that is policy, and openkal carries mechanism.
7878

79+
## The memory map is this package's, because it is a fact about this machine
80+
81+
`board.ld` states where the firmware hands control over (`0x80200000`, since
82+
OpenSBI itself occupies the start of RAM), what the layout has to contain for a
83+
C++ program to work — the initialiser arrays, the unwind tables and their bounds,
84+
the thread-local segment — and how much stack and heap the image reserves. It
85+
reaches a consumer's link line through this package's build program, in the same
86+
way its `kal_*` definitions reach the consumer's objects.
87+
88+
A program therefore states nothing. Until 2026-08-23 every program that wanted to
89+
run here carried a copy: `examples/hello` had one, the C++ runtime's
90+
`same-source` example had a second, and the specification's conformance suite
91+
would have needed a third. None of those is a property of a program.
92+
93+
⚠️ **A program that states one as well states it twice.** The fact reaches
94+
consumers transitively, and two linker scripts are both applied — which fails as
95+
overlapping output sections and says nothing about there being two:
96+
97+
```
98+
ld.lld: error: section .eh_frame file range overlaps with .debug_str_offsets
99+
```
100+
101+
The sizes — 256 KiB of stack, 16 MiB of heap — are generous rather than minimal,
102+
and that is the one judgement in the file. A C program printing a string needs
103+
neither; a program carrying a C library and a C++ standard library does, and it
104+
exhausts smaller figures during its own initialisation, before `main`, so what it
105+
looks like is a program that starts and prints nothing. Both regions lie past the
106+
end of the image and cost nothing in it. A board with far less memory states its
107+
own map instead of taking this one.
108+
79109
## Two details that were measured rather than assumed
80110

81111
**DBCN is probed, not assumed.** The Debug Console extension arrived in SBI
@@ -99,7 +129,12 @@ heap ok
99129
```
100130

101131
The image carries no C library (`[target.<triple>].sysroot = ""`) and no board
102-
package. It is loaded at `0x80200000`, because OpenSBI itself occupies the start
103-
of RAM.
132+
package, and it states no memory map of its own: `board.ld` above is this
133+
package's.
134+
135+
The specification's conformance suite also runs here, under the same firmware,
136+
selected to the `core` set — twelve observations held, none failed. Clause 9
137+
makes the behavioural half a property of every implementation, and an
138+
implementation of a machine with no operating system is not exempt from it.
104139

105140
[kal]: https://github.com/mcpplibs/openkal

0 commit comments

Comments
 (0)