feat: 加上接收控制的那个对象(standalone)

openkal-linux 和 openkal-windows 都有一个 start 对象:内核把控制交过来,它找到
参数、建立线程指针、调用程序。这里补上对应的一个,给一个交出的东西少得多的环境。

⚠️ 固件交出来的和内核交出来的不是一回事。内核启动一个**程序**:栈上有参数、有
线程指针要建、有程序头可读、栈已经在那里了。固件启动一个**镜像**:在 S 模式跳到
装载地址,a0 是 hart 号,a1 是设备树,别的没有。

于是这个文件多做一件、少做一件:
- 多:让栈存在。而 __stack_top 由**程序的链接脚本**定义,因为栈放哪里是关于镜像
  布局的陈述,而镜像是程序的。本包引用它、不定义它 —— 没有脚本就链接失败,这是
  正确的报告。
- 少:不读参数向量,因为没有人可能供给过一个。openkal.env 在这个环境的答案是
  「一个都没有」,这里传同样的答案,两边就不会互相矛盾。

__libc_start_main 弱引用,和另一个一样:直接写在 openkal 上的程序没有这个符号,
那时这个文件自己跑 init_array 再调 main。

feature 名沿用 standalone —— 它是关于**程序**的陈述,不是这个实现的精简版本;
知道是哪种安排的消费者才有资格声明它,所以由 openkal-musl 声明,本包不默认打开。

Author: speak-agent

mcpp.toml

@@ -25,6 +25,21 @@ repo        = "https://github.com/mcpplibs/openkal-opensbi"
 [dependencies]
 openkal = { git = "https://github.com/mcpplibs/openkal", branch = "feat/openkal-closure" }
 
+# ⭐ WHAT RECEIVES CONTROL, WHICH IS A STATEMENT ABOUT THE PROGRAM.
+#
+# A program that already carries a runtime has an entry object of its own and
+# must not get a second. A program that does not — one whose C library is
+# openkal-musl, or one written directly against openkal — needs something to
+# make a stack exist and call it. src/start.cpp is that something, and it is
+# compiled only when this feature says the second arrangement holds.
+#
+# It is not a smaller or faster variant of this implementation. It is the same
+# distinction openkal-linux and openkal-windows draw with the same name, and the
+# consumer that knows which arrangement holds is the one that declares it —
+# which is why openkal-musl declares it and this package does not default it on.
+[features]
+standalone = { defines = ["OPENKAL_OPENSBI_STANDALONE"] }
+
 [build]
 # The same reasoning openkal's other implementations record: no exception may
 # propagate out of a C entry point, and beneath a supervisor there is no

src/start.cpp

@@ -0,0 +1,104 @@
+// Program startup, for a program that carries no runtime of its own.
+//
+// The same object openkal-linux supplies, for an environment that supplies far
+// less. It belongs to the implementation for the same reason: every step is a
+// fact about what hands control over, and a consumer that contained these steps
+// would contain a copy of them per environment.
+//
+// ⚠️ WHAT FIRMWARE HANDS OVER, AND WHAT IT DOES NOT.
+//
+// A kernel starts a program with arguments on the stack, a thread pointer to
+// establish, program headers to report, and a stack already there. Firmware
+// starts an IMAGE: it jumps to the load address in supervisor mode with a hart
+// identifier in a0 and a device tree in a1, and nothing else. There is no
+// argument vector to find, because there is no one to have supplied one; and
+// there is no stack, because a stack is a region of the image's own memory and
+// only the image knows where it put one.
+//
+// So this file does two things the other does not have to: it makes the stack
+// exist, and it stops. And it does not do the thing the other spends most of
+// its length on, because there is nothing to read.
+//
+// ⚠️ THE STACK COMES FROM THE PROGRAM'S LINKER SCRIPT AND CANNOT COME FROM HERE.
+//
+// `__stack_top' is defined by the linker script the program supplies, because
+// where the stack goes is a statement about the image's layout and the image is
+// the program's. This package names the symbol and does not define it; a
+// program that links this object without a script that defines it is told so by
+// the linker, which is the right report.
+//
+// Control is handed on through `__libc_start_main', weakly, exactly as the
+// other does: a program written directly against openkal has no such symbol,
+// and then this file runs the initialisers and calls `main' itself.
+#ifdef OPENKAL_OPENSBI_STANDALONE
+
+#include <openkal/abort.h>
+
+extern "C" {
+
+int main(int, char**, char**);
+
+[[gnu::weak]] int __libc_start_main(int (*)(int, char**, char**), int, char**,
+                                    void (*)(), void (*)(), void (*)());
+
+[[noreturn]] void __okb_start_c(void);
+
+}
+
+namespace {
+
+using initialiser = void (*)(int, char**, char**);
+
+[[gnu::weak]] extern initialiser __preinit_array_start[];
+[[gnu::weak]] extern initialiser __preinit_array_end[];
+[[gnu::weak]] extern initialiser __init_array_start[];
+[[gnu::weak]] extern initialiser __init_array_end[];
+
+void run_initialisers() {
+    // ⚠️ Only when no C library took the hand-over. One that did runs these
+    // itself, and running them twice constructs every static object twice.
+    static char* nothing = nullptr;
+    for (initialiser* p = __preinit_array_start; p != __preinit_array_end; ++p)
+        (*p)(0, &nothing, &nothing);
+    for (initialiser* p = __init_array_start; p != __init_array_end; ++p)
+        (*p)(0, &nothing, &nothing);
+}
+
+}  // namespace
+
+// The stack, then C. `la` of a linker-defined symbol resolves at link time, so
+// the sequence needs nothing to have been set up before it runs --- which is
+// the situation it is in.
+//
+// ⚠️ In `.text.entry` rather than `.text`, because the linker script places
+// that section first. Firmware jumps to the load address, not to `_start`: the
+// entry recorded in the image header is not read by firmware that loads a raw
+// image, so the first instruction at the load address has to BE this one.
+asm(".section .text.entry\n"
+    ".globl _start\n"
+    ".type _start,@function\n"
+    "_start:\n"
+    "  la sp, __stack_top\n"
+    "  call __okb_start_c\n"
+    "1: j 1b\n"
+    ".size _start,.-_start\n");
+
+extern "C" [[noreturn]] void __okb_start_c(void) {
+    // Zero and null rather than a vector: openkal.env is what a program above
+    // this reads its arguments through, and this environment's answer there is
+    // that there are none. Passing the same answer here keeps the two from
+    // disagreeing.
+    static char* nothing = nullptr;
+
+    if (__libc_start_main != nullptr) {
+        __libc_start_main(main, 0, &nothing, nullptr, nullptr, nullptr);
+        // A C library's hand-over does not return. Reaching here means one did,
+        // and continuing would run the program a second time.
+        kal_exit(127);
+    }
+
+    run_initialisers();
+    kal_exit(main(0, &nothing, &nothing));
+}
+
+#endif  // OPENKAL_OPENSBI_STANDALONE