-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathprint.html
More file actions
7715 lines (7446 loc) · 402 KB
/
print.html
File metadata and controls
7715 lines (7446 loc) · 402 KB
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
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML>
<html lang="en" class="navy sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>The Asterinas Book</title>
<meta name="robots" content="noindex">
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon-de23e50b.svg">
<link rel="shortcut icon" href="favicon-8114d1fc.png">
<link rel="stylesheet" href="css/variables-8adf115d.css">
<link rel="stylesheet" href="css/general-2459343d.css">
<link rel="stylesheet" href="css/chrome-ae938929.css">
<link rel="stylesheet" href="css/print-9e4910d8.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="fonts/fonts-9644e21d.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="mdbook-highlight-css" href="highlight-493f70e1.css">
<link rel="stylesheet" id="mdbook-tomorrow-night-css" href="tomorrow-night-4c0ae647.css">
<link rel="stylesheet" id="mdbook-ayu-highlight-css" href="ayu-highlight-3fdfc3ac.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "navy";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "searchindex-58f9aaa7.js";
</script>
<!-- Start loading toc.js asap -->
<script src="toc-2005f4de.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="mdbook-body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('navy')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="mdbook-sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("mdbook-sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="mdbook-sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="mdbook-sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="mdbook-page-wrapper" class="page-wrapper">
<div class="page">
<div id="mdbook-menu-bar-hover-placeholder"></div>
<div id="mdbook-menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="mdbook-sidebar-toggle" class="icon-button" for="mdbook-sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="mdbook-sidebar">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg></span>
</label>
<button id="mdbook-theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="mdbook-theme-list">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M371.3 367.1c27.3-3.9 51.9-19.4 67.2-42.9L600.2 74.1c12.6-19.5 9.4-45.3-7.6-61.2S549.7-4.4 531.1 9.6L294.4 187.2c-24 18-38.2 46.1-38.4 76.1L371.3 367.1zm-19.6 25.4l-116-104.4C175.9 290.3 128 339.6 128 400c0 3.9 .2 7.8 .6 11.6c1.8 17.5-10.2 36.4-27.8 36.4H96c-17.7 0-32 14.3-32 32s14.3 32 32 32H240c61.9 0 112-50.1 112-112c0-2.5-.1-5-.2-7.5z"/></svg></span>
</button>
<ul id="mdbook-theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-ayu">Ayu</button></li>
</ul>
<button id="mdbook-search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="mdbook-searchbar">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352c79.5 0 144-64.5 144-144s-64.5-144-144-144S64 128.5 64 208s64.5 144 144 144z"/></svg></span>
</button>
</div>
<h1 class="menu-title">The Asterinas Book</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M128 0C92.7 0 64 28.7 64 64v96h64V64H354.7L384 93.3V160h64V93.3c0-17-6.7-33.3-18.7-45.3L400 18.7C388 6.7 371.7 0 354.7 0H128zM384 352v32 64H128V384 368 352H384zm64 32h32c17.7 0 32-14.3 32-32V256c0-35.3-28.7-64-64-64H64c-35.3 0-64 28.7-64 64v96c0 17.7 14.3 32 32 32H64v64c0 35.3 28.7 64 64 64H384c35.3 0 64-28.7 64-64V384zm-16-88c-13.3 0-24-10.7-24-24s10.7-24 24-24s24 10.7 24 24s-10.7 24-24 24z"/></svg></span>
</a>
</div>
</div>
<div id="mdbook-search-wrapper" class="hidden">
<form id="mdbook-searchbar-outer" class="searchbar-outer">
<div class="search-wrapper">
<input type="search" id="mdbook-searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="mdbook-searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<span class=fa-svg id="fa-spin"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M304 48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zm0 416c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM48 304c26.5 0 48-21.5 48-48s-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48zm464-48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM142.9 437c18.7-18.7 18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zm0-294.2c18.7-18.7 18.7-49.1 0-67.9S93.7 56.2 75 75s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zM369.1 437c18.7 18.7 49.1 18.7 67.9 0s18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9z"/></svg></span>
</div>
</div>
</form>
<div id="mdbook-searchresults-outer" class="searchresults-outer hidden">
<div id="mdbook-searchresults-header" class="searchresults-header"></div>
<ul id="mdbook-searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('mdbook-sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('mdbook-sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#mdbook-sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="mdbook-content" class="content">
<main>
<h1 id="the-asterinas-book"><a class="header" href="#the-asterinas-book">The Asterinas Book</a></h1>
<p align="center">
<img src="images/logo_en.svg" alt="asterinas-logo" width="620"><br>
</p>
<p>Welcome to the documentation for Asterinas,
an open-source project and community
focused on developing cutting-edge Rust OS kernels.</p>
<h2 id="book-structure"><a class="header" href="#book-structure">Book Structure</a></h2>
<p>This book is divided into six distinct parts:</p>
<h4 id="part-1-asterinas-nixos"><a class="header" href="#part-1-asterinas-nixos"><a href="distro">Part 1: Asterinas NixOS</a></a></h4>
<p>Asterinas NixOS is the first distribution built on top of the Asterinas kernel.
It is based on NixOS,
leveraging its powerful configuration model
and rich package ecosystem,
while swapping out the Linux kernel for Asterinas.</p>
<h4 id="part-2-asterinas-kernel"><a class="header" href="#part-2-asterinas-kernel"><a href="kernel">Part 2: Asterinas Kernel</a></a></h4>
<p>Explore the modern OS kernel at the heart of Asterinas.
Designed to realize the full potential of Rust,
Asterinas Kernel implements the Linux ABI in a safe and efficient way.
This means it can seamlessly replace Linux,
offering enhanced safety and security.</p>
<h4 id="part-3-asterinas-ostd"><a class="header" href="#part-3-asterinas-ostd"><a href="ostd">Part 3: Asterinas OSTD</a></a></h4>
<p>The Asterinas OSTD lays down a minimalistic, powerful, and solid foundation
for OS development.
It’s akin to Rust’s <code>std</code> crate
but crafted for the demands of <em>safe</em> Rust OS development.
The Asterinas Kernel is built on this very OSTD.</p>
<h4 id="part-4-asterinas-osdk"><a class="header" href="#part-4-asterinas-osdk"><a href="osdk/guide">Part 4: Asterinas OSDK</a></a></h4>
<p>The OSDK is a command-line tool
that streamlines the workflow to
create, build, test, and run Rust OS projects
that are built upon Asterinas OSTD.
Developed specifically for OS developers,
it extends Rust’s Cargo tool to better suite their specific needs.
OSDK is instrumental in the development of Asterinas Kernel.</p>
<h4 id="part-5-contributing-to-asterinas"><a class="header" href="#part-5-contributing-to-asterinas"><a href="to-contribute">Part 5: Contributing to Asterinas</a></a></h4>
<p>Asterinas is in its early stage
and welcomes your contributions!
This part provides guidance
on how you can become an integral part of the Asterinas project.</p>
<h4 id="part-6-requests-for-comments-rfcs"><a class="header" href="#part-6-requests-for-comments-rfcs"><a href="rfcs">Part 6: Requests for Comments (RFCs)</a></a></h4>
<p>Significant decisions in Asterinas are made through a transparent RFC process.
This part describes the RFC process
and archives all approvaed RFCs.</p>
<h2 id="licensing"><a class="header" href="#licensing">Licensing</a></h2>
<p>Asterinas’s source code and documentation primarily use the
<a href="https://github.com/asterinas/asterinas/blob/main/LICENSE-MPL">Mozilla Public License (MPL), Version 2.0</a>.
Select components are under more permissive licenses,
detailed <a href="https://github.com/asterinas/asterinas/blob/main/.licenserc.yaml">here</a>.</p>
<p>Our choice of the <a href="https://www.tldrlegal.com/license/mozilla-public-license-2-0-mpl-2">weak-copyleft</a> MPL license reflects a strategic balance:</p>
<ol>
<li>
<p><strong>Commitment to open-source freedom</strong>:
We believe that OS kernels are a communal asset that should benefit humanity.
The MPL ensures that any alterations to MPL-covered files remain open source,
aligning with our vision.
Additionally, we do not require contributors
to sign a Contributor License Agreement (CLA),
<a href="https://drewdevault.com/2018/10/05/Dont-sign-a-CLA.html">preserving their rights and preventing the possibility of their contributions being made closed source</a>.</p>
</li>
<li>
<p><strong>Accommodating proprietary modules</strong>:
Recognizing the evolving landscape
where large corporations also contribute significantly to open-source,
we accommodate the business need for proprietary kernel modules.
Unlike GPL,
the MPL permits the linking of MPL-covered files with proprietary code.</p>
</li>
</ol>
<p>In conclusion, we believe that
MPL is the best choice
to foster a vibrant, robust, and inclusive open-source community around Asterinas.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="asterinas-nixos"><a class="header" href="#asterinas-nixos">Asterinas NixOS</a></h1>
<p>Asterinas NixOS is the first distribution for Asterinas.
We choose <a href="https://nixos.org/">NixOS</a> as the base OS
for its unparalleled customizability and rich package ecosystem.
Asterinas NixOS is intended to look and feel like vanilla NixOS,
except that it replaces Linux with Asterinas as its kernel.
For more rationale about choosing NixOS,
see <a href="https://asterinas.github.io/book/rfcs/0002-asterinas-nixos.html">the RFC</a>.</p>
<p><strong>Disclaimer: Asterinas is an independent, community-led project.
Asterinas NixOS is <em>not</em> an official NixOS project and has <em>no</em> affiliation with the NixOS Foundation. <em>No</em> sponsorship or endorsement is implied.</strong></p>
<p>Asterinas NixOS is not ready for production use.
We provide Asterinas NixOS to make the Asterinas kernel more accessible,
allowing early adopters and enthusiasts to try it out and provide feedback.
In addition, Asterinas developers use this distro
as a key development vehicle
to facilitate enabling and testing more real-world applications
on the Asterinas kernel.</p>
<h2 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h2>
<h3 id="end-users"><a class="header" href="#end-users">End Users</a></h3>
<p>The following instructions describe how to install Asterinas NixOS in a VM
using the Asterinas NixOS installer ISO.</p>
<ol>
<li>
<p>Launch an x86-64 Ubuntu container:</p>
<pre><code class="language-bash">docker run -it --privileged --network=host ubuntu:latest bash
</code></pre>
</li>
<li>
<p>Inside the container, install QEMU:</p>
<pre><code class="language-bash">apt update
apt install -y qemu-system-x86 qemu-utils
</code></pre>
</li>
<li>
<p>Download the latest Asterinas NixOS installer ISO from <a href="https://github.com/asterinas/asterinas/releases">GitHub Releases</a>.</p>
</li>
<li>
<p>Create a file that will be used as the target disk to install Asterinas NixOS:</p>
<pre><code class="language-bash"># The capacity of the disk is 10GB; adjust it as you see fit
dd if=/dev/zero of=aster_nixos_disk.img bs=1G count=10
</code></pre>
</li>
<li>
<p>Start an x86-64 VM with two drives:
one is the installer CD-ROM and the other is the target disk:</p>
<pre><code class="language-bash">export INSTALLER_ISO=/path/to/your/downloaded/installer.iso
qemu-system-x86_64 \
-cpu host -m 8G -enable-kvm \
-drive file="$INSTALLER_ISO",media=cdrom -boot d \
-drive if=virtio,format=raw,file=aster_nixos_disk.img \
-chardev stdio,id=mux,mux=on,logfile=qemu.log \
-device virtio-serial-pci -device virtconsole,chardev=mux \
-serial chardev:mux -monitor chardev:mux \
-nographic
</code></pre>
<p>After the VM boots, you now have access to the installation environment.</p>
</li>
<li>
<p>Edit the <code>configuration.nix</code> file in the home directory
to customize the NixOS system to be installed:</p>
<pre><code class="language-bash">vim configuration.nix
</code></pre>
<p>The complete syntax and guidance for the <code>configuration.nix</code> file
can be found in <a href="https://nixos.org/manual/nixos/stable/#ch-configuration">the NixOS manual</a>.
If you are not familiar with NixOS,
you can simply skip this step.</p>
<p>Not all combinations of settings in <code>configuration.nix</code> are supported by Asterinas NixOS yet.
The ones that have been tested are documented in the subsequent chapters.</p>
</li>
<li>
<p>Start installation:</p>
<pre><code class="language-bash">install_aster_nixos.sh --config configuration.nix --disk /dev/vda --force-format-disk
</code></pre>
<p>The installation process involves downloading packages
and may take around 30 minutes to complete,
depending on your network speed.</p>
</li>
<li>
<p>After the installation is complete, you can shut down the VM:</p>
<pre><code class="language-bash">poweroff
</code></pre>
<p>Now Asterinas NixOS is installed in <code>aster_nixos_disk.img</code>.</p>
</li>
<li>
<p>Start a VM to boot the newly installed Asterinas NixOS:</p>
<pre><code class="language-bash">qemu-system-x86_64 \
-cpu host -m 8G -enable-kvm \
-bios /usr/share/qemu/OVMF.fd \
-drive if=none,format=raw,id=x0,file=aster_nixos_disk.img \
-device virtio-blk-pci,drive=x0,disable-legacy=on,disable-modern=off \
-chardev stdio,id=mux,mux=on,logfile=qemu.log \
-device virtio-serial-pci -device virtconsole,chardev=mux \
-serial chardev:mux -monitor chardev:mux \
-device virtio-net-pci,netdev=net0,disable-legacy=on,disable-modern=off \
-netdev user,id=net0 \
-device isa-debug-exit,iobase=0xf4,iosize=0x04 \
-nographic -display vnc=127.0.0.1:21
</code></pre>
<p>If a desktop environment is enabled in the <code>configuration.nix</code> file,
you can view the graphical interface using a VNC client.</p>
</li>
</ol>
<h3 id="kernel-developers"><a class="header" href="#kernel-developers">Kernel Developers</a></h3>
<ol>
<li>
<p>Follow Steps 1 and 2 in the <a href="#getting-started-1">“Getting Started” section of the Asterinas Kernel</a>
to set up the development environment.</p>
</li>
<li>
<p>Inside the Docker container,
generate a disk image with Asterinas NixOS installed using this command:</p>
<pre><code class="language-bash">make nixos
</code></pre>
<p>or this command:</p>
<pre><code class="language-bash">make iso && make run_iso
</code></pre>
<p>The difference between the two methods is that
the first installs NixOS to a disk image entirely inside the container,
whereas the second emulates the manual ISO installation steps
(see the <a href="#end-users">previous section</a>)
by running a VM.
Using either method results in a disk image with an Asterinas NixOS installation.</p>
</li>
<li>
<p>Start a VM to run the installed Asterinas NixOS:</p>
<pre><code class="language-bash">make run_nixos
</code></pre>
</li>
</ol>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="popular-applications"><a class="header" href="#popular-applications">Popular Applications</a></h1>
<p>The <a href="https://search.nixos.org/packages">Nix package collection</a> contains over 120,000 packages.
Many of them may already work out of the box on Asterinas NixOS,
but it is impractical to test every package
and document its support status.
Instead, we group popular applications into categories
and document the ones we have verified to work.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="package-management"><a class="header" href="#package-management">Package Management</a></h1>
<p>NixOS provides a set of <a href="https://nix.dev/manual/nix/2.28/command-ref/main-commands">tools</a>
for building, installing, and managing packages.</p>
<h2 id="verified-usage"><a class="header" href="#verified-usage">Verified Usage</a></h2>
<h3 id="nix-build"><a class="header" href="#nix-build"><code>nix-build</code></a></h3>
<p><code>nix-build</code> builds Nix derivations and produces outputs in the Nix store.
It is the preferred way to build software reproducibly.</p>
<pre><code class="language-bash"># Step 1: Create a clean workspace
rm -rf /tmp/nix-hello-c && mkdir -p /tmp/nix-hello-c && cd /tmp/nix-hello-c
# Step 2: Write a C program
cat > hello.c <<'EOF'
#include <stdio.h>
int main(void) {
puts("Hello, World!");
return 0;
}
EOF
# Step 3: Write a default.nix
cat > default.nix <<'EOF'
{ pkgs ? import <nixpkgs> {} }:
pkgs.stdenv.mkDerivation {
pname = "hello-c";
version = "0.1.0";
src = ./.;
dontConfigure = true;
buildPhase = ''
cc hello.c -o hello
'';
installPhase = ''
mkdir -p $out/bin
install -m755 hello $out/bin/hello
'';
}
EOF
# Step 4: Build and run
nix-build
./result/bin/hello
</code></pre>
<h3 id="nix-env"><a class="header" href="#nix-env"><code>nix-env</code></a></h3>
<p><code>nix-env</code> installs or removes individual packages in your user profile.</p>
<pre><code class="language-bash"># Install the `hello` package
nix-env -iA nixos.hello
# Remove the `hello` package
nix-env -e hello
</code></pre>
<h3 id="nix-shell"><a class="header" href="#nix-shell"><code>nix-shell</code></a></h3>
<p><code>nix-shell</code> creates a temporary development environment with the specified dependencies.
This is useful for testing software without modifying your system environment.</p>
<pre><code class="language-bash"># Enter a shell with the `hello` package available
nix-shell -p hello
</code></pre>
<h3 id="nixos-rebuild"><a class="header" href="#nixos-rebuild"><code>nixos-rebuild</code></a></h3>
<p><code>nixos-rebuild</code> manages the entire system configuration declaratively.
It applies changes defined in <code>configuration.nix</code>,
and is the recommended approach for installing packages system-wide.</p>
<pre><code class="language-bash"># Edit the system configuration file
vim /etc/nixos/configuration.nix
# Apply configuration changes and rebuild the system without rebooting
nixos-rebuild test
</code></pre>
<!--
TODO: upgrade mdbook to enable admonition blocks like the one below:
> [!WARNING]
> `nixos-rebuild switch` is not yet supported
-->
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="desktop-environment"><a class="header" href="#desktop-environment">Desktop Environment</a></h1>
<h2 id="xfce"><a class="header" href="#xfce">Xfce</a></h2>
<p><a href="https://www.xfce.org/">Xfce</a> is a lightweight desktop environment for UNIX-like operating systems.</p>
<h3 id="installation"><a class="header" href="#installation">Installation</a></h3>
<p>Add the following lines to the <code>configuration.nix</code> file:</p>
<pre><code class="language-nix">services.xserver.enable = true;
services.xserver.desktopManager.xfce.enable = true;
</code></pre>
<!--
TODO: upgrade mdbook to enable admonition blocks like the one below:
> [!WARNING]
> Xfce must be enabled during the initial installation of Asterinas NixOS. Applying configuration changes via `nixos-rebuild` is not working yet.
-->
<h3 id="verified-backends"><a class="header" href="#verified-backends">Verified Backends</a></h3>
<ul>
<li>Display server:
<ul>
<li>Xorg display server</li>
</ul>
</li>
<li>Graphics drivers:
<ul>
<li>Standard UEFI VGA framebuffer</li>
</ul>
</li>
</ul>
<h3 id="verified-functionality"><a class="header" href="#verified-functionality">Verified Functionality</a></h3>
<ul>
<li>Changing desktop wallpapers and background settings</li>
<li>Adjusting font size, style, and system theme</li>
<li>Creating application shortcuts and desktop launchers</li>
<li>Managing panels and window behavior</li>
<li>Using the settings manager and file browser</li>
</ul>
<h3 id="verified-gui-applications"><a class="header" href="#verified-gui-applications">Verified GUI Applications</a></h3>
<p>Utilities:</p>
<ul>
<li><code>galculator</code>: Calculator</li>
<li><code>mousepad</code>: The default Xfce text editor</li>
<li><code>mupdf</code>: A lightweight PDF and XPS viewer</li>
</ul>
<p>Games:</p>
<ul>
<li><code>fairymax</code>: Chess</li>
<li><code>five-or-more</code>: GNOME alignment game</li>
<li><code>lbreakout2</code>: Breakout/Arkanoid clone</li>
<li><code>gnome-chess</code>: GNOME chess</li>
<li><code>gnome-mines</code>: Minesweeper</li>
<li><code>gnome-sudoku</code>: GNOME sudoku</li>
<li><code>tali</code>: GNOME dice game</li>
<li><code>xboard</code>: Chess</li>
<li><code>xgalaga</code>: Galaga-style arcade game</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="containerization"><a class="header" href="#containerization">Containerization</a></h1>
<h2 id="podman"><a class="header" href="#podman">Podman</a></h2>
<p><a href="https://docs.podman.io/en/stable/Introduction.html">Podman</a> is a modern, daemonless container engine
that provides a Docker-compatible command-line interface,
making it easy for users familiar with Docker to transition.</p>
<h3 id="installation-1"><a class="header" href="#installation-1">Installation</a></h3>
<p>To install Podman, add the following line to <code>configuration.nix</code>:</p>
<pre><code class="language-nix">virtualization.podman.enable = true;
</code></pre>
<h3 id="verified-usage-1"><a class="header" href="#verified-usage-1">Verified Usage</a></h3>
<h4 id="podman-run"><a class="header" href="#podman-run"><code>podman run</code></a></h4>
<p><code>podman run</code> runs a command in a new container.</p>
<pre><code class="language-bash"># Start a container, execute a command, and then exit
podman run --name=c1 docker.io/library/alpine ls /etc
# Start a container and attach to an interactive shell
podman run -it docker.io/library/alpine
</code></pre>
<h4 id="podman-image"><a class="header" href="#podman-image"><code>podman image</code></a></h4>
<p><code>podman image</code> manages local images.</p>
<pre><code class="language-bash"># List downloaded images
podman image ls
</code></pre>
<h4 id="podman-ps"><a class="header" href="#podman-ps"><code>podman ps</code></a></h4>
<p><code>podman ps</code> lists containers.</p>
<pre><code class="language-bash"># Show the status of all containers (including exited ones)
podman ps -a
</code></pre>
<h4 id="podman-rm"><a class="header" href="#podman-rm"><code>podman rm</code></a></h4>
<p><code>podman rm</code> removes one or more containers.</p>
<pre><code class="language-bash"># Remove a container named foo
podman rm foo
</code></pre>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="asterinas-kernel"><a class="header" href="#asterinas-kernel">Asterinas Kernel</a></h1>
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>Asterinas is a <em>secure</em>, <em>fast</em>, and <em>general-purpose</em> OS kernel
that provides an <em>Linux-compatible</em> ABI.
It can serve as a seamless replacement for Linux
while enhancing <em>memory safety</em> and <em>developer friendliness</em>.</p>
<ul>
<li>
<p>Asterinas prioritizes memory safety
by employing Rust as its sole programming language
and limiting the use of <em>unsafe Rust</em>
to a clearly defined and minimal Trusted Computing Base (TCB).
This innovative approach,
known as <a href="#the-framekernel-architecture">the framekernel architecture</a>,
establishes Asterinas as a more secure and dependable kernel option.</p>
</li>
<li>
<p>Asterinas surpasses Linux in terms of developer friendliness.
It empowers kernel developers to
(1) utilize the more productive Rust programming language,
(2) leverage a purpose-built toolkit called <a href="#asterinas-kernel">OSDK</a> to streamline their workflows,
and (3) choose between releasing their kernel modules as open source
or keeping them proprietary,
thanks to the flexibility offered by <a href="">MPL</a>.</p>
</li>
</ul>
<p>While the journey towards a production-grade OS kernel can be challenging,
we are steadfastly progressing towards our goal.</p>
<h2 id="supported-cpu-architectures"><a class="header" href="#supported-cpu-architectures">Supported CPU Architectures</a></h2>
<p>Asterinas targets modern, 64-bit platforms only.</p>
<p>A <strong>development platform</strong> is where you build and test Asterinas
(i.e., the host machine running the Docker-based development environment).</p>
<div class="table-wrapper">
<table>
<thead>
<tr><th>Development Platform</th></tr>
</thead>
<tbody>
<tr><td>x86-64</td></tr>
</tbody>
</table>
</div>
<p>A <strong>deployment platform</strong> is a CPU architecture
that Asterinas can run on as an OS kernel.</p>
<div class="table-wrapper">
<table>
<thead>
<tr><th>Deployment Platform</th><th>Tier</th></tr>
</thead>
<tbody>
<tr><td>x86-64</td><td>Tier 1</td></tr>
<tr><td>x86-64 (Intel TDX)</td><td>Tier 2</td></tr>
<tr><td>RISC-V 64</td><td>Tier 2</td></tr>
<tr><td>LoongArch 64</td><td>Tier 3</td></tr>
</tbody>
</table>
</div>
<ul>
<li><strong>Tier 1:</strong> Fully supported and tested.
CI runs the full test suite on every PR.</li>
<li><strong>Tier 2:</strong> Actively developed with basic functionality working.
CI runs build checks and basic tests on a regular basis
(per PR for RISC-V and nightly for Intel TDX),
but the full test suite is not yet covered.</li>
<li><strong>Tier 3:</strong> Early-stage or experimental.
The kernel can boot and perform basic operations,
but CI coverage is limited and
may not include automated runtime tests for every pull request.</li>
</ul>
<h2 id="getting-started-1"><a class="header" href="#getting-started-1">Getting Started</a></h2>
<p>Get yourself an x86-64 Linux machine with Docker installed.
Follow the three simple steps below to get Asterinas up and running.</p>
<!-- REMINDER: Be careful when editing the first two steps
since `distro/README.md` references them -->
<ol>
<li>
<p>Download the latest source code.</p>
<pre><code class="language-bash">git clone https://github.com/asterinas/asterinas
</code></pre>
</li>
<li>
<p>Run a Docker container as the development environment.</p>
<pre><code class="language-bash">docker run -it --privileged \
--network=host \
-v /dev:/dev \
-v $(pwd)/asterinas:/root/asterinas \
asterinas/asterinas:0.17.1-20260319
</code></pre>
</li>
<li>
<p>Inside the container, go to the project folder to build and run Asterinas.</p>
<pre><code class="language-bash">make kernel
make run_kernel
</code></pre>
</li>
</ol>
<p>If everything goes well, Asterinas is now up and running inside a VM.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="advanced-build-and-test-instructions"><a class="header" href="#advanced-build-and-test-instructions">Advanced Build and Test Instructions</a></h1>
<h2 id="user-mode-unit-tests"><a class="header" href="#user-mode-unit-tests">User-Mode Unit Tests</a></h2>
<p>Asterinas consists of many crates,
some of which do not require a VM environment
and can be tested with the standard <code>cargo test</code>.
They are listed in the root <code>Makefile</code>
and can be tested together through the following Make command.</p>
<pre><code class="language-bash">make test
</code></pre>
<p>To test an individual crate, enter the directory of the crate and invoke <code>cargo test</code>.</p>
<h3 id="kernel-mode-unit-tests"><a class="header" href="#kernel-mode-unit-tests">Kernel-Mode Unit Tests</a></h3>
<p>Many crates in Asterinas do require a VM environment to be tested.
The unit tests for these crates are empowered by OSDK.</p>
<pre><code class="language-bash">make ktest
</code></pre>
<p>To test an individual crate in kernel mode, enter the directory of the crate and invoke <code>cargo osdk test</code>.</p>
<pre><code class="language-bash">cd asterinas/ostd
cargo osdk test
</code></pre>
<h2 id="integration-test"><a class="header" href="#integration-test">Integration Test</a></h2>
<h3 id="regression-test"><a class="header" href="#regression-test">Regression Test</a></h3>
<p>The following command builds and runs the regression test in <code>test/initramfs/src/regression</code> on Asterinas.</p>
<pre><code class="language-bash">make run_kernel AUTO_TEST=regression
</code></pre>
<h3 id="conformance-test"><a class="header" href="#conformance-test">Conformance Test</a></h3>
<p>The following command builds and runs the conformance test on Asterinas.</p>
<pre><code class="language-bash">make run_kernel AUTO_TEST=conformance
</code></pre>
<p>To run conformance test interactively, start an instance of Asterinas with the conformance tests built and installed.</p>
<pre><code class="language-bash">make run_kernel ENABLE_CONFORMANCE_TEST=true
</code></pre>
<p>Then, in the interactive shell, run the following script to start the conformance test.</p>
<pre><code class="language-bash">/opt/run_conformance_test.sh
</code></pre>
<h2 id="debug"><a class="header" href="#debug">Debug</a></h2>
<h3 id="using-gdb-to-debug"><a class="header" href="#using-gdb-to-debug">Using GDB to Debug</a></h3>
<p>To debug Asterinas via <a href="https://qemu-project.gitlab.io/qemu/system/gdb.html">QEMU GDB support</a>,
you can compile Asterinas in the debug profile,
start an Asterinas instance and run the GDB interactive shell in another terminal.</p>
<p>Start a GDB-enabled VM of Asterinas with OSDK and wait for debugging connection:</p>
<pre><code class="language-bash">make gdb_server
</code></pre>
<p>The server will listen at the default address specified in <code>Makefile</code>, i.e., a local TCP port <code>:1234</code>.
Change the address in <code>Makefile</code> for your convenience,
and check <code>cargo osdk run -h</code> for more details about the address.</p>
<p>Two options are provided to interact with the debug server.</p>
<ul>
<li>
<p>A GDB client: start a GDB client in another terminal.</p>
<pre><code class="language-bash">make gdb_client
</code></pre>
</li>
<li>
<p>VS Code: <a href="https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb">CodeLLDB</a> extension is required.
After starting a debug server with OSDK from the shell with <code>make gdb_server</code>,
a temporary <code>launch.json</code> is generated under <code>.vscode</code>.
Your previous launch configs will be restored after the server is down.
Press <code>F5</code>(Run and Debug) to start a debug session via VS Code.
Click <code>Continue</code>(or, press <code>F5</code>) at the first break to resume the paused server instance,
then it will continue until reaching your first breakpoint.</p>
</li>
</ul>
<p>Note that if debugging with KVM enabled, you must use hardware assisted breakpoints. See “hbreak” in
<a href="https://ftp.gnu.org/old-gnu/Manuals/gdb/html_node/gdb_28.html">the GDB manual</a> for details.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="intel-tdx"><a class="header" href="#intel-tdx">Intel TDX</a></h1>
<p>Asterinas can serve as a secure guest OS for Intel TDX-protected virtual machines (VMs).
This documentation describes
how Asterinas can be run and tested easily on a TDX-enabled Intel server.</p>
<p>Intel TDX (Trust Domain Extensions) is a Trusted Execution Environment (TEE) technology
that enhances VM security
by creating isolated, hardware-enforced trust domains
with encrypted memory, secure initialization, and attestation mechanisms.
For more information about Intel TDX, jump to the last section.</p>
<h2 id="why-choose-asterinas-for-intel-tdx"><a class="header" href="#why-choose-asterinas-for-intel-tdx">Why choose Asterinas for Intel TDX</a></h2>
<p>VM TEEs such as Intel TDX deserve a more secure option for its guest OS than Linux.
Linux,
with its inherent memory safety issues and large Trusted Computing Base (TCB),
has long suffered from security vulnerabilities due to memory safety bugs.
Additionally,
when Linux is used as the guest kernel inside a VM TEE,
it must process untrusted inputs
(over 1500 instances in Linux, per Intel’s estimation)
from the host (via hypercalls, MMIO, and etc.).
These untrusted inputs create new attack surfaces
that can be exploited through memory safety vulnerabilities,
known as Iago attacks.</p>
<p>Asterinas offers greater memory safety than Linux,
particularly against Iago attacks.
Thanks to its framekernel architecture,
the memory safety of Asterinas relies solely on the Asterinas Framework,
excluding the safe device drivers built on top of the Asterinas Framework
that may handle untrusted inputs from the host.
For more information, see <a href="https://www.youtube.com/watch?v=3AQ5lpXujGo">our talk on OC3’24</a>.</p>
<h2 id="prepare-the-intel-tdx-environment"><a class="header" href="#prepare-the-intel-tdx-environment">Prepare the Intel TDX Environment</a></h2>
<p>Please make sure your server supports Intel TDX.</p>
<p>See <a href="https://github.com/canonical/tdx/tree/noble-24.04?tab=readme-ov-file#4-setup-host-os">this guide</a>
or other materials to enable Intel TDX in host OS.</p>
<p>To verify the TDX host status,
you can type:</p>
<pre><code class="language-bash">dmesg | grep "TDX module initialized"
</code></pre>
<p>The following result is an example:</p>
<pre><code class="language-bash">[ 20.507296] tdx: TDX module initialized.
</code></pre>
<p><code>TDX module initialized</code> means TDX module is loaded successfully.</p>
<h2 id="build-and-run-asterinas"><a class="header" href="#build-and-run-asterinas">Build and run Asterinas</a></h2>
<ol>
<li>
<p>Download the latest source code.</p>
<pre><code class="language-bash">git clone https://github.com/asterinas/asterinas
</code></pre>
</li>
<li>
<p>Run a Docker container as the development environment.</p>
<pre><code class="language-bash">docker run -it --privileged --network=host --device=/dev/kvm -v $(pwd)/asterinas:/root/asterinas asterinas/asterinas:0.17.1-20260319
</code></pre>
</li>
<li>
<p>Inside the container,
go to the project folder to build and run Asterinas.</p>
<pre><code class="language-bash">make run_kernel INTEL_TDX=1
</code></pre>
</li>
</ol>
<p>If everything goes well,
Asterinas is now up and running inside a TD.</p>
<h2 id="using-gdb-to-debug-1"><a class="header" href="#using-gdb-to-debug-1">Using GDB to Debug</a></h2>
<p>A Trust Domain (TD) is debuggable if its <code>ATTRIBUTES.DEBUG</code> bit is 1.
In this mode, the host VMM can use Intel TDX module functions
to read and modify TD VCPU state and TD private memory,
which are not accessible when the TD is non-debuggable.</p>
<p>Start Asterinas in a GDB-enabled TD and wait for debugging connection:</p>
<pre><code class="language-bash">make gdb_server INTEL_TDX=1
</code></pre>
<p>Behind the scene, this command adds <code>debug=on</code> configuration to the QEMU parameters
to enable TD debuggable mode.</p>
<p>The server will listen at the default address specified in <code>Makefile</code>,
i.e., a local TCP port <code>:1234</code>.</p>
<p>Start a GDB client in another terminal:</p>
<pre><code class="language-bash">make gdb_client INTEL_TDX=1
</code></pre>
<p>Note that you must use hardware assisted breakpoints
because KVM is enabled when debugging a TD.</p>
<h2 id="about-intel-tdx"><a class="header" href="#about-intel-tdx">About Intel TDX</a></h2>
<p>Intel® Trust Domain Extensions (Intel® TDX)
is Intel’s newest confidential computing technology.
This hardware-based trusted execution environment (TEE)
facilitates the deployment of trust domains (TD),
which are hardware-isolated virtual machines (VM) designed to
protect sensitive data and applications from unauthorized access.</p>
<p>A CPU-measured Intel TDX module enables Intel TDX.
This software module runs in a new CPU Secure Arbitration Mode (SEAM)
as a peer virtual machine manager (VMM),
and supports TD entry and exit
using the existing virtualization infrastructure.
The module is hosted in a reserved memory space
identified by the SEAM Range Register (SEAMRR).</p>
<p>Intel TDX uses hardware extensions for managing and encrypting memory
and protects both the confidentiality and integrity
of the TD CPU state from non-SEAM mode.</p>
<p>Intel TDX uses architectural elements such as SEAM,
a shared bit in Guest Physical Address (GPA),
secure Extended Page Table (EPT),
physical-address-metadata table,
Intel® Total Memory Encryption – Multi-Key (Intel® TME-MK),
and remote attestation.</p>
<p>Intel TDX ensures data integrity, confidentiality, and authenticity,
which empowers engineers and tech professionals
to create and maintain secure systems,
enhancing trust in virtualized environments.</p>
<p>For more information,
please refer to <a href="https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/overview.html">Intel TDX website</a>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="the-framekernel-architecture"><a class="header" href="#the-framekernel-architecture">The Framekernel Architecture</a></h1>
<h2 id="framekernel-what-and-why"><a class="header" href="#framekernel-what-and-why">Framekernel: What and Why</a></h2>
<blockquote>
<p>The security of a microkernel, the speed of a monolithic kernel.</p>
</blockquote>
<p>Asterinas introduces a novel OS architecture called <em>framekernel</em>,
which unleashes the full power of Rust
to bring the best of both monolithic kernels and microkernels.</p>
<p>Within the framekernel architecture,
the entire OS resides in the same address space (like a monolithic kernel)
and is required to be written in Rust.
However, there’s a twist—the kernel is partitioned in two halves:
the OS Framework (akin to a microkernel)
and the OS Services.
Only the OS Framework is allowed to use <em>unsafe Rust</em>,
while the OS Services must be written exclusively in <em>safe Rust</em>.</p>
<div class="table-wrapper">
<table>
<thead>
<tr><th></th><th>Unsafe Rust</th><th>Responsibilities</th><th>Code Sizes</th></tr>
</thead>
<tbody>
<tr><td>OS Framework</td><td>Allowed</td><td>Encapsulate low-level unsafe code within high-level safe APIs</td><td>Small</td></tr>
<tr><td>OS Services</td><td>Not allowed</td><td>Implement OS functionalities, e.g., system calls, file systems, device drivers</td><td>Large</td></tr>
</tbody>
</table>
</div>
<p>As a result,
the memory safety of the kernel can be reduced to that of the OS Framework,
thus minimizing the Trusted Computing Base (TCB)
associated with the kernel’s memory safety.
On the other hand,
the single address space allows different parts of the kernel
to communicate in the most efficient means,
e.g., function calls and shared memory.
Thanks to the framekernel architecture,
Asterinas can offer both exceptional performance and enhanced safety.</p>
<p><img src="images/a_comparison_between_os_archs.svg" alt="A comparison between different OS architectures"></p>
<h2 id="requirements-for-the-os-framework"><a class="header" href="#requirements-for-the-os-framework">Requirements for the OS Framework</a></h2>
<p>While the concept of framekernel is straightforward,
the design and implementation of the required OS framework present challenges.
It must concurrently fulfill four criteria.</p>
<p><img src="images/four_requirements_for_os_framework.svg" alt="The four requirements for the OS framework"></p>
<ul>
<li><strong>Soundness.</strong>
The safe APIs of the framework are considered sound
if no <a href="https://doc.rust-lang.org/reference/behavior-considered-undefined.html#behavior-considered-undefined">undefined behaviors</a> shall be triggered
by whatever safe Rust code that a programmer may write using the APIs</li>
</ul>
<ul>
<li>as long as the code is verified by the Rust toolchain.
Soundness ensures that the OS framework,
in conjunction with the Rust toolchain,
bears the full responsibility for the kernel’s memory safety.</li>
</ul>
<ul>
<li>
<p><strong>Expressiveness.</strong>
The framework should empower developers
to implement a substantial range of OS functionalities
in safe Rust using the APIs.
It is especially important that
the framework enables writing device drivers in safe Rust,
considering that device drivers comprise the bulk of the code
in a fully-fleged OS kernel (like Linux).</p>
</li>
<li>
<p><strong>Minimalism.</strong>
As the TCB for memory safety,
the framework should be kept as small as possible.
No functionality should be implemented inside the framework
if doing it outside is possible.</p>
</li>
<li>
<p><strong>Efficiency.</strong>
The safe API provided by the framework is only allowed
to introduce minimal overheads.
Ideally, these APIs should be realized
as <a href="https://monomorph.is/posts/zero-cost-abstractions/">zero-cost abstractions</a>.</p>
</li>
</ul>
<p>Fortunately, our efforts
to design and implement an OS framework meeting these standards
have borne fruit in the form of the <a href="ostd">Asterinas OSTD</a>.
Using this framework as a foundation,
we have developed the Asterinas Kernel;
this framework also enables others to create their own framekernels,
with different goals and tradeoffs.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="linux-compatibility"><a class="header" href="#linux-compatibility">Linux Compatibility</a></h1>
<blockquote>
<p>“We don’t break user space.”</p>
<p>— Linus Torvalds</p>
</blockquote>
<p>Asterinas is dedicated to maintaining compatibility with the Linux ABI,
ensuring that applications and administrative tools
designed for Linux can seamlessly operate within Asterinas.
While we prioritize compatibility,
it is important to note that Asterinas does not,
nor will it in the future,
support the loading of Linux kernel modules.</p>
<h2 id="system-calls"><a class="header" href="#system-calls">System Calls</a></h2>
<p>At the time of writing,
Asterinas supports over 230 Linux system calls for the x86-64 architecture,
which are summarized in the table below.</p>
<div class="table-wrapper">
<table>
<thead>
<tr><th>Numbers</th><th>Names</th><th>Supported</th><th>Flag Coverage</th></tr>
</thead>
<tbody>
<tr><td>0</td><td>read</td><td>✅</td><td>💯</td></tr>
<tr><td>1</td><td>write</td><td>✅</td><td>💯</td></tr>
<tr><td>2</td><td>open</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/file-and-directory-operations#open-and-openat">⚠️</a></td></tr>
<tr><td>3</td><td>close</td><td>✅</td><td>💯</td></tr>
<tr><td>4</td><td>stat</td><td>✅</td><td>💯</td></tr>
<tr><td>5</td><td>fstat</td><td>✅</td><td>💯</td></tr>
<tr><td>6</td><td>lstat</td><td>✅</td><td>💯</td></tr>
<tr><td>7</td><td>poll</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/file-descriptor-and-io-control#poll-and-ppoll">⚠️</a></td></tr>
<tr><td>8</td><td>lseek</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/file-and-directory-operations#lseek">⚠️</a></td></tr>
<tr><td>9</td><td>mmap</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/memory-management#mmap-and-munmap">⚠️</a></td></tr>
<tr><td>10</td><td>mprotect</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/memory-management#mprotect">⚠️</a></td></tr>
<tr><td>11</td><td>munmap</td><td>✅</td><td>💯</td></tr>
<tr><td>12</td><td>brk</td><td>✅</td><td>💯</td></tr>
<tr><td>13</td><td>rt_sigaction</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/signals-and-timers#rt_sigaction">⚠️</a></td></tr>
<tr><td>14</td><td>rt_sigprocmask</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/signals-and-timers#rt_sigprocmask">⚠️</a></td></tr>
<tr><td>15</td><td>rt_sigreturn</td><td>✅</td><td>💯</td></tr>
<tr><td>16</td><td>ioctl</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/file-descriptor-and-io-control#ioctl">⚠️</a></td></tr>
<tr><td>17</td><td>pread64</td><td>✅</td><td>💯</td></tr>
<tr><td>18</td><td>pwrite64</td><td>✅</td><td>💯</td></tr>
<tr><td>19</td><td>readv</td><td>✅</td><td>💯</td></tr>
<tr><td>20</td><td>writev</td><td>✅</td><td>💯</td></tr>
<tr><td>21</td><td>access</td><td>✅</td><td>💯</td></tr>
<tr><td>22</td><td>pipe</td><td>✅</td><td>💯</td></tr>
<tr><td>23</td><td>select</td><td>✅</td><td>💯</td></tr>
<tr><td>24</td><td>sched_yield</td><td>✅</td><td>💯</td></tr>
<tr><td>25</td><td>mremap</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/memory-management#mremap">⚠️</a></td></tr>
<tr><td>26</td><td>msync</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/memory-management#msync">⚠️</a></td></tr>
<tr><td>27</td><td>mincore</td><td>❌</td><td>N/A</td></tr>
<tr><td>28</td><td>madvise</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/memory-management#madvise">⚠️</a></td></tr>
<tr><td>29</td><td>shmget</td><td>❌</td><td>N/A</td></tr>
<tr><td>30</td><td>shmat</td><td>❌</td><td>N/A</td></tr>
<tr><td>31</td><td>shmctl</td><td>❌</td><td>N/A</td></tr>
<tr><td>32</td><td>dup</td><td>✅</td><td>💯</td></tr>
<tr><td>33</td><td>dup2</td><td>✅</td><td>💯</td></tr>
<tr><td>34</td><td>pause</td><td>✅</td><td>💯</td></tr>
<tr><td>35</td><td>nanosleep</td><td>✅</td><td>💯</td></tr>
<tr><td>36</td><td>getitimer</td><td>✅</td><td>💯</td></tr>
<tr><td>37</td><td>alarm</td><td>✅</td><td>💯</td></tr>
<tr><td>38</td><td>setitimer</td><td>✅</td><td>💯</td></tr>
<tr><td>39</td><td>getpid</td><td>✅</td><td>💯</td></tr>
<tr><td>40</td><td>sendfile</td><td>✅</td><td>💯</td></tr>
<tr><td>41</td><td>socket</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#socket">⚠️</a></td></tr>
<tr><td>42</td><td>connect</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#connect">⚠️</a></td></tr>
<tr><td>43</td><td>accept</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#accept-and-accept4">⚠️</a></td></tr>
<tr><td>44</td><td>sendto</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#sendto-sendmsg-and-sendmmsg">⚠️</a></td></tr>
<tr><td>45</td><td>recvfrom</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#recvfrom-and-recvmsg">⚠️</a></td></tr>
<tr><td>46</td><td>sendmsg</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#sendto-sendmsg-and-sendmmsg">⚠️</a></td></tr>
<tr><td>47</td><td>recvmsg</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#recvfrom-and-recvmsg">⚠️</a></td></tr>
<tr><td>48</td><td>shutdown</td><td>✅</td><td>💯</td></tr>
<tr><td>49</td><td>bind</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#bind">⚠️</a></td></tr>
<tr><td>50</td><td>listen</td><td>✅</td><td>💯</td></tr>
<tr><td>51</td><td>getsockname</td><td>✅</td><td>💯</td></tr>
<tr><td>52</td><td>getpeername</td><td>✅</td><td>💯</td></tr>
<tr><td>53</td><td>socketpair</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#socketpair">⚠️</a></td></tr>
<tr><td>54</td><td>setsockopt</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#getsockopt-and-setsockopt">⚠️</a></td></tr>
<tr><td>55</td><td>getsockopt</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/networking-and-sockets#getsockopt-and-setsockopt">⚠️</a></td></tr>
<tr><td>56</td><td>clone</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/process-and-thread-management#clone-and-clone3">⚠️</a></td></tr>
<tr><td>57</td><td>fork</td><td>✅</td><td>💯</td></tr>
<tr><td>58</td><td>vfork</td><td>✅</td><td>💯</td></tr>
<tr><td>59</td><td>execve</td><td>✅</td><td>💯</td></tr>
<tr><td>60</td><td>exit</td><td>✅</td><td>💯</td></tr>
<tr><td>61</td><td>wait4</td><td>✅</td><td><a href="kernel/linux-compatibility/syscall-flag-coverage/process-and-thread-management#wait4">⚠️</a></td></tr>