1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
.TH MCPU-RUN 1 "Октябрь 2026" "LibMCPU" "Команды пользователя"
.SH ИМЯ
mcpu-run \- загрузчик, runtime и supervisor исполнения MCPU
.SH СИНТАКСИС
.B mcpu-run
.RI [ runtime-options ] " -- executable " [ program-args ...]
.br
.B mcpu-run
.RI [ runtime-options ] " executable " [ program-args ...]
.SH ОПИСАНИЕ
.B mcpu-run
— loader, startup linker, execution supervisor и host-side test bench для MELF
ET_EXEC. Предпочтительна форма с явным разделителем
.BR -- .
Размеры STACK и HEAP являются частью executable ABI и не переопределяются
runner-ом.
.PP
Поддерживаются статический ABI v1, исторический explicit-preload ABI v2 и
frozen ABI v3. Discovery зависимостей, symbol selection и runtime relocation
завершаются до первой guest instruction.
.SH HLL STARTUP И LIFECYCLE
HLL PROGRAM или MODEL executable всё равно входит через обычный MELF
_start/_life/_fini lifecycle, предоставленный linked CRT. mcpu-run не вызывает
main, init, life или fini напрямую.
.PP
Перед _start loader один раз создаёт в STACK постоянную область McpuStartup v1
с version, size, argc, PTR64 argv и reserved zero field. Массив argv и строки
аргументов остаются действительными весь executable lifetime. HLL CRT проверяет
это состояние и переводит его в обычный CALL ABI.
.PP
PROGRAM выполняет HLL main один раз и завершает работу с возвращённым int32
status. MODEL выполняет INIT через init(), затем вызывает life() один раз на
каждой lifecycle iteration. INT32_MIN означает продолжение через одну LIFE END
boundary; zero — нормальное завершение; positive value — error exit status.
Остальные отрицательные результаты life зарезервированы HLL Runtime ABI v1.
.PP
Graceful HLL exit вызывает user fini(), __mcpu_fini_array() и
__mcpu_libc_fini() перед финальным FINI END. Startup failure до перехода CRT в
RUNNING пропускает эти finalizers. Diagnostic stop по --steps остаётся
supervisor stop и не синтезирует graceful HLL finalization.
.SH SYSTEM OPTIONS
.TP
.B --no-config
Не читать mcpu-ld.conf, сохраняя executable-derived default system library tree.
.TP
.BI --sys-root= ПУТЬ
Использовать ПУТЬ как MCPU root, не читать config и использовать ПУТЬ/lib.
.TP
.B --dump-config
Вывести effective configuration и завершиться.
.TP
.B --print-search-dirs
Вывести search directories и завершиться.
.SH LIBRARY OPTIONS
Эти опции должны находиться перед executable или явным --.
.TP
.BI --library-path= КАТАЛОГ[:КАТАЛОГ...]
Добавить явные каталоги поиска. Опция повторяемая; эти каталоги предшествуют
system library path.
.TP
.BI --ldpreload= a.so:b.so
Предзагрузить ABI-v2/ABI-v3 shared objects. Имя без '/' ищется по search path;
имя с '/' считается явным pathname.
.SH ОКРУЖЕНИЕ
.TP
.B MCPU_LD_PRELOAD
Colon-separated preload list, применяемый раньше command-line --ldpreload. При
равной силе определения действует rightmost priority, поэтому command-line
preload может переопределить environment preload.
.SH INSPECTION ПОСЛЕ ОСТАНОВА
.TP
.BI --int-reg= r<bits>@<addr>
Вывести signed integer register.
.TP
.BI --real-reg= r<bits>@<addr>
Вывести real register.
.TP
.BI --int-data= <bits>@<addr>
.TQ
.BI --real-data= <bits>@<addr>
.TQ
.BI --raw-data= <bytes>@<addr>
Inspection DATA.
.TP
.BI --int-control= <bits>@<addr>
.TQ
.BI --real-control= <bits>@<addr>
.TQ
.BI --raw-control= <bytes>@<addr>
Inspection CONTROL.
.TP
.BI --int-heap= <bits>@<addr>
.TQ
.BI --real-heap= <bits>@<addr>
.TQ
.BI --raw-heap= <bytes>@<addr>
Inspection HEAP.
.TP
.BI --int-input= <bits>@<addr>
.TQ
.BI --real-input= <bits>@<addr>
.TQ
.BI --raw-input= <bytes>@<addr>
Inspection INPUT.
.TP
.BI --int-output= <bits>@<addr>
.TQ
.BI --real-output= <bits>@<addr>
.TQ
.BI --raw-output= <bytes>@<addr>
Inspection OUTPUT.
.TP
.BI --int-trace= <bits>@<addr>
.TQ
.BI --real-trace= <bits>@<addr>
.TQ
.BI --raw-trace= <bytes>@<addr>
Inspection TRACE.
.SH LIFECYCLE CONTROL
.TP
.BI --digits= n
Mantissa digits для real output; default 80.
.TP
.B --init-only
Выполнить INIT до END и остановиться.
.TP
.BI --steps= n
Остановиться после n LIFE END boundaries.
.TP
.BR -h ", " --help
Вывести справку.
.TP
.B --version
Вывести имя программы, идентификатор инструментария MCPU и версию, затем завершить работу.
.TP
.B --dump-version
Вывести только номер версии пакета MCPU и завершить работу.
.SH STAGE ACTIONS
Повторяемые stage options выполняют host actions на lifecycle boundaries:
.TP
.BI --before-run= action
После load/startup-link/relocations/startup area, до первой guest instruction.
.TP
.BI --after-init= action
После INIT END или один раз на logical empty INIT boundary без .init.
.TP
.BI --on-step= action
После каждого LIFE END.
.TP
.BI --after-run= action
После final normal stop; graceful FINI уже завершён.
.PP
Формы actions:
.nf
print-int-regs:r<bits>@<addr>[,...]
print-real-regs:r<bits>@<addr>[,...]
set-int-regs:r<bits>@<addr>=<value>[,...]
set-real-regs:r<bits>@<addr>=<value>[,...]
print-int-<memory>:<bits>@<addr>[,...]
print-real-<memory>:<bits>@<addr>[,...]
set-int-<memory>:<bits>@<addr>=<value>[,...]
set-real-<memory>:<bits>@<addr>=<value>[,...]
print-raw-<memory>:<bytes>@<addr>
.fi
.PP
memory = data, control, heap, input, output или trace. Scalar print выводит
comma-list одной строкой. Raw action содержит ровно один dump; для нескольких
нужно повторить stage option. set-raw-* отсутствуют. Set values разбираются
LibMPUIO mpu_sscanf(). Step-number filters не реализованы.
.SH LIFECYCLE И EXIT
END возвращает управление supervisor-у на INIT/LIFE/FINI boundaries. Graceful
EXIT может запустить optional FINI. Diagnostic stop по --steps не синтезирует
EXIT и сам по себе FINI не запускает.
.SH ФАЙЛЫ
.TP
.I <runtime-root>/etc/mcpu-ld.conf
Installed relocatable-tree configuration.
.TP
.I /etc/mcpu/mcpu-ld.conf
Machine-wide override.
.TP
.I $HOME/.mcpu/etc/mcpu-ld.conf
User override.
.SH СТАТУС ЗАВЕРШЕНИЯ
При нормальном завершении возвращается guest exit status. Loader/startup-linker,
option и runtime errors дают ненулевой host-side status.
.SH ПРИМЕРЫ
.nf
mcpu-run -- program arg1 arg2
mcpu-run --library-path=./lib -- program
MCPU_LD_PRELOAD=libhook.so mcpu-run -- program
mcpu-run --steps=20 --on-step=print-real-trace:128@0,128@16 -- pendulum
.fi
.SH СМ. ТАКЖЕ
.BR mcpu-ld (1),
.BR mcpu-readelf (1),
.BR mcpu-objdump (1),
.BR libmcpu (7)
|
