From d752a671375c1ce8a67528e2d1290aeffe3435c2 Mon Sep 17 00:00:00 2001 From: Yu Chen Date: Mon, 27 Jun 2022 22:22:44 +0800 Subject: [PATCH] add os[1-8]-ref for os refereces, add guide, add README --- .gitignore | 3 +- Makefile | 11 + README.md | 26 + guide/.gitignore | 5 + guide/LICENSE | 674 +++++++++++++++++ guide/Makefile | 23 + guide/all.sh | 2 + guide/make.bat | 35 + guide/requirements.txt | 28 + guide/show.sh | 1 + guide/source/0setup-devel-env.rst | 267 +++++++ guide/source/_static/dracula.css | 91 +++ guide/source/_static/my_style.css | 3 + guide/source/appendix-a/index.rst | 56 ++ guide/source/appendix-b/index.rst | 318 ++++++++ guide/source/appendix-c/index.rst | 18 + guide/source/appendix-d/index.rst | 32 + guide/source/chapter1/0intro.rst | 96 +++ guide/source/chapter1/1app-ee-platform.rst | 120 +++ guide/source/chapter1/2remove-std.rst | 158 ++++ guide/source/chapter1/3mini-rt-usrland.rst | 282 ++++++++ guide/source/chapter1/4mini-rt-baremetal.rst | 328 +++++++++ guide/source/chapter1/5exercise.rst | 143 ++++ guide/source/chapter1/app-software-stack.png | Bin 0 -> 11052 bytes guide/source/chapter1/chap1-intro.png | Bin 0 -> 9217 bytes guide/source/chapter1/color-demo.png | Bin 0 -> 71559 bytes guide/source/chapter1/index.rst | 13 + guide/source/chapter2/0intro.rst | 149 ++++ guide/source/chapter2/2application.rst | 214 ++++++ guide/source/chapter2/3batch-system.rst | 168 +++++ guide/source/chapter2/4trap-handling.rst | 519 +++++++++++++ guide/source/chapter2/5exercise.rst | 139 ++++ guide/source/chapter2/index.rst | 13 + guide/source/chapter3/0intro.rst | 209 ++++++ guide/source/chapter3/1multi-loader.rst | 71 ++ guide/source/chapter3/2task-switching.rst | 104 +++ guide/source/chapter3/3multiprogramming.rst | 317 ++++++++ .../source/chapter3/4time-sharing-system.rst | 161 +++++ guide/source/chapter3/5exercise.rst | 133 ++++ guide/source/chapter3/fsm-coop.png | Bin 0 -> 24175 bytes guide/source/chapter3/index.rst | 14 + guide/source/chapter3/multiprogramming.png | Bin 0 -> 20854 bytes guide/source/chapter4/0intro.rst | 143 ++++ .../chapter4/3sv39-implementation-1.rst | 216 ++++++ .../chapter4/4sv39-implementation-2.rst | 447 ++++++++++++ guide/source/chapter4/5kernel-app-spaces.rst | 586 +++++++++++++++ .../chapter4/6multitasking-based-on-as.rst | 684 ++++++++++++++++++ guide/source/chapter4/7exercise.rst | 113 +++ guide/source/chapter4/address-translation.png | Bin 0 -> 44213 bytes guide/source/chapter4/app-as-full.png | Bin 0 -> 34166 bytes guide/source/chapter4/index.rst | 12 + guide/source/chapter4/kernel-as-high.png | Bin 0 -> 34754 bytes guide/source/chapter4/kernel-as-low.png | Bin 0 -> 20344 bytes guide/source/chapter4/linear-table.png | Bin 0 -> 20340 bytes guide/source/chapter4/page-table.png | Bin 0 -> 53026 bytes guide/source/chapter4/pte-rwx.png | Bin 0 -> 44007 bytes guide/source/chapter4/rust-containers.png | Bin 0 -> 87375 bytes guide/source/chapter4/satp.png | Bin 0 -> 23634 bytes guide/source/chapter4/segmentation.png | Bin 0 -> 54739 bytes guide/source/chapter4/simple-base-bound.png | Bin 0 -> 44004 bytes guide/source/chapter4/sv39-full.png | Bin 0 -> 141865 bytes guide/source/chapter4/sv39-pte.png | Bin 0 -> 12849 bytes guide/source/chapter4/sv39-va-pa.png | Bin 0 -> 16067 bytes guide/source/chapter4/trie-1.png | Bin 0 -> 23035 bytes guide/source/chapter4/trie.png | Bin 0 -> 40076 bytes guide/source/chapter5/0intro.rst | 175 +++++ guide/source/chapter5/1process.rst | 230 ++++++ .../source/chapter5/2core-data-structures.rst | 540 ++++++++++++++ .../chapter5/3implement-process-mechanism.rst | 665 +++++++++++++++++ guide/source/chapter5/4exercise.rst | 137 ++++ guide/source/chapter5/index.rst | 12 + guide/source/chapter6/0intro.rst | 159 ++++ guide/source/chapter6/1file-descriptor.rst | 243 +++++++ guide/source/chapter6/1fs-interface.rst | 112 +++ .../source/chapter6/2fs-implementation-1.rst | 674 +++++++++++++++++ .../source/chapter6/2fs-implementation-2.rst | 591 +++++++++++++++ .../chapter6/3using-easy-fs-in-kernel.rst | 313 ++++++++ guide/source/chapter6/4exercise.rst | 114 +++ guide/source/chapter6/easy-fs-demo.png | Bin 0 -> 20644 bytes guide/source/chapter6/index.rst | 13 + guide/source/chapter7/0intro.rst | 118 +++ guide/source/chapter7/1pipe.rst | 364 ++++++++++ .../chapter7/2cmdargs-and-redirection.rst | 337 +++++++++ guide/source/chapter7/3exercise.rst | 20 + guide/source/chapter7/index.rst | 10 + guide/source/chapter7/user-stack-cmdargs.png | Bin 0 -> 16759 bytes guide/source/chapter7/user-stack-cmdargs.pptx | Bin 0 -> 50275 bytes guide/source/chapter8/0intro.rst | 239 ++++++ guide/source/chapter8/1thread-kernel.rst | 485 +++++++++++++ guide/source/chapter8/2lock.rst | 379 ++++++++++ guide/source/chapter8/3semaphore.rst | 275 +++++++ guide/source/chapter8/4condition-variable.rst | 300 ++++++++ guide/source/chapter8/5exercise.rst | 132 ++++ guide/source/chapter8/index.rst | 15 + guide/source/conf.py | 120 +++ guide/source/index.rst | 85 +++ guide/source/pygments-coloring.txt | 32 + guide/source/rest-example.rst | 76 ++ guide/source/setup-sphinx.rst | 16 + os1-ref/.cargo/config | 7 + os1-ref/Cargo.toml | 10 + os1-ref/Makefile | 49 ++ os1-ref/src/console.rs | 37 + os1-ref/src/entry.asm | 12 + os1-ref/src/lang_items.rs | 17 + os1-ref/src/linker.ld | 48 ++ os1-ref/src/logging.rs | 47 ++ os1-ref/src/main.rs | 49 ++ os1-ref/src/sbi.rs | 34 + os2-ref/.cargo/config | 7 + os2-ref/Cargo.toml | 12 + os2-ref/Makefile | 58 ++ os2-ref/build.rs | 56 ++ os2-ref/src/batch.rs | 141 ++++ os2-ref/src/console.rs | 37 + os2-ref/src/entry.asm | 12 + os2-ref/src/lang_items.rs | 17 + os2-ref/src/linker.ld | 48 ++ os2-ref/src/logging.rs | 47 ++ os2-ref/src/main.rs | 40 + os2-ref/src/sbi.rs | 34 + os2-ref/src/sync/mod.rs | 3 + os2-ref/src/sync/up.rs | 29 + os2-ref/src/syscall/fs.rs | 15 + os2-ref/src/syscall/mod.rs | 16 + os2-ref/src/syscall/process.rs | 6 + os2-ref/src/trap/context.rs | 25 + os2-ref/src/trap/mod.rs | 50 ++ os2-ref/src/trap/trap.S | 64 ++ os3-ref/.cargo/config | 7 + os3-ref/Cargo.toml | 13 + os3-ref/Makefile | 59 ++ os3-ref/build.rs | 59 ++ os3-ref/src/config.rs | 10 + os3-ref/src/console.rs | 35 + os3-ref/src/entry.asm | 12 + os3-ref/src/heap_alloc.rs | 26 + os3-ref/src/lang_items.rs | 20 + os3-ref/src/linker.ld | 48 ++ os3-ref/src/loader.rs | 101 +++ os3-ref/src/logging.rs | 45 ++ os3-ref/src/main.rs | 70 ++ os3-ref/src/sbi.rs | 45 ++ os3-ref/src/sync/mod.rs | 5 + os3-ref/src/sync/up.rs | 31 + os3-ref/src/syscall/fs.rs | 18 + os3-ref/src/syscall/mod.rs | 36 + os3-ref/src/syscall/process.rs | 48 ++ os3-ref/src/task/context.rs | 30 + os3-ref/src/task/mod.rs | 176 +++++ os3-ref/src/task/switch.S | 34 + os3-ref/src/task/switch.rs | 16 + os3-ref/src/task/task.rs | 20 + os3-ref/src/timer.rs | 23 + os3-ref/src/trap/context.rs | 28 + os3-ref/src/trap/mod.rs | 78 ++ os3-ref/src/trap/trap.S | 61 ++ os4-ref/.cargo/config | 7 + os4-ref/Cargo.toml | 17 + os4-ref/Makefile | 59 ++ os4-ref/build.rs | 60 ++ os4-ref/src/config.rs | 20 + os4-ref/src/console.rs | 35 + os4-ref/src/entry.asm | 12 + os4-ref/src/heap_alloc.rs | 26 + os4-ref/src/lang_items.rs | 20 + os4-ref/src/linker.ld | 53 ++ os4-ref/src/loader.rs | 26 + os4-ref/src/logging.rs | 45 ++ os4-ref/src/main.rs | 74 ++ os4-ref/src/mm/address.rs | 245 +++++++ os4-ref/src/mm/frame_allocator.rs | 136 ++++ os4-ref/src/mm/heap_allocator.rs | 51 ++ os4-ref/src/mm/memory_set.rs | 346 +++++++++ os4-ref/src/mm/mod.rs | 29 + os4-ref/src/mm/page_table.rs | 157 ++++ os4-ref/src/sbi.rs | 45 ++ os4-ref/src/sync/mod.rs | 5 + os4-ref/src/sync/up.rs | 31 + os4-ref/src/syscall/fs.rs | 21 + os4-ref/src/syscall/mod.rs | 42 ++ os4-ref/src/syscall/process.rs | 62 ++ os4-ref/src/task/context.rs | 28 + os4-ref/src/task/mod.rs | 193 +++++ os4-ref/src/task/switch.S | 34 + os4-ref/src/task/switch.rs | 16 + os4-ref/src/task/task.rs | 64 ++ os4-ref/src/timer.rs | 23 + os4-ref/src/trap/context.rs | 40 + os4-ref/src/trap/mod.rs | 115 +++ os4-ref/src/trap/trap.S | 69 ++ os5-ref/.cargo/config | 7 + os5-ref/Cargo.toml | 17 + os5-ref/Makefile | 55 ++ os5-ref/build.rs | 71 ++ os5-ref/src/config.rs | 13 + os5-ref/src/console.rs | 130 ++++ os5-ref/src/entry.asm | 12 + os5-ref/src/lang_items.rs | 29 + os5-ref/src/linker.ld | 53 ++ os5-ref/src/loader.rs | 71 ++ os5-ref/src/logging.rs | 45 ++ os5-ref/src/main.rs | 75 ++ os5-ref/src/mm/address.rs | 246 +++++++ os5-ref/src/mm/frame_allocator.rs | 136 ++++ os5-ref/src/mm/heap_allocator.rs | 51 ++ os5-ref/src/mm/memory_set.rs | 388 ++++++++++ os5-ref/src/mm/mod.rs | 29 + os5-ref/src/mm/page_table.rs | 198 +++++ os5-ref/src/sbi.rs | 45 ++ os5-ref/src/sync/mod.rs | 5 + os5-ref/src/sync/up.rs | 31 + os5-ref/src/syscall/fs.rs | 50 ++ os5-ref/src/syscall/mod.rs | 53 ++ os5-ref/src/syscall/process.rs | 144 ++++ os5-ref/src/task/context.rs | 32 + os5-ref/src/task/manager.rs | 47 ++ os5-ref/src/task/mod.rs | 99 +++ os5-ref/src/task/pid.rs | 116 +++ os5-ref/src/task/processor.rs | 105 +++ os5-ref/src/task/switch.S | 34 + os5-ref/src/task/switch.rs | 16 + os5-ref/src/task/task.rs | 199 +++++ os5-ref/src/timer.rs | 23 + os5-ref/src/trap/context.rs | 47 ++ os5-ref/src/trap/mod.rs | 131 ++++ os5-ref/src/trap/trap.S | 69 ++ os6-ref/.cargo/config | 7 + os6-ref/Cargo.toml | 18 + os6-ref/Makefile | 64 ++ os6-ref/build.rs | 6 + os6-ref/src/config.rs | 16 + os6-ref/src/console.rs | 130 ++++ os6-ref/src/drivers/block/mod.rs | 24 + os6-ref/src/drivers/block/virtio_blk.rs | 84 +++ os6-ref/src/drivers/mod.rs | 3 + os6-ref/src/entry.asm | 12 + os6-ref/src/fs/inode.rs | 169 +++++ os6-ref/src/fs/mod.rs | 43 ++ os6-ref/src/fs/stdio.rs | 48 ++ os6-ref/src/lang_items.rs | 29 + os6-ref/src/linker.ld | 53 ++ os6-ref/src/logging.rs | 45 ++ os6-ref/src/main.rs | 74 ++ os6-ref/src/mm/address.rs | 259 +++++++ os6-ref/src/mm/frame_allocator.rs | 136 ++++ os6-ref/src/mm/heap_allocator.rs | 51 ++ os6-ref/src/mm/memory_set.rs | 404 +++++++++++ os6-ref/src/mm/mod.rs | 29 + os6-ref/src/mm/page_table.rs | 260 +++++++ os6-ref/src/sbi.rs | 45 ++ os6-ref/src/sync/mod.rs | 5 + os6-ref/src/sync/up.rs | 31 + os6-ref/src/syscall/fs.rs | 93 +++ os6-ref/src/syscall/mod.rs | 64 ++ os6-ref/src/syscall/process.rs | 148 ++++ os6-ref/src/task/context.rs | 32 + os6-ref/src/task/manager.rs | 47 ++ os6-ref/src/task/mod.rs | 106 +++ os6-ref/src/task/pid.rs | 116 +++ os6-ref/src/task/processor.rs | 105 +++ os6-ref/src/task/switch.S | 34 + os6-ref/src/task/switch.rs | 16 + os6-ref/src/task/task.rs | 229 ++++++ os6-ref/src/timer.rs | 23 + os6-ref/src/trap/context.rs | 47 ++ os6-ref/src/trap/mod.rs | 131 ++++ os6-ref/src/trap/trap.S | 69 ++ os7-ref/.cargo/config | 7 + os7-ref/Cargo.toml | 18 + os7-ref/Makefile | 64 ++ os7-ref/build.rs | 6 + os7-ref/src/config.rs | 16 + os7-ref/src/console.rs | 130 ++++ os7-ref/src/drivers/block/mod.rs | 24 + os7-ref/src/drivers/block/virtio_blk.rs | 84 +++ os7-ref/src/drivers/mod.rs | 3 + os7-ref/src/entry.asm | 12 + os7-ref/src/fs/inode.rs | 169 +++++ os7-ref/src/fs/mod.rs | 45 ++ os7-ref/src/fs/pipe.rs | 179 +++++ os7-ref/src/fs/stdio.rs | 48 ++ os7-ref/src/lang_items.rs | 29 + os7-ref/src/linker.ld | 53 ++ os7-ref/src/logging.rs | 45 ++ os7-ref/src/main.rs | 74 ++ os7-ref/src/mm/address.rs | 259 +++++++ os7-ref/src/mm/frame_allocator.rs | 136 ++++ os7-ref/src/mm/heap_allocator.rs | 51 ++ os7-ref/src/mm/memory_set.rs | 404 +++++++++++ os7-ref/src/mm/mod.rs | 29 + os7-ref/src/mm/page_table.rs | 260 +++++++ os7-ref/src/sbi.rs | 45 ++ os7-ref/src/sync/mod.rs | 5 + os7-ref/src/sync/up.rs | 31 + os7-ref/src/syscall/fs.rs | 122 ++++ os7-ref/src/syscall/mod.rs | 68 ++ os7-ref/src/syscall/process.rs | 160 ++++ os7-ref/src/task/context.rs | 32 + os7-ref/src/task/manager.rs | 47 ++ os7-ref/src/task/mod.rs | 106 +++ os7-ref/src/task/pid.rs | 116 +++ os7-ref/src/task/processor.rs | 105 +++ os7-ref/src/task/switch.S | 34 + os7-ref/src/task/switch.rs | 16 + os7-ref/src/task/task.rs | 255 +++++++ os7-ref/src/timer.rs | 23 + os7-ref/src/trap/context.rs | 47 ++ os7-ref/src/trap/mod.rs | 131 ++++ os7-ref/src/trap/trap.S | 69 ++ os8-ref/.cargo/config | 7 + os8-ref/Cargo.toml | 18 + os8-ref/Makefile | 64 ++ os8-ref/build.rs | 6 + os8-ref/src/config.rs | 14 + os8-ref/src/console.rs | 128 ++++ os8-ref/src/drivers/block/mod.rs | 24 + os8-ref/src/drivers/block/virtio_blk.rs | 84 +++ os8-ref/src/drivers/mod.rs | 3 + os8-ref/src/entry.asm | 12 + os8-ref/src/fs/inode.rs | 169 +++++ os8-ref/src/fs/mod.rs | 45 ++ os8-ref/src/fs/pipe.rs | 179 +++++ os8-ref/src/fs/stdio.rs | 48 ++ os8-ref/src/lang_items.rs | 29 + os8-ref/src/linker.ld | 53 ++ os8-ref/src/logging.rs | 45 ++ os8-ref/src/main.rs | 77 ++ os8-ref/src/mm/address.rs | 259 +++++++ os8-ref/src/mm/frame_allocator.rs | 137 ++++ os8-ref/src/mm/heap_allocator.rs | 51 ++ os8-ref/src/mm/memory_set.rs | 393 ++++++++++ os8-ref/src/mm/mod.rs | 29 + os8-ref/src/mm/page_table.rs | 260 +++++++ os8-ref/src/sbi.rs | 45 ++ os8-ref/src/sync/condvar.rs | 39 + os8-ref/src/sync/mod.rs | 11 + os8-ref/src/sync/mutex.rs | 88 +++ os8-ref/src/sync/semaphore.rs | 45 ++ os8-ref/src/sync/up.rs | 31 + os8-ref/src/syscall/fs.rs | 114 +++ os8-ref/src/syscall/mod.rs | 100 +++ os8-ref/src/syscall/process.rs | 158 ++++ os8-ref/src/syscall/sync.rs | 143 ++++ os8-ref/src/syscall/thread.rs | 86 +++ os8-ref/src/task/context.rs | 33 + os8-ref/src/task/id.rs | 262 +++++++ os8-ref/src/task/kthread.rs | 76 ++ os8-ref/src/task/manager.rs | 46 ++ os8-ref/src/task/mod.rs | 158 ++++ os8-ref/src/task/process.rs | 280 +++++++ os8-ref/src/task/processor.rs | 121 ++++ os8-ref/src/task/stackless_coroutine.rs | 125 ++++ os8-ref/src/task/switch.S | 34 + os8-ref/src/task/switch.rs | 16 + os8-ref/src/task/task.rs | 140 ++++ os8-ref/src/timer.rs | 83 +++ os8-ref/src/trap/context.rs | 47 ++ os8-ref/src/trap/mod.rs | 133 ++++ os8-ref/src/trap/trap.S | 69 ++ 360 files changed, 32863 insertions(+), 1 deletion(-) create mode 100644 README.md create mode 100644 guide/.gitignore create mode 100644 guide/LICENSE create mode 100644 guide/Makefile create mode 100755 guide/all.sh create mode 100644 guide/make.bat create mode 100644 guide/requirements.txt create mode 100755 guide/show.sh create mode 100644 guide/source/0setup-devel-env.rst create mode 100644 guide/source/_static/dracula.css create mode 100644 guide/source/_static/my_style.css create mode 100644 guide/source/appendix-a/index.rst create mode 100644 guide/source/appendix-b/index.rst create mode 100644 guide/source/appendix-c/index.rst create mode 100644 guide/source/appendix-d/index.rst create mode 100644 guide/source/chapter1/0intro.rst create mode 100644 guide/source/chapter1/1app-ee-platform.rst create mode 100644 guide/source/chapter1/2remove-std.rst create mode 100644 guide/source/chapter1/3mini-rt-usrland.rst create mode 100644 guide/source/chapter1/4mini-rt-baremetal.rst create mode 100644 guide/source/chapter1/5exercise.rst create mode 100644 guide/source/chapter1/app-software-stack.png create mode 100644 guide/source/chapter1/chap1-intro.png create mode 100644 guide/source/chapter1/color-demo.png create mode 100644 guide/source/chapter1/index.rst create mode 100644 guide/source/chapter2/0intro.rst create mode 100644 guide/source/chapter2/2application.rst create mode 100644 guide/source/chapter2/3batch-system.rst create mode 100644 guide/source/chapter2/4trap-handling.rst create mode 100644 guide/source/chapter2/5exercise.rst create mode 100644 guide/source/chapter2/index.rst create mode 100644 guide/source/chapter3/0intro.rst create mode 100644 guide/source/chapter3/1multi-loader.rst create mode 100644 guide/source/chapter3/2task-switching.rst create mode 100644 guide/source/chapter3/3multiprogramming.rst create mode 100644 guide/source/chapter3/4time-sharing-system.rst create mode 100644 guide/source/chapter3/5exercise.rst create mode 100644 guide/source/chapter3/fsm-coop.png create mode 100644 guide/source/chapter3/index.rst create mode 100644 guide/source/chapter3/multiprogramming.png create mode 100644 guide/source/chapter4/0intro.rst create mode 100644 guide/source/chapter4/3sv39-implementation-1.rst create mode 100644 guide/source/chapter4/4sv39-implementation-2.rst create mode 100644 guide/source/chapter4/5kernel-app-spaces.rst create mode 100644 guide/source/chapter4/6multitasking-based-on-as.rst create mode 100644 guide/source/chapter4/7exercise.rst create mode 100644 guide/source/chapter4/address-translation.png create mode 100644 guide/source/chapter4/app-as-full.png create mode 100644 guide/source/chapter4/index.rst create mode 100644 guide/source/chapter4/kernel-as-high.png create mode 100644 guide/source/chapter4/kernel-as-low.png create mode 100644 guide/source/chapter4/linear-table.png create mode 100644 guide/source/chapter4/page-table.png create mode 100644 guide/source/chapter4/pte-rwx.png create mode 100644 guide/source/chapter4/rust-containers.png create mode 100644 guide/source/chapter4/satp.png create mode 100644 guide/source/chapter4/segmentation.png create mode 100755 guide/source/chapter4/simple-base-bound.png create mode 100644 guide/source/chapter4/sv39-full.png create mode 100644 guide/source/chapter4/sv39-pte.png create mode 100644 guide/source/chapter4/sv39-va-pa.png create mode 100644 guide/source/chapter4/trie-1.png create mode 100644 guide/source/chapter4/trie.png create mode 100644 guide/source/chapter5/0intro.rst create mode 100644 guide/source/chapter5/1process.rst create mode 100644 guide/source/chapter5/2core-data-structures.rst create mode 100644 guide/source/chapter5/3implement-process-mechanism.rst create mode 100644 guide/source/chapter5/4exercise.rst create mode 100644 guide/source/chapter5/index.rst create mode 100644 guide/source/chapter6/0intro.rst create mode 100644 guide/source/chapter6/1file-descriptor.rst create mode 100644 guide/source/chapter6/1fs-interface.rst create mode 100644 guide/source/chapter6/2fs-implementation-1.rst create mode 100644 guide/source/chapter6/2fs-implementation-2.rst create mode 100644 guide/source/chapter6/3using-easy-fs-in-kernel.rst create mode 100644 guide/source/chapter6/4exercise.rst create mode 100644 guide/source/chapter6/easy-fs-demo.png create mode 100644 guide/source/chapter6/index.rst create mode 100644 guide/source/chapter7/0intro.rst create mode 100644 guide/source/chapter7/1pipe.rst create mode 100644 guide/source/chapter7/2cmdargs-and-redirection.rst create mode 100644 guide/source/chapter7/3exercise.rst create mode 100644 guide/source/chapter7/index.rst create mode 100644 guide/source/chapter7/user-stack-cmdargs.png create mode 100644 guide/source/chapter7/user-stack-cmdargs.pptx create mode 100644 guide/source/chapter8/0intro.rst create mode 100644 guide/source/chapter8/1thread-kernel.rst create mode 100644 guide/source/chapter8/2lock.rst create mode 100644 guide/source/chapter8/3semaphore.rst create mode 100644 guide/source/chapter8/4condition-variable.rst create mode 100644 guide/source/chapter8/5exercise.rst create mode 100644 guide/source/chapter8/index.rst create mode 100644 guide/source/conf.py create mode 100644 guide/source/index.rst create mode 100644 guide/source/pygments-coloring.txt create mode 100644 guide/source/rest-example.rst create mode 100644 guide/source/setup-sphinx.rst create mode 100644 os1-ref/.cargo/config create mode 100644 os1-ref/Cargo.toml create mode 100644 os1-ref/Makefile create mode 100644 os1-ref/src/console.rs create mode 100644 os1-ref/src/entry.asm create mode 100644 os1-ref/src/lang_items.rs create mode 100644 os1-ref/src/linker.ld create mode 100644 os1-ref/src/logging.rs create mode 100644 os1-ref/src/main.rs create mode 100644 os1-ref/src/sbi.rs create mode 100644 os2-ref/.cargo/config create mode 100644 os2-ref/Cargo.toml create mode 100644 os2-ref/Makefile create mode 100644 os2-ref/build.rs create mode 100644 os2-ref/src/batch.rs create mode 100644 os2-ref/src/console.rs create mode 100644 os2-ref/src/entry.asm create mode 100644 os2-ref/src/lang_items.rs create mode 100644 os2-ref/src/linker.ld create mode 100644 os2-ref/src/logging.rs create mode 100644 os2-ref/src/main.rs create mode 100644 os2-ref/src/sbi.rs create mode 100644 os2-ref/src/sync/mod.rs create mode 100644 os2-ref/src/sync/up.rs create mode 100644 os2-ref/src/syscall/fs.rs create mode 100644 os2-ref/src/syscall/mod.rs create mode 100644 os2-ref/src/syscall/process.rs create mode 100644 os2-ref/src/trap/context.rs create mode 100644 os2-ref/src/trap/mod.rs create mode 100644 os2-ref/src/trap/trap.S create mode 100644 os3-ref/.cargo/config create mode 100644 os3-ref/Cargo.toml create mode 100644 os3-ref/Makefile create mode 100644 os3-ref/build.rs create mode 100644 os3-ref/src/config.rs create mode 100644 os3-ref/src/console.rs create mode 100644 os3-ref/src/entry.asm create mode 100644 os3-ref/src/heap_alloc.rs create mode 100644 os3-ref/src/lang_items.rs create mode 100644 os3-ref/src/linker.ld create mode 100644 os3-ref/src/loader.rs create mode 100644 os3-ref/src/logging.rs create mode 100644 os3-ref/src/main.rs create mode 100644 os3-ref/src/sbi.rs create mode 100644 os3-ref/src/sync/mod.rs create mode 100644 os3-ref/src/sync/up.rs create mode 100644 os3-ref/src/syscall/fs.rs create mode 100644 os3-ref/src/syscall/mod.rs create mode 100644 os3-ref/src/syscall/process.rs create mode 100644 os3-ref/src/task/context.rs create mode 100644 os3-ref/src/task/mod.rs create mode 100644 os3-ref/src/task/switch.S create mode 100644 os3-ref/src/task/switch.rs create mode 100644 os3-ref/src/task/task.rs create mode 100644 os3-ref/src/timer.rs create mode 100644 os3-ref/src/trap/context.rs create mode 100644 os3-ref/src/trap/mod.rs create mode 100644 os3-ref/src/trap/trap.S create mode 100644 os4-ref/.cargo/config create mode 100644 os4-ref/Cargo.toml create mode 100644 os4-ref/Makefile create mode 100644 os4-ref/build.rs create mode 100644 os4-ref/src/config.rs create mode 100644 os4-ref/src/console.rs create mode 100644 os4-ref/src/entry.asm create mode 100644 os4-ref/src/heap_alloc.rs create mode 100644 os4-ref/src/lang_items.rs create mode 100644 os4-ref/src/linker.ld create mode 100644 os4-ref/src/loader.rs create mode 100644 os4-ref/src/logging.rs create mode 100644 os4-ref/src/main.rs create mode 100644 os4-ref/src/mm/address.rs create mode 100644 os4-ref/src/mm/frame_allocator.rs create mode 100644 os4-ref/src/mm/heap_allocator.rs create mode 100644 os4-ref/src/mm/memory_set.rs create mode 100644 os4-ref/src/mm/mod.rs create mode 100644 os4-ref/src/mm/page_table.rs create mode 100644 os4-ref/src/sbi.rs create mode 100644 os4-ref/src/sync/mod.rs create mode 100644 os4-ref/src/sync/up.rs create mode 100644 os4-ref/src/syscall/fs.rs create mode 100644 os4-ref/src/syscall/mod.rs create mode 100644 os4-ref/src/syscall/process.rs create mode 100644 os4-ref/src/task/context.rs create mode 100644 os4-ref/src/task/mod.rs create mode 100644 os4-ref/src/task/switch.S create mode 100644 os4-ref/src/task/switch.rs create mode 100644 os4-ref/src/task/task.rs create mode 100644 os4-ref/src/timer.rs create mode 100644 os4-ref/src/trap/context.rs create mode 100644 os4-ref/src/trap/mod.rs create mode 100644 os4-ref/src/trap/trap.S create mode 100644 os5-ref/.cargo/config create mode 100644 os5-ref/Cargo.toml create mode 100644 os5-ref/Makefile create mode 100644 os5-ref/build.rs create mode 100644 os5-ref/src/config.rs create mode 100644 os5-ref/src/console.rs create mode 100644 os5-ref/src/entry.asm create mode 100644 os5-ref/src/lang_items.rs create mode 100644 os5-ref/src/linker.ld create mode 100644 os5-ref/src/loader.rs create mode 100644 os5-ref/src/logging.rs create mode 100644 os5-ref/src/main.rs create mode 100644 os5-ref/src/mm/address.rs create mode 100644 os5-ref/src/mm/frame_allocator.rs create mode 100644 os5-ref/src/mm/heap_allocator.rs create mode 100644 os5-ref/src/mm/memory_set.rs create mode 100644 os5-ref/src/mm/mod.rs create mode 100644 os5-ref/src/mm/page_table.rs create mode 100644 os5-ref/src/sbi.rs create mode 100644 os5-ref/src/sync/mod.rs create mode 100644 os5-ref/src/sync/up.rs create mode 100644 os5-ref/src/syscall/fs.rs create mode 100644 os5-ref/src/syscall/mod.rs create mode 100644 os5-ref/src/syscall/process.rs create mode 100644 os5-ref/src/task/context.rs create mode 100644 os5-ref/src/task/manager.rs create mode 100644 os5-ref/src/task/mod.rs create mode 100644 os5-ref/src/task/pid.rs create mode 100644 os5-ref/src/task/processor.rs create mode 100644 os5-ref/src/task/switch.S create mode 100644 os5-ref/src/task/switch.rs create mode 100644 os5-ref/src/task/task.rs create mode 100644 os5-ref/src/timer.rs create mode 100644 os5-ref/src/trap/context.rs create mode 100644 os5-ref/src/trap/mod.rs create mode 100644 os5-ref/src/trap/trap.S create mode 100644 os6-ref/.cargo/config create mode 100644 os6-ref/Cargo.toml create mode 100644 os6-ref/Makefile create mode 100644 os6-ref/build.rs create mode 100644 os6-ref/src/config.rs create mode 100644 os6-ref/src/console.rs create mode 100644 os6-ref/src/drivers/block/mod.rs create mode 100644 os6-ref/src/drivers/block/virtio_blk.rs create mode 100644 os6-ref/src/drivers/mod.rs create mode 100644 os6-ref/src/entry.asm create mode 100644 os6-ref/src/fs/inode.rs create mode 100644 os6-ref/src/fs/mod.rs create mode 100644 os6-ref/src/fs/stdio.rs create mode 100644 os6-ref/src/lang_items.rs create mode 100644 os6-ref/src/linker.ld create mode 100644 os6-ref/src/logging.rs create mode 100644 os6-ref/src/main.rs create mode 100644 os6-ref/src/mm/address.rs create mode 100644 os6-ref/src/mm/frame_allocator.rs create mode 100644 os6-ref/src/mm/heap_allocator.rs create mode 100644 os6-ref/src/mm/memory_set.rs create mode 100644 os6-ref/src/mm/mod.rs create mode 100644 os6-ref/src/mm/page_table.rs create mode 100644 os6-ref/src/sbi.rs create mode 100644 os6-ref/src/sync/mod.rs create mode 100644 os6-ref/src/sync/up.rs create mode 100644 os6-ref/src/syscall/fs.rs create mode 100644 os6-ref/src/syscall/mod.rs create mode 100644 os6-ref/src/syscall/process.rs create mode 100644 os6-ref/src/task/context.rs create mode 100644 os6-ref/src/task/manager.rs create mode 100644 os6-ref/src/task/mod.rs create mode 100644 os6-ref/src/task/pid.rs create mode 100644 os6-ref/src/task/processor.rs create mode 100644 os6-ref/src/task/switch.S create mode 100644 os6-ref/src/task/switch.rs create mode 100644 os6-ref/src/task/task.rs create mode 100644 os6-ref/src/timer.rs create mode 100644 os6-ref/src/trap/context.rs create mode 100644 os6-ref/src/trap/mod.rs create mode 100644 os6-ref/src/trap/trap.S create mode 100644 os7-ref/.cargo/config create mode 100644 os7-ref/Cargo.toml create mode 100644 os7-ref/Makefile create mode 100644 os7-ref/build.rs create mode 100644 os7-ref/src/config.rs create mode 100644 os7-ref/src/console.rs create mode 100644 os7-ref/src/drivers/block/mod.rs create mode 100644 os7-ref/src/drivers/block/virtio_blk.rs create mode 100644 os7-ref/src/drivers/mod.rs create mode 100644 os7-ref/src/entry.asm create mode 100644 os7-ref/src/fs/inode.rs create mode 100644 os7-ref/src/fs/mod.rs create mode 100644 os7-ref/src/fs/pipe.rs create mode 100644 os7-ref/src/fs/stdio.rs create mode 100644 os7-ref/src/lang_items.rs create mode 100644 os7-ref/src/linker.ld create mode 100644 os7-ref/src/logging.rs create mode 100644 os7-ref/src/main.rs create mode 100644 os7-ref/src/mm/address.rs create mode 100644 os7-ref/src/mm/frame_allocator.rs create mode 100644 os7-ref/src/mm/heap_allocator.rs create mode 100644 os7-ref/src/mm/memory_set.rs create mode 100644 os7-ref/src/mm/mod.rs create mode 100644 os7-ref/src/mm/page_table.rs create mode 100644 os7-ref/src/sbi.rs create mode 100644 os7-ref/src/sync/mod.rs create mode 100644 os7-ref/src/sync/up.rs create mode 100644 os7-ref/src/syscall/fs.rs create mode 100644 os7-ref/src/syscall/mod.rs create mode 100644 os7-ref/src/syscall/process.rs create mode 100644 os7-ref/src/task/context.rs create mode 100644 os7-ref/src/task/manager.rs create mode 100644 os7-ref/src/task/mod.rs create mode 100644 os7-ref/src/task/pid.rs create mode 100644 os7-ref/src/task/processor.rs create mode 100644 os7-ref/src/task/switch.S create mode 100644 os7-ref/src/task/switch.rs create mode 100644 os7-ref/src/task/task.rs create mode 100644 os7-ref/src/timer.rs create mode 100644 os7-ref/src/trap/context.rs create mode 100644 os7-ref/src/trap/mod.rs create mode 100644 os7-ref/src/trap/trap.S create mode 100644 os8-ref/.cargo/config create mode 100644 os8-ref/Cargo.toml create mode 100644 os8-ref/Makefile create mode 100644 os8-ref/build.rs create mode 100644 os8-ref/src/config.rs create mode 100644 os8-ref/src/console.rs create mode 100644 os8-ref/src/drivers/block/mod.rs create mode 100644 os8-ref/src/drivers/block/virtio_blk.rs create mode 100644 os8-ref/src/drivers/mod.rs create mode 100644 os8-ref/src/entry.asm create mode 100644 os8-ref/src/fs/inode.rs create mode 100644 os8-ref/src/fs/mod.rs create mode 100644 os8-ref/src/fs/pipe.rs create mode 100644 os8-ref/src/fs/stdio.rs create mode 100644 os8-ref/src/lang_items.rs create mode 100644 os8-ref/src/linker.ld create mode 100644 os8-ref/src/logging.rs create mode 100644 os8-ref/src/main.rs create mode 100644 os8-ref/src/mm/address.rs create mode 100644 os8-ref/src/mm/frame_allocator.rs create mode 100644 os8-ref/src/mm/heap_allocator.rs create mode 100644 os8-ref/src/mm/memory_set.rs create mode 100644 os8-ref/src/mm/mod.rs create mode 100644 os8-ref/src/mm/page_table.rs create mode 100644 os8-ref/src/sbi.rs create mode 100644 os8-ref/src/sync/condvar.rs create mode 100644 os8-ref/src/sync/mod.rs create mode 100644 os8-ref/src/sync/mutex.rs create mode 100644 os8-ref/src/sync/semaphore.rs create mode 100644 os8-ref/src/sync/up.rs create mode 100644 os8-ref/src/syscall/fs.rs create mode 100644 os8-ref/src/syscall/mod.rs create mode 100644 os8-ref/src/syscall/process.rs create mode 100644 os8-ref/src/syscall/sync.rs create mode 100644 os8-ref/src/syscall/thread.rs create mode 100644 os8-ref/src/task/context.rs create mode 100644 os8-ref/src/task/id.rs create mode 100644 os8-ref/src/task/kthread.rs create mode 100644 os8-ref/src/task/manager.rs create mode 100644 os8-ref/src/task/mod.rs create mode 100644 os8-ref/src/task/process.rs create mode 100644 os8-ref/src/task/processor.rs create mode 100644 os8-ref/src/task/stackless_coroutine.rs create mode 100644 os8-ref/src/task/switch.S create mode 100644 os8-ref/src/task/switch.rs create mode 100644 os8-ref/src/task/task.rs create mode 100644 os8-ref/src/timer.rs create mode 100644 os8-ref/src/trap/context.rs create mode 100644 os8-ref/src/trap/mod.rs create mode 100644 os8-ref/src/trap/trap.S diff --git a/.gitignore b/.gitignore index c4929e4..2cdbe56 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +.vscode .idea Cargo.lock target @@ -6,4 +7,4 @@ os/last-* user ci-user/ tools -workplace/ \ No newline at end of file +workplace/ diff --git a/Makefile b/Makefile index 347ac58..103d75d 100644 --- a/Makefile +++ b/Makefile @@ -2,8 +2,19 @@ DOCKER_NAME ?= dinghao188/rcore-tutorial DIR := workplace .PHONY: docker build_docker + test: test3 test4 test5 test6 test7 test8 +lab1: test3 + +lab2: test4 + +lab3: test5 + +lab4: test6 test7 + +lab5: test8 + setup: rm -rf ${DIR} mkdir ${DIR} diff --git a/README.md b/README.md new file mode 100644 index 0000000..d67b1a3 --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +# rust-based os comp 2022 + +## Guide + +- Guide deployed version can be found [here](https://LearningOS.github.io/rCore-Tutorial-Guide-2022S/). +- Source of Guide is in 'guide' DIR + +## os reference framework +The 'os[1-8]-ref' are the 'os[1-8]' reference framework. You can read and copy some codes into os[1-8] + +## kernel labs +There are five kernel labs. + +According to the [Guide](https://LearningOS.github.io/rCore-Tutorial-Guide-2022S/), write os codes for: +- lab1 in 'os3' DIR +- lab2 in 'os4' DIR +- lab3 in 'os5' DIR +- lab4 in 'os6' DIR +- lab5 in 'os8' DIR + +## Check your results +- lab1: `make test3` +- lab2 `make test4` +- lab3 `make test5` +- lab4 `make test6` and `make test7` +- lab5 `make test8` \ No newline at end of file diff --git a/guide/.gitignore b/guide/.gitignore new file mode 100644 index 0000000..a32f3e9 --- /dev/null +++ b/guide/.gitignore @@ -0,0 +1,5 @@ +build/ +.vscode/ +.idea +source/_build/ +.venv/ \ No newline at end of file diff --git a/guide/LICENSE b/guide/LICENSE new file mode 100644 index 0000000..f288702 --- /dev/null +++ b/guide/LICENSE @@ -0,0 +1,674 @@ + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/guide/Makefile b/guide/Makefile new file mode 100644 index 0000000..9c17f0c --- /dev/null +++ b/guide/Makefile @@ -0,0 +1,23 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile deploy + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +view: + make html && firefox build/html/index.html diff --git a/guide/all.sh b/guide/all.sh new file mode 100755 index 0000000..cf20d3b --- /dev/null +++ b/guide/all.sh @@ -0,0 +1,2 @@ +make clean && make html && google-chrome build/html/index.html + diff --git a/guide/make.bat b/guide/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/guide/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/guide/requirements.txt b/guide/requirements.txt new file mode 100644 index 0000000..d61da19 --- /dev/null +++ b/guide/requirements.txt @@ -0,0 +1,28 @@ +alabaster==0.7.12 +Babel==2.9.1 +certifi==2021.5.30 +charset-normalizer==2.0.4 +docutils==0.16 +idna==3.2 +imagesize==1.2.0 +jieba==0.42.1 +Jinja2==3.0.1 +MarkupSafe==2.0.1 +packaging==21.0 +Pygments==2.10.0 +pyparsing==2.4.7 +pytz==2021.1 +requests==2.26.0 +snowballstemmer==2.1.0 +Sphinx==4.1.2 +sphinx-comments==0.0.3 +sphinx-rtd-theme==0.5.2 +sphinx-tabs==3.2.0 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==2.0.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.5 +urllib3==1.26.6 +furo==2021.8.31 diff --git a/guide/show.sh b/guide/show.sh new file mode 100755 index 0000000..207f71c --- /dev/null +++ b/guide/show.sh @@ -0,0 +1 @@ +make html && google-chrome build/html/index.html diff --git a/guide/source/0setup-devel-env.rst b/guide/source/0setup-devel-env.rst new file mode 100644 index 0000000..1a8d0da --- /dev/null +++ b/guide/source/0setup-devel-env.rst @@ -0,0 +1,267 @@ +第零章：实验环境配置 +================================ + +.. toctree:: + :hidden: + :maxdepth: 4 + +本节我们将完成环境配置并成功运行 rCore-Tutorial 。整个流程分为下面几个部分： + +- OS 环境配置 +- Rust 开发环境配置 +- Qemu 模拟器安装 +- 其他工具安装 +- 试运行 rCore-Tutorial + +如果你在环境配置中遇到了无法解决的问题，请在本节讨论区留言，我们会尽力提供帮助。 + +OS 环境配置 +------------------------------- + +目前，实验主要支持 Ubuntu18.04/20.04 操作系统。使用 Windows10 和 macOS 的读者，可以安装一台 Ubuntu18.04 虚拟机或 Docker +进行实验。 + +Windows10 用户可以通过系统内置的 **WSL2** 虚拟机（请不要使用 WSL1）来安装 Ubuntu 18.04 / 20.04 。读者请自行在互联网上搜索相关安装教程，或 `适用于 Linux 的 Windows 子系统安装指南 (Windows 10) `_ 。 + +.. note:: + + **Docker 开发环境** + + 感谢 dinghao188 和张汉东老师帮忙配置好的 Docker 开发环境，进入 Docker 开发环境之后不需要任何软件工具链的安装和配置，可以直接将 tutorial 运行起来，目前应该仅支持将 tutorial 运行在 Qemu 模拟器上。 + + 使用方法如下（以 Ubuntu18.04 为例）： + + 1. 通过 ``su`` 切换到管理员账户 ``root`` ； + 2. 在 ``rCore-Tutorial`` 根目录下 ``make docker`` 进入到 Docker 环境； + 3. 进入 Docker 之后，会发现当前处于根目录 ``/`` ，我们通过 ``cd mnt`` 将当前工作路径切换到 ``/mnt`` 目录； + 4. 通过 ``ls`` 可以发现 ``/mnt`` 目录下的内容和 ``rCore-Tutorial-v3`` 目录下的内容完全相同，接下来就可以在这个环境下运行 tutorial 了。例如 ``cd os && make run`` 。 + +使用 macOS 进行实验理论上也是可行的，但本章节仅介绍 Ubuntu 下的环境配置方案。 + +.. note:: + + 经初步测试，使用 M1 芯片的 macOS 也可以运行本实验的框架，即我们的实验对平台的要求不是很高。但我们仍建议同学配置 Ubuntu 环境，以避免未知的环境问题。 + +Rust 开发环境配置 +------------------------------------------- + +首先安装 Rust 版本管理器 rustup 和 Rust 包管理器 cargo，可以使用官方安装脚本： + +.. code-block:: bash + + curl https://sh.rustup.rs -sSf | sh + +如果因网络问题通过命令行下载脚本失败了，可以在浏览器地址栏中输入 ``_ 将脚本下载到本地运行。或者使用字节跳动提供的镜像源。 + +建议将 rustup 的镜像地址修改为中科大的镜像服务器，以加速安装： + +.. code-block:: bash + + export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static + export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup + curl https://sh.rustup.rs -sSf | sh + +或者使用 tuna 源来加速（建议清华同学在校园网中使用） `参见 rustup 帮助 `_： + +.. code-block:: bash + + export RUSTUP_DIST_SERVER=https://mirrors.tuna.edu.cn/rustup + export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.edu.cn/rustup/rustup + curl https://sh.rustup.rs -sSf | sh + +也可以设置科学上网代理： + +.. code-block:: bash + + # e.g. Shadowsocks 代理，请根据自身配置灵活调整下面的链接 + export https_proxy=http://127.0.0.1:1080 + export http_proxy=http://127.0.0.1:1080 + export ftp_proxy=http://127.0.0.1:1080 + +安装中全程选择默认选项即可。 + +安装完成后，我们可以重新打开一个终端来让新设置的环境变量生效，也可以手动将环境变量设置应用到当前终端， +只需输入以下命令： + +.. code-block:: bash + + source $HOME/.cargo/env + +确认一下我们正确安装了 Rust 工具链： + +.. code-block:: bash + + rustc --version + +最好把 Rust 包管理器 cargo 镜像地址 crates.io 也替换成中国科学技术大学的镜像服务器，来加速三方库的下载。 +打开或新建 ``~/.cargo/config`` 文件，并把内容修改为： + +.. code-block:: toml + + [source.crates-io] + registry = "https://github.com/rust-lang/crates.io-index" + replace-with = 'ustc' + [source.ustc] + registry = "git://mirrors.ustc.edu.cn/crates.io-index" + +同样，也可以使用tuna源 `参见 crates.io 帮助 `_： + +.. code-block:: toml + + [source.crates-io] + replace-with = 'tuna' + + [source.tuna] + registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git" + + +推荐 JetBrains Clion + Rust插件 或者 Visual Studio Code 搭配 rust-analyzer 和 RISC-V Support 插件 进行代码阅读和开发。 + +.. note:: + + * JetBrains Clion是付费商业软件，但对于学生和教师，只要在 JetBrains 网站注册账号，可以享受一定期限（半年左右）的免费使用的福利。 + * Visual Studio Code 是开源软件。 + * 当然，采用 VIM，Emacs 等传统的编辑器也是没有问题的。 + +Qemu 模拟器安装 +---------------------------------------- + +我们需要使用 Qemu 5.0.0 版本进行实验，为此，从源码手动编译安装 Qemu 模拟器： + +.. attention:: + + 也可以使用 Qemu6，但要小心潜在的不兼容问题！ + +.. code-block:: bash + + # 安装编译所需的依赖包 + sudo apt install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \ + gawk build-essential bison flex texinfo gperf libtool patchutils bc \ + zlib1g-dev libexpat-dev pkg-config libglib2.0-dev libpixman-1-dev git tmux python3 + # 下载源码包 + # 如果下载速度过慢可以使用我们提供的百度网盘链接：https://pan.baidu.com/s/1z-iWIPjxjxbdFS2Qf-NKxQ + # 提取码 8woe + wget https://download.qemu.org/qemu-5.0.0.tar.xz + # 解压 + tar xvJf qemu-5.0.0.tar.xz + # 编译安装并配置 RISC-V 支持 + cd qemu-5.0.0 + ./configure --target-list=riscv64-softmmu,riscv64-linux-user + make -j$(nproc) + +.. note:: + + 注意，上面的依赖包可能并不完全，比如在 Ubuntu 18.04 上： + + - 出现 ``ERROR: pkg-config binary 'pkg-config' not found`` 时，可以安装 ``pkg-config`` 包； + - 出现 ``ERROR: glib-2.48 gthread-2.0 is required to compile QEMU`` 时，可以安装 + ``libglib2.0-dev`` 包； + - 出现 ``ERROR: pixman >= 0.21.8 not present`` 时，可以安装 ``libpixman-1-dev`` 包。 + + 另外一些 Linux 发行版编译 Qemu 的依赖包可以从 `这里 `_ + 找到。 + + GCC 11 可能无法正常编译 Qemu5 ，而 GCC 9.3.0 (Ubuntu 20.04 自带) 及 GCC 10.3.0 经测试可以编译，请自行选择合适的编译器版本。 + +之后我们可以在同目录下 ``sudo make install`` 将 Qemu 安装到 ``/usr/local/bin`` 目录下，但这样经常会引起 +冲突。个人来说更习惯的做法是，编辑 ``~/.bashrc`` 文件（如果使用的是默认的 ``bash`` 终端），在文件的末尾加入 +几行： + +.. code-block:: bash + + # 请注意，qemu-5.0.0 的父目录可以随着你的实际安装位置灵活调整 + export PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-5.0.0 + export PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-5.0.0/riscv64-softmmu + export PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-5.0.0/riscv64-linux-user + +随后即可在当前终端 ``source ~/.bashrc`` 更新系统路径，或者直接重启一个新的终端。 + +确认 Qemu 的版本： + +.. code-block:: bash + + qemu-system-riscv64 --version + qemu-riscv64 --version + +试运行 rCore-Tutorial +------------------------------------------------------------ + +.. code-block:: bash + + git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S + cd rCore-Tutorial-Code-2022S + +我们先运行不需要处理用户代码的 ch1 分支： + +.. code-block:: bash + + git checkout ch1 + cd os + LOG=DEBUG make run + +如果你的环境配置正确，你应当会看到如下输出： + +.. code-block:: bash + + [rustsbi] RustSBI version 0.2.0-alpha.4 + .______ __ __ _______.___________. _______..______ __ + | _ \ | | | | / | | / || _ \ | | + | |_) | | | | | | (----`---| |----`| (----`| |_) || | + | / | | | | \ \ | | \ \ | _ < | | + | |\ \----.| `--' |.----) | | | .----) | | |_) || | + | _| `._____| \______/ |_______/ |__| |_______/ |______/ |__| + + [rustsbi] Implementation: RustSBI-QEMU Version 0.0.1 + [rustsbi-dtb] Hart count: cluster0 with 1 cores + [rustsbi] misa: RV64ACDFIMSU + [rustsbi] mideleg: ssoft, stimer, sext (0x222) + [rustsbi] medeleg: ima, ia, bkpt, la, sa, uecall, ipage, lpage, spage (0xb1ab) + [rustsbi] pmp0: 0x80000000 ..= 0x800fffff (rwx) + [rustsbi] pmp1: 0x80000000 ..= 0x807fffff (rwx) + [rustsbi] pmp2: 0x0 ..= 0xffffffffffffff (---) + [rustsbi] enter supervisor 0x80200000 + Hello, world! + [DEBUG] .rodata [0x80203000, 0x80205000) + [ INFO] .data [0x80205000, 0x80206000) + [ WARN] boot_stack [0x80206000, 0x80216000) + [ERROR] .bss [0x80216000, 0x80217000) + Panicked at src/main.rs:48 Shutdown machine! + +通常 rCore 会自动关闭 Qemu 。如果在某些情况下需要强制结束，可以先按下 ``Ctrl+A`` ，再按下 ``X`` 来退出 Qemu。 + +.. attention:: + + 请务必执行 ``make run``，这将为你安装一些上文没有提及的 Rust 包依赖。 + + 如果卡在了 + + .. code-block:: + + Updating git repository `https://github.com/rcore-os/riscv` + + 请通过更换 hosts 等方式解决科学上网问题，或者将 riscv 项目下载到本地，并修改 os/Cargo.toml 中的 riscv 包依赖路径 + + .. code-block:: + + [dependencies] + riscv = { path = "YOUR riscv PATH", features = ["inline-asm"] } + +恭喜你完成了实验环境的配置，可以开始阅读教程的正文部分了！ + +GDB 调试支持* +------------------------------ + +.. attention:: + + 使用 GDB debug 并不是必须的，你可以暂时跳过本小节。 + + + +在 ``os`` 目录下 ``make debug`` 可以调试我们的内核，这需要安装终端复用工具 ``tmux`` ，还需要基于 riscv64 平台的 gdb 调试器 ``riscv64-unknown-elf-gdb`` 。该调试器包含在 riscv64 gcc 工具链中，工具链的预编译版本可以在如下链接处下载： + +- `Ubuntu 平台 `_ +- `macOS 平台 `_ +- `Windows 平台 `_ +- `CentOS 平台 `_ + +解压后在 ``bin`` 目录下即可找到 ``riscv64-unknown-elf-gdb`` 以及另外一些常用工具 ``objcopy/objdump/readelf`` 等。 diff --git a/guide/source/_static/dracula.css b/guide/source/_static/dracula.css new file mode 100644 index 0000000..30def14 --- /dev/null +++ b/guide/source/_static/dracula.css @@ -0,0 +1,91 @@ +/* Dracula Theme v1.2.5 + * + * https://github.com/zenorocha/dracula-theme + * + * Copyright 2016, All rights reserved + * + * Code licensed under the MIT license + * http://zenorocha.mit-license.org + * + * @author Rob G + * @author Chris Bracco + * @author Zeno Rocha + */ + + .highlight .hll { background-color: #111110 } + .highlight { background: #282a36; color: #f8f8f2 } + .highlight .c { color: #6272a4 } /* Comment */ + .highlight .err { color: #f8f8f2 } /* Error */ + .highlight .g { color: #f8f8f2 } /* Generic */ + .highlight .k { color: #ff79c6 } /* Keyword */ + .highlight .l { color: #f8f8f2 } /* Literal */ + .highlight .n { color: #f8f8f2 } /* Name */ + .highlight .o { color: #ff79c6 } /* Operator */ + .highlight .x { color: #f8f8f2 } /* Other */ + .highlight .p { color: #f8f8f2 } /* Punctuation */ + .highlight .ch { color: #6272a4 } /* Comment.Hashbang */ + .highlight .cm { color: #6272a4 } /* Comment.Multiline */ + .highlight .cp { color: #ff79c6 } /* Comment.Preproc */ + .highlight .cpf { color: #6272a4 } /* Comment.PreprocFile */ + .highlight .c1 { color: #6272a4 } /* Comment.Single */ + .highlight .cs { color: #6272a4 } /* Comment.Special */ + .highlight .gd { color: #962e2f } /* Generic.Deleted */ + .highlight .ge { color: #f8f8f2; text-decoration: underline } /* Generic.Emph */ + .highlight .gr { color: #f8f8f2 } /* Generic.Error */ + .highlight .gh { color: #f8f8f2; font-weight: bold } /* Generic.Heading */ + .highlight .gi { color: #f8f8f2; font-weight: bold } /* Generic.Inserted */ + .highlight .go { color: #44475a } /* Generic.Output */ + .highlight .gp { color: #f8f8f2 } /* Generic.Prompt */ + .highlight .gs { color: #f8f8f2 } /* Generic.Strong */ + .highlight .gu { color: #f8f8f2; font-weight: bold } /* Generic.Subheading */ + .highlight .gt { color: #f8f8f2 } /* Generic.Traceback */ + .highlight .kc { color: #ff79c6 } /* Keyword.Constant */ + .highlight .kd { color: #8be9fd; font-style: italic } /* Keyword.Declaration */ + .highlight .kn { color: #ff79c6 } /* Keyword.Namespace */ + .highlight .kp { color: #ff79c6 } /* Keyword.Pseudo */ + .highlight .kr { color: #ff79c6 } /* Keyword.Reserved */ + .highlight .kt { color: #8be9fd } /* Keyword.Type */ + .highlight .ld { color: #f8f8f2 } /* Literal.Date */ + .highlight .m { color: #bd93f9 } /* Literal.Number */ + .highlight .s { color: #f1fa8c } /* Literal.String */ + .highlight .na { color: #50fa7b } /* Name.Attribute */ + .highlight .nb { color: #8be9fd; font-style: italic } /* Name.Builtin */ + .highlight .nc { color: #50fa7b } /* Name.Class */ + .highlight .no { color: #f8f8f2 } /* Name.Constant */ + .highlight .nd { color: #f8f8f2 } /* Name.Decorator */ + .highlight .ni { color: #f8f8f2 } /* Name.Entity */ + .highlight .ne { color: #f8f8f2 } /* Name.Exception */ + .highlight .nf { color: #50fa7b } /* Name.Function */ + .highlight .nl { color: #8be9fd; font-style: italic } /* Name.Label */ + .highlight .nn { color: #f8f8f2 } /* Name.Namespace */ + .highlight .nx { color: #f8f8f2 } /* Name.Other */ + .highlight .py { color: #f8f8f2 } /* Name.Property */ + .highlight .nt { color: #ff79c6 } /* Name.Tag */ + .highlight .nv { color: #8be9fd; font-style: italic } /* Name.Variable */ + .highlight .ow { color: #ff79c6 } /* Operator.Word */ + .highlight .w { color: #f8f8f2 } /* Text.Whitespace */ + .highlight .mb { color: #bd93f9 } /* Literal.Number.Bin */ + .highlight .mf { color: #bd93f9 } /* Literal.Number.Float */ + .highlight .mh { color: #bd93f9 } /* Literal.Number.Hex */ + .highlight .mi { color: #bd93f9 } /* Literal.Number.Integer */ + .highlight .mo { color: #bd93f9 } /* Literal.Number.Oct */ + .highlight .sa { color: #f1fa8c } /* Literal.String.Affix */ + .highlight .sb { color: #f1fa8c } /* Literal.String.Backtick */ + .highlight .sc { color: #f1fa8c } /* Literal.String.Char */ + .highlight .dl { color: #f1fa8c } /* Literal.String.Delimiter */ + .highlight .sd { color: #f1fa8c } /* Literal.String.Doc */ + .highlight .s2 { color: #f1fa8c } /* Literal.String.Double */ + .highlight .se { color: #f1fa8c } /* Literal.String.Escape */ + .highlight .sh { color: #f1fa8c } /* Literal.String.Heredoc */ + .highlight .si { color: #f1fa8c } /* Literal.String.Interpol */ + .highlight .sx { color: #f1fa8c } /* Literal.String.Other */ + .highlight .sr { color: #f1fa8c } /* Literal.String.Regex */ + .highlight .s1 { color: #f1fa8c } /* Literal.String.Single */ + .highlight .ss { color: #f1fa8c } /* Literal.String.Symbol */ + .highlight .bp { color: #f8f8f2; font-style: italic } /* Name.Builtin.Pseudo */ + .highlight .fm { color: #50fa7b } /* Name.Function.Magic */ + .highlight .vc { color: #8be9fd; font-style: italic } /* Name.Variable.Class */ + .highlight .vg { color: #8be9fd; font-style: italic } /* Name.Variable.Global */ + .highlight .vi { color: #8be9fd; font-style: italic } /* Name.Variable.Instance */ + .highlight .vm { color: #8be9fd; font-style: italic } /* Name.Variable.Magic */ + .highlight .il { color: #bd93f9 } /* Literal.Number.Integer.Long */ diff --git a/guide/source/_static/my_style.css b/guide/source/_static/my_style.css new file mode 100644 index 0000000..8aa6c28 --- /dev/null +++ b/guide/source/_static/my_style.css @@ -0,0 +1,3 @@ +.wy-nav-content { + max-width: 1200px !important; +} diff --git a/guide/source/appendix-a/index.rst b/guide/source/appendix-a/index.rst new file mode 100644 index 0000000..23d27b2 --- /dev/null +++ b/guide/source/appendix-a/index.rst @@ -0,0 +1,56 @@ +附录 A：Rust 系统编程资料 +============================= + +.. toctree:: + :hidden: + :maxdepth: 4 + + +.. .. note:: + +.. **Rust 语法卡片：外部符号引用** + +.. extern "C" 可以引用一个外部的 C 函数接口（这意味着调用它的时候要遵从目标平台的 C 语言调用规范）。但我们这里只是引用位置标志 +.. 并将其转成 usize 获取它的地址。由此可以知道 ``.bss`` 段两端的地址。 + +.. **Rust 语法卡片：迭代器与闭包** + +.. 代码第 7 行用到了 Rust 的迭代器与闭包的语法，它们在很多情况下能够提高开发效率。如读者感兴趣的话也可以将其改写为等价的 for +.. 循环实现。 + +.. .. _term-raw-pointer: +.. .. _term-dereference: +.. .. warning:: + +.. **Rust 语法卡片：Unsafe** + +.. 代码第 8 行，我们将 ``.bss`` 段内的一个地址转化为一个 **裸指针** (Raw Pointer)，并将它指向的值修改为 0。这在 C 语言中是 +.. 一种司空见惯的操作，但在 Rust 中我们需要将他包裹在 unsafe 块中。这是因为，Rust 认为对于裸指针的 **解引用** (Dereference) +.. 是一种 unsafe 行为。 + +.. 相比 C 语言，Rust 进行了更多的语义约束来保证安全性（内存安全/类型安全/并发安全），这在编译期和运行期都有所体现。但在某些时候， +.. 尤其是与底层硬件打交道的时候，在 Rust 的语义约束之内没法满足我们的需求，这个时候我们就需要将超出了 Rust 语义约束的行为包裹 +.. 在 unsafe 块中，告知编译器不需要对它进行完整的约束检查，而是由程序员自己负责保证它的安全性。当代码不能正常运行的时候，我们往往也是 +.. 最先去检查 unsafe 块中的代码，因为它没有受到编译器的保护，出错的概率更大。 + +.. C 语言中的指针相当于 Rust 中的裸指针，它无所不能但又太过于灵活，程序员对其不谨慎的使用常常会引起很多内存不安全问题，最常见的如 +.. 悬垂指针和多次回收的问题，Rust 编译器没法确认程序员对它的使用是否安全，因此将其划到 unsafe Rust 的领域。在 safe Rust 中，我们 +.. 有引用 ``&/&mut`` 以及各种功能各异的智能指针 ``Box/RefCell/Rc`` 可以使用，只要按照 Rust 的规则来使用它们便可借助 +.. 编译器在编译期就解决很多潜在的内存不安全问题。 + +Rust编程相关 +-------------------------------- + +- `OS Tutorial Summer of Code 2020：Rust系统编程入门指导 `_ +- `Stanford 新开的一门很值得学习的 Rust 入门课程 `_ +- `一份简单的 Rust 入门介绍 `_ +- `《RustOS Guide》中的 Rust 介绍部分 `_ +- `一份简单的Rust宏编程新手指南 `_ + + +Rust系统编程pattern +--------------------------------- + +- `Arc> in Rust `_ +- `Understanding Closures in Rust `_ +- `Closures in Rust `_ \ No newline at end of file diff --git a/guide/source/appendix-b/index.rst b/guide/source/appendix-b/index.rst new file mode 100644 index 0000000..22d9e13 --- /dev/null +++ b/guide/source/appendix-b/index.rst @@ -0,0 +1,318 @@ +附录 B：常见工具的使用方法 +======================================== + +.. toctree:: + :hidden: + :maxdepth: 4 + + + +分析可执行文件 +------------------------ + +对于Rust编译器生成的执行程序，可通过各种有效工具进行分析。如果掌握了对这些工具的使用，那么在后续的开发工作中，对碰到的各种奇怪问题就进行灵活处理和解决了。 +我们以Rust编译生成的一个简单的“Hello, world”应用执行程序为分析对象，看看如何进行分析。 + +让我们先来通过 ``file`` 工具看看最终生成的可执行文件的格式： + +.. code-block:: console + + $ cargo new os + $ cd os; cargo build + Compiling os v0.1.0 (/tmp/os) + Finished dev [unoptimized + debuginfo] target(s) in 0.26s + + $ file target/debug/os + target/debug/os: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, + interpreter /lib64/ld-linux-x86-64.so.2, ...... + + $ + +.. _term-elf: +.. _term-metadata: + +从中可以看出可执行文件的格式为 **可执行和链接格式** (Executable and Linkable Format, ELF)，硬件平台是 x86-64。在 ELF 文件中， +除了程序必要的代码、数据段（它们本身都只是一些二进制的数据）之外，还有一些 **元数据** (Metadata) 描述这些段在地址空间中的位置和在 +文件中的位置以及一些权限控制信息，这些元数据只能放在代码、数据段的外面。 + +rust-readobj +^^^^^^^^^^^^^^^^^^^^^^^ + +我们可以通过二进制工具 ``rust-readobj`` 来看看 ELF 文件中究竟包含什么内容，输入命令： + +.. code-block:: console + + $ rust-readobj -all target/debug/os + +首先可以看到一个 ELF header，它位于 ELF 文件的开头： + +.. code-block:: objdump + :linenos: + :emphasize-lines: 8,19,20,21,24,25,26,27 + + File: target/debug/os + Format: elf64-x86-64 + Arch: x86_64 + AddressSize: 64bit + LoadName: + ElfHeader { + Ident { + Magic: (7F 45 4C 46) + Class: 64-bit (0x2) + DataEncoding: LittleEndian (0x1) + FileVersion: 1 + OS/ABI: SystemV (0x0) + ABIVersion: 0 + Unused: (00 00 00 00 00 00 00) + } + Type: SharedObject (0x3) + Machine: EM_X86_64 (0x3E) + Version: 1 + Entry: 0x5070 + ProgramHeaderOffset: 0x40 + SectionHeaderOffset: 0x32D8D0 + Flags [ (0x0) + ] + HeaderSize: 64 + ProgramHeaderEntrySize: 56 + ProgramHeaderCount: 12 + SectionHeaderEntrySize: 64 + SectionHeaderCount: 42 + StringTableSectionIndex: 41 + } + ...... + +.. _term-magic: + +- 第 8 行是一个称之为 **魔数** (Magic) 独特的常数，存放在 ELF header 的一个固定位置。当加载器将 ELF 文件加载到内存之前，通常会查看 + 该位置的值是否正确，来快速确认被加载的文件是不是一个 ELF 。 +- 第 19 行给出了可执行文件的入口点为 ``0x5070`` 。 +- 从 20-21 行中，我们可以知道除了 ELF header 之外，还有另外两种不同的 header，分别称为 program header 和 section header， + 它们都有多个。ELF header 中给出了其他两种header 的大小、在文件中的位置以及数目。 +- 从 24-27 行中，可以看到有 12 个不同的 program header，它们从文件的 0x40 字节偏移处开始，每个 56 字节； + 有64个section header,它们从文件的 0x2D8D0 字节偏移处开始，每个 64 字节； + + +有多个不同的 section header，下面是个具体的例子： + +.. code-block:: objdump + + ...... + Section { + Index: 14 + Name: .text (157) + Type: SHT_PROGBITS (0x1) + Flags [ (0x6) + SHF_ALLOC (0x2) + SHF_EXECINSTR (0x4) + ] + Address: 0x5070 + Offset: 0x5070 + Size: 208067 + Link: 0 + Info: 0 + AddressAlignment: 16 + EntrySize: 0 + } + + +每个 section header 则描述一个段的元数据。 + +其中，我们看到了代码段 ``.text`` 需要被加载到地址 ``0x5070`` ,大小 208067 字节，。 +它们分别由元数据的字段 Offset、 Size 和 Address 给出。。 + +我们还能够看到程序中的符号表： + +.. code-block:: + + Symbol { + Name: _start (37994) + Value: 0x5070 + Size: 47 + Binding: Global (0x1) + Type: Function (0x2) + Other: 0 + Section: .text (0xE) + } + Symbol { + Name: main (38021) + Value: 0x51A0 + Size: 47 + Binding: Global (0x1) + Type: Function (0x2) + Other: 0 + Section: .text (0xE) + } + +里面包括了我们写的 ``main`` 函数的地址以及用户态执行环境的起始地址 ``_start`` 函数的地址。 + +因此，从 ELF header 中可以看出，ELF 中的内容按顺序应该是： + +- ELF header +- 若干个 program header +- 程序各个段的实际数据 +- 若干的 section header + + +rust-objdump +^^^^^^^^^^^^^^^^^^^^^^^ + +如果想了解正常的ELF文件的具体指令内容，可以通过 ``rust-objdump`` 工具反汇编ELF文件得到： + +.. code-block:: console + + $ rust-objdump -all target/debug/os + +具体结果如下： + +.. code-block:: objdump + + 505b: e9 c0 ff ff ff jmp 0x5020 <.plt> + + Disassembly of section .plt.got: + + 0000000000005060 <.plt.got>: + 5060: ff 25 5a 3f 04 00 jmpq *278362(%rip) # 48fc0 <_GLOBAL_OFFSET_TABLE_+0x628> + 5066: 66 90 nop + + Disassembly of section .text: + + 0000000000005070 <_start>: + 5070: f3 0f 1e fa endbr64 + 5074: 31 ed xorl %ebp, %ebp + 5076: 49 89 d1 movq %rdx, %r9 + 5079: 5e popq %rsi + 507a: 48 89 e2 movq %rsp, %rdx + 507d: 48 83 e4 f0 andq $-16, %rsp + 5081: 50 pushq %rax + 5082: 54 pushq %rsp + 5083: 4c 8d 05 86 2c 03 00 leaq 208006(%rip), %r8 # 37d10 <__libc_csu_fini> + 508a: 48 8d 0d 0f 2c 03 00 leaq 207887(%rip), %rcx # 37ca0 <__libc_csu_init> + 5091: 48 8d 3d 08 01 00 00 leaq 264(%rip), %rdi # 51a0
+ 5098: ff 15 d2 3b 04 00 callq *277458(%rip) # 48c70 <_GLOBAL_OFFSET_TABLE_+0x2d8> + ...... + 00000000000051a0
: + 51a0: 48 83 ec 18 subq $24, %rsp + 51a4: 8a 05 db 7a 03 00 movb 228059(%rip), %al # 3cc85 <__rustc_debug_gdb_scripts_section__> + 51aa: 48 63 cf movslq %edi, %rcx + 51ad: 48 8d 3d ac ff ff ff leaq -84(%rip), %rdi # 5160 <_ZN2os4main17h717a6a6e05a70248E> + 51b4: 48 89 74 24 10 movq %rsi, 16(%rsp) + 51b9: 48 89 ce movq %rcx, %rsi + 51bc: 48 8b 54 24 10 movq 16(%rsp), %rdx + 51c1: 88 44 24 0f movb %al, 15(%rsp) + 51c5: e8 f6 00 00 00 callq 0x52c0 <_ZN3std2rt10lang_start17hc258028f546a93a1E> + 51ca: 48 83 c4 18 addq $24, %rsp + 51ce: c3 retq + 51cf: 90 nop + ...... + +从上面的反汇编结果，我们可以看到用户态执行环境的入口函数 ``_start`` 以及应用程序的主函数 ``main`` 的地址和具体汇编代码内容。 + + +rust-objcopy +^^^^^^^^^^^^^^^^^^^^^^^ + +当前的ELF执行程序有许多与执行无直接关系的信息（如调试信息等），可以通过 ``rust-objcopy`` 工具来清除。 + +.. code-block:: console + + $ rust-objcopy --strip-all target/debug/os target/debug/os.bin + $ ls -l target/debug/os* + -rwxrwxr-x 2 chyyuu chyyuu 3334992 1月 19 22:26 target/debug/os + -rwxrwxr-x 1 chyyuu chyyuu 297200 1月 19 22:59 target/debug/os.bin + + $ ./target/debug/os.bin + Hello, world! + +可以看到，经过处理的ELF文件 ``os.bin`` 在文件长度上大大减少了，但也能正常执行。 + +另外，当将程序加载到内存的时候，对于每个 program header 所指向的区域，我们需要将对应的数据从文件复制到内存中。这就需要解析 ELF 的元数据 +才能知道数据在文件中的位置以及即将被加载到内存中的位置。但如果我们不需要从 ELF 中解析元数据就知道程序的内存布局 +（这个内存布局是我们按照需求自己指定的），我们可以手动完成加载任务。 + +具体的做法是利用 ``rust-objcopy`` 工具删除掉 ELF 文件中的 +所有 header 只保留各个段的实际数据得到一个没有任何符号的纯二进制镜像文件： + +.. code-block:: console + + $ rust-objcopy --strip-all target/debug/os -O binary target/debug/os.bin + + + +这样就生成了一个没有任何符号的纯二进制镜像文件。由于缺少了必要的元数据，我们的 ``file`` 工具也没有办法 +对它完成解析了。而后，我们可直接将这个二进制镜像文件手动载入到内存中合适位置即可。 + + + +qemu 平台上可执行文件和二进制镜像的生成流程 +---------------------------------------------- + + + +make & Makefile +^^^^^^^^^^^^^^^^^^^^^^^ + +首先我们还原一下可执行文件和二进制镜像的生成流程： + +.. code-block:: makefile + + # os/Makefile + TARGET := riscv64gc-unknown-none-elf + MODE := release + KERNEL_ELF := target/$(TARGET)/$(MODE)/os + KERNEL_BIN := $(KERNEL_ELF).bin + + $(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + + kernel: + @cargo build --release + +这里可以看出 ``KERNEL_ELF`` 保存最终可执行文件 ``os`` 的路径，而 ``KERNEL_BIN`` 保存只保留各个段数据的二进制镜像文件 ``os.bin`` +的路径。目标 ``kernel`` 直接通过 ``cargo build`` 以 release 模式最终可执行文件，目标 ``KERNEL_BIN`` 依赖于目标 ``kernel``，将 +可执行文件通过 ``rust-objcopy`` 工具加上适当的配置移除所有的 header 和符号得到二进制镜像。 + +我们可以通过 ``make run`` 直接在 qemu 上运行我们的应用程序，qemu 是一个虚拟机，它完整的模拟了一整套硬件平台，就像是一台真正的计算机 +一样，我们来看运行 qemu 的具体命令： + +.. code-block:: makefile + :linenos: + :emphasize-lines: 11,12,13,14,15 + + KERNEL_ENTRY_PA := 0x80020000 + + BOARD ?= qemu + SBI ?= rustsbi + BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + + run: run-inner + + run-inner: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + + + +qemu +^^^^^^^^^^^^^^^^^^^^^^^ + +注意其中高亮部分给出了传给 qemu 的参数。 + +- ``-machine`` 告诉 qemu 使用预设的硬件配置。在整个项目中我们将一直沿用该配置。 +- ``-bios`` 告诉 qemu 使用我们放在 ``bootloader`` 目录下的预编译版本作为 bootloader。 +- ``-device`` 则告诉 qemu 将二进制镜像加载到内存指定的位置。 + +可以先输入 Ctrl+A ，再输入 X 来退出 qemu 终端。 + +.. warning:: + + **FIXME：使用 GDB 跟踪 qemu 的运行状态** + +其他工具和文件格式说明的参考 +------------------------------------------------------- + +- `链接脚本(Linker Scripts)语法和规则解析(翻译自官方手册) `_ +- `Make 命令教程 `_ diff --git a/guide/source/appendix-c/index.rst b/guide/source/appendix-c/index.rst new file mode 100644 index 0000000..4a5d3ee --- /dev/null +++ b/guide/source/appendix-c/index.rst @@ -0,0 +1,18 @@ +附录 C：深入机器模式：RustSBI +================================================= + +.. toctree:: + :hidden: + :maxdepth: 4 + +RISC-V指令集的SBI标准规定了类Unix操作系统之下的运行环境规范。这个规范拥有多种实现，RustSBI是它的一种实现。 + +RISC-V架构中，存在着定义于操作系统之下的运行环境。这个运行环境不仅将引导启动RISC-V下的操作系统， 还将常驻后台，为操作系统提供一系列二进制接口，以便其获取和操作硬件信息。 RISC-V给出了此类环境和二进制接口的规范，称为“操作系统二进制接口”，即“SBI”。 + +SBI的实现是在M模式下运行的特定于平台的固件，它将管理S、U等特权上的程序或通用的操作系统。 + +RustSBI项目发起于鹏城实验室的“rCore代码之夏-2020”活动，它是完全由Rust语言开发的SBI实现。 现在它能够在支持的RISC-V设备上运行rCore教程和其它操作系统内核。 + +RustSBI项目的目标是，制作一个从固件启动的最小Rust语言SBI实现，为可能的复杂实现提供参考和支持。 RustSBI也可以作为一个库使用，帮助更多的SBI开发者适配自己的平台，以支持更多处理器核和片上系统。 + +当前项目实现源码：https://github.com/luojia65/rustsbi \ No newline at end of file diff --git a/guide/source/appendix-d/index.rst b/guide/source/appendix-d/index.rst new file mode 100644 index 0000000..135613d --- /dev/null +++ b/guide/source/appendix-d/index.rst @@ -0,0 +1,32 @@ +附录 D：RISC-V相关信息 +================================================= + +RISCV汇编相关 +----------------------------------------------- + +- `RISC-V Assembly Programmer's Manual `_ +- `RISC-V Low-level Test Suits `_ +- `CoreMark®-PRO comprehensive, advanced processor benchmark `_ +- `riscv-tests的使用 `_ + +RISCV硬件相关 +----------------------------------------------- + +Quick Reference + +- `Registers & ABI `_ +- `Interrupt `_ +- `ISA & Extensions `_ +- `Toolchain `_ +- `Control and Status Registers (CSRs) `_ +- `Accessing CSRs `_ +- `Assembler & Instructions `_ + +ISA + +- `User-Level ISA, Version 1.12 `_ +- `4 Supervisor-Level ISA, Version 1.12 `_ +- `Vector Extension `_ +- `RISC-V Bitmanip Extension `_ +- `External Debug `_ +- `ISA Resources `_ \ No newline at end of file diff --git a/guide/source/chapter1/0intro.rst b/guide/source/chapter1/0intro.rst new file mode 100644 index 0000000..f3a18d5 --- /dev/null +++ b/guide/source/chapter1/0intro.rst @@ -0,0 +1,96 @@ +引言 +===================== + +本章导读 +-------------------------- + +大多数程序员的职业生涯都从 ``Hello, world!`` 开始。 + +.. code-block:: + + printf("Hello world!\n"); + cout << "Hello world!\n"; + print("Hello world!") + System.out.println("Hello world!"); + echo "Hello world!" + println!("Hello world!"); + +然而，要用几行代码向世界问好，并不像表面上那么简单。 +``Hello, world!`` 程序能够编译运行，靠的是以 **编译器** 为主的开发环境和以 **操作系统** 为主的执行环境。 + +在本章中，我们将抽丝剥茧，一步步让 ``Hello, world!`` 程序脱离其依赖的执行环境， +编写一个能打印 ``Hello, world!`` 的 OS。这趟旅途将让我们对应用程序及其执行环境有更深入的理解。 + +.. attention:: + 实验指导书存在的目的是帮助读者理解框架代码。 + + 为便于测试，完成编程实验时，请以框架代码为基础，不必跟着文档从零开始编写内核。 + +为了做到这一步，首先需要让程序不依赖于标准库， +并通过编译。 + +接下来要让脱离了标准库的程序能输出（即支持 ``println!``)，这对程序的开发和调试至关重要。 +我们先在用户态下实现该功能，在 `此处 `_ 获取相关代码。 + +最后把程序移植到内核态，构建在裸机上支持输出的最小运行时环境。 + +实践体验 +--------------------------- + +本章一步步实现了支持打印字符串的简单操作系统。 + +获取本章代码： + +.. code-block:: console + + $ git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S + $ cd rCore-Tutorial-Code-2022S + $ git checkout ch1 + +运行本章代码，并设置日志级别为 ``TRACE``： + +.. code-block:: console + + $ cd os + $ make run LOG=TRACE + + +预期输出： + +.. figure:: color-demo.png + :align: center + +除了 ``Hello, world!`` 之外还有一些额外的信息，最后关机。 + +本章代码树 +------------------------------------------------ + + +.. code-block:: + + ├── bootloader (内核依赖的运行在 M 特权级的 SBI 实现，本项目中我们使用 RustSBI) + │   └── rustsbi-qemu.bin + ├── os + │   ├── Cargo.toml (cargo 项目配置文件) + │   ├── Makefile + │   └── src + │   ├── console.rs (将打印字符的 SBI 接口进一步封装实现更加强大的格式化输出) + │   ├── entry.asm (设置内核执行环境的的一段汇编代码) + │   ├── lang_items.rs (需要我们提供给 Rust 编译器的一些语义项，目前包含内核 panic 时的处理逻辑) + │   ├── linker.ld (控制内核内存布局的链接脚本以使内核运行在 qemu 虚拟机上) + │   ├── logging.rs (为本项目实现了日志功能) + │   ├── main.rs (内核主函数) + │   └── sbi.rs (封装底层 SBI 实现提供的 SBI 接口) + └── rust-toolchain (整个项目的工具链版本) + + cloc os + ------------------------------------------------------------------------------- + Language files blank comment code + ------------------------------------------------------------------------------- + Rust 5 25 6 155 + make 1 11 4 34 + Assembly 1 1 0 11 + TOML 1 2 1 7 + ------------------------------------------------------------------------------- + SUM: 8 39 11 207 + ------------------------------------------------------------------------------- \ No newline at end of file diff --git a/guide/source/chapter1/1app-ee-platform.rst b/guide/source/chapter1/1app-ee-platform.rst new file mode 100644 index 0000000..4ccd02b --- /dev/null +++ b/guide/source/chapter1/1app-ee-platform.rst @@ -0,0 +1,120 @@ +应用程序执行环境与平台支持 +================================================ + +.. toctree:: + :hidden: + :maxdepth: 5 + + +执行应用程序 +------------------------------- + +我们先从最简单的 Rust ``Hello, world`` 程序开始，用 Cargo 工具创建 Rust 项目。 + +.. code-block:: console + + $ cargo new os + +此时，项目的文件结构如下： + +.. code-block:: console + + $ tree os + os + ├── Cargo.toml + └── src + └── main.rs + + 1 directory, 2 files + +其中 ``Cargo.toml`` 中保存了项目的库依赖、作者信息等。 + +cargo 为我们准备好了 ``Hello world!`` 源代码： + +.. code-block:: rust + :linenos: + :caption: 最简单的 Rust 应用 + + fn main() { + println!("Hello, world!"); + } + +输入 ``cargo run`` 构建并运行项目： + +.. code-block:: console + + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + Finished dev [unoptimized + debuginfo] target(s) in 1.15s + Running `target/debug/os` + Hello, world! + +我们在屏幕上看到了一行 ``Hello, world!`` ，但为了打印出 ``Hello, world!``，我们需要的不止几行源代码。 + +理解应用程序执行环境 +------------------------------- + +在现代通用操作系统（如 Linux）上运行应用程序，需要多层次的执行环境栈支持： + + +.. figure:: app-software-stack.png + :align: center + + 应用程序执行环境栈：图中的白色块自上而下表示各级执行环境，黑色块则表示相邻两层执行环境之间的接口。 + 下层作为上层的执行环境，支持上层代码运行。 + +我们的应用程序通过调用标准库或第三方库提供的接口，仅需少量源代码就能完成复杂的功能； +``Hello, world!`` 程序调用的 ``println!`` 宏就是由 Rust 标准库 std 和 GNU Libc 等提供的。 +这些库属于应用程序的 **执行环境** (Execution Environment)，而它们的实现又依赖于操作系统提供的系统调用。 + +平台与目标三元组 +--------------------------------------- + +编译器在编译、链接得到可执行文件时需要知道，程序要在哪个 **平台** (Platform) 上运行， +**目标三元组** (Target Triplet) 描述了目标平台的 CPU 指令集、操作系统类型和标准运行时库。 + +我们研究一下现在 ``Hello, world!`` 程序的目标三元组是什么： + +.. code-block:: console + + $ rustc --version --verbose + rustc 1.61.0-nightly (68369a041 2022-02-22) + binary: rustc + commit-hash: 68369a041cea809a87e5bd80701da90e0e0a4799 + commit-date: 2022-02-22 + host: x86_64-unknown-linux-gnu + release: 1.61.0-nightly + LLVM version: 14.0.0 + +其中 host 一项表明默认目标平台是 ``x86_64-unknown-linux-gnu``， +CPU 架构是 x86_64，CPU 厂商是 unknown，操作系统是 linux，运行时库是 gnu libc。 + +接下来，我们希望把 ``Hello, world!`` 移植到 RICV 目标平台 ``riscv64gc-unknown-none-elf`` 上运行。 + +.. note:: + + ``riscv64gc-unknown-none-elf`` 的 CPU 架构是 riscv64gc，厂商是 unknown，操作系统是 none， + elf 表示没有标准的运行时库。没有任何系统调用的封装支持，但可以生成 ELF 格式的执行程序。 + 我们不选择有 linux-gnu 支持的 ``riscv64gc-unknown-linux-gnu``，是因为我们的目标是开发操作系统内核，而非在 linux 系统上运行的应用程序。 + +修改目标平台 +---------------------------------- + +将程序的目标平台换成 ``riscv64gc-unknown-none-elf``，试试看会发生什么： + +.. code-block:: console + + $ cargo run --target riscv64gc-unknown-none-elf + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + error[E0463]: can't find crate for `std` + | + = note: the `riscv64gc-unknown-none-elf` target may not be installed + + +报错的原因是目标平台上确实没有 Rust 标准库 std，也不存在任何受 OS 支持的系统调用。 +这样的平台被我们称为 **裸机平台** (bare-metal)。 + +幸运的是，除了 std 之外，Rust 还有一个不需要任何操作系统支持的核心库 core， +它包含了 Rust 语言相当一部分核心机制，可以满足本门课程的需求。 +有很多第三方库也不依赖标准库 std，而仅仅依赖核心库 core。 + +为了以裸机平台为目标编译程序，我们要将对标准库 std 的引用换成核心库 core。 \ No newline at end of file diff --git a/guide/source/chapter1/2remove-std.rst b/guide/source/chapter1/2remove-std.rst new file mode 100644 index 0000000..f70f4d8 --- /dev/null +++ b/guide/source/chapter1/2remove-std.rst @@ -0,0 +1,158 @@ +.. _term-remove-std: + +移除标准库依赖 +========================== + +.. toctree:: + :hidden: + :maxdepth: 5 + + +首先在 ``os`` 目录下新建 ``.cargo`` 目录，并在这个目录下创建 ``config`` 文件，输入如下内容： + +.. code-block:: toml + + # os/.cargo/config + [build] + target = "riscv64gc-unknown-none-elf" + + +这将使 cargo 工具在 os 目录下默认会使用 riscv64gc-unknown-none-elf 作为目标平台。 +这种编译器运行的平台（x86_64）与可执行文件运行的目标平台不同的情况，称为 **交叉编译** (Cross Compile)。 + +移除 println! 宏 +---------------------------------- + + +我们在 ``main.rs`` 的开头加上一行 ``#![no_std]``， +告诉 Rust 编译器不使用 Rust 标准库 std 转而使用核心库 core。重新编译，报错如下： + +.. error:: + + .. code-block:: console + + $ cargo build + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + error: cannot find macro `println` in this scope + --> src/main.rs:4:5 + | + 4 | println!("Hello, world!"); + | ^^^^^^^ + +println! 宏是由标准库 std 提供的，且会使用到一个名为 write 的系统调用。 +无论如何，我们先将这行代码注释掉。 + + +提供语义项 panic_handler +---------------------------------------------------- + +.. error:: + + .. code-block:: console + + $ cargo build + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + error: `#[panic_handler]` function required, but not found + +标准库 std 提供了 Rust 错误处理函数 ``#[panic_handler]``，其大致功能是打印出错位置和原因并杀死当前应用。 +但核心库 core 并没有提供这项功能，得靠我们自己实现。 + +新建一个子模块 ``lang_items.rs``，在里面编写 panic 处理函数，通过标记 ``#[panic_handler]`` 告知编译器采用我们的实现： + +.. code-block:: rust + + // os/src/lang_items.rs + use core::panic::PanicInfo; + + #[panic_handler] + fn panic(_info: &PanicInfo) -> ! { + loop {} + } + +目前我们遇到错误什么都不做，只在原地 ``loop`` 。 + +移除 main 函数 +----------------------------- + +重新编译，又有了新错误： + +.. error:: + + .. code-block:: + + $ cargo build + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + error: requires `start` lang_item + +编译器提醒我们缺少一个名为 ``start`` 的语义项。 +``start`` 语义项代表了标准库 std 在执行应用程序之前需要进行的一些初始化工作。由于我们禁用了标准库，编译器也就找不到这项功能的实现了。 + +在 ``main.rs`` 的开头加入设置 ``#![no_main]`` 告诉编译器我们没有一般意义上的 ``main`` 函数， +并将原来的 ``main`` 函数删除。这样编译器也就不需要考虑初始化工作了。 + +.. code-block:: console + + $ cargo build + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + Finished dev [unoptimized + debuginfo] target(s) in 0.06s + +至此，我们终于移除了所有标准库依赖，目前的代码如下： + +.. code-block:: rust + + // os/src/main.rs + #![no_std] + #![no_main] + + mod lang_items; + + // os/src/lang_items.rs + use core::panic::PanicInfo; + + #[panic_handler] + fn panic(_info: &PanicInfo) -> ! { + loop {} + } + + +分析被移除标准库的程序 +----------------------------- + +我们可以通过一些工具来分析目前的程序： + +.. code-block:: console + + [文件格式] + $ file target/riscv64gc-unknown-none-elf/debug/os + target/riscv64gc-unknown-none-elf/debug/os: ELF 64-bit LSB executable, UCB RISC-V, ...... + + [文件头信息] + $ rust-readobj -h target/riscv64gc-unknown-none-elf/debug/os + File: target/riscv64gc-unknown-none-elf/debug/os + Format: elf64-littleriscv + Arch: riscv64 + AddressSize: 64bit + ...... + Type: Executable (0x2) + Machine: EM_RISCV (0xF3) + Version: 1 + Entry: 0x0 + ...... + } + + [反汇编导出汇编程序] + $ rust-objdump -S target/riscv64gc-unknown-none-elf/debug/os + target/riscv64gc-unknown-none-elf/debug/os: file format elf64-littleriscv + + +通过 ``file`` 工具对二进制程序 ``os`` 的分析可以看到，它好像是一个合法的 RV64 执行程序， +但 ``rust-readobj`` 工具告诉我们它的入口地址 Entry 是 ``0``。 +再通过 ``rust-objdump`` 工具把它反汇编，没有生成任何汇编代码。 +可见，这个二进制程序虽然合法，但它是一个空程序，原因是缺少了编译器规定的入口函数 ``_start`` 。 + +从下一节开始，我们将着手实现本节移除的、由用户态执行环境提供的功能。 + +.. note:: + + 本节内容部分参考自 `BlogOS 的相关章节 `_ 。 + diff --git a/guide/source/chapter1/3mini-rt-usrland.rst b/guide/source/chapter1/3mini-rt-usrland.rst new file mode 100644 index 0000000..b466f9d --- /dev/null +++ b/guide/source/chapter1/3mini-rt-usrland.rst @@ -0,0 +1,282 @@ +.. _term-print-userminienv: + +构建用户态执行环境 +================================= + +.. toctree:: + :hidden: + :maxdepth: 5 + +.. note:: + + 前三小节的用户态程序案例代码在 `此处 `_ 获取。 + + +用户态最小化执行环境 +---------------------------- + +执行环境初始化 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +首先我们要给 Rust 编译器编译器提供入口函数 ``_start()`` ， +在 ``main.rs`` 中添加如下内容： + + +.. code-block:: rust + + // os/src/main.rs + #[no_mangle] + extern "C" fn _start() { + loop{}; + } + + +对上述代码重新编译，再用分析工具分析： + + +.. code-block:: console + + $ cargo build + Compiling os v0.1.0 (/home/shinbokuow/workspace/v3/rCore-Tutorial-v3/os) + Finished dev [unoptimized + debuginfo] target(s) in 0.06s + + [反汇编导出汇编程序] + $ rust-objdump -S target/riscv64gc-unknown-none-elf/debug/os + target/riscv64gc-unknown-none-elf/debug/os: file format elf64-littleriscv + + Disassembly of section .text: + + 0000000000011120 <_start>: + ; loop {} + 11120: 09 a0 j 2 <_start+0x2> + 11122: 01 a0 j 0 <_start+0x2> + + +反汇编出的两条指令就是一个死循环， +这说明编译器生成的已经是一个合理的程序了。 +用 ``qemu-riscv64 target/riscv64gc-unknown-none-elf/debug/os`` 命令可以执行这个程序。 + + +程序正常退出 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +我们把 ``_start()`` 函数中的循环语句注释掉，重新编译并分析，看到其汇编代码是： + + +.. code-block:: console + + $ rust-objdump -S target/riscv64gc-unknown-none-elf/debug/os + + target/riscv64gc-unknown-none-elf/debug/os: file format elf64-littleriscv + + + Disassembly of section .text: + + 0000000000011120 <_start>: + ; } + 11120: 82 80 ret + +看起来是合法的执行程序。但如果我们执行它，会引发问题： + +.. code-block:: console + + $ qemu-riscv64 target/riscv64gc-unknown-none-elf/debug/os + 段错误 (核心已转储) + +这个简单的程序导致 ``qemu-riscv64`` 崩溃了！为什么会这样？ + +.. note:: + + QEMU有两种运行模式： + + ``User mode`` 模式，即用户态模拟，如 ``qemu-riscv64`` 程序， + 能够模拟不同处理器的用户态指令的执行，并可以直接解析ELF可执行文件， + 加载运行那些为不同处理器编译的用户级Linux应用程序。 + + ``System mode`` 模式，即系统态模式，如 ``qemu-system-riscv64`` 程序， + 能够模拟一个完整的基于不同CPU的硬件系统，包括处理器、内存及其他外部设备，支持运行完整的操作系统。 + + +目前的执行环境还缺了一个退出机制，我们需要操作系统提供的 ``exit`` 系统调用来退出程序。这里先给出代码： + +.. code-block:: rust + + // os/src/main.rs + + const SYSCALL_EXIT: usize = 93; + + fn syscall(id: usize, args: [usize; 3]) -> isize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") args[0] => ret, + in("x11") args[1], + in("x12") args[2], + in("x17") id, + ); + } + ret + } + + pub fn sys_exit(xstate: i32) -> isize { + syscall(SYSCALL_EXIT, [xstate as usize, 0, 0]) + } + + #[no_mangle] + extern "C" fn _start() { + sys_exit(9); + } + +``main.rs`` 增加的内容不多，但还是有点与一般的应用程序有所不同，因为它引入了汇编和系统调用。 +第二章的第二节 :doc:`/chapter2/2application` 会详细介绍上述代码的含义。 +这里读者只需要知道 ``_start`` 函数调用了一个 ``sys_exit`` 函数， +向操作系统发出了退出的系统调用请求，退出码为 ``9`` 。 + +我们编译执行以下修改后的程序： + +.. code-block:: console + + $ cargo build --target riscv64gc-unknown-none-elf + Compiling os v0.1.0 (/media/chyyuu/ca8c7ba6-51b7-41fc-8430-e29e31e5328f/thecode/rust/os_kernel_lab/os) + Finished dev [unoptimized + debuginfo] target(s) in 0.26s + + [打印程序的返回值] + $ qemu-riscv64 target/riscv64gc-unknown-none-elf/debug/os; echo $? + 9 + +可以看到，返回的结果确实是 ``9`` 。这样，我们勉强完成了一个简陋的用户态最小化执行环境。 + + +有显示支持的用户态执行环境 +---------------------------- + +没有 ``println`` 输出信息，终究觉得缺了点啥。 + +Rust 的 core 库内建了以一系列帮助实现显示字符的基本 Trait 和数据结构，函数等，我们可以对其中的关键部分进行扩展，就可以实现定制的 ``println!`` 功能。 + + +实现输出字符串的相关函数 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. attention:: + + 如果你觉得理解 Rust 宏有困难，把它当成黑盒就好！ + + +首先封装一下对 ``SYSCALL_WRITE`` 系统调用。 + +.. code-block:: rust + + const SYSCALL_WRITE: usize = 64; + + pub fn sys_write(fd: usize, buffer: &[u8]) -> isize { + syscall(SYSCALL_WRITE, [fd, buffer.as_ptr() as usize, buffer.len()]) + } + +然后实现基于 ``Write`` Trait 的数据结构，并完成 ``Write`` Trait 所需要的 ``write_str`` 函数，并用 ``print`` 函数进行包装。 + + +.. code-block:: rust + + struct Stdout; + + impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + sys_write(1, s.as_bytes()); + Ok(()) + } + } + + pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); + } + +最后，实现基于 ``print`` 函数，实现Rust语言 **格式化宏** ( `formatting macros `_ )。 + + +.. code-block:: rust + + #[macro_export] + macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } + } + + #[macro_export] + macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } + } + +接下来，我们调整一下应用程序，让它发出显示字符串和退出的请求： + +.. code-block:: rust + + #[no_mangle] + extern "C" fn _start() { + println!("Hello, world!"); + sys_exit(9); + } + + +现在，我们编译并执行一下，可以看到正确的字符串输出，且程序也能正确退出！ + + +.. code-block:: console + + $ cargo build --target riscv64gc-unknown-none-elf + Compiling os v0.1.0 (/media/chyyuu/ca8c7ba6-51b7-41fc-8430-e29e31e5328f/thecode/rust/os_kernel_lab/os) + Finished dev [unoptimized + debuginfo] target(s) in 0.61s + + $ qemu-riscv64 target/riscv64gc-unknown-none-elf/debug/os; echo $? + Hello, world! + 9 + + +.. 下面出错的情况是会在采用 linker.ld，加入了 .cargo/config +.. 的内容后会出错： +.. .. [build] +.. .. target = "riscv64gc-unknown-none-elf" +.. .. [target.riscv64gc-unknown-none-elf] +.. .. rustflags = [ +.. .. "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +.. .. ] + +.. 重新定义了栈和地址空间布局后才会出错 + +.. 段错误 (核心已转储) + +.. 系统崩溃了！借助以往的操作系统内核编程经验和与下一节调试kernel的成果经验，我们直接定位为是 **栈** (Stack) 没有设置的问题。我们需要添加建立栈的代码逻辑。 + +.. .. code-block:: asm + +.. # entry.asm + +.. .section .text.entry +.. .globl _start +.. _start: +.. la sp, boot_stack_top +.. call rust_main + +.. .section .bss.stack +.. .globl boot_stack +.. boot_stack: +.. .space 4096 * 16 +.. .globl boot_stack_top +.. boot_stack_top: + +.. 然后把汇编代码嵌入到 ``main.rs`` 中，并进行微调。 + +.. .. code-block:: rust + +.. #![feature(global_asm)] + +.. global_asm!(include_str!("entry.asm")); + +.. #[no_mangle] +.. #[link_section=".text.entry"] +.. extern "C" fn rust_main() { + +.. 再次编译执行，可以看到正确的字符串输出，且程序也能正确结束！ diff --git a/guide/source/chapter1/4mini-rt-baremetal.rst b/guide/source/chapter1/4mini-rt-baremetal.rst new file mode 100644 index 0000000..7cba2f9 --- /dev/null +++ b/guide/source/chapter1/4mini-rt-baremetal.rst @@ -0,0 +1,328 @@ +.. _term-print-kernelminienv: + +构建裸机执行环境 +================================= + +.. toctree:: + :hidden: + :maxdepth: 5 + +有了上一节实现的用户态的最小执行环境，稍加改造，就可以完成裸机上的最小执行环境了。 +本节中，我们将把 ``Hello world!`` 应用程序从用户态搬到内核态。 + + +裸机启动过程 +---------------------------- + +用 QEMU 软件 ``qemu-system-riscv64`` 来模拟 RISC-V 64 计算机。加载内核程序的命令如下： + +.. code-block:: bash + + qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + + +- ``-bios $(BOOTLOADER)`` 意味着硬件加载了一个 BootLoader 程序，即 RustSBI +- ``-device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA)`` 表示硬件内存中的特定位置 ``$(KERNEL_ENTRY_PA)`` 放置了操作系统的二进制代码 ``$(KERNEL_BIN)`` 。 ``$(KERNEL_ENTRY_PA)`` 的值是 ``0x80200000`` 。 + +当我们执行包含上述启动参数的 qemu-system-riscv64 软件，就意味给这台虚拟的 RISC-V64 计算机加电了。 +此时，CPU 的其它通用寄存器清零，而 PC 会指向 ``0x1000`` 的位置，这里有固化在硬件中的一小段引导代码， +它会很快跳转到 ``0x80000000`` 的 RustSBI 处。 +RustSBI完成硬件初始化后，会跳转到 ``$(KERNEL_BIN)`` 所在内存位置 ``0x80200000`` 处， +执行操作系统的第一条指令。 + +.. figure:: chap1-intro.png + :align: center + +.. note:: + + **RustSBI 是什么？** + + SBI 是 RISC-V 的一种底层规范，RustSBI 是它的一种实现。 + 操作系统内核与 RustSBI 的关系有点像应用与操作系统内核的关系，后者向前者提供一定的服务。只是SBI提供的服务很少， + 比如关机，显示字符串等。 + +实现关机功能 +---------------------------- + +对上一节实现的代码稍作调整，通过 ``ecall`` 调用 RustSBI 实现关机功能： + +.. _term-llvm-sbicall: + +.. code-block:: rust + + // bootloader/rustsbi-qemu.bin 直接添加的SBI规范实现的二进制代码，给操作系统提供基本支持服务 + + // os/src/sbi.rs + fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + ... + + const SBI_SHUTDOWN: usize = 8; + + pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); + } + + // os/src/main.rs + #[no_mangle] + extern "C" fn _start() { + shutdown(); + } + + +应用程序访问操作系统提供的系统调用的指令是 ``ecall`` ，操作系统访问 +RustSBI提供的SBI调用的指令也是 ``ecall`` ， +虽然指令一样，但它们所在的特权级是不一样的。 +简单地说，应用程序位于最弱的用户特权级（User Mode）， +操作系统位于内核特权级（Supervisor Mode）， +RustSBI位于机器特权级（Machine Mode）。 +下一章会进一步阐释具体细节。 + +编译执行，结果如下： + +.. code-block:: bash + + # 编译生成ELF格式的执行文件 + $ cargo build --release + Compiling os v0.1.0 (/media/chyyuu/ca8c7ba6-51b7-41fc-8430-e29e31e5328f/thecode/rust/os_kernel_lab/os) + Finished release [optimized] target(s) in 0.15s + # 把ELF执行文件转成bianary文件 + $ rust-objcopy --binary-architecture=riscv64 target/riscv64gc-unknown-none-elf/release/os --strip-all -O binary target/riscv64gc-unknown-none-elf/release/os.bin + + # 加载运行 + $ qemu-system-riscv64 -machine virt -nographic -bios ../bootloader/rustsbi-qemu.bin -device loader,file=target/riscv64gc-unknown-none-elf/release/os.bin,addr=0x80200000 + # 无法退出，风扇狂转，感觉碰到死循环 + +问题在哪？通过 rust-readobj 分析 ``os`` 可执行程序，发现其入口地址不是 +RustSBI 约定的 ``0x80200000`` 。我们需要修改程序的内存布局并设置好栈空间。 + + +设置正确的程序内存布局 +---------------------------- + +可以通过 **链接脚本** (Linker Script) 调整链接器的行为，使得最终生成的可执行文件的内存布局符合我们的预期。 + +修改 Cargo 的配置文件来使用我们自己的链接脚本 ``os/src/linker.ld``： + +.. code-block:: + :linenos: + :emphasize-lines: 5,6,7,8 + + // os/.cargo/config + [build] + target = "riscv64gc-unknown-none-elf" + + [target.riscv64gc-unknown-none-elf] + rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" + ] + +具体的链接脚本 ``os/src/linker.ld`` 如下： + +.. code-block:: + :linenos: + + OUTPUT_ARCH(riscv) + ENTRY(_start) + BASE_ADDRESS = 0x80200000; + + SECTIONS + { + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + } + + . = ALIGN(4K); + edata = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } + } + +第 1 行我们设置了目标平台为 riscv ；第 2 行我们设置了整个程序的入口点为之前定义的全局符号 ``_start``； +第 3 行定义了一个常量 ``BASE_ADDRESS`` 为 ``0x80200000`` ，RustSBI 期望的 OS 起始地址； + +.. attention:: + + linker 脚本的语法不做要求，感兴趣的同学可以自行查阅相关资料。 + +从 ``BASE_ADDRESS`` 开始，代码段 ``.text``, 只读数据段 ``.rodata``，数据段 ``.data``, bss 段 ``.bss`` 由低到高依次放置， +且每个段都有两个全局变量给出其起始和结束地址（比如 ``.text`` 段的开始和结束地址分别是 ``stext`` 和 ``etext`` ）。 + + +正确配置栈空间布局 +---------------------------- + +用另一段汇编代码初始化栈空间： + +.. code-block:: asm + :linenos: + + # os/src/entry.asm + .section .text.entry + .globl _start + _start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack + boot_stack: + .space 4096 * 16 + .globl boot_stack_top + boot_stack_top: + +在第 8 行，我们预留了一块大小为 4096 * 16 字节，也就是 :math:`64\text{KiB}` 的空间， +用作操作系统的栈空间。 +栈顶地址被全局符号 ``boot_stack_top`` 标识，栈底则被全局符号 ``boot_stack`` 标识。 +同时，这块栈空间被命名为 +``.bss.stack`` ，链接脚本里有它的位置。 + +``_start`` 作为操作系统的入口地址，将依据链接脚本被放在 ``BASE_ADDRESS`` 处。 +``la sp, boot_stack_top`` 作为 OS 的第一条指令， +将 sp 设置为栈空间的栈顶。 +简单起见，我们目前不考虑 sp 越过栈底 ``boot_stack`` ，也就是栈溢出的情形。 +第二条指令则是函数调用 ``rust_main`` ，这里的 ``rust_main`` 是我们稍后自己编写的应用入口。 + +接着，我们在 ``main.rs`` 中嵌入这些汇编代码并声明应用入口 ``rust_main`` ： + +.. code-block:: rust + :linenos: + :emphasize-lines: 7,9,10,11,12 + + // os/src/main.rs + #![no_std] + #![no_main] + + mod lang_items; + + core::arch::global_asm!(include_str!("entry.asm")); + + #[no_mangle] + pub fn rust_main() -> ! { + shutdown(); + } + +背景高亮指出了 ``main.rs`` 中新增的代码。 + +第 7 行，我们使用 ``global_asm`` 宏，将同目录下的汇编文件 ``entry.asm`` 嵌入到代码中。 + +从第 9 行开始， +我们声明了应用的入口点 ``rust_main`` ，需要注意的是，这里通过宏将 ``rust_main`` +标记为 ``#[no_mangle]`` 以避免编译器对它的名字进行混淆，不然在链接时， +``entry.asm`` 将找不到 ``main.rs`` 提供的外部符号 ``rust_main``，导致链接失败。 + +再次使用上节中的编译，生成和运行操作，我们看到QEMU模拟的RISC-V 64计算机 **优雅** 地退出了！ + +.. code-block:: console + # 教程使用的 RustSBI 版本比代码框架稍旧，输出有所不同 + $ qemu-system-riscv64 \ + > -machine virt \ + > -nographic \ + > -bios ../bootloader/rustsbi-qemu.bin \ + > -device loader,file=target/riscv64gc-unknown-none-elf/release/os.bin,addr=0x80200000 + [rustsbi] Version 0.1.0 + .______ __ __ _______.___________. _______..______ __ + | _ \ | | | | / | | / || _ \ | | + | |_) | | | | | | (----`---| |----`| (----`| |_) || | + | / | | | | \ \ | | \ \ | _ < | | + | |\ \----.| `--' |.----) | | | .----) | | |_) || | + | _| `._____| \______/ |_______/ |__| |_______/ |______/ |__| + + [rustsbi] Platform: QEMU + [rustsbi] misa: RV64ACDFIMSU + [rustsbi] mideleg: 0x222 + [rustsbi] medeleg: 0xb1ab + [rustsbi] Kernel entry: 0x80200000 + + +清空 .bss 段 +---------------------------------- + +等一等，与内存相关的部分太容易出错了， **清零 .bss 段** 的工作我们还没有完成。 + +.. code-block:: rust + :linenos: + + // os/src/main.rs + fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + (sbss as usize..ebss as usize).for_each(|a| { + unsafe { (a as *mut u8).write_volatile(0) } + }); + } + + pub fn rust_main() -> ! { + clear_bss(); + shutdown(); + } + +链接脚本 ``linker.ld`` 中给出的全局符号 ``sbss`` 和 ``ebss`` 让我们能轻松确定 ``.bss`` 段的位置。 + + +添加裸机打印相关函数 +---------------------------------- + +在上一节中我们为用户态程序实现的 ``println`` 宏，略作修改即可用于本节的内核态操作系统。 +详见 ``os/src/console.rs``。 + +利用 ``println`` 宏，我们重写异常处理函数 ``panic``，使其在 panic 时能打印错误发生的位置。 +相关代码位于 ``os/src/lang_items.rs`` 中。 + +我们还使用第三方库 ``log`` 为你实现了日志模块，相关代码位于 ``os/src/logging.rs`` 中。 + +.. note:: + + 在 cargo 项目中引入外部库 log，需要修改 ``Cargo.toml`` 加入相应的依赖信息。 + +现在，让我们重复一遍本章开头的试验，``make run LOG=TRACE``！ + +.. figure:: color-demo.png + :align: center + +产生 panic 的地点与源码中的实际位置一致！至此，我们完成了第一章的实验内容， + + +.. note:: + + 背景知识：`理解应用程序和执行环境 `_ \ No newline at end of file diff --git a/guide/source/chapter1/5exercise.rst b/guide/source/chapter1/5exercise.rst new file mode 100644 index 0000000..268ccc9 --- /dev/null +++ b/guide/source/chapter1/5exercise.rst @@ -0,0 +1,143 @@ +chapter1练习(已经废弃，没删是怕以后有用) +===================================================== + +.. toctree:: + :hidden: + :maxdepth: 4 + +- 本节难度： **低** + +编程作业 +------------------------------- + +彩色化 LOG ++++++++++++++++++++++++++++++++ + +.. lab1 的工作使得我们从硬件世界跳入了软件世界，当看到自己的小 os 可以在裸机硬件上输出 ``hello world`` 是不是很高兴呢？但是为了后续的一步开发，更好的调试环境也是必不可少的，第一章的练习要求大家实现更加炫酷的彩色log。 + +.. 详细的原理不多说，感兴趣的同学可以参考 `ANSI转义序列 `_ ，现在执行如下这条命令试试 + +.. .. code-block:: console + +.. $ echo -e "\x1b[31mhello world\x1b[0m" + +.. 如果你明白了我们是如何利用串口实现输出，那么要实现彩色输出就十分容易了，只需要用需要输出的字符串替换上一条命令中的 ``hello world``，用期望颜色替换 ``31(代表红色)`` 即可。 + +.. .. warning:: + +.. 以下内容仅为推荐实现，不是练习要求，有时间和兴趣的同学可以尝试。 + +.. 我们推荐实现如下几个等级的输出，输出优先级依次降低： + +.. .. list-table:: log 等级推荐 +.. :header-rows: 1 +.. :align: center + +.. * - 名称 +.. - 颜色 +.. - 用途 +.. * - ERROR +.. - 红色(31) +.. - 表示发生严重错误，很可能或者已经导致程序崩溃 +.. * - WARN +.. - 黄色(93) +.. - 表示发生不常见情况，但是并不一定导致系统错误 +.. * - INFO +.. - 蓝色(34) +.. - 比较中庸的选项，输出比较重要的信息，比较常用 +.. * - DEBUG +.. - 绿色(32) +.. - 输出信息较多，在 debug 时使用 +.. * - TRACE +.. - 灰色(90) +.. - 最详细的输出，跟踪了每一步关键路径的执行 + +.. 我们可以输出比设定输出等级以及更高输出等级的信息，如设置 ``LOG = INFO``，则输出 ``ERROR``、``WARN``、``INFO`` 等级的信息。简单 demo 如下，输出等级为 INFO: + +.. .. image:: color-demo.png + +.. 为了方便使用彩色输出，我们要求同学们实现彩色输出的宏或者函数，用以代替 print 完成输出内核信息的功能，它们有着和 prinf 十分相似的使用格式，要求支持可变参数解析，形如： + +.. .. code-block:: rust + +.. // 这段代码输出了 os 内存空间布局，这到这些信息对于编写 os 十分重要 + +.. info!(".text [{:#x}, {:#x})", s_text as usize, e_text as usize); +.. debug!(".rodata [{:#x}, {:#x})", s_rodata as usize, e_rodata as usize); +.. error!(".data [{:#x}, {:#x})", s_data as usize, e_data as usize); + +.. .. code-block:: c + +.. info("load range : [%d, %d] start = %d\n", s, e, start); + +.. 在以后，我们还可以在 log 信息中增加线程、CPU等信息（只是一个推荐，不做要求），这些信息将极大的方便你的代码调试。 + + +实验要求 ++++++++++++++++++++++++++++++++ + +.. - 实现分支：ch1。 +.. - 完成实验指导书中的内容，在裸机上实现 ``hello world`` 输出。 +.. - 实现彩色输出宏(只要求可以彩色输出，不要求 log 等级控制，不要求多种颜色)。 +.. - 隐形要求：可以关闭内核所有输出。从 lab2 开始要求关闭内核所有输出（如果实现了 log 等级控制，那么这一点自然就实现了）。 +.. - 利用彩色输出宏输出 os 内存空间布局，即：输出 ``.text``、``.data``、``.rodata``、``.bss`` 各段位置，输出等级为 ``INFO``。 + +实验检查 ++++++++++++++++++++++++++++++++ + +.. - 实验目录要求(Rust) + +.. .. code-block:: + +.. ├── os(内核实现) +.. │   ├── Cargo.toml(配置文件) +.. │   ├── Makefile (要求 make run LOG=xxx 可以正确执行，可以不实现对 LOG 这一属性的支持，设置默认输出等级为 INFO) +.. │   └── src(所有内核的源代码放在 os/src 目录下) +.. │   ├── main.rs(内核主函数) +.. │   └── ... +.. ├── reports +.. │   ├── lab1.md/pdf +.. │   └── ... +.. ├── README.md（其他必要的说明） +.. ├── ... + +.. 报告命名 labx.md/pdf，统一放在 reports 目录下。每个实验新增一个报告，为了方便修改，检查报告是以最新分支的所有报告为准。 + +.. - 检查 + +.. .. code-block:: console + +.. $ cd os +.. $ git checkout ch1 +.. $ make run LOG=INFO + +.. 可以正确执行(可以不支持LOG参数，只有要彩色输出就好)，可以看到正确的内存布局输出，根据实现不同数值可能有差异，但应该位于 ``linker.ld`` 中指示 ``BASE_ADDRESS`` 后一段内存，输出之后关机。 + +问答作业 +------------------------------- + +.. 1. 为了方便 os 处理，Ｍ态软件会将 S 态异常/中断委托给 S 态软件，请指出有哪些寄存器记录了委托信息，rustsbi 委托了哪些异常/中断？（也可以直接给出寄存器的值） + +.. 2. 请学习 gdb 调试工具的使用(这对后续调试很重要)，并通过 gdb 简单跟踪从机器加电到跳转到 0x80200000 的简单过程。只需要描述重要的跳转即可，只需要描述在 qemu 上的情况。 + +.. 3. tips: + +.. - 事实上进入 rustsbi 之后就不需要使用 gdb 调试了。可以直接阅读代码。`rustsbi起始代码 `_ 。 +.. - 可以使用示例代码 Makefile 中的 ``make debug`` 指令。 +.. - 一些可能用到的 gdb 指令： +.. - ``x/10i 0x80000000`` : 显示 0x80000000 处的10条汇编指令。 +.. - ``x/10i $pc`` : 显示即将执行的10条汇编指令。 +.. - ``x/10xw 0x80000000`` : 显示 0x80000000 处的10条数据，格式为16进制32bit。 +.. - ``info register``: 显示当前所有寄存器信息。 +.. - ``info r t0``: 显示 t0 寄存器的值。 +.. - ``break funcname``: 在目标函数第一条指令处设置断点。 +.. - ``break *0x80200000``: 在 0x80200000 出设置断点。 +.. - ``continue``: 执行直到碰到断点。 +.. - ``si``: 单步执行一条汇编指令。 + +报告要求 +------------------------------- + +- 简单总结你实现的功能（200字以内，不要贴代码）。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 \ No newline at end of file diff --git a/guide/source/chapter1/app-software-stack.png b/guide/source/chapter1/app-software-stack.png new file mode 100644 index 0000000000000000000000000000000000000000..021f145b53b6a82f9a9075747502e7b4aa819c56 GIT binary patch literal 11052 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 t^Cba$`_ + + +应用程序设计 +----------------------------- + +.. attention:: + + 用户库看起来很复杂，它预留了直到 ch7 内核才能实现的系统调用接口，console 模块还实现了输出缓存区。它们不是为本章准备的，你只需关注本节提到的部分即可。 + + +应用程序、用户库（包括入口函数、初始化函数、I/O函数和系统调用接口等多个rs文件组成）放在项目根目录的 ``user`` 目录下： + +- user/src/bin/*.rs：各个应用程序 +- user/src/*.rs：用户库（包括入口函数、初始化函数、I/O函数和系统调用接口等） +- user/src/linker.ld：应用程序的内存布局说明 + +项目结构 +^^^^^^^^^^^^^^^^^^^^^^ + +``user/src/bin`` 里面有多个文件，其中三个是： + +- ``hello_world``：在屏幕上打印一行 ``Hello, world!`` +- ``bad_address``：访问一个非法的物理地址，测试批处理系统是否会被该错误影响 +- ``power``：不断在计算操作和打印字符串操作之间切换 + +批处理系统会按照文件名顺序加载并运行它们。 + +每个应用程序的实现都在对应的单个文件中。打开 ``hello_world.rs``，能看到一个 ``main`` 函数，还有外部库引用： + +.. code-block:: rust + + #[macro_use] + extern crate user_lib; + +这个外部库其实就是 ``user`` 目录下的 ``lib.rs`` 以及它引用的若干子模块。 +在 ``user/Cargo.toml`` 中我们对于库的名字进行了设置： ``name = "user_lib"`` 。 +它作为 ``bin`` 目录下的源程序所依赖的用户库，等价于其他编程语言提供的标准库。 + +在 ``lib.rs`` 中我们定义了用户库的入口点 ``_start`` ： + +.. code-block:: rust + :linenos: + + #[no_mangle] + #[link_section = ".text.entry"] + pub extern "C" fn _start() -> ! { + clear_bss(); + exit(main()); + } + +第 2 行使用 ``link_section`` 宏将 ``_start`` 函数编译后的汇编代码放在名为 ``.text.entry`` 的代码段中， +方便用户库链接脚本将它作为用户程序的入口。 + +而从第 4 行开始，我们手动清零 ``.bss`` 段，然后调用 ``main`` 函数得到一个类型为 ``i32`` 的返回值， +最后，调用用户库提供的 ``exit`` 接口退出，并将返回值告知批处理系统。 + +我们在 ``lib.rs`` 中看到了另一个 ``main`` ： + +.. code-block:: rust + :linenos: + + #![feature(linkage)] // 启用弱链接特性 + + #[linkage = "weak"] + #[no_mangle] + fn main() -> i32 { + panic!("Cannot find main!"); + } + +我们使用 Rust 宏将其标志为弱链接。这样在最后链接的时候， +虽然 ``lib.rs`` 和 ``bin`` 目录下的某个应用程序中都有 ``main`` 符号， +但由于 ``lib.rs`` 中的 ``main`` 符号是弱链接， +链接器会使用 ``bin`` 目录下的函数作为 ``main`` 。 +如果在 ``bin`` 目录下找不到任何 ``main`` ，那么编译也能通过，但会在运行时报错。 + +内存布局 +^^^^^^^^^^^^^^^^^^^^^^ + +我们使用链接脚本 ``user/src/linker.ld`` 规定用户程序的内存布局： + +- 将程序的起始物理地址调整为 ``0x80400000`` ，三个应用程序都会被加载到这个物理地址上运行； +- 将 ``_start`` 所在的 ``.text.entry`` 放在整个程序的开头 ``0x80400000``； + 批处理系统在加载应用后，跳转到 ``0x80400000``，就进入了用户库的 ``_start`` 函数； +- 提供了最终生成可执行文件的 ``.bss`` 段的起始和终止地址，方便 ``clear_bss`` 函数使用。 + +其余的部分和第一章基本相同。 + +系统调用 +^^^^^^^^^^^^^^^^^^^^^^ + +在子模块 ``syscall`` 中我们来通过 ``ecall`` 调用批处理系统提供的接口， +由于应用程序运行在用户态（即 U 模式）， ``ecall`` 指令会触发名为 ``Environment call from U-mode`` 的异常， +并 Trap 进入 S 模式执行批处理系统针对这个异常特别提供的服务程序。 +这个接口被称为 ABI 或者系统调用。 +现在我们不关心 S 态的批处理系统如何提供应用程序所需的功能，只考虑如何使用它。 + +在本章中，应用程序和批处理系统约定如下两个系统调用： + +.. code-block:: rust + :caption: 第二章新增系统调用 + + /// 功能：将内存中缓冲区中的数据写入文件。 + /// 参数：`fd` 表示待写入文件的文件描述符； + /// `buf` 表示内存中缓冲区的起始地址； + /// `len` 表示内存中缓冲区的长度。 + /// 返回值：返回成功写入的长度。 + /// syscall ID：64 + fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize; + + /// 功能：退出应用程序并将返回值告知批处理系统。 + /// 参数：`xstate` 表示应用程序的返回值。 + /// 返回值：该系统调用不应该返回。 + /// syscall ID：93 + fn sys_exit(xstate: usize) -> !; + +实际调用时，我们要按照 RISC-V 调用规范，在合适的寄存器中放置参数， +然后执行 ``ecall`` 指令触发 Trap。当 Trap 结束，回到 U 模式后， +用户程序会从 ``ecall`` 的下一条指令继续执行，同时在合适的寄存器中读取返回值。 + +.. note:: + + RISC-V 寄存器编号从 ``0~31`` ，表示为 ``x0~x31`` 。 其中： + - ``x10~x17`` : 对应 ``a0~a7`` + - ``x1`` ：对应 ``ra`` + +约定寄存器 ``a0~a6`` 保存系统调用的参数， ``a0`` 保存系统调用的返回值， +寄存器 ``a7`` 用来传递 syscall ID。 +这超出了 Rust 语言的表达能力，我们需要内嵌汇编来完成参数/返回值绑定和 ``ecall`` 指令的插入： + +.. code-block:: rust + :linenos: + + // user/src/syscall.rs + + fn syscall(id: usize, args: [usize; 3]) -> isize { + let mut ret: isize; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") args[0] => ret, + in("x11") args[1], + in("x12") args[2], + in("x17") id + ); + } + ret + } + +第 3 行，我们将所有的系统调用都封装成 ``syscall`` 函数，可以看到它支持传入 syscall ID 和 3 个参数。 + +第 6 行开始，我们使用 Rust 提供的 ``asm!`` 宏在代码中内嵌汇编。 +Rust 编译器无法判定汇编代码的安全性，所以我们需要将其包裹在 unsafe 块中。 + +简而言之，这条汇编代码的执行结果是以寄存器 ``a0~a2`` 来保存系统调用的参数，以及寄存器 ``a7`` 保存 syscall ID， +返回值通过寄存器 ``a0`` 传递给局部变量 ``ret``。 + +这段汇编代码与第一章中出现过的内嵌汇编很像，读者可以查看 ``os/src/sbi.rs`` 。 + +.. note:: + + 可以查看 `Inline assembly `_ 了解 ``asm`` 宏。 + +于是 ``sys_write`` 和 ``sys_exit`` 只需将 ``syscall`` 进行包装： + +.. code-block:: rust + :linenos: + + // user/src/syscall.rs + + const SYSCALL_WRITE: usize = 64; + const SYSCALL_EXIT: usize = 93; + + pub fn sys_write(fd: usize, buffer: &[u8]) -> isize { + syscall(SYSCALL_WRITE, [fd, buffer.as_ptr() as usize, buffer.len()]) + } + + pub fn sys_exit(xstate: i32) -> isize { + syscall(SYSCALL_EXIT, [xstate as usize, 0, 0]) + } + +我们将上述两个系统调用在用户库 ``user_lib`` 中进一步封装，像标准库一样： + +.. code-block:: rust + :linenos: + + // user/src/lib.rs + use syscall::*; + + pub fn write(fd: usize, buf: &[u8]) -> isize { sys_write(fd, buf) } + pub fn exit(exit_code: i32) -> isize { sys_exit(exit_code) } + +在 ``console`` 子模块中，借助 ``write``，我们为应用程序实现了 ``println!`` 宏。 +传入到 ``write`` 的 ``fd`` 参数设置为 1，代表标准输出 STDOUT，暂时不用考虑其他的 ``fd`` 选取情况。 + + +编译生成应用程序二进制码 +------------------------------- + +简要介绍一下应用程序的构建，在 ``user`` 目录下 ``make build``： + +1. 对于 ``src/bin`` 下的每个应用程序， + 在 ``target/riscv64gc-unknown-none-elf/release`` 目录下生成一个同名的 ELF 可执行文件； +2. 使用 objcopy 二进制工具删除所有 ELF header 和符号，得到 ``.bin`` 后缀的纯二进制镜像文件。 + 它们将被链接进内核，并由内核在合适的时机加载到内存。 diff --git a/guide/source/chapter2/3batch-system.rst b/guide/source/chapter2/3batch-system.rst new file mode 100644 index 0000000..ce2786b --- /dev/null +++ b/guide/source/chapter2/3batch-system.rst @@ -0,0 +1,168 @@ + +.. _term-batchos: + +实现批处理操作系统 +============================== + +.. toctree:: + :hidden: + :maxdepth: 5 + +将应用程序链接到内核 +-------------------------------------------- + +在本章中，我们要把应用程序的二进制镜像文件作为数据段链接到内核里， +内核需要知道应用程序的数量和它们的位置。 + +在 ``os/src/main.rs`` 中能够找到这样一行： + +.. code-block:: rust + + core::arch::global_asm!(include_str!("link_app.S")); + +这里我们引入了一段汇编代码 ``link_app.S`` ，它是在 ``make run`` 构建操作系统时自动生成的，里面的内容大致如下： + +.. code-block:: asm + :linenos: + + # os/src/link_app.S + + .align 3 + .section .data + .global _num_app + _num_app: + .quad 3 + .quad app_0_start + .quad app_1_start + .quad app_2_start + .quad app_2_end + + .section .data + .global app_0_start + .global app_0_end + app_0_start: + .incbin "../user/target/riscv64gc-unknown-none-elf/release/hello_world.bin" + app_0_end: + + .section .data + .global app_1_start + .global app_1_end + app_1_start: + .incbin "../user/target/riscv64gc-unknown-none-elf/release/bad_address.bin" + app_1_end: + + .section .data + .global app_2_start + .global app_2_end + app_2_start: + .incbin "../user/target/riscv64gc-unknown-none-elf/release/power.bin" + app_2_end: + +第 13 行开始的三个数据段分别插入了三个应用程序的二进制镜像， +并且各自有一对全局符号 ``app_*_start, app_*_end`` 指示它们的开始和结束位置。 +而第 3 行开始的另一个数据段相当于一个 64 位整数数组。 +数组中的第一个元素表示应用程序的数量，后面则按照顺序放置每个应用程序的起始地址， +最后一个元素放置最后一个应用程序的结束位置。这样数组中相邻两个元素记录了每个应用程序的始末位置， +这个数组所在的位置由全局符号 ``_num_app`` 所指示。 + +这个文件是在 ``cargo build`` 时，由脚本 ``os/build.rs`` 控制生成的。 + +找到并加载应用程序二进制码 +----------------------------------------------- + +我们在 ``os`` 的 ``batch`` 子模块中实现一个应用管理器 ``AppManager`` ，结构体定义如下： + +.. code-block:: rust + + struct AppManager { + num_app: usize, + current_app: usize, + app_start: [usize; MAX_APP_NUM + 1], + } + +初始化 ``AppManager`` 的全局实例： + +.. code-block:: rust + + lazy_static! { + static ref APP_MANAGER: UPSafeCell = unsafe { + UPSafeCell::new({ + extern "C" { + fn _num_app(); + } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = num_app_ptr.read_volatile(); + let mut app_start: [usize; MAX_APP_NUM + 1] = [0; MAX_APP_NUM + 1]; + let app_start_raw: &[usize] = + core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1); + app_start[..=num_app].copy_from_slice(app_start_raw); + AppManager { + num_app, + current_app: 0, + app_start, + } + }) + }; + } + +初始化的逻辑很简单，就是找到 ``link_app.S`` 中提供的符号 ``_num_app`` ，并从这里开始解析出应用数量以及各个应用的开头地址。 +用容器 ``UPSafeCell`` 包裹 ``AppManager`` 是为了防止全局对象 ``APP_MANAGER`` 被重复获取。 + +.. note:: + + ``UPSafeCell`` 实现在 ``sync`` 模块中，调用 ``exclusive_access`` 方法能获取其内部对象的可变引用， + 如果程序运行中同时存在多个这样的引用，会触发 ``already borrowed: BorrowMutError``。 + + ``UPSafeCell`` 既提供了内部可变性，又在单核情境下防止了内部对象被重复借用，我们将在后文中多次见到它。 + +这里使用了外部库 ``lazy_static`` 提供的 ``lazy_static!`` 宏。 + +``lazy_static!`` 宏提供了全局变量的运行时初始化功能。一般情况下，全局变量必须在编译期设置初始值， +但是有些全局变量的初始化依赖于运行期间才能得到的数据。 +如这里我们借助 ``lazy_static!`` 声明了一个 ``AppManager`` 结构的名为 ``APP_MANAGER`` 的全局实例， +只有在它第一次被使用到的时候才会进行实际的初始化工作。 + +``AppManager`` 的方法中， ``print_app_info/get_current_app/move_to_next_app`` 都相当简单直接，需要说明的是 ``load_app``： + +.. code-block:: rust + :linenos: + + unsafe fn load_app(&self, app_id: usize) { + if app_id >= self.num_app { + panic!("All applications completed!"); + } + info!("[kernel] Loading app_{}", app_id); + // clear icache + core::arch::asm!("fence.i"); + // clear app area + core::slice::from_raw_parts_mut(APP_BASE_ADDRESS as *mut u8, APP_SIZE_LIMIT).fill(0); + let app_src = core::slice::from_raw_parts( + self.app_start[app_id] as *const u8, + self.app_start[app_id + 1] - self.app_start[app_id], + ); + let app_dst = core::slice::from_raw_parts_mut(APP_BASE_ADDRESS as *mut u8, app_src.len()); + app_dst.copy_from_slice(app_src); + } + +这个方法负责将参数 ``app_id`` 对应的应用程序的二进制镜像加载到物理内存以 ``0x80400000`` 起始的位置， +这个位置是批处理操作系统和应用程序之间约定的常数地址。 +我们将从这里开始的一块内存清空，然后找到待加载应用二进制镜像的位置，并将它复制到正确的位置。 + +清空内存前，我们插入了一条奇怪的汇编指令 ``fence.i`` ，它是用来清理 i-cache 的。 +我们知道， 缓存又分成 **数据缓存** (d-cache) 和 **指令缓存** (i-cache) 两部分，分别在 CPU 访存和取指的时候使用。 +通常情况下， CPU 会认为程序的代码段不会发生变化，因此 i-cache 是一种只读缓存。 +但在这里，我们会修改会被 CPU 取指的内存区域，使得 i-cache 中含有与内存不一致的内容， +必须使用 ``fence.i`` 指令手动清空 i-cache ，让里面所有的内容全部失效， +才能够保证程序执行正确性。 + +.. warning:: + + **模拟器与真机的不同之处** + + 在 Qemu 模拟器上，即使不加刷新 i-cache 的指令，大概率也能正常运行，但在物理计算机上不是这样。 + +``batch`` 子模块对外暴露出如下接口： + +- ``init`` ：调用 ``print_app_info`` 的时第一次用到了全局变量 ``APP_MANAGER`` ，它在这时完成初始化； +- ``run_next_app`` ：批处理操作系统的核心操作，即加载并运行下一个应用程序。 + 批处理操作系统完成初始化，或者应用程序运行结束/出错后会调用该函数。下节再介绍其具体实现。 \ No newline at end of file diff --git a/guide/source/chapter2/4trap-handling.rst b/guide/source/chapter2/4trap-handling.rst new file mode 100644 index 0000000..89de48b --- /dev/null +++ b/guide/source/chapter2/4trap-handling.rst @@ -0,0 +1,519 @@ +.. _term-trap-handle: + +实现特权级的切换 +=========================== + +.. toctree:: + :hidden: + :maxdepth: 5 + +RISC-V特权级切换 +--------------------------------------- + +特权级切换的起因 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +批处理操作系统为了建立好应用程序的执行环境，需要在执行应用程序前进行一些初始化工作， +并监控应用程序的执行，具体体现在： + +- 启动应用程序时，需要初始化应用程序的用户态上下文，并能切换到用户态执行应用程序； +- 应用程序发起系统调用后，需要切换到批处理操作系统中进行处理； +- 应用程序执行出错时，批处理操作系统要杀死该应用并加载运行下一个应用； +- 应用程序执行结束时，批处理操作系统要加载运行下一个应用。 + +这些处理都涉及到特权级切换，因此都需要硬件和操作系统协同提供的特权级切换机制。 + + +特权级切换相关的控制状态寄存器 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +本章中我们仅考虑当 CPU 在 U 特权级运行用户程序的时候触发 Trap， +并切换到 S 特权级的批处理操作系统进行处理。 + +.. list-table:: 进入 S 特权级 Trap 的相关 CSR + :header-rows: 1 + :align: center + :widths: 30 100 + + * - CSR 名 + - 该 CSR 与 Trap 相关的功能 + * - sstatus + - ``SPP`` 等字段给出 Trap 发生之前 CPU 处在哪个特权级（S/U）等信息 + * - sepc + - 当 Trap 是一个异常的时候，记录 Trap 发生之前执行的最后一条指令的地址 + * - scause + - 描述 Trap 的原因 + * - stval + - 给出 Trap 附加信息 + * - stvec + - 控制 Trap 处理代码的入口地址 + +特权级切换的具体过程一部分由硬件直接完成，另一部分则需要由操作系统来实现。 + +.. _trap-hw-mechanism: + +特权级切换的硬件控制机制 +------------------------------------- + +当 CPU 执行完一条指令并准备从用户特权级 陷入（ ``Trap`` ）到 S 特权级的时候，硬件会自动完成如下这些事情： + +- ``sstatus`` 的 ``SPP`` 字段会被修改为 CPU 当前的特权级（U/S）。 +- ``sepc`` 会被修改为 Trap 处理完成后默认会执行的下一条指令的地址。 +- ``scause/stval`` 分别会被修改成这次 Trap 的原因以及相关的附加信息。 +- CPU 会跳转到 ``stvec`` 所设置的 Trap 处理入口地址，并将当前特权级设置为 S ，然后从Trap 处理入口地址处开始执行。 + +.. note:: + + **stvec 相关细节** + + 在 RV64 中， ``stvec`` 是一个 64 位的 CSR，在中断使能的情况下，保存了中断处理的入口地址。它有两个字段： + + - MODE 位于 [1:0]，长度为 2 bits； + - BASE 位于 [63:2]，长度为 62 bits。 + + 当 MODE 字段为 0 的时候， ``stvec`` 被设置为 Direct 模式，此时进入 S 模式的 Trap 无论原因如何，处理 Trap 的入口地址都是 ``BASE<<2`` + ， CPU 会跳转到这个地方进行异常处理。本书中我们只会将 ``stvec`` 设置为 Direct 模式。而 ``stvec`` 还可以被设置为 Vectored 模式， + +而当 CPU 完成 Trap 处理准备返回的时候，需要通过一条 S 特权级的特权指令 ``sret`` 来完成，这一条指令具体完成以下功能： + +- CPU 会将当前的特权级按照 ``sstatus`` 的 ``SPP`` 字段设置为 U 或者 S ； +- CPU 会跳转到 ``sepc`` 寄存器指向的那条指令，然后继续执行。 + +用户栈与内核栈 +-------------------------------- + +在 Trap 触发的一瞬间， CPU 会切换到 S 特权级并跳转到 ``stvec`` 所指示的位置。 +但是在正式进入 S 特权级的 Trap 处理之前，我们必须保存原控制流的寄存器状态，这一般通过栈来完成。 +但我们需要用专门为操作系统准备的内核栈，而不是应用程序运行时用到的用户栈。 + +我们声明两个类型 ``KernelStack`` 和 ``UserStack`` 分别表示用户栈和内核栈，它们都只是字节数组的简单包装： + +.. code-block:: rust + :linenos: + + // os/src/batch.rs + + #[repr(align(4096))] + struct KernelStack { + data: [u8; KERNEL_STACK_SIZE], + } + + #[repr(align(4096))] + struct UserStack { + data: [u8; USER_STACK_SIZE], + } + + static KERNEL_STACK: KernelStack = KernelStack { + data: [0; KERNEL_STACK_SIZE], + }; + static USER_STACK: UserStack = UserStack { + data: [0; USER_STACK_SIZE], + }; + + +两个栈以全局变量的形式实例化在批处理操作系统的 ``.bss`` 段中。 + +我们为两个类型实现了 ``get_sp`` 方法来获取栈顶地址。由于在 RISC-V 中栈是向下增长的， +我们只需返回包裹的数组的结尾地址，以用户栈类型 ``UserStack`` 为例： + +.. code-block:: rust + :linenos: + + impl UserStack { + fn get_sp(&self) -> usize { + self.data.as_ptr() as usize + USER_STACK_SIZE + } + } + +换栈是非常简单的，只需将 ``sp`` 寄存器的值修改为 ``get_sp`` 的返回值即可。 + +.. _term-trap-context: + +接下来是 Trap 上下文，即在 Trap 发生时需要保存的物理资源内容，定义如下： + +.. code-block:: rust + :linenos: + + // os/src/trap/context.rs + + #[repr(C)] + pub struct TrapContext { + pub x: [usize; 32], + pub sstatus: Sstatus, + pub sepc: usize, + } + +可以看到里面包含所有的通用寄存器 ``x0~x31`` ，还有 ``sstatus`` 和 ``sepc`` 。 + +- 对于通用寄存器而言，两条控制流（应用程序控制流和内核控制流）运行在不同的特权级，所属的软件也可能由不同的编程语言编写，虽然在 Trap 控制流中只是会执行 Trap 处理 + 相关的代码，但依然可能直接或间接调用很多模块，因此很难甚至不可能找出哪些寄存器无需保存。既然如此我们就只能全部保存了。但这里也有一些例外， + 如 ``x0`` 被硬编码为 0 ，它自然不会有变化；还有 ``tp(x4)`` 寄存器，除非我们手动出于一些特殊用途使用它，否则一般也不会被用到。虽然它们无需保存， + 但我们仍然在 ``TrapContext`` 中为它们预留空间，主要是为了后续的实现方便。 +- 对于 CSR 而言，我们知道进入 Trap 的时候，硬件会立即覆盖掉 ``scause/stval/sstatus/sepc`` 的全部或是其中一部分。``scause/stval`` + 的情况是：它总是在 Trap 处理的第一时间就被使用或者是在其他地方保存下来了，因此它没有被修改并造成不良影响的风险。 + 而对于 ``sstatus/sepc`` 而言，它们会在 Trap 处理的全程有意义（在 Trap 控制流最后 ``sret`` 的时候还用到了它们），而且确实会出现 + Trap 嵌套的情况使得它们的值被覆盖掉。所以我们需要将它们也一起保存下来，并在 ``sret`` 之前恢复原样。 + + +Trap 管理 +------------------------------- + +Trap 上下文的保存与恢复 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +首先是具体实现 Trap 上下文保存和恢复的汇编代码。 + +.. _trap-context-save-restore: + + +在批处理操作系统初始化时，我们需要修改 ``stvec`` 寄存器来指向正确的 Trap 处理入口点。 + +.. code-block:: rust + :linenos: + + // os/src/trap/mod.rs + + core::arch::global_asm!(include_str!("trap.S")); + + pub fn init() { + extern "C" { fn __alltraps(); } + unsafe { + stvec::write(__alltraps as usize, TrapMode::Direct); + } + } + +这里我们引入了一个外部符号 ``__alltraps`` ，并将 ``stvec`` 设置为 Direct 模式指向它的地址。我们在 ``os/src/trap/trap.S`` +中实现 Trap 上下文保存/恢复的汇编代码，分别用外部符号 ``__alltraps`` 和 ``__restore`` 标记为函数，并通过 ``global_asm!`` 宏将 ``trap.S`` 这段汇编代码插入进来。 + +Trap 处理的总体流程如下：首先通过 ``__alltraps`` 将 Trap 上下文保存在内核栈上，然后跳转到使用 Rust 编写的 ``trap_handler`` 函数 +完成 Trap 分发及处理。当 ``trap_handler`` 返回之后，使用 ``__restore`` 从保存在内核栈上的 Trap 上下文恢复寄存器。最后通过一条 +``sret`` 指令回到应用程序执行。 + +首先是保存 Trap 上下文的 ``__alltraps`` 的实现： + +.. code-block:: riscv + :linenos: + + # os/src/trap/trap.S + + .macro SAVE_GP n + sd x\n, \n*8(sp) + .endm + + .align 2 + __alltraps: + csrrw sp, sscratch, sp + # now sp->kernel stack, sscratch->user stack + # allocate a TrapContext on kernel stack + addi sp, sp, -34*8 + # save general-purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they were saved on kernel stack + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it on the kernel stack + csrr t2, sscratch + sd t2, 2*8(sp) + # set input argument of trap_handler(cx: &mut TrapContext) + mv a0, sp + call trap_handler + +- 第 7 行我们使用 ``.align`` 将 ``__alltraps`` 的地址 4 字节对齐，这是 RISC-V 特权级规范的要求； +- 第 9 行的 ``csrrw`` 原型是 :math:`\text{csrrw rd, csr, rs}` 可以将 CSR 当前的值读到通用寄存器 :math:`\text{rd}` 中，然后将 + 通用寄存器 :math:`\text{rs}` 的值写入该 CSR 。因此这里起到的是交换 sscratch 和 sp 的效果。在这一行之前 sp 指向用户栈， sscratch + 指向内核栈（原因稍后说明），现在 sp 指向内核栈， sscratch 指向用户栈。 +- 第 12 行，我们准备在内核栈上保存 Trap 上下文，于是预先分配 :math:`34\times 8` 字节的栈帧，这里改动的是 sp ，说明确实是在内核栈上。 +- 第 13~24 行，保存 Trap 上下文的通用寄存器 x0~x31，跳过 x0 和 tp(x4)，原因之前已经说明。我们在这里也不保存 sp(x2)，因为它在第 9 行 + 后指向的是内核栈。用户栈的栈指针保存在 sscratch 中，必须通过 ``csrr`` 指令读到通用寄存器中后才能使用，因此我们先考虑保存其它通用寄存器，腾出空间。 + + 我们要基于 sp 来找到每个寄存器应该被保存到的正确的位置。实际上，在栈帧分配之后，我们可用于保存 Trap 上下文的地址区间为 :math:`[\text{sp},\text{sp}+8\times34)` ， + 按照 ``TrapContext`` 结构体的内存布局，基于内核栈的位置（sp所指地址）来从低地址到高地址分别按顺序放置 x0~x31这些通用寄存器，最后是 sstatus 和 sepc 。因此通用寄存器 xn + 应该被保存在地址区间 :math:`[\text{sp}+8n,\text{sp}+8(n+1))` 。 + + 为了简化代码，x5~x31 这 27 个通用寄存器我们通过类似循环的 ``.rept`` 每次使用 ``SAVE_GP`` 宏来保存，其实质是相同的。注意我们需要在 + ``trap.S`` 开头加上 ``.altmacro`` 才能正常使用 ``.rept`` 命令。 +- 第 25~28 行，我们将 CSR sstatus 和 sepc 的值分别读到寄存器 t0 和 t1 中然后保存到内核栈对应的位置上。指令 + :math:`\text{csrr rd, csr}` 的功能就是将 CSR 的值读到寄存器 :math:`\text{rd}` 中。这里我们不用担心 t0 和 t1 被覆盖， + 因为它们刚刚已经被保存了。 +- 第 30~31 行专门处理 sp 的问题。首先将 sscratch 的值读到寄存器 t2 并保存到内核栈上，注意： sscratch 的值是进入 Trap 之前的 sp 的值，指向 + 用户栈。而现在的 sp 则指向内核栈。 +- 第 33 行令 :math:`\text{a}_0\leftarrow\text{sp}`，让寄存器 a0 指向内核栈的栈指针也就是我们刚刚保存的 Trap 上下文的地址， + 这是由于我们接下来要调用 ``trap_handler`` 进行 Trap 处理，它的第一个参数 ``cx`` 由调用规范要从 a0 中获取。而 Trap 处理函数 + ``trap_handler`` 需要 Trap 上下文的原因在于：它需要知道其中某些寄存器的值，比如在系统调用的时候应用程序传过来的 syscall ID 和 + 对应参数。我们不能直接使用这些寄存器现在的值，因为它们可能已经被修改了，因此要去内核栈上找已经被保存下来的值。 + + +.. _term-atomic-instruction: + +.. note:: + + **CSR 相关原子指令** + + RISC-V 中读写 CSR 的指令是一类能不会被打断地完成多个读写操作的指令。这种不会被打断地完成多个操作的指令被称为 **原子指令** (Atomic Instruction)。这里的 **原子** 的含义是“不可分割的最小个体”，也就是说指令的多个操作要么都不完成，要么全部完成，而不会处于某种中间状态。 + +当 ``trap_handler`` 返回之后会从调用 ``trap_handler`` 的下一条指令开始执行，也就是从栈上的 Trap 上下文恢复的 ``__restore`` ： + +.. _code-restore: + +.. code-block:: riscv + :linenos: + + .macro LOAD_GP n + ld x\n, \n*8(sp) + .endm + + __restore: + # case1: start running app by __restore + # case2: back to U after handling trap + mv sp, a0 + # now sp->kernel stack(after allocated), sscratch->user stack + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + ld t2, 2*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + csrw sscratch, t2 + # restore general-purpuse registers except sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # release TrapContext on kernel stack + addi sp, sp, 34*8 + # now sp->kernel stack, sscratch->user stack + csrrw sp, sscratch, sp + sret + +- 第 8 行比较奇怪，我们暂且不管，假设它从未发生，那么 sp 仍然指向内核栈的栈顶。 +- 第 11~24 行负责从内核栈顶的 Trap 上下文恢复通用寄存器和 CSR 。注意我们要先恢复 CSR 再恢复通用寄存器，这样我们使用的三个临时寄存器 + 才能被正确恢复。 +- 在第 26 行之前，sp 指向保存了 Trap 上下文之后的内核栈栈顶， sscratch 指向用户栈栈顶。我们在第 26 行在内核栈上回收 Trap 上下文所 + 占用的内存，回归进入 Trap 之前的内核栈栈顶。第 27 行，再次交换 sscratch 和 sp，现在 sp 重新指向用户栈栈顶，sscratch 也依然保存 + 进入 Trap 之前的状态并指向内核栈栈顶。 +- 在应用程序控制流状态被还原之后，第 28 行我们使用 ``sret`` 指令回到 U 特权级继续运行应用程序控制流。 + +Trap 分发与处理 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Trap 在使用 Rust 实现的 ``trap_handler`` 函数中完成分发和处理： + +.. code-block:: rust + :linenos: + + // os/src/trap/mod.rs + + #[no_mangle] + pub fn trap_handler(cx: &mut TrapContext) -> &mut TrapContext { + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + cx.sepc += 4; + cx.x[10] = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]) as usize; + } + Trap::Exception(Exception::StoreFault) | + Trap::Exception(Exception::StorePageFault) => { + println!("[kernel] PageFault in application, core dumped."); + run_next_app(); + } + Trap::Exception(Exception::IllegalInstruction) => { + println!("[kernel] IllegalInstruction in application, core dumped."); + run_next_app(); + } + _ => { + panic!("Unsupported trap {:?}, stval = {:#x}!", scause.cause(), stval); + } + } + cx + } + +- 第 4 行声明返回值为 ``&mut TrapContext`` 并在第 25 行实际将传入的 ``cx`` 原样返回，因此在 ``__restore`` 的时候 ``a0`` 寄存器在调用 + ``trap_handler`` 前后并没有发生变化，仍然指向分配 Trap 上下文之后的内核栈栈顶，和此时 ``sp`` 的值相同，我们 :math:`\text{sp}\leftarrow\text{a}_0` + 并不会有问题； +- 第 7 行根据 ``scause`` 寄存器所保存的 Trap 的原因进行分发处理。这里我们无需手动操作这些 CSR ，而是使用 Rust 第三方库 riscv 。 +- 第 8~11 行，发现触发 Trap 的原因是来自 U 特权级的 Environment Call，也就是系统调用。这里我们首先修改保存在内核栈上的 Trap 上下文里面 + sepc，让其增加 4。这是因为我们知道这是一个由 ``ecall`` 指令触发的系统调用，在进入 Trap 的时候，硬件会将 sepc 设置为这条 ``ecall`` + 指令所在的地址（因为它是进入 Trap 之前最后一条执行的指令）。而在 Trap 返回之后，我们希望应用程序控制流从 ``ecall`` 的下一条指令 + 开始执行。因此我们只需修改 Trap 上下文里面的 sepc，让它增加 ``ecall`` 指令的码长，也即 4 字节。这样在 ``__restore`` 的时候 sepc + 在恢复之后就会指向 ``ecall`` 的下一条指令，并在 ``sret`` 之后从那里开始执行。 + + 用来保存系统调用返回值的 a0 寄存器也会同样发生变化。我们从 Trap 上下文取出作为 syscall ID 的 a7 和系统调用的三个参数 a0~a2 传给 + ``syscall`` 函数并获取返回值。 ``syscall`` 函数是在 ``syscall`` 子模块中实现的。 这段代码是处理正常系统调用的控制逻辑。 +- 第 12~20 行，分别处理应用程序出现访存错误和非法指令错误的情形。此时需要打印错误信息并调用 ``run_next_app`` 直接切换并运行下一个 + 应用程序。 +- 第 21 行开始，当遇到目前还不支持的 Trap 类型的时候，批处理操作系统整个 panic 报错退出。 + +对于系统调用而言， ``syscall`` 函数并不会实际处理系统调用，而只是根据 syscall ID 分发到具体的处理函数： + +.. code-block:: rust + :linenos: + + // os/src/syscall/mod.rs + + pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize { + match syscall_id { + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_EXIT => sys_exit(args[0] as i32), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } + } + +这里我们会将传进来的参数 ``args`` 转化成能够被具体的系统调用处理函数接受的类型。它们的实现都非常简单： + +.. code-block:: rust + :linenos: + + // os/src/syscall/fs.rs + + const FD_STDOUT: usize = 1; + + pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDOUT => { + let slice = unsafe { core::slice::from_raw_parts(buf, len) }; + let str = core::str::from_utf8(slice).unwrap(); + print!("{}", str); + len as isize + }, + _ => { + panic!("Unsupported fd in sys_write!"); + } + } + } + + // os/src/syscall/process.rs + + pub fn sys_exit(xstate: i32) -> ! { + println!("[kernel] Application exited with code {}", xstate); + run_next_app() + } + +- ``sys_write`` 我们将传入的位于应用程序内的缓冲区的开始地址和长度转化为一个字符串 ``&str`` ，然后使用批处理操作系统已经实现的 ``print!`` + 宏打印出来。这里我们并没有检查传入参数的安全性，存在安全隐患。 +- ``sys_exit`` 打印退出的应用程序的返回值并同样调用 ``run_next_app`` 切换到下一个应用程序。 + +.. _ch2-app-execution: + +执行应用程序 +------------------------------------- + +当批处理操作系统初始化完成，或者是某个应用程序运行结束或出错的时候，我们要调用 ``run_next_app`` 函数切换到下一个应用程序。此时 CPU 运行在 +S 特权级，而它希望能够切换到 U 特权级。在 RISC-V 架构中，唯一一种能够使得 CPU 特权级下降的方法就是通过 Trap 返回系列指令，比如 +``sret`` 。事实上，在运行应用程序之前要完成如下这些工作： + +- 跳转到应用程序入口点 ``0x80400000``； +- 将使用的栈切换到用户栈； +- 在 ``__alltraps`` 时我们要求 ``sscratch`` 指向内核栈，这个也需要在此时完成； +- 从 S 特权级切换到 U 特权级。 + +它们可以通过复用 ``__restore`` 的代码来更容易的实现上述工作。我们只需要在内核栈上压入一个为启动应用程序而特殊构造的 Trap 上下文，再通过 ``__restore`` 函数，就能 +让这些寄存器到达启动应用程序所需要的上下文状态。 + +.. code-block:: rust + :linenos: + + // os/src/trap/context.rs + + impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { self.x[2] = sp; } + pub fn app_init_context(entry: usize, sp: usize) -> Self { + let mut sstatus = sstatus::read(); + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + }; + cx.set_sp(sp); + cx + } + } + +为 ``TrapContext`` 实现 ``app_init_context`` 方法，修改其中的 sepc 寄存器为应用程序入口点 ``entry``， sp 寄存器为我们设定的 +一个栈指针，并将 sstatus 寄存器的 ``SPP`` 字段设置为 User 。 + +在 ``run_next_app`` 函数中我们能够看到： + +.. code-block:: rust + :linenos: + + // os/src/batch.rs + + pub fn run_next_app() -> ! { + let mut app_manager = APP_MANAGER.exclusive_access(); + let current_app = app_manager.get_current_app(); + unsafe { + app_manager.load_app(current_app); + } + app_manager.move_to_next_app(); + drop(app_manager); + // before this we have to drop local variables related to resources manually + // and release the resources + extern "C" { + fn __restore(cx_addr: usize); + } + unsafe { + __restore(KERNEL_STACK.push_context(TrapContext::app_init_context( + APP_BASE_ADDRESS, + USER_STACK.get_sp(), + )) as *const _ as usize); + } + panic!("Unreachable in batch::run_current_app!"); + } + + +``__restore`` 所做的事情是在内核栈上压入一个 Trap 上下文，其 ``sepc`` 是应用程序入口地址 ``0x80400000`` ，其 ``sp`` 寄存器指向用户栈，其 ``sstatus`` +的 ``SPP`` 字段被设置为 User 。 +``push_context`` 的返回值是内核栈压入 Trap 上下文之后的栈顶，它会被作为 ``__restore`` 的参数（ +回看 :ref:`__restore 代码 ` ，这时我们可以理解为何 ``__restore`` 函数的起始部分会完成 +:math:`\text{sp}\leftarrow\text{a}_0` ），这使得在 ``__restore`` 函数中 ``sp`` 仍然可以指向内核栈的栈顶。这之后，就和执行一次普通的 +``__restore`` 函数调用一样了。 + +.. note:: + + 有兴趣的读者可以思考： sscratch 是何时被设置为内核栈顶的？ + + + +.. + 马老师发生甚么事了？ + -- + 这里要说明目前只考虑从 U Trap 到 S ，而实际上 Trap 的要素就有：Trap 之前在哪个特权级，Trap 在哪个特权级处理。这个对于中断和异常 + 都是如此，只不过中断可能跟特权级的关系稍微更紧密一点。毕竟中断的类型都是跟特权级挂钩的。但是对于 Trap 而言有一点是共同的，也就是触发 + Trap 不会导致优先级下降。从中断/异常的代理就可以看出从定义上就不允许代理到更低的优先级。而且代理只能逐级代理，目前我们能操作的只有从 + M 代理到 S，其他代理都基本只出现在指令集拓展或者硬件还不支持。中断的情况是，如果是属于某个特权级的中断，不能在更低的优先级处理。事实上 + 这个中断只可能在 CPU 处于不会更高的优先级上收到（否则会被屏蔽），而 Trap 之后优先级不会下降（Trap 代理机制决定），这样就自洽了。 + -- + 之前提到异常是说需要执行环境功能的原因与某条指令的执行有关。而 Trap 的定义更加广泛一些，就是在执行某条指令之后发现需要执行环境的功能， + 如果是中断的话 Trap 回来之后默认直接执行下一条指令，如果是异常的话硬件会将 sepc 设置为 Trap 发生之前最后执行的那条指令，而异常发生 + 的原因不一定和这条指令的执行有关。应该指出的是，在大多数情况下都是和最后这条指令的执行有关。但在缓存的作用下也会出现那种特别极端的情况。 + -- + 然后是 Trap 到 S，就有 S 模式的一些相关 CSR，以及从 U Trap 到 S，硬件会做哪些事情（包括触发异常的一瞬间，以及处理完成调用 sret + 之后）。然后指出从用户的视角来看，如果是 ecall 的话， Trap 回来之后应该从 ecall 的下一条指令开始执行，且执行现场不能发生变化。 + 所以就需要将应用执行环境保存在内核栈上（还需要换栈！）。栈存在的原因可能是 Trap handler 是一条新的运行在 S 特权级的执行流，所以 + 这个可以理解成跨特权级的执行流切换，确实就复杂一点，要保存的内容也相对多一点。而下一章多任务的任务切换是全程发生在 S 特权级的执行流 + 切换，所以会简单一点，保存的通用寄存器大概率更少（少在调用者保存寄存器），从各种意义上都很像函数调用。从不同特权级的角度来解释换栈 + 是出于安全性，应用不应该看到 Trap 执行流的栈，这样做完之后，虽然理论上可以访问，但应用不知道内核栈的位置应该也有点麻烦。 + -- + 然后是 rust_trap 的处理，尤其是奇妙的参数传递，内部处理逻辑倒是非常简单。 + -- + 最后是如何利用 __restore 初始化应用的执行环境，包括如何设置入口点、用户栈以及保证在 U 特权级执行。 + + + + + diff --git a/guide/source/chapter2/5exercise.rst b/guide/source/chapter2/5exercise.rst new file mode 100644 index 0000000..fbeaa2c --- /dev/null +++ b/guide/source/chapter2/5exercise.rst @@ -0,0 +1,139 @@ +chapter2练习（已废弃） +===================================================== + +.. toctree:: + :hidden: + :maxdepth: 4 + +编程练习 +------------------------------- + +简单安全检查 ++++++++++++++++++++++++++++++++ + +.. lab2 中，我们实现了第一个系统调用 ``sys_write``，这使得我们可以在用户态输出信息。但是 os 在提供服务的同时，还有保护 os 本身以及其他用户程序不受错误或者恶意程序破坏的功能。 + +.. 由于还没有实现虚拟内存，我们可以在用户程序中指定一个属于其他程序字符串，并将它输出，这显然是不合理的，因此我们要对 sys_write 做检查： + +.. - sys_write 仅能输出位于程序本身内存空间内的数据，否则报错。 + +实验要求 ++++++++++++++++++++++++++++++++ +.. - 实现分支: ch2。 +.. - 完成实验指导书中的内容，能运行用户态程序并执行 sys_write，sys_exit 系统调用。 +.. - 为 sys_write 增加安全性检查，并通过 `Rust测例 `_ 中 chapter2 对应的所有测例，测例详情见对应仓库。 + +.. challenge: 支持多核，实现多个核运行用户程序。 + +实验约定 +++++++++++++++++++++++++++++++ + +.. 在第二章的测试中，我们对于内核有如下仅仅为了测试方便的要求，请调整你的内核代码来符合这些要求。 + +.. - 用户栈大小必须为 4096，且按照 4096 字节对齐。这一规定可以在实验4开始删除，仅仅为通过 lab2/3 测例设置。 + +.. .. _inherit-last-ch-changes: + +.. .. note:: + +.. **如何快速继承上一章练习题的修改** + +.. 从这一章开始，在完成本章习题之前，首先要做的就是将上一章框架的修改继承到本章的框架代码。出于各种原因，实际上通过 ``git merge`` 并不是很方便，这里给出一种打 patch 的方法，希望能够有所帮助。 + +.. 1. 切换到上一章的分支，通过 ``git log`` 找到你在此分支上的第一次 commit 的前一个 commit 的 ID ，复制其前 8 位，记作 ``base-commit`` 。假设分支上最新的一次 commit ID 是 ``last-commit`` 。 +.. 2. 确保你位于项目根目录 ``rCore-Tutorial-v3`` 下。通过 ``git diff > `` 即可在 ``patch-path`` 路径位置（比如 ``~/Desktop/chx.patch`` ）生成一个描述你对于上一章分支进行的全部修改的一个补丁文件。打开看一下，它给出了每个被修改的文件中涉及了哪些块的修改，还附加了块前后的若干行代码。如果想更加灵活进行合并的话，可以通过 ``git format-patch `` 命令在当前目录下生成一组补丁，它会对于 ``base-commit`` 后面的每一次 commit 均按照顺序生成一个补丁。 +.. 3. 切换到本章分支，通过 ``git apply --reject `` 来将一个补丁打到当前章节上。它的大概原理是对于补丁中的每个被修改文件中的每个修改块，尝试通过块的前后若干行代码来定位它在当前分支上的位置并进行替换。有一些块可能无法匹配，此时会生成与这些块所在的文件同名的 ``*.rej`` 文件，描述了哪些块替换失败了。在项目根目录 ``rCore-Tutorial-v3`` 下，可以通过 ``find . -name *.rej`` 来找到所有相关的 ``*.rej`` 文件并手动完成替换。 +.. 4. 在处理完所有 ``*.rej`` 之后，将它们删除并 commit 一下。现在就可以开始本章的实验了。 + + +实验检查 +++++++++++++++++++++++++++++++ + +.. - 实验目录要求(Rust) + +.. .. code-block:: + +.. ├── os(内核实现) +.. │   ├── build.rs (在这里实现用户程序的打包) +.. │   ├── Cargo.toml(配置文件) +.. │   ├── Makefile (要求 make run 可以正确执行，尽量不输出调试信息) +.. │   ├── src(所有内核的源代码放在 os/src 目录下) +.. │   ├── main.rs(内核主函数) +.. │   ├── ... +.. ├── reports +.. │   ├── lab2.md/pdf +.. │   └── ... +.. ├── README.md（其他必要的说明） +.. ├── ... + +.. 参考示例目录结构。目标用户目录 ``../user/build/bin``。 + +.. - 检查 + +.. .. code-block:: console + +.. $ git checkout ch2 +.. $ cd os +.. $ make run + +.. 可以正确执行正确执行目标用户测例，并得到预期输出（详见测例注释）。 + + +简答题 +------------------------------- + +.. 1. 正确进入 U 态后，程序的特征还应有：使用 S 态特权指令，访问 S 态寄存器后会报错。目前由于一些其他原因，这些问题不太好测试，请同学们可以自行测试这些内容（参考 `前三个测例 `_ ），描述程序出错行为，同时注意注明你使用的 sbi 及其版本。 + +.. 2. 请结合用例理解 `trap.S `_ 中两个函数 ``__alltraps`` 和 ``__restore`` 的作用，并回答如下几个问题: + +.. 1. L40：刚进入 ``__restore`` 时，``a0`` 代表了什么值。请指出 ``__restore`` 的两种使用情景。 + +.. 2. L46-L51：这几行汇编代码特殊处理了哪些寄存器？这些寄存器的的值对于进入用户态有何意义？请分别解释。 + +.. .. code-block:: riscv + +.. ld t0, 32*8(sp) +.. ld t1, 33*8(sp) +.. ld t2, 2*8(sp) +.. csrw sstatus, t0 +.. csrw sepc, t1 +.. csrw sscratch, t2 + +.. 3. L53-L59：为何跳过了 ``x2`` 和 ``x4``？ + +.. .. code-block:: riscv + +.. ld x1, 1*8(sp) +.. ld x3, 3*8(sp) +.. .set n, 5 +.. .rept 27 +.. LOAD_GP %n +.. .set n, n+1 +.. .endr + +.. 4. L63：该指令之后，``sp`` 和 ``sscratch`` 中的值分别有什么意义？ + +.. .. code-block:: riscv + +.. csrrw sp, sscratch, sp + +.. 5. ``__restore``：中发生状态切换在哪一条指令？为何该指令执行之后会进入用户态？ + +.. 6. L13：该指令之后，``sp`` 和 ``sscratch`` 中的值分别有什么意义？ + +.. .. code-block:: riscv + +.. csrrw sp, sscratch, sp + +.. 7. 从 U 态进入 S 态是哪一条指令发生的？ + +.. 3. 程序陷入内核的原因有中断和异常（系统调用），请问 riscv64 支持哪些中断 / 异常？如何判断进入内核是由于中断还是异常？描述陷入内核时的几个重要寄存器及其值。 + +.. 4. 对于任何中断，``__alltraps`` 中都需要保存所有寄存器吗？你有没有想到一些加速 ``__alltraps`` 的方法？简单描述你的想法。 + +报告要求 +------------------------------- + +- 简单总结你实现的功能（200字以内，不要贴代码）。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter2/index.rst b/guide/source/chapter2/index.rst new file mode 100644 index 0000000..5f1083d --- /dev/null +++ b/guide/source/chapter2/index.rst @@ -0,0 +1,13 @@ +.. _link-chapter2: + +第二章：批处理系统 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 2application + 3batch-system + 4trap-handling + diff --git a/guide/source/chapter3/0intro.rst b/guide/source/chapter3/0intro.rst new file mode 100644 index 0000000..84d6440 --- /dev/null +++ b/guide/source/chapter3/0intro.rst @@ -0,0 +1,209 @@ +引言 +======================================== + +本章导读 +-------------------------- + + +本章的目标是实现分时多任务系统，它能并发地执行多个用户程序，并调度这些程序。为此需要实现 + +- 一次性加载所有用户程序，减少任务切换开销； +- 支持任务切换机制，保存切换前后程序上下文； +- 支持程序主动放弃处理器，实现 yield 系统调用； +- 以时间片轮转算法调度用户程序，实现资源的时分复用。 + + +实践体验 +------------------------------------- + +.. code-block:: console + + $ git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S.git + $ cd rCore-Tutorial-Code-2022S + $ git checkout ch3 + $ git clone https://github.com/LearningOS/rCore-Tutorial-Test-2022S.git user + +在 qemu 模拟器上运行本章代码： + +.. code-block:: console + + $ cd os + $ make run + +运行代码，看到用户程序交替输出信息： + +.. code-block:: + + [rustsbi] RustSBI version 0.2.0-alpha.4 + .______ __ __ _______.___________. _______..______ __ + | _ \ | | | | / | | / || _ \ | | + | |_) | | | | | | (----`---| |----`| (----`| |_) || | + | / | | | | \ \ | | \ \ | _ < | | + | |\ \----.| `--' |.----) | | | .----) | | |_) || | + | _| `._____| \______/ |_______/ |__| |_______/ |______/ |__| + + [rustsbi] Implementation: RustSBI-QEMU Version 0.0.1 + [rustsbi-dtb] Hart count: cluster0 with 1 cores + [rustsbi] misa: RV64ACDFIMSU + [rustsbi] mideleg: ssoft, stimer, sext (0x222) + [rustsbi] medeleg: ima, ia, bkpt, la, sa, uecall, ipage, lpage, spage (0xb1ab) + [rustsbi] pmp0: 0x80000000 ..= 0x800fffff (rwx) + [rustsbi] pmp1: 0x80000000 ..= 0x807fffff (rwx) + [rustsbi] pmp2: 0x0 ..= 0xffffffffffffff (---) + [rustsbi] enter supervisor 0x80200000 + [kernel] Hello, world! + power_3 [10000/200000] + power_3 [20000/200000] + power_3 [30000/200000] + power_3 [40000/200000] + power_3 [50000/200000] + power_3 [60000/200000] + power_3 [70000/200000] + power_3 [80000/200000] + power_3 [90000/200000] + power_3 [100000/200000] + power_3 [110000/200000] + power_3 [120000/200000] + power_3 [130000/200000] + power_3 [140000/200000] + power_3 [150000/200000] + power_3 [160000/200000] + power_3 [170000/200000] + power_3 [180000/200000] + power_3 [190000/200000] + power_3 [200000/200000] + 3^200000 = 871008973(MOD 998244353) + Test power_3 OK! + power_5 [10000/140000] + power_5 [20000/140000] + power_5 [30000/140000] + power_5 [40000/140000] + power_5 [50000/140000] + power_5 [60000/140000] + power_7 [10000/160000] + power_7 [20000/160000] + power_7 [30000/160000] + power_7 [40000/160000] + power_7 [50000/160000] + power_7 [60000/160000] + power_7 [70000/160000] + power_7 [80000/160000] + power_7 [90000/160000] + power_7 [100000/160000] + power_7 [110000/160000] + power_7 [120000/160000] + power_7 [130000/160000] + power_7 [140000/160000] + power_7 [150000/160000] + power_7 [160000/160000] + 7^160000 = 667897727(MOD 998244353) + Test power_7 OK! + get_time OK! 42 + current time_msec = 42 + AAAAAAAAAA [1/5] + BBBBBBBBBB [1/5] + CCCCCCCCCC [1/5] + power_5 [70000/140000] + AAAAAAAAAA [2/5] + BBBBBBBBBB [2/5] + CCCCCCCCCC [2/5] + power_5 [80000/140000] + power_5 [90000/140000] + power_5 [100000/140000] + power_5 [110000/140000] + power_5 [120000/140000] + power_5 [130000/140000] + power_5 [140000/140000] + 5^140000 = 386471875(MOD 998244353) + Test power_5 OK! + AAAAAAAAAA [3/5] + BBBBBBBBBB [3/5] + CCCCCCCCCC [3/5] + AAAAAAAAAA [4/5] + BBBBBBBBBB [4/5] + CCCCCCCCCC [4/5] + AAAAAAAAAA [5/5] + BBBBBBBBBB [5/5] + CCCCCCCCCC [5/5] + Test write A OK! + Test write B OK! + Test write C OK! + time_msec = 143 after sleeping 100 ticks, delta = 101ms! + Test sleep1 passed! + Test sleep OK! + Panicked at src/task/mod.rs:98 All applications completed! + + +本章代码树 +--------------------------------------------- + +.. code-block:: + + ── os +    ├── build.rs +    ├── Cargo.toml +    ├── Makefile +    └── src +    ├── batch.rs(移除：功能分别拆分到 loader 和 task 两个子模块) +   ├── config.rs(新增：保存内核的一些配置) +    ├── console.rs + ├── logging.rs + ├── sync +    ├── entry.asm +    ├── lang_items.rs +    ├── link_app.S +    ├── linker.ld +    ├── loader.rs(新增：将应用加载到内存并进行管理) +    ├── main.rs(修改：主函数进行了修改) +    ├── sbi.rs(修改：引入新的 sbi call set_timer) +    ├── syscall(修改：新增若干 syscall) +    │   ├── fs.rs +    │   ├── mod.rs +    │   └── process.rs +    ├── task(新增：task 子模块，主要负责任务管理) +    │   ├── context.rs(引入 Task 上下文 TaskContext) +    │   ├── mod.rs(全局任务管理器和提供给其他模块的接口) +    │   ├── switch.rs(将任务切换的汇编代码解释为 Rust 接口 __switch) +    │   ├── switch.S(任务切换的汇编代码) +    │   └── task.rs(任务控制块 TaskControlBlock 和任务状态 TaskStatus 的定义) +    ├── timer.rs(新增：计时器相关) +    └── trap +    ├── context.rs +    ├── mod.rs(修改：时钟中断相应处理) +    └── trap.S + + cloc os + ------------------------------------------------------------------------------- + Language files blank comment code + ------------------------------------------------------------------------------- + Rust 21 87 20 627 + Assembly 4 12 22 144 + make 1 11 4 36 + TOML 1 2 1 10 + ------------------------------------------------------------------------------- + SUM: 27 112 47 817 + ------------------------------------------------------------------------------- + + +.. 本章代码导读 +.. ----------------------------------------------------- + +.. 本章的重点是实现对应用之间的协作式和抢占式任务切换的操作系统支持。与上一章的操作系统实现相比，有如下一些不同的情况导致实现上也有差异： + +.. - 多个应用同时放在内存中，所以他们的起始地址是不同的，且地址范围不能重叠 +.. - 应用在整个执行过程中会暂停或被抢占，即会有主动或被动的任务切换 + +.. 这些实现上差异主要集中在对应用程序执行过程的管理、支持应用程序暂停的系统调用和主动切换应用程序所需的时钟中断机制的管理。 + +.. 对于第一个不同情况，需要对应用程序的地址空间布局进行调整，每个应用的地址空间都不相同，且不能重叠。这并不要修改应用程序本身，而是通过一个脚本 ``build.py`` 来针对每个应用程序修改链接脚本 ``linker.ld`` 中的 ``BASE_ADDRESS`` ，让编译器在编译不同应用时用到的 ``BASE_ADDRESS`` 都不同，且有足够大的地址间隔。这样就可以让每个应用所在的内存空间是不同的。 + +.. 对于第二个不同情况，需要实现任务切换，这就需要在上一章的 ``trap`` 上下文切换的基础上，再加上一个 ``task`` 上下文切换，才能完成完整的任务切换。这里面的关键数据结构是表示应用执行上下文的 ``TaskContext`` 数据结构和具体完成上下文切换的汇编语言编写的 ``__switch`` 函数。一个应用的执行需要被操作系统管理起来，这是通过 ``TaskControlBlock`` 数据结构来表示应用执行上下文的动态过程和动态状态（运行态、就绪态等）。而为了做好应用程序第一次执行的前期初始化准备， ``TaskManager`` 数据结构的全局变量实例 ``TASK_MANAGER`` 描述了应用程序初始化所需的数据， 而 ``TASK_MANAGER`` 的初始化赋值过程是实现这个准备的关键步骤。 + +.. 应用程序可以在用户态执行后，还需要有新的系统调用 ``sys_yield`` 的实现来支持应用自己的主动暂停；还要添加对时钟中断的处理，来支持抢占应用执行的抢占式切换。有了时钟中断，就可以在一定时间内打断应用的执行，并主动切换到另外一个应用，这部分主要是通过对 ``trap_handler`` 函数中进行扩展，来完成在时钟中断产生时可能进行的任务切换。 ``TaskManager`` 数据结构的成员函数 ``run_next_task`` 来实现基于任务控制块的切换，并会具体调用 ``__switch`` 函数完成硬件相关部分的任务上下文切换。 + +.. 如果理解了上面的数据结构和相关函数的关系和相互调用的情况，那么就比较容易理解本章改进后的操作系统了。 + + +.. .. [#prionosuchus] 锯齿螈身长可达9米，是迄今出现过的最大的两栖动物，是二叠纪时期江河湖泊和沼泽中的顶级掠食者。 +.. .. [#eoraptor] 始初龙（也称始盗龙）是后三叠纪时期的两足食肉动物，也是目前所知最早的恐龙，它们只有一米长，却代表着恐龙的黎明。 +.. .. [#coelophysis] 腔骨龙（也称虚形龙）最早出现于三叠纪晚期，它体形纤细，善于奔跑，以小型动物为食。 diff --git a/guide/source/chapter3/1multi-loader.rst b/guide/source/chapter3/1multi-loader.rst new file mode 100644 index 0000000..7ebe569 --- /dev/null +++ b/guide/source/chapter3/1multi-loader.rst @@ -0,0 +1,71 @@ +多道程序放置与加载 +===================================== + +多道程序放置 +---------------------------- + + +在第二章中，内核让所有应用都共享同一个固定的起始地址。 +正因如此，内存中同时最多只能驻留一个应用， + +要一次加载运行多个程序，就要求每个用户程序被内核加载到内存中的起始地址都不同。 +为此，我们编写脚本 ``user/build.py`` 为每个应用定制各自的起始地址。 +它的思路很简单，对于每一个应用程序，使用 ``cargo rustc`` 单独编译， +用 ``-Clink-args=-Ttext=xxxx`` 选项指定链接时 .text 段的地址为 ``0x80400000 + app_id * 0x20000`` 。 + +.. note:: + + qemu 预留的内存空间是有限的，如果加载的程序过多，程序地址超出内存空间，可能出现 ``core dumped``. + +多道程序加载 +---------------------------- + +在第二章中负责应用加载和执行的子模块 ``batch`` 被拆分为 ``loader`` 和 ``task`` ， +前者负责启动时加载应用程序，后者负责切换和调度。 + +其中， ``loader`` 模块的 ``load_apps`` 函数负责将所有用户程序在内核初始化的时一并加载进内存。 + +.. code-block:: rust + :linenos: + + // os/src/loader.rs + + pub fn load_apps() { + extern "C" { + fn _num_app(); + } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = get_num_app(); + let app_start = unsafe { core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1) }; + // clear i-cache first + unsafe { + core::arch::asm!("fence.i"); + } + // load apps + for i in 0..num_app { + let base_i = get_base_i(i); + // clear region + (base_i..base_i + APP_SIZE_LIMIT) + .for_each(|addr| unsafe { (addr as *mut u8).write_volatile(0) }); + // load app from data section to memory + let src = unsafe { + core::slice::from_raw_parts(app_start[i] as *const u8, app_start[i + 1] - app_start[i]) + }; + let dst = unsafe { core::slice::from_raw_parts_mut(base_i as *mut u8, src.len()) }; + dst.copy_from_slice(src); + } + } + +第 :math:`i` 个应用被加载到以物理地址 ``base_i`` 开头的一段物理内存上，而 ``base_i`` 的计算方式如下： + +.. code-block:: rust + :linenos: + + // os/src/loader.rs + + fn get_base_i(app_id: usize) -> usize { + APP_BASE_ADDRESS + app_id * APP_SIZE_LIMIT + } + +我们可以在 ``config`` 子模块中找到这两个常数， ``APP_BASE_ADDRESS`` 被设置为 ``0x80400000`` ， +而 ``APP_SIZE_LIMIT`` 和上一章一样被设置为 ``0x20000`` 。这种放置方式与 ``user/build.py`` 的实现一致。 diff --git a/guide/source/chapter3/2task-switching.rst b/guide/source/chapter3/2task-switching.rst new file mode 100644 index 0000000..b32046b --- /dev/null +++ b/guide/source/chapter3/2task-switching.rst @@ -0,0 +1,104 @@ +任务切换 +================================ + + +本节我们将见识操作系统的核心机制—— **任务切换** ， +即应用在运行中主动或被动地交出 CPU 的使用权，内核可以选择另一个程序继续执行。 +内核需要保证用户程序两次运行期间，任务上下文（如寄存器、栈等）保持一致。 + +任务切换的设计与实现 +--------------------------------- + +任务切换与上一章提及的 Trap 控制流切换相比，有如下异同： + +- 与 Trap 切换不同，它不涉及特权级切换，部分由编译器完成； +- 与 Trap 切换相同，它对应用是透明的。 + +事实上，任务切换是来自两个不同应用在内核中的 Trap 控制流之间的切换。 +当一个应用 Trap 到 S 态 OS 内核中进行进一步处理时， +其 Trap 控制流可以调用一个特殊的 ``__switch`` 函数。 +在 ``__switch`` 返回之后，Trap 控制流将继续从调用该函数的位置继续向下执行。 +而在调用 ``__switch`` 之后到返回前的这段时间里， +原 Trap 控制流 ``A`` 会先被暂停并被切换出去， CPU 转而运行另一个应用的 Trap 控制流 ``B`` 。 +``__switch`` 返回之后，原 Trap 控制流 ``A`` 才会从某一条 Trap 控制流 ``C`` 切换回来继续执行。 + +我们需要在 ``__switch`` 中保存 CPU 的某些寄存器，它们就是 **任务上下文** (Task Context)。 + +下面我们给出 ``__switch`` 的实现： + +.. code-block:: riscv + :linenos: + + # os/src/task/switch.S + + .altmacro + .macro SAVE_SN n + sd s\n, (\n+2)*8(a0) + .endm + .macro LOAD_SN n + ld s\n, (\n+2)*8(a1) + .endm + .section .text + .globl __switch + __switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + +它的两个参数分别是当前和即将被切换到的 Trap 控制流的 ``task_cx_ptr`` ，从 RISC-V 调用规范可知，它们分别通过寄存器 ``a0/a1`` 传入。 + +内核先把 ``current_task_cx_ptr`` 中包含的寄存器值逐个保存，再把 ``next_task_cx_ptr`` 中包含的寄存器值逐个恢复。 + +``TaskContext`` 里包含的寄存器有： + +.. code-block:: rust + :linenos: + + // os/src/task/context.rs + #[repr(C)] + pub struct TaskContext { + ra: usize, + sp: usize, + s: [usize; 12], + } + +``s0~s11`` 是被调用者保存寄存器， ``__switch`` 是用汇编编写的，编译器不会帮我们处理这些寄存器。 +保存 ``ra`` 很重要，它记录了 ``__switch`` 函数返回之后应该跳转到哪里继续执行。 + +我们将这段汇编代码 ``__switch`` 解释为一个 Rust 函数： + +.. code-block:: rust + :linenos: + + // os/src/task/switch.rs + + core::arch::global_asm!(include_str!("switch.S")); + + extern "C" { + pub fn __switch( + current_task_cx_ptr: *mut TaskContext, + next_task_cx_ptr: *const TaskContext); + } + +我们会调用该函数来完成切换功能，而不是直接跳转到符号 ``__switch`` 的地址。 +因此在调用前后，编译器会帮我们保存和恢复调用者保存寄存器。 diff --git a/guide/source/chapter3/3multiprogramming.rst b/guide/source/chapter3/3multiprogramming.rst new file mode 100644 index 0000000..5132c3a --- /dev/null +++ b/guide/source/chapter3/3multiprogramming.rst @@ -0,0 +1,317 @@ +管理多道程序 +========================================= + + +而内核为了管理任务，需要维护任务信息，相关内容包括： + +- 任务运行状态：未初始化、准备执行、正在执行、已退出 +- 任务控制块：维护任务状态和任务上下文 +- 任务相关系统调用：程序主动暂停 ``sys_yield`` 和主动退出 ``sys_exit`` + +yield 系统调用 +------------------------------------------------------------------------- + + +.. image:: multiprogramming.png + +上图描述了一种多道程序执行的典型情况。其中横轴为时间线，纵轴为正在执行的实体。 +开始时，蓝色应用向外设提交了一个请求，外设随即开始工作， +但是它要一段时间后才能返回结果。蓝色应用于是调用 ``sys_yield`` 交出 CPU 使用权， +内核让绿色应用继续执行。一段时间后 CPU 切换回蓝色应用，发现外设仍未返回结果， +于是再次 ``sys_yield`` 。直到第二次切换回蓝色应用，外设才处理完请求，于是蓝色应用终于可以向下执行了。 + +我们还会遇到很多其他需要等待其完成才能继续向下执行的事件，调用 ``sys_yield`` 可以避免等待过程造成的资源浪费。 + +.. code-block:: rust + :caption: 第三章新增系统调用（一） + + /// 功能：应用主动交出 CPU 所有权并切换到其他应用。 + /// 返回值：总是返回 0。 + /// syscall ID：124 + fn sys_yield() -> isize; + +用户库对应的实现和封装： + +.. code-block:: rust + + // user/src/syscall.rs + + pub fn sys_yield() -> isize { + syscall(SYSCALL_YIELD, [0, 0, 0]) + } + + // user/src/lib.rs + // yield 是 Rust 的关键字 + pub fn yield_() -> isize { sys_yield() } + +下文介绍内核应如何实现该系统调用。 + +任务控制块与任务运行状态 +--------------------------------------------------------- + +任务运行状态暂包括如下几种： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + #[derive(Copy, Clone, PartialEq)] + pub enum TaskStatus { + UnInit, // 未初始化 + Ready, // 准备运行 + Running, // 正在运行 + Exited, // 已退出 + } + +任务状态外和任务上下文一并保存在名为 **任务控制块** (Task Control Block) 的数据结构中： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + #[derive(Copy, Clone)] + pub struct TaskControlBlock { + pub task_status: TaskStatus, + pub task_cx: TaskContext, + } + + +任务控制块非常重要。在内核中，它就是应用的管理单位。后面的章节我们还会不断向里面添加更多内容。 + +任务管理器 +-------------------------------------- + +内核需要一个全局的任务管理器来管理这些任务控制块： + +.. code-block:: rust + + // os/src/task/mod.rs + + pub struct TaskManager { + num_app: usize, + inner: UPSafeCell, + } + + struct TaskManagerInner { + tasks: [TaskControlBlock; MAX_APP_NUM], + current_task: usize, + } + +这里用到了变量与常量分离的编程风格：字段 ``num_app`` 表示应用数目，它在 ``TaskManager`` 初始化后将保持不变； +而包裹在 ``TaskManagerInner`` 内的任务控制块数组 ``tasks``，以及正在执行的应用编号 ``current_task`` 会在执行过程中变化。 + +初始化 ``TaskManager`` 的全局实例 ``TASK_MANAGER``： + +.. code-block:: rust + :linenos: + + // os/src/task/mod.rs + + lazy_static! { + pub static ref TASK_MANAGER: TaskManager = { + let num_app = get_num_app(); + let mut tasks = [TaskControlBlock { + task_cx: TaskContext::zero_init(), + task_status: TaskStatus::UnInit, + }; MAX_APP_NUM]; + for (i, t) in tasks.iter_mut().enumerate().take(num_app) { + t.task_cx = TaskContext::goto_restore(init_app_cx(i)); + t.task_status = TaskStatus::Ready; + } + TaskManager { + num_app, + inner: unsafe { + UPSafeCell::new(TaskManagerInner { + tasks, + current_task: 0, + }) + }, + } + }; + } + +- 第 5 行：调用 ``loader`` 子模块提供的 ``get_num_app`` 接口获取链接到内核的应用总数； +- 第 10~12 行：依次对每个任务控制块进行初始化，将其运行状态设置为 ``Ready`` ，并在它的内核栈栈顶压入一些初始化 + 上下文，然后更新它的 ``task_cx`` 。一些细节我们会稍后介绍。 +- 从第 14 行开始：创建 ``TaskManager`` 实例并返回。 + +.. note:: + + 关于 Rust 迭代器语法如 ``iter_mut/(a..b)`` ，及其方法如 ``enumerate/map/find/take``，请参考 Rust 官方文档。 + +实现 sys_yield 和 sys_exit +---------------------------------------------------------------------------- + +``sys_yield`` 的实现用到了 ``task`` 子模块提供的 ``suspend_current_and_run_next`` 接口，这个接口如字面含义，就是暂停当前的应用并切换到下个应用。 + +.. code-block:: rust + + // os/src/syscall/process.rs + + use crate::task::suspend_current_and_run_next; + + pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 + } + +``sys_exit`` 基于 ``task`` 子模块提供的 ``exit_current_and_run_next`` 接口，它的含义是退出当前的应用并切换到下个应用： + +.. code-block:: rust + + // os/src/syscall/process.rs + + use crate::task::exit_current_and_run_next; + + pub fn sys_exit(exit_code: i32) -> ! { + println!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(); + panic!("Unreachable in sys_exit!"); + } + +那么 ``suspend_current_and_run_next`` 和 ``exit_current_and_run_next`` 各是如何实现的呢？ + +.. code-block:: rust + + // os/src/task/mod.rs + + pub fn suspend_current_and_run_next() { + TASK_MANAGER.mark_current_suspended(); + TASK_MANAGER.run_next_task(); + } + + pub fn exit_current_and_run_next() { + TASK_MANAGER.mark_current_exited(); + TASK_MANAGER.run_next_task(); + } + + +它们都是先修改当前应用的运行状态，然后尝试切换到下一个应用。修改运行状态比较简单，实现如下： + +.. code-block:: rust + :linenos: + + // os/src/task/mod.rs + + impl TaskManager { + fn mark_current_suspended(&self) { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[current].task_status = TaskStatus::Ready; + } + } + +以 ``mark_current_suspended`` 为例。首先获得里层 ``TaskManagerInner`` 的可变引用，然后修改任务控制块数组 ``tasks`` 中当前任务的状态。 + +再看 ``run_next_task`` 的实现： + +.. code-block:: rust + :linenos: + + // os/src/task/mod.rs + + impl TaskManager { + fn run_next_task(&self) { + if let Some(next) = self.find_next_task() { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[next].task_status = TaskStatus::Running; + inner.current_task = next; + let current_task_cx_ptr = &mut inner.tasks[current].task_cx as *mut TaskContext; + let next_task_cx_ptr = &inner.tasks[next].task_cx as *const TaskContext; + drop(inner); + // before this, we should drop local variables that must be dropped manually + unsafe { + __switch(current_task_cx_ptr, next_task_cx_ptr); + } + // go back to user mode + } else { + panic!("All applications completed!"); + } + } + + fn find_next_task(&self) -> Option { + let inner = self.inner.exclusive_access(); + let current = inner.current_task; + (current + 1..current + self.num_app + 1) + .map(|id| id % self.num_app) + .find(|id| inner.tasks[*id].task_status == TaskStatus::Ready) + } + } + +``run_next_task`` 会调用 ``find_next_task`` 方法尝试寻找一个运行状态为 ``Ready`` 的应用并获得其 ID 。 +如果找不到， 说明所有应用都执行完了， ``find_next_task`` 将返回 ``None`` ，内核 panic 退出。 +如果能够找到下一个可运行应用，我们就调用 ``__switch`` 切换任务。 + +切换任务之前，我们要手动 drop 掉我们获取到的 ``TaskManagerInner`` 可变引用。 +因为函数还没有返回， ``inner`` 不会自动销毁。我们只有令 ``TASK_MANAGER`` 的 ``inner`` 字段回到未被借用的状态，下次任务切换时才能再借用。 + +我们可以总结一下应用的运行状态变化图： + +.. image:: fsm-coop.png + +第一次进入用户态 +------------------------------------------ + +我们在第二章中介绍过 CPU 第一次从内核态进入用户态的方法，只需在内核栈上压入构造好的 Trap 上下文， +然后 ``__restore`` 即可。本章要在此基础上做一些扩展。 + +在初始化任务控制块时，我们是这样做的： + +.. code-block:: rust + + // os/src/task/mod.rs + + for (i, t) in tasks.iter_mut().enumerate().take(num_app) { + t.task_cx = TaskContext::goto_restore(init_app_cx(i)); + t.task_status = TaskStatus::Ready; + } + +``init_app_cx`` 在 ``loader`` 子模块中定义，它向内核栈压入了一个 Trap 上下文，并返回压入 Trap 上下文后 ``sp`` 的值。 +这个 Trap 上下文的构造方式与第二章相同。 + +``goto_restore`` 保存传入的 ``sp``，并将 ``ra`` 设置为 ``__restore`` 的入口地址，构造任务上下文后返回。这样，任务管理器中各个应用的任务上下文就得到了初始化。 + +.. code-block:: rust + + // os/src/task/context.rs + + impl TaskContext { + pub fn goto_restore(kstack_ptr: usize) -> Self { + extern "C" { fn __restore(); } + Self { + ra: __restore as usize, + sp: kstack_ptr, + s: [0; 12], + } + } + } + +在 ``rust_main`` 中我们调用 ``task::run_first_task`` 来执行第一个应用： + +.. code-block:: rust + :linenos: + + // os/src/task/mod.rs + + fn run_first_task(&self) -> ! { + let mut inner = self.inner.exclusive_access(); + let task0 = &mut inner.tasks[0]; + task0.task_status = TaskStatus::Running; + let next_task_cx_ptr = &task0.task_cx as *const TaskContext; + drop(inner); + let mut _unused = TaskContext::zero_init(); + // before this, we should drop local variables that must be dropped manually + unsafe { + __switch(&mut _unused as *mut TaskContext, next_task_cx_ptr); + } + panic!("unreachable in run_first_task!"); + } + +我们显式声明了一个 ``_unused`` 变量，并将它的地址作为第一个参数传给 ``__switch`` ， +声明此变量的意义仅仅是为了避免其他数据被覆盖。 + +在 ``__switch`` 中恢复 ``sp`` 后， ``sp`` 将指向 ``init_app_cx`` 构造的 Trap 上下文，后面就回到第二章的情况了。 +此外， ``__restore`` 的实现需要做出变化：它 **不再需要** 在开头 ``mv sp, a0`` 了。因为在 ``__switch`` 之后，``sp`` 就已经正确指向了我们需要的 Trap 上下文地址。 \ No newline at end of file diff --git a/guide/source/chapter3/4time-sharing-system.rst b/guide/source/chapter3/4time-sharing-system.rst new file mode 100644 index 0000000..9038da2 --- /dev/null +++ b/guide/source/chapter3/4time-sharing-system.rst @@ -0,0 +1,161 @@ +分时多任务系统 +=========================================================== + + +现代的任务调度算法基本都是抢占式的，它要求每个应用只能连续执行一段时间，然后内核就会将它强制性切换出去。 +一般将 **时间片** (Time Slice) 作为应用连续执行时长的度量单位，每个时间片可能在毫秒量级。 +简单起见，我们使用 **时间片轮转算法** (RR, Round-Robin) 来对应用进行调度。 + + +时钟中断与计时器 +------------------------------------------------------------------ + +实现调度算法需要计时。RISC-V 要求处理器维护时钟计数器 ``mtime``，还有另外一个 CSR ``mtimecmp`` 。 +一旦计数器 ``mtime`` 的值超过了 ``mtimecmp``，就会触发一次时钟中断。 + +运行在 M 特权级的 SEE 已经预留了相应的接口，基于此编写的 ``get_time`` 函数可以取得当前 ``mtime`` 计数器的值； + +.. code-block:: rust + + // os/src/timer.rs + + use riscv::register::time; + + pub fn get_time() -> usize { + time::read() + } + +在 10 ms 后设置时钟中断的代码如下： + +.. code-block:: rust + :linenos: + + // os/src/sbi.rs + + const SBI_SET_TIMER: usize = 0; + + pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); + } + + // os/src/timer.rs + + use crate::config::CLOCK_FREQ; + const TICKS_PER_SEC: usize = 100; + + pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); + } + +- 第 5 行， ``sbi`` 子模块有一个 ``set_timer`` 调用，用来设置 ``mtimecmp`` 的值。 +- 第 14 行， ``timer`` 子模块的 ``set_next_trigger`` 函数对 ``set_timer`` 进行了封装， + 它首先读取当前 ``mtime`` 的值，然后计算出 10ms 之内计数器的增量，再将 ``mtimecmp`` 设置为二者的和。 + 这样，10ms 之后一个 S 特权级时钟中断就会被触发。 + + 至于增量的计算方式， ``CLOCK_FREQ`` 是一个预先获取到的各平台不同的时钟频率，单位为赫兹，也就是一秒钟之内计数器的增量。 + 它可以在 ``config`` 子模块中找到。10ms 的话只需除以常数 ``TICKS_PER_SEC`` 也就是 100 即可。 + +后面可能还有一些计时的需求，我们再设计一个函数： + +.. code-block:: rust + + // os/src/timer.rs + + const MICRO_PER_SEC: usize = 1_000_000; + + pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) + } + + +``timer`` 子模块的 ``get_time_us`` 可以以微秒为单位返回当前计数器的值。 + +新增一个系统调用，使应用能获取当前的时间： + +.. code-block:: rust + :caption: 第三章新增系统调用（二） + + /// 功能：获取当前的时间，保存在 TimeVal 结构体 ts 中，_tz 在我们的实现中忽略 + /// 返回值：返回是否执行成功，成功则返回 0 + /// syscall ID：169 + fn sys_get_time(ts: *mut TimeVal, _tz: usize) -> isize; + +结构体 ``TimeVal`` 的定义如下，内核只需调用 ``get_time_us`` 即可实现该系统调用。 + +.. code-block:: rust + + // os/src/syscall/process.rs + + #[repr(C)] + pub struct TimeVal { + pub sec: usize, + pub usec: usize, + } + +RISC-V 架构中的嵌套中断问题 +----------------------------------- + +默认情况下，当 Trap 进入某个特权级之后，在 Trap 处理的过程中同特权级的中断都会被屏蔽。 + +- 当 Trap 发生时，``sstatus.sie`` 会被保存在 ``sstatus.spie`` 字段中，同时 ``sstatus.sie`` 置零， + 这也就在 Trap 处理的过程中屏蔽了所有 S 特权级的中断； +- 当 Trap 处理完毕 ``sret`` 的时候， ``sstatus.sie`` 会恢复到 ``sstatus.spie`` 内的值。 + +也就是说，如果不去手动设置 ``sstatus`` CSR ，在只考虑 S 特权级中断的情况下，是不会出现 **嵌套中断** (Nested Interrupt) 的。 + +.. note:: + + **嵌套中断与嵌套 Trap** + + 嵌套中断可以分为两部分：在处理一个中断的过程中又被同特权级/高特权级中断所打断。默认情况下硬件会避免前一部分， + 也可以通过手动设置来允许前一部分的存在；而从上面介绍的规则可以知道，后一部分则是无论如何设置都不可避免的。 + + 嵌套 Trap 则是指处理一个 Trap 过程中又再次发生 Trap ，嵌套中断算是嵌套 Trap 的一种。 + + +抢占式调度 +----------------------------------- + +有了时钟中断和计时器，抢占式调度就很容易实现了： + +.. code-block:: rust + + // os/src/trap/mod.rs + + match scause.cause() { + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + } + +我们只需在 ``trap_handler`` 函数下新增一个分支，触发了 S 特权级时钟中断时，重新设置计时器， +调用 ``suspend_current_and_run_next`` 函数暂停当前应用并切换到下一个。 + +为了避免 S 特权级时钟中断被屏蔽，我们需要在执行第一个应用前调用 ``enable_timer_interrupt()`` 设置 ``sie.stie``， +使得 S 特权级时钟中断不会被屏蔽；再设置第一个 10ms 的计时器。 + +.. code-block:: rust + :linenos: + + // os/src/main.rs + + #[no_mangle] + pub fn rust_main() -> ! { + // ... + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + // ... + } + + // os/src/trap/mod.rs + + use riscv::register::sie; + + pub fn enable_timer_interrupt() { + unsafe { sie::set_stimer(); } + } + +就这样，我们实现了时间片轮转任务调度算法。 ``power`` 系列用户程序可以验证我们取得的成果：这些应用并没有主动 yield， +内核仍能公平地把时间片分配给它们。 + diff --git a/guide/source/chapter3/5exercise.rst b/guide/source/chapter3/5exercise.rst new file mode 100644 index 0000000..422fbbd --- /dev/null +++ b/guide/source/chapter3/5exercise.rst @@ -0,0 +1,133 @@ +chapter3练习 +======================================= + +编程作业 +-------------------------------------- + +获取任务信息 +++++++++++++++++++++++++++ + +ch3 中，我们的系统已经能够支持多个任务分时轮流运行，我们希望引入一个新的系统调用 ``sys_task_info`` 以获取当前任务的信息，定义如下： + +.. code-block:: rust + + fn sys_task_info(ti: *mut TaskInfo) -> isize + +- syscall ID: 410 +- 查询当前正在执行的任务信息，任务信息包括任务控制块相关信息（任务状态）、任务使用的系统调用及调用次数、任务总运行时长（单位ms）。 + +.. code-block:: rust + + struct TaskInfo { + status: TaskStatus, + syscall_times: [u32; MAX_SYSCALL_NUM], + time: usize + } + +- 参数： + - ti: 待查询任务信息 +- 返回值：执行成功返回0，错误返回-1 +- 说明： + - 相关结构已在框架中给出，只需添加逻辑实现功能需求即可。 + - 在我们的实验中，系统调用号一定小于 500，所以直接使用一个长为 ``MAX_SYSCALL_NUM=500`` 的数组做桶计数。 + - 运行时间 time 返回系统调用时刻距离任务第一次被调度时刻的时长，也就是说这个时长可能包含该任务被其他任务抢占后的等待重新调度的时间。 + - 由于查询的是当前任务的状态，因此 TaskStatus 一定是 Running。（助教起初想设计根据任务 id 查询，但是既不好定义任务 id 也不好写测例，遂放弃 QAQ） + - 调用 ``sys_task_info`` 也会对本次调用计数。 +- 提示： + - 大胆修改已有框架！除了配置文件，你几乎可以随意修改已有框架的内容。 + - 程序运行时间可以通过调用 ``get_time()`` 获取，注意任务运行总时长的单位是 ms。 + - 系统调用次数可以考虑在进入内核态系统调用异常处理函数之后，进入具体系统调用函数之前维护。 + - 阅读 TaskManager 的实现，思考如何维护内核控制块信息（可以在控制块可变部分加入需要的信息）。 + + +实验要求 ++++++++++++++++++++++++++++++++++++++++++ + +- 完成分支: ch3。 + +- 实验目录要求 + +.. code-block:: + + ├── os(内核实现) + │   ├── Cargo.toml(配置文件) + │   └── src(所有内核的源代码放在 os/src 目录下) + │   ├── main.rs(内核主函数) + │   └── ... + ├── reports (不是 report) + │   ├── lab1.md/pdf + │   └── ... + ├── ... + + +- 通过所有测例： + + CI 使用的测例与本地相同，测试中，user 文件夹及其它与构建相关的文件将被替换，请不要试图依靠硬编码通过测试。 + + 默认情况下，makefile 仅编译基础测例 (``BASE=1``)，即无需修改框架即可正常运行的测例。 + 你需要在编译时指定 ``BASE=0`` 控制框架仅编译实验测例（在 os 目录执行 ``make run BASE=0``）， + 或指定 ``BASE=2`` 控制框架同时编译基础测例和实验测例。 + +.. note:: + + 你的实现只需且必须通过测例，建议读者感到困惑时先检查测例。 + + +简答作业 +-------------------------------------------- + +1. 正确进入 U 态后，程序的特征还应有：使用 S 态特权指令，访问 S 态寄存器后会报错。 + 请同学们可以自行测试这些内容 (运行 `Rust 三个 bad 测例 (ch2b_bad_*.rs) `_ ， + 注意在编译时至少需要指定 ``LOG=ERROR`` 才能观察到内核的报错信息) ， + 描述程序出错行为，同时注意注明你使用的 sbi 及其版本。 + +2. 深入理解 `trap.S `_ + 中两个函数 ``__alltraps`` 和 ``__restore`` 的作用，并回答如下问题: + + 1. L40：刚进入 ``__restore`` 时，``a0`` 代表了什么值。请指出 ``__restore`` 的两种使用情景。 + + 2. L46-L51：这几行汇编代码特殊处理了哪些寄存器？这些寄存器的的值对于进入用户态有何意义？请分别解释。 + + .. code-block:: riscv + + ld t0, 32*8(sp) + ld t1, 33*8(sp) + ld t2, 2*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + csrw sscratch, t2 + + 3. L53-L59：为何跳过了 ``x2`` 和 ``x4``？ + + .. code-block:: riscv + + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + + 4. L63：该指令之后，``sp`` 和 ``sscratch`` 中的值分别有什么意义？ + + .. code-block:: riscv + + csrrw sp, sscratch, sp + + 5. ``__restore``：中发生状态切换在哪一条指令？为何该指令执行之后会进入用户态？ + + 6. L13：该指令之后，``sp`` 和 ``sscratch`` 中的值分别有什么意义？ + + .. code-block:: riscv + + csrrw sp, sscratch, sp + + 7. 从 U 态进入 S 态是哪一条指令发生的？ + +报告要求 +------------------------------- + +- 简单总结你实现的功能（200字以内，不要贴代码）。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter3/fsm-coop.png b/guide/source/chapter3/fsm-coop.png new file mode 100644 index 0000000000000000000000000000000000000000..bc633bcd2b59f693f14c5a9ab9f90c62b0652f45 GIT binary patch literal 24175 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 literal 0 HcmV?d00001 diff --git a/guide/source/chapter3/index.rst b/guide/source/chapter3/index.rst new file mode 100644 index 0000000..d71d5a5 --- /dev/null +++ b/guide/source/chapter3/index.rst @@ -0,0 +1,14 @@ +.. _link-chapter3: + +第三章：多道程序与分时多任务 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 1multi-loader + 2task-switching + 3multiprogramming + 4time-sharing-system + 5exercise diff --git a/guide/source/chapter3/multiprogramming.png b/guide/source/chapter3/multiprogramming.png new file mode 100644 index 0000000000000000000000000000000000000000..7e4df49003f5a1bf229db490ffa6f1c42aa42085 GIT binary patch literal 20854 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 CrjdF8 literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/0intro.rst b/guide/source/chapter4/0intro.rst new file mode 100644 index 0000000..9334ff2 --- /dev/null +++ b/guide/source/chapter4/0intro.rst @@ -0,0 +1,143 @@ +引言 +============================== + +本章导读 +------------------------------- + +本章中内核将实现虚拟内存机制，这注定是一趟艰难的旅程。 + + +实践体验 +----------------------- + +本章应用运行起来效果与上一章基本一致。 + +获取本章代码： + +.. code-block:: console + + $ git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S.git + $ cd rCore-Tutorial-Code-2022S + $ git checkout ch4 + $ git clone https://github.com/LearningOS/rCore-Tutorial-Test-2022S.git user + +或许你之前已经克隆过了仓库，只希望从远程仓库更新，而非再克隆一次： + +.. code-block:: console + + $ cd rCore-Tutorial-Code-2022S + # 你可以将 upstream 改为你喜欢的名字 + $ git remote add upstream https://github.com/LearningOS/rCore-Tutorial-Code-2022S.git + # 更新仓库信息 + $ git fetch upstream + # 查看已添加的远程仓库；应该能看到已有一个 origin 和新添加的 upstream 仓库 + $ git remote -v + # 根据需求选择以下一种操作即可 + # 在本地新建一个与远程仓库对应的分支： + $ git checkout -b ch4 upstream/ch4 + # 本地已有分支，从远程仓库更新： + $ git checkout ch4 + $ git merge upstream/ch4 + # 将更新推送到自己的远程仓库 + $ git push origin ch4 + +在 qemu 模拟器上运行本章代码： + +.. code-block:: console + + $ cd os + $ make run + + +本章代码树 +----------------------------------------------------- + +.. code-block:: + :linenos: + + ├── os + │   ├── ... + │   └── src + │   ├── ... + │   ├── config.rs(修改：新增一些内存管理的相关配置) + │   ├── linker.ld(修改：将跳板页引入内存布局) + │   ├── loader.rs(修改：仅保留获取应用数量和数据的功能) + │   ├── main.rs(修改) + │   ├── mm(新增：内存管理的 mm 子模块) + │   │   ├── address.rs(物理/虚拟 地址/页号的 Rust 抽象) + │   │   ├── frame_allocator.rs(物理页帧分配器) + │   │   ├── heap_allocator.rs(内核动态内存分配器) + │   │   ├── memory_set.rs(引入地址空间 MemorySet 及逻辑段 MemoryArea 等) + │   │   ├── mod.rs(定义了 mm 模块初始化方法 init) + │   │   └── page_table.rs(多级页表抽象 PageTable 以及其他内容) + │   ├── syscall + │   │   ├── fs.rs(修改：基于地址空间的 sys_write 实现) + │   │   ├── mod.rs + │   │   └── process.rs + │   ├── task + │   │   ├── context.rs(修改：构造一个跳转到不同位置的初始任务上下文) + │   │   ├── mod.rs(修改，详见文档) + │   │   ├── switch.rs + │   │   ├── switch.S + │   │   └── task.rs(修改，详见文档) + │   └── trap + │   ├── context.rs(修改：在 Trap 上下文中加入了更多内容) + │   ├── mod.rs(修改：基于地址空间修改了 Trap 机制，详见文档) + │   └── trap.S(修改：基于地址空间修改了 Trap 上下文保存与恢复汇编代码) + └── user + ├── build.py(编译时不再使用) + ├── ... + └── src + ├── linker.ld(修改：将所有应用放在各自地址空间中固定的位置) + └── ... + + cloc os + ------------------------------------------------------------------------------- + Language files blank comment code + ------------------------------------------------------------------------------- + Rust 26 138 56 1526 + Assembly 3 3 26 86 + make 1 11 4 36 + TOML 1 2 1 13 + ------------------------------------------------------------------------------- + SUM: 31 154 87 1661 + ------------------------------------------------------------------------------- + + +.. 本章代码导读 +.. ----------------------------------------------------- + +.. 本章涉及的代码量相对多了起来，也许同学们不知如何从哪里看起或从哪里开始尝试实验。这里简要介绍一下“头甲龙”操作系统的大致开发过程。 + +.. 我们先从简单的地方入手，那当然就是先改进应用程序了。具体而言，主要就是把 ``linker.ld`` 中应用程序的起始地址都改为 ``0x0`` ，这是假定我们操作系统能够通过分页机制把不同应用的相同虚地址映射到不同的物理地址中。这样我们写应用就不用考虑物理地址布局的问题，能够以一种更加统一的方式编写应用程序，可以忽略掉一些不必要的细节。 + +.. 为了能够在内核中动态分配内存，我们的第二步需要在内核增加连续内存分配的功能，具体实现主要集中在 ``os/src/mm/heap_allocator.rs`` 中。完成这一步后，我们就可以在内核中用到Rust的堆数据结构了，如 ``Vec`` 、 ``Box`` 等，这样内核编程就更加灵活了。 + +.. 操作系统如果要建立页表，首先要能管理整个系统的物理内存，这就需要知道物理内存哪些区域放置内核的代码、数据，哪些区域则是空闲的等信息。所以需要了解整个系统的物理内存空间的范围，并以物理页帧为单位分配和回收物理内存，具体实现主要集中在 ``os/src/mm/frame_allocator.rs`` 中。 + +.. 页表中的页表项的索引其实是虚拟地址中的虚拟页号，页表项的重要内容是物理地址的物理页帧号。为了能够灵活地在虚拟地址、物理地址、虚拟页号、物理页号之间进行各种转换，在 ``os/src/mm/address.rs`` 中实现了各种转换函数。 + +.. 完成上述工作后，基本上就做好了建立页表的前期准备。我们就可以开始建立页表，这主要涉及到页表项的数据结构表示，以及多级页表的起始物理页帧位置和整个所占用的物理页帧的记录。具体实现主要集中在 ``os/src/mm/page_table.rs`` 中。 + +.. 一旦使能分页机制，那么内核中也将基于虚地址进行虚存访问，所以在给应用添加虚拟地址空间前，内核自己也会建立一个页表，把整个物理地址空间通过简单的恒等映射对应到一个虚拟地址空间中。后续的应用在执行前，也需要建立一个虚拟地址空间，这意味着第三章的 ``task`` 将进化到第五章的拥有独立页表的进程 。虚拟地址空间需要有一个数据结构管理起来，这就是 ``MemorySet`` ，即地址空间这个抽象概念所对应的具象体现。在一个虚拟地址空间中，有代码段，数据段等不同属性且不一定连续的子空间，它们通过一个重要的数据结构 ``MapArea`` 来表示和管理。围绕 ``MemorySet`` 等一系列的数据结构和相关操作的实现，主要集中在 ``os/src/mm/memory_set.rs`` 中。比如内核的页表和虚拟空间的建立在如下代码中： + +.. .. code-block:: rust +.. :linenos: + +.. // os/src/mm/memory_set.rs + +.. lazy_static! { +.. pub static ref KERNEL_SPACE: Arc> = Arc::new(Mutex::new( +.. MemorySet::new_kernel() +.. )); +.. } + +.. 完成到这里，我们就可以使能分页机制了。且我们应该有更加方便的机制来给支持应用运行。在本章之前，都是把应用程序的所有元数据丢弃从而转换成二进制格式来执行，这其实把编译器生成的 ELF 执行文件中大量有用的信息给去掉了，比如代码段、数据段的各种属性，程序的入口地址等。既然有了给应用运行提供虚拟地址空间的能力，我们就可以利用 ELF 执行文件中的各种信息来灵活构建应用运行所需要的虚拟地址空间。在 ``os/src/loader.rs`` 中可以看到如何获取一个应用的 ELF 执行文件数据，而在 ``os/src/mm/memory_set`` 中的 ``MemorySet::from_elf`` 可以看到如何通过解析 ELF 来创建一个应用地址空间。 + +.. 对于有了虚拟地址空间的 *任务* ，我们可以把它叫做 *进程* 了。操作系统为此需要扩展任务控制块 ``TaskControlBlock`` 的管理范围，使得操作系统能管理拥有独立页表和虚拟地址空间的应用程序的运行。相关主要的改动集中在 ``os/src/task/task.rs`` 中。 + +.. 由于代表应用程序运行的进程和管理应用的操作系统各自有独立的页表和虚拟地址空间，所以这就出现了两个比较挑战的事情。一个是由于系统调用、中断或异常导致的应用程序和操作系统之间的 Trap 上下文切换不像以前那么简单了，因为需要切换页表，这需要看看 ``os/src/trap/trap.S`` ；还有就是需要对来自用户态和内核态的 Trap 分别进行处理，这需要看看 ``os/src/trap/mod.rs`` 和 :ref:`跳板的实现 ` 中的讲解。 + +.. 另外一个挑战是，在内核地址空间中执行的内核代码常常需要读写应用地址空间的数据，这无法简单的通过一次访存交给 MMU 来解决，而是需要手动查应用地址空间的页表。在访问应用地址空间中的一块跨多个页数据的时候还需要注意处理边界条件。可以参考 ``os/src/syscall/fs.rs``、 ``os/src/mm/page_table.rs`` 中的 ``translated_byte_buffer`` 函数的实现。 + +.. 实现到这，应该就可以给应用程序运行提供一个方便且安全的虚拟地址空间了。 \ No newline at end of file diff --git a/guide/source/chapter4/3sv39-implementation-1.rst b/guide/source/chapter4/3sv39-implementation-1.rst new file mode 100644 index 0000000..79f6965 --- /dev/null +++ b/guide/source/chapter4/3sv39-implementation-1.rst @@ -0,0 +1,216 @@ +实现 SV39 多级页表机制（上） +======================================================== + +.. note:: + + 背景知识： `地址空间 `_ + + 背景知识： `SV39 多级页表原理 `_ + + +我们将在内核实现 RV64 架构 SV39 分页机制。由于内容过多，分成两个小节。 + +虚拟地址和物理地址 +------------------------------------------------------ + +内存控制相关的CSR寄存器 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +默认情况下 MMU 未被使能，此时无论 CPU 处于哪个特权级，访存的地址都将直接被视作物理地址。 +可以通过修改 S 特权级的 ``satp`` CSR 来启用分页模式，此后 S 和 U 特权级的访存地址会被视为虚拟地址，经过 MMU 的地址转换获得对应物理地址，再通过它来访问物理内存。 + +.. image:: satp.png + :name: satp-layout + +上图是 RV64 架构下 ``satp`` 的字段分布。当 ``MODE`` 设置为 0 的时候，所有访存都被视为物理地址；而设置为 8 +时，SV39 分页机制被启用，所有 S/U 特权级的访存被视为一个 39 位的虚拟地址，MMU 会将其转换成 56 位的物理地址；如果转换失败，则会触发异常。 + + +地址格式与组成 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. image:: sv39-va-pa.png + +我们采用分页管理，单个页面的大小设置为 :math:`4\text{KiB}` ，每个虚拟页面和物理页帧都按 4 KB 对齐。 +:math:`4\text{KiB}` 需要用 12 位字节地址来表示，因此虚拟地址和物理地址都被分成两部分： +它们的低 12 位被称为 **页内偏移** (Page Offset) 。虚拟地址的高 27 位，即 :math:`[38:12]` 为它的虚拟页号 VPN； +物理地址的高 44 位，即 :math:`[55:12]` 为它的物理页号 PPN。页号可以用来定位一个虚拟/物理地址属于哪一个虚拟页面/物理页帧。 + +地址转换是以页为单位进行的，转换前后地址页内偏移部分不变。MMU 只是从虚拟地址中取出 27 位虚拟页号， +在页表中查到其对应的物理页号，如果找到，就将得到的 44 位的物理页号与 12 位页内偏移拼接到一起，形成 56 位物理地址。 + +.. note:: + + **RV64 架构中虚拟地址为何只有 39 位？** + + 虚拟地址长度确实应该和位宽一致为 64 位，但是在启用 SV39 分页模式下，只有低 39 位是真正有意义的。 + SV39 分页模式规定 64 位虚拟地址的 :math:`[63:39]` 这 25 位必须和第 38 位相同，否则 MMU 会直接认定它是一个 + 不合法的虚拟地址。。 + + 也就是说，所有 :math:`2^{64}` 个虚拟地址中，只有最低的 :math:`256\text{GiB}` （当第 38 位为 0 时） + 以及最高的 :math:`256\text{GiB}` （当第 38 位为 1 时）是可能通过 MMU 检查的。 + +地址相关的数据结构抽象与类型定义 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +实现页表之前，先将地址和页号的概念抽象为 Rust 中的类型。 + +首先是这些类型的定义： + +.. code-block:: rust + + // os/src/mm/address.rs + + #[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] + pub struct PhysAddr(pub usize); + + #[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] + pub struct VirtAddr(pub usize); + + #[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] + pub struct PhysPageNum(pub usize); + + #[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] + pub struct VirtPageNum(pub usize); + +.. _term-type-convertion: + +上面分别给出了物理地址、虚拟地址、物理页号、虚拟页号的 Rust 类型声明，它们都是 usize 的一种简单包装。 +将它们各自抽象出来而不是直接使用 usize，是为了在 Rust 编译器的帮助下进行多种方便且安全的 **类型转换** (Type Convertion) 。 + +这些类型本身可以和 usize 之间互相转换，地址和页号之间也可以相互转换。以物理地址和物理页号之间的转换为例： + +.. code-block:: rust + :linenos: + + // os/src/mm/address.rs + + impl PhysAddr { + pub fn page_offset(&self) -> usize { self.0 & (PAGE_SIZE - 1) } + } + + impl From for PhysPageNum { + fn from(v: PhysAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } + } + + impl From for PhysAddr { + fn from(v: PhysPageNum) -> Self { Self(v.0 << PAGE_SIZE_BITS) } + } + +其中 ``PAGE_SIZE`` 为 :math:`4096` ， ``PAGE_SIZE_BITS`` 为 :math:`12` ，它们均定义在 ``config`` 子模块 +中，分别表示每个页面的大小和页内偏移的位宽。从物理页号到物理地址的转换只需左移 :math:`12` 位即可，但是物理地址需要 +保证它与页面大小对齐才能通过右移转换为物理页号。 + +对于不对齐的情况，物理地址不能通过 ``From/Into`` 转换为物理页号，而是需要通过它自己的 ``floor`` 或 ``ceil`` 方法来 +进行下取整或上取整的转换。 + +.. code-block:: rust + + // os/src/mm/address.rs + + impl PhysAddr { + pub fn floor(&self) -> PhysPageNum { PhysPageNum(self.0 / PAGE_SIZE) } + pub fn ceil(&self) -> PhysPageNum { PhysPageNum((self.0 + PAGE_SIZE - 1) / PAGE_SIZE) } + } + +页表项的数据结构抽象与类型定义 +----------------------------------------- + +.. image:: sv39-pte.png + +上图为 SV39 分页模式下的页表项，其中 :math:`[53:10]` 这 :math:`44` 位是物理页号，最低的 :math:`8` 位 +:math:`[7:0]` 则是标志位，它们的含义如下： + +- 仅当 V(Valid) 位为 1 时，页表项才是合法的； +- R/W/X 分别控制索引到这个页表项的对应虚拟页面是否允许读/写/取指； +- U 控制索引到这个页表项的对应虚拟页面是否在 CPU 处于 U 特权级的情况下是否被允许访问； +- G 我们不理会； +- A(Accessed) 记录自从页表项上的这一位被清零之后，页表项的对应虚拟页面是否被访问过； +- D(Dirty) 则记录自从页表项上的这一位被清零之后，页表项的对应虚拟页表是否被修改过。 + +先来实现页表项中的标志位 ``PTEFlags`` ： + +.. code-block:: rust + + // os/src/main.rs + + #[macro_use] + extern crate bitflags; + + // os/src/mm/page_table.rs + + use bitflags::*; + + bitflags! { + pub struct PTEFlags: u8 { + const V = 1 << 0; + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + const G = 1 << 5; + const A = 1 << 6; + const D = 1 << 7; + } + } + +`bitflags `_ 是一个 Rust 中常用来比特标志位的 crate 。它提供了 +一个 ``bitflags!`` 宏，如上面的代码段所展示的那样，可以将一个 ``u8`` 封装成一个标志位的集合类型，支持一些常见的集合 +运算。 + +接下来我们实现页表项 ``PageTableEntry`` ： + +.. code-block:: rust + :linenos: + + // os/src/mm/page_table.rs + + #[derive(Copy, Clone)] + #[repr(C)] + pub struct PageTableEntry { + pub bits: usize, + } + + impl PageTableEntry { + pub fn new(ppn: PhysPageNum, flags: PTEFlags) -> Self { + PageTableEntry { + bits: ppn.0 << 10 | flags.bits as usize, + } + } + pub fn empty() -> Self { + PageTableEntry { + bits: 0, + } + } + pub fn ppn(&self) -> PhysPageNum { + (self.bits >> 10 & ((1usize << 44) - 1)).into() + } + pub fn flags(&self) -> PTEFlags { + PTEFlags::from_bits(self.bits as u8).unwrap() + } + } + +- 第 3 行我们让编译器自动为 ``PageTableEntry`` 实现 ``Copy/Clone`` Trait，来让这个类型以值语义赋值/传参的时候 + 不会发生所有权转移，而是拷贝一份新的副本。 +- 第 10 行使得我们可以从一个物理页号 ``PhysPageNum`` 和一个页表项标志位 ``PTEFlags`` 生成一个页表项 + ``PageTableEntry`` 实例；而第 20 行和第 23 行则分别可以从一个页表项将它们两个取出。 +- 第 15 行中，我们也可以通过 ``empty`` 方法生成一个全零的页表项，注意这隐含着该页表项的 V 标志位为 0 ， + 因此它是不合法的。 + +后面我们还为 ``PageTableEntry`` 实现了一些辅助函数(Helper Function)，可以快速判断一个页表项的 V/R/W/X 标志位是否为 1，以 V +标志位的判断为例： + +.. code-block:: rust + + // os/src/mm/page_table.rs + + impl PageTableEntry { + pub fn is_valid(&self) -> bool { + (self.flags() & PTEFlags::V) != PTEFlags::empty() + } + } + +这里相当于判断两个集合的交集是否为空。 diff --git a/guide/source/chapter4/4sv39-implementation-2.rst b/guide/source/chapter4/4sv39-implementation-2.rst new file mode 100644 index 0000000..ce6df02 --- /dev/null +++ b/guide/source/chapter4/4sv39-implementation-2.rst @@ -0,0 +1,447 @@ +实现 SV39 多级页表机制（下） +======================================================== + +物理页帧管理 +----------------------------------- + +可用物理页的分配与回收 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +首先，我们需要知道物理内存的哪一部分是可用的。在 ``os/src/linker.ld`` 中，我们用符号 ``ekernel`` 指明了 +内核数据的终止物理地址，在它之后的物理内存都是可用的。而在 ``config`` 子模块中： + +.. code-block:: rust + + // os/src/config.rs + + pub const MEMORY_END: usize = 0x80800000; + +我们硬编码整块物理内存的终止物理地址为 ``0x80800000`` 。 而物理内存的起始物理地址为 ``0x80000000`` ， +意味着我们将可用内存大小设置为 :math:`8\text{MiB}` ，当然也可以设置的更大一点。 + +用一个左闭右开的物理页号区间来表示可用的物理内存，则： + +- 区间的左端点应该是 ``ekernel`` 的物理地址以上取整方式转化成的物理页号； +- 区间的右端点应该是 ``MEMORY_END`` 以下取整方式转化成的物理页号。 + +这个区间将被传给我们后面实现的物理页帧管理器用于初始化。 + +我们声明一个 ``FrameAllocator`` Trait 来描述一个物理页帧管理器需要提供哪些功能： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + trait FrameAllocator { + fn new() -> Self; + fn alloc(&mut self) -> Option; + fn dealloc(&mut self, ppn: PhysPageNum); + } + +我们实现一种最简单的栈式物理页帧管理策略 ``StackFrameAllocator`` ： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + pub struct StackFrameAllocator { + current: usize, + end: usize, + recycled: Vec, + } + +其中各字段的含义是：物理页号区间 :math:`[\text{current},\text{end})` 此前均 *从未* 被分配出去过，而向量 +``recycled`` 以后入先出的方式保存了被回收的物理页号（我们已经实现了堆分配器，参见第三章实验）。 + +初始化非常简单。在通过 ``FrameAllocator`` 的 ``new`` 方法创建实例的时候，只需将区间两端均设为 :math:`0` ， +然后创建一个新的向量；而在它真正被使用起来之前，需要调用 ``init`` 方法将自身的 :math:`[\text{current},\text{end})` +初始化为可用物理页号区间： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + impl FrameAllocator for StackFrameAllocator { + fn new() -> Self { + Self { + current: 0, + end: 0, + recycled: Vec::new(), + } + } + } + + impl StackFrameAllocator { + pub fn init(&mut self, l: PhysPageNum, r: PhysPageNum) { + self.current = l.0; + self.end = r.0; + } + } + +接下来我们来看核心的物理页帧分配和回收如何实现： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + impl FrameAllocator for StackFrameAllocator { + fn alloc(&mut self) -> Option { + if let Some(ppn) = self.recycled.pop() { + Some(ppn.into()) + } else { + if self.current == self.end { + None + } else { + self.current += 1; + Some((self.current - 1).into()) + } + } + } + fn dealloc(&mut self, ppn: PhysPageNum) { + let ppn = ppn.0; + // validity check + if ppn >= self.current || self.recycled + .iter() + .find(|&v| {*v == ppn}) + .is_some() { + panic!("Frame ppn={:#x} has not been allocated!", ppn); + } + // recycle + self.recycled.push(ppn); + } + } + +- 在分配 ``alloc`` 的时候，首先会检查栈 ``recycled`` 内有没有之前回收的物理页号，如果有的话直接弹出栈顶并返回； + 否则的话我们只能从之前从未分配过的物理页号区间 :math:`[\text{current},\text{end})` 上进行分配，我们分配它的 + 左端点 ``current`` ，同时将管理器内部维护的 ``current`` 加一代表 ``current`` 此前已经被分配过了。在即将返回 + 的时候，我们使用 ``into`` 方法将 usize 转换成了物理页号 ``PhysPageNum`` 。 + + 注意极端情况下可能出现内存耗尽分配失败的情况：即 ``recycled`` 为空且 :math:`\text{current}==\text{end}` 。 + 为了涵盖这种情况， ``alloc`` 的返回值被 ``Option`` 包裹，我们返回 ``None`` 即可。 +- 在回收 ``dealloc`` 的时候，我们需要检查回收页面的合法性，然后将其压入 ``recycled`` 栈中。回收页面合法有两个 + 条件： + + - 该页面之前一定被分配出去过，因此它的物理页号一定 :math:`<\text{current}` ； + - 该页面没有正处在回收状态，即它的物理页号不能在栈 ``recycled`` 中找到。 + + 我们通过 ``recycled.iter()`` 获取栈上内容的迭代器，然后通过迭代器的 ``find`` 方法试图 + 寻找一个与输入物理页号相同的元素。其返回值是一个 ``Option`` ，如果找到了就会是一个 ``Option::Some`` ， + 这种情况说明我们内核其他部分实现有误，直接报错退出。 + +之后创建 ``StackFrameAllocator`` 的全局实例 ``FRAME_ALLOCATOR``，并在正式分配物理页帧之前将 ``FRAME_ALLOCATOR`` 初始化，见 ``os/src/mm/frame_allocator.rs``。 + +分配/回收物理页帧的接口 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +公开给其他子模块调用的分配/回收物理页帧的接口： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + pub fn frame_alloc() -> Option { + FRAME_ALLOCATOR + .exclusive_access() + .alloc() + .map(FrameTracker::new) + } + + fn frame_dealloc(ppn: PhysPageNum) { + FRAME_ALLOCATOR.exclusive_access().dealloc(ppn); + } + + +可以发现， ``frame_alloc`` 的返回值类型并不是 ``FrameAllocator`` 要求的物理页号 ``PhysPageNum`` ，而是将其 +进一步包装为一个 ``FrameTracker`` ，其定义如下。 ``FrameTracker`` 被创建时，需要从 ``FRAME_ALLOCATOR`` 中分配一个物理页帧： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + pub struct FrameTracker { + pub ppn: PhysPageNum, + } + + impl FrameTracker { + pub fn new(ppn: PhysPageNum) -> Self { + // page cleaning + let bytes_array = ppn.get_bytes_array(); + for i in bytes_array { + *i = 0; + } + Self { ppn } + } + } + +我们将分配来的物理页帧的物理页号作为参数传给 ``FrameTracker`` 的 ``new`` 方法来创建一个 ``FrameTracker`` +实例。由于这个物理页帧之前可能被分配过并用做其他用途，我们在这里直接将这个物理页帧上的所有字节清零。这一过程并不 +那么显然，我们后面再详细介绍。 + +当一个 ``FrameTracker`` 生命周期结束被编译器回收的时候，我们需要将它控制的物理页帧回收掉 ``FRAME_ALLOCATOR`` 中： + +.. code-block:: rust + + // os/src/mm/frame_allocator.rs + + impl Drop for FrameTracker { + fn drop(&mut self) { + frame_dealloc(self.ppn); + } + } + +这里我们只需为 ``FrameTracker`` 实现 ``Drop`` Trait 即可。当一个 ``FrameTracker`` 实例被回收的时候，它的 +``drop`` 方法会自动被编译器调用，通过之前实现的 ``frame_dealloc`` 我们就将它控制的物理页帧回收以供后续使用了。 + +最后做一个小结：从其他模块的视角看来，物理页帧分配的接口是调用 ``frame_alloc`` 函数得到一个 ``FrameTracker`` +（如果物理内存还有剩余），它就代表了一个物理页帧，当它的生命周期结束之后它所控制的物理页帧将被自动回收。 + +多级页表实现 +----------------------------------- + + +页表基本数据结构与访问接口 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +我们知道，SV39 多级页表是以节点为单位进行管理的。每个节点恰好存储在一个物理页帧中，它的位置可以用一个物理页号来表示。 + +.. code-block:: rust + :linenos: + + // os/src/mm/page_table.rs + + pub struct PageTable { + root_ppn: PhysPageNum, + frames: Vec, + } + + impl PageTable { + pub fn new() -> Self { + let frame = frame_alloc().unwrap(); + PageTable { + root_ppn: frame.ppn, + frames: vec![frame], + } + } + } + +每个应用的地址空间都对应一个不同的多级页表，这也就意味这不同页表的起始地址（即页表根节点的地址）是不一样的。 +因此 ``PageTable`` 要保存它根节点的物理页号 ``root_ppn`` 作为页表唯一的区分标志。此外， +向量 ``frames`` 以 ``FrameTracker`` 的形式保存了页表所有的节点（包括根节点）所在的物理页帧。这与物理页帧管理模块 +的测试程序是一个思路，即将这些 ``FrameTracker`` 的生命周期进一步绑定到 ``PageTable`` 下面。当 ``PageTable`` +生命周期结束后，向量 ``frames`` 里面的那些 ``FrameTracker`` 也会被回收，也就意味着存放多级页表节点的那些物理页帧 +被回收了。 + +当我们通过 ``new`` 方法新建一个 ``PageTable`` 的时候，它只需有一个根节点。为此我们需要分配一个物理页帧 +``FrameTracker`` 并挂在向量 ``frames`` 下，然后更新根节点的物理页号 ``root_ppn`` 。 + +多级页表并不是被创建出来之后就不再变化的，为了 MMU 能够通过地址转换正确找到应用地址空间中的数据实际被内核放在内存中 +位置，操作系统需要动态维护一个虚拟页号到页表项的映射，支持插入/删除键值对，其方法签名如下： + +.. code-block:: rust + + // os/src/mm/page_table.rs + + impl PageTable { + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags); + pub fn unmap(&mut self, vpn: VirtPageNum); + } + +- 我们通过 ``map`` 方法来在多级页表中插入一个键值对，注意这里我们将物理页号 ``ppn`` 和页表项标志位 ``flags`` 作为 + 不同的参数传入而不是整合为一个页表项； +- 相对的，我们通过 ``unmap`` 方法来删除一个键值对，在调用时仅需给出作为索引的虚拟页号即可。 + +.. _modify-page-table: + +在这些操作的过程中，我们自然需要访问或修改多级页表节点的内容。每个节点都被保存在一个物理页帧中，在多级页表的架构中，我们以 +一个节点被存放在的物理页帧的物理页号作为指针指向该节点，这意味着，对于每个节点来说，一旦我们知道了指向它的物理页号，我们 +就能够修改这个节点的内容。 + +.. _term-identical-mapping: + +这就需要我们提前扩充多级页表维护的映射，使得对于每一个对应于某一特定物理页帧的物理页号 ``ppn`` ，均存在一个虚拟页号 +``vpn`` 能够映射到它，而且要能够较为简单的针对一个 ``ppn`` 找到某一个能映射到它的 ``vpn`` 。这里我们采用一种最 +简单的 **恒等映射** (Identical Mapping) ，也就是说对于物理内存上的每个物理页帧，我们都在多级页表中用一个与其 +物理页号相等的虚拟页号映射到它。当我们想针对物理页号构造一个能映射到它的虚拟页号的时候，也只需使用一个和该物理页号 +相等的虚拟页号即可。 + + +内核中访问物理页帧的方法 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _access-frame-in-kernel-as: + + +于是，我们来看看在内核中应如何访问一个特定的物理页帧： + +.. code-block:: rust + + // os/src/mm/address.rs + + impl PhysPageNum { + pub fn get_pte_array(&self) -> &'static mut [PageTableEntry] { + let pa: PhysAddr = self.clone().into(); + unsafe { + core::slice::from_raw_parts_mut(pa.0 as *mut PageTableEntry, 512) + } + } + pub fn get_bytes_array(&self) -> &'static mut [u8] { + let pa: PhysAddr = self.clone().into(); + unsafe { + core::slice::from_raw_parts_mut(pa.0 as *mut u8, 4096) + } + } + pub fn get_mut(&self) -> &'static mut T { + let pa: PhysAddr = self.clone().into(); + unsafe { + (pa.0 as *mut T).as_mut().unwrap() + } + } + } + +我们构造可变引用来直接访问一个物理页号 ``PhysPageNum`` 对应的物理页帧，不同的引用类型对应于物理页帧上的一种不同的 +内存布局，如 ``get_pte_array`` 返回的是一个页表项定长数组的可变引用，可以用来修改多级页表中的一个节点；而 +``get_bytes_array`` 返回的是一个字节数组的可变引用，可以以字节为粒度对物理页帧上的数据进行访问，前面进行数据清零 +就用到了这个方法； ``get_mut`` 是个泛型函数，可以获取一个恰好放在一个物理页帧开头的类型为 ``T`` 的数据的可变引用。 + +在实现方面，都是先把物理页号转为物理地址 ``PhysAddr`` ，然后再转成 usize 形式的物理地址。接着，我们直接将它 +转为裸指针用来访问物理地址指向的物理内存。在分页机制开启前，这样做自然成立；而开启之后，虽然裸指针被视为一个虚拟地址， +但是上面已经提到这种情况下虚拟地址会映射到一个相同的物理地址，因此在这种情况下也成立。注意，我们在返回值类型上附加了 +静态生命周期泛型 ``'static`` ，这是为了绕过 Rust 编译器的借用检查，实质上可以将返回的类型也看成一个裸指针，因为 +它也只是标识数据存放的位置以及类型。但与裸指针不同的是，无需通过 ``unsafe`` 的解引用访问它指向的数据，而是可以像一个 +正常的可变引用一样直接访问。 + + +建立和拆除虚实地址映射关系 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +接下来介绍建立和拆除虚实地址映射关系的 ``map`` 和 ``unmap`` 方法是如何实现的。它们都依赖于一个很重要的过程， +也即在多级页表中找到一个虚拟地址对应的页表项。找到之后，只要修改页表项的内容即可完成键值对的插入和删除。 +在寻找页表项的时候，可能出现页表的中间级节点还未被创建的情况，这个时候我们需要手动分配一个物理页帧来存放这个节点， +并将这个节点接入到当前的多级页表的某级中。 + + +.. code-block:: rust + :linenos: + + // os/src/mm/address.rs + + impl VirtPageNum { + pub fn indexes(&self) -> [usize; 3] { + let mut vpn = self.0; + let mut idx = [0usize; 3]; + for i in (0..3).rev() { + idx[i] = vpn & 511; + vpn >>= 9; + } + idx + } + } + + // os/src/mm/page_table.rs + + impl PageTable { + fn find_pte_create(&mut self, vpn: VirtPageNum) -> Option<&mut PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&mut PageTableEntry> = None; + for i in 0..3 { + let pte = &mut ppn.get_pte_array()[idxs[i]]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + let frame = frame_alloc().unwrap(); + *pte = PageTableEntry::new(frame.ppn, PTEFlags::V); + self.frames.push(frame); + } + ppn = pte.ppn(); + } + result + } + } + +- ``VirtPageNum`` 的 ``indexes`` 可以取出虚拟页号的三级页索引，并按照从高到低的顺序返回。注意它里面包裹的 + usize 可能有 :math:`27` 位，也有可能有 :math:`64-12=52` 位，但这里我们是用来在多级页表上进行遍历，因此 + 只取出低 :math:`27` 位。 +- ``PageTable::find_pte_create`` 在多级页表找到一个虚拟页号对应的页表项的可变引用方便后续的读写。如果在 + 遍历的过程中发现有节点尚未创建则会新建一个节点。 + + 变量 ``ppn`` 表示当前节点的物理页号，最开始指向多级页表的根节点。随后每次循环通过 ``get_pte_array`` 将 + 取出当前节点的页表项数组，并根据当前级页索引找到对应的页表项。如果当前节点是一个叶节点，那么直接返回这个页表项 + 的可变引用；否则尝试向下走。走不下去的话就新建一个节点，更新作为下级节点指针的页表项，并将新分配的物理页帧移动到 + 向量 ``frames`` 中方便后续的自动回收。注意在更新页表项的时候，不仅要更新物理页号，还要将标志位 V 置 1， + 不然硬件在查多级页表的时候，会认为这个页表项不合法，从而触发 Page Fault 而不能向下走。 + +于是， ``map/unmap`` 就非常容易实现了： + +.. code-block:: rust + + // os/src/mm/page_table.rs + + impl PageTable { + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(!pte.is_valid(), "vpn {:?} is mapped before mapping", vpn); + *pte = PageTableEntry::new(ppn, flags | PTEFlags::V); + } + pub fn unmap(&mut self, vpn: VirtPageNum) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(pte.is_valid(), "vpn {:?} is invalid before unmapping", vpn); + *pte = PageTableEntry::empty(); + } + } + +只需根据虚拟页号找到页表项，然后修改或者直接清空其内容即可。 + +.. warning:: + + 目前的实现方式并不打算对物理页帧耗尽的情形做任何处理而是直接 ``panic`` 退出。因此在前面的代码中能够看到 + 很多 ``unwrap`` ，这种使用方式并不为 Rust 所推荐，只是由于简单起见暂且这样做。 + +为了方便后面的实现，我们还需要 ``PageTable`` 提供一种不经过 MMU 而是手动查页表的方法： + +.. code-block:: rust + :linenos: + + // os/src/mm/page_table.rs + + impl PageTable { + /// Temporarily used to get arguments from user space. + pub fn from_token(satp: usize) -> Self { + Self { + root_ppn: PhysPageNum::from(satp & ((1usize << 44) - 1)), + frames: Vec::new(), + } + } + fn find_pte(&self, vpn: VirtPageNum) -> Option<&PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&PageTableEntry> = None; + for i in 0..3 { + let pte = &ppn.get_pte_array()[idxs[i]]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + return None; + } + ppn = pte.ppn(); + } + result + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.find_pte(vpn) + .map(|pte| {pte.clone()}) + } + } + +- 第 5 行的 ``from_token`` 可以临时创建一个专用来手动查页表的 ``PageTable`` ，它仅有一个从传入的 ``satp`` token + 中得到的多级页表根节点的物理页号，它的 ``frames`` 字段为空，也即不实际控制任何资源； +- 第 11 行的 ``find_pte`` 和之前的 ``find_pte_create`` 不同之处在于它不会试图分配物理页帧。一旦在多级页表上遍历 + 遇到空指针它就会直接返回 ``None`` 表示无法正确找到传入的虚拟页号对应的页表项； +- 第 28 行的 ``translate`` 调用 ``find_pte`` 来实现，如果能够找到页表项，那么它会将页表项拷贝一份并返回，否则就 + 返回一个 ``None`` 。 + +.. chyyuu 没有提到from_token的作用??? \ No newline at end of file diff --git a/guide/source/chapter4/5kernel-app-spaces.rst b/guide/source/chapter4/5kernel-app-spaces.rst new file mode 100644 index 0000000..3eb3da0 --- /dev/null +++ b/guide/source/chapter4/5kernel-app-spaces.rst @@ -0,0 +1,586 @@ +内核与应用的地址空间 +================================================ + + +本节我们就在内核中通过基于页表的各种数据结构实现地址空间的抽象。 + +实现地址空间抽象 +------------------------------------------ + + +逻辑段：一段连续地址的虚拟内存 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +我们以逻辑段 ``MapArea`` 为单位描述一段连续地址的虚拟内存。所谓逻辑段，就是指地址区间中的一段实际可用（即 MMU 通过查多级页表 +可以正确完成地址转换）的地址连续的虚拟地址区间，该区间内包含的所有虚拟页面都以一种相同的方式映射到物理页帧，具有可读/可写/可执行等属性。 + +.. code-block:: rust + + // os/src/mm/memory_set.rs + + pub struct MapArea { + vpn_range: VPNRange, + data_frames: BTreeMap, + map_type: MapType, + map_perm: MapPermission, + } + +其中 ``VPNRange`` 描述一段虚拟页号的连续区间，表示该逻辑段在地址区间中的位置和长度。它是一个迭代器，可以使用 Rust +的语法糖 for-loop 进行迭代。有兴趣的读者可以参考 ``os/src/mm/address.rs`` 中它的实现。 + +.. note:: + + **Rust 语法卡片：迭代器 Iterator** + + Rust编程的迭代器模式允许你对一个序列的项进行某些处理。迭代器（iterator）是负责遍历序列中的每一项和决定序列何时结束的控制逻辑。 + 对于如何使用迭代器处理元素序列和如何实现 Iterator trait 来创建自定义迭代器的内容， + 可以参考 `Rust 程序设计语言-中文版第十三章第二节 `_ + +``MapType`` 描述该逻辑段内的所有虚拟页面映射到物理页帧的同一种方式，它是一个枚举类型，在内核当前的实现中支持两种方式： + +.. code-block:: rust + + // os/src/mm/memory_set.rs + + #[derive(Copy, Clone, PartialEq, Debug)] + pub enum MapType { + Identical, + Framed, + } + +其中 ``Identical`` 表示之前也有提到的恒等映射，用于在启用多级页表之后仍能够访问一个特定的物理地址指向的物理内存；而 +``Framed`` 则表示对于每个虚拟页面都需要映射到一个新分配的物理页帧。 + +当逻辑段采用 ``MapType::Framed`` 方式映射到物理内存的时候， ``data_frames`` 是一个保存了该逻辑段内的每个虚拟页面 +和它被映射到的物理页帧 ``FrameTracker`` 的一个键值对容器 ``BTreeMap`` 中，这些物理页帧被用来存放实际内存数据而不是 +作为多级页表中的中间节点。和之前的 ``PageTable`` 一样，这也用到了 RAII 的思想，将这些物理页帧的生命周期绑定到它所在的逻辑段 +``MapArea`` 下，当逻辑段被回收之后这些之前分配的物理页帧也会自动地同时被回收。 + +``MapPermission`` 表示控制该逻辑段的访问方式，它是页表项标志位 ``PTEFlags`` 的一个子集，仅保留 U/R/W/X +四个标志位，因为其他的标志位仅与硬件的地址转换机制细节相关，这样的设计能避免引入错误的标志位。 + +.. code-block:: rust + + // os/src/mm/memory_set.rs + + bitflags! { + pub struct MapPermission: u8 { + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + } + } + + + +地址空间：一系列有关联的逻辑段 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +地址空间是一系列有关联的逻辑段，这种关联一般是指这些逻辑段属于一个运行的程序（目前把一个运行的程序称为任务，后续会称为进程）。 +用来表明正在运行的应用所在执行环境中的可访问内存空间，在这个内存空间中，包含了一系列的不一定连续的逻辑段。 +这样我们就有任务的地址空间、内核的地址空间等说法了。地址空间使用 ``MemorySet`` 类型来表示： + +.. code-block:: rust + + // os/src/mm/memory_set.rs + + pub struct MemorySet { + page_table: PageTable, + areas: Vec, + } + +它包含了该地址空间的多级页表 ``page_table`` 和一个逻辑段 ``MapArea`` 的向量 ``areas`` 。注意 ``PageTable`` 下 +挂着所有多级页表的节点所在的物理页帧，而每个 ``MapArea`` 下则挂着对应逻辑段中的数据所在的物理页帧，这两部分 +合在一起构成了一个地址空间所需的所有物理页帧。这同样是一种 RAII 风格，当一个地址空间 ``MemorySet`` 生命周期结束后， +这些物理页帧都会被回收。 + +地址空间 ``MemorySet`` 的方法如下： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + impl MemorySet { + pub fn new_bare() -> Self { + Self { + page_table: PageTable::new(), + areas: Vec::new(), + } + } + fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) { + map_area.map(&mut self.page_table); + if let Some(data) = data { + map_area.copy_data(&mut self.page_table, data); + } + self.areas.push(map_area); + } + /// Assume that no conflicts. + pub fn insert_framed_area( + &mut self, + start_va: VirtAddr, end_va: VirtAddr, permission: MapPermission + ) { + self.push(MapArea::new( + start_va, + end_va, + MapType::Framed, + permission, + ), None); + } + pub fn new_kernel() -> Self; + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize); + } + +- 第 4 行， ``new_bare`` 方法可以新建一个空的地址空间； +- 第 10 行， ``push`` 方法可以在当前地址空间插入一个新的逻辑段 ``map_area`` ，如果它是以 ``Framed`` 方式映射到 + 物理内存，还可以可选地在那些被映射到的物理页帧上写入一些初始化数据 ``data`` ； +- 第 18 行， ``insert_framed_area`` 方法调用 ``push`` ，可以在当前地址空间插入一个 ``Framed`` 方式映射到 + 物理内存的逻辑段。注意该方法的调用者要保证同一地址空间内的任意两个逻辑段不能存在交集，从后面即将分别介绍的内核和 + 应用的地址空间布局可以看出这一要求得到了保证； +- 第 29 行， ``new_kernel`` 可以生成内核的地址空间，而第 32 行的 ``from_elf`` 则可以应用的 ELF 格式可执行文件 + 解析出各数据段并对应生成应用的地址空间。它们的实现我们将在后面讨论。 + +在实现 ``push`` 方法在地址空间中插入一个逻辑段 ``MapArea`` 的时候，需要同时维护地址空间的多级页表 ``page_table`` +记录的虚拟页号到页表项的映射关系，也需要用到这个映射关系来找到向哪些物理页帧上拷贝初始数据。这用到了 ``MapArea`` +提供的另外几个方法： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + impl MapArea { + pub fn new( + start_va: VirtAddr, + end_va: VirtAddr, + map_type: MapType, + map_perm: MapPermission + ) -> Self { + let start_vpn: VirtPageNum = start_va.floor(); + let end_vpn: VirtPageNum = end_va.ceil(); + Self { + vpn_range: VPNRange::new(start_vpn, end_vpn), + data_frames: BTreeMap::new(), + map_type, + map_perm, + } + } + pub fn map(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.map_one(page_table, vpn); + } + } + pub fn unmap(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.unmap_one(page_table, vpn); + } + } + /// data: start-aligned but maybe with shorter length + /// assume that all frames were cleared before + pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) { + assert_eq!(self.map_type, MapType::Framed); + let mut start: usize = 0; + let mut current_vpn = self.vpn_range.get_start(); + let len = data.len(); + loop { + let src = &data[start..len.min(start + PAGE_SIZE)]; + let dst = &mut page_table + .translate(current_vpn) + .unwrap() + .ppn() + .get_bytes_array()[..src.len()]; + dst.copy_from_slice(src); + start += PAGE_SIZE; + if start >= len { + break; + } + current_vpn.step(); + } + } + } + +- 第 4 行的 ``new`` 方法可以新建一个逻辑段结构体，注意传入的起始/终止虚拟地址会分别被下取整/上取整为虚拟页号并传入 + 迭代器 ``vpn_range`` 中； +- 第 19 行的 ``map`` 和第 24 行的 ``unmap`` 可以将当前逻辑段到物理内存的映射从传入的该逻辑段所属的地址空间的 + 多级页表中加入或删除。可以看到它们的实现是遍历逻辑段中的所有虚拟页面，并以每个虚拟页面为单位依次在多级页表中进行 + 键值对的插入或删除，分别对应 ``MapArea`` 的 ``map_one`` 和 ``unmap_one`` 方法，我们后面将介绍它们的实现； +- 第 31 行的 ``copy_data`` 方法将切片 ``data`` 中的数据拷贝到当前逻辑段实际被内核放置在的各物理页帧上，从而 + 在地址空间中通过该逻辑段就能访问这些数据。调用它的时候需要满足：切片 ``data`` 中的数据大小不超过当前逻辑段的 + 总大小，且切片中的数据会被对齐到逻辑段的开头，然后逐页拷贝到实际的物理页帧。 + + 从第 36 行开始的循环会遍历每一个需要拷贝数据的虚拟页面，在数据拷贝完成后会在第 48 行通过调用 ``step`` 方法，该 + 方法来自于 ``os/src/mm/address.rs`` 中为 ``VirtPageNum`` 实现的 ``StepOne`` Trait，感兴趣的读者可以阅读 + 代码确认其实现。 + + 每个页面的数据拷贝需要确定源 ``src`` 和目标 ``dst`` 两个切片并直接使用 ``copy_from_slice`` 完成复制。当确定 + 目标切片 ``dst`` 的时候，第 ``39`` 行从传入的当前逻辑段所属的地址空间的多级页表中手动查找迭代到的虚拟页号被映射 + 到的物理页帧，并通过 ``get_bytes_array`` 方法获取能够真正改写该物理页帧上内容的字节数组型可变引用，最后再获取它 + 的切片用于数据拷贝。 + +接下来介绍对逻辑段中的单个虚拟页面进行映射/解映射的方法 ``map_one`` 和 ``unmap_one`` 。显然它们的实现取决于当前 +逻辑段被映射到物理内存的方式： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + impl MemoryArea { + pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + let ppn: PhysPageNum; + match self.map_type { + MapType::Identical => { + ppn = PhysPageNum(vpn.0); + } + MapType::Framed => { + let frame = frame_alloc().unwrap(); + ppn = frame.ppn; + self.data_frames.insert(vpn, frame); + } + } + let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap(); + page_table.map(vpn, ppn, pte_flags); + } + pub fn unmap_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + match self.map_type { + MapType::Framed => { + self.data_frames.remove(&vpn); + } + _ => {} + } + page_table.unmap(vpn); + } + } + +- 对于第 4 行的 ``map_one`` 来说，在虚拟页号 ``vpn`` 已经确定的情况下，它需要知道要将一个怎么样的页表项插入多级页表。 + 页表项的标志位来源于当前逻辑段的类型为 ``MapPermission`` 的统一配置，只需将其转换为 ``PTEFlags`` ；而页表项的 + 物理页号则取决于当前逻辑段映射到物理内存的方式： + + - 当以恒等映射 ``Identical`` 方式映射的时候，物理页号就等于虚拟页号； + - 当以 ``Framed`` 方式映射的时候，需要分配一个物理页帧让当前的虚拟页面可以映射过去，此时页表项中的物理页号自然就是 + 这个被分配的物理页帧的物理页号。此时还需要将这个物理页帧挂在逻辑段的 ``data_frames`` 字段下。 + + 当确定了页表项的标志位和物理页号之后，即可调用多级页表 ``PageTable`` 的 ``map`` 接口来插入键值对。 +- 对于第 19 行的 ``unmap_one`` 来说，基本上就是调用 ``PageTable`` 的 ``unmap`` 接口删除以传入的虚拟页号为键的 + 键值对即可。然而，当以 ``Framed`` 映射的时候，不要忘记同时将虚拟页面被映射到的物理页帧 ``FrameTracker`` 从 + ``data_frames`` 中移除，这样这个物理页帧才能立即被回收以备后续分配。 + +内核地址空间 +------------------------------------------ + +.. _term-isolation: + +在本章之前，内核和应用代码的访存地址都被视为一个物理地址直接访问物理内存，而在分页模式开启之后，它们都需要通过 MMU 的 +地址转换变成物理地址再交给 CPU 的访存单元去访问物理内存。地址空间抽象的重要意义在于 **隔离** (Isolation) ，当我们 +在执行每个应用的代码的时候，内核需要控制 MMU 使用这个应用地址空间的多级页表进行地址转换。由于每个应用地址空间在创建 +的时候也顺带设置好了多级页表使得只有那些存放了它的数据的物理页帧能够通过该多级页表被映射到，这样它就只能访问自己的数据 +而无法触及其他应用或是内核的数据。 + +.. _term-trampoline: + +启用分页模式下，内核代码的访存地址也会被视为一个虚拟地址并需要经过 MMU 的地址转换，因此我们也需要为内核对应构造一个 +地址空间，它除了仍然需要允许内核的各数据段能够被正常访问之后，还需要包含所有应用的内核栈以及一个 +**跳板** (Trampoline) 。我们会在本章的最后一节再深入介绍跳板的机制。 + +下图是软件看到的 64 位地址空间在 SV39 分页模式下实际可能通过 MMU 检查的最高 :math:`256\text{GiB}` （之前在 +:ref:`这里 ` 中解释过最高和最低 :math:`256\text{GiB}` 的问题）： + +.. image:: kernel-as-high.png + :name: kernel-as-high + :align: center + :height: 400 + +可以看到，跳板放在最高的一个虚拟页面中。接下来则是从高到低放置每个应用的内核栈，内核栈的大小由 ``config`` 子模块的 +``KERNEL_STACK_SIZE`` 给出。它们的映射方式为 ``MapPermission`` 中的 rw 两个标志位，意味着这个逻辑段仅允许 +CPU 处于内核态访问，且只能读或写。 + +.. _term-guard-page: + +注意相邻两个内核栈之间会预留一个 **保护页面** (Guard Page) ，它是内核地址空间中的空洞，多级页表中并不存在与它相关的映射。 +它的意义在于当内核栈空间不足（如调用层数过多或死递归）的时候，代码会尝试访问 +空洞区域内的虚拟地址，然而它无法在多级页表中找到映射，便会触发异常，此时控制权会交给 trap handler 对这种情况进行 +处理。由于编译器会对访存顺序和局部变量在栈帧中的位置进行优化，我们难以确定一个已经溢出的栈帧中的哪些位置会先被访问， +但总的来说，空洞区域被设置的越大，我们就能越早捕获到这一错误并避免它覆盖其他重要数据。由于我们的内核非常简单且内核栈 +的大小设置比较宽裕，在当前的设计中我们仅将空洞区域的大小设置为单个页面。 + +下面则给出了内核地址空间的低 :math:`256\text{GiB}` 的布局： + +.. image:: kernel-as-low.png + :align: center + :height: 400 + +四个逻辑段 ``.text/.rodata/.data/.bss`` 被恒等映射到物理内存，这使得我们在无需调整内核内存布局 ``os/src/linker.ld`` +的情况下就仍能和启用页表机制之前那样访问内核的各数据段。注意我们借用页表机制对这些逻辑段的访问方式做出了限制，这都是为了 +在硬件的帮助下能够尽可能发现内核中的 bug ，在这里： + +- 四个逻辑段的 U 标志位均未被设置，使得 CPU 只能在处于 S 特权级（或以上）时访问它们； +- 代码段 ``.text`` 不允许被修改； +- 只读数据段 ``.rodata`` 不允许被修改，也不允许从它上面取指； +- ``.data/.bss`` 均允许被读写，但是不允许从它上面取指。 + +此外， :ref:`之前 ` 提到过内核地址空间中需要存在一个恒等映射到内核数据段之外的可用物理 +页帧的逻辑段，这样才能在启用页表机制之后，内核仍能以纯软件的方式读写这些物理页帧。它们的标志位仅包含 rw ，意味着该 +逻辑段只能在 S 特权级以上访问，并且只能读写。 + +下面我们给出创建内核地址空间的方法 ``new_kernel`` ： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss_with_stack(); + fn ebss(); + fn ekernel(); + fn strampoline(); + } + + impl MemorySet { + /// Without kernel stacks. + pub fn new_kernel() -> Self { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map kernel sections + println!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + println!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + println!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + println!(".bss [{:#x}, {:#x})", sbss_with_stack as usize, ebss as usize); + println!("mapping .text section"); + memory_set.push(MapArea::new( + (stext as usize).into(), + (etext as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::X, + ), None); + println!("mapping .rodata section"); + memory_set.push(MapArea::new( + (srodata as usize).into(), + (erodata as usize).into(), + MapType::Identical, + MapPermission::R, + ), None); + println!("mapping .data section"); + memory_set.push(MapArea::new( + (sdata as usize).into(), + (edata as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), None); + println!("mapping .bss section"); + memory_set.push(MapArea::new( + (sbss_with_stack as usize).into(), + (ebss as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), None); + println!("mapping physical memory"); + memory_set.push(MapArea::new( + (ekernel as usize).into(), + MEMORY_END.into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), None); + memory_set + } + } + +``new_kernel`` 将映射跳板和地址空间中最低 :math:`256\text{GiB}` 中的所有的逻辑段。第 3 行开始，我们从 +``os/src/linker.ld`` 中引用了很多表示了各个段位置的符号，而后在 ``new_kernel`` 中，我们从低地址到高地址 +依次创建 5 个逻辑段并通过 ``push`` 方法将它们插入到内核地址空间中，上面我们已经详细介绍过这 5 个逻辑段。跳板 +是通过 ``map_trampoline`` 方法来映射的，我们也将在本章最后一节进行讲解。 + +应用地址空间 +------------------------------------------ + +现在我们来介绍如何创建应用的地址空间。在前面的章节中，我们直接将丢弃所有符号的应用二进制镜像链接到内核，在初始化的时候 +内核仅需将他们加载到正确的初始物理地址就能使它们正确执行。但本章中，我们希望效仿内核地址空间的设计，同样借助页表机制 +使得应用地址空间的各个逻辑段也可以有不同的访问方式限制，这样可以提早检测出应用的错误并及时将其终止以最小化它对系统带来的 +恶劣影响。 + +在第三章中，每个应用链接脚本中的起始地址被要求是不同的，这样它们的代码和数据存放的位置才不会产生冲突。但是这是一种对于应用开发者 +极其不友好的设计。现在，借助地址空间的抽象，我们终于可以让所有应用程序都使用同样的起始地址，这也意味着所有应用可以使用同一个链接脚本了： + +.. code-block:: + :linenos: + + /* user/src/linker.ld */ + + OUTPUT_ARCH(riscv) + ENTRY(_start) + + BASE_ADDRESS = 0x0; + + SECTIONS + { + . = BASE_ADDRESS; + .text : { + *(.text.entry) + *(.text .text.*) + } + . = ALIGN(4K); + .rodata : { + *(.rodata .rodata.*) + } + . = ALIGN(4K); + .data : { + *(.data .data.*) + } + .bss : { + *(.bss .bss.*) + } + /DISCARD/ : { + *(.eh_frame) + *(.debug*) + } + } + +我们将起始地址 ``BASE_ADDRESS`` 设置为 :math:`\text{0x0}` ，显然它只能是一个地址空间中的虚拟地址而非物理地址。 +事实上由于我们将入口汇编代码段放在最低的地方，这也是整个应用的入口点。 +我们只需清楚这一事实即可，而无需像之前一样将其硬编码到代码中。此外，在 ``.text`` 和 ``.rodata`` 中间以及 ``.rodata`` 和 +``.data`` 中间我们进行了页面对齐，因为前后两个逻辑段的访问方式限制是不同的，由于我们只能以页为单位对这个限制进行设置， +因此就只能将下一个逻辑段对齐到下一个页面开始放置。相对的， ``.data`` 和 ``.bss`` 两个逻辑段由于限制相同，它们中间 +则无需进行页面对齐。 + +下图展示了应用地址空间的布局： + +.. image:: app-as-full.png + :align: center + :height: 400 + +左侧给出了应用地址空间最低 :math:`256\text{GiB}` 的布局：从 :math:`\text{0x0}` 开始向高地址放置应用内存布局中的 +各个逻辑段，最后放置带有一个保护页面的用户栈。这些逻辑段都是以 ``Framed`` 方式映射到物理内存的，从访问方式上来说都加上 +了 U 标志位代表 CPU 可以在 U 特权级也就是执行应用代码的时候访问它们。右侧则给出了最高的 :math:`256\text{GiB}` ， +可以看出它只是和内核地址空间一样将跳板放置在最高页，还将 Trap 上下文放置在次高页中。这两个虚拟页面虽然位于应用地址空间， +但是它们并不包含 U 标志位，事实上它们在地址空间切换的时候才会发挥作用，请同样参考本章的最后一节。 + +在 ``os/src/build.rs`` 中，我们不再将丢弃了所有符号的应用二进制镜像链接进内核，而是直接使用 ELF 格式的可执行文件， +因为在前者中内存布局中各个逻辑段的位置和访问限制等信息都被裁剪掉了。而 ``loader`` 子模块也变得极其精简： + +.. code-block:: rust + + // os/src/loader.rs + + pub fn get_num_app() -> usize { + extern "C" { fn _num_app(); } + unsafe { (_num_app as usize as *const usize).read_volatile() } + } + + pub fn get_app_data(app_id: usize) -> &'static [u8] { + extern "C" { fn _num_app(); } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = get_num_app(); + let app_start = unsafe { + core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1) + }; + assert!(app_id < num_app); + unsafe { + core::slice::from_raw_parts( + app_start[app_id] as *const u8, + app_start[app_id + 1] - app_start[app_id] + ) + } + } + +它仅需要提供两个函数： ``get_num_app`` 获取链接到内核内的应用的数目，而 ``get_app_data`` 则根据传入的应用编号 +取出对应应用的 ELF 格式可执行文件数据。它们和之前一样仍是基于 ``build.rs`` 生成的 ``link_app.S`` 给出的符号来 +确定其位置，并实际放在内核的数据段中。 +``loader`` 模块中原有的内核和用户栈则分别作为逻辑段放在内核和用户地址空间中，我们无需再去专门为其定义一种类型。 + +在创建应用地址空间的时候，我们需要对 ``get_app_data`` 得到的 ELF 格式数据进行解析，找到各个逻辑段所在位置和访问 +限制并插入进来，最终得到一个完整的应用地址空间： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + impl MemorySet { + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map program headers of elf, with U flag + let elf = xmas_elf::ElfFile::new(elf_data).unwrap(); + let elf_header = elf.header; + let magic = elf_header.pt1.magic; + assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!"); + let ph_count = elf_header.pt2.ph_count(); + let mut max_end_vpn = VirtPageNum(0); + for i in 0..ph_count { + let ph = elf.program_header(i).unwrap(); + if ph.get_type().unwrap() == xmas_elf::program::Type::Load { + let start_va: VirtAddr = (ph.virtual_addr() as usize).into(); + let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into(); + let mut map_perm = MapPermission::U; + let ph_flags = ph.flags(); + if ph_flags.is_read() { map_perm |= MapPermission::R; } + if ph_flags.is_write() { map_perm |= MapPermission::W; } + if ph_flags.is_execute() { map_perm |= MapPermission::X; } + let map_area = MapArea::new( + start_va, + end_va, + MapType::Framed, + map_perm, + ); + max_end_vpn = map_area.vpn_range.get_end(); + memory_set.push( + map_area, + Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]) + ); + } + } + // map user stack with U flags + let max_end_va: VirtAddr = max_end_vpn.into(); + let mut user_stack_bottom: usize = max_end_va.into(); + // guard page + user_stack_bottom += PAGE_SIZE; + let user_stack_top = user_stack_bottom + USER_STACK_SIZE; + memory_set.push(MapArea::new( + user_stack_bottom.into(), + user_stack_top.into(), + MapType::Framed, + MapPermission::R | MapPermission::W | MapPermission::U, + ), None); + // map TrapContext + memory_set.push(MapArea::new( + TRAP_CONTEXT.into(), + TRAMPOLINE.into(), + MapType::Framed, + MapPermission::R | MapPermission::W, + ), None); + (memory_set, user_stack_top, elf.header.pt2.entry_point() as usize) + } + } + +- 第 9 行，我们将跳板插入到应用地址空间； +- 第 11 行，我们使用外部 crate ``xmas_elf`` 来解析传入的应用 ELF 数据并可以轻松取出各个部分。 + :ref:`此前 ` 我们简要介绍过 ELF 格式的布局。第 14 行，我们取出 ELF 的魔数来判断 + 它是不是一个合法的 ELF 。 + + 第 15 行，我们可以直接得到 program header 的数目，然后遍历所有的 program header 并将合适的区域加入 + 到应用地址空间中。这一过程的主体在第 17~39 行之间。第 19 行我们确认 program header 的类型是 ``LOAD`` ， + 这表明它有被内核加载的必要，此时不必理会其他类型的 program header 。接着通过 ``ph.virtual_addr()`` 和 + ``ph.mem_size()`` 来计算这一区域在应用地址空间中的位置，通过 ``ph.flags()`` 来确认这一区域访问方式的 + 限制并将其转换为 ``MapPermission`` 类型（注意它默认包含 U 标志位）。最后我们在第 27 行创建逻辑段 + ``map_area`` 并在第 34 行 ``push`` 到应用地址空间。在 ``push`` 的时候我们需要完成数据拷贝，当前 + program header 数据被存放的位置可以通过 ``ph.offset()`` 和 ``ph.file_size()`` 来找到。 注意当 + 存在一部分零初始化的时候， ``ph.file_size()`` 将会小于 ``ph.mem_size()`` ，因为这些零出于缩减可执行 + 文件大小的原因不应该实际出现在 ELF 数据中。 +- 我们从第 40 行开始处理用户栈。注意在前面加载各个 program header 的时候，我们就已经维护了 ``max_end_vpn`` + 记录目前涉及到的最大的虚拟页号，只需紧接着在它上面再放置一个保护页面和用户栈即可。 +- 第 53 行则在应用地址空间中映射次高页面来存放 Trap 上下文。 +- 第 59 行返回的时候，我们不仅返回应用地址空间 ``memory_set`` ，也同时返回用户栈虚拟地址 ``user_stack_top`` + 以及从解析 ELF 得到的该应用入口点地址，它们将被我们用来创建应用的任务控制块。 \ No newline at end of file diff --git a/guide/source/chapter4/6multitasking-based-on-as.rst b/guide/source/chapter4/6multitasking-based-on-as.rst new file mode 100644 index 0000000..24ec9e7 --- /dev/null +++ b/guide/source/chapter4/6multitasking-based-on-as.rst @@ -0,0 +1,684 @@ +基于地址空间的分时多任务 +============================================================== + +本节我们介绍如何基于地址空间抽象来实现第三章的分时多任务系统。 + +建立并开启基于分页模式的虚拟地址空间 +-------------------------------------------- + +当 SBI 实现（本项目中基于 RustSBI）初始化完成后， CPU 将跳转到内核入口点并在 S 特权级上执行，此时还并没有开启分页模式 +，内核的每一次访存仍被视为一个物理地址直接访问物理内存。而在开启分页模式之后，内核的代码在访存的时候只能看到内核地址空间， +此时每次访存将被视为一个虚拟地址且需要通过 MMU 基于内核地址空间的多级页表的地址转换。这两种模式之间的过渡在内核初始化期间 +完成。 + +创建内核地址空间 +^^^^^^^^^^^^^^^^^^^^^^^^ + + +我们创建内核地址空间的全局实例： + +.. code-block:: rust + + // os/src/mm/memory_set.rs + + lazy_static! { + pub static ref KERNEL_SPACE: Arc> = Arc::new(unsafe { + UPSafeCell::new(MemorySet::new_kernel() + )}); + } + +从之前对于 ``lazy_static!`` 宏的介绍可知， ``KERNEL_SPACE`` 在运行期间它第一次被用到时才会实际进行初始化，而它所 +占据的空间则是编译期被放在全局数据段中。 ``Arc>`` 同时带来 ``Arc`` 提供的共享 +引用，和 ``UPSafeCell`` 提供的互斥访问。 + +在 ``rust_main`` 函数中，我们首先调用 ``mm::init`` 进行内存管理子系统的初始化： + +.. code-block:: rust + + // os/src/mm/mod.rs + + pub use memory_set::KERNEL_SPACE; + + pub fn init() { + heap_allocator::init_heap(); + frame_allocator::init_frame_allocator(); + KERNEL_SPACE.exclusive_access().activate(); + } + +可以看到，我们最先进行了全局动态内存分配器的初始化，因为接下来马上就要用到 Rust 的堆数据结构。接下来我们初始化物理页帧 +管理器（内含堆数据结构 ``Vec`` ）使能可用物理页帧的分配和回收能力。最后我们创建内核地址空间并让 CPU 开启分页模式， +MMU 在地址转换的时候使用内核的多级页表，这一切均在一行之内做到： + +- 首先，我们引用 ``KERNEL_SPACE`` ，这是它第一次被使用，就在此时它会被初始化，调用 ``MemorySet::new_kernel`` + 创建一个内核地址空间并使用 ``Arc>`` 包裹起来； + +- 最然后，我们调用 ``MemorySet::activate`` ： + + .. code-block:: rust + :linenos: + + // os/src/mm/page_table.rs + + pub fn token(&self) -> usize { + 8usize << 60 | self.root_ppn.0 + } + + // os/src/mm/memory_set.rs + + impl MemorySet { + pub fn activate(&self) { + let satp = self.page_table.token(); + unsafe { + satp::write(satp); + core::arch::asm!("sfence.vma"); + } + } + } + + ``PageTable::token`` 会按照 :ref:`satp CSR 格式要求 ` 构造一个无符号 64 位无符号整数，使得其 + 分页模式为 SV39 ，且将当前多级页表的根节点所在的物理页号填充进去。在 ``activate`` 中，我们将这个值写入当前 CPU 的 + satp CSR ，从这一刻开始 SV39 分页模式就被启用了，而且 MMU 会使用内核地址空间的多级页表进行地址转换。 + + 我们必须注意切换 satp CSR 是否是一个 *平滑* 的过渡：其含义是指，切换 satp 的指令及其下一条指令这两条相邻的指令的 + 虚拟地址是相邻的（由于切换 satp 的指令并不是一条跳转指令， pc 只是简单的自增当前指令的字长）， + 而它们所在的物理地址一般情况下也是相邻的，但是它们所经过的地址转换流程却是不同的——切换 satp 导致 MMU 查的多级页表 + 是不同的。这就要求前后两个地址空间在切换 satp 的指令 *附近* 的映射满足某种意义上的连续性。 + + 幸运的是，我们做到了这一点。这条写入 satp 的指令及其下一条指令都在内核内存布局的代码段中，在切换之后是一个恒等映射， + 而在切换之前是视为物理地址直接取指，也可以将其看成一个恒等映射。这完全符合我们的期待：即使切换了地址空间，指令仍应该 + 能够被连续的执行。 + +注意到在 ``activate`` 的最后，我们插入了一条汇编指令 ``sfence.vma`` ，它又起到什么作用呢？ + +让我们再来回顾一下多级页表：它相比线性表虽然大量节约了内存占用，但是却需要 MMU 进行更多的隐式访存。如果是一个线性表， +MMU 仅需单次访存就能找到页表项并完成地址转换，而多级页表（以 SV39 为例，不考虑大页）最顺利的情况下也需要三次访存。这些 +额外的访存和真正访问数据的那些访存在空间上并不相邻，加大了多级缓存的压力，一旦缓存缺失将带来巨大的性能惩罚。如果采用 +多级页表实现，这个问题会变得更为严重，使得地址空间抽象的性能开销过大。 + +.. _term-tlb: + +为了解决性能问题，一种常见的做法是在 CPU 中利用部分硬件资源额外加入一个 **快表** +(TLB, Translation Lookaside Buffer) ， 它维护了部分虚拟页号到页表项的键值对。当 MMU 进行地址转换的时候，首先 +会到快表中看看是否匹配，如果匹配的话直接取出页表项完成地址转换而无需访存；否则再去查页表并将键值对保存在快表中。一旦 +我们修改了 satp 切换了地址空间，快表中的键值对就会失效，因为它还表示着上个地址空间的映射关系。为了 MMU 的地址转换 +能够及时与 satp 的修改同步，我们可以选择立即使用 ``sfence.vma`` 指令将快表清空，这样 MMU 就不会看到快表中已经 +过期的键值对了。 + +.. _term-trampoline: + +跳板的实现 +------------------------------------ + +上一小节我们看到无论是内核还是应用的地址空间，最高的虚拟页面都是一个跳板。同时应用地址空间的次高虚拟页面还被设置为用来 +存放应用的 Trap 上下文。那么跳板究竟起什么作用呢？为何不直接把 Trap 上下文仍放到应用的内核栈中呢？ + +回忆曾在第二章介绍过的，当一个应用 Trap 到内核的时候， +``sscratch`` 已经指出了该应用内核栈的栈顶，我们用一条指令即可从用户栈切换到内核栈，然后直接将 Trap 上下文压入内核栈 +栈顶。当 Trap 处理完毕返回用户态的时候，将 Trap 上下文中的内容恢复到寄存器上，最后将保存着应用用户栈顶的 ``sscratch`` +与 sp 进行交换，也就从内核栈切换回了用户栈。在这个过程中， ``sscratch`` 起到了非常关键的作用，它使得我们可以在不破坏 +任何通用寄存器的情况下完成用户栈和内核栈顶的 Trap 上下文这两个工作区域之间的切换。 + +然而，一旦使能了分页机制，一切就并没有这么简单了，我们必须在这个过程中同时完成地址空间的切换。 +具体来说，当 ``__alltraps`` 保存 Trap 上下文的时候，我们必须通过修改 satp 从应用地址空间切换到内核地址空间， +因为 trap handler 只有在内核地址空间中才能访问； +同理，在 ``__restore`` 恢复 Trap 上下文的时候，我们也必须从内核地址空间切换回应用地址空间，因为应用的代码和 +数据只能在它自己的地址空间中才能访问，内核地址空间是看不到的。 +进而，地址空间的切换不能影响指令的连续执行，这就要求应用和内核地址空间在切换地址空间指令附近是平滑的。 + +.. _term-meltdown: + +.. note:: + + **内核与应用地址空间的隔离** + + 目前我们的设计是有一个唯一的内核地址空间存放内核的代码、数据，同时对于每个应用维护一个它们自己的地址空间，因此在 + Trap 的时候就需要进行地址空间切换，而在任务切换的时候无需进行（因为这个过程全程在内核内完成）。而教程前两版以及 + :math:`\mu` core 中的设计是每个应用都有一个地址空间，可以将其中的逻辑段分为内核和用户两部分，分别映射到内核和 + 用户的数据和代码，且分别在 CPU 处于 S/U 特权级时访问。此设计中并不存在一个单独的内核地址空间。 + + 之前设计方式的优点在于： Trap 的时候无需切换地址空间，而在任务切换的时候才需要切换地址空间。由于后者比前者更容易 + 实现，这降低了实现的复杂度。而且在应用高频进行系统调用的时候能够避免地址空间切换的开销，这通常源于快表或 cache + 的失效问题。但是这种设计方式也有缺点：即内核的逻辑段需要在每个应用的地址空间内都映射一次，这会带来一些无法忽略的 + 内存占用开销，并显著限制了嵌入式平台的任务并发数。此外，这种做法无法应对处理器的 `熔断 + (Meltdown) 漏洞 `_ ， + 使得恶意应用能够以某种方式看到它本来无权访问的地址空间中内核部分的数据。将内核与地址空间隔离便是修复此漏洞的一种方法。 + + 经过权衡，在本教程中我们参考 MIT 的教学 OS `xv6 `_ ， + 采用内核和应用地址空间隔离的设计。 + +我们为何将应用的 Trap 上下文放到应用地址空间的次高页面而不是内核地址空间中的内核栈中呢？原因在于，假如我们将其放在内核栈 +中，在保存 Trap 上下文之前我们必须先切换到内核地址空间，这就需要我们将内核地址空间的 token 写入 satp 寄存器，之后我们 +还需要有一个通用寄存器保存内核栈栈顶的位置，这样才能以它为基址保存 Trap 上下文。在保存 Trap 上下文之前我们必须完成这 +两项工作。然而，我们无法在不破坏任何一个通用寄存器的情况下做到这一点。因为事实上我们需要用到内核的两条信息：内核地址空间 +的 token 还有应用内核栈顶的位置，硬件却只提供一个 ``sscratch`` 可以用来进行周转。所以，我们不得不将 Trap 上下文保存在 +应用地址空间的一个虚拟页面中以避免切换到内核地址空间才能保存。 + +为了方便实现，我们在 Trap 上下文中包含更多内容（和我们关于上下文的定义有些不同，它们在初始化之后便只会被读取而不会被写入 +，并不是每次都需要保存/恢复）： + +.. code-block:: rust + :linenos: + :emphasize-lines: 8,9,10 + + // os/src/trap/context.rs + + #[repr(C)] + pub struct TrapContext { + pub x: [usize; 32], + pub sstatus: Sstatus, + pub sepc: usize, + pub kernel_satp: usize, + pub kernel_sp: usize, + pub trap_handler: usize, + } + +在多出的三个字段中： + +- ``kernel_satp`` 表示内核地址空间的 token ； +- ``kernel_sp`` 表示当前应用在内核地址空间中的内核栈栈顶的虚拟地址； +- ``trap_handler`` 表示内核中 trap handler 入口点的虚拟地址。 + +它们在应用初始化的时候由内核写入应用地址空间中的 TrapContext 的相应位置，此后就不再被修改。 + +让我们来看一下现在的 ``__alltraps`` 和 ``__restore`` 各是如何在保存和恢复 Trap 上下文的同时也切换地址空间的： + +.. code-block:: riscv + :linenos: + + # os/src/trap/trap.S + + .section .text.trampoline + .globl __alltraps + .globl __restore + .align 2 + __alltraps: + csrrw sp, sscratch, sp + # now sp->*TrapContext in user space, sscratch->user stack + # save other general purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they have been saved in TrapContext + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it in TrapContext + csrr t2, sscratch + sd t2, 2*8(sp) + # load kernel_satp into t0 + ld t0, 34*8(sp) + # load trap_handler into t1 + ld t1, 36*8(sp) + # move to kernel_sp + ld sp, 35*8(sp) + # switch to kernel space + csrw satp, t0 + sfence.vma + # jump to trap_handler + jr t1 + + __restore: + # a0: *TrapContext in user space(Constant); a1: user space token + # switch to user space + csrw satp, a1 + sfence.vma + csrw sscratch, a0 + mv sp, a0 + # now sp points to TrapContext in user space, start restoring based on it + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + # restore general purpose registers except x0/sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # back to user stack + ld sp, 2*8(sp) + sret + +- 当应用 Trap 进入内核的时候，硬件会设置一些 CSR 并在 S 特权级下跳转到 ``__alltraps`` 保存 Trap 上下文。此时 + sp 寄存器仍指向用户栈，但 ``sscratch`` 则被设置为指向应用地址空间中存放 Trap 上下文的位置，实际在次高页面。 + 随后，就像之前一样，我们 ``csrrw`` 交换 sp 和 ``sscratch`` ，并基于指向 Trap 上下文位置的 sp 开始保存通用 + 寄存器和一些 CSR ，这个过程在第 28 行结束。到这里，我们就全程在应用地址空间中完成了保存 Trap 上下文的工作。 + +- 接下来该考虑切换到内核地址空间并跳转到 trap handler 了。第 30 行我们将内核地址空间的 token 载入到 t0 寄存器中， + 第 32 行我们将 trap handler 入口点的虚拟地址载入到 t1 寄存器中，第 34 行我们直接将 sp 修改为应用内核栈顶的地址。 + 这三条信息均是内核在初始化该应用的时候就已经设置好的。第 36~37 行我们将 satp 修改为内核地址空间的 token 并使用 + ``sfence.vma`` 刷新快表，这就切换到了内核地址空间。最后在第 39 行我们通过 ``jr`` 指令跳转到 t1 寄存器所保存的 + trap handler 入口点的地址。注意这里我们不能像之前的章节那样直接 ``call trap_handler`` ，原因稍后解释。 +- 当内核将 Trap 处理完毕准备返回用户态的时候会 *调用* ``__restore`` ，它有两个参数：第一个是 Trap 上下文在应用 + 地址空间中的位置，这个对于所有的应用来说都是相同的，由调用规范在 a0 寄存器中传递；第二个则是即将回到的应用的地址空间 + 的 token ，在 a1 寄存器中传递。由于 Trap 上下文是保存在应用地址空间中的，第 44~45 行我们先切换回应用地址空间。第 + 46 行我们将传入的 Trap 上下文位置保存在 ``sscratch`` 寄存器中，这样 ``__alltraps`` 中才能基于它将 Trap 上下文 + 保存到正确的位置。第 47 行我们将 sp 修改为 Trap 上下文的位置，后面基于它恢复各通用寄存器和 CSR。最后在第 64 行， + 我们通过 ``sret`` 指令返回用户态。 + +接下来还需要考虑切换地址空间前后指令能否仍能连续执行。可以看到我们将 ``trap.S`` 中的整段汇编代码放置在 +``.text.trampoline`` 段，并在调整内存布局的时候将它对齐到代码段的一个页面中： + +.. code-block:: diff + :linenos: + + # os/src/linker.ld + + stext = .; + .text : { + *(.text.entry) + + . = ALIGN(4K); + + strampoline = .; + + *(.text.trampoline); + + . = ALIGN(4K); + *(.text .text.*) + } + +这样，这段汇编代码放在一个物理页帧中，且 ``__alltraps`` 恰好位于这个物理页帧的开头，其物理地址被外部符号 +``strampoline`` 标记。在开启分页模式之后，内核和应用代码都只能看到各自的虚拟地址空间，而在它们的视角中，这段汇编代码 +被放在它们地址空间的最高虚拟页面上，由于这段汇编代码在执行的时候涉及到地址空间切换，故而被称为跳板页面。 + +那么在产生trap前后的一小段时间内会有一个比较 **极端** 的情况，即刚产生trap时，CPU已经进入了内核态（即Supervisor Mode）， +但此时执行代码和访问数据还是在应用程序所处的用户态虚拟地址空间中，而不是我们通常理解的内核虚拟地址空间。在这段特殊的时间内，CPU指令 +为什么能够被连续执行呢？这里需要注意：无论是内核还是应用的地址空间，跳板的虚拟页均位于同样位置，且它们也将会映射到同一个实际存放这段 +汇编代码的物理页帧。也就是说，在执行 ``__alltraps`` 或 ``__restore`` 函数进行地址空间切换的时候， +应用的用户态虚拟地址空间和操作系统内核的内核态虚拟地址空间对切换地址空间的指令所在页的映射方式均是相同的， +这就说明了这段切换地址空间的指令控制流仍是可以连续执行的。 + +现在可以说明我们在创建用户/内核地址空间中用到的 ``map_trampoline`` 是如何实现的了： + +.. code-block:: rust + :linenos: + + // os/src/config.rs + + pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1; + + // os/src/mm/memory_set.rs + + impl MemorySet { + /// Mention that trampoline is not collected by areas. + fn map_trampoline(&mut self) { + self.page_table.map( + VirtAddr::from(TRAMPOLINE).into(), + PhysAddr::from(strampoline as usize).into(), + PTEFlags::R | PTEFlags::X, + ); + } + } + +这里我们为了实现方便并没有新增逻辑段 ``MemoryArea`` 而是直接在多级页表中插入一个从地址空间的最高虚拟页面映射到 +跳板汇编代码所在的物理页帧的键值对，访问方式限制与代码段相同，即 RX 。 + +最后可以解释为何我们在 ``__alltraps`` 中需要借助寄存器 ``jr`` 而不能直接 ``call trap_handler`` 了。因为在 +内存布局中，这条 ``.text.trampoline`` 段中的跳转指令和 ``trap_handler`` 都在代码段之内，汇编器（Assembler） +和链接器（Linker）会根据 ``linker.ld`` 的地址布局描述，设定电子指令的地址，并计算二者地址偏移量 +并让跳转指令的实际效果为当前 pc 自增这个偏移量。但实际上我们知道由于我们设计的缘故，这条跳转指令在被执行的时候， +它的虚拟地址被操作系统内核设置在地址空间中的最高页面之内，加上这个偏移量并不能正确的得到 ``trap_handler`` 的入口地址。 + +**问题的本质可以概括为：跳转指令实际被执行时的虚拟地址和在编译器/汇编器/链接器进行后端代码生成和链接形成最终机器码时设置此指令的地址是不同的。** + +加载和执行应用程序 +------------------------------------ + +扩展任务控制块 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +为了让应用在运行时有一个安全隔离且符合编译器给应用设定的地址空间布局的虚拟地址空间，操作系统需要对任务进行更多的管理，所以任务控制块相比第三章也包含了更多内容： + +.. code-block:: rust + :linenos: + :emphasize-lines: 6,7,8 + + // os/src/task/task.rs + + pub struct TaskControlBlock { + pub task_status: TaskStatus, + pub task_cx: TaskContext, + pub memory_set: MemorySet, + pub trap_cx_ppn: PhysPageNum, + pub base_size: usize, + } + +除了应用的地址空间 ``memory_set`` 之外，还有位于应用地址空间次高页的 Trap 上下文被实际存放在物理页帧的物理页号 +``trap_cx_ppn`` ，它能够方便我们对于 Trap 上下文进行访问。此外， ``base_size`` 统计了应用数据的大小，也就是 +在应用地址空间中从 :math:`\text{0x0}` 开始到用户栈结束一共包含多少字节。它后续还应该包含用于应用动态内存分配的 +堆空间的大小，但我们暂不支持。 + + + +更新对任务控制块的管理 +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +下面是任务控制块的创建： + +.. code-block:: rust + :linenos: + + // os/src/config.rs + + /// Return (bottom, top) of a kernel stack in kernel space. + pub fn kernel_stack_position(app_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) + } + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn new(elf_data: &[u8], app_id: usize) -> Self { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + let task_status = TaskStatus::Ready; + // map a kernel-stack in kernel space + let (kernel_stack_bottom, kernel_stack_top) = kernel_stack_position(app_id); + KERNEL_SPACE + .exclusive_access() + .insert_framed_area( + kernel_stack_bottom.into(), + kernel_stack_top.into(), + MapPermission::R | MapPermission::W, + ); + let task_control_block = Self { + task_status, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + memory_set, + trap_cx_ppn, + base_size: user_sp, + }; + // prepare TrapContext in user space + let trap_cx = task_control_block.get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + kernel_stack_top, + trap_handler as usize, + ); + task_control_block + } + } + +- 第 15 行，我们解析传入的 ELF 格式数据构造应用的地址空间 ``memory_set`` 并获得其他信息； +- 第 16 行，我们从地址空间 ``memory_set`` 中查多级页表找到应用地址空间中的 Trap 上下文实际被放在哪个物理页帧； +- 第 22 行，我们根据传入的应用 ID ``app_id`` 调用在 ``config`` 子模块中定义的 ``kernel_stack_position`` 找到 + 应用的内核栈预计放在内核地址空间 ``KERNEL_SPACE`` 中的哪个位置，并通过 ``insert_framed_area`` 实际将这个逻辑段 + 加入到内核地址空间中； + +.. _trap-return-intro: + +- 我们在应用的内核栈顶压入一个跳转到 ``trap_return`` 而不是 ``__restore`` 的任务上下文， + 这主要是为了能够支持对该应用的启动并顺利切换到用户地址空间执行。在构造方式上，只是将 ra 寄存器的值设置为 + ``trap_return`` 的地址。 ``trap_return`` 是我们后面要介绍的新版的 Trap 处理的一部分。 +- 初始化该应用的 Trap 上下文，由于它是在应用地址空间而不是在内核地址空间中，我们只能手动查页表找到 + Trap 上下文实际被放在的物理页帧，再获得在用户空间的 Trap 上下文的可变引用用于初始化： + + .. code-block:: rust + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + } + + 此处需要说明的是，返回 ``'static`` 的可变引用和之前一样可以看成一个绕过 unsafe 的裸指针；而 ``PhysPageNum::get_mut`` + 是一个泛型函数，由于我们已经声明了总体返回 ``TrapContext`` 的可变引用，则Rust编译器会给 ``get_mut`` 泛型函数针对具体类型 ``TrapContext`` + 的情况生成一个特定版本的 ``get_mut`` 函数实现。在 ``get_trap_cx`` 函数中则会静态调用``get_mut`` 泛型函数的特定版本实现。 + + .. code-block:: rust + :linenos: + :emphasize-lines: 8,9,10,18,19,20 + + // os/src/trap/context.rs + + impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { self.x[2] = sp; } + pub fn app_init_context( + entry: usize, + sp: usize, + kernel_satp: usize, + kernel_sp: usize, + trap_handler: usize, + ) -> Self { + let mut sstatus = sstatus::read(); + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + kernel_satp, + kernel_sp, + trap_handler, + }; + cx.set_sp(sp); + cx + } + } + + 和之前相比 ``TrapContext::app_init_context`` 需要补充上让应用在 ``__alltraps`` 能够顺利进入到内核地址空间 + 并跳转到 trap handler 入口点的相关信息。 + +在内核初始化的时候，需要将所有的应用加载到全局应用管理器中： + +.. code-block:: rust + :linenos: + + // os/src/task/mod.rs + + struct TaskManagerInner { + tasks: Vec, + current_task: usize, + } + + lazy_static! { + pub static ref TASK_MANAGER: TaskManager = { + info!("init TASK_MANAGER"); + let num_app = get_num_app(); + info!("num_app = {}", num_app); + let mut tasks: Vec = Vec::new(); + for i in 0..num_app { + tasks.push(TaskControlBlock::new(get_app_data(i), i)); + } + TaskManager { + num_app, + inner: unsafe { + UPSafeCell::new(TaskManagerInner { + tasks, + current_task: 0, + }) + }, + } + }; + } + +可以看到，在 ``TaskManagerInner`` 中我们使用向量 ``Vec`` 来保存任务控制块。在全局任务管理器 ``TASK_MANAGER`` +初始化的时候，只需使用 ``loader`` 子模块提供的 ``get_num_app`` 和 ``get_app_data`` 分别获取链接到内核的应用 +数量和每个应用的 ELF 文件格式的数据，然后依次给每个应用创建任务控制块并加入到向量中即可。我们还将 ``current_task`` 设置 +为 0 ，于是将从第 0 个应用开始执行。 + +回过头来介绍一下应用构建器 ``os/build.rs`` 的改动： + +- 首先，我们在 ``.incbin`` 中不再插入清除全部符号的应用二进制镜像 ``*.bin`` ，而是将构建得到的 ELF 格式文件直接链接进来； +- 其次，在链接每个 ELF 格式文件之前我们都加入一行 ``.align 3`` 来确保它们对齐到 8 字节，这是由于如果不这样做， + ``xmas-elf`` crate 可能会在解析 ELF 的时候进行不对齐的内存读写，例如使用 ``ld`` 指令从内存的一个没有对齐到 8 字节的地址加载一个 64 位的值到一个通用寄存器。 + +为了方便后续的实现，全局任务管理器还需要提供关于当前应用与地址空间有关的一些信息。通过 ``current_user_token`` 和 +``current_trap_cx`` 分别可以获得当前正在执行的应用的地址空间的 token 和可以在 +内核地址空间中修改位于该应用地址空间中的 Trap 上下文的可变引用。 + +改进 Trap 处理的实现 +------------------------------------ + +为了能够支持地址空间，让我们来看现在 ``trap_handler`` 的改进实现： + +.. code-block:: rust + :linenos: + + // os/src/trap/mod.rs + + fn set_kernel_trap_entry() { + unsafe { + stvec::write(trap_from_kernel as usize, TrapMode::Direct); + } + } + + #[no_mangle] + pub fn trap_from_kernel() -> ! { + panic!("a trap from kernel!"); + } + + #[no_mangle] + pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let cx = current_trap_cx(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + ... + } + trap_return(); + } + +由于应用的 Trap 上下文不在内核地址空间，因此我们调用 ``current_trap_cx`` 来获取当前应用的 Trap 上下文的可变引用 +而不是像之前那样作为参数传入 ``trap_handler`` 。至于 Trap 处理的过程则没有发生什么变化。 + +注意到，在 ``trap_handler`` 的开头还调用 ``set_kernel_trap_entry`` 将 ``stvec`` 修改为同模块下另一个函数 +``trap_from_kernel`` 的地址。这就是说，一旦进入内核后再次触发到 S 的 Trap，则会在硬件设置一些 CSR 之后跳过寄存器 +的保存过程直接跳转到 ``trap_from_kernel`` 函数，在这里我们直接 ``panic`` 退出。这是因为内核和应用的地址空间分离 +之后，从 U 还是从 S Trap 到 S 的 Trap 上下文保存与恢复实现方式和 Trap 处理逻辑有很大差别，我们不得不实现两遍而 +不太可能将二者整合起来。这里简单起见我们弱化了从 S 到 S 的 Trap ，省略了 Trap 上下文保存过程而直接 ``panic`` 。 + +在 ``trap_handler`` 完成 Trap 处理之后，我们需要调用 ``trap_return`` 返回用户态： + +.. code-block:: rust + :linenos: + + // os/src/trap/mod.rs + + fn set_user_trap_entry() { + unsafe { + stvec::write(TRAMPOLINE as usize, TrapMode::Direct); + } + } + + #[no_mangle] + pub fn trap_return() -> ! { + set_user_trap_entry(); + let trap_cx_ptr = TRAP_CONTEXT; + let user_satp = current_user_token(); + extern "C" { + fn __alltraps(); + fn __restore(); + } + let restore_va = __restore as usize - __alltraps as usize + TRAMPOLINE; + unsafe { + core::arch::asm!( + "fence.i", + "jr {restore_va}", + restore_va = in(reg) restore_va, + in("a0") trap_cx_ptr, + in("a1") user_satp, + options(noreturn) + ); + } + panic!("Unreachable in back_to_user!"); + } + +- 第 11 行，在 ``trap_return`` 的开头我们调用 ``set_user_trap_entry`` 来让应用 Trap 到 S 的时候可以跳转到 + ``__alltraps`` 。注意我们把 ``stvec`` 设置为内核和应用地址空间共享的跳板页面的起始地址 ``TRAMPOLINE`` 而不是 + 编译器在链接时看到的 ``__alltraps`` 的地址，因为启用分页模式之后我们只能通过跳板页面上的虚拟地址来实际取得 + ``__alltraps`` 和 ``__restore`` 的汇编代码。 +- 之前介绍的时候提到过 ``__restore`` 需要两个参数：分别是 Trap 上下文在应用地址空间中的虚拟地址和要继续执行的应用 + 地址空间的 token 。第 12 和第 13 行则分别准备好这两个参数。 +- 最后我们需要跳转到 ``__restore`` 切换到应用地址空间从 Trap 上下文中恢复通用寄存器并 ``sret`` 继续执行应用。它的 + 关键在于如何找到 ``__restore`` 在内核/应用地址空间中共同的虚拟地址。第 18 行我们展示了计算它的过程：由于 + ``__alltraps`` 是对齐到地址空间跳板页面的起始地址 ``TRAMPOLINE`` 上的， 则 ``__restore`` 的虚拟地址只需在 + ``TRAMPOLINE`` 基础上加上 ``__restore`` 相对于 ``__alltraps`` 的偏移量即可。这里 ``__alltraps`` 和 + ``__restore`` 都是指编译器在链接时看到的内核内存布局中的地址。我们使用 ``jr`` 指令完成了跳转的任务。 +- 在开始执行应用之前，我们需要使用 ``fence.i`` 指令清空指令缓存 i-cache 。这是因为，在内核中进行的一些操作 + 可能导致一些原先存放某个应用代码的物理页帧如今用来存放数据或者是其他应用的代码，i-cache 中可能还保存着该物理页帧的 + 错误快照。因此我们直接将整个 i-cache 清空避免错误。 + +改进 sys_write 的实现 +------------------------------------ + +同样由于内核和应用地址空间的隔离， ``sys_write`` 不再能够直接访问位于应用空间中的数据，而需要手动查页表才能知道那些 +数据被放置在哪些物理页帧上并进行访问。 + +为此，页表模块 ``page_table`` 提供了将应用地址空间中一个缓冲区转化为在内核空间中能够直接访问的形式的辅助函数： + +.. code-block:: rust + :linenos: + + // os/src/mm/page_table.rs + + pub fn translated_byte_buffer( + token: usize, + ptr: *const u8, + len: usize + ) -> Vec<&'static [u8]> { + let page_table = PageTable::from_token(token); + let mut start = ptr as usize; + let end = start + len; + let mut v = Vec::new(); + while start < end { + let start_va = VirtAddr::from(start); + let mut vpn = start_va.floor(); + let ppn = page_table + .translate(vpn) + .unwrap() + .ppn(); + vpn.step(); + let mut end_va: VirtAddr = vpn.into(); + end_va = end_va.min(VirtAddr::from(end)); + v.push(&ppn.get_bytes_array()[start_va.page_offset()..end_va.page_offset()]); + start = end_va.into(); + } + v + } + +参数中的 ``token`` 是某个应用地址空间的 token ， ``ptr`` 和 ``len`` 则分别表示该地址空间中的一段缓冲区的起始地址 +和长度。 ``translated_byte_buffer`` 会以向量的形式返回一组可以在内核空间中直接访问的字节数组切片，具体实现在这里 +不再赘述。 + +进而，我们完成对 ``sys_write`` 系统调用的改造： + +.. code-block:: rust + + // os/src/syscall/fs.rs + + pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDOUT => { + let buffers = translated_byte_buffer(current_user_token(), buf, len); + for buffer in buffers { + print!("{}", core::str::from_utf8(buffer).unwrap()); + } + len as isize + }, + _ => { + panic!("Unsupported fd in sys_write!"); + } + } + } + +我们尝试将每个字节数组切片转化为字符串 ``&str`` 然后输出即可。 + diff --git a/guide/source/chapter4/7exercise.rst b/guide/source/chapter4/7exercise.rst new file mode 100644 index 0000000..c14f860 --- /dev/null +++ b/guide/source/chapter4/7exercise.rst @@ -0,0 +1,113 @@ +chapter4练习 +============================================ + +编程作业 +--------------------------------------------- + +重写 sys_get_time 和 sys_task_info +++++++++++++++++++++++++++++++++++++++++++++ + +引入虚存机制后，原来内核的 sys_get_time 和 sys_task_info 函数实现就无效了。请你重写这个函数，恢复其正常功能。 + +mmap 和 munmap 匿名映射 +++++++++++++++++++++++++++++++++++++++++++++ + +`mmap `_ 在 Linux 中主要用于在内存中映射文件， +本次实验简化它的功能，仅用于申请内存。 + +请实现 mmap 和 munmap 系统调用，mmap 定义如下： + + +.. code-block:: rust + + fn sys_mmap(start: usize, len: usize, port: usize) -> isize + +- syscall ID：222 +- 申请长度为 len 字节的物理内存（不要求实际物理内存位置，可以随便找一块），将其映射到 start 开始的虚存，内存页属性为 port +- 参数： + - start 需要映射的虚存起始地址，要求按页对齐 + - len 映射字节长度，可以为 0 + - port：第 0 位表示是否可读，第 1 位表示是否可写，第 2 位表示是否可执行。其他位无效且必须为 0 +- 返回值：执行成功则返回 0，错误返回 -1 +- 说明： + - 为了简单，目标虚存区间要求按页对齐，len 可直接按页向上取整，不考虑分配失败时的页回收。 +- 可能的错误： + - start 没有按页大小对齐 + - port & !0x7 != 0 (port 其余位必须为0) + - port & 0x7 = 0 (这样的内存无意义) + - [start, start + len) 中存在已经被映射的页 + - 物理内存不足 + +munmap 定义如下： + +.. code-block:: rust + + fn sys_munmap(start: usize, len: usize) -> isize + +- syscall ID：215 +- 取消到 [start, start + len) 虚存的映射 +- 参数和返回值请参考 mmap +- 说明： + - 为了简单，参数错误时不考虑内存的恢复和回收。 +- 可能的错误： + - [start, start + len) 中存在未被映射的虚存。 + +tips: + +- 一定要注意 mmap 是的页表项，注意 riscv 页表项的格式与 port 的区别。 +- 你增加 PTE_U 了吗？ + +实验要求 +++++++++++++++++++++++++++++++++++++++++++ + +- 实现分支：ch4。 +- 实现 mmap 和 munmap 两个系统调用，通过所有测例。 +- 实验目录请参考 ch3，报告命名 lab2.md/pdf + +TIPS：注意 port 参数的语义，它与内核定义的 MapPermission 有明显不同！ + +问答作业 +------------------------------------------------- + +1. 请列举 SV39 页表页表项的组成，描述其中的标志位有何作用？ + +2. 缺页 + 缺页指的是进程访问页面时页面不在页表中或在页表中无效的现象，此时 MMU 将会返回一个中断， + 告知 os 进程内存访问出了问题。os 选择填补页表并重新执行异常指令或者杀死进程。 + + - 请问哪些异常可能是缺页导致的？ + - 发生缺页时，描述相关重要寄存器的值，上次实验描述过的可以简略。 + + 缺页有两个常见的原因，其一是 Lazy 策略，也就是直到内存页面被访问才实际进行页表操作。 + 比如，一个程序被执行时，进程的代码段理论上需要从磁盘加载到内存。但是 os 并不会马上这样做， + 而是会保存 .text 段在磁盘的位置信息，在这些代码第一次被执行时才完成从磁盘的加载操作。 + + - 这样做有哪些好处？ + + 其实，我们的 mmap 也可以采取 Lazy 策略，比如：一个用户进程先后申请了 10G 的内存空间， + 然后用了其中 1M 就直接退出了。按照现在的做法，我们显然亏大了，进行了很多没有意义的页表操作。 + + - 处理 10G 连续的内存页面，对应的 SV39 页表大致占用多少内存 (估算数量级即可)？ + - 请简单思考如何才能实现 Lazy 策略，缺页时又如何处理？描述合理即可，不需要考虑实现。 + + 缺页的另一个常见原因是 swap 策略，也就是内存页面可能被换到磁盘上了，导致对应页面失效。 + + - 此时页面失效如何表现在页表项(PTE)上？ + +3. 双页表与单页表 + + 为了防范侧信道攻击，我们的 os 使用了双页表。但是传统的设计一直是单页表的，也就是说， + 用户线程和对应的内核线程共用同一张页表，只不过内核对应的地址只允许在内核态访问。 + (备注：这里的单/双的说法仅为自创的通俗说法，并无这个名词概念，详情见 `KPTI `_ ) + + - 在单页表情况下，如何更换页表？ + - 单页表情况下，如何控制用户态无法访问内核页面？（tips:看看上一题最后一问） + - 单页表有何优势？（回答合理即可） + - 双页表实现下，何时需要更换页表？假设你写一个单页表操作系统，你会选择何时更换页表（回答合理即可）？ + +报告要求 +-------------------------------------------------------- + +- 简单总结你实现的功能（200字以内，不要贴代码）。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter4/address-translation.png b/guide/source/chapter4/address-translation.png new file mode 100644 index 0000000000000000000000000000000000000000..949120a5e05aaacaa5032085bcd735dd69cb35a1 GIT binary patch literal 44213 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 WjkhyT7p(dOGRM=^&t;ucLK6U%x2jeE literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/app-as-full.png b/guide/source/chapter4/app-as-full.png new file mode 100644 index 0000000000000000000000000000000000000000..796c23e751c721b86c3e4ad58eb4372c6ee46113 GIT binary patch literal 34166 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 KP@;G8+J6DbJy41O literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/index.rst b/guide/source/chapter4/index.rst new file mode 100644 index 0000000..715e8e2 --- /dev/null +++ b/guide/source/chapter4/index.rst @@ -0,0 +1,12 @@ +第四章：地址空间 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 3sv39-implementation-1 + 4sv39-implementation-2 + 5kernel-app-spaces + 6multitasking-based-on-as + 7exercise diff --git a/guide/source/chapter4/kernel-as-high.png b/guide/source/chapter4/kernel-as-high.png new file mode 100644 index 0000000000000000000000000000000000000000..344d94d92d9bbfbba00084dce256b12be6f06221 GIT binary patch literal 34754 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 UBIb3p02A;rI%A@TJ7pXEZ$f14Y5)KL literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/kernel-as-low.png b/guide/source/chapter4/kernel-as-low.png new file mode 100644 index 0000000000000000000000000000000000000000..8cf78a470e3dc17e243ce6d370cd3b92108a36a4 GIT binary patch literal 20344 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 JlG|3#{|DV!7lQx* literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/linear-table.png b/guide/source/chapter4/linear-table.png new file mode 100644 index 0000000000000000000000000000000000000000..ce3d95f3e42ec37414262b9e984d36ccdfee1402 GIT binary patch literal 20340 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

J8+azc$Axz}iS8qGd08R;;O1YjS-f@zy|lp(0R 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 XfxRNTJ-aN+Ym literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/rust-containers.png b/guide/source/chapter4/rust-containers.png new file mode 100644 index 0000000000000000000000000000000000000000..239ecba10220f43b1da57f1c5f01d31362f36787 GIT binary patch literal 87375 zcmd43bySqy7dDI_jdX}~2@D{mbT^2=zzp3XQW8pcmvk#3Lk|s-N(e}*C|y#DNO#wF z#^+aSy=#5%_viPAK8_D_-{; zQKKSRd$I;clCK?Io;`nBH@#^sESa@=A~o#ovE7#9ILMmiy*ej&LnepA6h{2dZ*pic zkpF%pCDnqF{O4n0Vh|$cUq1)F5q6s#{_n5hFtM_}EoJ`iN2Xhf6#scB4lXVS^1ts; zQIUZv{`aFC`v3KnA^k;nudW**q_Yy80NUpZc-UKI~_VJa{RA_ zMos@+2!qSU1P@!{X0XIPA;(Of*AMLw*E98QD{AA;4DlNkW*w&ICp!#wIiF&w913&~ zFA|>9y>nj*=OZ=!*Ct5SQETqOWJGMr(zuoSo@^)mO1$zRh9}DVFwzY28x3YGwkP=) zMHYm0S#??|{aMCO7|2bKI#-F)%oh26|J~(TChk8b=%GjLkRL7N>F>{3NdjrK!KboH zsShH$Zb>jm@S5l|(dNCmZuPr9TW$Qz{V#LxVFK$W>PJh#i7c^}Kk+-@FhA`I!);VA zbs>Sa%VZd|_PeEe_5TX#>GDa{|JRy5QCsg3W7In2=2ZU?nuv(nrz3_F>mQFYf4~3F z&m?A|ekP2qKQSaxu96Lh%s26gB0q)5uA%rumt3${Ki3E4D$19h6=X{P91*TG$_^Ho z))Bb_p&g|Sw>jnH@S}Q$r7pNfd{;Q?X+OS{r}SX|`*hY1`QYK1l-A34ZGOpkHNP&B z4@tBT0v+xhulzSVUX7$mCf+X{JDczKpckDrXvl4P&16K}C$({rAy^P_@_ ze|(8m{qFIq!1iR=SgAL%zegl@-ekR`sPx{;Vk1|b$DoV zy1pUZm)r22%6MFt!v@MrtPg&FF&w&)QCM>K-KcCTbee5kzbSB@Yj#!B(#VrCF-rNz zsYx|Z-Y!R~5`Bk8=&l->bBpIruJH#isKckviA?hE*oK2#rW+hGCiZ!W;V)LdjvH>j z_|;F+J$bnhcymXMGNrAi%gkC|7WT+t;xq3o)<1{O+WhyaSSA`vYW|5NiDd2RBu0&n zNhB;v3Q3}g&~n|%MWgd9ez+X>^($J4c%~GYh^uEsizAsgD>m%vcI zcd`&@R%O;v6{m!Wz_Y{|#pX3`W(>t9(!CC*Ve>G_FJx9=_5 zt-Z6=JnSOk)}+#V51%DAvhM%zTo{;d^Bvz0ytyi2O_3bR;LR`#I8$_p9<-FBOcG=) z5PCjW+Ms}&``&YBFbtRM7w|~K>V}({1_yiUX?aQC<5#IkVXoG)OuL!wm-~;$rR~Q! zj;JK*g6^7$G=rc$l?G{N&to zB=Axe%q)y5(>7#r{hH1Vqc30OooRia`>7;}kn@)!WBGDFxPm5^-Z-~IhuAf;6PLOp z%WW=+#ymkZY;9Eu`88@oa?NY6bIW*zC<}%*!hIi#xmJkJt6pBud$|2|Oj^R3+!?!n zq{|_^)zqtvkMNK)^%`r(j<1RHZ}`oLO#e|~MkJ9s?n_Ouv)r3A#aWJ8Wo=A@!z9wq zxnKA7BZu^f4P)4?epVIMvA9jY&F~>A>#EJ?jeo@rD*Gj+}z5Z6B=^0uh2YoRoT+D;$O&4^L_Tu)MJI(XDbIAOs zKT%G4-F@l$h>Hcm@M(;xIN)+mc^sQ@b647xMuNyhgUOfRB<>yb@0(VjAXqk zVtjYEd-onEG*m)7WKnrmYPlpYKs%&Ys`2>`WE>Wydgu#3Zer!XuF}(Ce4c=aS$ZSl z7W_ZC-BbqpX&3%Kxxa_&!Mqo(qR3^yVbW{Teshu7D_eTS>E|e;{Nr=P%M?n~aB)qA zHa9`0W7_w3;V#<$#ST4O9LOkkEtul}Wd2i}7|1d%Ih^Ew-Xj%)i19*Kg#Qn;h)Mtn zD^~_e@jr-SndSc%k0X5NG^^|O`!gp9+ZiCysMSCH^6U4PH#4Qq%`aBt=h}Sr929Gw zez|8iQW!n4&vWNq)UP4-{Xs5fP94LHSjus%w#APaNe}H523|`1Tm0E%l}Y_&|Ef+Bqb&N+ z&6mRT_b=C&o17QY0m89!NYTQc9V~ug*d1b%r#(_aHFQzxeu{P#ge6`!rD0l2Yg71+ z*2cW0)FbsHT_EZD?eoRJ<`sO2$LZYbi+5^0wq~An__`0KaoN7V(|b$WtQOy~JeG=g z!jSn#t9y#;&t5y8oz7!Xn?dq{H^SA~(t)NMacBr6yj<6CNct56uYh&b#4gEflTqLe zt@qZWB(uQrd-t3>t{Ok=_0rS@-UL)eidbz-RB9KgQ8di8`}-O+I%XLPp)VMKF!0Ur zn#okc>7(-HQHFkdMneRhRbLDNeZ?ajerj@f4;crN`E98HS|4i$uTh3;M2)#@lJs>= zV;iP;A&APUU={X~y7m(loZtnchRh&8>510}KK-0{akAsk#tO?4*DKUvueA8+#_cGI zHhIrR2|k?tezU)lVTL>g>4crf@LeLv?ncKXc&N+)y8#I2SHq-f ziefBf*>S`jn$%SP%c<6sXfiE^fYbceABCzZW2&4v7Tpo5wU(d8PQ0p3+Z+*iH{Hpt==^EKFyCo9F>8wke0erLLj^ULRW zb9&rEuS}aw)bF%LD1@LMET<_y?FSe((QV4JhD-4G91)o;`M zXt8ShaXkF1QE@*r7=N>K{Q`z_)q`Ksts{d zk&VzzYHMSrXqzK@hnqAm=IOdZ~2T#k;#I0}roT6uXfTl1WbPHo_ z9~3xja3surnj$+IGNhA6!csAG8nw16xoh;)+aB+5vW(1KjNv%+RkC+Yhqbq8cAZrp zA)7i1*&Pupw|eeW%`b%GQ-Q0oYtmvnOyBUzX*2NVBG2hfw@~cPV?Nujv<+rxyFbz% z+G&gW9#`12ym@(FJtbCz3_g&|bTBqE(L~{L{;tvdmf1#ulHHvD3-` z>bQy&d$(hdI2=fVPJUbkSTrd!Z~I;TBch8EQMV{=6MLtE+i1tQ!#VYhfoF<^UamzC|8Zrs*eQS5(h&43Uhq6BsR)#9YcU#<|CH$Uk z^<}M<=~NC)Met$D1(v&JV?c}OF8WLIm^U7rW89--ffj{^W)-F1p_pb6nblA!CGHOm zTy%gIz4*HSDWQT&f~cR1G(bcR?)Zk~VQ8q+q*OU3Vk`hj-#A2N>LvShIJfdBYIDBL z2$x;m`vM$VgDID!&tXlpe$YkeyYY`Z(gL<9R2Y^{s6er;$L_uVYrVEr?j#8|&a_JiW}Y4?g-Y@Ic==-xm~8%h%TK?G zjkKQ~5v<${4w5@2*MC0E`F+LgQw)WZfdeu8XjjQz9h5cm{wF4&Q2MHnRzHng@Mj;X z$#;MMvAe-*W$2HM%G@~tOQ7vlGsFg<#-E-0N@M&{hP`)ciJkh)*) zC1#!rg<_yv{}d(taVt*aB?52SGx5#T_92G9oLsOB{Ut_VGz3RbJ?CREi-TS``|&KK z(>E8xwwzn!d3mOreMe=$(YT)4y`w&jU<_0>L(ZWk1BxKKq3h7Ycf-%J9y#c;LXW0x z^Ek7@KT}3Z*dG8mB zsVF?jGyCLAT5g}5_0C-H=CW&jA|;9xX4oGn^EnEP=|CPyX)q7I$haJOs~A7pNZAQM$9 z*uxwM71QK9Q%xs|W3oVcnHE@0EV?-y)togIPK`WWiewnuukN@;7GKjfJT~h-d1gQK z6;~sD{kAr2>G{#QcE3oUUTZl5k9uvV&DLb1iAL^oh=C$SfYq+=M41k|djm9Ez4Mw{ zBZ%xq9tHl=ZXF}=Mw=3m1O}K*VL5z1s4W(V#b3^l2M)!DGz3t5y=QpLeh2e*UBT|h zzLzAvv_$DODZzC5o94~0do@EeFOHelMikXoFjOdO{f1}1%I(Zi^Yf6~ZB5yY&T{D) zhG$5|V?PuFB``J*hlc+rjwi8+#Egm9H=P*>yabvA&Q`lQR=>{17$?Fk4jkI48&tJP za5Pqfk+5~^(*;zMbkX`&z`~K`DslBxz^kfF>|K+}$v0imWyURTWv{5maz>=7#GKoX z(hs+0^&AXv3ro+}*d4qvRME?SnJLKga z$y;J&eV-EI+iG!`tWtAa<`wbUef#=1kwv%@<*0%yx(v4B2vhZ@paupflJP;U6Ri4y zc0okLT<`&PJe(w`oPvnS%$1KL=ceJl6IUA z`q zR&TvY`t2lp6g#|~aain_ARdIKEX+x=Bo?i&+vtVKA{g#Pc(fSt!rAWW<^ znW`|0^+)RyOU+$Uvgiver7t2k^|A?AuOt7WT~N7MJXS{xQf!u7laQ)B|Iu1hMfr+b zPW_Cz2hKN6H0_;unYbC2*l9@#4L1y)uCs}C`}n}Ph@PDin~1(b<8E^2zpISI8cb}5 z=CMG4c3_twL-nmParYiMHp#Xz{w)vn_(My(!o^049!2PhXjG9IN0k-DgTwq^L^F7IC%A5_3nsd;Y_a=O;Qnjh17E0zx@~em#Ud zlbIUiP=Igiz7^PNa_Tf1PlZ_pJ1sK|8hB*KnFb0fy?$rMW_JBSyV00>RJrcg0INeI zcZAjN*gAg7b0LhSL%KJQ9E1jv9~n1R3urf)nrxXcqwTonFBcVA?F1JmWayNn!Kw>| zXa$YNo=>UMar97XWQ#CGld@?Ki_$V{WS88z_;T-qy0mM!7CHQ6`-e_4-t3-^rX)Co zn9mU7v|I&DJ=q?I@j9Ewm3=q=I2cp5hx(obUrFXEgP*I#>hvFfKBJz%H8xJex|)|8 zlhcR6Cq)4Ttr1pFW5?`F@8IvzKF7Y{?KrPny0B^NT)mw~MS80d{$cpN#==AYMM1r{ zD!ASJ^`H98s$aopAsSkXXUB8`N|K)Sk?kGU51%&nzZN9Y#39ST!Gwn6yP-%f6Md{B zp}fFr?;~$oKJy^by>JDjrP z_hI-Ax?UVRwY*$Q zrj_)8`8)fauayWmPVw2zHP^mAk1Ic8qIot^VIc5)P6Qx)!V>6vG}BqNG{`{xuoRb3 z)AMm342*x44GL}vU}k1cq?{lJQjV7c*+mnB{6-K1d4ZjauSgN?bgBl+PZXAtS0a%P z@EZUzAFzQ+^L__Us6|}f8r~#GUnjm1cD6rZTwnL+Z97a(=1rgvSIVi-dU|=fw|;ZMO?ha(^lLlJ{>!K)n_qC0 z_~*||LwW1+Iv}AMaywDE>O_kNRgU14Rp9lgW3iz zA)sblh{oj@2@#h^KX>i|*YDO7Px`KSk$YwHBR3_&s+}MP*$;g$`(!|mqq^`(UayOU zmMnC|=k~hz1QlXE#re0&_vCOkgZ)B*fZk`_?&u`saOhr9Y1hhWTrX|GYNy3W{v=vA zzjGH2^ypKayLOE}XE%RAQ0bt~+o+{XdIt4u>Inp%j0Q*tPsCpSd5gZV&~bJAW>yEo zp9i@+LlY;eRE7t)`HEn;)A!#^Ga_eRZaaw-V@tgOW&gr$9oP~i2$$?WOlQhZ@{uTQ zi`O2aP(4dqDS^K7=r$3kKAI!#nTWBW*XMhlU`w4#{(Zrt#a3B%A zyn)vW&=r=hHPqhJ63*k+wPE3R=N-#)7U&DD@BGrLZ!~d2td}?isuoSIt0X1cu=#HL zjrezBH_pn;ElSFm&#oVByUb3#XJId&{l#T$9FzWlSK4vPhUNtuf(-8T{wPfA9(3p`@=4TTrfK;}u~S=1Y+&-T4FnRM#%0Eob-YG8yOjhDUriCzymchz*Wgya z<$=QjJ?g71A3?|ym1$L`w+?^xpO1Z56)BFe2lap5v+vB6HlIp&03y@AI)3|ScYkH5 zA)TT?iuUyC>SV!iC}zH72zk6UTmEORr9N3V^Ip`=8s2;q@(cD&(!C=Z)qo+7&=aI# zPJ|G2W%Fv*?av3F>OJY&g+MbS?ba88Rkyb%r&sZ2 zPeLeYoSdSH=`kY8Y&4}9nkDI38dn`#_SMdij|#GP1xex3&eDiRcgNV%IrZH493##2 zUbNuoC_>nfTDF{l*O#QcrV{X=oF4T`!-m4AUtS|!{A=<-weMR>>E}vJAuTKCK7lP> zp!hf~#UkZt+4Y}*OOkPW;ly-0U$wN?N8?U!+Q&Z${Z`e2VG@2QnU8{OPFX3}S{yX4 zxAlGfnK3k3UaQ%DHQo4Qkr#cG{cx7qiEh?t+_1WQHtyUd*XeW0Zg}a8@42SkXiL$c z!r*Jc*oSsU#p~TuiLRmC;w_3r=1G^@2uD|gs|&pGo9$iC!fl#{BA*ZfWqQ|y{L z+e!njAPHolcKzUwGPJ>Np&C*^l!twpmmu{9dA?^LhcyvIbgo)C=}uglwnvX}bvuKN+G<=QOT$7UN}+kWK`_0G=t z$hfQxnN>}hpKVu=+es96Hm<9~u1;rf4J5L?sr<2(!<1AU`Q&2L=*au~tk0t7pOfy4 z@%`Q_TecUC+558#RO36;jYVsDfhD~zz84qDccUSG#S7G88azK6LS2N;P253~0GFdc zip3jqAZ#dk)@m&BBGj+0uiY7du*M2VU#GupfMTRD0x$Vx=WevU_t9~8GNXkhwb&BN zxX1DJTGN-DjvBv%gPq1k`tks2Yomz8&H2D*g?pLk!=HeQP1jTlJ2^R6iJP@PkF4C< zUd2E_pvi@eu5 zNS4g7cB?BM0y~nph)Y+;AnMf7`b(Cw&GH{BvQ_TX*VV%D@1)T47{+eC=i$?n(X$8inQG(+ zjkHFSvL_w+YEI9f8jq4**=$2_-QW~qrO`3a1Nw-CuAZT7()tn_2yMcnhF48g?kmA; zz9fl{oY02-Ox&B;8k)Ya4V<-kb38TUWA0mOT%X(eB;vC{+L)^`du!*7>v7AB$FGsSlbtQ8f&nCkMBnMYe*>l-1Ku&m_OvIIz$vjx#9Vq@D7z)i_1ssC;k^JQEz* zA_nmX9>Rp&l?)w5uM<`Mym(taeBuoI7i&kIoNT49 zMWO^|I1e6jAkiaB#FKo?`{=P}kNt_^(vEYL>B5_mJe+0$k3fj)FFki13h3t7?4knP z2z|#*!+;Ax7J~>!^`RkVnSNV{&(=30=#kO^R^!pcj-i$JS57A zoME#eNm!C*LKlOu;<_MSeH6r3HGC~F*A({~4K#f1 z`NGw`q@=L2z}8YXaO<63$y2U5^@L61r{av%$LAEL@OR5o!Zw#ge0q5EKwVmmvdBz=vu$r_(`rkEO_2_mbD zS1Varbfu(WH$>ZkBEJRhLx|OS0e| zy*{-2asHAEP~dCM9A0rND{qdG9hq{Guh{+Rq9Rt8dm9=|qB9jJ1j=0MZYT6X_Ys+5 z_Ouq%3Dl1Q5?5j!`6QGNS#(y;R?TXnks_|kr5$&>VJcV0J|L)DV--9|e6W|uRjQ`P+U(1$yUtL@rbJcoM9bS zz|lF8&*wjIPS@M&P0K3B(|-2}9YP5ufPh0gUk(#qN*n$|zU=A5`<-?!pn*t7wQD5v zZ~ZrHxAAe>qs#D34X+8G?WZkGDQA%U9s_sK;w~;2KCeFd_N7I4V|0Dt2ToM@gsZQ zFSA0ml^g#Ytzq->3vf{iE?uY2y@a<7%F&0&;a_n}cJu>dAPNI+pWsh~+uBY`!q<5f z;pV$fjkd-vOwv}8nzZ=sMvD?Edq-dKrmM||D2@xoi0R^h!`z~#X3)o`eo&eaTBgz; zCY$tZj_^^i9}kk)ln`nTUANEg$JP*<$W$G|>bTG!kAluu4PtM73G9 zKn7B;x{7{b`BQ8|19LrSet2&+OtJ=Co{qftbgmSJl>^Z<=w$KxkD8lqeK5zDkIWr8eiVH*y-l>#rSa;?6P-o4z^sdKU>^nDi|?7Qt=Tu3c;98$*Z1J|Nw16?CObE+C^lTxH> zJ}`I}dQlG%*_1KYIsRxu<{<_}0Y4KPO75&UKITm}?t!@%wnabW)63Muj#pMtZT=m7 zBwyKR98gJj{c0;C)Xa_IRAE_cawf2|d(H}Q4y@eABK}pNXU=t74fZ5Q4DR0>L&f{R zVWJ|*sxRJ-r5!_{T_uTGz;1-qolVF3+dZ4-SNlV}$wE$s)KY%U5&@2BT*S(lc;t!a zM;ppXDnN6T+U|d$wl&jW11d-eO9kjq&OE!FXhtXQkqSC$<*Q;26WmTcgCUssV>h3s zz|p>&$B{bwMaDK&te%AsXcMsRUxY=O0Ckm3DJCe7Q8gIq062CX9#ZxLvV?YiTR{#c zI`ITY7oa3>QV`?a?QBGT+kxn*s08P@tq4~L8}zK;Re+a*Kf?gI0SJ!IbY2h0;jE2I zn$U0p4IBs#yik zTmjY4q!NqF0*Xli5~;Ka7Pp;w$+WgGF|F3-k&kd((Bwzfz3UWS@MEcNKetbf)j;*; z0QtfOdb_nipQwz>nC2{rZW!CRgWKh)>-Y&uS0f})LHp5@ zcYCAb=6ciz{a-8-imv%M3wQ%a3^Egy#yOCF3?M=01NI0suRRxAv|ve75z-)nzhMju zxY!bg?{J!a@Infuwdn_|`>f`8!Y0V<<*xt{KNEGac=O?Mf5>gI^A=m8S}F$+_BEn=jd-IvW&^uAG;9qU%6wud;6tbevNa}!dTcjb zgk4V*iGa(Z3|r&hj&1w(xdXM>%Tfq)9^fS(J>|{Q$d%w6NMX-#oUWTb-!oivji(jW zZrC~lBDQhcS!gNdy?>S3fc4`egAd{4wVC1B9ucTm(M~@^yQz#^%u8w)?6rL#=7Yq*{4oyh$Wh3YGA8|adYCZ zSi4P!_JtF0`So@Hbyel0*f`-0l@7^Puyq$4nskQQ@)BsQyaC}|q?soLt%99`eqH(I z{jr?$qe-*zcQQDF5)b;t#yYxEWvmS>K3}`*x40F3I2?IwKgeXtRb$bO1;@ZQFasJ5 zxIfxYKu)Cr8J_6|E^s>(U4jmpKVdF2(S?5x46hA%vU5!(qEr~K;EklIYL2eS%g$$? zC!r-4g53dTiaEls`;bm)|Du*+sud`HX=FSw86y|TLABXOHKpl*=&y$~j94lZ)V|s} zd&Zb<_)YSZ6zO!;@saAB)`}K%7iB>}MW`J<$p7gpJ-NE`Y-1&gHk7=tu2}&sh}fKK z(J|`AyCxE-1)A4t1#){OrgD588m3CdmP5|C(hN+di1MlsanJ42@@mAC___g#j5`Xv z*lI%QEROWK;K;&rG*cb*Cp}hp6#o!#;WAs99-EIkYZfwsR{{HWch@E|$F|_)xmyk6(MQZ?o`i-NH1D>%DuEQdj$IL5T|9?8eY8enq_k(FMc`*WLIt$gZ)e zYRXra&lyQV^7jYK3d5E%tCx$yqCu2<3<3tz0d~k5=%E`X^#A!@Fm8)Cx?+4w=O@s; z6+91Jptgo6_Vvcmq>)36n`>T+VMDEnW=iqLD+~nLqWKyK^^P%0--N$n!{Ih@WYWPK zv74%~KxUrDP;iY|@t@N&;S(G+ZVEQJe3G%&wP!x|1$3L)(&n?9A#rGc&16s6G5{3_MoUU8n!uJ{rd7JpS zUO#FdLykS((p4>sOa$O#_0LJthLTl}xy>TnyRHj-whiKQ>@qtWfFTp}eo=3LoHZOqe!I2bp@kYq$ zbt~yxK-9h%Yn^I}?5QgO3?OK>6|aw#734BlQ=AiT%{J*JsOFL4v_u4`ll5FPRcYOg z`P)^Xkm1v$Vt7vO$`J$H6f4Visj+wf|Wol81(wyd6q?eaQ!F{PQqu*Xn7dp)7l>ba?C%zXs zi#XSrG8@4pyDR)W8+i~GvUU2rZzttSWL<3OIMWh4ICh6@tmieqRRpOSv3#?p$xqIytuQ{` z<(fkH%M@&T{9&)w_16NF!UfX#ids;~|J#-mKT}nm|AmL$bX}3=1L4OiBB2kxvn`qy z%9vSGKWa#QC7#{Ue}kKSq`YKeO+)q~h`SxopwD;?LNF|>ji<~g^AgQ}#+9A}aSxp2 z1zmQ3P^#>)6-P)4MW!3J-64>=a-QAhRGRzSUqhmWw)Cnr88^G+Psm3(@V$v4p0p66 z;HMF}6>LW@GV7?z7mi^&0IE|BIkK^swXrgt)N-#Z5^`sy-;q~r=eW2+fOpG&7Mk7a zcUGt7@=Y*Jj>4K#^5C-|QUdpvaJyNQ?LX&to6n5u;F&09Vlzg48IJ3nr#d9{q=d_8 z$#`{mBQaqQmL6^q8Te%%E6d$+R!9qYB<`1i=uP=P)}*xrV!2*2o;z;>ttjG%R1;OE zBOod+c#N*t;3>;upNpBFV(PuXi+tq}g`tk|@`E8cF5Rvq^@Gvt#3!HZ0$Im)m0%Vf zH=nZv8@X1)AwVyj2#k#^U(Ir#@hJsy4wMy%i{vuPgy2yjTYZ2xguFs{=ifG9IK`SUaU?XFnmD_QXmI11jmDz50fu-R8(~r z*pR8J+Yw^<)a4VibJZVmH5Aw-y|4akhKo8vP~;2~3KkZ2n&3hO@3&M>WW4ow`tnE_+RvO`bWBg^;pq&>m%k5l)>bWYTF|u;i7V=HtwZs-n=J&_HEbFd)=XGm7BwCGHl#G929GL& zfEpoCPDm$Kc$8=!!VLkB>bVIkFO}P>Kw-WG$g(d;4j|**0`Q^efofbw*c8~AoN?$h zjMezhXi36r^t%tPR{fN!?coXSCf%||M22L{S23HxhY~gR$ zA08F-3SzCx)Ez_IiF#5b>PekxQ(Zhm=KzbYLxLnQ82m)G5)wO!pCj<7(1(DoPy+bW z{;YF{U0cuOKQ6`0_=BMV*=4aBe2Rr~gnQuhmTp&JNj&?;SVbIwuCE;B+ zA&(v>wMBG6_0$$XTa=f*b|HnIZgUvEE4|zayh#CSa+wXbYv5SuF-T%`y_;_GPM4`* z#`%x`USM|TSOqHBJA_jK1z?74p1-b;YwUh3{eirMny7O2X*13I~}60_lD5 zTTL5i#U!}frRAvq9;_UJ#x2$$l>M>l%T$_Ox93FNMH{u?f9Gu#PS`8X1<{#gU zxV%1&tboYLrMZy67XmISlVSZ)l5W4ECLUj6g7TLf&V*HhM*45hU&0E&K+RVGVfutm z7rshFoy`!kQvjDBvo*9L3OuWCD>6)Ai4o~ye7;^@4S^m35r=(SPu@Q^3^B)J#EXyU zE((pl__w3s>S-0MM=}I_Gt@=(+j+7WtaX^m@z{T>nCk-}4Y&ZLGF`GTaNa{gD@5$j zsGEPTq=GE}I0|BNaVPG6+Uo@V5hk(<`sp*t6kxTULEnt)tfM&*fj8G9)n?L0zVjcv zA)Ax9MADh4mrYXGwVm64~U%E8h;htH03>^y)QWQNBIBk&>@5~PyLn{qSn zBPUBM6~^n}9rxk|{TMEWC1UD+00f=547zpp%I;v+!Z3k?(vXO^hQ;nCR{#XH)e7Sl zZ6iw|3fDY~ZmGoWA7TSFOc-(xA_#nx=L4InD}U7c+S-lRg;xSeYq`qLeEN0w#t-xS z!CYvF?SXvx$anP1Tv`cg($pTH)_kX(;gC8+#WB_m~r(q zPWTx0z;e)dm+G`bDWQ*H5BPf7aOAv_2U;D`)}%!ht-^I-7dX`B>tCbK zgnZ?J_)IGDM$G!#ETm?x75`5=SPXd zQuNL=-LgZ$(mdi;9vgyp$FnulsJjIoXWJZ58u5OXs`#2sJyXj@jdbB{-b;C1 zscXv_hT}5ENaxW$MG&XD0!OWd+g= zWWU%Ry$P)CXu@cHSpqe3vjs|etfGn#-o=`SWN zcg87!lHj4s@jKti_;p6dfiAoKJ>`NT#e?6CIg?X~b_Kb%nXwS{)y@NjxcK9(nW^~& zBKA8g!NT1|Q9KB|h3Ipb^u_StY}@<&f7bY%(U+LLpj)9_#t_Ai4f%xn^R<3h% zEOMgK2)Sz4!E(0LlOM4ma94@M2qtHLD+_!sxLS;m`UOPtH{Y-!EX+ zJFVtEH%nlUP6rWD4OG1FEy%LyREFL6u2!P5K-<@6gWtjNf%y+WR1gzwX1Cu|*+e!N zjH-l(){;5A3lPD~wQY`tTwN(FeqMby0J@H$M|TNq!HdV=U-?eAV=#GK99!H^69xcc zCO@#M_KWBG)Pzfp7NK)vH2~IXGwAXD_RxR6&rB!0gJ-7 zW+m!y<9g*qKm2G1<2p=WVz1&es^VwbM%cn+wX+($TH~d*oI#CYNW>JD=n{z-RB+v2 zguqqw^X^lYV)U4Y`@~ytBVT?D;v4-)#`2E2F&gre?)*LnQcl`M03&?-%jv~p>=yn% zz^s|**k(7!?)UPV*gwW1ih-nH*5PP%;|z1ntzhL^i2xJ1U7R{R{A%7zS}O}%8%{Ea zY{v&ul-u;x)PXF14gMBLs^VLgVvMdtz!Y|)N?^#T@F+8*)qMlRP+VV^{2&lvBc5!| zG(7fw8s>$im`3?th&SA{< zae7pWk2aQ*@(Y8_)Xt9n-WO{MC9CUrbIDc31Lb?i*vuN6Mo*i6Oh+0hqzNz7;;$y8 zecU+`0AC3?yT){QfgfQgb$)Zg5-vC}OZ?MUewRmT)9&ZRYXw?+BY=8$;6QTc?_|!OA80C} zp;tdLeNk}IB?aQSg>9R9l3c{__l4j|V(dG>jIYA>em>5U3l98hb)jEm&gZp~rWdkr z6?m4&_MY#H=DuREAM*=g0Cnv1G`1H5_%|islikzD;RKj?9%tJW@%8CJOnZ5 zz4!=lE(CyR&o6ZYeS>^##k3O=ZYbt%PSj^4m~FF@%*RwrJJ^N6TxS@fpDdyVWmEu0 zN?(k(Gw)6d1&m_aL8pTX;4(On+49g83E=0zhj&;q5qOV~sKF3a3!U#64W3LyK=`y^qTo(>gX;*^Gq232NYNZ{)!K?@ zK3e>wA@^G__+1wA%0|%fICVb>DP^*jnySiD_>IOTE+x-mMzM>{% zeB?qw=j3s_-`TJ41`~SlZg3(AH3N9qqW?QyI zOQFhZ7!S6CZ(V{GG2Hz6@=VRrajHgk16K-|zncsiev%2$ts{CKNnk8;DP?D{O@5GMvk2=Yi=Uz(278 z3D$&U`gKfSi@92k1pH1In3Onac-~rw(oiC+S?EUkc84E?$C@M_>L#bE# z&u@BZA~qr|7aQU$5rcX=45sp)ifO!rei9_`A=}S2lD5VTs%E*OUNuYSO2Cj3U2xdh zdi`>A>G@kD;iHba!pH1;rd}V9MH+bwt()7SUd%|pJp?h=Q2;N1lp-7lF|F6F5nEr)|#y0tpLO7O?$J*UfJh!K*OtICO$# z-H=oYLR(|-mE`FdXfJ-8@nEFS zE&C^r=g$1mz`&a{E53n92cqs!!{_~UKMa)4oSv=HJMYXtg?XR#4%`$iN|{{sQIn z8>aoPSVX$*gD7I%aeL|1bUFr=wAVx^CC*VNP~w2@M?8acmGuA^bRtk3?_&t$233O2 zQ09Y^F&)hTFvbj{dFVK$HSgW$#=RQ!068Cct&C*Jk$mkNXW2E9RP(7@k9kCP(A?)zgHH7 z=6_k%1)v*u-5(6LEkDA+4>WTj`L>9#OY#{RadF8{Ujh2^h`~dXM_!{y^+uuHEO1CD zSNz86?DuLZ7=}g0WO%cRYZ%Ttcq+{GrU1esKhv|tZN<9x6?NUqHEnq)yig@cWm=vB z0@E^R1Y^%hR~IMcvlW1kqluFNEJAzNCs82vDhV4$QKMeD65iH;+qXXh?GPxsIs3}JfwREgPvF;>;TR9L%BRuA{)D>>i8Fb73bFMVcLc*}b z!K-9>vG384{s%bqU}{hI$8SJj!>vxGj}e3PuWSH+i3OC_Gl@Za%b#@g;NfrI06FvP z2hp#%=_K@6zEeE|eheVeRHwres3LR)%;Sp!dEOtO90mH)SD*oZj`IkL=~5FS_z9nq z`p-d_N)>K|IQywBZG1!k`Fx5VO5JWy&!Z}lKJwU3O@gQfSjx?uK zu934?KAuKcqsruc@it8|L6$LU0&i&7XI+3`2Y+2_I!AHZ7z6nUh#Dz5DC}1DoxX=rf74npD#|oSMYucoxqMp$(MVmN8zNibaAXgS-fq8Tr|=nwtVz zJ!P)eq04*buNhgj-g|8Q0<)jM9e6t~wd<@05DgVT6omGRij{PmD&$TA14>2kxDC~k zTI#~AR4zo(x{?=t@f8m)QY3fUPIAYpOpN|NSpW_T1~b^m`c07+bOazD0-<9JD(7J4 zk(fmxr9vyHVdYH=$r)z;%;f;>u<^Cw@mm*Bfx^v?sd5+is=!y~*tcmIK^nJ#_7k%g3Lqp5%5B{r ztCx#|SWB+~@>6+$VJ=d#-wml#5}#~?##{p0n{L;a-s6$8OlWmUjG;h~QC9Z>^fnp4 zyb;#3I?k5#)s@Tz9d~=l3GPw?YJq;B#7NZwf06qHmS0S9dj{k=7>(l8o<87aNx>wC zA!F`je-aCPmR>zY0le2zc3aks>E}>@J#*avAEw}x7R&%NKxwx=N>;%Hfze2y1DIxw zlkC6Ob+_tmWEmi<++$(1#>!OipM42>%-DJ>-L3tJBf-Cd?~dRXY%mt!pTyZkpphcM zRP?&YEd)WbNrxpPUM={CC^pvjK>e&gaQ|Y>^Z3_ro|#SZx{S|KW3whsxoMlvv;xKH zuM|zz7r#HN2`%x?beh8Q+bMI|Cu)h*X>Nn>mqSz%ZjwN{;n3ksipC74aQqi|{F^g& z(5o%@Sc{qvgQKV&gDT0J3?L%sE+gp5lm7wA0EFKfo9?83dch@!8S?)y_LX5#wd=nK zC?QhPh%kgS2#OL?BOoa?Lw6~mAPUk*N|&TT$1s#q0#X7>z9I-H7&Hi|gp}mD7ry)a z_c_=3aK7z#Uox|1t!F*YegEp#IgQPsE04m1auNEZ$Qq=$oqYAkHN7~a! z9?RcS*P~1VT=ML=2!B{E3Q#1O(PNQT;lg$doZo1kJrths zSRoPR8A%<4L)zG8H>(+gWDGjnj2#P>CcSj*2Sp^)O$;wqex z@PTKbR)r1UM+f80?m&a>>f$%8Eu|AOI&U>9g_M%?N5w{MNI$7E)=e$*N?&B0$Pc!Le}ujTi=;FaJN^Kychc*OyC&S^EF@bk&v|Tl-&^OElR>-Df2V zaGXe|z*A?-^2u$MgB+<2S6K8g$4|i3{ymc3x3fW!8&4xa3x)_sC3^Uk4|@h*h+>w& zVDa>!;NQK77sQK;cWFgHY~KjyJnc>#KbIQ~Wv&V7L*I7&@-=;j3HY7`fc6*Uw6-fM4LudnVbJ3LP^8{uI0WY?l7wdSL_U zEz{GE%gmd*GIE)hR8s?GN8S3yUpW6J{I^Y`R_Pa|rYYT`I=o=?S*Y#1>~lDg!sWS! zYAX!NOo|;Jq*Hzu1q3Na>14a)%8umKtj&kHZAc76HqIv01uPgg=h3J>PCQc%Jsp-J zPz86(5<&RFhIOs>p(8dCC8LL90w6v38%{;tH>42RWOLpIPPcGg_|KIap;Mb-C6d-V z#)k*{HD_tbt;WU?CsAcNk~YB>C7{xELYY2<=B^G#>-eE$4n2tiF5BXFO!!jMj=m65j1B?Qatg?i99s1z_K9lMHc@b-yVJuk4@<|40 zv}6p+?e+I#fu#~dUxE*dNe4T~BxuUT_Ly^;{mokf%*~HK2ja(sitNM@1kwQweM|zh zizm3|;3s;~zQAIvpV$+hL;LTJ!IEj*o{AO+*K*lIVip9~qMia@4*a-pGRU96iI4n= zE(Vs7nt#g$!qZ+&SD%3!r5DkruwHU`@1vRxSRHuM251D8h5@E#Iu~OVg|Bt35%bgB z9C&r(#=;k|xecaoovjB=Gi3%^r#fwXDZGmA>nPJ7v&bn|&m+{@$W||{!d>Awb0+;akH)7$GYyyY7yjDOlw@v`p)c zfk!4McytL}V6~Y#PK_11B5bdX@3xN$*e%6-S-sjT16@ zuCRnU2tIn|9mEh;WT6m5%QRS|-7k0{<4o5hVC|iRr$kp+cmc|Fra^zPhM*;<$AA8! z`c%-VQ=?TikG`*(`hW?k}0{G|{XcTE)c+snFt<#5Pbm1$h1v(yOmjE!L~E zyrn?o-z?1^vFrU?t4xtID5MSEK}X>!4UQrXLKJai{p%a~aGJqwiUw`K1^pmu(FaF# z9cMF%vGdU?D8LnXfMJv?BkVqijj3n~swCnPOK`<(=a2Tgh>%!muG zbEXO^8Ykv7c9qn(Q2ZB;A<-E~r)3`@u=ijN4oVPToK};gV7;X2KGTJQ9H(SRQW6vk z>#b^mP!xfZLilM;O^BT4s~of~dapch)dN?&c)ue9ha~LO(#gsn3Jq2lkGK(BkWb>K zk#bjBdj9-oq7mgzS)z1}(OJk@8V^)9sfNsmn#~0&MsU7kUN|^-EMM29XZz&f_CWI9 zcOAf$iNuRnnA?)&&)$1T)rD`{Ro^4BFmjo!bj4c6~1oztr=#hOS3mwNa@^1yPY zDr6y$P?>yAm#g!A>A@^|_3&WC-m6L0x3rf{S_ktcRHP)~c!$QS?+GV=#dS2dzFrtR zb%K|rG1K_ggoM5DWq3RRA0b!*1&I@bJ`tDyZeNCxSp7q2>PsqdV=rAr5of(!capLi z@7~RCb$70o*~)J$LtU06WGr5@H}}L9!KQ~Vaw~ys&kl)9!&n=WBnd)aUAw_i#vu~p zb`HO}JT7{;zm+u-#oU$u(c<*N7r&L=3*r{%$dAc2Ur1MlyIMP&ZDDH}7GI@A=xC`XpAGRZ@|T=H^{aDsoVH29 zu|SR*#n~%H0PPogN?Q2-l;BAf$YZGw&%>b^7;X;X60I2?Oy_J7{JUw;lg*pbDewIlfvU3ay)?|2Y8~>xI zSicB=3GVQDdaB?hI7{)d4F<5u#&F_SQ)b;hybV<{jW>yL`C%oLb;;Of@;nKNH&?5RTzBer^zQiv*T8U*B5JQwt0uJQJ(5L??Cy^$ zx;BeeINg<~0zSxF?nLhSJ7z89fyNbql;M#OrvEA`;+)FfgBDWXqu?H7C+t1vWEF&x z*(pj7V1`+c1nDZ#8vzLn4W-6LngCY4TaXK07)o~+v} zrZ>NYAP{zRPi1^|Cw^LBhAf2B9WZFbfa8ITkXzTzUsmtXV}ST3MP)h?4X*g z^pih~t}03O2%PzX)IGF&LM|s@IQci2t$)OXcBZRLx202Qg{}n zQxS?aB;iw>Nbd@>Vr`PH18Qeo^PD;-+J;wBEz+mp;~kZRx;{8+hVJts$`PoI(VSNS zqkcdZjw6(O6zQTsU>(M;WPy!OAYG|f*hGaUbA4}TlD`nzVR3uBSr~APH0X(Yprfg= zpgowt~JAYyKjHY?)tj;Lvt2R`p{t1*vAVV$QYa$Um*Tx+Dk0#TLqXd*U%`Ts{#XkbGG+{R-XcJ1m!(Z{p9Et zJt0)+_iPm`SmX+%`(z^x*G?(%O&D`bq#?aHJt%IsM2@qwnRAbv1hbA>NpP& zI19jL(b%vin9me(+kisJ1mvYdOb6EhDZ#Sefo=dz7!$DKzc!<`5k_iU(1}Rt;X3t~ z6fvXPm)nfhEJ@FejBq%-)`d_fDSdk)NI)<`gwWzN$KK^yKP-UL)akJW_@^QJDnQpZ zGgrf$7|QTFt5eDz^a^ID5|qM_-^%7^04Vx+nJgzy&$lFU?BOFq<=Yzl2aGPZ%W>P+ zHkuyKDdv9`GV;`{oNsWBzLDk2dG+lxecRpspO0QPn5Fhe+*VDbeVN}W!^rh@Bn4_9 z)GlqO3=}3hyyUS;*hEfcyY}!?CK~y05IYG>Jd?R^2QA0qCBQ94RJh(N({Hlg*%$$6 zj^8@WRwx0otWuZ=Ag7g`r!^tx_?Zj%+$Z!GKtsfj#V5l7!!c>A%wM+hmJta)IB(gKIWJcj70{4WKHNGV+dX)FhNEHo(s$liI((p&Y zc=b7#ExXU-B)9y#a@+P(irw^;GYRk8tv|fM`BkJ4=s(oS)4V(zV}UBUct~*-zcZy& z#O%*Eu0jDtV{)0;ETndOnf`5PVRhAC8!jwg8@k%c03} zO}HpW1BybrMP|&l7S61`vaFEd4)opVMgsmE%`M($m5TV8a^h2$f53L-BjvFOF4l+^ zB}ja(BY&5j_gtF1)K;qYXls91l)Ly-k8))t^DsZQTJelbnpy zS0PLfaiBOkD`iIu*xBa<&{h7v!$~))EuB6}xEi+moa6)9(onJOD=(FMRW?o^%Y`?V zJ{ppdb*-U`qY&k@*p&2_N4y;;S9oGXCGQs<($KPfDmP-~uf(A}Pe(D>_6V2b*Fc!7 z4v~68Oh~RRUF$vir$6U;`hbI`zQ2mWoO59ItGr$I&v_zti%u$rRrYQ1Y3zE0sG_uZ zfRfa#P$iCV`*u6C51ok0rMv)TMtH!gxChc$N!AubTgMBg!`Km9c!`6-p_x zu$ZyC4-QU9RB)v6r3O=N&9uiry-`Bw#_h)OfynUj^Q>jfh$5@&vd)P#=m>8`Ej3aP z(kGutDRnjwjOZh%L*>#bCBa8hZ2Gc%rh%-Jpsr;*g;#e%clNz_u(NaFaT{EzG7LD3n-&nw+DM@GV1v8Y0I9vCDBwS2M$gttFcsFNvQe zf7KFg)MjmLB>UWw3Jplia^%BLbam>_L>AWO`Uz)_UQ68gM1X8=%)+KM$>R3Cp<3DDqNr~WNfeHxoQqgA;%Z3A&LrHU#w3VR zYj+7;&7$$4@zKoa5Vt>t$ajcaBB3rJ-EH9gi#-`a1%loq45b&(PcWb5E8!@7e&I77 zD_HgrkUBE$vsb)0K>wZs4lVqw8*<#DLbu7`4n>T&8e=udsMbHAz;ALISK3V;0a|i^*-_I{>lm?BIsplQD4(clck2LMfV0^g5qW?PY{aMR z!+f8(2W75$3r7!dLdYwRjsQJ5XDBhT=3%ts82dYsmp2E{_7*(anP$=+i}~WjuR&T- z02DIPs!5C#XfS$jujH_pHhR6Vd-v4%S;4z>vAlfkETrtody7Cg#fWAE0`NaC;M+gc3;b6V^L7C~xR0yL&aJXs-B*=aXJZSoE*$2>!It!zN zsXUzk7c8mCb%&sRZ^$RIpMUoZ+%`~7+5<1_^rtn5DACi86~qhBlk4?TW8-ADs7;AZ zP`o#3K7Qyr+mqtHGND-3c_xNU#^7C+d__&}{K{neVvPKqQxRCwJZLjC9-Y$~+B`$L z640=dNsC5P*>Rz&zzm^ZE5vg_Gw13i+_{D<=pAKcsae#$GGWhkGZhJGa|?7VryND`Hh}ugGNzf zpYpNwPL>Eh(|eA2W2?9*Q!h|z7Fj%^N4fjNRA;Z~$TV)=uu0_4?WLv5WCQ<5nFxI$ zD-fl4gR;e!F#-=LM7zi|uPK2X)GSiW++wnCdp;{r1OQ)BvO8h{dtNC)o=_;4T^kxw zBP|A=4gYZyOoaOT@_Q>G_rAYZJbt^Vw;e>YhER6%*}jd@b)N%*8b3~28to_~jU-JW zS^#0FDowry!0oJr-F}z^$zeL%2_1TTep8s1uk4~)-|>3(NCq|%eMdoPvQ-gE(EbJjFdfT zSeGbN(M&(Dh!_Z+bfF7SY4H4szfA)6aZI|;@%k4oqv8^=2z=r6#gfDKM4M)sKHpqi zOC9YXqEwhB=Lrh(QHjfS`m;9c^yi~xU<#7QZU3OSJ>AE#A9AbgmcKPQF)xWg{J*da zk)B4&o^&XkQ}i)Xp&=Hc^s&gpkWCVHKPyvqeT7wvhqMWC@KQa32I+*06Fcn0LEqJ2 z8E}u3en7xYRHuruUcQ|SoC9tlysM9pTDOi}Rg~C5erV{bY^iATHoEMz z`h+*<1xokDvX|fVGOThgHvNV-PT=>c4^3pKIU-|K(Z&@tw_4a~(M{&!oQVCQmNQcB z&%LDKv1CCi)?1F6r^kiWTv~4~T4q1!`VQImJ^713U#V&zgB%{5>2V#VvlV%iO2f!T zoLUoy^d8lzT~Nr{(jDovkAGQ}&DY*-e@!7?b|whdcHe+6SW|9j@8qzMfSu36hfBz1 zjOz2KCr5CX0L)z+8-A_<2QrznTgW!DeFmiDCydEqdA=Os*OTnD2Q8nWQ7 z^gs`vCtO$_!ntVl@oa?b7pi>f8Rp6=f~ex@=2erN^ahL0o-7U`%6OvXM7f&yumLiZ zbQeS0mQOYzV;v4skCPN|12?O$^ATS+gDk%>H=$(CA!mO$AjQIAk)i!Mz%f#&^pK01 z{rf|T*V2>3#Ef>S{@K*NxG710szHint>@gFDDG-CP(3B7P~26icek&(p9Gss2J+@n zv(r9{24XUr2EGvY^&W@YtO2o|YJ>DoDW62^bo2 zhlY|!PUPamfw!Z%5VZXG{y4KpR{!q1^+Z`y5f8<)=*FYZ)eO&zK|d2Tw^=ymZA+C; zX-Ac>&1Y}Fz)5aRm6^By`!$_h=e!ar>LC2@59}jucINOt_~tvXu3PP<2Elg#3_~rU z!jVU+*CSTdrRpGc{X$2zR2PSx$U@L=B?+M#qlS;9y68Hpz4svC47)aj5^%{fgv!=w z+o?(&1lsh0R5-6O3#zCboVY7;xo{&@0ds153a4>Tu5vV#MxjPQZsJMC4W)xb{+rqT zy62^OxHYwgie?t9laGgg)>Zlw4tRyKcPts|+i6u@3D+I+|!jnO(*DChf;}Hmbh8WgIFs)^FaPI#~wKKQ#RbzQXsOCW*Ge#_Q(YW!vsjrW$Gw|hR}$r4SOQhulQXRwGnFf)2l?tP2@evw}Ogm-~H8dk+6goU6(Qp0|_8h?!cY#$&m7Pub-Xw{uSOW4anjKhz2zR6ukEq`zlBudQjhp`94RtSoo%Y3#&>8&NP7Aax$4 zSD7D?neb3tsm3{)PQ+#3w7#;7JZ zEI+|3Tb3nkdWl~r`vDTPx$$}0<=NrEt~UMXTYpH*Hb?ZF!|`J(%);8G08TD$i0b7> zAjyLO@$V%f4zT_;ALI|bb`&pVW`?x?^AZp~?9cK`WE#ZOig&#UEb=;K-0 zBXK45pOUip_K)yl_93Yg2x=Xd5%V3i%t*s0dHL#Zuk0YHe znaU9aGCqpYU~lW|tt8%{nl_2{A_}E#u7+F23sJLr{+qdYAlnDaOfT2$0SzjUxCT5z zajn0~FsSah0o6vb*@xdIw*qH~p9PSz2W-&8m9nqyN6+-}uYL2?t;!*%qprWN?R--K zQ{(Dt-t4J0Gr+YZ{($5zsC|}wy!V(qT$L6_YBmFR96RV-1X*v%t&qMKn#Dt8# zx?e$yMdCrv$areTPId}`XhHp~Tt8=Q zQ6!ywIo|X}AauPeb=I;b&YztSS~aR&-2UUcx?w+x#z*|DS?^Nh9foNZQ+@kt=X}+! zX>Co*ly$3qZdbXswgvXRbTU_^;at)3p1MQ`M!9mq_g#ePnXlU$|05( zn;~vLIMR0aG5;x+i|&Y zwSW2Z*wqs*UL)%dPOZEq)QA`ZusUVSM`tAUm{Nf z+gskX`A-@}rwuuz-hgUoxGx6WD`0$%7bX!wy3}4t2Cv29B0D%m@u$w`O+CB+ZNP*E zg0wH32XEqz!=y9cRxJBz^|JdYI3<`*6JkhxFr~VdEOAj9lDu4<5r{f z_!54SOxAB(Csr|k(u>-5n_bwnw)&qLj&j(P3pt$04Zj9w@BDhToGjGJc%m>#(T-+$ zK$*T3BkM=w@$1XzIsD2Sr$hUP7cq9rFoMG4`+F3RQG)R-S?Wu}6O=#_>uW(&L#mVY*ZS z%*hztWRbF|eus?wV5Z!En3FL3x#cF#Xme~qtAGXQ5aZowjjz)N{ z6hPj?CDICn7Rfjgjm^GoA{%Kf2z30L=P$_3TJy35~I_LG!e8`s(b{1GXtHN1Y}}~;LR+lyXW*W z(iB5Z6uWcri3YDiY1WI((_jJ|9Dn}!sD6T81ca%YFbJFEr*6cYosxxkdPHZC8L;E{ z1m^@9EbEKI8p6}P)RtBNbu~HV)zbILJh1CdK!qUV8ESwE5|*RJ=JBO(&A$|qM@^c|l%AmG>2BmY!TF9qIQ`CuLyJ+Lbz=t$ntEM# zvc1(#_QgwalBVF5k#l-=BEedf23V@Bue4a0DWfAVC&?93#kGA$?D1_i7}dCmyv*On z0v_7E^TN_AyN)}(6mX9VfI`)5w)d9Qcfs}e$8%e|qFE&`a)>S$bIvmLW^P2SFK_tf z?>@b3TVSVp-+Z{y$=;B)Cj&Ru{ObbtDcjaVj|3VC$7G3ib>9l7@!X`phn)pct;kD}H?W=rFQgF*{ki7y$*a?k_*8UT5`zTs9 zf+}GSMBndV@*TwO|3%i~Pr02jZ1(f6xdM_Q4|zz(!SoY#2K`HNSyNQv-KeRiOEd)i z8&0pDh4cdNf#W9`szKmRg%YOUC`!-*B2RLdYUNEh{|#ybD|p=MZ>?ng{-A#lG~V#Z zQD7U23x0~8<8PLKayj1Y(c)5tvioc$gV}iV*Rgp`OwH|E!i8}QA!B63MY-f*AB0!g!U0JJjf#(?X@&Qd%~cF1mmU6IU8E+{&;ioq6+FazjZLL_;X98IZUs^ zeY=_WU3!jPzK3c*S?+Uf@TjjV1sHo6N8+;#%@U12lo!Vc#n`JJs(K!r6&vnX#qenC z7zK`{7E%qE!=f08d2kUlc*p~a5X;7kIm_(Yru zC_ElFkepv4HO7!op3$l7JE$AAz&yL+t@oA6F6AuWba1rXu`{QS3%|62d?WCw2qQS2lf|j&sKQM=Q1KOJo!$7dnh4=IC zZ#{8$ORJI1Uj9e*!(qb0jM4TN9SqOq#?5pmxTrg9v;0ETHrc8&}g@0+YHj2a>ncgZqEKEU< z)_qP4!|)yKC~eabdxk$xGRkwlzoFDd`0Ny9fbt`qRFe;9MU%r*=$FaPeq!E%@G($D zb}&K$)=`TTaUGL$ZYU}25N|(}(DPWz{h0ur{_>Y^CYt71izKM9;y~ws>RR5Idemr@ zvgZD8B@7CT1}1ckPmBV_ zmH7zZY05=tj+y+#w2|i)OjX67u%8cT@)@3HH}*{{X_Uy9{4|o+6fAu+3a8B1Cp}5Q z=W(kTU<@QH#NON5;M!fyAk=NZ3+5(5LK-k2|NY4Zh}jX@^S6zqd4_u|^ZW5k|E@w$ zYP0BY$v1s#QGCK|vdsL|n(J@ex9mDy4JOwIhL-T#(&YF&w+4|ih{Rqpuw-aTm)=>w z6KbI;tN-@eVt}sZSBu*VlcKs|m4ZtYP8k#UP9}{6jvyrFZ1EFga2Jg^CYD{^f(#}O zP%Uv@RVOJhO?X|vsPa)!h4B~b2a03dbRuTqjv>_cV9u*DR|2jPByb)ZUT*Z;J{ybO zFzV><9&bcYxT~lK;Ij4-{1jSNqgS3~wMwKg*+t+tsE@@?gU_id>_41XjoQUnNoJ1^BR z+#UH@aRnXGGEj8?s!q;%zH)~UHl=k`Nfh;z)Z)aQ1>Uu-0)L7}%Aj5=aH+2xlTlN> ziKv$Vz91z#4IE6au(Ecx@-PUD3&21I^WG5RU+!@4ZW)hWqt~4@ODZlzSp-L75;z`j z%D%n#@u7r0()kn!UqAOwbH3I(3CM^F%|BKiLyFcf$)8GHGgj$uewieMT{-_$O9 z_~)J0lS|m8S@8ZLAjUA2acJ*jAkGa23$+A6OjjsmR;L4bfhFYv)`7-YJGEpHa}z{Y zsHe9fXu;u3YWRfDu>2`P1DKOz({!jMARrL$^0`*4#^Zx=Offh3j zgjANSJfU9X|JhO@=dWb{j~iKD$#0q|m=pk_4<-7_FaqKaAk^nU1S&s47ljP08g>U; zm>sYTPRt&*9H|J=W2XxQQ3^quy{?!)MVffnnR=fMJU2+Lkpw}Y-wfIu03KYF)43vr zL_q-8!Sl#X4b#O<;7GVih=d;Ube;h#7BU#{jC_EZ@YNHOheVpTOMqsZs5sDsn%#?U z&%hB5*kh!250O!Mh?5l3$lKPXyGp)4&_tgb0vy>6b^v?@NI($zQ%y|gKucg?P0YMJ z=y_^lc98%~>>Qbh@Gc|-7ccm3PBaa`cT!t!w{XMfz5f5&RqHh(!6MNn9Y;=0;@F6!4E1zf!#-e%`8 zK`sF!`91u5w3-1-475N7d80`xPzUi`>CF)?5?pR>RF2_7eEy4B{thga|8U?rR(~94 z5P#9UvnW{OxB0_Z;uIa6_H5Twvs*Wddj%{MLjE_t3IYY7bUUtstqGS%>`1f_q{*%+ z)qe2;_{eUj!GJMS1}Z1Z90xk_U?6UYDc&X)*oBJVb+i{UZe;3`R3%73CSwvz{&aGV z6u2I@@DTV)y`SIDl88+23~GoX-06@HuDc)_4~tMSiay%M`}_BULz(5qJo5YyC@J}J z!UTUPlN^YSREgrhm7B|C$lNbCd3)GC{GLEOC*e-8v<0 zBUvCZP6ZlsgJq%?B$rj)tq}iGTvB1(z+Py10P7Z?m7oypqOOXF6@g=?b|t;6E8%7& z@7;9Ay#0k66n?-ph$3%o1We#M-jq1|Nb0Tw;;yCunrh>f0G=Q!Chxp81b7auD>j{Y zln5jZ>0nqAR|EVHmNq(hJBrEHS~xcF>x!xVf&rm6`64O{*FgJNaoXKk8%64TFPFuAwa(YZSlZ7b3Wa#0;&Zy3?K4C77 z2?7g^M)ve~e@0AQiyzxrZ7dEi%B^gRY0<2aAD(uPO|S}Ta0hs0#N_WU+t|&Ct(=Qb z3AdeO_}}Z0?1EcLJ@^poFdzA)-QLJGWlNztu5gr)kNN|?F7^a;;kMOuf>zyP|Cs)V;Z(}Rz-MZUe^dHvv3f-s!mqBoRK-4YhXd^IT7}vj zhSC#MMdIr%`;*SpS805>6g%6?K6i~d{yL^fW{)jJYUAUZCVbQKkL!_#dVc)+ImyD6 zb6uQ*mk+6DYja?X%fD9(RSm3y)))yq$K#cBK?6ZiEt4i@$G!~Qj@N)DPo3wOy~a!nwrL zOP_|CJ~28L9caSjcqJK8UZDFD-fbT;ooXvAk}&&i2JL_STmw11*w{o#W9A36!#9W4}a){^zP)zBWKNRh*j&snM=p zDFvX!?$e2O-Acd4JF(o#JL>}{E^^?nKYh<~qGNrd{x%yN z3mq-#cNW>(VN}H5r_eY73eO~2U(Y{)_X?4irOZGvFowjEgl=acR<9${hm0pdt>$h~ z*Y5H)JLLsrF`z+>_dn;1C^8TzUp+;gLBtHVp@guAv`_wQnkLS4D>r!7I2esWB}Pi- z@!vajqZJfFdce#(er>3sfXxNji^14DqEd!@fsNoRPva%kSY|G8B6Ur7a{iu+yg9pv z&@L#dzg57$4-*-s^A50#t>y7FDA81-8H5pi&lrv#wi&{cPFUvQXs)0lU9LpYmTHl$ zAN*k8@er8EyEY;R|3DQ-q`P6$$T(X-EGnkS(ErB&Iv_AbO^;x80>Ylc$gQ5N>bd-_ zEENzuVI+v*jHH`F4g3^RG9kXwxW`!T?V&P3=;b{i0UWw7nm^yUoLT?gqX<0sDeyne zgx3=q3iLhVjo-WuT)r4M>Md5F)zT<8s~?KD0$#-)1OiDBt*~&MWx11Yjt&ZxK=<)>ws%b7;*W9m7Xik-tDUVuV+25u zANx;(0khRGNC3!Q%vjVTb0#tGN#u`!f^lceU7+ z$sO`=oEFIQMqcoUWB<7>_$x30q_6@oj{)-@%ca+XdB6alYBr2%cI{&Vf)Rr09Ntdc zmqY!65Q}gB#SYdhLcGMx?2uyt!~zvkU5N*Inqz-V!l%~|hdcu%`JhP$yVW&8vu0k9 z&pCSYzt&i!op*>g{Lq;DjTIf?n{JHRU>$^sSy|D$PhCDWo$J}2%3=V8{Q@ZLee+_% zuEO*BOLo?MTs%RIW%H#bC>vM>YvT>&>Y^Av^bbLwLv7=k;4bQKc)ViLl|2?m_WeDT0_>oa7 zk_WGqFiOuLU~TV4?F-xXB_WOJE65yGCNLLns$$QaO^FVL1ioQV&>;HHv1}_ zdc{9`;f_G|16nM5V4XVoOcMuBROTZ*y>?e&R`W%({z8l`7F#b(Z}>5Pi^7BIO9OUfyS7lW z@Z81eczGlTuXq;m=^8xS|(e88s0cT+YLx_@5LP)EH@s^e=e`x~X?9^i? z1FKy|^)_g>{#{+PavWOQAQ1saCiz~MJ|@iKXrXO?39ZCA4U`wJ2fTcE=1Plc4T;}- z(VlgAxC!C~76B3|NHKy;g@S|HiZuksBK^zX^p#4};@WC%My==H$G2U+T7cWJ|6{1v z*d>LK)_Q!0-ZhQ0^P)qaeiX~Ag^3sCD^Kt1)$fs|+}h}@$WpGS(r#zf-I(b5JNNi+&W~0wpb@8_%XTH{5!VMmcW*Vf57iqGXNHmupcF`iS>fSI{7&Z zOj>5?hut%VNenHF%so|qfVz58(g6c1Fg5iw5n-^ABq0LC|5$Kb-e)W7;W7O6cc#Nx zL?L0Dg6X_MEX~Ks|K|(1M&Bc-VGvl5dU$2$iQPYmZv=H~Y^L>!4NBDWS8Jw?$qX6dHW4|`1asRHpN1V)S&dy6g@DQ;=j>_rX=FfbNZkgf(d6& z{jMkTCHkDAfsmhJ6;9iW8?HUc{Oa66VzzJjjE{5l0QFXs8q|bq@ZBo!h-Edr1cRE# ztajEH^!{(~S5GsmP}S_AZ`o~XQr(S(!5VSDwKI_Bge>yJ$zcM2B2R+7ec8xmRX;

c$-D0cIlI8frUGlf9_(T6yqCpcSyN%++E|1)9fvYile); zT@J%!@t9xvWwN+&hK2VIhWQ?iWZKHZU?#)-1Z}|e;@U(QI8$Gx`BYNZIkG3W2c)Qo z?2;@WoXHw6b23HJy+aivY+R|N^_3{yF-QmxXcV9Ei8}>g_=2{)_!mi~dOSi^B6!DJ z-T$^eTzR)b@T;alkwXdFAJm?Iwc^;(Xh6_fBbXV2@;KADwo<)pY2nqt;sow8ATp5N z6?+xzzKRFfv&B$HFUOk4kbhpSkkMwbiOMs4_uaR>&K@Po#{Cp12e;fxhbv={ZSz5P`HiIA(o--Dp{8@;zH zVOLl5SzyKzbnYVK?M|VP-=_0n5qh~qS>H`uEmyi8?uHIBlL8tomy%-TqlZ0lQWx9o zq~-XvJ`IC2&`>ulJ@?O;X9^pyEAE9)tSO#~Di@B$!KJU0ARdu%ioz5dTRKVH6hP+B z!O*@Q_RjLLw_icdgyw9eVqe1kIpG)Ry(>$mNbG32P$R8Zjgex$&&nxWe=Qc!ygmli4>cOtRzq6^hq1wdHF)r)tL3d&WKSp+8j45D3J&4Wn~&gC zzni?>=Km>VAr!U&-A)REH-jaZV$S*gEJOb~HbNxHXYpf&=w;V$7-I`)h7$f`yMP1E zG7{e-u{1iC;xv?kn!fRAEWv2m@BB9yDRwltt%9>TO})v+Tl8pTiw55qsid%3fPmSJj%;rO#~$tFIUz)sa_BY=~Rvo zgkr|&vI|4OIE27(c1S(F_Dky1F@y=+?;Nl7Y*G=nTlut5>p60!-hQ-D7N+7+W07H* z@b6cOaAWs9i#h`No0E%mdKmbEV+36kF+8g2t+gUitc*fQ<0G5g$hHAd6Munhs0m(^ zT1E=^ZvOfz2txS*lLMmv?e8%8+G?2V^yOL>@cz7h+#cgD*3Pzg@||_$J7Y~eA_kWo z;efND;Ksr{b-t1-9frA!AI*7PZfSa-z2se6_Dtf&S>qSpS!HD~=xRH|QfXo9;+_Eh z-4C7P(RcX0b~mVZhUA-?phl6{?+;*u0ftf3{jKxouKjXJT@L1?cyzq{X8Hxg>p!1y zb60}|{r_^0Y#m)7`RaV+QsvJsdTgNmUa9DK_MIXE1ib9 z`2Os~qxphsYbB0$!^;m{rXd;1`L%eB%b~2}Io&WmcA<;YrxttCPn7UiDyc%cM|4dul{vXt%d6B4#a?X?PYFYfz z$Z*idFP9vasFZajJiaM;uv2R@SJ~UZkvB=IkV8)_@K zK;k~~mjQqcr~U6Dd%V+qIUItJ;8il4M(Xv{2tj1*Z$!g@5l4F(GxjxPub{6$&Ke@! zgtiMg(Egs)w69uc9RSDS2NZYE2MNFUw{reZUxD!D&8}@cpy+$)Rxx}EPCYdI2N+em z1g4}vNs*;3gE$gRDu;APa0NE!;FUQC!0^c@937_rmW|Z3(0k=TGjkN_im-M_a|zFu zAQ%6R^`F1lJjnFr&^nUx6J3IYDpZt`Du zgE*u(2m3rfB88fioDN)U0uelkoQwkl_T>DjWU;HCRTe+*es=NZKRD@b^|>=~=WA@- zEvKIMLBd08w=e;d=fR&gYfs)rG-w&wRNEyb{^;wZ-4u9C#JV+j*(;fkTFGPdSU)tIr*E zpor)c)dlLXp%hwbBXH_WJq5g812O8N^bp5Q4&((gcB8ad3=(X@sx+!D3*vD`A}uVR ze}5Ko{91|!Oi_WHu}k2q^ia*$a>ZwZwK3{uBF(N_;do0%EY~+z;Xl9alKPk}6P16D zSA8uvoZm^}GBxRb#?{mi&&GNKckpwmP@`<|O@UQ&pI)WW^WG8(R<3c2m#H>T{kmEehbN0iyBX)>mT2K7*l+I z{C4Ti`4lQ}z6LLUtsuy-R^lImk{o;_Mj5AY%%#ARUMM)dw#5d{_vGB?jD3v;vSz zqm0<=YE+-Y^aNB#R%jH?WaB5_pPPF3Qzk>3DHim)H#a_D8R#nu)EWB=IJH4NT>13z zWjuHLxHHU<0Z@>wp%SQ|S+1uxPIgqD3-J@HXdBzzt z*?f0awJ4QMdHB91<%>xC591Gf#Rc)!i|p{m0ulvgu_?1AA1q)>yeAn&hG2n(5**!T zEnGA{^VymGrT<*>?5^5HcJ3YjEsjV0?7kdf)SNwfl50^O>Dp}XGu96vo8}uG>Dge#XL+JJj+&Uk6RzY02XW3Dn1P$v5yTX~ZW;{r>(o zNL&rSfuJLZ=Ddd+#(jWF+Iw&N#rluYM=)A|y5(O$1E5&6u07{E|AWB&jWn1EgL)AU z4DSVq{imh=Z*WZWE$jf;bFYuWX3?sAIUh@;A=F^xs$XQL)|(%CXjP8?*;9S^L zGZH}c43agiAxmieg};wtKwLWl&#$B93Z!?a8;JEW^C$5l+%6cmKx3cJkw>0^?Rw4$ zh!p{hNkIjjs0`6R>|=hqb8YV*;NF;zML|ZAV}*1i3?t8=gQCshn3Dk@hiNdYt+@C> zhYa$h$e?LQr1n$V&*g)eMPgc&z)V(cnAriil_o{`!NU>)h?X!13Otmh&V+Xf>rI7x z+3N>?kBU7qD9Qq4XIir~m;>VC3n>jNqdG+3Pv3!s;Vl@l5}r>3e>_He^hf`mFMDL0 zYT>86ug$c`!ymn|yk3Bd3WIArb3>otPC{pWBe)L`K7nV_lFjAF~4*TLX z2(T2g2qXAaq$QtECo7=Q(Ll8H02WovaOZ6h5lKF{RGl*5!6#V3<3^CIgHRaW2?_-n zC?HM)NXiG3>mGrA7JsRd=EntE_(3GhipU9P(!rbnS?P)nd`DN@@gvu1vN1^9;pS&m zf8W3-!lG{i6)9bICG}cf4ZP6OVwQd$W@1rq7n;nUacyn(9bdhB{v%O`mecn83M4QI zj2A`%LuULZ@GYjVKmsiS9w5VeY93NBb0YMm32fOHf}Y9$Nbmy-U1DYNc^U2ow|5}!F&(Tmu4|0TZLsz*rkU4l z8tlQhO+a*_C-{9-ICisPr>g{r9l?2b6soS%qjC^9vYN*xUId?@1|D(NKQQPc+3VW) zHFp1eM7n>#OQ(cg<&?@-YbVz$b@O!GbWobzbLnp51c>R&nU!=U8kO&h1S8SQg3zYuepC^s5A;syIPa9 z=OcFYdvxjNv!}BDe;yb!@*87k=*~x$4%e(wc)(sA2zOr#Vy7=)W-zJqUR!+*3O!vS zk^n$SXE+Yw6L&<;80JHGMpQKyC-~-qvo15Z(E;b`^QK%L=|yBkoWnr3)tbL#NfffsM{4n40Lz<7+OnF2Q)u~alZ2Qua4gsyA114SOSE&d(LQlS_I z+osS5MPl65w#JYzfpmjXF`N`9#6e@;5V=e4|e)G!VLV$}oJDkt)%^{5n4AmCaSb z(*|0VG1vkf9aYLm0Z<qK3Uj8KR0M)vZ-*C_f!HTi0X_M z6ac=r5nbCw%I!NeOQha^yQQ(ADb%KHYY6Ve4{hUS!y!*#PZa=_N-lT%_w%c2busLM zEC#VpHoh5VlW)Zw|6%AwkDcDzxB`q3 zIHlC}BC0s6BS6ttlNm}j9*TV5T;A!i?$5* zqnNW+s_}moRK9;GkCj^g`^(A)N0HD5y+UlTp2EuCBNybAyQGFq( z=!S~A9oX(bq*|6ctAz1foir2dycEY4xhm-QNLPp(=+nQ^Y*;n*8?ci2Wxp!QG1WW*c`h0PA)28>FE=tyw|1)5O(kIa?P!O~&a2+9hGV1EwtyBQ zmACH0#*DK%AVEJ^UK@K+H%v?pqy!Q`1pLYg9CUMEaP!z$#7ay8jLg%-8SlEWBxcj4 z-V(4sXvo$b@(5RN>$7GnKrNp**Lp>dAUm3Gw=*aT1((x!FTPhwa*{AwVY-Pkv zgX_(35P@-fEWm&ljB-MvUd(|MpQ98b7FsmpXwRtPY+gXrfur#&~SW%U(E?xK30E!J(tNR*Hm=bqrfA`~2dk%Z1kXfwSVaP++y%YiAVo<&Slvcl`6)$#(Ef9}yv3d4 zwx5E31=0dJ>r=IuQrqc&0L8yURNDcAzFutd=$gM{HEPsXb}LQ2+G%(rmK|mPMUUwE zg*)a;^sm$9img<)qJ9b#t&-hVLjr3gHLrWwhgvhfCat5a?@}&h#p}rQ% z7I}Xz!P}YMvrG>nKBwq{NsD@J*ynAK_p^p|D|WMu$f((`4)#N}2tJ~Kzp}&%ynjDk zFeov7P55$3*65W682ox=aF^KhoS3gw1bfAM7D`_9G z;ErhWIRpYZTnNPc4Q7a{q)O7A;t*aCjMF66QR_nK z=1#2w09F+r4kQRCT?ifftoc*&TZoGso{2l@SN8lz z8|z;o!5ptGgL;MKJ8KU1E?UNK4jJTPT7!|NyItjQHGaJAWal2U4LKv#-|K|0x5Oqb zlx`7z9=`CejtM?v#6nP2%E0o+^I|eddGC*u43EtO zh=#eor;8`0E^DFsa;C!Sk>@!3V3d;Fg+UJxHGGLFGSoeBp3OFkeBdt_Y7Fdh#^qgq zfv2<5St8Gf^M&9q(NzgFQp`~3z*|0RlFTtr$1e*|A24=@s4*BAEVo**a0j$-R=Kvk zJ`kOj%!d4M@ldg3X5+26vZAhyUa;F5%7m~~LIo8e$mvdQu+vWcNC-~@Z3v%+U4j4k z8bMHIDE{Z2LH!~*wlw~3F2&VqfrT9B?)vzSfP;XCESkU<@%#0wOx@}roI=f@yYB%T zWheXIZbQ!17kX6tb#Gk9IcAD+^*%R8+AMki;$?ErZ_(;kB)@e|D@%m{9 z?IfQWjqico_P+trgp_V@vq!`>LC{3?{`nKX1P{7!sS57u^t!ofg?UxSx$)KeI|T`X z*gjXva{vAL^&g{`z&S?wT2_|@(+Lso#jX(0^6E1_2)Uo?63iioTo^H4pfhPrP%sT( z$Z~*JZCrXECKhO*lAW;7IZZSs+n#pwC9Pt(Fi80Li`xfbcufp77`o3Vb}=TlH#A3y zuaw|+96RYQSmedkw`7IgeZQDH;A~|}wa;5RQo#E*>RY^Qomh9}uYHU{MV54pBX1%< zePSE2yT+@_7EfguFBggyg-m%9Rn(?78%=lxE*bRb`wKVH7$EjSOKJkUzE9}O_X1_9 z##hVbrV00wC#vmz4J9lSEMsu--p(gA$qmIb~&xfCpuaU zoK7|le}2z-wi*b-IE%2tX`kcZArAmHpa&6VP!ZvL{Kv-n9JUxE+g~e_wfH^;I#NwY zjOty39S)m*n_Nv4D@fbDpD5dW@Q9u-?n?8aLl#TJz3t1}uBHk;-W&IZgfQ^3-f>A71##%{V$56y+wTEP_}M|Hd* zy=GU!@gZZ3-TcDmA6HTlomwH3$hkZJf!_Xue6xv&Im>Wi4!hcB(L(O+s{Z&6z+h6J))@(rG-N~#>16+$Z`vD_H(yv`bn*c(rN4sUDWo2+J&^@{JF7?TvMG`>_| z?GZPsy7>%S2f3LdsU1(Ckg`NRB5#B&P0(Lkh~F>xwg+AC;a?F`c4VU6*D|X z@-=KXjmqr9EuC&d>Mcj8s$FZs{PJ_y-g&kG%n{=;rZ!#7P39Yiu`AWr_f16Zg?{UP ziWR(pq1B#A&wHM76|*2(VXJ*)3{|d!V9||$6@Yj4U8HOVC=HC{&_2IOu3I}EAHL&= z)xg*5)Z?Tp91Hj`R40fQLgqLajFvP75B!Q8t|;A1Wl!2D5_nf2#zO&>VB+7l2Dj7? z196YSj(^8lh52His&47;(`eQ{UQFsd<~E#f@=866+~7|;z0x=bU>*yRKRRbym*F7{ zXU40){v;c03ubDcRV?>5GuHjDdq&PGq>2JJy9IEJ1pFHG*S%zmb>F%w1Yf{Eq~;KU zAh6#UVNUcTvP*Lo|L6Sszn%|vE|qIp4&h;KzF+d|kbAbQ< z=iglf@_YrjlNZmK{8UL)IMl|iK|bO9KIMmUVyOkkihcb*SRj&S6~+~0>P?SOc6BGf zAzf*o;-HfH6iHJZwjt(m;IM%x<_Xso5}#jh8FK+KTFxe$1;x4!qgR}*v-zfHG> zIQTa{2FHOUP?^(!Z3-b)KzBN;1PR>0{vm;FPg*=gO&TD8403G(h{}w!@;7k$Nf=M^ zzp@v2{Vc4*#M^G* z6fA>qc+eh0bQZy87iZo89hNFFQqA(-*MKB|HAub=q@BjiQO6_6+-y-~>;3g-nm+}w z74@HBsP%tNOn7l&=dqy+^CMF%!d2$yT_8Y{13IFMzsx~zp4?>fGARgI zu25`6>>5KIAMyh=U`1pfTn5o3?+=F5hc)1Kq4Behd`o=d%|J-0C9;8(pSq)xc$sLn zq2EMz&K^u6WD$?%%SYII#4@sIK+qGM$aI`_Ks3n*9;7OX*A349OI6WZqR=z$U_^RX zh4CV|7-la;9*0a=t)nM_`Vo`^6wmF*bo$S4lORDYL3bG3et9 z83V!Dz+MP$5G`DoKu-Y)x@1ALlSqu7X~) z|2}<>;#U-w<`T_yY3MEvLk!ymPe3#orc?zRM z#(XuU!`L>$}PFQmBhHw-3aS zoI8&pl)cAe2j%i$ckF=AipL@S=?JTXoSrv>JrLkbj2BA~uA)@8%5zD7O#UWpFw7=~ zjLhaoPth8ssf$WE3edvA*5W8aLJk1nZB29cW#PfcL-aQ0CZ2QgGS}=oT5Ap{ENKf` zElxqj58Buz*P$t-Q2u_|OR55EYNB39b%xeKwgbD2LoftTtSZ?7hqRIk{GWv=PHEjR zrwY(HD6~-nCOvyYI@%N3ItoBqa_8_h@RP>wv|OlrR1oz4Ilj=j7vVu&u~iTPUTTI|L&2|XjJ_B2U@le&0F%CS^14w!#`*Y8|cJWEgOM<7s8RXv79-~ z4#0qVKV~!jI*`4vANdE1kH4!{QXPbqRy2y-?5HV@KWsjH)R^Y>yC=cXVsuylpY(4n z!K`pdWf!YYy?m#nV;qHzGmSIz{%P1zsbPSeWJI&m{MAQ3E=sbbbc6m-od-vly$a%9hBIusTS*b!itJ?hY3s$=3)6!~h3J_VH^ATotL<};W z;Bj?6G(uaFL#hev(9Ro~uyYWLgq_qQHR!xzIr=idQ+6<_4fTsNd~KvTAmI!SP0SqT z3EOP}dEwYV!@WCWR>$Iuy<;J*AMnj$#7={17S=%KjR#t`Gvd^Fd;n0k?ZZ-Tr*NW= zCw>g${!uUKZh+xBMIlk+YJms_tUfMu)gI7VQ~mZaNek>5->kV$SLFdK!F??x4CH5y z+r~!kFwfA|4vHXsawbTy_vS3Vkzh4@c2ME#Y1X-C4FKVt5Tj>$Kykl8^N5xTfIAe= z0g<->$CCg0ozS>r5b^@#D+Z`JjDQkJQ{UzhF!Ew*MpQS$_k_e4^eN1<#$x+Ry z!j+}HSJX*e0owJ*R1!IuKqtP^c}(AN`!O&v@%+Ma&>6lc{1w*PC~gUw#MNI&bEEiy z-ot%&I_Q$+%(_iHFw7oO+YPFJ106dw*$GWfZQsqG1y$iKua_u|5CU%8>$~s|bRUVR z2HgT2Xp~?376m;v;I+vSCC~Z21Sbxu{Z)MjFYXx;pmBi-) zu$-^*^g$2S)kMC;#VZV$|FR>|z(7o3cCf!?!4n5?4zN!JbeF!pi@yS=&n%ky3veJ(0 z?vJ=(d$nq((O|+ThKNd+VhI7u(TtUjxZEm-M69`llijjRfa$mGdElu{5|< zXt~5k6B&TPfb2{cD*g#i)kCmLXlvoSq52Ivl&L7@dyJyWWyEY_-z8iyZdWSMgBAPc z9OpWhK5!d8ree*5MoK_DG68C@@P5z!gbxn_(UGfP-$dA?C-H?6mIDm>4yePJv1hp8 zYr%uT-;Ue%rYGuVs}|U(=?+0P#2%a(x~i4@3qgb7Jsdq%pWZ>wJJ|l|JhKpeQ25TG z-r8)kg81=BebFp0o`i~?S>Dv~b3DJn8x)~v7>!L`-^0Ic(H$3UB{v?&eSU`=T8Jb~ zMFtgzgTYBQY4Pb_3;8d7&vv`^TSAERaBE@pwPV;RR`2CCv)+P)e>Xmkj2hXw!N7X( zA#s4fK?$Wb;&u*y%vvARQ;?~Mk3}t-5J3C?j=ol^csw-w6%sbgsNPm@SI1 zADrfczG<)g>O3{f9~>Y4y0GKM3R%V`g|OkFae8%{ydd3qD)Q|}dOquzh*QN&**Iwj zGp<*7eL+Vr21QZNYZr=i+l}q~r{o`*jV62^7--Few@7RgR;~TjBIIGw8 z3#WR11njfHI>nYgD`c)ddW6svM7J4Is9?xLE})6G34etygsWQ0`KPj-rG1rxY$UL= zg5nx{zr}|8{q34Q*DSfg&=nG(TyA z^dkRdfH5@A=TsdheM7&f1FdM}#o4Y>rFgK-hAXSDK~)Lx~f0sujeqmpSc0{N+{J-X8udOP5kdnk*6S2V9Q4X_T z@@~LX7rqC_3gK6#T7(goO^_#2I~@^yq_~Yd;aTzNNjc=UtSqw0xe=2L#H_ClL~Ri- zKjNdIR|+?(^;%AaJRzM{Yg&T)4eiPV4Dt!-&8$U;YWkb*-}8Li0^CMTptXO4Q_ms# z2vp*_O^{1m_Oi{D9XMM9=7LJxN1yd?V82>%;=AZCa0A@?^d=4Tq97Eme?L+Re+-t! z@=&z6_&-NH4F}Zh{9!&JVtmO`K&dbVEvWwtE}0t`LHvO%D-HfNy$!hB z9}I+qTlP0k+pzu{OT?Tyi~3>|9*F0-&c`h!Yf!}2KspxR1_ST3bYmw8Il7=&lT-EK zqzcOI8N8RPz)>8WawYt73$%Z4^in_INCY~ZG4$-@!U6v8!ie6F{~HF~4FF96{%{*| z`vc|2Z*WWwtNLkrWI4czE9U&);+~OST;;ehTP6UY$lb-TK-KW5Jrh*^})Xgv^LZQyddY4Yj)1vxOd_kNzU12gt%5$gL&i z@BN#t;j3g-(fGw&&2BKTI5Hs*=R1Rj9FND7l@!V!JV^U0?8NGjULe}Icx}?QbFfPu zna%WNJTQesaO2F?OmIigt98AJtd+%A^N>n{)Y$4(*fr-slrs_5in1^3UlUO4j^I#e zM%;uL1Pn8F+$gt^CfJL;ve_;TAfD?P9nnd~AZ#vx7?r?~;_V;6Do6&_OTmA4S@_B` zt^TLM!VH*9lisr@5iK>}4aOJxl*);7AFG4ixLuxe#@!2vU%# z)2|>`1R0d1Yp@NTg*`;qfAd3iqYEOChZGavv%WjM@5V`pY%dzT6HWIGcrLwx9S5o9 zy2v<>iX&1D#w4*>P+vik3Tzo`_tKqM+cXLqm&vy=4gDn@XfXqm0j?F6b$P`kO$F%fyqZfL$#ii{>Js zsL04C-Zv)^vk9`FIoY6_1 zDR(Sq%jScb<6!q3protN%s(jBkU=i^$s^^VOQ@mkaA#hJ1`;g2$V8VN1owPH zZ%Lwj#BW54ljZcKow{RMNI*!kb}i`WroS=5D+p6OTa8B5zwsftFr2XnQ)z_(V<#B8 z;tUQWnBPCnJt}eV+9Sp?wJZX0M07rj6pPdfXK!W_C%>pA!TvCQM5BI>t5S(yB=qL+ zugqJgF$K#5Ro7`2L3B!8@D&BV@0CUk&UdA59${NLNOOtevVyo0d;wDYC`H(B|Hoj% z$%p;~jk?kEhsUq*aU);kL~vuMZ;pq9I zoe2ZLmtL|UnEF*wwu!RU_c#Mnjf9F7C-j>U(*zliL!1YZ4O7F3nHVa3-yC&u8Y0Rq z(L>+Hp5{kMn197IgzxnRuu+SRbuvYX*-6QzJ$_`Qa~Q|Z1pFFrBF2)Hi*zuMSa!}n zLQayE`X!+{Kx76}%ripxqL;#UWqj6iSVAu3lN288k{`04G|Es`#h#eE52N>T?BYjgqfJleQnyqHRIgoL89D*YQuBRKHo1hlD zLNJFW#nx(v`jQdL_3k|K-xMoZW_e6HQeG`ify_V}rw{5GPg!!_HFxAHMe$QMU#IV( z!OV=%r!`%n5XZG8^QW40qI%dPSK5DsOjX+7a4)#S)bgo{nvS0m56{axn8tvSD*noX z(Ot7tU@y)VZzu_jcmS*M8vsQyz>91}krZeymYMqz8!68mLk}VCet;umKSs8)U@{{l zyeik0bdkPAIE3*&q9j^xg!TTuC2!#*NF_BWHpaflVywB}S9R+6U+mSF!^7kRbR;%! zYVX-`7X!zj{1_-?qU=8@Dc78H>3_5Fc5df;+he_yVFqCabm5BEvNDUf$oFDb1;_!O z0PJ2ku=>?W#12pSH|pGw;loZ?oeov3pw*vCGWq8Bn}r9T-h6plvy@RN?m``Q?#GTn z6?oTb03tKweauc{zl}l|_Y|A)-upDsrfKcwhtIa1KMfr%1eg*lMyRv=JF{^Wk@{r+*s4)H3e{E&?huoZ2r|(#-$`|#bVpAzXabj z5@^cP_6^V?*fP$ZKes+KG+Sk(b;5p8c(^`1b!NIKR|J6mFO5F0QdP+we;;)PAbRKn z%Pf^8E1`Jt=J>O9uNMf@9TCIZvX30Aa?I~JM^1)!o$_8GYYTiJS?H%QiW%r>cY z`R0pkn!IA8SE^>Jus8K|W^~;X#c9a?Sb4tl0OQaM<8#rrBD+P<022an2 zQTOb8MS`_E87iVS2I`{@JVe78|S8}r>vEhNKX&CN)QKtjdC z&7HOO`siV}?=WF#iQ`*Di^J2@NwGl;YE0s^t?(eD)z18gmdrqq+ZUR~APF2eNhCl+ zz1Z}MJz1HnOs%}J_)wvN_DPz8!^4(CP<+NV3X5@%UuEOvh)FdKISQ=S*GZmZg9EeyndhQfgt4zof#b zo_0ai;(Qz&b7LYdiR>J%AdG|`Vu1)EjC5~0be}wF3jz%fLnL@R z$Dub4iHg${0?ms_DJ^5s!=f(q9nboEO@4c^g?f?w>D%If{)l8D2U7tu*!g_b?85bJ zYnMUI1;=24L=W;bZ_0iyK_~ckWA4aUH0muyeZ!9uLF>nY$WDlS9dFNw zWC$7EQ3OWIj0_sE{`6l2ytuUru#^~Jl+_jg{vP+;n>s29@0j#x-)aFwWeuI{-%Z=v z?{7d?^yPWF9!M&WZ1q50y3Xf!UL6K;pw)w-N&%+e$yE6YQvCufD<)NYYJWR)n z!n6fu4b}BAh@}XmuOD-dZoB7oM&!GjBGb~kdWgu7dsmGPDOTZd@71{f)&zX!1>;KG z9@H7Y!EeOQEQA)b57X^?+8sy@pCah>0?^F$Cw=DGB%H&RL~uv9pAR>Wc893hJ@RX$ z8Nmfnq-wUaxy%ppj0uo#7U*QdF$ew1*O7=D^rOZh{7aH0Ca2dK@drU!49)|5zC0%& zw!8{q6xJ~V;P(Q38R(3Qhvivo^2ZOfHT59e9!kxJTx$K38b`rgZHyYbk8)O4Rt{{z z{f$2E_sGI_0Udk#6O^z&IzoH}qlVAbfzoM?>r7h(91(~;AyPA4te%MyZjOUX6_m|G z5wXA7|Ne&eFVj5jmn9{HTa))ocYptceuTwKYmAS#Vr5q1zyszzh;HW#jr?4(0Ed+X z#JdLG(i!MiNCNaWCHeCeO}cRxUf?y=!*CxZFdyc+j6$L>N4eHTK*l~rP>{P_SjRh$Sp znu5F)X{N!@{DJJV%fP}vw`2>X;x((CzF?R_OB`YEGB|JgTKsr17&jIyWmf4x!SNel zMS3;AUK3K|L{1LeUyDIQYz7%X!*G$cIRnW5#neHuP@s}^ zz44@?qY!=l2QIR8>y!9Cv+MV!8bF#&hBp{O+b&3A`lJt^;S|2T=&mlKG_wBI`H;H zqtZABKpE0x?p@cq11(rpcYnkDL$=@M=S)UOBU$R7MO4B@LZR;p1+0c?OgQbZM%!834$TJ9{O z#g|IDw+djv&>vtF!9G_Kg)#~}&83r|XP`A()ej?D0;xaVetZh5=Yy4~{~3CE43h=PY`;z$ z2rUqr80zW}vtVwHpQ&_hJNAusa3T!D&|WoU^CKV`_}q0K3r|u>{jPh0K%yMg9(BElgLlu5uiYK z)b%zP(@aNJ5>e`VUTCb}f9=3We`f<~sVO&%$H6|2}2J`Df)X}BruOU83NHu*3$`pfsN*eDn@OLbL z(BdX05`TDbk@1Pue?2Z-yM^X@47Bxtq**Rlh#8&OJmX^;f`5Mb;|UIj5r$_Xt!Z4H z$Op{ywUOJB{5zf_g+sA`-sz*UU|KXZ1?K4mPi6ggmutRP-C7;7P%*Ay@cF?N4~TQU zXB0cef3IBq{S$6#Sx&v?#&?-lI@VtXGStmdxyez*V+xd$1TQA_rVBn1d|qB;qZzN6 z96k4U>i&wT%lRAUteB-JLijXjTI%I(l7uZ>dUS8K3A3`kI$CP)w#@^!=a_D4`z6h! zeE4n1Dc>#fc&^?C3&ua=#f9vFdu|)|K9}7DZqY--dncWy%yTqQ@vAM2+dGaB5Zxig zrf8>+lVz4zFh0Aab=LiMe9K`o8zxg`>TQ&&f&9po1djz}`CZD^RP_cgRm0rOv8gu^ z-zlZ2kUK&^uB8|ST_j>~Kk+X#*$z&pNheI|v}F#?g^J{J_lJK4+GUf@&|Kli!>ho% zYLMz9Ao$`Z+A;J9tP!_GUGxFJx{tXtOQ3U@2ye6C zYk*CE_7%Q~C-}g_1AJnltz*gOTGv*x=Y6RfkbRgnM2`E{yaPl{h)7#Ad6X0jT9-jtX2u(7#Sj6kRnKcwgK?yh(UN$;=*YDltaXzMbvmg=UZF(o2T0H1;_EQHIO=U zdRBTUmF0B4IPR#kG49U&@%ib2bl7Y?xRkdPA^(s%{cmsL&La8)cHrF*zkaCu(WeD^ zM40u_+c4+ChX(MGw;M*{A9phJyH~J`aFZYswa)s=cj0Vck*%w zo|r^tu{8i|>|d&#pZnO41Md1|BDL!|m~|s^F4%h_+*y{EI&%cJr_`V86Di0~dn5}Q zGkrW^MdAOk)U=LU@;BR#^Zdu>22ajwm*naGwK;BaO*x^g%!(!SCWq56|LgSZ=d?S7 z557lJ$TMmrGe`xDn@$s6cbB^zE%o%+8uNo*+Wk5RX30k$+!2z9VPNuhwR!u2!g|UpTYuOtrpnMcYSdQHAHi)<$}%u%8Axz* z5Zw7b^3*f|>rM<*s3gqbWEk0RU{_@Ism4hI&PFd_s6%|!EvzKu!1xp5A!q(c%OpHJ zI0&5x6Zdl_vB&(%fSUE|V^;DyP^fbE-%flACv&Q%G8L<2M!-awlEns~XWjFX2Iu0h zWUOu<8&T!BU`9~mg1Va6wN?7Ut#wOE_wVbi9mqW72YT1%R2d&A2IKd4V?rh@8^B9- zr|9j20#rSzQKv6@Ya4X=@S^Avixw9lo-9R739G;5ZGIwb{`F@Ug%$=*?~+T}KdY)? zZ7cc<+4RL6!M6+VWs%AV$W>)^_;k(JmjhSodGecdTODFVqhF5oD;{K#E7T8KYg6K7A)tAUb_pSYSJ9y;U^4u-t*x1-`9me}85){t_zT&30cvSAbtsbw z3WEdy|H>BOu|N!VQ;0{yG=3086C!p?_C)VZ4%0hQLv2}}j@ffL5^>*m(|9YU@3T#K z_-=|DU$c}=U7w4|AfN3woH}%$XR#VR)={mP5!PmM`sI0+>%L(=(f%PJGoDM)b1i$f zSZlvpGIYeEn5Ftt9zv@!LLMBPe~07(niTwyeV5e723z}2> zgxXsY*x0?Z9nP~VuY}a;f?0i~!}bZXoJ*F(hS2|~y39dKOALn`HDExyvHQDI?A9l3 z@4dAb+DQJ?^FlI1&0@23km~$(sohi3bz^H@#|m$jUGdX}w6e#PPKw62u|N%%Q$}A> zT-dinC6g$b@rQMj0F7N9Rqej2xWzsVW3>)rm3bpqLzP#;>fxu8Way#2?a2^6#q6u0 zU(#7FiT9i(YB>}t2|>p@jzs%Vo(SP|nv%~hjF%Tty*z`&&ro}@6)3yOh_Oey&!xlU zs90*8zT6Vx;l2~M@KwOVTS33@Hf6ulcR_P_QiNMdXc2g^EfyN58v8zdw2B_NMB53+WkcJ;NQaE5;9QF=2fNBR0@$5(^Ps;_~DZC{iD-jXXqmnGyxu5#<9Xe9;BRixkF=Scr_WaJ?XEr z#aPG|x65{NaaC#c1c5*Y4x9z$ zJBu>QPEnZ=P_xsQQ|@M@&dvAu-%lgIgGNowE5~=TVC2U}shNrv#T_#XzWq@wk6>h=&yjQ@y7^%A@AxmKp6lo(++@@J!jd5UbTq2xm_CS# zKZE>XMBh-EzD|Do+bMTGNs+Up##d-*rI=v}riT>FChISKrvE{wlM`NkBMLp-^a9Nw z^K@QNt;UPAjOq77Ue-+hi~$p)ndlekC#gqkE>m%~n&=QClY{|Ya|W?Q{R#j_>mM$5 z%s+a#M!rkHqsd}>*lzhDh@)I2PI_{ktm5Ixi%C}3WTOo{SJFgVoSxAJ_{a$TkwrDx z>Vyq+Euo_$cwHcfprx(y+rEo3wn~#}=zgjMGeX$9SHbi?J&nq7C{@r&%CHzG?S&lB z(Qmf7H6od_hA++Dq+2Ij5m`aQYV(+vk5aE|fHSrcy%ci(?yxkvC1PxipS9m8oV%hj1<&l^_%5NW_ zvDT0*X5|31P5bt=F($12*b-bXp;81FSp+#(f;hwxt(>`Dgg?R@rTqJ_BrNg5<-z>T z$r0-9tqUMu&YcCdE?#g#detN_jtBV&Jw$J++ptwQE%Q==l@7}2E#yn~5CrHAZE%HB zH>no@Q9rf!gHNBz&vt4B@p)dok7-gjUOYQDShhUYbiS=>?F-~2Fr>LAeeIvIm2% zQtQh@Wx}%5=L2!+P-q3x_U#_s93@Bm8#~=F%kxhryZ<_IXVtc%RTtJ1ou@2j^xdbv zFo}|m&haHA(Kh*hVGpVZHZkm_#4}-3j3E=%U}3`4A!BLygPbYyBB2;0r!nZni&1Dm zchHGkDd?db=2O<&yP8hI6e>JkI-VP^34HAPILEq`urT~jNJy|k@STpKo&ePBzNBeN z!vCqmEq}PBgQ~x!V?%aZ2U~U9#;Edk^Ri7Q?hO@w^0|bjUamS<%g;&Y`#!vp@QnQc z=ZB%Oc4p9d4ORlyJ<#|ZSrYVrUrJTS^Y3_oLR2vmmlwCo%^h_Mza<61iauMsD~_6U$*GxV zgtJbS_rBT_L0fhyzXR&A?o+Sm_;4)pUg4E?BZHe2p?Ftv{G|_R7gW~2V?9UA?$zbn zK4!7G@1GA#@rpYUn<^DyG%HhCinek>Cr`I;Pp17*E`m?oP{ZF z14i!}+P8?H{ifq#+&C5yzoI`Zk{>qz=Lt3zzI0bO%?gcm(>1`|kKS|0cV3DMEpm0% zO_Vhf8=Jc>gp4zFUbAJc=%pe3-%SIr0`D=4`NpNnd;Y?S-x(WZ!^HTyh00!bt4*a+ z<ncnKOh}jdv9OJ@E9ZstnVJ|e=1@8@0WW*RcAvn^3foH)5jgH9H(4f=H105 zhwYUcj5!I8YRnw?_bZSj*b4iP><4 zW$P$}RLii@#EAF|4zHh|>9KrK2S4I`Hqmh~F;*@;?#k3&iIC%PNtCZ}_L@1nF|pjrJ>aRJWcJbLx1mS&4Q_-m>t#&x_QCZ zp4E)|8=1=U`w?TQ^SpIDh4BMrNlVpT@1q7RTrD1oxveURL?YMs1@8ref@pE)2}7#%iEN>?OkcUd%#0GRWI&0hY^B6Al%(=Y-L*AXeNfUQQ)n|r<)SZ` zCt~M|DdsEbeJHe&LB5J^RHHx%;wBkCj*7=?$KHAD^}M{`4LRPo+JQ&&yjEm&k>^DH zdJli8vI#?Eo8x;JsC7}?-4psc5*|Oh9av^CNk8kXCt}-Ix+xfi1^MO2=hH`W@9Awk zSR1}#@wWE56Q5}?9!VC3N2us~57b)ei!$)~?YCF9Q%|OL{dj+I;x}1&x=%pGeRD=C z`5SowhVt^8#i`UC_n*N&IR5q=PRUuyd-xJg;~8I--`WDR#1stphIuEDWuDCO0YpAQ z>^>*R=~&I7my9hi(oVWFTAWAgWYd*uwwcz9`#!sFG$V}b7rf+pyTVDTqU(FpY3tog z>a))E;w!F;LsCz36leB6K}R-Z=oju>(?=(!cRtwswMyN+@G`c*((!wnJrrOGYg&GP zzJ$We{Q7u*-qZ8TppUR-$nA~snwx_EvmuoWMjM1}k>>r9U;NzE6rCLctCEFo*A?5Ux#9#%|-mjfKZ)BBn3QIl3>e_!{)vs536t+r5?eRpqv* zDEs!xh4JpGu{!-K$#Qc8#t?iTvc25`!VX<{Qfw8=pbla2$Q@&YD&xuq7fx7Y@J97o zGrD*T(LD*-C+7vt|8F;nW1 zslz$pb)Bw3b5fhf-L_#Z84j!OAH#fmW}YfKDUZ|Gh?~mL7)d`RGx()T%(lD8Si2yD z&wtczq_wpMh&&tG!c&#^n-;%YH5 za--=3R3?q+;QqxsDp*7VB6r2obak}PE5i!=U?~yf;{DjV2iGJ1P?6m1_aDmz;obn< z7v&#zTD;Jxk{aLcyIXz}s#RD6d5`_}&$5#3%t>dWl_bN4O#yy1f_;Dz&s~Vz?#X|* zyWzLa{NAEAg(bgD+Ldo{qvo>urm0Vk;lg_VLV3W-+*LW8wAarRzpaUT-&y~SE804q z&gQIR?6{~4HQJ+iMJEnY`KI`*IMp4nCIXWpFcPVkPC4R#f_inQC zMN5SRoghS8`SA-_)CXj;h_D@o5M-EC-^uG3ZnYuH&`1`ZYj#>$|KcD8m?s>@gdzBM zd{BS7N*KbI3=4)yd19qPN57UB`|9?`C&1!Nbyxm%swl%@^f^C-Y&H<%MZWw@guN~t zh)$$>)|S~Ofg|sPxU3J2;ul+lJh$2`od!7&enDJ}KplLBuxlsAmV~Eb^x^Q&7JkiiWxgeKF z91MZ3P?u*=vY>bQ7i~tuTl$}9DsnJ`oPd6Es?L2r2{aYd0Ut-S@AZ-;z+4C^b0f4? zXiCG`z!d`E3Pduv9oNGP%(8n@+kbxAKsZv-CW@;EC<(M(UZ_p&2e>P9=L%E=b5UrP3$48O8%|~g#SL1sVp2<5l)p$p>sg?CmA)-6V^p}}B->&$h zUh+Xf9VedLY5iPez7h`CNHBEy8_Aw9p~rE36nU=AF^ zzSD7&S3y%>7lK+##ZNTcD|870?m#%Nm^H*3^ZDw|xSxkKkju%@nZK z{$i@6d^Mi^H0j$1sS$Lf!MI2ie;44C1@(Wy@yclV4$M#Ptaq<7_y`cXF+vjn{|d2W z8ePd9(7qqMzSb?=;v~eCl>^kGK0JAGVL0y}8oI|&7dn}PbR;9r8!V;djl@`B#6a1> zE7TvV0r$l`7cob<*rpyAk^s^%k(^kCuH-a%|53Q58M4)zjme+h28BPll%`b#(mX$p ztJ9Ov=zWQqdV6cTP+gXpK)2RX2X!3!u&fvrv&b?Uj%8JyrR8x3Dk68oF}g5<=&kU+ znGdUqZEC4rA967BQ!P!VkxC3PtdD1@OHBdekO{R$-5W(Gg3(JL;2ew(R9Jm22 z32m5gWvn%$BKL8>8frG_1h^I}oFD&lEiTrPYz=x6t)>ClSZ_w%XcL)V3_rU$2l9401mI=cXoNN*B3@*=otp33#(Yp1KF4qSq--@;g6{e+H5UJOQ`V-EU+^S7JgB&A9L8I=$^*^jc|Ac$OOA z{`T}@MQ@;_z;Z)%Vx;a|uIn$Q{#xu6Dc^&jdZ(!c?HrAmF1<=?+6xACMT0mKEn_b` z_T_3TlNlDwvT=p-x=k!Yy#-WN z?cOh{B7%q@;v$qrL^>3d5@`WJVl6;Y1f{!6ln_KhloF7VT(ooxN(fTYDM&XejllU& z^nLgK_SxTe_C4c{JMJ38p#xcK&H2nH{_zX$T=Q*vgTSdPWVgdzgBEVJ?({Gj#Zjqb zJ7ORZOiwfXSZdV0=3_FEEZ-j7xzELk%HhBghV)@OQk2;H>FJV3=TZ_pp_4d2I^#S9mzvsu)k@8bx2*`$s0roA`v})$0 z)hC>f@v*`cNA3#?GRSG3Q5tYKDrp_G;>!W0Mf|7_ zkR1S3hM<}FlByii!wDNOn_vn6AS|2Wbu>Z-AJA#IFOagcxnfjZA&#J7ibMSB@7HIq z>ORzXxw;6;j4)AH{<88cJm&xl{YtFCR~mFzV~r>~bwx>J=PT)kQr*M6!I}%1E^JBO ztc!tG+PhCXvN;@-N+?Vgcnf@M%i>fHULa)1t#J`)`^wJm|Z zcyQU*=GwE^OFZ7J_9xl(QewMJl_X9V>eiU(40t|_Tynrc;(eCG%lZbF^`eCq??V!2 z{K2jA8-r46oE{376r9yW_Hl$Fhjb(B2^{9Uhdw?|Fr9j7QXJCqY<;ucE!iqQj@N2K z^6piqmo`UATtb%|?q+?wyuKH891tt*ANOksL~op){i=oAALThcxBq43nJ!Nb`7)n< z(_>=^iZcRI5MiH$l7+bHpG{6O%Z%J9!@I9!S|K7tRO8~;*x`#>{GTI%Atcw{Sf0@s z;;mhA@E~7Y$C*n%<~HH@88kh*xH^(}MK`gxFCi^X$+MH;^YVel@5_+%Vr5>$8@qD! z>k@2UY;asEhn(6y;@Ee(@4S#Jg*U71#S@sU(sRGpR`XHcJZwzaM8JISlJe%79pj0C zed6b+d58sS&Zs#oIPO+u;TWM;8r}Ng=iwB-7B9sxbtv)6?ho&NSa4GR{PK~9TbU>+ zLw5aD_-Kgb{_)ZDzHj<#y#pi2;~qG9kg;{cO3tf0IzJnFC(~g{fWI}xZph-m4@Ozv z%}^G zQV~2gLo#n{fB21?OK@hoayc#bKbb)1Q>o5ZK>6(!!RFVrO@sOT+12ywYpQqpbw!bE zLx8dldn+9Z>z{zWYWU&l>Eg%&FD*Egc}nOQ2>4E5h}iA%W_OH@_~LMhEI%wAd4ob? z$Bh(XC2-$>@!Jfzs5hzN+uzD!e0e8GSKG70!{^X=oo#p9Ada1^6fq zdy+3Be$pZ>Hdu{kdW6_-YS+*77=53-j$uy=+j(TDg!&<#+03aUm=O`-Y#w@55mGP$ z)Nv&Md_;hfhWsCB`VRm|Wwao@X)w8a1-M86HfnYA0u4fx5KE<7zWZY20lV5|*!_PI zq%}3}Ou*+eAAWxLWnUha&L!dyj+YG?u*W67140QxEzquTR6uA-qw+8Ws*&{R;?@p7 zrxp0_NJ@@B6ARBgv1Y=B$qaKe4+s67=14Y6x7S6iYL__ypcQd!+ipOYMiG;Dlhfs* zhbD{GyF5t@YrWjq{9t1KlG_JOn4&>6qw-ia)`@;ry<(p*jwM&FA?@kA#GKCqy|$`f81@H-&M&5#(cM z)6X<`D{Wel?`EX|r9tfF%1C+juty#z{5;0_Oh%KlmmZ9xoke()WeqBp^1Za4R7b)p zja6RUkvZoEf-m8~O?hp{fbh6Rjv(cDWkaZ$vmVFb%d}|=()6zP4qodK3mADYuEv_h zsv?;~E!-qGHh9%YQ4%O3GHq15EQ_adKWY8!>(?by^zD0VSSwyUM8j5!nsuXu#Ke($ zpa|VSxKjT^c_uiwM8~NYd0bv}Sm@FnlJ7Ym0S74p)Jm`|5Nwf1L9IFmmTBeh$~01; zt`D%_Ne=*H<|Fo$k5+5XVb^Kd9_q*J%|_zh_}H1jiUr&_>k=4h^w?f5ny+YL>LsRv9cDWF8B`D(mB*?{sS_SN1Mr69A$Yq{` z%S1jcPXVc$rh2nh?6q363zNH#4tWq?RHM&g)vK;7YhY{vz$zt#snE~)F9TO+1{54r z42&bGH+GA>7|w@tZ4g?zL$;Z84|W{v7NoxMkF=o#|8e7;QlzRER*hP#34#~MNedww z9OSl3HT4QAU&yH#?kbQ8dRJB51(&MqK}&ma*D>y06*~_>uIzn0%q!;4VGo0bUl?@l?Hdhg0B+ky@9CR!Q;UJ2AImtI+FDh4Hy=09zyMEB;>4$jAgt`G}_{ zuYk+=6=+%LC=y^Vwa3oJg|zIP>?6Z`dc{+>;Vd_hk0%_6Wn;`jQu)I>KQVc@}vU0^Z z=Bl@d9*pM|t_-Sie3&pD#wJpUc;3``cp4i~S#eV&l3J!XefuWT24c;C6{`bN`eF~Z zH{xY|OVj6!Q$0UQ$a9?Hy>#M(JywEAmk;EBT5D4N>b6s-iRx53A?`6=4wMy=rVx#6-O88z|dLaEESYC$_HSVMu= zd={a*o-(4lFT>ch?utYbOktbwE^J_@dJ{}%BHEKB^S`_^US{1qz=dQ9DH-1%d!XA^Dtq zd;Nvms3vim0tb%Yrg|5?=b8I&_UEFIvi3vH*whHC(F!rBlrsv2Sg4Ajs-35+ewLS; z&sRpKh!wb+x_&Rm{qj!2j<0IwBhjY_#?0uAtkUC{malpY97ESsyC`X7xmrfG*zF?Q zBbeh|#BufUyNEod1dSbZs_%EHpql0mik{w)Xe5jfYbR3b5=^iA$$qz3vhWC32eP-x zv5H~Zs9exd-g9@H-hjV^S_PNT&fK+^KN8W)E@mRJf0Nkghd?&o8=| zZCKhIDzT2uF+w%bmS57tg{NFUJF`!B!as9e3J6J2hUTW>%REkL+oObYIP) zMVt)n{OIUjz#No`;|4TiORiPqk{d&|tb=UD!(P~M`D+=ggUjzevYJE0cR3a~OIxtB zOF~bq8B?u^PQ;)SlW?b=)mCBh467EqxEwRA8_RE#AIq`8)4_9ycyPg~ifxWJ`FU}c z;s;G$sNJ%r%Y9cO*!;2Sn1jjA;jXg%Iiv!1gDB^5o^zaP9UdZP^-Lh4`BY6)OLQb% z^M*)oZiT5npTly?JL6V&*?69+3Mop0zMcaigIaV(Uukf6mY$C7^e6frQ*}%W2^y^S z?(T2a9AwO7<b`(~QC z2bV@Lri(w%Lub%L@Gvq%?PnzD)3et;uhV2E9-BxF(#mY7S|9zjm3*5* z2vdaZ?(@)JWBanF+_&#%wo^7v+P&acw@c1Jx4vFkW_pisyPvzou z@01;IQTR3jv!?DYH2!3-TuP^PS>il}887>|xqI?JugKmcL#;Rq&3RX)_;ZYrTNPXg ziUb!xlj%r;I$juF``*O5O}k zZ~RyGN`~sr3c%hSKSJ^3ED^fXi$G^bT68ywN^~pRl;`R0=C62aTAB#qvY#z7v{bfS z5^TJ`q?E$1-8qW-K_4a2!s_wnACC!2@2<8!1n+q^s5Q-#9()_V+hX|Zr)ni+>?pQ`WVjk6u5ahyg8lI&cASQ0+Mhf;DRFge4d$} zUWmeTQWpK4R+LqGi+j*ez!mSekw+ilb3)Z>=coqp3`t*|fq(mEm%nb+M8jMa=F^ug@q@tMGB@IG?v<^wCt$kF$)a0sTzF*!I69Y)E2XqVzGPq` z$n2G-ASP(>z{SKI(DUxZEzdCf|7 zPSI-gNB(qir@F~cv@b~gJYQH`5Dl+bE^ir`KSqCE(<4!yq?~?z{(G`!u=m*0^_Wbt z?o73u3{9_oxYNKM--YpwbzV=T>i~Z)rQu>;HMINpM%#V7GLZzmlFgjE6a33AVYy_X z<<`5#C$}3urxZsvru}&=pUE)&GP*Se4uMmn4HirPTH*7ZIUB!{#=k!Q$*tfaMC^Tk zA4>b>`%I2}(7KMu(MwP5bUmq0(spUqr3xx$idojDv32<{d8fkaocWBGd`tpW`5t_s z+I+nud@5Jg+?$nI4SsK20|F9TO(ow~C^~ML7KL+d#U{WM`a&Ycn@YUAuM#BYYhuO0 zpj@EqChx#3eLaZu>R2+-&bxc(en;P4l<0Api9>kE@K9+s#eySJF1-4Pu;FfH_5pch zo!zrLNIv+ULdk`cK#|Cq{YpR$q$|`5D#?=D*hYEEm$rWzt`r(ihY~o@K&3RHLUt?dJ?Z+|+b`^66<_{jv8Heb3?E zey1`2B@L^*1cQFSG=lMo4 zMJ7oNaYdsK%}=#6fgZrTcbQ#^c4v}GsNJ#1$Kh!6QR0kS7>ubMeDad`)2O|2t#Kdli5) zY@I7N_52gCyXeYn9~M^$$6}S9XwR30vFY@0*s57CbP@%bf4$I4;FrLvGTM^vrz(1J z;N3$=o?@{Yp_TJhfi;dukx1b}xnruu=!G~WT}Lhk;<;g_hf2PjPp;eXH$>HI6kMnL zvVWz*Jof?;0wS~W8Hj^CuO~>aqfft|uki%sjUDn$z}|Zz{%*@^e=YFH5zG}?NilS5 z5&PjI;N*dT{W45dxPi+y&{@gXI0`i(GB(=)v7RN(-Hn#{_aP7Th*O-Ef)_PSE0(k1 z7h_=$NBUol9u8yxk2cab)C)(<=Jms#xREN|p3` zVjyxO^AQ6@=s#)kzj-gz929X+hbn=*5QP40h3k;6M{ALi_!7WXJx3|Qm*g{~LDL3l ztRrMA4fwZ4)?-L1pQ8le;!umo#v&<+=v>s_$3?@m%W8somvs-hVyNDb{hMn>I52sV z?n->SMdXG(LtS^-)r3#2q(J{3EST@_mTIu8EkdBhhCJt{*Q4$~6`U$!b zlkOw{ZKB?-9F%>KuTh%;jmy_7IUN8xPhFbO&)2YFtBlMAtYP&B2J$#I&pZN!^_9LD zs0{W(3vmkAhk@VABB5s|U_JI2h&MndjDR9@l-+kbU}t`c;D{Nnbm`JQ>jahwey*dS z8+a{pcw=jV;ch{|WGmZC(V8aa_$cz@pB^7YbPdg_qE4|-x0Cl7@EW;qjpKz%2T7WC zpUF^_0g;NH7UMR$#Am(r=!R0~Y#w~&Rt zdmsgr70MgK8vKtcn~E(MJoim}G#@uEw8FiofUxa6U+oTJWzMcsj;EQx^CBPuE-mS{obkyezl$Djc61)-ri%*Op!VI7l z8gfWf2c>V+t;Ahw@uWk>^Mq$tiafI@C=NyUL3!VQ2l(rl{%(*wae;yFd0;pF8IgR< zH1TOV@uce98R7s11<>>8`^j%q*niibhN8$r=J1sL?Ujnq!*_nL=1 zG`(4eMQIr8ilM1~2N3}+8pguoVI}MWx7tk2lTT`3(-pJPQNO5n!=ChN1f#QfhqpL+ z6`=8_D7aWzp-h7I=2N9y|7YLCcSUxm&SY2xOtgfEQRm+N$K;tEJFK6qg~4I$NhgEl4)GF-3fVnXoe0B~Zbqom zK|Gm@beBJtJ^=p^rJum|tU@?t3N=7y$Fik7C9?uA7v(OBTvm`8nCIJREwWv^ZYX)q z{r6FL|K4yUAbv8B2Jz6eb|gxS;Ca;+wmGbImpho*aS9TaR^qWoaeoKw|pw_8a|`2H>n&2q8onx+=ZjT zJ%Cgh7V`nI8>;d357$*GhN&jb&Z(&zPx-t*WpF<6c|V}}yKQ0Afd{7kgye?X>Og`- zASk6~=ADX{@z~wKWS6&9@Jm{4LWI6LD*c>2Fy3cjwxgLK+bfSMgt$Eo%qo@}X^fRX z=}@|9ZS(8w;KRV($sG#Jla~Wyw~MsvG}bg6Fj)WDO2XQ6n)>5}9yt|cS6;o!(Fq#* z{GxW2*SNKB)TMDNzBxQ-sBwnrMAoK{8s_wQ3Y@fw8#UVv8vC_)_(y_>IG9>2_!iCEoP=fZfatoLwek02B zzr2OCMM#t--yc13qP)kbr>^#Vx%I4Gv-iny@)L^1q(ceKIlHpvxC{0h-+j}*ain|s zI7dA>fw|7zi#KgE1?e^SxYgo$2-|tN4!{S+s|eSvyI=2r zt@ikFR=UsOyJNJA5Aha;+Tin8qq1c3nAVb9}x#tR6U5g58#Xr{MAI3)U>(wHNE>if*0@d8VJ8} z`pOsKGCxpoC~&H<;v{mfu%Y(e@MAJwtLp7k%^DyetKe0~Es!rzahM&+y`pPX2g1~6y7?g2pL$|qmoUcuPuor0?N=s=xD5ZILQw*iXq^Om9r|D_qxa+f# z_IkbNtoD1Ixh&;@pq0d18T`bY4QN}={!j8jdk`Dpxmt^tv+FogcFM8_*3P^j{`HlL zl^cA^r(x=iAT$Sme}-dqzMw|@+OBh3uvNGY&&-LF&^YS@i&dIm3CuP&3h|2yPJ2Hc z2<(65mT=x11@iTSH77wgy>?uVC)^K%o|1_=iiJ;o?Q!MQrnB(F z(Rzw2z3yHQKIQlGZ&S{lcrU$>_Q8)hlT2yMY!CDthK@C`ysNv{I<{Rt!6zm!3X{DY zfL};}c--g2Y3?66^&rK9Eq}Bn*jlNx^?3Qw`C|<2T_4;|VA482HYIzr>ZRS>M4=Pq z6H0PC_Z5v+7RttU@Y@S-da)8d1T83OrJm$x{xob<6Oy|G*yS=A!^vBW_Ft+jK{e1d zyn-fm!RCC|8Dk}1%;fj8nZ5UNA~jAL2C`OiUMHp4zhB8>KLPSPm6ea}Mk=;6Yv6IH z-?YNf09lIO)fX_{zn4Ae+0~KEn-7;Nx4!iy6px29Gehn6sN$6sHuqIWS7#7A>#Ak^ ze5BA;Jd@=(rdsjIGFv*R?#2X4HcxnQ20-ADOMpEl@TMwv1_V^dUBF$V=W6+7*M*%( z-l?U6iSdku9M9`55jWnFdojTwc5j+ea4yG_+cK8N5k+I00FzC>oFp0-cuO%bAmu^?sR7otHXRZ_5t6zQ~tDO@!U4&XIb61i5C0i_<=5`gdg|SlPCv^I7lHG)G%Yh^r zLh7A6!2@Faw;W_7l%TD$xFei4MBr8 zSN;NDFkHlsfKDcxZQD@LR{~8CP5Rp)YOp^;bB%ywE^A~94%{OXFZJDSo)QLCufB7K z4{96aIgmW@4hETfhv6E@94LOP89AK_2WD&&Ft{hd z-#rY-#iQEiDHdMuW_8tWfCfwpNG+JR;Wq4u#u-&Tzi8t!g51_$hY*2-5+?7Sn1JhA z`Y(_twFN|Wj64o0Hevo5bKDCM=X`DVB!B-7w>K-H>GHq6c?&S5$yQ&hU$UrPLO9Hz z_|Qs?_V{->7!|-xm=V=QqYq}orTGNx_W&X?zXMtikznuL0%3W2#5F)3kK6&(hKmrc z%oEzy9PC$oj=6RR0`3&cgFi}986BVI;kREPpn%=Fr5m6tYFY*rbNx1m#F;=-R0Rl~ zh&Iu$^*+6MUg0)q^vgoXnWB^^zFe^7QbBy&3I010iC~A0Tea&T+Z0BlrqpAYzm3Kj z!8=xym`X$=$Y<1J8uHv$X5Syj7sH&-Ih zv8Xfww(#vVV6Hik<0!ht2KS3zLpm@#Kp2)cKymSlc3UBA%sR0j-(Q0uO73 zDDg}Zy%K`_?%O?Lws2XmeWbZS3IoZ(p^eg`_m7W$$<-6(+XG3ZvJWYU9}$hqB+0sS zRvwXj*yV8|5EXsR2%t|j$m`?P7N~l2^>TZ!Afk7?hD`|(^rc<7Z%~%xZs5MmB3icPA-&b zZO`vqb6VCm0aNE_>Bm03GCLb*z9BZKI;r$Z^PO+~1ejT8CD?efxJ~RPwddnJs_lYk41Wmk^VJY1*2?^G4W3<>BY3#PTxz1bfhZvTtEq zMWL&9<}+C-#3*oPE#ao?96D8QODs^^;~e*~0!dHRF168RoUFuGH8VNer?8sE<{7D- zNvE=V+`kisok^a%IR}XYP`vWu@|VApAJv8;jUk9>VI5-9;8gWN<0A@Rm-e6-rLcPn%U#_0#%a_<$g&f38_@C`?>#^)*82x2 zsJouVT8o1247$X3<}ew%ZkUWIiTadRCi95i_KDIlR%h3g(4_EduOn z|Cyb89&Z<>fZ1q}h0}gB1GFx%Md!wf&!7`gC_4L(3qF0QjwAw(_Z{MGstIB}h@909 z@cRQ?V=24=3mBIhQ!?Xi`Pf(|MS`o!5>#(5U;h*KcX($Q5GKPimxCQ}#5*G%D8&vF z5}W+?6NqV$9_w^QW8(T{N`@-E;6G3JSDBuB!H9+_a&FDq)Hqq|k-fr#Xd z5NSHzKmbskuo!@X z!!i554`$vD0Y@i6n6tO9b?B#vm(qd}6OHFwqAYWQv6_g6VG0;9tNrk1&hUjy_0W3OQ^z8oc zO0=Y;Y~8i56i>cv|7`db%_nV)^55H)g3^GIIn{MK+li+Fq!$sE2I9n$uKe~h(^GJ2 ziBWwDl{#6NJd;qHyB4W*vD8Hs#6B6deG81Fc#X))tZSn-@nW8pSo~Ns0e_Ltuj$Ih zT<-xW{sqWEM#&R`A$eHHjh&`g((Rpv+!W)^B*Y$|?9pC%S=cNT?hi*e>|*8G%cj-w z>A(zY{ZLY7$<*5%CXUR~hO zyR$AW9~FR-GVM9LJl-Nd`Ep4T|N+o1&LaKM447PN2Dc8vjD z8K_`KB1RSaZHhE!-i&YRudjAMa#jy)| z7t}HaC3arp4m!lr3&hx^K@s$U?tQ3pjlq7GvpFHJfOYpfz?b6QBRq|PdlS+V%+0(^L>o_Ht3EUSB2AmSh6-9;0^s&A7nCl zi&&KX$KGax``2oQ0;9Lc7cvK8Uw4a?N zhT`n2-c!4%dI_p7Kh2sNGLE8@)+l=3`^W3Nw0K?DjC+Et z3KVh8VP6fV7Pc`H_`Ltc**D|FyR#e#t>0g_#yP~sFT9OluHrN zxl;&s$J&TxrX!)H_a>yxujQ=(;849ieF2bf1>HG1T0s_4<5nxWpcL0iNm~A#q5q@2 zc3whRhY#74auVu>_`1q#knfk{K#I`=fA5=IH#t&%U}B6y?9dTmQ1FFfAItHC02h3S z8uzGxHAMVK?&V+i=+=I1OBGvOnI;h* zH$2k+hy*?2GP7ip!5xS0Olr6~=Gm3ZQ~vJ$c^&2KMQ{|j(EFOC?y`^SY}`D2YKI^e z3?#5@3E@Uc4!!HCmyzz(8^InkHg>tezsLE>(Kee@Q9{X}uKfkNlW^OD`uFU7aPVJd z;lxhdqm7JYH;LW5LwqU7(%Y5WfvVELoXuiHF!U_b{ZVyDN1x)jAred38Qj$qpYurmhWhAOu-=43=Vu zt=P^(4~k^bGaK`iXq{^JyE(^q!@SQa|9zEy3G;Jlt&|LY5=y>f0hiB0yBT>UT?_$K zDFAfOefsmO|IyLK@C6(@CLt%emw#VJ`FfE7!~22ni!{V+I;JImNf{hccg7^lUcRPD#uwuXJeb#FU6y;ScL~$d5%-}*7*|C z%QEe>N|8%Kd(Y5-4-9|l?sAl<32QzM-|uLK|?VD)&ih(HDIy1|C-wV z=RSibRR))aNuWYekNMr6|4~}w4;a(~z*30g$>EMf!UF8XI*c8Y%<`hjyW2K%gB1mu z#Yr^@tT8Af*OZ9sP^a=!K)u^b>oQ#3M?5cKo*Yqv1)ky|ZdMrlDafz2}RsYMy z(DcipZY!wmWg)x73<DD9C*2A<&k%I} z*{`j)`NQN^L!Bw|4aI(q{crusI`AwFB%gHR?V(sBiFcc0`3eNRb?a49lCcZkKH=8D zg1Phzt5QE4AP#4jW5{#VufNvOn`O}?i}W@7mHQgK2#v|v!%-u$FS>sXJB zg9}hHlv<|GN*kc(TKL(NfsAdySk~*l%b#nX5AE@sV?;; zg>-vG)L{Rc)Wk{vilH_78HC9^HKyTB;L6>#zcm<4#=c68wzndzEEl8SG5Bdq%GnKN#FwJQ9)@TFdZs0aIuO6Xym^UW64 z!q__gr@MDcApSoWnGi5Up}go^E#n^>JjC8fp6P^+DO8MP>WdOck!8hI)AKyB5iJz%nl9yl`$ z;0dDw(dbIeg~+8LBm3H}NBaY_!80s&(?i)A!ezRa0=6Hc8kW9QgYx_|eX$s-gePgp znma`8%s;XByZMQnX}iH)0c>j9EZ$JzW+xApSmhQEfzWj`XzaDhukM9u1F@YGtP3$C z#m^8?Y7(i02o5QJ%d1Ah3BH70_<`4aSXCSF@v=atCR@Agi^GKnX!1V91s3YyxAVd+|0I*Lj1v7vN6h5eGu~{tL zYp6Ya2e$e^R~rw%p7UWZyyoi`#U7?`s z^oe*USSqfx{$@lGPxd$u@QrR9(YETTy? z6g<`ATh2dnc3#YH>;?v8(&1^NEIC-FnktU;7BLF=HkIbx*UXnDr5wfqV}9R0EAJ%dUD0&1wo4?_pWo^DF8 z4HfHKDSbK=vbzYbYZ2a1ntj;LUw-m_VCG;^(BpHfVY0GK1XLQ*hLsQ#S4FGi#D2p%JECtxM z9EfUIkIRCi!|>1?B7okIp=lIn0ysA1zvBk>grNoCkzt-g*kvmV7HU1tn0tVpPA;Da z7ShPlP(SyG2mkCZ>ka^z6^%@T@-6r-8tQ_8m-x-6mP1(`D1qO_HR!9}GB)|GQ1Ck- zlQT}0J!!c%+bMP$dtbt;pwv^Xj=Z<1NQzeg5n(`H0k_~-=ZrmrRyGEek4x1!e}Wk} zU_lHa-2Q+3;bn%aW`pP@^E`1?a0%t^tF+^r;;#)b@cpo%@B~_wHnj}lN`UjA;P0<9pVo!>8+;R@Lk$X5%c~Xd~#+jSoc@6 za3j|T3^HnsK8P9pR*oR;z7+WmC7(G|cCc?~`Wv-<;}3<3RXRMfuKtwlgxcw;*=?NpcOGe?p{#tY@|`cG zlC`Jasl2u1GZ{#9DI5w0a47-x35+aWFP}H-%(&2Fr2Xl5)tQbq8ZLk5+Xi)c9gHPP z05nzR{xj_X(3@bj|JT72enAX`8UhcST_PQQ9Uz`lA*6rQXEv=HBNPVPfw-zEx)Xvb z1&Pug88)+}AvJ;p3m%p+x_U^c?^e20}-(odh+%nuiNQ zDk-i^d_fUvpFZb!aSZZ>|IvX%xaS}KWpd%C;cUR3ixdH*?9yTKL7+?OrXF z6g10FORRS2mn1BvkxZo&76M~dq_wpAJ9!n~vi(w~IdylJoA?)JDFT}Yg{EW94m z8!o4enw%Qo!cGDEE|RM3oqR5{+bs~)LZ1oYGOcOdpXf=y}|-bL5)(XzcvT za=TNL(1jq?(YGxxjGmuHU$^{9h;2FvaBmK6K6Ts4ww%!x9XBVnmSXDRtkD&Ut0Exf zJ=dG|TqwQH?EoTSZ2JZGwyS1ck~ajZMFuSzfZX9r`g%NYLIIv^N(70{0f`F%=$h^X$}v2 zMSerItCyg02|_Xp9#kM0je(%xe2VQ5i&^} z@~;I`7DWr>i^9%tHXCo+#*VkR>J+AnpCUjc#=tNn$y#Z!^ugK{kMU~j3sra<=!u~* z`}KNx@^EjX&GZP$-i7(UE(PNB*|QqeasnAW2~W=(Q^#{{#pWL>dHwIpYuuTxJ%Lq! zn*eJ&(}J?N+l(g8coHn)jdc>$L;=;xj0O3AOx&+B1NM^BSnW;U1XGY!!)DSc-VIsy zX}?30vi#LmM`yg$<4QUM^R3T^5bXcydyo`&o&0A3nZm1=59HJ5)O9^&gP2n)77FKv z<;vIQC-=WXFbbB0>v!V6&=_crf7Xv01wPLCKGXLd%!VHt%`UpNnJ-)V#-W0Tu7UIb zoX6+L|7E*Grnr$(c%D0SK+4c1$`+qMmn1AxyO;W6;u)$bjwqQRCSTQNH=%Vz~B?+ulY*ZyH)*Oec zQ-XG_Km(*7iLf9pTT38@Y+AN7htW4l-rHK7ZD25CJIG5`I#956Vw=3YJN_G0f`pE` zy>E8@sAyNDP4~}55R#)p7hq#V_TaxaMmQc1m1F^hx_a{lLL6DEUlM}9p)-J}_&{OC z|2=#=0MUPcJ94HXDl72+49AE#h4?J9+ISn}`kObJ81+ff4?acTWkqw+!Z9agwXvvD zq%EL!3<@d@N8y{2KGyzuA3MoyI8Z5!d*`_6IF1$FN(a2(=0XocdGcla$oI2>zOx09Mh&q$AdEhpNME6?&d~J+X3B zAnwDTR_XTb8S|kgwe~%v_^kL>B^FvEkHK$74t&;n)}TY4smZql{>iOxd!W#*(+zS1 z;EM@nU-bZ0Wq${$RS^}U)eC-5h-qvyI18qTzrevGf*jN(Stf+$C3y1!V%Q%-+=gEv zQ2=#;e6`@JS?}#1)2*4}sQ{VEoSGFJ0fC@TZ-h$94L25pZ@nSH+Pm=qP^y zZ}bdIW<Q?`AWRzM)pWGu{w#C_5mTuq zc=8t|o)RKeeh129S&+JehtDOXL)?Y$e#YxPlxLHnl`?;T$f`#`&Xax*PyYpx>=|3= zkl#@l`c95U^wz2A_Tcfd#+E@l+|%JRZ~0A%hbj&3#-Vw`wCgx*9qt z1YS@APn`y240H#N$l)25u7C^})`ZPRl2IlY-35-&G4o$azzwM!NRVZd`X`Jcc}DxY2e9$ zJ+lZr1zB97sNU(eH<`yctYB&Ys5=5u*}+&+#I%P1BoO3K*(tprpOKCneOc0oz~0+Y zVt2exoJMCd6|zb^X9UIX(YSU1r=b0PhWf$SP;>eueJ6BRz`6@;Xq&+*>@v*4@IcBd z(ekIk$qYju28!3c+M12Q)DI8?=s|G6g$V!fcMXmUp?}f%2K_fA#und) z4opQF;jP7A}h~@Mc}{I8ckDClMF(F-=o^ zqcXCQ)xmnY1S!2|Cqh>QLmrdhP7rervt@- z2@nuWN7bQC^17pkq@yPvP}QdAb*5?DSH-qhKM?o0(}_U_iy5x%g`I^JK|^+_;XmVk zM4q5U>vhe3PePtKup*_gUGUMbQdf?SDxQu6f)XM7StY)pJPv3iF88YajT{Ed+!Nt{ zz7Ow&ig+SZUZ6zBi1^yn8h$K2v$yJI!{8<>*$O2UeTT9(U?lugm8e zYL5x4`S4Rjo@_rlLd2&h*29)tnN)u4zLKMM8qAyd?~I?to?jBta03XSI1Qm(Fi+m< zb$g|UzC#uO5DJ4*i9>idN5U9PuCsvL-Y3^tw|`7#tW;z-qsW&NPE^x_uBV=NeJo5Z{*|QPyQcvp6hM_3TO&;xGOW3 z0P=ZLXgM+%TX44;n%EJg{~-vSJlR2(3%W)t-#LX|=+f-z&7D7hSM20S8) zuCT4YTMWJ=z$JxV*d(~-U7J~C0?Fcfat6@@c0gcFixWe%3CyJ5eeqBngx3Luo19d@ zQ0O686qvX&t?i(84*qjV5DFp&UIFA>oQSC(Y)aTE@UVz@ddoxm(f+oP320-1$e}s` ziuEFBLQi6_Cb9W5b%LohVA?UgwX~mzXfB6sF&r{>)&| z0NydN!YnF9SQ`LM33J}rI;i#tYJ3e%Sbvg+A60HrKc=pv>Tj4cUdMq4^BWU#xJN(Q zTUU448u!DrAZ#7kr-YP-9SLIdyvH@*bVh^hEHwI3Qb|-$(g73qPh$a*#M~~j85_O- zy^$6%AVe(2QRpeC7lHjYI}F(&6X*~sl~%S4PB|n4qGWzJVsk@5EfY063)Q z$%+=Y8P{w^vKAcc9V(=`A5`7-eS6CwRI4N~flvqUXv>+0E_DYb zR#v|b>Yp<}QDm6b8@u{fH^9G%9yyaVmDd*sR1xDGgrh`|bLQ%trAKd$Cjg>Sl4V~> zD`hXwd79+0CI z;%|(^UP*AH)#Mux+q~hio~aJ5H@z`IAjp~<-&AS?fQVtPZA^{5pFWv^K#gh}5#0uJd#2mF&HJFNl z*2D1g${>@nD z%h$eYI;58<0I}qS{W&8=jG8DGvIpTwqQ4iO0Dk%I9N^QyGzhUIcR$?BkT!5n zuGDifps9#q4$=BJ2q;t>lXW@gfbRs0s7;+lwMPXsy_^FZj!X;KoqzJ81~^{CGQPKr z+M`e1c5b40OMp`dA^M}W^jqPq4SV{8S?dd}r`RiTF{@zwAly)HIt==Z*Z;9Y{r?yU zgDk}V1N`)GGW}m8ZT`Rd0;Z!#I6Dmf7s!mZll_Lo)sx_H$~Pl!1-*lp99sN#ZLg8N z5h=6HG@Y!|udpeg)|FB6c0G9#L)5UPkEJ`b@A5>q8@$*(4Wuca#M z#ZIK*gK!PZM=J*^rH84nTi<-x9%s?!t7yIq5+(bu*zdkWC{L|SiIFb=NilrQV$iS+ zmow1|ds8pw9xf3?)lODJfWD1K3f)K-MEAUC{z)vb9nWpCbe^PBh6!NzuN2B6NEUx?M;mtqSo**AhkgX#z*d~u|rukvcC@Yl?! zMmMnc+vkZq-gv>PGVw;s_q`Xu++2?%-tf3S01?pKez4?tK`w0UKL(8AKf!>p0g?9= zh=@h^@gsDa`Sp14zbv~b=@pRu-W_=W z;IFq4^(aT)=P0&^$Wvb-7ZOGIp#tPo`2q>Io1lt{0*n>+%&|x%F-$_P0wAhAUOc7d zTVxl3Z-X`kZxQi+uEKJ*as$B~R205JaWI+dsnJtiL{Ydd4IznB#EXa9+vkJ4K~~y4 zi9;?TSnEE9MU z+|Ge?I%0V#-H!E&H{)+^m4$G?9xA;bl(A}0)^lFbW)DPpY3Z*pcaJAvxTj^Dtt)t> zj=SV{RUQM-;9WIxEE0x|QZyN3j{yhe1K8Z5uNF+L2W7p~)h98LjVOjdkfM%C;y#3- z2)?Rr%HLLWN#p*)-WS!5Q;XXJeQtxZcDLroXSQAZ>4BxPn&WKIjiYyfNjZPVrgD(J zefKkO9}z@59_%$J)HSklIj1IvgS>R`QyX;j;s-jMljpl|EzoO zvRlGNP~iL9sUx--K!!QKg)y6p^=d@*e}J}UpXALEzdc_!;3oZhbyXcQ@Nuc$u`B%u z4?#|f7cUQlBHstUyTaXo540;Klx7>&UHMohJ@LebUGNwTkk4}LW}6lzmXcP0Cu*}@ zyBymUvhdF4{F+B<*){iFYG~s(iv#c5=)o+WTZ34SQUXUc@Ecmv;RO3eOjFWu1m-6; z_YFL|s12CYMOo*rTF(?e5aOw+r3v-wfN21PrCRuf5FCF3JlIC&a4bF0cpRkMs?( ztN$K9F3KE)dSj`tM%pSaIs*La>L_i4H=(VqQ zX-2oyC{EYs(Xqs=wYe?q-I7_AhDUAZmayWbfU;#EeUZ)No_f$OqeXS=gEETM3ppit z#F}3*Hu+48Y^qM57P>@O?4ijDBlcL4dI5H>yFD3UiWO_wd7yln1JG-UcM1kG2Wa85 zVDJq8sS}qg9v6*FdWP7=Gd`Ec7Or+Eol$>8BqqL5~H(70j&7@e!Z*6@A; zoDby~FWT@;>F$k7TYmfWb9(rhN!cjPMr&yHm0DO!O&a!YG8}HmwXvTuKCHW;5i7h8 z)|pL5&hpDsk#byOPCEhRA}*vgrpqV#n= zw72Co8?Ea`xd$fY-V8^$xvD+G`&iT+^tQApKuzg?N+)AC&1)+3-gAQ!3XMh-8j(tMuBpMU`}?#tw0(Wpbiq)A9#p(BQ}M%sxX7EOMQu zm-&-D6Yoa2Xsu0`DZmiNucuF{&L78@Qs3r5^%$u=som+x&%ndVuVNkQ>T;yr#5Up6 z$PzQ|0IY+T(!nf&hbH&m2=K)63(ZJga862OrIO_*SyBxz-A!DpFoRQ8&`v-ij3@ee zDjE(bXfKbMAN2TH2P-zNVp`=2Ge(?jyC7J8={hWkzvfy@xmsI7Q8su7V-&jXA5f~4 z^snNk8J%mjaEDfA<<_CY!R-W}$ib29`l(ysg|1H71!%5me;4i5ra+r*7?7|lZVB&P z7L5n1QZ$MRbgABlIyu_T`C06AEP^Ao@ zX}13+vvy7oHb$2KdHJc@e6}rGCn?XEv#!|!yU?Hnqx#(h8=*Nz3V_r*KbSX`!QI-G z5LuJgE~i}x-}`w|mAAxVI>2vBtVS`plgweqi9;m**>;xIn6jH2n@?fy#ts`_Vl@}C zqaFt{qdUc>To6`%db@bJmK(1*S)+n&jZRXn7!yCzY00zErdCQ?F+$bdPOT&~R$X!6 zbJOnCuy-@56bsnXZ6^mEoGK6|EqcI0;h=pogPZ!egVu4n*^A1NSSROJP<53%2*XGD z{bZ=(V@KA}VNE+PO&4?tP*~kna;oNl(jbMFO`I(tPF^_z%8ci2a`M{1`Qij4vU^-g zae_u(aJ)ddZ5ZXhIsV2WT|blCnV_M9p(LazZ72k<{q3&`**oCYAZu+z0mMP7XFuNv z-gk&u?aKM`Z$$D@ewSzi2gcE!y+WPJ=MK%&r7akxa`CbLj1qx3CZ0UhN!QSH@={cG zoq7YbQ3u7}@nYZdhqe0Hlj{qiijfWoT){ulV_}s2y2J5?;x}fW6Q0E6`q^DRKg!*W zyKnbnXZ1$9uZixMt>#S73jC!R7ks`eQ7$ zNQ1%{k2nUiVDW+}%$|2-KoT-mgIut|he&;_@H13|up-!D-;;$y@)U3V%yuHgNu?&$&r=vs$%ZWoUbQz z?IqsL-@sA7cn`SnpP4-pSyZ4Uj_zu%V8i|#Ix27Znt~Y3K;$7}ftoFwYsWcgJC(i% zC~#ZkFu1og;-NpTo0sM;{}{A@;rI?a(!EW=fIB~*?JH#2gkb}IHv4|SyHmH{U%v^* z^}&)|6;~x@+l0O=Qs5(m8tmYqhp;Y|^P&qbdk#>Yx~}7gurfS=mvWZKrn5 z%B&mG?%QeY7_!yaL5R#6L_Ay_57pYkNiRN>r%OWU#_6t?F6Q&XeCSF)`s}Ovw7o@g zEq(H9LZ9yb21#4VgQU1G#}kf@8T)&-{zI_Nl_S2gUhrdY11N2O4ISEbWKQ|AC)*+W zaTl#TaPQ~2t7;xnhB8|&U-5a)JD}Hnf-ivSp^aOI6bp>Z-v4umC7uG$#A*uH+{awt zY{UjU5R>0ii(0pv(HA7$4LSQ{EpN+_KQ62)MCuSzd}evkUvGb*!}X=w6^@}^x|zvj z3x}}H)s~VqXRzUu{&qyYkzT~aSBqCPsd&}pmC>;pOI40({jkk~r_fx{S;u3(hoNDI zK?nvFT8^bmqRwBSh{RKKk*tFy_B4q{|AgnkH#wNWu~FGa!7Wp3jHs4R&j{ z`xl7(3_`XDoiwu>I{WHnQi1eZIt1>Lf)U54A0_4oOf`-4C;V4gpAla)@{ssH$*akj zAP8$a;rQekKP&v-QV$tr0LY@>V{{f?+zqh#Pvd4A!+Ho41be62=Kmbl?5Eo=jTj`F z!XggwcCwU)Xs&Vgg>Kb2bd&YX)yKM08JVFlL(&p#{^>ZMs$&JD+9F)BEU#d-?lEO& zpA#)ZP|KhNR6*0lkj;W7>BNpNQ@+}KD^!WQ?s;lLX2?DS>^(65fDRnoK2{lPMpn1pZnwOt$W1sP zaeLH*1uFnFVUQ>##)C5{Xe)4F2D5`%g!rx0St2E*Wfw!fI%KwXjY)^8DnbU1)+fcg_kIDrRE)(sTk)TtcuKK$_Sy00Xo`VqLtq)yTD;1;JG{-gG(J@{9~zL*yKqpE1txO|OzGb7T^*jt1}zIL%}f0^rD*Z9@&$f?VXkM88$3TQD}xPIqK zk#g($E(@E>cSEnl-`L>YXO-``d*WpXd+p6rFC^kP;9{4i&G5@du>z(pb-UGdRB!C5 zrj9z+eUlMY7@G;km#-!y#8rWYf7P12JaPkj5Nr=>?6Rn(HEt7#afhGi9YzypB3~Ma zD{mLqgtg-F;RUwmYBeVCmo^6#C+@p-N+S74)ZPfTItX8Z;MeJ<#R*gZ5LRAqs{7Xb zKg|)+a160oV6k5e;9{bxVH#NKK7l6=TOHTH@0Mk1@Ygl(-}KQUq%l`C4`6zg{<1XP zO1V}DqgGia)8Hkp3-dYLnnUeOOo%~D)apYwjHY+F9WN@_jictWG4(&Ov4SjQUF{mU z|9aegn?07j@D?1h7gq0gp*_8dMe(`eT7P(9<5Utd#5kVV#>Idvw~kSkU!7SlRUU&i8BRb;0rah zsz+0yc9yqYi9NQ4xrM+Q`sflJ_1gf_LvnI&H}p|-&WP+ zXdULIuq8H`M54(wY7`DA`CcY_)7lw zju(Oq*#lKa+?CvV^{|VouGLS@R4YfBdJ$0eqs416%W2Mbx;>*iPN62^lZIN4gjdQ6 z3RYYHa8wob;lrQ--x{tfwHom}NfMjYv&~?kV?%{lrPMMx(kgE6=Okr-8Ra5q-70+2P`yX5{pMO##yD% zt!O-vlut>I!%(I2h!#LHzU8w^N|0`~Wds<&iN?ZAEwGEUo^H*`sdDX?mr>YSSn^+V zx{buD_7=c%5=>$4phMj^d5sv?HlnoV4hVJpE#jBvo%^}572x`9NJ&0dX=^-)lpR@0 z7L@htqHV5F((@BcDSDdwKe{a%!$bt*0+AY9o>UM!VplikyyB+LxByv`?5gB_@uUU> zL5n(Czmu^v>M2}m3>11+q}QPRn?_GLquPQVN1ZMxux|si0SDM9)YTkxF<>$O^tSBiTh}wosN9GT#t6&w z><<7a2|XmHL@SncS8sqzq`O=$yNL7fs>#}nAxHRDDGmuQl%V^qQ7|Lk@7lz(VyGn+ z2Fb07Sooua-_b|)mQXWylUgy@95$@q%%J`Fs9<^fmgss2LtIjm{^L)kIScs}qTCt? z!*MUqghfD+sBiOY3?{S$P2GJLyctr9M1jDZuc;Zh9A776V({fsgAKHEQ5fOVG3W|5 zSBGuj)j$FzQ1F{!c{%dedR*3y^+p9@qfTG2%O-(DFW208-urt6Ecj##-&R2eAG+l5 zOU;_2(T8wfE?NpEW!kMaDTClO@yaek&LoGsRW1uT9lDgu?}Dt<5%w@0QPm>awsZND zI(*}hsHmR~bk6(P=ChX(y=&L3#M2rO8wIx8lPH3x5zP6p#vMuOO6a&EU%s{n<^QAtc{;u% zxSGS(#fnk=gDZNaipC0Y3XI9!I)f(6%D&ftwg;~Zmp5s~H-{570POT^Yp{L%y86ib zgmrWju6D`-OV*=%J2UxmXsr_Qph~`_L+9h2@V(k}daA17u-0>4qGU;t*z;JHC7x6d z9ohkU~?bbAHDIr;85?Jh72G~JO}h* zMGR)wwPLD;pI(F)?u*R@$t7v9^a-`*dheC+&6DOQ`#_2|J&;F9FUv|?*jsDo!cwjvpWv;dCSpn4 zCbgL7QQ>yRJvwEZk}crEw=yQPj8E$#bqBZ}`5dQSuV?A#u-?SX$}{(k}B9+iLq literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/satp.png b/guide/source/chapter4/satp.png new file mode 100644 index 0000000000000000000000000000000000000000..33357b737a7fe4be045d3b6a085e9ee2323339f7 GIT binary patch literal 23634 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%0AJsH%33NEr-&C_V?zfBD6F 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 literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/segmentation.png b/guide/source/chapter4/segmentation.png new file mode 100644 index 0000000000000000000000000000000000000000..46bb1e6fd1d8e7d42687bc7ea99f7888a0ff91cb GIT binary patch literal 54739 zcmeFZcT|&G_bwV6Hc&xS5CMTu1p)y@iWG&=doL1@4nmYBU8oJ#)@y&Xp%x8j3W>&L4w7 zAT-KK@;VU6K^z3KKi~)z_!qg#i%j6JeQr96*CEB77iPgP2kqq4p;IlAOrTw@^X4!=3i@%zT(vPsMEyUWnp`g?iX%xYVzRqg9-{* zrLR2uXu}z_<>jsy$oGHh_P@v;@c3ey{}It+qHa#Am*7fiXXI=i^IYvtXMkR$dMfwE za%a)7a z)<`fYPts#W9XTAxBqA|+cJj-#C3GKTb@6_{`zK;snHe;Y$r|%*I0Hxju;| ziAsaR5Xkxg1RdoywF}D$3?b%ErZ(W^&!tps5k@YYjAw$THf+*A+mNd_N$~QD5trBE zjj_;44pvXQpFUM4&sQB&Z~H-u4CfMJ{Z$VA+}eALJwm1 zeQGo16+53Uka~3kpMC$?O9QST^UZ>w{bU=xCN;Jl zSD3dIyIA06Xth`&8mcs&;e|wS{mtg62qd7^ms>Om! zJ%^BeL*Bee5q~7%<}hpCn0?IVPehq+&N)(r+j7TZr3})5i`aB+cq*5Z;T&b^<28@zd)jB(ruhG9q=>&i~V3Ch$$w@7hb zuv(+G3q8m0N0itF`D?H4M|r(eXj^xF%r3X`rDWkdY`tpg{!(g}`>AEd^ZL091|w5v zdKP>}Z0ahu{%z8N;v6)SWW6G5UPn!l6yGsO8q>O;A~=f>2!rrgA_Im|?I=GTG`MSG26XR`n@r}tB+&Y;pNC`MH|{#kxC0wBYKThTe1SB z{o1o`YQ)da*GQ6mqEVwcZgu3-G8aIR>pP1xlsO_;*rUE{&#SQ{{+Tx8QR5!jF+u7~V{JREXWNX{{sM zm-)5Jl;pRCDW$pSe9On=xKRkCI&0^iJ7pSw+PREGs_NUWHYgIF_0&W45Bz1Dw#hI zEq2AR7Ek|B-C5syVMSZs7lG}cdv%XAP@&N>a)pRE3z4mK$JkLY6~f?#uz?aA!=fuW zTwkWepvyugg2;r*(lKJ$O@zL6XnzD2+GkyNLA6#0DT&<&B{^lNc=D%v7SbfGd2Eth zreDo7ct{r3;fa91|`C5!J^cx0T(xHVfaV<0#QOC-Bgu6PT@|8}>po>%- z+fIf$HN^{&oujKh1?woZ;w|F*G{!GQ`sAhSGwHzEhcsfaP?D5h)n@6;d!^p0#g$h- z9HCF7;DX4*5LwuY=MReWhcMhgI6%E8W&J9zXFo7scUx9&Yq4)t=fTq~^G+ZVl!v+T zz9uDuB@2(W9>tWDT+y#Q{jy=L2f$qwIlhD$AKpX8Reg!fi3p_5mP*y{*LaPiL?kP)Q==5GPq4*0A* zK{p!?{B^}&4$DopHDZFSF#U2x{?ea0`}5{d(_Q3o73yi~r@*ATtNNU6|PA zEIu@glE@X-e8BYnev2}s{qbKT{NMPqKil_B=aV;h=pnMt-t0PX2*Z9jb%obX<*7st zu&!LDzXP8e5RRh?Z>z-X z9m_4pMk~sEIBuC^0i`*iz)qgj<4jN&Vqk9=C_oOm(6jM)oaX$XX`NXP$Ev|cz}cWW zil7U51pKZ?#vlUcC%!^^?iu1N)K&2AI6KN@SlPEJRcq)qMLdbsXCkkD z8_FV!Zzmg$NdncZ@B6Kq3IvW7Zo~CJ-B3Z6ko}|uZ?D3F(()#@mBDfOgGu=QR;8sW zMZpe{m+za^Z#&V zVN|BUa`{UO21`WrSWZRQ91)g@ za5?+ouXD8@*5j;O@L|(!AKM(tk~`YM1!W4kQ>TZBZNBd`>jW2GevS-WtBsMPQ~2V3 z{gQ~r{NVcLdf-~uP?WLlw1~`E&&@{@FuWQjLcgndWO@3k*k}!7`lJI}8{qhC!Qj+Gj&)iwmmygmLPP~zwttBEOFkUg%g5rBSl7sl|Yn!0kRQ)kf{g$7B96yGVluEH8I5ZRDB;wP;D9vW9XUt5aJSc-fw#gzWr(%7-n$` zQnw;38kLIDoeSJF`Z)>REEVDqM%qdfMKKxqWB=uQX+gjZr1HrDt!U8}Jr$D9!B`-;j;I z_sOnrVRj>5hAyXWu1${!TFC`HZ1qTXos=Vt6kFx4Ix#AgubdC0f4;v-WA~M6zcEKFRkhy`Oo^BOi&nr8d_Q!t4d!A`Ae{uK$^`QhB^18EcQAAO$1dOaz!bi5rA9g&1 z=rwbfF7j2L)}LRRk3q{1p*M)rhyVl`X7xZXUI#dO@Ha${_vC+Znjzdl@lYK(a7|~ z6TNKXss}?N$|RcJR@@{ty^Y1XCm&X*Lz2Z;n%=rXiFyn7@y%|h^;=kxexsb47@A=Z zw)|EF{Rk+&c(W2#=YYXH zj}5XX^|EufYeg6NZm)F6X7%?C&I8R|%hQ>2ube(^{`BT(QM^xHXe-HSel>HD8RpbB z{BkRQcw z@06?a)nDze6DuRR!6)tx)ii4rn56Q;^{eHk3+9F|mzxY-4A0D;Na9}an8K&#TO};U zr5cv24J>9RxlsdS)BIy>aNLUP401dDxs(rf)nhX>H+HBkr&g=gqWie5iy2`iYbc!+ zxZFTwHY)@mf?Fj-3F>&AQckQQ`+r0MHRTF*|4^5^N_(2CKg@h;(TMf zH#PO7`i5JY-@*mLPaoVGvPqF>aQ0c$48!nJUkx8=t9PjnzIBB&eR-gB?I_;&nR(>$ zXBvrx`;RJm=IoOKWmt8#NBS{yl?jt^+D!RYP46OnG1nM-#EYw`{%ezIm4(Ri2s*X1 zRoH$(3}ZR?Z!PZMOJqcq{yh_zan*Yg zR-Jy`Qmf>WBoRLxA@WA?=Bu#lyHExYm+}dEbCpqfzV7x~L4Ge{#Mh;BQ<)A>TC#qB zry~seC#|8^Tvv12+wYGib|s3SdMO^V8~OYFR}9KbHQ%0!+qU|cev`DTQZ^j8%NVl@ z=zr%y)DP|o;|4c33_GJ`R%j#DlWLvF$wVkoOJ_V&%5`=YHq2JI7~DFG5?CC{@YFLe z53A5z$oF-QYAusaFvl>$7%ecY<;jB|9U1fHUWKXrm;4OM3($|49@BGO@#0ufO^;1@ z6&8BB8D>SAZwrTZEPJSHzthvdsauBR0vUw=`0w0f(gJ$ze&{vZ*38jUI(k}{PPb$p z;lL-01?H(;z_Az#!HaKzHY{wR)7*>=Xu+l?D; zoFDt6jYum`z9V7U3FByyePLsLf$Tl5l+PDOy0Rs8nzAFPKiZ@~u)_lXq`nQb+)1_^ z?wcQ$S%a1)Us0!6QSI-f2_(Y_mc5Q%CUx!Txpzt+A{G_+M-pXmAq+~x`V!8&Q*B(y z)s`Cuy|gGl_H8n4H+KHB+5jw+nA%xsJ%AItmu@|(e;&|tWY<*cnwz@}E7dO&^vx-T za~!;44%RatYS1%D+0N!Jn|h2|0atLFh9lOVB#i)+9j3PC%4{~Mjy=ATCF6!)k zU6~XVs##t195tSsr!zh-6rPE$0=}{a5Mbr6x3(y@*-r!306zX~LK=u(iqSPm^^|q! zKGL`(qO2{ut-I9=7)xH(l(@D<%}j$fE0B$sQT?I>!Olg2WP*jbd|6G+HZ;-<_ka*w z?M*YHgtI)Jnc^V>5cY@y8P@AVGh zmj~mIvfV7R*B0lt{rvW0_s~Mch+vUf)r;hpd_!h#>e`wMhNTwu4-?ihIaOn$-LjYF z`zA~#5KPXZx)q%g^O?l9xVZA1mU;WC5fr{QS@PUMz}yA5c43=chFT5Ipv<$Yhj1(c z+M-5kR67H=Dop8bm8Tm&Xi|Dh!MK`lT&=aol`rnIl~F=;l2XusL%GZ_#z~Qq8$lpZ zC;t=OTJeWLMcnh-85I_Is+Fd~=E|>UN6nce6|q0Fo-xwXbGd5#PS3^Ucr@Ge`wGh2|P88=#0XE7~DCV+L5cw-xn6FKsd`?S@Zu z6u@)!idQS)!DWKw&RE?dHExPD@qf}qD@&*`J$7qBn-JN$b>}Yw9=aAa7Lk-_k-Rgp zLrNnY{fL35FUdj0c{Q!4PFK{d^-+t;pk2D{eUB&rH|Age@IRRZ!*LE}J%#CJYvBx= zx^w0tN$pn?VLr`5ZcTHD8^cnzK18aR1oNV>OA9#*k?l}ZRKbyKj7}ly$If;8;_Tw% zKr9CSKdTeQeN}Y|IRS5Hc!8D=Jlgvu(2(mXa(uWjgoPA83+?#9d0C{EyYm7KRVcNESrx^p?>j zE-lN4uhzvw=vzCOonGoc!hY|O(|=M%6Dmc@#tKZdKI)Zn&S(m%EI)r@NHfGYEbQPT zxU<{l$v$Z$UU=;1$V8kWh}Ix0ztb11!Z0YKKw`yn`zm3*_>0ALP1FhK$MFj1K}z(f z;(buz>;yR|@neNiZT{+gYsZgujJC2ws=hRy3P~Xvt%lWpnh<+vf?|Om!PIT)nb&&( z;sAwHuI( z+Fi=z@rZ`DK&ODs?#e-pDqOU+so!*vriL_By{$Zi?}bNMFB+@0m1Yzta`Y6RsK-q& z`atLbhaXvDk7$+ejs6Huc$^jL=c#B+Df|^NJi-#n$745w+A`{!S?>cxu&1-KfgVL2 z0o-NGw2>gEh=-J|hO&Och&9}J|LuX&W+j4vmy^WV5s=>oZ!IiId;&A`j9 zOrM$@yQ;fK&ZNLyS z-QbS}CzE;oaqdffFJM0NUlP{q7MhC4g$b^(B-phr1dg?01wPe7fTfOieT}-6?k{Z`$#DIr4I_(V^VXPqY}nwbZxDDm^k= zQZY4QI26~PGT=Ljz5C3vxx!LwM0ns^8n%Tnl$SXkYj@NNfMnvEv@mD_1EwxDPLZF8 zlVjI?2a94-!lt9us-DNFE-%|`q8YDXhM^6O?U`sl^XfiEx8b&t?_7FfP3ewF?qQpE zDeNPcFdT3`;p~y_lQBKLd~}Lj;R(WZbz=83dH7mN6niIjR*^fGb86AzjM8K{_Na9g zHorX;{TjqDP1FK?=qGjepBn|=Pgpd9n~zqUMX2hbx^cV&n&)QlFtl$1O#7Oy`NSh^ zznJw|eP2cmP%DB&bppv1#y&_T2UkJ7aF|G$%yOy@9Aym1q+WnLA-J{z+RN$DUzL zMP2|7Hqzw9de>%C)oP`<{Wl3{SmuMzcN%0+S;m0WE~!_hd`w zu?wMSCcQ59SkffLX{zt%$g`w>cGDVK#=$5sXzA0(C1zpm{y~aSIE3Ye5|;w4Lc{06 zI%q>{l9WkYYx+7oaI?m+&d)Oi85yHoSI3%fx4K$Vg3Ln8^cT0*IAm>g&Xd=ND{Jc3 z*h-w1IZ;ptqm-EW4^vHfH`N7XB6xgSP&wH)QkMMtAhOJ}aoB#9@t+QtSNKr6eSC4^ z);93q_Nxh++NRl~?n}#P@06U})=x_#Gi^54$*y>2AbriKqJ=Vsg<{`F!!m=k-95j( zui^0Sd!MAh_hWTaijkw|R2iC4rb}^OLcfL{(!;k3St)j>P%W|R_H3h)PLge`LTjZi z`I!V`;`B7g9+R}N`v!`$V_6lg87O<64LqsrGlnv3zvG7wX!x>xBQ{d7cLHunKgRL$ z-JEy%YhNyWA*^ep7@p?ZpwzIWmy%>*fF!L>M>#8AI>3)Q4dR-_g9x1l9*Ngq18bZU zwAl~H_t`!oa7Bu_L77xyndHa2mxzvr2wiEt4n=9>gke2NN91xr7!>c~T%vXk)$GOF zs<_IDTC*3w6oz&odMs9zD;znI7M5v1Y8bhFBx%A{=AGsXlIL#9aQ>GDu~?y0 z>p>$s-qQ*;>qD(Iyo8Pm34EB8$h0LyL=2HQZno6;G{%7m&5SDkxn6{GbMnTAn`2lD z!nlo>flleg(r&-gQ`zs zZ&cl7C)-qCmM9ZUK$wi5JQ>w~=Sc+&m7_8yIGqv6pI3ouOOIB=n7?iUTp8pd)vk>` z6FW5=(-mnQ^jPc~x-47_XI*GirDxM_lt7r@@Q_D@4Zn2OefJbuSpsYMt0e=YW^x4{ zm0ux-tGIzhm^2bPQtUT4ClE1c--UpQNGbM0CiQZWqoa2xSo!eO-1-W_APJ-nz?@g+ z>k5yM3XT-RpufzT6F45!c-z?MxO^$YA&XCQC~NCtK5ja>d2hKyC}2igz!?&v`FpR4 z)dJp=*MlCbok5X!NR4wRMwCdari{ww`8l7RrBzxM1M(d2yOEnS_!LH9WY2uU{4|Nn zyfV?zj;<8eFk5g39xEy;czx>h(VBe_i|&;XrB=5?M5-sOb6GQ-rW!qJWW)B`jHp+j z3^ny+dkv|e%XFnnQISj}*_hCX&%aZ`prZMq8^x zSfackvVrm*<1@)VtzO=zCrapGJ+2_KWOEfnUI(|X z;GhXi27&?a!XoUe_`FX;#gt51{A`NGh?^CvMN=KzjCL4r-Dp^Tk`)$m%a^jW5J0Yk`aT|;ZvSc2f-9UsvnI>cA>%%x=Ea_-rZ55k$MiZU%eJcgrM~;AZ zNpPH)Kf0=&o94{2v+8*BlC$xKx37p{8H>!Lj-emK@fl%nE5$a4S}xA-2F#!s0PW~= zg~y<)PuK7IE8!Bpbez{si3D^Q7nV12#bNc#m6nS4gpR+I9A#80 zikegNSAX)P*(Y%#zlCQSEU1vzHoWzzj4>_}J^iF^X*l-lhu!_Pk8=r!ihkU!@6}Ug zqdttfSjM67I^Nh)`zjY}xRti>xYCPe=Fm>;(r218Q3G+-Pk%mUPT)nRb7GBay>Zw}>=>5;)JyboIyX^0!nZ9f-EhFOwe<8d~e26S8nt& zwTioGzoR3^f*z&A|KaPXP?0nTGN=OIDxK%mZ}>bozDWAA$@2r39{Ur10U}#l{~v1o z``QN~z%B8FWtQH+DxEE*pM7`9h1Y36ME2%y`hCwch#RAuai85gMWqBE9vlZ?dVH^{ zz>=<8LI;k~1cthD=e2k8B7+V<7-W8PS2fqJPy-1aH(*Z#?Djvc*ITu@%BUKz0)b>4 z`cFB6a#W9T9AzsBmdWn*(vnxzXSZiSk-*;cRO!*5-W~CGen|s72iqhh`?FE|i(y?c zBhJH-Pcl2Bx)ZEYPeAyy$MfawEpVX@@EmGRwmd0~}7|9I#pbY4bFT<$0UW73o z8?73Y-YMJz#Gy2O{i-w9C%HGgkxB@(5?0M=Vu!PeK2mAa9T<9N0n*uc#jM$hBSDh; zA?}BNt3hlw=z%xO^xt4MN=211^T5NzKkwJA88luuC9)58M1PefbK;Q;E0{#eK zdEt11f<7{+p!NNM)$5Hq19z@Iy9dxANM^t6=|2|0H6|paX$w>c53yq7s0S$L#&&)A z%+mD}DeF;5!L}D$Exv5-m(~4a4}ab$Zo1ADAjTppFnM(Hd5SzTD5|*t#B-p}>c7?3 z_KM{=<4NxmEK%)8a>YVaoMO;p?6Hqk4)`no%hReiBLX$QnVoshZj~M*zHe2QOV@=Z z@j_`) z5ck=dzu721^Vv#`=A|&{m@9~OqVTk8`d57QDfmEtRA1cN|-vQ#H zxzP6Op(@MM`nb{~5FwR+kw}zm)NIzRl{eFNhb~B`wuc;53Uw2DtHyovK(Z5rLG)i_ z0_!k3!6Fiy&T}@V#sA{ltZjL$Dn%TgKjVW#M;$;}@g07N8(g@A6KKZbaj+8l(rCZk z4~{ z`3U3lW*B7sa^ZAnK^E8V{Y(n%EutZGWrma;JoS$k`)C4ue~jIWcwnvL9n~Z3U(Y_t z)>Ut%BYM359OJ{YFop_%N7iU=VSU;?4k7@!Y27a4aR~jsR6;ThJn)w!98)GGxK@4 zAn{UrX923N(pHw|P;c-M#_-Vbw$@uoEQOf1CTc07^-QdxbDPUHSN&W5V8AbpH>Tqr zBNBt=Z`CY`d(l6Ga^&%a1U}b^deB)ScH+!4gx-1Ctv@H0g4xvB+VpfiN-yu+>_4vX zm%KI~pUC8c3sS3y=?~LAt@@WQ&_NnOf6%Y;&8|CWu!v8a``H(5MXezbiSY}r4=nS4x5#ds1PK_YYlt4K4~ zOHhC(eKk8BLlt%Kf39@yAz;_4yg=0O*d!m;`aIKZw&Mnh|E|mP;_iv-VBY|3|ILIZ zAmSL9$Aa#=Ha{2fQ@v3>>}<>w;2!)qL@%7M7=4Zp1l9l=!A8r^Q!$?b>U@)F0ZvLe zE=h%fCQ1&tHp%H$JakfdX#W&j7}H86MRC9zzBXt`%XkRhjn|7dR0KK+JRqcGNEgGEaVl-%e`*af%ne{BpW@}y`G(aH&pSns zK>;p6XOAUrp1U{Ud#`$_k*V(oerL;l+f^#8T0eALrLwL%Ij~{PCgAx<4?_( zLJTvfuPu7dDr@@atk2`O=gZdT3UZpH*Ggx5A~Ehh?>JbnENg!SpV@I7H*qS8Nm)*w z&I}hDzv^5^o|;8&6Op}wufO8J^O0GTkur5gP31%8N#9-t@M!zreK=ld`5kfqSSMsG zgH3Ag3O&A&e^167liDKWhGR+HbR;xG!o)jKWyqsqOJ z(Jm8(Sx%ZgEb~)teYM2znG1ev?d`$p`Qq2T*M5vfVRkkqat^b2rTzRNh9|49zlUM8 z3l~E!74yVKv3acYD4yH-_G&U>Hg$V8^;pL2-N^f9KBTDBWb@U0!>p6&PX`>9zPz7p zy;P#+_w#_Q^c$WuF((G8HxxX2^XV_1voM_G5EEmNgr7GB{Ao)MvVg5-c<-_FGIfjJ zcfkp%no4fB>%Bj|obr}_{WX5$^-7!{Id0at%f|q8;}!L8OzdpG?XUX&_IO_hNsXvJk^4*$8!l?Nm3{oq$Gy#Vh zD8|LW4`-odIQrUZTCCPb__}l+b(VCBOtBrINJQ{h8kyL>a?`y>VYd6mNp+O(yy@{} zBHKxCB|u)6huWv!tDV0&`&YvW)#;S`F6&@7bOiNT>9OuDoN<}J8CO0|?k(*tnR zW?k4DWi~&%4?E;!vF`kAvRRl)XY+o&Sa;v2RW}7^PQt~} z_ZaSM;CDKZT{ywp5LCRBuRn!Zq?0y88k%+q~E4D zeo2fq&E}R~dZO@leh9z4Iy=d_<$Niq=y!7_)OKQhurfq*?$YxW5nxX%KbvHv zolD=Jo#kL9D@jZzy9tH+5MoVTcU$6tTk)Qs%O;~4 zU4HID@_R4W`a|a^c=$@mXB(WR3jRZoKY$KtzWo=h!69BxpFT9*oZ^ApPq-~>VbyH; z>n+kK?k#l5HuBnm(@InT5{1) z?RpLdzgQSDC1okhE_2LtBz#mEqWdR$fGk|($eU}s6Mu45ak?u=5`p+Ku;X^mk|jT4 zJE(Klv4;BGnehFQ_3Ylbcv0oJ&ur4frmgX@ZnalVm#HQAc3qPOw&&txJ(H?F0@uo6 zwSO*?(p!n^{Kea+UFk4p7q z+&jO5a~U_Tg}a)wOtAs8bE}gSjK)5`KXmh+fGQ;M(4Vyn@%##=$gvFU`pBBn%;wA^ zp(Y%+9M12qK9}1M>{su|_*%sZDGo0+cBg^HhF4bPPqYOIdH^CQTOIoMu9GOg$a+z> zW((5P^Um6^tn3r_GIy2lvrO?YTOAXd>LwMpjg9vUk@x5@BdwL6L^^ ztJ;Z^Qr~5L#^%lA#(y@7Wy|c4yKH#h5cVj(KQN!?Oxydu6+kQav-f&Rtu`sZJyARq zC*bkxxNt>MfL(#^8**oT$mZx9>%FftGoGxPy~taw(8I5#X-zc@FescWKqy_1R&_TN z5>EJ9Ie~Ei2VdRL+}j4|Oni^dq8^3?ZSIOr9h^i>pEcFda5q9FV^`ZP#O2f-w9i*7 z)+AuM=CKepsz2xKO=dbz3|~XD>(Y0dS3Vib1q>c@X>aA$m_-zbnCGg<|GH*|9aH^o&m=b}|6%^-F8gmkbJ(00#QSM96Ia zd~q;se2>WLoV#`c;<8fN8SmFZ{y80x_$CE+3z>)^yCSg(Nnd^!wSc5@sjG!R*@1W^+{b+UMVi0K@`A%IxGK zn)Dh@DvjUNbRP%l82$6*38!~-y8?@b##}PYUL7=r`EE|K!c-x1hyU0YWFf;omZ!>X zHvrY2R+}E}^r+N!*xj5SDHjlyt-L)~CnR7}mdn2{_uL;9L);_N^?*ZR%aCh402m?} zmCl(pJF^|%P)7WC8O6}n#20S zI;3ei8U+84N`4euoWlU_lGk;rRNLE(q zi+JJE=HkvaY8V{+zI}%;XvIRp#P+N;?4&je%LY6-j5C*Y&F0kr%XYker@(co;0Lc} zvy*z=Qa483o7sYaB~2dRBkiO@NBH+L+hx;#sMRw1tytXpD)pLDk?XSSf9xN(75y`DS`N}r(aNUBYlsC zTjlZ5ic+(JbU9>NsQD*Y&tlnBqEoi6=CyL53)miA-dQZ=eq4zEe!BegLxYqk=08nL=E+*tQDGngb%$`G#=B)=# z_*=E})Pb~E=J^OH2e_A~uu3JsC^IhGn&mxyp?Bh>-)%F)*7+pRCU@+_)ldE_>E~*B z#_liHg0bxPj0Le~*)3v$)lzzD6!xPAdM3KX18Hd)k1p`RQR80LX7`?ws3NJ^8O=bS zMa}0I+fIf>C2%Ct2Ez>cr`}Mr{(N(|7sN}(8vDY|?$L>bwDma}?``-VR|qwbpy zTLv??^7{Ae0cS{iaC$V@R;R^#WIk8}^lM7$+uO|%rX!^6Q0midm!TZc5~o!t>R~*| z2K_9zPK`5x3lw-Ftcm$nHlSAl$L`?-^>!18tB?^3PM;Bsnj)`bHfphiA>Nmrt&#)% zB*;Q~ZYBk~i1csl_c&9C1ZXA+Q48t5QEx{Q5$=W*C0&rBso0T?f-Ns*Dr^(00W z!;=8}5fmY&0v%Wdb*Jo%^+XJDBPR=AG|F@hjx02Db~Fjnt{cOxskfO+r|IG4K)JeezKpL6mxa6#y>gcHImG%lA*$-W-F+r&I8-sPr3S6^wu95{ir5oY>5Rr6&U|oF4e$kw4ca zlpg}osYTBuw=8B%6q}ip3}ZJ-ziXRe?ypqFI2m915fmL(kXz>*EE7BKK8MhChPc0t zF*HwLAvY^#9~XR;2F{w`9fRpGbF3jb3xwkG0W zC2-ps?Jwcn_y|4@1omnO0gH}~D1kY!mT9oATIm>DbLl&ypaQTPiu0Gfms?Sh+ZC>O zygq4lwQ@pmWYNCL^YXw6*_>pLLF3(YeK$}B8rf?g)CUyU6Ly28j?{iw!z*@%uVBFGki%1&AO91;D)2jS^fOsZBWfL zt9mjNo;|#8CP))Qikjtwc`L622W}P%p+3C#e3&(#_SWo;`+RJ&egRlwLvB7{nTG5- z(FuBixmX>}ln)eR32waP=gtea{YntH!G%a)u|&tiX{Kid&EhL2FdMGNEUxZx$dJj0 zbY6>qpY5AtB@gn!Mk$fYb0L-&zK*KnJbAdT)ycM6ZTRC0${3}@?T9(k1cG{;252+D z%GA+J)M@75EZ-WNQX)-f#SOI%-SF0uaoyP?1}9mZ?1j;bW^g*`Sa(r z;~rgM3K2qH$TqK35Pm~)eN0yCizBNv;Rq#+8)?rbyxT<%kA+VTl&LzHx(AAyd;1hZHpb(| zH>bqnbRk=Nq6dioAdmPx05*E#l#(cYm!**Gl?n8+`^@v;Sn%kBKd}kKf2{@BH(HhU z{IO{~bug&ZE?uBHKv0xf*Y;_?!GbHUA+>^N_}-qd0W!lvG!7BUP*$$Bxl**&Ph)VI z_S6?~YN~cSnT?Mty>WGA$@^!R_ZSgmy^9Yd`gVO)RQs>f0dWrQrY3-CdkLQW!}EfM zHmYD>MwfC>So@nU}_5e1_}U{>Gn_sPF{(lX{LME3;42K-naqb zjf;lOMo50+QH4nSL*ezmvQ?pDo`6;jdL=is7p#Q5cC+FAi26mposF_V6Q``@PRSDf zefF&Xwwhcc%AHyeP`2^SYa75<%)c#p@=bP2l0OzAm za(pSm_1MLry=MHM4bT|%+u520IlF5$zyKhQ{=aIFiIS}iyS51c9sm0i989KtjaZ6Lp)lUyfxv$VtGiOU z6WDDAj@o4FP~BSjt;bBVC-%S;B;YV8m4h?Yn4m5;R>m+z_359>pj4Fs1YC8akdqx( zMhd|c|I`PiNq{nbr_X#*T&K*=rt2{XN8a6EWdv}I@)M=1<#i(9?(_$%NOe=^a((eb z{@DJjzY0;HTkrd?IpmnVhWk=t1@W6C*JFwQD&*W7ZW(gRN^E6KR`SE_z0ue2StNFu zq}`;VkqO1Gn%4498=%xmQyS6)DPQd4`{i^hPtJco;UkPQNU1h4`8hn$E3q?CwscY8 zgI9SOA>*#E@^aC)5ROR++yFM6oY6}Pm~u&4g> zunP}B(^;`Nro61tYC4h693G!eoO6K+__U2WGgU6k$AxU|&pk>Z(W?nK)mC16zJDBn z6qoQ*s3W}Wv!DD@uS6EAg@mP7GbuA|ZH+odnJg&Y)W2}gKk*LWf3k1h8!HF8dHW|@ z20OsJKJrE>Uel!0edEPPSJqMvH)YV_I8=fgh#a2y#%h;iV?_2y)EoS!C5cyuKP($N zYneri^xnyD%k?#FOtLk(Qj)}ETj$%MD{lx}mpx6r!>DFdO3W~g+yZ^G~Wcl*^a%0GZhO&n*{nJc*QC%ka zil#H!V~SRXTmfdT9$8OB5i9Vx$VPBAdrKpWxNq(qZ%#7Kd^vF_TDM#NpU|V=$HZ_H ze5FSMx=PG`r81SD7W>|^iL@RxLhDUr2d2+sTSmRRMZ6;p~xJ*+sOX%RqbClVF4{C_5*47g^aC$PW ztOI%dg0f>?pbYQ~B*%r|=>4hV0yi0uGlM$7VJYn(9tA_$bSvoxDGL^GkV*M#zFU0c z^<`%}LDVSEd8LtWZd^of9F;Rvd6)|o?d`yHUpTs-N_Olj;pvUu*ArXc{+~up?Mh=T z11-A(`iUq>H*&JPKB-YXr%@|s)h#b2vpLsuu8UjXq?Q;ZNLcx5C-XWvv5iv4V2|uY z>(pZIQi9q=^t7aiI9%gKuhTp33rq;Ux!ee+gHR>SirePShnQ zzE3(IASBG52);&(di}z`9PD9i7!4yrS^~kP%~gemcZJ!8@9GnfSXiTnS=ICouW5K78qfxDF;Mrp+nka~u{+P`{*GCb*C>v8aT(CXT5k*ZtT_b3v#ydnTw5 z`{yV(Br~iUXvEY&#q~#9oeUYQF;rzcydTH0IG*^}a68EXnSUg%jzyEdc5qcUu<=vHKQw=XWl81u$tJGFC$Bc z@QISq{$3#wyqPt$1-eY2H3DD1RIl{#x$JHO$#3AJhr{toUhWey> zm_a_fm{F$G6Auk;1h@;y4LVn<9z>PMz;UiO?4&uAr~1(&A=raA9_;pXP-1<`y+XjA z_A@F>-3FvIv0t<{kpVPg71%?C9Xaws44Tqou$hx{)B0cyLHl~61*s@NTtf3fWuT=JZ%YJ1iWEe8G-+5D?Pxtfv z{dpIh^FGUSp69hZdyE<2HRJvBrO~oU>#f!|@a>3f$a3_Rl&mNv1e)b`e=pVtLWgi= zSG4dZjvn|+Otdd8H(tSN=1^Dvy+3}9Jr1+^m1V}!z|R~EqJ&QaLDJ(3cGbZsC%1Ry79v z)U@q0DOz-%6B(*oj*ycM7-@x1hj!_kud#*s0`4U(v;0> zh2<=542$5A(&M5LILd~M77uFfDMcOCaJqZJ%hG@8lY0!cq2#6UzhmECn&de-o0G5K z8o0d-j!Q**ySAO(c)GreTivxKw0v&R+xlk|Pd)r->J4YOg?|8>JT5aK!)kx+SZw`T zPJ`B|epPG&2g_CtO=!_ZiFt@Q4#a+sKmYYO-pdAFv{>Hxbb7B$@Ivt4SKwa4H5<-t z|HAD5_g{XeMM1lI@5N3xd*JuKQ|Z3LwTSB7T1_R7^DpYe4*UC?DTdMpc=GxVr6_>c z`TzWuq2-+Nd{JOhls|;~eD0e6kl4ha+1`Hp7gGud_Z7|rjO*Pmbp0Z16);f1ttj~O zz5hSIF$uhxH12WZ#j0&lW%EFu=Kk0J_xBk#TQLlpZ_BVCIdUtODH1dR$j9aXj?f*i zKpNC!FH3*IgXE(Axp(}2XIg=8ksf@?es1xYi(=}lb`^;D*LuTHvkFjbNXGgKFGaJ& zR)~NikuG1{(TZCwEb#bOUG7;&sT`;L)WK?#uisoCW-!Pw6oHeIZ`C$6KjIs!`+wML zbac-`9`>CHkjDJa|0zMZ?(i#1kv@oI5p2i|!6CVjztR!l+QSM(Sm|F8mM=+p4WIs) z{^wXQSUg!>UWJQKB-=U!uFHdl*y zy4Tce4dNGBHGbb;kxx=Xr7iU^)`hWNY^a8Shxmt|k>IN2n0bu1`5fk2+q&$am~BsB zBb>be$ETL{2MNU2o|P%>`#P6Uf#!)!cf!D$jX5HSn4&;jHOP7T&14mWO#byJf^=a! z6GfkT=Z&6gKd1}n68pJGhe3*60Ej<_qm8#D2_iH;LKur09s%SDA;n8%xYuSG5OL{k z%tuRl0!BiU?tmK{W1ibcl2ut(R-LB;ATvL6BosLPUGtl$ef{TerHSjO+6`rqT=mNA zHVbK9|4AGH(MB6Erd$9cBC>(78i{RuvNVoYvGb}EX=r9nnCj)N`P^XpkM~VYxLfBZ z2ByXm6*%Emd2XKGhGKDI7^iULW?O}SGPeBt1g@HbZH-77jd+RGIbEf~A;qH_H2lu_ z_acCyrp*bng)~KoM?n;tG53dfcdxdH=B(W#OPBbXb@oA3{@!V!d8u8d5*(YYU9JpLcM{5=PLuZ(3f z`Fy=KlXuufbShl@0i58aGW!WRkZxZ+9t?~Krr+sUM-~rnmCiV}ng!SaRG>jx+?+3e zM=o$`ky}(~}%g!oI*_01^_}yCyV30{--;M@>2h^~#kZ%p_5XI4`OhQ%wLrtHsP{eGflCwI}ZSu(B~NbA}-?+)J4+$F44 ztv9>I@D`4LRxkJX3&#p~?XSNCV_U`&iS`4M^%?}jBvXyVex5$rhrfsUO95_+oixt1wh#Xh08Ek--aX=yPe0i;vhvgb^RlX8 zQ;~Kd40dnzi*2lxDO-nKUDS6z@Q0mnN5Fv%`JBLEG9cNMg2fSESu1^kSBa)2$p$3( zubWO^b5JFR1$FsE<_*nH{TC#sn|*gsjsu-Aopyv;0>r_g%x}`Xc;m!YOOD4?xb9(Cy`2 zqseYlfE`H=3M&c)l2-WUoox8sGKCn%pK}{tFyXb&PxFbIhK~K?jg{{sg-3AM zga{Y-#KuHyT>jRj=P0MM*9X6Nk3BtRobsn@GC4c8Gi&|Aa&5k*##1&9xF;pWJlV8n zbknVvV~8EK9^3cLeT!RFf0(p1vHs?JZGBHtr#{DMi5X>ppMtFb@OOj4zp8X;mr(^W zy3JDv^WCUce|alc?j-F3@=K-_s$CAzARwpm%Ccbk9M>mU{qq9a@NIl*ihX?eth2dV zFARX3!*7?U?ll5N(#-mlftz!Yn{TrEG1V$Q8`8Wr! zGJ#?KYjeb)GBEVCCYov(ZJ(BpEWXem4sQ22tNHQU1+vFg#Z}MXHYgLv>2;Q|)W}5@F^OEjd0%Hm>I25p*4C7#QLdUaQT_u8JUcjG(u0sQEv_j>(PqyZeswaK+_S zuJ#weJ|910T<-k!P;N5jB`gd>$&jG9iy@CRx^ zVbSXj7wQ2-x9~JthzBIYIF8&fRwPx+L_^nP!(`UhPZ5Cam8rBXLjOTl7B9f|%<^0z4F0Eyw{&*5Q0T)Z!-<7)NCbC`-IA|i8@F3(;0 z!)+u+kiQ>+>J;j&D*C<5DIpNGktw85jF`goe(W21u`LTfRTdrbvHh7W8w_D@lq^*T z#)vq=Q{SMw+`Tq`H7j<0hK!5$-}{LB;Y`W2u8eeu$SD%1%d9f~G)gG#aQ5$YPTJE` z_QHX|Aw!Sepr@^gbvNnI6LPWW~1b z_@!y8jZNl^w5vz+xw_f35HoQMcKOiLB4Y1a(3O?b z#UL@*z7bf|TwHtB3%qTDH$la2H?yGu`m$M!?g>1ebfCLIxC^C!{$IuBHsOZ5Ho=9_ zTIHzHh<@Z2)&}Om<9bF=l>iAbE9z~4I`|aIN1qqNpDkX942tRQl~CL{U1}LW^|;^D z921{kmG6ACdf9g!w{B}*w5XSh)5h)(BR~Y}8Hi&5%HOKL-Cq}#>dqN0q#bGIp=HX< zy7KU(oL#SD=X!LLawsHDMOL)_1%97xC$P=JR*a^mSR>4}mN&o4MD`nY;pJ>Vkff~Y z`2@saOsGm&%z(p23bq$U4Yt}eg`?gEI1^Y>wgbB9T*iy9>6 zrZ}^rhEleBxEgQh%*g@R@CJ-t6Z+AAI&{QE5o}cT$I?O8gBG{mAa_X!{{e2&OUJ^MI{KaSt@QVP zho$fG5^|-zyF`@dju+7|@GRTW8p7@@0FoH);lD4aIV&SMUbfFB5+E*8yU{+|adqhK z$k%Jr7(m#ja}d%_%pKH}IM+3z0U42i7dHAkNad6O@w)=RX~%aTZcd8qj@0gq>W?Xb z_kjxJ1q$-(!E=>)_3kf;ali5GCxGx;VWmy26Ijh#=tHq%FHfeE09W0CIO$zFjuWUIp@n5}0RL`rRu&(uAxTG)fVe zGfVUdP@YVuwWmV&ieVujCLIr*%dbYLd}WN#Dj9UsG5cc|#M6jW$`)X+?^?-(aR93s zpdpm#i0y%~8vOV3+*kt81n+$H&NhH`*Y*x8q{AD%Mn~7hM6XxAP{PuTg0_Y_$5Z~j z*R;g(Z6I|J&MoRO2S4QcKR*;Yu(097=o7`?Vj4I3-Ww8!K_BEFNDt5f=qOk9_pR*J zYh{4s^Gx_bpsjsoW+R@WoftsHHfkkW?cdAeuD2!PXfrbqiyG`$rQIFd4e1u;fy8$V zCG4&>$=I$*{h7@jY6hG!VvMMTDfsPpv*(bMTyy=|xjP>j z9dmMvg)%_rf!);h*LdDdqgU`%6@1HeQ-}^}UC>SfO7tWI764IiOb)y+*cOTu{M<*d~BPP(GHTidHxQ+BXn+p#NKjT}m zFH=Gk_G%MblaxkrgI$V0sEVEZ_p+`KfzEP-6&3ja$*<4AE|v?9Q^!9?HhF)e>hv`qod zV#925X$1{rT%F(5>8<8^pZ)r)cc414Xz`a+KxR4j?>#k-PdLWjbLDjIA5@Z1N%uiH zYO?E|nCk`R6?o0;lDxs4FaPhUnj71S39y{f=otUU-2#<+%Kq*iBlM!`53pJAKS>A= z_Nun=yFyWL>9EHgc_7Vl-M`Hc8H!+6cM;zED%Pcdx7rCYbyuL=95AIs{yoTCv@}8e z>o*$DenXAxryocknc3B{`A&cw)wLg#odIh5ey`T~>wD;FPTo&NoAb5?`9?ArbgjJJ z+bPqJz&4RpnUst`RfALqTvGr0bLx}$rUUdhDWws0KGF)$FJ+ETd*M9uWRw|sj($Fv zcWnBRT;+`3%)9*zA{lf+|2{<0M>lQ-+K9aZC71gruz!!HEKk#afD-e>HS~#Jn|eQ|b|ukqn1KY+_? z_7MJGUp4;oi>ii$HOR?l6Nv2nj~u^GU{A&i1Mu{iK4N`*g%Ddo0?WR~J=;Bgrb@Sv z{gWYnorvBYgw%6E#T#n85L!+y?Xv=$;D(9$pxyPS+Z! zd>kwdX}VUnG^`p8{KejRGsPWaFFO=@U+&2KrZ%WPwXQQbPxo^$3>&i|8Q~F^)84Ik zP)jc<09UQ#S~|s1NNNP>e!xETha$rV`6IgfyKbv2InI2h2whB;GME6j zWY{U2h<-~@E_HXDx@tH2g2}#7gu;kCYq?oPrcvfIXrE_d1KG3{Sav4+Q^RLn+&|s_ zRN$mG;S})%#tb|K6#sz=8M|?e(jfecKnMb);rsnf9T?SXYS*#z2J7H0z*LC{_?9$@vwK7N4Shnto;JiY1Y{T19OU)IL^;EyOzxbs2G zw)Ig*U&&_z(E?b7I7AXR$N6V&F!)_7Tc1n-Lv4p{1!$;N%J1q#3Px|||L9S1@6QSO z>kqnVW>+zRuUhQ_5@rIZV($9Q?;lM|b8RL8EI8Q`TwUQ1{ji4-Q6|9UTii<3@s)kj z58M`jHN@YteSlZmQ40inU}-&|r3KO93X${rEqTj_NJ+_aC+PYw)pXj3)fs;Gxnm>n z-sXk7$Z{ROW-qyABY&at4LqeNjQHKQ0@$?ZYT)}jD{jPTFoNH~tZ|C`o;TK#ki1IH zc&WM-To=fy0v&z8JeGNQm=!6GoHKP>?bs<0GME~%o*x6NB{?=n zlwS5)uM%^PtA^@wAz6yF9aOZ_91uT0&x5O#vnDfu&mfvXrvc?Ekn;rn(!S5BF`KvF zcE^sGv?LuXjiHMVrf>*qBZH$+iB<+8e`IPoY!w!EY~-t?CrW_?U?p><&Nip&+8UwF zHxX33Qb0+PvqgR^j12UWfNPZo2@62XOVRj2$8!@E@@$keUkDq{)*L_e&gKPZtf66Y zGT@3TiIHB73@HEa6hOS?5e=xhJ;y@tVHH={l%!TEC~yPm7QQ?D6ie#v}?niMFq z^T)kAm)eo*S4&|N2=EByklhsdtLkA7UeKey8KX3foxOm(k@#hZta{)*t zS9$}tdT0DbHmrfdtE#`=fvEQ|>LL*QBb@;PRj1xiT@h3&VF`>g z4aPS{?P+qU2@iW>2DA^QoN|;>zGJetika6Txf7sjf&2C|L?Z>F_($zzJfZOX?#^gu_06?O9V z7PU7667$Ufc-j*T7xC*`96-EtkWUQbVbg)*$wU*MXyzgHQ?BaMc)*JuG zgVJwDqxEV5xG9vO=RdTDoYybgFeB~oL6v=PB1d6kj>Ne@3@e&W@8ajn#!Uy~6c8yz zK{3b`sT8V2`*-yT#NVT!s0$Gf!##Vgb?)}NeY=82aQ#;OTy16s z39GaN!wqR9@ekPBOGBTQ!U(>gC_XIFqCWX|Rh!9LCQqEgSYn&+wQ1#s^U7VAe2RcKFq-DmetojRp9arCx?m_Rk2 z@{hOsr9*_KM`hy(c%eY5$>q81X>J_{l{`k|(0O3)rl~jukC}C0?g0+9kiO&jSD>>t z@CD*y43HS?YE_`w>~DI9c5?xX&JtXH<4TR4p|3Q?{CI70DLbAaOF)q1ts zB1_cSB2d#)BP(nEZ@cBK#X!~EH=o&OfYM|KyqA_B&Xj;++dsT#WGt269X}nX0i3|j z>6gYx!^AFoJ~96rcfmcg;e5x`rlun&VEXfudrp#{fQg>P^?1Z54`iRvRehZ6OTYF? zPT9Q-o1Z!Sf_JR;tX8RXYl0fk4GQLu`+NEAJvJTY z_v5WhU|XJTvNZgNuOiEe2{7Oz1Sr`dVubc_o)A9l4>P$sx+unJcZ(TICQs>P@Hd+) zhc{B|Diprk-Wj^oa8@?LXBtGG8CT&oz|SUZug`QYujJ?FJ64CgfTH-#CLpd%k_AE@ zkazFiX2`>{*18+%a{kwgABZW=M0^5m4l@iS(_`XHH|}loE9K0U z^u;=F(-RUSrtuS(Jm%NwT&>F030w-8$}&+2l6g z=MG0w*&YsGG%~Ytvyj2hOg(KGs3eSNaSCPGzAk5KFSk%&(7QO zY`TovvwB@dh3FHBgO<~pUvIG?VPsA&k&rh+nK|4o_?&vvedD3J?w=!q^M zN&ZxteEp>~Nxr!wn7259e>Hekt_sI_$rcD6*6hs0un}=8ph!Aj42D`n-#oti`ny%A zr*O~^QY(d}GKGabv|f2hY@N5!Ll0fjITVwNVMM|2+it}z=&<;ola^R=+0B-YYC=P2D|z7 zUtsJKr+o3P5hN{6F59RCPE)aZ=Jo>M1$eVzc4`toJE_*~KW+@DfrHo0X#)*@k_0#R z%c54qB5oGD zQ`4U|1gNmd%Nhhlq&^lQpwR008#k%EY^Dh=N=mt&St8luO!ci6-e0~cR|A~vm9CR5 zENjT?af?|%(de9W^~M|EWpHIff-Uh!O<-nirW3=6{$Ge!tC9fXC_1q*APyEh zGMMWGe`Nh~x!;08qj)I-TeWtz<4ie`ust&pp_8yVfS*|(;0!wHbYV-s*!;(%m2edU z9j@(_-jESI&YzDDx*6MnOrI)d66tyEEr`^CTqo9CIemIOwiFk3z&x~7J^^v zk{O%+`Hq(HSqY2Qsj6sjKqr_kJmsuD;ri+ajh&LN#fb_8_aO%l%7}yy6Bl)+*u}e! zbmie;o}IY-cqf+lM*#~vd+hI72$@8C+=D=;CIS5WR7WXux6Yab1p>WFBRvzB=U8KR zUKk%26}Dc-FKnD}<|t_$XlaDx0H=}~@bDRz;#4y)(%dYdxrCx$jB(1qRZDk^Nk7=& z`k`h{DRS;8M|hboU9Ol})lAp(Qj)FQe1OqPSPZz_|JTl^nITOgVRfft#&IbwBVz}# z^U7nHcj^V>Y%Gg7N>zEM&ZC9RRW~D$~#h(W%Zw3CGulXwF?pqq)pR7YgPX$ZsuC!G`s5uZ{xZI1vqL`S@oL^ z_0?bl#mzO(JFT{XOkWiql+*_h8PkwiXFpI=cfx2qD@GbgM~X)PxldQi_NtEY{D*OO zO6k>?frCraEAdH)gcFM1cgnscb{f+bZD*8Nh>`kMI4^UL{y4{+R-&vXi?z2t`Y^rq znx&^k8MPcEG~Ot_MRV@FT3vxkDU5X?gewO`lE;oF=q3@(DrbH)Pm0_$_vxEDmNoBy zm?erSO_2fq&QB5@@$u;QuWdbDU7~M@5I$vZaKt%ZrS~FS)Jl=sdPS9!?dVVg11g8m z8adt=pyVk@@XzB>U3ujME^KzxQ1M7kdjF%z+dXFXOQnICP==(@zE4Bra*2^gnCC0I z+tV1~<#wrIEqG`Bcyk88fO^;Fo`kU$*$<@G2~;m+;)Ib@+lO(NVC$pKRaK;ULs(?~ z;?u(H`6X7s@G?bT?eyX3GFQEJXS_>t*m;(9A?8d{v6b(lV7_S6`MAsRtDb@0OD;17 zuD4=aXtN2Oc^FH>CRP6#v6-$3KhiPr!D@*Rx8{kA3%bG&rD=>|skZs1zusE%s}!6!;nY@YmM#p6du;h+1n>pv5? z18u(fPkmMUGfhjw;EI99vj~CyiH~|6RT;XPXC^dGWoNATDQ&hfg^rBWBG#zf4O*q) z%$}rap63^%=G24m+ywtCgl)0q7rJYU_wj8{{f95GY2%VXL_cL#8jXTG*knU0vQxEZ zRS2`iw2(NtTR=mGi$=dJmND3&0TpII>8crZ>*_42ZhDCk>7?eVJM1u5yf^p#(A@v{ z@7y6LRU*G50W^Bp(qeD0qn>_0{DhRvM~jC2vTv20FPPSvWZ1$CY3b~vI;%Z@OM``W}2 za>Ln2z2m`EBKrBUUQ4o$qHCX>)FHz5c0DiHy?W28?!G@EHMO?Vxvj7@=d$tg>b%<( z+BWq#CPBdFRQ*NYPr~WdU6XxxYU3_oHQFOIH7?6h@apWo(XDIkGIpz9$gl^WH3u?P zT>G_#FQTtR0C#6)RsUv^tWBNwm_}gEE0Yat6Dn`?z%v9kG<~4{2B~;cQp(W>lMf1rjGx4O#A4R&zKtZ%H-42D7y$L11f5y*YKf+-2JtMSQb)`{t~1^lavl`otl>{mZM&??kLKFKe3rFJ zBV0AX zWy{+Jc3fxMhdZ7qEJsLH%)G0|fq8xlVm$4l6~Jr43ZNC0PzsvPb?y%UOZq%eV^jq; z(R4;C(G!e{!~T-%iP{8W>{)#y&KaI%KBr!rfxjrg#v61Bjm$LJu#1mN#l}GYxEDOI zH8!v3s_fH~5VyYxi5HEXM{)}~q3|f+g_FYEy=anq%3Sy_0doyTEhSOTTbG^Lj;V9$ z1$mtC6if3lvN<`smUSb;(Ab}oRCB`OlR!N1k&Os@c%xp`SbYz3G_GagO8`ZBZjOMJ zc7QQ${WkXXQ3v?#O=Yg9X}&_s8U)=_-EXGP#YqhtN}2_r@Y)D&EpR}s;q~9zl|h42 zj0;6e7DJf;$rQa;qAT@diyyO z_F=ElN1c;K(irgjg4Y@vW6n&hf0x=y5EnKy(TobSSAByNyzd6l(uZ3 zGNrDn`~i&*5}+gWu48W0fQs%@r@)M!!&D6-Yj1DLA^bJJD;=*(`ciH$KJPF!HkV29 z1Qi|bVCJW=LR33y9#kJR;4Ch*p6y4a*VTFzWmwz18;^fbE{S%#;OU!8RRXJ0ZNcge z`X=CukHd6GL;H8HoZ~v~$x?qqYRjOstTAxmgC>^GcT13=VqbZVN$fI2I~h&@G0^cF zu;zU9{9+gF#qcc<977B?HN|tspu51%z~r*C&ezJVqdT)rY0Vv8wXUc6$W>F>qkK!I z3kl%eElrsCbcq_2AIHt=rfor-ni0&5xlEterx5uh`w2|6aUkat&V$WK=f8 zvFNP{>Jz*6C~9&76%vHW-ptjzP637(eZ*S!O2K@D)^12THusu0EfWmjSJ|WPl=%p4 zs58`3$LNXyS{D&q5|){1T}{%8!o?qR@aL^DoQ=JdIg*1bp>2J5-mcF*FBZ2jvY%&{ zxvd8Sr7(t09?qpFD><00Y>|D>&q0}1%2{S>R@Acdl?|mLL?-{5>i5Uw^>Ct2XauL8 zG$BIBNiL*>hq)9ss=w5lz(a8#ur$rlDb z&&(xgKL_w zMH4MVQCzLW<%;{{R>XeEXHd;OWa@SB*tfz~eSjY0z{mFaZ!xH7!iq~t7?`CU9X;lh zVMN*udLd%$c9-X@Ne-}$Sqrhyzd%vF*V5PghL}KbfgFnsAF?rxhSI>ZJ=}wdmSP%D zu+4r~-<>q$`5G;?UYqlR3`P;bCu#!fbL6lz>UQMcYSeOEls87B-=&qc`vAF=zStV;Dqw` zcPl}16)8X{xNG19eVN10`|s2~SR;L!!X#UlZ845EX1SeQ2f)K#nJSzS`5>lhH9hlX zWNg4I36^k`WqQZQI2bj5b&PV8i)U9gMGlHQpR@?w;eBZ8l zi`=e(>;rvcrHs=9(>A$)Cy*c7_5I%mJ6kzyhoDwQG8#{Gd2~p*tu%(Xuiol=ZB>o| z^CNI;th|1#A_8P{o{;+x1oG;tzB{nHmF}@Q$86Im9$)AiI~IC5iPlTGl^uszs>O4w z{DHc5LzQ5?M&vq%(G^W8+HPhtmunYjc$wmiF14BbJB*i2cio>JUw9<_MgYeNPd?59JaE>RGcDMmPc34_sr_1lB+Tx+yX}*V3L(HIpFnvq0<> zgK12Tv#px_5wOlTXbK_{yCj7#A72B)NBW+!`MD)@sAdj7e+OY^3=%w-(8#MJ>&t9u z(_cp{En4D2!_qcWj5RuFi!|^4iLs4`;^_`1KJJ&$nzVlNE3SxoX$q(zMY(1Pu`sb$ zfSAIxg(!&*%0qhAqH53GG4icVm3-2Z^}^fhxe+HCW~?;<4?Zs3I41^-eFV5@EMY;< zwaPg{ZpIC@GIn_GqiUiPTfIL^br82#G71h{ciW3N*ZE)fiA{IMm$60P-+J^M<$nwYX^Jm>QEe-Pq$=T4W0>*eX|j}k6KPub zwh)h#<87nAZxQ7!j9i4{9(mSbUydx9mgA~6KSgkTDpW(Nw!4tUBHFO}wHxUWzF{ zRP23sPUP!Um;FOx!%{ZwbB(6L)KuXa`UnhV*+i9??-jt2E0-^&KTt3)8<JEYJp?bEs@^|ucuogm$e3(ay+G_% zp@G3<0JwP8p^K-JK?10L;zf6BT(O2-ONyCR>{GkG~r;|z^Ajp1-8&X_J z?Q-Et5&;`gHFhLNRn_ds*4WKWuUT?oGWu5Io5Phd^K0#T9baqiYO#n6^S`>uK3@E- zddGSOqxu8C60(Mq$1bG=bmpk~wuKd2kzEz3uPdj>lG9^a(B;&3Gcgx>lo9ULx4k^fu)#+OpK{btkl=R%@w zVUAB8y9up79O$?REvALfv(L}I${z?g18obsH%;qNyY1cpT=(}+UwEyox zHsj59m|wmdCmAA57Wt4GVZ-itEq*rXM`I|>j=8z^=C<#=$L9S|Qy(*Iyx8_v{th-` zpuM~S<#Ubv^uwEo=o6bw86A0t0}3Pv!?=qT0U4Zk9a0>uBT36^R3?^}k%*1_namnF zovCwcd9SULJU8$Ag;N9GdV6JlsT$PkU>S&dZlN|D#gD2l`*e|q@EL~pQev)!%Q2qJ z{t<9V#Tx(-&k@^85g=kU-vih7bKJe7VF$Wy>3!d?i`aZ6l;X*3MS`U`@GS0FEysHN2TS?QPH_|lu}~?sT#ft2-%-Ae z%~^Ssu`}Pas$$z*jmjVR`f?_$W;L-hW_+ziXM?n*OiSB&(*Up39!SCZ*PbmA+HRf- z{L!Xnml|WEIPd=D!p!S5M08cLw@W2XdxMSRu~4PMmi?o7val$oJBGW?<|J<6yJ*O= z@Qh`nA%)6!$y1gfqDf%W0ChYoNe-kyRz$8+8em&aeP*#*#FHmMe84Qx?fZXyF{ z5}G(fsQu5xzw8g&QO9k+Ha%?xE7WRWGLMi-13kM7nAeyyB2WBieeF^WTXv|IbWMw&g?ydM`iOo&`3vDVXe9RS}mr?XS?fpnLuyd9JfwBqIhRrYK&W!a{dUz(@;FD zu&yPaw49?wx)Ulk7d!hGOt8Q1CR!sz8!mFWK8&}fVZ#n4$nc->Zk+;6tX?E5FUPg& zVzy?l0$#}E-cxfgR($@kk1s-?AjKXYA{{1j8Lhs0n@=h$_F>OhlfY9Lo5rUtSm)sp z$+r%SaYyE#9~(~0Be+RqHIE+wrsRmgw(dJ^3`-hAg+I*esP3Z&q7WH(4-%AY= z9F^o=^2yKyIvgJ_VnS^O;E!(!By4w+? z9I3A;h%Kn+1JjZEJ>&vPi8SxtT>j({j9^B`MKCuonN4Yg$tAf}E~?53xN#-Z zHTz=~v>lrN zHju`-{*1ghEH0D^`i8WNkF7yX67|yw&5`Y$4eIcTT5jT0M&+TnsT|P3l}$#EG<4$A zn!ywwm-^p(Q*RaEwNb3UL#CMYQ@1_5K?g39pfe|UY@(N^3uIFbKQF_oeTT}iM z^ka7a(pW9$u&GlWbyhNj_KfZ2ja#mpy`Gaz1M5#MnnYsHGOhm2g{=AlFGZ8e?ARU3 zHymN0%hbK^bNGsNn}*odDL-mio>0A3L4HlWIwhSz65t#0!rjuvFWtne^qZK1jT0VXa0VXo7;7yt*i?znx+VVQCqg}l9yxO`PL{k<-33|J`xN3~a zac=SGM~w3k9}s)i%15k@yqMW7;@F>NJDT~PMvW@iVRLu#y*ziv?n-^})-xV@1>?9t zwpN}?6c*1Nw|q;5z@3#HS3B$IxM$Uajmocm2t{#ck;{4(e$Y8V<;>?BDK(CJQr73Q z6XtUWK_&Id{Zp^iItCbi*htO~^t{2ZNAWKqoEH1W8wheZnCs^H;FWfTmNkA=E|aOY zD@CuwOXhl*v9%I1c^IrQ+)O7=6r#4}z@a(2jz!KYFE|LDYF) z6Fj^+@LDvmyb)KKcQnvh8}@TG`=bqd93S^%Rd>*c!1RjO4H1p)HoNT%3-NY?&wX-2L$h1QKPPrW zXc;EQCc=$k6xa&aB9KS2RWU9v{E06shWv4P);-;!{sZRK6hX6(9SLg#Je7;@KoxL3 zHlsBwwgl}d7T^O*k_)}%beBy$P%NimS$1ocUT183edj*9Q@uZiMdI=#dW8s=@}-S6 z#?uu_Q`RtQJ($2P$R9cy#K~QpoHHuz@Y$|g|A(n2l<@SLkwO@M8fbjl^yOFy%veo) zc)fAUMXA!C@6KxAx77-TWw*4nS>CE_%LYAGXX8Vcy5YH#7N8yLag#a1`*xw;@T*m= z=<;>{eCu9lDvGigm8E}HW?H|+Abh5C>h4C3AGNa49JPd zv}jR+$)|%o#-2`uEnT)lBL)W;=EAw%qIbl(7Uq}#IE6pJ_>{KQ8wF^f!j*t63Cy#g zSC0T^ROS79&zP0piEL3HKx7W0OU0UjZN11{P?n|!QhAsDR0QUt! zE+f;Iu~p-!NAF*J>^to5Fz{<~-Hib*AFd^sXyCJ)s-jV)^@c@apyeB11XqhmQP@>$ ze&S;HT$wN4)uL7dZ)bPDUPO7u-Bmw7a7cKnt8u`4*xjBfBVUzT620Mm&avtVY5LsN z`jSw*^kqYf?GGxE>{y3Q^Ku35{JzYV+k%JvxsejC25_i<6wEwlw`qkpi zV^x8rvEOuT&3jxQ+cc7CzR#QZk#D~!I~#y^1h%bs!?r?UqU4h2m8%o|RsI9m_>h zHX;o#-9p@1Jc{H1Z@Jl=HBkma(>dh+`oZ>CaUmjpr=%T@4Yvpw;9iT`gr^8cFMA>2oDO+pTV_WHRGoxs6(DV-P}qa zXa|jq=S6b&|2#Dk z7p_E+ky7hL-2E|lge=5^nq7G-?0AQF4FjBHTU)!6wo#MhpH$ z)mv{2u;HsWG?Wg*=nr%^coW>1M6!WI5RqHb&{mgbm)(?Ps&=rluRX%k1f_N|y0L+f zmT;f6oaa+DZ>m8E_u~|d5msHuJ)TGfUIq${E(K$GpKiYmIH3gN05k#fcvOG5atVPL zftS8$!&)!zB!w?-O44UC7cK)8$vHGTayiBM`1!|ke<}Mww$qRcD=?daTog5yUVNiJ z@Q`!?@$Om|f$KyGjZ)rF>VBcu$k}5U7&IiU^aUo}6swptnbRFnODDztaA0#iRo{d* zbAdUUi&N}Yr$_2u)L|BE(*^SJ(KCyK>hOAX!-U~4ZNB6H{60HRH%HZ?WFdFH5x(4- zrc)#O!tRA{oywp{vu$@m9?rjhHW2ZNntKK)9Z!OURs|584uH) zEg}vhFsa9aJw(BI;h6fg9yn zeQ~w_pkGFH0~O2~l{oa2n@2D^*11c3Es`%zZTLK;qcksGPQT;!+x@D`Ssq`|OTB-d zegn&D$*SdG?_tyI9@Y|~Cyi8$b9HPWs;G$&L)b{m&NzuX#P?;-6x*Rg;4WAKF713O zqel(2Vy%50&HkWM*j)#sGs=T0LC(5d*KIh>x(L0y+|phT+R}Pp++jFls*jOs)4?!O zd&4RFM&_>Ao>axiRJr-P-*vkPGxLZ2;Q=7${F6z@-0qxoxCS__fJWmJZ1Y1vTT7_z zwM?wm#vm6)!ZRXy;VKY*M&3GE)c7{Zo|WOP*yqraDr&AH;B*2`-}zn2h;>5+h$qsM z3=-|P<&lC&%YZ4a#%ewyV2QYjIb1Uqmdd&cR9P4}oh|$N$38-8V=65Y7HZz{UCvcN zu*B#};5lh2odWF`O1F| zii5xX0#dZ6c?%xn{1aVcQh1m(U@3Pt#})qEM*1gB)xat5B^6U>kLQ{B*6Qz}u|2VJ zww6QQewgiX08A9&|5#!2!+oMRT5){rSjU~i)i=|VW0vQC$m-&@{XN}y9Cy|ht~Isx zM!GH@YK?EMx6vRFT`5>HxDg|yM~c3H215bDAj?T2Q&9GRAf|M*H}#Ik?3>ab<4-8kH8t- zHMa(hCVr6r`V>-dfG!(KVM1aHp!DW%&g)HD4KE)KKOVXrXyyzTz_rHVJl~_F6vx^k zUcqlZD8%&&pyF~;54{N_^`yU7_>wUl~@|2#XeIbS>=HU!vYwoe_S zDl9Z2w}+OpHvk{uL}`p0Pkqy)MXT2}iLqCt70MPH#7_tP18@K>%oc@jCf#+Ot4FPJ z=CE)~Iz;L4Xf?r@*$zW6A77+y##l^}Nmn_wJg3K56R=%AcNJi?AxMA8&vd*k{3-{U z6>0P^LagC&a=pOp*%&RQ#s>!~Q*cM1Tb^tgxJ8}00D8de>HhX+mF69{3fw)7=sB-f z#6?9|#Y&Rg;0<^uMET_=6J1`ZQ2)4@x3=YaqU9)Gs=c+@ zX7aM1JF^T)y=T9kgJ{i>{f^f&8UCmnEn^k+72E8}K$z(7yQl=^P_vno!zK@BDRgP! z)&ph!>y!c;b}2%Ph?!B0Zm$W9P&;cfpC9ygqGnWDUF`Bi+PM>Vf%%J|wQ_9o_Gh-6 zmpa;ti1}YaQ=FMV*~kkA#BUI(IxY4%D8JMz6N1UzQxS?+Y&v_ zk{8;32cTpbSF35=6U=mENXLM#P}hX84<`y8Pny<1b{%&_Lx8lA@GVwLr8O?1<>5S;9lSEGwv8Bm6Iu&JdGNU=&r(>8p+3>eF|F(H}VF$Uwi_ zD25ZEjtdwNoy9lH}qrvUU(*E@lfG1EY$t=oKh*Ik&e`7E`XQtcuutS+m6NCs9qn_%< zWM3LEHNh9_!oWBV{v3yRz>H33yCxS<*Iwk`Tjt9Um>~lmh02<;6?*Fg>G??4vqDP1 zsmd;>^mK1v7VgeiWuOp6U?%kTSxf)5uBD1Xfkw1h2C5>^bFF9w(it+Ru(aw|^#^^{ z0U?NUJ;fQ&@~eSxMibw}LCGwzvT!I!K3xb0&l>5Wi6gG;ueGM2}_n5d(Z$u*VVh`EO<0bGw+6^;Bcs@+&#Td z;}D^^H>hN0#6L6P^^My=b!gBs6!C=Q@+=s<4MC$p$GZNB5)qURj#B0EQD%TyakYQG z(~99${I$FNTI?-T_2@t#2A5%OhZN|LT(>MT4%x1(9LW_ zcSzV?mLcWUM{;o*3TLt8cCFQ`^`!xz)FvEQ0#5>R;YW@(hdRE_c?s&igmkif4VDsw zS$;Ouurg4NTZkz=91X^5qmdy;2ntdBV0Xa2M7E zl~3TcO%bzOCV#lH>G-l;$>XIDHvWi5awP@SSU>XdSZ%&b4!itLD?5YPM}4K;@)vh~ z7kj2x4UNfqz|B+tB&fB)CZw(MujtW2SO=%@Y|qGt+ijk2hJEK=a&1j(+8#X~0(l-f zwx=S&arHP>X;vd(oyxPj4Z&!h@YK8U`iK|-P8;ZhF>-6+b~k=0?^{Pfk4 z;#(~zWswr=0uTMYk7;yxYpeAFy90Vm=wzCsAjEQSc$(tC#-@izbzrS&4N3uC80sbq zq@vcHp{A|B^3z&%dR^ammTma7^5a)o(Iwkwf*$0B@*G-O>JAakM-CP3rZ10A#^Yp zPy{I|BqUU6DqW;^=|-wY1%(JCGywsD&`XX;k**>jUAlAyLN5|}Xm9Q4@!oshePg^b z#`{ZAva|QvtIqk&--is#wtHzo8$(ye9BVM;Wvh zpT8A3ks;{hE}?)XdTaKRTJW4jGucaVK`jCm$0*ZDgDKCr#X`fcY>W%7C^09z8=9H- zRyu4%V|0m>v>QK~C#{7THBnsl6pIEB4R)RB>;C?lIP7sClwiyp7}En8 ztpK~G58ydXK-IYtFaiVBkFYI2VDiU=I0=cRS9}&4mFwBt(Ugk#BTTV;rl?l=({&{N zBv6F~e7o=9!W5@9b+wIoi3vsbANSyVWNz{5>KYkOFD-WD_WqC`&*xlUvF#lz(yTBj zon6(^n)cfU21=|LrB@ zLl>(N`o(zZ>fX=KbAtdwTxe@iZpY1^F*jbD-(!G}XMS;oZ4R@fjEleS^%%tZ-E34T&};cnvtR8LglA*Or3-eAl7lG-kXHT7Fg9Nt$WMOZN09+85d2q z<}}nchubf`vTPJK^#{>(3SbzKhZa&?#ym|i#}z7atu;Z;?yVHa*`1pd+eQ+YUUcwn z{?KK`Y5>n2bp;W(5T5{;WKM1nhe!XL&+`ugk{A=YD*)R!1?s?)V7o1(40~<-B^Cr= z%(+0REDS}08%VgaWs7CNiTD2m>$YQ;cXh74^K)hqUrYQvhx_*C;w zHwmYGH{Ef1-zC=G=7lDzTN$1rJn<(NzJN#lA;582$9FFx5*h2&LG-T@$iz}we@MOz zf|_8_kQwZ60@|U%ncO)p>R%aNV-D_s?v`mBD59DxIBbuqeH z9sgUcu22(N_@SGiYwEjt4_^1RHJ?PTT6fNx?~_}b z*<+pHjlOq|HBi&$68llHj7!z?$Id0kO%G2bhp0gkwf1Psc-_crry$}6-H6h)4a*n7 z1N-7Q(FDRfNZ_6`pwxPia=0G$ zO8FLVLGP`CtTIpsf#Ys0a@6FA9jeC=OROsuXJtDb^ngq_imA@o0U&hG&t6&16Ph$f zBapmX)E^GAiJ3=+ z>iZKL;alZ(4e=52)UwLx3@xvFJ3l;{Rg{YfX7a--P^0OvVM`pRDr}zT*NU=zU<}ar zUNDBg-klr-Rs7RE!Tw;se@%DyalnPC?%gzOK+CTMf6-}g-mJ|ka*G$Z?Qjg{bifR4XHTW6?cCcmnCn8s|Fn z&Fg5*o<;~;&?d~Q8_$)0!dRTHyFx`1@jPPDW>=zj@zjMPU6jxfUEGuNpWh+dGwa{g zs|q<9FnrB#yIFXhw>ej#_B9t{{cAjF9lppPV$jw-463?0@PHo|RG(rb+ebFIk;b|8 zA$n*!cBrgJ#gzcgH+N{O<;F5v<2__wz2kQ4MoZQx2;b<-eRgk` zR*EXig?EJz!z!0^96{ms-J8EB7l4xrhlo#|1DLj(VnXd-q<&8-6*YXd~S=6x^@3;rRR2-C0C#@8@8tH>QM3B)aJR;ib9OlY(Qb% zu{_#}<2L1T&KYiNqrrlF2$+w#AZK;G#5H93&_Kb2;oBM=Gd)yIL~x=RZzLdcTl46~&MN3z z>)Q5_E~l=ThodzwcrP^hSD_ZorR!XQs0tm`QiEb3 zQuAet^~5pib9FB+C=We3=sDtf2)4xhbEE*b6bb6VZ1b5l94^T=0+*~n?BUk>6e~=W z@bki51$I03x*NDH!DJ;j9-x{p+zN1%Ei#za^p2LTFfi|`z?xq+?n^OOwJGYR*RZLA za(YDh`Wk>HE*JU#HJN26)2f=U6X8Tr6(na+2PAN{Ux5e~+p3HkZHo<-%MpzSWXDv_ zwy5q#Y2vL{tK`Yb%JqcF;CXL>?8=G!*+cUD#72@;w0`AAie$p))v@5l^AQ4vu)fO3 z$li;@NY3TfX!GpgrYNc#mIb>U?o*p!;5#Kj-gv+F3?}Z}<2uC)Io{jz7NC{Bdl(9U z#fP=rfEn1cs?m)QgQcmT^GGe>H;M%S#0cKxOtAFo6;(^~57QGZgqE&F8Uf|Ei zUZxA(`AnW#4Ij3bqqTS!o=pQC zP$64jpBmbg_>AAaR7Br=$;y{I`STfQA^}Au_H2RD#3f3>8?^k0tB=_^^D4tB3pl0i zN8w?_tIJVI>w(%pih0|pFrU9AAi;YhmQz`-*epaRvS=cyn^Qs}57dW@QIExw=^6)PKvvE@iDL}AOiu5>{%Wu)#{}_ zsv;aXPb^}q1}y?UmYXW+t6EDXVaC2(;Bz3JPAI_As8PlSNAw$9&I%AGKm_fSMOaeU z=8w16ZC;`^jZ!}iR``Tl9(<7?N~AsZuU!Ak!$a*lCdsNYLUp^cb$XXG4QI#>prMn1 zBWPukr-FnQHV8@Gw%l!O90_|b3b`LwA4Y*H0C^Vd2rxCedeF)W(5OV#>ozR>bFnhx z(rj8&HgL*u6w)*Egr5G1`C0X~?vK}qIM??X2-R_6?>d#iWS2^6o@7abIxfbJRov(!W{MH0-c{g^f&!Y>?EF5Zpj9g_hc(7Q2N6cTeW1h_!ao>ad6}%t5C`=%^VQaGJUq*%7Pn zP|Q=lQb1OP^mxFpb}H7D^X>^KqVXTCsc-2;wc}~7pcR^rL|-Xw!9OO9CI^OlV0c@- z4(8|#+TXDCuGxtRa>si3ct}n0MmY;M9Sw+$!1M5I1V>I5`2zz8pB@a`@YrC&~ zg*rjmMo{Q<3>UfNx%V?Gu=>t%^cE@~xvRh?Ae;p@U}Go(sR9YVjdg?{p*)whl>t} zUc^t|1B4BA$ZxP6m=)o>OBKXz4o0Pr53LH$QXrPL!F)HXSk4YEDjfkkAw-dM}Gap)S5~ zzQS%(C`zmexO#Te#pIk0IEx3?@h#-CA#d+PpHMh5UGfgF?gBrP#sR5ea;aS%pJ(2;qc(>GcO% zX1yBOC`6r#rXedv@0Pztz6v65B3Zd|yZ6^_f55rtyo)m@gVL`e04m$q{VN@ICh*Qb zPza!^3d8eI?h%i79>T+)v8=eg0my3zQj-RphnVDtYFs}Rbl76OlV~Yu`S^fiC7Lna|MoEJyOd?8@ zc}8xY}h0QO@UevEWG; zO+wvDMmRa0!}>~WW3q_?r<-6j2Kkce%s^PwP(BhMUw()?V;gj{qzEoEDcz1Xo0h(O z;e9X7J6cR?&wAQD++IvD_R`!5*HRNu4yXk}&9Id|$I2z(9xhc5-aHnB=E?PvFwxw* za5~q?MuAb3t>o4zla41KOe6>)v|3nD5OB)5*}#mQGTw+MsUy~}t=*G4N|Yp>w_z*k zQl`#0g{g2SeCktPkIZzwcwU<{6GN+tdWdg^cfSZXIFB0((VGSs2IF%uvBt38s z?GS0_-b5b=A!u|>1Or+C!qB;nXHsrwQ7-7bTc96g2HtL8G;pg6=2rqtryy!f`g!U1 z{Im%Weouh5qgmOxqsLJ`6Va*MUZ4^PuG(PGmS>Z8vZe_`d^CE}Qd#NM*5WD87Zh;( zORpCOsf_0Mi!l(FII-G2t4U_+3+d4ANfLcQJi~k z#xuAS*k}cs4FGQw^+REk+Z*%hfYxVAn^gCWsQ}j7DM1%X(pfGS0rgrM!{x8%=n4)f z=ie6ZIj8$l2X@mKv^E`J^$nzyaZQcf*ynFgJr|#Q{??r7zX<#zoWzM{X9Z4Jhd+N? zs{vJ(qS3)Dzw;^|bh0E(g$k6>vmSeORY#q^Tex1ElEcjGkYs z+D^v*ctUrMrsuZ(>&mxg9T8K;0NDucTkjI94B%SgNk8#dYrD|$Jxt!DPdy_s8~h=H zdK;UD7C;>(67<&ucQl$UGW8+YnIu)Pq82ZLta>X-=Qvuz+jgf044W)3C?uL5pA^e- zv>VjMUHSupn4!@pV17{67E+b17+(25_EX-gMmJYR~|dob_J;dTt7m& zf}x^V)F*;}7HawCc%ZW&HUJ@G%WH#81zJ|?X9han+Qz@G4RCBQ8;G04NnD*ETgmOUr*&T5#+x0o?mv*}eQ?BMsaG$UYiOR%t@yr#b^K6M!VfS~`H+(J- zZ~lm}p}RMN#_oWauF$+a1+v<$80LOgh1yodz;ncPQw@}CqFYuAW#buF=NVA9=9J0_ zMTzP}1IMs{o*DH^0&TVQ-!4}VR7Zv+es1r=N)GCG%dl|pypz=!&EXkNqq4rnF9o+O zptAOAi8DvjCO}jbPd*i`&URGs#C$6>zJ9{BU^nTMTBu`q`DqN#C_Bpf@H!Q`0?_Q~ zMdui(4JSJ=nyv(Ac7bjJMTU4`qXsaJ86y5e7Ob6rWUBJNysYB0#dfhvQv>l~YVYO- z#6WI+HKH%gcWdQp`@zaJJ=}6*^%)G!6N+kzflLA*>A;C9JkFe#^pV7w>HDBqHv_JN zx|p~PX8eENaJVv>7_In+ae*owp%zaq=vh|IIb6d2v1W@O?_?V25Z|csMMb6=-b091yq^XimoNl-)CVSaoVcY$+Q(3bZok zL6GWp*QT=IjjeF10EGY+plM($)C5%re#Gqdi}|Tr5IwN(Pnrpu=$|IgJMqzlx$%f$ zDM;!+MPwgX7DNf?Li-|iZ0S{IFj4T+`ajb-j3&QY-%VSV@#u{cjH1i(#$D|}<8AFl zpaKKVV7Rd!Sk6-7@6XHNrWH=)B8J-vWG1gGi0B;t)gICTyRJ3;8qDyscc%havBuKt z5vbuAkT`z&smIEWXOBRL!N)r>r+&>)5038ndC%beV?g=lNqRyz6W$@C-r2DZ20POy^ECUu#z0s}(lljkA`_J!|){B-0**;RU2oBo0z_Bm>MAjQe2XI*%z<{(Gi>3D^V^A7te^ zivc?c0X%8!CJQ%6=41{2cr;m9p7ii>B%aIh955Yr1X(IoTN}AuKb>?EgX=55aKRT~ z?Y`nFO?=IT7*Zxc#RJ&eO-G2Y5`D73j95$pp{V+|(32c8g@cTOju{{WTins?Amr>^ z%u+vNKm;z=oo{F?*!GxSb(o(NG+xq^sgRc}qv)0*0V7oiWq+(IeqGyF`x3ju9UR!N z#K@cALHq~-v@E?5+qkrzO7m}{Zuapc%H;ufcfE#YiKRwh#_q9JlsUbD16-%_i{V9% zP|{@fXq=e$x3%Ksgr%kJ8Am|pk%e80gT@Ik2j<;{9E1@1dM{OwabP#H%+wR!J*@z`M4~91i#w4S@={a*QC~+^KAd3|AFlmVIAUa4 zVc9&7-BZm{iD$=5(WMHq=eo8N#PwqN@_U>3MDC9f4-meIT7r;d(?yo04XaEWsGk;ApxIkWp z&Iw0)4>}H|1HGOEr<#BInlJGbE)?apH&ntQzbwMjv^q+NT34TiKX05CN7Kp7oacVL zP)21?RYc?vicONYMB$#^rr34+%Eh&?G*Q4KZ%!EU>EWo10D#2w( zz@Ao-G}BqI?mn>&h&eCioOiy=3Fb~FZ(qP35kj#?w44;%9}x1fF4+>eT2cnR zz)7f=_2JlbL%#+*MB9964SE8)Apu6@S$<^k@)ff7K{sT;>qDHU;2Y}i{}O0phA&fYGyjoJTl z553Fj%q_0DgHJSy$$Wci$LfA)h=-z(0)qTV?d%G8Rs9(`y{P&m8uIC8+3ZU1U5j|* zkO(Z>3FgjjsT_kT*NIobk2^anGrQ|Cf&RS(HkF)hQZYa+?=@_fF{Nxb;%_8PzB=Fd zkgu8we^I z8^Kgyw(MOjp#)4KtdAw^kTc1NF1@lDHooPFV`1*M3x+*d0lwp@kF*R?Fx1gLNc6(Q>?9!4r&TK~-9n2pKon-a1>8fW+SwoH3I zPOWDF-Ihu&>{)pr-*g7+Q=XaZwn6U2R&1%Q7D2$M-=n%IpG+(?&go4->zet^O8>OvGF(^%_%<{`r} zS0Ki@`KhhbWBbjkKb=Su4K61W^>J@8W6%EOcM*g6<#+KI^1Ha*5u$Dur@RQt?Hu0% zxSLI9g+vqF(GEx1FkfDD-slUTho<+-zlQ^EPvY&m>^IGwNq%J-!>Z>U$3C+xEN+Tk z=zQxe)X-2K&BQ9-yWd!`>f_8jkSrSyF+PoT^rX_Zfd`A5bhb)n?>4ZBxy*n%3&O5? zhPc}Jv^3M;D*|2@f4;0r)7A_M!qX?ynU5a#H&S6eDiO~FI@hs>gb=tUNlkW0vGwJ; zNjvcf2WMRJN?9E@P7E~`9MatSiv{!z_zn4H*;TCMlmU7TYIXxdD$7L)TlZZu?DUb? z=wnnZV1(V|gDR}tw81=^v-w3t>d{GXngNmdoAryV=%ww z<$(fMxuF$TJ!5q23b3M$rJJ>=u>tlili~gL9P4; zzEW>HuT*hNqx1fiXeH5yffdqMJt>-bhc#xxaMk0Swb?N=mNGcF*vsdj#@xN@zn-F*Dj*@{WM|V?XUk_CQy&ttVz>L}iK*-$~2tNg96&_^&o5dtb*_ z77fe{W}`+r$FYmQ+-O3?0xxI|+fig=Mn`)qmtx2Y8ex6m~ON0hlN7uf%IhPen`)vhaXuf$sST{%Wu-6 zw+T9M>dvR&#*>ceFS9F17#?889agJ|h&HRSiU)->#3w{^DE`l6!E+?L5x z*2eZdUX{tStv-zRFtONa771ae703{RZ?zQ?Kic{^LF_@$c@;`FN{x>i-#UI{gm24e zxl{(%vs!QLEORql6Y$nvVsiv&%irFC>Wm`^Rj{8jc4&M1Q8eN=DrsQvkN< zMvoq5rQ6*_C)(0_*_J{KS7pRzmmZl`G2eOeWg=y0Ja^-j(e}OA=l{qzi>X5UWZP%Z z6}O;@#`mGu3H}SPWDsfx!3wouyR97L1mM#+Intt@)~4ln$O?KrM;&;f2I0*njooE( z*Wzy2nu)G6&(dX=_pk75<_bXw?0*Z+pxBo7;48|;y3;@iSb@uFHJ5FGOYXlS3ef3%>w%w!D*>M* z_)M0K0Rna{xbb`2Y|hR5NP4xR4lEnf$|pV2hK$2b*oK^7@LfcVD~*B;F7jm!Wg47g ze?K1&#O{Hz8&HKpU~Dm<0n~4Npi&yz(P!+%w_q1}wsP`JlHKSc^%8)ur`wEXS`>#c zdG8&0DtmDo;2u>FecR7|j@t4AiQCvpv8_R))%cTai_d{Ri*F(F`KWQnsSNR>Of8Qb zN{Fq$Ptgf{L4a8_`c{K3|kALn91Yd%u4#ee5>7H5Yp_4irnk7ZN4x$gZ z<$}MJuNjtGjJKpT4XyOJQuF2`Dy3OY0k3Zp2P8pU{K7rRasoRngHPvKE=mLtmz<-} zcttaKG02h{mj3`0zh9||EvE$5mGwhqr@am;W96Lso!ue@15hX%_ z{SRW!_Zy>iU3V^ap7u4mIy4qqCC8#2^oP`CgU&{CA%R+=2RJX4X(+k%Rs*1p_z{SU-Wy=~`ZW(=P zwv!w|YO2s~%%1Alj`(yS(Pq*kuQN9xfi@tF<&;|LANC*(o$O##9_C;OXunzPlf2zU z-jjHPLl*kxn3|!2TiJIs`pcMw@7#=Ryr&_*J?1bLQs_9+6Wu21+>YV+CP)Rdz<^ou=EuXxwK zRvO8A4QzS?kNPTE?A4X!iJ)kpNF zo;JuUw-I#|>%JtQ7?o4p~WD2MZgPx${DR_c0F&F6Kg9kK8#3Nih=`uq+CF%1Cu7SKuwzQiyBk-riluY8bA2BDf*~POD>C(@ zaHRo>zv4JJ1L5nrJVFHOCU=YMZog^D$bH?M4(w!j-np#EIiJl%M&-SPqRNClGYW*I zPh0{uV!?SQ1jZ+&-8YML;LjV^s~zR8%63^SABTAv=oT;SeEeoij6_WLHkFm)SW%BtGMO2T`A->PSj04)RzZ8 z+`Wx7m%rZL4B-;+-3|MZ7q_KWH$7GXb6=dY%%PpyaXB8YqtG*$!=iLCyb~j7!E|Fi zz0b~TbG9i~V!p5}O6O*eM`6rCm|qlkjZE9QZXo_|{NtTSPKSTVaKl6KsMm-qpFTam| z!5h23zR*1kgPq2hoNL>6m(M~32D|f(|H!rgRWuNOSAzcYH3Hm_3H$e_xUePsM8AQT z1u)p%T_~cf27FiPMcZAl_qzk(lS!D}e}5CU4Mo@s8V9)59p)#Jg18R;`l_37EHmoF z-*<;0Uikm=ML%9~P0AS$4eWgH_E=5Wnur}fzuu`nKew||>*Gb-GM%a1ZVSQIyd?GQ z*i$%tA3m_h$ql?4aM|qNb@?8>?c()1HaEx~t8$y$RhlWh`?Ngz=TL32Lo#KB^S#U7 z+3fR&?{fcazzh^du+a|v>n;-k(V?rITD6%Xi3RE(lGQk=Zvqi^98>+`kQ)`ENT__ zM47d^+RIDCO7<2(TbV@2KEh@iCQZ&bE$A{9(%Wg9$)na}z}q>_o$`w9X{VP6R>sm} z+rTz=J!3?RtI5;`xh-j~*}UtolmBt+`RRS7TmmV|^#oF+jKJNR6;ducn<xgZSww%pvWAbUCWvMWHPL>~W(;Kgz=R4C-JZ0M~L>jZ5ZBFp@nOd9S?5o{S zowCU`7-I3Yb(VgwM(?TbHCV(^A5-vo_hc(hi?4eQM0I>5oxbi;^AcwuQxWfLr%XT= z@(84rEG$deUKb-TWn}qHEfU6D%nI6AqFxzVmdE39Q)_znIuq1$C2IK!UY1^xMEv98 zCro84B83W$v1UB2D?n)u__%Ms5fOSoW#cZ`%oyP;ZGI!e+I=S>MEp>ko>V7NP|`DD z`K42Q8lJpQ%a9PhFtC{HpxS)+KN~0c)5{Rw?AO@lLt&DpDw;(Jah1Vx${fCvQsW)N zyjhQ&XP2X~i!MZ2H$wPmjE%;vFk3IR#Bdkb%qRN5VSjpE3vQq!A~Ln2yss(k0&y&l zA{>?LqUO!ps%zuqVtdhbdQFlw%FMju(g=d5cF%u&uAX0rsQ0>qYebVEE_XZK0*?ik zL21hN-Xil+lxlbiUQ1qW(VdddZqZD@Y7be;_!{6w^(88!hZNy zSN+kEmw1|UgjHrSGfuA`Z)PBKVVpH%DDzf}i@TSI##B|B%OI0paXc-@a`{7#<@h9V zq~`0Z(zz^@x{;$DSuWuXqI>BLm>y5-uRqWql-FztGp$|I4;$I#{&Ro@e|#-);sQ^K zx`^ah2N+=~jXh2U4>J3v7cBREF&zi}BC)o)JtY#gczbGmTy&+Am~mRl1sgu9XZyx& zdX46l`qto~amYVgA&lva0DfxfW%xN4YcW2G^6g0JG>j6JP`LiE=JA{9ccYP90^{ta zl{9MAR>6BVb9HZD+*U~m|Hjl*RvPH0BJ<>mZ5H3jp${pe(y*&P=Q>4`FH8riWsTK0 zB~r(_780buJpJ!O`dkZ`@a~HIYoPpZ`~&&w|CgEY_5aP3D{w@igX%NHkO*snF?&>pF|!+)-`MX>G%7e|GoEl?!C`*d#0zE=KKA8-kB_9V3sF8j!MFCVIPCxFVt1>S`fT&{BDPp8SCd$IN1Qu8Wbr~QW7l?!byhD_Z3ehmN6y9Qy`FbvmA5orv^x1riXM(KCD$f&2& z;`uA~D1ZJ7+2>O=x9aAKU2L$$$Dma$ch_K`kC4&{!&b9sZBom`>T&ufK?{!)g?i)# z^dGwpQ%hLc&bwUEQzZIjRGJZkz$=?T5rQq8WzJgT&e|FO`A z8p8}{2Fo)dAG4!X>q^LUuPmqRl(5l?p?s(`nU@XyNaIn8`z{k~ z-KkV+7V!%6aB?&69?~|e)vfzB9Ipju{sZ=Ie-YlVdj~{4c1zSqz+ttm7mOTbPmdT$ z%Y0rz<{$`xk%>$DA{34QI!Z%YX(V}UO~^d^YI9oi|^pObM9GlyuvnqGy2KAq70o8cDwh}?D$tR5|3B$lwi1q@s8y{ zZ2Lff2b3{@ccfe&MlJ7)6`_sXQhPa%?g=iE_&mTkT44-{wqe-_1M{uBcy+ucchEDn zw4>TofM~y%ig>R%rPe?H4&sio@wPI-&(g{ZSERE_K0rQFC&Um-p#T zsCriw5!-HcePEg5HeAK3Eg@Nbf-fqlIFd{7iG@~}_iyl|k7*+sD(~W_x->_tMqFee zLxpT5uIqM?Z`-g1B}smhl6Agnem0lDVlKYh9V^&9Ay!!L_sQa>)*BU`x224C5!US2 zhr69p+iJb67W-1ej@}HO9QQ9>JCr*PR4`ncTj$!GFX>q$UX(-x^_tk}Rwzmj)-Xq`Z%M4Y6-CNJ(&&;af@X z`yA2jDB7ZR_0vjHHMGas)VOk_(TmDk{G=D%$aS_#P6KssRUK3PGPcy#eAD~QB-IbM z#X@{=h0>#JJ~gpBHfNsPMK-Sb?YH>>-CciP%kUKoXds-%FeU}%l*&5;n;iCuRw8=S z@523>a5xTf)wYj0-W|*uFGW5q%sxBOgC*@;r4{Kn`q(yhZmPQ~4%@{I3I&Z>x@d_P zIU@nT`%V*E<9X+ahcHYHU%T@}r(}beoT__J!QAGCLrka@{mc-ox3$Y*^XcSIa49FhEQuwJo! zm3)T0P#NyCXPG0PC0u?Ld^n&dLwZlZ5p(Whwgd=Al|R!>mylRRJh8gDdk1sk z$SS3WF~zEol8n8)u;`we?Dx>&9W(=tYrD1h!8V@MG`*a;w_(9G}h?=Emsh#QhFK%*810wq2FJJo%^Af{d6FG&*dXxI{9q zG$%-oUk75j9!G#S|9=~dA^&ei_W!fRLO#Ojt+&Mz#6w*7uB9FiE{?Oqz3BQ;niuXt z>%7;4x6wBG1sf2Ude+&pSARm!354Nu0&8py5la_I*pV)BNNPQ2xp)t1Zux)f=0m0+ zQ?T;EF@|P!h62ciWmeVIV~Ms~3NoU#W?qff9i~gRdsb7hQy+891ZV@1q6eo)1nuQd zM^c2yFOWgpOvEs5&xtv$3x%bWCenPmUc_~b$MBFJ35iDDnC>s3uVioLb=vjdUkUKR0WNX#WCqD6}+0dvE*hnt#s6AP$=5?Il? zQ|=asW4rycFI}e&DacdZgn|mhVt91I zJ0n`7It89=(Uoy{5oFjAf6bc8=@$hzdwwZJz9hO$`(@Z7MkYiJ7zKt*sRDNxmpI0jD9F|l)EmYVOp%7qF zQ;EHjKxK40({Pv~oFWcMU#@booko@y(!3~-T5v^(sOBuFGgbs4nJ^gntpxePsUog_ zm=!p=)WYdV>5zi78vG)fQ*7)$awidQEGu-i?#h@}m;yfH&)Sj0h;)-4M$?uYT@e}c zhHiK9m?shsu4OJSOI=}AQ;_BZfy(uMIn{A1_tEk*?)e3L7}tR}mIH^|ru}Tb)g-20 z$j;qtQ^9{pFAU1|DxTzkG=}*@{rIw5wHcrRC>8SDvul`LfZ)M+f2laE#BG!k`D8J~(%2T)T0oUIF${R(_UFLlPEmz-(Y0!!V(j6NiZy zGio&!J&KxRU?|JGm#c#d5hrAZf$>d5|Drs1f+Fymg|sq-;e`<`-zlTP!^x_?(#F&M z#6p>=d-N@Zt$xo&Z}mO=kXS~zDmUhZh{UWeFZ8gCl2`2MADU)`kTmQe+1+1C?_)oo zn=M>koK>XG)4^L9SyyLA4`hFIkr2G(3!Kx!yTcoI@#rugLrmL(AII1yW~xd z{OK}QZ#m^Ar(KbhmN>?DjPapXxzW_5Bz0i?V&n7T+#1HHHD?JYiX$PbI~h~`-ER~q zq!mrb>0f+;XhvLxPq%sBCR%Fc@zOe+28Pd#=^eJge%hK5mkU2Hbyn50+UGFqaBaO? zsZ)cWH;bwP6>c4N@1<7H5hc$u`gBEIiIt`2az=tVC`lY?bkKBFOV`mEcXume_9e z$(N#6gG=mkd03kfczAFN3q`eO*A$iyWg$qdZ%EP5VB40jNv^h5k6s}c^Ws++u~i}9tv*1}#vw$GMdGu@L3>c&Y~K6E_B-{WOG_US_?q-rlUy%dy&SsA1qCqmw? zn(|M*$?eHnkTPKr%O>-jG^6R21o3k#OO0d6E6d4N1GHmd@(P7S13gJjp`ndU#9vY$ zSFH|hC6R_P2-2CJ**}J7KANMRX8Ba?qn@<(THuM&a+y^>Xo z$yDODq=&!S1*@oqN4QA2U~bG%d}XrDTYSmOD>dDO;ItoUkBAtCXSgw40PzaK-G>Fw zl|K`SFAoxqwv-R&rv(C${Y}Zw@_CxYBC6N4zoFRvK}s|?O`^cR9Z}Kcc~OWfWKLB3 zquX%bf|HDUGF?;Ii_K2ghRG0}U!26g`NW6V1zDk>X3rL9x;Nz-!--jV9@)_GO5|;F z1B<-;<;8TLWWLg#`B^8a8UOSs5taw1$!UN4&ZLJ}Qb|8HpIKY%1dN)z9cIOpq9d>1 zsgcQ0MqY#SqEBRjXVl{jd}Vwv=CA2!5lzaKe#qxvBY=_c;SnP-(%U7e zlQ273YbB!#2M7J=<_CPw73$?IQ$_SFR~_D|5-J`^c^NOH;$KPi&Bur8OcyteP1EFI z#*CKPdVlie$M7UxLE?s*>|r9#lX1xNZekgJ&+;Q^MuYDcSkk*)oMcX_I>k?U_cB@p z$&^#TAxpHK_SNq%$9dRcp^VGMMCny5sX|-joq&m;{hO8Qa+cU~A+iYTyAM?bi(4XP zJwzaIqbtc3CXl&}$eeuM>h=+M5vp;nCJQ)G_6Iwmq* z-)z;lq(B9yia_%#JcJJi(=0ln^Tda-!fp2P&AI4it537+3hY=ps%Ob>nz$G8*RLL7 zq(0F@Out9jcxt8bd6REc1==nAYgvK|9U218lp; zSU-E0^p0wgq^lD>RIU3&f;zfywmy4B3*_xfm&8#=YtRSIy%09IjY>_{Y+_5YXfB8cl!eA-II+zUxN<5fw;&%@$p)!qDk#0nR) z59y@7l{kEQ>iJ*}uW~-RQMD|p)3BU1XaI{kmD)dDmh2&!fa;@qlt<9nEz_>g6x{{Qvpp+;lxO?yr@}Ue=5su8Qi# z89V~#)GA_frRS6EgFY`I6mT+E8(F21TtB>C2I#n*OUGxRkv*Yvqy4!uC+FxIAPo+& z*tecZ?=qWM9MB?M_NPomKxgXQi6AM4Sca{k9y)GH>G-al!ONkaMCu^nNntTyUMUb}_yC*f7fBL_*qX#yGQK+bIH+)jP>#`>L^Q+ZfAT0qQlb zk_dEP{*rr&y76pwNUQ4T*((X0m`mqp2e2`Dt~igp@7B+i!Y;juo-v*dli=QX`%U(x z-R{ZFs-k)_{2C}pMGi`h+U1V2&-eKKVh_lq#<`)VSZN(|%vHMwjmLc{w93l8`d3Dm z1|l>*!C+=(EGVQ$Y{hyYknY61|H67OEo<2=Ka1E0bU-Qk`-vZ=n^+F;J#&=%>Xi_M zS@mK@or*#Ad50OXHB>p5E*oUrRu9I;1gpxNafQa(cYCu40_TlGw*Zbht%G7lvC7nv zxyB@stEDVJMbCN}n$yxa$nk;uNuM^jy!o5eaod<_s z^g2nxjX|g?&QX5uDu^7R`i~J@!4(cR-^-R1VWiS0muh`Ql_MDOO-OL+*Oz}OV`BGF zyOhlVxPu#W8_>CCmL6{mf0@XNAuIf%>`hzgIU|Hr;@t-p(EIPDsh`Y2+Nl5=g1J<= zgF{%0uUAYTtwAZDBNtRc7@@%F1NPDTjLodeXF8jM1C#E^b0~J~eA1}gf&7))d3SPz z%K8Q&%D0z?{H&Veq^fV3-e{Kc`(Qt?Wqy$d60#(Db|Pcp%l+WzWuBac^fP9SOPeL> z4P(hb2^5R8ED032#aj6mzp4KssF-q9d9lh=wTLZJc`$$^Tcg#&pe8|Y{p|gXGtrcz zu|cjvDD|qQ;F>D8mQKSRUZ&AwFcV8en`<&0Eo9yWl zg%b)d3K}r)?+w#t`>MkABA^QVTI?fJi!LeE!$p~6OHY}MoGMRF-dZ&jaIP+K4emy6 zmZD$ik>eh6LXF23d%BW5{i*9r;iB~v=Xb$QTjShdhA0)RQC47= z!)G&=E`^AZ^oTE=m>M=4KT@R;Q%>hO9Jwh6N=0;rVZ3FMid}Mr7$oGEn9_d{N}X5w z)aAYl;izO3`8GOsxa;txKDp^Gss#OhR{nnCfv^k1g_Xm}=e-6GAPjo~%X5?7YqHD- zDhMhasajU4C;e~rfmX<`rQ}(gx~sC+P70YR6+hkiqJN`Qtk_|sF8Y-*-KJ-$YO=~W zI){+tL(eT$bTwQa4xF8aLoR6i@Xg|6HJ&FiSO6IB-fiN-RgMx|y z7rjBi;|9ABWhb8KTDKuxaipxJZ+@c7wb*Y+1_iBe(6I~f)Xoy2~p)7TNsbOc3 zbJfX;v;{_5r+^$Em;YjPxsWvgVA~Oeus_ti)dW#uIo3}yI8)BXco%J~CyU^@v#jpV zp6MEoY%+eZocV-;yD>{>D1 z)iIB!8LI3VZxjy2Dp>Bl9p#anh@|JEsI5%YkQI!2(<+NmO0eLDLjil+>u?w1lD!6w zwwzQuPvawlBed#F@I9AU(m&rfncZ4c<69y~zpg4hC+t8hP^6lE{tREnG(OZR5xXu| zH`mrsd@z4{^^{srR3>5cFxw|gk?pJ)rYO#Az%PCv;AZRSBbq@Dzk)bOa?m<7y&>b^eY*-+ko#1;M3L0W+Q_;@~dQ1}R0x4H}#a1TB zLndgbb_y?~r#!CHFg-%#K#)uN^M))%NQtSc;Q5i9J+=qJkD*?k`?Mwa>|@e~8VtWK z9V23>uGy4mI^dmv?MiIZ-DTT^!N1$980`K8SKqph^#owaxyPz%M1}&&-ix*@i|M zw9EAuuLk)HK^1WYXlcTbn0Vt2!^)Sg0m20ys04Jd{eW+In8nT1dr%!okYI>q)VBO^ zmf=Dn&2w~tIPG=YY=Ei) za)9T+ZG>F?xbuV!*Xhv)8!u23W~zqHHXcLrJh@{L1_eM`OXR+YR@E{Ox%B0Wbs1wU z<%2`qbt!etlXz900QY>@X_)blSvqgqJi=_7j($b*&k}+B7x#?2Cu9s* z5Q%(?2bBG?q1)LC*dfte$VyL>r|g3Z_0 zl}UhONS-)5%eA#DC^QGM#4C^;{I|LHzZBZ3@{w2v%vK@;Y@@)xO~dX=c-Z!VTgGF2 z(Gu6o6FAtyqPA6pRYi>kM(oz=SYhe-ZsjsnbLfYtF+=TtTT>lbPvAxd=F0ql7(^n% z=N|NCxrwlhSjY;&(FxDHaK*sPRa)jyZV)7)_f3Sc>MnYN?VExTUmLJ)a$;A@epnS~ zh;#klf5^*v!cr9?@dzxZAOmgaf-1CQY@aZ5cCbFtrlrE9P&JmxS=*q9w`V>{hsg`N zl&-R>c7h%=TU^z`*F6d2L<_TDJoN+`4}}3$mHsbgt99qd4AJ=^Ddip$dI-O@Op5DM zKm~hAb~93aYJBcX{SpFR#S(&O{90@^0^Fv1m+OQhHN=@~L|MNC!SA<=AWtGIwBWN_ z9E^S`h~+kbFxGcZS0;9)iB=Ny=7!#TqCzCUxSQxWw$-15pp^sy9YQT>S{a%qcv4jX@^vdM*ad+f)O8!ro? z%ZrO+n~;{afkZ8zfc`QA2v1$!FM!E&iHuD~-e(iTWb+=)zB$Qqhuv89#Y`Us4gdVY z8cJ%_;yB()OH0dVg%6T{`bUb!6>`jhy-#<>xg;le@^R5Tk5s|O)PlX*M_Ru180`-` zhro+;Gn$ua#IZK~&dPmpo~_uMW)+p%#Lpn*DfIR8%LiKgAq%1t{43!GQX1D%+39WZ z-%RIT=p0DFTM63_Dr`^)(0CAR?Ol*HF3@OdSVFBrtN=}QbQFxK4%I8NDIJDxdPQ%c@;RnL?Q;KR3g9f|i zGi+KG#p16dkW&r_kWhZ{xmI5Jm_s zM4F2GCx;_*E$;%Tz5o92y`KrffXx=#*|^EAi11N_~F@o!zz=4OoRxjI8}a?#?_5 z(wFB_KQb~RTUKrlyOksV$;N7;-U!{*S%v}$$Deb2 z4xn!OiA0EHY?0=QD)UBz!tVE@^`b1T+FGNDQNj*%c8~bX%4B{}7QVms_1TI_yUbFI z&p3IANBx%+9z^2KePpVL9du8mh==9IYna?p0h!9Mqb1DSK~#GUi~)0na-ZDwMq?;A z&?*R0!A7)QOE-B|G(xO4Fcb-Z22fqJc{f5%{-EhqH$M>14Im!9BwcBlJL(B{l9cv# zDPJ65T0-R(D*YOx@N^)izAtch1&%$aT!nL~pY{hLgexkIbMk<_5a6>#0@{546dH%9++FR)gB8mL*WX3gS@};EzKq}qR3IR74HX$ z($k|SVE;{<2Um3z_+@r2jp#|n)|%>ckBQ5LY1}N2QyAW!^|?7%@kwHd&U@7)el;3X z8iq!7@aAGW4bcaS>T$K)MZc=kBgR<}C)po((HepE;cE%aJ!q_VKB1%Iyc8QEC;CH2 zE>H5V`9AS<6GiP$HX{Dtu&U3`{ZN1#nL_Js^By$yM#|0$2YzLyF!-RXiw*;kAeQ;s zd$QX@Fa+_lzhqSfi8?i*m#IHdc4%lSljX}zWW^xFpWs!IH;>re&WJP7ozC(g@~4Xc zVFwtMW{X^yQt3!;PAqd?cZt9n{x6=dsw8;^30{trgLbPHA#t#;>a)VXu3?cpu z6u+!J_E(2UvGxxO{(NSqjvDw-4qBB4l>wBQnT4g9x_dv|>e~dBkgFgnxPm@pLhYBc zj3>6WA+A5cIWDug@n=8PMoXJK{`LK%Pc;5>VAO0KC;W%g_|IazJWoJ=wr(t3#r)38 zx05Ge;6U$W9GL$?lg7xW*SD8y$8BJBAb(hI5dT7xM@-s${jorv(SMP_5y7fnGIg>C z_=gz&f1$`_!UhJS!KVfOn2rDPb&g9zy!3*w!=8Vk${^O64N3V~r~V_GBW?#x(h3aO zTfx^r6V@BpzkD4KRHIdV;$Nip=(#g12O|8_UH>AlTR?>e%AB2HJl5HCuY>x3R4928 z_`@5ylKHq(el42}xcutsk(rw1VLEwesX)en10gq_*#6Xs7}i0G5Rpk^{pPUoS>t!* z+tPk*QW7?GGDnohLHoGj{xXm1PB~-cHWy=uJZy)^P}$7p7! zAxB{KU6@drJcRyvPvnOely~v}cJUmzI6FcM)Q0(Q!J7I+{XJujjV>|{tmDyqpau&4 zQBFDpPI6Spp?FAQJ@>jneT~-Us4i$7{ie78C@Fbmzn7GCv?}k(i>%%m1=jAmtKhsn z*>;^-Ay;lT@PMd8zhHi`A2r^QnjcK~4ffyPZ`dix=-&xmkj@yu3FII@LQq27a8Jn9 z8xKq3k>F*T_2{4pFc}?zXR;3`dsJM^>WYt#K*a7w#~`Pp!Rzqk+ZWZ<)k|e475g{G zQv~;p?1?;w_C1xt8{W80;JL)*YtxQ!@Oo@anr^HN>HFuwQi zl<;JD(KLbKBZ*18dm(@t^8chp=(ICFt&qt7Rs_iFHI#BkgI_pWc8iYMtCs%eTJX{_ z$Us4E#GNiOseW$EQ$KQ_?}D((VOohQcpZwb9b^G>EJKHsf=jag?Gk*d->{7o4E2T` z;Aa3ySO0gW2zh6AL3b_jJ^o*g66&NjCGZE(l7C~AgQQ@PudlDf>fOR-AozbfgbZM~ z&q{rcjE7>!!xpOR&T@GN>peFiQE&B|ptMFPji0`M?ybh?|FS^>wRjxFK0Jyyi>v>? zNc}PD;mw7w?-etVUxHQqU-IrmTmONqVSK5Nh=vsvbB*a&<(k|n89=*FJEi1v{%jT! zQm_j?8;9U3^)ED^!L_^s$Qc>Al|0fIU3Q}NCAcsp4(1T`pNj!KSeBxg(dA^)?Hq=@ zQ<4S;xK6<=Wb%Ko>62f%$z(>*J>SrM6a8i_0n`c8w57X$e);dyUcR1zlo-1$N#WJ& zJ{EX0e`nVJ5Xa4@v9v3X@lNGJ9#Oo{xmhlXw<+>JdBU}XxNp!wehvM%`L)BTUaRk( z+>ARN&YebyI}U05yq`}Jd}$1#o$b{Ea4J3SRL{B%g$h%6A<1i3XP;dDblb!SpwD=e zt^vd7sK&a$HXJS&iixZpaCdgjMh%M`+5l8)A5}i$PFjj*RW7?`=vJF@S#Ap$7M5B< zb+fC;Mb+2Mj>WGlwNAKiXvyov4lOdq*J|Dv-mm^$A95!zv}BNycBGqV2_XwQo}D-n z=v2nFTfKwuy)Wz>3IHN%IB_?2T}9LqHFofAhI3JELw64%<=p&{%91Ya+GJgsFsWot zXS$x%H*Mc(Yaeo9W!!>qb`h09aKB) z7w&p?=lkSDxC=Tna|(g~k=QkEbd6pfT~aPD6C(HV_|1{ib|v*i1gukoNm8dF{>A)a zd6>pPOJYGeJlmzKv)Lus6}ReCQDnTf96*3fw+!-U>8_;!ef+{w6gOenAM9zYP`r$_K19Y2M#@NHL!7e4f;-khge*g zinyi=wVMK9bMzs_(YsOp_>6fptRw$Hv%Og(>jmN?YF_s0U|Oaaq1Oj~A6iMWv^~H; zHm(jTxF55BW9(_x1RQ)FM8m(d@vknGLl(PMZ*!sIwFp!<1ym0BFNw1$0QMD=?sv~y zxhw;F_eZ`&NWp%pYk=>0Uxvk-ik3Wt*6$mR&fhjf*%wwT)|m8YTxwj7!>pnUOOaiF zG|bOdw00VvNdJWcI`sb3EuT$ZVk!+?l5E<+ zFgbDY9J3ktBL0Sr{zQfk(fy{R40NUQooWUp=E|QRvC5J#FGA-*sN5haaR;9w7=50! zTh<5tbU(?Y#aXA3lhILaM2$f961Fvw;m5I3yr?U~|N8*N z7?rkC6&xOYXA@{+A4E|qMf{R=(fXc89;xgL8y}|t)Ma@t!@nWkVBzgkcow;KZr|T1 znfX49{|Hvat&8X6tsD{Yfe{4Yj9RNl{>0)B<8GG>sMQ{Ub66C9;J!*E z!_hQ)2Jd4N)W+lRBJqTcBcn^DxE*BV^!2m==*L)ngoN1r;3s7@P>d)^%%vQxOQ!Zz zZ}|7+4|I>4a-qV*dDCT0tdblRMh|Y-a-h^sxpoY4$W-$R*Y9K=M=_7@+bZ6)7JSwZ zVsqiMp3KmQlSi@}cgkh6CX=dAK2I%5g*2XY4(lR>~@)ZE^G}H5zO!1UhO>Rgm&LS z8m{k@mdvw&i-|_Ds|Wb33*$pjhF2{KwXEk~z<)(a z-G)!SRP1-H&NN8BC$hUrDWg~~^nr+l*l`!z(hGIpOqI8LyVwQD2tB2ucKM4Lep7c9 z%(=SNvD}`6Qb4N2`nn2gfk~$H7_1q2UN$JEJ>$|fxDnHC)t`v%a!K=eY56HGi`Cb6 zApBQKK!z>@4SM3t+RLpoxcSV{%{C$1^tS8~(>qGR84Ez)ag$rkRj&5EiWz6_Ep0yIm_f0%L_2|J zQ-0Ch`{_|A#xB_{pB^HEZot z^+1cU1h#@Y1AT(j&gF$?vlxMhDh`w#?(e!@h=uTL*+6AFvB?szEZ zU+^di@#v1UPpL(|AoAnej|}>jENz$^H2a_@>CIu(iNa$G87UtJq=Yz<;@rJVT^tw# zZckY?F1tl_(VpHX>5gjo(-QB7)s8V#As*T+H3%@p;($*x71~X=;y!X3E8|k#hB6L` zO?@Cc&>!-*g+oy(<#8^<s-I_DX=xf1iY;p$P*Y5y1eeyLk9FEiKO9t|StCVt37 zJAsOQ#O8Tyy1sIElW@ApF_et_gEB`GMq7k0U20@6sOCMihkPA^H-_BzObb6TP`)fRMJUP%EyI|j|+p1Coyqsg9Om&2jaaKDpT3dx!YD4(^kvd=^uDpdzP|3J9ijRs&*U0>k0BWN2|od{D0$;nk~Ql_l9r_E<$Mo08n*j=__*)G%9x`-?;`Of0=>Lw{auqTG!M=?a&C)1 z$kA@Na5~df5H>yD-^6sUrKYi+N%l;4x}UIRL3w+cNNH(zfKrS4O|8^u3k%$cpa+i%&aW;0Lg zIkl&W(5y==D}c5Y-IaNmPD+qzPw<&04yMh%VPMlqnP|M#^xUy9=;9q7A<^<6T7VK~ zK$J-xMYr zZ1UlPTZK!ZB01hnJs`UKO8^SUDb;c*lbftIHl(;I8=XP^03GYfC4EHiqGl~k0_EJTi;D@AP+fIJqZ5qrKu4CK*g)inqHvQ4X-7FS3>|ef$e} zMeB47dkRxDOz*4gKvgMeJ>@MIayT;WKC~LJd~-Lj|5R=Ap;h9=bGG9h-V~k2IO}OD zgXqD`5x}dG`a)^MRHO>8#<9<_`X*_Th;g7__JXQds*qRmyZg20{a4lqGj^%RHALgA zNI)Ng>u8S0j_r}uGMu`gF|?uU006~k=B zm@nfvtb90o44!5@kiD+v?LCAlvh~-L+9qeEaidtQD>;Vl7VzNq^yOx^sk);H*n@Gr zhY_g`9O#sb-|A&{Uxr$zhBEMs`7e>P%QwyB%MT%VVpn{7KBh4NrOu?zW&z3Q3r}8* z8nr2IoGLv}F+o)GinfpP9j&-oQ>(((&`zM}t#cS^)q}Ww{VC}t$lNOx)`}1PG}g4U z)ocKv`Z`RiyyKC4RzOlHmmzEk>kS=Mx|4o&0h6yM$;7w zoBJdyaeoT;4#p+OMO+;G7D!B%UN-aUN}nhialAdsp+=3 zKuB8cm~Cz5{BS_mdofT4)*YYU3?DrNk`qmmpy!AjFN?LDI;Jso!znawwk}fBVX9@- zf2lTr1De%o*z7ij5$$z(!Emsh)LUpdk}G+I)xCNQ%~CMcP(0UD@vI`OKXe&4E&*L3 zt}yE#Sky`}#!7u3&69gdu8^Z=$L?<8Kv9yBZIeEZJ?3t>+QKH*6|}$PO*^*4$KcVM z*GEv52=hr2`zYgsnlKf8mQn|%?+?x=9^$%>E0jO46rpEGim29j;!>)I{#x zs#(Cek=%m6?v;H1xcktth;^t&V$l3e*g>*+^XCT7gWKC@4VgKM7}rJJT{WI> z!!#G^HXf3_V2rdYpgb0OuM_g*_(86rjU>6&i!>%WgY=4|+dxk%&lwPTfeh*FJKNnD_3W~4;6oKG5fqdta zqmpIl!O7nQx$@Fff3djMfI0Nrx~$6Oh5rbLW&%|CkPYVxj2S`yEe)w17#=Nr4IHO@ zdS=EFbYy_T`dI-S64OPu0T|$1Ur!pXJgjz8$ojR^i7y=iok#k9;9%+k^`f*z>4#d-hBO|3@zTQ&qX~Q zwCvve^$_C+=KD z)-DEx#HLJL5ec+jQe`*do*3I~SwAJkm(5(&TzPwI?dr1GtQ5~YSPyu-F^}k3jnJq# z2Py&g8kuq!7adKhlAd0k0Ua2Lnw>Qh`n_unDP=FB%HiT&qCc zcYvJ547ML5T}G}Z1+PwLqo{^FK+Sb*)TbhxS>Eel|J8GdGp9nZ*|}oB4fzo4%3j|l z9v->2BOU+5kp2vyo~_P3&dQqrDweU7E`rPn=)5a!&f+G19%o=}Y@T}G3_Hk}=>&J) z6gDkM`EJ3P#;#&fSSNd9e`?2m%Wd=+Fd7Pp`5?poB4f#&_FWoYuJzN%#37h`;cP(C zQ|b+8UG(bDyBi;j(uiJ|Z1Pz>53xUk5GmW}9$d39m;^1+-bxf1WEGcUzuyfJgG`3v zU#b4%zkch)$r_g}REji?zh7zXlSQ;Ov`(-pJW~uS)l)Tn+%m6xEKQGxAFyl+-hx!A zmO57%E`OtpumtB6)_`AI(5Jn2OF=Il0R<)GnHK}=m2bcDZYS7LDz%fF=IW%!gNQY9 z3NP>vY?k5gEtDi8F(@oWZ{Uuh&=oxPQ@c>hiwwfFv))A6o0}kmJG5xReh1Xi!g(i7YQL zz6T93;RF_Uou!qvZlx=EanZx+)d@q`B|D#9i{1zr^UJ{F-tJ9OK-xbVZCvEpfY$Kv zfMwN~k*rHq(AX=Hvj9Ila8oS4Z)~8@M1g-lR-2B|RR~0MEw?M}rvIhp@_wbW`A*_W z89Mv@3&s%U$jmt67?&xuldMS-%a8|x4iNV@&r)~6&Mu9vr+?+OwMknBE>G{D+7{K57A4@&@ zfj!luFXASn*Bx>{H~~{GWM0-eNPfk2_k7v82~jWQHeR&E^AGv881SZS)1ZOZ^eIaW;(9IKGqcLn6&@2GsaYp}TDykU|h#@jAx z$iM0}yCD0p)R|W~?`3Cp8|>44`?xR8~LBm-@AoZJ%H1@TU*#Bz+2^W=E_;x2dR|ovxWP?lWSVgja^tb zM%AbNeZANS=nIlF^SVYp0^pQ&4p8=dyp>2`e|_F^%`6gZGx%ehGrK5d#Qd z{qufDlEzR#CornIs)UK&m(K_B=&*zk-DB?J6oQ;J644~zXiDBzIE_34&gNV2UnEcWdCost7`GWp$x z3>O(lUDjlxYHECw#=^Q8{iM&IMTWy`m}9DFmOAvupaDceh@TqJve=bjXn17mzwY>} ze)sT&p}$6Bxio(tVGx2i-ku+69KdP(%(m8MAclumnvPkj{`FSqIxKeQ&q;}`^&i=9A}-f-`4AD&Lx-~%j|4hAnA zER*l4`!Qn>l3M~sv4Yu5k5>9WIpn4H+XzRg^ZUYdclQcF=R)b@T;p6iwj*fD44vGr z9qfI!z=+(fIjwCTur+OXTok?1;8BD`{q_hNk%$|O)0#r`lzZ%E9adOvF@#>k#iROy zD>fUWC-YOVv0= zHDEDtAM0ZrA&7K{OD~@OKd7%fB7f+i#5486dc0%Xb+Muq{~Zrj9-d%ZD%4yb@twft zXPFveV{b}^>5Ko~=)??MMSe@_3P#@eSgtx!73xz3ejz09Aap*m*NfHX)t+@u^rtRi z!*pd*dn{L#;p?dnci_kJR>LYJL;mGfnTr#B@|ZSF<^uRZ3E`^%UW#gK9A{seVT~JA!Wi6Gc+`mz|Zxz-{*1_1TJZ)?!JK#4&g@+GepS;&`*$;LdwciFX8`43-3VFza`j z!Dn6i8}yy{A;jwz_|<>dq(3n_>~25t$VP+ObtIJOZroe0x)E9Isp|j!Y+h0=HM0zj z)f;-tc@KM$bGNbaV2E;-*D4q}u>o=E#CmmMxGmkp3OrL4;Ax^U@;$t=%IdqIHR8bKKTD9gER7gm7I#1DHp6b&}iTV1bAHo*0Kc)AY$3R#l*6 zBSvBHpmXhF9!?XYcO?QP7Egi=7KgLjYWGs#Y6ej=WD3)$FAw(O=LZay-fMoJ@PdSF zf2JLn*eRe`VpM%0r5d1$3Eidaaf_j-_GM=3bhOx}PN9fNlYJTMDBDyLg~m1p6H|#9#$=lrW5&#UpBXLA^7($g z*YEG2|6CXEXS<*KxwqHrE`}NR2e{8^%w!?fQpt5Ds*XvjXOL`?!+a>n7LPvFC4sJS z`lO}qWicdA*QNH5j60Xu!H(*d7#livH36U6Myr$Ocv1a)=^hx|{k9!TSHp*9N1FeH z@_YgbtKBbeB-CYfEV(C8f0SW@35#?n*zMk1#PpApDwm;;28fshSEJ8c5Ol2<<)pdJ}hCdayX}!EG{gZFqux}m=I{knYF!wqDJbv0~Ih|qz z4g2ZyMOSu$G+KhHk+U%)dj&|dC3!1eE+=-G%`VTd+HZoHOgTeWix}V4@+Qf80y{G~ z?UM7!oO^$ZDWsiBwMlCqQ4H?fE;y|?C3bgZ_q^_p{Xp-^#!4WC&_9DW}v2B`wz zWv+WAu?WR)jN4F1HP-1FCYAlUwRYx?nt4%6_E2eXh`2lh)0;lIKY*fxdVgSY+K12w zi@%!6L?y~yEGNRN1^{&bsbxyi8~huN)n0%F@b0vzB=T#B`C_Hhdv9OYjxS%aQH!O1 zo4s1igP15Sx+tEZUv+Ui)OOR5ngY*p`J>-VI(JQ+o<03sb*^A`{hv($Xz6Ta>-f=h znM>s#D^mTZeFW*l?NbT~Ui}I-yOie&G+5U69|!NuX@`}r(L}nH%yiM@AuV)5dUy7S z^Y+riP2-UzAIvF_1lZslKlg^2HIXRF_7bWoN7WW2V%1yR`M#*asxMWHJk0C^%md4v z=7`dF-$X@b2xR?5={I@G01J-}=hh`t^{A4XKx|qD$IdEL*OS z@apuDEq}@(c3H$6xgEXL>2`ZVo(Tkj5C53ZL%T`I_bgk}$U!LZdU%6%W$+H(oZd)i z_6W}?!jke!@3@}^hzdk=XGB7(gB6O`neR|LYDdD%y}`6(B^}!_T0V~~TP#&z6k+{L;&B+>Ff!n5eyRKg-(A zA$?`7{r*f4`u1@IHEla6+btc!UGY03;bUNIX>K)YX53y9Oos3>ASsqRZ4tjqAe-xj zAC^dQNGOAyKBq={pO~pN_*JRO`+wSxV3oB;>A5y57m~FD#Z}sxc4DJ@3C`*E6WE#A z5#f;`r5D5Q)0O)|+7%3M7KRRJ*(;cFrH(YK7qW?hz7FoZBLH4Eh$vlYpLIbo0!Y}%(z|DKN7sc*P>I)# zzertaMj4ceueKJy(pD|FyZ}06(3;Fh7b~w-F!=zd6~}sUk)BVb&b|w^$06DIjE`ty_`AT-b?>kc0ey6Z zRhWq&Dp}e8X$DUm>L1m`g7G9ho%<-~U=`Wd znWsqLHjo;Pg_FH!ED&24oFPb*N}!Jq2x&?~9+k*hm#0}zw8EOwbFrxW3pd-?vwNJl z=j9H$vDJ~Xr;zsHc>NJaik{p$dlFwVJR0SS8v#?B^zZ z*y-sb%wXYJ4idVnWa5SK=bmP>+@O-YwjGgcD&S?JD21_$(=MAYs%6Dx<<7xaM3b1S zEsrzMVgNGS+-0*)2v~G3xThlin7d#Om>+~ZV3NDzZpee!4l;m!{Xk6y@>AX7Ez&2% zb{xanL(25N0cXEC=QGiiXeyDiOp-*8&F`#qYNXZt^an{zMWG$Aq{yCO_Dd~ zJ1)oC>^b-GT9&5#>Dj|CU&=ADr|P?<&YGU~UB*Bs9DhW@lqX6>$=iD}2fkG&P>>i3Jo3t44yQE|~~ z3a5K&`ih>ea_x=OK7sjlO9KAI%T0-YxA5HFBMu_b>16&jIK76oS%2oi#vZ zM=*WeU5tiyTIH%vTv>Jo9r=DxV%CwUbE&8@9!)fdaRBEpB=`R8c+bDLQwZF7<$Q1- zMNB`9;asaPUqPzUQk$~_FG}>sF=5Ch;Gt&m{2*dtm+i+ZZ7kssQKN_p$w#r!LTfg@ zvbHcnIE`^Pj(lwGiD>aqwe1%PXK?kK5$k6wqnazbDi4m7`8Lt< zvtqA`=kzOYEW!)_CA3?I1qc8$fuSs=^9>y1(bm?eosD8>X0h2+JtipdiC^?u>{E<_ zLT|RAo=EKdMF_<=t?b$A4*Hr_k7?iVR$t@%F#+rBrqrw(2b^*q4^^Z^Tz|(0@#iYm zxCMh$HOKdMVW;sKeQ?Ro?lOjk(Yru&%h_rrQl5KpTBGHS*&FWZhGi!-j0uTycB}zQ zOoPVKW0Sg~vP2P}IAO|9sMFgkopy4;JCSZ{yq^wg9L@6iO@0Yo1e|M_5S`>w29M5*#={y>nH2vPc6?N{vO0g zMmhii77dQ3jYq)*ew+IDWx|$?Z0W$ToiKJcv}A6%P5qU8CIG}m^2DxSVf}r`>>Wrh za%u;vRFVK11uveLN>`5Ss9rvmUrWs=RE?uSuyFL;DLIUA&{#OAAJwrx3<+Wyb-Y{* zFL%^vJlx7?ie6pEsLpdB@JQ^YC*pLHxZcAF)&Bv6&KS4~0w`LCxx@tnY5K=f|7rut zkLzKV56J>2gmX0p)vAr%-1suiZ{xZpKcn)`bn0-D4GO@6$q zrH0%ndiDw5i13PP`%I2)06JvSI8Pid4t9wckEFT?+T;YM5wWCH>fEqTXlUi?o9XNV zn4MMF%XN7G`ssiUd!?2qj@FY*Ri|!`9+8VU&3=aAKMTHzov^^h$PXJ%-m)r?q|CLW zKFZEpf~f-6#8(IU$2dYEf2SB4nwBz=F0#UMbhcBQHu|&eZ!RLDex|yzwX|>Y@-ZZ$2ps+ zr=EC=qBu()LjZz}PmvXgq84OTVY64A-$o*FUGlQq05bURt<@x)wY|S~rl<*mk!}hxt}-XOme7VQIzv{5M>=%swG1Yg1aE}Ub(lMh ztR+kNi&+;>wr~3Syyp|C zr-WY?*DD3nu~H2LG+-n#W2*bzB627D{8vmjdwz_E1Db5X!)QRyRvqXq&V64(XPWV1QFV+3GUzirQUGj`!nyYOkqmm$CmL(-@|N7RC zPFLO~R6j2^168Zh2lCKSpVgKj6Igzb_|>IkxO{?~-LBt8*73a3goq0}C)#grCKA4o zw;}l{oV#X*74erA|K@&oIe0g(<7yGN-hXMXD~;fIsM-id4+xFD8y`H*I_pFBq2dm) zKRLyko6(vi&H+LgG8L-0p&Q8Bt&j0Zc2a|;8|)mAt_n{92>j>^bk=OJ?=OFuedex( zz8-$lojFrR?&IA317h^P57#UsStyv(To3A*Au-r$07E-Z2GD&WBcG3;Y7c}WHEXi~ zvz}HqNc=lzV`fxDzoS$Wv%H}$_97Ay`JjY65HeUNq-rC5*m>DT`rxy&&sVz&k_IB38C3cTo!vJ!4c&W|J z&s10opb9uh*L4@zEQaLe*i2yWz@KWTsYyH(_AKQM)%BdC3*yyC_n!EBC2##-#JJN| zpNk}&KiWM4vDH%Mfm-g-{!pei76k)@CW}t3M9k42Ii`@4lmnS?P0q+hC=vO-zB6I( zF?gU6zlzYbANlh?juX$jSw<;Kd5cO_xWaT;wiY1APm*+Ntb6xW88uru9K47Pl&^_; z_wEJR?+|3Gx2mjn`B+)q?;_nqEx=_K|5NGak*vUF?$hJC!+jL{vsnTAJL=)#*X8Uk zs!v{)^|8s? zUFxM%mG^@YI7{*X{?k5$mI1ZnSmIfpJx&>esvo;~g+A{SeY=cetX`b{O^FH+*S)lr z+pWByb9@K%)gjGPlpDS5hTx&)_k^3`wHMk^KQq^l4geioy3LSnLA(_Jo=7k@{*f|Ee zVu`B&sbNCx2@oQt4h*?RPNUDJ7m)>k!0D{>cIaT^fMyXoV7yO8@_1Aliq?A5Lfbop zE&88g?=8N!1n!NK|H*TDwd?fa2f*jv;_82AD{I6de>oz^u!c9J{Xk`lr){+)ewYae zG@;Fl9mR>$3ted`l6$(HWj#BTa-29miM`UNI`CeXL)8FNPv|gBFT+2x7zt~;ya+tb z+JBdiF0p)&Ksm$9O(M`9o!gCt;RztGf1!Gi?v5Lz6Oat(EOCC+}X^blK z=;4RD>*Uk9d$vUup=+~j&ShBZ0meY3et$Ngd*nag2R&*Xh9&D_qV=7j%7q@yIlCrG zrYN*H1~@jllfg+Gpsmk{M;|Qmq$Zo@Sq0U z6~N;*EN_UJZWIiZM=6}rvT-)=)&tX727v5thy=L=t$B1U7@Qx(&25NjgK2t0E~X85 z9%sDO|K!RLM_Lj&nNlFMxA*AjUSAD@-!AFZ_&7O8UsC&Wd07iUTJs9-r4e7`?QCXD z@l`4rbf3nie$vxTl>1GgcO2icFEjWeJg~hZ0`T+>k!aixJzwF|RZSKKf-^H)S-r>m zmN{jIKIo__O$bYlQ9Gg2dgEsqnNRzW$Y^N=XF4H-a{IX23BLy$9Mw$=h zL6&7}O`Nw!BJ4=wq+C2zu@4v0oLUQl3rv4r4OHD`7Lh+waag_1fh$v ziSePhxibLKTprWuxN{|7dA}}$D3AJ|u7)HKem1I`znQ_>Z3}QI&_|PUm+_#?R{Z^{ zmkP47EO(U4eUp`dUQJHMLY|W|7Z`m88a2THu+ueM~^oWNH>IS&j8zI}@<`02a5uU&z0YT2--~ag(SCIsWR(5t2?!Lso87&zciguW1d| z-@tpy`*CT#ui75xRwYD@IJ*MR>!D7fh{whkZ%g2mv>(YU;=jbbgMK*xJ| z8v##lYBVtFH@~lB0ph0`M8-aSDjWE59bFn+@;)61%AK>=EIJDToT`}~nTK<=YP_9y zQxZ1(`ReWB{5o*|tZTmn;|%r$6g<`Ld#MoL2l(FFZSt}Nm)6ffGKf0f#u7S-|9v!F zqkz}Rs7ncN{dY`t%4>MJ>iJlx1bQT3e7DWB>gTG=l7yr0&? zD=g^Pju5ZNIW5P&fnBds6!EXl?Wjv<%4*#etOlvGu-nr<|Bo}^R^>s9V40`4r0(c` zyhTR0@RKIR;RGL0``CIqUGj)er@x;?!@3%WIOg{BfxEZ z{QvRVB_VE4m)b$dWgt>;=KuZfxZ_6$BLIQzz3=L*Z|VQ0POh&;sB3iR_3fu!Z!U*O zNcPx=pa=2uTpE&>6r>jBADzzXlLDTB+Zl9u4*CF~P-O359B$I6E1JUj3b|F?3|f2P z#mlOe)6>OT$@%5*H+{p8GuiVd+W&Ov-C{JJ9XxP0>wi-Y|LfoRS}I~d3$Cj7!DIkN`p*ni@$3{Xkra+2C<+jRXawt;3F5g~tDSovqzBN#gy^gALiz#**B3 zZ}zEFx9Rh3AZI!1t*|&Z5T;^aOwIEad>=FGw!?TJXhTAxtq?>3M&7Q*>a2WLS;=g$ zTifiBT}SO5pM3BlmCvUs|7F^M11X&RWSgd2=&n+3k%2Z*wVDRRP9q|gZ-m08!kBJM zaKz5M&(5@GFM1A{T(#Vk>+u5p(!&E}GxsX2=3nu$Do4QYr^USj&eV|I+*A-uHCI#Yqrgq68y-$dxQVIZT{Ak1cd*53z9BUOn z(H_Zlsp)zVTX}h-fQpblmeQz7&ja^hehyB+u66X2i>jnl0aE&$3=MqqG1hlSrA}Rv zE!BPAkR9A2FXgmcK49i&=_3)ABJzMS)wFXt;7x-FrSKf*fM&czPsuP6y=NgUglX?s%4;hbkc>{mzpytxO zdG4s@b+{VgC++u;!c0KvCVbP3KI^o7>9IedsXLkV!M?JHu?JA$)p41qQWsOEUI$zb zAs;gq^$td+be%EgB_+E(Kz&7_dS)`;L6t#*u}U0 zD`WO;VEj3HI==LduI+LJbP`=x!D}W)e7ZUdYDqz_5;16YR5nKjP$7wJl$wxWR=EsD5tODhHyNh%5235 zOd4tq5h@n7tfQU)+IC=mMrUL~{eD8fTNI+43?X??m*#|56ueVTX?&->SI14d@PL@0 zP3DxJI|#z6?`ij?ie4+KgjrUi8iwqkKPjD{uQPU7c?EDCvLy6AZ0R$S?8(*LP^~U+ z#=TrMn5c2!B_x;f#jVh{9NnE39FaRabZtX*V)Non@dJ~cc20B;wFqH-YWi>6)Tf%) z@cgpM<;bmoYUGf99Wyi=v!45!@-(P9xivd5y43^whfeD|<^0F&OMqwYgX0w=GE?vhF4 zU!1NWZ3S8;jeB~?Q8;@96pu;&DxBude%}z`)|kgpiKoO?kj-@Svb{>Z9*YvvJ> z#D<;$r0`m26(+o#WMk$cRv`3j`))AI=$*ClFC8iNBN>fK8_O)Xpi*~`2G@XJi|2~V zm!?8eQxgBSAi?KfWAq)rnp!r~n%DOm&n4bqpj^U0p!~+(y)5ey{B8j`$@=tBdfBY_ z)J-rAdCaSg5rxd&LwQA@TK5-%fB!oYYi@J(Hq9gqY#^jzs`=-Cir>N!6h1h5%M)wb z%#B?>U~RsCI8wo?bICyCVG3Z$K42~5HXQ%lTlQCAzfFF8J2`74#A`=e3UxIJh8e^o z-_>J|_9MyT3ZHJEWuCCBsE&Mg3Ilb75#4g{M$T`XrYuapk4{xs4ATEP{YmZ2bKpAT zIwSeT`l0?IdkWKy-uL?yyg=i%7_5L&)~+6d&HI^Z`W41&!KP^uW{K zk?7wp6$LpNE}R>(p^?awgZk=uKCo>4su^lQ=ZRL_u7|fs+gP{2Wtr``Y^`Dx@l5`a z!g2Uc1`C}jpF^iqMNtBj5CA?<)qxkI^1dqVZlb3noRG$uHQ2SVG!vAUON&5U`!oW2D1vCIPuOhb}aS? z$JzGLI&wQJcsySSn(V+nmVp)Kq5g zSKeD$D7FSg+mBQGbhWwd@N>PT_LIE;MZ5vKCtK^OwRhxP6=G-D+a&9?yf$g+>#xKQ zIa~VcP*vQnoF)A)Gf$hV*Z?KiS?HG1*eA`iyg4t}j4@neJtm1y?~0%+FgY(7AieGF_^IA`=0EJ%1)Z>EqxD z%KmW#P(lUDlE|0hNr^v;|MOb%9vgjQz9b3jBQGv_bgA==Vtyn(@8<%N?S1(Q`+xJ;$N2AT|{ z<9+nEf77BZRc4n}8$6i5xAU|C|1-(G-OY4~PQ?sbjIGtGJTK`EWmY4&ZQ-GTLg z{@B&PsJPMb-KVAg_HSpScr?z+4V(=U&0)Qb+(%rsZsWo!#t^Cx9}$~9-=Zvf;gh)u z=_aZSE}Wj9RskXg+8{iCElpXTn-JE87HcnH;zAo6%|u@oOD|kpUsnU|Ig#ltxx&Es zR${&1^J(F_l=;=N@-bpd=WE!*mkxx@NG3v_3wS|OpE`XzjQF6F<_G6*gT%G;P-|2; zy=URdGIm1`%)L+7`~DxnCj~i}wQXW;Bsuk-o)YQ5kJYb;QCl4u_ig6~RXXo16q6n< z_=oEYC+7-uVrURQ>7{D_yNZk(I-wb2-6USvvBsdEeq4h?P_xT^i=;n_Nd>=(vvXqu z?WXF2b3UWex$3L3luT~}35<4S;b@6qv@r05Y~s@Gi*9|pKJi5!RT&HS5Nm+HqV+eI zAtsi%!f=5kmaEtT_0?7>`r+2cae5Zx<-f}?IyZgpb~EKcqFdy2Nz}7Cc8d0UP||+@ z19R~WpzgN(_^!8%FPcGIIFFWSEO3q4`UeV9<9XIn<(GcM%&<@}7m3!BC=ZW3d|Tsa zRoW=hn6rL%syWGBWRRXlEGw*-d62xXgvKfV_BEgsHgrfW+`;W&2VMUBz8{TeTumUP zvZ6Q1?)bT?6^OpsV%Q^!X1C=x*`IiJ-nQFtp@{5jR4Cr|U64^H0X>p{lEp~UjGrhW zpUJOT)r?DS+mVesTPezizF07sVCaFkhLnXD>ExH5#oHw`HWE2)JY$)GKE4ISzTc(; zm$m&GgZpsVS=IIO*EShdH{yKVW<3k5>c~C50TdU@xh<`(-*o11y7FtURexJ%xZk36 z0HyoY;S=wexhF1H{(Vo7(cq4RpJIkgA44;UkH>X6eUyQFFVm)J+M$nFx?@TsWtrt) z?_xad`p&j%Lk>V+eGk5PbTlgLIU=@vC82UjmNHyeu?!F(S8pq@qL8BGa4=i*UP-`AN1?q?mk_6IOst`l&DAv5kb8UrTyUp* zu+~O0QTWdbKD+v%a@I*KGU!z2EPTZead8O*iw9ue?~4aT5ctv3I7~KifB0NPmOM{> zV!@T>y)V{^_}dN5^N_v&L%%_6*((sNO)7*adqBFwt06ayvIg+oX&Gg(SlP&yjC@=k za!||aq(Pm$-Gz~`gRJNIm&}_KoGx^s-_ib7hcGywVzkf~VDkV-65*Q!f}Q{_%R=Dp zkS1&4S|6Vo!P9^HY%M7$@TP%>X_tze{%-tVi!st>0(z9BgzoPNuxmG;bQB(kwb*K#)wX?Q#jpuggjyf}uy=_>WAn#GUz? z!BybVDaB*Di3qK#mx)=Ppbz1KuST|N5~`|(X3-X3zZ%AFcHd`Uf_Ky#HNT2}7hAT+ z;_nG~3FT|o5lP-z7oPd-^@eiu|9Pz0w(LTd-3b0<&5%ZS zeNmq%)OO9fCEMJgQO*sK@r4|GMG!{F%FZWp}qnoz^#~>Gkb80UUCvRo$ zF~g#uv_;7@5^8;wR|I*p8FA{(VigE4$9~eyBd->I%nmVe4N{;Q*?O%*G7dVNdkSGF zKh%*apj4S4Xl@c;^;;>1BnYv3tHf8jJQ>~)Pb6ei&4!bosGN_{$mkLVL=8;#uC-oc z)aE1?2(6pxW$%KdDY^70twAj!&4bxAvhCk)!S@6;a>Yoi6yZc(=gO2DX;A;oyzF*EZGNg>i8c z-ru`XiQl#Pg1+8SW&kQu@S95=DYh@mCK5TZ#5fkl4FVaFdCuw|e|jjnuGPYwChYN5 zJyXl+xi+6>zmt`-H@UA6&^M{p*`may38YouNVLWGaDGQ&FaVfamahn%IWaGy2Mj@N zj}{Sil)Vo3w20Smz_5-NUun3P>1Ers{W#N_X~VQ-o?+TCImdPs;V65nzSFw@*ygi6 z*~WsAQNcJ0#U4#2JgE}v2qR&i`I#H4VWc6CxW{Iveb7G1k|L{ow}?`IoKL0W!~dyR zL6WRkP)fMqgccN+iA7Dq+`g~`OhRJ&uL{WzV)I7K6Tcg}=+WALZ_0uaQGlfVCOkh~ zG5bynE@rr!KX$3Mo8Q>s#YWxV%H|R`@!li(OcID3?{;_iebvcr+u7nphthp$ll;5gG3|%h+k3&k0%lD;DQ1A8vQ&P?P~?G7feU6xnx?6IbzH__L?f!uB~m_rQkgbeJzXwN5tf z!tGx;LZ$OR%};7D`TL|e{o%AUQnajM-U&c)BBcCk9Vo6zF6*|n1N18nSrDU$AU$>+ z5!B9_P4@hI&cPY|MSY!c(W0z*t`8w_mDMw>D1`m-^&|XRLesT*6t8l9Cj7F)L)Ho)4|Y>r+RA@=f6? z{+pfguIlCOrO=uOdAzF9^Tv*w*9Ek9EJk?os}5xN@R#nem@cdQ90t;K9myND>saA&aCaC)427>|?ve+EMGLxa6&3G*#zr zKY(uNGUo$W%q!Ta7{4eyv{XlF7CQn=;F249{FyWXv%_O`iPi7wB1EL<&o7~nerum0AAsgjf_F9?67jO(tJ zb`*0<3xMLqziqz>u_P~t$cF0l-!N48X?Cq4N6X!k$ZkhfoGNrVe;es9bM3UMgi+Nv zX1t2=%P|#oa7Onvj8e_j!pB0iAiRRbU_%wW6?*~pd?%XI&hh;-VX?C4xu>+jWPXS4 z=5^jvns7-)ZHYrN%}KG8C3VisiR=)KnGMY6~T|c+AgNq z*V0yMm4N)aTET97qt_9?N1kFBt7V(Isu9|J3mUZ={fDaYOIRm>@_pmV5kHPj02px2 zD?$%#HvP~rymWQAy0AIiQs>!B ze_&V@pMUR;;q*dg)UOj!2T^@7yKk>ywiTubW%eImdd}&vP>ui8+uv^qsf(NakGcAx zxf7m7K~BV>b}g4b4V(YtjP@Wnx}#N|C$JI4`u}mvS*BpS=2W5$g&&(EHU$3aj)jWp z#lP|+Nm^6bgSzm+A=6FKhCHQUL|T;z1f{Ily?~5D^1Om0dj7P>Lbbmr^ESBpai2G; z0^t_-ul@FdYwm_#Z7rcx%$X*!+dQM8?~8O-|Hq8ZA>rIAk4+9}W1Eu<6CNX*@iZ zWPlWEc6i!5Y3mE39R@;=^WhIVXiJVi!C6->(`JNdeWwZjTK1Fmv)fqRv}0|dW#$B| z|AicANoh34bXIEcUo%>3^{H?vi-slMvwW#v6>Cs8|soO!bcH&mYuAo;NLH93n zwFvN5wO0C`KM!WRpi_s3%*O`Bw5M4ErxN{{Hp`!kDD`3~wPU)ZUJUXJB5A&>?PJ&! zJwyv!cWTiProG-mmGzH44q0p5ynaICZGkKivTg&8dZ*17GtXI^kM|dqhO5ps<&Uy; zq>n0W?=8EgBO(i*E0T$;OM`Pthf)ADEp^6o<^ifD6TU3VOf6)t(3!^zivQe>S`l7+ z{O^+m!AEhuXePYeCg-o#yNM<$kmnaOVbTplDM{YSBiQG#2Qx~(-jP>xPZwidDs)m{ zp`oFA>m3(xUwn;yh$}xk^qfJ5Qtnz4%glB|N4 z`AI^!TKMwtJ@)_8=5J+f%mTZk-)o@?^h=$+%Ke|gHCoVU1O%79Zm{JR)@1X^3f7@3 zb$-8~`-_ImS#-P>klnn$FZH#&i43Ie6>W^}WW-5%t6Ed@2FB|#eVBcgx9R!gU7z>z zDqpH1GOL7^P1pX}Le~O|x{@TkiYKV}ykh_igy5#ZdKIIn zjZ!K>pLylqDZ@ejVBYuZeNlN6bAKarpq&__lp016)G|5&DcAJptDjD3+yQy_RS%}+QErF=kt&EfV_g|8&&I6@E zx7Ug`gmM?{@%Jz=A3)6XlK`<+o|<_=7bUBM5CG^nMiUIa+;0u;y|r!!sKGdaE9}&& zeE)l9dF!;7Dq^YVS%Qjzy*5hHi(5$!PW@Yz^Su8VRg`2lPJhun`LQ`FUVo3Jhram$ zzzUK8i{U8TXP(G#=8`Ey*=L`cdCKYa=e4oXd` zGZTn;y#gboPErA(HB$bhOK(%k&Of1j_JH!cFfvjx6TX0cT_T#2vebqia*pq3U}a6o zxp%`|45K#o?DjZhu5qv(?>I|I_pfDlFTss)aB*^1U;oVWauL+p%yjg>*~Kw zd7ifUD@FScX{0zcd9cdNrh1spe;Pgy5i=2QLE{@VY{DLIHm}G7G(CR}kZ)*n<{oW$ zE-vtR9nc9_*e}^?#~vZqP+nbs!gTt<75`(h57XZO`3R zKP$Bv9N;Kt2i(d&0zP1I|8JETkxQ*U)0{5-neg%#k)`LfNnVC`>c5Xs17vjN9J?*j zftBO~gVCPXCog)`3Qkf|d(lq6za7-IhPl|)FyB%+>oN5nb5o#Ni}!G{yVTPk=CT9c z`EN0!giYoy+r@ZbXjbVp!suGhq3cS~ed1^qMkli2T|`L*;Pj)S4A2NsW3*J2Fb7KL z6}aWnPN{#R>i@d^zNx#ROy4fu6!R@|QY>8#*tziOGH6G32eB{IA=g!~kjMP1UX^fahc; zC$-XZ7p-Z-DBYz@KIx`O;%;itdQisj+h;q_m(u0RU1?~Cgjrb>7T=+FOMs_<%aV=@Y};b;ZvzL`iu8V}Hr3vX>7t07zU=~w`H z@s+(BZI`*Kog0=mu3A-K8O1?sLtd-5cmsl6xZ3aXhMvti%MtWH7Mp@hY}@hrgy5?e z6`goE$ng8*-RBZE9r}If53`xq2Ub;nIl+(+Pw2jC$d3PfDD=x&l`lX(BRI$HT&sd^ z-7%Ch^Sv4Pd8_hY0Nc8ujnmYXE@)g3%J0x2#yZB87v?!is~)B5?D zwj<_0EUvaD;ka$hfq|DPSvM3z&d-n<&-d^M0VxA4_y&Ym?bmdT{jsa>KzODCu$S9j}`) z=*ktq9F++NR)bZ~l5@VhA`@PP{Aeuq#P63=H3ZinNVVHEs(jFh!TGJ8OUeqNBncjt z@L3+4yOO)-;as^Y`1bl_AoL;<(5>fOv;q@eaTa`NR{^LqYX?TlrLkG#6a|P*PB53o zq7(2@X45dn$O(po8-vuf8vYBq&iX{9&ul>Vrw4{o$J>Jvj`sd|$#+JkTanw$brxHE zOfVbmDRhzv`*iIAT;9490&3BGno2`*Hk%WHHPu^Z=342ymL;Wb-AVPiSNMHvZi8IZ z+Q&jL6<;#r8i<0EB((O!wmtK4b5Wn==c75PXNOBRbBrHwW!h$ zmuxfSZiCjKKdXgHJv#D_Pme0`xD z?;KLw%`$hnddH}%*O=N!hq*xOwgZGS_NJ87^WRbc@wwlRzI69Q&YTS`Jr*iPl{;)4 zpIAekUz^E}gy5R$l3b_FQ;LG6q^`7fP%kc+vQFvR1CvKuI4$WLdU`5DXV>cE6AlL0 zZhkV;!P*ad2f7(cU9oKc$G_lQW{xC8@7r6@-lW>!u^zMNBKD8+)uJd!synW?EOJbs zV^qzQl>&V%SL-imn`bX`AxJq{csM`E#eU9S3*?z874m&OIjWYGcc2_+z#yRNT~%9z zSrH{AwPBe6vGnox26<9aQio%}$G#dg;8%sAn@x>efl@wAN;oY*fN!kCXjRb zAYKoCp3onueGTq_->%531bs7Vz^}I-UrYGrKZ9Rwg4(|Mu;91;FG1NhAj{DpHTrl zc)si!2qYS@YbdI`oBCeeP82h7c0e$zFzf2<_{g(MHOmAZ)=sSYH55=sCl=>vsnbmv z_V5m1myW{QU?kXpy}o@Hhvh_4*qE(BVhgXmq!2$!Z9+RVbu}VsqqkmgNQ);Hp*LIo zJdFLlljW6PODWn}@Aul?&OB9SX1QzXAs|Y>rl<1r(QVOCM$Z>Z5tLaLzwPKI6Urga ze@wvTaHSe|*&~gUZO3XXJFi)=QNIm(ZM3F;fY|4W5{8m?iXKEQJ4x}QFf=`|hYO;1 zkc8;EM5G?$y*6jlszO^r^09zBlPWrbQ*hUmEJT*I=|*MCix`LVcazx6t@v%k@e>4y zV7y*G{&H$cdhB2DyR~Q(S`QyJ_N0-DgQxZ|ui8ggbYjcisI4)Z+;= zmY5yATWeY!^RFGQ{I%Kf2A)xer=IVgtt95e_@yGM9UI2o7|jFP z9t1_^4y|nX6yK8nQsnO^qCjnXbwr0=b;B_YLA^odo=?2ksYB2}>hW9pmhvkT;g#Nf$&W`4cYS}Fo-35Rvl%PMu|2P{g1Wb9xK;mU z>P5`X5Ss$i)L@&fRHqpE4X+MgAn}il1Ma-_XgN$cfb-GE+Hf8H=$km{y&^ zX5~K468KY|#8B>4)Z*c9|9A>!{$_XvP7QtCkW{w1oKCAFMEaJw_6W~V;wUiCP5x$u z8u7-`bi@~nX8z!>7>DUu?+%45t*MR7P?Z@BJao>mw<^_SJG@#{%m3|78TI^J|0Tcb zPn?uvoMaV6UL41uTi8ZK3R287!-F1rLHR9a&2-Ras9|yH(^@>F;vxKQMdeebW#_TZ zt2y75%oVK*inG1Zk+w9b%?;CO-Qck6-K+-%clV7?-_KfoH!IYsaUcJfiWcL2Zs#+N z?mI2`2K^q5PKC#gu!Bo4Tvo~QCRD<0IR;~;maa(c3*-Gdgy0U3u#6E`Bqmn)g*hG4 zUT)m5IBxfNs+4PM`PVqXA1PbWKY)oKPR05#Lub9NYLzMX}Gy z)oZ|ypj|~MfR7?7{6I^Fsm7aR1;akQ+_}ger$Yd zTQTMZgCpjaId}DN`-ink-K(zqH5Vsb?8E~?xZo$0zG!JB4eiwJmi$_HYUxa+x6_78 zjM38Zt_Ke0?r9TQRBZ5l1nj-Z6+g^Hoq#z%&PD|-oHr_ld1LpHXm~7a%b&+_u#DJR zbC(997TzlOY^wpXYAm||9_Ev+;5QOlICwD99UxkLu)!LR9g&`Jk9L9QG>qR?=9yYv zv91Jhm)STLcvN4te6`lPC1rS~$+I6Sxo0a}an>?zX>eB8<<8RX%colzPd2!WKPF|W zZMDRByX{afJyi#3e;j-ueiOag{b-tB@ac+^3jVuJ@E^ln{9ND|Z>T8n;&f!Mj(6WU zoN})gMbYc68W#A&UCPlO=DHn*DdayEYvp@C0Fub}bJby5l?c|5Gl_X^rsEzM%~Y%M z)fCmlVKQw$N7dChl~!pb^1m=n)kBlZMXYD=SLow})D0JVeVgf1;eP2w{Coh~th4Ov zyLFKt)-EU#_%h!RtSBKFXTMu=Qhs;vv2z8T=Ty`!r&W$vGWv3zDzk|95b5D_g%AyX zX!$5;eM193i{RCVeG60^mab&QvvbBcz z7+xvJnu0fFX*HYiUa?b-%{Y)}Y4A#f8*@A^TGuI+UP`U7BJD0eX_(N5mmP9`;`$yG z;~H*v5=tDMr21CMmoH5pFqk4;PpCz7J)Nig+A_v$$n z->FS1nek6`&$uz%&i4@@MfdFl;v1DQn7^THWLTds#Lzt-sUMd-Q2fh%>E1mQmc>bi3f% z{#VHM@xuVVn`2r40yx3H2$rw$NHZ-YI~Lz<4N#flhL_==F!8@_`4S3VKhZ^kDdnAC zYRUli7NRa3Q29M#z8NOz)DD2B5>qMbQYk__;8vF)Hqk0Zghp^@KNmm+c%?+}Gg0{h zE!OJ}(Tm_KaN9p=R2mH6RFNe_dc6w;W~p`|1&YoNFHgv#&TQp3<1f2W+70uz<1O>J z1{DHjN;K0PUT@gFyEI%^G3e6k3F41MxQg)bG_ti`2qVcI^?!EE zZoSq!`N*s9@AVzl%c)-l+{tzO)%V8MX}|tvMQ^Q*iu-(H-xh}hw>p5^>i>q@XIIWv zGh4qbyY^S)(!Z;KM{jO@?D4rY@wdzWt+lJqC)|FQX&1U@uix#Y_sj3k{~Pz`Tjs83 zmrM5M&3FABynnymbMCeNr_Il<{(AGDz5DSFKrm>4=rzul&irZ^ZYyU;i5A?k{Wlx@NVBuk77reT(g;m$HQZD!;t% zvela4wU>UcSez*vH(Tvi+3k3(|CY1r+82HO`S$w$s~6ATTim<1eOmV7@0V+S#rTGO z+`awn%R_bQzhZyg@9n$)rhM_+jmfvqC%<2r`D>0=t>1pXTD{xHCocPWzxC|xk~uGG zP3Ldht*!g`y!S0LR@GZ!k8gL^ie0SvXF9d++uM^7w|jGgZr>7HCGk7w=0Ee;Z{cMz zKhA6Yy7^xC@9wp-*>el!Q;+YN?|$3h{r8mPbL^a#ymZ(CKCD;bDKk$qB(YqWfBh%x zw$829Jj=Zej6%QN^s?%Yda*cJ^U)2bw3}s#pnJ!edD_8>o#dySaErO{u08pn$L)@t zD=)2(sNI&!vt?Gqi^;uBmrFpaLT+TpyZvN147{nDA-d%PyXvOsZ(gsK4 zt8SZNhXnV3o!PGQo*SE1wN0>FY?u9wXG!kDm-9GR+(Eik!0guAC4o}T8;iRSH43>2YuQ{+-)c|`?4c}u`@Z$r!WC;6e3;#} zft{xYk-62Ni;YSOwlD#?9v64I11|~!-hDpYB&S$?7nv&Bkoh2k71U{DxZ%`d2WBut zcU)ixvl6(0%OAlYN6|?h%xKVcdBF^3ZDF!RK;VEFaCIe^h2OBbtA71w XwlE3ba!R511W3K7tDnm{r-UW|N~#2I literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/sv39-full.png b/guide/source/chapter4/sv39-full.png new file mode 100644 index 0000000000000000000000000000000000000000..5678542eb3eefe7f421d84f8f5ba2ecf1e7496ec GIT binary patch literal 141865 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 literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/sv39-pte.png b/guide/source/chapter4/sv39-pte.png new file mode 100644 index 0000000000000000000000000000000000000000..7f693907429c67ad64a0f1e731fa76c7aa0348eb GIT binary patch literal 12849 zcmch8bzD^Mw=M=blF~>H2m(4tH`1j@DS}9+fPmD{N|!X!jR*!v*N_6zNOuh}lEZ+M z)P2YAIrn$Yx%b?E?&sb=fW3#!-uqqeif28~B3x5LnV5*42nPp;SXD(q8wck)3>+H~ z;DPVg-bkx~A6HzomE~|s25zl`lk3*9k7RLh%3>gArnumo&`Cw#1qX+k1N(JFRhxYm z2j_mLs)DR8+-N%!e{!^aI%K<1q`gyC(u;TU!4~lr70(}@utt%s#z6ce=wWmo7q>7k z3w4AUnvqOatIP~-d9j%V!}QXWH%!f0c*OheZ1&*ZX*en0w_3}zp7*rIg9eew5wK#v zE%8yn{&gbw|La7E2IhBp?y*1XGMLI!iWr{tMmM_4M5rd*PL&PBOYOba&?kAk7`T>f z?1vc$EAaf48``JL?7Olp)OxYI^u4jM?d)*IajkMhWB(ATvm<3mS{1x-3O*8a z=E{erU7VlJZ1VVujC}j71XV|?&TpL5`jtlNE;H9Z{Lp0A*qsi$H8Igg?>w!nr}}A5 zBOxt`j?<3^QFfsBwu@tcEp%k#_BC8luVo0^l z^6YG2lU|*@*>I;?>f(5Lek_mv7fbXlv0+2+?J6r&rbl)2wnNR_T4p9w&sX2m!|EHh zm8S=r*42|{kp0zUV=uk-{EXAvwt;z~tJBxEPwDNxnBtK#+0XmzKYAYOu{AmLFhg{x zfsILZ>IpQV>WKaEfsbMH#FI}L(ier=3sqSw{WQ^=N0x72&-`Po^t5mqk2$ww{ny;4)RXx9lG~aBZ)FATFJQmM>Fg&; zGS^3o6U6qqpyqc%%zs1+Mc%D`rbzr?*1L!4WiPSFtjVjU6D!A3!i+CTPYt?-_BY8WH42O{&v5T#v*KTe`LaAooNwZ%#LO zIG$c~-c4uU{-o87^o~#Vk}g@;Jj&QL0t+F3X^Os2ZNvorsx&Heuihb*wvd#6CXkRUm_zk1wwPbb{}7ysCwk^?r!CMPjJ<8iJr>3TKoZTGuH;c(}T z;*SQ(P)WyoL~B>Icb8)86{+>xx#fzUv*~l&W_TTJSl)h^ViGNLaje?`nUZ&4wQvOf zEtKtlQRh)WC=+$`<{HVj(}@=znW^T{Vqbc0T@Ow8HVihiTS7an_9*C^Ho9WM$b0H! zh>bBqs1uQ1(J!2??>6?N5!%nE){YvGKD9@ycv3bv#tU=xf7(f7==65(2gZ_w_eZ_krj^Xmly&yhuJ+o!_wuve)X2SF80<7FPZGPZ z8i7H{3VnyFF$A=qENuYAO}u~4eSzIUGf}zhHESK)!G4za&N`!Q_f-h5iSRt!+_99; zcKQi4F8PSv?!c$Yuarl3`E#8TMbl?>iz%9takNV+Zv>5M)l3ze8|G?KtXu(`bz+d% z7mIrwWvc1I4))`-Tq@ih8C>yoU%s^wRU;|aA57A5a}s__=~Zc?Yg5hVrfw4^T>o8M zc?B$u#k+{v|MI*>-=$xuAB6Ip853K6wjY0~Cn|HIX}PrdqTZugoM=wq2C90&&)e~F zfnsrIisvVg+M;SEZkUGnl(?V<=HvFb+!h2KG${+8)$tAYiOE&un-s+IN6H(xkJ(t9 zOLZGa85b{XvaSAkSrVU!HgMeAg8Vo*HROy$D#in!Q+a`Su!O=-^*x;W2zmbdJKcge zS_-Wqpesm=Lzm_;ZOfUSnW_nkljIs&iWQ*9i_5v=lkqJ#M&@F2<}>2o7m`S|G-JU^ z(w1SQlu$kWlE*viC}YJ)HBmj+J4BYF>0tbMqf{LA2YU1O;>$kp3(4*|(P(*XLQq5s zi6h!5d6GRAd?&JIth0R)(7UW!^V;fnSGTD+?>4*?EWgOI_?lHZigt^8?JK0G+T-z6 z#PcwC`HydjPLHE=9Q(|+L2Nx7Gv~1|#e6;RhBY_GH35_+nYygJ`lQ-;#Vu=GZlxZp zmN!@C<8CX*-&KhxelRKpVf8K|{vJYH!7XZe^Li3B)wppUMEQ$)^1bRa+9`;Y9xPez z=tdw^?wQz9DBBC9U?=Z#C&ly9razxDf2gfF+;WpvuJz&oVUi}y6`}LRkd|)6Fqb{< zp{a?2_&wW6;712X?2!jP+J2><6M-K+m~OI@>W%~@5Z!xKpAr`Ts%GT28zz8{WfWEP z^YOSX>IZU_2RGu@#7^_&#XNc3bz1vT0vx)slSaCwtG7Y}Nu?(*WK=k?8Jk-EFjgAY z_&eTqruysGuw61`&l-O6tR>&Ff3JiRe0(0%P-pt$a`Jm)Hts;&giDHtPzL@9Cg6GXyH$g4s_X-!4XvtNL&V1?D zv_abKV%oTtFONuG{t5(*vKPq_vSFDdtSvn;CqrmCdZKER8H zJ-%{!9t8IuoR&YJ?trK?%xT1@h0z3gYOC^*@(~c`AIm;-r0X(?qEO>97fr_`=^5FU zK5@rbuzGKupt8~1LM~%Z^rjZlBg$xBG`Qb=-WcuucuL;4Wr#y;dbC)l5&CHH`tO~& zncGbH4~f3=41^iQFi9aA;feLuwB^|Xjww#BcBHO$pKona}SG_bD=pIWzP zYD6SE}KvPpGGz7uGj-3EAjP<$EjIZ+@tQ<~Xl_pOv4sLH8j=0B!|rfs)wYh?U-p~d9< z7e>R|tME+-Wj5BqgTGhrkDeUkB;0 zVp-+4p7KEN0$_|UVtV(LoU-Rf!lciu!?s5Y{>}TTdklmb&G=04mZp5s?W(*iklO+u z{TvsNdRyK6EZsQFYwF2-*M@iefmhQl09QAbm?LafAd!`-d2<@+0MGwhF9jN^RW{7O zPBftZwi%YFv)_uC!@HVH&$ZOGFBJn3k{|C% z%&2l^T6i7pFnZqOnF%9@K1{y%f^E>!l7ZhMY|8dyCOEd;9Q&MH_bV?F`?$REGkI^B;t|tRdfwZd0r=d4~DX4`LI!ZJ7W%#tCdp&l|am9Zs5mg~wTvh%Vv)TrmOnp0WVxxaL}%=L&Fd z5dhtH56ioALz!OQYd(AJ2usgl$YIuvXotknQouf;fES1u`yPzRJg+-D+aJ92Icz{T z?MIK}19+D};~fjvk{X-7T5Cp10o!}q4iSlkFOg8dW|fe^3@Qk+0TxW2ms5dNwy%4| zsJ42l`}VY_^72TjvCQcdwm-A4p0b)B`h&e{4||JG9}S-4=xwpaAUigZS+ zzUwz13n!1kHZw$_wpu(GB&ci$7ZdRXTZVt1(q2=feo)E|B9cB)3&Eb5MW>Kh-xxpA-IDe@57?Y=)n&tOr9g9EK zI%tf4OKaWgX|kIrDO8SOvH}UA>hhz2YH0LAN*G=3<;7_~wkOYK@DE;iGjQ1z2i^8O zM*CmdX-FODx(tY+CbvPOFTk1MBp11Nwirmdg*uj;aFP-u-H@d~DrR^@E#&xLUaWns znctI6x@8+lQ#qjyYpl%7&!V;sr%5ChuABGToFZ8Oo@P@$`&xZQmRZIR(YOYlTDh8V zT{Vnmv<|fY2wzx{^0~*mGhRfXEV8n7H9iR5iXITyy`cFF*+re#zd;r3ta@>WM_OL&{CGKLernH_3lpHJ7lkd) zf)#!Ik)EJG>jT}aBbJ4@*@h_}6j|^o7N*cgg);kn8`x)ybB`JMj-CA1jEw@pvyGHddrDM$hfR->7a1}E{n$k1X4$q(0 z1?TEGgE&aHOnx!`>MYw_Ho{Gl>?(=a3R%UV^yy@Q=I1Zv5$ls>`Hw`Y3$;2Ty{4~@ z4l^x|JeCnsX7Vi1_rY{DLWcxDVYivf3gVi0`g`3RcOBc5Tu5a~cvP=4DMBM@v@F#^ z!-t%EHn2_=Jx%@G-ZXO-+@Sq*<@ciQ$jivUkYV@HM5zc*-s$tc7f#(N;hX}N>fFh^E|4n*;$Pe zy?$W3K?z$0Vho8x{d!?_Mm(DXCSX8nuo8>ql;b&x!5JsH0RrC_yCKs|4a)4RBPzeXL+XnV>5Mly60v66n z8g}@ zsniN1xoOH~AHPtMjViLOlKiP)&Y5jdUM-*+wmj**GWz(&eEa}lsz6^wg}=IUJ+%lT z^eR}KOLuX`zT%zRiqEfaEM`v4pG)d{B&HSeBWPqdY$36QQa{5?NG&ou>srh1C}BS> ze?{8S4$0UD9LTrekt0Ax8K4-QIUa)jlvPW*!zehdCT?r$)Ly(yv`Vrxx6<%E_Ye>Q z=~4p(?yP`7pz$V_(`7x*g50ZZnfXi#VhH>hejser8&ELK+q4|A(@0#jxOf*Z3`ukMQo00eXu8JEu1tl5EIORznu=uC99^u%@xl; zPgQ*MPzaKpToQ?(FDu2PX^$ipo@|k3pz>lpBiGa&0rtxpAk1`=QxJP>eVd5ew3>^^ zO_N}gUK0KdbeKu~fS|EKwfP?}h0be*(`Y_^{zh<{m4IB70;ZPW=FMdRDQ!GVOSLUb z?ZYyW(Egv!2ByJOh(;@RBSEcC59wr=B{MDk|AdmVRx3171r!^Kel^7e6fuai-Dsms zTZ=I7@tx4OW<+=W=KJ#mZCkDyN#i_!U+Hw*(B)CZq*-KA1`}1NU`M2}-${pkwX*sRS(btHx4c0-Ro!w4U71=|`<+;F#udr3RUjr%@F?lh-c_3~&jSC#TYC z|Fd%@bq$~7ceD!P4agq_wxqJ`M(xneL(MK~vb{PKz$<`?n1wIDJDg2-Yy#AS98&S- zhn~a%I@FXAdiHUfH#6}urNYzuxYQDa5yR4=tx>9!lj1AkvRROeCbQz}VYlbN+d=cyc(C@6bG1r$ zsP5|P*G2G@)aE@oX>xO|otpt@EDK67nR^+^qa(!db5Qxf ze%FX^j*>aPxk6Lhg6-ab1X|Lu)QesXvAh3*uSSGuO`g?IA$a0izF`m(d7E;f?$g;Y zZZ3KTqucSNWf-;ujPS!^^mok$5A-XU$G6RI1fiFY*mCLB@)qhEcH1ERZ}FLIrfVD* zoBfwnEj4T8O$) z8-P;SZV1rB&krVm*;&h&^T@M5Cj4%`JRiK>8=2641Hcgx#<*`^f7-I#XP#O-*(uU| z=@ZN@SM>RV5fYcIqos;n=u1dtJEV|!>E_9C?q%YOVRjCqV=coQ6rI6u+vWDpdliw2 z&S&dXmlsFP4q1@};@?d{s2YAkzr1TiX$KOTE#~T(J_Lvxl^z8gbM1*OCi5ZFL>e$Bf~SpO}M0d=ub`OGFac&nGF zubDlce<2wd+vx>@#r2QOmS7bAq!zJmpex|NTUUer6r+IX2sV2er`%c(1 zRyx)|!n2*=mZjS$vV|qbEdjn(-M41PxuX^zNZa1vI|y0!O4^nXhG^>yhMvcHX+6dS z{L(7|i6rY#jD}=|KS2$% z0h<~YqlYPA+z#^GtN;vLd7Tv~4P7N)0mZ3C^+`ejD8Dif6R4=eELu*c01fxGHB|38 zL7OBrL*czPahrk| zs$00IvpJ`sL^Arc{@(v)*U;}rcb<8Xu|`CbPK~Lz+E8YHXyn`rL7U6#lB}^3$bLRaFMd?uU@Z*^p@8vG zh;J|X&|vvO-&Dw5HwA)QjE8r03MYMaIYwpPYY{O}Cy@jzA7?c4T0RSo*!SgfN;dK; zK9`B3j4Hw8g|KGyWXDA1e{b~6VqsS$jPC2GlYzZ(JHjzGzV3LqP)XdbjU?S+4${I~ zN?Gee_(eZSzYZSeynAwoK|EP(_caVu7`QTznc-*rx4q|qrhYMm?)|3)(BGuB1 zQbDdX#9XDKOovgX@nZ6ts&T5yL8FW5s+Urjx*F$6a3mV6bxbG`PD03r$s=rjm@nSD z!plMtPa>DNtmJKQBR(B7*C9UPDq7c>O}ZVbc}kYLehRHT-mYz?=c!zX-x@$}_1<)CZqdt!JSg;K^43EG z#541ELS|D0nbmR*PIUzwMw$~NA+fbLX>(Slx)fst!95q{eD!!RSJkjZ{5@P&X6Evo z+~kV!+t#xJTUt!O2dxuXTgo=RKS6K#8lg8lS&j|GHtlq-9IcQ1h+y@3ACa0&&~q+r ztimM(OCV=xPu&$H)!jA;_$Yex12j}l<3`3~Q4QCh)&cj~$#|39aQ%MN8ONCG({%#= zn0vJEuC>Ox{bvu$jlEm>a;(Qs_@x`p(}u-c;dz0ewzR=UJ27z; z8|h0ne64!wqY5Dg9q_$Tk19%7&NBw>JK$_l*|?10Itw2wJI5p7aH0}tIbpP>N-<0h zgNlkGWF_D0fc`utp-rn)c3w;?t!L;Qe2!=ymKR&VXJ20Vqit%}w}})t8fOWjz(-Yq z2!%;a1o4w8>USrL(8IjF+p=?KjBkS4sx;|f>&*<@?;GN6^KF5|BSxM=n8EUB@x zUCAKJ6M5FnP7r{{c+Fo|V&~{279G%@>bIiA>cc5e-GMk@L`Tp6y$XZ|N< zDa&zXM$`F8NK6vrr_$XIpto>wf zt}c*iEtlE^w5(Dbkip3CzpWRvttL>zej$|ZI-mo$k3Vx$8eAX@<0)agPcSv>7UgW( z_s>?TUQofpezG!?xj*5e2sug}S}nl3phk2noa z>kDylqF@K)7m(r4)5{vT-rgakmqW0q;Vk9FYWIf;$Oz&Rv6GrnQ84pMhU%@Qh`W7q zlYW+aEk(KWbpmLCKFs0A7h@ zb27S5J2%&){CYI=d?=T8fA7s;2r^jaN7*n<$?#wTPq62vu3E?LlhxM}pA#J$+_xVB zj>N%wY~h=}(#sQ#o;hIHbNj!Bo!ty>Itr0vQb|Z@gCg7i$#D$_EdIM~pMw{bb zp&xnG{zf=ww$HG{Foh4pK*dTXDWi~|%k*dsYiaCk z#PRI5m^N5U5yA7VRF!AbRCvJ=U$=BfR3m7h%F&hiJyAx~*JhT)V#L;H(JF45oE#iR zINQR0JUWGtulx@Z`K84IT}mQo-oU$BRsf~526~FeZ@M>pRO1TZtqZ{p@fOXRQf(&G z7t)6-oW3RRK@aIQ;Q`vqu}Y9DtKqU56c<)_I`N;ZzpsE@gFfz%GrN6DMu{eso??eZ zfEk~Y7)49|CWJMG^i2^_B724?z06updE@?o#5~m_K7TZz-m3Rw$Q4r3yDq;2P!yG5 z@lq?vijrMXR+r^95|FVxT-V#{WRf_kn0mR(GMGoSZ5EwgYvClkV!@_2;=3ABjGp4o zlSJ?C4Kkx@O4s%Y>;xAH{j@RhevVO0J zXXfNQ5u!nlCh48S%RRHPyW{OAfQQe;+%nig&MEU0HITWjM&Vk&z7_W|B4{dDNj(st z(T?|n?D2vr9~P+M$zWWhO7F-~=Z8`C_M2a8s+;dOLq{BoHg{bj6fJe-C;-bL;EtT= zh&oiB5+Sbum(0t!5l-xh`TKcdTPU0ZybF$QJo2Tkj_(qDX6*#0_Q%NMsjzFRjlH0p zJ*Xr>OEmGJId#fXnF1fk`=+u3F6ANfM`=zud@?Jd8Jtq*;B?e*J`_NRaP6pX*kUjebbtswzabjg7x4KZ8c6 z6Y0nN&OnUtgOhugu_iY++rW7$Pv`5Wtv`8<>dm5Eglfq=>!XqEQWsL{-^nG!T$HUI_pL$zSIm`A81qvh%TT9})yO2xmhX zPlT=?#T3S;T7t8b@Vhe3E4C06iZAH+XhfL0F1C0@(!A-CYxgktch;TVD2xS+tUcDQ z#-V^IP^ciB0)f*T#23P~c-W0jp2+{V zTgHH^=mE$702wR+ZVR~gS1cGgQPAXUw8rI`S?-9t@b?CPm^kKj*#tQv8!?IfRq;4= z3l-1{;z+^M-?l?MfKmXSjlGK#9uO1c^CnAPG)%u+s4!G9*!0gDv)c#m>im9g3GaN!-IvL_nl|tjfuD>+XOIbHEsyk<}3LwJ?xtqpw_v!=<@$L+; zPjRU7a$-9E_O06GXzcM2;UsAMpg{Zq8r||2T52~S51EECTKzdfGh?M9>C-Lq5-@B9 zSy=rT?s90Ws_AV#q(j(7%K; z+y9e_mUp%37zsi92cIm*$n+JcCiMLkp4lAFfEZ%6x6-`^2=o2u#I=uLtmJPm%}M`u zQ08*h2T}-E7gnDc`S_T*0!W+bSn3s@dlc)C? zCENv}N>RHdDNN;WJvPVt?~#VR*aDi8d$@4i<0AZLJuhb*YJ^Z3F3~Tvo$}ua^J95u zk6;^i@NT*P&AXNF-k^Y)wNT_>dEOUSi@|W3Rh%L1YPv0m@Frk97;k1w(pjan8iKi}`JvmindWnj8PD_X`IIys8dLxx zduA}=?5*ZlvCc>8gBBpe^c%YLTLLXl2pwiai8b3S)@)+Z$)8u2=pI-u;dz#EGE2pH zTddQu8zmCv^9B=9a=L=qH~#OTq({+$ej~e>9bvVbkTjF)#hU7_#EKQWZZZqV4RkX`3AjUm%ByYmc^XgL>02o<`&jA*cW(w zKbwc=Kfgfj1+Yy|!LzqnK+_yo%@lS>^C(DVa6}Acc>^uD5y}>6U*3J&>b<_zeNw64 zvEY}P?$h1xF)eSeZC_yJh&7-*j5K1Y3C+ zI%gh)(R`d0K^@W%J>R%}flFg(a)bsGpbaqkz+h^FuJ@@AdU{} zk|+;7)6_VJ#mh2Y@zB(-l{MPxRvuhtDv<%%hX2mfoTzdEMwSRbK+KB^dvBG6f-R3T z_CFs(08wq;NL}3Zmr3t2;Mu;NMh%w@y5?c!Ay11Rj2;xJoCM`1qYK+v6j%~@ug zf}Lb_VV9?P_jZd_CQ;`y(n3?Yg;AIKRVusya!o?t_Cr!1y7}@|%tU)Lk;E2gZ{r(VaT zo%*#Aa!$H{snTQ*g%!pr`HS#Rmx}yF&_xn%h)7qY)X6W;+3yD+>uKE%Ci?xkw5eR< z7k@7=pi#SfVa@h~j^A4Gz_bvj`=lv8P@MNC2^by}q=3zLNM(jEzCCy&TJS!I!zq6Ml{jU;dH{PcGn2&#V2960ngS`TK;YYh=}G3}}6g69VQH_xTB<+M-yFr2r0(|rewoPagr zGx_YwVs(MP1G*B!H{9h?AA>PkiQzu%{OVvP92pKS6X|j&2ScIh*pXii2#fRQ?BzE} z;R@!g-d)Tc8~$-OHVA41d)kQi%pOa7F&#ObV?$Q8?5e}qrzAIp{58b9@6p`htd=t4 zDkHhR_10urA(-&BIy=UI0WvTQOnQp0-z>4~^#K{yU8V~=H8Z$fhsv5KA0l9RswGt_M(5!;zc70a%Uuo%oW(5*#DpAQ_YbsZ`tzI0@AaB7?_%_zW z5e!p+m`u6cLe=i-rPKlc*!Ckcp46;$zJMQ2S#RGu2H3_6yv}Np-e2kJBT-nV>|rbn zIsV^dfNOgOK=A171C)Op)RH$@O}m;&$_r$WW6Tfc?O*iK@4AF_K57VUPge;z%v4vw zYMRRwn0WeGR34@Yb~j9?%(>6>y8`2Pbn&R39-m#DqS1`xo=70=R`K+IV=p0HZSJ6c zo&rFo0Z*SGEjB;AI){DAPaI6b{m-@RpL*d0CTr6k2~V|)^8y%OI``hl%eG;56^ue` zycoNFLQKY&(%V;m5mkcKQP+0Alfr1ldCR{8uHT+3JaRHT}MaRC|HpGMGIs9*Aq7X?`}Y1-gkM8;0km#eu~lu{F?`ks-lKM JiJVEm{{Zb|GRpt} literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/sv39-va-pa.png b/guide/source/chapter4/sv39-va-pa.png new file mode 100644 index 0000000000000000000000000000000000000000..daf34be5435ee5a65f4ba3cd911c3a3881974498 GIT binary patch literal 16067 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 literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/trie-1.png b/guide/source/chapter4/trie-1.png new file mode 100644 index 0000000000000000000000000000000000000000..29df0c12011646651ffd5da0258c4472deaf7462 GIT binary patch literal 23035 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 GGywq7olWTg literal 0 HcmV?d00001 diff --git a/guide/source/chapter4/trie.png b/guide/source/chapter4/trie.png new file mode 100644 index 0000000000000000000000000000000000000000..0a6e3cf9be4031917cf918cde1ebb48954d29734 GIT binary patch literal 40076 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 + +可以通过输入ch5b开头的应用来测试ch5实现的fork等功能: + +.. code-block:: + + >> ch5b_forktest_simple + + sys_wait without child process test passed! + parent start, pid = 2! + ready waiting on parent process! + hello child process! + child process pid = 3, exit code = 100 + Shell: Process 2 exited with code 0 + +本章代码树 +-------------------------------------- + +.. code-block:: + :linenos: + + ├── os +    ├── build.rs(修改：基于应用名的应用构建器) +    ├── ... +    └── src +    ├── ... +    ├── loader.rs(修改：基于应用名的应用加载器) +    ├── main.rs(修改) +    ├── mm(修改：为了支持本章的系统调用对此模块做若干增强) +    │   ├── address.rs +    │   ├── frame_allocator.rs +    │   ├── heap_allocator.rs +    │   ├── memory_set.rs +    │   ├── mod.rs +    │   └── page_table.rs +    ├── syscall +    │   ├── fs.rs(修改：新增 sys_read) +    │   ├── mod.rs(修改：新的系统调用的分发处理) +    │   └── process.rs（修改：新增 sys_getpid/fork/exec/waitpid） +    ├── task +    │   ├── context.rs +    │   ├── manager.rs(新增：任务管理器，为上一章任务管理器功能的一部分) +    │   ├── mod.rs(修改：调整原来的接口实现以支持进程) +    │   ├── pid.rs(新增：进程标识符和内核栈的 Rust 抽象) +    │   ├── processor.rs(新增：处理器管理结构 ``Processor`` ，为上一章任务管理器功能的一部分) +    │   ├── switch.rs +    │   ├── switch.S +    │   └── task.rs(修改：支持进程机制的任务控制块) +    └── trap +    ├── context.rs +    ├── mod.rs(修改：对于系统调用的实现进行修改以支持进程系统调用) +    └── trap.S + + cloc os + ------------------------------------------------------------------------------- + Language files blank comment code + ------------------------------------------------------------------------------- + Rust 29 180 138 2049 + Assembly 4 20 26 229 + make 1 11 4 36 + TOML 1 2 1 13 + ------------------------------------------------------------------------------- + SUM: 35 213 169 2327 + ------------------------------------------------------------------------------- + + +.. 本章代码导读 +.. ----------------------------------------------------- + +.. 本章的第一小节 :doc:`/chapter5/1process` 介绍了操作系统中经典的进程概念，并描述我们将要实现的参考自 Unix 系内核并经过简化的精简版进程模型。在该模型下，若想对进程进行管理，实现创建、退出等操作，核心就在于 ``fork/exec/waitpid`` 三个系统调用。 + +.. 首先我们修改运行在应用态的应用软件，它们均放置在 ``user`` 目录下。在新增系统调用的时候，需要在 ``user/src/lib.rs`` 中新增一个 ``sys_*`` 的函数，它的作用是将对应的系统调用按照与内核约定的 ABI 在 ``syscall`` 中转化为一条用于触发系统调用的 ``ecall`` 的指令；还需要在用户库 ``user_lib`` 将 ``sys_*`` 进一步封装成一个应用可以直接调用的与系统调用同名的函数。通过这种方式我们新增三个进程模型中核心的系统调用 ``fork/exec/waitpid`` ，一个查看进程 PID 的系统调用 ``getpid`` ，还有一个允许应用程序获取用户键盘输入的 ``read`` 系统调用。 + +.. 基于进程模型，我们在 ``user/src/bin`` 目录下重新实现了一组应用程序。其中有两个特殊的应用程序：用户初始程序 ``initproc.rs`` 和 shell 程序 ``user_shell.rs`` ，可以认为它们位于内核和其他应用程序之间的中间层提供一些基础功能，但是它们仍处于应用层。前者会被内核唯一自动加载、也是最早加载并执行，后者则负责从键盘接收用户输入的应用名并执行对应的应用。剩下的应用从不同层面测试了我们内核实现的正确性，读者可以自行参考。值得一提的是， ``usertests`` 可以按照顺序执行绝大部分应用，会在测试的时候为我们提供很多方便。 + +.. 接下来就需要在内核中实现简化版的进程机制并支持新增的系统调用。在本章第二小节 :doc:`/chapter5/2core-data-structures` 中我们对一些进程机制相关的数据结构进行了重构或者修改： + +.. - 为了支持基于应用名而不是应用 ID 来查找应用 ELF 可执行文件，从而实现灵活的应用加载，在 ``os/build.rs`` 以及 ``os/src/loader.rs`` 中更新了 ``link_app.S`` 的格式使得它包含每个应用的名字，另外提供 ``get_app_data_by_name`` 接口获取应用的 ELF 数据。 +.. - 在本章之前，任务管理器 ``TaskManager`` 不仅负责管理所有的任务状态，还维护着我们的 CPU 当前正在执行哪个任务。这种设计耦合度较高，我们将后一个功能分离到 ``os/src/task/processor.rs`` 中的处理器管理结构 ``Processor`` 中，它负责管理 CPU 上执行的任务和一些其他信息；而 ``os/src/task/manager.rs`` 中的任务管理器 ``TaskManager`` 仅负责管理所有任务。 +.. - 针对新的进程模型，我们复用前面章节的任务控制块 ``TaskControlBlock`` 作为进程控制块来保存进程的一些信息，相比前面章节还要新增 PID、内核栈、应用数据大小、父子进程、退出码等信息。它声明在 ``os/src/task/task.rs`` 中。 +.. - 从本章开始，内核栈在内核地址空间中的位置由所在进程的 PID 决定，我们需要在二者之间建立联系并提供一些相应的资源自动回收机制。可以参考 ``os/src/task/pid.rs`` 。 + +.. 有了这些数据结构的支撑，我们在本章第三小节 :doc:`/chapter5/3implement-process-mechanism` 实现进程机制。它可以分成如下几个方面： + +.. - 初始进程的自动创建。在内核初始化的时候需要调用 ``os/src/task/mod.rs`` 中的 ``add_initproc`` 函数，它会调用 ``TaskControlBlock::new`` 读取并解析初始应用 ``initproc`` 的 ELF 文件数据并创建初始进程 ``INITPROC`` ，随后会将它加入到全局任务管理器 ``TASK_MANAGER`` 中参与调度。 +.. - 进程切换机制。当一个进程退出或者是主动/被动交出 CPU 使用权之后需要由内核将 CPU 使用权交给其他进程。在本章中我们沿用 ``os/src/task/mod.rs`` 中的 ``suspend_current_and_run_next`` 和 ``exit_current_and_run_next`` 两个接口来实现进程切换功能，但是需要适当调整它们的实现。我们需要调用 ``os/src/task/task.rs`` 中的 ``schedule`` 函数进行进程切换，它会首先切换到处理器的 idle 控制流（即 ``os/src/task/processor`` 的 ``Processor::run`` 方法），然后在里面选取要切换到的进程并切换过去。 +.. - 进程调度机制。在进程切换的时候我们需要选取一个进程切换过去。选取进程逻辑可以参考 ``os/src/task/manager.rs`` 中的 ``TaskManager::fetch_task`` 方法。 +.. - 进程生成机制。这主要是指 ``fork/exec`` 两个系统调用。它们的实现分别可以在 ``os/src/syscall/process.rs`` 中找到，分别基于 ``os/src/process/task.rs`` 中的 ``TaskControlBlock::fork/exec`` 。 +.. - 进程资源回收机制。当一个进程主动退出或出错退出的时候，在 ``exit_current_and_run_next`` 中会立即回收一部分资源并在进程控制块中保存退出码；而需要等到它的父进程通过 ``waitpid`` 系统调用（与 ``fork/exec`` 两个系统调用放在相同位置）捕获到它的退出码之后，它的进程控制块才会被回收，从而所有资源都被回收。 +.. - 为了支持用户终端 ``user_shell`` 读取用户键盘输入的功能，还需要实现 ``read`` 系统调用，它可以在 ``os/src/syscall/fs.rs`` 中找到。 \ No newline at end of file diff --git a/guide/source/chapter5/1process.rst b/guide/source/chapter5/1process.rst new file mode 100644 index 0000000..2024aa3 --- /dev/null +++ b/guide/source/chapter5/1process.rst @@ -0,0 +1,230 @@ +与进程有关的重要系统调用 +================================================ + +重要系统调用 +------------------------------------------------------------ + +fork 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rust + + /// 功能：由当前进程 fork 出一个子进程。 + /// 返回值：对于子进程返回 0，对于当前进程则返回子进程的 PID 。 + /// syscall ID：220 + pub fn sys_fork() -> isize; + +exec 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rust + + /// 功能：将当前进程的地址空间清空并加载一个特定的可执行文件，返回用户态后开始它的执行。 + /// 参数：字符串 path 给出了要加载的可执行文件的名字； + /// 返回值：如果出错的话（如找不到名字相符的可执行文件）则返回 -1，否则不应该返回。 + /// 注意：path 必须以 "\0" 结尾，否则内核将无法确定其长度 + /// syscall ID：221 + pub fn sys_exec(path: &str) -> isize; + +利用 ``fork`` 和 ``exec`` 的组合，我们能让创建一个子进程，并令其执行特定的可执行文件。 + +waitpid 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rust + + /// 功能：当前进程等待一个子进程变为僵尸进程，回收其全部资源并收集其返回值。 + /// 参数：pid 表示要等待的子进程的进程 ID，如果为 -1 的话表示等待任意一个子进程； + /// exit_code 表示保存子进程返回值的地址，如果这个地址为 0 的话表示不必保存。 + /// 返回值：如果要等待的子进程不存在则返回 -1；否则如果要等待的子进程均未结束则返回 -2； + /// 否则返回结束的子进程的进程 ID。 + /// syscall ID：260 + pub fn sys_waitpid(pid: isize, exit_code: *mut i32) -> isize; + + +``sys_waitpid`` 在用户库中被封装成两个不同的 API， ``wait(exit_code: &mut i32)`` 和 ``waitpid(pid: usize, exit_code: &mut i32)``， +前者用于等待任意一个子进程，后者用于等待特定子进程。它们实现的策略是如果子进程还未结束，就以 yield 让出时间片： + +.. code-block:: rust + :linenos: + + // user/src/lib.rs + + pub fn wait(exit_code: &mut i32) -> isize { + loop { + match sys_waitpid(-1, exit_code as *mut _) { + -2 => { sys_yield(); } + n => { return n; } + } + } + } + + +应用程序示例 +----------------------------------------------- + +借助这三个重要系统调用，我们可以开发功能更强大的应用。下面是两个案例： **用户初始程序-init** 和 **shell程序-user_shell** 。 + +用户初始程序-initproc +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在内核初始化完毕后创建的第一个进程，是 **用户初始进程** (Initial Process) ，它将通过 +``fork+exec`` 创建 ``user_shell`` 子进程，并将被用于回收僵尸进程。 + +.. code-block:: rust + :linenos: + + // user/src/bin/ch5b_initproc.rs + + #![no_std] + #![no_main] + + #[macro_use] + extern crate user_lib; + + use user_lib::{ + fork, + wait, + exec, + yield_, + }; + + #[no_mangle] + fn main() -> i32 { + if fork() == 0 { + exec("ch5b_user_shell\0"); + } else { + loop { + let mut exit_code: i32 = 0; + let pid = wait(&mut exit_code); + if pid == -1 { + yield_(); + continue; + } + println!( + "[initproc] Released a zombie process, pid={}, exit_code={}", + pid, + exit_code, + ); + } + } + 0 + } + +- 第 19 行为 ``fork`` 出的子进程分支，通过 ``exec`` 启动shell程序 ``user_shell`` ， + 注意我们需要在字符串末尾手动加入 ``\0`` 。 +- 第 21 行开始则为父进程分支，表示用户初始程序-initproc自身。它不断循环调用 ``wait`` 来等待并回收系统中的僵尸进程占据的资源。 + 如果回收成功的话则会打印一条报告信息给出被回收子进程的 PID 和返回值；否则就 ``yield_`` 交出 CPU 资源并在下次轮到它执行的时候再回收看看。 + + +shell程序-user_shell +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +user_shell 需要捕获用户输入并进行解析处理，为此添加一个能获取用户输入的系统调用： + +.. code-block:: rust + + /// 功能：从文件中读取一段内容到缓冲区。 + /// 参数：fd 是待读取文件的文件描述符，切片 buffer 则给出缓冲区。 + /// 返回值：如果出现了错误则返回 -1，否则返回实际读到的字节数。 + /// syscall ID：63 + pub fn sys_read(fd: usize, buffer: &mut [u8]) -> isize; + +实际调用时，我们必须要同时向内核提供缓冲区的起始地址及长度： + +.. code-block:: rust + + // user/src/syscall.rs + + pub fn sys_read(fd: usize, buffer: &mut [u8]) -> isize { + syscall(SYSCALL_READ, [fd, buffer.as_mut_ptr() as usize, buffer.len()]) + } + +我们在用户库中将其进一步封装成每次能够从 **标准输入** 中获取一个字符的 ``getchar`` 函数。 + +shell程序 ``user_shell`` 实现如下： + +.. code-block:: rust + :linenos: + :emphasize-lines: 28,53,61 + + // user/src/bin/ch5b_user_shell.rs + + #![no_std] + #![no_main] + + extern crate alloc; + + #[macro_use] + extern crate user_lib; + + const LF: u8 = 0x0au8; + const CR: u8 = 0x0du8; + const DL: u8 = 0x7fu8; + const BS: u8 = 0x08u8; + + use alloc::string::String; + use user_lib::{fork, exec, waitpid, yield_}; + use user_lib::console::getchar; + + #[no_mangle] + pub fn main() -> i32 { + println!("Rust user shell"); + let mut line: String = String::new(); + print!(">> "); + loop { + let c = getchar(); + match c { + LF | CR => { + println!(""); + if !line.is_empty() { + line.push('\0'); + let pid = fork(); + if pid == 0 { + // child process + if exec(line.as_str()) == -1 { + println!("Error when executing!"); + return -4; + } + unreachable!(); + } else { + let mut exit_code: i32 = 0; + let exit_pid = waitpid(pid as usize, &mut exit_code); + assert_eq!(pid, exit_pid); + println!( + "Shell: Process {} exited with code {}", + pid, exit_code + ); + } + line.clear(); + } + print!(">> "); + } + BS | DL => { + if !line.is_empty() { + print!("{}", BS as char); + print!(" "); + print!("{}", BS as char); + line.pop(); + } + } + _ => { + print!("{}", c as char); + line.push(c as char); + } + } + } + } + +可以看到，在以第 25 行开头的主循环中，每次都是调用 ``getchar`` 获取一个用户输入的字符， +并根据它相应进行一些动作。第 23 行声明的字符串 ``line`` 则维护着用户当前输入的命令内容，它也在不断发生变化。 + +- 如果用户输入回车键（第 28 行），那么user_shell 会 fork 出一个子进程（第 34 行开始）并试图通过 + ``exec`` 系统调用执行一个应用，应用的名字在字符串 ``line`` 中给出。如果 exec 的返回值为 -1 ， + 说明在应用管理器中找不到对应名字的应用，此时子进程就直接打印错误信息并退出；否则子进程将开始执行目标应用。 + + fork 之后的 user_shell 进程自己的逻辑可以在第 41 行找到。它在等待 fork 出来的子进程结束并回收掉它的资源，还会顺带收集子进程的退出状态并打印出来。 +- 如果用户输入退格键（第 53 行），首先我们需要将屏幕上当前行的最后一个字符用空格替换掉， + 这可以通过输入一个特殊的退格字节 ``BS`` 来实现。其次，user_shell 进程内维护的 ``line`` 也需要弹出最后一个字符。 +- 如果用户输入了一个其他字符（第 61 行），就接将它打印在屏幕上，并加入到 ``line`` 中。 +- 按键 ``Ctrl+A`` 再输入 ``X`` 来退出qemu模拟器。 \ No newline at end of file diff --git a/guide/source/chapter5/2core-data-structures.rst b/guide/source/chapter5/2core-data-structures.rst new file mode 100644 index 0000000..b43388a --- /dev/null +++ b/guide/source/chapter5/2core-data-structures.rst @@ -0,0 +1,540 @@ +进程管理的核心数据结构 +=================================== + +本节导读 +----------------------------------- + +为了更好实现进程管理，我们需要设计和调整内核中的一些数据结构，包括： + +- 基于应用名的应用链接/加载器 +- 进程标识符 ``PidHandle`` 以及内核栈 ``KernelStack`` +- 任务控制块 ``TaskControlBlock`` +- 任务管理器 ``TaskManager`` +- 处理器管理结构 ``Processor`` + +基于应用名的应用链接/加载器 +------------------------------------------------------------------------ + +在实现 ``exec`` 系统调用的时候，我们需要根据应用的名字而不仅仅是一个编号来获取应用的 ELF 格式数据。 +因此，在链接器 ``os/build.rs`` 中，我们按顺序保存链接进来的每个应用的名字： + +.. code-block:: + :linenos: + :emphasize-lines: 8-13 + + // os/build.rs + + for i in 0..apps.len() { + writeln!(f, r#" .quad app_{}_start"#, i)?; + } + writeln!(f, r#" .quad app_{}_end"#, apps.len() - 1)?; + + writeln!(f, r#" + .global _app_names + _app_names:"#)?; + for app in apps.iter() { + writeln!(f, r#" .string "{}""#, app)?; + } + + for (idx, app) in apps.iter().enumerate() { + ... + } + +第 8~13 行，各个应用的名字通过 ``.string`` 伪指令放到数据段中，注意链接器会自动在每个字符串的结尾加入分隔符 +``\0`` ，它们的位置由全局符号 ``_app_names`` 指出。 + +而在加载器 ``loader.rs`` 中，我们用一个全局可见的 *只读* 向量 ``APP_NAMES`` 来按照顺序将所有应用的名字保存在内存中： + +.. code-block:: Rust + + // os/src/loader.rs + + lazy_static! { + static ref APP_NAMES: Vec<&'static str> = { + let num_app = get_num_app(); + extern "C" { fn _app_names(); } + let mut start = _app_names as usize as *const u8; + let mut v = Vec::new(); + unsafe { + for _ in 0..num_app { + let mut end = start; + while end.read_volatile() != '\0' as u8 { + end = end.add(1); + } + let slice = core::slice::from_raw_parts(start, end as usize - start as usize); + let str = core::str::from_utf8(slice).unwrap(); + v.push(str); + start = end.add(1); + } + } + v + }; + } + +使用 ``get_app_data_by_name`` 可以按照应用的名字来查找获得应用的 ELF 数据，而 ``list_apps`` +在内核初始化时被调用，它可以打印出所有可用应用的名字。 + +.. code-block:: rust + + // os/src/loader.rs + + pub fn get_app_data_by_name(name: &str) -> Option<&'static [u8]> { + let num_app = get_num_app(); + (0..num_app) + .find(|&i| APP_NAMES[i] == name) + .map(|i| get_app_data(i)) + } + + pub fn list_apps() { + println!("/**** APPS ****"); + for app in APP_NAMES.iter() { + println!("{}", app); + } + println!("**************/") + } + + +进程标识符和内核栈 +------------------------------------------------------------------------ + +进程标识符 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +同一时间存在的所有进程都有一个自己的进程标识符，它们是互不相同的整数。这里将其抽象为一个 ``PidHandle`` +类型，当它的生命周期结束后，对应的整数会被编译器自动回收： + +.. code-block:: rust + + // os/src/task/pid.rs + + pub struct PidHandle(pub usize); + +类似之前的物理页帧分配器 ``FrameAllocator`` ，我们实现一个同样使用简单栈式分配策略的进程标识符分配器 +``PidAllocator`` ，并将其全局实例化为 ``PID_ALLOCATOR`` ： + +.. code-block:: rust + + // os/src/task/pid.rs + + struct PidAllocator { + current: usize, + recycled: Vec, + } + + impl PidAllocator { + pub fn new() -> Self { + PidAllocator { + current: 0, + recycled: Vec::new(), + } + } + pub fn alloc(&mut self) -> PidHandle { + if let Some(pid) = self.recycled.pop() { + PidHandle(pid) + } else { + self.current += 1; + PidHandle(self.current - 1) + } + } + pub fn dealloc(&mut self, pid: usize) { + assert!(pid < self.current); + assert!( + self.recycled.iter().find(|ppid| **ppid == pid).is_none(), + "pid {} has been deallocated!", pid + ); + self.recycled.push(pid); + } + } + + lazy_static! { + static ref PID_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(PidAllocator::new()) }; + } + +``PidAllocator::alloc`` 将会分配出去一个将 ``usize`` 包装之后的 ``PidHandle`` 。 +我们将其包装为一个全局分配进程标识符的接口 ``pid_alloc``： + +.. code-block:: rust + + // os/src/task/pid.rs + + pub fn pid_alloc() -> PidHandle { + PID_ALLOCATOR.exclusive_access().alloc() + } + +同时我们也需要为 ``PidHandle`` 实现 ``Drop`` Trait 来允许编译器进行自动的资源回收： + +.. code-block:: rust + + // os/src/task/pid.rs + + impl Drop for PidHandle { + fn drop(&mut self) { + //println!("drop pid {}", self.0); + PID_ALLOCATOR.exclusive_access().dealloc(self.0); + } + } + +内核栈 +~~~~~~~~~~~~~~~~~~~~~~ + +从本章开始，我们将应用编号替换为进程标识符来决定每个进程内核栈在地址空间中的位置。 + +在内核栈 ``KernelStack`` 中保存着它所属进程的 PID ： + +.. code-block:: rust + + // os/src/task/pid.rs + + pub struct KernelStack { + pid: usize, + } + +它提供以下方法： + +.. code-block:: rust + :linenos: + + // os/src/task/pid.rs + + /// Return (bottom, top) of a kernel stack in kernel space. + pub fn kernel_stack_position(app_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) + } + + impl KernelStack { + pub fn new(pid_handle: &PidHandle) -> Self { + let pid = pid_handle.0; + let (kernel_stack_bottom, kernel_stack_top) = kernel_stack_position(pid); + KERNEL_SPACE.exclusive_access().insert_framed_area( + kernel_stack_bottom.into(), + kernel_stack_top.into(), + MapPermission::R | MapPermission::W, + ); + KernelStack { + pid: pid_handle.0, + } + } + pub fn push_on_top(&self, value: T) -> *mut T where + T: Sized, { + let kernel_stack_top = self.get_top(); + let ptr_mut = (kernel_stack_top - core::mem::size_of::()) as *mut T; + unsafe { *ptr_mut = value; } + ptr_mut + } + pub fn get_top(&self) -> usize { + let (_, kernel_stack_top) = kernel_stack_position(self.pid); + kernel_stack_top + } + } + +- 第 11 行， ``new`` 方法可以从一个 ``PidHandle`` ，也就是一个已分配的进程标识符中对应生成一个内核栈 ``KernelStack`` 。 + 它调用了第 4 行声明的 ``kernel_stack_position`` 函数来根据进程标识符计算内核栈在内核地址空间中的位置， + 随即在第 14 行将一个逻辑段插入内核地址空间 ``KERNEL_SPACE`` 中。 +- 第 25 行的 ``push_on_top`` 方法可以将一个类型为 ``T`` 的变量压入内核栈顶并返回其裸指针， + 这也是一个泛型函数。它在实现的时候用到了第 32 行的 ``get_top`` 方法来获取当前内核栈顶在内核地址空间中的地址。 + +内核栈 ``KernelStack`` 用到了 RAII 的思想，具体来说，实际保存它的物理页帧的生命周期被绑定到它下面，当 +``KernelStack`` 生命周期结束后，这些物理页帧也将会被编译器自动回收： + +.. code-block:: rust + + // os/src/task/pid.rs + + impl Drop for KernelStack { + fn drop(&mut self) { + let (kernel_stack_bottom, _) = kernel_stack_position(self.pid); + let kernel_stack_bottom_va: VirtAddr = kernel_stack_bottom.into(); + KERNEL_SPACE + .exclusive_access() + .remove_area_with_start_vpn(kernel_stack_bottom_va.into()); + } + } + + +为 ``KernelStack`` 实现 ``Drop`` Trait，一旦它的生命周期结束，就将内核地址空间中对应的逻辑段删除，为此在 ``MemorySet`` +中新增了一个名为 ``remove_area_with_start_vpn`` 的方法，感兴趣的读者可以查阅。 + +进程控制块 +------------------------------------------------------------------------ + +在内核中，每个进程的执行状态、资源控制等元数据均保存在一个被称为 **进程控制块** (PCB, Process Control Block) +的结构中，它是内核对进程进行管理的单位。在内核看来，它就等价于一个进程。 + +承接前面的章节，我们仅需对任务控制块 ``TaskControlBlock`` 进行若干改动，让它直接承担进程控制块的功能： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + pub struct TaskControlBlock { + // immutable + pub pid: PidHandle, + pub kernel_stack: KernelStack, + // mutable + inner: UPSafeCell, + } + + pub struct TaskControlBlockInner { + pub trap_cx_ppn: PhysPageNum, + pub base_size: usize, + pub task_cx: TaskContext, + pub task_status: TaskStatus, + pub memory_set: MemorySet, + pub parent: Option>, + pub children: Vec>, + pub exit_code: i32, + } + + +任务控制块中包含两部分： + +- 在初始化之后就不再变化的作为一个字段直接放在任务控制块中。这里将进程标识符 ``PidHandle`` 和内核栈 ``KernelStack`` 放在其中； +- 在运行过程中可能发生变化的则放在 ``TaskControlBlockInner`` 中，将它再包裹上一层 ``UPSafeCell`` 放在任务控制块中。 + 在此使用 ``UPSafeCell`` 可以提供互斥从而避免数据竞争。 + +``TaskControlBlockInner`` 中包含下面这些内容： + +- ``trap_cx_ppn`` 指出了应用地址空间中的 Trap 上下文被放在的物理页帧的物理页号。 +- ``base_size`` 的含义是：应用数据仅有可能出现在应用地址空间低于 ``base_size`` 字节的区域中。借助它我们可以清楚的知道应用有多少数据驻留在内存中。 +- ``task_cx`` 保存任务上下文，用于任务切换。 +- ``task_status`` 维护当前进程的执行状态。 +- ``memory_set`` 表示应用地址空间。 +- ``parent`` 指向当前进程的父进程（如果存在的话）。注意我们使用 ``Weak`` 而非 ``Arc`` + 来包裹另一个任务控制块，因此这个智能指针将不会影响父进程的引用计数。 +- ``children`` 则将当前进程的所有子进程的任务控制块以 ``Arc`` 智能指针的形式保存在一个向量中，这样才能够更方便的找到它们。 +- 当进程调用 exit 系统调用主动退出或者执行出错由内核终止的时候，它的退出码 ``exit_code`` + 会被内核保存在它的任务控制块中，并等待它的父进程通过 waitpid 回收它的资源的同时也收集它的 PID 以及退出码。 + +注意我们在维护父子进程关系的时候大量用到了智能指针 ``Arc/Weak`` ，当且仅当它的引用计数变为 0 的时候，进程控制块以及被绑定到它上面的各类资源才会被回收。 + +``TaskControlBlockInner`` 提供的方法主要是对于它内部字段的快捷访问： + +.. code-block:: rust + + // os/src/task/task.rs + + impl TaskControlBlockInner { + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + pub fn get_user_token(&self) -> usize { + self.memory_set.token() + } + fn get_status(&self) -> TaskStatus { + self.task_status + } + pub fn is_zombie(&self) -> bool { + self.get_status() == TaskStatus::Zombie + } + } + +而任务控制块 ``TaskControlBlock`` 目前提供以下方法： + +.. code-block:: rust + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn inner_exclusive_access(&self) -> RefMut<'_, TaskControlBlockInner> { + self.inner.exclusive_access() + } + pub fn getpid(&self) -> usize { + self.pid.0 + } + pub fn new(elf_data: &[u8]) -> Self {...} + pub fn exec(&self, elf_data: &[u8]) {...} + pub fn fork(self: &Arc) -> Arc {...} + } + +- ``inner_exclusive_access`` 尝试获取互斥锁来得到 ``TaskControlBlockInner`` 的可变引用。 +- ``getpid`` 以 ``usize`` 的形式返回当前进程的进程标识符。 +- ``new`` 用来创建一个新的进程，目前仅用于内核中手动创建唯一一个初始进程 ``initproc`` 。 +- ``exec`` 用来实现 ``exec`` 系统调用，即当前进程加载并执行另一个 ELF 格式可执行文件。 +- ``fork`` 用来实现 ``fork`` 系统调用，即当前进程 fork 出来一个与之几乎相同的子进程。 + +``new/exec/fork`` 的实现我们将在下一小节再介绍。 + +任务管理器 +------------------------------------------------------------------------ + +在前面的章节中，任务管理器 ``TaskManager`` 不仅负责管理所有的任务，还维护着 CPU 当前在执行哪个任务。 +由于这种设计不够灵活，我们需要将任务管理器对于 CPU 的监控职能拆分到处理器管理结构 ``Processor`` 中去， +任务管理器自身仅负责管理所有任务。在这里，任务指的就是进程。 + +.. code-block:: rust + :linenos: + + // os/src/task/manager.rs + + pub struct TaskManager { + ready_queue: VecDeque>, + } + + /// A simple FIFO scheduler. + impl TaskManager { + pub fn new() -> Self { + Self { + ready_queue: VecDeque::new(), + } + } + pub fn add(&mut self, task: Arc) { + self.ready_queue.push_back(task); + } + pub fn fetch(&mut self) -> Option> { + self.ready_queue.pop_front() + } + } + + lazy_static! { + pub static ref TASK_MANAGER: UPSafeCell = + unsafe { UPSafeCell::new(TaskManager::new()) }; + } + + pub fn add_task(task: Arc) { + TASK_MANAGER.exclusive_access().add(task); + } + + pub fn fetch_task() -> Option> { + TASK_MANAGER.exclusive_access().fetch() + } + +``TaskManager`` 将所有的任务控制块用引用计数 ``Arc`` 智能指针包裹后放在一个双端队列 ``VecDeque`` 中。 +使用智能指针的原因在于，任务控制块经常需要被放入/取出，如果直接移动任务控制块自身将会带来大量的数据拷贝开销， +而对于智能指针进行移动则没有多少开销。其次，允许任务控制块的共享引用在某些情况下能够让我们的实现更加方便。 + +``TaskManager`` 提供 ``add/fetch`` 两个操作，前者表示将一个任务加入队尾，后者则表示从队头中取出一个任务来执行。 +从调度算法来看，这里用到的就是最简单的 RR 算法。全局实例 ``TASK_MANAGER`` 则提供给内核的其他子模块 ``add_task/fetch_task`` 两个函数。 + +处理器管理结构 +------------------------------------------------------------------------ + +处理器管理结构 ``Processor`` 负责维护从任务管理器 ``TaskManager`` 分离出去的那部分 CPU 状态： + +.. code-block:: rust + + // os/src/task/processor.rs + + pub struct Processor { + current: Option>, + idle_task_cx: TaskContext, + } + +包括： + +- ``current`` 表示在当前处理器上正在执行的任务； +- ``idle_task_cx_ptr`` 表示当前处理器上的 idle 控制流的任务上下文的地址。 + +在单核环境下，我们仅创建单个 ``Processor`` 的全局实例 ``PROCESSOR`` ： + +.. code-block:: rust + + // os/src/task/processor.rs + + lazy_static! { + pub static ref PROCESSOR: UPSafeCell = unsafe { UPSafeCell::new(Processor::new()) }; + } + +正在执行的任务 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rust + :linenos: + + // os/src/task/processor.rs + + impl Processor { + pub fn take_current(&mut self) -> Option> { + self.current.take() + } + pub fn current(&self) -> Option> { + self.current.as_ref().map(|task| Arc::clone(task)) + } + } + + pub fn take_current_task() -> Option> { + PROCESSOR.take_current() + } + + pub fn current_task() -> Option> { + PROCESSOR.current() + } + + pub fn current_user_token() -> usize { + let task = current_task().unwrap(); + let token = task.inner_exclusive_access().get_user_token(); + token + } + + pub fn current_trap_cx() -> &'static mut TrapContext { + current_task() + .unwrap() + .inner_exclusive_access() + .get_trap_cx() + } + + +- 第 4 行的 ``Processor::take_current`` 可以取出当前正在执行的任务。 ``Option::take`` 意味着 ``current`` 字段也变为 ``None`` 。 +- 第 7 行的 ``Processor::current`` 返回当前执行的任务的一份拷贝。。 +- ``current_user_token`` 和 ``current_trap_cx`` 基于 ``current_task`` 实现，提供当前正在执行的任务的更多信息。 + + +任务调度的 idle 控制流 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +每个 ``Processor`` 都有一个 idle 控制流，它们运行在每个核各自的启动栈上，功能是尝试从任务管理器中选出一个任务来在当前核上执行。 +在内核初始化完毕之后，核通过调用 ``run_tasks`` 函数来进入 idle 控制流： + +.. code-block:: rust + :linenos: + + // os/src/task/processor.rs + + impl Processor { + fn get_idle_task_cx_ptr(&mut self) -> *mut TaskContext { + &mut self.idle_task_cx as *mut _ + } + } + + pub fn run_tasks() { + loop { + let mut processor = PROCESSOR.exclusive_access(); + if let Some(task) = fetch_task() { + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + // access coming task TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let next_task_cx_ptr = &task_inner.task_cx as *const TaskContext; + task_inner.task_status = TaskStatus::Running; + drop(task_inner); + // release coming task TCB manually + processor.current = Some(task); + // release processor manually + drop(processor); + unsafe { + __switch(idle_task_cx_ptr, next_task_cx_ptr); + } + } + } + } + +调度功能的主体在 ``run_tasks`` 中实现。它循环调用 ``fetch_task`` 直到顺利从任务管理器中取出一个任务，然后获得 +``__switch`` 两个参数进行任务切换。注意在整个过程中要严格控制临界区。 + +当一个应用交出 CPU 使用权时，进入内核后它会调用 ``schedule`` 函数来切换到 idle 控制流并开启新一轮的任务调度。 + +.. code-block:: rust + + // os/src/task/processor.rs + + pub fn schedule(switched_task_cx_ptr: *mut TaskContext) { + let mut processor = PROCESSOR.exclusive_access(); + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + drop(processor); + unsafe { + __switch(switched_task_cx_ptr, idle_task_cx_ptr); + } + } + +切换回去之后，我们将跳转到 ``Processor::run`` 中 ``__switch`` 返回之后的位置，也即开启了下一轮循环。 diff --git a/guide/source/chapter5/3implement-process-mechanism.rst b/guide/source/chapter5/3implement-process-mechanism.rst new file mode 100644 index 0000000..1de6985 --- /dev/null +++ b/guide/source/chapter5/3implement-process-mechanism.rst @@ -0,0 +1,665 @@ +进程管理机制的设计实现 +============================================ + +本节导读 +-------------------------------------------- + +本节将介绍如何基于上一节设计的内核数据结构来实现进程管理： + +- 初始进程 ``initproc`` 的创建； +- 进程调度机制：当进程主动调用 ``sys_yield`` 交出 CPU 使用权，或者内核本轮分配的时间片用尽之后如何切换到下一个进程； +- 进程生成机制：介绍进程相关的两个重要系统调用 ``sys_fork/sys_exec`` 的实现； +- 字符输入机制：介绍 ``sys_read`` 系统调用的实现； +- 进程资源回收机制：当进程调用 ``sys_exit`` 正常退出或者出错被内核终止后，如何保存其退出码，其父进程又是如何通过 + ``sys_waitpid`` 收集该进程的信息并回收其资源。 + +初始进程的创建 +-------------------------------------------- + +内核初始化完毕之后，即会调用 ``task`` 子模块提供的 ``add_initproc`` 函数来将初始进程 ``initproc`` +加入任务管理器，但在这之前，我们需要初始进程的进程控制块 ``INITPROC`` ，这基于 ``lazy_static`` 在运行时完成。 + +.. code-block:: rust + + // os/src/task/mod.rs + + lazy_static! { + pub static ref INITPROC: Arc = Arc::new(TaskControlBlock::new( + get_app_data_by_name("initproc").unwrap() + )); + } + + pub fn add_initproc() { + add_task(INITPROC.clone()); + } + +我们调用 ``TaskControlBlock::new`` 来创建一个进程控制块，它需要传入 ELF 可执行文件的数据切片作为参数， +这可以通过加载器 ``loader`` 子模块提供的 ``get_app_data_by_name`` 接口查找 ``initproc`` 的 ELF 数据来获得。在初始化 +``INITPROC`` 之后，则在 ``add_initproc`` 中可以调用 ``task`` 的任务管理器 ``manager`` 子模块提供的 ``add_task`` 接口将其加入到任务管理器。 + +接下来介绍 ``TaskControlBlock::new`` 是如何实现的： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + use super::{PidHandle, pid_alloc, KernelStack}; + use super::TaskContext; + use crate::config::TRAP_CONTEXT; + use crate::trap::TrapContext; + + // impl TaskControlBlock + pub fn new(elf_data: &[u8]) -> Self { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + // push a task context which goes to trap_return to the top of kernel stack + let task_cx_ptr = kernel_stack.push_on_top(TaskContext::goto_trap_return()); + let task_control_block = Self { + pid: pid_handle, + kernel_stack, + inner: unsafe { UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: user_sp, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + }) + }, + }; + // prepare TrapContext in user space + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + kernel_stack_top, + trap_handler as usize, + ); + task_control_block + } + +- 第 10 行，解析 ELF 得到应用地址空间 ``memory_set`` ，用户栈在应用地址空间中的位置 ``user_sp`` 以及应用的入口点 ``entry_point`` 。 +- 第 11 行，手动查页表找到应用地址空间中的 Trap 上下文实际所在的物理页帧。 +- 第 16~18 行，为新进程分配 PID 以及内核栈，并记录下内核栈在内核地址空间的位置 ``kernel_stack_top`` 。 +- 第 20 行，在该进程的内核栈上压入初始化的任务上下文，使得第一次任务切换到它的时候可以跳转到 ``trap_return`` 并进入用户态开始执行。 +- 第 21 行，整合之前的部分信息创建进程控制块 ``task_control_block`` 。 +- 第 39 行，初始化位于该进程应用地址空间中的 Trap 上下文，使得第一次进入用户态时，能正确跳转到应用入口点并设置好用户栈， + 同时也保证在 Trap 的时候用户态能正确进入内核态。 + +进程调度机制 +-------------------------------------------- + +调用 ``task`` 子模块提供的 ``suspend_current_and_run_next`` 函数可以暂停当前任务，并切换到下一个任务，下面给出了两种典型的使用场景： + +.. code-block:: rust + :emphasize-lines: 4,18 + + // os/src/syscall/process.rs + + pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 + } + + // os/src/trap/mod.rs + + #[no_mangle] + pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + ... + } + trap_return(); + } + +随着进程概念的引入， ``suspend_current_and_run_next`` 的实现也需要发生变化： + +.. code-block:: rust + :linenos: + + // os/src/task/mod.rs + + use processor::{task_current_task, schedule}; + use manager::add_task; + + pub fn suspend_current_and_run_next() { + // There must be an application running. + let task = take_current_task().unwrap(); + + // ---- access current TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let task_cx_ptr = &mut task_inner.task_cx as *mut TaskContext; + // Change status to Ready + task_inner.task_status = TaskStatus::Ready; + drop(task_inner); + // ---- release current PCB + + // push back to ready queue. + add_task(task); + // jump to scheduling cycle + schedule(task_cx_ptr); + } + +首先通过 ``take_current_task`` 来取出当前正在执行的任务，修改其进程控制块内的状态，随后将这个任务放入任务管理器的队尾。接着调用 +``schedule`` 函数来触发调度并切换任务。当仅有一个任务的时候， ``suspend_current_and_run_next`` 的效果是会继续执行这个任务。 + +进程的生成机制 +-------------------------------------------- + +fork 系统调用的实现 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +实现 fork 时，最为关键且困难一点的是为子进程创建一个和父进程几乎完全相同的地址空间。我们的实现如下： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + impl MapArea { + pub fn from_another(another: &MapArea) -> Self { + Self { + vpn_range: VPNRange::new( + another.vpn_range.get_start(), + another.vpn_range.get_end() + ), + data_frames: BTreeMap::new(), + map_type: another.map_type, + map_perm: another.map_perm, + } + } + } + + impl MemorySet { + pub fn from_existed_user(user_space: &MemorySet) -> MemorySet { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // copy data sections/trap_context/user_stack + for area in user_space.areas.iter() { + let new_area = MapArea::from_another(area); + memory_set.push(new_area, None); + // copy data from another space + for vpn in area.vpn_range { + let src_ppn = user_space.translate(vpn).unwrap().ppn(); + let dst_ppn = memory_set.translate(vpn).unwrap().ppn(); + dst_ppn.get_bytes_array().copy_from_slice(src_ppn.get_bytes_array()); + } + } + memory_set + } + } + +这需要对内存管理子模块 ``mm`` 做一些拓展： + +- 第 4 行的 ``MapArea::from_another`` 可以从一个逻辑段复制得到一个虚拟地址区间、映射方式和权限控制均相同的逻辑段， + 不同的是由于它还没有真正被映射到物理页帧上，所以 ``data_frames`` 字段为空。 +- 第 18 行的 ``MemorySet::from_existed_user`` 可以复制一个完全相同的地址空间。首先在第 19 行，我们通过 ``new_bare`` + 新创建一个空的地址空间，并在第 21 行通过 ``map_trampoline`` 为这个地址空间映射上跳板页面，这是因为我们解析 ELF + 创建地址空间的时候，并没有将跳板页作为一个单独的逻辑段插入到地址空间的逻辑段向量 ``areas`` 中，所以这里需要单独映射上。 + + 剩下的逻辑段都包含在 ``areas`` 中。我们遍历原地址空间中的所有逻辑段，将复制之后的逻辑段插入新的地址空间， + 在插入的时候就已经实际分配了物理页帧了。接着我们遍历逻辑段中的每个虚拟页面，对应完成数据复制， + 这只需要找出两个地址空间中的虚拟页面各被映射到哪个物理页帧，就可转化为将数据从物理内存中的一个位置复制到另一个位置，使用 + ``copy_from_slice`` 即可轻松实现。 + +接着，我们实现 ``TaskControlBlock::fork`` 来从父进程的进程控制块创建一份子进程的控制块： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn fork(self: &Arc) -> Arc { + // ---- access parent PCB exclusively + let mut parent_inner = self.inner_exclusive_access(); + // copy user space(include trap context) + let memory_set = MemorySet::from_existed_user(&parent_inner.memory_set); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + let task_control_block = Arc::new(TaskControlBlock { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: parent_inner.base_size, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: Some(Arc::downgrade(self)), + children: Vec::new(), + exit_code: 0, + }) + }, + }); + // add child + parent_inner.children.push(task_control_block.clone()); + // modify kernel_sp in trap_cx + // **** access children PCB exclusively + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + trap_cx.kernel_sp = kernel_stack_top; + // return + task_control_block + // ---- release parent PCB automatically + // **** release children PCB automatically + } + } + +它基本上和新建进程控制块的 ``TaskControlBlock::new`` 是相同的，但要注意以下几点： + +- 子进程的地址空间不是通过解析 ELF，而是通过在第 8 行调用 ``MemorySet::from_existed_user`` 复制父进程地址空间得到的； +- 在 fork 的时候需要注意父子进程关系的维护。既要将父进程的弱引用计数放到子进程的进程控制块中，又要将子进程插入到父进程的孩子向量 ``children`` 中。 + +实现 ``sys_fork`` 时，我们需要特别注意如何体现父子进程的差异： + +.. code-block:: rust + :linenos: + + // os/src/syscall/process.rs + + pub fn sys_fork() -> isize { + let current_task = current_task().unwrap(); + let new_task = current_task.fork(); + let new_pid = new_task.pid.0; + // modify trap context of new_task, because it returns immediately after switching + let trap_cx = new_task.inner_exclusive_access().get_trap_cx(); + // we do not have to move to next instruction since we have done it before + // for child process, fork returns 0 + trap_cx.x[10] = 0; + // add new task to scheduler + add_task(new_task); + new_pid as isize + } + +在调用 ``sys_fork`` 之前，我们已经将当前进程 Trap 上下文中的 sepc 向后移动了 4 字节，使得它回到用户态之后会从 ecall +的下一条指令开始执行。之后，当我们复制地址空间时，子进程地址空间 Trap 上下文的 sepc 也是移动之后的值，我们无需再进行修改。 + +父子进程回到用户态的瞬间都处于刚刚从一次系统调用返回的状态，但二者返回值不同。第 8~11 行我们将子进程的 Trap +上下文中用来存放系统调用返回值的 a0 寄存器修改为 0 ，而父进程系统调用的返回值会在 ``syscall`` 返回之后再设置为 ``sys_fork`` +的返回值。这就做到了父进程 ``fork`` 的返回值为子进程的 PID ，而子进程的返回值为 0。 + +exec 系统调用的实现 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``exec`` 系统调用使得一个进程能够加载一个新的 ELF 可执行文件替换原有的应用地址空间并开始执行。我们先从进程控制块的层面进行修改： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn exec(&self, elf_data: &[u8]) { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + + // **** access inner exclusively + let mut inner = self.inner_exclusive_access(); + // substitute memory_set + inner.memory_set = memory_set; + // update trap_cx ppn + inner.trap_cx_ppn = trap_cx_ppn; + // initialize trap_cx + let trap_cx = inner.get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + self.kernel_stack.get_top(), + trap_handler as usize, + ); + // **** release inner automatically + } + } + +它在解析传入的 ELF 格式数据之后只做了两件事情： + +- 首先从 ELF 生成一个全新的地址空间并直接替换进来（第 15 行），这将导致原有地址空间生命周期结束，里面包含的全部物理页帧都会被回收； +- 然后修改新的地址空间中的 Trap 上下文，将解析得到的应用入口点、用户栈位置以及一些内核的信息进行初始化，这样才能正常实现 Trap 机制。 + +``sys_exec`` 的实现如下，它调用 ``translated_str`` 找到要执行的应用名，并试图从应用加载器提供的 ``get_app_data_by_name`` +接口中获取对应的 ELF 数据，如果找到的话就调用 ``TaskControlBlock::exec`` 替换地址空间。 + + + +.. code-block:: rust + + // os/src/syscall/process.rs + + pub fn sys_exec(path: *const u8) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + if let Some(data) = get_app_data_by_name(path.as_str()) { + let task = current_task().unwrap(); + task.exec(data); + 0 + } else { + -1 + } + } + +应用在 ``sys_exec`` 系统调用中传递给内核的只有一个应用名字符串在用户地址空间中的首地址，内核必限手动查页表来获得字符串的值。 + +``translated_str`` 用来从用户地址空间中查找字符串，其原理就是逐字节查页表直到发现一个 ``\0`` 为止。为什么要逐字节查页表？ +因为内核不知道字符串的长度，且字符串可能是跨物理页的。 + +.. code-block:: rust + + // os/src/mm/page_table.rs + + pub fn translated_str(token: usize, ptr: *const u8) -> String { + let page_table = PageTable::from_token(token); + let mut string = String::new(); + let mut va = ptr as usize; + loop { + let ch: u8 = *(page_table.translate_va(VirtAddr::from(va)).unwrap().get_mut()); + if ch == 0 { + break; + } else { + string.push(ch as char); + va += 1; + } + } + string + } + +系统调用后重新获取 Trap 上下文 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +原来在 ``trap_handler`` 中我们是这样处理系统调用的： + +.. code-block:: rust + + // os/src/trap/mod.rs + + #[no_mangle] + pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let cx = current_trap_cx(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + cx.sepc += 4; + cx.x[10] = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]) as usize; + } + ... + } + trap_return(); + } + +这里的 ``cx`` 是当前应用的 Trap 上下文的可变引用，我们需要通过查页表找到它具体被放在哪个物理页帧上， +并构造相同的虚拟地址来在内核中访问它。对于系统调用 ``sys_exec`` 来说，调用它之后， ``trap_handler`` +原来上下文中的 ``cx`` 失效了，因为它是就原来的地址空间而言的。为了能够处理类似的这种情况，我们在 ``syscall`` +返回之后需要重新获取 ``cx`` ，目前的实现如下： + +.. code-block:: rust + + // os/src/trap/mod.rs + + #[no_mangle] + pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + // jump to next instruction anyway + let mut cx = current_trap_cx(); + cx.sepc += 4; + // get system call return value + let result = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]); + // cx is changed during sys_exec, so we have to call it again + cx = current_trap_cx(); + cx.x[10] = result as usize; + } + ... + } + trap_return(); + } + + +sys_read 获取输入 +-------------------------------------------- + +我们需要实现 ``sys_read`` 系统调用，使应用能够取得用户的键盘输入。 + +.. code-block:: rust + + // os/src/syscall/fs.rs + + use crate::sbi::console_getchar; + + const FD_STDIN: usize = 0; + + pub fn sys_read(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDIN => { + assert_eq!(len, 1, "Only support len = 1 in sys_read!"); + let mut c: usize; + loop { + c = console_getchar(); + if c == 0 { + suspend_current_and_run_next(); + continue; + } else { + break; + } + } + let ch = c as u8; + let mut buffers = translated_byte_buffer(current_user_token(), buf, len); + unsafe { buffers[0].as_mut_ptr().write_volatile(ch); } + 1 + } + _ => { + panic!("Unsupported fd in sys_read!"); + } + } + } + +目前我们仅支持从标准输入 ``FD_STDIN`` 即文件描述符 0 读入，且每次只能读入一个字符，这是利用 ``sbi`` +提供的接口 ``console_getchar`` 实现的。如果还没有输入，我们就切换到其他进程，等下次切换回来时再看看是否有输入了。 +获取到输入后就退出循环，并手动查页表将输入字符正确写入到应用地址空间。 + +进程资源回收机制 +-------------------------------------------- + +进程的退出 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +当应用调用 ``sys_exit`` 系统调用主动退出，或者出错由内核终止之后，会在内核中调用 ``exit_current_and_run_next`` 函数： + +.. code-block:: rust + :linenos: + :emphasize-lines: 4,29,34 + + // os/src/syscall/process.rs + + pub fn sys_exit(exit_code: i32) -> ! { + exit_current_and_run_next(exit_code); + panic!("Unreachable in sys_exit!"); + } + + // os/src/trap/mod.rs + + #[no_mangle] + pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::StoreFault) | + Trap::Exception(Exception::StorePageFault) | + Trap::Exception(Exception::InstructionFault) | + Trap::Exception(Exception::InstructionPageFault) | + Trap::Exception(Exception::LoadFault) | + Trap::Exception(Exception::LoadPageFault) => { + println!( + "[kernel] {:?} in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", + scause.cause(), + stval, + current_trap_cx().sepc, + ); + // page fault exit code + exit_current_and_run_next(-2); + } + Trap::Exception(Exception::IllegalInstruction) => { + println!("[kernel] IllegalInstruction in application, core dumped."); + // illegal instruction exit code + exit_current_and_run_next(-3); + } + ... + } + trap_return(); + } + +相比前面的章节， ``exit_current_and_run_next`` 带有一个退出码作为参数，这个退出码会在 +``exit_current_and_run_next`` 写入当前进程的进程控制块： + +.. code-block:: rust + :linenos: + + // os/src/mm/memory_set.rs + + impl MemorySet { + pub fn recycle_data_pages(&mut self) { + self.areas.clear(); + } + } + + // os/src/task/mod.rs + + pub fn exit_current_and_run_next(exit_code: i32) { + // take from Processor + let task = take_current_task().unwrap(); + // **** access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + // Change status to Zombie + inner.task_status = TaskStatus::Zombie; + // Record exit code + inner.exit_code = exit_code; + // do not move to its parent but under initproc + + // ++++++ access initproc TCB exclusively + { + let mut initproc_inner = INITPROC.inner_exclusive_access(); + for child in inner.children.iter() { + child.inner_exclusive_access().parent = Some(Arc::downgrade(&INITPROC)); + initproc_inner.children.push(child.clone()); + } + } + // ++++++ release parent PCB + + inner.children.clear(); + // deallocate user space + inner.memory_set.recycle_data_pages(); + drop(inner); + // **** release current PCB + // drop task manually to maintain rc correctly + drop(task); + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); + } + + +- 第 13 行，调用 ``take_current_task`` 来将当前进程控制块从处理器监控 ``PROCESSOR`` + 中取出，而不只是得到一份拷贝，这是为了正确维护进程控制块的引用计数； +- 第 17 行将进程控制块中的状态修改为 ``TaskStatus::Zombie`` 即僵尸进程； +- 第 19 行将传入的退出码 ``exit_code`` 写入进程控制块中，后续父进程在 ``waitpid`` 的时候可以收集； +- 第 24~26 行所做的事情是，将当前进程的所有子进程挂在初始进程 ``initproc`` 下面。第 32 行将当前进程的孩子向量清空。 +- 第 34 行，对于当前进程占用的资源进行早期回收。 ``MemorySet::recycle_data_pages`` 只是将地址空间中的逻辑段列表 + ``areas`` 清空，这将导致应用地址空间的所有数据被存放在的物理页帧被回收，而用来存放页表的那些物理页帧此时则不会被回收。 +- 最后在第 41 行我们调用 ``schedule`` 触发调度及任务切换，我们再也不会回到该进程的执行过程，因此无需关心任务上下文的保存。 + +父进程回收子进程资源 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rust + :linenos: + + // os/src/syscall/process.rs + + /// If there is not a child process whose pid is same as given, return -1. + /// Else if there is a child process but it is still running, return -2. + pub fn sys_waitpid(pid: isize, exit_code_ptr: *mut i32) -> isize { + let task = current_task().unwrap(); + // find a child process + + // ---- access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + if !inner + .children + .iter() + .any(|p| pid == -1 || pid as usize == p.getpid()) + { + return -1; + // ---- release current PCB + } + let pair = inner.children.iter().enumerate().find(|(_, p)| { + // ++++ temporarily access child PCB lock exclusively + p.inner_exclusive_access().is_zombie() && (pid == -1 || pid as usize == p.getpid()) + // ++++ release child PCB + }); + if let Some((idx, _)) = pair { + let child = inner.children.remove(idx); + // confirm that child will be deallocated after removing from children list + assert_eq!(Arc::strong_count(&child), 1); + let found_pid = child.getpid(); + // ++++ temporarily access child TCB exclusively + let exit_code = child.inner_exclusive_access().exit_code; + // ++++ release child PCB + *translated_refmut(inner.memory_set.token(), exit_code_ptr) = exit_code; + found_pid as isize + } else { + -2 + } + // ---- release current PCB lock automatically + } + +``sys_waitpid`` 是一个立即返回的系统调用，它的返回值语义是：如果当前的进程不存在一个符合要求的子进程，则返回 +-1；如果至少存在一个，但是其中没有僵尸进程（也即仍未退出）则返回 -2；如果都不是的话则可以正常回收并返回回收子进程的 +pid 。但在编写应用的开发者看来， ``wait/waitpid`` 两个辅助函数都必定能够返回一个有意义的结果，要么是 -1，要么是一个正数 +PID ，是不存在 -2 这种通过等待即可消除的中间结果的。等待的过程由用户库 ``user_lib`` 完成。 + +首先判断 ``sys_waitpid`` 是否会返回 -1 ，这取决于当前进程是否有一个符合要求的子进程。当传入的 ``pid`` 为 -1 +的时候，任何一个子进程都算是符合要求；但 ``pid`` 不为 -1 的时候，则只有 PID 恰好与 ``pid`` +相同的子进程才算符合条件。我们简单通过迭代器即可完成判断。 + +再判断符合要求的子进程中是否有僵尸进程。如果找不到的话直接返回 ``-2`` ，否则进行下一步处理： + +我们将子进程从向量中移除并置于当前上下文中，当它所在的代码块结束，这次引用变量的生命周期结束，子进程进程控制块的引用计数将变为 +0 ，内核将彻底回收掉它占用的所有资源，包括内核栈、它的 PID 、存放页表的那些物理页帧等等。 + +获得子进程退出码后，考虑到应用传入的指针指向应用地址空间，我们还需要手动查页表找到对应物理内存中的位置。 +``translated_refmut`` 的实现可以在 ``os/src/mm/page_table.rs`` 中找到。 \ No newline at end of file diff --git a/guide/source/chapter5/4exercise.rst b/guide/source/chapter5/4exercise.rst new file mode 100644 index 0000000..0a4e915 --- /dev/null +++ b/guide/source/chapter5/4exercise.rst @@ -0,0 +1,137 @@ +chapter5练习 +============================================== + +编程作业 +--------------------------------------------- + +进程创建 ++++++++++++++++++++++++++++++++++++++++++++++ + +大家一定好奇过为啥进程创建要用 fork + exec 这么一个奇怪的系统调用，就不能直接搞一个新进程吗？ +思而不学则殆，我们就来试一试！这章的编程练习请大家实现一个完全 DIY 的系统调用 spawn，用以创建一个新进程。 + +spawn 系统调用定义( `标准spawn看这里 `_ )： + +.. code-block:: rust + + fn sys_spawn(path: *const u8) -> isize + +- syscall ID: 400 +- 功能：新建子进程，使其执行目标程序。 +- 说明：成功返回子进程id，否则返回 -1。 +- 可能的错误： + - 无效的文件名。 + - 进程池满/内存不足等资源错误。 + +TIPS：虽然测例很简单，但提醒读者 spawn **不必** 像 fork 一样复制父进程的地址空间。 + +stride 调度算法 ++++++++++++++++++++++++++++++++++++++++++ + +ch3 中我们实现的调度算法十分简单。现在我们要为我们的 os 实现一种带优先级的调度算法：stride 调度算法。 + +算法描述如下: + +(1) 为每个进程设置一个当前 stride，表示该进程当前已经运行的“长度”。另外设置其对应的 pass +值（只与进程的优先权有关系），表示对应进程在调度后，stride 需要进行的累加值。 + +(2) 每次需要调度时，从当前 runnable 态的进程中选择 stride 最小的进程调度。对于获得调度的进程 P，将对应的 stride 加上其对应的步长 pass。 + +(3) 一个时间片后，回到上一步骤，重新调度当前 stride 最小的进程。 + +可以证明，如果令 P.pass = BigStride / P.priority 其中 P.priority 表示进程的优先权（大于 1），而 +BigStride 表示一个预先定义的大常数，则该调度方案为每个进程分配的时间将与其优先级成正比。证明过程我们在这里略去，有兴趣的同学可以在网上查找相关资料。 + +其他实验细节： + +- stride 调度要求进程优先级 :math:`\geq 2`，所以设定进程优先级 :math:`\leq 1` 会导致错误。 +- 进程初始 stride 设置为 0 即可。 +- 进程初始优先级设置为 16。 + +为了实现该调度算法，内核还要增加 set_prio 系统调用 + +.. code-block:: rust + + // syscall ID：140 + // 设置当前进程优先级为 prio + // 参数：prio 进程优先级，要求 prio >= 2 + // 返回值：如果输入合法则返回 prio，否则返回 -1 + fn sys_set_priority(prio: isize) -> isize; + +实现 tips: + +- 你可以在TCB加入新的字段来支持优先级等。 +- 为了减少整数除的误差，BIG_STRIDE 一般需要很大，但为了不至于发生反转现象（详见问答作业），或许选择一个适中的数即可，当然能进行溢出处理就更好了。 +- stride 算法要找到 stride 最小的进程，使用优先级队列是效率不错的办法，但是我们的实验测例很简单，所以效率完全不是问题。事实上，很推荐使用暴力扫一遍的办法找最小值。 +- 注意设置进程的初始优先级。 + +.. attention:: + + 为了让大家能在本编程作业中使用 ``Vec`` 等数据结构，我们利用第三方库 ``buddy_system_allocator`` + 为大家实现了堆内存分配器，相关代码位于 ``mm/heap_allocator`` 模块。 + + 背景知识： `Rust 中的动态内存分配 `_ + +实验要求 ++++++++++++++++++++++++++++++++++++++++++++++ +- 实现分支：ch5。 +- 实验目录请参考 ch3。注意在reports中放入lab1-3的所有报告。 +- 通过所有测例。 + + 在 os 目录下 ``make run BASE=2`` 加载所有测例， ``ch5_usertest`` 打包了所有你需要通过的测例， + 你也可以通过修改这个文件调整本地测试的内容, 或者单独运行某测例来纠正特定的错误。 ``ch5_stride`` + 检查 stride 调度算法是否满足公平性要求，六个子程序运行的次数应该大致与其优先级呈正比，测试通过标准是 + :math:`\max{\frac{runtimes}{prio}}/ \min{\frac{runtimes}{prio}} < 1.5`. + + CI 的原理是用 ``ch5_usertest`` 替代 ``ch5b_initproc`` ，使内核在所有测例执行完后直接退出。 + + 从本章开始，你的内核必须前向兼容，能通过前一章的所有测例。 + +.. note:: + + 利用 ``git cherry-pick`` 系列指令，能方便地将前一章分支 commit 移植到本章分支。 + +问答作业 +-------------------------------------------- + +stride 算法深入 + + stride 算法原理非常简单，但是有一个比较大的问题。例如两个 pass = 10 的进程，使用 8bit 无符号整形储存 + stride， p1.stride = 255, p2.stride = 250，在 p2 执行一个时间片后，理论上下一次应该 p1 执行。 + + - 实际情况是轮到 p1 执行吗？为什么？ + + 我们之前要求进程优先级 >= 2 其实就是为了解决这个问题。可以证明， **在不考虑溢出的情况下** , 在进程优先级全部 >= 2 + 的情况下，如果严格按照算法执行，那么 STRIDE_MAX – STRIDE_MIN <= BigStride / 2。 + + - 为什么？尝试简单说明（不要求严格证明）。 + + - 已知以上结论，**考虑溢出的情况下**，可以为 Stride 设计特别的比较器，让 BinaryHeap 的 pop + 方法能返回真正最小的 Stride。补全下列代码中的 ``partial_cmp`` 函数，假设两个 Stride 永远不会相等。 + + .. code-block:: rust + + use core::cmp::Ordering; + + struct Stride(u64); + + impl PartialOrd for Stride { + fn partial_cmp(&self, other: &Self) -> Option { + // ... + } + } + + impl PartialEq for Stride { + fn eq(&self, other: &Self) -> bool { + false + } + } + + TIPS: 使用 8 bits 存储 stride, BigStride = 255, 则: ``(125 < 255) == false``, ``(129 < 255) == true``. + +报告要求 +------------------------------------------------------------ + +- 简单总结你实现的功能（200字以内，不要贴代码）。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter5/index.rst b/guide/source/chapter5/index.rst new file mode 100644 index 0000000..7aaf8e1 --- /dev/null +++ b/guide/source/chapter5/index.rst @@ -0,0 +1,12 @@ +第五章：进程及进程管理 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 1process + 2core-data-structures + 3implement-process-mechanism + 4exercise + \ No newline at end of file diff --git a/guide/source/chapter6/0intro.rst b/guide/source/chapter6/0intro.rst new file mode 100644 index 0000000..4e7dd2a --- /dev/null +++ b/guide/source/chapter6/0intro.rst @@ -0,0 +1,159 @@ +引言 +========================================= + +本章导读 +----------------------------------------- + +本章我们将实现一个简单的文件系统 -- easyfs，能够对 **持久存储设备** (Persistent Storage) I/O 资源进行管理；将设计两种文件：常规文件和目录文件，它们均以文件系统所维护的 **磁盘文件** 形式被组织并保存在持久存储设备上。 + +实践体验 +----------------------------------------- + +获取本章代码： + +.. code-block:: console + + $ git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S.git + $ cd rCore-Tutorial-Code-2022S + $ git checkout ch6 + +在 qemu 模拟器上运行本章代码： + +.. code-block:: console + + $ cd os + $ make run + +内核初始化完成之后就会进入shell程序，在这里我们运行一下本章的测例 ``ch6b_filetest_simple`` ： + +.. code-block:: + + >> ch6b_filetest_simple + file_test passed! + Shell: Process 2 exited with code 0 + >> + +它会将 ``Hello, world!`` 输出到另一个文件 ``filea`` ，并读取里面的内容确认输出正确。我们也可以通过命令行工具 ``ch6b_cat`` 来查看 ``filea`` 中的内容： + +.. code-block:: + + >> ch6b_cat + Hello, world! + Shell: Process 2 exited with code 0 + >> + +本章代码树 +----------------------------------------- + +.. code-block:: + :linenos: + + ├── easy-fs(新增：从内核中独立出来的一个简单的文件系统 EasyFileSystem 的实现) + │   ├── Cargo.toml + │   └── src + │   ├── bitmap.rs(位图抽象) + │   ├── block_cache.rs(块缓存层，将块设备中的部分块缓存在内存中) + │   ├── block_dev.rs(声明块设备抽象接口 BlockDevice，需要库的使用者提供其实现) + │   ├── efs.rs(实现整个 EasyFileSystem 的磁盘布局) + │   ├── layout.rs(一些保存在磁盘上的数据结构的内存布局) + │   ├── lib.rs + │   └── vfs.rs(提供虚拟文件系统的核心抽象，即索引节点 Inode) + ├── easy-fs-fuse(新增：将当前 OS 上的应用可执行文件按照 easy-fs 的格式进行打包) + │   ├── Cargo.toml + │   └── src + │   └── main.rs + ├── os +    ├── build.rs(修改：不再需要将用户态程序链接到内核中） +    ├── Cargo.toml(修改：新增 Qemu 的块设备驱动依赖 crate) +    ├── Makefile(修改：新增文件系统的构建流程) +    └── src +    ├── config.rs(修改：新增访问块设备所需的一些 MMIO 配置) +    ├── ... +    ├── drivers(新增：Qemu 平台的块设备驱动) +    │   ├── block +    │   │   ├── mod.rs(将不同平台上的块设备全局实例化为 BLOCK_DEVICE 提供给其他模块使用) +    │   │   └── virtio_blk.rs(Qemu 平台的 virtio-blk 块设备) +    │   └── mod.rs +    ├── fs(新增：对文件系统及文件抽象) +    │   ├── inode.rs(新增：将 easy-fs 提供的 Inode 抽象封装为内核看到的 OSInode +    │   │ 并实现 fs 子模块的 File Trait) +    │   ├── mod.rs +    │   └── stdio.rs(新增：将标准输入输出也抽象为文件) +    ├── loader.rs(移除：应用加载器 loader 子模块，本章开始从文件系统中加载应用) +    ├── mm +    │   ├── address.rs +    │   ├── frame_allocator.rs +    │   ├── heap_allocator.rs +    │   ├── memory_set.rs(修改：在创建地址空间的时候插入 MMIO 虚拟页面) +    │   ├── mod.rs +    │   └── page_table.rs(新增：应用地址空间的缓冲区抽象 UserBuffer 及其迭代器实现) +    ├── syscall +    │   ├── fs.rs(修改：新增 sys_open，修改sys_read、sys_write) +    │   ├── mod.rs +    │   └── process.rs(修改：sys_exec 改为从文件系统中加载 ELF) +    ├── task +       ├── context.rs +       ├── manager.rs +       ├── mod.rs(修改：初始进程 INITPROC 的初始化) +       ├── pid.rs +       ├── processor.rs +       ├── switch.rs +       ├── switch.S +       └── task.rs(修改：在任务控制块中加入文件描述符表的相关机制) + + cloc easy-fs os + ------------------------------------------------------------------------------- + Language files blank comment code + ------------------------------------------------------------------------------- + Rust 41 306 418 3349 + Assembly 4 53 26 526 + make 1 13 4 48 + TOML 2 4 2 23 + ------------------------------------------------------------------------------- + SUM: 48 376 450 3946 + ------------------------------------------------------------------------------- + +.. 本章代码导读 +.. ----------------------------------------------------- + +.. 本章涉及的代码量相对较多，且与进程执行相关的管理还有直接的关系。其实我们是参考经典的UNIX基于索引的文件系统，设计了一个简化的有一级目录并支持创建/打开/读写/关闭文件一系列操作的文件系统。这里简要介绍一下在内核中添加文件系统的大致开发过程。 + +.. 第一步是能够写出与文件访问相关的应用。这里是参考了Linux的创建/打开/读写/关闭文件的系统调用接口，力图实现一个 :ref:`简化版的文件系统模型 ` 。在用户态我们只需要遵从相关系统调用的接口约定，在用户库里完成对应的封装即可。这一过程我们在前面的章节中已经重复过多次，读者应当对其比较熟悉。其中最为关键的是系统调用可以参考 :ref:`sys_open 语义介绍 ` ，此外我们还给出了 :ref:`测例代码解读 ` 。 + +.. 第二步就是要实现 easyfs 文件系统了。由于 Rust 语言的特点，我们可以在用户态实现 easyfs 文件系统，并在用户态完成文件系统功能的基本测试并基本验证其实现正确性之后，就可以放心的将该模块嵌入到操作系统内核中。当然，有了文件系统的具体实现，还需要对上一章的操作系统内核进行扩展，实现与 easyfs 文件系统对接的接口，这样才可以让操作系统拥有一个简单可用的文件系统。从而，内核可以支持允许文件读写功能的更复杂的应用，在命令行参数机制的加持下，可以进一步提升整个系统的灵活性，让应用的开发和调试变得更为轻松。 + +.. easyfs 文件系统的整体架构自下而上可分为五层。它的最底层就是对块设备的访问操作接口。在 ``easy-fs/src/block_dev.rs`` 中，可以看到 ``BlockDevice`` trait 代表了一个抽象块设备，该 trait 仅需求两个函数 ``read_block`` 和 ``write_block`` ，分别代表将数据从块设备读到内存中的缓冲区中，或者将数据从内存中的缓冲区写回到块设备中，数据需要以块为单位进行读写。easy-fs 库的使用者需要负责为它们看到的实际的块设备具体实现 ``BlockDevice`` trait 并提供给 easy-fs 库的上层，这样的话 easy-fs 库的最底层就与一个具体的执行环境对接起来了。至于为什么块设备层位于 easy-fs 的最底层，是因为文件系统仅仅是在块设备上存储的结构稍微复杂一点的数据，但无论它的操作变换如何复杂，从块设备的角度终究可以被分解成若干次块读写。 + +.. 尽管在最底层我们就已经有了块读写的能力，但从编程方便性和性能的角度，仅有块读写这么基础的底层接口是不足以实现如此复杂的文件系统的，虽然它已经被我们大幅简化过了。比如，将一个块的内容读到内存的缓冲区，对缓冲区进行修改，并尚未写回的时候，如果由于编程上的不小心再次将该块的内容读到另一个缓冲区，而不是使用已有的缓冲区，这将会造成不一致问题。此外还有可能增加很多不必要的块读写次数，大幅降低文件系统的性能。因此，通过程序自动而非程序员手动对块的缓冲区进行统一管理也就势在必行了，该机制被我们抽象为 easy-fs 自底向上的第二层，即块缓存层。在 ``easy-fs/src/block_cache.rs`` 中， ``BlockCache`` 代表一个被我们管理起来的块的缓冲区，它带有缓冲区本体以及块的编号等信息。当它被创建的时候，将触发一次 ``read_block`` 将数据从块设备读到它的缓冲区中。接下来只要它驻留在内存中，便可保证对于同一个块的所有操作都会直接在它的缓冲区中进行而无需额外的 ``read_block`` 。块缓存管理器 ``BlockManager`` 在内存中管理有限个 ``BlockCache`` 并实现了类似 FIFO 的缓存替换算法，当一个块缓存被换出的时候视情况可能调用 ``write_block`` 将缓冲区数据写回块设备。总之，块缓存层对上提供 ``get_block_cache`` 接口来屏蔽掉相关细节，从而可以透明的读写一个块。 + +.. 有了块缓存，我们就可以在内存中方便地处理easyfs文件系统在磁盘上的各种数据了，这就是第三层文件系统的磁盘数据结构。easyfs文件系统中的所有需要持久保存的数据都会放到磁盘上，这包括了管理这个文件系统的 **超级块 (Super Block)**，管理空闲磁盘块的 **索引节点位图区** 和 **数据块位图区** ，以及管理文件的 **索引节点区** 和 放置文件数据的 **数据块区** 组成。 + +.. easyfs文件系统中管理这些磁盘数据的控制逻辑主要集中在 **磁盘块管理器** 中，这是文件系统的第四层。对于文件系统管理而言，其核心是 ``EasyFileSystem`` 数据结构及其关键成员函数： + +.. - EasyFileSystem.create：创建文件系统 +.. - EasyFileSystem.open：打开文件系统 +.. - EasyFileSystem.alloc_inode：分配inode （dealloc_inode未实现，所以还不能删除文件） +.. - EasyFileSystem.alloc_data：分配数据块 +.. - EasyFileSystem.dealloc_data：回收数据块 + +.. 对于单个文件的管理和读写的控制逻辑主要是 **索引节点** 来完成，这是文件系统的第五层，其核心是 ``Inode`` 数据结构及其关键成员函数： + +.. - Inode.new：在磁盘上的文件系统中创建一个inode +.. - Inode.find：根据文件名查找对应的磁盘上的inode +.. - Inode.create：在根目录下创建一个文件 +.. - Inode.read_at：根据inode找到文件数据所在的磁盘数据块，并读到内存中 +.. - Inode.write_at：根据inode找到文件数据所在的磁盘数据块，把内存中数据写入到磁盘数据块中 + +.. 上述五层就构成了easyfs文件系统的整个内容。我们可以把easyfs文件系统看成是一个库，被应用程序调用。而 ``easy-fs-fuse`` 这个应用就通过调用easyfs文件系统库中各种函数，并用Linux上的文件模拟了一个块设备，就可以在这个模拟的块设备上创建了一个easyfs文件系统。 + +.. 第三步，我们需要把easyfs文件系统加入到我们的操作系统内核中。这还需要做两件事情，第一件是在Qemu模拟的 ``virtio`` 块设备上实现块设备驱动程序 ``os/src/drivers/block/virtio_blk.rs`` 。由于我们可以直接使用 ``virtio-drivers`` crate中的块设备驱动，所以只要提供这个块设备驱动所需要的内存申请与释放以及虚实地址转换的4个函数就可以了。而我们之前操作系统中的虚存管理实现中，以及有这些函数，导致块设备驱动程序很简单，具体实现细节都被 ``virtio-drivers`` crate封装好了。 + +.. 第二件事情是把文件访问相关的系统调用与easyfs文件系统连接起来。在easfs文件系统中是没有进程的概念的。而进程是程序运行过程中访问资源的管理实体，这就要对 ``easy-fs`` crate 提供的 ``Inode`` 结构进一步封装，形成 ``OSInode`` 结构，以表示进程中一个打开的常规文件。对于应用程序而言，它理解的磁盘数据是常规的文件和目录，不是 ``OSInode`` 这样相对复杂的结构。其实常规文件对应的 OSInode 是文件在操作系统内核中的内部表示，因此需要为它实现 File Trait 从而能够可以将它放入到进程文件描述符表中，并通过 sys_read/write 系统调用进行读写。这样就建立了文件与 ``OSInode`` 的对应关系，并通过上面描述的三个步骤完成了包含文件系统的操作系统内核，并能给应用提供基于文件的系统调用服务。 + +.. 完成包含文件系统的操作系统内核后，我们在shell程序和内核中支持命令行参数的解析和传递，这样可以让应用根据灵活地通过命令行参数来动态地表示要操作的文件。这需要扩展对应的系统调用 ``sys_exec`` ,主要的改动就是在创建新进程时，把命令行参数压入用户栈中，这样应用程序在执行时就可以从用户栈中获取到命令行的参数值了。 + +.. 在上一章，我们提到了把标准输出设备在文件描述符表中的文件描述符的值规定为 1 ，用 Stdin 表示；把标准输入设备在文件描述符表中的文件描述符的值规定为 0，用 stdout 表示 。另外，还有一条文件描述符相关的重要规则：即进程打开一个文件的时候，内核总是会将文件分配到该进程文件描述符表中编号 最小的 空闲位置。利用这些约定，只实现新的系统调用 ``sys_dup`` 完成对文件描述符的复制，就可以巧妙地实现标准 I/O 重定向功能了。 + +.. 具体思路是，在某应用进程执行之前，父进程（比如 user_shell进程）要对子应用进程的文件描述符表进行某种替换。以输出为例，父进程在创建子进程前，提前打开一个常规文件 A，然后 ``fork`` 子进程，在子进程的最初执行中，通过 ``sys_close`` 关闭 Stdout 文件描述符，用 ``sys_dup`` 复制常规文件 A 的文件描述符，这样 Stdout 文件描述符实际上指向的就是常规文件A了，这时再通过 ``sys_close`` 关闭常规文件 A 的文件描述符。至此，常规文件 A 替换掉了应用文件描述符表位置 1 处的标准输出文件，这就完成了所谓的 **重定向** ，即完成了执行新应用前的准备工作。 + +.. 接下来是子进程调用 ``sys_exec`` 系统调用，创建并开始执行新子应用进程。在重定向之后，新的子应用进程认为自己输出到 fd=1 的标准输出文件，但实际上是输出到父进程（比如 user_shell进程）指定的文件A中。文件这一抽象概念透明化了文件、I/O设备之间的差异，因为在进程看来无论是标准输出还是常规文件都是一种文件，可以通过同样的接口来读写。这就是文件的强大之处。 diff --git a/guide/source/chapter6/1file-descriptor.rst b/guide/source/chapter6/1file-descriptor.rst new file mode 100644 index 0000000..8fe5b58 --- /dev/null +++ b/guide/source/chapter6/1file-descriptor.rst @@ -0,0 +1,243 @@ +文件与文件描述符 +=========================================== + +文件简介 +------------------------------------------- + +文件可代表很多种不同类型的I/O 资源，但是在进程看来，所有文件的访问都可以通过一个简洁统一的抽象接口 ``File`` 进行： + +.. code-block:: rust + + // os/src/fs/mod.rs + + pub trait File : Send + Sync { + fn readable(&self) -> bool; + fn writable(&self) -> bool; + fn read(&self, buf: UserBuffer) -> usize; + fn write(&self, buf: UserBuffer) -> usize; + } + + +这个接口在内存和I/O资源之间建立了数据交换的通道。其中 ``UserBuffer`` 是我们在 ``mm`` 子模块中定义的应用地址空间中的一段缓冲区，我们可以将它看成一个 ``&[u8]`` 切片。 + +``read`` 指的是从文件（即I/O资源）中读取数据放到缓冲区中，最多将缓冲区填满（即读取缓冲区的长度那么多字节），并返回实际读取的字节数；而 ``write`` 指的是将缓冲区中的数据写入文件，最多将缓冲区中的数据全部写入，并返回直接写入的字节数。 + +回过头来再看一下用户缓冲区的抽象 ``UserBuffer`` ，它的声明如下： + +.. code-block:: rust + + // os/src/mm/page_table.rs + + pub fn translated_byte_buffer( + token: usize, + ptr: *const u8, + len: usize + ) -> Vec<&'static mut [u8]>; + + pub struct UserBuffer { + pub buffers: Vec<&'static mut [u8]>, + } + + impl UserBuffer { + pub fn new(buffers: Vec<&'static mut [u8]>) -> Self { + Self { buffers } + } + pub fn len(&self) -> usize { + let mut total: usize = 0; + for b in self.buffers.iter() { + total += b.len(); + } + total + } + } + +它只是将我们调用 ``translated_byte_buffer`` 获得的包含多个切片的 ``Vec`` 进一步包装起来，通过 ``len`` 方法可以得到缓冲区的长度。此外，我们还让它作为一个迭代器可以逐字节进行读写。有兴趣的读者可以参考类型 ``UserBufferIterator`` 还有 ``IntoIterator`` 和 ``Iterator`` 两个 Trait 的使用方法。 + +标准输入和标准输出 +-------------------------------------------- + +其实我们在第二章就对应用程序引入了基于 **文件** 的标准输出接口 ``sys_write`` ，在第五章引入标准输入接口 ``sys_read`` 。我们提前把标准输出设备在文件描述符表中的文件描述符的值规定为 ``1`` ，用 ``Stdout`` 表示；把标准输入设备文件描述符规定为 ``0``，用 ``Stdin`` 表示 。现在，我们重写这些系统调用，先为标准输入和标准输出实现 ``File`` Trait： + +.. code-block:: rust + :linenos: + + // os/src/fs/stdio.rs + + pub struct Stdin; + + pub struct Stdout; + + impl File for Stdin { + fn readable(&self) -> bool { true } + fn writable(&self) -> bool { false } + fn read(&self, mut user_buf: UserBuffer) -> usize { + assert_eq!(user_buf.len(), 1); + // busy loop + let mut c: usize; + loop { + c = console_getchar(); + if c == 0 { + suspend_current_and_run_next(); + continue; + } else { + break; + } + } + let ch = c as u8; + unsafe { user_buf.buffers[0].as_mut_ptr().write_volatile(ch); } + 1 + } + fn write(&self, _user_buf: UserBuffer) -> usize { + panic!("Cannot write to stdin!"); + } + } + + impl File for Stdout { + fn readable(&self) -> bool { false } + fn writable(&self) -> bool { true } + fn read(&self, _user_buf: UserBuffer) -> usize{ + panic!("Cannot read from stdout!"); + } + fn write(&self, user_buf: UserBuffer) -> usize { + for buffer in user_buf.buffers.iter() { + print!("{}", core::str::from_utf8(*buffer).unwrap()); + } + user_buf.len() + } + } + +可以看到，标准输入文件 ``Stdin`` 是只读文件，只允许进程通过 ``read`` 从里面读入，目前每次仅支持读入一个字符，其实现与之前的 ``sys_read`` 基本相同，只是需要通过 ``UserBuffer`` 来获取具体将字节写入的位置。相反，标准输出文件 ``Stdout`` 是只写文件，只允许进程通过 ``write`` 写入到里面，实现方法是遍历每个切片，将其转化为字符串通过 ``print!`` 宏来输出。 + +文件描述符与文件描述符表 +-------------------------------------------- + +为简化操作系统设计实现，可以让每个进程都带有一个线性的 **文件描述符表** ，记录所有它请求内核打开并可以读写的那些文件集合。而 **文件描述符** (File Descriptor) 则是一个非负整数，表示文件描述符表中一个打开的 **文件描述符** 所处的位置（可理解为数组下标）。进程通过文件描述符，可以在自身的文件描述符表中找到对应的文件记录信息，从而也就找到了对应的文件，并对文件进行读写。当打开（ ``open`` ）或创建（ ``create`` ） 一个文件的时候，如果顺利，内核会返回给应用刚刚打开或创建的文件对应的文件描述符；而当应用想关闭（ ``close`` ）一个文件的时候，也需要向内核提供对应的文件描述符。 + + +文件I/O操作 +------------------------------------------- + +在进程控制块中加入文件描述符表的相应字段： + +.. code-block:: rust + :linenos: + :emphasize-lines: 12 + + // os/src/task/task.rs + + pub struct TaskControlBlockInner { + pub trap_cx_ppn: PhysPageNum, + pub base_size: usize, + pub task_cx: TaskContext, + pub task_status: TaskStatus, + pub memory_set: MemorySet, + pub parent: Option>, + pub children: Vec>, + pub exit_code: i32, + pub fd_table: Vec>>, + } + +可以看到 ``fd_table`` 的类型包含多层嵌套，我们从外到里分别说明： + +- ``Vec`` 的动态长度特性使得我们无需设置一个固定的文件描述符数量上限； +- ``Option`` 使得我们可以区分一个文件描述符当前是否空闲，当它是 ``None`` 的时候是空闲的，而 ``Some`` 则代表它已被占用； +- ``Arc`` 首先提供了共享引用能力。后面我们会提到，可能会有多个进程共享同一个文件对它进行读写。此外被它包裹的内容会被放到内核堆而不是栈上，于是它便不需要在编译期有着确定的大小； +- ``dyn`` 关键字表明 ``Arc`` 里面的类型实现了 ``File/Send/Sync`` 三个 Trait ，但是编译期无法知道它具体是哪个类型（可能是任何实现了 ``File`` Trait 的类型如 ``Stdin/Stdout`` ，故而它所占的空间大小自然也无法确定），需要等到运行时才能知道它的具体类型。 + +.. note:: + + **Rust 语法卡片：Rust 中的多态** + + 在编程语言中， **多态** (Polymorphism) 指的是在同一段代码中可以隐含多种不同类型的特征。在 Rust 中主要通过泛型和 Trait 来实现多态。 + + 泛型是一种 **编译期多态** (Static Polymorphism)，在编译一个泛型函数的时候，编译器会对于所有可能用到的类型进行实例化并对应生成一个版本的汇编代码，在编译期就能知道选取哪个版本并确定函数地址，这可能会导致生成的二进制文件体积较大；而 Trait 对象（也即上面提到的 ``dyn`` 语法）是一种 **运行时多态** (Dynamic Polymorphism)，需要在运行时查一种类似于 C++ 中的 **虚表** (Virtual Table) 才能找到实际类型对于抽象接口实现的函数地址并进行调用，这样会带来一定的运行时开销，但是更为灵活。 + +当新建一个进程的时候，我们需要按照先前的说明为进程打开标准输入文件和标准输出文件： + +.. code-block:: rust + :linenos: + :emphasize-lines: 19-26 + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn new(elf_data: &[u8]) -> Self { + ... + let task_control_block = Self { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: user_sp, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + fd_table: vec![ + // 0 -> stdin + Some(Arc::new(Stdin)), + // 1 -> stdout + Some(Arc::new(Stdout)), + // 2 -> stderr + Some(Arc::new(Stdout)), + ], + }) + }, + }; + ... + } + } + +此外，在 fork 时，子进程需要完全继承父进程的文件描述符表来和父进程共享所有文件。这样，即使我们仅手动为初始进程 ``initproc`` 打开了标准输入输出，所有进程也都可以访问它们。 + +文件读写系统调用 +--------------------------------------------------- + +基于文件抽象接口和文件描述符表，我们终于可以让文件读写系统调用 ``sys_read/write`` 变得更加具有普适性，不仅仅局限于之前特定的标准输入输出： + +.. code-block:: rust + + // os/src/syscall/fs.rs + + pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let task = current_task().unwrap(); + let inner = task.acquire_inner_lock(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release Task lock manually to avoid deadlock + drop(inner); + file.write( + UserBuffer::new(translated_byte_buffer(token, buf, len)) + ) as isize + } else { + -1 + } + } + + pub fn sys_read(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let task = current_task().unwrap(); + let inner = task.acquire_inner_lock(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release Task lock manually to avoid deadlock + drop(inner); + file.read( + UserBuffer::new(translated_byte_buffer(token, buf, len)) + ) as isize + } else { + -1 + } + } + +我们都是在当前进程的文件描述符表中通过文件描述符找到某个文件，无需关心文件具体的类型，只要知道它一定实现了 ``File`` Trait 的 ``read/write`` 方法即可。Trait 对象提供的运行时多态能力会在运行的时候帮助我们定位到 ``read/write`` 的符合实际类型的实现。 diff --git a/guide/source/chapter6/1fs-interface.rst b/guide/source/chapter6/1fs-interface.rst new file mode 100644 index 0000000..9bc27d0 --- /dev/null +++ b/guide/source/chapter6/1fs-interface.rst @@ -0,0 +1,112 @@ +文件系统接口 +================================================= + +简易文件与目录抽象 +------------------------------------------------- + +与课堂所学相比，我们实现的文件系统进行了很大的简化： + +- 扁平化：仅存在根目录 ``/`` 一个目录，所有的文件都放在根目录内。直接以文件名索引文件。 +- 不设置用户和用户组概念，不记录文件访问/修改的任何时间戳，不支持软硬链接。 +- 只实现了最基本的文件系统相关系统调用。 + +打开与读写文件的系统调用 +-------------------------------------------------- + +打开文件 +++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. code-block:: rust + + /// 功能：打开一个常规文件，并返回可以访问它的文件描述符。 + /// 参数：path 描述要打开的文件的文件名（简单起见，文件系统不需要支持目录，所有的文件都放在根目录 / 下）， + /// flags 描述打开文件的标志，具体含义下面给出。 + /// dirfd 和 mode 仅用于保证兼容性，忽略 + /// 返回值：如果出现了错误则返回 -1，否则返回打开常规文件的文件描述符。可能的错误原因是：文件不存在。 + /// syscall ID：56 + fn sys_openat(dirfd: usize, path: &str, flags: u32, mode: u32) -> isize + +目前我们的内核支持以下几种标志（多种不同标志可能共存）： + +- 如果 ``flags`` 为 0，则表示以只读模式 *RDONLY* 打开； +- 如果 ``flags`` 第 0 位被设置（0x001），表示以只写模式 *WRONLY* 打开； +- 如果 ``flags`` 第 1 位被设置（0x002），表示既可读又可写 *RDWR* ； +- 如果 ``flags`` 第 9 位被设置（0x200），表示允许创建文件 *CREATE* ，在找不到该文件的时候应创建文件；如果该文件已经存在则应该将该文件的大小归零； +- 如果 ``flags`` 第 10 位被设置（0x400），则在打开文件的时候应该清空文件的内容并将该文件的大小归零，也即 *TRUNC* 。 + +在用户库 ``user_lib`` 中，我们将该系统调用封装为 ``open`` 接口： + +.. code-block:: rust + + // user/src/lib.rs + + bitflags! { + pub struct OpenFlags: u32 { + const RDONLY = 0; + const WRONLY = 1 << 0; + const RDWR = 1 << 1; + const CREATE = 1 << 9; + const TRUNC = 1 << 10; + } + } + + pub fn open(path: &str, flags: OpenFlags) -> isize { + sys_openat(AT_FDCWD as usize, path, flags.bits, OpenFlags::RDWR.bits) + } + +借助 ``bitflags!`` 宏我们将一个 ``u32`` 的 flags 包装为一个 ``OpenFlags`` 结构体，可以从它的 ``bits`` 字段获得 ``u32`` 表示。 + + +顺序读写文件 +++++++++++++++++++++++++++++++++++++++++++++++++++ + +在打开一个文件之后，我们就可以用之前的 ``sys_read/sys_write`` 两个系统调用来对它进行读写了。本教程只实现文件的顺序读写，而不考虑随机读写。 + +以本章的测试用例 ``ch6b_filetest_simple`` 来介绍文件系统接口的使用方法： + +.. code-block:: rust + :linenos: + + // user/src/bin/ch6b_filetest_simple.rs + + #![no_std] + #![no_main] + + #[macro_use] + extern crate user_lib; + + use user_lib::{ + open, + close, + read, + write, + OpenFlags, + }; + + #[no_mangle] + pub fn main() -> i32 { + let test_str = "Hello, world!"; + let filea = "filea\0"; + let fd = open(filea, OpenFlags::CREATE | OpenFlags::WRONLY); + assert!(fd > 0); + let fd = fd as usize; + write(fd, test_str.as_bytes()); + close(fd); + + let fd = open(filea, OpenFlags::RDONLY); + assert!(fd > 0); + let fd = fd as usize; + let mut buffer = [0u8; 100]; + let read_len = read(fd, &mut buffer) as usize; + close(fd); + + assert_eq!( + test_str, + core::str::from_utf8(&buffer[..read_len]).unwrap(), + ); + println!("file_test passed!"); + 0 + } + +- 第 20~25 行，我们以 *只写 + 创建* 的模式打开文件 ``filea`` ，向其中写入字符串 ``Hello, world!`` 而后关闭文件。 +- 第 27~32 行，我们以只读 的方式将文件 ``filea`` 的内容读取到缓冲区 ``buffer`` 中。 ``filea`` 的总大小不超过缓冲区的大小，因此通过单次 ``read`` 即可将内容全部读出来而更常见的情况是需要进行多次 ``read`` ，直到返回值为 0 才能确认文件已被读取完毕。 diff --git a/guide/source/chapter6/2fs-implementation-1.rst b/guide/source/chapter6/2fs-implementation-1.rst new file mode 100644 index 0000000..b79fa3d --- /dev/null +++ b/guide/source/chapter6/2fs-implementation-1.rst @@ -0,0 +1,674 @@ +简易文件系统 easy-fs (上) +======================================= + +松耦合模块化设计思路 +--------------------------------------- + +内核的功能越来越多，代码量也越来越大。出于解耦合考虑，文件系统 easy-fs 被从内核中分离出来，分成两个不同的 crate ： + +- ``easy-fs`` 是简易文件系统的本体； +- ``easy-fs-fuse`` 是能在开发环境（如 Ubuntu）中运行的应用程序，用于将应用打包为 easy-fs 格式的文件系统镜像，也可以用来对 ``easy-fs`` 进行测试。 + +easy-fs与底层设备驱动之间通过抽象接口 ``BlockDevice`` 来连接，采用轮询方式访问 ``virtio_blk`` 虚拟磁盘设备，避免调用外设中断的相关内核函数。easy-fs 避免了直接访问进程相关的数据和函数，从而能独立于内核开发。 + +``easy-fs`` crate 以层次化思路设计，自下而上可以分成五个层次： + +1. 磁盘块设备接口层：以块为单位对磁盘块设备进行读写的 trait 接口 +2. 块缓存层：在内存中缓存磁盘块的数据，避免频繁读写磁盘 +3. 磁盘数据结构层：磁盘上的超级块、位图、索引节点、数据块、目录项等核心数据结构和相关处理 +4. 磁盘块管理器层：合并了上述核心数据结构和磁盘布局所形成的磁盘文件系统数据结构 +5. 索引节点层：管理索引节点，实现了文件创建/文件打开/文件读写等成员函数 + +本节将介绍前三层，下一节将介绍后两层。 + +.. image:: easy-fs-demo.png + :align: center + +块设备接口层 +--------------------------------------- + +在 ``easy-fs`` 库的最底层声明了块设备的抽象接口 ``BlockDevice`` ： + +.. code-block:: rust + + // easy-fs/src/block_dev.rs + + pub trait BlockDevice : Send + Sync + Any { + fn read_block(&self, block_id: usize, buf: &mut [u8]); + fn write_block(&self, block_id: usize, buf: &[u8]); + } + +它定义了两个抽象方法： + +- ``read_block`` 可以将编号为 ``block_id`` 的块从磁盘读入内存中的缓冲区 ``buf`` ； +- ``write_block`` 可以将内存中的缓冲区 ``buf`` 中的数据写入磁盘编号为 ``block_id`` 的块。 + +``easy-fs`` 的使用者将负责提供抽象方法的实现。 + +块缓存层 +--------------------------------------- + +为了加速 IO，内存可以作为磁盘的缓存。实现磁盘块缓存功能的代码在 ``block_cache.rs`` 。 + +块缓存 ++++++++++++++++++++++++++++++++++++++++++ + +块缓存 ``BlockCache`` 的声明如下： + +.. code-block:: rust + + // easy-fs/src/lib.rs + + pub const BLOCK_SZ: usize = 512; + + // easy-fs/src/block_cache.rs + + pub struct BlockCache { + cache: [u8; BLOCK_SZ], + block_id: usize, + block_device: Arc, + modified: bool, + } + +其中： + +- ``cache`` 是一个 512 字节的数组，表示位于内存中的缓冲区； +- ``block_id`` 记录了这个块的编号； +- ``block_device`` 记录块所属的底层设备； +- ``modified`` 记录自从这个块缓存从磁盘载入内存之后，它有没有被修改过。 + +创建 ``BlockCache`` 时，将一个块从磁盘读到缓冲区 ``cache`` ： + +.. code-block:: rust + + // easy-fs/src/block_cache.rs + + impl BlockCache { + /// Load a new BlockCache from disk. + pub fn new( + block_id: usize, + block_device: Arc + ) -> Self { + let mut cache = [0u8; BLOCK_SZ]; + block_device.read_block(block_id, &mut cache); + Self { + cache, + block_id, + block_device, + modified: false, + } + } + } + +``BlockCache`` 向上提供以下方法： + +.. code-block:: rust + :linenos: + + // easy-fs/src/block_cache.rs + + impl BlockCache { + fn addr_of_offset(&self, offset: usize) -> usize { + &self.cache[offset] as *const _ as usize + } + + pub fn get_ref(&self, offset: usize) -> &T where T: Sized { + let type_size = core::mem::size_of::(); + assert!(offset + type_size <= BLOCK_SZ); + let addr = self.addr_of_offset(offset); + unsafe { &*(addr as *const T) } + } + + pub fn get_mut(&mut self, offset: usize) -> &mut T where T: Sized { + let type_size = core::mem::size_of::(); + assert!(offset + type_size <= BLOCK_SZ); + self.modified = true; + let addr = self.addr_of_offset(offset); + unsafe { &mut *(addr as *mut T) } + } + } + +- ``addr_of_offset`` 可以得到一个 ``BlockCache`` 内部的缓冲区中指定偏移量 ``offset`` 的字节地址； +- ``get_ref`` 是一个泛型方法，它可以获取缓冲区中的位于偏移量 ``offset`` 的一个类型为 ``T`` 的磁盘上数据结构的不可变引用。该泛型方法的 Trait Bound 限制类型 ``T`` 必须是一个编译时已知大小的类型，我们通过 ``core::mem::size_of::()`` 在编译时获取类型 ``T`` 的大小并确认该数据结构被整个包含在磁盘块及其缓冲区之内。这里编译器会自动进行生命周期标注，约束返回的引用的生命周期不超过 ``BlockCache`` 自身，在使用的时候我们会保证这一点。 +- ``get_mut`` 与 ``get_ref`` 的不同之处在于它会获取磁盘上数据结构的可变引用，由此可以对数据结构进行修改。由于这些数据结构目前位于内存中的缓冲区中，我们需要将 ``BlockCache`` 的 ``modified`` 标记为 true 表示该缓冲区已经被修改，之后需要将数据写回磁盘块才能真正将修改同步到磁盘。 + +我们可以将 ``get_ref/get_mut`` 进一步封装为更为易用的形式： + +.. code-block:: rust + + // easy-fs/src/block_cache.rs + + impl BlockCache { + pub fn read(&self, offset: usize, f: impl FnOnce(&T) -> V) -> V { + f(self.get_ref(offset)) + } + + pub fn modify(&mut self, offset:usize, f: impl FnOnce(&mut T) -> V) -> V { + f(self.get_mut(offset)) + } + } + +它们的含义是：在 ``BlockCache`` 缓冲区偏移量为 ``offset`` 的位置，获取一个类型为 ``T`` 不可变/可变引用，将闭包 ``f`` 作用于这个引用，返回 ``f`` 的返回值。 中所定义的操作。 + +这里我们传入闭包的类型为 ``FnOnce`` ，这是因为闭包里面的变量被捕获的方式涵盖了不可变引用/可变引用/和 move 三种可能性，故而我们需要选取范围最广的 ``FnOnce`` 。参数中的 ``impl`` 关键字体现了一种类似泛型的静态分发功能。 + +.. warning:: + + **Rust 语法卡片：闭包** + + 闭包是持有外部环境变量的函数。所谓外部环境, 就是指创建闭包时所在的词法作用域。Rust中定义的闭包，按照对外部环境变量的使用方式（借用、复制、转移所有权），分为三个类型: Fn、FnMut、FnOnce。Fn类型的闭包会在闭包内部以共享借用的方式使用环境变量；FnMut类型的闭包会在闭包内部以独占借用的方式使用环境变量；而FnOnce类型的闭包会在闭包内部以所有者的身份使用环境变量。由此可见，根据闭包内使用环境变量的方式，即可判断创建出来的闭包的类型。 + + +当 ``BlockCache`` 的生命周期结束后，缓冲区也会被回收， ``modified`` 标记将会决定数据是否需要写回磁盘： + +.. code-block:: rust + + // easy-fs/src/block_cache.rs + + impl Drop for BlockCache { + fn drop(&mut self) { + if self.modified { + self.modified = false; + self.block_device.write_block(self.block_id, &self.cache); + } + } + } + +块缓存全局管理器 ++++++++++++++++++++++++++++++++++++++++++ + +内存只能同时缓存有限个磁盘块。当我们要对一个磁盘块进行读写时，块缓存全局管理器检查它是否已经被载入内存中，如果是则直接返回，否则就读取磁盘块到内存。如果内存中驻留的磁盘块缓冲区的数量已满，则需要进行缓存替换。这里使用一种类 FIFO 的缓存替换算法，在管理器中只需维护一个队列： + +.. code-block:: rust + + // easy-fs/src/block_cache.rs + + use alloc::collections::VecDeque; + + pub struct BlockCacheManager { + queue: VecDeque<(usize, Arc>)>, + } + +队列 ``queue`` 维护块编号和块缓存的二元组。块缓存的类型是一个 ``Arc>`` ，这是 Rust 中的经典组合，它可以同时提供共享引用和互斥访问。这里的共享引用意义在于块缓存既需要在管理器 ``BlockCacheManager`` 保留一个引用，还需要将引用返回给块缓存的请求者。而互斥访问在单核上的意义在于提供内部可变性通过编译，在多核环境下则可以帮助我们避免可能的并发冲突。 + +``get_block_cache`` 方法尝试从块缓存管理器中获取一个编号为 ``block_id`` 的块缓存，如果找不到的话会读取磁盘，还有可能会发生缓存替换： + +.. code-block:: rust + :linenos: + + // easy-fs/src/block_cache.rs + + impl BlockCacheManager { + pub fn get_block_cache( + &mut self, + block_id: usize, + block_device: Arc, + ) -> Arc> { + if let Some(pair) = self.queue + .iter() + .find(|pair| pair.0 == block_id) { + Arc::clone(&pair.1) + } else { + // substitute + if self.queue.len() == BLOCK_CACHE_SIZE { + // from front to tail + if let Some((idx, _)) = self.queue + .iter() + .enumerate() + .find(|(_, pair)| Arc::strong_count(&pair.1) == 1) { + self.queue.drain(idx..=idx); + } else { + panic!("Run out of BlockCache!"); + } + } + // load block into mem and push back + let block_cache = Arc::new(Mutex::new( + BlockCache::new(block_id, Arc::clone(&block_device)) + )); + self.queue.push_back((block_id, Arc::clone(&block_cache))); + block_cache + } + } + } + +- 第 9 行，遍历整个队列试图找到一个编号相同的块缓存，如果找到，将块缓存管理器中保存的块缓存的引用复制一份并返回； +- 第 13 行对应找不到的情况，此时必须将块从磁盘读入内存中的缓冲区。读取前需要判断已保存的块数量是否达到了上限。是，则执行缓存替换算法，替换的标准是其强引用计数 :math:`\eq 1` ，即除了块缓存管理器保留的一份副本之外，在外面没有副本正在使用。 +- 第 27 行开始，创建一个新的块缓存（会触发 ``read_block`` 进行块读取）并加入到队尾，最后返回给请求者。 + +磁盘布局及磁盘上数据结构 +--------------------------------------- + +磁盘数据结构层的代码在 ``layout.rs`` 和 ``bitmap.rs`` 中。 + +easy-fs 磁盘布局概述 ++++++++++++++++++++++++++++++++++++++++ + +easy-fs 磁盘按照块编号从小到大顺序分成 5 个连续区域： + +- 第一个区域只包括一个块，它是 **超级块** (Super Block)，用于定位其他连续区域的位置，检查文件系统合法性。 +- 第二个区域是一个索引节点位图，长度为若干个块。它记录了索引节点区域中有哪些索引节点已经被分配出去使用了。 +- 第三个区域是索引节点区域，长度为若干个块。其中的每个块都存储了若干个索引节点。 +- 第四个区域是一个数据块位图，长度为若干个块。它记录了后面的数据块区域中有哪些已经被分配出去使用了。 +- 最后的区域则是数据块区域，其中的每个被分配出去的块保存了文件或目录的具体内容。 + +easy-fs 超级块 ++++++++++++++++++++++++++++++++++++++++ + +超级块 ``SuperBlock`` 的内容如下： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + #[repr(C)] + pub struct SuperBlock { + magic: u32, + pub total_blocks: u32, + pub inode_bitmap_blocks: u32, + pub inode_area_blocks: u32, + pub data_bitmap_blocks: u32, + pub data_area_blocks: u32, + } + +其中， ``magic`` 是一个用于文件系统合法性验证的魔数， ``total_block`` 给出文件系统的总块数。后面的四个字段则分别给出 easy-fs 布局中后四个连续区域的长度各为多少个块。 + +下面是它实现的方法： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl SuperBlock { + pub fn initialize( + &mut self, + total_blocks: u32, + inode_bitmap_blocks: u32, + inode_area_blocks: u32, + data_bitmap_blocks: u32, + data_area_blocks: u32, + ); + + pub fn is_valid(&self) -> bool { + self.magic == EFS_MAGIC + } + } + +- ``initialize`` 用于在创建一个 easy-fs 的时候初始化超级块，各个区域的块数由更上层的磁盘块管理器传入。 +- ``is_valid`` 则可以通过魔数判断超级块所在的文件系统是否合法。 + +位图 ++++++++++++++++++++++++++++++++++++++++ + +在 easy-fs 布局中存在两类不同的位图，分别对索引节点和数据块进行管理。每个位图都由若干个块组成，每个块大小 4096 bits。每个 bit 都代表一个索引节点/数据块的分配状态。 + +.. code-block:: rust + + // easy-fs/src/bitmap.rs + + pub struct Bitmap { + start_block_id: usize, + blocks: usize, + } + + type BitmapBlock = [u64; 64]; + + +``Bitmap`` 是位图区域的管理器，它保存了位图区域的起始块编号和块数。而 ``BitmapBlock`` 将位图区域中的一个磁盘块解释为长度为 64 的一个 ``u64`` 数组。 + +首先来看 ``Bitmap`` 如何分配一个bit： + +.. code-block:: rust + :linenos: + + // easy-fs/src/bitmap.rs + + const BLOCK_BITS: usize = BLOCK_SZ * 8; + + impl Bitmap { + pub fn alloc(&self, block_device: &Arc) -> Option { + for block_id in 0..self.blocks { + let pos = get_block_cache( + block_id + self.start_block_id as usize, + Arc::clone(block_device), + ) + .lock() + .modify(0, |bitmap_block: &mut BitmapBlock| { + if let Some((bits64_pos, inner_pos)) = bitmap_block + .iter() + .enumerate() + .find(|(_, bits64)| **bits64 != u64::MAX) + .map(|(bits64_pos, bits64)| { + (bits64_pos, bits64.trailing_ones() as usize) + }) { + // modify cache + bitmap_block[bits64_pos] |= 1u64 << inner_pos; + Some(block_id * BLOCK_BITS + bits64_pos * 64 + inner_pos as usize) + } else { + None + } + }); + if pos.is_some() { + return pos; + } + } + None + } + } + +其主要思路是遍历区域中的每个块，再在每个块中以bit组（每组 64 bits）为单位进行遍历，找到一个尚未被全部分配出去的组，最后在里面分配一个bit。它将会返回分配的bit所在的位置，等同于索引节点/数据块的编号。如果所有bit均已经被分配出去了，则返回 ``None`` 。 + +第 7 行枚举区域中的每个块（编号为 ``block_id`` ），在循环内部我们需要读写这个块，在块内尝试找到一个空闲的bit并置 1 。一旦涉及到块的读写，就需要用到块缓存层提供的接口： + +- 第 8 行我们调用 ``get_block_cache`` 获取块缓存，注意我们传入的块编号是区域起始块编号 ``start_block_id`` 加上区域内的块编号 ``block_id`` 得到的块设备上的块编号。 +- 第 12 行我们通过 ``.lock()`` 获取块缓存的互斥锁从而可以对块缓存进行访问。 +- 第 13 行我们使用到了 ``BlockCache::modify`` 接口。它传入的偏移量 ``offset`` 为 0，这是因为整个块上只有一个 ``BitmapBlock`` ，它的大小恰好为 512 字节。因此我们需要从块的开头开始才能访问到完整的 ``BitmapBlock`` 。同时，传给它的闭包需要显式声明参数类型为 ``&mut BitmapBlock`` ，不然的话， ``BlockCache`` 的泛型方法 ``modify/get_mut`` 无法得知应该用哪个类型来解析块上的数据。在声明之后，编译器才能在这里将两个方法中的泛型 ``T`` 实例化为具体类型 ``BitmapBlock`` 。 + + 总结一下，这里 ``modify`` 的含义就是：从缓冲区偏移量为 0 的位置开始将一段连续的数据（数据的长度随具体类型而定）解析为一个 ``BitmapBlock`` 并要对该数据结构进行修改。在闭包内部，我们可以使用这个 ``BitmapBlock`` 的可变引用 ``bitmap_block`` 对它进行访问。 ``read/get_ref`` 的用法完全相同，后面将不再赘述。 +- 闭包的主体位于第 14~26 行。它尝试在 ``bitmap_block`` 中找到一个空闲的bit并返回其位置，如果不存在的话则返回 ``None`` 。它的思路是，遍历每 64 bits构成的组（一个 ``u64`` ），如果它并没有达到 ``u64::MAX`` （即 :math:`2^{64}-1` ），则通过 ``u64::trailing_ones`` 找到最低的一个 0 并置为 1 。如果能够找到的话，bit组的编号将保存在变量 ``bits64_pos`` 中，而分配的bit在组内的位置将保存在变量 ``inner_pos`` 中。在返回分配的bit编号的时候，它的计算方式是 ``block_id*BLOCK_BITS+bits64_pos*64+inner_pos`` 。注意闭包中的 ``block_id`` 并不在闭包的参数列表中，因此它是从外部环境（即自增 ``block_id`` 的循环）中捕获到的。 + +我们一旦在某个块中找到一个空闲的bit并成功分配，就不再考虑后续的块。第 28 行体现了提前返回的思路。 + +回收 bit 的方法类似，感兴趣的读者可自行阅读源代码。 + +磁盘上索引节点 ++++++++++++++++++++++++++++++++++++++++ + +在磁盘上的索引节点区域，每个块上都保存着若干个索引节点 ``DiskInode`` ： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + const INODE_DIRECT_COUNT: usize = 28; + + #[repr(C)] + pub struct DiskInode { + pub size: u32, + pub direct: [u32; INODE_DIRECT_COUNT], + pub indirect1: u32, + pub indirect2: u32, + type_: DiskInodeType, + } + + #[derive(PartialEq)] + pub enum DiskInodeType { + File, + Directory, + } + +每个文件/目录在磁盘上均以一个 ``DiskInode`` 的形式存储。其中包含文件/目录的元数据： ``size`` 表示文件/目录内容的字节数， ``type_`` 表示索引节点的类型 ``DiskInodeType`` ，目前仅支持文件 ``File`` 和目录 ``Directory`` 两种类型。其余的 ``direct/indirect1/indirect2`` 都是存储文件内容/目录内容的数据块的索引，这也是索引节点名字的由来。 + +为了尽可能节约空间，在进行索引的时候，块的编号用一个 ``u32`` 存储。索引方式分成直接索引和间接索引两种： + +- 当文件很小的时候，只需用到直接索引， ``direct`` 数组中最多可以指向 ``INODE_DIRECT_COUNT`` 个数据块，当取值为 28 的时候，通过直接索引可以找到 14KiB 的内容。 +- 当文件比较大的时候，不仅直接索引的 ``direct`` 数组装满，还需要用到一级间接索引 ``indirect1`` 。它指向一个一级索引块，这个块也位于磁盘布局的数据块区域中。这个一级索引块中的每个 ``u32`` 都用来指向数据块区域中一个保存该文件内容的数据块，因此，最多能够索引 :math:`\frac{512}{4}=128` 个数据块，对应 64KiB 的内容。 +- 当文件大小超过直接索引和一级索引支持的容量上限 78KiB 的时候，就需要用到二级间接索引 ``indirect2`` 。它指向一个位于数据块区域中的二级索引块。二级索引块中的每个 ``u32`` 指向一个不同的一级索引块，这些一级索引块也位于数据块区域中。因此，通过二级间接索引最多能够索引 :math:`128\times 64\text{KiB}=8\text{MiB}` 的内容。 + +为了充分利用空间，我们将 ``DiskInode`` 的大小设置为 128 字节，每个块正好能够容纳 4 个 ``DiskInode`` 。在后续需要支持更多类型的元数据的时候，可以适当缩减直接索引 ``direct`` 的块数，并将节约出来的空间用来存放其他元数据，仍可保证 ``DiskInode`` 的总大小为 128 字节。 + +通过 ``initialize`` 方法可以初始化一个 ``DiskInode`` 为一个文件或目录： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DiskInode { + /// indirect1 and indirect2 block are allocated only when they are needed. + pub fn initialize(&mut self, type_: DiskInodeType) { + self.size = 0; + self.direct.iter_mut().for_each(|v| *v = 0); + self.indirect1 = 0; + self.indirect2 = 0; + self.type_ = type_; + } + } + +需要注意的是， ``indirect1/2`` 均被初始化为 0 。因为最开始文件内容的大小为 0 字节，并不会用到一级/二级索引。为了节约空间，我们会完全按需分配一级/二级索引块。此外，直接索引 ``direct`` 也被清零。 + +``is_file`` 和 ``is_dir`` 两个方法可以用来确认 ``DiskInode`` 的类型为文件还是目录： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DiskInode { + pub fn is_dir(&self) -> bool { + self.type_ == DiskInodeType::Directory + } + pub fn is_file(&self) -> bool { + self.type_ == DiskInodeType::File + } + } + +``get_block_id`` 方法体现了 ``DiskInode`` 最重要的数据块索引功能，它可以从索引中查到它自身用于保存文件内容的第 ``block_id`` 个数据块的块编号，这样后续才能对这个数据块进行访问： + +.. code-block:: rust + :linenos: + :emphasize-lines: 10,12,18 + + // easy-fs/src/layout.rs + + const INODE_INDIRECT1_COUNT: usize = BLOCK_SZ / 4; + const INDIRECT1_BOUND: usize = DIRECT_BOUND + INODE_INDIRECT1_COUNT; + type IndirectBlock = [u32; BLOCK_SZ / 4]; + + impl DiskInode { + pub fn get_block_id(&self, inner_id: u32, block_device: &Arc) -> u32 { + let inner_id = inner_id as usize; + if inner_id < INODE_DIRECT_COUNT { + self.direct[inner_id] + } else if inner_id < INDIRECT1_BOUND { + get_block_cache(self.indirect1 as usize, Arc::clone(block_device)) + .lock() + .read(0, |indirect_block: &IndirectBlock| { + indirect_block[inner_id - INODE_DIRECT_COUNT] + }) + } else { + let last = inner_id - INDIRECT1_BOUND; + let indirect1 = get_block_cache( + self.indirect2 as usize, + Arc::clone(block_device) + ) + .lock() + .read(0, |indirect2: &IndirectBlock| { + indirect2[last / INODE_INDIRECT1_COUNT] + }); + get_block_cache( + indirect1 as usize, + Arc::clone(block_device) + ) + .lock() + .read(0, |indirect1: &IndirectBlock| { + indirect1[last % INODE_INDIRECT1_COUNT] + }) + } + } + } + +这里需要说明的是： + +- 第 10/12/18 行分别利用直接索引/一级索引和二级索引，具体选用哪种索引方式取决于 ``block_id`` 所在的区间。 +- 在对一个索引块进行操作的时候，我们将其解析为磁盘数据结构 ``IndirectBlock`` ，实质上就是一个 ``u32`` 数组，每个都指向一个下一级索引块或者数据块。 +- 对于二级索引的情况，需要先查二级索引块找到挂在它下面的一级索引块，再通过一级索引块找到数据块。 + +在初始化之后文件/目录的 ``size`` 均为 0 ，此时并不会索引到任何数据块。它需要通过 ``increase_size`` 方法逐步扩充容量。在扩充的时候，自然需要一些新的数据块来作为索引块或是保存内容的数据块。我们需要先编写一些辅助方法来确定在容量扩充的时候额外需要多少块： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DiskInode { + /// Return block number correspond to size. + pub fn data_blocks(&self) -> u32 { + Self::_data_blocks(self.size) + } + fn _data_blocks(size: u32) -> u32 { + (size + BLOCK_SZ as u32 - 1) / BLOCK_SZ as u32 + } + /// Return number of blocks needed include indirect1/2. + pub fn total_blocks(size: u32) -> u32 { + let data_blocks = Self::_data_blocks(size) as usize; + let mut total = data_blocks as usize; + // indirect1 + if data_blocks > INODE_DIRECT_COUNT { + total += 1; + } + // indirect2 + if data_blocks > INDIRECT1_BOUND { + total += 1; + // sub indirect1 + total += (data_blocks - INDIRECT1_BOUND + INODE_INDIRECT1_COUNT - 1) / INODE_INDIRECT1_COUNT; + } + total as u32 + } + pub fn blocks_num_needed(&self, new_size: u32) -> u32 { + assert!(new_size >= self.size); + Self::total_blocks(new_size) - Self::total_blocks(self.size) + } + } + +``data_blocks`` 方法可以计算为了容纳自身 ``size`` 字节的内容需要多少个数据块。计算的过程只需用 ``size`` 除以每个块的大小 ``BLOCK_SZ`` 并向上取整。而 ``total_blocks`` 不仅包含数据块，还需要统计索引块。计算的方法也很简单，先调用 ``data_blocks`` 得到需要多少数据块，再根据数据块数目所处的区间统计索引块即可。 ``blocks_num_needed`` 可以计算将一个 ``DiskInode`` 的 ``size`` 扩容到 ``new_size`` 需要额外多少个数据和索引块。这只需要调用两次 ``total_blocks`` 作差即可。 + +下面给出 ``increase_size`` 方法的接口： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DiskInode { + pub fn increase_size( + &mut self, + new_size: u32, + new_blocks: Vec, + block_device: &Arc, + ); + } + +其中 ``new_size`` 表示容量扩充之后的文件大小； ``new_blocks`` 是一个保存了本次容量扩充所需块编号的向量，这些块都是由上层的磁盘块管理器负责分配的。 ``increase_size`` 的实现有些复杂，在这里不详细介绍。大致的思路是按照直接索引、一级索引再到二级索引的顺序进行扩充。 + +有些时候我们还需要清空文件的内容并回收所有数据和索引块。这是通过 ``clear_size`` 方法来实现的： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DiskInode { + /// Clear size to zero and return blocks that should be deallocated. + /// + /// We will clear the block contents to zero later. + pub fn clear_size(&mut self, block_device: &Arc) -> Vec; + } + +它会将回收的所有块的编号保存在一个向量中返回给磁盘块管理器。它的实现原理和 ``increase_size`` 一样也分为多个阶段，在这里不展开。 + +接下来需要考虑通过 ``DiskInode`` 来读写它索引的那些数据块中的数据。这些数据可以被视为一个字节序列，而每次我们都是选取其中的一段连续区间进行操作，以 ``read_at`` 为例： + +.. code-block:: rust + :linenos: + + // easy-fs/src/layout.rs + + type DataBlock = [u8; BLOCK_SZ]; + + impl DiskInode { + pub fn read_at( + &self, + offset: usize, + buf: &mut [u8], + block_device: &Arc, + ) -> usize { + let mut start = offset; + let end = (offset + buf.len()).min(self.size as usize); + if start >= end { + return 0; + } + let mut start_block = start / BLOCK_SZ; + let mut read_size = 0usize; + loop { + // calculate end of current block + let mut end_current_block = (start / BLOCK_SZ + 1) * BLOCK_SZ; + end_current_block = end_current_block.min(end); + // read and update read size + let block_read_size = end_current_block - start; + let dst = &mut buf[read_size..read_size + block_read_size]; + get_block_cache( + self.get_block_id(start_block as u32, block_device) as usize, + Arc::clone(block_device), + ) + .lock() + .read(0, |data_block: &DataBlock| { + let src = &data_block[start % BLOCK_SZ..start % BLOCK_SZ + block_read_size]; + dst.copy_from_slice(src); + }); + read_size += block_read_size; + // move to next block + if end_current_block == end { break; } + start_block += 1; + start = end_current_block; + } + read_size + } + } + +它的含义是：将文件内容从 ``offset`` 字节开始的部分读到内存中的缓冲区 ``buf`` 中，并返回实际读到的字节数。如果文件剩下的内容还足够多，那么缓冲区会被填满；不然的话文件剩下的全部内容都会被读到缓冲区中。具体实现上有很多细节，但大致的思路是遍历位于字节区间 ``start,end`` 中间的那些块，将它们视为一个 ``DataBlock`` （也就是一个字节数组），并将其中的部分内容复制到缓冲区 ``buf`` 中适当的区域。 ``start_block`` 维护着目前是文件内部第多少个数据块，需要首先调用 ``get_block_id`` 从索引中查到这个数据块在块设备中的块编号，随后才能传入 ``get_block_cache`` 中将正确的数据块缓存到内存中进行访问。 + +在第 14 行进行了简单的边界条件判断，如果要读取的内容超出了文件的范围那么直接返回 0 表示读取不到任何内容。 + +``write_at`` 的实现思路基本上和 ``read_at`` 完全相同。但不同的是 ``write_at`` 不会出现失败的情况，传入的整个缓冲区的数据都必定会被写入到文件中。当从 ``offset`` 开始的区间超出了文件范围的时候，就需要调用者在调用 ``write_at`` 之前提前调用 ``increase_size`` 将文件大小扩充到区间的右端保证写入的完整性。 + +目录项 ++++++++++++++++++++++++++++++++++++++++ + +对于文件而言，它的内容在文件系统或内核看来没有任何既定的格式，只是一个字节序列。目录的内容却需要遵从一种特殊的格式，它可以看成一个目录项的序列，每个目录项都是一个二元组，包括目录下文件的文件名和索引节点编号。目录项 ``DirEntry`` 的定义如下： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + const NAME_LENGTH_LIMIT: usize = 27; + + #[repr(C)] + pub struct DirEntry { + name: [u8; NAME_LENGTH_LIMIT + 1], + inode_number: u32, + } + + pub const DIRENT_SZ: usize = 32; + +目录项 ``Dirent`` 保存的文件名长度不能超过 27。目录项自身长 32 字节，每个数据块可以存储 16 个目录项。可以通过 ``empty`` 和 ``new`` 方法生成目录项，通过 ``name`` 和 ``inode_number`` 方法取出目录项中的内容： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DirEntry { + pub fn empty() -> Self; + pub fn new(name: &str, inode_number: u32) -> Self; + pub fn name(&self) -> &str; + pub fn inode_number(&self) -> u32 + } + +在从目录中读取目录项，或将目录项写入目录时，需要将目录项转化为缓冲区（即字节切片）的形式来符合 ``read_at OR write_at`` 接口的要求： + +.. code-block:: rust + + // easy-fs/src/layout.rs + + impl DirEntry { + pub fn as_bytes(&self) -> &[u8] { + unsafe { + core::slice::from_raw_parts( + self as *const _ as usize as *const u8, + DIRENT_SZ, + ) + } + } + pub fn as_bytes_mut(&mut self) -> &mut [u8] { + unsafe { + core::slice::from_raw_parts_mut( + self as *mut _ as usize as *mut u8, + DIRENT_SZ, + ) + } + } + } diff --git a/guide/source/chapter6/2fs-implementation-2.rst b/guide/source/chapter6/2fs-implementation-2.rst new file mode 100644 index 0000000..d8f0a57 --- /dev/null +++ b/guide/source/chapter6/2fs-implementation-2.rst @@ -0,0 +1,591 @@ +简易文件系统 easy-fs (下) +======================================= + + +磁盘块管理器 +--------------------------------------- + +本层的代码在 ``efs.rs`` 中。 + +.. code-block:: rust + + // easy-fs/src/efs.rs + + pub struct EasyFileSystem { + pub block_device: Arc, + pub inode_bitmap: Bitmap, + pub data_bitmap: Bitmap, + inode_area_start_block: u32, + data_area_start_block: u32, + } + +``EasyFileSystem`` 包含索引节点和数据块的两个位图 ``inode_bitmap`` 和 ``data_bitmap`` ，还记录下索引节点区域和数据块区域起始块编号方便确定每个索引节点和数据块在磁盘上的具体位置。我们还要在其中保留块设备的一个指针 ``block_device`` ，在进行后续操作的时候，该指针会被拷贝并传递给下层的数据结构，让它们也能够直接访问块设备。 + +通过 ``create`` 方法可以在块设备上创建并初始化一个 easy-fs 文件系统： + +.. code-block:: rust + :linenos: + + // easy-fs/src/efs.rs + + impl EasyFileSystem { + pub fn create( + block_device: Arc, + total_blocks: u32, + inode_bitmap_blocks: u32, + ) -> Arc> { + // calculate block size of areas & create bitmaps + let inode_bitmap = Bitmap::new(1, inode_bitmap_blocks as usize); + let inode_num = inode_bitmap.maximum(); + let inode_area_blocks = + ((inode_num * core::mem::size_of::() + BLOCK_SZ - 1) / BLOCK_SZ) as u32; + let inode_total_blocks = inode_bitmap_blocks + inode_area_blocks; + let data_total_blocks = total_blocks - 1 - inode_total_blocks; + let data_bitmap_blocks = (data_total_blocks + 4096) / 4097; + let data_area_blocks = data_total_blocks - data_bitmap_blocks; + let data_bitmap = Bitmap::new( + (1 + inode_bitmap_blocks + inode_area_blocks) as usize, + data_bitmap_blocks as usize, + ); + let mut efs = Self { + block_device: Arc::clone(&block_device), + inode_bitmap, + data_bitmap, + inode_area_start_block: 1 + inode_bitmap_blocks, + data_area_start_block: 1 + inode_total_blocks + data_bitmap_blocks, + }; + // clear all blocks + for i in 0..total_blocks { + get_block_cache( + i as usize, + Arc::clone(&block_device) + ) + .lock() + .modify(0, |data_block: &mut DataBlock| { + for byte in data_block.iter_mut() { *byte = 0; } + }); + } + // initialize SuperBlock + get_block_cache(0, Arc::clone(&block_device)) + .lock() + .modify(0, |super_block: &mut SuperBlock| { + super_block.initialize( + total_blocks, + inode_bitmap_blocks, + inode_area_blocks, + data_bitmap_blocks, + data_area_blocks, + ); + }); + // write back immediately + // create a inode for root node "/" + assert_eq!(efs.alloc_inode(), 0); + let (root_inode_block_id, root_inode_offset) = efs.get_disk_inode_pos(0); + get_block_cache( + root_inode_block_id as usize, + Arc::clone(&block_device) + ) + .lock() + .modify(root_inode_offset, |disk_inode: &mut DiskInode| { + disk_inode.initialize(DiskInodeType::Directory); + }); + Arc::new(Mutex::new(efs)) + } + } + +- 第 10~21 行根据传入的参数计算每个区域各应该包含多少块。根据 inode 位图的大小计算 inode 区域至少需要多少个块才能够使得 inode 位图中的每个bit都能够有一个实际的 inode 可以对应，这样就确定了 inode 位图区域和 inode 区域的大小。剩下的块都分配给数据块位图区域和数据块区域。我们希望数据块位图中的每个bit仍然能够对应到一个数据块，但是数据块位图又不能过小，不然会造成某些数据块永远不会被使用。因此数据块位图区域最合理的大小是剩余的块数除以 4097 再上取整，因为位图中的每个块能够对应 4096 个数据块。其余的块就都作为数据块使用。 +- 第 22 行创建我们的 ``EasyFileSystem`` 实例 ``efs`` 。 +- 第 30 行首先将块设备的前 ``total_blocks`` 个块清零，因为我们的 easy-fs 要用到它们，这也是为初始化做准备。 +- 第 41 行将位于块设备编号为 0 块上的超级块进行初始化，只需传入之前计算得到的每个区域的块数就行了。 +- 第 54~63 行我们要做的事情是创建根目录 ``/`` 。首先需要调用 ``alloc_inode`` 在 inode 位图中分配一个 inode ，由于这是第一次分配，它的编号固定是 0 。接下来需要将分配到的 inode 初始化为 easy-fs 中的唯一一个目录，我们需要调用 ``get_disk_inode_pos`` 来根据 inode 编号获取该 inode 所在的块的编号以及块内偏移，之后就可以将它们传给 ``get_block_cache`` 和 ``modify`` 了。 + +通过 ``open`` 方法可以从一个已写入了 easy-fs 镜像的块设备上打开我们的 easy-fs ： + +.. code-block:: rust + + // easy-fs/src/efs.rs + + impl EasyFileSystem { + pub fn open(block_device: Arc) -> Arc> { + // read SuperBlock + get_block_cache(0, Arc::clone(&block_device)) + .lock() + .read(0, |super_block: &SuperBlock| { + assert!(super_block.is_valid(), "Error loading EFS!"); + let inode_total_blocks = + super_block.inode_bitmap_blocks + super_block.inode_area_blocks; + let efs = Self { + block_device, + inode_bitmap: Bitmap::new( + 1, + super_block.inode_bitmap_blocks as usize + ), + data_bitmap: Bitmap::new( + (1 + inode_total_blocks) as usize, + super_block.data_bitmap_blocks as usize, + ), + inode_area_start_block: 1 + super_block.inode_bitmap_blocks, + data_area_start_block: 1 + inode_total_blocks + super_block.data_bitmap_blocks, + }; + Arc::new(Mutex::new(efs)) + }) + } + } + +它只需将块设备编号为 0 的块作为超级块读取进来，就可以从中知道 easy-fs 的磁盘布局，由此可以构造 ``efs`` 实例。 + +``EasyFileSystem`` 知道整个磁盘布局，即可以从 inode位图 或数据块位图上分配的 bit 编号，来算出各个存储inode和数据块的磁盘块在磁盘上的实际位置。 + +.. code-block:: rust + + // easy-fs/src/efs.rs + + impl EasyFileSystem { + pub fn get_disk_inode_pos(&self, inode_id: u32) -> (u32, usize) { + let inode_size = core::mem::size_of::(); + let inodes_per_block = (BLOCK_SZ / inode_size) as u32; + let block_id = self.inode_area_start_block + inode_id / inodes_per_block; + (block_id, (inode_id % inodes_per_block) as usize * inode_size) + } + + pub fn get_data_block_id(&self, data_block_id: u32) -> u32 { + self.data_area_start_block + data_block_id + } + } + +inode 和数据块的分配/回收也由它负责： + +.. code-block:: rust + + // easy-fs/src/efs.rs + + impl EasyFileSystem { + pub fn alloc_inode(&mut self) -> u32 { + self.inode_bitmap.alloc(&self.block_device).unwrap() as u32 + } + + /// Return a block ID not ID in the data area. + pub fn alloc_data(&mut self) -> u32 { + self.data_bitmap.alloc(&self.block_device).unwrap() as u32 + self.data_area_start_block + } + + pub fn dealloc_data(&mut self, block_id: u32) { + get_block_cache( + block_id as usize, + Arc::clone(&self.block_device) + ) + .lock() + .modify(0, |data_block: &mut DataBlock| { + data_block.iter_mut().for_each(|p| { *p = 0; }) + }); + self.data_bitmap.dealloc( + &self.block_device, + (block_id - self.data_area_start_block) as usize + ) + } + } + +注意： + +- ``alloc_data`` 和 ``dealloc_data`` 分配/回收数据块传入/返回的参数都表示数据块在块设备上的编号，而不是在数据块位图中分配的bit编号； +- ``dealloc_inode`` 未实现，不支持文件删除。 + +索引节点 +--------------------------------------- + +服务于文件相关系统调用的索引节点层的代码在 ``vfs.rs`` 中。 + +``EasyFileSystem`` 实现了我们设计的磁盘布局并能够将所有块有效的管理起来。但是对于文件系统的使用者而言，他们往往不关心磁盘布局是如何实现的，而是更希望能够直接看到目录树结构中逻辑上的文件和目录。为此我们设计索引节点 ``Inode`` 暴露给文件系统的使用者，让他们能够直接对文件和目录进行操作。 ``Inode`` 和 ``DiskInode`` 的区别从它们的名字中就可以看出： ``DiskInode`` 放在磁盘块中比较固定的位置，而 ``Inode`` 是放在内存中的记录文件索引节点信息的数据结构。 + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + pub struct Inode { + block_id: usize, + block_offset: usize, + fs: Arc>, + block_device: Arc, + } + +``block_id`` 和 ``block_offset`` 记录该 ``Inode`` 对应的 ``DiskInode`` 保存在磁盘上的具体位置方便我们后续对它进行访问。 ``fs`` 是指向 ``EasyFileSystem`` 的一个指针，因为对 ``Inode`` 的种种操作实际上都是要通过底层的文件系统来完成。 + +仿照 ``BlockCache::read/modify`` ，我们可以设计两个方法来简化对于 ``Inode`` 对应的磁盘上的 ``DiskInode`` 的访问流程，而不是每次都需要 ``get_block_cache.lock.read/modify`` ： + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + impl Inode { + fn read_disk_inode(&self, f: impl FnOnce(&DiskInode) -> V) -> V { + get_block_cache( + self.block_id, + Arc::clone(&self.block_device) + ).lock().read(self.block_offset, f) + } + + fn modify_disk_inode(&self, f: impl FnOnce(&mut DiskInode) -> V) -> V { + get_block_cache( + self.block_id, + Arc::clone(&self.block_device) + ).lock().modify(self.block_offset, f) + } + } + +下面我们分别介绍文件系统的使用者对于文件系统的一些常用操作： + +获取根目录的 inode ++++++++++++++++++++++++++++++++++++++++ + +文件系统的使用者在通过 ``EasyFileSystem::open`` 从装载了 easy-fs 镜像的块设备上打开 easy-fs 之后，要做的第一件事情就是获取根目录的 ``Inode`` 。因为我们目前仅支持绝对路径，对于任何文件/目录的索引都必须从根目录开始向下逐级进行。等到索引完成之后，我们才能对文件/目录进行操作。事实上 ``EasyFileSystem`` 提供了另一个名为 ``root_inode`` 的方法来获取根目录的 ``Inode`` : + +.. code-block:: rust + + // easy-fs/src/efs.rs + + impl EasyFileSystem { + pub fn root_inode(efs: &Arc>) -> Inode { + let block_device = Arc::clone(&efs.lock().block_device); + // acquire efs lock temporarily + let (block_id, block_offset) = efs.lock().get_disk_inode_pos(0); + // release efs lock + Inode::new( + block_id, + block_offset, + Arc::clone(efs), + block_device, + ) + } + } + + // easy-fs/src/vfs.rs + + impl Inode { + /// We should not acquire efs lock here. + pub fn new( + block_id: u32, + block_offset: usize, + fs: Arc>, + block_device: Arc, + ) -> Self { + Self { + block_id: block_id as usize, + block_offset, + fs, + block_device, + } + } + } + +在 ``root_inode`` 中，主要是在 ``Inode::new`` 的时候将传入的 ``inode_id`` 设置为 0 ，因为根目录对应于文件系统中第一个分配的 inode ，因此它的 ``inode_id`` 总会是 0 。同时在设计上，我们不会在 ``Inode::new`` 中尝试获取整个 ``EasyFileSystem`` 的锁来查询 inode 在块设备中的位置，而是在调用它之前预先查询并作为参数传过去。 + +文件索引 ++++++++++++++++++++++++++++++++++++++++ + +为了尽可能简化我们的实现，所有的文件都在根目录下面。于是，我们不必实现目录索引。文件索引的查找比较简单，仅需在根目录的目录项中根据文件名找到文件的 inode 编号即可。由于没有子目录的存在，这个过程只会进行一次。 + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + impl Inode { + pub fn find(&self, name: &str) -> Option> { + let fs = self.fs.lock(); + self.read_disk_inode(|disk_inode| { + self.find_inode_id(name, disk_inode) + .map(|inode_id| { + let (block_id, block_offset) = fs.get_disk_inode_pos(inode_id); + Arc::new(Self::new( + block_id, + block_offset, + self.fs.clone(), + self.block_device.clone(), + )) + }) + }) + } + + fn find_inode_id( + &self, + name: &str, + disk_inode: &DiskInode, + ) -> Option { + // assert it is a directory + assert!(disk_inode.is_dir()); + let file_count = (disk_inode.size as usize) / DIRENT_SZ; + let mut dirent = DirEntry::empty(); + for i in 0..file_count { + assert_eq!( + disk_inode.read_at( + DIRENT_SZ * i, + dirent.as_bytes_mut(), + &self.block_device, + ), + DIRENT_SZ, + ); + if dirent.name() == name { + return Some(dirent.inode_number() as u32); + } + } + None + } + } + +``find`` 方法只会被根目录 ``Inode`` 调用，文件系统中其他文件的 ``Inode`` 不会调用这个方法。它首先调用 ``find_inode_id`` 方法尝试从根目录的 ``DiskInode`` 上找到要索引的文件名对应的 inode 编号。这就需要将根目录内容中的所有目录项都读到内存进行逐个比对。如果能够找到的话， ``find`` 方法会根据查到 inode 编号对应生成一个 ``Inode`` 用于后续对文件的访问。 + +这里需要注意的是，包括 ``find`` 在内所有暴露给文件系统的使用者的文件系统操作（还包括接下来将要介绍的几种），全程均需持有 ``EasyFileSystem`` 的互斥锁（相对的，文件系统内部的操作如之前的 ``Inode::new`` 或是上面的 ``find_inode_id`` 都是假定在已持有 efs 锁的情况下才被调用的，因此它们不应尝试获取锁）。这能够保证在多核情况下，同时最多只能有一个核在进行文件系统相关操作。这样也许会带来一些不必要的性能损失，但我们目前暂时先这样做。如果我们在这里加锁的话，其实就能够保证块缓存的互斥访问了。 + +文件列举 ++++++++++++++++++++++++++++++++++++++++ + +``ls`` 方法可以收集根目录下的所有文件的文件名并以向量的形式返回，这个方法只有根目录的 ``Inode`` 才会调用： + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + impl Inode { + pub fn ls(&self) -> Vec { + let _fs = self.fs.lock(); + self.read_disk_inode(|disk_inode| { + let file_count = (disk_inode.size as usize) / DIRENT_SZ; + let mut v: Vec = Vec::new(); + for i in 0..file_count { + let mut dirent = DirEntry::empty(); + assert_eq!( + disk_inode.read_at( + i * DIRENT_SZ, + dirent.as_bytes_mut(), + &self.block_device, + ), + DIRENT_SZ, + ); + v.push(String::from(dirent.name())); + } + v + }) + } + } + +文件创建 ++++++++++++++++++++++++++++++++++++++++ + +``create`` 方法可以在根目录下创建一个文件，该方法只有根目录的 ``Inode`` 会调用： + +.. code-block:: rust + :linenos: + + // easy-fs/src/vfs.rs + + impl Inode { + pub fn create(&self, name: &str) -> Option> { + let mut fs = self.fs.lock(); + if self.modify_disk_inode(|root_inode| { + // assert it is a directory + assert!(root_inode.is_dir()); + // has the file been created? + self.find_inode_id(name, root_inode) + }).is_some() { + return None; + } + // create a new file + // alloc a inode with an indirect block + let new_inode_id = fs.alloc_inode(); + // initialize inode + let (new_inode_block_id, new_inode_block_offset) + = fs.get_disk_inode_pos(new_inode_id); + get_block_cache( + new_inode_block_id as usize, + Arc::clone(&self.block_device) + ).lock().modify(new_inode_block_offset, |new_inode: &mut DiskInode| { + new_inode.initialize(DiskInodeType::File); + }); + self.modify_disk_inode(|root_inode| { + // append file in the dirent + let file_count = (root_inode.size as usize) / DIRENT_SZ; + let new_size = (file_count + 1) * DIRENT_SZ; + // increase size + self.increase_size(new_size as u32, root_inode, &mut fs); + // write dirent + let dirent = DirEntry::new(name, new_inode_id); + root_inode.write_at( + file_count * DIRENT_SZ, + dirent.as_bytes(), + &self.block_device, + ); + }); + + let (block_id, block_offset) = fs.get_disk_inode_pos(new_inode_id); + // return inode + Some(Arc::new(Self::new( + block_id, + block_offset, + self.fs.clone(), + self.block_device.clone(), + ))) + // release efs lock automatically by compiler + } + } + +- 第 6~13 行，检查文件是否已经在根目录下，如果找到的话返回 ``None`` ； +- 第 14~25 行，为待创建文件分配一个新的 inode 并进行初始化； +- 第 26~39 行，将待创建文件的目录项插入到根目录的内容中使得之后可以索引过来。 + +文件清空 ++++++++++++++++++++++++++++++++++++++++ + +在以某些标志位打开文件（例如带有 *CREATE* 标志打开一个已经存在的文件）的时候，需要首先将文件清空。在索引到文件的 ``Inode`` 之后可以调用 ``clear`` 方法： + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + impl Inode { + pub fn clear(&self) { + let mut fs = self.fs.lock(); + self.modify_disk_inode(|disk_inode| { + let size = disk_inode.size; + let data_blocks_dealloc = disk_inode.clear_size(&self.block_device); + assert!(data_blocks_dealloc.len() == DiskInode::total_blocks(size) as usize); + for data_block in data_blocks_dealloc.into_iter() { + fs.dealloc_data(data_block); + } + }); + } + } + +这会将之前该文件占据的索引块和数据块在 ``EasyFileSystem`` 中回收。 + +文件读写 ++++++++++++++++++++++++++++++++++++++++ + +从根目录索引到一个文件之后可以对它进行读写，注意，和 ``DiskInode`` 一样，这里的读写作用在字节序列的一段区间上： + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + impl Inode { + pub fn read_at(&self, offset: usize, buf: &mut [u8]) -> usize { + let _fs = self.fs.lock(); + self.read_disk_inode(|disk_inode| { + disk_inode.read_at(offset, buf, &self.block_device) + }) + } + + pub fn write_at(&self, offset: usize, buf: &[u8]) -> usize { + let mut fs = self.fs.lock(); + self.modify_disk_inode(|disk_inode| { + self.increase_size((offset + buf.len()) as u32, disk_inode, &mut fs); + disk_inode.write_at(offset, buf, &self.block_device) + }) + } + } + +具体实现比较简单，需要注意在 ``DiskInode::write_at`` 之前先调用 ``increase_size`` 对自身进行扩容： + +.. code-block:: rust + + // easy-fs/src/vfs.rs + + impl Inode { + fn increase_size( + &self, + new_size: u32, + disk_inode: &mut DiskInode, + fs: &mut MutexGuard, + ) { + if new_size < disk_inode.size { + return; + } + let blocks_needed = disk_inode.blocks_num_needed(new_size); + let mut v: Vec = Vec::new(); + for _ in 0..blocks_needed { + v.push(fs.alloc_data()); + } + disk_inode.increase_size(new_size, v, &self.block_device); + } + } + +这里会从 ``EasyFileSystem`` 中分配一些用于扩容的数据块并传给 ``DiskInode::increase_size`` 。 + +将应用打包为 easy-fs 镜像 +--------------------------------------- + +在第六章中我们需要将所有的应用都链接到内核中，随后在应用管理器中通过应用名进行索引来找到应用的 ELF 数据。这样做有一个缺点，就是会造成内核体积过度膨胀。同时这也会浪费内存资源，因为未被执行的应用也占据了内存空间。在实现了我们自己的文件系统之后，终于可以将这些应用打包到 easy-fs 镜像中放到磁盘中，当我们要执行应用的时候只需从文件系统中取出ELF 执行文件格式的应用 并加载到内存中执行即可，这样就避免了上面的那些问题。 + +``easy-fs-fuse`` 的主体 ``easy-fs-pack`` 函数就实现了这个功能： + +.. code-block:: rust + :linenos: + + // easy-fs-fuse/src/main.rs + + use clap::{Arg, App}; + + fn easy_fs_pack() -> std::io::Result<()> { + let matches = App::new("EasyFileSystem packer") + .arg(Arg::with_name("source") + .short("s") + .long("source") + .takes_value(true) + .help("Executable source dir(with backslash)") + ) + .arg(Arg::with_name("target") + .short("t") + .long("target") + .takes_value(true) + .help("Executable target dir(with backslash)") + ) + .get_matches(); + let src_path = matches.value_of("source").unwrap(); + let target_path = matches.value_of("target").unwrap(); + println!("src_path = {}\ntarget_path = {}", src_path, target_path); + let block_file = Arc::new(BlockFile(Mutex::new({ + let f = OpenOptions::new() + .read(true) + .write(true) + .create(true) + .open(format!("{}{}", target_path, "fs.img"))?; + f.set_len(8192 * 512).unwrap(); + f + }))); + // 4MiB, at most 4095 files + let efs = EasyFileSystem::create( + block_file.clone(), + 8192, + 1, + ); + let root_inode = Arc::new(EasyFileSystem::root_inode(&efs)); + let apps: Vec<_> = read_dir(src_path) + .unwrap() + .into_iter() + .map(|dir_entry| { + let mut name_with_ext = dir_entry.unwrap().file_name().into_string().unwrap(); + name_with_ext.drain(name_with_ext.find('.').unwrap()..name_with_ext.len()); + name_with_ext + }) + .collect(); + for app in apps { + // load app data from host file system + let mut host_file = File::open(format!("{}{}", target_path, app)).unwrap(); + let mut all_data: Vec = Vec::new(); + host_file.read_to_end(&mut all_data).unwrap(); + // create a file in easy-fs + let inode = root_inode.create(app.as_str()).unwrap(); + // write data to easy-fs + inode.write_at(0, all_data.as_slice()); + } + // list apps + for app in root_inode.ls() { + println!("{}", app); + } + Ok(()) + } + +- 为了实现 ``easy-fs-fuse`` 和 ``os/user`` 的解耦，第 6~21 行使用 ``clap`` crate 进行命令行参数解析，需要通过 ``-s`` 和 ``-t`` 分别指定应用的源代码目录和保存应用 ELF 的目录而不是在 ``easy-fs-fuse`` 中硬编码。如果解析成功的话它们会分别被保存在变量 ``src_path`` 和 ``target_path`` 中。 +- 第 23~38 行依次完成：创建 4MiB 的 easy-fs 镜像文件、进行 easy-fs 初始化、获取根目录 inode 。 +- 第 39 行获取源码目录中的每个应用的源代码文件并去掉后缀名，收集到向量 ``apps`` 中。 +- 第 48 行开始，枚举 ``apps`` 中的每个应用，从放置应用执行程序的目录中找到对应应用的 ELF 文件（这是一个 HostOS 上的文件）并将数据读入内存。接着需要在我们的 easy-fs 中创建一个同名文件并将 ELF 数据写入到这个文件中。这个过程相当于将 HostOS 上的文件系统中的一个文件复制到我们的 easy-fs 中。 + +尽管没有进行任何同步写回磁盘的操作，我们也不用担心块缓存中的修改没有写回磁盘。因为在 ``easy-fs-fuse`` 这个应用正常退出的过程中，块缓存因生命周期结束会被回收，届时如果 ``modified`` 标志为 true 就会将修改写回磁盘。 \ No newline at end of file diff --git a/guide/source/chapter6/3using-easy-fs-in-kernel.rst b/guide/source/chapter6/3using-easy-fs-in-kernel.rst new file mode 100644 index 0000000..b4c60d7 --- /dev/null +++ b/guide/source/chapter6/3using-easy-fs-in-kernel.rst @@ -0,0 +1,313 @@ +在内核中使用 easy-fs +=============================================== + +块设备驱动层 +----------------------------------------------- + +在 ``drivers`` 子模块中的 ``block/mod.rs`` 中，我们可以找到内核访问的块设备实例 ``BLOCK_DEVICE`` ： + +.. code-block:: rust + + // os/src/drivers/block/mod.rs + + type BlockDeviceImpl = virtio_blk::VirtIOBlock; + + lazy_static! { + pub static ref BLOCK_DEVICE: Arc = Arc::new(BlockDeviceImpl::new()); + } + +在 qemu 上，我们使用 ``VirtIOBlock`` 访问 VirtIO 块设备，并将它全局实例化为 ``BLOCK_DEVICE`` ，使内核的其他模块可以访问。 + +在启动 Qemu 模拟器的时候，我们可以配置参数来添加一块 VirtIO 块设备： + +.. code-block:: makefile + :linenos: + :emphasize-lines: 11-12 + + # os/Makefile + + FS_IMG := ../user/target/$(TARGET)/$(MODE)/fs.img + + run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) \ + -drive file=$(FS_IMG),if=none,format=raw,id=x0 \ + -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 + +- 第 11 行，我们为虚拟机添加一块虚拟硬盘，内容为我们之前通过 ``easy-fs-fuse`` 工具打包的包含应用 ELF 的 easy-fs 镜像，并命名为 ``x0`` 。 +- 第 12 行，我们将硬盘 ``x0`` 作为一个 VirtIO 总线中的一个块设备接入到虚拟机系统中。 ``virtio-mmio-bus.0`` 表示 VirtIO 总线通过 MMIO 进行控制，且该块设备在总线中的编号为 0 。 + +**内存映射 I/O** (MMIO, Memory-Mapped I/O) 指通过特定的物理内存地址来访问外设的设备寄存器。查阅资料，可知 VirtIO 总线的 MMIO 物理地址区间为从 0x10001000 开头的 4KiB 。 + +在 ``config`` 子模块中我们硬编码 Qemu 上的 VirtIO 总线的 MMIO 地址区间（起始地址，长度）。在创建内核地址空间的时候需要建立页表映射： + +.. code-block:: rust + + // os/src/config.rs + + pub const MMIO: &[(usize, usize)] = &[ + (0x10001000, 0x1000), + ]; + + // os/src/mm/memory_set.rs + + use crate::config::MMIO; + + impl MemorySet { + /// Without kernel stacks. + pub fn new_kernel() -> Self { + ... + println!("mapping memory-mapped registers"); + for pair in MMIO { + memory_set.push(MapArea::new( + (*pair).0.into(), + ((*pair).0 + (*pair).1).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), None); + } + memory_set + } + } + +这里我们进行的是透明的恒等映射，让内核可以兼容于直接访问物理地址的设备驱动库。 + +由于设备驱动的开发过程比较琐碎，我们这里直接使用已有的 `virtio-drivers `_ crate，感兴趣的同学可以自行了解。 + + +内核索引节点层 +----------------------------------------------- + +内核将 ``easy-fs`` 提供的 ``Inode`` 进一步封装为 OS 中的索引节点 ``OSInode`` 。 + +.. code-block:: rust + + // os/src/fs/inode.rs + + pub struct OSInode { + readable: bool, + writable: bool, + inner: UPSafeCell, + } + + pub struct OSInodeInner { + offset: usize, + inode: Arc, + } + +``OSInode`` 就表示进程中一个被打开的常规文件或目录。 ``readable/writable`` 分别表明该文件是否允许通过 ``sys_read/write`` 进行读写，读写过程中的偏移量 ``offset`` 和 ``Inode`` 则加上互斥锁丢到 ``OSInodeInner`` 中。 + +文件描述符层 +----------------------------------------------- + +``OSInode`` 也是要一种要放到进程文件描述符表中，通过 ``sys_read/write`` 进行读写的文件，我们需要为它实现 ``File`` Trait ： + +.. code-block:: rust + + // os/src/fs/inode.rs + + impl File for OSInode { + fn readable(&self) -> bool { self.readable } + fn writable(&self) -> bool { self.writable } + fn read(&self, mut buf: UserBuffer) -> usize { + let mut inner = self.inner.lock(); + let mut total_read_size = 0usize; + for slice in buf.buffers.iter_mut() { + let read_size = inner.inode.read_at(inner.offset, *slice); + if read_size == 0 { + break; + } + inner.offset += read_size; + total_read_size += read_size; + } + total_read_size + } + fn write(&self, buf: UserBuffer) -> usize { + let mut inner = self.inner.lock(); + let mut total_write_size = 0usize; + for slice in buf.buffers.iter() { + let write_size = inner.inode.write_at(inner.offset, *slice); + assert_eq!(write_size, slice.len()); + inner.offset += write_size; + total_write_size += write_size; + } + total_write_size + } + } + +``read/write`` 的实现也比较简单，只需遍历 ``UserBuffer`` 中的每个缓冲区片段，调用 ``Inode`` 写好的 ``read/write_at`` 接口就好了。注意 ``read/write_at`` 的起始位置是在 ``OSInode`` 中维护的 ``offset`` ，这个 ``offset`` 也随着遍历的进行被持续更新。在 ``read/write`` 的全程需要获取 ``OSInode`` 的互斥锁，保证两个进程无法同时访问同个文件。 + +本章我们为 ``File`` Trait 新增了 ``readable/writable`` 两个抽象接口，从而在 ``sys_read/sys_write`` 的时候进行简单的访问权限检查。 + +文件系统相关内核机制实现 +----------------------------------------------- + +文件系统初始化 ++++++++++++++++++++++++++++++++++++++++++++++++ + +为了使用 ``easy-fs`` 提供的抽象，内核需要进行一些初始化操作。我们需要从块设备 ``BLOCK_DEVICE`` 上打开文件系统，并从文件系统中获取根目录的 inode 。 + + +.. code-block:: rust + + // os/src/fs/inode.rs + + lazy_static! { + pub static ref ROOT_INODE: Arc = { + let efs = EasyFileSystem::open(BLOCK_DEVICE.clone()); + Arc::new(EasyFileSystem::root_inode(&efs)) + }; + } + +这之后就可以使用根目录的 inode ``ROOT_INODE`` ，在内核中调用 ``easy-fs`` 的相关接口了。例如，在文件系统初始化完毕之后，调用 ``list_apps`` 函数来打印所有可用应用的文件名： + +.. code-block:: rust + + // os/src/fs/inode.rs + + pub fn list_apps() { + println!("/**** APPS ****"); + for app in ROOT_INODE.ls() { + println!("{}", app); + } + println!("**************/") + } + + +通过 sys_open 打开文件 ++++++++++++++++++++++++++++++++++++++++++++++++ + +在内核中也定义一份打开文件的标志 ``OpenFlags`` ： + +.. code-block:: rust + + // os/src/fs/inode.rs + + bitflags! { + pub struct OpenFlags: u32 { + const RDONLY = 0; + const WRONLY = 1 << 0; + const RDWR = 1 << 1; + const CREATE = 1 << 9; + const TRUNC = 1 << 10; + } + } + + impl OpenFlags { + /// Do not check validity for simplicity + /// Return (readable, writable) + pub fn read_write(&self) -> (bool, bool) { + if self.is_empty() { + (true, false) + } else if self.contains(Self::WRONLY) { + (false, true) + } else { + (true, true) + } + } + } + +它的 ``read_write`` 方法可以根据标志的情况返回要打开的文件是否允许读写。简单起见，这里假设标志自身一定合法。 + +接着，我们实现 ``open_file`` 内核函数，可根据文件名打开一个根目录下的文件： + +.. code-block:: rust + + // os/src/fs/inode.rs + + pub fn open_file(name: &str, flags: OpenFlags) -> Option> { + let (readable, writable) = flags.read_write(); + if flags.contains(OpenFlags::CREATE) { + if let Some(inode) = ROOT_INODE.find(name) { + // clear size + inode.clear(); + Some(Arc::new(OSInode::new( + readable, + writable, + inode, + ))) + } else { + // create file + ROOT_INODE.create(name) + .map(|inode| { + Arc::new(OSInode::new( + readable, + writable, + inode, + )) + }) + } + } else { + ROOT_INODE.find(name) + .map(|inode| { + if flags.contains(OpenFlags::TRUNC) { + inode.clear(); + } + Arc::new(OSInode::new( + readable, + writable, + inode + )) + }) + } + } + +这里主要是实现了 ``OpenFlags`` 各标志位的语义。例如只有 ``flags`` 参数包含 `CREATE` 标志位才允许创建文件；而如果文件已经存在，则清空文件的内容。 + +在其基础上， ``sys_open`` 也就很容易实现了。 + +通过 sys_exec 加载并执行应用 ++++++++++++++++++++++++++++++++++++++++++++++++ + +有了文件系统支持后， ``sys_exec`` 所需的表示应用 ELF 格式数据改为从文件系统中获取： + +.. code-block:: rust + :linenos: + :emphasize-lines: 17-25 + + // os/src/syscall/process.rs + + pub fn sys_exec(path: *const u8, mut args: *const usize) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + let mut args_vec: Vec = Vec::new(); + loop { + let arg_str_ptr = *translated_ref(token, args); + if arg_str_ptr == 0 { + break; + } + args_vec.push(translated_str(token, arg_str_ptr as *const u8)); + unsafe { + args = args.add(1); + } + } + if let Some(app_inode) = open_file(path.as_str(), OpenFlags::RDONLY) { + let all_data = app_inode.read_all(); + let task = current_task().unwrap(); + let argc = args_vec.len(); + task.exec(all_data.as_slice(), args_vec); + argc as isize + } else { + -1 + } + +注意上面代码片段中的高亮部分。当执行获取应用的 ELF 数据的操作时，首先调用 ``open_file`` 函数，以只读的方式在内核中打开应用文件并获取它对应的 ``OSInode`` 。接下来可以通过 ``OSInode::read_all`` 将该文件的数据全部读到一个向量 ``all_data`` 中： + +之后，就可以从向量 ``all_data`` 中拿到应用中的 ELF 数据，当解析完毕并创建完应用地址空间后该向量将会被回收。 + +同样的，我们在内核中创建初始进程 ``initproc`` 也需要替换为基于文件系统的实现： + +.. code-block:: rust + + // os/src/task/mod.rs + + lazy_static! { + pub static ref INITPROC: Arc = Arc::new({ + let inode = open_file("ch6b_initproc", OpenFlags::RDONLY).unwrap(); + let v = inode.read_all(); + TaskControlBlock::new(v.as_slice()) + }); + } diff --git a/guide/source/chapter6/4exercise.rst b/guide/source/chapter6/4exercise.rst new file mode 100644 index 0000000..6b15015 --- /dev/null +++ b/guide/source/chapter6/4exercise.rst @@ -0,0 +1,114 @@ +chapter6练习 +================================================ + +编程作业 +------------------------------------------------- + +硬链接 +++++++++++++++++++++++++++++++++++++++++++++++++++ + +硬链接要求两个不同的目录项指向同一个文件，在我们的文件系统中也就是两个不同名称目录项指向同一个磁盘块。 + +本节要求实现三个系统调用 ``sys_linkat、sys_unlinkat、sys_stat`` 。 + +**linkat**： + + * syscall ID: 37 + * 功能：创建一个文件的一个硬链接， `linkat标准接口 `_ 。 + * Ｃ接口： ``int linkat(int olddirfd, char* oldpath, int newdirfd, char* newpath, unsigned int flags)`` + * Rust 接口： ``fn linkat(olddirfd: i32, oldpath: *const u8, newdirfd: i32, newpath: *const u8, flags: u32) -> i32`` + * 参数： + * olddirfd，newdirfd: 仅为了兼容性考虑，本次实验中始终为 AT_FDCWD (-100)，可以忽略。 + * flags: 仅为了兼容性考虑，本次实验中始终为 0，可以忽略。 + * oldpath：原有文件路径 + * newpath: 新的链接文件路径。 + * 说明： + * 为了方便，不考虑新文件路径已经存在的情况（属于未定义行为），除非链接同名文件。 + * 返回值：如果出现了错误则返回 -1，否则返回 0。 + * 可能的错误 + * 链接同名文件。 + +**unlinkat**: + + * syscall ID: 35 + * 功能：取消一个文件路径到文件的链接, `unlinkat标准接口 `_ 。 + * Ｃ接口： ``int unlinkat(int dirfd, char* path, unsigned int flags)`` + * Rust 接口： ``fn unlinkat(dirfd: i32, path: *const u8, flags: u32) -> i32`` + * 参数： + * dirfd: 仅为了兼容性考虑，本次实验中始终为 AT_FDCWD (-100)，可以忽略。 + * flags: 仅为了兼容性考虑，本次实验中始终为 0，可以忽略。 + * path：文件路径。 + * 说明： + * 注意考虑使用 unlink 彻底删除文件的情况，此时需要回收inode以及它对应的数据块。 + * 返回值：如果出现了错误则返回 -1，否则返回 0。 + * 可能的错误 + * 文件不存在。 + +**fstat**: + + * syscall ID: 80 + * 功能：获取文件状态。 + * Ｃ接口： ``int fstat(int fd, struct Stat* st)`` + * Rust 接口： ``fn fstat(fd: i32, st: *mut Stat) -> i32`` + * 参数： + * fd: 文件描述符 + * st: 文件状态结构体 + + .. code-block:: rust + + #[repr(C)] + #[derive(Debug)] + pub struct Stat { + /// 文件所在磁盘驱动器号，该实验中写死为 0 即可 + pub dev: u64, + /// inode 文件所在 inode 编号 + pub ino: u64, + /// 文件类型 + pub mode: StatMode, + /// 硬链接数量，初始为1 + pub nlink: u32, + /// 无需考虑，为了兼容性设计 + pad: [u64; 7], + } + + /// StatMode 定义： + bitflags! { + pub struct StatMode: u32 { + const NULL = 0; + /// directory + const DIR = 0o040000; + /// ordinary regular file + const FILE = 0o100000; + } + } + + +实验要求 ++++++++++++++++++++++++++++++++++++++++++++++ +- 实现分支：ch6。 +- 实验目录要求不变。 +- 通过所有测例。 + + 在 os 目录下 ``make run BASE=2`` 加载所有测例， ``ch6_usertest`` 打包了所有你需要通过的测例，你也可以通过修改这个文件调整本地测试的内容。 + + 你的内核必须前向兼容，能通过前一章的所有测例。 + +.. note:: + + **如何调试 easy-fs** + + 如果你在第一章练习题中已经借助 ``log`` crate 实现了日志功能，那么你可以直接在 ``easy-fs`` 中引入 ``log`` crate，通过 ``log::info!/debug!`` 等宏即可进行调试并在内核中看到日志输出。具体来说，在 ``easy-fs`` 中的修改是：在 ``easy-fs/Cargo.toml`` 的依赖中加入一行 ``log = "0.4.0"``，然后在 ``easy-fs/src/lib.rs`` 中加入一行 ``extern crate log`` 。 + + 你也可以完全在用户态进行调试。仿照 ``easy-fs-fuse`` 建立一个在当前操作系统中运行的应用程序，将测试逻辑写在 ``main`` 函数中。这个时候就可以将它引用的 ``easy-fs`` 的 ``no_std`` 去掉并使用 ``println!`` 进行调试。 + + +问答作业 +---------------------------------------------------------- + +1. 在我们的easy-fs中，root inode起着什么作用？如果root inode中的内容损坏了，会发生什么？ + +报告要求 +----------------------------------------------------------- +- 简单总结你实现的功能（200字以内，不要贴代码）。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter6/easy-fs-demo.png b/guide/source/chapter6/easy-fs-demo.png new file mode 100644 index 0000000000000000000000000000000000000000..9fd70d62f3bda18c3cf2dad08ab038555964fbed GIT binary patch literal 20644 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 literal 0 HcmV?d00001 diff --git a/guide/source/chapter6/index.rst b/guide/source/chapter6/index.rst new file mode 100644 index 0000000..92a5d7d --- /dev/null +++ b/guide/source/chapter6/index.rst @@ -0,0 +1,13 @@ +第六章：文件系统与I/O重定向 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 1file-descriptor.rst + 1fs-interface + 2fs-implementation-1 + 2fs-implementation-2 + 3using-easy-fs-in-kernel + 4exercise diff --git a/guide/source/chapter7/0intro.rst b/guide/source/chapter7/0intro.rst new file mode 100644 index 0000000..1a9299c --- /dev/null +++ b/guide/source/chapter7/0intro.rst @@ -0,0 +1,118 @@ +引言 +========================================= + +本章导读 +----------------------------------------- + +本章将基于文件描述符实现父子进程之间的通信机制——管道。 +我们还将扩展 ``exec`` 系统调用，使之能传递运行参数，并进一步改进 shell 程序，使其支持重定向符号 ``>`` 和 ``<`` 。 + +实践体验 +----------------------------------------- + +获取本章代码： + +.. code-block:: console + + $ git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S.git + $ cd rCore-Tutorial-Code-2022S + $ git checkout ch7 + +在 qemu 模拟器上运行本章代码： + +.. code-block:: console + + $ cd os + $ make run + +进入shell程序后，可以运行管道机制的简单测例 ``ch7b_pipetest``， ``ch7b_pipetest`` 需要保证父进程通过管道传输给子进程的字符串不会发生变化。 + +测例输出大致如下： + +.. code-block:: + + >> ch7b_pipetest + Read OK, child process exited! + pipetest passed! + Shell: Process 2 exited with code 0 + >> + +同样的，也可以运行较为复杂的测例 ``ch7b_pipe_large_test``，体验通过两个管道实现双向通信。 + +此外，在本章我们为shell程序支持了输入/输出重定向功能，可以将一个应用的输出保存到一个指定的文件。例如，下面的命令可以将 ``ch7b_yield`` 应用的输出保存在文件 ``fileb`` 当中，并在应用执行完毕之后确认它的输出： + +.. code-block:: + + >> ch7b_yield > fileb + Shell: Process 2 exited with code 0 + >> ch7b_cat fileb + Hello, I am process 2. + Back in process 2, iteration 0. + Back in process 2, iteration 1. + Back in process 2, iteration 2. + Back in process 2, iteration 3. + Back in process 2, iteration 4. + yield pass. + + Shell: Process 2 exited with code 0 + >> + +本章代码树 +----------------------------------------- + +.. code-block:: + + ── os +    └── src +    ├── ... +    ├── fs +    │   ├── inode.rs +    │   ├── mod.rs +    │   ├── pipe.rs(新增：实现了 File Trait 的第三个实现——可用来进程间通信的管道) +    │   └── stdio.rs +    ├── mm +    │   ├── address.rs +    │   ├── frame_allocator.rs +    │   ├── heap_allocator.rs +    │   ├── memory_set.rs +    │   ├── mod.rs +    │   └── page_table.rs +    ├── syscall +    │   ├── fs.rs(修改：添加了sys_pipe和sys_dup) +    │   ├── mod.rs +    │   └── process.rs(修改：sys_exec添加了对参数的支持) +    ├── task +       ├── context.rs +       ├── manager.rs +       ├── mod.rs +       ├── pid.rs +       ├── processor.rs +       ├── switch.rs +       ├── switch.S +       └── task.rs(修改：在exec中将参数压入用户栈中) + + cloc easy-fs os + ------------------------------------------------------------------------------- + Language files blank comment code + ------------------------------------------------------------------------------- + Rust 42 317 434 3574 + Assembly 4 53 26 526 + make 1 13 4 48 + TOML 2 4 2 23 + ------------------------------------------------------------------------------- + SUM: 49 387 466 4171 + ------------------------------------------------------------------------------- + + +.. 本章代码导读 +.. ----------------------------------------------------- + +.. 在本章第一节 :doc:`/chapter6/1file-descriptor` 中，我们引入了文件的概念，用它来代表进程可以读写的多种被内核管理的硬件/软件资源。进程必须通过系统调用打开一个文件，将文件加入到自身的文件描述符表中，才能通过文件描述符（也就是某个特定文件在自身文件描述符表中的下标）来读写该文件。 + +.. 文件的抽象 Trait ``File`` 声明在 ``os/src/fs/mod.rs`` 中，它提供了 ``read/write`` 两个接口，可以将数据写入应用缓冲区抽象 ``UserBuffer`` ，或者从应用缓冲区读取数据。应用缓冲区抽象类型 ``UserBuffer`` 来自 ``os/src/mm/page_table.rs`` 中，它将 ``translated_byte_buffer`` 得到的 ``Vec<&'static mut [u8]>`` 进一步包装，不仅保留了原有的分段读写能力，还可以将其转化为一个迭代器逐字节进行读写，这在读写一些流式设备的时候特别有用。 + +.. 在进程控制块 ``TaskControlBlock`` 中需要加入文件描述符表字段 ``fd_table`` ，可以看到它是一个向量，里面保存了若干实现了 ``File`` Trait 的文件，由于采用动态分发，文件的类型可能各不相同。 ``os/src/syscall/fs.rs`` 的 ``sys_read/write`` 两个读写文件的系统调用需要访问当前进程的文件描述符表，用应用传入内核的文件描述符来索引对应的已打开文件，并调用 ``File`` Trait 的 ``read/write`` 接口； ``sys_close`` 这可以关闭一个文件。调用 ``TaskControlBlock`` 的 ``alloc_fd`` 方法可以在文件描述符表中分配一个文件描述符。进程控制块的其他操作也需要考虑到新增的文件描述符表字段的影响，如 ``TaskControlBlock::new`` 的时候需要对 ``fd_table`` 进行初始化， ``TaskControlBlock::fork`` 中则需要将父进程的 ``fd_table`` 复制一份给子进程。 + +.. 到本章为止我们支持两种文件：标准输入输出和管道。不同于前面章节，我们将标准输入输出分别抽象成 ``Stdin`` 和 ``Stdout`` 两个类型，并为他们实现 ``File`` Trait 。在 ``TaskControlBlock::new`` 创建初始进程的时候，就默认打开了标准输入输出，并分别绑定到文件描述符 0 和 1 上面。 + +.. 管道 ``Pipe`` 是另一种文件，它可以用于父子进程间的单向进程间通信。我们也需要为它实现 ``File`` Trait 。 ``os/src/syscall/fs.rs`` 中的系统调用 ``sys_pipe`` 可以用来打开一个管道并返回读端/写端两个文件的文件描述符。管道的具体实现在 ``os/src/fs/pipe.rs`` 中，本章第二节 :doc:`/chapter6/2pipe` 中给出了详细的讲解。管道机制的测试用例可以参考 ``user/src/bin`` 目录下的 ``pipetest.rs`` 和 ``pipe_large_test.rs`` 两个文件。 diff --git a/guide/source/chapter7/1pipe.rst b/guide/source/chapter7/1pipe.rst new file mode 100644 index 0000000..29ab917 --- /dev/null +++ b/guide/source/chapter7/1pipe.rst @@ -0,0 +1,364 @@ +管道 +============================================ + +管道的系统调用原型及使用方法 +-------------------------------------------- + +新增为当前进程打开一个管道（包含一个只读文件，一个只写文件）的系统调用： + +.. code-block:: rust + + /// 功能：为当前进程打开一个管道。 + /// 参数：pipe 表示应用地址空间中的一个长度为 2 的 usize 数组的起始地址，内核需要按顺序将管道读端 + /// 和写端的文件描述符写入到数组中。 + /// 返回值：如果出现了错误则返回 -1，否则返回 0 。可能的错误原因是：传入的地址不合法。 + /// syscall ID：59 + pub fn sys_pipe(pipe: *mut usize) -> isize; + +用户库会将其包装为 ``pipe`` 函数： + +.. code-block:: rust + + // user/src/lib.rs + + pub fn pipe(pipe_fd: &mut [usize]) -> isize { sys_pipe(pipe_fd) } + +只有当一个管道的所有读端文件/写端文件都被关闭之后，管道占用的资源才会被回收。 + +.. code-block:: rust + + /// 功能：当前进程关闭一个文件。 + /// 参数：fd 表示要关闭的文件的文件描述符。 + /// 返回值：如果成功关闭则返回 0 ，否则返回 -1 。可能的出错原因：传入的文件描述符并不对应一个打开的文件。 + /// syscall ID：57 + pub fn sys_close(fd: usize) -> isize; + +它会在用户库中被包装为 ``close`` 函数。 + +我们从测例 ``ch7b_pipetest`` 中理解管道的使用方法： + +.. code-block:: rust + :linenos: + + // user/src/bin/ch7b_pipetest.rs + + #![no_std] + #![no_main] + + #[macro_use] + extern crate user_lib; + + use user_lib::{fork, close, pipe, read, write, wait}; + + static STR: &str = "Hello, world!"; + + #[no_mangle] + pub fn main() -> i32 { + // create pipe + let mut pipe_fd = [0usize; 2]; + pipe(&mut pipe_fd); + // read end + assert_eq!(pipe_fd[0], 3); + // write end + assert_eq!(pipe_fd[1], 4); + if fork() == 0 { + // child process, read from parent + // close write_end + close(pipe_fd[1]); + let mut buffer = [0u8; 32]; + let len_read = read(pipe_fd[0], &mut buffer) as usize; + // close read_end + close(pipe_fd[0]); + assert_eq!(core::str::from_utf8(&buffer[..len_read]).unwrap(), STR); + println!("Read OK, child process exited!"); + 0 + } else { + // parent process, write to child + // close read end + close(pipe_fd[0]); + assert_eq!(write(pipe_fd[1], STR.as_bytes()), STR.len() as isize); + // close write end + close(pipe_fd[1]); + let mut child_exit_code: i32 = 0; + wait(&mut child_exit_code); + assert_eq!(child_exit_code, 0); + println!("pipetest passed!"); + 0 + } + } + +在父进程中，我们通过 ``pipe`` 打开一个管道文件数组，其中 ``pipe_fd[0]`` 保存了管道读端的文件描述符，而 ``pipe_fd[1]`` 保存了管道写端的文件描述符。在 ``fork`` 之后，子进程会完全继承父进程的文件描述符表，于是子进程也可以通过同样的文件描述符来访问同一个管道的读端和写端。之前提到过管道是单向的，在这个测例中我们希望管道中的数据从父进程流向子进程，也即父进程仅通过管道的写端写入数据，而子进程仅通过管道的读端读取数据。 + +因此，在第 25 和第 34 行，分别第一时间在子进程中关闭管道的写端和在父进程中关闭管道的读端。父进程在第 35 行将字符串 ``STR`` 写入管道的写端，随后在第 37 行关闭管道的写端；子进程在第 27 行从管道的读端读取字符串，并在第 29 行关闭。 + +如果想在父子进程之间实现双向通信，我们就必须创建两个管道。有兴趣的读者可以参考测例 ``ch7b_pipe_large_test`` 。 + +通过 sys_close 关闭文件 +-------------------------------------------- + +关闭文件的系统调用 ``sys_close`` 实现非常简单，我们只需将进程控制块中的文件描述符表对应的一项改为 ``None`` 代表它已经空闲即可，同时这也会导致内层的引用计数类型 ``Arc`` 被销毁，会减少一个文件的引用计数，当引用计数减少到 0 之后，文件所占用的资源就会被自动回收。 + +.. code-block:: rust + + // os/src/syscall/fs.rs + + pub fn sys_close(fd: usize) -> isize { + let task = current_task().unwrap(); + let mut inner = task.acquire_inner_lock(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + inner.fd_table[fd].take(); + 0 + } + +基于文件的管道 +-------------------------------------------- + +我们将管道的一端（读端或写端）抽象为 ``Pipe`` 类型： + +.. code-block:: rust + + // os/src/fs/pipe.rs + + pub struct Pipe { + readable: bool, + writable: bool, + buffer: Arc>, + } + +``readable`` 和 ``writable`` 分别指出该管道端可否支持读取/写入，通过 ``buffer`` 字段还可以找到该管道端所在的管道自身。后续我们将为它实现 ``File`` Trait ，之后它便可以通过文件描述符来访问。 + +而管道自身，也就是那个带有一定大小缓冲区的字节队列，我们抽象为 ``PipeRingBuffer`` 类型： + +.. code-block:: rust + + // os/src/fs/pipe.rs + + const RING_BUFFER_SIZE: usize = 32; + + #[derive(Copy, Clone, PartialEq)] + enum RingBufferStatus { + FULL, + EMPTY, + NORMAL, + } + + pub struct PipeRingBuffer { + arr: [u8; RING_BUFFER_SIZE], + head: usize, + tail: usize, + status: RingBufferStatus, + write_end: Option>, + } + +- ``RingBufferStatus`` 记录了缓冲区目前的状态：``FULL`` 表示缓冲区已满不能再继续写入； ``EMPTY`` 表示缓冲区为空无法从里面读取；而 ``NORMAL`` 则表示除了 ``FULL`` 和 ``EMPTY`` 之外的其他状态。 +- ``PipeRingBuffer`` 的 ``arr/head/tail`` 三个字段用来维护一个循环队列，其中 ``arr`` 为存放数据的数组， ``head`` 为循环队列队头的下标， ``tail`` 为循环队列队尾的下标。 +- ``PipeRingBuffer`` 的 ``write_end`` 字段还保存了它的写端的一个弱引用计数，这是由于在某些情况下需要确认该管道所有的写端是否都已经被关闭了，通过这个字段很容易确认这一点。 + +从内存管理的角度，每个读端或写端中都保存着所属管道自身的强引用计数，且我们确保这些引用计数只会出现在管道端口 ``Pipe`` 结构体中。于是，一旦一个管道所有的读端和写端均被关闭，便会导致它们所属管道的引用计数变为 0 ，循环队列缓冲区所占用的资源被自动回收。虽然 ``PipeRingBuffer`` 中保存了一个指向写端的引用计数，但是它是一个弱引用，也就不会出现循环引用的情况导致内存泄露。 + +.. chyyuu 介绍弱引用??? + +管道创建 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +通过 ``PipeRingBuffer::new`` 可以创建一个新的管道： + +.. code-block:: rust + + // os/src/fs/pipe.rs + + impl PipeRingBuffer { + pub fn new() -> Self { + Self { + arr: [0; RING_BUFFER_SIZE], + head: 0, + tail: 0, + status: RingBufferStatus::EMPTY, + write_end: None, + } + } + } + +``Pipe`` 的 ``read/write_end_with_buffer`` 方法可以分别从一个已有的管道创建它的读端和写端： + +.. code-block:: rust + + // os/src/fs/pipe.rs + + impl Pipe { + pub fn read_end_with_buffer(buffer: Arc>) -> Self { + Self { + readable: true, + writable: false, + buffer, + } + } + pub fn write_end_with_buffer(buffer: Arc>) -> Self { + Self { + readable: false, + writable: true, + buffer, + } + } + } + +可以看到，读端和写端的访问权限进行了相应设置：不允许向读端写入，也不允许从写端读取。 + +通过 ``make_pipe`` 方法可以创建一个管道并返回它的读端和写端： + +.. code-block:: rust + + // os/src/fs/pipe.rs + + impl PipeRingBuffer { + pub fn set_write_end(&mut self, write_end: &Arc) { + self.write_end = Some(Arc::downgrade(write_end)); + } + } + + /// Return (read_end, write_end) + pub fn make_pipe() -> (Arc, Arc) { + let buffer = Arc::new(Mutex::new(PipeRingBuffer::new())); + let read_end = Arc::new( + Pipe::read_end_with_buffer(buffer.clone()) + ); + let write_end = Arc::new( + Pipe::write_end_with_buffer(buffer.clone()) + ); + buffer.lock().set_write_end(&write_end); + (read_end, write_end) + } + +注意，我们调用 ``PipeRingBuffer::set_write_end`` 在管道中保留它的写端的弱引用计数。 + +现在来实现创建管道的系统调用 ``sys_pipe`` ： + +.. code-block:: rust + :linenos: + + // os/src/task/task.rs + + impl TaskControlBlockInner { + pub fn alloc_fd(&mut self) -> usize { + if let Some(fd) = (0..self.fd_table.len()) + .find(|fd| self.fd_table[*fd].is_none()) { + fd + } else { + self.fd_table.push(None); + self.fd_table.len() - 1 + } + } + } + + // os/src/syscall/fs.rs + + pub fn sys_pipe(pipe: *mut usize) -> isize { + let task = current_task().unwrap(); + let token = current_user_token(); + let mut inner = task.acquire_inner_lock(); + let (pipe_read, pipe_write) = make_pipe(); + let read_fd = inner.alloc_fd(); + inner.fd_table[read_fd] = Some(pipe_read); + let write_fd = inner.alloc_fd(); + inner.fd_table[write_fd] = Some(pipe_write); + *translated_refmut(token, pipe) = read_fd; + *translated_refmut(token, unsafe { pipe.add(1) }) = write_fd; + 0 + } + +``TaskControlBlockInner::alloc_fd`` 可以在进程控制块中分配一个最小的空闲文件描述符来访问一个新打开的文件。它先从小到大遍历所有曾经被分配过的文件描述符尝试找到一个空闲的，如果没有的话就需要拓展文件描述符表的长度并新分配一个。 + +在 ``sys_pipe`` 中，第 21 行我们调用 ``make_pipe`` 创建一个管道并获取其读端和写端，第 22~25 行我们分别为读端和写端分配文件描述符并将它们放置在文件描述符表中的相应位置中。第 26~27 行我们则是将读端和写端的文件描述符写回到应用地址空间。 + +管道读写 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +首先来看如何为 ``Pipe`` 实现 ``File`` Trait 的 ``read`` 方法，即从管道的读端读取数据。在此之前，我们需要对于管道循环队列进行封装来让它更易于使用： + +.. code-block:: rust + :linenos: + + // os/src/fs/pipe.rs + + impl PipeRingBuffer { + pub fn read_byte(&mut self) -> u8 { + self.status = RingBufferStatus::NORMAL; + let c = self.arr[self.head]; + self.head = (self.head + 1) % RING_BUFFER_SIZE; + if self.head == self.tail { + self.status = RingBufferStatus::EMPTY; + } + c + } + pub fn available_read(&self) -> usize { + if self.status == RingBufferStatus::EMPTY { + 0 + } else { + if self.tail > self.head { + self.tail - self.head + } else { + self.tail + RING_BUFFER_SIZE - self.head + } + } + } + pub fn all_write_ends_closed(&self) -> bool { + self.write_end.as_ref().unwrap().upgrade().is_none() + } + } + +``PipeRingBuffer::read_byte`` 方法可以从管道中读取一个字节，注意在调用它之前需要确保管道缓冲区中不是空的。它会更新循环队列队头的位置，并比较队头和队尾是否相同，如果相同的话则说明管道的状态变为空 ``EMPTY`` 。仅仅通过比较队头和队尾是否相同不能确定循环队列是否为空，因为它既有可能表示队列为空，也有可能表示队列已满。因此我们需要在 ``read_byte`` 的同时进行状态更新。 + +``PipeRingBuffer::available_read`` 可以计算管道中还有多少个字符可以读取。我们首先需要需要判断队列是否为空，因为队头和队尾相等可能表示队列为空或队列已满，两种情况 ``available_read`` 的返回值截然不同。如果队列为空的话直接返回 0，否则根据队头和队尾的相对位置进行计算。 + +``PipeRingBuffer::all_write_ends_closed`` 可以判断管道的所有写端是否都被关闭了，这是通过尝试将管道中保存的写端的弱引用计数升级为强引用计数来实现的。如果升级失败的话，说明管道写端的强引用计数为 0 ，也就意味着管道所有写端都被关闭了，从而管道中的数据不会再得到补充，待管道中仅剩的数据被读取完毕之后，管道就可以被销毁了。 + +下面是 ``Pipe`` 的 ``read`` 方法的实现： + +.. code-block:: rust + :linenos: + + // os/src/fs/pipe.rs + + impl File for Pipe { + fn read(&self, buf: UserBuffer) -> usize { + assert_eq!(self.readable, true); + let mut buf_iter = buf.into_iter(); + let mut read_size = 0usize; + loop { + let mut ring_buffer = self.buffer.lock(); + let loop_read = ring_buffer.available_read(); + if loop_read == 0 { + if ring_buffer.all_write_ends_closed() { + return read_size; + } + drop(ring_buffer); + suspend_current_and_run_next(); + continue; + } + // read at most loop_read bytes + for _ in 0..loop_read { + if let Some(byte_ref) = buf_iter.next() { + unsafe { *byte_ref = ring_buffer.read_byte(); } + read_size += 1; + } else { + return read_size; + } + } + } + } + } + +- 第 6 行的 ``buf_iter`` 将传入的应用缓冲区 ``buf`` 转化为一个能够逐字节对于缓冲区进行访问的迭代器，每次调用 ``buf_iter.next()`` 即可按顺序取出用于访问缓冲区中一个字节的裸指针。 +- 第 7 行的 ``read_size`` 用来维护实际有多少字节从管道读入应用的缓冲区。 +- ``File::read`` 的语义是要从文件中最多读取应用缓冲区大小那么多字符。这可能超出了循环队列的大小，或者由于尚未有进程从管道的写端写入足够的字符，因此我们需要将整个读取的过程放在一个循环中，当循环队列中不存在足够字符的时候暂时进行任务切换，等待循环队列中的字符得到补充之后再继续读取。 + + 这个循环从第 8 行开始，第 10 行我们用 ``loop_read`` 来保存循环这一轮次中可以从管道循环队列中读取多少字符。如果管道为空则会检查管道的所有写端是否都已经被关闭，如果是的话，说明我们已经没有任何字符可以读取了，这时可以直接返回；否则我们需要等管道的字符得到填充之后再继续读取，因此我们调用 ``suspend_current_and_run_next`` 切换到其他任务，等到切换回来之后回到循环开头再看一下管道中是否有字符了。在调用之前我们需要手动释放管道自身的锁，因为切换任务时候的 ``__switch`` 并不是一个正常的函数调用。 + + 如果 ``loop_read`` 不为 0 ，在这一轮次中管道中就有 ``loop_read`` 个字节可以读取。我们可以迭代应用缓冲区中的每个字节指针并调用 ``PipeRingBuffer::read_byte`` 方法来从管道中进行读取。如果这 ``loop_read`` 个字节均被读取之后还没有填满应用缓冲区就需要进入循环的下一个轮次，否则就可以直接返回了。 + +``Pipe`` 的 ``write`` 方法——即通过管道的写端向管道中写入数据的实现和 ``read`` 的原理类似，篇幅所限在这里不再赘述，感兴趣的读者可自行查阅。 diff --git a/guide/source/chapter7/2cmdargs-and-redirection.rst b/guide/source/chapter7/2cmdargs-and-redirection.rst new file mode 100644 index 0000000..87ab705 --- /dev/null +++ b/guide/source/chapter7/2cmdargs-and-redirection.rst @@ -0,0 +1,337 @@ +命令行参数与标准 I/O 重定向 +================================================= + + +命令行参数 +------------------------------------------------- + +使用 C 语言开发 Linux 应用时，可以使用标准库提供的 ``argc/argv`` 来获取命令行参数，我们希望在我们自己的内核和shell程序上支持这个功能。为了支持命令行参数， ``sys_exec`` 的系统调用接口需要发生变化： + +.. code-block:: rust + + // user/src/syscall.rs + + pub fn sys_exec(path: &str, args: &[*const u8]) -> isize; + +可以看到，它的参数多出了一个 ``args`` 数组，数组中的每个元素都是命令行参数字符串的起始地址。实际传递给内核的实际上是这个数组的起始地址： + +.. code-block:: rust + + // user/src/syscall.rs + + pub fn sys_exec(path: &str, args: &[*const u8]) -> isize { + syscall(SYSCALL_EXEC, [path.as_ptr() as usize, args.as_ptr() as usize, 0]) + } + + // user/src/lib.rs + + pub fn exec(path: &str, args: &[*const u8]) -> isize { sys_exec(path, args) } + + +shell程序的命令行参数分割 ++++++++++++++++++++++++++++++++++++++++++++++++++ + +回忆一下，在shell程序 ``user_shell`` 中，一旦接收到一个回车，我们就会将当前行的内容 ``line`` 作为一个名字并试图去执行同名的应用。但是现在 ``line`` 还可能包含一些命令行参数，只有最开头的一个才是要执行的应用名。因此我们要做的第一件事情就是将 ``line`` 用空格分割： + +.. code-block:: rust + + // user/src/bin/ch6b_user_shell.rs + + let args: Vec<_> = line.as_str().split(' ').collect(); + let mut args_copy: Vec = args + .iter() + .map(|&arg| { + let mut string = String::new(); + string.push_str(arg); + string + }) + .collect(); + + args_copy + .iter_mut() + .for_each(|string| { + string.push('\0'); + }); + +经过分割， ``args`` 中的 ``&str`` 都是 ``line`` 中的一段子区间，它们的结尾并没有包含 ``\0`` ，因为 ``line`` 是我们输入得到的，中间本来就没有 ``\0`` 。由于在向内核传入字符串的时候，我们只能传入字符串的起始地址，因此我们必须保证其结尾为 ``\0`` 。从而我们用 ``args_copy`` 将 ``args`` 中的字符串拷贝一份到堆上并在末尾手动加入 ``\0`` 。这样就可以安心的将 ``args_copy`` 中的字符串传入内核了。我们用 ``args_addr`` 来收集这些字符串的起始地址： + +.. code-block:: rust + + // user/src/bin/ch6b_user_shell.rs + + let mut args_addr: Vec<*const u8> = args_copy + .iter() + .map(|arg| arg.as_ptr()) + .collect(); + args_addr.push(0 as *const u8); + +向量 ``args_addr`` 中的每个元素都代表一个命令行参数字符串的起始地址。为了让内核能够获取到命令行参数的个数，我们在 ``args_addr`` 的末尾放入一个 0 ，这样内核看到它时就能知道命令行参数已经获取完毕了。 + +在 ``fork`` 出来的子进程中，我们调用 ``exec`` 传入命令行参数。 + +sys_exec 将命令行参数压入用户栈 ++++++++++++++++++++++++++++++++++++++++++++++++++ + +在 ``sys_exec`` 中，首先需要将应用传进来的命令行参数取出来： + +.. code-block:: rust + :linenos: + :emphasize-lines: 6-14,19 + + // os/src/syscall/process.rs + + pub fn sys_exec(path: *const u8, mut args: *const usize) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + let mut args_vec: Vec = Vec::new(); + loop { + let arg_str_ptr = *translated_ref(token, args); + if arg_str_ptr == 0 { + break; + } + args_vec.push(translated_str(token, arg_str_ptr as *const u8)); + unsafe { args = args.add(1); } + } + if let Some(app_inode) = open_file(path.as_str(), OpenFlags::RDONLY) { + let all_data = app_inode.read_all(); + let task = current_task().unwrap(); + let argc = args_vec.len(); + task.exec(all_data.as_slice(), args_vec); + // return argc because cx.x[10] will be covered with it later + argc as isize + } else { + -1 + } + } + +每次我们都可以从一个起始地址通过 ``translated_str`` 拿到一个字符串，直到 ``args`` 为 0 就说明没有更多命令行参数了。在第 19 行调用 ``TaskControlBlock::exec`` 的时候，我们需要将获取到的 ``args_vec`` 传入进去并将里面的字符串压入到用户栈上。 + +.. code-block:: rust + :linenos: + :emphasize-lines: 11-34,45,50,51 + + // os/src/task/task.rs + + impl TaskControlBlock { + pub fn exec(&self, elf_data: &[u8], args: Vec) { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, mut user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // push arguments on user stack + user_sp -= (args.len() + 1) * core::mem::size_of::(); + let argv_base = user_sp; + let mut argv: Vec<_> = (0..=args.len()) + .map(|arg| { + translated_refmut( + memory_set.token(), + (argv_base + arg * core::mem::size_of::()) as *mut usize + ) + }) + .collect(); + *argv[args.len()] = 0; + for i in 0..args.len() { + user_sp -= args[i].len() + 1; + *argv[i] = user_sp; + let mut p = user_sp; + for c in args[i].as_bytes() { + *translated_refmut(memory_set.token(), p as *mut u8) = *c; + p += 1; + } + *translated_refmut(memory_set.token(), p as *mut u8) = 0; + } + // make the user_sp aligned to 8B + user_sp -= user_sp % core::mem::size_of::(); + + // **** access current TCB exclusively + let mut inner = self.inner_exclusive_access(); + // substitute memory_set + inner.memory_set = memory_set; + // update trap_cx ppn + inner.trap_cx_ppn = trap_cx_ppn; + // initialize trap_cx + let mut trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + self.kernel_stack.get_top(), + trap_handler as usize, + ); + trap_cx.x[10] = args.len(); + trap_cx.x[11] = argv_base; + *inner.get_trap_cx() = trap_cx; + // **** release current PCB + } + } + +第 11-34 行所做的主要工作是将命令行参数以某种格式压入用户栈。具体的格式可以参考下图（比如应用传入了两个命令行参数 ``aa`` 和 ``bb`` ）： + +.. image:: user-stack-cmdargs.png + :align: center + +- 首先需要在用户栈上分配一个字符串指针数组，也就是蓝色区域。数组中的每个元素都指向一个用户栈更低处的命令行参数字符串的起始地址。在第 12~24 行可以看到，最开始我们只是分配空间，具体的值要等到字符串被放到用户栈上之后才能确定更新。 +- 第 23~32 行，我们逐个将传入的 ``args`` 中的字符串压入到用户栈中，对应于图中的橙色区域。为了实现方便，我们在用户栈上预留空间之后逐字节进行复制。注意 ``args`` 中的字符串是通过 ``translated_str`` 从应用地址空间取出的，它的末尾不包含 ``\0`` 。为了应用能知道每个字符串的长度，我们需要手动在末尾加入 ``\0`` 。 +- 第 34 行将 ``user_sp`` 以 8 字节对齐，在 Qemu 平台上其实可以忽略这一步。 + +我们还需要对应修改 Trap 上下文。首先是第 45 行，我们的 ``user_sp`` 相比之前已经发生了变化，它上面已经压入了命令行参数。同时，我们还需要修改 Trap 上下文中的 ``a0/a1`` 寄存器，让 ``a0`` 表示命令行参数的个数，而 ``a1`` 则表示图中 ``argv_base`` 即蓝色区域的起始地址。这两个参数在第一次进入对应应用的用户态的时候会被接收并用于还原命令行参数。 + +用户库从用户栈上还原命令行参数 ++++++++++++++++++++++++++++++++++++++++++++++++++ + +在应用第一次进入用户态的时候，我们放在 Trap 上下文 a0/a1 两个寄存器中的内容可以被用户库中的入口函数以参数的形式接收： + +.. code-block:: rust + :linenos: + :emphasize-lines: 10-24 + + // user/src/lib.rs + + #[no_mangle] + #[link_section = ".text.entry"] + pub extern "C" fn _start(argc: usize, argv: usize) -> ! { + unsafe { // 初始化堆分配器 + HEAP.lock() + .init(HEAP_SPACE.as_ptr() as usize, USER_HEAP_SIZE); + } + let mut v: Vec<&'static str> = Vec::new(); + for i in 0..argc { + let str_start = unsafe { + ((argv + i * core::mem::size_of::()) as *const usize).read_volatile() + }; + let len = (0usize..).find(|i| unsafe { + ((str_start + *i) as *const u8).read_volatile() == 0 + }).unwrap(); + v.push( + core::str::from_utf8(unsafe { + core::slice::from_raw_parts(str_start as *const u8, len) + }).unwrap() + ); + } + exit(main(argc, v.as_slice())); + } + +可以看到，在入口 ``_start`` 中我们就接收到了命令行参数个数 ``argc`` 和字符串数组的起始地址 ``argv`` 。但是这个起始地址不太好用，我们希望能够将其转化为编写应用的时候看到的 ``&[&str]`` 的形式。转化的主体在第 10~23 行，就是分别取出 ``argc`` 个字符串的起始地址（基于字符串数组的 base 地址 ``argv`` ），从它向后找到第一个 ``\0`` 就可以得到一个完整的 ``&str`` 格式的命令行参数字符串并加入到向量 ``v`` 中。最后通过 ``v.as_slice`` 就得到了我们在 ``main`` 主函数中看到的 ``&[&str]`` 。 + +有了命令行参数支持，我们就可以编写命令行工具 ``ch6b_cat`` 来输出指定文件的内容了。读者可以自行参阅其实现。 + +标准输入输出重定向 +------------------------------------------------- + +为了增强 shell 程序使用文件系统时的灵活性，我们需要新增标准输入输出重定向功能。 + +重定向功能对于应用来说是透明的。在应用中除非明确指出了数据要从指定的文件输入或者输出到指定的文件，否则数据默认都是输入自进程文件描述表位置 0 处的标准输入，并输出到进程文件描述符表位置 1 处的标准输出。 + +为了对应用进程的文件描述符表进行某种替换，引入一个新的系统调用 ``sys_dup`` ： + +.. code-block:: rust + + // user/src/syscall.rs + + /// 功能：将进程中一个已经打开的文件复制一份并分配到一个新的文件描述符中。 + /// 参数：fd 表示进程中一个已经打开的文件的文件描述符。 + /// 返回值：如果出现了错误则返回 -1，否则能够访问已打开文件的新文件描述符。 + /// 可能的错误原因是：传入的 fd 并不对应一个合法的已打开文件。 + /// syscall ID：24 + pub fn sys_dup(fd: usize) -> isize; + +这个系统调用的实现非常简单： + +.. code-block:: rust + + // os/src/syscall/fs.rs + + pub fn sys_dup(fd: usize) -> isize { + let task = current_task().unwrap(); + let mut inner = task.acquire_inner_lock(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + let new_fd = inner.alloc_fd(); + inner.fd_table[new_fd] = Some(Arc::clone(inner.fd_table[fd].as_ref().unwrap())); + new_fd as isize + } + +在 ``sys_dup`` 函数中，首先检查传入 ``fd`` 的合法性。然后在文件描述符表中分配一个新的文件描述符，并保存 ``fd`` 指向的已打开文件的一份拷贝即可。 + +在shell程序 ``user_shell`` 分割命令行参数的时候，我们要检查是否存在通过 ``<`` 或 ``>`` 进行输入输出重定向的情况，如果存在的话则需要将它们从命令行参数中移除，并记录匹配到的输入文件名或输出文件名到字符串 ``input`` 或 ``output`` 中。注意，为了实现方便，我们这里假设输入shell程序的命令一定合法：即 ``<`` 或 ``>`` 最多只会出现一次，且后面总是会有一个参数作为重定向到的文件。 + +.. code-block:: rust + + // user/src/bin/ch6b_user_shell.rs + + // redirect input + let mut input = String::new(); + if let Some((idx, _)) = args_copy + .iter() + .enumerate() + .find(|(_, arg)| arg.as_str() == "<\0") { + input = args_copy[idx + 1].clone(); + args_copy.drain(idx..=idx + 1); + } + + // redirect output + let mut output = String::new(); + if let Some((idx, _)) = args_copy + .iter() + .enumerate() + .find(|(_, arg)| arg.as_str() == ">\0") { + output = args_copy[idx + 1].clone(); + args_copy.drain(idx..=idx + 1); + } + +打开文件和替换的过程则发生在 ``fork`` 之后的子进程分支中： + +.. code-block:: rust + :linenos: + + // user/src/bin/user_shell.rs + + let pid = fork(); + if pid == 0 { + // input redirection + if !input.is_empty() { + let input_fd = open(input.as_str(), OpenFlags::RDONLY); + if input_fd == -1 { + println!("Error when opening file {}", input); + return -4; + } + let input_fd = input_fd as usize; + close(0); + assert_eq!(dup(input_fd), 0); + close(input_fd); + } + // output redirection + if !output.is_empty() { + let output_fd = open( + output.as_str(), + OpenFlags::CREATE | OpenFlags::WRONLY + ); + if output_fd == -1 { + println!("Error when opening file {}", output); + return -4; + } + let output_fd = output_fd as usize; + close(1); + assert_eq!(dup(output_fd), 1); + close(output_fd); + } + // child process + if exec(args_copy[0].as_str(), args_addr.as_slice()) == -1 { + println!("Error when executing!"); + return -4; + } + unreachable!(); + } else { + let mut exit_code: i32 = 0; + let exit_pid = waitpid(pid as usize, &mut exit_code); + assert_eq!(pid, exit_pid); + println!("Shell: Process {} exited with code {}", pid, exit_code); + } + +- 输入重定向发生在第 6~16 行。我们尝试打开输入文件 ``input`` 到 ``input_fd`` 中。之后，首先通过 ``close`` 关闭标准输入所在的文件描述符 0 。之后通过 ``dup`` 来分配一个新的文件描述符来访问 ``input_fd`` 对应的输入文件。这里用到了文件描述符分配的重要性质：即必定分配可用描述符中编号最小的一个。由于我们刚刚关闭了描述符 0 ，那么在 ``dup`` 的时候一定会将它分配出去，于是现在应用进程的文件描述符 0 就对应到输入文件了。最后，因为应用进程的后续执行不会用到输入文件原来的描述符 ``input_fd`` ，所以就将其关掉。 +- 输出重定向则发生在 18~31 行。它的原理和输入重定向几乎完全一致，只是通过 ``open`` 打开文件的标志不太相同 diff --git a/guide/source/chapter7/3exercise.rst b/guide/source/chapter7/3exercise.rst new file mode 100644 index 0000000..fc6ff3f --- /dev/null +++ b/guide/source/chapter7/3exercise.rst @@ -0,0 +1,20 @@ +chapter7练习 +=========================================== + +编程作业 +------------------------------------------- + +本章无编程作业 + +问答作业 +------------------------------------------- + +(1) 举出使用 pipe 的一个实际应用的例子。 + +(2) 如果需要在多个进程间互相通信，则需要为每一对进程建立一个管道，非常繁琐，请设计一个更易用的多进程通信机制。 + +报告要求 +--------------------------------------- + +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter7/index.rst b/guide/source/chapter7/index.rst new file mode 100644 index 0000000..692cf6d --- /dev/null +++ b/guide/source/chapter7/index.rst @@ -0,0 +1,10 @@ +第七章：进程间通信 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 1pipe + 2cmdargs-and-redirection + 3exercise diff --git a/guide/source/chapter7/user-stack-cmdargs.png b/guide/source/chapter7/user-stack-cmdargs.png new file mode 100644 index 0000000000000000000000000000000000000000..b707600a66d8a6dc5840d82806367f7e94a11553 GIT binary patch literal 16759 zcmeIacT`i|*De|h7C@zj@(L)@2_T?Sq=*ozh!i2zD2O6Oq}K#2C=ehPqzH(BG!bHe z1f(PuAWEbPgpLLg1OkQ@NC=!Aec#_X=brD}@0@SkGw%JyxPN41?47mOT6?Xz=6vQe z=S{XM~I!-Sx{By;h(_8?rTQY zMj#Lt&9ix#3%K5Y)7&`(1Om%)K07SzWPX7_M!Xg#Mh=l4w7kGq-gE90dG*xddpX%> zng(va>3Gq*^MF%sB-AGwm!N(k%j2xxH)xJgiuMb&DoZPkBX!I|4FQc-QSBCy1d%Jl zawYGy4_Jm;n!bK3EAc=CdN}z(RvWLx4QszQ`^Xy$F@#cL)I!a`R>%Ny&1H_UAv5t= zXD({MrOP9xbFn7>8m*@5%|Q_8k_jIV2$aI@xdRk$YXkv-jw>Ysvp40!fJA zf}KJ=!@^XZFdq6tOA3sIF;^Tzcvii&&}#;EjUUxELtoP`u^#k>%$^>=f#SVue6aQL zmVAi%3zXznEk(4aW4TY%Tcooi@da@az$?5pFoGN!sZ*(Lyy=J?CC0_!h#4;+neGYq zVW3O-M>6iyM!-Yv+7+-gG}?)A>+V%mUB{>iAA4X;<^@}pUN<{lp)?CxY9`j7xM(%1 z1`b)ALzAneAc(pOrFR^f#jsbxqEtcy5V3XF zV-3t`!#mzqb0+e{i|{s5z?hM|vL3;6G1E>Hsd0gsE50jZgN(J| zzjofcG0$+92YuY{88ukd$Bl%)TS<8iJkprhx;QTWp7ruqP9&x@{qEwB!W3-N@k*Z7 zcpcWf{~jP15-2bVb$KIANiZ;;^xhxBCm~PGHi6fk5T3AuK$3#XA(lrL1iScAu`&y; z;MH}OQuJmtWVQ&?eAm&^jPk)MMjW%&6ST704JljH-ErnTSQ%{9YI`fCEU|G=St-j_ zRp3n2c1w%XFGLcT_FC$+?NPMX%^eX1X(QyRf~DQ1rpw z&>LNrLK0+wSMH_3uRsq_&@R|o0#BTdGQZMW)mogl8YsT_4h(OCX_HM|%7gKD?E{4P z%5JQGQs&)zErrEu9WKm;R1gRv)>6HTaIH`l8)<} z)doXwt(L*AZ`wjk?S{Pl|16SMVYVgQXjCg2idjxOdIIQXIBe+WE8Zk1tg!CJnC?)u zB(RF2(MUdC!Qr21F>%%;2Prs9`+Q)?!_*OJ+;mwA12x&Zky-^Eg>S2cs!&&Z zblORmWI(H{lVY=iwV`~=2;_O z*_KT1QXY5bcn9rTeefRP!vP^dn&8A_horiSeH$><_c>H-x|ayp%mg8vr^#&sZ;W)| zHYIhhxg1Sf7w=M<|+r0P#)7i?D9g#+IT-9AjK zpuf>_gwhN=cZ`*R@>VMKB~b-U2aOZ7seTtufuP@=nO{&JM z`m9XN&yjgr#hC4q_k*?hXCN<}Az*v%J=i7_c#nY6-EkXCvY+Ai@i_N(L^JypY+tgZ zv5sFdZ(dE{o9ktKIgtl^S8y>gv|%$QGwSnH^FE80;Re_wSo^f)iUbBt*fO3@^dGkI zH+U%)4=c&DgS6c?f~cuGj5<7bh~M-bWmBKBySI$jBfXAfN4~M>p-ffWP!H`Skkq}g zGaK}fNm;#s3w!P~!c%<+ zi7sB;+l=vf(n6KUywMa#8#JD;?$SL07Lh52SQ<~y#|VB%Z_hRh{mpfUEjoueLVLP0Bu$?(d- zXuWGjt+tp9E4Pni>d%mYj89DNYyxF%iJ1xz$(QSpSddQh2rFrU(%VK}1MI#S1!eewClTA@7q z5%TS_$uf)px<*Cy(WAU;R!qtxg@hj=FUJCOiQdkgjwwmR|-W=igb{SmntchLF~`&1eah2U^ZP<-+PE zBj2isKn*vC!KkL>TRgSMUl;GXL4<|5XwwG#0rsx*7&dul;n`^_)ytQ+@i}`Xi%Jhg z22@CVL7eEUM@up;6xheDR&<0)=XmTY2=FEjhgGg>MsK;jWfdY)uLz9DKm^f6h)vkZ zlBJC$?Xa!&$S~f;X@uwY(qRN;bnm*fN_PU02$jlODj_ ze?P~#fWEyBZqb0d9ltLC4+ugVv)xg9s_VOu96<7m~=8!tKJfD~||=2XCDm1Kb|RsChai0u%G4|DtO^zRsUFJ||<-JXzY{)U;$} zlVE3hJG;^C_p6glq=R76=(v7Y#~Pt2^0Ua<&_+TP?R4f5Fo0|__J8l~LFcy{YbcJ$ zir2+WM#Qaq(?a%pa$rsN85u!T5q`ATTcghEtT)RI@WcRgBlkcd!=;hBrq#4M*1x8+ z`}cyMJ2H}3jCVNoPq#0GP!mT>>Lggt00%Gr4d*F42t5Y%ViTG6XKMt_6~R{_pySv0 z$h+;5i-G+Eh3vqdI|4X?8Gv>;gXiZ7)Y=nYeupz47-=K``f(7rU8wDA#5@20d6~V_nv`%(>k)Z` zu$|dZxBZsXSj5<}WVjn{`i;e;#nrGfwYFmznugn~vB1%oZ{M?b$LoAZNjQOemao>d zEh7(Ay&!Tvz_Wma&B~o4ps| z?7yz5;I=rO@S$Ev7ntv{l?JA!BizBEaPUZeiw|hcV8A(9V6M)U1~A1zgnhvL@cbx~ z=g6m6pC1B@%GE^_Bl`~QL`^r$Z|4J*Ehs6W89_rJwq8uqd39(ok*eZyv0w~kl$-x#|;VEO?1bY3lryw{@Osi=7n}Sd2kh_|L2|=dz%Sl?*tY`a@?hZ@kvkfX&NvTx zeNzbxKdpOp)Xc7Y?88mqEn5p=X96SV8l{G+^j6dIb;scFOd7yA7tWOE`Y{Bgr=?bwsJTZz%u*j2sH@`XFLN6treRR0V9nR7Victjf zn2}OOgn6u|)ke|-TI}TR!0sjEGvCYX9YZC(611Y#N8gE0n_}1UUJF%KBfp_}NwEfx zjkKE#U60kJ0A!iX$jN)df9>mI%=TBHSNiMwh;B=}L~|TGZTT-AO~2HRCr~ALFuR3D zWCZJ4v)d-&s~P?Hr!u3C$=*IX{yt*oj36IIn`0QYgB8DAj|?y5FqsW6Yye&?bi#C` zuf&UTA&0xE8x|^Qab{!{Lx|9GWY1xJ8y_6e8%Ykfh3|)!udbeoM?AEI7~9_JJCr9- zhfyBBf#P!P?Z(?lCU@EURjAyDMm>2Slp&Kb9XDshkT6^!k2Q|R)t%lNn)qqJq}xPv z#Vr{z8uPc@ek%|I)*F#Vj!uzp)-r1y&`ilPDBmaiwL0#cwUTt_ZOc$q+>;t!a@k@Q zvgpjlfRB`ofVxMaGI}cLD0on-C~+!D{uzvYKkux^#$ZJSv_mm)lp??arZrsBQb??T z`I0Yt7*up1bHlt2TaMNZjEgL4;$ff77B(>p`Xu5|^D?3XR2Fag@YNJYHyk9?3Kv(Z$B(=i!cnl=h*Uycb-u{Ar+H$X@`o@p%E!l~g%|dFJ z9ktS_Fo!bsosw*$H?O|m#zSZ$AkUq1Uj_CD@y;VH(FM4{gFGG^T|^Zg#l z*YaSVF#$RqHN2@t=Hj?1b->y2-8pAGy|STaN}H&g-+Nr{dP{ZHdfU*sQG!)Z+TvC( zC8tUGGd(zK_xA|w0hK$7jVV1ztbt(`6;Yy^5f;oxVAz3It=GaDnHlT%ni6Dh^|u^7 z#gD4yd3x0OnLsLZ?`yT*MA=T5Lm!)U!@8N7uiIgV5uQop%g@Gm zfvyvar8?~N1_(}b9;cKt%Las320c#W@#WSe3if_7^8xHsc38meDZ9r<-e$evM`?tj zTcK{iqPo<|ideL~f8--`K<&+H5;Wct`nVa{j&x_`)p>*!TOeRuHV0ySh z;(18ME$(osj0~pFo-g;&!kLXHB+;MHN5^Z_X9ZhJ2sq?3BaT#+w-lD~F&Srt_Cs5> z!J~t5PS};!X)yuRwUg})-p9GHyhVj`F$d@jn8T%u>-~-_S>u4^$rN)_@U1mk&i?&* zT_n+`0g>TF=G?l-!%nfh;x)s*z+rPCXWOluHK2%jgKFvx% zG4t0-GoFMrMhjo^=d=3YV?nNw?XdJkgzxvvR#p1ma2{f4B*#aVvMS$j_%B^JaY;#&KbO(J@YMElrXq);f{}c zJdbufGJ-^BW?WTl2vU8+VF({w1s(zcDE;z(a+Lmm8ms9W!XxQ64cp5bh6@YCUuI*A zNapew=j4x>8E*YtSf4<=jG?gNnptU5%&CQqiRhb4DLdaDHUbb z|LL9iH@!}tkHtk&ivW?#sBT)YcB)`Ud=i~L^V=ci*$22oinn0k2e6gZuu7Y3ju$oN zg(hx=64i9JpFWWp-)ydX$tFh{{#X2EtKi*-PjVZT!h+81{{x1uD%o;BN?dBIYp#oF zRVIew*vf>3>{)_3T@<(G^2hVrS)B?a%qNvbPaS=;uI=qA#xRC}EC_SHIa|sUz zZY~@mz6yj4M|*D%mySm<+s7HQ?FgaOe)Tb@>6oQ#Dd$xRL+RH-1byVq>t)#6v-QXT!EsDBk2LY$0 ziPb5Cp8{Y^u`wAs8NFFCUM-GlLj&;=Ub`e{f_=h;+lnL14L_OXig_>fsxRfQhVncxCf%uHeRaz6n>gqXR`apssbN@^v3q#Y3&r z<+%Qg4~0#Z-?Zo2L?@Br_pd@8Wpq}Ei2^fL_fZ9}hS?6A{rfN>C5ZTxj~djD*Dxmi z_tcSbGMn4yjaF{_CVhDK0+Kr+6j0!9taS|r162Z8PP01>8i^J8FPUlHRD-ga+U zkyzOq6HrLws8>+a;galrIr63UQ(h}6sfbkv>p3u%o8mUtpJ|D}-B#eJ|znqr& zLFNb%6#!tgp{ps+te-3*?PCo-Rr)JWE*}Mh6fAVSY=c%8@A$|)zrC1!TYxbFh5V0p zbRyVeuy4E%clRP{vkcaJnsTL3e$mi5#j)JDF@LFnH+mjCI=p#Oj}BTofY- zJHs;7;08n7L%(@3tAjvTJOTFT&TpdhFc44QihoBv-m%EkAOLC@3ky_eRpSJ zjW!}b@h;cs_m6!o(gk{q(U7r?<>^Lcr>b24j(31p;J8@W5c;$CC7-g0nupuiX4*_l zK!g-01a4n^Lp0;#*TV?ng zmT-OYl_b31kHVeh?-d{llV{z)Rt#l$N5xx4o(*dzcEl5_pld3FZymbbRvdtIYa6lR zkJ{r@xctPkXVq?E=_$-)O7z=2lh;9sBZ2Aq0MgB0Y#) zI5(7%9BA_X%UZxS<@ZYuzWdg9QzX5T&==E2Je?zWyH?uS3Fu~&-sLQ45_H>Q>udg& zutv|!2EW#gQ5eEqZbUyrJSWk6Ul)w(ed}%%N_!b@3?rfe)@M@jX zPco`O55o}p6s|TdY)Y;aV#KMcjsBV97U?`f+*p%8zkO_bxRJp0rdio+>~iCl%YixU zyU2I(5?g6}=psb*g{}t;dA4$W;6)Jur|$nA@MuzS;T;c}a*GYlS7JH^S^aJEAv7lJ zk`^ENV-zjHuu=T}ZhJq&?RLW&-)*yrl}H>ys%InDnA>_9bNSsB0Tg!`cL8^i2f}ry zaYA?3H(ePeHDN`jOKU?D=~9#1ciE%pfXt!fK?ewZ{9fDhWo2FBHMhAm*_HZG$f`XR zxBTYb+I_ka8*sgUrb-A{ZN{~h010%-SG)l1stg)2d$CLs~MO`@_N}( z=wj+6DotL*mhsKH)ITumR00c6xhI!hJEt_mYzW`7#`1>disQ6+XIubtL9}l1Tp1)2 zJTxlY{RX8Hy<5s|`td4l;liP}FGx+@nTWy;m!<%LbeGx|#}S*T1(i5@?S$@r+G+7! zD+A9Y)+Ow~=O*T_3U02a2Onm7)D$coUVwYXP`T63;HSox`b-o8T!)3t-4fc7u1V>Ex{i3vBg(`#8j^*q7Xi|U(ipwDa2uw zvi0=3IiGE08;Np?44q^I!xZ_tuEfT=?}Cyjc!J-~#yc=m%UrRQF?bOEO_Ee*wJ!o; zV+IfsLW_+z&Z!gzy|pU4+3?YFk5aNy8g^g9*Ye1QUrNBv;Y>$~YB;Bb_ceF49}jY+ zTB9wzden>NA!!2oruh@>S{2JdP5yu{t4pgWTJh_YPBAn_eKnP<^C0lXs=q8J*uv9w z#KqLong;;$a7c#u6!!6cyXn z>{t)T|*;qC@tZL1@g^IX;`!&E)?UL=3yLaPdre_bYsRq{k zUW*3KC-=3X!(dn{tA!e2P7Ag%(v(Lhy|Lrk*^tRCIbk?Vng3^2g;Zsxq_oN z|25`xA&0PcP(E=go*wv98NoPXiH(#Z@57!k(cC-cm88XbQt;OZ$mdf7`Yq3Ao5#|2wFhCzM6qg48e2c~{b8fH+O>WEC;BK&G4{XP! zjUyRJEey+*z)E+`ba#VOah8A6@fJ-MhWEWI-Tx-}g}O|C{5pvF`x1zyal!?FwoT*$ z5+FDsBu<3jXa}eDYi;a<>w7^Nhcy5Bz4-EGI5jLzFs}Sh=c!b9{5(tVb&VXdY0F`& z4I%d1K=&$aeFP(Ttt#2C==3M$or%A3tJR&d?#7wLxk(yglh7rebM}M*kd2X8Y*c$< z>OB!XWU`r~V!!pmEAib(cvnh z;Tazbk4mp{>xBonQ#vgyMe5!=?WDySy`AwY106DTpFsu>OpPYe8hD~*D5tp&ew znpURICg^o6Cpa-x6;=*}T>ie^Eif^3F~(2b>N4oKJP`d5hzs!mxWS-P_V^A(al=3R z)*^;N4)sW}3bRoLuAc+7p3O~$oIw7WpI8H_aAJ@_!6BvvQl&VnkbNOk4N9!=Ofpy4 zVuJ%K{x$gj7G$`@ar{!hFJ;GVQ5w6N7CXkIwgxo;qW+iu*!0#1R-@roGu$w0&yGv` zk9!^MD4d?Qfp4B=l;+13u;R8^5e*{Sq&V8vA}!wyx8rT_8OVW2^i{eU{t8Mm=D?pj zsZ>LK$eX_5uBYoG8}@9$w%_tpY`gO9k$ApAN$~)3V12#a;hM>x`$i5k?klU;TX6>0 zQqgMf`i4vSQZe_24|Z_q=Q#?7k!A~Uk#&ucbm~uB)zs1yd5lh{f06|07(osc7AuN8 zLwuH_PK5M4a;@wVDx~*c7&-bTYWZr!xA!83M$!BBe`IsA39DC&X>@G?-ZPFsnqd(U zN6lGd5s1~8Nwjb(78veU%X6`h#a5Y)(%tLKHqjuW0yqR9x4(pU-0ZxahMDw{eDE|+l!6*(b#Y{5wo z1)~rYJ)Rmvj%!_&%^0Z*JhV_D^}af*Low*ntCXw9PQGa&8tBO6E1Gz{D!?0SX22H4 z8Y70017fIawuxLn+FrFR&DV5QA-h)sX`;T$s3A9jYo}a>A04k{0~UxLsu=Jx@Ywi? zXx@{3;XZ8u|0G72MBVs7iqQu03FTGPlFTPacr;?(3+=Bg*fpmm(V`_hGwSkam$p!i z5Xzq0bfn$$ROY%Gbl?Vo)dlu*e&wHIzar{eM(fVK2obnjEUj4f)oiqcrE{|Hs@Qe7 z1PdURD`-roiPHx7t$wL_;ZsgkZqDqt>DWsvVa}g39u#k1 z_r(1ya$n(BW0r{^zM~A7#j;AD32k#Xi7vi&{2tPecU#t8DZ$(A&Um<08AKb#U2Ggr z1=Hy#P&>4DceF08e6hhW7auK8cVUp1e1lw_KmSNyYD1{t*gphPiESd!w(G`t3^&pi z-m#u77%Yzy*IqADi2m@YMVS=e z$P{srGk#A|Q;>A4%gJ|xC)-jN-rd<-vFOKj{UAM<($Ke-XLVvr+?TZ(XYgz+rC9Ee zlo^zm`^H?)_wl6^rjM)69G|gg(xilCKnjR;74MmJR(;q5T%#jHsHs>Rpz>N>2HZ^S zzB&qW*F+7kl^MW<1DH*gU;(oufGNLnxKVIR{yu zV$nIT13$Xzy6mi270gM5?#L3a5g^MO(34(XNI`xCHt+twsY`$fpFZK0+)BfVp#opc z<+&2%?Hh;G?zK>5Pb9Duj-Ld?F>L1kE6CN5Pu==pb{m1n2^;%t{*faqz4P#QjFDR> zU3+*-4xwaKBPn^ArVpdfo8&aH)Lk0b^(tMY9xhcv5B zhSms9xKR+INqhdZh(@m1sxSd_6^b%=50#oK#LG^0?fY^d{1exupMOxid?1r&Olq^H zwBdiyos;OWxXlIa~&2-PW2UoJ)w?Ds5D@FIArObb#W6M_~s9C->Wf?u9 zAda2qpFD(epkr{#0(W`Xdx^`QI2*CmWdmH_)_H=U;WhufyK54uJ2>Wp11E!bz_m1g z*LE;5{-a{hQq;3Y1`)K1VU{ZXegzAmk82M4VjR%qbI z(5qYvT^MyRKmYkIk*ub#tZ=>dY zmhOM$;Nq{pFaLWi_1o|MZ=e>Cgqj@=EGoy|{=qilZGrM03@v&lzytvqF93$(`bg;7 zb=r?gnzNY-9L@X(a-scuNUwQu48#j^Lu8!yOHJw21DrWt=M#<=VH41Gh83{bO?O5h z{~siEolnL3%`ZlWT&Hx#x|VCnrUgk{iX)`e(=&_1tP*xN`$Jrl{qm`9EI&_GP#R$ z?!`^4>{T}rHAyvzQyiaG5^i+^XJDV$wwLqZybh6#2-Iu7ZWtOj1@WY_pCHDFV#Ah=H?Nm514TDYsS_=qh-WaX#L3}?ZHRLzGwN{r89u(yhRzYTj9yIOG`D)5ED^C%=)a_?`Q{IDekGJyIH`R@Wc2xK;5+*J~y@I4XeE9Q_KNcQ!s zGC}3;Y?WHTXDGSYxYf_t{soWw@RQyLXKje;Rt*cK4v`$F_1mp#v2(s_#a;?bml0}E zZS!IK`ALKyJ*zHh?YF2)nkHO?_9wV=5eIAn5T5i$*)shUo9TzVgsH{tsf!S_9VG5& zMHeQm$bjj=S_isD7sQ2~W1yz{)TwWPRPEMDAE{I$TE+!8ZU?DWDxJ};8hD{w9Z;n& zL{J_DjXtw6h{{5bwU8XvYHP3ps~_*WuNYR_j6tu}9qIc)0D$e+NfV=tnqv}X6Mo^} z4RovU8!@Dvkh;LXBzA!^Y@)GcuYC8$#WiPL~E!_og$(C>05*P zaGDF?Hzsfrlg0r5(+1ypXg}1m#|v;Me|#EU7*zY{XRilgE{0 zQ!A}#*_U&+9)dXchLzs@hgHqu6lG`O{(7Rv(96J$8`7)&k1XdaklyM8jH$@buCs_q zd_Z>;TRS&$fe zbsylRE8P$d`HpIFA0`{+ov|R1TgDb>}DUAUTDOy{# zC+Dp>EdHAVHG_-CLjRU{IynpkE7uVzN(3{c_Hn_NhBQr7;b zDxv;?QZ(<>D@Bda^CBDSEq1*TsqPaTrdU`?cZQwVbZQ z+AiE*AP*|B+Sp9z6eRRGt=#p9s!-T?Qp38QMCPR#-bHKeQ7ZG;X}1zaL$-D6uq5wG z67dY-ZSx5_32deFh5o4Mnk7@W(AbLcZ%-a&S~YXpcRhA0EJt^8 zOHKDUr>j>n$ZEDEs>+P^)Lazsm75J9A|g`45TFQQv5-@Q;BX~uzWNAIhp;n=%O$cg znW4)}n~(>qO|CY#)-?@0tUv77*}a+TqCMp``+;Nv*=u400;;+4&3aZZcaO3=0b^;%Lf{@j3*1M9_w4YSTY#oW4f;)b%6y_6(*6xL_MJe(hY?$@SXa;BMs&x)m^ZBOtmC7vwrg0=ej zVs^h4_-vB#NI$&w9G82K4i1rXyWzkyYxD4DDnH>?g+foe%ERk^Zf1B-D90G$kKU7f z3@u&GSReIW_WBj(=xYbgxNnzZy&=AmRNgYVn4@nE(5FD@S(K3QX)@H-=nEdk=M`kH zp3djyAS_%CYdJPtf**vl=Ct{REhXe7?Y#!MXr&|}bm_96D=llGD5wpwQcn&tb=&mQ zl(3CCM=%{OZIYAKt%H7Lv#LT`Sbg8Ue%=WF;t}b5V@CHJP=*VPc1wVrKRC6Wz}>V~ zVR3o?4A;Hy@&z3aIZ42$kK1he#wg6zsEkL5Y$g)|2Q;qz*cx27*c*@Yx%a&IRlzG) zxtBqJ8c@;y`2;b6KnI~{S}<=&fc+VD?}3~6E5%r0XLQ%sZ+uygJ!rD~fk=y;5%uP+uy>SGU7~&9BrQr&sEPj< z3V+ugAfTfX)yfX_m#Rq5>@iSUPv$CQQ(f=-dD6YU5RtsIS~A@3f8l=D69ch(psH7? zejkO|*qsr8T=f{=zEH4cFeQ*t{6&8MDkbO`5@M`*7)Sa3Ehs%e(#(2~aiG>f&}hl> zY>>GnvtdAr6Z}_#3E*xoI{ln_)rwj7ddJ}Xzy(XtFGSqqe%)4J@Q|>~({;0bSrmTX z4&t%!$i%Wx&vLXRC^};oC?3Y`26-ZmpdtIEcnA}pWNY1N8Be&e+`*MuJY7PT`+ef_ ziI5-BvBTr?6$U_I@l^OX(rK9t!ZJ`{%V%{9Rcz-~)|~s(NAByCnh2uHN9N$_;)j~V zf^@sHK!F1nAK94tsPBPx%Y_&qc~c`xcG6oZ-)uXB;g)hu)_C$_<99(|JAb#UJvSvC zcvN93HS(M6OBeN2^5t2l@xAnp5UaLcMLHs#5T0+A6d5yd?jt#<_)L@jxRi#m)*6s$ z(PyrfF+Bg4?Wf6I_k?_*jeJ>Y0MI_?j7g$OZQyP`UnhrkYal2329K>`YaywerW@E4 zScFl@8wQGJfTxdwMMywmP%a^pf8<2b>mzQ@`zfB?L_|GW09Bi)nQEXOg|{1-@M&bF zL&qLnI04pIUG1Srx++S1>PI^T_ZaA=5hR~-mFEwKB6ffPk@qZrWu+(~>?-Uj;s)hv zu-Vs^P~WtDxzAC#_kF^!?Payh523MLKDl&%jxKE&-f||M@=z{QIXB_&b4PyI1F=G^D3b=G{&+|Rz; zYxj%ZdmFvAi_xAJzxIDy?@F@Z5a=LKATS^xAS572P^nGLpdcU~@E{;)ATVG$qV{$! zW_B(Hs-6yJ&Uy?UwgBQH2r%jb5U|hw|M&QBJOh*IdW!u_=wX-guSl}?2($&HxKLPr zx=+HS?*Z)u1?$c7I>_%`7I?_y`=WuX*%aUTFTL}U-E3A)*1D>;`8!Bu7P5(}N5!&LB)NX$4?amlCuq)KNF z%)*zOUsK_MRBKcs;L@H5wMR|xNp-kF`*NT%{K(&R5WXoi5(?TNWv;|P$uoy~f}mfr z)M6MLp1^<#(Mx2ihK$b~@Z?DwlVMENA|j!=#pnICo@dmb1-CZ&492?kg(2W4EQFr< zCaWxSwDmZX@q`dg~K zeI5D@+g1fz?fZlZ^*fZ) zp6*}NGm841U-2IK2VRr1Drj+Id%3!w_;ggo&bqS0&fl|zR8+DLKM*eLKMnQc0~|!@ zKY6?5qe~(9r?>BYI`fxLZ#Qr<12{7>{B{1nUjEur@#gy;VQMCcj@G|{a3No37mZ_z5oFR+&#h!_Dc#PRbsa>U-A}ZvlTFkKKj87vm zG75-fxrxx!NP=^)v~x8g!gIZ^Ek|%tYxVDND?a2cpWF*)UDX$SXL%*_jylUC?Z0Dd z4U4s*$De%Tbn#UnS!eYWJ^WK_6q7IEbi{r68FfXw}&yL#j4Kp8c-JW?NaVZ?(rYMJ+(B7^wMY+^~P{xAIy z-@o!Ght{O$3(}u@(pMDeq9K$a{`hIFpwhI^p68u6?%qUtDzlgp44^d?XOlZ<)R4Nt z+tir6rAl6{lp0HHPA96z+OW-B;7z=wh1uarOkwvd*VC$;)_Fs*AE4PTD;W*6yH|`l zm2;>LK-3mli^33$m{;{<{GHmZ={Qa*E`a#m2z8L8F4?&e3^k_np#LTQX~Xf1JPLZ* z&z^sAtCQym1@-nC9yPpcLh)-W47FonMT2#2!Ccl)CO#Vs7ukC`!TI9tW3=K4 zNM@U}=BDECW*2N`i#^w)?RP)}4zLbujJ`}A>&l;WIM|9{O{gKzVBBk67N*-hyL8;>EEX#6}VGBBx zx!{48&#QYqv(`mC&#IzN-1xs4G2AmbvP>1mLIaZ26Dq$5*LdM0L4~^?8qGcOXE9}E zg-8k@pifX8Ke-@F2tY+0pxyg8Fb!S9louO=ih~P9=CiHE2f$-|q5ci}YqQA8}Hf697u|Mk4yK`?Q+$X(qvwy6&V368| zE(5qzW1xBQy0X5`9@kEp0tb7so!GfwO^|)CZMfYQa83L8m)467s>)gSX}O%GARrk3 zv|eX`m8qFCsW(=5F zHK}5rw8b9;(g*!QEYyy}0`Le14D_yIeYqNA+Lc6^rRNX(7%c^A(k&;Pn}5wF0Jt3B z%1R7AyvhE`zrJ?YXK0u+(^kJF6~sx7zw$^qOg843nNb`T^dKbTCscDyQcSKIT}ZyJ zY{K(#~Weqep7U`0+pnLS%C9FU->r?EzwrLfoh%}7C%S{g zw?((k2Uc(1jTFA^zaA33zukSj-bTc9MEU41`KB_AKaD*~I?DN?4B-#eg>&6=-;miU z$z{fsM}d$3inp~Uji)kOXS;RR7ziD;(QC?39514oK8>dwDmpv!8x^`l-bTRInIihi z7?JS{0@luFkW4g@>J7P`_zEUg>OAvmMDL4G?u+d$y5ttPyJB}^<1&47V|E6nh}5zR zNS~%`MXg)rT!z)weMmuw(Rj@tNvBS_%IAe9&6xA)u^)0&t_#a!6siqf%{@bTHBkV8 z*dwiF{8dWX;3|AQ%C)h_KRGU$25qzxJ@iIzPLln_90$rDS9R3}W>(qz3xD8wc1sDU zd2eJX(S%fa&4F4h@*4|a0|o|4`9-uaEKTnD!gH0K9q?{PTjmQ}J8VyDI89qL%~+tg(?AaKB_(1Wfo%) z)VuNX>x`gIOUKfQSjAK)E`Igc@oCcfst!2cHomX2^=uL8=B^}b<(wmhA<9O^Q*fc$z{Twxkea1o=&2gum1St$HbSjN7;G z&C+2r?ml#696j?S^t73b&MJ*iM7|qA8&5J5jjbXhTen!ThfWkR^ELQJ(*%V}z#Z7} zjnSRiTP4rn9rlU!dmB>N$pPjYM`^XC;VF`!g$+KuCZG%> zQW&Q66N~;eW*8Qm$}lHjjn;57Enp5DgDEIUNcfBxXV^`>-(qxtN2Hqt{T)S^nLi-_ zB?D$S+wlM*28~If_s2sZB*9LbqU&AJ3ZUc?*^CJ!lSln5-T#60rJD%$9` zm=H1PgEP^oA727P4H<9;BC)BAb0Qo`50m4ul1&&Z7g!We*+8m5e)DV_$l0MGc1exb zGNi!__M)y|xa3WpX~-+N5UJ)O`&nEEzC>7;>oL*po*r904@7%rstX|wc8hgtu+{V@ z?!4X^bUk(0Z@(@W#EmM6CSB0Nk%R`x7w`>gp_9*Zb{U!t@Sh5_~_yw?)7lF;I|*-VZaY zBA1;|oY*s7V_Rv~$sTZ5kEfgn`-U~!E5GAD(wd<7Jr*K|vuCLYv4L&uWq7-6h*&Ep z?bg)P#y=Fug_+UkA4dWB=@AV)N8X@^#1wkXpPI4QcF|t9-ay&rQ{J)E$ey7D@cto8 zB=9CJh*z&#Kvv2zU9)0&0$vm)*OTSzBq)BFnTa0LSfXak!*qQaizdwwwlC3dhOj$U z;Qz|7VE169J=OCYspzEhy(r_zbt(6%%s^lD&O%yXstSK~vX(9ytC1~JpZ^VzMz?Up zWZcm>Q+Ud;5=XEBeeCTpD(9IsmEPrL{2+PY*v=(i2t9GBklk6>e8vKqQr&zjZF?O9 z^AmVop~e5bXQbhPW`_TdcQ9Dz5M@WbTk0Msde_Ix2rbXH0QUW=O?(SRswA+hs=J|1 zm{{~}K1fmOT*rhEq!0PQGK3E{Jn`}*;UoatFWsGPC-$Bc)Oj2rKFD)-P+!Riy{ID4 zQPJx$}B1s}FX^uSj~yRKwq{7_pIMw7j4 z9M(%zDjzdGRlptE2Vz1R9;lykF`|Y0xSD%wwem6cN4EEUjZ{`)xIipMN@IxQ==VE) z)0Xo+xP&{)Op(v}sMHVG5EH+=(yiRq44k&1^P%5X@j8>b_+INKTVlLr{O8zbB(K$) z`a>QUy*EnxT@dlAAg4$-W>v`HKjBNE(G#gnyZgZgf7|wqHKI-INziSytqufb2E7iL zp1DpUFnya6Li2%P`X)_oADl*z0S$5}c><=@RnS#9gLFq>n=d89&Q1+ui>|bbR>FOk zNJPs;AZZlvB&&ba;?P<8* z_kSNbGkCW)lZ`u8+EHT%EoM#zO)88-egJ9Wf%CX^r8d-!m%eO4amV8@UC>2P?+9#S z!JpE>i(6KC1x%>?%7R_k52pcb*;RXmu^xbPuYPnu;AZkletH7fQnyfS1r#secq6mg zJumUg{ctVf&9XlW>5&zL*YkJu=Zp*E84Cm_sYk@VLAQvo*(WiO3M?_MFH9E-hR?fFBN?|`AE8CR{cD-fN{DNnrDr9;;z2`!u_8iE|A*vK}L_e&Z|CVtO@L zA9q;@sTsLp+7t7yyYg|ks&^l9E?5#%U#4>*_xE0-9I(n#bPlmArSxwFdGRI} zp;8igV!GbAnX4XBP<)0N^${cCupnzG)&aUzzwUETR>D|+=73Fq-Tmh&*f+1!XnYCh^)sYnb%D-nTRgZl&3$BKj;nW32bgo=BN~PMyP1!(JI0TTDa9Vo zx7!cGxxz5Z5Vu(NFj3QfF0mX#q)g%{C1Q*r5{^6$q_)Y!GUXoUO!*@8`hiM49|YF5 zcwjbEJNwxis@Own)JN+*#pYCCowksfs5z1=3I@gb zO}iYa;>&!P=*XxCc5wo5R)fbl$OGDu*r7C3wTJ>*=>~h75?X?(aa!X@$iX1NLnm5D zkmbvWzuNbut15iS6rvxF&K~MJHk;*0k0yHFi9g^@+pI_7*=xd~z+Ouhad;m*i@+T)-P`)+ zISd8l79E}n5hxKCA}kEO-B#G=qV#=Do9?snuPt5Z`gTf}YfEldyD<=k`$gVI!B|cd z{UwW-&^bn~$}k?<5g(_{r6}BByB)z8Qzl5b(PE3REMO6D|5>kk<6B;S%_OL(C^DYi zTpp799O0gN+FF}seEQUkb7kjt9Ph=UXC}wn+BfmW6_mV7JZbO?vivLT>sjhwLn;ND zOojvo!P>}L{W?KmuCZ5Xt?WwaL(xsT+9ciF1Iwg($m1!NSUdvOz-4=l&U?CSj;6F! z#iWA=#_Y6!1|b-TsftpHh5O|@`ujPOtxrAgUx<2N+R^wxK1ID_2oMnB|GdQehraj! zF7*CZ`Z^aotOuCTp?14w-I*+EO?e{;WPZ_=A|I>HLnANO(^=~!q^R`xLY5+nTJxaC zw!eLh;J9%4omM;w5v8!h)2N69mbHrDjO|{$zSf14irGQrR|!M0LUFl0xQA=xc*w=~ zm+MliM8U!jV{eg_77{7n3RQ_FD?pvG$6K9HxOVy6It%+j+&CmZf6lHTQ8 zg!_-R3>0|zG`xuyM{?4X&sXq5Ix#Y{5QkW!NBLj24&uQ6;V?;#Rjy@T2gI1iDqEPS z+Qgg+;uxub89V|Q9Ru6e4Ro!gfsgXbrg*bak`md5G z9s@fx{O6O|&$%T6fdTzX-ucJ0{eMNC|0$D#eilPM2mJRws*;5j2AGh=AEY+>viKcU z3Pj2kIAJQjkVE_gq0A)5jI;HWBWWG6E+kjOa7{e;xPSG`s@FKXRA{94Qdx!>O+v@c znpYoZ1KW-ospK_8FR3VLfr9)aRX5GZsLoh!79qY!BS}|=jXE2)`G`x&w=F${fqSTuHBc z4i1yhKL}8u(6o_Oy^5lAhatq(G_TOBV+NerL8Ip39!co4M1|*5bFtD@2RWL;-8Mc5 zUBi7*P>1NF7gfadZgnNOo7u?&KQfbzDzDCtn+dA~VFaGTpZ>L8Sok%j)9ACfHo@^% zeeEB5;olx8Z{+M^=JZe9uB@L@Aa29{KxZN+JW|gjhx*_mDT9Z_1hj?l%>< zph9xp0v}BDp$(qk$J$$!-e552TTr+s_^?z|%Z^nX_sn{=I!eqyq`{_aBU50vQI?_) zV(U{m`{AxF}_(SE`7(O zr4}J3Q;g4Zh%_Ekk0CE%#MyNDt1mA;M^T@Ehx7`H<)baP(`xMPa2}C+7BAT%z;@GK zZCp*3PuDd5h6%me^zx2xW4guZDJY2RbDvrDk!2mVExmvH613UlTBkH&>QYaU6) zy!Xc;s_+>DpO4F<5rdCX14Q<62F?ObrI51oSm?+;hxWa>!ALeu^O0SX6b# zsbK`aguqsh!Tq{aD19+FzaW5qyc1vE zy)qPVi{`8jje04R-U%n`RMlwa%jT1+rXIFj9EjQ6cj0!ylY4LX+59&FgGfn53r#4c zS9T2c)U3>#zwYvK(fIj(m(|Az2*MiXD6sCfHBkh1x|Z<~NTiA%(28s5UfKE~hdXU& zJ|^zr!$6nI;i+v(6INmE16v4eRlL~59t0iJIFbY|7``xsQNN;WoJO1+^^~Gw~pGU@(o%zDlIlpMA0!W^0uw9mHQv@n%SW}`OD?-OSH<5tOzfX^m{Hze!US{-;s#5!|xan#>IA}a>7+!4@`Yz24rbe0 zqPyx%1-jxIC*VSv1{<+Dw@_nU0ht1ifBe>dJslJDzdjwCz|)L85GQ~FRwY!^w32wk zZ#L^ri7zf#&Tz1gux1=Gi&(8R=P;Z^Z%!lgXKxU9>e^YHbQtB8Ci01hd!=rpiU6`O z8|lr{xMVgKUDF1Z<}8tq?4PwvEJ6xu_F-OokgEF_n%pEbN9z)dNP^RdAdLEji>;|) z)sr$2l~IexRi(?5m?(^7jHzLn&bZ=|^c=!|u;C4``4yv=t9#DE(KVb9m3(_QR3cGM zPLa%v$XXnZ}9rO*t91drX43`)tFXNv^SO6 z=oU;^w;w{bOUP^FRng6{+qB<9wyP6-!TBzmq6qRmEv>Ql)>oQ86c8P}8v2qBRkuRs zZ}H+d)Jt(DGmh{!H8|yd5ZL`lov7M6%MKM3aNuH-1)=+AA~E@bjvA}ikhYv_arp>e zTf9Nqix5VQRqrmLFq3)mg;|t7>WD@z6+O`qaY3E2}T+##{>{#zj&hDtUWigUId9n z@lI(dc2k!&JM=p7I->ndpo0rHRpug}7!c;T#&;Spo`2K<;ntxTw2uMt6B&e@#Mm>9 z<2v_?yn4dDp%r1sZP`osl0!Rch2RvRVb{8xU;yjng6E;Pt1CQhE!#FN2fL4Z(*fPq z+ZME0ExNuW5$ev)ox@p3lnf{32DM2Se=F{-o=hw$}T&8M({a-$Yc3k%R{Lk zr|y0xNROR)XxQtbK-^o&)JRsl$89!nVV%FT)H_0xY zU&VGdRQehXcURc*8mIG4)fD^jS+)GHz`Hb;blv&MC7hoOOaCAFM9#?5-qpqVpY;1T zvi##GW~RT2M1SLN%uE+tKNB+amEILW{{>}ra0HtxN?)J&AJDj8>rflyzlx4Gvgd+= z_kG{qbsPQVi#=3~u{y)F)rm*54RbHqH)}?gFd;1dV2`H{I*Pd;O^g|I)Mrbv|T*ky8oA}rvHs;_?y=L51R%M zH?Fvs&xND#XKDLC(dz%ShW}s(Y=74ZHFfMa#nAmE_XIT$J&k9E?zya0*7Wg6LQ6<5 zkQ}n5$(o9iKn;vtJNG)YTXs}DEnHVsc$G$%tj7c{l&_ zMZ7!5fMzgh=x3=&RC{Wac|{c)BQ7(uTzFA&XM<1a#dD)g7iopIANu@y&LoOXZJrD} zRt@vla;o4lz^nm}7{_r(xD@RL)VM!Kbtf>E_ZZQ73+EEh`S|2r!9!v+Dl(>>3?sYE4ND`r)TPc*#8`B&Aw<6Op0FaGi$pBc?TXrsjOsbwrs*G zoW{0ji8I_6QUcn@a?2x388oUIXseWdY3CAPh6kf`>X8*EH|4g8HwEjEy`k<=$cD(7 z*D96rB!cOqB4ah22n?tW+(<80%5`0-l&`r_mwRq> z97|jC!jBTx=MTYwlq9{c4Cq>ho-U$$V%9<4XM)s7vuRp;wLIIH8#dVAxs3h2weIcp z@+4>wPXxHI_0!tt*!JY|YS-h|>(JMtCj<|D%#6Qb#dPr_l|Fu`BVv-c!3Rc zP7gszav{J7Z*@+!3e~cwuN*6eS9$SlR>*$f-FEe()~NO(-EZfOrTb-{{CtcX!8=NC zB>)B-1BYfuuQ_nZ(RKG4AY>@%?h>5ii?C{T6KK;@(`6tlzq-Fe*{?I8s<*LBJR3RH z)eHlQ8Abq77|JF^Jp?6qwoIKLN+%=2sEvdEb3OnTCVoFzm2xstRB%fX4nSA|L!;Su z8e*_XE*#wCJ;wMNA4hd!wOZZ^@VQ>dpRs>qGAedcSUWb}v!YQ0{WxcPq!0rbsu+VT z1Y`cTR9)F(?FzBp^{y&Ec|7T5)YNQ>;VVPshb5cAbT1zAy=;W`&c=In!?6|2DX7i= z_Q&%n5Kx5k3ck2MXBDAqY7?MjhqjmAQQQssXW~Z(mlPsJFSGbqg$iofY$MwM*dV*B zP{Ba%p%z>Q=A3I>n4R^opA5}@IbPXj`+|9q1t(F@!}(z{>!@gv)yHj9d4&D|{RW5Y zFD1Oy1djk0IdILq8c@Z75H5~p{B!lqaT4xPdI4^N)*Apj-3=Y8e}BRHtj)1TDylMq zOu6tGP;qs+hdmk~j{#V2wH9L!vW1uGE>VEaOLT!e%UnT2VkLEk_V#AYQ(dHgBdq?C})aJiuh?)7Jr zh$n_WY&*LQ&K=O|c$Uc}w@XhL7xc@v1IfizhppPrpiilADUHOa$!0B!?UN&A%bKO4ziyXT-6mX5czugLyMh{- zW}TXKEjlpLF5h~7<~p00qmE57!jZozF{GEuH6_`<=GeZ}1uUX(ysaD-FC!d@?r0UkRl4gIu~tI4v^*zb);Z&x#pJ-yYVIRY7&%_BiY|;G9TQT=T@GifSP1l@g@MO< z0R;oS1TE=+`619CY?!ggS=Gxb=cH2=X8IL~Ha0=!Sj#Ad=$Q3gS&!o&LN98(6HT&~ zS%FH7AeVGf=WwqmX(g*DzQfoxWoQj7ueqg-zOx0VW+d5SviObJ z=fnu?2Tx4}$_&@daEUv%7JxoP&6u&(papLL3lnHe|B} zjnNQN>WNyCoy?<^%_RM^1L8Xy_iY0?-FjWpVf@T$h-xCO7mH8miC!ObR!@TeGAHdxRf?y5(){74H2v>rp5?D>H2Jx4^^@jD zE)zYVCv+7r>PHMJ?PxY^$Vw8#N_;_9c(d6bzj(WKZ2XP$D#dXB#QCyWT2)*)q;Ib7 z8?A=sfXjJGwN_>I@z|pQR*UJ(kITu`BgU8{P3*m*n1&|$e&+`2UAD<~<@N2b=tf~JZ~GqkY}4%j_F|fb5-Z@CZ@_385+L!EO&YI@PcGm~Kj13; zi{&9gIHCzEbRaa!FUZr-wU$fCBUI}14Cq(|&+dwl-5VSdc2iU(;P9bCo(=AcI{{S( z6PgoWbX8b=?k5-$9TkeF82stre3Y0=kkEXrGkf*GW0Wx?|dw3-2WDV)6Z60adMBE2Syj zDuUfC4qVOPr&tb`6oaXpc9_Gv=Zwd}yYDiQkevdX|G+d;R+}b3_}tQ4!69mxJxHL% zD7`;l5V5|;zN3LZb&GOkg+RO}+=_Ah0KXj!hzEs<|req%qc?kT(_~W2w6!Bzg zx(1fBL}#P4MN762Wo8oKkg1)1qpu}bO(p1nvroXMj+RzPEp)Fdzd*0%>gv+94SMSQ z?S{I9XP4(jB9g^mre9HpWU5?6ZdK;TQ-qAX`r%s^HEJUE%04i?vtjiR7o5eZ;dchT zQ)XHxtK|^I8s$Frt;96pW^51*3N)Qj?R{Ve37oLpvM1j6-FdfC4z28Sf8Mn>@8_4d zvA66-D)+pPm!&^H-vO5sGOZ_l#be1EbjLIxB&4q>I5o7OtjsEu* zNPZY8tWlwJ%)AYyr@aYkFbS7dy~?^ss{%=dR;LYiuIiEEiv;vxIbbNHL54+7Fo$V~~hZpL8ZXPynj~l2hsc5V3Hul^br?774zqbwm#mVPmoFf~49Wi3J zw@)1gWe0hy%v9I0Vt9XN3l1_J4VDnk28>^IOpa+x}!3wXFr zZerbj&TH}%SVt55l3UThs;>=T6ly95kOqqsal-3ca8bL(oT6T+xXoe1Sb}d)uZKuq zaOZGJ=QI+|MRCAV8%BOZ6RZ;8fk9j46DP7I$~ohKIcUoQwNA?vb<`cEk4!hrhn-+0@*m_0?~4DO-mD6E-1unA+f>L?Rx&BXk(Iq z{{^H6N%2WaMgDjr%Lx3J7LU-ZtL0+@G#%avkD6#Jn~5KJs^j9&*Sp^(RC5b>@jKpL z`woyt$c$O}^%5BRm1|D;vKqPzpon5@t-P2^Yb)%#HZ&qNChIk)%q>n4aSh_U=_a%@ zHM^uUr0*SY2e`FHz1=AZQKnmBP#=F1e%Q-%TUcgaK-2H<4G{0(J4GBDql2ZpAHZ)~ z9~;9&cYUt^UOvOte+6v->Jz`uCt_B8?qB|QL5=nApr*MMx5~{Ch?XdbI#c%<(u7mfNULcWsA1HK3i{QQYn33;3CoN>Lt3v}(pbw@ zi|9$*A!U88^ZDiDi;q)MeHJ@Wi4LGqV~fJy3?S zJtI=off3z8at%!`V=9fk%*p|A;EL(pnM$F8asb#J(=fo_-tvB4aNiUDrdI{~v)cIH zPtR5j%i5@iyF*FVs{f5wQ0s)y#k@#oQcToy+PA}A!iIOB=g7SUWqw-9+~?w^vVUY0 zF?G+4iBMvH>HPL zvXW)y0yE~k?#&YJn=ESwzth)p>#;GeOH3^;op`O5XX)FsQRec@>Vi`eu16++w6P?u z$#kh7LUsC1*6(5c)L{Kiw>S1{9Ks{J0o}|+^p7+sgKe|T{9W*yJ>va4-|O9WUl*Qa zyq)0F%h>?*izH_cK+VDGJ{eC{`-s6bOxTIb&aa(i+2<6LopC2PM$NvPDOy<}R%wxlR52b}^ixGK zxtqBhjdM)}7ZDXmM}~Hr_hFtXex(-i(UwJ^Uzgrq7AI;_qQETbmUmceN(u4J0JL%CFq1S#k$Nyw^ab};vgZ6Z)@1J80_Vj#JkHS(m z?=0PeoQY1i_ZR5A9Z>4Dq}A>uzHfQZm4xQ$Fa}0JhuhEime%(tP>c z4+Yr7Vy?E+*B**Ms@F)vEg~~zHO~(u)m~5sUs)nys+*8uhc?-@oP|c_kqTdJU`xJm zMWQJRDdUD+xUiC+R;(zvay9v%P*uYm@nc?LuybLj0{FB!sG<1e(Q?tfn> zFZ+u|v)Z3~sBc_6IlZ>y1^gXcoa4>_P4Q$OpY0n=owM?(L0sUzN;euFAD4kU7~+A5&OjngsPwwk88LCd>u?@@tuSJg zS7CCo&x#~8_;~9YS^3}!_A=iZO!~R+EaddZ9F-;`Tb}0j@6$AFAG|fzvY~ zVXNA5;Ca}u14;RR;HWCOFNnoTw%*nHuv?3CrHnYb2t^TG1-clmvQl8SNUf69SKka^cFJEk zI`XuZFxB#lZopOWu zZr+aCMML`qLy`G#*h}92Qfm@)=Gl62X)EcBlF_t8%Qiqq7UZQm0jk3tZMgO3*|X@V z3&~ak{twlqvTLWkmj-miZTY>@N8=(~MtBCwW_=wu2A(CnAtG^BS3E@3LdSv^Ypp-# z%e>MC`a?2{%NA!rbqG%z39j#6>NW?d)xee|J^ZjY}CMZsdRGG!nyNY&u z$_FaZ-%7=CvtS=Z@rl7Mj`_6|N)Q)n3zLcQkf0Ngvxdi6G`P}Q+mHUH-2)CDPC;0; zq}W1qw?`ht!;zujL+7~!(drp8F52iPOjUXdLZqkNP&c&wTwWQN5^VMNW%6+_IawLm)7O%5((V zqV4yOIQa5-+Kw!&miEND*Hrul)dCtMFzWWDXML91%?hlRP}zwhFijm~$;8v8dtRc5 zuoH}*qMCLAsZLoP)Q|=GpvL_!Yi@L^7fiqq8YSgWYoRJqY-o&|fpS!!&=3ZV7(6hS zAG6B3jY!=Xqs|nGZlx{CNJTSJt#=+yeT7@?3&+>0K^ns~Ld~$b)tK0zR82^_T0@G% z$CTKB&-ThYm5l|hHk9f>hX5Z~cOB}7{2WABE-tS9TtXyQ| zajh2Th+P70ag1G}0ETVySW3aDxx$N0YpU|v)&*yfx&1}XFFCVCu0<%Z1fvM|T5Lu5 zXmihZD#0JZq0o}*(OwOS1_EzRM<zz55GNDJ(Ael_;FuM zJM!>TvwnVSKO+FkG(Y9pl>_+FHJJ6%mwEBK_SpEc?h~|E(Giq z0=bA;=q#WaQHz!9wgO;5lHA4{@Jy%0E4y5lP*uNWdXb&qa_MVu;o~LaE`TW=VC94* zG%yI_ya*9?h8=*cP+-)dzF@kbxV)~F2fXmq41W4@OGY5nHACc_?H1%Fpkrns8A%K54^r4^7D7y?~sW-ZxY}!%+^UuAQH_10c29v zl~W>;MX!fRY1$sPFKC!h$x85Z_nPQm=ZPgQ9Bfg0?mYdPo1T()Y=^h!uUS3%z7(Cs z&{BOE z{ru|1zgtpp{8J~f-jw*%Nxt|(7wX5CCQ8g(kMSHgqU&x9j)BWHH|i_FrrI ziBr4KfL-AsuYsXXe!xZVCV3ir#*AAoLvP7krlnPv*lyVD<@&beUZXm|gJ(Z0&W#3F zrMxK0qw-xuRaCw*`RjyLm-=TswMb4nQthSRSsKpS4r#uXV|CeDcFMxE=FHEx@Z-)b zf&DUJn${@N6z!0v40^q?&;)#00^U}sJE{+`INb}1qDI3tU{s8*swdK`if7$$!yCI2 zG$^_?)T_+mL*)rRy&gM!9K`R8Lc6-=vM&FLdV1+xuV`s&+R3qZrXb+F?eGLH^B+(C zvSm&uxG-37e_Foz-_- zH(i2q=OHLo{JsTVx<-gIDnb98V9rNS(Yn8SRZUGv9Y#pnu9!fCf;AMz9RW{;2*2>& zlo@+r)Ssz(5bUUk)uQ+{>pLvtnG@-963gZ6F)TPU^T{BfzmvbW-Odvn=_HYW6!nJ}U@`QgMDrMmMBNe+hL=l(9Af1C^IaA(KE{}zSXs+M zCd`;h=JvvrY}ssqeT9P;jy|**as}#R00ND8pPl|u%I>%bNthcse9{>HfqqjaCW6&7 z0cx5IDQC>@9jwzW<{~nWJnJbuSi-}Wjw+Ue?S*)ntnA+mt|3XJ;iIlO4*sm4q4=TU zN-OS95czpKK5Ssb9#WJtGdTjpTH@ulpe~J&NmpELOU{@b0fKAyFx5N+1k_U}~5*Im{|A9g#>oV&5Kz*iU9_O4ppgRjTEs zkY#hQ+DAlhI@s8j!Gxkm$ zw$383wAaaT?k=RZ%6TWiMk9^(;vw=(E!qwprucA~d<#&M{+T={RaNM1tHF{tx4KKA zC9M&0zWlf+jhutNpi5`|InRokvl|MW0}0fVgVDLT3_W77rMf>YqcqWodWX@>M;d`6piq@)+vf#)egEr&N-Bf5=e@D}7kh*?aQ?eYweStJA?^Eg2;^R(~=0}9SL$7QuL6*_)hcQ<(l9M(rxnyilt%-t9>I3WJ?g~9>aAu~@GICW=W@As%f(b!v<;+W@p)Q; z=~tX=*SfmHm6DQ#bMsXcc0STed_Q!SpkmkNd0s8p+qGkR{NMKNiF~`i72k&a5BAR%J@D%uHC*hFgABTmQOMYC zJJ2gxss%PdH(Gvfq(Xv|=+hv;S7=F?UM~F3)5#S56>;?C7Bc?(;g|-F9pP86q;*WM ztEbCJld4Rwju+jRaa!KXtgurB{J?UF=Zk}75oh{?iiKwk2Xa_U$u)KBIo>(Ccjlv; zT>1qM#rXG`>519T`4WA*cwjj9N8i zKTZxjWvL={un=lgf?wwHp+tArrfQw%Zlwin_@MX|00k;=DvXqFMdt0&r8?#D<{ouH zgOY?G%_JnyEm~9D>3W=o>w2-(y%v>~ig6+?kv;$7#5jZ-j@oQQ=~YN%7HJ<`G54Tk zfWLH~CAJ*tw^sQo0A5}5wHnhg%pxO(1lqFs%5#2nY&^w)e}(_5sFHcD#XLCj)G56KFP%DS(E5u+=TvyZBg1Zx~~ zHE8fgh^cWP{7?*?n~tMRs~gM2=@jnzoS6w#Qi7VbPfID*ju>bWqgdxR!k#Put-c58;w9fga@qw_7ntYVqpqnT(Oa9NMKNv@6?0bShq|K>ZBJ(2hhn zPc7vE9UpWds~+m@*k>ftFJ68`w4yS=;Twly9xI~9*%EK_CnTZJOPj;>H_#B5E-vlY zt!9TFy2s%UM%l1GAjDmbHy0RWX(J;&)BHI#b(Nl*UUGKkXjgVIboS77zW!l`)^r#? zSOKXuWXtu5tWr9vJ<|-3%kgc>N&wnZMhj|tV8}`iA4WqJYkR4FkM@GpnE0dDYBtjE zhXXzOVyz=IydgP&83j}tf#Vcid7g+^sL!!tAp4bpD$n{*IIV+A^CCgB*UUOD)Y@z) zC+jq=UQ-?&ouxjoF#J_GsNX6Y9OLb`$z%^2+~kgkVDr`Zq<2T>-OjIwXDp|@Qh~{7 zWXQ-pViMu=3V0-t4}K>m3;DZC3&1r$+7#)7;w))4J=kNfq}v`LI;!B^t< z5cJZ^()&cCltA-OaH_~|0QPT?(vwrZMHbM@pUqZMN81zl9p^M|_bt~)X3BuM0w^C% z*c1&N&ph0Wm_px)6l&=BjdG@SQ)pS1?58Z!y$?-JJkN<%Fz$TDZH&g6&>g|`6fr&~ zs$PL^;~$5)h9N7fhk#z==YPR#u>boom-U~mVJ7tp!83-+!Wh}5{^HU1xrP?X9nSM$Qp%w-vOm1izipMa;(b0Y zXn5FYORhk(vsv4a5iRJYkJTU0QHC-~sc_^Frh^XhvLhPr_2)e)dYYnrvg({a+IvTc zme_2PvUU_}t=qa&w`<_dp{o$SICQk%{;3d=TfQ?&oZ-T$~Z3`wC|mmBZkU*=~iJI zk%w@k1*l3H{Hr+dGz2I(@U5akE~y|KjDDe|rNekMP^^1O7TLkVv7gjvM~o%%xYU(x z-0&M4Dn)&VG<*coK-(mxH}!g3mo9OoZdZwMjwt!@CA4{tnV$uoiDZK0ql<)BXlcQZ zsy~b70pV1+%o+NrO_rcm+m6(_u89!E!c^UsLy*zzk^IuXxQ05lssLFI4hhPR$3IU- zaK43FawG6i$CK%(*p& zh|_%&86ch^D*s~KQXXBGV6R`)VHM+$U2Xq-!O*?XpL-eIUkoHT~ z<>vM`f(qd*$l!Y^{cm1|+7og5I!nXjAhs+@15u++z~rvY6=P=Omd2)+yY&g3moA=l zcaMk7C%;A7&K2)gciW3F3B{MF%rovTTF4U9638(_EotuB{tp!jvv~E6M)$TT?Y9p1 z%UukJEXCm;(JjBGS^-~p=!CT~mIP`c1JKke2dj57I}BS8LZ75o4hI6th(zQnG~=+) zEN({TV|)YB^XzBT}n$CXJi{M_fspqO;Gy> zEmLIzO0LAhOo$~g20z6pa)Bu9On*i~5p2JM1MOAg^Hl&dXY_$*lpi7oKu91IH~C;P zYWZh?%4N^_48mvge|0DVpph{XT7W>TZ0C=Gz{X=wrGv~d@5JXr$LDb~Oa1u%`WwTH zwE5T!K31mb8jAA;DXSh*e4>Qk885d5p1s>A6SCMqzdN}QBtmzbL2AwCnR9720Iwu= z(3jxBqN?AfZrGq0>(1SKj7Any06WU7NSj>RI7B;Szy0j219jZ(3AG)SdX@43Bxy6@ z#z*pU#I5_Q>mJu8YP&uDrE3-1C714xb+wU)Vy3~bo>AtCZEyPrZ$Z5E&XSWQYuM4L znSxvZr~W9p%yYme4w`J11-ffTa2QVawzGtwvCqms*%qw!hM#%4<=4fQZ=a4jOBeis z_+sR#5`-t;7zJIFT~L3ja-tDT`bTxvxa-mC@W31ltBC8%>*9E{%zTyt%tRSrl9^Ke z9(Ew6lUPuLD;A}EkNMuf?sV`q%^$f= zp1&Z+xlsT!O`rRbd4l)8Zq$IBmR+JHLcgkE7R!*OCfMvJ9F0IMZYo$0V( zz=NB$LOWZbhIQogrQ)m8A4o*B@HG-_;w~4?3ba;hLQr5m91UGswgCX zq?V{aFFoYWm22{`eKG9I+;AR$D1!o44;c*1UDxT5@Ukl9evOK*5)i_5`=Ld=^HW3; zBhWHj$oHX7a3wcblIhlz`v_Joc_#2^ec>dlE9-Zg!{y8Q?TP#BTE%eOOS__)rLMm! zHI7$s*quJYO$}uqGgZHqaakjg#9de`j`vs~5Xr^tQCAXJA&*p4o^L@MzCxT}J@)=} zAy7mpxOC8T0sHQI)Dh0zo52ssaqt9b?qw5!F zrSA`5(4gvIa?V7yo~C|$^He&_V6yY!X_oc+^~B-LTm()yV`w|U^=7zR?PKn{3h_nE zUl7cdlpz*M8CY%DB8k&lcV>?avG`;eeGr^5Oz{p?Q+HbASZx+4`8=&9@B@^fG)33R zBbsc}L8cS>$^a=mn&S@OyAtJes*%%vJ z9%uLSQLyK|87G+{#^3Tl`vS~H7_HZz>c%AAx9lWg#n7zwX3g;A;wVluPP7Rr^P=a^|vce<*;S2XwxJ^SQO6aGbO6-RwTq}R9iV_c21UB!L!jN0eT*{VsRiJX)*OK6Mv(07mhK$2P-8t)OeKUq z?WR0y*vhUI#-mPFf_GFH&9M0{{gKiSEZjf% zvMrE*RPMQ^PA*ZPxyDnkun}kodm(HQM?HP7Bwlny5d1+&$NZc}#f+>3J)Ul)Szfo7 zZS<2DF>Id5BzQs?>(W)Rr@5kaqP2P|t?IeppU+bnHX>DU1+;t5{}sFUZ;1rS8c}n9 z>>lMEr_fQII4)-hqyFcwDfy-KnsZvunZ^v9@(vc;SjPNfN&+jyPW%-s1r%ayD)pXZ z!9}nVX1wtF##s)Rv(fKMh3+ZEo2!GQ8^}};`FnUE5H7bOadJ- zkEvK@PdL8D#jjloYy^K4y+8*tDfx^^o=KTGo++5I1xp9t(1QoFUvF--PafN-o<%`K zoG;~Lo{pw;LER47LKsVVEFAN#RnoCRx6H^lXOv!=nDc~I)=>PGcIXr#9zzwnw;-R^ zh<^mT@%?x5+N*VA%l-8tK^AW(`>JZ%S_dtM@_;>-aC>3|FHKm%wgCBHCXNnSLGz>) zGmBw?+qC1SsAW~9c)Y&vE9O%v@FVd_R4g<3l#DRnpQ?ISb72yCTj|rA0{d>lCiI0hhD3~hCsaLl?jL4G`A(Vx$`BzVgQzzx zf?ZRO+OQcaucxOD{f$WapYt~apdz#citJSPm3gv@dbzBE&3X*51%I24WpoHc7d>?b z_!gu=b}vo&?wov^3i0*G|Dwz|UM7v3JZVL)lEXA=y|8gCj~?dsDE!rkeKu@VW3*{4 zZy`Qupc*8?{+A&+twEr{xE5pSIR(Yd)I|v=J+oy=L+-DsoWib1A7fLY_Jf&YaDkt{ zWPB}Vg@a_$+q*_Yy(c8TQ9Tq>iuRa9nDCR99HMGT6JN<)5^O0AbC7~e;wJ@lbCXK) z3t$X5#QTOx-l?|IX?^Im-cO$PbR2b@Xvnf^zdoFuZaptVR9UDSr$rUY+SpAV``kbW zi^sQE^sY9=1v^JK*RXiny0>;dy>8r9ymU#fhzl!x{pCmxg56KiJv9U38;PiCddJmw z#~nO%^<_9 zVeVnTkzY8vxp6>o^ud1=>XjrKHw$?pwJBv4_#886h)2V(7|La#tS2M%qZl8Ez64G> zb|Wg@nN!a@;NpRTaZ-V-V1nWF;QLH1I0nN=Mo}$PD1t2ubX=*npz%sGG$H<^h*BtZoxjG}Zl;m6#>*l;T<#4&7i}#1~*)aVs zk$nBbv;LByFL+0|-!m5W;bLXCZ1y)mVVzVc2%d)FX;Q(ii#&B{Cg<5H;<-k~@ zCvG#I-ve03?gu90WJ6k5A68_fIHBZUI4Si_<7+Nf8vJg$JX<3TjWaP;n;NoS>YqmS$qS^*y4l$Xl?ZJJ8%l?)3 z1^0>iWFcF}RMiI#GlDP&#azvyzd~{~%gY|cIs^~^E%p>_)02n}O}|F*xrH={sEeI=vZ%VH1fZlfYj=D!RI6&f z2TcR{D(!b}-JwBk@fiMo4B2_s--WI18(Y}nd-1R~7lh)5`}b4>(Tqn(@nI!$-x22YDR`(nhZc#P7{X* z4X#5y`*lF~vnCv5?UQd{Cr=PKwk=-%>J>}eaxZv07v~i81(fBtY7kdyXy#3tf_%Xg zJL$#kmRgl$;Z8SumeFl%0aw%1RjnI)82DE&NfNY`RvMG8lVpcz_+Py9zV<1B4W{6VO3&omr!G4?im`U)Yz z#)G4_-*in4;RR!b&-qZ2#m*;Fim=k*j?4&9V1In+ZxP>zOtWyT;!kM|x8C@ABPYt> zOZsgWF`p^ybS4C++tz$HJdZH!EnLcLZM9*Tq1C5PvhR%662fr+j&0Y z1j=8AX=QRz^UVZAkv^qX@R0+WaLb;%v$#BMHx2!aLGsXQnfoW7xD9^@eq+re*A8Kw zRv8^e)2^n8-DN@gWJ`%Pk$ zdLkCak6w!-;5d~XTYNsBk!Mh+p}k-!0H7T;Q*|Zo)T(?MHm%6i-maJ{%dDc&NCMYi zW+jSAks_66jxMH!k|oMfasEb?3i&xg)sqJ9uHiD2D;*GSGla*fN75%9cuRJ#NZfUM zp5o3infzQ!8Mw!6P-(Jb79sTQwY#O>VR0`5^}>tLu(%-3 zY)*d=(%j8t2gnX+A(7g)6`-OE&@apFvHpCKcL z9+hEm(Rr_v-4FZzXzsDY?A1)wK03LZ>oWdk1Oz;B)s3gNsFiSKZ3# z9PGGxn@)9GhDgrQ0!M)Lc!kT0)}k5H%LA2dakq2Z@k)bso*ZSHbx&o2{&R$Jj`ep6 ztG0FP+td4wfQr45qz%a%3hmX8zw0dm0j_@)B0$Ua7Z)fX;QkK*K@0#x8v{9e8(RmU z3v{y5x7IVWq%pTOGWl5g*aRR;h=_{-KtMnMy1+lc$0|S&00s*B=LIa_z!wBG1OzxZ z1S}L3Bs4rMJUkpM92^27Dl!5h3L+dF@@Hg}PiW}q=qPshPQh zqm#3XtJ@Dh|A4@t;E>SRxcG#`q~w&;+`RmP!lL4m(%QQEhQ_Amme$_B{(-@vU&A9a zvvczci%ZKZTiZLkd;156N5@y!H@A29506jJfB5>t=ikb|G4}u93kAp*C^$G6IMg4$ zKtNr91cm|*K|~LU$}bP4XZMMi!511$ASS1#2j&Z-!X>)C{WR=n5~i)MSASUhi?jb4 zV?Y0oIQtLA{*$j206Z87u=2oA0K9-V#oSObz&}v?hR)-%-j-OB*YYBTH?%jub| zg`r}3%^<(`FB-0WDs$ylr!+Y)XaVroR!iL!hIhX>Qv&HBrhN;_N|Fv@gt<2?s z5MML=ErokW`jaS?n95gw3b#;uhkZtyK@4la1k6tGA*Tf8c>Uu$>3Bii#4|2-S^s#W z!2TKx*r*hZxUS0uH`4iiEEt&D)?@WbWED74PCoK4-n#QjwMMCc;ji=jx;I;d`}v#B?$1!Ns%Y-1f6$44rYHZ~XTKsj%U;g- z5CpbY*o;+Y*i@(tMnv98NZAe6eR%13=ta6No7$bOqn?m-?mqxUDU{LIvoB>&Dno-- zl!|dXCJ}2+Zm9E4qg#8yaSkYUv?M#YaT9>sO8g<=`FTRthpTlC@%CZ}z9%hLLc_OR zo_>6b2QIF?Q{5K)(I$hN)Edoek2T;jSn)X#oh(OK!fcK0Um~|xG_l`EtH!*S4y0RZ z9_I^S_EFhqD~TD%N!qCMyIUq5Vivh6FD|fNIp^Bt-OQM~Le3p`gGM&6e8j#ke_^x+ zNwDqq5utM~A*!Z-TKvRvWoM#jeo*bAyHzU;Kh8O(P7CW@7#P0agLWO{Y;*BJ@{}RZ>0g%kImHt(w*lIvsr(gNY{?Ou=rD zc0Lh2YOHfS$-V|vz40FGOYE`|oUoRQK zZGJq;6~;!m=6CjU*LAQWJWG8esT%iQs!|D3ddp@)BG+>6vHbwh;riK-ow}ocxvZKA zeccJkF9?t5O7OCL9?MYo>++t4K$8cG#8((i4&+}U&9kJ}hzFhf)enI1%6H-aZC4Iz zpLLLu(%~v?h!qk#`~$GMxHG=Q>OIu&SEZfMzk2w?vz#2wIfjB%Hi`7HHS+`D*7^Z( zeO_$xkePDiya>i;F-gR%GF)gt*=IVt?piSdB>d+1VW;iUipyXjfNmi?>mSK8XIyda0Cgt+K}dx?BIfCIdSuFlsGG`t0HZ(8JUhL)tczn&#dDWbvEc8Wd5ussYVpI zzP>j@L==%=XqC^1ZmhC<{XMmSpm()|ixEG@W!p-@nMZQi*_y;`CkEXuRK#BCGvWrz z{^$;;vXTQARG1w;U zXY)_y_zYLf^Y!!%_0I#hHT9KOEh;V1;W<(zJ%?`S2dP|%8c%RiSpfkz@S3>4xk z|9rByBn0n`E%5CjJ-~}_&O)_5!x_qC4(2I=KTw~Gmqh3o^|z@Xy`e!X>3OA`*q*EW zwg{Ev=GAJK5I3P=5$Fao8t~Er4+0C7TZg~=3R_RmR8jPOqifq+NWQqUN>DrIZ1s}I z=Pm2JQuncMt0@usr%gIuY#qMU9v;ihLTBHVNjNnZLD7Jl3q=2w*f&Cr(sO*R_PX>y zqvPso{9O|;5)XqH*57JcuNIeMc7-`@PJKxA!uBBp^+jbqoZo*xe6H3i4cUs+Eg}@l zskRHhIhFQ`>y5Dhp~<{?jd}9M7?z}qXn6R(KY_)==Bi4S>Cv<>Gw?-_irRp(RScI< zinwu~BphOR5(*rd^SA^*!34Iopq!#okl_@QgiLrP1Hhutk9oAxZMFTNGFrdV_jiiJ4hK%yT^sz~+;RFb)bEW5 zTv`BC+-$440XbD+2BpZlFDb3_!cx zcS4+G>y(_;1>%9&&0wj8v_}U@TO1`xtR{sh&a1zsF>D{O`8kr=nlas^dfX}NGUAB$ z7OwUK(CzpEfE~Kb@`Va;;ug3)eoidpp)bK zXGHL^{AXqM|Li*tsij-v1JVC~=x?h`TNxRe0sXF(o{13)jjgpwh@6Zl0xb5QFCmDF z2`K=#i$D^B1|mrTU*+Y@fg2D91yKP&XT#v~-8W8)K(Q`I%Kb@d5~O3Es#YU&!AT--Rgc<9=C>;;|+ zV=JcS01O+T{2`E$Z#TTa+s70a;#V>iJWF0pEv17G;GZMUWDAC-sK5A#cP|i!i`?0( z466EwNI_(DY&eoIM-34oju9jIYx65i^;BkUDQko)&NtVA37AJPdKeUwxRR{l!aR8R zGw2$TSL$~o*QO5)(I#%pdff_6bDWW*BsCX^ENBkqmt2F7BM$J%uh879NDW0f<7S?uMKT`RI(xN7x z{ZCO_N7nG>giGITX(v5xV{*9f_pVH=AyAfQ$wdkBEI^_Z$VVifCB2yqtSvOX z@5X`T6*9jdLQonW!*^Y$ux$}u_y$$^+?DC~75J8Lf1-fTNrr5cfw%-?js;7oC*SJ9 z3-<#yh;SEAD*eKzRczY`mj}WF6n1MQUvS@Lz2!=MIL}V`=u8{kaj5AOCu&RYO$aAsn>HT2z^V}p03rN`Re}}20TsELy6|jo(!(w4DcABmsJD!H8N_&_! zQly=5D}u8}WXV3}UyexF1i@XKYK{HMjN$K`*3*hBqY|6lfeNN(+Gjzx2;nzvU%APL z;N4zsUX;L+R9YURw$dP9tK+7|A~un>N|IhmDGJ4COSc%HPPP{ncqHx-PHUc4mp0x0 zW!Js_7x>XO+1HCWLx~t|UY6G8oE93#)R{_Eot`0Bf}I{W135aZBnqX`U4QA;=I`;s zK_V~J4C=5mnn|N3zL|uc#^vX5>d^M>i(Tji`%$g!d{hoYvn(I#U7sDa#FiV=t4CNH zGmj`7wFcXF^8t@P_f0Fq_9^?6TI`l|ku@{%9p9#tP7jSuXnX^tD?Vj|4y3sh!J&_x zk=vt+R;NA>v{Vk$Tnv-*uNjdcCx@xxX2#aqgBa&v;_oe)aRP;uHwuzsS@d$|!Uc47rx=fYdG!BQ=@t#pW zzT|O=*C|8Lkdm4PRi>?tX|}Di<6794y$7Q+f3NXFXWtasL5<+sHt%xhBYNtdzfWBH z7RbqP$ndP1Xeg5dhq=U*JTZm$#-7%R!JTB}#rq{Whu1Q3{;6~_U^T*Xc1vfzoNIj4 zL3E(g^TUQv4^eUTLwIhotMAFMT8p;T^;M^}YPAyYN!ZCIa05`OfKe~l(^dGmu|%oA zNka>M(#Uz%HM9NYZ)z<@a$P|(%!@>CS=t=70JLoYfVi-XP^EzG&p-AQ4FCxMF1-cJ zy3I5EVi5t1)iD5VBhaS&g`@wopxa*o$v@dsK}N>c9~2_1)AY}3+6xxXUKxEbwZN25cAq`NZ~ zKgs#Mv~g?t^+VAk=`+-o_aGhhjNjiBMO2i>X;1L`CqIvWt(iKdl=m}$ZWQ?SAX*Zj zgGG7Z%7R@a9IWBO=l3b<3Y0qs%^SEowK-PN`$JkoO3h4a3e}o#ef^+`Gb< zSK+KR$|c{*Qh_I+ibqprc(??c%LQW9$!LKu@CebEL{d+~nc6UY3e@0dTD|L2f^@C9 zTqlP0W9|U3uLi3Leiiy1i75jlH8=2&o@%OdWx-7Q5^;8()_!!zYm|2cR2LCM=B9q2YNgJ@ za^&@GM({O;mZQ$7hl>w%Bwup{SvES{FV@%G>a1`=WPWqxC= z(x$i1ERB_@a1G=5BMwX)~z~XVWQ4ql8ybNp&V9^9oFciSM&5 zrH$Xv>*onnucD@PX}|vU)?KPH%+PBXioODF`j$=tLhOJ?Dm?rl(3rG`OjJ}%ej9{t z6qvW^8}Tb-g*y+mkszr3#Lq)eagmr!9h4MQ1~(ux`fOj#-Y7*$Lmn<*1-@!QGMuBh zV=f%;rSutE#APC?d;TEXi8Ej(v+ZY-7sHa_u14F{rp2*S?DK{xn&pIM;M;`yVs&pv z4!jq(KA)GbpfBKrW|H6NvGa-cpVrILTSQbj@JJ(&J^|@ZZi=IxzNL|(qno9X!ym1J z9}`FXNr%a|)e+)i`tC_BC{KdcOGxQ*3_=l4bi`+xhq|+7^mH9dJI*VSo1}Vb$OQJW z34+?nyp|6I8RhP0z_(zxW@lEfTMY~6*0@o?Whd+AP=@yXWUA0K%@#7x!9gI{N;IdL zJ6Y}U?9N#Jw^a*#zQ&{bYyyez0ba;<9OPU`W)ExWPr}^#?xNAXU^6i=%^ysIc1jEL zEhTRhR9<|wz$c4;(&zw^PHKk01#?t^4@$_ubs+y^@Iuel_77)-x#0hI;YXn4%9Z#n z=J?P$;ogIY9;}@U8jVt5D43F-!%J*(60>D$fWu@`O(57~HuscM77JTajMmhH5K>gxJn zZ>Vs+9tE&;}c&DoK`0tc0M@pJPk1mB|)f_H~58j!fQ;@Gc1Xxr2VpRR7wcXQLdQ z>l{1uECD^E(ys|VRF4(vzaGxMx0HJ4^B8pmUv))+&Ugi z%1#GkHe`arG>u#|N{m3pO+EFw+OlpnoYL@Kx&x^*Ce-vDy2*W*xJ^pX*r4y2aUg|G zg`YB(D-zWzp7HgXotr~ug9|USy_L$t`m=S!7cY`nIHDaneWMG z7qCJsZnR7V{>-P;6vC-g>%!5^WBvvHZMx@Vg8|pgSl5YA4FyYo>vX zz0v8+()cIXjJuKwnjg_*SaKW;h zJtoLKP0QMSjT&tTE||_nWg% z113P+{o!p90}JQmenX$-vgUR$7N>3~G zsWZj6zg54%ry89hfBRf<;&L^+d){d^zn`0e4u%#)4hPSQ)vu`bGgX2nyy3}f)yubPT!Eq`$y<$=}07J_p9lnK9H$Q%9v zY^8;$;dt=p8fNS6bXSY?AlZHJ!AgJAu<|w{s14@hZVUOz?i+vd1>9rMG%1XopU5#j z7AOC26_4kZZ5^P<|MuYWpPhIr>y6z|p#S(o|D+So`2W(0?*m>;_^(cUw^*(gaOb~O zC*J>Wop_77QV#gQ7BZD2*kWjk`1cPTxAlB-!cFYo4#th=M>he;zM84|T9lWrT=-E# zJ6En;nX+Fh`RbC|E=Z&Z29qx$K`5uayy1J^2!eC2={>-C0(prP2;*_8RYGa<_uT;r zp~BieVMOvcofnvCus`Qj>*Og=?Z~HV`k7coB)1tl{oEe;zatx`Cdkg+!tol6g%aR& z(+j<(PH;dC6>e53Z(4*X_p_&!GP<_~Kjueto;tt_Ha(YqgF?C`#}R}VZdD_=y!*^~ z$x=X|a8E_jlIh<~Uv66TMFOWkyriBPLS+jyLhCA@<&M9kH~Hkcq5FiD0cCr1rSvEF z@0F$!;-VvbM7*O`Vfge)O3T(=mcj6mfNsj7=Rg9MUHUF=19KCp9#ATK_!<_Z$|aoj zq7&jvy^~(Z#(pe_ngW}5TlnfZ)u=7bRsX?qH9>k!VQc|r<2w|UzD^$I0D+YnNO$6) zDRNZT>gKn6Pmov|f_zNKyI@Fi&XOF9;9W`PZi13sQe;7DN@3xauX^UNaQaDN-9z}q z+eI$w0({eLfj;y6AzxlhDCOVP*j)57q>TbhiW7yxuV#vA(#gxm43;EY$|?x?M1uod zTqAoV!pjIFdpuWfVtVeT66`{-j297*MFiE(k%FBy#Z6;*I-h>zOT0$-TI?Wf(u zSzjQ79wykrbb+J(aksSvXE9iCQhAV*q-u|Ur{T-u2_ND{iG6ivC7FsVcxgqNszD(A zl$4R)pb|1ZJ8WA3U$X4*MY;Lx%0IuCs3>Z9V1WaO7UL1!@+|7gMs>sSY>v#mg|hAepS` z9qh<{tDQ&w0`ok~2}(3FROnWI&~-SK(_s`D0&SmPVhA-Vo5=%vLf~*xIaT3(EIP72 zA^Rm-i{@18C@Pjx3Zr4*2+cMvs9d{hm+Ayxw!EmE$+UK}*w#p-u6S@%6GC!S{p8ELX}GjqEUS8ERr&K zLzQt;zGMHU!7USY02#)-ozHqz^HZ>?7w@*PFgL5cR6VaOY>W~aKP;`JtbBCyqwkqU z(Y?Yx{~9SW&O0LkKb>$5YiHDFRSU@$CzMTSL<)Hi%J=?M1MHJf;Nqw4cES-P(3_$x z6wG^voA~#RnJ>Woz1b19FCx$zOEb`*FXmdtYQClB&kK(7Y)NR0TXa9n!R{_<*zYV=14STw?aey z$8rgMweKN+WwRY`v`pJ}bGuqS62V^b3O!3AuAji!yt+KFZy8Q>Y>efFG4ohv zi(7Y&P@YlpyJu~JN7J8UxdTD63!1*stK$08qxLZmm6Lou>o?`ACO{cM-R?yJO+`r< zPlQ^@BWE?kzT!a9WkyS-_!%99rAVqdM;8k@q*rJkUFuG+Ve1Qrr?v|3zWILjY zv%+5w!K%E7rBod6-mYq!kx$rQEJiqe@(!jWKQ$=2tYp@6I4X6Po*Y1->RZn|CD%=> z7gL4jgwQk8oB>g%R4W}xufFcwX-`RdvdfiCApaGTk$IVaz z`Cz_;T*ce~Qy#^d^1lBW|FDrE0Y=MklQ?LWO5Z2C3{eeraRMi52ufAALfA;XCO_;~ zSFO*$_0J69-tYAV-9P_WST00%8GZVkN~sBFi&xBPv=k{i-5-7=YBsWC>@6IZx||q@YNcR6P!wdO@FvCC9dcN+ zg*LQQqjv`Jk@8qZY@l;xz(byHyKkuo&PojaT*BH+ z5sFnIH4BVM{g^I74vM2;uqAY_5`;)4qyc6@Ngjv-h9tm)*kubyf9ub{WOOQIsHWzO zS%)&oF?lW+pFR}eFI;3>B=2*LC2tgEz=TgQOFBd=5ylf)Q}TfIoYT{BT!cs-I~GdH z=Tu+QrC(L)M$GwcNi1a3{*n+nj~hm zj?MXU&==yGH>z5FMz6WDJ`XuX?$lDAwWpX~*_gn|(HZUH&dkqGUNA(3I8&jj4$2Bb zC_{tfGZhmt4R;w`h!(Vw>s9_e6^~PETDFW!fp~_P)emUFIblpA*=mz1QM{x6Z5L;_ ze8cMKfc1jPifn#7%((FZ7PeZpa7{JgtMMv$g&;mTf&h+$%slJV?sTu??xSRPOIjxs zbZ9~t6Eu)*`idT_hY|~NQ#sLgTP8O}Fw=%gtu6*JyuBY+$h*pT57Di|_fin>bYdA_ zH?eLNF$OLyUs9xlrdnvZvnxxovp8Hcq;ml3YrdDs91JfKMX>Rz<4DD6M88H2TCwgq z96i=fp#N8QXB`$r`~82qyPE}RY3WV@$rX@XKtN(a>5`C632Bk;5-DjUR0IiW5J3SE zc#uX?h3|kq&*BsGrt@AIr!Q<8vAOSo5^dGWfMv>SyW%Y+vz0oKJVv16Q`T_lm+ zY57eQx5r4i17i&OmHDbPEGD!eD$_XudUQ0z`krpx+eUSdqFXg-V;D*n(Ms~FZTm2z z=F)CBh1p$w!SxA~oO-&1G%IHS=`H{TtNhZkVCDJ_|&1kA}OA#a4X$qVg zAamQf=SI8Yf2FvP?Rrv_8jsOJm`=C3VM-^f;m5am6?y&%DckeQ_A@LtL^p!4IN7t& zOH^0HhUU24c4gI)w0QvASA=A1c&RT2arP9+nm>|Vm{Pk)WY28sKqj1#+=c7qp@#@A zO207X<)Qze2th5E5IaE!`f5HCEF&zS32b{8w>`EOJ{naYv1u+R-3`#O-%s^_Vbys% zSab~u$NPe6ALiarrf!yPWTc8+l+A$Yl>gN|yZBBGi32)tUYURK)4dI8f{yhE#LtV- z2rXg;=3V`ZOrB-$ac&!H*)TB~=p-VnXly*DcSWZ@XslJUquEJ1a6s(c zCay;1uOqLr;B70-*s;X-p!yPe2`OBU=k^IDjutt2p{H$Q&2aDX9@7EUY?t&FIUg={ zh|m#5cFaI)N;#U*?g`FdN&fuDR5Ixu5B(2nInh!w8T+~;$X9nSc7(drXw+z}S2*$@ zQ@x;l^bX~S7=nBAQ-FCzRuje8G`4EjF1S|#L8bJh;Wiy#WCnT7`W;*XfyAJHK05lw zOJhE>DF}H((&xLIs87B((%u#-s;4z^^Uhde_7`eeN6gZpFX@G>D2Cvo))ZdF=mn{^ zFBXF<9MocJ6GdCriY;Q6yoX2kD=v>$(LQ^Az4i?{$}g5LrUZ(25Uz}@-&%b(Vg38d zo1>WlFDQ^Cefs{z<&EHPE^mNH=I=jE9~9V}K05wi`e}-0`Tg?d{_Erw5gbL8Y>-T9 z*p-luqmxH1O3AAt$cp;;pM_dmOs@ok-n@t}&%X?N4t4sJ`GmUqy}?6a74BvpLFv2y z;DdAa9;j6)yr}X!U=mW82$^z7DBp0+`WW_VPPtZnlrHd-0*l^f?Mb4wF`96c*GVN` zDJ>PG<+~6sJsDcdTj|`*O65tEEIq{J3>Sjp^$6e3$DbI!O66Y<*)pJ&B5@J(2xACsmg=$czBvbZe0rO3$Xoy0XpZlOCfm56 zc<Ss8;U|yhS}}S&A{B*XZyMECP`)7(fmlY%>ja`?@}+C(1+P_a9nQp84RHFH)cz z+=E$I;pA1+>-S_{H0qs-%KjST3#cU~`+B>KOLDeqa8pnZ)jsJoq5hTnkD^w zYvWo^;(DOD{NbM@J_J1$vk{wp=u{Fam;H5Uw4kn?&aERgLJcdo*=$bcvHZ@k;yiOk zw9#kwbX*o6y&7@|Bgj$}R|Gq7N|AgIoO$5+lB)V<8lFB%9t(Q9J#jqC^rQ9*)k;F1 zD0cOf~CexQaL=*E^E*bTb2Gak4g zU?<${gv^ax@YW$N?G?sg&zf%VtU=rEpo(Z@W^a?^uAI-rXlgDVu`-`8h;^u2IF0K zW9Q{kYrMYd;>rm>@|?MB79^goMbXZq`xp)RHy96S^?GTK(;Jq}8yiG~3dxQe4AoI(8OxS+MQFJU5_N95mxRHbs9+1WG`wZP)zQZjyE3>cBj#W^e-7ct!F4&4e@w(0LQ(MhprL2(SS`dik zzRp`NAF*0G89&4d$jlyXUJ&WhQJ@WGec!MW%7(w>iQ<(sER>1CF}*(X0ok&Mw?bYL_cU=Tqz65{@5jTNp26 zdA?*cc~FN;Ci{vL$8(H+-kjHKuULAAakG1hExT;Kr#$9qQw@u{uwOe~3t znUFzU-ovtcsnHFo&5iBtPt}t@e5TI0fofdX>CTqF=C9Z=>FyZ0HT}`-lYhrQ1GLH4 zE-4&CLgyr_#beONy~lF4mo~G-Qe86F}<&9 zd{1^D>7;2jCIql9pzl@&eW%`hgQhTzeysGD3<<6*MFP6U$xZpjaJESwE%9<{Bz{)U zw3X-cu6fR}g!;imU!9sHYnmv8_A7?v16&)IUB1|q`f7VPOt~Wvz7)hl8HSQuA_UI( zI@4WWG`9^edK2g|Ta<J4$({&SHYu=P23c16{B!^rcm`^!c8y@JO)_AW12n`mbHJ4l-B)8uYjhy>7yA|K~ ziMs%f!ZmrGP?_M%sCvU$IrX^xBTt1*?vT?+>{>%K1D|TXE5z@>QHr~>{za3o3jI#i zaz(%)?o8U0L%iJTw!>%;-ExPi#N?){?ls&kqx{9yEGMbhbsevaoG-8dq_a3Aj>~z{ z63W$vcQ9BAet&K@+%_MP0?xFj?_Zpog@1EyK8=3(7W>5p^*B9I|1X`Jkww0ro6}yW z;HD#xn5$r9c8TkEi_6eXUyF-uvqb6RYdk-5ruv;1IS%MOnQ=XZ`8c|&pyeKYuex4BC?62QTJ9>sH(Z8FM+xh!e{h2OGK*! z!VcE=io|>p=vd>FG@vucS1?P4#XWYML5YP+N>WIoKvI7I)=3Vs7p;kmCt7)1-kR)d zIo1N@K4fq&^H0^%;^-0fyHyp|)m1m?%`Vx0omD(?_gRC$O}A$Ox0!q6Qnh%67tKF+ zkh(%wlWRt7G7I%AV%**D*{4mbUBD{ZoT_R#(di;dzX<~8@I{n@#V>UyJ^+~#J zYSbkkRKg7L;b2t42R4T~ z(Ws;8QB@nnxkVu7yq+~Th2%LOvj|5yS@AJjZUwD3ewFJMquN@Zc0E&Tq_fyjZlmOV_90(S+Dimp;*WpkP*yQI$qCf;-)GF%bldJ?GY2cf3uA6$O8@m3f2 zHc;@69prFAM=&*m6uCM{yG!G4Dq?9;=350Wez2aRsyvhN68dHj`R>ZHy(g1A6 zQ8L}6IEv8guov2-aQ}1BwJ)MC3T+{I88O99SoYM{ds?q}PpkA+lkCt&`F^BR9ucXZ zSoGJ8F1w{0PE{nc7lH0F!T8}VP*Zw9eBILKRwHRnyX?)kvg9#+yCmX7f*OcNBMR8_ z)RJyVVZ#gf`Rq=8{f{p#5NI<%(~*q&E=<&66!fiVV&CJu%MNJhr8e40lpWge`rm3;PIt3JWmJP;qiWJWiz`q`~#kRl`XLk zjZEBDNh$V7Q6_0V&5bIX;%Th$8V`M$-z6TdTnovmqUZ1Jt-e!O#K+iAv?wL@3M|&}ObUUV?#F5``#)CkQtm65J#_O8}WRrd%>r6{j{*)9J^96<)!K8$Q{y&AQNA>5 zk|v0RBpgp_kI~5(JwB+kq%n+S=dn9n!gIB0O1Xx|C+{*{wVeh+{9=#`GNR^_6f|rW z!NLr#)FaSGn&!S>jH}8~66%H>jo=ITuXzkJ2W-m!Dd>{du@qsxR(c(nBc@tZoD^=ziz6yX zR0*LUY4Fi4r&_nFy2}UzpX3UVP}*dQ>@!vn0N6JgLDymyI634{c_3{4ty`o8Ds{?i zOK1Zw^U9Z4)JaF%y9eUSbFVW)eN=3*^k~xxxxcz772JmeVucONj_|qQ&Ie$D-(S3< zy;ty%D9MU={JBnJrIx&8X9-j6U8g;AO+Zdc~RX z)?DxfT*~qnnY~0jVwqdoCc(Ic5eMDe)kXb*b&JSB&ZtUD+YzB;bE?NuF6^!wmw9An zS#m17@|l<8>$#^NgHBw?hs1%o1)15fl1MU+(mR}}o64&bIz$i;UW&84O%V18O|kmk z<$CcV$sXICuT`RJ3{z>4Sj}*Xr>Z8wt1mK`5N^;D^lS)G=(9TZnc1Z9hd*|}>&y>E zM;jXZ_-PL${&5_;onv|;7_Fu7T^IH8r@cYE`o#qj=DB|K!hMzke0g>4Os%GDJU%(H z=Mm7@Qj9ihs`HK{bn6jQkApI9mMj*VQu6P8c%I4IcgleOK7Iefhx7lzhfAD=8pLdb zoaX5NFI_XD$bI+Wsc({je1T9|Fj(pNr9QTWuUXC~qP3Y~!bTHR={+76)Y-#rw(;?z zG4DnGdkx&FK4HwA5(~($lJ*&WIe7#WtI!>9xlyfN94D|BW*$9}=gwDotbLbP$70Pp zhMhFN>$vi%k5u_rCdQpXF%O-yZ#Dz|Q3JlQhDMN$H@=4yu$Obo&lVIa zF<8+T$!tfMuR`I%%@A2qA(K_mv$bxxvKk>((BWaQTO&7O6+yL;&BYDf`+}@#sG8Lw zlOZM8D3K_DH)QOp%hw70WI)B4Q!vXg4lcZB5pr`$U^F5Kp^qz*cYx{+q12Q7S7zBD zTKAliH~}k9?8BhBEyb{8@=Z3}tLkc(Qp37pL~;VD%F9h2&G%JPKCXT@N!;l;ft+)7 z+&kg&y~PKS%S)b#pjv)R@4kZ(Bq?L}XG)^E=pf!RoK*<(QZ^?Q< zgpaYtlthAZ;UXS}-BdR-f>J5Ts!+9y1RB<*Heen+i4xH3;OlkLy|inr=l%Q&gDuaH zlxbjPvIrt+0(#`u1po-FW8AN=oj*j;ZjHb;aSH7^s z29Djz>4ONn_yiH(rH8u0aVs?2#Is7Z3SE6hw*JL(!v|=?>7t>a(r2+oo`+f;PO?`8 zRtUnI-W+}ai8iN`yDpVzr5`@^A$+bIl3#T)3@^kENjc{GQd%6bI)EJ3NQ zE$!;DgJ5({8`fx=b@}LNY66HYcgc+|<_Jz&d)9HQaj@Mzv`s?ZQBR3BtxtHfh76`b zi1fvp&hNq>gq2RYQ73DD(4eZK+NZzmm&RB38FyvuV#ASMbo3ZXnE5Q;^}OpJLnH-m z+$ery;L-DrCp#KPU|gd)5y5>Ni|=~5KDSuQ^3GQ~wuhn7sU**#Miaa1dypkJS{yG( z*cDIr&-uF?W1bCD6E8@09+)?@`Yw72yp=e2_yd06PB7}L3A8|HVE__P+2**AX0v#eZ#22RyZdM3vb(b;ZH6Y3;48s;T-N;HHIJhd%i%!FD?B&`jF|b(7zv11b2~` z&%nNs1!f4t4^|@p)B3;t^RLzCs!N;+cK&G)P9=6>i`d0q;Lh#zZ(BI4Zu!eG*nNCu zQWLm-X(oay$Hw;{n+mTzCYv6l#${4ZBKM4=>u3-4jd*w z;_`sm^(X7j)L-Fo1bfCT27o}|E-=Y|#Fnj#tIAG1wNS;F>j$S`f&zbDH9DeFIZ(x2uAOfMFm46nKho6pL2-^lP9tltQ*uupi+ zIv7FC`L_yo@DTXqeHbJ>;F}rnsr>LAflpV35hg>w5q?Nsg>Md@F$rs)82+vK5BZbu z&EXUKV9hxrzYpV&X@2m4ACu=`&4IlBsB@$EJ(Ui=^^XZY=UeB+oNN7Wy3e=fuw4kB zbpZpY-}`Cw&vG!}3GlJMFal=EPlU5bV0Z$2cnyrOob?moEZ7E~0RIpWMhGtYiE#Ev z5S{>kTOUUFRQ40$>?S`v0sf{EjL=Z^6XEO@la?wfa7}Ysdw~;y8u(ekUw``F{{a&S Be2V}8 literal 0 HcmV?d00001 diff --git a/guide/source/chapter8/0intro.rst b/guide/source/chapter8/0intro.rst new file mode 100644 index 0000000..43c92bd --- /dev/null +++ b/guide/source/chapter8/0intro.rst @@ -0,0 +1,239 @@ +引言 +========================================= + +本章导读 +----------------------------------------- + +到本章开始之前，我们好像已经完成了组成应用程序执行环境的操作系统的三个重要抽象：进程、地址空间和文件， +让应用程序开发、运行和存储数据越来越方便和灵活。有了进程以后，可以让操作系统从宏观层面实现多个应用的并发执行， +而并发是通过操作系统基于处理器的时间片不断地切换进程来达到的。到目前为止的并发，仅仅是进程间的并发， +对于一个进程内部还没有并发性的体现。而这就是线程（Thread）出现的起因：提高一个进程内的并发性。 + +.. chyyuu + https://en.wikipedia.org/wiki/Per_Brinch_Hansen 关于操作系统并发 Binch Hansen 和 Hoare ??？ + https://en.wikipedia.org/wiki/Thread_(computing) 关于线程 + http://www.serpentine.com/blog/threads-faq/the-history-of-threads/ The history of threads + https://en.wikipedia.org/wiki/Core_War 我喜欢的一种早期游戏 + [Dijkstra, 65] Dijkstra, E. W., Cooperating sequential processes, in Programming Languages, Genuys, F. (ed.), Academic Press, 1965. + [Saltzer, 66] Saltzer, J. H., Traffic control in a multiplexed computer system, MAC-TR-30 (Sc.D. Thesis), July, 1966. + https://en.wikipedia.org/wiki/THE_multiprogramming_system + http://www.cs.utexas.edu/users/EWD/ewd01xx/EWD196.PDF + https://en.wikipedia.org/wiki/Edsger_W._Dijkstra + https://en.wikipedia.org/wiki/Per_Brinch_Hansen + https://en.wikipedia.org/wiki/Tony_Hoare + https://en.wikipedia.org/wiki/Mutual_exclusion + https://en.wikipedia.org/wiki/Semaphore_(programming) + https://en.wikipedia.org/wiki/Monitor_(synchronization) + Dijkstra, Edsger W. The structure of the 'THE'-multiprogramming system (EWD-196) (PDF). E.W. Dijkstra Archive. Center for American History, University of Texas at Austin. (transcription) (Jun 14, 1965) + + +有了进程以后，为什么还会出现线程呢？考虑如下情况，对于很多应用（以单一进程的形式运行）而言， +逻辑上存在多个可并行执行的任务，如果其中一个任务被阻塞，将会引起不依赖该任务的其他任务也被阻塞。 +举个具体的例子，我们平常用编辑器来编辑文本内容的时候，都会有一个定时自动保存的功能， +这个功能的作用是在系统或应用本身出现故障的情况前，已有的文档内容会被提前保存。 +假设编辑器自动保存时由于磁盘性能导致写入较慢，导致整个进程被操作系统挂起，这就会影响到用户编辑文档的人机交互体验： +即软件的及时响应能力不足，用户只有等到磁盘写入完成后，操作系统重新调度该进程运行后，用户才可编辑。 +如果我们把一个进程内的多个可并行执行任务通过一种更细粒度的方式让操作系统进行调度， +那么就可以通过处理器时间片切换实现这种细粒度的并发执行。这种细粒度的调度对象就是线程。 + + +.. _term-thread-define: + +线程定义 +~~~~~~~~~~~~~~~~~~~~ + +简单地说，线程是进程的组成部分，进程可包含1 -- n个线程，属于同一个进程的线程共享进程的资源， +比如地址空间、打开的文件等。基本的线程由线程ID、执行状态、当前指令指针 (PC)、寄存器集合和栈组成。 +线程是可以被操作系统或用户态调度器独立调度（Scheduling）和分派（Dispatch）的基本单位。 + +在本章之前，进程是程序的基本执行实体，是程序关于某数据集合上的一次运行活动，是系统进行资源（处理器、 +地址空间和文件等）分配和调度的基本单位。在有了线程后，对进程的定义也要调整了，进程是线程的资源容器， +线程成为了程序的基本执行实体。 + + +同步互斥 +~~~~~~~~~~~~~~~~~~~~~~ + +在上面提到了同步互斥和数据一致性，它们的含义是什么呢？当多个线程共享同一进程的地址空间时， +每个线程都可以访问属于这个进程的数据（全局变量）。如果每个线程使用到的变量都是其他线程不会读取或者修改的话， +那么就不存在一致性问题。如果变量是只读的，多个线程读取该变量也不会有一致性问题。但是，当一个线程修改变量时， +其他线程在读取这个变量时，可能会看到一个不一致的值，这就是数据不一致性的问题。 + +.. note:: + + **并发相关术语** + + - 共享资源（shared resource）：不同的线程/进程都能访问的变量或数据结构。 + - 临界区（critical section）：访问共享资源的一段代码。 + - 竞态条件（race condition）：多个线程/进程都进入临界区时，都试图更新共享的数据结构，导致产生了不期望的结果。 + - 不确定性（indeterminate）： 多个线程/进程在执行过程中出现了竞态条件，导致执行结果取决于哪些线程在何时运行， + 即执行结果不确定，而开发者期望得到的是确定的结果。 + - 互斥（mutual exclusion）：一种操作原语，能保证只有一个线程进入临界区，从而避免出现竞态，并产生确定的执行结果。 + - 原子性（atomic）：一系列操作要么全部完成，要么一个都没执行，不会看到中间状态。在数据库领域， + 具有原子性的一系列操作称为事务（transaction）。 + - 同步（synchronization）：多个并发执行的进程/线程在一些关键点上需要互相等待，这种相互制约的等待称为进程/线程同步。 + - 死锁（dead lock）：一个线程/进程集合里面的每个线程/进程都在等待只能由这个集合中的其他一个线程/进程 + （包括他自身）才能引发的事件，这种情况就是死锁。 + - 饥饿（hungry）：指一个可运行的线程/进程尽管能继续执行，但由于操作系统的调度而被无限期地忽视，导致不能执行的情况。 + +在后续的章节中，会大量使用上述术语，如果现在还不够理解，没关系，随着后续的一步一步的分析和实验， +相信大家能够掌握上述术语的实际含义。 + + + +实践体验 +----------------------------------------- + +获取本章代码： + +.. code-block:: console + + $ git clone https://github.com/LearningOS/rCore-Tutorial-Code-2022S.git + $ cd rCore-Tutorial-Code-2022S + $ git checkout ch8 + $ git clone https://github.com/LearningOS/rCore-Tutorial-Test-2022S.git user + +记得更新测例仓库的代码。 + +在 qemu 模拟器上运行本章代码： + +.. code-block:: console + + $ cd os + $ make run + +内核初始化完成之后就会进入 shell 程序，我们可以体会一下线程的创建和执行过程。在这里我们运行一下本章的测例 ``ch8b_threads`` ： + +.. code-block:: + + >> ch8b_threads + aaa....bbb...ccc... + thread#1 exited with code 1 + thread#2 exited with code 2 + thread#3 exited with code 3 + main thread exited. + Shell: Process 2 exited with code 0 + >> + +它会有4个线程在执行，等前3个线程执行完毕后，主线程退出，导致整个进程退出。 + +此外，在本章的操作系统支持通过互斥来执行“哲学家就餐问题”这个应用程序： + +.. code-block:: + + >> ch8b_phil_din_mutex + Here comes 5 philosophers! + time cost = 720 + '-' -> THINKING; 'x' -> EATING; ' ' -> WAITING + #0: ------- xxxxxxxx---------- xxxx----- xxxxxx--xxx + #1: ---xxxxxx-- xxxxxxx---------- x---xxxxxx + #2: ----- xx---------xx----xxxxxx------------ xxxx + #3: -----xxxxxxxxxx------xxxxx-------- xxxxxx-- xxxxxxxxx + #4: ------ x------ xxxxxx-- xxxxx------ xx + #0: ------- xxxxxxxx---------- xxxx----- xxxxxx--xxx + Shell: Process 2 exited with code 0 + >> + +我们可以看到5个代表“哲学家”的线程通过操作系统的 **信号量** 互斥机制在进行 “THINKING”、“EATING”、“WAITING” 的日常生活。 +没有哲学家由于拿不到筷子而饥饿，也没有两个哲学家同时拿到一个筷子。 + +.. note:: + + **哲学家就餐问题** + + 计算机科学家 Dijkstra 提出并解决的哲学家就餐问题是经典的进程同步互斥问题。哲学家就餐问题描述如下： + + 有5个哲学家共用一张圆桌，分别坐在周围的5张椅子上，在圆桌上有5个碗和5只筷子，他们的生活方式是交替地进行思考和进餐。 + 平时，每个哲学家进行思考，饥饿时便试图拿起其左右最靠近他的筷子，只有在他拿到两只筷子时才能进餐。进餐完毕，放下筷子继续思考。 + + +本章代码树 +----------------------------------------- + +.. code-block:: + :linenos: + + . + ├── bootloader + │ └── rustsbi-qemu.bin + ├── Dockerfile + ├── easy-fs + │ ├── Cargo.lock + │ ├── Cargo.toml + │ └── src + │ ├── bitmap.rs + │ ├── block_cache.rs + │ ├── block_dev.rs + │ ├── efs.rs + │ ├── layout.rs + │ ├── lib.rs + │ └── vfs.rs + ├── easy-fs-fuse + │ ├── Cargo.lock + │ ├── Cargo.toml + │ └── src + │ └── main.rs + ├── LICENSE + ├── Makefile + ├── os + │ ├── build.rs + │ ├── Cargo.lock + │ ├── Cargo.toml + │ ├── Makefile + │ └── src + │ ├── config.rs (修改：扩大了内核堆空间) + │ ├── console.rs + │ ├── drivers + │ │ ├── block + │ │ │ ├── mod.rs + │ │ │ └── virtio_blk.rs + │ │ └── mod.rs + │ ├── entry.asm + │ ├── fs + │ │ ├── inode.rs + │ │ ├── mod.rs + │ │ ├── pipe.rs + │ │ └── stdio.rs + │ ├── lang_items.rs + │ ├── linker.ld + │ ├── logging.rs + │ ├── main.rs + │ ├── mm + │ │ ├── address.rs + │ │ ├── frame_allocator.rs + │ │ ├── heap_allocator.rs + │ │ ├── memory_set.rs (修改：去除了构建进程地址空间时分配用户栈和映射陷入上下文的逻辑) + │ │ ├── mod.rs + │ │ └── page_table.rs + │ ├── sbi.rs + │ ├── sync (新增：互斥锁、信号量和条件变量三种同步互斥机制的实现) + │ │ ├── condvar.rs + │ │ ├── mod.rs + │ │ ├── mutex.rs + │ │ ├── semaphore.rs + │ │ └── up.rs + │ ├── syscall + │ │ ├── fs.rs (修改：将原先对 task 的调用改为对 process 的调用) + │ │ ├── mod.rs + │ │ ├── process.rs (修改：将原先对 task 的调用改为对 process 的调用) + │ │ ├── sync.rs (新增：三种同步互斥机制相关的系统调用，以及基于定时器条件变量的 sleep 调用) + │ │ └── thread.rs (新增：线程相关系统调用) + │ ├── task + │ │ ├── context.rs (修改：将任务上下文的成员变量改为 pub 类型) + │ │ ├── id.rs (新增：由 pid.rs 修改而来，提供 pid/tid 、 kstack/ustack 的分配和回收机制) + │ │ ├── kthread.rs (新增：完全在内核态运行的线程，仅供参考，在实验中未使用) + │ │ ├── manager.rs + │ │ ├── mod.rs (修改：增加阻塞线程的功能，将 exit 扩展到多线程，并在主线程退出时一并退出进程) + │ │ ├── processor.rs (修改：增加获取当前线程的中断上下文虚拟地址及获取当前进程的功能) + │ │ ├── process.rs (新增：将原先 Task 中的地址空间、文件等机制拆分为进程) + │ │ ├── stackless_coroutine.rs (新增：完全在内核态运行的无栈协程，仅供参考，在实验中未使用) + │ │ ├── switch.rs + │ │ ├── switch.S + │ │ └── task.rs (修改：将进程相关的功能移至 process.rs 中) + │ ├── timer.rs (修改：增加定时器条件变量的实现) + │ └── trap + │ ├── context.rs + │ ├── mod.rs (修改：使用线程对应的中断上下文地址而非固定的 TRAP_CONTEXT) + │ └── trap.S + ├── README.md + └── rust-toolchain diff --git a/guide/source/chapter8/1thread-kernel.rst b/guide/source/chapter8/1thread-kernel.rst new file mode 100644 index 0000000..1e5c130 --- /dev/null +++ b/guide/source/chapter8/1thread-kernel.rst @@ -0,0 +1,485 @@ +内核态的线程管理 +========================================= + +线程概念 +--------------------------------------------- + +这里会结合与进程的比较来说明线程的概念。到本章之前，我们看到了进程这一抽象，操作系统让进程拥有相互隔离的虚拟的地址空间， +让进程感到在独占一个虚拟的处理器。其实这只是操作系统通过时分复用和空分复用技术来让每个进程复用有限的物理内存和物理CPU。 +而线程是在进程内中的一个新的抽象。在没有线程之前，一个进程在一个时刻只有一个执行点（即程序计数器 (PC) +寄存器保存的要执行指令的指针）。但线程的引入把进程内的这个单一执行点给扩展为多个执行点，即在进程中存在多个线程， +每个线程都有一个执行点。而且这些线程共享进程的地址空间，所以可以不必采用相对比较复杂的 IPC 机制（一般需要内核的介入）， +而可以很方便地直接访问进程内的数据。 + +在线程的具体运行过程中，需要有程序计数器寄存器来记录当前的执行位置，需要有一组通用寄存器记录当前的指令的操作数据， +需要有一个栈来保存线程执行过程的函数调用栈和局部变量等，这就形成了线程上下文的主体部分。 +这样如果两个线程运行在一个处理器上，就需要采用类似两个进程运行在一个处理器上的调度/切换管理机制， +即需要在一定时刻进行线程切换，并进行线程上下文的保存与恢复。这样在一个进程中的多线程可以独立运行， +取代了进程，成为操作系统调度的基本单位。 + +由于把进程的结构进行了细化，通过线程来表示对处理器的虚拟化，使得进程成为了管理线程的容器。 +在进程中的线程没有父子关系，大家都是兄弟，但还是有个老大。这个代表老大的线程其实就是创建进程（比如通过 +``fork`` 系统调用创建进程）时，建立的第一个线程，它的线程标识符（TID）为 ``0`` 。 + + +线程模型与重要系统调用 +---------------------------------------------- + +目前，我们只介绍本章实现的内核中采用的一种非常简单的线程模型。这个线程模型有三个运行状态： +就绪态、运行态和等待态；共享所属进程的地址空间和其他共享资源（如文件等）；可被操作系统调度来分时占用CPU执行； +可以动态创建和退出；可通过系统调用获得操作系统的服务。我们实现的线程模型建立在进程的地址空间抽象之上： +每个线程都共享进程的代码段和和可共享的地址空间（如全局数据段、堆等），但有自己的独占的栈。 +线程模型需要操作系统支持一些重要的系统调用：创建线程、等待子线程结束等，来支持灵活的多线程应用。 +接下来会介绍这些系统调用的基本功能和设计思路。 + + +线程创建系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在一个进程的运行过程中，进程可以创建多个属于这个进程的线程，每个线程有自己的线程标识符（TID，Thread Identifier）。 +系统调用 ``thread_create`` 的原型如下： + +.. code-block:: rust + :linenos: + + /// 功能：当前进程创建一个新的线程 + /// 参数：entry 表示线程的入口函数地址 + /// 参数：arg：表示线程的一个参数 + pub fn sys_thread_create(entry: usize, arg: usize) -> isize + +当进程调用 ``thread_create`` 系统调用后，内核会在这个进程内部创建一个新的线程，这个线程能够访问到进程所拥有的代码段， +堆和其他数据段。但内核会给这个新线程分配一个它专有的用户态栈，这样每个线程才能相对独立地被调度和执行。 +另外，由于用户态进程与内核之间有各自独立的页表，所以二者需要有一个跳板页 ``TRAMPOLINE`` +来处理用户态切换到内核态的地址空间平滑转换的事务。所以当出现线程后，在进程中的每个线程也需要有一个独立的跳板页 +``TRAMPOLINE`` 来完成同样的事务。 + +相比于创建进程的 ``fork`` 系统调用，创建线程不需要要建立新的地址空间，这是二者之间最大的不同。 +另外属于同一进程中的线程之间没有父子关系，这一点也与进程不一样。 + +等待子线程系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +当一个线程执行完代表它的功能后，会通过 ``exit`` 系统调用退出。内核在收到线程发出的 ``exit`` 系统调用后， +会回收线程占用的部分资源，即用户态用到的资源，比如用户态的栈，用于系统调用和异常处理的跳板页等。 +而该线程的内核态用到的资源，比如内核栈等，需要通过进程/主线程调用 ``waittid`` 来回收了， +这样整个线程才能被彻底销毁。系统调用 ``waittid`` 的原型如下： + +.. code-block:: rust + :linenos: + + /// 参数：tid表示线程id + /// 返回值：如果线程不存在，返回-1；如果线程还没退出，返回-2；其他情况下，返回结束线程的退出码 + pub fn sys_waittid(tid: usize) -> i32 + + +一般情况下进程/主线程要负责通过 ``waittid`` 来等待它创建出来的线程（不是主线程）结束并回收它们在内核中的资源 +（如线程的内核栈、线程控制块等）。如果进程/主线程先调用了 ``exit`` 系统调用来退出，那么整个进程 +（包括所属的所有线程）都会退出，而对应父进程会通过 ``waitpid`` 回收子进程剩余还没被回收的资源。 + + +进程相关的系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在引入了线程机制后，进程相关的重要系统调用： ``fork`` 、 ``exec`` 、 ``waitpid`` 虽然在接口上没有变化， +但在它要完成的功能上需要有一定的扩展。首先，需要注意到把以前进程中与处理器执行相关的部分拆分到线程中。这样，在通过 +``fork`` 创建进程其实也意味着要单独建立一个主线程来使用处理器，并为以后创建新的线程建立相应的线程控制块向量。 +相对而言， ``exec`` 和 ``waitpid`` 这两个系统调用要做的改动比较小，还是按照与之前进程的处理方式来进行。总体上看， +进程相关的这三个系统调用还是保持了已有的进程操作的语义，并没有由于引入了线程，而带来大的变化。 + + +应用程序示例 +---------------------------------------------- + +我们刚刚介绍了 thread_create/waittid 两个重要系统调用，我们可以借助它们和之前实现的系统调用， +开发出功能更为灵活的应用程序。下面我们通过描述一个多线程应用程序 ``threads`` 的开发过程来展示这些系统调用的使用方法。 + + +系统调用封装 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +同学可以在 user/src/syscall.rs 中看到以 sys_* 开头的系统调用的函数原型，它们后续还会在 user/src/lib.rs 中被封装成方便应用程序使用的形式。如 ``sys_thread_create`` 被封装成 ``thread_create`` ，而 ``sys_waittid`` 被封装成 ``waittid`` ： + +.. code-block:: rust + :linenos: + + pub fn thread_create(entry: usize, arg: usize) -> isize { sys_thread_create(entry, arg) } + + pub fn waittid(tid: usize) -> isize { + loop { + match sys_waittid(tid) { + -2 => { yield_(); } + exit_code => return exit_code, + } + } + } + +waittid 等待一个线程标识符的值为tid 的线程结束。在具体实现方面，我们看到当 sys_waittid 返回值为 -2 ，即要等待的线程存在但它却尚未退出的时候，主线程调用 yield_ 主动交出 CPU 使用权，待下次 CPU 使用权被内核交还给它的时候再次调用 sys_waittid 查看要等待的线程是否退出。这样做是为了减小 CPU 资源的浪费。这种方法是为了尽可能简化内核的实现。 + + +多线程应用程序 -- threads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +多线程应用程序 -- threads 开始执行后，先调用 ``thread_create`` 创建了三个线程，加上进程自带的主线程，其实一共有四个线程。每个线程在打印了1000个字符后，会执行 ``exit`` 退出。进程通过 ``waittid`` 等待这三个线程结束后，最终结束进程的执行。下面是多线程应用程序 -- threads 的源代码： + +.. code-block:: rust + :linenos: + + //usr/src/bin/ch8b_threads.rs + + #![no_std] + #![no_main] + + #[macro_use] + extern crate user_lib; + extern crate alloc; + + use user_lib::{thread_create, waittid, exit}; + use alloc::vec::Vec; + + pub fn thread_a() -> ! { + for _ in 0..1000 { print!("a"); } + exit(1) + } + + pub fn thread_b() -> ! { + for _ in 0..1000 { print!("b"); } + exit(2) + } + + pub fn thread_c() -> ! { + for _ in 0..1000 { print!("c"); } + exit(3) + } + + #[no_mangle] + pub fn main() -> i32 { + let mut v = Vec::new(); + v.push(thread_create(thread_a as usize, 0)); + v.push(thread_create(thread_b as usize, 0)); + v.push(thread_create(thread_c as usize, 0)); + for tid in v.iter() { + let exit_code = waittid(*tid as usize); + println!("thread#{} exited with code {}", tid, exit_code); + } + println!("main thread exited."); + 0 + } + +线程管理的核心数据结构 +----------------------------------------------- + +为了在现有进程管理的基础上实现线程管理，我们需要改进一些数据结构包含的内容及接口。 +基本思路就是把进程中与处理器相关的部分分拆出来，形成线程相关的部分。 + +本节将按照如下顺序来进行介绍： + +- 任务控制块 TaskControlBlock ：表示线程的核心数据结构。 +- 任务管理器 TaskManager ：管理线程集合的核心数据结构。 +- 处理器管理结构 Processor ：用于线程调度，维护线程的处理器状态。 + +线程控制块 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在内核中，每个线程的执行状态和线程上下文等均保存在一个被称为线程控制块 (TCB, Task Control Block) +的结构中，它是内核对线程进行管理的核心数据结构。在内核看来，它就等价于一个线程。 + +.. code-block:: rust + :linenos: + + pub struct TaskControlBlock { + // immutable + pub process: Weak, + pub kernel_stack: KernelStack, + // mutable + inner: UPSafeCell, + } + + pub struct TaskControlBlockInner { + pub trap_cx_ppn: PhysPageNum, + pub task_cx: TaskContext, + pub task_status: TaskStatus, + pub exit_code: Option, + pub res: Option, + } + +线程控制块就是任务控制块（TaskControlBlock），主要包括在线程初始化之后就不再变化的元数据： +线程所属的进程和线程的内核栈，以及在运行过程中可能发生变化的元数据： UPSafeCell 。 +大部分的细节放在 ``TaskControlBlockInner`` 中： + +之前进程中的定义不存在的： + +- ``res: Option`` 指出了用户态的线程代码执行需要的信息，这些在线程初始化之后就不再变化： + +.. code-block:: rust + :linenos: + + pub struct TaskUserRes { + pub tid: usize, + pub ustack_base: usize, + pub process: Weak, + } + +- tid：线程标识符 +- ustack_base：线程的栈顶地址 +- process：线程所属的进程 + +与之前进程中的定义相同/类似的部分： + +- ``trap_cx_ppn`` 指出了应用地址空间中线程的 Trap 上下文被放在的物理页帧的物理页号。 +- ``task_cx`` 保存暂停线程的线程上下文，用于线程切换。 +- ``task_status`` 维护当前线程的执行状态。 +- ``exit_code`` 线程退出码。 + + +包含线程的进程控制块 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +把线程相关数据单独组织成数据结构后，进程的结构也需要进行一定的调整： + +.. code-block:: rust + :linenos: + + pub struct ProcessControlBlock { + // immutable + pub pid: PidHandle, + // mutable + inner: UPSafeCell, + } + + pub struct ProcessControlBlockInner { + ... + pub tasks: Vec>>, + pub task_res_allocator: RecycleAllocator, + } + +从中可以看出，进程把与处理器执行相关的部分都移到了 ``TaskControlBlock`` 中，并组织为一个线程控制块向量中， +这就自然对应到多个线程的管理上了。而 ``RecycleAllocator`` 是对之前的 ``PidAllocator`` 的一个升级版， +即一个相对通用的资源分配器，可用于分配进程标识符（PID）和线程的内核栈（KernelStack）。 + +.. chyyuu 加一个PidAllocator的链接??? + +线程与处理器管理结构 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +线程管理的结构是线程管理器，即任务管理器，位于 ``os/src/task/manager.rs`` 中， +其数据结构和方法与之前章节中进程的任务管理器完全一样，仅负责管理所有线程。而处理器管理结构 ``Processor`` +负责维护 CPU 状态、调度和特权级切换等事务。其数据结构与之前章节中进程的处理器管理结构完全一样。 +但在相关方法上面，由于多个线程有各自的用户栈和跳板页，所以有些不同，下面会进一步分析。 + +.. chyyuu 加一个taskmanager,processor的链接??? + +线程管理机制的设计与实现 +----------------------------------------------- + +在上述线程模型和内核数据结构的基础上，我们还需完成线程管理的基本实现，从而构造出一个完整的“达科塔盗龙”操作系统。 +本节将分析如何实现线程管理： + +- 线程创建、线程退出与等待线程结束 +- 线程执行中的特权级切换 +.. - 进程管理中与线程相关的处理 + + +线程创建、线程退出与等待线程结束 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +线程创建 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +当一个进程执行中发出了创建线程的系统调用 ``sys_thread_create`` 后，操作系统就需要在当前进程的基础上创建一个线程了， +这里重点是需要了解创建线程控制块，在线程控制块中初始化各个成员变量，建立好进程和线程的关系等。 +只有建立好这些成员变量，才能给线程建立一个灵活方便的执行环境。这里列出支持线程正确运行所需的重要的执行环境要素： + +- 线程的用户态栈：确保在用户态的线程能正常执行函数调用； +- 线程的内核态栈：确保线程陷入内核后能正常执行函数调用； +- 线程的跳板页：确保线程能正确的进行用户态<-->内核态切换； +- 线程上下文：即线程用到的寄存器信息，用于线程切换。 + +线程创建的具体实现如下： + +.. code-block:: rust + :linenos: + + // os/src/syscall/thread.rs + + pub fn sys_thread_create(entry: usize, arg: usize) -> isize { + let task = current_task().unwrap(); + let process = task.process.upgrade().unwrap(); + // create a new thread + let new_task = Arc::new(TaskControlBlock::new( + Arc::clone(&process), + task.inner_exclusive_access().res.as_ref().unwrap().ustack_base, + true, + )); + // add new task to scheduler + add_task(Arc::clone(&new_task)); + let new_task_inner = new_task.inner_exclusive_access(); + let new_task_res = new_task_inner.res.as_ref().unwrap(); + let new_task_tid = new_task_res.tid; + let mut process_inner = process.inner_exclusive_access(); + // add new thread to current process + let tasks = &mut process_inner.tasks; + while tasks.len() < new_task_tid + 1 { + tasks.push(None); + } + tasks[new_task_tid] = Some(Arc::clone(&new_task)); + let new_task_trap_cx = new_task_inner.get_trap_cx(); + *new_task_trap_cx = TrapContext::app_init_context( + entry, + new_task_res.ustack_top(), + kernel_token(), + new_task.kernel_stack.get_top(), + trap_handler as usize, + ); + (*new_task_trap_cx).x[10] = arg; + new_task_tid as isize + } + +上述代码主要完成了如下事务： + +- 第4-5行，找到当前正在执行的线程 ``task`` 和此线程所属的进程 ``process`` 。 +- 第7-11行，调用 ``TaskControlBlock::new`` 方法，创建一个新的线程 ``new_task`` ，在创建过程中，建立与进程 + ``process`` 的所属关系，分配了线程用户态栈、内核态栈、用于异常/中断的跳板页。 +- 第13行，把线程挂到调度队列中。 +- 第19-22行，把线程接入到所需进程的线程列表 ``tasks`` 中。 +- 第25~32行，初始化位于该线程在用户态地址空间中的 Trap 上下文：设置线程的函数入口点和用户栈， + 使得第一次进入用户态时能从线程起始位置开始正确执行；设置好内核栈和陷入函数指针 ``trap_handler`` ， + 保证在 Trap 的时候用户态的线程能正确进入内核态。 + +线程退出 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +当一个非主线程的其他线程发出 ``sys_exit`` 系统调用时，内核会调用 ``exit_current_and_run_next`` +函数退出当前线程并切换到下一个线程，但不会导致其所属进程的退出。当 **主线程** 即进程发出这个系统调用， +内核会回收整个进程（这包括了其管理的所有线程）资源，并退出。具体实现如下： + +.. code-block:: rust + :linenos: + + // os/src/syscall/process.rs + + pub fn sys_exit(exit_code: i32) -> ! { + exit_current_and_run_next(exit_code); + panic!("Unreachable in sys_exit!"); + } + + // os/src/task/mod.rs + + pub fn exit_current_and_run_next(exit_code: i32) { + let task = take_current_task().unwrap(); + let mut task_inner = task.inner_exclusive_access(); + let process = task.process.upgrade().unwrap(); + let tid = task_inner.res.as_ref().unwrap().tid; + // record exit code + task_inner.exit_code = Some(exit_code); + task_inner.res = None; + // here we do not remove the thread since we are still using the kstack + // it will be deallocated when sys_waittid is called + drop(task_inner); + drop(task); + // however, if this is the main thread of current process + // the process should terminate at once + if tid == 0 { + let mut process_inner = process.inner_exclusive_access(); + // mark this process as a zombie process + process_inner.is_zombie = true; + // record exit code of main process + process_inner.exit_code = exit_code; + { + // move all child processes under init process + let mut initproc_inner = INITPROC.inner_exclusive_access(); + for child in process_inner.children.iter() { + child.inner_exclusive_access().parent = Some(Arc::downgrade(&INITPROC)); + initproc_inner.children.push(child.clone()); + } + } + let mut recycle_res = Vec::::new(); + // deallocate user res (including tid/trap_cx/ustack) of all threads + // it has to be done before we dealloc the whole memory_set + // otherwise they will be deallocated twice + for task in process_inner.tasks.iter().filter(|t| t.is_some()) { + let task = task.as_ref().unwrap(); + let mut task_inner = task.inner_exclusive_access(); + if let Some(res) = task_inner.res.take() { + recycle_res.push(res); + } + } + drop(process_inner); + recycle_res.clear(); + let mut process_inner = process.inner_exclusive_access(); + process_inner.children.clear(); + // deallocate other data in user space i.e. program code/data section + process_inner.memory_set.recycle_data_pages(); + } + drop(process); + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); + } + +上述代码主要完成了如下事务： + +- 第11-21行，回收线程的各种资源。 +- 第24-56行，如果是主线程发出的退去请求，则回收整个进程的部分资源，并退出进程。第 33~37 + 行所做的事情是将当前进程的所有子进程挂在初始进程 INITPROC 下面，其做法是遍历每个子进程， + 修改其父进程为初始进程，并加入初始进程的孩子向量中。第 49 行将当前进程的孩子向量清空。 +- 第58-59行，进行线程调度切换。 + +上述实现中很大一部分与第五章讲解的 进程的退出 的功能实现大致相同。 + +.. chyyuu 加上链接??? + +等待线程结束 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +主线程通过系统调用 ``sys_waittid`` 来等待其他线程的结束。具体实现如下： + +.. code-block:: rust + :linenos: + + // os/src/syscall/ch8b_thread.rs + + pub fn sys_waittid(tid: usize) -> i32 { + let task = current_task().unwrap(); + let process = task.process.upgrade().unwrap(); + let task_inner = task.inner_exclusive_access(); + let mut process_inner = process.inner_exclusive_access(); + // a thread cannot wait for itself + if task_inner.res.as_ref().unwrap().tid == tid { + return -1; + } + let mut exit_code: Option = None; + let waited_task = process_inner.tasks[tid].as_ref(); + if let Some(waited_task) = waited_task { + if let Some(waited_exit_code) = waited_task.inner_exclusive_access().exit_code { + exit_code = Some(waited_exit_code); + } + } else { + // waited thread does not exist + return -1; + } + if let Some(exit_code) = exit_code { + // dealloc the exited thread + process_inner.tasks[tid] = None; + exit_code + } else { + // waited thread has not exited + -2 + } + } + +上述代码主要完成了如下事务： + +- 第9-10行，如果是线程等自己，返回错误. +- 第12-21行，如果找到 ``tid`` 对应的退出线程，则收集该退出线程的退出码 ``exit_tid`` ，否则返回错误（退出线程不存在）。 +- 第22-29行，如果退出码存在，则清空进程中对应此退出线程的线程控制块（至此，线程所占资源算是全部清空了），否则返回错误（线程还没退出）。 + + +线程执行中的特权级切换和调度切换 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +线程执行中的特权级切换与第三章中 **任务切换的设计与实现** 小节中讲解的过程是一致的。而线程执行中的调度切换过程与第五章的 **进程调度机制** 小节中讲解的过程是一致的。 +这里就不用再赘述一遍了。 + + +.. [#dak] 达科塔盗龙是一种生存于距今6700万-6500万年前白垩纪晚期的兽脚类驰龙科恐龙，它主打的并不是霸王龙的力量路线，而是利用自己修长的后肢来提高敏捷度和奔跑速度。它全身几乎都长满了羽毛，可能会滑翔或者其他接近飞行行为的行动模式。 \ No newline at end of file diff --git a/guide/source/chapter8/2lock.rst b/guide/source/chapter8/2lock.rst new file mode 100644 index 0000000..f67f0ee --- /dev/null +++ b/guide/source/chapter8/2lock.rst @@ -0,0 +1,379 @@ +锁机制 +========================================= + +本节导读 +----------------------------------------- + +.. chyyuu https://en.wikipedia.org/wiki/Lock_(computer_science) + +到目前为止，我们已经实现了进程和线程，也能够理解在一个时间段内，会有多个线程在执行，这就是并发。 +而且，由于线程的引入，多个线程可以共享进程中的全局数据。如果多个线程都想读和更新全局数据， +那么谁先更新取决于操作系统内核的抢占式调度和分派策略。在一般情况下，每个线程都有可能先执行， +且可能由于中断等因素，随时被操作系统打断其执行，而切换到另外一个线程运行， +形成在一段时间内，多个线程交替执行的现象。如果没有一些保障机制（比如互斥、同步等）， +那么这些对共享数据进行读写的交替执行的线程，其期望的共享数据的正确结果可能无法达到。 + +所以，我们需要研究一种保障机制 --- 锁 ，确保无论操作系统如何抢占线程，调度和切换线程的执行， +都可以保证对拥有锁的线程，可以独占地对共享数据进行读写，从而能够得到正确的共享数据结果。 +这种机制的能力来自于处理器的指令、操作系统系统调用的基本支持，从而能够保证线程间互斥地读写共享数据。 +下面各个小节将从为什么需要锁、锁的基本思路、锁的不同实现方式等逐步展开讲解。 + +为什么需要锁 +----------------------------------------- + +上一小节已经提到，没有保障机制的多个线程，在对共享数据进行读写的过程中，可能得不到预期的结果。 +我们来看看这个简单的例子： + +.. code-block:: c + :linenos: + :emphasize-lines: 4 + + // 线程的入口函数 + int a=0; + void f() { + a = a + 1; + } + +对于上述函数中的第 4 行代码，一般人理解处理器会一次就执行完这条简单的语句，但实际情况并不是这样。 +我们可以用 GCC 编译出上述函数的汇编码： + +.. code-block:: shell + :linenos: + + $ riscv64-unknown-elf-gcc -o f.s -S f.c + + +可以看到生成的汇编代码如下： + +.. code-block:: asm + :linenos: + :emphasize-lines: 18-23 + + //f.s + .text + .globl a + .section .sbss,"aw",@nobits + .align 2 + .type a, @object + .size a, 4 + a: + .zero 4 + .text + .align 1 + .globl f + .type f, @function + f: + addi sp,sp,-16 + sd s0,8(sp) + addi s0,sp,16 + lui a5,%hi(a) + lw a5,%lo(a)(a5) + addiw a5,a5,1 + sext.w a4,a5 + lui a5,%hi(a) + sw a4,%lo(a)(a5) + nop + ld s0,8(sp) + addi sp,sp,16 + jr ra + + +.. chyyuu 可以给上面的汇编码添加注释??? + +从中可以看出，对于高级语言的一条简单语句（C 代码的第 4 行，对全局变量进行读写），很可能是由多条汇编代码 +（汇编代码的第 18~23 行）组成。如果这个函数是多个线程要执行的函数，那么在上述汇编代码第 +18 行到第 23 行中的各行之间，可能会发生中断，从而导致操作系统执行抢占式的线程调度和切换， +就会得到不一样的结果。由于执行这段汇编代码（第 18~23 行））的多个线程在访问全局变量过程中可能导致竞争状态， +因此我们将此段代码称为临界区（critical section）。临界区是访问共享变量（或共享资源）的代码片段， +不能由多个线程同时执行，即需要保证互斥。 + +下面是有两个线程T0、T1在一个时间段内的一种可能的执行情况： + +===== ===== ======= ======= =========== ========= +时间 T0 T1 OS 共享变量a 寄存器a5 +===== ===== ======= ======= =========== ========= +1 L18 -- -- 0 a的高位地址 +2 -- -- 切换 0 0 +3 -- L18 -- 0 a的高位地址 +4 L20 -- -- 0 1 +5 -- -- 切换 0 a的高位地址 +6 -- L20 -- 0 1 +7 -- -- 切换 0 1 +8 L23 -- -- 1 1 +9 -- -- 切换 1 1 +10 -- L23 -- 1 1 +===== ===== ======= ======= =========== ========= + +一般情况下，线程 T0 执行完毕后，再执行线程 T1，那么共享全局变量 ``a`` 的值为 2 。但在上面的执行过程中， +可以看到在线程执行指令的过程中会发生线程切换，这样在时刻 10 的时候，共享全局变量 ``a`` 的值为 1 ， +这不是我们预期的结果。出现这种情况的原因是两个线程在操作系统的调度下（在哪个时刻调度具有不确定性）， +交错执行 ``a = a + 1`` 的不同汇编指令序列，导致虽然增加全局变量 ``a`` 的代码被执行了两次， +但结果还是只增加了 1 。这种多线程的最终执行结果不确定（indeterminate），取决于由于调度导致的、 +不确定指令执行序列的情况就是竞态条件（race condition）。 + +如果每个线程在执行 ``a = a + 1`` 这个 C 语句所对应多条汇编语句过程中，不会被操作系统切换， +那么就不会出现多个线程交叉读写全局变量的情况，也就不会出现结果不确定的问题了。 + +所以，访问（特指写操作）共享变量代码片段，不能由多个线程同时执行（即并行）或者在一个时间段内都去执行 +（即并发）。要做到这一点，需要互斥机制的保障。从某种角度上看，这种互斥性也是一种原子性， +即线程在临界区的执行过程中，不会出现只执行了一部分，就被打断并切换到其他线程执行的情况。即， +要么线程执行的这一系列操作/指令都完成，要么这一系列操作/指令都不做，不会出现指令序列执行中被打断的情况。 + + +锁的基本思路 +----------------------------------------- + +要保证多线程并发执行中的临界区的代码具有互斥性或原子性，我们可以建立一种锁， +只有拿到锁的线程才能在临界区中执行。这里的锁与现实生活中的锁的含义很类似。比如，我们可以写出如下的伪代码： + +.. code-block:: Rust + :linenos: + + lock(mutex); // 尝试取锁 + a = a + 1; // 临界区，访问临界资源 a + unlock(mutex); // 是否锁 + ... // 剩余区 + +对于一个应用程序而言，它的执行是受到其执行环境的管理和限制的，而执行环境的主要组成就是用户态的系统库、 +操作系统和更底层的处理器，这说明我们需要有硬件和操作系统来对互斥进行支持。一个自然的想法是，这个 +``lock/unlock`` 互斥操作就是CPU提供的机器指令，那上面这一段程序就很容易在计算机上执行了。 +但需要注意，这里互斥的对象是线程的临界区代码，而临界区代码可以访问各种共享变量（简称临界资源）。 +只靠两条机器指令，难以识别各种共享变量，不太可能约束可能在临界区的各种指令执行共享变量操作的互斥性。 +所以，我们还是需要有一些相对更灵活和复杂一点的方法，能够设置一种所有线程能看到的标记， +在一个能进入临界区的线程设置好这个标记后，其他线程都不能再进入临界区了。总体上看， +对临界区的访问过程分为四个部分： + +1. 尝试取锁: 查看锁是否可用，即临界区是否可访问（看占用临界区标志是否被设置），如果可以访问， + 则设置占用临界区标志（锁不可用）并转到步骤 2 ，否则线程忙等或被阻塞; +2. 临界区: 访问临界资源的系列操作 +3. 释放锁: 清除占用临界区标志（锁可用），如果有线程被阻塞，会唤醒阻塞线程； +4. 剩余区: 与临界区不相关部分的代码 + +根据上面的步骤，可以看到锁机制有两种：让线程忙等的忙等锁（spin lock），以及让线程阻塞的睡眠锁 +（sleep lock）。锁的实现大体上基于三类机制：用户态软件、机器指令硬件、内核态操作系统。 +下面我们介绍来 rCore 中基于内核态操作系统级方法实现的支持互斥的锁。 + +我们还需要知道如何评价各种锁实现的效果。一般我们需要关注锁的三种属性： + +1. 互斥性（mutual exclusion），即锁是否能够有效阻止多个线程进入临界区，这是最基本的属性。 +2. 公平性（fairness），当锁可用时，每个竞争线程是否有公平的机会抢到锁。 +3. 性能（performance），即使用锁的时间开销。 + + +内核态操作系统级方法实现锁 --- mutex 系统调用 +----------------------------------------- + + +使用 mutex 系统调用 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +如何能够实现轻量的可睡眠锁？一个自然的想法就是，让等待锁的线程睡眠，让释放锁的线程显式地唤醒等待锁的线程。 +如果有多个等待锁的线程，可以全部释放，让大家再次竞争锁；也可以只释放最早等待的那个线程。 +这就需要更多的操作系统支持，特别是需要一个等待队列来保存等待锁的线程。 + +我们先看看多线程应用程序如何使用mutex系统调用的： + + +.. code-block:: Rust + :linenos: + :emphasize-lines: 8,13,21,32,35,38 + + // user/src/bin/race_adder_mutex_blocking.rs + + static mut A: usize = 0; + ... + unsafe fn f() -> ! { + let mut t = 2usize; + for _ in 0..PER_THREAD { + mutex_lock(0); + let a = &mut A as *mut usize; + let cur = a.read_volatile(); + for _ in 0..500 { t = t * t % 10007; } + a.write_volatile(cur + 1); + mutex_unlock(0); + } + exit(t as i32) + } + + #[no_mangle] + pub fn main() -> i32 { + let start = get_time(); + assert_eq!(mutex_blocking_create(), 0); + let mut v = Vec::new(); + for _ in 0..THREAD_COUNT { + v.push(thread_create(f as usize, 0) as usize); + } + ... + } + + // usr/src/syscall.rs + + pub fn sys_mutex_create(blocking: bool) -> isize { + syscall(SYSCALL_MUTEX_CREATE, [blocking as usize, 0, 0]) + } + pub fn sys_mutex_lock(id: usize) -> isize { + syscall(SYSCALL_MUTEX_LOCK, [id, 0, 0]) + } + pub fn sys_mutex_unlock(id: usize) -> isize { + syscall(SYSCALL_MUTEX_UNLOCK, [id, 0, 0]) + } + + +- 第21行，创建了一个ID为 ``0`` 的互斥锁，对应的是第32行 ``SYSCALL_MUTEX_CREATE`` 系统调用； +- 第8行，尝试获取锁（对应的是第35行 ``SYSCALL_MUTEX_LOCK`` 系统调用），如果取得锁， + 将继续向下执行临界区代码；如果没有取得锁，将阻塞； +- 第13行，释放锁（对应的是第38行 ``SYSCALL_MUTEX_UNLOCK`` 系统调用），如果有等待在该锁上的线程， + 则唤醒这些等待线程。 + +mutex 系统调用的实现 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +操作系统如何实现这些系统调用呢？首先考虑一下与此相关的核心数据结构， +然后考虑与数据结构相关的相关函数/方法的实现。 + +在线程的眼里， **互斥** 是一种每个线程能看到的资源，且在一个进程中，可以存在多个不同互斥资源， +所以我们可以把所有的互斥资源放在一起让进程来管理，如下面代码第 9 行所示。这里需要注意的是： +``mutex_list: Vec>>`` 表示的是实现了 ``Mutex`` trait 的一个“互斥资源”的向量。而 +``MutexBlocking`` 是会实现 ``Mutex`` trait 的内核数据结构，它就是我们提到的 **互斥资源** 即 +**互斥锁** 。操作系统需要显式地施加某种控制，来确定当一个线程释放锁时，等待的线程谁将能抢到锁。 +为了做到这一点，操作系统需要有一个等待队列来保存等待锁的线程，如下面代码的第 20 行所示。 + +.. code-block:: Rust + :linenos: + :emphasize-lines: 9,20 + + pub struct ProcessControlBlock { + // immutable + pub pid: PidHandle, + // mutable + inner: UPSafeCell, + } + pub struct ProcessControlBlockInner { + ... + pub mutex_list: Vec>>, + } + pub trait Mutex: Sync + Send { + fn lock(&self); + fn unlock(&self); + } + pub struct MutexBlocking { + inner: UPSafeCell, + } + pub struct MutexBlockingInner { + locked: bool, + wait_queue: VecDeque>, + } + + +这样，在操作系统中，需要设计实现三个核心成员变量。互斥锁的成员变量有两个：表示是否锁上的 ``locked`` +和管理等待线程的等待队列 ``wait_queue``；进程的成员变量：锁向量 ``mutex_list`` 。 + +首先需要创建一个互斥锁，下面是应对 ``SYSCALL_MUTEX_CREATE`` 系统调用的创建互斥锁的函数： + +.. code-block:: Rust + :linenos: + :emphasize-lines: 14,18 + + // os/src/syscall/sync.rs + pub fn sys_mutex_create(blocking: bool) -> isize { + let process = current_process(); + let mut process_inner = process.inner_exclusive_access(); + if let Some(id) = process_inner + .mutex_list + .iter() + .enumerate() + .find(|(_, item)| item.is_none()) + .map(|(id, _)| id) { + process_inner.mutex_list[id] = if !blocking { + Some(Arc::new(MutexSpin::new())) + } else { + Some(Arc::new(MutexBlocking::new())) + }; + id as isize + } else { + process_inner.mutex_list.push(Some(Arc::new(MutexSpin::new()))); + process_inner.mutex_list.len() as isize - 1 + } + } + +- 第 14 行，如果向量中有空的元素，就在这个空元素的位置创建一个可睡眠的互斥锁； +- 第 18 行，如果向量满了，就在向量中添加新的可睡眠的互斥锁； + + +有了互斥锁，接下来就是实现 ``Mutex`` trait的内核函数：对应 ``SYSCALL_MUTEX_LOCK`` 系统调用的 +``sys_mutex_lock`` 。操作系统主要工作是，在锁已被其他线程获取的情况下，把当前线程放到等待队列中， +并调度一个新线程执行。主要代码如下： + +.. code-block:: Rust + :linenos: + :emphasize-lines: 8,16,17,19,21 + + // os/src/syscall/sync.rs + pub fn sys_mutex_lock(mutex_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let mutex = Arc::clone(process_inner.mutex_list[mutex_id].as_ref().unwrap()); + drop(process_inner); + drop(process); + mutex.lock(); + 0 + } + + // os/src/sync/mutex.rs + impl Mutex for MutexBlocking { + fn lock(&self) { + let mut mutex_inner = self.inner.exclusive_access(); + if mutex_inner.locked { + mutex_inner.wait_queue.push_back(current_task().unwrap()); + drop(mutex_inner); + block_current_and_run_next(); + } else { + mutex_inner.locked = true; + } + } + } + +.. chyyuu drop的作用？？？ + +- 第 8 行，调用 ID 为 ``mutex_id`` 的互斥锁 ``mutex`` 的 ``lock`` 方法，具体工作由该方法来完成。 +- 第 16 行，如果互斥锁 ``mutex`` 已经被其他线程获取了，那么在第 17 行，将把当前线程放入等待队列中; + 在第 19 行，让当前线程处于等待状态，并调度其他线程执行。 +- 第 21 行，如果互斥锁 ``mutex`` 还没被获取，那么当前线程会获取给互斥锁，并返回系统调用。 + + +最后是实现 ``Mutex`` trait 的内核函数：对应 ``SYSCALL_MUTEX_UNLOCK`` 系统调用的 ``sys_mutex_unlock`` 。 +操作系统的主要工作是，如果有等待在这个互斥锁上的线程，需要唤醒最早等待的线程。主要代码如下： + +.. code-block:: Rust + :linenos: + :emphasize-lines: 8,17-18,20 + + // os/src/syscall/sync.rs + pub fn sys_mutex_unlock(mutex_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let mutex = Arc::clone(process_inner.mutex_list[mutex_id].as_ref().unwrap()); + drop(process_inner); + drop(process); + mutex.unlock(); + 0 + } + + // os/src/sync/mutex.rs + impl Mutex for MutexBlocking { + fn unlock(&self) { + let mut mutex_inner = self.inner.exclusive_access(); + assert!(mutex_inner.locked); + if let Some(waking_task) = mutex_inner.wait_queue.pop_front() { + add_task(waking_task); + } else { + mutex_inner.locked = false; + } + } + } + +- 第 8 行，调用 ID 为 ``mutex_id`` 的互斥锁 ``mutex`` 的 ``unlock`` 方法，具体工作由该方法来完成的。 +- 第 17-18 行，如果有等待的线程，唤醒等待最久的那个线程，相当于将锁的所有权移交给该线程。 +- 第 20 行，若没有线程等待，则释放锁。 + + diff --git a/guide/source/chapter8/3semaphore.rst b/guide/source/chapter8/3semaphore.rst new file mode 100644 index 0000000..3a5f529 --- /dev/null +++ b/guide/source/chapter8/3semaphore.rst @@ -0,0 +1,275 @@ +信号量机制 +========================================= + +本节导读 +----------------------------------------- + +.. chyyuu https://en.wikipedia.org/wiki/Semaphore_(programming) + +在上一节中，我们介绍了互斥锁（mutex 或 lock）的起因、使用和实现过程。通过互斥锁， +可以让线程在临界区执行时，独占临界资源。当我们需要更灵活的互斥访问或同步操作方式，如提供了最多只允许 +N 个线程访问临界资源的情况，让某个线程等待另外一个线程执行完毕后再继续执行的同步过程等， +互斥锁这种方式就有点力不从心了。 + +在本节中，将介绍功能更加强大和灵活的同步互斥机制 -- 信号量（Semaphore），它的设计思路、 +使用和在操作系统中的具体实现。可以看到，信号量的实现需要互斥锁和处理器原子指令的支持， +它是一种更高级的同步互斥机制。 + + +信号量的起源和基本思路 +----------------------------------------- + +1963 年前后，当时的数学家（其实是计算机科学家）Edsger Dijkstra 和他的团队在为 Electrologica X8 +计算机开发一个操作系统（称为 THE multiprogramming system，THE 多道程序系统）的过程中，提出了信号量 +（Semphore）是一种变量或抽象数据类型，用于控制多个线程对共同资源的访问。 + +信号量是对互斥锁的一种巧妙的扩展。上一节中的互斥锁的初始值一般设置为 1 的整型变量， +表示临界区还没有被某个线程占用。互斥锁用 0 表示临界区已经被占用了，用 1 表示临界区为空，再通过 +``lock/unlock`` 操作来协调多个线程轮流独占临界区执行。而信号量的初始值可设置为 N 的整数变量, 如果 N +大于 0， 表示最多可以有 N 个线程进入临界区执行，如果 N 小于等于 0 ，表示不能有线程进入临界区了， +必须在后续操作中让信号量的值加 1 ，才能唤醒某个等待的线程。 + +Dijkstra 对信号量设计了两种操作：P（Proberen（荷兰语），尝试）操作和 V（Verhogen（荷兰语），增加）操作。 +P 操作是检查信号量的值是否大于 0，若该值大于 0，则将其值减 1 并继续（表示可以进入临界区了）；若该值为 +0，则线程将睡眠。注意，此时 P 操作还未结束。而且由于信号量本身是一种临界资源（可回想一下上一节的锁， +其实也是一种临界资源），所以在 P 操作中，检查/修改信号量值以及可能发生的睡眠这一系列操作， +是一个不可分割的原子操作过程。通过原子操作才能保证，一旦 P 操作开始，则在该操作完成或阻塞睡眠之前， +其他线程均不允许访问该信号量。 + +V 操作会对信号量的值加 1 ，然后检查是否有一个或多个线程在该信号量上睡眠等待。如有， +则选择其中的一个线程唤醒并允许该线程继续完成它的 P 操作；如没有，则直接返回。注意，信号量的值加 1， +并可能唤醒一个线程的一系列操作同样也是不可分割的原子操作过程。不会有某个进程因执行 V 操作而阻塞。 + +如果信号量是一个任意的整数，通常被称为计数信号量（Counting Semaphore），或一般信号量（General +Semaphore）；如果信号量只有0或1的取值，则称为二值信号量（Binary Semaphore）。可以看出， +互斥锁是信号量的一种特例 --- 二值信号量，信号量很好地解决了最多允许 N 个线程访问临界资源的情况。 + +信号量的一种实现伪代码如下所示： + +.. code-block:: rust + :linenos: + + fn P(S) { + if S >= 1 + S = S - 1; + else + ; + } + fn V(S) { + if + ; + else + S = S + 1; + } + +在上述实现中，S 的取值范围为大于等于 0 的整数。S 的初值一般设置为一个大于 0 的正整数， +表示可以进入临界区的线程数。当 S 取值为 1，表示是二值信号量，也就是互斥锁了。 +使用信号量实现线程互斥访问临界区的伪代码如下： + +.. code-block:: rust + :linenos: + + let static mut S: semaphore = 1; + + // Thread i + fn foo() { + ... + P(S); + execute Cricital Section; + V(S); + ... + } + +下面是另外一种信号量实现的伪代码： + +.. code-block:: rust + :linenos: + + fn P(S) { + S = S - 1; + if S < 0 then + ; + } + + fn V(S) { + S = S + 1; + if + ; + } + +在这种实现中，S 的初值一般设置为一个大于 0 的正整数，表示可以进入临界区的线程数。但 S +的取值范围可以是小于 0 的整数，表示等待进入临界区的睡眠线程数。 + +信号量的另一种用途是用于实现同步（synchronization）。比如，把信号量的初始值设置为 0 ， +当一个线程 A 对此信号量执行一个 P 操作，那么该线程立即会被阻塞睡眠。之后有另外一个线程 B +对此信号量执行一个 V 操作，就会将线程 A 唤醒。这样线程 B 中执行 V 操作之前的代码序列 B-stmts +和线程 A 中执行 P 操作之后的代码 A-stmts 序列之间就形成了一种确定的同步执行关系，即线程 B 的 +B-stmts 会先执行，然后才是线程 A 的 A-stmts 开始执行。相关伪代码如下所示： + +.. code-block:: rust + :linenos: + + let static mut S: semaphore = 0; + + //Thread A + ... + P(S); + Label_2: + A-stmts after Thread B::Label_1; + ... + + //Thread B + ... + B-stmts before Thread A::Label_2; + Label_1: + V(S); + ... + + +实现信号量 +------------------------------------------ + +使用 semaphore 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +我们通过例子来看看如何实际使用信号量。下面是面向应用程序对信号量系统调用的简单使用， +可以看到对它的使用与上一节介绍的互斥锁系统调用类似。 + +在这个例子中，主线程先创建了信号量初值为 0 的信号量 ``SEM_SYNC`` ，然后再创建两个线程 First +和 Second 。线程 First 会先睡眠 10ms，而当线程 Second 执行时，会由于执行信号量的 P +操作而等待睡眠；当线程 First 醒来后，会执行 V 操作，从而能够唤醒线程 Second。这样线程 First +和线程 Second 就形成了一种稳定的同步关系。 + +.. code-block:: rust + :linenos: + :emphasize-lines: 5,10,16,22,25,28 + + const SEM_SYNC: usize = 0; //信号量ID + unsafe fn first() -> ! { + sleep(10); + println!("First work and wakeup Second"); + semaphore_up(SEM_SYNC); //信号量V操作 + exit(0) + } + unsafe fn second() -> ! { + println!("Second want to continue,but need to wait first"); + semaphore_down(SEM_SYNC); //信号量P操作 + println!("Second can work now"); + exit(0) + } + pub fn main() -> i32 { + // create semaphores + assert_eq!(semaphore_create(0) as usize, SEM_SYNC); // 信号量初值为0 + // create first, second threads + ... + } + + pub fn sys_semaphore_create(res_count: usize) -> isize { + syscall(SYSCALL_SEMAPHORE_CREATE, [res_count, 0, 0]) + } + pub fn sys_semaphore_up(sem_id: usize) -> isize { + syscall(SYSCALL_SEMAPHORE_UP, [sem_id, 0, 0]) + } + pub fn sys_semaphore_down(sem_id: usize) -> isize { + syscall(SYSCALL_SEMAPHORE_DOWN, [sem_id, 0, 0]) + } + + +- 第 16 行，创建了一个初值为 0 ，ID 为 ``SEM_SYNC`` 的信号量，对应的是第 22 行 + ``SYSCALL_SEMAPHORE_CREATE`` 系统调用； +- 第 10 行，线程 Second 执行信号量 P 操作（对应第 28行 ``SYSCALL_SEMAPHORE_DOWN`` + 系统调用），由于信号量初值为 0 ，该线程将阻塞； +- 第 5 行，线程 First 执行信号量 V 操作（对应第 25 行 ``SYSCALL_SEMAPHORE_UP`` 系统调用）， + 会唤醒等待该信号量的线程 Second。 + +实现 semaphore 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +操作系统如何实现信号量系统调用呢？我们还是采用通常的分析做法：数据结构+方法， +即首先考虑一下与此相关的核心数据结构，然后考虑与数据结构相关的相关函数/方法的实现。 + +在线程的眼里，信号量是一种每个线程能看到的共享资源，且在一个进程中，可以存在多个不同信号量资源， +所以我们可以把所有的信号量资源放在一起让进程来管理，如下面代码第 9 行所示。这里需要注意的是： +``semaphore_list: Vec>>`` 表示的是信号量资源的列表。而 ``Semaphore`` +是信号量的内核数据结构，由信号量值和等待队列组成。操作系统需要显式地施加某种控制，来确定当一个线程执行 +P 操作和 V 操作时，如何让线程睡眠或唤醒线程。在这里，P 操作是由 ``Semaphore`` 的 ``down`` +方法实现，而 V 操作是由 ``Semaphore`` 的 ``up`` 方法实现。 + +.. code-block:: rust + :linenos: + :emphasize-lines: 9,16,17,34-36,44-47 + + pub struct ProcessControlBlock { + // immutable + pub pid: PidHandle, + // mutable + inner: UPSafeCell, + } + pub struct ProcessControlBlockInner { + ... + pub semaphore_list: Vec>>, + } + + pub struct Semaphore { + pub inner: UPSafeCell, + } + pub struct SemaphoreInner { + pub count: isize, + pub wait_queue: VecDeque>, + } + impl Semaphore { + pub fn new(res_count: usize) -> Self { + Self { + inner: unsafe { UPSafeCell::new( + SemaphoreInner { + count: res_count as isize, + wait_queue: VecDeque::new(), + } + )}, + } + } + + pub fn up(&self) { + let mut inner = self.inner.exclusive_access(); + inner.count += 1; + if inner.count <= 0 { + if let Some(task) = inner.wait_queue.pop_front() { + add_task(task); + } + } + } + + pub fn down(&self) { + let mut inner = self.inner.exclusive_access(); + inner.count -= 1; + if inner.count < 0 { + inner.wait_queue.push_back(current_task().unwrap()); + drop(inner); + block_current_and_run_next(); + } + } + } + + +首先是核心数据结构： + +- 第 9 行，进程控制块中管理的信号量列表。 +- 第 16-17 行，信号量的核心数据成员：信号量值和等待队列。 + +然后是重要的三个成员函数： + +- 第 20 行，创建信号量，信号量初值为参数 ``res_count`` 。 +- 第 31 行，实现 V 操作的 ``up`` 函数，第 34 行，当信号量值小于等于 0 时， + 将从信号量的等待队列中弹出一个线程放入线程就绪队列。 +- 第 41 行，实现 P 操作的 ``down`` 函数，第 44 行，当信号量值小于 0 时， + 将把当前线程放入信号量的等待队列，设置当前线程为挂起状态并选择新线程执行。 + + +Dijkstra, Edsger W. Cooperating sequential processes (EWD-123) (PDF). E.W. Dijkstra Archive. +Center for American History, University of Texas at Austin. (transcription) (September 1965) +https://www.cs.utexas.edu/users/EWD/transcriptions/EWD01xx/EWD123.html + +Downey, Allen B. (2016) [2005]. "The Little Book of Semaphores" (2nd ed.). Green Tea Press. + +Leppäjärvi, Jouni (May 11, 2008). "A pragmatic, historically oriented survey on the universality +of synchronization primitives" (pdf). University of Oulu, Finland. \ No newline at end of file diff --git a/guide/source/chapter8/4condition-variable.rst b/guide/source/chapter8/4condition-variable.rst new file mode 100644 index 0000000..699fa1a --- /dev/null +++ b/guide/source/chapter8/4condition-variable.rst @@ -0,0 +1,300 @@ +条件变量机制 +========================================= + +本节导读 +----------------------------------------- + +到目前为止，我们已经了解了操作系统提供的互斥锁和信号量。但应用程序在使用这两者时需要非常小心， +如果使用不当，就会产生效率低下、竞态条件、死锁或者其他一些不可预测的情况。为了简化编程、避免错误， +计算机科学家针对某些情况设计了一种更高层的同步互斥原语。具体而言，在有些情况下， +线程需要检查某一条件（condition）满足之后，才会继续执行。 + +我们来看一个例子，有两个线程 first 和 second 在运行，线程 first 会把全局变量 A 设置为 +1，而线程 second 在 ``A != 0`` 的条件满足后，才能继续执行，如下面的伪代码所示： + +.. code-block:: rust + :linenos: + + static mut A: usize = 0; + unsafe fn first() -> ! { + A=1; + ... + } + + unsafe fn second() -> ! { + while A==0 { + // 忙等或睡眠等待 A==1 + }; + //继续执行相关事务 + } + +在上面的例子中，如果线程 second 先执行，会忙等在 while 循环中，在操作系统的调度下，线程 +first 会执行并把 A 赋值为 1 后，然后线程 second 再次执行时，就会跳出 while 循环，进行接下来的工作。 +配合互斥锁，可以正确完成上述带条件的同步流程，如下面的伪代码所示： + +.. code-block:: rust + :linenos: + + static mut A: usize = 0; + unsafe fn first() -> ! { + mutex.lock(); + A=1; + mutex.unlock(); + ... + } + + unsafe fn second() -> ! { + mutex.lock(); + while A==0 { + mutex.unlock(); + // give other thread a chance to lock + mutex.lock(); + }; + mutex.unlock(); + //继续执行相关事务 + } + +这种实现能执行，但效率低下，因为线程 second 会忙等检查，浪费处理器时间。我们希望有某种方式让线程 +second 休眠，直到等待的条件满足，再继续执行。于是，我们可以写出如下的代码： + +.. code-block:: rust + :linenos: + + static mut A: usize = 0; + unsafe fn first() -> ! { + mutex.lock(); + A=1; + wakup(second); + mutex.unlock(); + ... + } + + unsafe fn second() -> ! { + mutex.lock(); + while A==0 { + wait(); + }; + mutex.unlock(); + //继续执行相关事务 + } + +粗略地看，这样就可以实现睡眠等待了。但请同学仔细想想，当线程 second 在睡眠的时候， ``mutex`` +是否已经上锁了？ 确实，线程 second 是带着上锁的 ``mutex`` 进入等待睡眠状态的。 +如果这两个线程的调度顺序是先执行线程 second，再执行线程first，那么线程 second 会先睡眠且拥有 +``mutex`` 的锁；当线程 first 执行时，会由于没有 ``mutex`` 的锁而进入等待锁的睡眠状态。 +结果就是两个线程都睡了，都执行不下去，这就出现了 **死锁** 。 + +这里需要解决的两个关键问题： **如何等待一个条件？** 和 **在条件为真时如何向等待线程发出信号** 。 +我们的计算机科学家给出了 **管程（Monitor）** 和 **条件变量（Condition Variables）** +这种巧妙的方法。接下来，我们就会深入讲解条件变量的设计与实现。 + +条件变量的基本思路 +------------------------------------------- + +管程有一个很重要的特性，即任一时刻只能有一个活跃线程调用管程中的过程， +这一特性使线程在调用执行管程中过程时能保证互斥，这样线程就可以放心地访问共享变量。 +管程是编程语言的组成部分，编译器知道其特殊性，因此可以采用与其他过程调用不同的方法来处理对管程的调用. +因为是由编译器而非程序员来生成互斥相关的代码，所以出错的可能性要小。 + +管程虽然借助编译器提供了一种实现互斥的简便途径，但这还不够，还需要一种线程间的沟通机制。 +首先是等待机制：由于线程在调用管程中某个过程时，发现某个条件不满足，那就在无法继续运行而被阻塞。 +其次是唤醒机制：另外一个线程可以在调用管程的过程中，把某个条件设置为真，并且还需要有一种机制， +及时唤醒等待条件为真的阻塞线程。为了避免管程中同时有两个活跃线程， +我们需要一定的规则来约定线程发出唤醒操作的行为。目前有三种典型的规则方案： + +- Hoare 语义：线程发出唤醒操作后，马上阻塞自己，让新被唤醒的线程运行。注：此时唤醒线程的执行位置还在管程中。 +- Hansen 语义：是执行唤醒操作的线程必须立即退出管程，即唤醒操作只可能作为一个管程过程的最后一条语句。 + 注：此时唤醒线程的执行位置离开了管程。 +- Mesa 语义：唤醒线程在发出行唤醒操作后继续运行，并且只有它退出管程之后，才允许等待的线程开始运行。 + 注：此时唤醒线程的执行位置还在管程中。 + +一般开发者会采纳 Brinch Hansen 的建议，因为它在概念上更简单，并且更容易实现。这种沟通机制的具体实现就是 +**条件变量** 和对应的操作：wait 和 signal。线程使用条件变量来等待一个条件变成真。 +条件变量其实是一个线程等待队列，当条件不满足时，线程通过执行条件变量的 wait +操作就可以把自己加入到等待队列中，睡眠等待（waiting）该条件。另外某个线程，当它改变条件为真后， +就可以通过条件变量的 signal 操作来唤醒一个或者多个等待的线程（通过在该条件上发信号），让它们继续执行。 + +早期提出的管程是基于 Concurrent Pascal 来设计的，其他语言如 C 和 Rust 等，并没有在语言上支持这种机制。 +我们还是可以用手动加入互斥锁的方式来代替编译器，就可以在 C 和 Rust 的基础上实现原始的管程机制了。 +在目前的 C 语言应用开发中，实际上也是这么做的。这样，我们就可以用互斥锁和条件变量， +来重现上述的同步互斥例子： + +.. code-block:: rust + :linenos: + + static mut A: usize = 0; + unsafe fn first() -> ! { + mutex.lock(); + A=1; + condvar.wakup(); + mutex.unlock(); + ... + } + + unsafe fn second() -> ! { + mutex.lock(); + while A==0 { + condvar.wait(mutex); //在睡眠等待之前，需要释放mutex + }; + mutex.unlock(); + //继续执行相关事务 + } + +有了上面的介绍，我们就可以实现条件变量的基本逻辑了。下面是条件变量的 wait 和 signal 操作的伪代码： + +.. code-block:: rust + :linenos: + + fn wait(mutex) { + mutex.unlock(); + ; + mutex.lock(); + } + + fn signal() { + ; + } + +条件变量的wait操作包含三步，1. 释放锁；2. 把自己挂起；3. 被唤醒后，再获取锁。条件变量的 signal +操作只包含一步：找到挂在条件变量上睡眠的线程，把它唤醒。 + +注意，条件变量不像信号量那样有一个整型计数值的成员变量，所以条件变量也不能像信号量那样有读写计数值的能力。 +如果一个线程向一个条件变量发送唤醒操作，但是在该条件变量上并没有等待的线程，则唤醒操作实际上什么也没做。 + +实现条件变量 +------------------------------------------- + +使用 condvar 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +我们通过例子来看看如何实际使用条件变量。下面是面向应用程序对条件变量系统调用的简单使用， +可以看到对它的使用与上一节介绍的信号量系统调用类似。 在这个例子中，主线程先创建了初值为 1 +的互斥锁和一个条件变量，然后再创建两个线程 First 和 Second。线程 First 会先睡眠 10ms，而当线程 +Second 执行时，会由于条件不满足执行条件变量的 wait 操作而等待睡眠；当线程 First 醒来后，通过设置 +A 为 1，让线程 second 等待的条件满足，然后会执行条件变量的 signal 操作，从而能够唤醒线程 Second。 +这样线程 First 和线程 Second 就形成了一种稳定的同步与互斥关系。 + +.. code-block:: rust + :linenos: + :emphasize-lines: 11,19,26,33,36,39 + + static mut A: usize = 0; //全局变量 + + const CONDVAR_ID: usize = 0; + const MUTEX_ID: usize = 0; + + unsafe fn first() -> ! { + sleep(10); + println!("First work, Change A --> 1 and wakeup Second"); + mutex_lock(MUTEX_ID); + A=1; + condvar_signal(CONDVAR_ID); + mutex_unlock(MUTEX_ID); + ... + } + unsafe fn second() -> ! { + println!("Second want to continue,but need to wait A=1"); + mutex_lock(MUTEX_ID); + while A==0 { + condvar_wait(CONDVAR_ID, MUTEX_ID); + } + mutex_unlock(MUTEX_ID); + ... + } + pub fn main() -> i32 { + // create condvar & mutex + assert_eq!(condvar_create() as usize, CONDVAR_ID); + assert_eq!(mutex_blocking_create() as usize, MUTEX_ID); + // create first, second threads + ... + } + + pub fn condvar_create() -> isize { + sys_condvar_create(0) + } + pub fn condvar_signal(condvar_id: usize) { + sys_condvar_signal(condvar_id); + } + pub fn condvar_wait(condvar_id: usize, mutex_id: usize) { + sys_condvar_wait(condvar_id, mutex_id); + } + +- 第 26 行，创建了一个 ID 为 ``CONDVAR_ID`` 的条件量，对应第 33 行 ``SYSCALL_CONDVAR_CREATE`` 系统调用； +- 第 19 行，线程 Second 执行条件变量 ``wait`` 操作（对应第 39 行 ``SYSCALL_CONDVAR_WAIT`` 系统调用）， + 该线程将释放 ``mutex`` 锁并阻塞； +- 第 5 行，线程 First 执行条件变量 ``signal`` 操作（对应第 36 行 ``SYSCALL_CONDVAR_SIGNAL`` 系统调用）， + 会唤醒等待该条件变量的线程 Second。 + + +实现 condvar 系统调用 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +操作系统如何实现条件变量系统调用呢？在线程的眼里，条件变量是一种每个线程能看到的共享资源， +且在一个进程中，可以存在多个不同条件变量资源，所以我们可以把所有的条件变量资源放在一起让进程来管理， +如下面代码第9行所示。这里需要注意的是： ``condvar_list: Vec>>`` +表示的是条件变量资源的列表。而 ``Condvar`` 是条件变量的内核数据结构，由等待队列组成。 +操作系统需要显式地施加某种控制，来确定当一个线程执行 ``wait`` 操作和 ``signal`` 操作时， +如何让线程睡眠或唤醒线程。在这里， ``wait`` 操作是由 ``Condvar`` 的 ``wait`` 方法实现，而 ``signal`` +操作是由 ``Condvar`` 的 ``signal`` 方法实现。 + +.. code-block:: rust + :linenos: + :emphasize-lines: 9,15,18,27,33 + + pub struct ProcessControlBlock { + // immutable + pub pid: PidHandle, + // mutable + inner: UPSafeCell, + } + pub struct ProcessControlBlockInner { + ... + pub condvar_list: Vec>>, + } + pub struct Condvar { + pub inner: UPSafeCell, + } + pub struct CondvarInner { + pub wait_queue: VecDeque>, + } + impl Condvar { + pub fn new() -> Self { + Self { + inner: unsafe { UPSafeCell::new( + CondvarInner { + wait_queue: VecDeque::new(), + } + )}, + } + } + pub fn signal(&self) { + let mut inner = self.inner.exclusive_access(); + if let Some(task) = inner.wait_queue.pop_front() { + add_task(task); + } + } + pub fn wait(&self, mutex:Arc) { + mutex.unlock(); + let mut inner = self.inner.exclusive_access(); + inner.wait_queue.push_back(current_task().unwrap()); + drop(inner); + block_current_and_run_next(); + mutex.lock(); + } + } + +首先是核心数据结构： + +- 第 9 行，进程控制块中管理的条件变量列表。 +- 第 15 行，条件变量的核心数据成员：等待队列。 + +然后是重要的三个成员函数： + +- 第 18 行，创建条件变量，即创建了一个空的等待队列。 +- 第 27 行，实现 ``signal`` 操作，将从条件变量的等待队列中弹出一个线程放入线程就绪队列。 +- 第 33 行，实现 ``wait`` 操作，释放 ``mutex`` 互斥锁，将把当前线程放入条件变量的等待队列， + 设置当前线程为挂起状态并选择新线程执行。在恢复执行后，再加上 ``mutex`` 互斥锁。 + +Hansen, Per Brinch (1993). "Monitors and concurrent Pascal: a personal history". HOPL-II: +The second ACM SIGPLAN conference on History of programming languages. History of Programming +Languages. New York, NY, USA: ACM. pp. 1–35. doi:10.1145/155360.155361. ISBN 0-89791-570-4. \ No newline at end of file diff --git a/guide/source/chapter8/5exercise.rst b/guide/source/chapter8/5exercise.rst new file mode 100644 index 0000000..5c99687 --- /dev/null +++ b/guide/source/chapter8/5exercise.rst @@ -0,0 +1,132 @@ +chapter8 练习 +======================================= + +编程作业 +-------------------------------------- + +.. warning:: + + 本次实验框架变动较大，且改动较为复杂，为降低同学们的工作量，本次实验不要求合并之前的实验内容， + 只需通过 ch8 的全部测例和其他章节的基础测例即可。你可以直接在实验框架的 ch8 分支上完成以下作业。 + +.. note:: + + 本次实验的工作量约为 100 行代码。 + + +死锁检测 ++++++++++++++++++++++++++++++++ + +目前的 mutex 和 semaphore 相关的系统调用不会分析资源的依赖情况，用户程序可能出现死锁。 +我们希望在系统中加入死锁检测机制，当发现可能发生死锁时拒绝对应的资源获取请求。 +一种检测死锁的算法如下： + +定义如下三个数据结构： + +- 可利用资源向量 Available ：含有 m 个元素的一维数组，每个元素代表可利用的某一类资源的数目， + 其初值是该类资源的全部可用数目，其值随该类资源的分配和回收而动态地改变。 + Available[j] = k，表示第 j 类资源的可用数量为 k。 +- 分配矩阵 Allocation：n * m 矩阵，表示每类资源已分配给每个线程的资源数。 + Allocation[i,j] = g，则表示线程 i 当前己分得第 j 类资源的数量为 g。 +- 需求矩阵 Need：n * m 的矩阵，表示每个线程还需要的各类资源数量。 + Need[i,j] = d，则表示线程 i 还需要第 j 类资源的数量为 d 。 + +算法运行过程如下： + +1. 设置两个向量: 工作向量 Work，表示操作系统可提供给线程继续运行所需的各类资源数目，它含有 + m 个元素。初始时，Work = Available ；结束向量 Finish，表示系统是否有足够的资源分配给线程， + 使之运行完成。初始时 Finish[0..n-1] = false，表示所有线程都没结束；当有足够资源分配给线程时， + 设置 Finish[i] = true。 +2. 从线程集合中找到一个能满足下述条件的线程 + +.. code-block:: Rust + :linenos: + + Finish[i] == false; + Need[i,j] ≤ Work[j]; + +若找到，执行步骤 3，否则执行步骤 4。 + +3. 当线程 thr[i] 获得资源后，可顺利执行，直至完成，并释放出分配给它的资源，故应执行: + +.. code-block:: Rust + :linenos: + + Work[j] = Work[j] + Allocation[i, j]; + Finish[i] = true; + +跳转回步骤2 + +4. 如果 Finish[0..n-1] 都为 true，则表示系统处于安全状态；否则表示系统处于不安全状态，即出现死锁。 + +出于兼容性和灵活性考虑，我们允许进程按需开启或关闭死锁检测功能。为此我们将实现一个新的系统调用： +``sys_enable_deadlock_detect`` 。 + +**enable_deadlock_detect**： + +* syscall ID: 469 +* 功能：为当前进程启用或禁用死锁检测功能。 +* C 接口： ``int enable_deadlock_detect(int is_enable)`` +* Rust 接口： ``fn enable_deadlock_detect(is_enable: i32) -> i32`` +* 参数： + * is_enable: 为 1 表示启用死锁检测， 0 表示禁用死锁检测。 +* 说明： + * 开启死锁检测功能后， ``mutex_lock`` 和 ``semaphore_down`` 如果检测到死锁， + 应拒绝相应操作并返回 -0xDEAD (十六进制值)。 + * 简便起见可对 mutex 和 semaphore 分别进行检测，无需考虑二者 (以及 ``waittid`` 等) + 混合使用导致的死锁。 +* 返回值：如果出现了错误则返回 -1，否则返回 0。 +* 可能的错误 + * 参数不合法 + * 死锁检测开启失败 + + +实验要求 ++++++++++++++++++++++++++++++++++++++++++ + +- 完成分支: ch8。 +- 实验目录要求不变。 +- 通过所有测例。 + +问答作业 +-------------------------------------------- + +1. 在我们的多线程实现中，当主线程 (即 0 号线程) 退出时，视为整个进程退出， + 此时需要结束该进程管理的所有线程并回收其资源。 + - 需要回收的资源有哪些？ + - 其他线程的 TaskControlBlock 可能在哪些位置被引用，分别是否需要回收，为什么？ +2. 对比以下两种 ``Mutex.unlock`` 的实现，二者有什么区别？这些区别可能会导致什么问题？ + +.. code-block:: Rust + :linenos: + + impl Mutex for Mutex1 { + fn unlock(&self) { + let mut mutex_inner = self.inner.exclusive_access(); + assert!(mutex_inner.locked); + mutex_inner.locked = false; + if let Some(waking_task) = mutex_inner.wait_queue.pop_front() { + add_task(waking_task); + } + } + } + + impl Mutex for Mutex2 { + fn unlock(&self) { + let mut mutex_inner = self.inner.exclusive_access(); + assert!(mutex_inner.locked); + if let Some(waking_task) = mutex_inner.wait_queue.pop_front() { + add_task(waking_task); + } else { + mutex_inner.locked = false; + } + } + } + + +报告要求 +------------------------------- + +- 简单总结你实现的功能（200字以内，不要贴代码）及你完成本次实验所用的时间。 +- 完成问答题。 +- (optional) 你对本次实验设计及难度/工作量的看法，以及有哪些需要改进的地方，欢迎畅所欲言。 diff --git a/guide/source/chapter8/index.rst b/guide/source/chapter8/index.rst new file mode 100644 index 0000000..a89f945 --- /dev/null +++ b/guide/source/chapter8/index.rst @@ -0,0 +1,15 @@ +第八章：并发 +============================================== + +.. toctree:: + :maxdepth: 4 + + 0intro + 1thread-kernel + 2lock + 3semaphore + 4condition-variable + 5exercise + +.. chyyuu + 扩展章节，添加其他类型同步互斥的介绍 \ No newline at end of file diff --git a/guide/source/conf.py b/guide/source/conf.py new file mode 100644 index 0000000..f6be921 --- /dev/null +++ b/guide/source/conf.py @@ -0,0 +1,120 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'rCore-Tutorial-Guide-2022S' +copyright = 'OS2022Spring' +author = 'Yifan Wu' +language = 'zh_CN' +html_search_language = 'zh' + +# The full version, including alpha/beta/rc tags +# release = '0.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx_comments", + "sphinx_tabs.tabs" +] + +comments_config = { + "utterances": { + "repo": "LearningOS/rCore-Tutorial-Guide-2022S", + "issue-term": "pathname", + "label": "comments", + "theme": "github-light", + "crossorigin": "anonymous", + } +} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'furo' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +html_css_files = [ + 'my_style.css', + #'dracula.css', +] + +from pygments.lexer import RegexLexer +from pygments import token +from sphinx.highlighting import lexers + +class RVLexer(RegexLexer): + name = 'riscv' + tokens = { + 'root': [ + # Comment + (r'#.*\n', token.Comment), + # General Registers + (r'\b(?:x[1-2]?[0-9]|x30|x31|zero|ra|sp|gp|tp|fp|t[0-6]|s[0-9]|s1[0-1]|a[0-7]|pc)\b', token.Name.Attribute), + # CSRs + (r'\bs(?:status|tvec|ip|ie|counteren|scratch|epc|cause|tval|atp|)\b', token.Name.Constant), + (r'\bm(?:isa|vendorid|archid|hardid|status|tvec|ideleg|ip|ie|counteren|scratch|epc|cause|tval)\b', token.Name.Constant), + # Instructions + (r'\b(?:(addi?w?)|(slti?u?)|(?:and|or|xor)i?|(?:sll|srl|sra)i?w?|lui|auipc|subw?|jal|jalr|beq|bne|bltu?|bgeu?|s[bhwd]|(l[bhw]u?)|ld)\b', token.Name.Decorator), + (r'\b(?:csrr?[rws]i?)\b', token.Name.Decorator), + (r'\b(?:ecall|ebreak|[msu]ret|wfi|sfence.vma)\b', token.Name.Decorator), + (r'\b(?:nop|li|la|mv|not|neg|negw|sext.w|seqz|snez|sltz|sgtz|f(?:mv|abs|neg).(?:s|d)|b(?:eq|ne|le|ge|lt)z|bgt|ble|bgtu|bleu|j|jr|ret|call)\b', token.Name.Decorator), + (r'(?:%hi|%lo|%pcrel_hi|%pcrel_lo|%tprel_(?:hi|lo|add))', token.Name.Decorator), + # Directives + (r'(?:.2byte|.4byte|.8byte|.quad|.half|.word|.dword|.byte|.dtpreldword|.dtprelword|.sleb128|.uleb128|.asciz|.string|.incbin|.zero)', token.Name.Function), + (r'(?:.align|.balign|.p2align)', token.Name.Function), + (r'(?:.globl|.local|.equ)', token.Name.Function), + (r'(?:.text|.data|.rodata|.bss|.comm|.common|.section)', token.Name.Function), + (r'(?:.option|.macro|.endm|.file|.ident|.size|.type)', token.Name.Function), + (r'(?:.set|.rept|.endr|.macro|.endm|.altmacro)', token.Name.Function), + # Number + (r'\b(?:(?:0x|)[\da-f]+|(?:0o|)[0-7]+|\d+)\b', token.Number), + # Labels + (r'\S+:', token.Name.Builtin), + # Whitespace + (r'\s', token.Whitespace), + # Other operators + (r'[,\+\*\-\(\)\\%]', token.Text), + # Hacks + (r'(?:SAVE_GP|trap_handler|__switch|LOAD_GP|SAVE_SN|LOAD_SN|__alltraps|__restore)', token.Name.Builtin), + (r'(?:.trampoline)', token.Name.Function), + (r'(?:n)', token.Name.Entity), + (r'(?:x)', token.Text), + ], + } + +lexers['riscv'] = RVLexer() diff --git a/guide/source/index.rst b/guide/source/index.rst new file mode 100644 index 0000000..2e3affd --- /dev/null +++ b/guide/source/index.rst @@ -0,0 +1,85 @@ +.. rCore-Tutorial-Guide-2022S documentation master file, created by + sphinx-quickstart on Thu Oct 29 22:25:54 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +rCore-Tutorial-Guide 2022 春季学期 +================================================== + +.. toctree:: + :maxdepth: 2 + :caption: 正文 + :hidden: + + 0setup-devel-env + chapter1/index + chapter2/index + chapter3/index + chapter4/index + chapter5/index + chapter6/index + chapter7/index + chapter8/index + +.. toctree:: + :maxdepth: 2 + :caption: 附录 + :hidden: + + appendix-a/index + appendix-b/index + appendix-c/index + appendix-d/index + +.. toctree:: + :maxdepth: 2 + :caption: 开发注记 + :hidden: + + setup-sphinx + rest-example + + +项目简介 +--------------------- + +本教程展示了如何 **从零开始** 用 **Rust** 语言写一个基于 **RISC-V** 架构的 **类 Unix 内核** 。 + +用于 2022 年春季学期操作系统课堂教学。 + +导读 +--------------------- + +请先阅读 :doc:`0setup-devel-env` 完成环境配置。 + +以下是读者为了完成实验需掌握的技术，你可以在实操中熟悉它们。 + +- 阅读简单的 Makefile 文件； +- 阅读简单的 RISC-V 汇编代码； +- git 的基本功能，解决 git merge 冲突的办法； +- Rust 基本语法和一些进阶语法，包括 **Cargo 项目结构、Trait、函数式编程、Unsafe Rust、错误处理等** 。 + +鸣谢 +---------------------- +本项目基于 `2021 年秋季学期操作系统实验指导书 `_ ，重构的目标是在保留结构的基础上屏蔽不必要的细节，缩短篇幅，优化语言，降低阅读成本。 + +如果你觉得本教程某些章节不够细致或不够连贯，可以参考上学期实验指导书的对应章节。 + +.. note:: + + 这是一个注解，以这种方式出现的卡片提供了非必要的背景知识，你可以选择忽略。 + + +.. attention:: + + 虽然实验本身在总评中占比有限，但根据往届经验，考试中可能大量出现与编程作业、思考题、代码实现思路直接相关的题目。 + + +项目协作 +---------------------- + +- :doc:`/setup-sphinx` 介绍了如何基于 Sphinx 框架配置文档开发环境，之后可以本地构建并渲染 html 或其他格式的文档； +- :doc:`/rest-example` 给出了目前编写文档才用的 ReStructuredText 标记语言的一些基础语法及用例； +- 时间仓促，本项目还有很多不完善之处，欢迎大家积极在每一个章节的评论区留言，或者提交 Issues 或 Pull Requests，让我们 + 一起努力让这本书变得更好！ + diff --git a/guide/source/pygments-coloring.txt b/guide/source/pygments-coloring.txt new file mode 100644 index 0000000..09c2cb5 --- /dev/null +++ b/guide/source/pygments-coloring.txt @@ -0,0 +1,32 @@ +Pygments 默认配色： +Keyword.Constant 深绿加粗 +Keyword.Declaration 深绿加粗 +Keyword.Namespace 深绿加粗 +Keyword.Pseudo 浅绿 +Keyword.Reserved 深绿加粗 +Keyword.Type 樱桃红 +Name.Attribute 棕黄 +Name.Builtin 浅绿 +Name.Builtin.Pseudo 浅绿 +Name.Class 深蓝加粗 +Name.Constant 棕红 +Name.Decorator 浅紫 +Name.Entity 灰色 +Name.Exception 深红 +Name.Function 深蓝 +Name.Function.Magic 深蓝 +Name.Label 棕黄 +Name.Namespace 深蓝加粗 +Name.Other 默认黑色 +Name.Tag 深绿加粗 +Name.Variable 蓝黑 + + +通用寄存器 -> 棕黄 Name.Attribute +CSR -> 棕红 Name.Constant +指令 -> 浅紫 Name.Decorator +伪指令 -> 樱桃红 Keyword.Type +Directives -> 深蓝 Name.Function +标签/剩余字面量 -> 浅绿 Name.Builtin +数字 -> Number + diff --git a/guide/source/rest-example.rst b/guide/source/rest-example.rst new file mode 100644 index 0000000..dbaa0dc --- /dev/null +++ b/guide/source/rest-example.rst @@ -0,0 +1,76 @@ +reStructuredText 基本语法 +===================================================== + +.. toctree:: + :hidden: + :maxdepth: 4 + +.. note:: + 下面是一个注记。 + + `这里 `_ 给出了在 Sphinx 中 + 外部链接的引入方法。注意，链接的名字和用一对尖括号包裹起来的链接地址之间必须有一个空格。链接最后的下划线和片段的后续内容之间也需要 + 有一个空格。 + + 接下来是一个文档内部引用的例子。比如，戳 :doc:`chapter0/5setup-devel-env` 可以进入快速上手环节。 + +.. warning:: + + 下面是一个警告。 + + .. code-block:: rust + :linenos: + :caption: 一段示例 Rust 代码 + + // 我们甚至可以插入一段 Rust 代码！ + fn add(a: i32, b: i32) -> i32 { a + b } + + 下面继续我们的警告。 + +.. attention:: Here is an attention. + +.. caution:: please be cautious! + +.. error:: + + 下面是一个错误。 + +.. danger:: it is dangerous! + + +.. tip:: here is a tip + +.. important:: this is important! + +.. hint:: this is a hint. + + + +这里是一行数学公式 :math:`\sin(\alpha+\beta)=\sin\alpha\cos\beta+\cos\alpha\sin\beta`。 + +基本的文本样式：这是 *斜体* ，这是 **加粗** ，接下来的则是行间公式 ``a0`` 。它们的前后都需要有一个空格隔开其他内容，这个让人挺不爽的... + +`这是 `_ 一个全面展示 +章节分布的例子，来自于 ReadTheDocs 的官方文档。事实上，现在我们也采用 ReadTheDocs 主题了，它非常美观大方。 + +下面是一个测试 gif。 + +.. image:: resources/test.gif + +接下来是一个表格的例子。 + +.. list-table:: RISC-V 函数调用跳转指令 + :widths: 20 30 + :header-rows: 1 + :align: center + + * - 指令 + - 指令功能 + * - :math:`\text{jal}\ \text{rd},\ \text{imm}[20:1]` + - :math:`\text{rd}\leftarrow\text{pc}+4` + + :math:`\text{pc}\leftarrow\text{pc}+\text{imm}` + * - :math:`\text{jalr}\ \text{rd},\ (\text{imm}[11:0])\text{rs}` + - :math:`\text{rd}\leftarrow\text{pc}+4` + + :math:`\text{pc}\leftarrow\text{rs}+\text{imm}` \ No newline at end of file diff --git a/guide/source/setup-sphinx.rst b/guide/source/setup-sphinx.rst new file mode 100644 index 0000000..850fcce --- /dev/null +++ b/guide/source/setup-sphinx.rst @@ -0,0 +1,16 @@ +修改和构建本项目 +==================================== + +.. toctree:: + :hidden: + :maxdepth: 4 + +TL;DR: ``python -m venv .venv`` 创建一个虚拟环境（你也可以使用 conda 等工具），activate 后 ``pip install -r requirements.txt``。 + +1. 参考 `这里 `_ 安装 Sphinx。 +2. ``pip install sphinx_rtd_theme`` 安装 Read The Docs 主题。 +3. ``pip install jieba`` 安装中文分词。 +4. ``pip install sphinx-comments`` 安装 Sphinx 讨论区插件。 +5. :doc:`/rest-example` 是 ReST 的一些基本语法，也可以参考已完成的文档。 +6. 修改之后，在项目根目录下 ``make clean && make html`` 即可在 ``build/html/index.html`` 查看本地构建的主页。请注意在修改章节目录结构之后需要 ``make clean`` 一下，不然可能无法正常更新。 +7. 确认修改无误之后，将更改提交到自己的仓库，然后向项目仓库提交 Pull Request。如有问题，可直接提交 Issue 或课程微信群内联系助教。 diff --git a/os1-ref/.cargo/config b/os1-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os1-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os1-ref/Cargo.toml b/os1-ref/Cargo.toml new file mode 100644 index 0000000..ef61cb9 --- /dev/null +++ b/os1-ref/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +log = "0.4" diff --git a/os1-ref/Makefile b/os1-ref/Makefile new file mode 100644 index 0000000..53e0591 --- /dev/null +++ b/os1-ref/Makefile @@ -0,0 +1,49 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +build: env $(KERNEL_BIN) + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +kernel: + @cargo build --release + +clean: + @cargo clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean run-inner diff --git a/os1-ref/src/console.rs b/os1-ref/src/console.rs new file mode 100644 index 0000000..632e662 --- /dev/null +++ b/os1-ref/src/console.rs @@ -0,0 +1,37 @@ +/*！ + +本模块实现了 print 和 println 宏。 + +*/ + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} diff --git a/os1-ref/src/entry.asm b/os1-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os1-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os1-ref/src/lang_items.rs b/os1-ref/src/lang_items.rs new file mode 100644 index 0000000..a6217a0 --- /dev/null +++ b/os1-ref/src/lang_items.rs @@ -0,0 +1,17 @@ +use crate::sbi::shutdown; +use core::panic::PanicInfo; + +#[panic_handler] +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println!( + "Panicked at {}:{} {}", + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println!("Panicked: {}", info.message().unwrap()); + } + shutdown() +} diff --git a/os1-ref/src/linker.ld b/os1-ref/src/linker.ld new file mode 100644 index 0000000..8bcce1a --- /dev/null +++ b/os1-ref/src/linker.ld @@ -0,0 +1,48 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os1-ref/src/logging.rs b/os1-ref/src/logging.rs new file mode 100644 index 0000000..7b7cc56 --- /dev/null +++ b/os1-ref/src/logging.rs @@ -0,0 +1,47 @@ +/*！ + +本模块利用 log crate 为你提供了日志功能，使用方式见 main.rs. + +*/ + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os1-ref/src/main.rs b/os1-ref/src/main.rs new file mode 100644 index 0000000..f3b68eb --- /dev/null +++ b/os1-ref/src/main.rs @@ -0,0 +1,49 @@ +#![no_std] +#![no_main] +#![feature(panic_info_message)] + +use log::*; + +#[macro_use] +mod console; +mod lang_items; +mod logging; +mod sbi; + +core::arch::global_asm!(include_str!("entry.asm")); + +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + (sbss as usize..ebss as usize).for_each(|a| unsafe { (a as *mut u8).write_volatile(0) }); +} + +#[no_mangle] +pub fn rust_main() -> ! { + extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss(); + fn ebss(); + fn boot_stack(); + fn boot_stack_top(); + } + clear_bss(); + logging::init(); + println!("Hello, world!"); + trace!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + debug!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + info!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + warn!( + "boot_stack [{:#x}, {:#x})", + boot_stack as usize, boot_stack_top as usize + ); + error!(".bss [{:#x}, {:#x})", sbss as usize, ebss as usize); + panic!("Shutdown machine!"); +} diff --git a/os1-ref/src/sbi.rs b/os1-ref/src/sbi.rs new file mode 100644 index 0000000..751a4d2 --- /dev/null +++ b/os1-ref/src/sbi.rs @@ -0,0 +1,34 @@ +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os2-ref/.cargo/config b/os2-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os2-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os2-ref/Cargo.toml b/os2-ref/Cargo.toml new file mode 100644 index 0000000..7ddc171 --- /dev/null +++ b/os2-ref/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } diff --git a/os2-ref/Makefile b/os2-ref/Makefile new file mode 100644 index 0000000..59f3000 --- /dev/null +++ b/os2-ref/Makefile @@ -0,0 +1,58 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -oP 'ch\K[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +disasm: + @$(OBJDUMP) $(KERNEL_ELF) -S > $(KERNEL_ELF).asm + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean run-inner diff --git a/os2-ref/build.rs b/os2-ref/build.rs new file mode 100644 index 0000000..4a44c56 --- /dev/null +++ b/os2-ref/build.rs @@ -0,0 +1,56 @@ +use std::fs::{read_dir, File}; +use std::io::{Result, Write}; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); + insert_app_data().unwrap(); +} + +static TARGET_PATH: &str = "../user/build/bin/"; + +fn insert_app_data() -> Result<()> { + let mut f = File::create("src/link_app.S").unwrap(); + let mut apps: Vec<_> = read_dir("../user/build/bin/") + .unwrap() + .into_iter() + .map(|dir_entry| { + let mut name_with_ext = dir_entry.unwrap().file_name().into_string().unwrap(); + name_with_ext.drain(name_with_ext.find('.').unwrap()..name_with_ext.len()); + name_with_ext + }) + .collect(); + apps.sort(); + + writeln!( + f, + r#" + .align 3 + .section .data + .global _num_app +_num_app: + .quad {}"#, + apps.len() + )?; + + for i in 0..apps.len() { + writeln!(f, r#" .quad app_{}_start"#, i)?; + } + writeln!(f, r#" .quad app_{}_end"#, apps.len() - 1)?; + + for (idx, app) in apps.iter().enumerate() { + println!("app_{}: {}", idx, app); + writeln!( + f, + r#" + .section .data + .global app_{0}_start + .global app_{0}_end +app_{0}_start: + .incbin "{2}{1}.bin" +app_{0}_end:"#, + idx, app, TARGET_PATH + )?; + } + Ok(()) +} diff --git a/os2-ref/src/batch.rs b/os2-ref/src/batch.rs new file mode 100644 index 0000000..7f97793 --- /dev/null +++ b/os2-ref/src/batch.rs @@ -0,0 +1,141 @@ +use crate::sync::UPSafeCell; +use crate::trap::TrapContext; +use lazy_static::*; + +const USER_STACK_SIZE: usize = 4096; +const KERNEL_STACK_SIZE: usize = 4096 * 2; +const MAX_APP_NUM: usize = 16; +const APP_BASE_ADDRESS: usize = 0x80400000; +const APP_SIZE_LIMIT: usize = 0x20000; + +#[repr(align(4096))] +struct KernelStack { + data: [u8; KERNEL_STACK_SIZE], +} + +#[repr(align(4096))] +struct UserStack { + data: [u8; USER_STACK_SIZE], +} + +static KERNEL_STACK: KernelStack = KernelStack { + data: [0; KERNEL_STACK_SIZE], +}; +static USER_STACK: UserStack = UserStack { + data: [0; USER_STACK_SIZE], +}; + +impl KernelStack { + fn get_sp(&self) -> usize { + self.data.as_ptr() as usize + KERNEL_STACK_SIZE + } + pub fn push_context(&self, cx: TrapContext) -> &'static mut TrapContext { + let cx_ptr = (self.get_sp() - core::mem::size_of::()) as *mut TrapContext; + unsafe { + *cx_ptr = cx; + } + unsafe { cx_ptr.as_mut().unwrap() } + } +} + +impl UserStack { + fn get_sp(&self) -> usize { + self.data.as_ptr() as usize + USER_STACK_SIZE + } +} + +struct AppManager { + num_app: usize, + current_app: usize, + app_start: [usize; MAX_APP_NUM + 1], +} + +impl AppManager { + pub fn print_app_info(&self) { + info!("[kernel] num_app = {}", self.num_app); + for i in 0..self.num_app { + info!( + "[kernel] app_{} [{:#x}, {:#x})", + i, + self.app_start[i], + self.app_start[i + 1] + ); + } + } + + unsafe fn load_app(&self, app_id: usize) { + if app_id >= self.num_app { + panic!("All applications completed!"); + } + info!("[kernel] Loading app_{}", app_id); + // clear icache + core::arch::asm!("fence.i"); + // clear app area + core::slice::from_raw_parts_mut(APP_BASE_ADDRESS as *mut u8, APP_SIZE_LIMIT).fill(0); + let app_src = core::slice::from_raw_parts( + self.app_start[app_id] as *const u8, + self.app_start[app_id + 1] - self.app_start[app_id], + ); + let app_dst = core::slice::from_raw_parts_mut(APP_BASE_ADDRESS as *mut u8, app_src.len()); + app_dst.copy_from_slice(app_src); + } + + pub fn get_current_app(&self) -> usize { + self.current_app + } + + pub fn move_to_next_app(&mut self) { + self.current_app += 1; + } +} + +lazy_static! { + static ref APP_MANAGER: UPSafeCell = unsafe { + UPSafeCell::new({ + extern "C" { + fn _num_app(); + } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = num_app_ptr.read_volatile(); + let mut app_start: [usize; MAX_APP_NUM + 1] = [0; MAX_APP_NUM + 1]; + let app_start_raw: &[usize] = + core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1); + app_start[..=num_app].copy_from_slice(app_start_raw); + AppManager { + num_app, + current_app: 0, + app_start, + } + }) + }; +} + +pub fn init() { + print_app_info(); +} + +pub fn print_app_info() { + APP_MANAGER.exclusive_access().print_app_info(); +} + +pub fn run_next_app() -> ! { + let mut app_manager = APP_MANAGER.exclusive_access(); + let current_app = app_manager.get_current_app(); + unsafe { + app_manager.load_app(current_app); + } + app_manager.move_to_next_app(); + drop(app_manager); + // before this we have to drop local variables related to resources manually + // and release the resources + extern "C" { + fn __restore(cx_addr: usize); + } + unsafe { + __restore(KERNEL_STACK.push_context(TrapContext::app_init_context( + APP_BASE_ADDRESS, + USER_STACK.get_sp(), + )) as *const _ as usize); + } + panic!("Unreachable in batch::run_current_app!"); +} diff --git a/os2-ref/src/console.rs b/os2-ref/src/console.rs new file mode 100644 index 0000000..632e662 --- /dev/null +++ b/os2-ref/src/console.rs @@ -0,0 +1,37 @@ +/*！ + +本模块实现了 print 和 println 宏。 + +*/ + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} diff --git a/os2-ref/src/entry.asm b/os2-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os2-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os2-ref/src/lang_items.rs b/os2-ref/src/lang_items.rs new file mode 100644 index 0000000..a6217a0 --- /dev/null +++ b/os2-ref/src/lang_items.rs @@ -0,0 +1,17 @@ +use crate::sbi::shutdown; +use core::panic::PanicInfo; + +#[panic_handler] +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println!( + "Panicked at {}:{} {}", + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println!("Panicked: {}", info.message().unwrap()); + } + shutdown() +} diff --git a/os2-ref/src/linker.ld b/os2-ref/src/linker.ld new file mode 100644 index 0000000..8bcce1a --- /dev/null +++ b/os2-ref/src/linker.ld @@ -0,0 +1,48 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os2-ref/src/logging.rs b/os2-ref/src/logging.rs new file mode 100644 index 0000000..7b7cc56 --- /dev/null +++ b/os2-ref/src/logging.rs @@ -0,0 +1,47 @@ +/*！ + +本模块利用 log crate 为你提供了日志功能，使用方式见 main.rs. + +*/ + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os2-ref/src/main.rs b/os2-ref/src/main.rs new file mode 100644 index 0000000..cafaae9 --- /dev/null +++ b/os2-ref/src/main.rs @@ -0,0 +1,40 @@ +#![no_std] +#![no_main] +#![feature(panic_info_message)] + +#[macro_use] +extern crate log; + +#[macro_use] +mod console; +mod batch; +mod lang_items; +mod logging; +mod sbi; +mod sync; +mod syscall; +mod trap; + +core::arch::global_asm!(include_str!("entry.asm")); +core::arch::global_asm!(include_str!("link_app.S")); + +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + trap::init(); + batch::init(); + batch::run_next_app(); +} diff --git a/os2-ref/src/sbi.rs b/os2-ref/src/sbi.rs new file mode 100644 index 0000000..751a4d2 --- /dev/null +++ b/os2-ref/src/sbi.rs @@ -0,0 +1,34 @@ +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os2-ref/src/sync/mod.rs b/os2-ref/src/sync/mod.rs new file mode 100644 index 0000000..d1ce5bc --- /dev/null +++ b/os2-ref/src/sync/mod.rs @@ -0,0 +1,3 @@ +mod up; + +pub use up::UPSafeCell; diff --git a/os2-ref/src/sync/up.rs b/os2-ref/src/sync/up.rs new file mode 100644 index 0000000..c7b2c9e --- /dev/null +++ b/os2-ref/src/sync/up.rs @@ -0,0 +1,29 @@ +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os2-ref/src/syscall/fs.rs b/os2-ref/src/syscall/fs.rs new file mode 100644 index 0000000..3e38eae --- /dev/null +++ b/os2-ref/src/syscall/fs.rs @@ -0,0 +1,15 @@ +const FD_STDOUT: usize = 1; + +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDOUT => { + let slice = unsafe { core::slice::from_raw_parts(buf, len) }; + let str = core::str::from_utf8(slice).unwrap(); + print!("{}", str); + len as isize + } + _ => { + panic!("Unsupported fd in sys_write!"); + } + } +} diff --git a/os2-ref/src/syscall/mod.rs b/os2-ref/src/syscall/mod.rs new file mode 100644 index 0000000..430af56 --- /dev/null +++ b/os2-ref/src/syscall/mod.rs @@ -0,0 +1,16 @@ +const SYSCALL_WRITE: usize = 64; +const SYSCALL_EXIT: usize = 93; + +mod fs; +mod process; + +use fs::*; +use process::*; + +pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize { + match syscall_id { + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_EXIT => sys_exit(args[0] as i32), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os2-ref/src/syscall/process.rs b/os2-ref/src/syscall/process.rs new file mode 100644 index 0000000..28caecd --- /dev/null +++ b/os2-ref/src/syscall/process.rs @@ -0,0 +1,6 @@ +use crate::batch::run_next_app; + +pub fn sys_exit(exit_code: i32) -> ! { + info!("[kernel] Application exited with code {}", exit_code); + run_next_app() +} diff --git a/os2-ref/src/trap/context.rs b/os2-ref/src/trap/context.rs new file mode 100644 index 0000000..af5a53a --- /dev/null +++ b/os2-ref/src/trap/context.rs @@ -0,0 +1,25 @@ +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +pub struct TrapContext { + pub x: [usize; 32], + pub sstatus: Sstatus, + pub sepc: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context(entry: usize, sp: usize) -> Self { + let mut sstatus = sstatus::read(); + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os2-ref/src/trap/mod.rs b/os2-ref/src/trap/mod.rs new file mode 100644 index 0000000..c2cfcb4 --- /dev/null +++ b/os2-ref/src/trap/mod.rs @@ -0,0 +1,50 @@ +mod context; + +use crate::batch::run_next_app; +use crate::syscall::syscall; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Trap}, + stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +pub fn init() { + extern "C" { + fn __alltraps(); + } + unsafe { + stvec::write(__alltraps as usize, TrapMode::Direct); + } +} + +#[no_mangle] +pub fn trap_handler(cx: &mut TrapContext) -> &mut TrapContext { + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + cx.sepc += 4; + cx.x[10] = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]) as usize; + } + Trap::Exception(Exception::StoreFault) | Trap::Exception(Exception::StorePageFault) => { + error!("[kernel] PageFault in application, core dumped."); + run_next_app(); + } + Trap::Exception(Exception::IllegalInstruction) => { + error!("[kernel] IllegalInstruction in application, core dumped."); + run_next_app(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + cx +} + +pub use context::TrapContext; diff --git a/os2-ref/src/trap/trap.S b/os2-ref/src/trap/trap.S new file mode 100644 index 0000000..9d6967c --- /dev/null +++ b/os2-ref/src/trap/trap.S @@ -0,0 +1,64 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->kernel stack, sscratch->user stack + # allocate a TrapContext on kernel stack + addi sp, sp, -34*8 + # save general-purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they were saved on kernel stack + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it on the kernel stack + csrr t2, sscratch + sd t2, 2*8(sp) + # set input argument of trap_handler(cx: &mut TrapContext) + mv a0, sp + call trap_handler + +__restore: + # case1: start running app by __restore + # case2: back to U after handling trap + mv sp, a0 + # now sp->kernel stack(after allocated), sscratch->user stack + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + ld t2, 2*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + csrw sscratch, t2 + # restore general-purpuse registers except sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # release TrapContext on kernel stack + addi sp, sp, 34*8 + # now sp->kernel stack, sscratch->user stack + csrrw sp, sscratch, sp + sret diff --git a/os3-ref/.cargo/config b/os3-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os3-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os3-ref/Cargo.toml b/os3-ref/Cargo.toml new file mode 100644 index 0000000..7790c1a --- /dev/null +++ b/os3-ref/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +buddy_system_allocator = "0.6" +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } diff --git a/os3-ref/Makefile b/os3-ref/Makefile new file mode 100644 index 0000000..ef0c7d6 --- /dev/null +++ b/os3-ref/Makefile @@ -0,0 +1,59 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -oP 'ch\K[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + @$(OBJDUMP) $(KERNEL_ELF) -S > $(KERNEL_ELF).asm + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean run-inner diff --git a/os3-ref/build.rs b/os3-ref/build.rs new file mode 100644 index 0000000..92953d5 --- /dev/null +++ b/os3-ref/build.rs @@ -0,0 +1,59 @@ +//! Building applications linker + +use std::fs::{read_dir, File}; +use std::io::{Result, Write}; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); + insert_app_data().unwrap(); +} + +static TARGET_PATH: &str = "../user/build/bin/"; + +/// get app data and build linker +fn insert_app_data() -> Result<()> { + let mut f = File::create("src/link_app.S").unwrap(); + let mut apps: Vec<_> = read_dir("../user/build/bin/") + .unwrap() + .into_iter() + .map(|dir_entry| { + let mut name_with_ext = dir_entry.unwrap().file_name().into_string().unwrap(); + name_with_ext.drain(name_with_ext.find('.').unwrap()..name_with_ext.len()); + name_with_ext + }) + .collect(); + apps.sort(); + + writeln!( + f, + r#" + .align 3 + .section .data + .global _num_app +_num_app: + .quad {}"#, + apps.len() + )?; + + for i in 0..apps.len() { + writeln!(f, r#" .quad app_{}_start"#, i)?; + } + writeln!(f, r#" .quad app_{}_end"#, apps.len() - 1)?; + + for (idx, app) in apps.iter().enumerate() { + println!("app_{}: {}", idx, app); + writeln!( + f, + r#" + .section .data + .global app_{0}_start + .global app_{0}_end +app_{0}_start: + .incbin "{2}{1}.bin" +app_{0}_end:"#, + idx, app, TARGET_PATH + )?; + } + Ok(()) +} diff --git a/os3-ref/src/config.rs b/os3-ref/src/config.rs new file mode 100644 index 0000000..45c0907 --- /dev/null +++ b/os3-ref/src/config.rs @@ -0,0 +1,10 @@ +//! Constants used in rCore + +pub const USER_STACK_SIZE: usize = 4096; +pub const KERNEL_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_HEAP_SIZE: usize = 0x20000; +pub const MAX_APP_NUM: usize = 16; +pub const APP_BASE_ADDRESS: usize = 0x80400000; +pub const APP_SIZE_LIMIT: usize = 0x20000; +pub const CLOCK_FREQ: usize = 12500000; +pub const MAX_SYSCALL_NUM: usize = 500; diff --git a/os3-ref/src/console.rs b/os3-ref/src/console.rs new file mode 100644 index 0000000..7e44bb2 --- /dev/null +++ b/os3-ref/src/console.rs @@ -0,0 +1,35 @@ +//! SBI console driver, for text output + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +/// print string macro +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +/// println string macro +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} diff --git a/os3-ref/src/entry.asm b/os3-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os3-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os3-ref/src/heap_alloc.rs b/os3-ref/src/heap_alloc.rs new file mode 100644 index 0000000..199b353 --- /dev/null +++ b/os3-ref/src/heap_alloc.rs @@ -0,0 +1,26 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} diff --git a/os3-ref/src/lang_items.rs b/os3-ref/src/lang_items.rs new file mode 100644 index 0000000..6045066 --- /dev/null +++ b/os3-ref/src/lang_items.rs @@ -0,0 +1,20 @@ +//! The panic handler + +use crate::sbi::shutdown; +use core::panic::PanicInfo; + +#[panic_handler] +/// panic handler +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println!( + "Panicked at {}:{} {}", + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println!("[kernel] Panicked: {}", info.message().unwrap()); + } + shutdown() +} diff --git a/os3-ref/src/linker.ld b/os3-ref/src/linker.ld new file mode 100644 index 0000000..8bcce1a --- /dev/null +++ b/os3-ref/src/linker.ld @@ -0,0 +1,48 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os3-ref/src/loader.rs b/os3-ref/src/loader.rs new file mode 100644 index 0000000..aeab808 --- /dev/null +++ b/os3-ref/src/loader.rs @@ -0,0 +1,101 @@ +//! Loading user applications into memory +//! +//! For chapter 3, user applications are simply part of the data included in the +//! kernel binary, so we only need to copy them to the space allocated for each +//! app to load them. We also allocate fixed spaces for each task's +//! [`KernelStack`] and [`UserStack`]. + +use crate::config::*; +use crate::trap::TrapContext; + +#[repr(align(4096))] +#[derive(Copy, Clone)] +/// kernel stack structure +struct KernelStack { + data: [u8; KERNEL_STACK_SIZE], +} + +#[repr(align(4096))] +#[derive(Copy, Clone)] +/// user stack structure +struct UserStack { + data: [u8; USER_STACK_SIZE], +} + +/// kernel stack instance +static KERNEL_STACK: [KernelStack; MAX_APP_NUM] = [KernelStack { + data: [0; KERNEL_STACK_SIZE], +}; MAX_APP_NUM]; + +/// user stack instance +static USER_STACK: [UserStack; MAX_APP_NUM] = [UserStack { + data: [0; USER_STACK_SIZE], +}; MAX_APP_NUM]; + +impl KernelStack { + fn get_sp(&self) -> usize { + self.data.as_ptr() as usize + KERNEL_STACK_SIZE + } + pub fn push_context(&self, trap_cx: TrapContext) -> usize { + let trap_cx_ptr = (self.get_sp() - core::mem::size_of::()) as *mut TrapContext; + unsafe { + *trap_cx_ptr = trap_cx; + } + trap_cx_ptr as usize + } +} + +impl UserStack { + fn get_sp(&self) -> usize { + self.data.as_ptr() as usize + USER_STACK_SIZE + } +} + +/// Get base address of app i. +fn get_base_i(app_id: usize) -> usize { + APP_BASE_ADDRESS + app_id * APP_SIZE_LIMIT +} + +/// Get the total number of applications. +pub fn get_num_app() -> usize { + extern "C" { + fn _num_app(); + } + unsafe { (_num_app as usize as *const usize).read_volatile() } +} + +/// Load nth user app at +/// [APP_BASE_ADDRESS + n * APP_SIZE_LIMIT, APP_BASE_ADDRESS + (n+1) * APP_SIZE_LIMIT). +pub fn load_apps() { + extern "C" { + fn _num_app(); + } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = get_num_app(); + let app_start = unsafe { core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1) }; + // clear i-cache first + unsafe { + core::arch::asm!("fence.i"); + } + // load apps + for i in 0..num_app { + let base_i = get_base_i(i); + // clear region + (base_i..base_i + APP_SIZE_LIMIT) + .for_each(|addr| unsafe { (addr as *mut u8).write_volatile(0) }); + // load app from data section to memory + let src = unsafe { + core::slice::from_raw_parts(app_start[i] as *const u8, app_start[i + 1] - app_start[i]) + }; + let dst = unsafe { core::slice::from_raw_parts_mut(base_i as *mut u8, src.len()) }; + dst.copy_from_slice(src); + } +} + +/// get app info with entry and sp and save `TrapContext` in kernel stack +pub fn init_app_cx(app_id: usize) -> usize { + KERNEL_STACK[app_id].push_context(TrapContext::app_init_context( + get_base_i(app_id), + USER_STACK[app_id].get_sp(), + )) +} diff --git a/os3-ref/src/logging.rs b/os3-ref/src/logging.rs new file mode 100644 index 0000000..e12448e --- /dev/null +++ b/os3-ref/src/logging.rs @@ -0,0 +1,45 @@ +//! Global logger + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +/// a simple logger +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +/// initiate logger +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os3-ref/src/main.rs b/os3-ref/src/main.rs new file mode 100644 index 0000000..a8b2958 --- /dev/null +++ b/os3-ref/src/main.rs @@ -0,0 +1,70 @@ +//! The main module and entrypoint +//! +//! Various facilities of the kernels are implemented as submodules. The most +//! important ones are: +//! +//! - [`trap`]: Handles all cases of switching from userspace to the kernel +//! - [`task`]: Task management +//! - [`syscall`]: System call handling and implementation +//! +//! The operating system also starts in this module. Kernel code starts +//! executing from `entry.asm`, after which [`rust_main()`] is called to +//! initialize various pieces of functionality. (See its source code for +//! details.) +//! +//! We then call [`task::run_first_task()`] and for the first time go to +//! userspace. + +#![no_std] +#![no_main] +#![feature(panic_info_message)] +#![feature(alloc_error_handler)] + +#[macro_use] +extern crate log; + +extern crate alloc; + +#[macro_use] +mod console; +mod config; +mod heap_alloc; +mod lang_items; +mod loader; +mod logging; +mod sbi; +mod sync; +pub mod syscall; +pub mod task; +mod timer; +pub mod trap; + +core::arch::global_asm!(include_str!("entry.asm")); +core::arch::global_asm!(include_str!("link_app.S")); + +/// clear BSS segment +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +/// the rust entry-point of os +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + heap_alloc::init_heap(); + trap::init(); + loader::load_apps(); + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + task::run_first_task(); + panic!("Unreachable in rust_main!"); +} diff --git a/os3-ref/src/sbi.rs b/os3-ref/src/sbi.rs new file mode 100644 index 0000000..4af7620 --- /dev/null +++ b/os3-ref/src/sbi.rs @@ -0,0 +1,45 @@ +//! SBI call wrappers + +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +/// general sbi call +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +/// use sbi call to set timer +pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); +} + +/// use sbi call to putchar in console (qemu uart handler) +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +/// use sbi call to getchar from console (qemu uart handler) +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +/// use sbi call to shutdown the kernel +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os3-ref/src/sync/mod.rs b/os3-ref/src/sync/mod.rs new file mode 100644 index 0000000..4743e31 --- /dev/null +++ b/os3-ref/src/sync/mod.rs @@ -0,0 +1,5 @@ +//! Synchronization and interior mutability primitives + +mod up; + +pub use up::UPSafeCell; diff --git a/os3-ref/src/sync/up.rs b/os3-ref/src/sync/up.rs new file mode 100644 index 0000000..039b039 --- /dev/null +++ b/os3-ref/src/sync/up.rs @@ -0,0 +1,31 @@ +//! Uniprocessor interior mutability primitives + +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os3-ref/src/syscall/fs.rs b/os3-ref/src/syscall/fs.rs new file mode 100644 index 0000000..0aa64b5 --- /dev/null +++ b/os3-ref/src/syscall/fs.rs @@ -0,0 +1,18 @@ +//! File and filesystem-related syscalls + +const FD_STDOUT: usize = 1; + +// YOUR JOB: 修改 sys_write 使之通过测试 +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDOUT => { + let slice = unsafe { core::slice::from_raw_parts(buf, len) }; + let str = core::str::from_utf8(slice).unwrap(); + print!("{}", str); + len as isize + } + _ => { + panic!("Unsupported fd in sys_write!"); + } + } +} diff --git a/os3-ref/src/syscall/mod.rs b/os3-ref/src/syscall/mod.rs new file mode 100644 index 0000000..21d8bc6 --- /dev/null +++ b/os3-ref/src/syscall/mod.rs @@ -0,0 +1,36 @@ +//! Implementation of syscalls +//! +//! The single entry point to all system calls, [`syscall()`], is called +//! whenever userspace wishes to perform a system call using the `ecall` +//! instruction. In this case, the processor raises an 'Environment call from +//! U-mode' exception, which is handled as one of the cases in +//! [`crate::trap::trap_handler`]. +//! +//! For clarity, each single syscall is implemented as its own function, named +//! `sys_` then the name of the syscall. You can find functions like this in +//! submodules, and you should also implement syscalls this way. + +const SYSCALL_WRITE: usize = 64; +const SYSCALL_EXIT: usize = 93; +const SYSCALL_YIELD: usize = 124; +const SYSCALL_GET_TIME: usize = 169; +const SYSCALL_TASK_INFO: usize = 410; + +mod fs; +mod process; + +use fs::*; +use process::*; + +/// handle syscall exception with `syscall_id` and other arguments +pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize { + // LAB1: You may need to update syscall info here. + match syscall_id { + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_EXIT => sys_exit(args[0] as i32), + SYSCALL_YIELD => sys_yield(), + SYSCALL_GET_TIME => sys_get_time(args[0] as *mut TimeVal, args[1]), + SYSCALL_TASK_INFO => sys_task_info(args[0] as *mut TaskInfo), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os3-ref/src/syscall/process.rs b/os3-ref/src/syscall/process.rs new file mode 100644 index 0000000..9d73627 --- /dev/null +++ b/os3-ref/src/syscall/process.rs @@ -0,0 +1,48 @@ +//! Process management syscalls + +use crate::config::{MAX_APP_NUM, MAX_SYSCALL_NUM}; +use crate::task::{exit_current_and_run_next, suspend_current_and_run_next, TaskStatus}; +use crate::timer::get_time_us; + +#[repr(C)] +#[derive(Debug)] +pub struct TimeVal { + pub sec: usize, + pub usec: usize, +} + +pub struct TaskInfo { + status: TaskStatus, + syscall_times: [u32; MAX_SYSCALL_NUM], + time: usize, +} + +/// task exits and submit an exit code +pub fn sys_exit(exit_code: i32) -> ! { + info!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(); + panic!("Unreachable in sys_exit!"); +} + +/// current task gives up resources for other tasks +pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 +} + +/// get time with second and microsecond +pub fn sys_get_time(ts: *mut TimeVal, _tz: usize) -> isize { + let us = get_time_us(); + unsafe { + *ts = TimeVal { + sec: us / 1_000_000, + usec: us % 1_000_000, + }; + } + 0 +} + +/// YOUR JOB: Finish sys_task_info to pass testcases +pub fn sys_task_info(ti: *mut TaskInfo) -> isize { + -1 +} diff --git a/os3-ref/src/task/context.rs b/os3-ref/src/task/context.rs new file mode 100644 index 0000000..4264302 --- /dev/null +++ b/os3-ref/src/task/context.rs @@ -0,0 +1,30 @@ +//! Implementation of [`TaskContext`] + +#[derive(Copy, Clone)] +#[repr(C)] +/// task context structure containing some registers +pub struct TaskContext { + ra: usize, + sp: usize, + s: [usize; 12], +} + +impl TaskContext { + pub fn zero_init() -> Self { + Self { + ra: 0, + sp: 0, + s: [0; 12], + } + } + pub fn goto_restore(kstack_ptr: usize) -> Self { + extern "C" { + fn __restore(); + } + Self { + ra: __restore as usize, + sp: kstack_ptr, + s: [0; 12], + } + } +} diff --git a/os3-ref/src/task/mod.rs b/os3-ref/src/task/mod.rs new file mode 100644 index 0000000..6d67a57 --- /dev/null +++ b/os3-ref/src/task/mod.rs @@ -0,0 +1,176 @@ +//! Task management implementation +//! +//! Everything about task management, like starting and switching tasks is +//! implemented here. +//! +//! A single global instance of [`TaskManager`] called `TASK_MANAGER` controls +//! all the tasks in the operating system. +//! +//! Be careful when you see [`__switch`]. Control flow around this function +//! might not be what you expect. + +mod context; +mod switch; +#[allow(clippy::module_inception)] +mod task; + +use crate::config::{MAX_APP_NUM, MAX_SYSCALL_NUM}; +use crate::loader::{get_num_app, init_app_cx}; +use crate::sync::UPSafeCell; +use lazy_static::*; +pub use switch::__switch; +pub use task::{TaskControlBlock, TaskStatus}; + +pub use context::TaskContext; + +/// The task manager, where all the tasks are managed. +/// +/// Functions implemented on `TaskManager` deals with all task state transitions +/// and task context switching. For convenience, you can find wrappers around it +/// in the module level. +/// +/// Most of `TaskManager` are hidden behind the field `inner`, to defer +/// borrowing checks to runtime. You can see examples on how to use `inner` in +/// existing functions on `TaskManager`. +pub struct TaskManager { + /// total number of tasks + num_app: usize, + /// use inner value to get mutable access + inner: UPSafeCell, +} + +/// The task manager inner in 'UPSafeCell' +struct TaskManagerInner { + /// task list + tasks: [TaskControlBlock; MAX_APP_NUM], + /// id of current `Running` task + current_task: usize, +} + +lazy_static! { + /// a `TaskManager` instance through lazy_static! + pub static ref TASK_MANAGER: TaskManager = { + let num_app = get_num_app(); + let mut tasks = [TaskControlBlock { + task_cx: TaskContext::zero_init(), + task_status: TaskStatus::UnInit, + }; MAX_APP_NUM]; + for (i, t) in tasks.iter_mut().enumerate().take(num_app) { + t.task_cx = TaskContext::goto_restore(init_app_cx(i)); + t.task_status = TaskStatus::Ready; + } + TaskManager { + num_app, + inner: unsafe { + UPSafeCell::new(TaskManagerInner { + tasks, + current_task: 0, + }) + }, + } + }; +} + +impl TaskManager { + /// Run the first task in task list. + /// + /// Generally, the first task in task list is an idle task (we call it zero process later). + /// But in ch3, we load apps statically, so the first task is a real app. + fn run_first_task(&self) -> ! { + let mut inner = self.inner.exclusive_access(); + let task0 = &mut inner.tasks[0]; + task0.task_status = TaskStatus::Running; + let next_task_cx_ptr = &task0.task_cx as *const TaskContext; + drop(inner); + let mut _unused = TaskContext::zero_init(); + // before this, we should drop local variables that must be dropped manually + unsafe { + __switch(&mut _unused as *mut TaskContext, next_task_cx_ptr); + } + panic!("unreachable in run_first_task!"); + } + + /// Change the status of current `Running` task into `Ready`. + fn mark_current_suspended(&self) { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[current].task_status = TaskStatus::Ready; + } + + /// Change the status of current `Running` task into `Exited`. + fn mark_current_exited(&self) { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[current].task_status = TaskStatus::Exited; + } + + /// Find next task to run and return task id. + /// + /// In this case, we only return the first `Ready` task in task list. + fn find_next_task(&self) -> Option { + let inner = self.inner.exclusive_access(); + let current = inner.current_task; + (current + 1..current + self.num_app + 1) + .map(|id| id % self.num_app) + .find(|id| inner.tasks[*id].task_status == TaskStatus::Ready) + } + + /// Switch current `Running` task to the task we have found, + /// or there is no `Ready` task and we can exit with all applications completed + fn run_next_task(&self) { + if let Some(next) = self.find_next_task() { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[next].task_status = TaskStatus::Running; + inner.current_task = next; + let current_task_cx_ptr = &mut inner.tasks[current].task_cx as *mut TaskContext; + let next_task_cx_ptr = &inner.tasks[next].task_cx as *const TaskContext; + drop(inner); + // before this, we should drop local variables that must be dropped manually + unsafe { + __switch(current_task_cx_ptr, next_task_cx_ptr); + } + // go back to user mode + } else { + panic!("All applications completed!"); + } + } + + // LAB1: Try to implement your function to update or get task info! +} + +/// Run the first task in task list. +pub fn run_first_task() { + TASK_MANAGER.run_first_task(); +} + +/// Switch current `Running` task to the task we have found, +/// or there is no `Ready` task and we can exit with all applications completed +fn run_next_task() { + TASK_MANAGER.run_next_task(); +} + +/// Change the status of current `Running` task into `Ready`. +fn mark_current_suspended() { + TASK_MANAGER.mark_current_suspended(); +} + +/// Change the status of current `Running` task into `Exited`. +fn mark_current_exited() { + TASK_MANAGER.mark_current_exited(); +} + +/// Suspend the current 'Running' task and run the next task in task list. +pub fn suspend_current_and_run_next() { + mark_current_suspended(); + run_next_task(); +} + +/// Exit the current 'Running' task and run the next task in task list. +pub fn exit_current_and_run_next() { + mark_current_exited(); + run_next_task(); +} + +// LAB1: Public functions implemented here provide interfaces. +// You may use TASK_MANAGER member functions to handle requests. diff --git a/os3-ref/src/task/switch.S b/os3-ref/src/task/switch.S new file mode 100644 index 0000000..3f985d2 --- /dev/null +++ b/os3-ref/src/task/switch.S @@ -0,0 +1,34 @@ +.altmacro +.macro SAVE_SN n + sd s\n, (\n+2)*8(a0) +.endm +.macro LOAD_SN n + ld s\n, (\n+2)*8(a1) +.endm + .section .text + .globl __switch +__switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + diff --git a/os3-ref/src/task/switch.rs b/os3-ref/src/task/switch.rs new file mode 100644 index 0000000..af08289 --- /dev/null +++ b/os3-ref/src/task/switch.rs @@ -0,0 +1,16 @@ +//! Rust wrapper around `__switch`. +//! +//! Switching to a different task's context happens here. The actual +//! implementation must not be in Rust and (essentially) has to be in assembly +//! language (Do you know why?), so this module really is just a wrapper around +//! `switch.S`. + +core::arch::global_asm!(include_str!("switch.S")); + +use super::TaskContext; + +extern "C" { + /// Switch to the context of `next_task_cx_ptr`, saving the current context + /// in `current_task_cx_ptr`. + pub fn __switch(current_task_cx_ptr: *mut TaskContext, next_task_cx_ptr: *const TaskContext); +} diff --git a/os3-ref/src/task/task.rs b/os3-ref/src/task/task.rs new file mode 100644 index 0000000..044e698 --- /dev/null +++ b/os3-ref/src/task/task.rs @@ -0,0 +1,20 @@ +//! Types related to task management + +use super::TaskContext; + +#[derive(Copy, Clone)] +/// task control block structure +pub struct TaskControlBlock { + pub task_status: TaskStatus, + pub task_cx: TaskContext, + // LAB1: Add whatever you need about the Task. +} + +#[derive(Copy, Clone, PartialEq)] +/// task status: UnInit, Ready, Running, Exited +pub enum TaskStatus { + UnInit, + Ready, + Running, + Exited, +} diff --git a/os3-ref/src/timer.rs b/os3-ref/src/timer.rs new file mode 100644 index 0000000..4f40494 --- /dev/null +++ b/os3-ref/src/timer.rs @@ -0,0 +1,23 @@ +//! RISC-V timer-related functionality + +use crate::config::CLOCK_FREQ; +use crate::sbi::set_timer; +use riscv::register::time; + +const TICKS_PER_SEC: usize = 100; +const MICRO_PER_SEC: usize = 1_000_000; + +/// read the `mtime` register +pub fn get_time() -> usize { + time::read() +} + +/// get current time in microseconds +pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) +} + +/// set the next timer interrupt +pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); +} diff --git a/os3-ref/src/trap/context.rs b/os3-ref/src/trap/context.rs new file mode 100644 index 0000000..8abb5c5 --- /dev/null +++ b/os3-ref/src/trap/context.rs @@ -0,0 +1,28 @@ +//! Implementation of [`TrapContext`] + +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +/// trap context structure containing sstatus, sepc and registers +pub struct TrapContext { + pub x: [usize; 32], + pub sstatus: Sstatus, + pub sepc: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context(entry: usize, sp: usize) -> Self { + let mut sstatus = sstatus::read(); + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os3-ref/src/trap/mod.rs b/os3-ref/src/trap/mod.rs new file mode 100644 index 0000000..b712cc6 --- /dev/null +++ b/os3-ref/src/trap/mod.rs @@ -0,0 +1,78 @@ +//! Trap handling functionality +//! +//! For rCore, we have a single trap entry point, namely `__alltraps`. At +//! initialization in [`init()`], we set the `stvec` CSR to point to it. +//! +//! All traps go through `__alltraps`, which is defined in `trap.S`. The +//! assembly language code does just enough work restore the kernel space +//! context, ensuring that Rust code safely runs, and transfers control to +//! [`trap_handler()`]. +//! +//! It then calls different functionality based on what exactly the exception +//! was. For example, timer interrupts trigger task preemption, and syscalls go +//! to [`syscall()`]. + +mod context; + +use crate::syscall::syscall; +use crate::task::{exit_current_and_run_next, suspend_current_and_run_next}; +use crate::timer::set_next_trigger; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Interrupt, Trap}, + sie, stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +/// initialize CSR `stvec` as the entry of `__alltraps` +pub fn init() { + extern "C" { + fn __alltraps(); + } + unsafe { + stvec::write(__alltraps as usize, TrapMode::Direct); + } +} + +/// timer interrupt enabled +pub fn enable_timer_interrupt() { + unsafe { + sie::set_stimer(); + } +} + +#[no_mangle] +/// handle an interrupt, exception, or system call from user space +pub fn trap_handler(cx: &mut TrapContext) -> &mut TrapContext { + let scause = scause::read(); // get trap cause + let stval = stval::read(); // get extra value + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + cx.sepc += 4; + cx.x[10] = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]) as usize; + } + Trap::Exception(Exception::StoreFault) | Trap::Exception(Exception::StorePageFault) => { + error!("[kernel] PageFault in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", stval, cx.sepc); + exit_current_and_run_next(); + } + Trap::Exception(Exception::IllegalInstruction) => { + error!("[kernel] IllegalInstruction in application, core dumped."); + exit_current_and_run_next(); + } + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + cx +} + +pub use context::TrapContext; diff --git a/os3-ref/src/trap/trap.S b/os3-ref/src/trap/trap.S new file mode 100644 index 0000000..70a18a9 --- /dev/null +++ b/os3-ref/src/trap/trap.S @@ -0,0 +1,61 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->kernel stack, sscratch->user stack + # allocate a TrapContext on kernel stack + addi sp, sp, -34*8 + # save general-purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they were saved on kernel stack + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it on the kernel stack + csrr t2, sscratch + sd t2, 2*8(sp) + # set input argument of trap_handler(cx: &mut TrapContext) + mv a0, sp + call trap_handler + +__restore: + # now sp->kernel stack(after allocated), sscratch->user stack + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + ld t2, 2*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + csrw sscratch, t2 + # restore general-purpuse registers except sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # release TrapContext on kernel stack + addi sp, sp, 34*8 + # now sp->kernel stack, sscratch->user stack + csrrw sp, sscratch, sp + sret diff --git a/os4-ref/.cargo/config b/os4-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os4-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os4-ref/Cargo.toml b/os4-ref/Cargo.toml new file mode 100644 index 0000000..e9bacac --- /dev/null +++ b/os4-ref/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +bitflags = "1.2.1" +buddy_system_allocator = "0.6" +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } +spin = "0.9" +lock_api = "=0.4.6" +xmas-elf = "0.7.0" diff --git a/os4-ref/Makefile b/os4-ref/Makefile new file mode 100644 index 0000000..ab4b02b --- /dev/null +++ b/os4-ref/Makefile @@ -0,0 +1,59 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -o 'ch[0-9]' | grep -o '[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + @$(OBJDUMP) $(KERNEL_ELF) -S > $(KERNEL_ELF).asm + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean run-inner \ No newline at end of file diff --git a/os4-ref/build.rs b/os4-ref/build.rs new file mode 100644 index 0000000..63845c7 --- /dev/null +++ b/os4-ref/build.rs @@ -0,0 +1,60 @@ +//! Building applications linker + +use std::fs::{read_dir, File}; +use std::io::{Result, Write}; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); + insert_app_data().unwrap(); +} + +static TARGET_PATH: &str = "../user/build/elf/"; + +/// get app data and build linker +fn insert_app_data() -> Result<()> { + let mut f = File::create("src/link_app.S").unwrap(); + let mut apps: Vec<_> = read_dir("../user/build/elf/") + .unwrap() + .into_iter() + .map(|dir_entry| { + let mut name_with_ext = dir_entry.unwrap().file_name().into_string().unwrap(); + name_with_ext.drain(name_with_ext.find('.').unwrap()..name_with_ext.len()); + name_with_ext + }) + .collect(); + apps.sort(); + + writeln!( + f, + r#" + .align 3 + .section .data + .global _num_app +_num_app: + .quad {}"#, + apps.len() + )?; + + for i in 0..apps.len() { + writeln!(f, r#" .quad app_{}_start"#, i)?; + } + writeln!(f, r#" .quad app_{}_end"#, apps.len() - 1)?; + + for (idx, app) in apps.iter().enumerate() { + println!("app_{}: {}", idx, app); + writeln!( + f, + r#" + .section .data + .global app_{0}_start + .global app_{0}_end + .align 3 +app_{0}_start: + .incbin "{2}{1}.elf" +app_{0}_end:"#, + idx, app, TARGET_PATH + )?; + } + Ok(()) +} diff --git a/os4-ref/src/config.rs b/os4-ref/src/config.rs new file mode 100644 index 0000000..89696b3 --- /dev/null +++ b/os4-ref/src/config.rs @@ -0,0 +1,20 @@ +//! Constants used in rCore + +pub const USER_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_HEAP_SIZE: usize = 0x30_0000; +pub const MEMORY_END: usize = 0x80800000; +pub const PAGE_SIZE: usize = 0x1000; +pub const PAGE_SIZE_BITS: usize = 0xc; +pub const MAX_SYSCALL_NUM: usize = 500; + +pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1; +pub const TRAP_CONTEXT: usize = TRAMPOLINE - PAGE_SIZE; +/// Return (bottom, top) of a kernel stack in kernel space. +pub fn kernel_stack_position(app_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) +} + +pub const CLOCK_FREQ: usize = 12500000; diff --git a/os4-ref/src/console.rs b/os4-ref/src/console.rs new file mode 100644 index 0000000..7e44bb2 --- /dev/null +++ b/os4-ref/src/console.rs @@ -0,0 +1,35 @@ +//! SBI console driver, for text output + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +/// print string macro +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +/// println string macro +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} diff --git a/os4-ref/src/entry.asm b/os4-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os4-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os4-ref/src/heap_alloc.rs b/os4-ref/src/heap_alloc.rs new file mode 100644 index 0000000..199b353 --- /dev/null +++ b/os4-ref/src/heap_alloc.rs @@ -0,0 +1,26 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} diff --git a/os4-ref/src/lang_items.rs b/os4-ref/src/lang_items.rs new file mode 100644 index 0000000..6045066 --- /dev/null +++ b/os4-ref/src/lang_items.rs @@ -0,0 +1,20 @@ +//! The panic handler + +use crate::sbi::shutdown; +use core::panic::PanicInfo; + +#[panic_handler] +/// panic handler +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println!( + "Panicked at {}:{} {}", + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println!("[kernel] Panicked: {}", info.message().unwrap()); + } + shutdown() +} diff --git a/os4-ref/src/linker.ld b/os4-ref/src/linker.ld new file mode 100644 index 0000000..5baafbd --- /dev/null +++ b/os4-ref/src/linker.ld @@ -0,0 +1,53 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + . = ALIGN(4K); + strampoline = .; + *(.text.trampoline); + . = ALIGN(4K); + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + sbss_with_stack = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os4-ref/src/loader.rs b/os4-ref/src/loader.rs new file mode 100644 index 0000000..855187d --- /dev/null +++ b/os4-ref/src/loader.rs @@ -0,0 +1,26 @@ +//! Loading user applications into memory + +/// Get the total number of applications. +pub fn get_num_app() -> usize { + extern "C" { + fn _num_app(); + } + unsafe { (_num_app as usize as *const usize).read_volatile() } +} + +/// get applications data +pub fn get_app_data(app_id: usize) -> &'static [u8] { + extern "C" { + fn _num_app(); + } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = get_num_app(); + let app_start = unsafe { core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1) }; + assert!(app_id < num_app); + unsafe { + core::slice::from_raw_parts( + app_start[app_id] as *const u8, + app_start[app_id + 1] - app_start[app_id], + ) + } +} diff --git a/os4-ref/src/logging.rs b/os4-ref/src/logging.rs new file mode 100644 index 0000000..e12448e --- /dev/null +++ b/os4-ref/src/logging.rs @@ -0,0 +1,45 @@ +//! Global logger + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +/// a simple logger +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +/// initiate logger +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os4-ref/src/main.rs b/os4-ref/src/main.rs new file mode 100644 index 0000000..8800735 --- /dev/null +++ b/os4-ref/src/main.rs @@ -0,0 +1,74 @@ +//! The main module and entrypoint +//! +//! Various facilities of the kernels are implemented as submodules. The most +//! important ones are: +//! +//! - [`trap`]: Handles all cases of switching from userspace to the kernel +//! - [`task`]: Task management +//! - [`syscall`]: System call handling and implementation +//! +//! The operating system also starts in this module. Kernel code starts +//! executing from `entry.asm`, after which [`rust_main()`] is called to +//! initialize various pieces of functionality. (See its source code for +//! details.) +//! +//! We then call [`task::run_first_task()`] and for the first time go to +//! userspace. + +#![no_std] +#![no_main] +#![feature(panic_info_message)] +#![feature(alloc_error_handler)] + +#[macro_use] +extern crate bitflags; +#[macro_use] +extern crate log; + +extern crate alloc; + +#[macro_use] +mod console; +mod config; +mod lang_items; +mod loader; +mod logging; +mod mm; +mod sbi; +mod sync; +pub mod syscall; +pub mod task; +mod timer; +pub mod trap; + +core::arch::global_asm!(include_str!("entry.asm")); +core::arch::global_asm!(include_str!("link_app.S")); + +/// clear BSS segment +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +/// the rust entry-point of os +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + mm::init(); + println!("[kernel] back to world!"); + mm::remap_test(); + trap::init(); + //trap::enable_interrupt(); + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + task::run_first_task(); + panic!("Unreachable in rust_main!"); +} diff --git a/os4-ref/src/mm/address.rs b/os4-ref/src/mm/address.rs new file mode 100644 index 0000000..57a08e8 --- /dev/null +++ b/os4-ref/src/mm/address.rs @@ -0,0 +1,245 @@ +//! Implementation of physical and virtual address and page number. + +use super::PageTableEntry; +use crate::config::{PAGE_SIZE, PAGE_SIZE_BITS}; +use core::fmt::{self, Debug, Formatter}; + +/// physical address +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysAddr(pub usize); + +/// virtual address +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtAddr(pub usize); + +/// physical page number +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysPageNum(pub usize); + +/// virtual page number +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtPageNum(pub usize); + +/// Debugging + +impl Debug for VirtAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VA:{:#x}", self.0)) + } +} +impl Debug for VirtPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VPN:{:#x}", self.0)) + } +} +impl Debug for PhysAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PA:{:#x}", self.0)) + } +} +impl Debug for PhysPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PPN:{:#x}", self.0)) + } +} + +/// T: {PhysAddr, VirtAddr, PhysPageNum, VirtPageNum} +/// T -> usize: T.0 +/// usize -> T: usize.into() + +impl From for PhysAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for PhysPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for usize { + fn from(v: PhysAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: PhysPageNum) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtPageNum) -> Self { + v.0 + } +} + +impl VirtAddr { + pub fn floor(&self) -> VirtPageNum { + VirtPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> VirtPageNum { + VirtPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for VirtPageNum { + fn from(v: VirtAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for VirtAddr { + fn from(v: VirtPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} +impl PhysAddr { + pub fn floor(&self) -> PhysPageNum { + PhysPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> PhysPageNum { + PhysPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for PhysPageNum { + fn from(v: PhysAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for PhysAddr { + fn from(v: PhysPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} + +impl VirtPageNum { + pub fn indexes(&self) -> [usize; 3] { + let mut vpn = self.0; + let mut idx = [0usize; 3]; + for i in (0..3).rev() { + idx[i] = vpn & 511; + vpn >>= 9; + } + idx + } +} + +impl PhysPageNum { + pub fn get_pte_array(&self) -> &'static mut [PageTableEntry] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut PageTableEntry, 512) } + } + pub fn get_bytes_array(&self) -> &'static mut [u8] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut u8, 4096) } + } + pub fn get_mut(&self) -> &'static mut T { + let pa: PhysAddr = (*self).into(); + unsafe { (pa.0 as *mut T).as_mut().unwrap() } + } +} + +pub trait StepByOne { + fn step(&mut self); +} +impl StepByOne for VirtPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +#[derive(Copy, Clone)] +/// a simple range structure for type T +pub struct SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + l: T, + r: T, +} +impl SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(start: T, end: T) -> Self { + assert!(start <= end, "start {:?} > end {:?}!", start, end); + Self { l: start, r: end } + } + pub fn get_start(&self) -> T { + self.l + } + pub fn get_end(&self) -> T { + self.r + } +} +impl IntoIterator for SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + type IntoIter = SimpleRangeIterator; + fn into_iter(self) -> Self::IntoIter { + SimpleRangeIterator::new(self.l, self.r) + } +} +/// iterator for the simple range structure +pub struct SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + current: T, + end: T, +} +impl SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(l: T, r: T) -> Self { + Self { current: l, end: r } + } +} +impl Iterator for SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + fn next(&mut self) -> Option { + if self.current == self.end { + None + } else { + let t = self.current; + self.current.step(); + Some(t) + } + } +} + +/// a simple range structure for virtual page number +pub type VPNRange = SimpleRange; diff --git a/os4-ref/src/mm/frame_allocator.rs b/os4-ref/src/mm/frame_allocator.rs new file mode 100644 index 0000000..2b1ae17 --- /dev/null +++ b/os4-ref/src/mm/frame_allocator.rs @@ -0,0 +1,136 @@ +//! Implementation of [`FrameAllocator`] which +//! controls all the frames in the operating system. + +use super::{PhysAddr, PhysPageNum}; +use crate::config::MEMORY_END; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use core::fmt::{self, Debug, Formatter}; +use lazy_static::*; + +/// manage a frame which has the same lifecycle as the tracker +pub struct FrameTracker { + pub ppn: PhysPageNum, +} + +impl FrameTracker { + pub fn new(ppn: PhysPageNum) -> Self { + // page cleaning + let bytes_array = ppn.get_bytes_array(); + for i in bytes_array { + *i = 0; + } + Self { ppn } + } +} + +impl Debug for FrameTracker { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("FrameTracker:PPN={:#x}", self.ppn.0)) + } +} + +impl Drop for FrameTracker { + fn drop(&mut self) { + frame_dealloc(self.ppn); + } +} + +trait FrameAllocator { + fn new() -> Self; + fn alloc(&mut self) -> Option; + fn dealloc(&mut self, ppn: PhysPageNum); +} + +/// an implementation for frame allocator +pub struct StackFrameAllocator { + current: usize, + end: usize, + recycled: Vec, +} + +impl StackFrameAllocator { + pub fn init(&mut self, l: PhysPageNum, r: PhysPageNum) { + self.current = l.0; + self.end = r.0; + } +} +impl FrameAllocator for StackFrameAllocator { + fn new() -> Self { + Self { + current: 0, + end: 0, + recycled: Vec::new(), + } + } + fn alloc(&mut self) -> Option { + if let Some(ppn) = self.recycled.pop() { + Some(ppn.into()) + } else if self.current == self.end { + None + } else { + self.current += 1; + Some((self.current - 1).into()) + } + } + fn dealloc(&mut self, ppn: PhysPageNum) { + let ppn = ppn.0; + // validity check + if ppn >= self.current || self.recycled.iter().any(|v| *v == ppn) { + panic!("Frame ppn={:#x} has not been allocated!", ppn); + } + // recycle + self.recycled.push(ppn); + } +} + +type FrameAllocatorImpl = StackFrameAllocator; + +lazy_static! { + /// frame allocator instance through lazy_static! + pub static ref FRAME_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(FrameAllocatorImpl::new()) }; +} + +/// initiate the frame allocator using `ekernel` and `MEMORY_END` +pub fn init_frame_allocator() { + extern "C" { + fn ekernel(); + } + FRAME_ALLOCATOR.exclusive_access().init( + PhysAddr::from(ekernel as usize).ceil(), + PhysAddr::from(MEMORY_END).floor(), + ); +} + +/// allocate a frame +pub fn frame_alloc() -> Option { + FRAME_ALLOCATOR + .exclusive_access() + .alloc() + .map(FrameTracker::new) +} + +/// deallocate a frame +fn frame_dealloc(ppn: PhysPageNum) { + FRAME_ALLOCATOR.exclusive_access().dealloc(ppn); +} + +#[allow(unused)] +/// a simple test for frame allocator +pub fn frame_allocator_test() { + let mut v: Vec = Vec::new(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + v.clear(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + drop(v); + info!("frame_allocator_test passed!"); +} diff --git a/os4-ref/src/mm/heap_allocator.rs b/os4-ref/src/mm/heap_allocator.rs new file mode 100644 index 0000000..d518fae --- /dev/null +++ b/os4-ref/src/mm/heap_allocator.rs @@ -0,0 +1,51 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[allow(unused)] +pub fn heap_test() { + use alloc::boxed::Box; + use alloc::vec::Vec; + extern "C" { + fn sbss(); + fn ebss(); + } + let bss_range = sbss as usize..ebss as usize; + let a = Box::new(5); + assert_eq!(*a, 5); + assert!(bss_range.contains(&(a.as_ref() as *const _ as usize))); + drop(a); + let mut v: Vec = Vec::new(); + for i in 0..500 { + v.push(i); + } + for (i, vi) in v.iter().enumerate().take(500) { + assert_eq!(*vi, i); + } + assert!(bss_range.contains(&(v.as_ptr() as usize))); + drop(v); + info!("heap_test passed!"); +} diff --git a/os4-ref/src/mm/memory_set.rs b/os4-ref/src/mm/memory_set.rs new file mode 100644 index 0000000..3e2aa19 --- /dev/null +++ b/os4-ref/src/mm/memory_set.rs @@ -0,0 +1,346 @@ +//! Implementation of [`MapArea`] and [`MemorySet`]. + +use super::{frame_alloc, FrameTracker}; +use super::{PTEFlags, PageTable, PageTableEntry}; +use super::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use super::{StepByOne, VPNRange}; +use crate::config::{MEMORY_END, PAGE_SIZE, TRAMPOLINE, TRAP_CONTEXT, USER_STACK_SIZE}; +use alloc::collections::BTreeMap; +use alloc::sync::Arc; +use alloc::vec::Vec; +use lazy_static::*; +use riscv::register::satp; +use spin::Mutex; + +extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss_with_stack(); + fn ebss(); + fn ekernel(); + fn strampoline(); +} + +lazy_static! { + /// a memory set instance through lazy_static! managing kernel space + pub static ref KERNEL_SPACE: Arc> = + Arc::new(Mutex::new(MemorySet::new_kernel())); +} + +/// memory set structure, controls virtual-memory space +pub struct MemorySet { + page_table: PageTable, + areas: Vec, +} + +impl MemorySet { + pub fn new_bare() -> Self { + Self { + page_table: PageTable::new(), + areas: Vec::new(), + } + } + pub fn token(&self) -> usize { + self.page_table.token() + } + /// Assume that no conflicts. + pub fn insert_framed_area( + &mut self, + start_va: VirtAddr, + end_va: VirtAddr, + permission: MapPermission, + ) { + self.push( + MapArea::new(start_va, end_va, MapType::Framed, permission), + None, + ); + } + fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) { + map_area.map(&mut self.page_table); + if let Some(data) = data { + map_area.copy_data(&mut self.page_table, data); + } + self.areas.push(map_area); + } + /// Mention that trampoline is not collected by areas. + fn map_trampoline(&mut self) { + self.page_table.map( + VirtAddr::from(TRAMPOLINE).into(), + PhysAddr::from(strampoline as usize).into(), + PTEFlags::R | PTEFlags::X, + ); + } + /// Without kernel stacks. + pub fn new_kernel() -> Self { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map kernel sections + info!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + info!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + info!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + info!( + ".bss [{:#x}, {:#x})", + sbss_with_stack as usize, ebss as usize + ); + info!("mapping .text section"); + memory_set.push( + MapArea::new( + (stext as usize).into(), + (etext as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::X, + ), + None, + ); + info!("mapping .rodata section"); + memory_set.push( + MapArea::new( + (srodata as usize).into(), + (erodata as usize).into(), + MapType::Identical, + MapPermission::R, + ), + None, + ); + info!("mapping .data section"); + memory_set.push( + MapArea::new( + (sdata as usize).into(), + (edata as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping .bss section"); + memory_set.push( + MapArea::new( + (sbss_with_stack as usize).into(), + (ebss as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping physical memory"); + memory_set.push( + MapArea::new( + (ekernel as usize).into(), + MEMORY_END.into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + memory_set + } + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map program headers of elf, with U flag + let elf = xmas_elf::ElfFile::new(elf_data).unwrap(); + let elf_header = elf.header; + let magic = elf_header.pt1.magic; + assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!"); + let ph_count = elf_header.pt2.ph_count(); + let mut max_end_vpn = VirtPageNum(0); + for i in 0..ph_count { + let ph = elf.program_header(i).unwrap(); + if ph.get_type().unwrap() == xmas_elf::program::Type::Load { + let start_va: VirtAddr = (ph.virtual_addr() as usize).into(); + let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into(); + let mut map_perm = MapPermission::U; + let ph_flags = ph.flags(); + if ph_flags.is_read() { + map_perm |= MapPermission::R; + } + if ph_flags.is_write() { + map_perm |= MapPermission::W; + } + if ph_flags.is_execute() { + map_perm |= MapPermission::X; + } + let map_area = MapArea::new(start_va, end_va, MapType::Framed, map_perm); + max_end_vpn = map_area.vpn_range.get_end(); + memory_set.push( + map_area, + Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]), + ); + } + } + // map user stack with U flags + let max_end_va: VirtAddr = max_end_vpn.into(); + let mut user_stack_bottom: usize = max_end_va.into(); + // guard page + user_stack_bottom += PAGE_SIZE; + let user_stack_top = user_stack_bottom + USER_STACK_SIZE; + memory_set.push( + MapArea::new( + user_stack_bottom.into(), + user_stack_top.into(), + MapType::Framed, + MapPermission::R | MapPermission::W | MapPermission::U, + ), + None, + ); + // map TrapContext + memory_set.push( + MapArea::new( + TRAP_CONTEXT.into(), + TRAMPOLINE.into(), + MapType::Framed, + MapPermission::R | MapPermission::W, + ), + None, + ); + ( + memory_set, + user_stack_top, + elf.header.pt2.entry_point() as usize, + ) + } + pub fn activate(&self) { + let satp = self.page_table.token(); + unsafe { + satp::write(satp); + core::arch::asm!("sfence.vma"); + } + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.page_table.translate(vpn) + } +} + +/// map area structure, controls a contiguous piece of virtual memory +pub struct MapArea { + vpn_range: VPNRange, + data_frames: BTreeMap, + map_type: MapType, + map_perm: MapPermission, +} + +impl MapArea { + pub fn new( + start_va: VirtAddr, + end_va: VirtAddr, + map_type: MapType, + map_perm: MapPermission, + ) -> Self { + let start_vpn: VirtPageNum = start_va.floor(); + let end_vpn: VirtPageNum = end_va.ceil(); + Self { + vpn_range: VPNRange::new(start_vpn, end_vpn), + data_frames: BTreeMap::new(), + map_type, + map_perm, + } + } + pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + let ppn: PhysPageNum; + match self.map_type { + MapType::Identical => { + ppn = PhysPageNum(vpn.0); + } + MapType::Framed => { + let frame = frame_alloc().unwrap(); + ppn = frame.ppn; + self.data_frames.insert(vpn, frame); + } + } + let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap(); + page_table.map(vpn, ppn, pte_flags); + } + #[allow(unused)] + pub fn unmap_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + #[allow(clippy::single_match)] + match self.map_type { + MapType::Framed => { + self.data_frames.remove(&vpn); + } + _ => {} + } + page_table.unmap(vpn); + } + pub fn map(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.map_one(page_table, vpn); + } + } + #[allow(unused)] + pub fn unmap(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.unmap_one(page_table, vpn); + } + } + /// data: start-aligned but maybe with shorter length + /// assume that all frames were cleared before + pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) { + assert_eq!(self.map_type, MapType::Framed); + let mut start: usize = 0; + let mut current_vpn = self.vpn_range.get_start(); + let len = data.len(); + loop { + let src = &data[start..len.min(start + PAGE_SIZE)]; + let dst = &mut page_table + .translate(current_vpn) + .unwrap() + .ppn() + .get_bytes_array()[..src.len()]; + dst.copy_from_slice(src); + start += PAGE_SIZE; + if start >= len { + break; + } + current_vpn.step(); + } + } +} + +#[derive(Copy, Clone, PartialEq, Debug)] +/// map type for memory set: identical or framed +pub enum MapType { + Identical, + Framed, +} + +bitflags! { + /// map permission corresponding to that in pte: `R W X U` + pub struct MapPermission: u8 { + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + } +} + +#[allow(unused)] +pub fn remap_test() { + let mut kernel_space = KERNEL_SPACE.lock(); + let mid_text: VirtAddr = ((stext as usize + etext as usize) / 2).into(); + let mid_rodata: VirtAddr = ((srodata as usize + erodata as usize) / 2).into(); + let mid_data: VirtAddr = ((sdata as usize + edata as usize) / 2).into(); + assert!(!kernel_space + .page_table + .translate(mid_text.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_rodata.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_data.floor()) + .unwrap() + .executable()); + info!("remap_test passed!"); +} diff --git a/os4-ref/src/mm/mod.rs b/os4-ref/src/mm/mod.rs new file mode 100644 index 0000000..3745b63 --- /dev/null +++ b/os4-ref/src/mm/mod.rs @@ -0,0 +1,29 @@ +//! Memory management implementation +//! +//! SV39 page-based virtual-memory architecture for RV64 systems, and +//! everything about memory management, like frame allocator, page table, +//! map area and memory set, is implemented here. +//! +//! Every task or process has a memory_set to control its virtual memory. + + +mod address; +mod frame_allocator; +mod heap_allocator; +mod memory_set; +mod page_table; + +pub use address::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use address::{StepByOne, VPNRange}; +pub use frame_allocator::{frame_alloc, FrameTracker}; +pub use memory_set::remap_test; +pub use memory_set::{MapPermission, MemorySet, KERNEL_SPACE}; +pub use page_table::{translated_byte_buffer, PageTableEntry}; +use page_table::{PTEFlags, PageTable}; + +/// initiate heap allocator, frame allocator and kernel space +pub fn init() { + heap_allocator::init_heap(); + frame_allocator::init_frame_allocator(); + KERNEL_SPACE.lock().activate(); +} diff --git a/os4-ref/src/mm/page_table.rs b/os4-ref/src/mm/page_table.rs new file mode 100644 index 0000000..b7ae072 --- /dev/null +++ b/os4-ref/src/mm/page_table.rs @@ -0,0 +1,157 @@ +//! Implementation of [`PageTableEntry`] and [`PageTable`]. + +use super::{frame_alloc, FrameTracker, PhysPageNum, StepByOne, VirtAddr, VirtPageNum}; +use alloc::vec; +use alloc::vec::Vec; +use bitflags::*; + +bitflags! { + /// page table entry flags + pub struct PTEFlags: u8 { + const V = 1 << 0; + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + const G = 1 << 5; + const A = 1 << 6; + const D = 1 << 7; + } +} + +#[derive(Copy, Clone)] +#[repr(C)] +/// page table entry structure +pub struct PageTableEntry { + pub bits: usize, +} + +impl PageTableEntry { + pub fn new(ppn: PhysPageNum, flags: PTEFlags) -> Self { + PageTableEntry { + bits: ppn.0 << 10 | flags.bits as usize, + } + } + pub fn empty() -> Self { + PageTableEntry { bits: 0 } + } + pub fn ppn(&self) -> PhysPageNum { + (self.bits >> 10 & ((1usize << 44) - 1)).into() + } + pub fn flags(&self) -> PTEFlags { + PTEFlags::from_bits(self.bits as u8).unwrap() + } + pub fn is_valid(&self) -> bool { + (self.flags() & PTEFlags::V) != PTEFlags::empty() + } + pub fn readable(&self) -> bool { + (self.flags() & PTEFlags::R) != PTEFlags::empty() + } + pub fn writable(&self) -> bool { + (self.flags() & PTEFlags::W) != PTEFlags::empty() + } + pub fn executable(&self) -> bool { + (self.flags() & PTEFlags::X) != PTEFlags::empty() + } +} + +/// page table structure +pub struct PageTable { + root_ppn: PhysPageNum, + frames: Vec, +} + +/// Assume that it won't oom when creating/mapping. +impl PageTable { + pub fn new() -> Self { + let frame = frame_alloc().unwrap(); + PageTable { + root_ppn: frame.ppn, + frames: vec![frame], + } + } + /// Temporarily used to get arguments from user space. + pub fn from_token(satp: usize) -> Self { + Self { + root_ppn: PhysPageNum::from(satp & ((1usize << 44) - 1)), + frames: Vec::new(), + } + } + fn find_pte_create(&mut self, vpn: VirtPageNum) -> Option<&mut PageTableEntry> { + let mut idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&mut PageTableEntry> = None; + for (i, idx) in idxs.iter_mut().enumerate() { + let pte = &mut ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + let frame = frame_alloc().unwrap(); + *pte = PageTableEntry::new(frame.ppn, PTEFlags::V); + self.frames.push(frame); + } + ppn = pte.ppn(); + } + result + } + fn find_pte(&self, vpn: VirtPageNum) -> Option<&PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&PageTableEntry> = None; + for (i, idx) in idxs.iter().enumerate() { + let pte = &ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + return None; + } + ppn = pte.ppn(); + } + result + } + #[allow(unused)] + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(!pte.is_valid(), "vpn {:?} is mapped before mapping", vpn); + *pte = PageTableEntry::new(ppn, flags | PTEFlags::V); + } + #[allow(unused)] + pub fn unmap(&mut self, vpn: VirtPageNum) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(pte.is_valid(), "vpn {:?} is invalid before unmapping", vpn); + *pte = PageTableEntry::empty(); + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.find_pte(vpn).copied() + } + pub fn token(&self) -> usize { + 8usize << 60 | self.root_ppn.0 + } +} + +/// translate a pointer to a mutable u8 Vec through page table +pub fn translated_byte_buffer(token: usize, ptr: *const u8, len: usize) -> Vec<&'static mut [u8]> { + let page_table = PageTable::from_token(token); + let mut start = ptr as usize; + let end = start + len; + let mut v = Vec::new(); + while start < end { + let start_va = VirtAddr::from(start); + let mut vpn = start_va.floor(); + let ppn = page_table.translate(vpn).unwrap().ppn(); + vpn.step(); + let mut end_va: VirtAddr = vpn.into(); + end_va = end_va.min(VirtAddr::from(end)); + if end_va.page_offset() == 0 { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..]); + } else { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..end_va.page_offset()]); + } + start = end_va.into(); + } + v +} diff --git a/os4-ref/src/sbi.rs b/os4-ref/src/sbi.rs new file mode 100644 index 0000000..4af7620 --- /dev/null +++ b/os4-ref/src/sbi.rs @@ -0,0 +1,45 @@ +//! SBI call wrappers + +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +/// general sbi call +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +/// use sbi call to set timer +pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); +} + +/// use sbi call to putchar in console (qemu uart handler) +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +/// use sbi call to getchar from console (qemu uart handler) +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +/// use sbi call to shutdown the kernel +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os4-ref/src/sync/mod.rs b/os4-ref/src/sync/mod.rs new file mode 100644 index 0000000..4743e31 --- /dev/null +++ b/os4-ref/src/sync/mod.rs @@ -0,0 +1,5 @@ +//! Synchronization and interior mutability primitives + +mod up; + +pub use up::UPSafeCell; diff --git a/os4-ref/src/sync/up.rs b/os4-ref/src/sync/up.rs new file mode 100644 index 0000000..039b039 --- /dev/null +++ b/os4-ref/src/sync/up.rs @@ -0,0 +1,31 @@ +//! Uniprocessor interior mutability primitives + +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os4-ref/src/syscall/fs.rs b/os4-ref/src/syscall/fs.rs new file mode 100644 index 0000000..0cbd0ca --- /dev/null +++ b/os4-ref/src/syscall/fs.rs @@ -0,0 +1,21 @@ +//! File and filesystem-related syscalls + +use crate::mm::translated_byte_buffer; +use crate::task::current_user_token; + +const FD_STDOUT: usize = 1; + +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDOUT => { + let buffers = translated_byte_buffer(current_user_token(), buf, len); + for buffer in buffers { + print!("{}", core::str::from_utf8(buffer).unwrap()); + } + len as isize + } + _ => { + panic!("Unsupported fd in sys_write!"); + } + } +} diff --git a/os4-ref/src/syscall/mod.rs b/os4-ref/src/syscall/mod.rs new file mode 100644 index 0000000..a3be941 --- /dev/null +++ b/os4-ref/src/syscall/mod.rs @@ -0,0 +1,42 @@ +//! Implementation of syscalls +//! +//! The single entry point to all system calls, [`syscall()`], is called +//! whenever userspace wishes to perform a system call using the `ecall` +//! instruction. In this case, the processor raises an 'Environment call from +//! U-mode' exception, which is handled as one of the cases in +//! [`crate::trap::trap_handler`]. +//! +//! For clarity, each single syscall is implemented as its own function, named +//! `sys_` then the name of the syscall. You can find functions like this in +//! submodules, and you should also implement syscalls this way. + +const SYSCALL_WRITE: usize = 64; +const SYSCALL_EXIT: usize = 93; +const SYSCALL_YIELD: usize = 124; +const SYSCALL_GET_TIME: usize = 169; +const SYSCALL_MUNMAP: usize = 215; +const SYSCALL_MMAP: usize = 222; +const SYSCALL_SET_PRIORITY: usize = 140; +const SYSCALL_TASK_INFO: usize = 410; + +mod fs; +mod process; + +use fs::*; +use process::*; + +/// handle syscall exception with `syscall_id` and other arguments +pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize { + // LAB1: You may need to update syscall info here. + match syscall_id { + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_EXIT => sys_exit(args[0] as i32), + SYSCALL_YIELD => sys_yield(), + SYSCALL_GET_TIME => sys_get_time(args[0] as *mut TimeVal, args[1]), + SYSCALL_MMAP => sys_mmap(args[0], args[1], args[2]), + SYSCALL_MUNMAP => sys_munmap(args[0], args[1]), + SYSCALL_SET_PRIORITY => sys_set_priority(args[0] as isize), + SYSCALL_TASK_INFO => sys_task_info(args[0] as *mut TaskInfo), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os4-ref/src/syscall/process.rs b/os4-ref/src/syscall/process.rs new file mode 100644 index 0000000..1274ce3 --- /dev/null +++ b/os4-ref/src/syscall/process.rs @@ -0,0 +1,62 @@ +//! Process management syscalls + +use crate::config::MAX_SYSCALL_NUM; +use crate::task::{exit_current_and_run_next, suspend_current_and_run_next, TaskStatus}; +use crate::timer::get_time_us; + +#[repr(C)] +#[derive(Debug)] +pub struct TimeVal { + pub sec: usize, + pub usec: usize, +} + +#[derive(Clone, Copy)] +pub struct TaskInfo { + pub status: TaskStatus, + pub syscall_times: [u32; MAX_SYSCALL_NUM], + pub time: usize, +} + +pub fn sys_exit(exit_code: i32) -> ! { + info!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(); + panic!("Unreachable in sys_exit!"); +} + +/// current task gives up resources for other tasks +pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 +} + +// YOUR JOB: 引入虚地址后重写 sys_get_time +pub fn sys_get_time(_ts: *mut TimeVal, _tz: usize) -> isize { + let _us = get_time_us(); + // unsafe { + // *ts = TimeVal { + // sec: us / 1_000_000, + // usec: us % 1_000_000, + // }; + // } + 0 +} + +// CLUE: 从 ch4 开始不再对调度算法进行测试~ +pub fn sys_set_priority(_prio: isize) -> isize { + -1 +} + +// YOUR JOB: 扩展内核以实现 sys_mmap 和 sys_munmap +pub fn sys_mmap(_start: usize, _len: usize, _port: usize) -> isize { + -1 +} + +pub fn sys_munmap(_start: usize, _len: usize) -> isize { + -1 +} + +// YOUR JOB: 引入虚地址后重写 sys_task_info +pub fn sys_task_info(ti: *mut TaskInfo) -> isize { + -1 +} diff --git a/os4-ref/src/task/context.rs b/os4-ref/src/task/context.rs new file mode 100644 index 0000000..225b396 --- /dev/null +++ b/os4-ref/src/task/context.rs @@ -0,0 +1,28 @@ +//! Implementation of [`TaskContext`] +use crate::trap::trap_return; + +#[derive(Copy, Clone)] +#[repr(C)] +/// task context structure containing some registers +pub struct TaskContext { + ra: usize, + sp: usize, + s: [usize; 12], +} + +impl TaskContext { + pub fn zero_init() -> Self { + Self { + ra: 0, + sp: 0, + s: [0; 12], + } + } + pub fn goto_trap_return(kstack_ptr: usize) -> Self { + Self { + ra: trap_return as usize, + sp: kstack_ptr, + s: [0; 12], + } + } +} diff --git a/os4-ref/src/task/mod.rs b/os4-ref/src/task/mod.rs new file mode 100644 index 0000000..9c487dc --- /dev/null +++ b/os4-ref/src/task/mod.rs @@ -0,0 +1,193 @@ +//! Task management implementation +//! +//! Everything about task management, like starting and switching tasks is +//! implemented here. +//! +//! A single global instance of [`TaskManager`] called `TASK_MANAGER` controls +//! all the tasks in the operating system. +//! +//! Be careful when you see [`__switch`]. Control flow around this function +//! might not be what you expect. + +mod context; +mod switch; +#[allow(clippy::module_inception)] +mod task; + +use crate::loader::{get_app_data, get_num_app}; +use crate::sync::UPSafeCell; +use crate::trap::TrapContext; +use alloc::vec::Vec; +use lazy_static::*; +pub use switch::__switch; +pub use task::{TaskControlBlock, TaskStatus}; + +pub use context::TaskContext; + +/// The task manager, where all the tasks are managed. +/// +/// Functions implemented on `TaskManager` deals with all task state transitions +/// and task context switching. For convenience, you can find wrappers around it +/// in the module level. +/// +/// Most of `TaskManager` are hidden behind the field `inner`, to defer +/// borrowing checks to runtime. You can see examples on how to use `inner` in +/// existing functions on `TaskManager`. +pub struct TaskManager { + /// total number of tasks + num_app: usize, + /// use inner value to get mutable access + inner: UPSafeCell, +} + +/// The task manager inner in 'UPSafeCell' +struct TaskManagerInner { + /// task list + tasks: Vec, + /// id of current `Running` task + current_task: usize, +} + +lazy_static! { + /// a `TaskManager` instance through lazy_static! + pub static ref TASK_MANAGER: TaskManager = { + info!("init TASK_MANAGER"); + let num_app = get_num_app(); + info!("num_app = {}", num_app); + let mut tasks: Vec = Vec::new(); + for i in 0..num_app { + tasks.push(TaskControlBlock::new(get_app_data(i), i)); + } + TaskManager { + num_app, + inner: unsafe { + UPSafeCell::new(TaskManagerInner { + tasks, + current_task: 0, + }) + }, + } + }; +} + +impl TaskManager { + /// Run the first task in task list. + /// + /// Generally, the first task in task list is an idle task (we call it zero process later). + /// But in ch4, we load apps statically, so the first task is a real app. + fn run_first_task(&self) -> ! { + let mut inner = self.inner.exclusive_access(); + let next_task = &mut inner.tasks[0]; + next_task.task_status = TaskStatus::Running; + let next_task_cx_ptr = &next_task.task_cx as *const TaskContext; + drop(inner); + let mut _unused = TaskContext::zero_init(); + // before this, we should drop local variables that must be dropped manually + unsafe { + __switch(&mut _unused as *mut _, next_task_cx_ptr); + } + panic!("unreachable in run_first_task!"); + } + + /// Change the status of current `Running` task into `Ready`. + fn mark_current_suspended(&self) { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[current].task_status = TaskStatus::Ready; + } + + /// Change the status of current `Running` task into `Exited`. + fn mark_current_exited(&self) { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[current].task_status = TaskStatus::Exited; + } + + /// Find next task to run and return task id. + /// + /// In this case, we only return the first `Ready` task in task list. + fn find_next_task(&self) -> Option { + let inner = self.inner.exclusive_access(); + let current = inner.current_task; + (current + 1..current + self.num_app + 1) + .map(|id| id % self.num_app) + .find(|id| inner.tasks[*id].task_status == TaskStatus::Ready) + } + + /// Get the current 'Running' task's token. + fn get_current_token(&self) -> usize { + let inner = self.inner.exclusive_access(); + inner.tasks[inner.current_task].get_user_token() + } + + #[allow(clippy::mut_from_ref)] + /// Get the current 'Running' task's trap contexts. + fn get_current_trap_cx(&self) -> &mut TrapContext { + let inner = self.inner.exclusive_access(); + inner.tasks[inner.current_task].get_trap_cx() + } + + /// Switch current `Running` task to the task we have found, + /// or there is no `Ready` task and we can exit with all applications completed + fn run_next_task(&self) { + if let Some(next) = self.find_next_task() { + let mut inner = self.inner.exclusive_access(); + let current = inner.current_task; + inner.tasks[next].task_status = TaskStatus::Running; + inner.current_task = next; + let current_task_cx_ptr = &mut inner.tasks[current].task_cx as *mut TaskContext; + let next_task_cx_ptr = &inner.tasks[next].task_cx as *const TaskContext; + drop(inner); + // before this, we should drop local variables that must be dropped manually + unsafe { + __switch(current_task_cx_ptr, next_task_cx_ptr); + } + // go back to user mode + } else { + panic!("All applications completed!"); + } + } +} + +/// Run the first task in task list. +pub fn run_first_task() { + TASK_MANAGER.run_first_task(); +} + +/// Switch current `Running` task to the task we have found, +/// or there is no `Ready` task and we can exit with all applications completed +fn run_next_task() { + TASK_MANAGER.run_next_task(); +} + +/// Change the status of current `Running` task into `Ready`. +fn mark_current_suspended() { + TASK_MANAGER.mark_current_suspended(); +} + +/// Change the status of current `Running` task into `Exited`. +fn mark_current_exited() { + TASK_MANAGER.mark_current_exited(); +} + +/// Suspend the current 'Running' task and run the next task in task list. +pub fn suspend_current_and_run_next() { + mark_current_suspended(); + run_next_task(); +} + +/// Exit the current 'Running' task and run the next task in task list. +pub fn exit_current_and_run_next() { + mark_current_exited(); + run_next_task(); +} + +/// Get the current 'Running' task's token. +pub fn current_user_token() -> usize { + TASK_MANAGER.get_current_token() +} + +/// Get the current 'Running' task's trap contexts. +pub fn current_trap_cx() -> &'static mut TrapContext { + TASK_MANAGER.get_current_trap_cx() +} diff --git a/os4-ref/src/task/switch.S b/os4-ref/src/task/switch.S new file mode 100644 index 0000000..3f985d2 --- /dev/null +++ b/os4-ref/src/task/switch.S @@ -0,0 +1,34 @@ +.altmacro +.macro SAVE_SN n + sd s\n, (\n+2)*8(a0) +.endm +.macro LOAD_SN n + ld s\n, (\n+2)*8(a1) +.endm + .section .text + .globl __switch +__switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + diff --git a/os4-ref/src/task/switch.rs b/os4-ref/src/task/switch.rs new file mode 100644 index 0000000..af08289 --- /dev/null +++ b/os4-ref/src/task/switch.rs @@ -0,0 +1,16 @@ +//! Rust wrapper around `__switch`. +//! +//! Switching to a different task's context happens here. The actual +//! implementation must not be in Rust and (essentially) has to be in assembly +//! language (Do you know why?), so this module really is just a wrapper around +//! `switch.S`. + +core::arch::global_asm!(include_str!("switch.S")); + +use super::TaskContext; + +extern "C" { + /// Switch to the context of `next_task_cx_ptr`, saving the current context + /// in `current_task_cx_ptr`. + pub fn __switch(current_task_cx_ptr: *mut TaskContext, next_task_cx_ptr: *const TaskContext); +} diff --git a/os4-ref/src/task/task.rs b/os4-ref/src/task/task.rs new file mode 100644 index 0000000..892d2bf --- /dev/null +++ b/os4-ref/src/task/task.rs @@ -0,0 +1,64 @@ +//! Types related to task management +use super::TaskContext; +use crate::config::{kernel_stack_position, TRAP_CONTEXT}; +use crate::mm::{MapPermission, MemorySet, PhysPageNum, VirtAddr, KERNEL_SPACE}; +use crate::trap::{trap_handler, TrapContext}; + +/// task control block structure +pub struct TaskControlBlock { + pub task_status: TaskStatus, + pub task_cx: TaskContext, + pub memory_set: MemorySet, + pub trap_cx_ppn: PhysPageNum, + pub base_size: usize, +} + +impl TaskControlBlock { + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + pub fn get_user_token(&self) -> usize { + self.memory_set.token() + } + pub fn new(elf_data: &[u8], app_id: usize) -> Self { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + let task_status = TaskStatus::Ready; + // map a kernel-stack in kernel space + let (kernel_stack_bottom, kernel_stack_top) = kernel_stack_position(app_id); + KERNEL_SPACE.lock().insert_framed_area( + kernel_stack_bottom.into(), + kernel_stack_top.into(), + MapPermission::R | MapPermission::W, + ); + let task_control_block = Self { + task_status, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + memory_set, + trap_cx_ppn, + base_size: user_sp, + }; + // prepare TrapContext in user space + let trap_cx = task_control_block.get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.lock().token(), + kernel_stack_top, + trap_handler as usize, + ); + task_control_block + } +} + +#[derive(Copy, Clone, PartialEq)] +/// task status: UnInit, Ready, Running, Exited +pub enum TaskStatus { + Ready, + Running, + Exited, +} diff --git a/os4-ref/src/timer.rs b/os4-ref/src/timer.rs new file mode 100644 index 0000000..4f40494 --- /dev/null +++ b/os4-ref/src/timer.rs @@ -0,0 +1,23 @@ +//! RISC-V timer-related functionality + +use crate::config::CLOCK_FREQ; +use crate::sbi::set_timer; +use riscv::register::time; + +const TICKS_PER_SEC: usize = 100; +const MICRO_PER_SEC: usize = 1_000_000; + +/// read the `mtime` register +pub fn get_time() -> usize { + time::read() +} + +/// get current time in microseconds +pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) +} + +/// set the next timer interrupt +pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); +} diff --git a/os4-ref/src/trap/context.rs b/os4-ref/src/trap/context.rs new file mode 100644 index 0000000..420c016 --- /dev/null +++ b/os4-ref/src/trap/context.rs @@ -0,0 +1,40 @@ +//! Implementation of [`TrapContext`] + +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +/// trap context structure containing sstatus, sepc and registers +pub struct TrapContext { + pub x: [usize; 32], + pub sstatus: Sstatus, + pub sepc: usize, + pub kernel_satp: usize, + pub kernel_sp: usize, + pub trap_handler: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context( + entry: usize, + sp: usize, + kernel_satp: usize, + kernel_sp: usize, + trap_handler: usize, + ) -> Self { + let mut sstatus = sstatus::read(); + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + kernel_satp, + kernel_sp, + trap_handler, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os4-ref/src/trap/mod.rs b/os4-ref/src/trap/mod.rs new file mode 100644 index 0000000..20c52b2 --- /dev/null +++ b/os4-ref/src/trap/mod.rs @@ -0,0 +1,115 @@ +//! Trap handling functionality +//! +//! For rCore, we have a single trap entry point, namely `__alltraps`. At +//! initialization in [`init()`], we set the `stvec` CSR to point to it. +//! +//! All traps go through `__alltraps`, which is defined in `trap.S`. The +//! assembly language code does just enough work restore the kernel space +//! context, ensuring that Rust code safely runs, and transfers control to +//! [`trap_handler()`]. +//! +//! It then calls different functionality based on what exactly the exception +//! was. For example, timer interrupts trigger task preemption, and syscalls go +//! to [`syscall()`]. +mod context; + +use crate::config::{TRAMPOLINE, TRAP_CONTEXT}; +use crate::syscall::syscall; +use crate::task::{ + current_trap_cx, current_user_token, exit_current_and_run_next, suspend_current_and_run_next, +}; +use crate::timer::set_next_trigger; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Interrupt, Trap}, + sie, stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +pub fn init() { + set_kernel_trap_entry(); +} + +fn set_kernel_trap_entry() { + unsafe { + stvec::write(trap_from_kernel as usize, TrapMode::Direct); + } +} + +fn set_user_trap_entry() { + unsafe { + stvec::write(TRAMPOLINE as usize, TrapMode::Direct); + } +} + +pub fn enable_timer_interrupt() { + unsafe { + sie::set_stimer(); + } +} + +#[no_mangle] +pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let cx = current_trap_cx(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + cx.sepc += 4; + cx.x[10] = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]) as usize; + } + Trap::Exception(Exception::StoreFault) + | Trap::Exception(Exception::StorePageFault) + | Trap::Exception(Exception::LoadPageFault) => { + error!("[kernel] PageFault in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", stval, cx.sepc); + exit_current_and_run_next(); + } + Trap::Exception(Exception::IllegalInstruction) => { + error!("[kernel] IllegalInstruction in application, core dumped."); + exit_current_and_run_next(); + } + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + trap_return(); +} + +#[no_mangle] +pub fn trap_return() -> ! { + set_user_trap_entry(); + let trap_cx_ptr = TRAP_CONTEXT; + let user_satp = current_user_token(); + extern "C" { + fn __alltraps(); + fn __restore(); + } + let restore_va = __restore as usize - __alltraps as usize + TRAMPOLINE; + unsafe { + core::arch::asm!( + "fence.i", + "jr {restore_va}", + restore_va = in(reg) restore_va, + in("a0") trap_cx_ptr, + in("a1") user_satp, + options(noreturn) + ); + } +} + +#[no_mangle] +pub fn trap_from_kernel() -> ! { + panic!("a trap from kernel!"); +} + +pub use context::TrapContext; diff --git a/os4-ref/src/trap/trap.S b/os4-ref/src/trap/trap.S new file mode 100644 index 0000000..c0e2d15 --- /dev/null +++ b/os4-ref/src/trap/trap.S @@ -0,0 +1,69 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text.trampoline + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->*TrapContext in user space, sscratch->user stack + # save other general purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they have been saved in TrapContext + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it in TrapContext + csrr t2, sscratch + sd t2, 2*8(sp) + # load kernel_satp into t0 + ld t0, 34*8(sp) + # load trap_handler into t1 + ld t1, 36*8(sp) + # move to kernel_sp + ld sp, 35*8(sp) + # switch to kernel space + csrw satp, t0 + sfence.vma + # jump to trap_handler + jr t1 + +__restore: + # a0: *TrapContext in user space(Constant); a1: user space token + # switch to user space + csrw satp, a1 + sfence.vma + csrw sscratch, a0 + mv sp, a0 + # now sp points to TrapContext in user space, start restoring based on it + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + # restore general purpose registers except x0/sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # back to user stack + ld sp, 2*8(sp) + sret diff --git a/os5-ref/.cargo/config b/os5-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os5-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os5-ref/Cargo.toml b/os5-ref/Cargo.toml new file mode 100644 index 0000000..e9bacac --- /dev/null +++ b/os5-ref/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +bitflags = "1.2.1" +buddy_system_allocator = "0.6" +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } +spin = "0.9" +lock_api = "=0.4.6" +xmas-elf = "0.7.0" diff --git a/os5-ref/Makefile b/os5-ref/Makefile new file mode 100644 index 0000000..f476572 --- /dev/null +++ b/os5-ref/Makefile @@ -0,0 +1,55 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -o 'ch[0-9]' | grep -o '[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean run-inner \ No newline at end of file diff --git a/os5-ref/build.rs b/os5-ref/build.rs new file mode 100644 index 0000000..d333f8c --- /dev/null +++ b/os5-ref/build.rs @@ -0,0 +1,71 @@ +//! Building applications linker + +use std::fs::{read_dir, File}; +use std::io::{Result, Write}; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); + insert_app_data().unwrap(); +} + +static TARGET_PATH: &str = "../user/build/elf/"; + +/// get app data and build linker +/// while saving app names in order +fn insert_app_data() -> Result<()> { + let mut f = File::create("src/link_app.S").unwrap(); + let mut apps: Vec<_> = read_dir("../user/build/elf/") + .unwrap() + .into_iter() + .map(|dir_entry| { + let mut name_with_ext = dir_entry.unwrap().file_name().into_string().unwrap(); + name_with_ext.drain(name_with_ext.find('.').unwrap()..name_with_ext.len()); + name_with_ext + }) + .collect(); + apps.sort(); + + writeln!( + f, + r#" + .align 3 + .section .data + .global _num_app +_num_app: + .quad {}"#, + apps.len() + )?; + + for i in 0..apps.len() { + writeln!(f, r#" .quad app_{}_start"#, i)?; + } + writeln!(f, r#" .quad app_{}_end"#, apps.len() - 1)?; + + writeln!( + f, + r#" + .global _app_names +_app_names:"# + )?; + for app in apps.iter() { + writeln!(f, r#" .string "{}""#, app)?; + } + + for (idx, app) in apps.iter().enumerate() { + println!("app_{}: {}", idx, app); + writeln!( + f, + r#" + .section .data + .global app_{0}_start + .global app_{0}_end + .align 3 +app_{0}_start: + .incbin "{2}{1}.elf" +app_{0}_end:"#, + idx, app, TARGET_PATH + )?; + } + Ok(()) +} diff --git a/os5-ref/src/config.rs b/os5-ref/src/config.rs new file mode 100644 index 0000000..e2dcc10 --- /dev/null +++ b/os5-ref/src/config.rs @@ -0,0 +1,13 @@ +//! Constants used in rCore + +pub const USER_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_HEAP_SIZE: usize = 0x20_0000; +pub const MEMORY_END: usize = 0x88000000; +pub const PAGE_SIZE: usize = 0x1000; +pub const PAGE_SIZE_BITS: usize = 0xc; +pub const MAX_SYSCALL_NUM: usize = 500; + +pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1; +pub const TRAP_CONTEXT: usize = TRAMPOLINE - PAGE_SIZE; +pub const CLOCK_FREQ: usize = 12500000; diff --git a/os5-ref/src/console.rs b/os5-ref/src/console.rs new file mode 100644 index 0000000..a23a0e0 --- /dev/null +++ b/os5-ref/src/console.rs @@ -0,0 +1,130 @@ +//! SBI console driver, for text output + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +/// print string macro +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +/// println string macro +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} + +/* +以下代码提供了与颜色相关的 ANSI 转义字符，以及彩色输出可以使用的函数与宏。 + +可以使用它们，甚至扩展它们，来提升开发体验和显示效果。 +*/ + +// 使用 ANSI 转义字符来加上颜色 +#[macro_export] +macro_rules! colorize { + ($content: ident, $foreground_color: ident) => { + format_args!("\u{1B}[{}m{}\u{1B}[0m", $foreground_color as u8, $content) + }; + ($content: ident, $foreground_color: ident, $background_color: ident) => { + format_args!( + "\u{1B}[{}m\u{1B}[{}m{}\u{1B}[0m", + $foreground_color.into(), + $background_color.into(), + $content + ) + }; +} + +pub fn print_colorized( + args: fmt::Arguments, + foreground_color: impl Into, + background_color: impl Into, +) { + Stdout + .write_fmt(colorize!(args, foreground_color, background_color)) + .unwrap(); +} + +#[macro_export] +macro_rules! print_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!($fmt $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + }; +} + +#[macro_export] +macro_rules! println_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!(concat!($fmt, "\n") $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + } +} + +#[allow(dead_code)] +pub enum ANSICON { + Reset = 0, + Bold = 1, + Underline = 4, + Blink = 5, + Reverse = 7, + FgBlack = 30, + FgRed = 31, + FgGreen = 32, + FgYellow = 33, + FgBlue = 34, + FgMagenta = 35, + FgCyan = 36, + FgWhite = 37, + FgDefault = 39, + FgLightGray = 90, + FgLightRed = 91, + FgLightGreen = 92, + FgLightYellow = 93, + FgLightBlue = 94, + FgLightMagenta = 95, + FgLightCyan = 96, + FgLightWhite = 97, + BgBlack = 40, + BgRed = 41, + BgGreen = 42, + BgYellow = 43, + BgBlue = 44, + BgMagenta = 45, + BgCyan = 46, + BgWhite = 47, + BgDefault = 49, + BgLightGray = 100, + BgLightRed = 101, + BgLightGreen = 102, + BgLightYellow = 103, + BgLightBlue = 104, + BgLightMagenta = 105, + BgLightCyan = 106, + BgLightWhite = 107, +} + +impl From for u8 { + fn from(con: ANSICON) -> Self { + con as Self + } +} diff --git a/os5-ref/src/entry.asm b/os5-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os5-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os5-ref/src/lang_items.rs b/os5-ref/src/lang_items.rs new file mode 100644 index 0000000..e52afff --- /dev/null +++ b/os5-ref/src/lang_items.rs @@ -0,0 +1,29 @@ +//! The panic handler + +use crate::console::ANSICON; +use crate::sbi::shutdown; + +use core::panic::PanicInfo; + +#[panic_handler] +/// panic handler +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println_colorized!( + "[kernel] Panicked at {}:{} {}", + ANSICON::FgRed, + ANSICON::BgDefault, + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println_colorized!( + "[kernel] Panicked: {}", + ANSICON::FgRed, + ANSICON::BgDefault, + info.message().unwrap() + ); + } + shutdown() +} diff --git a/os5-ref/src/linker.ld b/os5-ref/src/linker.ld new file mode 100644 index 0000000..5baafbd --- /dev/null +++ b/os5-ref/src/linker.ld @@ -0,0 +1,53 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + . = ALIGN(4K); + strampoline = .; + *(.text.trampoline); + . = ALIGN(4K); + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + sbss_with_stack = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os5-ref/src/loader.rs b/os5-ref/src/loader.rs new file mode 100644 index 0000000..a2b8fa4 --- /dev/null +++ b/os5-ref/src/loader.rs @@ -0,0 +1,71 @@ +//! Loading user applications into memory + +use alloc::vec::Vec; +use lazy_static::*; + +/// Get the total number of applications. +pub fn get_num_app() -> usize { + extern "C" { + fn _num_app(); + } + unsafe { (_num_app as usize as *const usize).read_volatile() } +} + +/// get applications data +pub fn get_app_data(app_id: usize) -> &'static [u8] { + extern "C" { + fn _num_app(); + } + let num_app_ptr = _num_app as usize as *const usize; + let num_app = get_num_app(); + let app_start = unsafe { core::slice::from_raw_parts(num_app_ptr.add(1), num_app + 1) }; + assert!(app_id < num_app); + unsafe { + core::slice::from_raw_parts( + app_start[app_id] as *const u8, + app_start[app_id + 1] - app_start[app_id], + ) + } +} + +lazy_static! { + /// A global read-only vector for saving app names + static ref APP_NAMES: Vec<&'static str> = { + let num_app = get_num_app(); + extern "C" { + fn _app_names(); + } + let mut start = _app_names as usize as *const u8; + let mut v = Vec::new(); + unsafe { + for _ in 0..num_app { + let mut end = start; + while end.read_volatile() != b'\0' { + end = end.add(1); + } + let slice = core::slice::from_raw_parts(start, end as usize - start as usize); + let str = core::str::from_utf8(slice).unwrap(); + v.push(str); + start = end.add(1); + } + } + v + }; +} + +/// Get elf data by app name +pub fn get_app_data_by_name(name: &str) -> Option<&'static [u8]> { + let num_app = get_num_app(); + (0..num_app) + .find(|&i| APP_NAMES[i] == name) + .map(get_app_data) +} + +/// Print all of app names during kernel initialization +pub fn list_apps() { + println!("/**** APPS ****"); + for app in APP_NAMES.iter() { + println!("{}", app); + } + println!("**************/"); +} diff --git a/os5-ref/src/logging.rs b/os5-ref/src/logging.rs new file mode 100644 index 0000000..e12448e --- /dev/null +++ b/os5-ref/src/logging.rs @@ -0,0 +1,45 @@ +//! Global logger + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +/// a simple logger +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +/// initiate logger +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os5-ref/src/main.rs b/os5-ref/src/main.rs new file mode 100644 index 0000000..ee8fb4b --- /dev/null +++ b/os5-ref/src/main.rs @@ -0,0 +1,75 @@ +//! The main module and entrypoint +//! +//! Various facilities of the kernels are implemented as submodules. The most +//! important ones are: +//! +//! - [`trap`]: Handles all cases of switching from userspace to the kernel +//! - [`task`]: Task management +//! - [`syscall`]: System call handling and implementation +//! +//! The operating system also starts in this module. Kernel code starts +//! executing from `entry.asm`, after which [`rust_main()`] is called to +//! initialize various pieces of functionality. (See its source code for +//! details.) +//! +//! We then call [`task::run_first_task()`] and for the first time go to +//! userspace. + +#![no_std] +#![no_main] +#![feature(panic_info_message)] +#![feature(alloc_error_handler)] + +#[macro_use] +extern crate bitflags; +#[macro_use] +extern crate log; + +extern crate alloc; + +#[macro_use] +mod console; +mod config; +mod lang_items; +mod loader; +mod logging; +mod mm; +mod sbi; +mod sync; +mod syscall; +mod task; +mod timer; +mod trap; + +core::arch::global_asm!(include_str!("entry.asm")); +core::arch::global_asm!(include_str!("link_app.S")); + +/// clear BSS segment +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +/// the rust entry-point of os +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + mm::init(); + mm::remap_test(); + task::add_initproc(); + info!("after initproc!"); + trap::init(); + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + loader::list_apps(); + task::run_tasks(); + panic!("Unreachable in rust_main!"); +} diff --git a/os5-ref/src/mm/address.rs b/os5-ref/src/mm/address.rs new file mode 100644 index 0000000..4cec8ce --- /dev/null +++ b/os5-ref/src/mm/address.rs @@ -0,0 +1,246 @@ +//! Implementation of physical and virtual address and page number. +use super::PageTableEntry; +use crate::config::{PAGE_SIZE, PAGE_SIZE_BITS}; +use core::fmt::{self, Debug, Formatter}; + +/// Definitions +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysAddr(pub usize); + +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtAddr(pub usize); + +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysPageNum(pub usize); + +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtPageNum(pub usize); + +/// Debugging + +impl Debug for VirtAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VA:{:#x}", self.0)) + } +} +impl Debug for VirtPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VPN:{:#x}", self.0)) + } +} +impl Debug for PhysAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PA:{:#x}", self.0)) + } +} +impl Debug for PhysPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PPN:{:#x}", self.0)) + } +} + +/// T: {PhysAddr, VirtAddr, PhysPageNum, VirtPageNum} +/// T -> usize: T.0 +/// usize -> T: usize.into() + +impl From for PhysAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for PhysPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for usize { + fn from(v: PhysAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: PhysPageNum) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtPageNum) -> Self { + v.0 + } +} + +impl VirtAddr { + pub fn floor(&self) -> VirtPageNum { + VirtPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> VirtPageNum { + VirtPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for VirtPageNum { + fn from(v: VirtAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for VirtAddr { + fn from(v: VirtPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} +impl PhysAddr { + pub fn floor(&self) -> PhysPageNum { + PhysPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> PhysPageNum { + PhysPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for PhysPageNum { + fn from(v: PhysAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for PhysAddr { + fn from(v: PhysPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} + +impl VirtPageNum { + pub fn indexes(&self) -> [usize; 3] { + let mut vpn = self.0; + let mut idx = [0usize; 3]; + for i in (0..3).rev() { + idx[i] = vpn & 511; + vpn >>= 9; + } + idx + } +} + +impl PhysAddr { + pub fn get_mut(&self) -> &'static mut T { + unsafe { (self.0 as *mut T).as_mut().unwrap() } + } +} +impl PhysPageNum { + pub fn get_pte_array(&self) -> &'static mut [PageTableEntry] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut PageTableEntry, 512) } + } + pub fn get_bytes_array(&self) -> &'static mut [u8] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut u8, 4096) } + } + pub fn get_mut(&self) -> &'static mut T { + let pa: PhysAddr = (*self).into(); + pa.get_mut() + } +} + +pub trait StepByOne { + fn step(&mut self); +} +impl StepByOne for VirtPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +#[derive(Copy, Clone)] +/// a simple range structure for type T +pub struct SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + l: T, + r: T, +} +impl SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(start: T, end: T) -> Self { + assert!(start <= end, "start {:?} > end {:?}!", start, end); + Self { l: start, r: end } + } + pub fn get_start(&self) -> T { + self.l + } + pub fn get_end(&self) -> T { + self.r + } +} +impl IntoIterator for SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + type IntoIter = SimpleRangeIterator; + fn into_iter(self) -> Self::IntoIter { + SimpleRangeIterator::new(self.l, self.r) + } +} +/// iterator for the simple range structure +pub struct SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + current: T, + end: T, +} +impl SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(l: T, r: T) -> Self { + Self { current: l, end: r } + } +} +impl Iterator for SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + fn next(&mut self) -> Option { + if self.current == self.end { + None + } else { + let t = self.current; + self.current.step(); + Some(t) + } + } +} + +/// a simple range structure for virtual page number +pub type VPNRange = SimpleRange; diff --git a/os5-ref/src/mm/frame_allocator.rs b/os5-ref/src/mm/frame_allocator.rs new file mode 100644 index 0000000..c74b824 --- /dev/null +++ b/os5-ref/src/mm/frame_allocator.rs @@ -0,0 +1,136 @@ +//! Implementation of [`FrameAllocator`] which +//! controls all the frames in the operating system. + +use super::{PhysAddr, PhysPageNum}; +use crate::config::MEMORY_END; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use core::fmt::{self, Debug, Formatter}; +use lazy_static::*; + +/// manage a frame which has the same lifecycle as the tracker +pub struct FrameTracker { + pub ppn: PhysPageNum, +} + +impl FrameTracker { + pub fn new(ppn: PhysPageNum) -> Self { + // page cleaning + let bytes_array = ppn.get_bytes_array(); + for i in bytes_array { + *i = 0; + } + Self { ppn } + } +} + +impl Debug for FrameTracker { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("FrameTracker:PPN={:#x}", self.ppn.0)) + } +} + +impl Drop for FrameTracker { + fn drop(&mut self) { + frame_dealloc(self.ppn); + } +} + +trait FrameAllocator { + fn new() -> Self; + fn alloc(&mut self) -> Option; + fn dealloc(&mut self, ppn: PhysPageNum); +} + +/// an implementation for frame allocator +pub struct StackFrameAllocator { + current: usize, + end: usize, + recycled: Vec, +} + +impl StackFrameAllocator { + pub fn init(&mut self, l: PhysPageNum, r: PhysPageNum) { + self.current = l.0; + self.end = r.0; + info!("last {} Physical Frames.", self.end - self.current); + } +} +impl FrameAllocator for StackFrameAllocator { + fn new() -> Self { + Self { + current: 0, + end: 0, + recycled: Vec::new(), + } + } + fn alloc(&mut self) -> Option { + if let Some(ppn) = self.recycled.pop() { + Some(ppn.into()) + } else if self.current == self.end { + None + } else { + self.current += 1; + Some((self.current - 1).into()) + } + } + fn dealloc(&mut self, ppn: PhysPageNum) { + let ppn = ppn.0; + // validity check + if ppn >= self.current || self.recycled.iter().any(|v| *v == ppn) { + panic!("Frame ppn={:#x} has not been allocated!", ppn); + } + // recycle + self.recycled.push(ppn); + } +} + +type FrameAllocatorImpl = StackFrameAllocator; + +lazy_static! { + /// frame allocator instance through lazy_static! + pub static ref FRAME_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(FrameAllocatorImpl::new()) }; +} + +pub fn init_frame_allocator() { + extern "C" { + fn ekernel(); + } + FRAME_ALLOCATOR.exclusive_access().init( + PhysAddr::from(ekernel as usize).ceil(), + PhysAddr::from(MEMORY_END).floor(), + ); +} + +/// initiate the frame allocator using `ekernel` and `MEMORY_END` +pub fn frame_alloc() -> Option { + FRAME_ALLOCATOR + .exclusive_access() + .alloc() + .map(FrameTracker::new) +} + +/// deallocate a frame +fn frame_dealloc(ppn: PhysPageNum) { + FRAME_ALLOCATOR.exclusive_access().dealloc(ppn); +} + +#[allow(unused)] +/// a simple test for frame allocator +pub fn frame_allocator_test() { + let mut v: Vec = Vec::new(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + v.clear(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + drop(v); + info!("frame_allocator_test passed!"); +} diff --git a/os5-ref/src/mm/heap_allocator.rs b/os5-ref/src/mm/heap_allocator.rs new file mode 100644 index 0000000..d518fae --- /dev/null +++ b/os5-ref/src/mm/heap_allocator.rs @@ -0,0 +1,51 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[allow(unused)] +pub fn heap_test() { + use alloc::boxed::Box; + use alloc::vec::Vec; + extern "C" { + fn sbss(); + fn ebss(); + } + let bss_range = sbss as usize..ebss as usize; + let a = Box::new(5); + assert_eq!(*a, 5); + assert!(bss_range.contains(&(a.as_ref() as *const _ as usize))); + drop(a); + let mut v: Vec = Vec::new(); + for i in 0..500 { + v.push(i); + } + for (i, vi) in v.iter().enumerate().take(500) { + assert_eq!(*vi, i); + } + assert!(bss_range.contains(&(v.as_ptr() as usize))); + drop(v); + info!("heap_test passed!"); +} diff --git a/os5-ref/src/mm/memory_set.rs b/os5-ref/src/mm/memory_set.rs new file mode 100644 index 0000000..ca2979c --- /dev/null +++ b/os5-ref/src/mm/memory_set.rs @@ -0,0 +1,388 @@ +//! Implementation of [`MapArea`] and [`MemorySet`]. + +use super::{frame_alloc, FrameTracker}; +use super::{PTEFlags, PageTable, PageTableEntry}; +use super::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use super::{StepByOne, VPNRange}; +use crate::config::{MEMORY_END, PAGE_SIZE, TRAMPOLINE, TRAP_CONTEXT, USER_STACK_SIZE}; +use crate::sync::UPSafeCell; +use alloc::collections::BTreeMap; +use alloc::sync::Arc; +use alloc::vec::Vec; +use lazy_static::*; +use riscv::register::satp; + +extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss_with_stack(); + fn ebss(); + fn ekernel(); + fn strampoline(); +} + +lazy_static! { + /// a memory set instance through lazy_static! managing kernel space + pub static ref KERNEL_SPACE: Arc> = + Arc::new(unsafe { UPSafeCell::new(MemorySet::new_kernel()) }); +} + +/// memory set structure, controls virtual-memory space +pub struct MemorySet { + page_table: PageTable, + areas: Vec, +} + +impl MemorySet { + pub fn new_bare() -> Self { + Self { + page_table: PageTable::new(), + areas: Vec::new(), + } + } + pub fn token(&self) -> usize { + self.page_table.token() + } + /// Assume that no conflicts. + pub fn insert_framed_area( + &mut self, + start_va: VirtAddr, + end_va: VirtAddr, + permission: MapPermission, + ) { + self.push( + MapArea::new(start_va, end_va, MapType::Framed, permission), + None, + ); + } + pub fn remove_area_with_start_vpn(&mut self, start_vpn: VirtPageNum) { + if let Some((idx, area)) = self + .areas + .iter_mut() + .enumerate() + .find(|(_, area)| area.vpn_range.get_start() == start_vpn) + { + area.unmap(&mut self.page_table); + self.areas.remove(idx); + } + } + fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) { + map_area.map(&mut self.page_table); + if let Some(data) = data { + map_area.copy_data(&mut self.page_table, data); + } + self.areas.push(map_area); + } + /// Mention that trampoline is not collected by areas. + fn map_trampoline(&mut self) { + self.page_table.map( + VirtAddr::from(TRAMPOLINE).into(), + PhysAddr::from(strampoline as usize).into(), + PTEFlags::R | PTEFlags::X, + ); + } + /// Without kernel stacks. + pub fn new_kernel() -> Self { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map kernel sections + info!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + info!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + info!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + info!( + ".bss [{:#x}, {:#x})", + sbss_with_stack as usize, ebss as usize + ); + info!("mapping .text section"); + memory_set.push( + MapArea::new( + (stext as usize).into(), + (etext as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::X, + ), + None, + ); + info!("mapping .rodata section"); + memory_set.push( + MapArea::new( + (srodata as usize).into(), + (erodata as usize).into(), + MapType::Identical, + MapPermission::R, + ), + None, + ); + info!("mapping .data section"); + memory_set.push( + MapArea::new( + (sdata as usize).into(), + (edata as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping .bss section"); + memory_set.push( + MapArea::new( + (sbss_with_stack as usize).into(), + (ebss as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping physical memory"); + memory_set.push( + MapArea::new( + (ekernel as usize).into(), + MEMORY_END.into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + memory_set + } + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map program headers of elf, with U flag + let elf = xmas_elf::ElfFile::new(elf_data).unwrap(); + let elf_header = elf.header; + let magic = elf_header.pt1.magic; + assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!"); + let ph_count = elf_header.pt2.ph_count(); + let mut max_end_vpn = VirtPageNum(0); + for i in 0..ph_count { + let ph = elf.program_header(i).unwrap(); + if ph.get_type().unwrap() == xmas_elf::program::Type::Load { + let start_va: VirtAddr = (ph.virtual_addr() as usize).into(); + let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into(); + let mut map_perm = MapPermission::U; + let ph_flags = ph.flags(); + if ph_flags.is_read() { + map_perm |= MapPermission::R; + } + if ph_flags.is_write() { + map_perm |= MapPermission::W; + } + if ph_flags.is_execute() { + map_perm |= MapPermission::X; + } + let map_area = MapArea::new(start_va, end_va, MapType::Framed, map_perm); + max_end_vpn = map_area.vpn_range.get_end(); + memory_set.push( + map_area, + Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]), + ); + } + } + // map user stack with U flags + let max_end_va: VirtAddr = max_end_vpn.into(); + let mut user_stack_bottom: usize = max_end_va.into(); + // guard page + user_stack_bottom += PAGE_SIZE; + let user_stack_top = user_stack_bottom + USER_STACK_SIZE; + memory_set.push( + MapArea::new( + user_stack_bottom.into(), + user_stack_top.into(), + MapType::Framed, + MapPermission::R | MapPermission::W | MapPermission::U, + ), + None, + ); + // map TrapContext + memory_set.push( + MapArea::new( + TRAP_CONTEXT.into(), + TRAMPOLINE.into(), + MapType::Framed, + MapPermission::R | MapPermission::W, + ), + None, + ); + ( + memory_set, + user_stack_top, + elf.header.pt2.entry_point() as usize, + ) + } + /// Copy an identical user_space + pub fn from_existed_user(user_space: &MemorySet) -> MemorySet { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // copy data sections/trap_context/user_stack + for area in user_space.areas.iter() { + let new_area = MapArea::from_another(area); + memory_set.push(new_area, None); + // copy data from another space + for vpn in area.vpn_range { + let src_ppn = user_space.translate(vpn).unwrap().ppn(); + let dst_ppn = memory_set.translate(vpn).unwrap().ppn(); + dst_ppn + .get_bytes_array() + .copy_from_slice(src_ppn.get_bytes_array()); + } + } + memory_set + } + pub fn activate(&self) { + let satp = self.page_table.token(); + unsafe { + satp::write(satp); + core::arch::asm!("sfence.vma"); + } + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.page_table.translate(vpn) + } + pub fn recycle_data_pages(&mut self) { + //*self = Self::new_bare(); + self.areas.clear(); + } +} + +/// map area structure, controls a contiguous piece of virtual memory +pub struct MapArea { + vpn_range: VPNRange, + data_frames: BTreeMap, + map_type: MapType, + map_perm: MapPermission, +} + +impl MapArea { + pub fn new( + start_va: VirtAddr, + end_va: VirtAddr, + map_type: MapType, + map_perm: MapPermission, + ) -> Self { + let start_vpn: VirtPageNum = start_va.floor(); + let end_vpn: VirtPageNum = end_va.ceil(); + Self { + vpn_range: VPNRange::new(start_vpn, end_vpn), + data_frames: BTreeMap::new(), + map_type, + map_perm, + } + } + pub fn from_another(another: &MapArea) -> Self { + Self { + vpn_range: VPNRange::new(another.vpn_range.get_start(), another.vpn_range.get_end()), + data_frames: BTreeMap::new(), + map_type: another.map_type, + map_perm: another.map_perm, + } + } + pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + let ppn: PhysPageNum; + match self.map_type { + MapType::Identical => { + ppn = PhysPageNum(vpn.0); + } + MapType::Framed => { + let frame = frame_alloc().unwrap(); + ppn = frame.ppn; + self.data_frames.insert(vpn, frame); + } + } + let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap(); + page_table.map(vpn, ppn, pte_flags); + } + + pub fn unmap_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + #[allow(clippy::single_match)] + match self.map_type { + MapType::Framed => { + self.data_frames.remove(&vpn); + } + _ => {} + } + page_table.unmap(vpn); + } + pub fn map(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.map_one(page_table, vpn); + } + } + pub fn unmap(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.unmap_one(page_table, vpn); + } + } + /// data: start-aligned but maybe with shorter length + /// assume that all frames were cleared before + pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) { + assert_eq!(self.map_type, MapType::Framed); + let mut start: usize = 0; + let mut current_vpn = self.vpn_range.get_start(); + let len = data.len(); + loop { + let src = &data[start..len.min(start + PAGE_SIZE)]; + let dst = &mut page_table + .translate(current_vpn) + .unwrap() + .ppn() + .get_bytes_array()[..src.len()]; + dst.copy_from_slice(src); + start += PAGE_SIZE; + if start >= len { + break; + } + current_vpn.step(); + } + } +} + +#[derive(Copy, Clone, PartialEq, Debug)] +/// map type for memory set: identical or framed +pub enum MapType { + Identical, + Framed, +} + +bitflags! { + /// map permission corresponding to that in pte: `R W X U` + pub struct MapPermission: u8 { + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + } +} + +#[allow(unused)] +pub fn remap_test() { + let mut kernel_space = KERNEL_SPACE.exclusive_access(); + let mid_text: VirtAddr = ((stext as usize + etext as usize) / 2).into(); + let mid_rodata: VirtAddr = ((srodata as usize + erodata as usize) / 2).into(); + let mid_data: VirtAddr = ((sdata as usize + edata as usize) / 2).into(); + assert!(!kernel_space + .page_table + .translate(mid_text.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_rodata.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_data.floor()) + .unwrap() + .executable()); + info!("remap_test passed!"); +} diff --git a/os5-ref/src/mm/mod.rs b/os5-ref/src/mm/mod.rs new file mode 100644 index 0000000..e6a2256 --- /dev/null +++ b/os5-ref/src/mm/mod.rs @@ -0,0 +1,29 @@ +//! Memory management implementation +//! +//! SV39 page-based virtual-memory architecture for RV64 systems, and +//! everything about memory management, like frame allocator, page table, +//! map area and memory set, is implemented here. +//! +//! Every task or process has a memory_set to control its virtual memory. + + +mod address; +mod frame_allocator; +mod heap_allocator; +mod memory_set; +mod page_table; + +pub use address::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use address::{StepByOne, VPNRange}; +pub use frame_allocator::{frame_alloc, FrameTracker}; +pub use memory_set::remap_test; +pub use memory_set::{MapPermission, MemorySet, KERNEL_SPACE}; +pub use page_table::{translated_byte_buffer, translated_refmut, translated_str, PageTableEntry}; +use page_table::{PTEFlags, PageTable}; + +/// initiate heap allocator, frame allocator and kernel space +pub fn init() { + heap_allocator::init_heap(); + frame_allocator::init_frame_allocator(); + KERNEL_SPACE.exclusive_access().activate(); +} diff --git a/os5-ref/src/mm/page_table.rs b/os5-ref/src/mm/page_table.rs new file mode 100644 index 0000000..ce82e5d --- /dev/null +++ b/os5-ref/src/mm/page_table.rs @@ -0,0 +1,198 @@ +//! Implementation of [`PageTableEntry`] and [`PageTable`]. + +use super::{frame_alloc, FrameTracker, PhysAddr, PhysPageNum, StepByOne, VirtAddr, VirtPageNum}; +use alloc::string::String; +use alloc::vec; +use alloc::vec::Vec; +use bitflags::*; + +bitflags! { + /// page table entry flags + pub struct PTEFlags: u8 { + const V = 1 << 0; + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + const G = 1 << 5; + const A = 1 << 6; + const D = 1 << 7; + } +} + +#[derive(Copy, Clone)] +#[repr(C)] +/// page table entry structure +pub struct PageTableEntry { + pub bits: usize, +} + +impl PageTableEntry { + pub fn new(ppn: PhysPageNum, flags: PTEFlags) -> Self { + PageTableEntry { + bits: ppn.0 << 10 | flags.bits as usize, + } + } + pub fn empty() -> Self { + PageTableEntry { bits: 0 } + } + pub fn ppn(&self) -> PhysPageNum { + (self.bits >> 10 & ((1usize << 44) - 1)).into() + } + pub fn flags(&self) -> PTEFlags { + PTEFlags::from_bits(self.bits as u8).unwrap() + } + pub fn is_valid(&self) -> bool { + (self.flags() & PTEFlags::V) != PTEFlags::empty() + } + pub fn readable(&self) -> bool { + (self.flags() & PTEFlags::R) != PTEFlags::empty() + } + pub fn writable(&self) -> bool { + (self.flags() & PTEFlags::W) != PTEFlags::empty() + } + pub fn executable(&self) -> bool { + (self.flags() & PTEFlags::X) != PTEFlags::empty() + } +} + +/// page table structure +pub struct PageTable { + root_ppn: PhysPageNum, + frames: Vec, +} + +/// Assume that it won't oom when creating/mapping. +impl PageTable { + pub fn new() -> Self { + let frame = frame_alloc().unwrap(); + PageTable { + root_ppn: frame.ppn, + frames: vec![frame], + } + } + /// Temporarily used to get arguments from user space. + pub fn from_token(satp: usize) -> Self { + Self { + root_ppn: PhysPageNum::from(satp & ((1usize << 44) - 1)), + frames: Vec::new(), + } + } + fn find_pte_create(&mut self, vpn: VirtPageNum) -> Option<&mut PageTableEntry> { + let mut idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&mut PageTableEntry> = None; + for (i, idx) in idxs.iter_mut().enumerate() { + let pte = &mut ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + let frame = frame_alloc().unwrap(); + *pte = PageTableEntry::new(frame.ppn, PTEFlags::V); + self.frames.push(frame); + } + ppn = pte.ppn(); + } + result + } + fn find_pte(&self, vpn: VirtPageNum) -> Option<&PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&PageTableEntry> = None; + for (i, idx) in idxs.iter().enumerate() { + let pte = &ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + return None; + } + ppn = pte.ppn(); + } + result + } + #[allow(unused)] + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(!pte.is_valid(), "vpn {:?} is mapped before mapping", vpn); + *pte = PageTableEntry::new(ppn, flags | PTEFlags::V); + } + #[allow(unused)] + pub fn unmap(&mut self, vpn: VirtPageNum) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(pte.is_valid(), "vpn {:?} is invalid before unmapping", vpn); + *pte = PageTableEntry::empty(); + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.find_pte(vpn).copied() + } + pub fn translate_va(&self, va: VirtAddr) -> Option { + self.find_pte(va.clone().floor()).map(|pte| { + //println!("translate_va:va = {:?}", va); + let aligned_pa: PhysAddr = pte.ppn().into(); + //println!("translate_va:pa_align = {:?}", aligned_pa); + let offset = va.page_offset(); + let aligned_pa_usize: usize = aligned_pa.into(); + (aligned_pa_usize + offset).into() + }) + } + pub fn token(&self) -> usize { + 8usize << 60 | self.root_ppn.0 + } +} + +/// translate a pointer to a mutable u8 Vec through page table +pub fn translated_byte_buffer(token: usize, ptr: *const u8, len: usize) -> Vec<&'static mut [u8]> { + let page_table = PageTable::from_token(token); + let mut start = ptr as usize; + let end = start + len; + let mut v = Vec::new(); + while start < end { + let start_va = VirtAddr::from(start); + let mut vpn = start_va.floor(); + let ppn = page_table.translate(vpn).unwrap().ppn(); + vpn.step(); + let mut end_va: VirtAddr = vpn.into(); + end_va = end_va.min(VirtAddr::from(end)); + if end_va.page_offset() == 0 { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..]); + } else { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..end_va.page_offset()]); + } + start = end_va.into(); + } + v +} + +pub fn translated_str(token: usize, ptr: *const u8) -> String { + let page_table = PageTable::from_token(token); + let mut string = String::new(); + let mut va = ptr as usize; + loop { + let ch: u8 = *(page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut()); + if ch == 0 { + break; + } else { + string.push(ch as char); + va += 1; + } + } + string +} + +pub fn translated_refmut(token: usize, ptr: *mut T) -> &'static mut T { + //println!("into translated_refmut!"); + let page_table = PageTable::from_token(token); + let va = ptr as usize; + //println!("translated_refmut: before translate_va"); + page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut() +} diff --git a/os5-ref/src/sbi.rs b/os5-ref/src/sbi.rs new file mode 100644 index 0000000..4af7620 --- /dev/null +++ b/os5-ref/src/sbi.rs @@ -0,0 +1,45 @@ +//! SBI call wrappers + +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +/// general sbi call +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +/// use sbi call to set timer +pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); +} + +/// use sbi call to putchar in console (qemu uart handler) +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +/// use sbi call to getchar from console (qemu uart handler) +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +/// use sbi call to shutdown the kernel +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os5-ref/src/sync/mod.rs b/os5-ref/src/sync/mod.rs new file mode 100644 index 0000000..4743e31 --- /dev/null +++ b/os5-ref/src/sync/mod.rs @@ -0,0 +1,5 @@ +//! Synchronization and interior mutability primitives + +mod up; + +pub use up::UPSafeCell; diff --git a/os5-ref/src/sync/up.rs b/os5-ref/src/sync/up.rs new file mode 100644 index 0000000..039b039 --- /dev/null +++ b/os5-ref/src/sync/up.rs @@ -0,0 +1,31 @@ +//! Uniprocessor interior mutability primitives + +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os5-ref/src/syscall/fs.rs b/os5-ref/src/syscall/fs.rs new file mode 100644 index 0000000..d05f44b --- /dev/null +++ b/os5-ref/src/syscall/fs.rs @@ -0,0 +1,50 @@ +//! File and filesystem-related syscalls + +use crate::mm::translated_byte_buffer; +use crate::sbi::console_getchar; +use crate::task::{current_user_token, suspend_current_and_run_next}; + +const FD_STDIN: usize = 0; +const FD_STDOUT: usize = 1; + +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDOUT => { + let buffers = translated_byte_buffer(current_user_token(), buf, len); + for buffer in buffers { + print!("{}", core::str::from_utf8(buffer).unwrap()); + } + len as isize + } + _ => { + panic!("Unsupported fd in sys_write!"); + } + } +} + +pub fn sys_read(fd: usize, buf: *const u8, len: usize) -> isize { + match fd { + FD_STDIN => { + assert_eq!(len, 1, "Only support len = 1 in sys_read!"); + let mut c: usize; + loop { + c = console_getchar(); + if c == 0 { + suspend_current_and_run_next(); + continue; + } else { + break; + } + } + let ch = c as u8; + let mut buffers = translated_byte_buffer(current_user_token(), buf, len); + unsafe { + buffers[0].as_mut_ptr().write_volatile(ch); + } + 1 + } + _ => { + panic!("Unsupported fd in sys_read!"); + } + } +} diff --git a/os5-ref/src/syscall/mod.rs b/os5-ref/src/syscall/mod.rs new file mode 100644 index 0000000..362ec2b --- /dev/null +++ b/os5-ref/src/syscall/mod.rs @@ -0,0 +1,53 @@ +//! Implementation of syscalls +//! +//! The single entry point to all system calls, [`syscall()`], is called +//! whenever userspace wishes to perform a system call using the `ecall` +//! instruction. In this case, the processor raises an 'Environment call from +//! U-mode' exception, which is handled as one of the cases in +//! [`crate::trap::trap_handler`]. +//! +//! For clarity, each single syscall is implemented as its own function, named +//! `sys_` then the name of the syscall. You can find functions like this in +//! submodules, and you should also implement syscalls this way. + +const SYSCALL_READ: usize = 63; +const SYSCALL_WRITE: usize = 64; +const SYSCALL_EXIT: usize = 93; +const SYSCALL_YIELD: usize = 124; +const SYSCALL_GET_TIME: usize = 169; +const SYSCALL_GETPID: usize = 172; +const SYSCALL_FORK: usize = 220; +const SYSCALL_EXEC: usize = 221; +const SYSCALL_WAITPID: usize = 260; +const SYSCALL_SPAWN: usize = 400; +const SYSCALL_MUNMAP: usize = 215; +const SYSCALL_MMAP: usize = 222; +const SYSCALL_SET_PRIORITY: usize = 140; +const SYSCALL_TASK_INFO: usize = 410; + +mod fs; +mod process; + +use fs::*; +use process::*; + +/// handle syscall exception with `syscall_id` and other arguments +pub fn syscall(syscall_id: usize, args: [usize; 3]) -> isize { + match syscall_id { + SYSCALL_READ => sys_read(args[0], args[1] as *const u8, args[2]), + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_EXIT => sys_exit(args[0] as i32), + SYSCALL_YIELD => sys_yield(), + SYSCALL_GETPID => sys_getpid(), + SYSCALL_FORK => sys_fork(), + SYSCALL_EXEC => sys_exec(args[0] as *const u8), + SYSCALL_WAITPID => sys_waitpid(args[0] as isize, args[1] as *mut i32), + SYSCALL_GET_TIME => sys_get_time(args[0] as *mut TimeVal, args[1]), + SYSCALL_MMAP => sys_mmap(args[0], args[1], args[2]), + SYSCALL_MUNMAP => sys_munmap(args[0], args[1]), + SYSCALL_SET_PRIORITY => sys_set_priority(args[0] as isize), + SYSCALL_TASK_INFO => sys_task_info(args[0] as *mut TaskInfo), + SYSCALL_SPAWN => sys_spawn(args[0] as *const u8), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os5-ref/src/syscall/process.rs b/os5-ref/src/syscall/process.rs new file mode 100644 index 0000000..9ec4839 --- /dev/null +++ b/os5-ref/src/syscall/process.rs @@ -0,0 +1,144 @@ +//! Process management syscalls + +use crate::loader::get_app_data_by_name; +use crate::mm::{translated_refmut, translated_str}; +use crate::task::{ + add_task, current_task, current_user_token, exit_current_and_run_next, + suspend_current_and_run_next, TaskStatus, +}; +use crate::timer::get_time_us; +use alloc::sync::Arc; +use crate::config::MAX_SYSCALL_NUM; + +#[repr(C)] +#[derive(Debug)] +pub struct TimeVal { + pub sec: usize, + pub usec: usize, +} + +#[derive(Clone, Copy)] +pub struct TaskInfo { + pub status: TaskStatus, + pub syscall_times: [u32; MAX_SYSCALL_NUM], + pub time: usize, +} + +pub fn sys_exit(exit_code: i32) -> ! { + debug!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(exit_code); + panic!("Unreachable in sys_exit!"); +} + +/// current task gives up resources for other tasks +pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 +} + +pub fn sys_getpid() -> isize { + current_task().unwrap().pid.0 as isize +} + +/// Syscall Fork which returns 0 for child process and child_pid for parent process +pub fn sys_fork() -> isize { + let current_task = current_task().unwrap(); + let new_task = current_task.fork(); + let new_pid = new_task.pid.0; + // modify trap context of new_task, because it returns immediately after switching + let trap_cx = new_task.inner_exclusive_access().get_trap_cx(); + // we do not have to move to next instruction since we have done it before + // for child process, fork returns 0 + trap_cx.x[10] = 0; + // add new task to scheduler + add_task(new_task); + new_pid as isize +} + +/// Syscall Exec which accepts the elf path +pub fn sys_exec(path: *const u8) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + if let Some(data) = get_app_data_by_name(path.as_str()) { + let task = current_task().unwrap(); + task.exec(data); + 0 + } else { + -1 + } +} + +/// If there is not a child process whose pid is same as given, return -1. +/// Else if there is a child process but it is still running, return -2. +pub fn sys_waitpid(pid: isize, exit_code_ptr: *mut i32) -> isize { + let task = current_task().unwrap(); + // find a child process + + // ---- access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + if !inner + .children + .iter() + .any(|p| pid == -1 || pid as usize == p.getpid()) + { + return -1; + // ---- release current PCB + } + let pair = inner.children.iter().enumerate().find(|(_, p)| { + // ++++ temporarily access child PCB lock exclusively + p.inner_exclusive_access().is_zombie() && (pid == -1 || pid as usize == p.getpid()) + // ++++ release child PCB + }); + if let Some((idx, _)) = pair { + let child = inner.children.remove(idx); + // confirm that child will be deallocated after removing from children list + assert_eq!(Arc::strong_count(&child), 1); + let found_pid = child.getpid(); + // ++++ temporarily access child TCB exclusively + let exit_code = child.inner_exclusive_access().exit_code; + // ++++ release child PCB + *translated_refmut(inner.memory_set.token(), exit_code_ptr) = exit_code; + found_pid as isize + } else { + -2 + } + // ---- release current PCB lock automatically +} + +// YOUR JOB: 引入虚地址后重写 sys_get_time +pub fn sys_get_time(_ts: *mut TimeVal, _tz: usize) -> isize { + let _us = get_time_us(); + // unsafe { + // *ts = TimeVal { + // sec: us / 1_000_000, + // usec: us % 1_000_000, + // }; + // } + 0 +} + +// YOUR JOB: 引入虚地址后重写 sys_task_info +pub fn sys_task_info(ti: *mut TaskInfo) -> isize { + -1 +} + +// YOUR JOB: 实现sys_set_priority，为任务添加优先级 +pub fn sys_set_priority(_prio: isize) -> isize { + -1 +} + +// YOUR JOB: 扩展内核以实现 sys_mmap 和 sys_munmap +pub fn sys_mmap(_start: usize, _len: usize, _port: usize) -> isize { + -1 +} + +pub fn sys_munmap(_start: usize, _len: usize) -> isize { + -1 +} + +// +// YOUR JOB: 实现 sys_spawn 系统调用 +// ALERT: 注意在实现 SPAWN 时不需要复制父进程地址空间，SPAWN != FORK + EXEC +pub fn sys_spawn(_path: *const u8) -> isize { + -1 +} diff --git a/os5-ref/src/task/context.rs b/os5-ref/src/task/context.rs new file mode 100644 index 0000000..200bfb1 --- /dev/null +++ b/os5-ref/src/task/context.rs @@ -0,0 +1,32 @@ +//! Implementation of [`TaskContext`] + +use crate::trap::trap_return; + +#[derive(Copy, Clone)] +#[repr(C)] +/// task context structure containing some registers +pub struct TaskContext { + /// Ret position after task switching + ra: usize, + /// Stack pointer + sp: usize, + /// s0-11 register, callee saved + s: [usize; 12], +} + +impl TaskContext { + pub fn zero_init() -> Self { + Self { + ra: 0, + sp: 0, + s: [0; 12], + } + } + pub fn goto_trap_return(kstack_ptr: usize) -> Self { + Self { + ra: trap_return as usize, + sp: kstack_ptr, + s: [0; 12], + } + } +} diff --git a/os5-ref/src/task/manager.rs b/os5-ref/src/task/manager.rs new file mode 100644 index 0000000..47f7ace --- /dev/null +++ b/os5-ref/src/task/manager.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TaskManager`] +//! +//! It is only used to manage processes and schedule process based on ready queue. +//! Other CPU process monitoring functions are in Processor. + + +use super::TaskControlBlock; +use crate::sync::UPSafeCell; +use alloc::collections::VecDeque; +use alloc::sync::Arc; +use lazy_static::*; + +pub struct TaskManager { + ready_queue: VecDeque>, +} + +// YOUR JOB: FIFO->Stride +/// A simple FIFO scheduler. +impl TaskManager { + pub fn new() -> Self { + Self { + ready_queue: VecDeque::new(), + } + } + /// Add process back to ready queue + pub fn add(&mut self, task: Arc) { + self.ready_queue.push_back(task); + } + /// Take a process out of the ready queue + pub fn fetch(&mut self) -> Option> { + self.ready_queue.pop_front() + } +} + +lazy_static! { + /// TASK_MANAGER instance through lazy_static! + pub static ref TASK_MANAGER: UPSafeCell = + unsafe { UPSafeCell::new(TaskManager::new()) }; +} + +pub fn add_task(task: Arc) { + TASK_MANAGER.exclusive_access().add(task); +} + +pub fn fetch_task() -> Option> { + TASK_MANAGER.exclusive_access().fetch() +} diff --git a/os5-ref/src/task/mod.rs b/os5-ref/src/task/mod.rs new file mode 100644 index 0000000..4db65cf --- /dev/null +++ b/os5-ref/src/task/mod.rs @@ -0,0 +1,99 @@ +//! Implementation of process management mechanism +//! +//! Here is the entry for process scheduling required by other modules +//! (such as syscall or clock interrupt). +//! By suspending or exiting the current process, you can +//! modify the process state, manage the process queue through TASK_MANAGER, +//! and switch the control flow through PROCESSOR. +//! +//! Be careful when you see [`__switch`]. Control flow around this function +//! might not be what you expect. + +mod context; +mod manager; +mod pid; +mod processor; +mod switch; +#[allow(clippy::module_inception)] +mod task; + +use crate::loader::get_app_data_by_name; +use alloc::sync::Arc; +use lazy_static::*; +use manager::fetch_task; +use switch::__switch; +pub use task::{TaskControlBlock, TaskStatus}; + +pub use context::TaskContext; +pub use manager::add_task; +pub use pid::{pid_alloc, KernelStack, PidHandle}; +pub use processor::{ + current_task, current_trap_cx, current_user_token, run_tasks, schedule, take_current_task, +}; + +/// Make current task suspended and switch to the next task +pub fn suspend_current_and_run_next() { + // There must be an application running. + let task = take_current_task().unwrap(); + + // ---- access current TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let task_cx_ptr = &mut task_inner.task_cx as *mut TaskContext; + // Change status to Ready + task_inner.task_status = TaskStatus::Ready; + drop(task_inner); + // ---- release current PCB + + // push back to ready queue. + add_task(task); + // jump to scheduling cycle + schedule(task_cx_ptr); +} + +/// Exit current task, recycle process resources and switch to the next task +pub fn exit_current_and_run_next(exit_code: i32) { + // take from Processor + let task = take_current_task().unwrap(); + // **** access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + // Change status to Zombie + inner.task_status = TaskStatus::Zombie; + // Record exit code + inner.exit_code = exit_code; + // do not move to its parent but under initproc + + // ++++++ access initproc TCB exclusively + { + let mut initproc_inner = INITPROC.inner_exclusive_access(); + for child in inner.children.iter() { + child.inner_exclusive_access().parent = Some(Arc::downgrade(&INITPROC)); + initproc_inner.children.push(child.clone()); + } + } + // ++++++ release parent PCB + + inner.children.clear(); + // deallocate user space + inner.memory_set.recycle_data_pages(); + drop(inner); + // **** release current PCB + // drop task manually to maintain rc correctly + drop(task); + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); +} + +lazy_static! { + /// Creation of initial process + /// + /// the name "initproc" may be changed to any other app name like "usertests", + /// but we have user_shell, so we don't need to change it. + pub static ref INITPROC: Arc = Arc::new(TaskControlBlock::new( + get_app_data_by_name("ch5b_initproc").unwrap() + )); +} + +pub fn add_initproc() { + add_task(INITPROC.clone()); +} diff --git a/os5-ref/src/task/pid.rs b/os5-ref/src/task/pid.rs new file mode 100644 index 0000000..6e5c194 --- /dev/null +++ b/os5-ref/src/task/pid.rs @@ -0,0 +1,116 @@ +//! Task pid implementation. +//! +//! Assign PID to the process here. At the same time, the position of the application KernelStack +//! is determined according to the PID. + +use crate::config::{KERNEL_STACK_SIZE, PAGE_SIZE, TRAMPOLINE}; +use crate::mm::{MapPermission, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use lazy_static::*; + +/// Process identifier allocator using stack allocation +struct PidAllocator { + /// A new PID to be assigned + current: usize, + /// Recycled PID sequence + recycled: Vec, +} + +impl PidAllocator { + pub fn new() -> Self { + PidAllocator { + current: 0, + recycled: Vec::new(), + } + } + pub fn alloc(&mut self) -> PidHandle { + if let Some(pid) = self.recycled.pop() { + PidHandle(pid) + } else { + self.current += 1; + PidHandle(self.current - 1) + } + } + pub fn dealloc(&mut self, pid: usize) { + assert!(pid < self.current); + assert!( + !self.recycled.iter().any(|ppid| *ppid == pid), + "pid {} has been deallocated!", + pid + ); + self.recycled.push(pid); + } +} + +lazy_static! { + /// Pid allocator instance through lazy_static! + static ref PID_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(PidAllocator::new()) }; +} + +/// Abstract structure of PID +pub struct PidHandle(pub usize); + +impl Drop for PidHandle { + fn drop(&mut self) { + //println!("drop pid {}", self.0); + PID_ALLOCATOR.exclusive_access().dealloc(self.0); + } +} + +pub fn pid_alloc() -> PidHandle { + PID_ALLOCATOR.exclusive_access().alloc() +} + +/// Return (bottom, top) of a kernel stack in kernel space. +pub fn kernel_stack_position(app_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) +} + +/// KernelStack corresponding to PID +pub struct KernelStack { + pid: usize, +} + +impl KernelStack { + pub fn new(pid_handle: &PidHandle) -> Self { + let pid = pid_handle.0; + let (kernel_stack_bottom, kernel_stack_top) = kernel_stack_position(pid); + KERNEL_SPACE.exclusive_access().insert_framed_area( + kernel_stack_bottom.into(), + kernel_stack_top.into(), + MapPermission::R | MapPermission::W, + ); + KernelStack { pid: pid_handle.0 } + } + #[allow(unused)] + /// Push a variable of type T into the top of the KernelStack and return its raw pointer + pub fn push_on_top(&self, value: T) -> *mut T + where + T: Sized, + { + let kernel_stack_top = self.get_top(); + let ptr_mut = (kernel_stack_top - core::mem::size_of::()) as *mut T; + unsafe { + *ptr_mut = value; + } + ptr_mut + } + pub fn get_top(&self) -> usize { + let (_, kernel_stack_top) = kernel_stack_position(self.pid); + kernel_stack_top + } +} + +impl Drop for KernelStack { + fn drop(&mut self) { + let (kernel_stack_bottom, _) = kernel_stack_position(self.pid); + let kernel_stack_bottom_va: VirtAddr = kernel_stack_bottom.into(); + KERNEL_SPACE + .exclusive_access() + .remove_area_with_start_vpn(kernel_stack_bottom_va.into()); + } +} diff --git a/os5-ref/src/task/processor.rs b/os5-ref/src/task/processor.rs new file mode 100644 index 0000000..4218e3b --- /dev/null +++ b/os5-ref/src/task/processor.rs @@ -0,0 +1,105 @@ +//! Implementation of [`Processor`] and Intersection of control flow +//! +//! Here, the continuous operation of user apps in CPU is maintained, +//! the current running state of CPU is recorded, +//! and the replacement and transfer of control flow of different applications are executed. + + +use super::__switch; +use super::{fetch_task, TaskStatus}; +use super::{TaskContext, TaskControlBlock}; +use crate::sync::UPSafeCell; +use crate::trap::TrapContext; +use alloc::sync::Arc; +use lazy_static::*; + +/// Processor management structure +pub struct Processor { + /// The task currently executing on the current processor + current: Option>, + /// The basic control flow of each core, helping to select and switch process + idle_task_cx: TaskContext, +} + +impl Processor { + pub fn new() -> Self { + Self { + current: None, + idle_task_cx: TaskContext::zero_init(), + } + } + fn get_idle_task_cx_ptr(&mut self) -> *mut TaskContext { + &mut self.idle_task_cx as *mut _ + } + pub fn take_current(&mut self) -> Option> { + self.current.take() + } + pub fn current(&self) -> Option> { + self.current.as_ref().map(|task| Arc::clone(task)) + } +} + +lazy_static! { + /// PROCESSOR instance through lazy_static! + pub static ref PROCESSOR: UPSafeCell = unsafe { UPSafeCell::new(Processor::new()) }; +} + +/// The main part of process execution and scheduling +/// +/// Loop fetch_task to get the process that needs to run, +/// and switch the process through __switch +pub fn run_tasks() { + loop { + let mut processor = PROCESSOR.exclusive_access(); + if let Some(task) = fetch_task() { + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + // access coming task TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let next_task_cx_ptr = &task_inner.task_cx as *const TaskContext; + task_inner.task_status = TaskStatus::Running; + drop(task_inner); + // release coming task TCB manually + processor.current = Some(task); + // release processor manually + drop(processor); + unsafe { + __switch(idle_task_cx_ptr, next_task_cx_ptr); + } + } + } +} + +/// Get current task through take, leaving a None in its place +pub fn take_current_task() -> Option> { + PROCESSOR.exclusive_access().take_current() +} + +/// Get a copy of the current task +pub fn current_task() -> Option> { + PROCESSOR.exclusive_access().current() +} + +/// Get token of the address space of current task +pub fn current_user_token() -> usize { + let task = current_task().unwrap(); + let token = task.inner_exclusive_access().get_user_token(); + token +} + +/// Get the mutable reference to trap context of current task +pub fn current_trap_cx() -> &'static mut TrapContext { + current_task() + .unwrap() + .inner_exclusive_access() + .get_trap_cx() +} + +/// Return to idle control flow for new scheduling +pub fn schedule(switched_task_cx_ptr: *mut TaskContext) { + let mut processor = PROCESSOR.exclusive_access(); + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + drop(processor); + unsafe { + __switch(switched_task_cx_ptr, idle_task_cx_ptr); + } +} diff --git a/os5-ref/src/task/switch.S b/os5-ref/src/task/switch.S new file mode 100644 index 0000000..3f985d2 --- /dev/null +++ b/os5-ref/src/task/switch.S @@ -0,0 +1,34 @@ +.altmacro +.macro SAVE_SN n + sd s\n, (\n+2)*8(a0) +.endm +.macro LOAD_SN n + ld s\n, (\n+2)*8(a1) +.endm + .section .text + .globl __switch +__switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + diff --git a/os5-ref/src/task/switch.rs b/os5-ref/src/task/switch.rs new file mode 100644 index 0000000..af08289 --- /dev/null +++ b/os5-ref/src/task/switch.rs @@ -0,0 +1,16 @@ +//! Rust wrapper around `__switch`. +//! +//! Switching to a different task's context happens here. The actual +//! implementation must not be in Rust and (essentially) has to be in assembly +//! language (Do you know why?), so this module really is just a wrapper around +//! `switch.S`. + +core::arch::global_asm!(include_str!("switch.S")); + +use super::TaskContext; + +extern "C" { + /// Switch to the context of `next_task_cx_ptr`, saving the current context + /// in `current_task_cx_ptr`. + pub fn __switch(current_task_cx_ptr: *mut TaskContext, next_task_cx_ptr: *const TaskContext); +} diff --git a/os5-ref/src/task/task.rs b/os5-ref/src/task/task.rs new file mode 100644 index 0000000..84d4ed0 --- /dev/null +++ b/os5-ref/src/task/task.rs @@ -0,0 +1,199 @@ +//! Types related to task management & Functions for completely changing TCB + +use super::TaskContext; +use super::{pid_alloc, KernelStack, PidHandle}; +use crate::config::TRAP_CONTEXT; +use crate::mm::{MemorySet, PhysPageNum, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use crate::trap::{trap_handler, TrapContext}; +use alloc::sync::{Arc, Weak}; +use alloc::vec::Vec; +use core::cell::RefMut; + +/// Task control block structure +/// +/// Directly save the contents that will not change during running +pub struct TaskControlBlock { + // immutable + /// Process identifier + pub pid: PidHandle, + /// Kernel stack corresponding to PID + pub kernel_stack: KernelStack, + // mutable + inner: UPSafeCell, +} + +/// Structure containing more process content +/// +/// Store the contents that will change during operation +/// and are wrapped by UPSafeCell to provide mutual exclusion +pub struct TaskControlBlockInner { + /// The physical page number of the frame where the trap context is placed + pub trap_cx_ppn: PhysPageNum, + /// Application data can only appear in areas + /// where the application address space is lower than base_size + pub base_size: usize, + /// Save task context + pub task_cx: TaskContext, + /// Maintain the execution status of the current process + pub task_status: TaskStatus, + /// Application address space + pub memory_set: MemorySet, + /// Parent process of the current process. + /// Weak will not affect the reference count of the parent + pub parent: Option>, + /// A vector containing TCBs of all child processes of the current process + pub children: Vec>, + /// It is set when active exit or execution error occurs + pub exit_code: i32, +} + +/// Simple access to its internal fields +impl TaskControlBlockInner { + /* + pub fn get_task_cx_ptr2(&self) -> *const usize { + &self.task_cx_ptr as *const usize + } + */ + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + pub fn get_user_token(&self) -> usize { + self.memory_set.token() + } + fn get_status(&self) -> TaskStatus { + self.task_status + } + pub fn is_zombie(&self) -> bool { + self.get_status() == TaskStatus::Zombie + } +} + +impl TaskControlBlock { + /// Get the mutex to get the RefMut TaskControlBlockInner + pub fn inner_exclusive_access(&self) -> RefMut<'_, TaskControlBlockInner> { + self.inner.exclusive_access() + } + + /// Create a new process + /// + /// At present, it is only used for the creation of initproc + pub fn new(elf_data: &[u8]) -> Self { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + // push a task context which goes to trap_return to the top of kernel stack + let task_control_block = Self { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: user_sp, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + }) + }, + }; + // prepare TrapContext in user space + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + kernel_stack_top, + trap_handler as usize, + ); + task_control_block + } + /// Load a new elf to replace the original application address space and start execution + pub fn exec(&self, elf_data: &[u8]) { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + + // **** access inner exclusively + let mut inner = self.inner_exclusive_access(); + // substitute memory_set + inner.memory_set = memory_set; + // update trap_cx ppn + inner.trap_cx_ppn = trap_cx_ppn; + // initialize trap_cx + let trap_cx = inner.get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + self.kernel_stack.get_top(), + trap_handler as usize, + ); + // **** release inner automatically + } + /// Fork from parent to child + pub fn fork(self: &Arc) -> Arc { + // ---- access parent PCB exclusively + let mut parent_inner = self.inner_exclusive_access(); + // copy user space(include trap context) + let memory_set = MemorySet::from_existed_user(&parent_inner.memory_set); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + let task_control_block = Arc::new(TaskControlBlock { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: parent_inner.base_size, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: Some(Arc::downgrade(self)), + children: Vec::new(), + exit_code: 0, + }) + }, + }); + // add child + parent_inner.children.push(task_control_block.clone()); + // modify kernel_sp in trap_cx + // **** access children PCB exclusively + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + trap_cx.kernel_sp = kernel_stack_top; + // return + task_control_block + // ---- release parent PCB automatically + // **** release children PCB automatically + } + pub fn getpid(&self) -> usize { + self.pid.0 + } +} + +#[derive(Copy, Clone, PartialEq)] +/// task status: UnInit, Ready, Running, Exited +pub enum TaskStatus { + UnInit, + Ready, + Running, + Zombie, +} diff --git a/os5-ref/src/timer.rs b/os5-ref/src/timer.rs new file mode 100644 index 0000000..4f40494 --- /dev/null +++ b/os5-ref/src/timer.rs @@ -0,0 +1,23 @@ +//! RISC-V timer-related functionality + +use crate::config::CLOCK_FREQ; +use crate::sbi::set_timer; +use riscv::register::time; + +const TICKS_PER_SEC: usize = 100; +const MICRO_PER_SEC: usize = 1_000_000; + +/// read the `mtime` register +pub fn get_time() -> usize { + time::read() +} + +/// get current time in microseconds +pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) +} + +/// set the next timer interrupt +pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); +} diff --git a/os5-ref/src/trap/context.rs b/os5-ref/src/trap/context.rs new file mode 100644 index 0000000..58e199c --- /dev/null +++ b/os5-ref/src/trap/context.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TrapContext`] + +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +/// trap context structure containing sstatus, sepc and registers +pub struct TrapContext { + /// General-Purpose Register x0-31 + pub x: [usize; 32], + /// sstatus + pub sstatus: Sstatus, + /// sepc + pub sepc: usize, + /// Token of kernel address space + pub kernel_satp: usize, + /// Kernel stack pointer of the current application + pub kernel_sp: usize, + /// Virtual address of trap handler entry point in kernel + pub trap_handler: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context( + entry: usize, + sp: usize, + kernel_satp: usize, + kernel_sp: usize, + trap_handler: usize, + ) -> Self { + let mut sstatus = sstatus::read(); + // set CPU privilege to User after trapping back + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + kernel_satp, + kernel_sp, + trap_handler, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os5-ref/src/trap/mod.rs b/os5-ref/src/trap/mod.rs new file mode 100644 index 0000000..96a9ff6 --- /dev/null +++ b/os5-ref/src/trap/mod.rs @@ -0,0 +1,131 @@ +//! Trap handling functionality +//! +//! For rCore, we have a single trap entry point, namely `__alltraps`. At +//! initialization in [`init()`], we set the `stvec` CSR to point to it. +//! +//! All traps go through `__alltraps`, which is defined in `trap.S`. The +//! assembly language code does just enough work restore the kernel space +//! context, ensuring that Rust code safely runs, and transfers control to +//! [`trap_handler()`]. +//! +//! It then calls different functionality based on what exactly the exception +//! was. For example, timer interrupts trigger task preemption, and syscalls go +//! to [`syscall()`]. + +mod context; + +use crate::config::{TRAMPOLINE, TRAP_CONTEXT}; +use crate::syscall::syscall; +use crate::task::{ + current_trap_cx, current_user_token, exit_current_and_run_next, suspend_current_and_run_next, +}; +use crate::timer::set_next_trigger; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Interrupt, Trap}, + sie, stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +pub fn init() { + set_kernel_trap_entry(); +} + +fn set_kernel_trap_entry() { + unsafe { + stvec::write(trap_from_kernel as usize, TrapMode::Direct); + } +} + +fn set_user_trap_entry() { + unsafe { + stvec::write(TRAMPOLINE as usize, TrapMode::Direct); + } +} + +pub fn enable_timer_interrupt() { + unsafe { + sie::set_stimer(); + } +} + +#[no_mangle] +pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + // jump to next instruction anyway + let mut cx = current_trap_cx(); + cx.sepc += 4; + // get system call return value + let result = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12]]); + // cx is changed during sys_exec, so we have to call it again + cx = current_trap_cx(); + cx.x[10] = result as usize; + } + Trap::Exception(Exception::StoreFault) + | Trap::Exception(Exception::StorePageFault) + | Trap::Exception(Exception::InstructionFault) + | Trap::Exception(Exception::InstructionPageFault) + | Trap::Exception(Exception::LoadFault) + | Trap::Exception(Exception::LoadPageFault) => { + println!( + "[kernel] {:?} in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", + scause.cause(), + stval, + current_trap_cx().sepc, + ); + // page fault exit code + exit_current_and_run_next(-2); + } + Trap::Exception(Exception::IllegalInstruction) => { + println!("[kernel] IllegalInstruction in application, core dumped."); + // illegal instruction exit code + exit_current_and_run_next(-3); + } + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + trap_return(); +} + +#[no_mangle] +pub fn trap_return() -> ! { + set_user_trap_entry(); + let trap_cx_ptr = TRAP_CONTEXT; + let user_satp = current_user_token(); + extern "C" { + fn __alltraps(); + fn __restore(); + } + let restore_va = __restore as usize - __alltraps as usize + TRAMPOLINE; + unsafe { + core::arch::asm!( + "fence.i", + "jr {restore_va}", + restore_va = in(reg) restore_va, + in("a0") trap_cx_ptr, + in("a1") user_satp, + options(noreturn) + ); + } +} + +#[no_mangle] +pub fn trap_from_kernel() -> ! { + panic!("a trap {:?} from kernel!", scause::read().cause()); +} + +pub use context::TrapContext; diff --git a/os5-ref/src/trap/trap.S b/os5-ref/src/trap/trap.S new file mode 100644 index 0000000..c0e2d15 --- /dev/null +++ b/os5-ref/src/trap/trap.S @@ -0,0 +1,69 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text.trampoline + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->*TrapContext in user space, sscratch->user stack + # save other general purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they have been saved in TrapContext + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it in TrapContext + csrr t2, sscratch + sd t2, 2*8(sp) + # load kernel_satp into t0 + ld t0, 34*8(sp) + # load trap_handler into t1 + ld t1, 36*8(sp) + # move to kernel_sp + ld sp, 35*8(sp) + # switch to kernel space + csrw satp, t0 + sfence.vma + # jump to trap_handler + jr t1 + +__restore: + # a0: *TrapContext in user space(Constant); a1: user space token + # switch to user space + csrw satp, a1 + sfence.vma + csrw sscratch, a0 + mv sp, a0 + # now sp points to TrapContext in user space, start restoring based on it + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + # restore general purpose registers except x0/sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # back to user stack + ld sp, 2*8(sp) + sret diff --git a/os6-ref/.cargo/config b/os6-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os6-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os6-ref/Cargo.toml b/os6-ref/Cargo.toml new file mode 100644 index 0000000..d0d9e54 --- /dev/null +++ b/os6-ref/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +bitflags = "1.2.1" +buddy_system_allocator = "0.6" +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } +lock_api = "=0.4.6" +xmas-elf = "0.7.0" +virtio-drivers = { git = "https://gitee.com/rcore-os/virtio-drivers" } +easy-fs = { path = "../easy-fs" } diff --git a/os6-ref/Makefile b/os6-ref/Makefile new file mode 100644 index 0000000..b90f596 --- /dev/null +++ b/os6-ref/Makefile @@ -0,0 +1,64 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm +FS_IMG := ../user/target/$(TARGET)/$(MODE)/fs.img +APPS := ../user/src/bin/* + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -o 'ch[0-9]' | grep -o '[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) fs-img + +fs-img: $(APPS) + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cd ../easy-fs-fuse && cargo run --release -- -s ../user/build/app/ -t ../user/target/riscv64gc-unknown-none-elf/release/ + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + @cd ../user && make clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) \ + -drive file=$(FS_IMG),if=none,format=raw,id=x0 \ + -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -drive file=$(FS_IMG),if=none,format=raw,id=x0 -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean fs-img diff --git a/os6-ref/build.rs b/os6-ref/build.rs new file mode 100644 index 0000000..5529b4f --- /dev/null +++ b/os6-ref/build.rs @@ -0,0 +1,6 @@ +static TARGET_PATH: &str = "../user/target/riscv64gc-unknown-none-elf/release/"; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); +} diff --git a/os6-ref/src/config.rs b/os6-ref/src/config.rs new file mode 100644 index 0000000..851df0a --- /dev/null +++ b/os6-ref/src/config.rs @@ -0,0 +1,16 @@ +//! Constants used in rCore + +pub const USER_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_HEAP_SIZE: usize = 0x20_0000; +pub const MEMORY_END: usize = 0x88000000; +pub const PAGE_SIZE: usize = 0x1000; +pub const PAGE_SIZE_BITS: usize = 0xc; +pub const MAX_SYSCALL_NUM: usize = 500; + +pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1; +pub const TRAP_CONTEXT: usize = TRAMPOLINE - PAGE_SIZE; +pub const CLOCK_FREQ: usize = 12500000; +pub const MMIO: &[(usize, usize)] = &[ + (0x10001000, 0x1000), +]; diff --git a/os6-ref/src/console.rs b/os6-ref/src/console.rs new file mode 100644 index 0000000..a23a0e0 --- /dev/null +++ b/os6-ref/src/console.rs @@ -0,0 +1,130 @@ +//! SBI console driver, for text output + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +/// print string macro +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +/// println string macro +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} + +/* +以下代码提供了与颜色相关的 ANSI 转义字符，以及彩色输出可以使用的函数与宏。 + +可以使用它们，甚至扩展它们，来提升开发体验和显示效果。 +*/ + +// 使用 ANSI 转义字符来加上颜色 +#[macro_export] +macro_rules! colorize { + ($content: ident, $foreground_color: ident) => { + format_args!("\u{1B}[{}m{}\u{1B}[0m", $foreground_color as u8, $content) + }; + ($content: ident, $foreground_color: ident, $background_color: ident) => { + format_args!( + "\u{1B}[{}m\u{1B}[{}m{}\u{1B}[0m", + $foreground_color.into(), + $background_color.into(), + $content + ) + }; +} + +pub fn print_colorized( + args: fmt::Arguments, + foreground_color: impl Into, + background_color: impl Into, +) { + Stdout + .write_fmt(colorize!(args, foreground_color, background_color)) + .unwrap(); +} + +#[macro_export] +macro_rules! print_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!($fmt $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + }; +} + +#[macro_export] +macro_rules! println_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!(concat!($fmt, "\n") $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + } +} + +#[allow(dead_code)] +pub enum ANSICON { + Reset = 0, + Bold = 1, + Underline = 4, + Blink = 5, + Reverse = 7, + FgBlack = 30, + FgRed = 31, + FgGreen = 32, + FgYellow = 33, + FgBlue = 34, + FgMagenta = 35, + FgCyan = 36, + FgWhite = 37, + FgDefault = 39, + FgLightGray = 90, + FgLightRed = 91, + FgLightGreen = 92, + FgLightYellow = 93, + FgLightBlue = 94, + FgLightMagenta = 95, + FgLightCyan = 96, + FgLightWhite = 97, + BgBlack = 40, + BgRed = 41, + BgGreen = 42, + BgYellow = 43, + BgBlue = 44, + BgMagenta = 45, + BgCyan = 46, + BgWhite = 47, + BgDefault = 49, + BgLightGray = 100, + BgLightRed = 101, + BgLightGreen = 102, + BgLightYellow = 103, + BgLightBlue = 104, + BgLightMagenta = 105, + BgLightCyan = 106, + BgLightWhite = 107, +} + +impl From for u8 { + fn from(con: ANSICON) -> Self { + con as Self + } +} diff --git a/os6-ref/src/drivers/block/mod.rs b/os6-ref/src/drivers/block/mod.rs new file mode 100644 index 0000000..e3a6345 --- /dev/null +++ b/os6-ref/src/drivers/block/mod.rs @@ -0,0 +1,24 @@ +mod virtio_blk; + +use lazy_static::*; +use alloc::sync::Arc; +use easy_fs::BlockDevice; +type BlockDeviceImpl = virtio_blk::VirtIOBlock; + +lazy_static! { + pub static ref BLOCK_DEVICE: Arc = Arc::new(BlockDeviceImpl::new()); +} + +#[allow(unused)] +pub fn block_device_test() { + let block_device = BLOCK_DEVICE.clone(); + let mut write_buffer = [0u8; 512]; + let mut read_buffer = [0u8; 512]; + for i in 0..512 { + for byte in write_buffer.iter_mut() { *byte = i as u8; } + block_device.write_block(i as usize, &write_buffer); + block_device.read_block(i as usize, &mut read_buffer); + assert_eq!(write_buffer, read_buffer); + } + println!("block device test passed!"); +} \ No newline at end of file diff --git a/os6-ref/src/drivers/block/virtio_blk.rs b/os6-ref/src/drivers/block/virtio_blk.rs new file mode 100644 index 0000000..c9956f5 --- /dev/null +++ b/os6-ref/src/drivers/block/virtio_blk.rs @@ -0,0 +1,84 @@ + +use virtio_drivers::{VirtIOBlk, VirtIOHeader}; +use crate::mm::{ + PhysAddr, + VirtAddr, + frame_alloc, + frame_dealloc, + PhysPageNum, + FrameTracker, + PageTable, + StepByOne, + kernel_token, +}; +use super::BlockDevice; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use lazy_static::*; + +#[allow(unused)] +const VIRTIO0: usize = 0x10001000; + +pub struct VirtIOBlock(UPSafeCell>); + +lazy_static! { + static ref QUEUE_FRAMES: UPSafeCell> = unsafe { + UPSafeCell::new(Vec::new()) + }; +} + +impl BlockDevice for VirtIOBlock { + fn read_block(&self, block_id: usize, buf: &mut [u8]) { + self.0.exclusive_access() + .read_block(block_id, buf) + .expect("Error when reading VirtIOBlk"); + } + fn write_block(&self, block_id: usize, buf: &[u8]) { + self.0.exclusive_access() + .write_block(block_id, buf) + .expect("Error when writing VirtIOBlk"); + } +} + +impl VirtIOBlock { + #[allow(unused)] + pub fn new() -> Self { + unsafe { + Self(UPSafeCell::new(VirtIOBlk::new( + &mut *(VIRTIO0 as *mut VirtIOHeader) + ).unwrap())) + } + } +} + +#[no_mangle] +pub extern "C" fn virtio_dma_alloc(pages: usize) -> PhysAddr { + let mut ppn_base = PhysPageNum(0); + for i in 0..pages { + let frame = frame_alloc().unwrap(); + if i == 0 { ppn_base = frame.ppn; } + assert_eq!(frame.ppn.0, ppn_base.0 + i); + QUEUE_FRAMES.exclusive_access().push(frame); + } + ppn_base.into() +} + +#[no_mangle] +pub extern "C" fn virtio_dma_dealloc(pa: PhysAddr, pages: usize) -> i32 { + let mut ppn_base: PhysPageNum = pa.into(); + for _ in 0..pages { + frame_dealloc(ppn_base); + ppn_base.step(); + } + 0 +} + +#[no_mangle] +pub extern "C" fn virtio_phys_to_virt(paddr: PhysAddr) -> VirtAddr { + VirtAddr(paddr.0) +} + +#[no_mangle] +pub extern "C" fn virtio_virt_to_phys(vaddr: VirtAddr) -> PhysAddr { + PageTable::from_token(kernel_token()).translate_va(vaddr).unwrap() +} diff --git a/os6-ref/src/drivers/mod.rs b/os6-ref/src/drivers/mod.rs new file mode 100644 index 0000000..43a6f54 --- /dev/null +++ b/os6-ref/src/drivers/mod.rs @@ -0,0 +1,3 @@ +mod block; + +pub use block::BLOCK_DEVICE; diff --git a/os6-ref/src/entry.asm b/os6-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os6-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os6-ref/src/fs/inode.rs b/os6-ref/src/fs/inode.rs new file mode 100644 index 0000000..5e4ca68 --- /dev/null +++ b/os6-ref/src/fs/inode.rs @@ -0,0 +1,169 @@ +use easy_fs::{ + EasyFileSystem, + Inode, +}; +use crate::drivers::BLOCK_DEVICE; +use crate::sync::UPSafeCell; +use alloc::sync::Arc; +use lazy_static::*; +use bitflags::*; +use alloc::vec::Vec; +use super::File; +use crate::mm::UserBuffer; + +/// A wrapper around a filesystem inode +/// to implement File trait atop +pub struct OSInode { + readable: bool, + writable: bool, + inner: UPSafeCell, +} + +/// The OS inode inner in 'UPSafeCell' +pub struct OSInodeInner { + offset: usize, + inode: Arc, +} + +impl OSInode { + /// Construct an OS inode from a inode + pub fn new( + readable: bool, + writable: bool, + inode: Arc, + ) -> Self { + Self { + readable, + writable, + inner: unsafe { UPSafeCell::new(OSInodeInner { + offset: 0, + inode, + })}, + } + } + /// Read all data inside a inode into vector + pub fn read_all(&self) -> Vec { + let mut inner = self.inner.exclusive_access(); + let mut buffer = [0u8; 512]; + let mut v: Vec = Vec::new(); + loop { + let len = inner.inode.read_at(inner.offset, &mut buffer); + if len == 0 { + break; + } + inner.offset += len; + v.extend_from_slice(&buffer[..len]); + } + v + } +} + +lazy_static! { + /// The root of all inodes, or '/' in short + pub static ref ROOT_INODE: Arc = { + let efs = EasyFileSystem::open(BLOCK_DEVICE.clone()); + Arc::new(EasyFileSystem::root_inode(&efs)) + }; +} + +/// List all files in the filesystems +pub fn list_apps() { + println!("/**** APPS ****"); + for app in ROOT_INODE.ls() { + println!("{}", app); + } + println!("**************/"); +} + +bitflags! { + /// Flags for opening files + pub struct OpenFlags: u32 { + const RDONLY = 0; + const WRONLY = 1 << 0; + const RDWR = 1 << 1; + const CREATE = 1 << 9; + const TRUNC = 1 << 10; + } +} + +impl OpenFlags { + /// Get the current read write permission on an inode + /// does not check validity for simplicity + /// returns (readable, writable) + pub fn read_write(&self) -> (bool, bool) { + if self.is_empty() { + (true, false) + } else if self.contains(Self::WRONLY) { + (false, true) + } else { + (true, true) + } + } +} + +/// Open a file by path +pub fn open_file(name: &str, flags: OpenFlags) -> Option> { + let (readable, writable) = flags.read_write(); + if flags.contains(OpenFlags::CREATE) { + if let Some(inode) = ROOT_INODE.find(name) { + // clear size + inode.clear(); + Some(Arc::new(OSInode::new( + readable, + writable, + inode, + ))) + } else { + // create file + ROOT_INODE.create(name) + .map(|inode| { + Arc::new(OSInode::new( + readable, + writable, + inode, + )) + }) + } + } else { + ROOT_INODE.find(name) + .map(|inode| { + if flags.contains(OpenFlags::TRUNC) { + inode.clear(); + } + Arc::new(OSInode::new( + readable, + writable, + inode + )) + }) + } +} + +impl File for OSInode { + fn readable(&self) -> bool { self.readable } + fn writable(&self) -> bool { self.writable } + fn read(&self, mut buf: UserBuffer) -> usize { + let mut inner = self.inner.exclusive_access(); + let mut total_read_size = 0usize; + for slice in buf.buffers.iter_mut() { + let read_size = inner.inode.read_at(inner.offset, *slice); + if read_size == 0 { + break; + } + inner.offset += read_size; + total_read_size += read_size; + } + total_read_size + } + fn write(&self, buf: UserBuffer) -> usize { + let mut inner = self.inner.exclusive_access(); + let mut total_write_size = 0usize; + for slice in buf.buffers.iter() { + let write_size = inner.inode.write_at(inner.offset, *slice); + assert_eq!(write_size, slice.len()); + inner.offset += write_size; + total_write_size += write_size; + } + total_write_size + } +} diff --git a/os6-ref/src/fs/mod.rs b/os6-ref/src/fs/mod.rs new file mode 100644 index 0000000..9603abc --- /dev/null +++ b/os6-ref/src/fs/mod.rs @@ -0,0 +1,43 @@ +mod stdio; +mod inode; + +use crate::mm::UserBuffer; + +/// The common abstraction of all IO resources +pub trait File : Send + Sync { + fn readable(&self) -> bool; + fn writable(&self) -> bool; + fn read(&self, buf: UserBuffer) -> usize; + fn write(&self, buf: UserBuffer) -> usize; +} + +/// The stat of a inode +#[repr(C)] +#[derive(Debug)] +pub struct Stat { + /// ID of device containing file + pub dev: u64, + /// inode number + pub ino: u64, + /// file type and mode + pub mode: StatMode, + /// number of hard links + pub nlink: u32, + /// unused pad + pad: [u64; 7], +} + +bitflags! { + /// The mode of a inode + /// whether a directory or a file + pub struct StatMode: u32 { + const NULL = 0; + /// directory + const DIR = 0o040000; + /// ordinary regular file + const FILE = 0o100000; + } +} + +pub use stdio::{Stdin, Stdout}; +pub use inode::{OSInode, open_file, OpenFlags, list_apps}; diff --git a/os6-ref/src/fs/stdio.rs b/os6-ref/src/fs/stdio.rs new file mode 100644 index 0000000..87dca0e --- /dev/null +++ b/os6-ref/src/fs/stdio.rs @@ -0,0 +1,48 @@ +use super::File; +use crate::mm::{UserBuffer}; +use crate::sbi::console_getchar; +use crate::task::suspend_current_and_run_next; + +/// The standard input +pub struct Stdin; +/// The standard output +pub struct Stdout; + +impl File for Stdin { + fn readable(&self) -> bool { true } + fn writable(&self) -> bool { false } + fn read(&self, mut user_buf: UserBuffer) -> usize { + assert_eq!(user_buf.len(), 1); + // busy loop + let mut c: usize; + loop { + c = console_getchar(); + if c == 0 { + suspend_current_and_run_next(); + continue; + } else { + break; + } + } + let ch = c as u8; + unsafe { user_buf.buffers[0].as_mut_ptr().write_volatile(ch); } + 1 + } + fn write(&self, _user_buf: UserBuffer) -> usize { + panic!("Cannot write to stdin!"); + } +} + +impl File for Stdout { + fn readable(&self) -> bool { false } + fn writable(&self) -> bool { true } + fn read(&self, _user_buf: UserBuffer) -> usize{ + panic!("Cannot read from stdout!"); + } + fn write(&self, user_buf: UserBuffer) -> usize { + for buffer in user_buf.buffers.iter() { + print!("{}", core::str::from_utf8(*buffer).unwrap()); + } + user_buf.len() + } +} diff --git a/os6-ref/src/lang_items.rs b/os6-ref/src/lang_items.rs new file mode 100644 index 0000000..e52afff --- /dev/null +++ b/os6-ref/src/lang_items.rs @@ -0,0 +1,29 @@ +//! The panic handler + +use crate::console::ANSICON; +use crate::sbi::shutdown; + +use core::panic::PanicInfo; + +#[panic_handler] +/// panic handler +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println_colorized!( + "[kernel] Panicked at {}:{} {}", + ANSICON::FgRed, + ANSICON::BgDefault, + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println_colorized!( + "[kernel] Panicked: {}", + ANSICON::FgRed, + ANSICON::BgDefault, + info.message().unwrap() + ); + } + shutdown() +} diff --git a/os6-ref/src/linker.ld b/os6-ref/src/linker.ld new file mode 100644 index 0000000..5baafbd --- /dev/null +++ b/os6-ref/src/linker.ld @@ -0,0 +1,53 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + . = ALIGN(4K); + strampoline = .; + *(.text.trampoline); + . = ALIGN(4K); + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + sbss_with_stack = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os6-ref/src/logging.rs b/os6-ref/src/logging.rs new file mode 100644 index 0000000..e12448e --- /dev/null +++ b/os6-ref/src/logging.rs @@ -0,0 +1,45 @@ +//! Global logger + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +/// a simple logger +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +/// initiate logger +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os6-ref/src/main.rs b/os6-ref/src/main.rs new file mode 100644 index 0000000..8036bca --- /dev/null +++ b/os6-ref/src/main.rs @@ -0,0 +1,74 @@ +//! The main module and entrypoint +//! +//! Various facilities of the kernels are implemented as submodules. The most +//! important ones are: +//! +//! - [`trap`]: Handles all cases of switching from userspace to the kernel +//! - [`task`]: Task management +//! - [`syscall`]: System call handling and implementation +//! +//! The operating system also starts in this module. Kernel code starts +//! executing from `entry.asm`, after which [`rust_main()`] is called to +//! initialize various pieces of functionality. (See its source code for +//! details.) +//! +//! We then call [`task::run_first_task()`] and for the first time go to +//! userspace. + +#![no_std] +#![no_main] +#![feature(panic_info_message)] +#![feature(alloc_error_handler)] + +#[macro_use] +extern crate bitflags; +#[macro_use] +extern crate log; + +extern crate alloc; + +#[macro_use] +mod console; +mod config; +mod lang_items; +mod logging; +mod mm; +mod sbi; +mod sync; +mod syscall; +mod task; +mod timer; +mod trap; +mod drivers; +mod fs; + +core::arch::global_asm!(include_str!("entry.asm")); + +/// clear BSS segment +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +/// the rust entry-point of os +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + mm::init(); + mm::remap_test(); + trap::init(); + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + fs::list_apps(); + task::add_initproc(); + task::run_tasks(); + panic!("Unreachable in rust_main!"); +} diff --git a/os6-ref/src/mm/address.rs b/os6-ref/src/mm/address.rs new file mode 100644 index 0000000..5c24ae7 --- /dev/null +++ b/os6-ref/src/mm/address.rs @@ -0,0 +1,259 @@ +//! Implementation of physical and virtual address and page number. +use super::PageTableEntry; +use crate::config::{PAGE_SIZE, PAGE_SIZE_BITS}; +use core::fmt::{self, Debug, Formatter}; + +/// Definitions +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysAddr(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtAddr(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysPageNum(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtPageNum(pub usize); + +/// Debugging + +impl Debug for VirtAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VA:{:#x}", self.0)) + } +} +impl Debug for VirtPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VPN:{:#x}", self.0)) + } +} +impl Debug for PhysAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PA:{:#x}", self.0)) + } +} +impl Debug for PhysPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PPN:{:#x}", self.0)) + } +} + +/// T: {PhysAddr, VirtAddr, PhysPageNum, VirtPageNum} +/// T -> usize: T.0 +/// usize -> T: usize.into() + +impl From for PhysAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for PhysPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for usize { + fn from(v: PhysAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: PhysPageNum) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtPageNum) -> Self { + v.0 + } +} + +impl VirtAddr { + pub fn floor(&self) -> VirtPageNum { + VirtPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> VirtPageNum { + VirtPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for VirtPageNum { + fn from(v: VirtAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for VirtAddr { + fn from(v: VirtPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} +impl PhysAddr { + pub fn floor(&self) -> PhysPageNum { + PhysPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> PhysPageNum { + PhysPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for PhysPageNum { + fn from(v: PhysAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for PhysAddr { + fn from(v: PhysPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} + +impl VirtPageNum { + pub fn indexes(&self) -> [usize; 3] { + let mut vpn = self.0; + let mut idx = [0usize; 3]; + for i in (0..3).rev() { + idx[i] = vpn & 511; + vpn >>= 9; + } + idx + } +} + +impl PhysAddr { + pub fn get_ref(&self) -> &'static T { + unsafe { (self.0 as *const T).as_ref().unwrap() } + } + pub fn get_mut(&self) -> &'static mut T { + unsafe { (self.0 as *mut T).as_mut().unwrap() } + } +} +impl PhysPageNum { + pub fn get_pte_array(&self) -> &'static mut [PageTableEntry] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut PageTableEntry, 512) } + } + pub fn get_bytes_array(&self) -> &'static mut [u8] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut u8, 4096) } + } + pub fn get_mut(&self) -> &'static mut T { + let pa: PhysAddr = (*self).into(); + pa.get_mut() + } +} + +pub trait StepByOne { + fn step(&mut self); +} +impl StepByOne for VirtPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +impl StepByOne for PhysPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +#[derive(Copy, Clone)] +/// a simple range structure for type T +pub struct SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + l: T, + r: T, +} +impl SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(start: T, end: T) -> Self { + assert!(start <= end, "start {:?} > end {:?}!", start, end); + Self { l: start, r: end } + } + pub fn get_start(&self) -> T { + self.l + } + pub fn get_end(&self) -> T { + self.r + } +} +impl IntoIterator for SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + type IntoIter = SimpleRangeIterator; + fn into_iter(self) -> Self::IntoIter { + SimpleRangeIterator::new(self.l, self.r) + } +} +/// iterator for the simple range structure +pub struct SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + current: T, + end: T, +} +impl SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(l: T, r: T) -> Self { + Self { current: l, end: r } + } +} +impl Iterator for SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + fn next(&mut self) -> Option { + if self.current == self.end { + None + } else { + let t = self.current; + self.current.step(); + Some(t) + } + } +} + +/// a simple range structure for virtual page number +pub type VPNRange = SimpleRange; diff --git a/os6-ref/src/mm/frame_allocator.rs b/os6-ref/src/mm/frame_allocator.rs new file mode 100644 index 0000000..ab1ed57 --- /dev/null +++ b/os6-ref/src/mm/frame_allocator.rs @@ -0,0 +1,136 @@ +//! Implementation of [`FrameAllocator`] which +//! controls all the frames in the operating system. + +use super::{PhysAddr, PhysPageNum}; +use crate::config::MEMORY_END; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use core::fmt::{self, Debug, Formatter}; +use lazy_static::*; + +/// manage a frame which has the same lifecycle as the tracker +pub struct FrameTracker { + pub ppn: PhysPageNum, +} + +impl FrameTracker { + pub fn new(ppn: PhysPageNum) -> Self { + // page cleaning + let bytes_array = ppn.get_bytes_array(); + for i in bytes_array { + *i = 0; + } + Self { ppn } + } +} + +impl Debug for FrameTracker { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("FrameTracker:PPN={:#x}", self.ppn.0)) + } +} + +impl Drop for FrameTracker { + fn drop(&mut self) { + frame_dealloc(self.ppn); + } +} + +trait FrameAllocator { + fn new() -> Self; + fn alloc(&mut self) -> Option; + fn dealloc(&mut self, ppn: PhysPageNum); +} + +/// an implementation for frame allocator +pub struct StackFrameAllocator { + current: usize, + end: usize, + recycled: Vec, +} + +impl StackFrameAllocator { + pub fn init(&mut self, l: PhysPageNum, r: PhysPageNum) { + self.current = l.0; + self.end = r.0; + info!("last {} Physical Frames.", self.end - self.current); + } +} +impl FrameAllocator for StackFrameAllocator { + fn new() -> Self { + Self { + current: 0, + end: 0, + recycled: Vec::new(), + } + } + fn alloc(&mut self) -> Option { + if let Some(ppn) = self.recycled.pop() { + Some(ppn.into()) + } else if self.current == self.end { + None + } else { + self.current += 1; + Some((self.current - 1).into()) + } + } + fn dealloc(&mut self, ppn: PhysPageNum) { + let ppn = ppn.0; + // validity check + if ppn >= self.current || self.recycled.iter().any(|v| *v == ppn) { + panic!("Frame ppn={:#x} has not been allocated!", ppn); + } + // recycle + self.recycled.push(ppn); + } +} + +type FrameAllocatorImpl = StackFrameAllocator; + +lazy_static! { + /// frame allocator instance through lazy_static! + pub static ref FRAME_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(FrameAllocatorImpl::new()) }; +} + +pub fn init_frame_allocator() { + extern "C" { + fn ekernel(); + } + FRAME_ALLOCATOR.exclusive_access().init( + PhysAddr::from(ekernel as usize).ceil(), + PhysAddr::from(MEMORY_END).floor(), + ); +} + +/// initiate the frame allocator using `ekernel` and `MEMORY_END` +pub fn frame_alloc() -> Option { + FRAME_ALLOCATOR + .exclusive_access() + .alloc() + .map(FrameTracker::new) +} + +/// deallocate a frame +pub fn frame_dealloc(ppn: PhysPageNum) { + FRAME_ALLOCATOR.exclusive_access().dealloc(ppn); +} + +#[allow(unused)] +/// a simple test for frame allocator +pub fn frame_allocator_test() { + let mut v: Vec = Vec::new(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + v.clear(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + drop(v); + info!("frame_allocator_test passed!"); +} diff --git a/os6-ref/src/mm/heap_allocator.rs b/os6-ref/src/mm/heap_allocator.rs new file mode 100644 index 0000000..d518fae --- /dev/null +++ b/os6-ref/src/mm/heap_allocator.rs @@ -0,0 +1,51 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[allow(unused)] +pub fn heap_test() { + use alloc::boxed::Box; + use alloc::vec::Vec; + extern "C" { + fn sbss(); + fn ebss(); + } + let bss_range = sbss as usize..ebss as usize; + let a = Box::new(5); + assert_eq!(*a, 5); + assert!(bss_range.contains(&(a.as_ref() as *const _ as usize))); + drop(a); + let mut v: Vec = Vec::new(); + for i in 0..500 { + v.push(i); + } + for (i, vi) in v.iter().enumerate().take(500) { + assert_eq!(*vi, i); + } + assert!(bss_range.contains(&(v.as_ptr() as usize))); + drop(v); + info!("heap_test passed!"); +} diff --git a/os6-ref/src/mm/memory_set.rs b/os6-ref/src/mm/memory_set.rs new file mode 100644 index 0000000..44cf097 --- /dev/null +++ b/os6-ref/src/mm/memory_set.rs @@ -0,0 +1,404 @@ +//! Implementation of [`MapArea`] and [`MemorySet`]. + +use super::{frame_alloc, FrameTracker}; +use super::{PTEFlags, PageTable, PageTableEntry}; +use super::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use super::{StepByOne, VPNRange}; +use crate::config::{MEMORY_END, PAGE_SIZE, TRAMPOLINE, TRAP_CONTEXT, USER_STACK_SIZE, MMIO}; +use crate::sync::UPSafeCell; +use alloc::collections::BTreeMap; +use alloc::sync::Arc; +use alloc::vec::Vec; +use lazy_static::*; +use riscv::register::satp; + +extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss_with_stack(); + fn ebss(); + fn ekernel(); + fn strampoline(); +} + +lazy_static! { + /// a memory set instance through lazy_static! managing kernel space + pub static ref KERNEL_SPACE: Arc> = + Arc::new(unsafe { UPSafeCell::new(MemorySet::new_kernel()) }); +} + +/// Get the token of the kernel memory space +pub fn kernel_token() -> usize { + KERNEL_SPACE.exclusive_access().token() +} + +/// memory set structure, controls virtual-memory space +pub struct MemorySet { + page_table: PageTable, + areas: Vec, +} + +impl MemorySet { + pub fn new_bare() -> Self { + Self { + page_table: PageTable::new(), + areas: Vec::new(), + } + } + pub fn token(&self) -> usize { + self.page_table.token() + } + /// Assume that no conflicts. + pub fn insert_framed_area( + &mut self, + start_va: VirtAddr, + end_va: VirtAddr, + permission: MapPermission, + ) { + self.push( + MapArea::new(start_va, end_va, MapType::Framed, permission), + None, + ); + } + pub fn remove_area_with_start_vpn(&mut self, start_vpn: VirtPageNum) { + if let Some((idx, area)) = self + .areas + .iter_mut() + .enumerate() + .find(|(_, area)| area.vpn_range.get_start() == start_vpn) + { + area.unmap(&mut self.page_table); + self.areas.remove(idx); + } + } + fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) { + map_area.map(&mut self.page_table); + if let Some(data) = data { + map_area.copy_data(&mut self.page_table, data); + } + self.areas.push(map_area); + } + /// Mention that trampoline is not collected by areas. + fn map_trampoline(&mut self) { + self.page_table.map( + VirtAddr::from(TRAMPOLINE).into(), + PhysAddr::from(strampoline as usize).into(), + PTEFlags::R | PTEFlags::X, + ); + } + /// Without kernel stacks. + pub fn new_kernel() -> Self { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map kernel sections + info!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + info!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + info!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + info!( + ".bss [{:#x}, {:#x})", + sbss_with_stack as usize, ebss as usize + ); + info!("mapping .text section"); + memory_set.push( + MapArea::new( + (stext as usize).into(), + (etext as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::X, + ), + None, + ); + info!("mapping .rodata section"); + memory_set.push( + MapArea::new( + (srodata as usize).into(), + (erodata as usize).into(), + MapType::Identical, + MapPermission::R, + ), + None, + ); + info!("mapping .data section"); + memory_set.push( + MapArea::new( + (sdata as usize).into(), + (edata as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping .bss section"); + memory_set.push( + MapArea::new( + (sbss_with_stack as usize).into(), + (ebss as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping physical memory"); + memory_set.push( + MapArea::new( + (ekernel as usize).into(), + MEMORY_END.into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping memory-mapped registers"); + for pair in MMIO { + memory_set.push( + MapArea::new( + (*pair).0.into(), + ((*pair).0 + (*pair).1).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None); + } + memory_set + } + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map program headers of elf, with U flag + let elf = xmas_elf::ElfFile::new(elf_data).unwrap(); + let elf_header = elf.header; + let magic = elf_header.pt1.magic; + assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!"); + let ph_count = elf_header.pt2.ph_count(); + let mut max_end_vpn = VirtPageNum(0); + for i in 0..ph_count { + let ph = elf.program_header(i).unwrap(); + if ph.get_type().unwrap() == xmas_elf::program::Type::Load { + let start_va: VirtAddr = (ph.virtual_addr() as usize).into(); + let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into(); + let mut map_perm = MapPermission::U; + let ph_flags = ph.flags(); + if ph_flags.is_read() { + map_perm |= MapPermission::R; + } + if ph_flags.is_write() { + map_perm |= MapPermission::W; + } + if ph_flags.is_execute() { + map_perm |= MapPermission::X; + } + let map_area = MapArea::new(start_va, end_va, MapType::Framed, map_perm); + max_end_vpn = map_area.vpn_range.get_end(); + memory_set.push( + map_area, + Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]), + ); + } + } + // map user stack with U flags + let max_end_va: VirtAddr = max_end_vpn.into(); + let mut user_stack_bottom: usize = max_end_va.into(); + // guard page + user_stack_bottom += PAGE_SIZE; + let user_stack_top = user_stack_bottom + USER_STACK_SIZE; + memory_set.push( + MapArea::new( + user_stack_bottom.into(), + user_stack_top.into(), + MapType::Framed, + MapPermission::R | MapPermission::W | MapPermission::U, + ), + None, + ); + // map TrapContext + memory_set.push( + MapArea::new( + TRAP_CONTEXT.into(), + TRAMPOLINE.into(), + MapType::Framed, + MapPermission::R | MapPermission::W, + ), + None, + ); + ( + memory_set, + user_stack_top, + elf.header.pt2.entry_point() as usize, + ) + } + /// Copy an identical user_space + pub fn from_existed_user(user_space: &MemorySet) -> MemorySet { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // copy data sections/trap_context/user_stack + for area in user_space.areas.iter() { + let new_area = MapArea::from_another(area); + memory_set.push(new_area, None); + // copy data from another space + for vpn in area.vpn_range { + let src_ppn = user_space.translate(vpn).unwrap().ppn(); + let dst_ppn = memory_set.translate(vpn).unwrap().ppn(); + dst_ppn + .get_bytes_array() + .copy_from_slice(src_ppn.get_bytes_array()); + } + } + memory_set + } + pub fn activate(&self) { + let satp = self.page_table.token(); + unsafe { + satp::write(satp); + core::arch::asm!("sfence.vma"); + } + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.page_table.translate(vpn) + } + pub fn recycle_data_pages(&mut self) { + //*self = Self::new_bare(); + self.areas.clear(); + } +} + +/// map area structure, controls a contiguous piece of virtual memory +pub struct MapArea { + vpn_range: VPNRange, + data_frames: BTreeMap, + map_type: MapType, + map_perm: MapPermission, +} + +impl MapArea { + pub fn new( + start_va: VirtAddr, + end_va: VirtAddr, + map_type: MapType, + map_perm: MapPermission, + ) -> Self { + let start_vpn: VirtPageNum = start_va.floor(); + let end_vpn: VirtPageNum = end_va.ceil(); + Self { + vpn_range: VPNRange::new(start_vpn, end_vpn), + data_frames: BTreeMap::new(), + map_type, + map_perm, + } + } + pub fn from_another(another: &MapArea) -> Self { + Self { + vpn_range: VPNRange::new(another.vpn_range.get_start(), another.vpn_range.get_end()), + data_frames: BTreeMap::new(), + map_type: another.map_type, + map_perm: another.map_perm, + } + } + pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + let ppn: PhysPageNum; + match self.map_type { + MapType::Identical => { + ppn = PhysPageNum(vpn.0); + } + MapType::Framed => { + let frame = frame_alloc().unwrap(); + ppn = frame.ppn; + self.data_frames.insert(vpn, frame); + } + } + let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap(); + page_table.map(vpn, ppn, pte_flags); + } + + pub fn unmap_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + #[allow(clippy::single_match)] + match self.map_type { + MapType::Framed => { + self.data_frames.remove(&vpn); + } + _ => {} + } + page_table.unmap(vpn); + } + pub fn map(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.map_one(page_table, vpn); + } + } + pub fn unmap(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.unmap_one(page_table, vpn); + } + } + /// data: start-aligned but maybe with shorter length + /// assume that all frames were cleared before + pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) { + assert_eq!(self.map_type, MapType::Framed); + let mut start: usize = 0; + let mut current_vpn = self.vpn_range.get_start(); + let len = data.len(); + loop { + let src = &data[start..len.min(start + PAGE_SIZE)]; + let dst = &mut page_table + .translate(current_vpn) + .unwrap() + .ppn() + .get_bytes_array()[..src.len()]; + dst.copy_from_slice(src); + start += PAGE_SIZE; + if start >= len { + break; + } + current_vpn.step(); + } + } +} + +#[derive(Copy, Clone, PartialEq, Debug)] +/// map type for memory set: identical or framed +pub enum MapType { + Identical, + Framed, +} + +bitflags! { + /// map permission corresponding to that in pte: `R W X U` + pub struct MapPermission: u8 { + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + } +} + +#[allow(unused)] +pub fn remap_test() { + let mut kernel_space = KERNEL_SPACE.exclusive_access(); + let mid_text: VirtAddr = ((stext as usize + etext as usize) / 2).into(); + let mid_rodata: VirtAddr = ((srodata as usize + erodata as usize) / 2).into(); + let mid_data: VirtAddr = ((sdata as usize + edata as usize) / 2).into(); + assert!(!kernel_space + .page_table + .translate(mid_text.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_rodata.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_data.floor()) + .unwrap() + .executable()); + info!("remap_test passed!"); +} diff --git a/os6-ref/src/mm/mod.rs b/os6-ref/src/mm/mod.rs new file mode 100644 index 0000000..211cc2f --- /dev/null +++ b/os6-ref/src/mm/mod.rs @@ -0,0 +1,29 @@ +//! Memory management implementation +//! +//! SV39 page-based virtual-memory architecture for RV64 systems, and +//! everything about memory management, like frame allocator, page table, +//! map area and memory set, is implemented here. +//! +//! Every task or process has a memory_set to control its virtual memory. + + +mod address; +mod frame_allocator; +mod heap_allocator; +mod memory_set; +mod page_table; + +pub use address::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +pub use address::{StepByOne, VPNRange}; +pub use frame_allocator::{frame_alloc, frame_dealloc, FrameTracker}; +pub use memory_set::{remap_test, kernel_token}; +pub use memory_set::{MapPermission, MemorySet, KERNEL_SPACE}; +pub use page_table::{translated_byte_buffer, translated_refmut, translated_ref, translated_str, PageTableEntry}; +pub use page_table::{PTEFlags, PageTable, UserBuffer}; + +/// initiate heap allocator, frame allocator and kernel space +pub fn init() { + heap_allocator::init_heap(); + frame_allocator::init_frame_allocator(); + KERNEL_SPACE.exclusive_access().activate(); +} diff --git a/os6-ref/src/mm/page_table.rs b/os6-ref/src/mm/page_table.rs new file mode 100644 index 0000000..dbb195a --- /dev/null +++ b/os6-ref/src/mm/page_table.rs @@ -0,0 +1,260 @@ +//! Implementation of [`PageTableEntry`] and [`PageTable`]. + +use super::{frame_alloc, FrameTracker, PhysAddr, PhysPageNum, StepByOne, VirtAddr, VirtPageNum}; +use alloc::string::String; +use alloc::vec; +use alloc::vec::Vec; +use bitflags::*; + +bitflags! { + /// page table entry flags + pub struct PTEFlags: u8 { + const V = 1 << 0; + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + const G = 1 << 5; + const A = 1 << 6; + const D = 1 << 7; + } +} + +#[derive(Copy, Clone)] +#[repr(C)] +/// page table entry structure +pub struct PageTableEntry { + pub bits: usize, +} + +impl PageTableEntry { + pub fn new(ppn: PhysPageNum, flags: PTEFlags) -> Self { + PageTableEntry { + bits: ppn.0 << 10 | flags.bits as usize, + } + } + pub fn empty() -> Self { + PageTableEntry { bits: 0 } + } + pub fn ppn(&self) -> PhysPageNum { + (self.bits >> 10 & ((1usize << 44) - 1)).into() + } + pub fn flags(&self) -> PTEFlags { + PTEFlags::from_bits(self.bits as u8).unwrap() + } + pub fn is_valid(&self) -> bool { + (self.flags() & PTEFlags::V) != PTEFlags::empty() + } + pub fn readable(&self) -> bool { + (self.flags() & PTEFlags::R) != PTEFlags::empty() + } + pub fn writable(&self) -> bool { + (self.flags() & PTEFlags::W) != PTEFlags::empty() + } + pub fn executable(&self) -> bool { + (self.flags() & PTEFlags::X) != PTEFlags::empty() + } +} + +/// page table structure +pub struct PageTable { + root_ppn: PhysPageNum, + frames: Vec, +} + +/// Assume that it won't oom when creating/mapping. +impl PageTable { + pub fn new() -> Self { + let frame = frame_alloc().unwrap(); + PageTable { + root_ppn: frame.ppn, + frames: vec![frame], + } + } + /// Temporarily used to get arguments from user space. + pub fn from_token(satp: usize) -> Self { + Self { + root_ppn: PhysPageNum::from(satp & ((1usize << 44) - 1)), + frames: Vec::new(), + } + } + fn find_pte_create(&mut self, vpn: VirtPageNum) -> Option<&mut PageTableEntry> { + let mut idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&mut PageTableEntry> = None; + for (i, idx) in idxs.iter_mut().enumerate() { + let pte = &mut ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + let frame = frame_alloc().unwrap(); + *pte = PageTableEntry::new(frame.ppn, PTEFlags::V); + self.frames.push(frame); + } + ppn = pte.ppn(); + } + result + } + fn find_pte(&self, vpn: VirtPageNum) -> Option<&PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&PageTableEntry> = None; + for (i, idx) in idxs.iter().enumerate() { + let pte = &ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + return None; + } + ppn = pte.ppn(); + } + result + } + #[allow(unused)] + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(!pte.is_valid(), "vpn {:?} is mapped before mapping", vpn); + *pte = PageTableEntry::new(ppn, flags | PTEFlags::V); + } + #[allow(unused)] + pub fn unmap(&mut self, vpn: VirtPageNum) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(pte.is_valid(), "vpn {:?} is invalid before unmapping", vpn); + *pte = PageTableEntry::empty(); + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.find_pte(vpn).copied() + } + pub fn translate_va(&self, va: VirtAddr) -> Option { + self.find_pte(va.clone().floor()).map(|pte| { + //println!("translate_va:va = {:?}", va); + let aligned_pa: PhysAddr = pte.ppn().into(); + //println!("translate_va:pa_align = {:?}", aligned_pa); + let offset = va.page_offset(); + let aligned_pa_usize: usize = aligned_pa.into(); + (aligned_pa_usize + offset).into() + }) + } + pub fn token(&self) -> usize { + 8usize << 60 | self.root_ppn.0 + } +} + +/// translate a pointer to a mutable u8 Vec through page table +pub fn translated_byte_buffer(token: usize, ptr: *const u8, len: usize) -> Vec<&'static mut [u8]> { + let page_table = PageTable::from_token(token); + let mut start = ptr as usize; + let end = start + len; + let mut v = Vec::new(); + while start < end { + let start_va = VirtAddr::from(start); + let mut vpn = start_va.floor(); + let ppn = page_table.translate(vpn).unwrap().ppn(); + vpn.step(); + let mut end_va: VirtAddr = vpn.into(); + end_va = end_va.min(VirtAddr::from(end)); + if end_va.page_offset() == 0 { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..]); + } else { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..end_va.page_offset()]); + } + start = end_va.into(); + } + v +} + +pub fn translated_str(token: usize, ptr: *const u8) -> String { + let page_table = PageTable::from_token(token); + let mut string = String::new(); + let mut va = ptr as usize; + loop { + let ch: u8 = *(page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut()); + if ch == 0 { + break; + } else { + string.push(ch as char); + va += 1; + } + } + string +} + +pub fn translated_ref(token: usize, ptr: *const T) -> &'static T { + let page_table = PageTable::from_token(token); + page_table.translate_va(VirtAddr::from(ptr as usize)).unwrap().get_mut() +} + +pub fn translated_refmut(token: usize, ptr: *mut T) -> &'static mut T { + //println!("into translated_refmut!"); + let page_table = PageTable::from_token(token); + let va = ptr as usize; + //println!("translated_refmut: before translate_va"); + page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut() +} + +/// An abstraction over a buffer passed from user space to kernel space +pub struct UserBuffer { + pub buffers: Vec<&'static mut [u8]>, +} + +impl UserBuffer { + /// Constuct a UserBuffer + pub fn new(buffers: Vec<&'static mut [u8]>) -> Self { + Self { buffers } + } + /// Get the length of a UserBuffer + pub fn len(&self) -> usize { + let mut total: usize = 0; + for b in self.buffers.iter() { + total += b.len(); + } + total + } +} + +impl IntoIterator for UserBuffer { + type Item = *mut u8; + type IntoIter = UserBufferIterator; + fn into_iter(self) -> Self::IntoIter { + UserBufferIterator { + buffers: self.buffers, + current_buffer: 0, + current_idx: 0, + } + } +} + +// An iterator over a UserBuffer +pub struct UserBufferIterator { + buffers: Vec<&'static mut [u8]>, + current_buffer: usize, + current_idx: usize, +} + +impl Iterator for UserBufferIterator { + type Item = *mut u8; + fn next(&mut self) -> Option { + if self.current_buffer >= self.buffers.len() { + None + } else { + let r = &mut self.buffers[self.current_buffer][self.current_idx] as *mut _; + if self.current_idx + 1 == self.buffers[self.current_buffer].len() { + self.current_idx = 0; + self.current_buffer += 1; + } else { + self.current_idx += 1; + } + Some(r) + } + } +} diff --git a/os6-ref/src/sbi.rs b/os6-ref/src/sbi.rs new file mode 100644 index 0000000..4af7620 --- /dev/null +++ b/os6-ref/src/sbi.rs @@ -0,0 +1,45 @@ +//! SBI call wrappers + +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +/// general sbi call +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +/// use sbi call to set timer +pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); +} + +/// use sbi call to putchar in console (qemu uart handler) +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +/// use sbi call to getchar from console (qemu uart handler) +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +/// use sbi call to shutdown the kernel +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os6-ref/src/sync/mod.rs b/os6-ref/src/sync/mod.rs new file mode 100644 index 0000000..4743e31 --- /dev/null +++ b/os6-ref/src/sync/mod.rs @@ -0,0 +1,5 @@ +//! Synchronization and interior mutability primitives + +mod up; + +pub use up::UPSafeCell; diff --git a/os6-ref/src/sync/up.rs b/os6-ref/src/sync/up.rs new file mode 100644 index 0000000..039b039 --- /dev/null +++ b/os6-ref/src/sync/up.rs @@ -0,0 +1,31 @@ +//! Uniprocessor interior mutability primitives + +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os6-ref/src/syscall/fs.rs b/os6-ref/src/syscall/fs.rs new file mode 100644 index 0000000..f41b5cd --- /dev/null +++ b/os6-ref/src/syscall/fs.rs @@ -0,0 +1,93 @@ +//! File and filesystem-related syscalls + +use crate::mm::translated_byte_buffer; +use crate::mm::translated_str; +use crate::mm::translated_refmut; +use crate::task::current_user_token; +use crate::task::current_task; +use crate::fs::open_file; +use crate::fs::OpenFlags; +use crate::fs::Stat; +use crate::mm::UserBuffer; +use alloc::sync::Arc; + +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let task = current_task().unwrap(); + let inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release current task TCB manually to avoid multi-borrow + drop(inner); + file.write( + UserBuffer::new(translated_byte_buffer(token, buf, len)) + ) as isize + } else { + -1 + } +} + +pub fn sys_read(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let task = current_task().unwrap(); + let inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release current task TCB manually to avoid multi-borrow + drop(inner); + file.read( + UserBuffer::new(translated_byte_buffer(token, buf, len)) + ) as isize + } else { + -1 + } +} + +pub fn sys_open(path: *const u8, flags: u32) -> isize { + let task = current_task().unwrap(); + let token = current_user_token(); + let path = translated_str(token, path); + if let Some(inode) = open_file( + path.as_str(), + OpenFlags::from_bits(flags).unwrap() + ) { + let mut inner = task.inner_exclusive_access(); + let fd = inner.alloc_fd(); + inner.fd_table[fd] = Some(inode); + fd as isize + } else { + -1 + } +} + +pub fn sys_close(fd: usize) -> isize { + let task = current_task().unwrap(); + let mut inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + inner.fd_table[fd].take(); + 0 +} + +// YOUR JOB: 扩展 easy-fs 和内核以实现以下三个 syscall +pub fn sys_fstat(_fd: usize, _st: *mut Stat) -> isize { + -1 +} + +pub fn sys_linkat(_old_name: *const u8, _new_name: *const u8) -> isize { + -1 +} + +pub fn sys_unlinkat(_name: *const u8) -> isize { + -1 +} diff --git a/os6-ref/src/syscall/mod.rs b/os6-ref/src/syscall/mod.rs new file mode 100644 index 0000000..832d6a6 --- /dev/null +++ b/os6-ref/src/syscall/mod.rs @@ -0,0 +1,64 @@ +//! Implementation of syscalls +//! +//! The single entry point to all system calls, [`syscall()`], is called +//! whenever userspace wishes to perform a system call using the `ecall` +//! instruction. In this case, the processor raises an 'Environment call from +//! U-mode' exception, which is handled as one of the cases in +//! [`crate::trap::trap_handler`]. +//! +//! For clarity, each single syscall is implemented as its own function, named +//! `sys_` then the name of the syscall. You can find functions like this in +//! submodules, and you should also implement syscalls this way. + +const SYSCALL_UNLINKAT: usize = 35; +const SYSCALL_LINKAT: usize = 37; +const SYSCALL_OPEN: usize = 56; +const SYSCALL_CLOSE: usize = 57; +const SYSCALL_READ: usize = 63; +const SYSCALL_WRITE: usize = 64; +const SYSCALL_FSTAT: usize = 80; +const SYSCALL_EXIT: usize = 93; +const SYSCALL_YIELD: usize = 124; +const SYSCALL_GET_TIME: usize = 169; +const SYSCALL_GETPID: usize = 172; +const SYSCALL_FORK: usize = 220; +const SYSCALL_EXEC: usize = 221; +const SYSCALL_WAITPID: usize = 260; +const SYSCALL_SPAWN: usize = 400; +const SYSCALL_MUNMAP: usize = 215; +const SYSCALL_MMAP: usize = 222; +const SYSCALL_SET_PRIORITY: usize = 140; +const SYSCALL_TASK_INFO: usize = 410; + +mod fs; +pub mod process; + +use fs::*; +use process::*; +use crate::fs::Stat; + +/// handle syscall exception with `syscall_id` and other arguments +pub fn syscall(syscall_id: usize, args: [usize; 4]) -> isize { + match syscall_id { + SYSCALL_LINKAT => sys_linkat(args[1] as *const u8, args[3] as *const u8), + SYSCALL_UNLINKAT => sys_unlinkat(args[1] as *const u8), + SYSCALL_OPEN => sys_open(args[1] as *const u8, args[2] as u32), + SYSCALL_CLOSE => sys_close(args[0]), + SYSCALL_READ => sys_read(args[0], args[1] as *const u8, args[2]), + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_FSTAT => sys_fstat(args[0], args[1] as *mut Stat), + SYSCALL_EXIT => sys_exit(args[0] as i32), + SYSCALL_YIELD => sys_yield(), + SYSCALL_GETPID => sys_getpid(), + SYSCALL_FORK => sys_fork(), + SYSCALL_EXEC => sys_exec(args[0] as *const u8), + SYSCALL_WAITPID => sys_waitpid(args[0] as isize, args[1] as *mut i32), + SYSCALL_GET_TIME => sys_get_time(args[0] as *mut TimeVal, args[1]), + SYSCALL_MMAP => sys_mmap(args[0], args[1], args[2]), + SYSCALL_MUNMAP => sys_munmap(args[0], args[1]), + SYSCALL_SET_PRIORITY => sys_set_priority(args[0] as isize), + SYSCALL_TASK_INFO => sys_task_info(args[0] as *mut TaskInfo), + SYSCALL_SPAWN => sys_spawn(args[0] as *const u8), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os6-ref/src/syscall/process.rs b/os6-ref/src/syscall/process.rs new file mode 100644 index 0000000..b7009e9 --- /dev/null +++ b/os6-ref/src/syscall/process.rs @@ -0,0 +1,148 @@ +//! Process management syscalls + +use crate::mm::{translated_refmut, translated_ref, translated_str}; +use crate::task::{ + add_task, current_task, current_user_token, exit_current_and_run_next, + suspend_current_and_run_next, TaskStatus, +}; +use crate::fs::{open_file, OpenFlags}; +use crate::timer::get_time_us; +use alloc::sync::Arc; +use alloc::vec::Vec; +use crate::config::MAX_SYSCALL_NUM; +use alloc::string::String; + +#[repr(C)] +#[derive(Debug)] +pub struct TimeVal { + pub sec: usize, + pub usec: usize, +} + +#[derive(Clone, Copy)] +pub struct TaskInfo { + pub status: TaskStatus, + pub syscall_times: [u32; MAX_SYSCALL_NUM], + pub time: usize, +} + +pub fn sys_exit(exit_code: i32) -> ! { + debug!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(exit_code); + panic!("Unreachable in sys_exit!"); +} + +/// current task gives up resources for other tasks +pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 +} + +pub fn sys_getpid() -> isize { + current_task().unwrap().pid.0 as isize +} + +/// Syscall Fork which returns 0 for child process and child_pid for parent process +pub fn sys_fork() -> isize { + let current_task = current_task().unwrap(); + let new_task = current_task.fork(); + let new_pid = new_task.pid.0; + // modify trap context of new_task, because it returns immediately after switching + let trap_cx = new_task.inner_exclusive_access().get_trap_cx(); + // we do not have to move to next instruction since we have done it before + // for child process, fork returns 0 + trap_cx.x[10] = 0; + // add new task to scheduler + add_task(new_task); + new_pid as isize +} + +/// Syscall Exec which accepts the elf path +pub fn sys_exec(path: *const u8) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + if let Some(app_inode) = open_file(path.as_str(), OpenFlags::RDONLY) { + let all_data = app_inode.read_all(); + let task = current_task().unwrap(); + task.exec(all_data.as_slice()); + 0 + } else { + -1 + } +} + + +/// If there is not a child process whose pid is same as given, return -1. +/// Else if there is a child process but it is still running, return -2. +pub fn sys_waitpid(pid: isize, exit_code_ptr: *mut i32) -> isize { + let task = current_task().unwrap(); + // find a child process + + // ---- access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + if !inner + .children + .iter() + .any(|p| pid == -1 || pid as usize == p.getpid()) + { + return -1; + // ---- release current PCB + } + let pair = inner.children.iter().enumerate().find(|(_, p)| { + // ++++ temporarily access child PCB lock exclusively + p.inner_exclusive_access().is_zombie() && (pid == -1 || pid as usize == p.getpid()) + // ++++ release child PCB + }); + if let Some((idx, _)) = pair { + let child = inner.children.remove(idx); + // confirm that child will be deallocated after removing from children list + assert_eq!(Arc::strong_count(&child), 1); + let found_pid = child.getpid(); + // ++++ temporarily access child TCB exclusively + let exit_code = child.inner_exclusive_access().exit_code; + // ++++ release child PCB + *translated_refmut(inner.memory_set.token(), exit_code_ptr) = exit_code; + found_pid as isize + } else { + -2 + } + // ---- release current PCB lock automatically +} + +// YOUR JOB: 引入虚地址后重写 sys_get_time +pub fn sys_get_time(_ts: *mut TimeVal, _tz: usize) -> isize { + let _us = get_time_us(); + // unsafe { + // *ts = TimeVal { + // sec: us / 1_000_000, + // usec: us % 1_000_000, + // }; + // } + 0 +} + +// YOUR JOB: 引入虚地址后重写 sys_task_info +pub fn sys_task_info(ti: *mut TaskInfo) -> isize { + -1 +} + +// YOUR JOB: 实现sys_set_priority，为任务添加优先级 +pub fn sys_set_priority(_prio: isize) -> isize { + -1 +} + +// YOUR JOB: 扩展内核以实现 sys_mmap 和 sys_munmap +pub fn sys_mmap(_start: usize, _len: usize, _port: usize) -> isize { + -1 +} + +pub fn sys_munmap(_start: usize, _len: usize) -> isize { + -1 +} + +// +// YOUR JOB: 实现 sys_spawn 系统调用 +// ALERT: 注意在实现 SPAWN 时不需要复制父进程地址空间，SPAWN != FORK + EXEC +pub fn sys_spawn(_path: *const u8) -> isize { + -1 +} diff --git a/os6-ref/src/task/context.rs b/os6-ref/src/task/context.rs new file mode 100644 index 0000000..200bfb1 --- /dev/null +++ b/os6-ref/src/task/context.rs @@ -0,0 +1,32 @@ +//! Implementation of [`TaskContext`] + +use crate::trap::trap_return; + +#[derive(Copy, Clone)] +#[repr(C)] +/// task context structure containing some registers +pub struct TaskContext { + /// Ret position after task switching + ra: usize, + /// Stack pointer + sp: usize, + /// s0-11 register, callee saved + s: [usize; 12], +} + +impl TaskContext { + pub fn zero_init() -> Self { + Self { + ra: 0, + sp: 0, + s: [0; 12], + } + } + pub fn goto_trap_return(kstack_ptr: usize) -> Self { + Self { + ra: trap_return as usize, + sp: kstack_ptr, + s: [0; 12], + } + } +} diff --git a/os6-ref/src/task/manager.rs b/os6-ref/src/task/manager.rs new file mode 100644 index 0000000..47f7ace --- /dev/null +++ b/os6-ref/src/task/manager.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TaskManager`] +//! +//! It is only used to manage processes and schedule process based on ready queue. +//! Other CPU process monitoring functions are in Processor. + + +use super::TaskControlBlock; +use crate::sync::UPSafeCell; +use alloc::collections::VecDeque; +use alloc::sync::Arc; +use lazy_static::*; + +pub struct TaskManager { + ready_queue: VecDeque>, +} + +// YOUR JOB: FIFO->Stride +/// A simple FIFO scheduler. +impl TaskManager { + pub fn new() -> Self { + Self { + ready_queue: VecDeque::new(), + } + } + /// Add process back to ready queue + pub fn add(&mut self, task: Arc) { + self.ready_queue.push_back(task); + } + /// Take a process out of the ready queue + pub fn fetch(&mut self) -> Option> { + self.ready_queue.pop_front() + } +} + +lazy_static! { + /// TASK_MANAGER instance through lazy_static! + pub static ref TASK_MANAGER: UPSafeCell = + unsafe { UPSafeCell::new(TaskManager::new()) }; +} + +pub fn add_task(task: Arc) { + TASK_MANAGER.exclusive_access().add(task); +} + +pub fn fetch_task() -> Option> { + TASK_MANAGER.exclusive_access().fetch() +} diff --git a/os6-ref/src/task/mod.rs b/os6-ref/src/task/mod.rs new file mode 100644 index 0000000..c2a8ab1 --- /dev/null +++ b/os6-ref/src/task/mod.rs @@ -0,0 +1,106 @@ +//! Implementation of process management mechanism +//! +//! Here is the entry for process scheduling required by other modules +//! (such as syscall or clock interrupt). +//! By suspending or exiting the current process, you can +//! modify the process state, manage the process queue through TASK_MANAGER, +//! and switch the control flow through PROCESSOR. +//! +//! Be careful when you see [`__switch`]. Control flow around this function +//! might not be what you expect. + +mod context; +mod manager; +mod pid; +mod processor; +mod switch; +#[allow(clippy::module_inception)] +mod task; + +use alloc::sync::Arc; +use lazy_static::*; +use manager::fetch_task; +use switch::__switch; +use crate::mm::VirtAddr; +use crate::mm::MapPermission; +use crate::config::PAGE_SIZE; +use crate::timer::get_time_us; +pub use crate::syscall::process::TaskInfo; +use crate::fs::{open_file, OpenFlags}; +pub use task::{TaskControlBlock, TaskStatus}; + +pub use context::TaskContext; +pub use manager::add_task; +pub use pid::{pid_alloc, KernelStack, PidHandle}; +pub use processor::{ + current_task, current_trap_cx, current_user_token, run_tasks, schedule, take_current_task, +}; + +/// Make current task suspended and switch to the next task +pub fn suspend_current_and_run_next() { + // There must be an application running. + let task = take_current_task().unwrap(); + + // ---- access current TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let task_cx_ptr = &mut task_inner.task_cx as *mut TaskContext; + // Change status to Ready + task_inner.task_status = TaskStatus::Ready; + drop(task_inner); + // ---- release current PCB + + // push back to ready queue. + add_task(task); + // jump to scheduling cycle + schedule(task_cx_ptr); +} + +/// Exit current task, recycle process resources and switch to the next task +pub fn exit_current_and_run_next(exit_code: i32) { + // take from Processor + let task = take_current_task().unwrap(); + // **** access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + // Change status to Zombie + inner.task_status = TaskStatus::Zombie; + // Record exit code + inner.exit_code = exit_code; + // do not move to its parent but under initproc + + // ++++++ access initproc TCB exclusively + { + let mut initproc_inner = INITPROC.inner_exclusive_access(); + for child in inner.children.iter() { + child.inner_exclusive_access().parent = Some(Arc::downgrade(&INITPROC)); + initproc_inner.children.push(child.clone()); + } + } + // ++++++ release parent PCB + + inner.children.clear(); + // deallocate user space + inner.memory_set.recycle_data_pages(); + drop(inner); + // **** release current PCB + // drop task manually to maintain rc correctly + drop(task); + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); +} + +lazy_static! { + /// Creation of initial process + /// + /// the name "initproc" may be changed to any other app name like "usertests", + /// but we have user_shell, so we don't need to change it. + pub static ref INITPROC: Arc = Arc::new({ + let inode = open_file("ch6b_initproc", OpenFlags::RDONLY).unwrap(); + let v = inode.read_all(); + TaskControlBlock::new(v.as_slice()) + }); +} + +pub fn add_initproc() { + add_task(INITPROC.clone()); +} diff --git a/os6-ref/src/task/pid.rs b/os6-ref/src/task/pid.rs new file mode 100644 index 0000000..6e5c194 --- /dev/null +++ b/os6-ref/src/task/pid.rs @@ -0,0 +1,116 @@ +//! Task pid implementation. +//! +//! Assign PID to the process here. At the same time, the position of the application KernelStack +//! is determined according to the PID. + +use crate::config::{KERNEL_STACK_SIZE, PAGE_SIZE, TRAMPOLINE}; +use crate::mm::{MapPermission, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use lazy_static::*; + +/// Process identifier allocator using stack allocation +struct PidAllocator { + /// A new PID to be assigned + current: usize, + /// Recycled PID sequence + recycled: Vec, +} + +impl PidAllocator { + pub fn new() -> Self { + PidAllocator { + current: 0, + recycled: Vec::new(), + } + } + pub fn alloc(&mut self) -> PidHandle { + if let Some(pid) = self.recycled.pop() { + PidHandle(pid) + } else { + self.current += 1; + PidHandle(self.current - 1) + } + } + pub fn dealloc(&mut self, pid: usize) { + assert!(pid < self.current); + assert!( + !self.recycled.iter().any(|ppid| *ppid == pid), + "pid {} has been deallocated!", + pid + ); + self.recycled.push(pid); + } +} + +lazy_static! { + /// Pid allocator instance through lazy_static! + static ref PID_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(PidAllocator::new()) }; +} + +/// Abstract structure of PID +pub struct PidHandle(pub usize); + +impl Drop for PidHandle { + fn drop(&mut self) { + //println!("drop pid {}", self.0); + PID_ALLOCATOR.exclusive_access().dealloc(self.0); + } +} + +pub fn pid_alloc() -> PidHandle { + PID_ALLOCATOR.exclusive_access().alloc() +} + +/// Return (bottom, top) of a kernel stack in kernel space. +pub fn kernel_stack_position(app_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) +} + +/// KernelStack corresponding to PID +pub struct KernelStack { + pid: usize, +} + +impl KernelStack { + pub fn new(pid_handle: &PidHandle) -> Self { + let pid = pid_handle.0; + let (kernel_stack_bottom, kernel_stack_top) = kernel_stack_position(pid); + KERNEL_SPACE.exclusive_access().insert_framed_area( + kernel_stack_bottom.into(), + kernel_stack_top.into(), + MapPermission::R | MapPermission::W, + ); + KernelStack { pid: pid_handle.0 } + } + #[allow(unused)] + /// Push a variable of type T into the top of the KernelStack and return its raw pointer + pub fn push_on_top(&self, value: T) -> *mut T + where + T: Sized, + { + let kernel_stack_top = self.get_top(); + let ptr_mut = (kernel_stack_top - core::mem::size_of::()) as *mut T; + unsafe { + *ptr_mut = value; + } + ptr_mut + } + pub fn get_top(&self) -> usize { + let (_, kernel_stack_top) = kernel_stack_position(self.pid); + kernel_stack_top + } +} + +impl Drop for KernelStack { + fn drop(&mut self) { + let (kernel_stack_bottom, _) = kernel_stack_position(self.pid); + let kernel_stack_bottom_va: VirtAddr = kernel_stack_bottom.into(); + KERNEL_SPACE + .exclusive_access() + .remove_area_with_start_vpn(kernel_stack_bottom_va.into()); + } +} diff --git a/os6-ref/src/task/processor.rs b/os6-ref/src/task/processor.rs new file mode 100644 index 0000000..4218e3b --- /dev/null +++ b/os6-ref/src/task/processor.rs @@ -0,0 +1,105 @@ +//! Implementation of [`Processor`] and Intersection of control flow +//! +//! Here, the continuous operation of user apps in CPU is maintained, +//! the current running state of CPU is recorded, +//! and the replacement and transfer of control flow of different applications are executed. + + +use super::__switch; +use super::{fetch_task, TaskStatus}; +use super::{TaskContext, TaskControlBlock}; +use crate::sync::UPSafeCell; +use crate::trap::TrapContext; +use alloc::sync::Arc; +use lazy_static::*; + +/// Processor management structure +pub struct Processor { + /// The task currently executing on the current processor + current: Option>, + /// The basic control flow of each core, helping to select and switch process + idle_task_cx: TaskContext, +} + +impl Processor { + pub fn new() -> Self { + Self { + current: None, + idle_task_cx: TaskContext::zero_init(), + } + } + fn get_idle_task_cx_ptr(&mut self) -> *mut TaskContext { + &mut self.idle_task_cx as *mut _ + } + pub fn take_current(&mut self) -> Option> { + self.current.take() + } + pub fn current(&self) -> Option> { + self.current.as_ref().map(|task| Arc::clone(task)) + } +} + +lazy_static! { + /// PROCESSOR instance through lazy_static! + pub static ref PROCESSOR: UPSafeCell = unsafe { UPSafeCell::new(Processor::new()) }; +} + +/// The main part of process execution and scheduling +/// +/// Loop fetch_task to get the process that needs to run, +/// and switch the process through __switch +pub fn run_tasks() { + loop { + let mut processor = PROCESSOR.exclusive_access(); + if let Some(task) = fetch_task() { + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + // access coming task TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let next_task_cx_ptr = &task_inner.task_cx as *const TaskContext; + task_inner.task_status = TaskStatus::Running; + drop(task_inner); + // release coming task TCB manually + processor.current = Some(task); + // release processor manually + drop(processor); + unsafe { + __switch(idle_task_cx_ptr, next_task_cx_ptr); + } + } + } +} + +/// Get current task through take, leaving a None in its place +pub fn take_current_task() -> Option> { + PROCESSOR.exclusive_access().take_current() +} + +/// Get a copy of the current task +pub fn current_task() -> Option> { + PROCESSOR.exclusive_access().current() +} + +/// Get token of the address space of current task +pub fn current_user_token() -> usize { + let task = current_task().unwrap(); + let token = task.inner_exclusive_access().get_user_token(); + token +} + +/// Get the mutable reference to trap context of current task +pub fn current_trap_cx() -> &'static mut TrapContext { + current_task() + .unwrap() + .inner_exclusive_access() + .get_trap_cx() +} + +/// Return to idle control flow for new scheduling +pub fn schedule(switched_task_cx_ptr: *mut TaskContext) { + let mut processor = PROCESSOR.exclusive_access(); + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + drop(processor); + unsafe { + __switch(switched_task_cx_ptr, idle_task_cx_ptr); + } +} diff --git a/os6-ref/src/task/switch.S b/os6-ref/src/task/switch.S new file mode 100644 index 0000000..3f985d2 --- /dev/null +++ b/os6-ref/src/task/switch.S @@ -0,0 +1,34 @@ +.altmacro +.macro SAVE_SN n + sd s\n, (\n+2)*8(a0) +.endm +.macro LOAD_SN n + ld s\n, (\n+2)*8(a1) +.endm + .section .text + .globl __switch +__switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + diff --git a/os6-ref/src/task/switch.rs b/os6-ref/src/task/switch.rs new file mode 100644 index 0000000..af08289 --- /dev/null +++ b/os6-ref/src/task/switch.rs @@ -0,0 +1,16 @@ +//! Rust wrapper around `__switch`. +//! +//! Switching to a different task's context happens here. The actual +//! implementation must not be in Rust and (essentially) has to be in assembly +//! language (Do you know why?), so this module really is just a wrapper around +//! `switch.S`. + +core::arch::global_asm!(include_str!("switch.S")); + +use super::TaskContext; + +extern "C" { + /// Switch to the context of `next_task_cx_ptr`, saving the current context + /// in `current_task_cx_ptr`. + pub fn __switch(current_task_cx_ptr: *mut TaskContext, next_task_cx_ptr: *const TaskContext); +} diff --git a/os6-ref/src/task/task.rs b/os6-ref/src/task/task.rs new file mode 100644 index 0000000..2707342 --- /dev/null +++ b/os6-ref/src/task/task.rs @@ -0,0 +1,229 @@ +//! Types related to task management & Functions for completely changing TCB + +use super::TaskContext; +use super::{pid_alloc, KernelStack, PidHandle}; +use crate::config::TRAP_CONTEXT; +use crate::mm::{MemorySet, PhysPageNum, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use crate::trap::{trap_handler, TrapContext}; +use alloc::sync::{Arc, Weak}; +use alloc::vec::Vec; +use core::cell::RefMut; +use crate::fs::{File, Stdin, Stdout}; +use alloc::string::String; +use crate::mm::translated_refmut; + +/// Task control block structure +/// +/// Directly save the contents that will not change during running +pub struct TaskControlBlock { + // immutable + /// Process identifier + pub pid: PidHandle, + /// Kernel stack corresponding to PID + pub kernel_stack: KernelStack, + // mutable + inner: UPSafeCell, +} + +/// Structure containing more process content +/// +/// Store the contents that will change during operation +/// and are wrapped by UPSafeCell to provide mutual exclusion +pub struct TaskControlBlockInner { + /// The physical page number of the frame where the trap context is placed + pub trap_cx_ppn: PhysPageNum, + /// Application data can only appear in areas + /// where the application address space is lower than base_size + pub base_size: usize, + /// Save task context + pub task_cx: TaskContext, + /// Maintain the execution status of the current process + pub task_status: TaskStatus, + /// Application address space + pub memory_set: MemorySet, + /// Parent process of the current process. + /// Weak will not affect the reference count of the parent + pub parent: Option>, + /// A vector containing TCBs of all child processes of the current process + pub children: Vec>, + /// It is set when active exit or execution error occurs + pub exit_code: i32, + pub fd_table: Vec>>, +} + +/// Simple access to its internal fields +impl TaskControlBlockInner { + /* + pub fn get_task_cx_ptr2(&self) -> *const usize { + &self.task_cx_ptr as *const usize + } + */ + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + pub fn get_user_token(&self) -> usize { + self.memory_set.token() + } + fn get_status(&self) -> TaskStatus { + self.task_status + } + pub fn is_zombie(&self) -> bool { + self.get_status() == TaskStatus::Zombie + } + pub fn alloc_fd(&mut self) -> usize { + if let Some(fd) = (0..self.fd_table.len()) + .find(|fd| self.fd_table[*fd].is_none()) { + fd + } else { + self.fd_table.push(None); + self.fd_table.len() - 1 + } + } +} + +impl TaskControlBlock { + /// Get the mutex to get the RefMut TaskControlBlockInner + pub fn inner_exclusive_access(&self) -> RefMut<'_, TaskControlBlockInner> { + self.inner.exclusive_access() + } + + /// Create a new process + /// + /// At present, it is only used for the creation of initproc + pub fn new(elf_data: &[u8]) -> Self { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + // push a task context which goes to trap_return to the top of kernel stack + let task_control_block = Self { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: user_sp, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + fd_table: alloc::vec![ + // 0 -> stdin + Some(Arc::new(Stdin)), + // 1 -> stdout + Some(Arc::new(Stdout)), + // 2 -> stderr + Some(Arc::new(Stdout)), + ], + }) + }, + }; + // prepare TrapContext in user space + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + kernel_stack_top, + trap_handler as usize, + ); + task_control_block + } + /// Load a new elf to replace the original application address space and start execution + pub fn exec(&self, elf_data: &[u8]) { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, mut user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // **** access inner exclusively + let mut inner = self.inner_exclusive_access(); + // substitute memory_set + inner.memory_set = memory_set; + // update trap_cx ppn + inner.trap_cx_ppn = trap_cx_ppn; + // initialize trap_cx + let trap_cx = inner.get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + self.kernel_stack.get_top(), + trap_handler as usize, + ); + // **** release inner automatically + } + /// Fork from parent to child + pub fn fork(self: &Arc) -> Arc { + // ---- access parent PCB exclusively + let mut parent_inner = self.inner_exclusive_access(); + // copy user space(include trap context) + let memory_set = MemorySet::from_existed_user(&parent_inner.memory_set); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + let mut new_fd_table: Vec>> = Vec::new(); + // clone all fds from parent to child + for fd in parent_inner.fd_table.iter() { + if let Some(file) = fd { + new_fd_table.push(Some(file.clone())); + } else { + new_fd_table.push(None); + } + } + let task_control_block = Arc::new(TaskControlBlock { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: parent_inner.base_size, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: Some(Arc::downgrade(self)), + children: Vec::new(), + exit_code: 0, + fd_table: new_fd_table, + }) + }, + }); + // add child + parent_inner.children.push(task_control_block.clone()); + // modify kernel_sp in trap_cx + // **** access children PCB exclusively + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + trap_cx.kernel_sp = kernel_stack_top; + // return + task_control_block + // ---- release parent PCB automatically + // **** release children PCB automatically + } + pub fn getpid(&self) -> usize { + self.pid.0 + } +} + +#[derive(Copy, Clone, PartialEq)] +/// task status: UnInit, Ready, Running, Exited +pub enum TaskStatus { + UnInit, + Ready, + Running, + Zombie, +} diff --git a/os6-ref/src/timer.rs b/os6-ref/src/timer.rs new file mode 100644 index 0000000..4f40494 --- /dev/null +++ b/os6-ref/src/timer.rs @@ -0,0 +1,23 @@ +//! RISC-V timer-related functionality + +use crate::config::CLOCK_FREQ; +use crate::sbi::set_timer; +use riscv::register::time; + +const TICKS_PER_SEC: usize = 100; +const MICRO_PER_SEC: usize = 1_000_000; + +/// read the `mtime` register +pub fn get_time() -> usize { + time::read() +} + +/// get current time in microseconds +pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) +} + +/// set the next timer interrupt +pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); +} diff --git a/os6-ref/src/trap/context.rs b/os6-ref/src/trap/context.rs new file mode 100644 index 0000000..58e199c --- /dev/null +++ b/os6-ref/src/trap/context.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TrapContext`] + +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +/// trap context structure containing sstatus, sepc and registers +pub struct TrapContext { + /// General-Purpose Register x0-31 + pub x: [usize; 32], + /// sstatus + pub sstatus: Sstatus, + /// sepc + pub sepc: usize, + /// Token of kernel address space + pub kernel_satp: usize, + /// Kernel stack pointer of the current application + pub kernel_sp: usize, + /// Virtual address of trap handler entry point in kernel + pub trap_handler: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context( + entry: usize, + sp: usize, + kernel_satp: usize, + kernel_sp: usize, + trap_handler: usize, + ) -> Self { + let mut sstatus = sstatus::read(); + // set CPU privilege to User after trapping back + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + kernel_satp, + kernel_sp, + trap_handler, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os6-ref/src/trap/mod.rs b/os6-ref/src/trap/mod.rs new file mode 100644 index 0000000..d686aea --- /dev/null +++ b/os6-ref/src/trap/mod.rs @@ -0,0 +1,131 @@ +//! Trap handling functionality +//! +//! For rCore, we have a single trap entry point, namely `__alltraps`. At +//! initialization in [`init()`], we set the `stvec` CSR to point to it. +//! +//! All traps go through `__alltraps`, which is defined in `trap.S`. The +//! assembly language code does just enough work restore the kernel space +//! context, ensuring that Rust code safely runs, and transfers control to +//! [`trap_handler()`]. +//! +//! It then calls different functionality based on what exactly the exception +//! was. For example, timer interrupts trigger task preemption, and syscalls go +//! to [`syscall()`]. + +mod context; + +use crate::config::{TRAMPOLINE, TRAP_CONTEXT}; +use crate::syscall::syscall; +use crate::task::{ + current_trap_cx, current_user_token, exit_current_and_run_next, suspend_current_and_run_next, +}; +use crate::timer::set_next_trigger; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Interrupt, Trap}, + sie, stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +pub fn init() { + set_kernel_trap_entry(); +} + +fn set_kernel_trap_entry() { + unsafe { + stvec::write(trap_from_kernel as usize, TrapMode::Direct); + } +} + +fn set_user_trap_entry() { + unsafe { + stvec::write(TRAMPOLINE as usize, TrapMode::Direct); + } +} + +pub fn enable_timer_interrupt() { + unsafe { + sie::set_stimer(); + } +} + +#[no_mangle] +pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + // jump to next instruction anyway + let mut cx = current_trap_cx(); + cx.sepc += 4; + // get system call return value + let result = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12], cx.x[13]]); + // cx is changed during sys_exec, so we have to call it again + cx = current_trap_cx(); + cx.x[10] = result as usize; + } + Trap::Exception(Exception::StoreFault) + | Trap::Exception(Exception::StorePageFault) + | Trap::Exception(Exception::InstructionFault) + | Trap::Exception(Exception::InstructionPageFault) + | Trap::Exception(Exception::LoadFault) + | Trap::Exception(Exception::LoadPageFault) => { + println!( + "[kernel] {:?} in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", + scause.cause(), + stval, + current_trap_cx().sepc, + ); + // page fault exit code + exit_current_and_run_next(-2); + } + Trap::Exception(Exception::IllegalInstruction) => { + println!("[kernel] IllegalInstruction in application, core dumped."); + // illegal instruction exit code + exit_current_and_run_next(-3); + } + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + trap_return(); +} + +#[no_mangle] +pub fn trap_return() -> ! { + set_user_trap_entry(); + let trap_cx_ptr = TRAP_CONTEXT; + let user_satp = current_user_token(); + extern "C" { + fn __alltraps(); + fn __restore(); + } + let restore_va = __restore as usize - __alltraps as usize + TRAMPOLINE; + unsafe { + core::arch::asm!( + "fence.i", + "jr {restore_va}", + restore_va = in(reg) restore_va, + in("a0") trap_cx_ptr, + in("a1") user_satp, + options(noreturn) + ); + } +} + +#[no_mangle] +pub fn trap_from_kernel() -> ! { + panic!("a trap {:?} from kernel!", scause::read().cause()); +} + +pub use context::TrapContext; diff --git a/os6-ref/src/trap/trap.S b/os6-ref/src/trap/trap.S new file mode 100644 index 0000000..c0e2d15 --- /dev/null +++ b/os6-ref/src/trap/trap.S @@ -0,0 +1,69 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text.trampoline + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->*TrapContext in user space, sscratch->user stack + # save other general purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they have been saved in TrapContext + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it in TrapContext + csrr t2, sscratch + sd t2, 2*8(sp) + # load kernel_satp into t0 + ld t0, 34*8(sp) + # load trap_handler into t1 + ld t1, 36*8(sp) + # move to kernel_sp + ld sp, 35*8(sp) + # switch to kernel space + csrw satp, t0 + sfence.vma + # jump to trap_handler + jr t1 + +__restore: + # a0: *TrapContext in user space(Constant); a1: user space token + # switch to user space + csrw satp, a1 + sfence.vma + csrw sscratch, a0 + mv sp, a0 + # now sp points to TrapContext in user space, start restoring based on it + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + # restore general purpose registers except x0/sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # back to user stack + ld sp, 2*8(sp) + sret diff --git a/os7-ref/.cargo/config b/os7-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os7-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os7-ref/Cargo.toml b/os7-ref/Cargo.toml new file mode 100644 index 0000000..d0d9e54 --- /dev/null +++ b/os7-ref/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +bitflags = "1.2.1" +buddy_system_allocator = "0.6" +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } +lock_api = "=0.4.6" +xmas-elf = "0.7.0" +virtio-drivers = { git = "https://gitee.com/rcore-os/virtio-drivers" } +easy-fs = { path = "../easy-fs" } diff --git a/os7-ref/Makefile b/os7-ref/Makefile new file mode 100644 index 0000000..b90f596 --- /dev/null +++ b/os7-ref/Makefile @@ -0,0 +1,64 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm +FS_IMG := ../user/target/$(TARGET)/$(MODE)/fs.img +APPS := ../user/src/bin/* + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -o 'ch[0-9]' | grep -o '[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) fs-img + +fs-img: $(APPS) + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cd ../easy-fs-fuse && cargo run --release -- -s ../user/build/app/ -t ../user/target/riscv64gc-unknown-none-elf/release/ + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + @cd ../user && make clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) \ + -drive file=$(FS_IMG),if=none,format=raw,id=x0 \ + -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -drive file=$(FS_IMG),if=none,format=raw,id=x0 -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean fs-img diff --git a/os7-ref/build.rs b/os7-ref/build.rs new file mode 100644 index 0000000..5529b4f --- /dev/null +++ b/os7-ref/build.rs @@ -0,0 +1,6 @@ +static TARGET_PATH: &str = "../user/target/riscv64gc-unknown-none-elf/release/"; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); +} diff --git a/os7-ref/src/config.rs b/os7-ref/src/config.rs new file mode 100644 index 0000000..851df0a --- /dev/null +++ b/os7-ref/src/config.rs @@ -0,0 +1,16 @@ +//! Constants used in rCore + +pub const USER_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_HEAP_SIZE: usize = 0x20_0000; +pub const MEMORY_END: usize = 0x88000000; +pub const PAGE_SIZE: usize = 0x1000; +pub const PAGE_SIZE_BITS: usize = 0xc; +pub const MAX_SYSCALL_NUM: usize = 500; + +pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1; +pub const TRAP_CONTEXT: usize = TRAMPOLINE - PAGE_SIZE; +pub const CLOCK_FREQ: usize = 12500000; +pub const MMIO: &[(usize, usize)] = &[ + (0x10001000, 0x1000), +]; diff --git a/os7-ref/src/console.rs b/os7-ref/src/console.rs new file mode 100644 index 0000000..a23a0e0 --- /dev/null +++ b/os7-ref/src/console.rs @@ -0,0 +1,130 @@ +//! SBI console driver, for text output + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +/// print string macro +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +/// println string macro +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} + +/* +以下代码提供了与颜色相关的 ANSI 转义字符，以及彩色输出可以使用的函数与宏。 + +可以使用它们，甚至扩展它们，来提升开发体验和显示效果。 +*/ + +// 使用 ANSI 转义字符来加上颜色 +#[macro_export] +macro_rules! colorize { + ($content: ident, $foreground_color: ident) => { + format_args!("\u{1B}[{}m{}\u{1B}[0m", $foreground_color as u8, $content) + }; + ($content: ident, $foreground_color: ident, $background_color: ident) => { + format_args!( + "\u{1B}[{}m\u{1B}[{}m{}\u{1B}[0m", + $foreground_color.into(), + $background_color.into(), + $content + ) + }; +} + +pub fn print_colorized( + args: fmt::Arguments, + foreground_color: impl Into, + background_color: impl Into, +) { + Stdout + .write_fmt(colorize!(args, foreground_color, background_color)) + .unwrap(); +} + +#[macro_export] +macro_rules! print_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!($fmt $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + }; +} + +#[macro_export] +macro_rules! println_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!(concat!($fmt, "\n") $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + } +} + +#[allow(dead_code)] +pub enum ANSICON { + Reset = 0, + Bold = 1, + Underline = 4, + Blink = 5, + Reverse = 7, + FgBlack = 30, + FgRed = 31, + FgGreen = 32, + FgYellow = 33, + FgBlue = 34, + FgMagenta = 35, + FgCyan = 36, + FgWhite = 37, + FgDefault = 39, + FgLightGray = 90, + FgLightRed = 91, + FgLightGreen = 92, + FgLightYellow = 93, + FgLightBlue = 94, + FgLightMagenta = 95, + FgLightCyan = 96, + FgLightWhite = 97, + BgBlack = 40, + BgRed = 41, + BgGreen = 42, + BgYellow = 43, + BgBlue = 44, + BgMagenta = 45, + BgCyan = 46, + BgWhite = 47, + BgDefault = 49, + BgLightGray = 100, + BgLightRed = 101, + BgLightGreen = 102, + BgLightYellow = 103, + BgLightBlue = 104, + BgLightMagenta = 105, + BgLightCyan = 106, + BgLightWhite = 107, +} + +impl From for u8 { + fn from(con: ANSICON) -> Self { + con as Self + } +} diff --git a/os7-ref/src/drivers/block/mod.rs b/os7-ref/src/drivers/block/mod.rs new file mode 100644 index 0000000..e3a6345 --- /dev/null +++ b/os7-ref/src/drivers/block/mod.rs @@ -0,0 +1,24 @@ +mod virtio_blk; + +use lazy_static::*; +use alloc::sync::Arc; +use easy_fs::BlockDevice; +type BlockDeviceImpl = virtio_blk::VirtIOBlock; + +lazy_static! { + pub static ref BLOCK_DEVICE: Arc = Arc::new(BlockDeviceImpl::new()); +} + +#[allow(unused)] +pub fn block_device_test() { + let block_device = BLOCK_DEVICE.clone(); + let mut write_buffer = [0u8; 512]; + let mut read_buffer = [0u8; 512]; + for i in 0..512 { + for byte in write_buffer.iter_mut() { *byte = i as u8; } + block_device.write_block(i as usize, &write_buffer); + block_device.read_block(i as usize, &mut read_buffer); + assert_eq!(write_buffer, read_buffer); + } + println!("block device test passed!"); +} \ No newline at end of file diff --git a/os7-ref/src/drivers/block/virtio_blk.rs b/os7-ref/src/drivers/block/virtio_blk.rs new file mode 100644 index 0000000..c9956f5 --- /dev/null +++ b/os7-ref/src/drivers/block/virtio_blk.rs @@ -0,0 +1,84 @@ + +use virtio_drivers::{VirtIOBlk, VirtIOHeader}; +use crate::mm::{ + PhysAddr, + VirtAddr, + frame_alloc, + frame_dealloc, + PhysPageNum, + FrameTracker, + PageTable, + StepByOne, + kernel_token, +}; +use super::BlockDevice; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use lazy_static::*; + +#[allow(unused)] +const VIRTIO0: usize = 0x10001000; + +pub struct VirtIOBlock(UPSafeCell>); + +lazy_static! { + static ref QUEUE_FRAMES: UPSafeCell> = unsafe { + UPSafeCell::new(Vec::new()) + }; +} + +impl BlockDevice for VirtIOBlock { + fn read_block(&self, block_id: usize, buf: &mut [u8]) { + self.0.exclusive_access() + .read_block(block_id, buf) + .expect("Error when reading VirtIOBlk"); + } + fn write_block(&self, block_id: usize, buf: &[u8]) { + self.0.exclusive_access() + .write_block(block_id, buf) + .expect("Error when writing VirtIOBlk"); + } +} + +impl VirtIOBlock { + #[allow(unused)] + pub fn new() -> Self { + unsafe { + Self(UPSafeCell::new(VirtIOBlk::new( + &mut *(VIRTIO0 as *mut VirtIOHeader) + ).unwrap())) + } + } +} + +#[no_mangle] +pub extern "C" fn virtio_dma_alloc(pages: usize) -> PhysAddr { + let mut ppn_base = PhysPageNum(0); + for i in 0..pages { + let frame = frame_alloc().unwrap(); + if i == 0 { ppn_base = frame.ppn; } + assert_eq!(frame.ppn.0, ppn_base.0 + i); + QUEUE_FRAMES.exclusive_access().push(frame); + } + ppn_base.into() +} + +#[no_mangle] +pub extern "C" fn virtio_dma_dealloc(pa: PhysAddr, pages: usize) -> i32 { + let mut ppn_base: PhysPageNum = pa.into(); + for _ in 0..pages { + frame_dealloc(ppn_base); + ppn_base.step(); + } + 0 +} + +#[no_mangle] +pub extern "C" fn virtio_phys_to_virt(paddr: PhysAddr) -> VirtAddr { + VirtAddr(paddr.0) +} + +#[no_mangle] +pub extern "C" fn virtio_virt_to_phys(vaddr: VirtAddr) -> PhysAddr { + PageTable::from_token(kernel_token()).translate_va(vaddr).unwrap() +} diff --git a/os7-ref/src/drivers/mod.rs b/os7-ref/src/drivers/mod.rs new file mode 100644 index 0000000..43a6f54 --- /dev/null +++ b/os7-ref/src/drivers/mod.rs @@ -0,0 +1,3 @@ +mod block; + +pub use block::BLOCK_DEVICE; diff --git a/os7-ref/src/entry.asm b/os7-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os7-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os7-ref/src/fs/inode.rs b/os7-ref/src/fs/inode.rs new file mode 100644 index 0000000..5e4ca68 --- /dev/null +++ b/os7-ref/src/fs/inode.rs @@ -0,0 +1,169 @@ +use easy_fs::{ + EasyFileSystem, + Inode, +}; +use crate::drivers::BLOCK_DEVICE; +use crate::sync::UPSafeCell; +use alloc::sync::Arc; +use lazy_static::*; +use bitflags::*; +use alloc::vec::Vec; +use super::File; +use crate::mm::UserBuffer; + +/// A wrapper around a filesystem inode +/// to implement File trait atop +pub struct OSInode { + readable: bool, + writable: bool, + inner: UPSafeCell, +} + +/// The OS inode inner in 'UPSafeCell' +pub struct OSInodeInner { + offset: usize, + inode: Arc, +} + +impl OSInode { + /// Construct an OS inode from a inode + pub fn new( + readable: bool, + writable: bool, + inode: Arc, + ) -> Self { + Self { + readable, + writable, + inner: unsafe { UPSafeCell::new(OSInodeInner { + offset: 0, + inode, + })}, + } + } + /// Read all data inside a inode into vector + pub fn read_all(&self) -> Vec { + let mut inner = self.inner.exclusive_access(); + let mut buffer = [0u8; 512]; + let mut v: Vec = Vec::new(); + loop { + let len = inner.inode.read_at(inner.offset, &mut buffer); + if len == 0 { + break; + } + inner.offset += len; + v.extend_from_slice(&buffer[..len]); + } + v + } +} + +lazy_static! { + /// The root of all inodes, or '/' in short + pub static ref ROOT_INODE: Arc = { + let efs = EasyFileSystem::open(BLOCK_DEVICE.clone()); + Arc::new(EasyFileSystem::root_inode(&efs)) + }; +} + +/// List all files in the filesystems +pub fn list_apps() { + println!("/**** APPS ****"); + for app in ROOT_INODE.ls() { + println!("{}", app); + } + println!("**************/"); +} + +bitflags! { + /// Flags for opening files + pub struct OpenFlags: u32 { + const RDONLY = 0; + const WRONLY = 1 << 0; + const RDWR = 1 << 1; + const CREATE = 1 << 9; + const TRUNC = 1 << 10; + } +} + +impl OpenFlags { + /// Get the current read write permission on an inode + /// does not check validity for simplicity + /// returns (readable, writable) + pub fn read_write(&self) -> (bool, bool) { + if self.is_empty() { + (true, false) + } else if self.contains(Self::WRONLY) { + (false, true) + } else { + (true, true) + } + } +} + +/// Open a file by path +pub fn open_file(name: &str, flags: OpenFlags) -> Option> { + let (readable, writable) = flags.read_write(); + if flags.contains(OpenFlags::CREATE) { + if let Some(inode) = ROOT_INODE.find(name) { + // clear size + inode.clear(); + Some(Arc::new(OSInode::new( + readable, + writable, + inode, + ))) + } else { + // create file + ROOT_INODE.create(name) + .map(|inode| { + Arc::new(OSInode::new( + readable, + writable, + inode, + )) + }) + } + } else { + ROOT_INODE.find(name) + .map(|inode| { + if flags.contains(OpenFlags::TRUNC) { + inode.clear(); + } + Arc::new(OSInode::new( + readable, + writable, + inode + )) + }) + } +} + +impl File for OSInode { + fn readable(&self) -> bool { self.readable } + fn writable(&self) -> bool { self.writable } + fn read(&self, mut buf: UserBuffer) -> usize { + let mut inner = self.inner.exclusive_access(); + let mut total_read_size = 0usize; + for slice in buf.buffers.iter_mut() { + let read_size = inner.inode.read_at(inner.offset, *slice); + if read_size == 0 { + break; + } + inner.offset += read_size; + total_read_size += read_size; + } + total_read_size + } + fn write(&self, buf: UserBuffer) -> usize { + let mut inner = self.inner.exclusive_access(); + let mut total_write_size = 0usize; + for slice in buf.buffers.iter() { + let write_size = inner.inode.write_at(inner.offset, *slice); + assert_eq!(write_size, slice.len()); + inner.offset += write_size; + total_write_size += write_size; + } + total_write_size + } +} diff --git a/os7-ref/src/fs/mod.rs b/os7-ref/src/fs/mod.rs new file mode 100644 index 0000000..c14151e --- /dev/null +++ b/os7-ref/src/fs/mod.rs @@ -0,0 +1,45 @@ +mod stdio; +mod inode; +mod pipe; + +use crate::mm::UserBuffer; + +/// The common abstraction of all IO resources +pub trait File : Send + Sync { + fn readable(&self) -> bool; + fn writable(&self) -> bool; + fn read(&self, buf: UserBuffer) -> usize; + fn write(&self, buf: UserBuffer) -> usize; +} + +/// The stat of a inode +#[repr(C)] +#[derive(Debug)] +pub struct Stat { + /// ID of device containing file + pub dev: u64, + /// inode number + pub ino: u64, + /// file type and mode + pub mode: StatMode, + /// number of hard links + pub nlink: u32, + /// unused pad + pad: [u64; 7], +} + +bitflags! { + /// The mode of a inode + /// whether a directory or a file + pub struct StatMode: u32 { + const NULL = 0; + /// directory + const DIR = 0o040000; + /// ordinary regular file + const FILE = 0o100000; + } +} + +pub use stdio::{Stdin, Stdout}; +pub use inode::{OSInode, open_file, OpenFlags, list_apps}; +pub use pipe::{Pipe, make_pipe}; diff --git a/os7-ref/src/fs/pipe.rs b/os7-ref/src/fs/pipe.rs new file mode 100644 index 0000000..0827594 --- /dev/null +++ b/os7-ref/src/fs/pipe.rs @@ -0,0 +1,179 @@ +use super::File; +use alloc::sync::{Arc, Weak}; +use crate::sync::UPSafeCell; +use crate::mm::UserBuffer; + +use crate::task::suspend_current_and_run_next; + +/// One end of a pipe +pub struct Pipe { + readable: bool, + writable: bool, + buffer: Arc>, +} + +impl Pipe { + /// Create the read end of a pipe from a ring buffer + pub fn read_end_with_buffer(buffer: Arc>) -> Self { + Self { + readable: true, + writable: false, + buffer, + } + } + /// Create the write end of a pipe with a ring buffer + pub fn write_end_with_buffer(buffer: Arc>) -> Self { + Self { + readable: false, + writable: true, + buffer, + } + } +} + +const RING_BUFFER_SIZE: usize = 32; + +#[derive(Copy, Clone, PartialEq)] +enum RingBufferStatus { + FULL, + EMPTY, + NORMAL, +} + +/// The underlying ring buffer of a pipe +pub struct PipeRingBuffer { + arr: [u8; RING_BUFFER_SIZE], + head: usize, + tail: usize, + status: RingBufferStatus, + write_end: Option>, +} + +impl PipeRingBuffer { + pub fn new() -> Self { + Self { + arr: [0; RING_BUFFER_SIZE], + head: 0, + tail: 0, + status: RingBufferStatus::EMPTY, + write_end: None, + } + } + /// Set the write end bound to this buffer + pub fn set_write_end(&mut self, write_end: &Arc) { + self.write_end = Some(Arc::downgrade(write_end)); + } + /// Write into the buffer + pub fn write_byte(&mut self, byte: u8) { + self.status = RingBufferStatus::NORMAL; + self.arr[self.tail] = byte; + self.tail = (self.tail + 1) % RING_BUFFER_SIZE; + if self.tail == self.head { + self.status = RingBufferStatus::FULL; + } + } + /// Read from the buffer + pub fn read_byte(&mut self) -> u8 { + self.status = RingBufferStatus::NORMAL; + let c = self.arr[self.head]; + self.head = (self.head + 1) % RING_BUFFER_SIZE; + if self.head == self.tail { + self.status = RingBufferStatus::EMPTY; + } + c + } + /// Get the length of remaining data in the buffer + pub fn available_read(&self) -> usize { + if self.status == RingBufferStatus::EMPTY { + 0 + } else { + if self.tail > self.head { + self.tail - self.head + } else { + self.tail + RING_BUFFER_SIZE - self.head + } + } + } + /// Get the length of remaining space in the buffer + pub fn available_write(&self) -> usize { + if self.status == RingBufferStatus::FULL { + 0 + } else { + RING_BUFFER_SIZE - self.available_read() + } + } + /// Check if all write ends bounded to this buffer are closed + pub fn all_write_ends_closed(&self) -> bool { + self.write_end.as_ref().unwrap().upgrade().is_none() + } +} + +/// Crate a pipe +/// return (read_end, write_end) +pub fn make_pipe() -> (Arc, Arc) { + let buffer = Arc::new(unsafe { + UPSafeCell::new(PipeRingBuffer::new()) + }); + let read_end = Arc::new( + Pipe::read_end_with_buffer(buffer.clone()) + ); + let write_end = Arc::new( + Pipe::write_end_with_buffer(buffer.clone()) + ); + buffer.exclusive_access().set_write_end(&write_end); + (read_end, write_end) +} + +impl File for Pipe { + fn readable(&self) -> bool { self.readable } + fn writable(&self) -> bool { self.writable } + fn read(&self, buf: UserBuffer) -> usize { + assert_eq!(self.readable(), true); + let mut buf_iter = buf.into_iter(); + let mut read_size = 0usize; + loop { + let mut ring_buffer = self.buffer.exclusive_access(); + let loop_read = ring_buffer.available_read(); + if loop_read == 0 { + if ring_buffer.all_write_ends_closed() { + return read_size; + } + drop(ring_buffer); + suspend_current_and_run_next(); + continue; + } + // read at most loop_read bytes + for _ in 0..loop_read { + if let Some(byte_ref) = buf_iter.next() { + unsafe { *byte_ref = ring_buffer.read_byte(); } + read_size += 1; + } else { + return read_size; + } + } + } + } + fn write(&self, buf: UserBuffer) -> usize { + assert_eq!(self.writable(), true); + let mut buf_iter = buf.into_iter(); + let mut write_size = 0usize; + loop { + let mut ring_buffer = self.buffer.exclusive_access(); + let loop_write = ring_buffer.available_write(); + if loop_write == 0 { + drop(ring_buffer); + suspend_current_and_run_next(); + continue; + } + // write at most loop_write bytes + for _ in 0..loop_write { + if let Some(byte_ref) = buf_iter.next() { + ring_buffer.write_byte(unsafe { *byte_ref }); + write_size += 1; + } else { + return write_size; + } + } + } + } +} diff --git a/os7-ref/src/fs/stdio.rs b/os7-ref/src/fs/stdio.rs new file mode 100644 index 0000000..87dca0e --- /dev/null +++ b/os7-ref/src/fs/stdio.rs @@ -0,0 +1,48 @@ +use super::File; +use crate::mm::{UserBuffer}; +use crate::sbi::console_getchar; +use crate::task::suspend_current_and_run_next; + +/// The standard input +pub struct Stdin; +/// The standard output +pub struct Stdout; + +impl File for Stdin { + fn readable(&self) -> bool { true } + fn writable(&self) -> bool { false } + fn read(&self, mut user_buf: UserBuffer) -> usize { + assert_eq!(user_buf.len(), 1); + // busy loop + let mut c: usize; + loop { + c = console_getchar(); + if c == 0 { + suspend_current_and_run_next(); + continue; + } else { + break; + } + } + let ch = c as u8; + unsafe { user_buf.buffers[0].as_mut_ptr().write_volatile(ch); } + 1 + } + fn write(&self, _user_buf: UserBuffer) -> usize { + panic!("Cannot write to stdin!"); + } +} + +impl File for Stdout { + fn readable(&self) -> bool { false } + fn writable(&self) -> bool { true } + fn read(&self, _user_buf: UserBuffer) -> usize{ + panic!("Cannot read from stdout!"); + } + fn write(&self, user_buf: UserBuffer) -> usize { + for buffer in user_buf.buffers.iter() { + print!("{}", core::str::from_utf8(*buffer).unwrap()); + } + user_buf.len() + } +} diff --git a/os7-ref/src/lang_items.rs b/os7-ref/src/lang_items.rs new file mode 100644 index 0000000..e52afff --- /dev/null +++ b/os7-ref/src/lang_items.rs @@ -0,0 +1,29 @@ +//! The panic handler + +use crate::console::ANSICON; +use crate::sbi::shutdown; + +use core::panic::PanicInfo; + +#[panic_handler] +/// panic handler +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println_colorized!( + "[kernel] Panicked at {}:{} {}", + ANSICON::FgRed, + ANSICON::BgDefault, + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println_colorized!( + "[kernel] Panicked: {}", + ANSICON::FgRed, + ANSICON::BgDefault, + info.message().unwrap() + ); + } + shutdown() +} diff --git a/os7-ref/src/linker.ld b/os7-ref/src/linker.ld new file mode 100644 index 0000000..5baafbd --- /dev/null +++ b/os7-ref/src/linker.ld @@ -0,0 +1,53 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + . = ALIGN(4K); + strampoline = .; + *(.text.trampoline); + . = ALIGN(4K); + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + sbss_with_stack = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os7-ref/src/logging.rs b/os7-ref/src/logging.rs new file mode 100644 index 0000000..e12448e --- /dev/null +++ b/os7-ref/src/logging.rs @@ -0,0 +1,45 @@ +//! Global logger + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +/// a simple logger +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +/// initiate logger +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os7-ref/src/main.rs b/os7-ref/src/main.rs new file mode 100644 index 0000000..8036bca --- /dev/null +++ b/os7-ref/src/main.rs @@ -0,0 +1,74 @@ +//! The main module and entrypoint +//! +//! Various facilities of the kernels are implemented as submodules. The most +//! important ones are: +//! +//! - [`trap`]: Handles all cases of switching from userspace to the kernel +//! - [`task`]: Task management +//! - [`syscall`]: System call handling and implementation +//! +//! The operating system also starts in this module. Kernel code starts +//! executing from `entry.asm`, after which [`rust_main()`] is called to +//! initialize various pieces of functionality. (See its source code for +//! details.) +//! +//! We then call [`task::run_first_task()`] and for the first time go to +//! userspace. + +#![no_std] +#![no_main] +#![feature(panic_info_message)] +#![feature(alloc_error_handler)] + +#[macro_use] +extern crate bitflags; +#[macro_use] +extern crate log; + +extern crate alloc; + +#[macro_use] +mod console; +mod config; +mod lang_items; +mod logging; +mod mm; +mod sbi; +mod sync; +mod syscall; +mod task; +mod timer; +mod trap; +mod drivers; +mod fs; + +core::arch::global_asm!(include_str!("entry.asm")); + +/// clear BSS segment +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +/// the rust entry-point of os +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + mm::init(); + mm::remap_test(); + trap::init(); + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + fs::list_apps(); + task::add_initproc(); + task::run_tasks(); + panic!("Unreachable in rust_main!"); +} diff --git a/os7-ref/src/mm/address.rs b/os7-ref/src/mm/address.rs new file mode 100644 index 0000000..5c24ae7 --- /dev/null +++ b/os7-ref/src/mm/address.rs @@ -0,0 +1,259 @@ +//! Implementation of physical and virtual address and page number. +use super::PageTableEntry; +use crate::config::{PAGE_SIZE, PAGE_SIZE_BITS}; +use core::fmt::{self, Debug, Formatter}; + +/// Definitions +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysAddr(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtAddr(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysPageNum(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtPageNum(pub usize); + +/// Debugging + +impl Debug for VirtAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VA:{:#x}", self.0)) + } +} +impl Debug for VirtPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VPN:{:#x}", self.0)) + } +} +impl Debug for PhysAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PA:{:#x}", self.0)) + } +} +impl Debug for PhysPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PPN:{:#x}", self.0)) + } +} + +/// T: {PhysAddr, VirtAddr, PhysPageNum, VirtPageNum} +/// T -> usize: T.0 +/// usize -> T: usize.into() + +impl From for PhysAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for PhysPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for usize { + fn from(v: PhysAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: PhysPageNum) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtPageNum) -> Self { + v.0 + } +} + +impl VirtAddr { + pub fn floor(&self) -> VirtPageNum { + VirtPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> VirtPageNum { + VirtPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for VirtPageNum { + fn from(v: VirtAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for VirtAddr { + fn from(v: VirtPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} +impl PhysAddr { + pub fn floor(&self) -> PhysPageNum { + PhysPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> PhysPageNum { + PhysPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for PhysPageNum { + fn from(v: PhysAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for PhysAddr { + fn from(v: PhysPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} + +impl VirtPageNum { + pub fn indexes(&self) -> [usize; 3] { + let mut vpn = self.0; + let mut idx = [0usize; 3]; + for i in (0..3).rev() { + idx[i] = vpn & 511; + vpn >>= 9; + } + idx + } +} + +impl PhysAddr { + pub fn get_ref(&self) -> &'static T { + unsafe { (self.0 as *const T).as_ref().unwrap() } + } + pub fn get_mut(&self) -> &'static mut T { + unsafe { (self.0 as *mut T).as_mut().unwrap() } + } +} +impl PhysPageNum { + pub fn get_pte_array(&self) -> &'static mut [PageTableEntry] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut PageTableEntry, 512) } + } + pub fn get_bytes_array(&self) -> &'static mut [u8] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut u8, 4096) } + } + pub fn get_mut(&self) -> &'static mut T { + let pa: PhysAddr = (*self).into(); + pa.get_mut() + } +} + +pub trait StepByOne { + fn step(&mut self); +} +impl StepByOne for VirtPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +impl StepByOne for PhysPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +#[derive(Copy, Clone)] +/// a simple range structure for type T +pub struct SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + l: T, + r: T, +} +impl SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(start: T, end: T) -> Self { + assert!(start <= end, "start {:?} > end {:?}!", start, end); + Self { l: start, r: end } + } + pub fn get_start(&self) -> T { + self.l + } + pub fn get_end(&self) -> T { + self.r + } +} +impl IntoIterator for SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + type IntoIter = SimpleRangeIterator; + fn into_iter(self) -> Self::IntoIter { + SimpleRangeIterator::new(self.l, self.r) + } +} +/// iterator for the simple range structure +pub struct SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + current: T, + end: T, +} +impl SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(l: T, r: T) -> Self { + Self { current: l, end: r } + } +} +impl Iterator for SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + fn next(&mut self) -> Option { + if self.current == self.end { + None + } else { + let t = self.current; + self.current.step(); + Some(t) + } + } +} + +/// a simple range structure for virtual page number +pub type VPNRange = SimpleRange; diff --git a/os7-ref/src/mm/frame_allocator.rs b/os7-ref/src/mm/frame_allocator.rs new file mode 100644 index 0000000..ab1ed57 --- /dev/null +++ b/os7-ref/src/mm/frame_allocator.rs @@ -0,0 +1,136 @@ +//! Implementation of [`FrameAllocator`] which +//! controls all the frames in the operating system. + +use super::{PhysAddr, PhysPageNum}; +use crate::config::MEMORY_END; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use core::fmt::{self, Debug, Formatter}; +use lazy_static::*; + +/// manage a frame which has the same lifecycle as the tracker +pub struct FrameTracker { + pub ppn: PhysPageNum, +} + +impl FrameTracker { + pub fn new(ppn: PhysPageNum) -> Self { + // page cleaning + let bytes_array = ppn.get_bytes_array(); + for i in bytes_array { + *i = 0; + } + Self { ppn } + } +} + +impl Debug for FrameTracker { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("FrameTracker:PPN={:#x}", self.ppn.0)) + } +} + +impl Drop for FrameTracker { + fn drop(&mut self) { + frame_dealloc(self.ppn); + } +} + +trait FrameAllocator { + fn new() -> Self; + fn alloc(&mut self) -> Option; + fn dealloc(&mut self, ppn: PhysPageNum); +} + +/// an implementation for frame allocator +pub struct StackFrameAllocator { + current: usize, + end: usize, + recycled: Vec, +} + +impl StackFrameAllocator { + pub fn init(&mut self, l: PhysPageNum, r: PhysPageNum) { + self.current = l.0; + self.end = r.0; + info!("last {} Physical Frames.", self.end - self.current); + } +} +impl FrameAllocator for StackFrameAllocator { + fn new() -> Self { + Self { + current: 0, + end: 0, + recycled: Vec::new(), + } + } + fn alloc(&mut self) -> Option { + if let Some(ppn) = self.recycled.pop() { + Some(ppn.into()) + } else if self.current == self.end { + None + } else { + self.current += 1; + Some((self.current - 1).into()) + } + } + fn dealloc(&mut self, ppn: PhysPageNum) { + let ppn = ppn.0; + // validity check + if ppn >= self.current || self.recycled.iter().any(|v| *v == ppn) { + panic!("Frame ppn={:#x} has not been allocated!", ppn); + } + // recycle + self.recycled.push(ppn); + } +} + +type FrameAllocatorImpl = StackFrameAllocator; + +lazy_static! { + /// frame allocator instance through lazy_static! + pub static ref FRAME_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(FrameAllocatorImpl::new()) }; +} + +pub fn init_frame_allocator() { + extern "C" { + fn ekernel(); + } + FRAME_ALLOCATOR.exclusive_access().init( + PhysAddr::from(ekernel as usize).ceil(), + PhysAddr::from(MEMORY_END).floor(), + ); +} + +/// initiate the frame allocator using `ekernel` and `MEMORY_END` +pub fn frame_alloc() -> Option { + FRAME_ALLOCATOR + .exclusive_access() + .alloc() + .map(FrameTracker::new) +} + +/// deallocate a frame +pub fn frame_dealloc(ppn: PhysPageNum) { + FRAME_ALLOCATOR.exclusive_access().dealloc(ppn); +} + +#[allow(unused)] +/// a simple test for frame allocator +pub fn frame_allocator_test() { + let mut v: Vec = Vec::new(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + v.clear(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + drop(v); + info!("frame_allocator_test passed!"); +} diff --git a/os7-ref/src/mm/heap_allocator.rs b/os7-ref/src/mm/heap_allocator.rs new file mode 100644 index 0000000..d518fae --- /dev/null +++ b/os7-ref/src/mm/heap_allocator.rs @@ -0,0 +1,51 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[allow(unused)] +pub fn heap_test() { + use alloc::boxed::Box; + use alloc::vec::Vec; + extern "C" { + fn sbss(); + fn ebss(); + } + let bss_range = sbss as usize..ebss as usize; + let a = Box::new(5); + assert_eq!(*a, 5); + assert!(bss_range.contains(&(a.as_ref() as *const _ as usize))); + drop(a); + let mut v: Vec = Vec::new(); + for i in 0..500 { + v.push(i); + } + for (i, vi) in v.iter().enumerate().take(500) { + assert_eq!(*vi, i); + } + assert!(bss_range.contains(&(v.as_ptr() as usize))); + drop(v); + info!("heap_test passed!"); +} diff --git a/os7-ref/src/mm/memory_set.rs b/os7-ref/src/mm/memory_set.rs new file mode 100644 index 0000000..44cf097 --- /dev/null +++ b/os7-ref/src/mm/memory_set.rs @@ -0,0 +1,404 @@ +//! Implementation of [`MapArea`] and [`MemorySet`]. + +use super::{frame_alloc, FrameTracker}; +use super::{PTEFlags, PageTable, PageTableEntry}; +use super::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use super::{StepByOne, VPNRange}; +use crate::config::{MEMORY_END, PAGE_SIZE, TRAMPOLINE, TRAP_CONTEXT, USER_STACK_SIZE, MMIO}; +use crate::sync::UPSafeCell; +use alloc::collections::BTreeMap; +use alloc::sync::Arc; +use alloc::vec::Vec; +use lazy_static::*; +use riscv::register::satp; + +extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss_with_stack(); + fn ebss(); + fn ekernel(); + fn strampoline(); +} + +lazy_static! { + /// a memory set instance through lazy_static! managing kernel space + pub static ref KERNEL_SPACE: Arc> = + Arc::new(unsafe { UPSafeCell::new(MemorySet::new_kernel()) }); +} + +/// Get the token of the kernel memory space +pub fn kernel_token() -> usize { + KERNEL_SPACE.exclusive_access().token() +} + +/// memory set structure, controls virtual-memory space +pub struct MemorySet { + page_table: PageTable, + areas: Vec, +} + +impl MemorySet { + pub fn new_bare() -> Self { + Self { + page_table: PageTable::new(), + areas: Vec::new(), + } + } + pub fn token(&self) -> usize { + self.page_table.token() + } + /// Assume that no conflicts. + pub fn insert_framed_area( + &mut self, + start_va: VirtAddr, + end_va: VirtAddr, + permission: MapPermission, + ) { + self.push( + MapArea::new(start_va, end_va, MapType::Framed, permission), + None, + ); + } + pub fn remove_area_with_start_vpn(&mut self, start_vpn: VirtPageNum) { + if let Some((idx, area)) = self + .areas + .iter_mut() + .enumerate() + .find(|(_, area)| area.vpn_range.get_start() == start_vpn) + { + area.unmap(&mut self.page_table); + self.areas.remove(idx); + } + } + fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) { + map_area.map(&mut self.page_table); + if let Some(data) = data { + map_area.copy_data(&mut self.page_table, data); + } + self.areas.push(map_area); + } + /// Mention that trampoline is not collected by areas. + fn map_trampoline(&mut self) { + self.page_table.map( + VirtAddr::from(TRAMPOLINE).into(), + PhysAddr::from(strampoline as usize).into(), + PTEFlags::R | PTEFlags::X, + ); + } + /// Without kernel stacks. + pub fn new_kernel() -> Self { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map kernel sections + info!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + info!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + info!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + info!( + ".bss [{:#x}, {:#x})", + sbss_with_stack as usize, ebss as usize + ); + info!("mapping .text section"); + memory_set.push( + MapArea::new( + (stext as usize).into(), + (etext as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::X, + ), + None, + ); + info!("mapping .rodata section"); + memory_set.push( + MapArea::new( + (srodata as usize).into(), + (erodata as usize).into(), + MapType::Identical, + MapPermission::R, + ), + None, + ); + info!("mapping .data section"); + memory_set.push( + MapArea::new( + (sdata as usize).into(), + (edata as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping .bss section"); + memory_set.push( + MapArea::new( + (sbss_with_stack as usize).into(), + (ebss as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping physical memory"); + memory_set.push( + MapArea::new( + (ekernel as usize).into(), + MEMORY_END.into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping memory-mapped registers"); + for pair in MMIO { + memory_set.push( + MapArea::new( + (*pair).0.into(), + ((*pair).0 + (*pair).1).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None); + } + memory_set + } + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map program headers of elf, with U flag + let elf = xmas_elf::ElfFile::new(elf_data).unwrap(); + let elf_header = elf.header; + let magic = elf_header.pt1.magic; + assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!"); + let ph_count = elf_header.pt2.ph_count(); + let mut max_end_vpn = VirtPageNum(0); + for i in 0..ph_count { + let ph = elf.program_header(i).unwrap(); + if ph.get_type().unwrap() == xmas_elf::program::Type::Load { + let start_va: VirtAddr = (ph.virtual_addr() as usize).into(); + let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into(); + let mut map_perm = MapPermission::U; + let ph_flags = ph.flags(); + if ph_flags.is_read() { + map_perm |= MapPermission::R; + } + if ph_flags.is_write() { + map_perm |= MapPermission::W; + } + if ph_flags.is_execute() { + map_perm |= MapPermission::X; + } + let map_area = MapArea::new(start_va, end_va, MapType::Framed, map_perm); + max_end_vpn = map_area.vpn_range.get_end(); + memory_set.push( + map_area, + Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]), + ); + } + } + // map user stack with U flags + let max_end_va: VirtAddr = max_end_vpn.into(); + let mut user_stack_bottom: usize = max_end_va.into(); + // guard page + user_stack_bottom += PAGE_SIZE; + let user_stack_top = user_stack_bottom + USER_STACK_SIZE; + memory_set.push( + MapArea::new( + user_stack_bottom.into(), + user_stack_top.into(), + MapType::Framed, + MapPermission::R | MapPermission::W | MapPermission::U, + ), + None, + ); + // map TrapContext + memory_set.push( + MapArea::new( + TRAP_CONTEXT.into(), + TRAMPOLINE.into(), + MapType::Framed, + MapPermission::R | MapPermission::W, + ), + None, + ); + ( + memory_set, + user_stack_top, + elf.header.pt2.entry_point() as usize, + ) + } + /// Copy an identical user_space + pub fn from_existed_user(user_space: &MemorySet) -> MemorySet { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // copy data sections/trap_context/user_stack + for area in user_space.areas.iter() { + let new_area = MapArea::from_another(area); + memory_set.push(new_area, None); + // copy data from another space + for vpn in area.vpn_range { + let src_ppn = user_space.translate(vpn).unwrap().ppn(); + let dst_ppn = memory_set.translate(vpn).unwrap().ppn(); + dst_ppn + .get_bytes_array() + .copy_from_slice(src_ppn.get_bytes_array()); + } + } + memory_set + } + pub fn activate(&self) { + let satp = self.page_table.token(); + unsafe { + satp::write(satp); + core::arch::asm!("sfence.vma"); + } + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.page_table.translate(vpn) + } + pub fn recycle_data_pages(&mut self) { + //*self = Self::new_bare(); + self.areas.clear(); + } +} + +/// map area structure, controls a contiguous piece of virtual memory +pub struct MapArea { + vpn_range: VPNRange, + data_frames: BTreeMap, + map_type: MapType, + map_perm: MapPermission, +} + +impl MapArea { + pub fn new( + start_va: VirtAddr, + end_va: VirtAddr, + map_type: MapType, + map_perm: MapPermission, + ) -> Self { + let start_vpn: VirtPageNum = start_va.floor(); + let end_vpn: VirtPageNum = end_va.ceil(); + Self { + vpn_range: VPNRange::new(start_vpn, end_vpn), + data_frames: BTreeMap::new(), + map_type, + map_perm, + } + } + pub fn from_another(another: &MapArea) -> Self { + Self { + vpn_range: VPNRange::new(another.vpn_range.get_start(), another.vpn_range.get_end()), + data_frames: BTreeMap::new(), + map_type: another.map_type, + map_perm: another.map_perm, + } + } + pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + let ppn: PhysPageNum; + match self.map_type { + MapType::Identical => { + ppn = PhysPageNum(vpn.0); + } + MapType::Framed => { + let frame = frame_alloc().unwrap(); + ppn = frame.ppn; + self.data_frames.insert(vpn, frame); + } + } + let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap(); + page_table.map(vpn, ppn, pte_flags); + } + + pub fn unmap_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + #[allow(clippy::single_match)] + match self.map_type { + MapType::Framed => { + self.data_frames.remove(&vpn); + } + _ => {} + } + page_table.unmap(vpn); + } + pub fn map(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.map_one(page_table, vpn); + } + } + pub fn unmap(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.unmap_one(page_table, vpn); + } + } + /// data: start-aligned but maybe with shorter length + /// assume that all frames were cleared before + pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) { + assert_eq!(self.map_type, MapType::Framed); + let mut start: usize = 0; + let mut current_vpn = self.vpn_range.get_start(); + let len = data.len(); + loop { + let src = &data[start..len.min(start + PAGE_SIZE)]; + let dst = &mut page_table + .translate(current_vpn) + .unwrap() + .ppn() + .get_bytes_array()[..src.len()]; + dst.copy_from_slice(src); + start += PAGE_SIZE; + if start >= len { + break; + } + current_vpn.step(); + } + } +} + +#[derive(Copy, Clone, PartialEq, Debug)] +/// map type for memory set: identical or framed +pub enum MapType { + Identical, + Framed, +} + +bitflags! { + /// map permission corresponding to that in pte: `R W X U` + pub struct MapPermission: u8 { + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + } +} + +#[allow(unused)] +pub fn remap_test() { + let mut kernel_space = KERNEL_SPACE.exclusive_access(); + let mid_text: VirtAddr = ((stext as usize + etext as usize) / 2).into(); + let mid_rodata: VirtAddr = ((srodata as usize + erodata as usize) / 2).into(); + let mid_data: VirtAddr = ((sdata as usize + edata as usize) / 2).into(); + assert!(!kernel_space + .page_table + .translate(mid_text.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_rodata.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_data.floor()) + .unwrap() + .executable()); + info!("remap_test passed!"); +} diff --git a/os7-ref/src/mm/mod.rs b/os7-ref/src/mm/mod.rs new file mode 100644 index 0000000..211cc2f --- /dev/null +++ b/os7-ref/src/mm/mod.rs @@ -0,0 +1,29 @@ +//! Memory management implementation +//! +//! SV39 page-based virtual-memory architecture for RV64 systems, and +//! everything about memory management, like frame allocator, page table, +//! map area and memory set, is implemented here. +//! +//! Every task or process has a memory_set to control its virtual memory. + + +mod address; +mod frame_allocator; +mod heap_allocator; +mod memory_set; +mod page_table; + +pub use address::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +pub use address::{StepByOne, VPNRange}; +pub use frame_allocator::{frame_alloc, frame_dealloc, FrameTracker}; +pub use memory_set::{remap_test, kernel_token}; +pub use memory_set::{MapPermission, MemorySet, KERNEL_SPACE}; +pub use page_table::{translated_byte_buffer, translated_refmut, translated_ref, translated_str, PageTableEntry}; +pub use page_table::{PTEFlags, PageTable, UserBuffer}; + +/// initiate heap allocator, frame allocator and kernel space +pub fn init() { + heap_allocator::init_heap(); + frame_allocator::init_frame_allocator(); + KERNEL_SPACE.exclusive_access().activate(); +} diff --git a/os7-ref/src/mm/page_table.rs b/os7-ref/src/mm/page_table.rs new file mode 100644 index 0000000..dbb195a --- /dev/null +++ b/os7-ref/src/mm/page_table.rs @@ -0,0 +1,260 @@ +//! Implementation of [`PageTableEntry`] and [`PageTable`]. + +use super::{frame_alloc, FrameTracker, PhysAddr, PhysPageNum, StepByOne, VirtAddr, VirtPageNum}; +use alloc::string::String; +use alloc::vec; +use alloc::vec::Vec; +use bitflags::*; + +bitflags! { + /// page table entry flags + pub struct PTEFlags: u8 { + const V = 1 << 0; + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + const G = 1 << 5; + const A = 1 << 6; + const D = 1 << 7; + } +} + +#[derive(Copy, Clone)] +#[repr(C)] +/// page table entry structure +pub struct PageTableEntry { + pub bits: usize, +} + +impl PageTableEntry { + pub fn new(ppn: PhysPageNum, flags: PTEFlags) -> Self { + PageTableEntry { + bits: ppn.0 << 10 | flags.bits as usize, + } + } + pub fn empty() -> Self { + PageTableEntry { bits: 0 } + } + pub fn ppn(&self) -> PhysPageNum { + (self.bits >> 10 & ((1usize << 44) - 1)).into() + } + pub fn flags(&self) -> PTEFlags { + PTEFlags::from_bits(self.bits as u8).unwrap() + } + pub fn is_valid(&self) -> bool { + (self.flags() & PTEFlags::V) != PTEFlags::empty() + } + pub fn readable(&self) -> bool { + (self.flags() & PTEFlags::R) != PTEFlags::empty() + } + pub fn writable(&self) -> bool { + (self.flags() & PTEFlags::W) != PTEFlags::empty() + } + pub fn executable(&self) -> bool { + (self.flags() & PTEFlags::X) != PTEFlags::empty() + } +} + +/// page table structure +pub struct PageTable { + root_ppn: PhysPageNum, + frames: Vec, +} + +/// Assume that it won't oom when creating/mapping. +impl PageTable { + pub fn new() -> Self { + let frame = frame_alloc().unwrap(); + PageTable { + root_ppn: frame.ppn, + frames: vec![frame], + } + } + /// Temporarily used to get arguments from user space. + pub fn from_token(satp: usize) -> Self { + Self { + root_ppn: PhysPageNum::from(satp & ((1usize << 44) - 1)), + frames: Vec::new(), + } + } + fn find_pte_create(&mut self, vpn: VirtPageNum) -> Option<&mut PageTableEntry> { + let mut idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&mut PageTableEntry> = None; + for (i, idx) in idxs.iter_mut().enumerate() { + let pte = &mut ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + let frame = frame_alloc().unwrap(); + *pte = PageTableEntry::new(frame.ppn, PTEFlags::V); + self.frames.push(frame); + } + ppn = pte.ppn(); + } + result + } + fn find_pte(&self, vpn: VirtPageNum) -> Option<&PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&PageTableEntry> = None; + for (i, idx) in idxs.iter().enumerate() { + let pte = &ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + return None; + } + ppn = pte.ppn(); + } + result + } + #[allow(unused)] + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(!pte.is_valid(), "vpn {:?} is mapped before mapping", vpn); + *pte = PageTableEntry::new(ppn, flags | PTEFlags::V); + } + #[allow(unused)] + pub fn unmap(&mut self, vpn: VirtPageNum) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(pte.is_valid(), "vpn {:?} is invalid before unmapping", vpn); + *pte = PageTableEntry::empty(); + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.find_pte(vpn).copied() + } + pub fn translate_va(&self, va: VirtAddr) -> Option { + self.find_pte(va.clone().floor()).map(|pte| { + //println!("translate_va:va = {:?}", va); + let aligned_pa: PhysAddr = pte.ppn().into(); + //println!("translate_va:pa_align = {:?}", aligned_pa); + let offset = va.page_offset(); + let aligned_pa_usize: usize = aligned_pa.into(); + (aligned_pa_usize + offset).into() + }) + } + pub fn token(&self) -> usize { + 8usize << 60 | self.root_ppn.0 + } +} + +/// translate a pointer to a mutable u8 Vec through page table +pub fn translated_byte_buffer(token: usize, ptr: *const u8, len: usize) -> Vec<&'static mut [u8]> { + let page_table = PageTable::from_token(token); + let mut start = ptr as usize; + let end = start + len; + let mut v = Vec::new(); + while start < end { + let start_va = VirtAddr::from(start); + let mut vpn = start_va.floor(); + let ppn = page_table.translate(vpn).unwrap().ppn(); + vpn.step(); + let mut end_va: VirtAddr = vpn.into(); + end_va = end_va.min(VirtAddr::from(end)); + if end_va.page_offset() == 0 { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..]); + } else { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..end_va.page_offset()]); + } + start = end_va.into(); + } + v +} + +pub fn translated_str(token: usize, ptr: *const u8) -> String { + let page_table = PageTable::from_token(token); + let mut string = String::new(); + let mut va = ptr as usize; + loop { + let ch: u8 = *(page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut()); + if ch == 0 { + break; + } else { + string.push(ch as char); + va += 1; + } + } + string +} + +pub fn translated_ref(token: usize, ptr: *const T) -> &'static T { + let page_table = PageTable::from_token(token); + page_table.translate_va(VirtAddr::from(ptr as usize)).unwrap().get_mut() +} + +pub fn translated_refmut(token: usize, ptr: *mut T) -> &'static mut T { + //println!("into translated_refmut!"); + let page_table = PageTable::from_token(token); + let va = ptr as usize; + //println!("translated_refmut: before translate_va"); + page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut() +} + +/// An abstraction over a buffer passed from user space to kernel space +pub struct UserBuffer { + pub buffers: Vec<&'static mut [u8]>, +} + +impl UserBuffer { + /// Constuct a UserBuffer + pub fn new(buffers: Vec<&'static mut [u8]>) -> Self { + Self { buffers } + } + /// Get the length of a UserBuffer + pub fn len(&self) -> usize { + let mut total: usize = 0; + for b in self.buffers.iter() { + total += b.len(); + } + total + } +} + +impl IntoIterator for UserBuffer { + type Item = *mut u8; + type IntoIter = UserBufferIterator; + fn into_iter(self) -> Self::IntoIter { + UserBufferIterator { + buffers: self.buffers, + current_buffer: 0, + current_idx: 0, + } + } +} + +// An iterator over a UserBuffer +pub struct UserBufferIterator { + buffers: Vec<&'static mut [u8]>, + current_buffer: usize, + current_idx: usize, +} + +impl Iterator for UserBufferIterator { + type Item = *mut u8; + fn next(&mut self) -> Option { + if self.current_buffer >= self.buffers.len() { + None + } else { + let r = &mut self.buffers[self.current_buffer][self.current_idx] as *mut _; + if self.current_idx + 1 == self.buffers[self.current_buffer].len() { + self.current_idx = 0; + self.current_buffer += 1; + } else { + self.current_idx += 1; + } + Some(r) + } + } +} diff --git a/os7-ref/src/sbi.rs b/os7-ref/src/sbi.rs new file mode 100644 index 0000000..4af7620 --- /dev/null +++ b/os7-ref/src/sbi.rs @@ -0,0 +1,45 @@ +//! SBI call wrappers + +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +/// general sbi call +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +/// use sbi call to set timer +pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); +} + +/// use sbi call to putchar in console (qemu uart handler) +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +/// use sbi call to getchar from console (qemu uart handler) +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +/// use sbi call to shutdown the kernel +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os7-ref/src/sync/mod.rs b/os7-ref/src/sync/mod.rs new file mode 100644 index 0000000..4743e31 --- /dev/null +++ b/os7-ref/src/sync/mod.rs @@ -0,0 +1,5 @@ +//! Synchronization and interior mutability primitives + +mod up; + +pub use up::UPSafeCell; diff --git a/os7-ref/src/sync/up.rs b/os7-ref/src/sync/up.rs new file mode 100644 index 0000000..039b039 --- /dev/null +++ b/os7-ref/src/sync/up.rs @@ -0,0 +1,31 @@ +//! Uniprocessor interior mutability primitives + +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os7-ref/src/syscall/fs.rs b/os7-ref/src/syscall/fs.rs new file mode 100644 index 0000000..d3def22 --- /dev/null +++ b/os7-ref/src/syscall/fs.rs @@ -0,0 +1,122 @@ +//! File and filesystem-related syscalls + +use crate::mm::translated_byte_buffer; +use crate::mm::translated_str; +use crate::mm::translated_refmut; +use crate::task::current_user_token; +use crate::task::current_task; +use crate::fs::open_file; +use crate::fs::OpenFlags; +use crate::fs::Stat; +use crate::fs::make_pipe; +use crate::mm::UserBuffer; +use alloc::sync::Arc; + +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let task = current_task().unwrap(); + let inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release current task TCB manually to avoid multi-borrow + drop(inner); + file.write( + UserBuffer::new(translated_byte_buffer(token, buf, len)) + ) as isize + } else { + -1 + } +} + +pub fn sys_read(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let task = current_task().unwrap(); + let inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release current task TCB manually to avoid multi-borrow + drop(inner); + file.read( + UserBuffer::new(translated_byte_buffer(token, buf, len)) + ) as isize + } else { + -1 + } +} + +pub fn sys_open(path: *const u8, flags: u32) -> isize { + let task = current_task().unwrap(); + let token = current_user_token(); + let path = translated_str(token, path); + if let Some(inode) = open_file( + path.as_str(), + OpenFlags::from_bits(flags).unwrap() + ) { + let mut inner = task.inner_exclusive_access(); + let fd = inner.alloc_fd(); + inner.fd_table[fd] = Some(inode); + fd as isize + } else { + -1 + } +} + +pub fn sys_close(fd: usize) -> isize { + let task = current_task().unwrap(); + let mut inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + inner.fd_table[fd].take(); + 0 +} + +pub fn sys_pipe(pipe: *mut usize) -> isize { + let task = current_task().unwrap(); + let token = current_user_token(); + let mut inner = task.inner_exclusive_access(); + let (pipe_read, pipe_write) = make_pipe(); + let read_fd = inner.alloc_fd(); + inner.fd_table[read_fd] = Some(pipe_read); + let write_fd = inner.alloc_fd(); + inner.fd_table[write_fd] = Some(pipe_write); + *translated_refmut(token, pipe) = read_fd; + *translated_refmut(token, unsafe { pipe.add(1) }) = write_fd; + 0 +} + +pub fn sys_dup(fd: usize) -> isize { + let task = current_task().unwrap(); + let mut inner = task.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + let new_fd = inner.alloc_fd(); + inner.fd_table[new_fd] = Some(Arc::clone(inner.fd_table[fd].as_ref().unwrap())); + new_fd as isize +} + +// YOUR JOB: 扩展 easy-fs 和内核以实现以下三个 syscall +pub fn sys_fstat(_fd: usize, _st: *mut Stat) -> isize { + -1 +} + +pub fn sys_linkat(_old_name: *const u8, _new_name: *const u8) -> isize { + -1 +} + +pub fn sys_unlinkat(_name: *const u8) -> isize { + -1 +} diff --git a/os7-ref/src/syscall/mod.rs b/os7-ref/src/syscall/mod.rs new file mode 100644 index 0000000..01eba3d --- /dev/null +++ b/os7-ref/src/syscall/mod.rs @@ -0,0 +1,68 @@ +//! Implementation of syscalls +//! +//! The single entry point to all system calls, [`syscall()`], is called +//! whenever userspace wishes to perform a system call using the `ecall` +//! instruction. In this case, the processor raises an 'Environment call from +//! U-mode' exception, which is handled as one of the cases in +//! [`crate::trap::trap_handler`]. +//! +//! For clarity, each single syscall is implemented as its own function, named +//! `sys_` then the name of the syscall. You can find functions like this in +//! submodules, and you should also implement syscalls this way. + +const SYSCALL_DUP: usize = 24; +const SYSCALL_UNLINKAT: usize = 35; +const SYSCALL_LINKAT: usize = 37; +const SYSCALL_OPEN: usize = 56; +const SYSCALL_CLOSE: usize = 57; +const SYSCALL_PIPE: usize = 59; +const SYSCALL_READ: usize = 63; +const SYSCALL_WRITE: usize = 64; +const SYSCALL_FSTAT: usize = 80; +const SYSCALL_EXIT: usize = 93; +const SYSCALL_YIELD: usize = 124; +const SYSCALL_GET_TIME: usize = 169; +const SYSCALL_GETPID: usize = 172; +const SYSCALL_FORK: usize = 220; +const SYSCALL_EXEC: usize = 221; +const SYSCALL_WAITPID: usize = 260; +const SYSCALL_SPAWN: usize = 400; +const SYSCALL_MUNMAP: usize = 215; +const SYSCALL_MMAP: usize = 222; +const SYSCALL_SET_PRIORITY: usize = 140; +const SYSCALL_TASK_INFO: usize = 410; + +mod fs; +pub mod process; + +use fs::*; +use process::*; +use crate::fs::Stat; + +/// handle syscall exception with `syscall_id` and other arguments +pub fn syscall(syscall_id: usize, args: [usize; 4]) -> isize { + match syscall_id { + SYSCALL_DUP => sys_dup(args[0]), + SYSCALL_LINKAT => sys_linkat(args[1] as *const u8, args[3] as *const u8), + SYSCALL_UNLINKAT => sys_unlinkat(args[1] as *const u8), + SYSCALL_OPEN => sys_open(args[1] as *const u8, args[2] as u32), + SYSCALL_CLOSE => sys_close(args[0]), + SYSCALL_PIPE => sys_pipe(args[0] as *mut usize), + SYSCALL_READ => sys_read(args[0], args[1] as *const u8, args[2]), + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_FSTAT => sys_fstat(args[0], args[1] as *mut Stat), + SYSCALL_EXIT => sys_exit(args[0] as i32), + SYSCALL_YIELD => sys_yield(), + SYSCALL_GETPID => sys_getpid(), + SYSCALL_FORK => sys_fork(), + SYSCALL_EXEC => sys_exec(args[0] as *const u8, args[1] as *const usize), + SYSCALL_WAITPID => sys_waitpid(args[0] as isize, args[1] as *mut i32), + SYSCALL_GET_TIME => sys_get_time(args[0] as *mut TimeVal, args[1]), + SYSCALL_MMAP => sys_mmap(args[0], args[1], args[2]), + SYSCALL_MUNMAP => sys_munmap(args[0], args[1]), + SYSCALL_SET_PRIORITY => sys_set_priority(args[0] as isize), + SYSCALL_TASK_INFO => sys_task_info(args[0] as *mut TaskInfo), + SYSCALL_SPAWN => sys_spawn(args[0] as *const u8), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os7-ref/src/syscall/process.rs b/os7-ref/src/syscall/process.rs new file mode 100644 index 0000000..823aa90 --- /dev/null +++ b/os7-ref/src/syscall/process.rs @@ -0,0 +1,160 @@ +//! Process management syscalls + +use crate::mm::{translated_refmut, translated_ref, translated_str}; +use crate::task::{ + add_task, current_task, current_user_token, exit_current_and_run_next, + suspend_current_and_run_next, TaskStatus, +}; +use crate::fs::{open_file, OpenFlags}; +use crate::timer::get_time_us; +use alloc::sync::Arc; +use alloc::vec::Vec; +use crate::config::MAX_SYSCALL_NUM; +use alloc::string::String; + +#[repr(C)] +#[derive(Debug)] +pub struct TimeVal { + pub sec: usize, + pub usec: usize, +} + +#[derive(Clone, Copy)] +pub struct TaskInfo { + pub status: TaskStatus, + pub syscall_times: [u32; MAX_SYSCALL_NUM], + pub time: usize, +} + +pub fn sys_exit(exit_code: i32) -> ! { + debug!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(exit_code); + panic!("Unreachable in sys_exit!"); +} + +/// current task gives up resources for other tasks +pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 +} + +pub fn sys_getpid() -> isize { + current_task().unwrap().pid.0 as isize +} + +/// Syscall Fork which returns 0 for child process and child_pid for parent process +pub fn sys_fork() -> isize { + let current_task = current_task().unwrap(); + let new_task = current_task.fork(); + let new_pid = new_task.pid.0; + // modify trap context of new_task, because it returns immediately after switching + let trap_cx = new_task.inner_exclusive_access().get_trap_cx(); + // we do not have to move to next instruction since we have done it before + // for child process, fork returns 0 + trap_cx.x[10] = 0; + // add new task to scheduler + add_task(new_task); + new_pid as isize +} + +/// Syscall Exec which accepts the elf path +pub fn sys_exec(path: *const u8, mut args: *const usize) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + let mut args_vec: Vec = Vec::new(); + loop { + let arg_str_ptr = *translated_ref(token, args); + if arg_str_ptr == 0 { + break; + } + args_vec.push(translated_str(token, arg_str_ptr as *const u8)); + unsafe { + args = args.add(1); + } + } + if let Some(app_inode) = open_file(path.as_str(), OpenFlags::RDONLY) { + let all_data = app_inode.read_all(); + let task = current_task().unwrap(); + let argc = args_vec.len(); + task.exec(all_data.as_slice(), args_vec); + argc as isize + } else { + -1 + } +} + + +/// If there is not a child process whose pid is same as given, return -1. +/// Else if there is a child process but it is still running, return -2. +pub fn sys_waitpid(pid: isize, exit_code_ptr: *mut i32) -> isize { + let task = current_task().unwrap(); + // find a child process + + // ---- access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + if !inner + .children + .iter() + .any(|p| pid == -1 || pid as usize == p.getpid()) + { + return -1; + // ---- release current PCB + } + let pair = inner.children.iter().enumerate().find(|(_, p)| { + // ++++ temporarily access child PCB lock exclusively + p.inner_exclusive_access().is_zombie() && (pid == -1 || pid as usize == p.getpid()) + // ++++ release child PCB + }); + if let Some((idx, _)) = pair { + let child = inner.children.remove(idx); + // confirm that child will be deallocated after removing from children list + assert_eq!(Arc::strong_count(&child), 1); + let found_pid = child.getpid(); + // ++++ temporarily access child TCB exclusively + let exit_code = child.inner_exclusive_access().exit_code; + // ++++ release child PCB + *translated_refmut(inner.memory_set.token(), exit_code_ptr) = exit_code; + found_pid as isize + } else { + -2 + } + // ---- release current PCB lock automatically +} + +// YOUR JOB: 引入虚地址后重写 sys_get_time +pub fn sys_get_time(_ts: *mut TimeVal, _tz: usize) -> isize { + let _us = get_time_us(); + // unsafe { + // *ts = TimeVal { + // sec: us / 1_000_000, + // usec: us % 1_000_000, + // }; + // } + 0 +} + +// YOUR JOB: 引入虚地址后重写 sys_task_info +pub fn sys_task_info(ti: *mut TaskInfo) -> isize { + -1 +} + +// YOUR JOB: 实现sys_set_priority，为任务添加优先级 +pub fn sys_set_priority(_prio: isize) -> isize { + -1 +} + +// YOUR JOB: 扩展内核以实现 sys_mmap 和 sys_munmap +pub fn sys_mmap(_start: usize, _len: usize, _port: usize) -> isize { + -1 +} + +pub fn sys_munmap(_start: usize, _len: usize) -> isize { + -1 +} + +// +// YOUR JOB: 实现 sys_spawn 系统调用 +// ALERT: 注意在实现 SPAWN 时不需要复制父进程地址空间，SPAWN != FORK + EXEC +pub fn sys_spawn(_path: *const u8) -> isize { + -1 +} diff --git a/os7-ref/src/task/context.rs b/os7-ref/src/task/context.rs new file mode 100644 index 0000000..200bfb1 --- /dev/null +++ b/os7-ref/src/task/context.rs @@ -0,0 +1,32 @@ +//! Implementation of [`TaskContext`] + +use crate::trap::trap_return; + +#[derive(Copy, Clone)] +#[repr(C)] +/// task context structure containing some registers +pub struct TaskContext { + /// Ret position after task switching + ra: usize, + /// Stack pointer + sp: usize, + /// s0-11 register, callee saved + s: [usize; 12], +} + +impl TaskContext { + pub fn zero_init() -> Self { + Self { + ra: 0, + sp: 0, + s: [0; 12], + } + } + pub fn goto_trap_return(kstack_ptr: usize) -> Self { + Self { + ra: trap_return as usize, + sp: kstack_ptr, + s: [0; 12], + } + } +} diff --git a/os7-ref/src/task/manager.rs b/os7-ref/src/task/manager.rs new file mode 100644 index 0000000..47f7ace --- /dev/null +++ b/os7-ref/src/task/manager.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TaskManager`] +//! +//! It is only used to manage processes and schedule process based on ready queue. +//! Other CPU process monitoring functions are in Processor. + + +use super::TaskControlBlock; +use crate::sync::UPSafeCell; +use alloc::collections::VecDeque; +use alloc::sync::Arc; +use lazy_static::*; + +pub struct TaskManager { + ready_queue: VecDeque>, +} + +// YOUR JOB: FIFO->Stride +/// A simple FIFO scheduler. +impl TaskManager { + pub fn new() -> Self { + Self { + ready_queue: VecDeque::new(), + } + } + /// Add process back to ready queue + pub fn add(&mut self, task: Arc) { + self.ready_queue.push_back(task); + } + /// Take a process out of the ready queue + pub fn fetch(&mut self) -> Option> { + self.ready_queue.pop_front() + } +} + +lazy_static! { + /// TASK_MANAGER instance through lazy_static! + pub static ref TASK_MANAGER: UPSafeCell = + unsafe { UPSafeCell::new(TaskManager::new()) }; +} + +pub fn add_task(task: Arc) { + TASK_MANAGER.exclusive_access().add(task); +} + +pub fn fetch_task() -> Option> { + TASK_MANAGER.exclusive_access().fetch() +} diff --git a/os7-ref/src/task/mod.rs b/os7-ref/src/task/mod.rs new file mode 100644 index 0000000..79f52a4 --- /dev/null +++ b/os7-ref/src/task/mod.rs @@ -0,0 +1,106 @@ +//! Implementation of process management mechanism +//! +//! Here is the entry for process scheduling required by other modules +//! (such as syscall or clock interrupt). +//! By suspending or exiting the current process, you can +//! modify the process state, manage the process queue through TASK_MANAGER, +//! and switch the control flow through PROCESSOR. +//! +//! Be careful when you see [`__switch`]. Control flow around this function +//! might not be what you expect. + +mod context; +mod manager; +mod pid; +mod processor; +mod switch; +#[allow(clippy::module_inception)] +mod task; + +use alloc::sync::Arc; +use lazy_static::*; +use manager::fetch_task; +use switch::__switch; +use crate::mm::VirtAddr; +use crate::mm::MapPermission; +use crate::config::PAGE_SIZE; +use crate::timer::get_time_us; +pub use crate::syscall::process::TaskInfo; +use crate::fs::{open_file, OpenFlags}; +pub use task::{TaskControlBlock, TaskStatus}; + +pub use context::TaskContext; +pub use manager::add_task; +pub use pid::{pid_alloc, KernelStack, PidHandle}; +pub use processor::{ + current_task, current_trap_cx, current_user_token, run_tasks, schedule, take_current_task, +}; + +/// Make current task suspended and switch to the next task +pub fn suspend_current_and_run_next() { + // There must be an application running. + let task = take_current_task().unwrap(); + + // ---- access current TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let task_cx_ptr = &mut task_inner.task_cx as *mut TaskContext; + // Change status to Ready + task_inner.task_status = TaskStatus::Ready; + drop(task_inner); + // ---- release current PCB + + // push back to ready queue. + add_task(task); + // jump to scheduling cycle + schedule(task_cx_ptr); +} + +/// Exit current task, recycle process resources and switch to the next task +pub fn exit_current_and_run_next(exit_code: i32) { + // take from Processor + let task = take_current_task().unwrap(); + // **** access current TCB exclusively + let mut inner = task.inner_exclusive_access(); + // Change status to Zombie + inner.task_status = TaskStatus::Zombie; + // Record exit code + inner.exit_code = exit_code; + // do not move to its parent but under initproc + + // ++++++ access initproc TCB exclusively + { + let mut initproc_inner = INITPROC.inner_exclusive_access(); + for child in inner.children.iter() { + child.inner_exclusive_access().parent = Some(Arc::downgrade(&INITPROC)); + initproc_inner.children.push(child.clone()); + } + } + // ++++++ release parent PCB + + inner.children.clear(); + // deallocate user space + inner.memory_set.recycle_data_pages(); + drop(inner); + // **** release current PCB + // drop task manually to maintain rc correctly + drop(task); + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); +} + +lazy_static! { + /// Creation of initial process + /// + /// the name "initproc" may be changed to any other app name like "usertests", + /// but we have user_shell, so we don't need to change it. + pub static ref INITPROC: Arc = Arc::new({ + let inode = open_file("ch7b_initproc", OpenFlags::RDONLY).unwrap(); + let v = inode.read_all(); + TaskControlBlock::new(v.as_slice()) + }); +} + +pub fn add_initproc() { + add_task(INITPROC.clone()); +} diff --git a/os7-ref/src/task/pid.rs b/os7-ref/src/task/pid.rs new file mode 100644 index 0000000..6e5c194 --- /dev/null +++ b/os7-ref/src/task/pid.rs @@ -0,0 +1,116 @@ +//! Task pid implementation. +//! +//! Assign PID to the process here. At the same time, the position of the application KernelStack +//! is determined according to the PID. + +use crate::config::{KERNEL_STACK_SIZE, PAGE_SIZE, TRAMPOLINE}; +use crate::mm::{MapPermission, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use lazy_static::*; + +/// Process identifier allocator using stack allocation +struct PidAllocator { + /// A new PID to be assigned + current: usize, + /// Recycled PID sequence + recycled: Vec, +} + +impl PidAllocator { + pub fn new() -> Self { + PidAllocator { + current: 0, + recycled: Vec::new(), + } + } + pub fn alloc(&mut self) -> PidHandle { + if let Some(pid) = self.recycled.pop() { + PidHandle(pid) + } else { + self.current += 1; + PidHandle(self.current - 1) + } + } + pub fn dealloc(&mut self, pid: usize) { + assert!(pid < self.current); + assert!( + !self.recycled.iter().any(|ppid| *ppid == pid), + "pid {} has been deallocated!", + pid + ); + self.recycled.push(pid); + } +} + +lazy_static! { + /// Pid allocator instance through lazy_static! + static ref PID_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(PidAllocator::new()) }; +} + +/// Abstract structure of PID +pub struct PidHandle(pub usize); + +impl Drop for PidHandle { + fn drop(&mut self) { + //println!("drop pid {}", self.0); + PID_ALLOCATOR.exclusive_access().dealloc(self.0); + } +} + +pub fn pid_alloc() -> PidHandle { + PID_ALLOCATOR.exclusive_access().alloc() +} + +/// Return (bottom, top) of a kernel stack in kernel space. +pub fn kernel_stack_position(app_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - app_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) +} + +/// KernelStack corresponding to PID +pub struct KernelStack { + pid: usize, +} + +impl KernelStack { + pub fn new(pid_handle: &PidHandle) -> Self { + let pid = pid_handle.0; + let (kernel_stack_bottom, kernel_stack_top) = kernel_stack_position(pid); + KERNEL_SPACE.exclusive_access().insert_framed_area( + kernel_stack_bottom.into(), + kernel_stack_top.into(), + MapPermission::R | MapPermission::W, + ); + KernelStack { pid: pid_handle.0 } + } + #[allow(unused)] + /// Push a variable of type T into the top of the KernelStack and return its raw pointer + pub fn push_on_top(&self, value: T) -> *mut T + where + T: Sized, + { + let kernel_stack_top = self.get_top(); + let ptr_mut = (kernel_stack_top - core::mem::size_of::()) as *mut T; + unsafe { + *ptr_mut = value; + } + ptr_mut + } + pub fn get_top(&self) -> usize { + let (_, kernel_stack_top) = kernel_stack_position(self.pid); + kernel_stack_top + } +} + +impl Drop for KernelStack { + fn drop(&mut self) { + let (kernel_stack_bottom, _) = kernel_stack_position(self.pid); + let kernel_stack_bottom_va: VirtAddr = kernel_stack_bottom.into(); + KERNEL_SPACE + .exclusive_access() + .remove_area_with_start_vpn(kernel_stack_bottom_va.into()); + } +} diff --git a/os7-ref/src/task/processor.rs b/os7-ref/src/task/processor.rs new file mode 100644 index 0000000..4218e3b --- /dev/null +++ b/os7-ref/src/task/processor.rs @@ -0,0 +1,105 @@ +//! Implementation of [`Processor`] and Intersection of control flow +//! +//! Here, the continuous operation of user apps in CPU is maintained, +//! the current running state of CPU is recorded, +//! and the replacement and transfer of control flow of different applications are executed. + + +use super::__switch; +use super::{fetch_task, TaskStatus}; +use super::{TaskContext, TaskControlBlock}; +use crate::sync::UPSafeCell; +use crate::trap::TrapContext; +use alloc::sync::Arc; +use lazy_static::*; + +/// Processor management structure +pub struct Processor { + /// The task currently executing on the current processor + current: Option>, + /// The basic control flow of each core, helping to select and switch process + idle_task_cx: TaskContext, +} + +impl Processor { + pub fn new() -> Self { + Self { + current: None, + idle_task_cx: TaskContext::zero_init(), + } + } + fn get_idle_task_cx_ptr(&mut self) -> *mut TaskContext { + &mut self.idle_task_cx as *mut _ + } + pub fn take_current(&mut self) -> Option> { + self.current.take() + } + pub fn current(&self) -> Option> { + self.current.as_ref().map(|task| Arc::clone(task)) + } +} + +lazy_static! { + /// PROCESSOR instance through lazy_static! + pub static ref PROCESSOR: UPSafeCell = unsafe { UPSafeCell::new(Processor::new()) }; +} + +/// The main part of process execution and scheduling +/// +/// Loop fetch_task to get the process that needs to run, +/// and switch the process through __switch +pub fn run_tasks() { + loop { + let mut processor = PROCESSOR.exclusive_access(); + if let Some(task) = fetch_task() { + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + // access coming task TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let next_task_cx_ptr = &task_inner.task_cx as *const TaskContext; + task_inner.task_status = TaskStatus::Running; + drop(task_inner); + // release coming task TCB manually + processor.current = Some(task); + // release processor manually + drop(processor); + unsafe { + __switch(idle_task_cx_ptr, next_task_cx_ptr); + } + } + } +} + +/// Get current task through take, leaving a None in its place +pub fn take_current_task() -> Option> { + PROCESSOR.exclusive_access().take_current() +} + +/// Get a copy of the current task +pub fn current_task() -> Option> { + PROCESSOR.exclusive_access().current() +} + +/// Get token of the address space of current task +pub fn current_user_token() -> usize { + let task = current_task().unwrap(); + let token = task.inner_exclusive_access().get_user_token(); + token +} + +/// Get the mutable reference to trap context of current task +pub fn current_trap_cx() -> &'static mut TrapContext { + current_task() + .unwrap() + .inner_exclusive_access() + .get_trap_cx() +} + +/// Return to idle control flow for new scheduling +pub fn schedule(switched_task_cx_ptr: *mut TaskContext) { + let mut processor = PROCESSOR.exclusive_access(); + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + drop(processor); + unsafe { + __switch(switched_task_cx_ptr, idle_task_cx_ptr); + } +} diff --git a/os7-ref/src/task/switch.S b/os7-ref/src/task/switch.S new file mode 100644 index 0000000..3f985d2 --- /dev/null +++ b/os7-ref/src/task/switch.S @@ -0,0 +1,34 @@ +.altmacro +.macro SAVE_SN n + sd s\n, (\n+2)*8(a0) +.endm +.macro LOAD_SN n + ld s\n, (\n+2)*8(a1) +.endm + .section .text + .globl __switch +__switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + diff --git a/os7-ref/src/task/switch.rs b/os7-ref/src/task/switch.rs new file mode 100644 index 0000000..af08289 --- /dev/null +++ b/os7-ref/src/task/switch.rs @@ -0,0 +1,16 @@ +//! Rust wrapper around `__switch`. +//! +//! Switching to a different task's context happens here. The actual +//! implementation must not be in Rust and (essentially) has to be in assembly +//! language (Do you know why?), so this module really is just a wrapper around +//! `switch.S`. + +core::arch::global_asm!(include_str!("switch.S")); + +use super::TaskContext; + +extern "C" { + /// Switch to the context of `next_task_cx_ptr`, saving the current context + /// in `current_task_cx_ptr`. + pub fn __switch(current_task_cx_ptr: *mut TaskContext, next_task_cx_ptr: *const TaskContext); +} diff --git a/os7-ref/src/task/task.rs b/os7-ref/src/task/task.rs new file mode 100644 index 0000000..1fb4476 --- /dev/null +++ b/os7-ref/src/task/task.rs @@ -0,0 +1,255 @@ +//! Types related to task management & Functions for completely changing TCB + +use super::TaskContext; +use super::{pid_alloc, KernelStack, PidHandle}; +use crate::config::TRAP_CONTEXT; +use crate::mm::{MemorySet, PhysPageNum, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use crate::trap::{trap_handler, TrapContext}; +use alloc::sync::{Arc, Weak}; +use alloc::vec::Vec; +use core::cell::RefMut; +use crate::fs::{File, Stdin, Stdout}; +use alloc::string::String; +use crate::mm::translated_refmut; + +/// Task control block structure +/// +/// Directly save the contents that will not change during running +pub struct TaskControlBlock { + // immutable + /// Process identifier + pub pid: PidHandle, + /// Kernel stack corresponding to PID + pub kernel_stack: KernelStack, + // mutable + inner: UPSafeCell, +} + +/// Structure containing more process content +/// +/// Store the contents that will change during operation +/// and are wrapped by UPSafeCell to provide mutual exclusion +pub struct TaskControlBlockInner { + /// The physical page number of the frame where the trap context is placed + pub trap_cx_ppn: PhysPageNum, + /// Application data can only appear in areas + /// where the application address space is lower than base_size + pub base_size: usize, + /// Save task context + pub task_cx: TaskContext, + /// Maintain the execution status of the current process + pub task_status: TaskStatus, + /// Application address space + pub memory_set: MemorySet, + /// Parent process of the current process. + /// Weak will not affect the reference count of the parent + pub parent: Option>, + /// A vector containing TCBs of all child processes of the current process + pub children: Vec>, + /// It is set when active exit or execution error occurs + pub exit_code: i32, + pub fd_table: Vec>>, +} + +/// Simple access to its internal fields +impl TaskControlBlockInner { + /* + pub fn get_task_cx_ptr2(&self) -> *const usize { + &self.task_cx_ptr as *const usize + } + */ + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + pub fn get_user_token(&self) -> usize { + self.memory_set.token() + } + fn get_status(&self) -> TaskStatus { + self.task_status + } + pub fn is_zombie(&self) -> bool { + self.get_status() == TaskStatus::Zombie + } + pub fn alloc_fd(&mut self) -> usize { + if let Some(fd) = (0..self.fd_table.len()) + .find(|fd| self.fd_table[*fd].is_none()) { + fd + } else { + self.fd_table.push(None); + self.fd_table.len() - 1 + } + } +} + +impl TaskControlBlock { + /// Get the mutex to get the RefMut TaskControlBlockInner + pub fn inner_exclusive_access(&self) -> RefMut<'_, TaskControlBlockInner> { + self.inner.exclusive_access() + } + + /// Create a new process + /// + /// At present, it is only used for the creation of initproc + pub fn new(elf_data: &[u8]) -> Self { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + // push a task context which goes to trap_return to the top of kernel stack + let task_control_block = Self { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: user_sp, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + fd_table: alloc::vec![ + // 0 -> stdin + Some(Arc::new(Stdin)), + // 1 -> stdout + Some(Arc::new(Stdout)), + // 2 -> stderr + Some(Arc::new(Stdout)), + ], + }) + }, + }; + // prepare TrapContext in user space + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + kernel_stack_top, + trap_handler as usize, + ); + task_control_block + } + /// Load a new elf to replace the original application address space and start execution + pub fn exec(&self, elf_data: &[u8], args: Vec) { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, mut user_sp, entry_point) = MemorySet::from_elf(elf_data); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // push arguments on user stack + user_sp -= (args.len() + 1) * core::mem::size_of::(); + let argv_base = user_sp; + let mut argv: Vec<_> = (0..=args.len()) + .map(|arg| { + translated_refmut( + memory_set.token(), + (argv_base + arg * core::mem::size_of::()) as *mut usize + ) + }) + .collect(); + *argv[args.len()] = 0; + for i in 0..args.len() { + user_sp -= args[i].len() + 1; + *argv[i] = user_sp; + let mut p = user_sp; + for c in args[i].as_bytes() { + *translated_refmut(memory_set.token(), p as *mut u8) = *c; + p += 1; + } + *translated_refmut(memory_set.token(), p as *mut u8) = 0; + } + // make the user_sp aligned to 8B for k210 platform + user_sp -= user_sp % core::mem::size_of::(); + // **** access inner exclusively + let mut inner = self.inner_exclusive_access(); + // substitute memory_set + inner.memory_set = memory_set; + // update trap_cx ppn + inner.trap_cx_ppn = trap_cx_ppn; + // initialize trap_cx + let trap_cx = inner.get_trap_cx(); + *trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + self.kernel_stack.get_top(), + trap_handler as usize, + ); + trap_cx.x[10] = args.len(); + trap_cx.x[11] = argv_base; + // **** release inner automatically + } + /// Fork from parent to child + pub fn fork(self: &Arc) -> Arc { + // ---- access parent PCB exclusively + let mut parent_inner = self.inner_exclusive_access(); + // copy user space(include trap context) + let memory_set = MemorySet::from_existed_user(&parent_inner.memory_set); + let trap_cx_ppn = memory_set + .translate(VirtAddr::from(TRAP_CONTEXT).into()) + .unwrap() + .ppn(); + // alloc a pid and a kernel stack in kernel space + let pid_handle = pid_alloc(); + let kernel_stack = KernelStack::new(&pid_handle); + let kernel_stack_top = kernel_stack.get_top(); + let mut new_fd_table: Vec>> = Vec::new(); + // clone all fds from parent to child + for fd in parent_inner.fd_table.iter() { + if let Some(file) = fd { + new_fd_table.push(Some(file.clone())); + } else { + new_fd_table.push(None); + } + } + let task_control_block = Arc::new(TaskControlBlock { + pid: pid_handle, + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + trap_cx_ppn, + base_size: parent_inner.base_size, + task_cx: TaskContext::goto_trap_return(kernel_stack_top), + task_status: TaskStatus::Ready, + memory_set, + parent: Some(Arc::downgrade(self)), + children: Vec::new(), + exit_code: 0, + fd_table: new_fd_table, + }) + }, + }); + // add child + parent_inner.children.push(task_control_block.clone()); + // modify kernel_sp in trap_cx + // **** access children PCB exclusively + let trap_cx = task_control_block.inner_exclusive_access().get_trap_cx(); + trap_cx.kernel_sp = kernel_stack_top; + // return + task_control_block + // ---- release parent PCB automatically + // **** release children PCB automatically + } + pub fn getpid(&self) -> usize { + self.pid.0 + } +} + +#[derive(Copy, Clone, PartialEq)] +/// task status: UnInit, Ready, Running, Exited +pub enum TaskStatus { + UnInit, + Ready, + Running, + Zombie, +} diff --git a/os7-ref/src/timer.rs b/os7-ref/src/timer.rs new file mode 100644 index 0000000..4f40494 --- /dev/null +++ b/os7-ref/src/timer.rs @@ -0,0 +1,23 @@ +//! RISC-V timer-related functionality + +use crate::config::CLOCK_FREQ; +use crate::sbi::set_timer; +use riscv::register::time; + +const TICKS_PER_SEC: usize = 100; +const MICRO_PER_SEC: usize = 1_000_000; + +/// read the `mtime` register +pub fn get_time() -> usize { + time::read() +} + +/// get current time in microseconds +pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) +} + +/// set the next timer interrupt +pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); +} diff --git a/os7-ref/src/trap/context.rs b/os7-ref/src/trap/context.rs new file mode 100644 index 0000000..58e199c --- /dev/null +++ b/os7-ref/src/trap/context.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TrapContext`] + +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +/// trap context structure containing sstatus, sepc and registers +pub struct TrapContext { + /// General-Purpose Register x0-31 + pub x: [usize; 32], + /// sstatus + pub sstatus: Sstatus, + /// sepc + pub sepc: usize, + /// Token of kernel address space + pub kernel_satp: usize, + /// Kernel stack pointer of the current application + pub kernel_sp: usize, + /// Virtual address of trap handler entry point in kernel + pub trap_handler: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context( + entry: usize, + sp: usize, + kernel_satp: usize, + kernel_sp: usize, + trap_handler: usize, + ) -> Self { + let mut sstatus = sstatus::read(); + // set CPU privilege to User after trapping back + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + kernel_satp, + kernel_sp, + trap_handler, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os7-ref/src/trap/mod.rs b/os7-ref/src/trap/mod.rs new file mode 100644 index 0000000..d686aea --- /dev/null +++ b/os7-ref/src/trap/mod.rs @@ -0,0 +1,131 @@ +//! Trap handling functionality +//! +//! For rCore, we have a single trap entry point, namely `__alltraps`. At +//! initialization in [`init()`], we set the `stvec` CSR to point to it. +//! +//! All traps go through `__alltraps`, which is defined in `trap.S`. The +//! assembly language code does just enough work restore the kernel space +//! context, ensuring that Rust code safely runs, and transfers control to +//! [`trap_handler()`]. +//! +//! It then calls different functionality based on what exactly the exception +//! was. For example, timer interrupts trigger task preemption, and syscalls go +//! to [`syscall()`]. + +mod context; + +use crate::config::{TRAMPOLINE, TRAP_CONTEXT}; +use crate::syscall::syscall; +use crate::task::{ + current_trap_cx, current_user_token, exit_current_and_run_next, suspend_current_and_run_next, +}; +use crate::timer::set_next_trigger; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Interrupt, Trap}, + sie, stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +pub fn init() { + set_kernel_trap_entry(); +} + +fn set_kernel_trap_entry() { + unsafe { + stvec::write(trap_from_kernel as usize, TrapMode::Direct); + } +} + +fn set_user_trap_entry() { + unsafe { + stvec::write(TRAMPOLINE as usize, TrapMode::Direct); + } +} + +pub fn enable_timer_interrupt() { + unsafe { + sie::set_stimer(); + } +} + +#[no_mangle] +pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + // jump to next instruction anyway + let mut cx = current_trap_cx(); + cx.sepc += 4; + // get system call return value + let result = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12], cx.x[13]]); + // cx is changed during sys_exec, so we have to call it again + cx = current_trap_cx(); + cx.x[10] = result as usize; + } + Trap::Exception(Exception::StoreFault) + | Trap::Exception(Exception::StorePageFault) + | Trap::Exception(Exception::InstructionFault) + | Trap::Exception(Exception::InstructionPageFault) + | Trap::Exception(Exception::LoadFault) + | Trap::Exception(Exception::LoadPageFault) => { + println!( + "[kernel] {:?} in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", + scause.cause(), + stval, + current_trap_cx().sepc, + ); + // page fault exit code + exit_current_and_run_next(-2); + } + Trap::Exception(Exception::IllegalInstruction) => { + println!("[kernel] IllegalInstruction in application, core dumped."); + // illegal instruction exit code + exit_current_and_run_next(-3); + } + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + suspend_current_and_run_next(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + trap_return(); +} + +#[no_mangle] +pub fn trap_return() -> ! { + set_user_trap_entry(); + let trap_cx_ptr = TRAP_CONTEXT; + let user_satp = current_user_token(); + extern "C" { + fn __alltraps(); + fn __restore(); + } + let restore_va = __restore as usize - __alltraps as usize + TRAMPOLINE; + unsafe { + core::arch::asm!( + "fence.i", + "jr {restore_va}", + restore_va = in(reg) restore_va, + in("a0") trap_cx_ptr, + in("a1") user_satp, + options(noreturn) + ); + } +} + +#[no_mangle] +pub fn trap_from_kernel() -> ! { + panic!("a trap {:?} from kernel!", scause::read().cause()); +} + +pub use context::TrapContext; diff --git a/os7-ref/src/trap/trap.S b/os7-ref/src/trap/trap.S new file mode 100644 index 0000000..c0e2d15 --- /dev/null +++ b/os7-ref/src/trap/trap.S @@ -0,0 +1,69 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text.trampoline + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->*TrapContext in user space, sscratch->user stack + # save other general purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they have been saved in TrapContext + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it in TrapContext + csrr t2, sscratch + sd t2, 2*8(sp) + # load kernel_satp into t0 + ld t0, 34*8(sp) + # load trap_handler into t1 + ld t1, 36*8(sp) + # move to kernel_sp + ld sp, 35*8(sp) + # switch to kernel space + csrw satp, t0 + sfence.vma + # jump to trap_handler + jr t1 + +__restore: + # a0: *TrapContext in user space(Constant); a1: user space token + # switch to user space + csrw satp, a1 + sfence.vma + csrw sscratch, a0 + mv sp, a0 + # now sp points to TrapContext in user space, start restoring based on it + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + # restore general purpose registers except x0/sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # back to user stack + ld sp, 2*8(sp) + sret diff --git a/os8-ref/.cargo/config b/os8-ref/.cargo/config new file mode 100644 index 0000000..4275fca --- /dev/null +++ b/os8-ref/.cargo/config @@ -0,0 +1,7 @@ +[build] +target = "riscv64gc-unknown-none-elf" + +[target.riscv64gc-unknown-none-elf] +rustflags = [ + "-Clink-arg=-Tsrc/linker.ld", "-Cforce-frame-pointers=yes" +] diff --git a/os8-ref/Cargo.toml b/os8-ref/Cargo.toml new file mode 100644 index 0000000..d0d9e54 --- /dev/null +++ b/os8-ref/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "os" +version = "0.1.0" +authors = ["Yifan Wu "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +bitflags = "1.2.1" +buddy_system_allocator = "0.6" +lazy_static = { version = "1.4.0", features = ["spin_no_std"] } +log = "0.4" +riscv = { git = "https://gitee.com/rcore-os/riscv", features = ["inline-asm"] } +lock_api = "=0.4.6" +xmas-elf = "0.7.0" +virtio-drivers = { git = "https://gitee.com/rcore-os/virtio-drivers" } +easy-fs = { path = "../easy-fs" } diff --git a/os8-ref/Makefile b/os8-ref/Makefile new file mode 100644 index 0000000..b90f596 --- /dev/null +++ b/os8-ref/Makefile @@ -0,0 +1,64 @@ +# Building +TARGET := riscv64gc-unknown-none-elf +MODE := release +KERNEL_ELF := target/$(TARGET)/$(MODE)/os +KERNEL_BIN := $(KERNEL_ELF).bin +KERNEL_ASM := $(KERNEL_ELF).asm +FS_IMG := ../user/target/$(TARGET)/$(MODE)/fs.img +APPS := ../user/src/bin/* + +# BOARD +BOARD ?= qemu +SBI ?= rustsbi +BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin + +# KERNEL ENTRY +KERNEL_ENTRY_PA := 0x80200000 + +# Binutils +OBJDUMP := rust-objdump --arch-name=riscv64 +OBJCOPY := rust-objcopy --binary-architecture=riscv64 + +CHAPTER ?= $(shell git rev-parse --abbrev-ref HEAD | grep -o 'ch[0-9]' | grep -o '[0-9]') +TEST ?= $(CHAPTER) +BASE ?= 1 + +build: env $(KERNEL_BIN) fs-img + +fs-img: $(APPS) + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cd ../easy-fs-fuse && cargo run --release -- -s ../user/build/app/ -t ../user/target/riscv64gc-unknown-none-elf/release/ + +env: + (rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET) + cargo install cargo-binutils --vers ~0.3 + rustup component add rust-src + rustup component add llvm-tools-preview + +$(KERNEL_BIN): kernel + @$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@ + +kernel: + @make -C ../user build TEST=$(TEST) CHAPTER=$(CHAPTER) BASE=$(BASE) + @cargo build --release + +clean: + @cargo clean + @cd ../user && make clean + +run: build + @qemu-system-riscv64 \ + -machine virt \ + -nographic \ + -bios $(BOOTLOADER) \ + -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) \ + -drive file=$(FS_IMG),if=none,format=raw,id=x0 \ + -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 + +debug: build + @tmux new-session -d \ + "qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -drive file=$(FS_IMG),if=none,format=raw,id=x0 -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 -s -S" && \ + tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \ + tmux -2 attach-session -d + +.PHONY: build env kernel clean fs-img diff --git a/os8-ref/build.rs b/os8-ref/build.rs new file mode 100644 index 0000000..5529b4f --- /dev/null +++ b/os8-ref/build.rs @@ -0,0 +1,6 @@ +static TARGET_PATH: &str = "../user/target/riscv64gc-unknown-none-elf/release/"; + +fn main() { + println!("cargo:rerun-if-changed=../user/src/"); + println!("cargo:rerun-if-changed={}", TARGET_PATH); +} diff --git a/os8-ref/src/config.rs b/os8-ref/src/config.rs new file mode 100644 index 0000000..8562cd6 --- /dev/null +++ b/os8-ref/src/config.rs @@ -0,0 +1,14 @@ +//! Constants used in rCore + +pub const USER_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_STACK_SIZE: usize = 4096 * 2; +pub const KERNEL_HEAP_SIZE: usize = 0x30_0000; +pub const MEMORY_END: usize = 0x88000000; +pub const PAGE_SIZE: usize = 0x1000; +pub const PAGE_SIZE_BITS: usize = 0xc; +pub const MAX_SYSCALL_NUM: usize = 500; + +pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1; +pub const TRAP_CONTEXT: usize = TRAMPOLINE - PAGE_SIZE; +pub const CLOCK_FREQ: usize = 12500000; +pub const MMIO: &[(usize, usize)] = &[(0x10001000, 0x1000)]; diff --git a/os8-ref/src/console.rs b/os8-ref/src/console.rs new file mode 100644 index 0000000..c90f9e6 --- /dev/null +++ b/os8-ref/src/console.rs @@ -0,0 +1,128 @@ +//! SBI console driver, for text output + +use crate::sbi::console_putchar; +use core::fmt::{self, Write}; + +struct Stdout; + +impl Write for Stdout { + fn write_str(&mut self, s: &str) -> fmt::Result { + for c in s.chars() { + console_putchar(c as usize); + } + Ok(()) + } +} + +pub fn print(args: fmt::Arguments) { + Stdout.write_fmt(args).unwrap(); +} + +#[macro_export] +/// print string macro +macro_rules! print { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!($fmt $(, $($arg)+)?)); + } +} + +#[macro_export] +/// println string macro +macro_rules! println { + ($fmt: literal $(, $($arg: tt)+)?) => { + $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?)); + } +} + +/// 以下代码提供了与颜色相关的 ANSI 转义字符，以及彩色输出可以使用的函数与宏。 +/// 可以使用它们，甚至扩展它们，来提升开发体验和显示效果。 +/// 使用 ANSI 转义字符来加上颜色 +#[macro_export] +macro_rules! colorize { + ($content: ident, $foreground_color: ident) => { + format_args!("\u{1B}[{}m{}\u{1B}[0m", $foreground_color as u8, $content) + }; + ($content: ident, $foreground_color: ident, $background_color: ident) => { + format_args!( + "\u{1B}[{}m\u{1B}[{}m{}\u{1B}[0m", + $foreground_color.into(), + $background_color.into(), + $content + ) + }; +} + +pub fn print_colorized( + args: fmt::Arguments, + foreground_color: impl Into, + background_color: impl Into, +) { + Stdout + .write_fmt(colorize!(args, foreground_color, background_color)) + .unwrap(); +} + +/// 带色彩的 print +#[macro_export] +macro_rules! print_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!($fmt $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + }; +} + +/// 带色彩的 println +#[macro_export] +macro_rules! println_colorized { + ($fmt: literal, $foreground_color: expr, $background_color: expr $(, $($arg: tt)+)?) => { + $crate::console::print_colorized(format_args!(concat!($fmt, "\n") $(, $($arg)+)?), $foreground_color as u8, $background_color as u8); + } +} + +#[allow(dead_code)] +pub enum ANSICON { + Reset = 0, + Bold = 1, + Underline = 4, + Blink = 5, + Reverse = 7, + FgBlack = 30, + FgRed = 31, + FgGreen = 32, + FgYellow = 33, + FgBlue = 34, + FgMagenta = 35, + FgCyan = 36, + FgWhite = 37, + FgDefault = 39, + FgLightGray = 90, + FgLightRed = 91, + FgLightGreen = 92, + FgLightYellow = 93, + FgLightBlue = 94, + FgLightMagenta = 95, + FgLightCyan = 96, + FgLightWhite = 97, + BgBlack = 40, + BgRed = 41, + BgGreen = 42, + BgYellow = 43, + BgBlue = 44, + BgMagenta = 45, + BgCyan = 46, + BgWhite = 47, + BgDefault = 49, + BgLightGray = 100, + BgLightRed = 101, + BgLightGreen = 102, + BgLightYellow = 103, + BgLightBlue = 104, + BgLightMagenta = 105, + BgLightCyan = 106, + BgLightWhite = 107, +} + +impl From for u8 { + fn from(con: ANSICON) -> Self { + con as Self + } +} diff --git a/os8-ref/src/drivers/block/mod.rs b/os8-ref/src/drivers/block/mod.rs new file mode 100644 index 0000000..e3a6345 --- /dev/null +++ b/os8-ref/src/drivers/block/mod.rs @@ -0,0 +1,24 @@ +mod virtio_blk; + +use lazy_static::*; +use alloc::sync::Arc; +use easy_fs::BlockDevice; +type BlockDeviceImpl = virtio_blk::VirtIOBlock; + +lazy_static! { + pub static ref BLOCK_DEVICE: Arc = Arc::new(BlockDeviceImpl::new()); +} + +#[allow(unused)] +pub fn block_device_test() { + let block_device = BLOCK_DEVICE.clone(); + let mut write_buffer = [0u8; 512]; + let mut read_buffer = [0u8; 512]; + for i in 0..512 { + for byte in write_buffer.iter_mut() { *byte = i as u8; } + block_device.write_block(i as usize, &write_buffer); + block_device.read_block(i as usize, &mut read_buffer); + assert_eq!(write_buffer, read_buffer); + } + println!("block device test passed!"); +} \ No newline at end of file diff --git a/os8-ref/src/drivers/block/virtio_blk.rs b/os8-ref/src/drivers/block/virtio_blk.rs new file mode 100644 index 0000000..c9956f5 --- /dev/null +++ b/os8-ref/src/drivers/block/virtio_blk.rs @@ -0,0 +1,84 @@ + +use virtio_drivers::{VirtIOBlk, VirtIOHeader}; +use crate::mm::{ + PhysAddr, + VirtAddr, + frame_alloc, + frame_dealloc, + PhysPageNum, + FrameTracker, + PageTable, + StepByOne, + kernel_token, +}; +use super::BlockDevice; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use lazy_static::*; + +#[allow(unused)] +const VIRTIO0: usize = 0x10001000; + +pub struct VirtIOBlock(UPSafeCell>); + +lazy_static! { + static ref QUEUE_FRAMES: UPSafeCell> = unsafe { + UPSafeCell::new(Vec::new()) + }; +} + +impl BlockDevice for VirtIOBlock { + fn read_block(&self, block_id: usize, buf: &mut [u8]) { + self.0.exclusive_access() + .read_block(block_id, buf) + .expect("Error when reading VirtIOBlk"); + } + fn write_block(&self, block_id: usize, buf: &[u8]) { + self.0.exclusive_access() + .write_block(block_id, buf) + .expect("Error when writing VirtIOBlk"); + } +} + +impl VirtIOBlock { + #[allow(unused)] + pub fn new() -> Self { + unsafe { + Self(UPSafeCell::new(VirtIOBlk::new( + &mut *(VIRTIO0 as *mut VirtIOHeader) + ).unwrap())) + } + } +} + +#[no_mangle] +pub extern "C" fn virtio_dma_alloc(pages: usize) -> PhysAddr { + let mut ppn_base = PhysPageNum(0); + for i in 0..pages { + let frame = frame_alloc().unwrap(); + if i == 0 { ppn_base = frame.ppn; } + assert_eq!(frame.ppn.0, ppn_base.0 + i); + QUEUE_FRAMES.exclusive_access().push(frame); + } + ppn_base.into() +} + +#[no_mangle] +pub extern "C" fn virtio_dma_dealloc(pa: PhysAddr, pages: usize) -> i32 { + let mut ppn_base: PhysPageNum = pa.into(); + for _ in 0..pages { + frame_dealloc(ppn_base); + ppn_base.step(); + } + 0 +} + +#[no_mangle] +pub extern "C" fn virtio_phys_to_virt(paddr: PhysAddr) -> VirtAddr { + VirtAddr(paddr.0) +} + +#[no_mangle] +pub extern "C" fn virtio_virt_to_phys(vaddr: VirtAddr) -> PhysAddr { + PageTable::from_token(kernel_token()).translate_va(vaddr).unwrap() +} diff --git a/os8-ref/src/drivers/mod.rs b/os8-ref/src/drivers/mod.rs new file mode 100644 index 0000000..43a6f54 --- /dev/null +++ b/os8-ref/src/drivers/mod.rs @@ -0,0 +1,3 @@ +mod block; + +pub use block::BLOCK_DEVICE; diff --git a/os8-ref/src/entry.asm b/os8-ref/src/entry.asm new file mode 100644 index 0000000..9d2ff71 --- /dev/null +++ b/os8-ref/src/entry.asm @@ -0,0 +1,12 @@ + .section .text.entry + .globl _start +_start: + la sp, boot_stack_top + call rust_main + + .section .bss.stack + .globl boot_stack +boot_stack: + .space 4096 * 16 + .globl boot_stack_top +boot_stack_top: \ No newline at end of file diff --git a/os8-ref/src/fs/inode.rs b/os8-ref/src/fs/inode.rs new file mode 100644 index 0000000..5e4ca68 --- /dev/null +++ b/os8-ref/src/fs/inode.rs @@ -0,0 +1,169 @@ +use easy_fs::{ + EasyFileSystem, + Inode, +}; +use crate::drivers::BLOCK_DEVICE; +use crate::sync::UPSafeCell; +use alloc::sync::Arc; +use lazy_static::*; +use bitflags::*; +use alloc::vec::Vec; +use super::File; +use crate::mm::UserBuffer; + +/// A wrapper around a filesystem inode +/// to implement File trait atop +pub struct OSInode { + readable: bool, + writable: bool, + inner: UPSafeCell, +} + +/// The OS inode inner in 'UPSafeCell' +pub struct OSInodeInner { + offset: usize, + inode: Arc, +} + +impl OSInode { + /// Construct an OS inode from a inode + pub fn new( + readable: bool, + writable: bool, + inode: Arc, + ) -> Self { + Self { + readable, + writable, + inner: unsafe { UPSafeCell::new(OSInodeInner { + offset: 0, + inode, + })}, + } + } + /// Read all data inside a inode into vector + pub fn read_all(&self) -> Vec { + let mut inner = self.inner.exclusive_access(); + let mut buffer = [0u8; 512]; + let mut v: Vec = Vec::new(); + loop { + let len = inner.inode.read_at(inner.offset, &mut buffer); + if len == 0 { + break; + } + inner.offset += len; + v.extend_from_slice(&buffer[..len]); + } + v + } +} + +lazy_static! { + /// The root of all inodes, or '/' in short + pub static ref ROOT_INODE: Arc = { + let efs = EasyFileSystem::open(BLOCK_DEVICE.clone()); + Arc::new(EasyFileSystem::root_inode(&efs)) + }; +} + +/// List all files in the filesystems +pub fn list_apps() { + println!("/**** APPS ****"); + for app in ROOT_INODE.ls() { + println!("{}", app); + } + println!("**************/"); +} + +bitflags! { + /// Flags for opening files + pub struct OpenFlags: u32 { + const RDONLY = 0; + const WRONLY = 1 << 0; + const RDWR = 1 << 1; + const CREATE = 1 << 9; + const TRUNC = 1 << 10; + } +} + +impl OpenFlags { + /// Get the current read write permission on an inode + /// does not check validity for simplicity + /// returns (readable, writable) + pub fn read_write(&self) -> (bool, bool) { + if self.is_empty() { + (true, false) + } else if self.contains(Self::WRONLY) { + (false, true) + } else { + (true, true) + } + } +} + +/// Open a file by path +pub fn open_file(name: &str, flags: OpenFlags) -> Option> { + let (readable, writable) = flags.read_write(); + if flags.contains(OpenFlags::CREATE) { + if let Some(inode) = ROOT_INODE.find(name) { + // clear size + inode.clear(); + Some(Arc::new(OSInode::new( + readable, + writable, + inode, + ))) + } else { + // create file + ROOT_INODE.create(name) + .map(|inode| { + Arc::new(OSInode::new( + readable, + writable, + inode, + )) + }) + } + } else { + ROOT_INODE.find(name) + .map(|inode| { + if flags.contains(OpenFlags::TRUNC) { + inode.clear(); + } + Arc::new(OSInode::new( + readable, + writable, + inode + )) + }) + } +} + +impl File for OSInode { + fn readable(&self) -> bool { self.readable } + fn writable(&self) -> bool { self.writable } + fn read(&self, mut buf: UserBuffer) -> usize { + let mut inner = self.inner.exclusive_access(); + let mut total_read_size = 0usize; + for slice in buf.buffers.iter_mut() { + let read_size = inner.inode.read_at(inner.offset, *slice); + if read_size == 0 { + break; + } + inner.offset += read_size; + total_read_size += read_size; + } + total_read_size + } + fn write(&self, buf: UserBuffer) -> usize { + let mut inner = self.inner.exclusive_access(); + let mut total_write_size = 0usize; + for slice in buf.buffers.iter() { + let write_size = inner.inode.write_at(inner.offset, *slice); + assert_eq!(write_size, slice.len()); + inner.offset += write_size; + total_write_size += write_size; + } + total_write_size + } +} diff --git a/os8-ref/src/fs/mod.rs b/os8-ref/src/fs/mod.rs new file mode 100644 index 0000000..c14151e --- /dev/null +++ b/os8-ref/src/fs/mod.rs @@ -0,0 +1,45 @@ +mod stdio; +mod inode; +mod pipe; + +use crate::mm::UserBuffer; + +/// The common abstraction of all IO resources +pub trait File : Send + Sync { + fn readable(&self) -> bool; + fn writable(&self) -> bool; + fn read(&self, buf: UserBuffer) -> usize; + fn write(&self, buf: UserBuffer) -> usize; +} + +/// The stat of a inode +#[repr(C)] +#[derive(Debug)] +pub struct Stat { + /// ID of device containing file + pub dev: u64, + /// inode number + pub ino: u64, + /// file type and mode + pub mode: StatMode, + /// number of hard links + pub nlink: u32, + /// unused pad + pad: [u64; 7], +} + +bitflags! { + /// The mode of a inode + /// whether a directory or a file + pub struct StatMode: u32 { + const NULL = 0; + /// directory + const DIR = 0o040000; + /// ordinary regular file + const FILE = 0o100000; + } +} + +pub use stdio::{Stdin, Stdout}; +pub use inode::{OSInode, open_file, OpenFlags, list_apps}; +pub use pipe::{Pipe, make_pipe}; diff --git a/os8-ref/src/fs/pipe.rs b/os8-ref/src/fs/pipe.rs new file mode 100644 index 0000000..0827594 --- /dev/null +++ b/os8-ref/src/fs/pipe.rs @@ -0,0 +1,179 @@ +use super::File; +use alloc::sync::{Arc, Weak}; +use crate::sync::UPSafeCell; +use crate::mm::UserBuffer; + +use crate::task::suspend_current_and_run_next; + +/// One end of a pipe +pub struct Pipe { + readable: bool, + writable: bool, + buffer: Arc>, +} + +impl Pipe { + /// Create the read end of a pipe from a ring buffer + pub fn read_end_with_buffer(buffer: Arc>) -> Self { + Self { + readable: true, + writable: false, + buffer, + } + } + /// Create the write end of a pipe with a ring buffer + pub fn write_end_with_buffer(buffer: Arc>) -> Self { + Self { + readable: false, + writable: true, + buffer, + } + } +} + +const RING_BUFFER_SIZE: usize = 32; + +#[derive(Copy, Clone, PartialEq)] +enum RingBufferStatus { + FULL, + EMPTY, + NORMAL, +} + +/// The underlying ring buffer of a pipe +pub struct PipeRingBuffer { + arr: [u8; RING_BUFFER_SIZE], + head: usize, + tail: usize, + status: RingBufferStatus, + write_end: Option>, +} + +impl PipeRingBuffer { + pub fn new() -> Self { + Self { + arr: [0; RING_BUFFER_SIZE], + head: 0, + tail: 0, + status: RingBufferStatus::EMPTY, + write_end: None, + } + } + /// Set the write end bound to this buffer + pub fn set_write_end(&mut self, write_end: &Arc) { + self.write_end = Some(Arc::downgrade(write_end)); + } + /// Write into the buffer + pub fn write_byte(&mut self, byte: u8) { + self.status = RingBufferStatus::NORMAL; + self.arr[self.tail] = byte; + self.tail = (self.tail + 1) % RING_BUFFER_SIZE; + if self.tail == self.head { + self.status = RingBufferStatus::FULL; + } + } + /// Read from the buffer + pub fn read_byte(&mut self) -> u8 { + self.status = RingBufferStatus::NORMAL; + let c = self.arr[self.head]; + self.head = (self.head + 1) % RING_BUFFER_SIZE; + if self.head == self.tail { + self.status = RingBufferStatus::EMPTY; + } + c + } + /// Get the length of remaining data in the buffer + pub fn available_read(&self) -> usize { + if self.status == RingBufferStatus::EMPTY { + 0 + } else { + if self.tail > self.head { + self.tail - self.head + } else { + self.tail + RING_BUFFER_SIZE - self.head + } + } + } + /// Get the length of remaining space in the buffer + pub fn available_write(&self) -> usize { + if self.status == RingBufferStatus::FULL { + 0 + } else { + RING_BUFFER_SIZE - self.available_read() + } + } + /// Check if all write ends bounded to this buffer are closed + pub fn all_write_ends_closed(&self) -> bool { + self.write_end.as_ref().unwrap().upgrade().is_none() + } +} + +/// Crate a pipe +/// return (read_end, write_end) +pub fn make_pipe() -> (Arc, Arc) { + let buffer = Arc::new(unsafe { + UPSafeCell::new(PipeRingBuffer::new()) + }); + let read_end = Arc::new( + Pipe::read_end_with_buffer(buffer.clone()) + ); + let write_end = Arc::new( + Pipe::write_end_with_buffer(buffer.clone()) + ); + buffer.exclusive_access().set_write_end(&write_end); + (read_end, write_end) +} + +impl File for Pipe { + fn readable(&self) -> bool { self.readable } + fn writable(&self) -> bool { self.writable } + fn read(&self, buf: UserBuffer) -> usize { + assert_eq!(self.readable(), true); + let mut buf_iter = buf.into_iter(); + let mut read_size = 0usize; + loop { + let mut ring_buffer = self.buffer.exclusive_access(); + let loop_read = ring_buffer.available_read(); + if loop_read == 0 { + if ring_buffer.all_write_ends_closed() { + return read_size; + } + drop(ring_buffer); + suspend_current_and_run_next(); + continue; + } + // read at most loop_read bytes + for _ in 0..loop_read { + if let Some(byte_ref) = buf_iter.next() { + unsafe { *byte_ref = ring_buffer.read_byte(); } + read_size += 1; + } else { + return read_size; + } + } + } + } + fn write(&self, buf: UserBuffer) -> usize { + assert_eq!(self.writable(), true); + let mut buf_iter = buf.into_iter(); + let mut write_size = 0usize; + loop { + let mut ring_buffer = self.buffer.exclusive_access(); + let loop_write = ring_buffer.available_write(); + if loop_write == 0 { + drop(ring_buffer); + suspend_current_and_run_next(); + continue; + } + // write at most loop_write bytes + for _ in 0..loop_write { + if let Some(byte_ref) = buf_iter.next() { + ring_buffer.write_byte(unsafe { *byte_ref }); + write_size += 1; + } else { + return write_size; + } + } + } + } +} diff --git a/os8-ref/src/fs/stdio.rs b/os8-ref/src/fs/stdio.rs new file mode 100644 index 0000000..87dca0e --- /dev/null +++ b/os8-ref/src/fs/stdio.rs @@ -0,0 +1,48 @@ +use super::File; +use crate::mm::{UserBuffer}; +use crate::sbi::console_getchar; +use crate::task::suspend_current_and_run_next; + +/// The standard input +pub struct Stdin; +/// The standard output +pub struct Stdout; + +impl File for Stdin { + fn readable(&self) -> bool { true } + fn writable(&self) -> bool { false } + fn read(&self, mut user_buf: UserBuffer) -> usize { + assert_eq!(user_buf.len(), 1); + // busy loop + let mut c: usize; + loop { + c = console_getchar(); + if c == 0 { + suspend_current_and_run_next(); + continue; + } else { + break; + } + } + let ch = c as u8; + unsafe { user_buf.buffers[0].as_mut_ptr().write_volatile(ch); } + 1 + } + fn write(&self, _user_buf: UserBuffer) -> usize { + panic!("Cannot write to stdin!"); + } +} + +impl File for Stdout { + fn readable(&self) -> bool { false } + fn writable(&self) -> bool { true } + fn read(&self, _user_buf: UserBuffer) -> usize{ + panic!("Cannot read from stdout!"); + } + fn write(&self, user_buf: UserBuffer) -> usize { + for buffer in user_buf.buffers.iter() { + print!("{}", core::str::from_utf8(*buffer).unwrap()); + } + user_buf.len() + } +} diff --git a/os8-ref/src/lang_items.rs b/os8-ref/src/lang_items.rs new file mode 100644 index 0000000..e52afff --- /dev/null +++ b/os8-ref/src/lang_items.rs @@ -0,0 +1,29 @@ +//! The panic handler + +use crate::console::ANSICON; +use crate::sbi::shutdown; + +use core::panic::PanicInfo; + +#[panic_handler] +/// panic handler +fn panic(info: &PanicInfo) -> ! { + if let Some(location) = info.location() { + println_colorized!( + "[kernel] Panicked at {}:{} {}", + ANSICON::FgRed, + ANSICON::BgDefault, + location.file(), + location.line(), + info.message().unwrap() + ); + } else { + println_colorized!( + "[kernel] Panicked: {}", + ANSICON::FgRed, + ANSICON::BgDefault, + info.message().unwrap() + ); + } + shutdown() +} diff --git a/os8-ref/src/linker.ld b/os8-ref/src/linker.ld new file mode 100644 index 0000000..5baafbd --- /dev/null +++ b/os8-ref/src/linker.ld @@ -0,0 +1,53 @@ +OUTPUT_ARCH(riscv) +ENTRY(_start) +BASE_ADDRESS = 0x80200000; + +SECTIONS +{ + . = BASE_ADDRESS; + skernel = .; + + stext = .; + .text : { + *(.text.entry) + . = ALIGN(4K); + strampoline = .; + *(.text.trampoline); + . = ALIGN(4K); + *(.text .text.*) + } + + . = ALIGN(4K); + etext = .; + srodata = .; + .rodata : { + *(.rodata .rodata.*) + *(.srodata .srodata.*) + } + + . = ALIGN(4K); + erodata = .; + sdata = .; + .data : { + *(.data .data.*) + *(.sdata .sdata.*) + } + + . = ALIGN(4K); + edata = .; + sbss_with_stack = .; + .bss : { + *(.bss.stack) + sbss = .; + *(.bss .bss.*) + *(.sbss .sbss.*) + } + + . = ALIGN(4K); + ebss = .; + ekernel = .; + + /DISCARD/ : { + *(.eh_frame) + } +} \ No newline at end of file diff --git a/os8-ref/src/logging.rs b/os8-ref/src/logging.rs new file mode 100644 index 0000000..e12448e --- /dev/null +++ b/os8-ref/src/logging.rs @@ -0,0 +1,45 @@ +//! Global logger + +use log::{self, Level, LevelFilter, Log, Metadata, Record}; + +/// a simple logger +struct SimpleLogger; + +impl Log for SimpleLogger { + fn enabled(&self, _metadata: &Metadata) -> bool { + true + } + fn log(&self, record: &Record) { + if !self.enabled(record.metadata()) { + return; + } + let color = match record.level() { + Level::Error => 31, // Red + Level::Warn => 93, // BrightYellow + Level::Info => 34, // Blue + Level::Debug => 32, // Green + Level::Trace => 90, // BrightBlack + }; + println!( + "\u{1B}[{}m[{:>5}] {}\u{1B}[0m", + color, + record.level(), + record.args(), + ); + } + fn flush(&self) {} +} + +/// initiate logger +pub fn init() { + static LOGGER: SimpleLogger = SimpleLogger; + log::set_logger(&LOGGER).unwrap(); + log::set_max_level(match option_env!("LOG") { + Some("ERROR") => LevelFilter::Error, + Some("WARN") => LevelFilter::Warn, + Some("INFO") => LevelFilter::Info, + Some("DEBUG") => LevelFilter::Debug, + Some("TRACE") => LevelFilter::Trace, + _ => LevelFilter::Off, + }); +} diff --git a/os8-ref/src/main.rs b/os8-ref/src/main.rs new file mode 100644 index 0000000..df21f04 --- /dev/null +++ b/os8-ref/src/main.rs @@ -0,0 +1,77 @@ +//! The main module and entrypoint +//! +//! Various facilities of the kernels are implemented as submodules. The most +//! important ones are: +//! +//! - [`trap`]: Handles all cases of switching from userspace to the kernel +//! - [`task`]: Task management +//! - [`syscall`]: System call handling and implementation +//! +//! The operating system also starts in this module. Kernel code starts +//! executing from `entry.asm`, after which [`rust_main()`] is called to +//! initialize various pieces of functionality. (See its source code for +//! details.) +//! +//! We then call [`task::run_first_task()`] and for the first time go to +//! userspace. + +#![no_std] +#![no_main] +#![feature(panic_info_message)] +#![feature(alloc_error_handler)] + +#[macro_use] +extern crate bitflags; +#[macro_use] +extern crate log; + +extern crate alloc; + +#[macro_use] +mod console; +mod config; +mod drivers; +mod fs; +mod lang_items; +mod logging; +mod mm; +mod sbi; +mod sync; +mod syscall; +mod task; +mod timer; +mod trap; + +core::arch::global_asm!(include_str!("entry.asm")); + +/// clear BSS segment +fn clear_bss() { + extern "C" { + fn sbss(); + fn ebss(); + } + unsafe { + core::slice::from_raw_parts_mut(sbss as usize as *mut u8, ebss as usize - sbss as usize) + .fill(0); + } +} + +#[no_mangle] +/// the rust entry-point of os +pub fn rust_main() -> ! { + clear_bss(); + logging::init(); + println!("[kernel] Hello, world!"); + mm::init(); + mm::remap_test(); + trap::init(); + trap::enable_timer_interrupt(); + timer::set_next_trigger(); + // Uncomment following lines and see what happens! + // task::kernel_stackless_coroutine_test(); + // task::kernel_stackful_coroutine_test(); + fs::list_apps(); + task::add_initproc(); + task::run_tasks(); + panic!("Unreachable in rust_main!"); +} diff --git a/os8-ref/src/mm/address.rs b/os8-ref/src/mm/address.rs new file mode 100644 index 0000000..5c24ae7 --- /dev/null +++ b/os8-ref/src/mm/address.rs @@ -0,0 +1,259 @@ +//! Implementation of physical and virtual address and page number. +use super::PageTableEntry; +use crate::config::{PAGE_SIZE, PAGE_SIZE_BITS}; +use core::fmt::{self, Debug, Formatter}; + +/// Definitions +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysAddr(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtAddr(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct PhysPageNum(pub usize); + +#[repr(C)] +#[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq)] +pub struct VirtPageNum(pub usize); + +/// Debugging + +impl Debug for VirtAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VA:{:#x}", self.0)) + } +} +impl Debug for VirtPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("VPN:{:#x}", self.0)) + } +} +impl Debug for PhysAddr { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PA:{:#x}", self.0)) + } +} +impl Debug for PhysPageNum { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("PPN:{:#x}", self.0)) + } +} + +/// T: {PhysAddr, VirtAddr, PhysPageNum, VirtPageNum} +/// T -> usize: T.0 +/// usize -> T: usize.into() + +impl From for PhysAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for PhysPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtAddr { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for VirtPageNum { + fn from(v: usize) -> Self { + Self(v) + } +} +impl From for usize { + fn from(v: PhysAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: PhysPageNum) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtAddr) -> Self { + v.0 + } +} +impl From for usize { + fn from(v: VirtPageNum) -> Self { + v.0 + } +} + +impl VirtAddr { + pub fn floor(&self) -> VirtPageNum { + VirtPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> VirtPageNum { + VirtPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for VirtPageNum { + fn from(v: VirtAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for VirtAddr { + fn from(v: VirtPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} +impl PhysAddr { + pub fn floor(&self) -> PhysPageNum { + PhysPageNum(self.0 / PAGE_SIZE) + } + pub fn ceil(&self) -> PhysPageNum { + PhysPageNum((self.0 - 1 + PAGE_SIZE) / PAGE_SIZE) + } + pub fn page_offset(&self) -> usize { + self.0 & (PAGE_SIZE - 1) + } + pub fn aligned(&self) -> bool { + self.page_offset() == 0 + } +} +impl From for PhysPageNum { + fn from(v: PhysAddr) -> Self { + assert_eq!(v.page_offset(), 0); + v.floor() + } +} +impl From for PhysAddr { + fn from(v: PhysPageNum) -> Self { + Self(v.0 << PAGE_SIZE_BITS) + } +} + +impl VirtPageNum { + pub fn indexes(&self) -> [usize; 3] { + let mut vpn = self.0; + let mut idx = [0usize; 3]; + for i in (0..3).rev() { + idx[i] = vpn & 511; + vpn >>= 9; + } + idx + } +} + +impl PhysAddr { + pub fn get_ref(&self) -> &'static T { + unsafe { (self.0 as *const T).as_ref().unwrap() } + } + pub fn get_mut(&self) -> &'static mut T { + unsafe { (self.0 as *mut T).as_mut().unwrap() } + } +} +impl PhysPageNum { + pub fn get_pte_array(&self) -> &'static mut [PageTableEntry] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut PageTableEntry, 512) } + } + pub fn get_bytes_array(&self) -> &'static mut [u8] { + let pa: PhysAddr = (*self).into(); + unsafe { core::slice::from_raw_parts_mut(pa.0 as *mut u8, 4096) } + } + pub fn get_mut(&self) -> &'static mut T { + let pa: PhysAddr = (*self).into(); + pa.get_mut() + } +} + +pub trait StepByOne { + fn step(&mut self); +} +impl StepByOne for VirtPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +impl StepByOne for PhysPageNum { + fn step(&mut self) { + self.0 += 1; + } +} + +#[derive(Copy, Clone)] +/// a simple range structure for type T +pub struct SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + l: T, + r: T, +} +impl SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(start: T, end: T) -> Self { + assert!(start <= end, "start {:?} > end {:?}!", start, end); + Self { l: start, r: end } + } + pub fn get_start(&self) -> T { + self.l + } + pub fn get_end(&self) -> T { + self.r + } +} +impl IntoIterator for SimpleRange +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + type IntoIter = SimpleRangeIterator; + fn into_iter(self) -> Self::IntoIter { + SimpleRangeIterator::new(self.l, self.r) + } +} +/// iterator for the simple range structure +pub struct SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + current: T, + end: T, +} +impl SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + pub fn new(l: T, r: T) -> Self { + Self { current: l, end: r } + } +} +impl Iterator for SimpleRangeIterator +where + T: StepByOne + Copy + PartialEq + PartialOrd + Debug, +{ + type Item = T; + fn next(&mut self) -> Option { + if self.current == self.end { + None + } else { + let t = self.current; + self.current.step(); + Some(t) + } + } +} + +/// a simple range structure for virtual page number +pub type VPNRange = SimpleRange; diff --git a/os8-ref/src/mm/frame_allocator.rs b/os8-ref/src/mm/frame_allocator.rs new file mode 100644 index 0000000..5be113f --- /dev/null +++ b/os8-ref/src/mm/frame_allocator.rs @@ -0,0 +1,137 @@ +//! Implementation of [`FrameAllocator`] which +//! controls all the frames in the operating system. + +use super::{PhysAddr, PhysPageNum}; +use crate::config::MEMORY_END; +use crate::sync::UPSafeCell; +use alloc::vec::Vec; +use core::fmt::{self, Debug, Formatter}; +use lazy_static::*; + +/// manage a frame which has the same lifecycle as the tracker +#[derive(Clone)] +pub struct FrameTracker { + pub ppn: PhysPageNum, +} + +impl FrameTracker { + pub fn new(ppn: PhysPageNum) -> Self { + // page cleaning + let bytes_array = ppn.get_bytes_array(); + for i in bytes_array { + *i = 0; + } + Self { ppn } + } +} + +impl Debug for FrameTracker { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("FrameTracker:PPN={:#x}", self.ppn.0)) + } +} + +impl Drop for FrameTracker { + fn drop(&mut self) { + frame_dealloc(self.ppn); + } +} + +trait FrameAllocator { + fn new() -> Self; + fn alloc(&mut self) -> Option; + fn dealloc(&mut self, ppn: PhysPageNum); +} + +/// an implementation for frame allocator +pub struct StackFrameAllocator { + current: usize, + end: usize, + recycled: Vec, +} + +impl StackFrameAllocator { + pub fn init(&mut self, l: PhysPageNum, r: PhysPageNum) { + self.current = l.0; + self.end = r.0; + info!("last {} Physical Frames.", self.end - self.current); + } +} +impl FrameAllocator for StackFrameAllocator { + fn new() -> Self { + Self { + current: 0, + end: 0, + recycled: Vec::new(), + } + } + fn alloc(&mut self) -> Option { + if let Some(ppn) = self.recycled.pop() { + Some(ppn.into()) + } else if self.current == self.end { + None + } else { + self.current += 1; + Some((self.current - 1).into()) + } + } + fn dealloc(&mut self, ppn: PhysPageNum) { + let ppn = ppn.0; + // validity check + if ppn >= self.current || self.recycled.iter().any(|v| *v == ppn) { + panic!("Frame ppn={:#x} has not been allocated!", ppn); + } + // recycle + self.recycled.push(ppn); + } +} + +type FrameAllocatorImpl = StackFrameAllocator; + +lazy_static! { + /// frame allocator instance through lazy_static! + pub static ref FRAME_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(FrameAllocatorImpl::new()) }; +} + +pub fn init_frame_allocator() { + extern "C" { + fn ekernel(); + } + FRAME_ALLOCATOR.exclusive_access().init( + PhysAddr::from(ekernel as usize).ceil(), + PhysAddr::from(MEMORY_END).floor(), + ); +} + +/// initiate the frame allocator using `ekernel` and `MEMORY_END` +pub fn frame_alloc() -> Option { + FRAME_ALLOCATOR + .exclusive_access() + .alloc() + .map(FrameTracker::new) +} + +/// deallocate a frame +pub fn frame_dealloc(ppn: PhysPageNum) { + FRAME_ALLOCATOR.exclusive_access().dealloc(ppn); +} + +#[allow(unused)] +/// a simple test for frame allocator +pub fn frame_allocator_test() { + let mut v: Vec = Vec::new(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + v.clear(); + for i in 0..5 { + let frame = frame_alloc().unwrap(); + info!("{:?}", frame); + v.push(frame); + } + drop(v); + info!("frame_allocator_test passed!"); +} diff --git a/os8-ref/src/mm/heap_allocator.rs b/os8-ref/src/mm/heap_allocator.rs new file mode 100644 index 0000000..d518fae --- /dev/null +++ b/os8-ref/src/mm/heap_allocator.rs @@ -0,0 +1,51 @@ +//! The global allocator + +use crate::config::KERNEL_HEAP_SIZE; +use buddy_system_allocator::LockedHeap; + +#[global_allocator] +/// heap allocator instance +static HEAP_ALLOCATOR: LockedHeap = LockedHeap::empty(); + +#[alloc_error_handler] +/// panic when heap allocation error occurs +pub fn handle_alloc_error(layout: core::alloc::Layout) -> ! { + panic!("Heap allocation error, layout = {:?}", layout); +} + +/// heap space ([u8; KERNEL_HEAP_SIZE]) +static mut HEAP_SPACE: [u8; KERNEL_HEAP_SIZE] = [0; KERNEL_HEAP_SIZE]; + +/// initiate heap allocator +pub fn init_heap() { + unsafe { + HEAP_ALLOCATOR + .lock() + .init(HEAP_SPACE.as_ptr() as usize, KERNEL_HEAP_SIZE); + } +} + +#[allow(unused)] +pub fn heap_test() { + use alloc::boxed::Box; + use alloc::vec::Vec; + extern "C" { + fn sbss(); + fn ebss(); + } + let bss_range = sbss as usize..ebss as usize; + let a = Box::new(5); + assert_eq!(*a, 5); + assert!(bss_range.contains(&(a.as_ref() as *const _ as usize))); + drop(a); + let mut v: Vec = Vec::new(); + for i in 0..500 { + v.push(i); + } + for (i, vi) in v.iter().enumerate().take(500) { + assert_eq!(*vi, i); + } + assert!(bss_range.contains(&(v.as_ptr() as usize))); + drop(v); + info!("heap_test passed!"); +} diff --git a/os8-ref/src/mm/memory_set.rs b/os8-ref/src/mm/memory_set.rs new file mode 100644 index 0000000..3ecd7dd --- /dev/null +++ b/os8-ref/src/mm/memory_set.rs @@ -0,0 +1,393 @@ +//! Implementation of [`MapArea`] and [`MemorySet`]. + +use super::{frame_alloc, FrameTracker}; +use super::{PTEFlags, PageTable, PageTableEntry}; +use super::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +use super::{StepByOne, VPNRange}; +use crate::config::{MEMORY_END, MMIO, PAGE_SIZE, TRAMPOLINE}; +use crate::sync::UPSafeCell; +use alloc::collections::BTreeMap; +use alloc::sync::Arc; +use alloc::vec::Vec; +use lazy_static::*; +use riscv::register::satp; + +extern "C" { + fn stext(); + fn etext(); + fn srodata(); + fn erodata(); + fn sdata(); + fn edata(); + fn sbss_with_stack(); + fn ebss(); + fn ekernel(); + fn strampoline(); +} + +lazy_static! { + /// a memory set instance through lazy_static! managing kernel space + pub static ref KERNEL_SPACE: Arc> = + Arc::new(unsafe { UPSafeCell::new(MemorySet::new_kernel()) }); +} + +/// Get the token of the kernel memory space +pub fn kernel_token() -> usize { + KERNEL_SPACE.exclusive_access().token() +} + +/// memory set structure, controls virtual-memory space +pub struct MemorySet { + page_table: PageTable, + areas: Vec, +} + +impl MemorySet { + pub fn new_bare() -> Self { + Self { + page_table: PageTable::new(), + areas: Vec::new(), + } + } + pub fn token(&self) -> usize { + self.page_table.token() + } + /// Assume that no conflicts. + pub fn insert_framed_area( + &mut self, + start_va: VirtAddr, + end_va: VirtAddr, + permission: MapPermission, + ) { + self.push( + MapArea::new(start_va, end_va, MapType::Framed, permission), + None, + ); + } + pub fn remove_area_with_start_vpn(&mut self, start_vpn: VirtPageNum) { + if let Some((idx, area)) = self + .areas + .iter_mut() + .enumerate() + .find(|(_, area)| area.vpn_range.get_start() == start_vpn) + { + area.unmap(&mut self.page_table); + self.areas.remove(idx); + } + } + fn push(&mut self, mut map_area: MapArea, data: Option<&[u8]>) { + map_area.map(&mut self.page_table); + if let Some(data) = data { + map_area.copy_data(&mut self.page_table, data); + } + self.areas.push(map_area); + } + /// Mention that trampoline is not collected by areas. + fn map_trampoline(&mut self) { + self.page_table.map( + VirtAddr::from(TRAMPOLINE).into(), + PhysAddr::from(strampoline as usize).into(), + PTEFlags::R | PTEFlags::X, + ); + } + /// Without kernel stacks. + pub fn new_kernel() -> Self { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map kernel sections + info!(".text [{:#x}, {:#x})", stext as usize, etext as usize); + info!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize); + info!(".data [{:#x}, {:#x})", sdata as usize, edata as usize); + info!( + ".bss [{:#x}, {:#x})", + sbss_with_stack as usize, ebss as usize + ); + info!("mapping .text section"); + memory_set.push( + MapArea::new( + (stext as usize).into(), + (etext as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::X, + ), + None, + ); + info!("mapping .rodata section"); + memory_set.push( + MapArea::new( + (srodata as usize).into(), + (erodata as usize).into(), + MapType::Identical, + MapPermission::R, + ), + None, + ); + info!("mapping .data section"); + memory_set.push( + MapArea::new( + (sdata as usize).into(), + (edata as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping .bss section"); + memory_set.push( + MapArea::new( + (sbss_with_stack as usize).into(), + (ebss as usize).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping physical memory"); + memory_set.push( + MapArea::new( + (ekernel as usize).into(), + MEMORY_END.into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + info!("mapping memory-mapped registers"); + for pair in MMIO { + memory_set.push( + MapArea::new( + (*pair).0.into(), + ((*pair).0 + (*pair).1).into(), + MapType::Identical, + MapPermission::R | MapPermission::W, + ), + None, + ); + } + memory_set + } + /// Include sections in elf and trampoline and TrapContext and user stack, + /// also returns user_sp and entry point. + pub fn from_elf(elf_data: &[u8]) -> (Self, usize, usize) { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // map program headers of elf, with U flag + let elf = xmas_elf::ElfFile::new(elf_data).unwrap(); + let elf_header = elf.header; + let magic = elf_header.pt1.magic; + assert_eq!(magic, [0x7f, 0x45, 0x4c, 0x46], "invalid elf!"); + let ph_count = elf_header.pt2.ph_count(); + let mut max_end_vpn = VirtPageNum(0); + for i in 0..ph_count { + let ph = elf.program_header(i).unwrap(); + if ph.get_type().unwrap() == xmas_elf::program::Type::Load { + let start_va: VirtAddr = (ph.virtual_addr() as usize).into(); + let end_va: VirtAddr = ((ph.virtual_addr() + ph.mem_size()) as usize).into(); + let mut map_perm = MapPermission::U; + let ph_flags = ph.flags(); + if ph_flags.is_read() { + map_perm |= MapPermission::R; + } + if ph_flags.is_write() { + map_perm |= MapPermission::W; + } + if ph_flags.is_execute() { + map_perm |= MapPermission::X; + } + let map_area = MapArea::new(start_va, end_va, MapType::Framed, map_perm); + max_end_vpn = map_area.vpn_range.get_end(); + memory_set.push( + map_area, + Some(&elf.input[ph.offset() as usize..(ph.offset() + ph.file_size()) as usize]), + ); + } + } + // We don't map user stack and trapframe here since they will be later + // allocated through TaskControlBlock::new() + let max_end_va: VirtAddr = max_end_vpn.into(); + let mut user_stack_top: usize = max_end_va.into(); + user_stack_top += PAGE_SIZE; + ( + memory_set, + user_stack_top, + elf.header.pt2.entry_point() as usize, + ) + } + /// Copy an identical user_space + pub fn from_existed_user(user_space: &MemorySet) -> MemorySet { + let mut memory_set = Self::new_bare(); + // map trampoline + memory_set.map_trampoline(); + // copy data sections/trap_context/user_stack + for area in user_space.areas.iter() { + let new_area = MapArea::from_another(area); + memory_set.push(new_area, None); + // copy data from another space + for vpn in area.vpn_range { + let src_ppn = user_space.translate(vpn).unwrap().ppn(); + let dst_ppn = memory_set.translate(vpn).unwrap().ppn(); + dst_ppn + .get_bytes_array() + .copy_from_slice(src_ppn.get_bytes_array()); + } + } + memory_set + } + pub fn activate(&self) { + let satp = self.page_table.token(); + unsafe { + satp::write(satp); + core::arch::asm!("sfence.vma"); + } + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.page_table.translate(vpn) + } + pub fn recycle_data_pages(&mut self) { + //*self = Self::new_bare(); + self.areas.clear(); + } + pub fn kernel_copy() -> Self { + let areas = KERNEL_SPACE.exclusive_access().areas.clone(); + Self { + page_table: PageTable::from_token(kernel_token()), + areas: areas, + } + } +} + +/// map area structure, controls a contiguous piece of virtual memory +#[derive(Clone)] +pub struct MapArea { + vpn_range: VPNRange, + data_frames: BTreeMap, + map_type: MapType, + map_perm: MapPermission, +} + +impl MapArea { + pub fn new( + start_va: VirtAddr, + end_va: VirtAddr, + map_type: MapType, + map_perm: MapPermission, + ) -> Self { + let start_vpn: VirtPageNum = start_va.floor(); + let end_vpn: VirtPageNum = end_va.ceil(); + Self { + vpn_range: VPNRange::new(start_vpn, end_vpn), + data_frames: BTreeMap::new(), + map_type, + map_perm, + } + } + pub fn from_another(another: &MapArea) -> Self { + Self { + vpn_range: VPNRange::new(another.vpn_range.get_start(), another.vpn_range.get_end()), + data_frames: BTreeMap::new(), + map_type: another.map_type, + map_perm: another.map_perm, + } + } + pub fn map_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + let ppn: PhysPageNum; + match self.map_type { + MapType::Identical => { + ppn = PhysPageNum(vpn.0); + } + MapType::Framed => { + let frame = frame_alloc().unwrap(); + ppn = frame.ppn; + self.data_frames.insert(vpn, frame); + } + } + let pte_flags = PTEFlags::from_bits(self.map_perm.bits).unwrap(); + page_table.map(vpn, ppn, pte_flags); + } + + pub fn unmap_one(&mut self, page_table: &mut PageTable, vpn: VirtPageNum) { + #[allow(clippy::single_match)] + match self.map_type { + MapType::Framed => { + self.data_frames.remove(&vpn); + } + _ => {} + } + page_table.unmap(vpn); + } + pub fn map(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.map_one(page_table, vpn); + } + } + pub fn unmap(&mut self, page_table: &mut PageTable) { + for vpn in self.vpn_range { + self.unmap_one(page_table, vpn); + } + } + /// data: start-aligned but maybe with shorter length + /// assume that all frames were cleared before + pub fn copy_data(&mut self, page_table: &mut PageTable, data: &[u8]) { + assert_eq!(self.map_type, MapType::Framed); + let mut start: usize = 0; + let mut current_vpn = self.vpn_range.get_start(); + let len = data.len(); + loop { + let src = &data[start..len.min(start + PAGE_SIZE)]; + let dst = &mut page_table + .translate(current_vpn) + .unwrap() + .ppn() + .get_bytes_array()[..src.len()]; + dst.copy_from_slice(src); + start += PAGE_SIZE; + if start >= len { + break; + } + current_vpn.step(); + } + } +} + +#[derive(Copy, Clone, PartialEq, Debug)] +/// map type for memory set: identical or framed +pub enum MapType { + Identical, + Framed, +} + +bitflags! { + /// map permission corresponding to that in pte: `R W X U` + pub struct MapPermission: u8 { + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + } +} + +#[allow(unused)] +pub fn remap_test() { + let mut kernel_space = KERNEL_SPACE.exclusive_access(); + let mid_text: VirtAddr = ((stext as usize + etext as usize) / 2).into(); + let mid_rodata: VirtAddr = ((srodata as usize + erodata as usize) / 2).into(); + let mid_data: VirtAddr = ((sdata as usize + edata as usize) / 2).into(); + assert!(!kernel_space + .page_table + .translate(mid_text.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_rodata.floor()) + .unwrap() + .writable()); + assert!(!kernel_space + .page_table + .translate(mid_data.floor()) + .unwrap() + .executable()); + info!("remap_test passed!"); +} diff --git a/os8-ref/src/mm/mod.rs b/os8-ref/src/mm/mod.rs new file mode 100644 index 0000000..211cc2f --- /dev/null +++ b/os8-ref/src/mm/mod.rs @@ -0,0 +1,29 @@ +//! Memory management implementation +//! +//! SV39 page-based virtual-memory architecture for RV64 systems, and +//! everything about memory management, like frame allocator, page table, +//! map area and memory set, is implemented here. +//! +//! Every task or process has a memory_set to control its virtual memory. + + +mod address; +mod frame_allocator; +mod heap_allocator; +mod memory_set; +mod page_table; + +pub use address::{PhysAddr, PhysPageNum, VirtAddr, VirtPageNum}; +pub use address::{StepByOne, VPNRange}; +pub use frame_allocator::{frame_alloc, frame_dealloc, FrameTracker}; +pub use memory_set::{remap_test, kernel_token}; +pub use memory_set::{MapPermission, MemorySet, KERNEL_SPACE}; +pub use page_table::{translated_byte_buffer, translated_refmut, translated_ref, translated_str, PageTableEntry}; +pub use page_table::{PTEFlags, PageTable, UserBuffer}; + +/// initiate heap allocator, frame allocator and kernel space +pub fn init() { + heap_allocator::init_heap(); + frame_allocator::init_frame_allocator(); + KERNEL_SPACE.exclusive_access().activate(); +} diff --git a/os8-ref/src/mm/page_table.rs b/os8-ref/src/mm/page_table.rs new file mode 100644 index 0000000..dbb195a --- /dev/null +++ b/os8-ref/src/mm/page_table.rs @@ -0,0 +1,260 @@ +//! Implementation of [`PageTableEntry`] and [`PageTable`]. + +use super::{frame_alloc, FrameTracker, PhysAddr, PhysPageNum, StepByOne, VirtAddr, VirtPageNum}; +use alloc::string::String; +use alloc::vec; +use alloc::vec::Vec; +use bitflags::*; + +bitflags! { + /// page table entry flags + pub struct PTEFlags: u8 { + const V = 1 << 0; + const R = 1 << 1; + const W = 1 << 2; + const X = 1 << 3; + const U = 1 << 4; + const G = 1 << 5; + const A = 1 << 6; + const D = 1 << 7; + } +} + +#[derive(Copy, Clone)] +#[repr(C)] +/// page table entry structure +pub struct PageTableEntry { + pub bits: usize, +} + +impl PageTableEntry { + pub fn new(ppn: PhysPageNum, flags: PTEFlags) -> Self { + PageTableEntry { + bits: ppn.0 << 10 | flags.bits as usize, + } + } + pub fn empty() -> Self { + PageTableEntry { bits: 0 } + } + pub fn ppn(&self) -> PhysPageNum { + (self.bits >> 10 & ((1usize << 44) - 1)).into() + } + pub fn flags(&self) -> PTEFlags { + PTEFlags::from_bits(self.bits as u8).unwrap() + } + pub fn is_valid(&self) -> bool { + (self.flags() & PTEFlags::V) != PTEFlags::empty() + } + pub fn readable(&self) -> bool { + (self.flags() & PTEFlags::R) != PTEFlags::empty() + } + pub fn writable(&self) -> bool { + (self.flags() & PTEFlags::W) != PTEFlags::empty() + } + pub fn executable(&self) -> bool { + (self.flags() & PTEFlags::X) != PTEFlags::empty() + } +} + +/// page table structure +pub struct PageTable { + root_ppn: PhysPageNum, + frames: Vec, +} + +/// Assume that it won't oom when creating/mapping. +impl PageTable { + pub fn new() -> Self { + let frame = frame_alloc().unwrap(); + PageTable { + root_ppn: frame.ppn, + frames: vec![frame], + } + } + /// Temporarily used to get arguments from user space. + pub fn from_token(satp: usize) -> Self { + Self { + root_ppn: PhysPageNum::from(satp & ((1usize << 44) - 1)), + frames: Vec::new(), + } + } + fn find_pte_create(&mut self, vpn: VirtPageNum) -> Option<&mut PageTableEntry> { + let mut idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&mut PageTableEntry> = None; + for (i, idx) in idxs.iter_mut().enumerate() { + let pte = &mut ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + let frame = frame_alloc().unwrap(); + *pte = PageTableEntry::new(frame.ppn, PTEFlags::V); + self.frames.push(frame); + } + ppn = pte.ppn(); + } + result + } + fn find_pte(&self, vpn: VirtPageNum) -> Option<&PageTableEntry> { + let idxs = vpn.indexes(); + let mut ppn = self.root_ppn; + let mut result: Option<&PageTableEntry> = None; + for (i, idx) in idxs.iter().enumerate() { + let pte = &ppn.get_pte_array()[*idx]; + if i == 2 { + result = Some(pte); + break; + } + if !pte.is_valid() { + return None; + } + ppn = pte.ppn(); + } + result + } + #[allow(unused)] + pub fn map(&mut self, vpn: VirtPageNum, ppn: PhysPageNum, flags: PTEFlags) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(!pte.is_valid(), "vpn {:?} is mapped before mapping", vpn); + *pte = PageTableEntry::new(ppn, flags | PTEFlags::V); + } + #[allow(unused)] + pub fn unmap(&mut self, vpn: VirtPageNum) { + let pte = self.find_pte_create(vpn).unwrap(); + assert!(pte.is_valid(), "vpn {:?} is invalid before unmapping", vpn); + *pte = PageTableEntry::empty(); + } + pub fn translate(&self, vpn: VirtPageNum) -> Option { + self.find_pte(vpn).copied() + } + pub fn translate_va(&self, va: VirtAddr) -> Option { + self.find_pte(va.clone().floor()).map(|pte| { + //println!("translate_va:va = {:?}", va); + let aligned_pa: PhysAddr = pte.ppn().into(); + //println!("translate_va:pa_align = {:?}", aligned_pa); + let offset = va.page_offset(); + let aligned_pa_usize: usize = aligned_pa.into(); + (aligned_pa_usize + offset).into() + }) + } + pub fn token(&self) -> usize { + 8usize << 60 | self.root_ppn.0 + } +} + +/// translate a pointer to a mutable u8 Vec through page table +pub fn translated_byte_buffer(token: usize, ptr: *const u8, len: usize) -> Vec<&'static mut [u8]> { + let page_table = PageTable::from_token(token); + let mut start = ptr as usize; + let end = start + len; + let mut v = Vec::new(); + while start < end { + let start_va = VirtAddr::from(start); + let mut vpn = start_va.floor(); + let ppn = page_table.translate(vpn).unwrap().ppn(); + vpn.step(); + let mut end_va: VirtAddr = vpn.into(); + end_va = end_va.min(VirtAddr::from(end)); + if end_va.page_offset() == 0 { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..]); + } else { + v.push(&mut ppn.get_bytes_array()[start_va.page_offset()..end_va.page_offset()]); + } + start = end_va.into(); + } + v +} + +pub fn translated_str(token: usize, ptr: *const u8) -> String { + let page_table = PageTable::from_token(token); + let mut string = String::new(); + let mut va = ptr as usize; + loop { + let ch: u8 = *(page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut()); + if ch == 0 { + break; + } else { + string.push(ch as char); + va += 1; + } + } + string +} + +pub fn translated_ref(token: usize, ptr: *const T) -> &'static T { + let page_table = PageTable::from_token(token); + page_table.translate_va(VirtAddr::from(ptr as usize)).unwrap().get_mut() +} + +pub fn translated_refmut(token: usize, ptr: *mut T) -> &'static mut T { + //println!("into translated_refmut!"); + let page_table = PageTable::from_token(token); + let va = ptr as usize; + //println!("translated_refmut: before translate_va"); + page_table + .translate_va(VirtAddr::from(va)) + .unwrap() + .get_mut() +} + +/// An abstraction over a buffer passed from user space to kernel space +pub struct UserBuffer { + pub buffers: Vec<&'static mut [u8]>, +} + +impl UserBuffer { + /// Constuct a UserBuffer + pub fn new(buffers: Vec<&'static mut [u8]>) -> Self { + Self { buffers } + } + /// Get the length of a UserBuffer + pub fn len(&self) -> usize { + let mut total: usize = 0; + for b in self.buffers.iter() { + total += b.len(); + } + total + } +} + +impl IntoIterator for UserBuffer { + type Item = *mut u8; + type IntoIter = UserBufferIterator; + fn into_iter(self) -> Self::IntoIter { + UserBufferIterator { + buffers: self.buffers, + current_buffer: 0, + current_idx: 0, + } + } +} + +// An iterator over a UserBuffer +pub struct UserBufferIterator { + buffers: Vec<&'static mut [u8]>, + current_buffer: usize, + current_idx: usize, +} + +impl Iterator for UserBufferIterator { + type Item = *mut u8; + fn next(&mut self) -> Option { + if self.current_buffer >= self.buffers.len() { + None + } else { + let r = &mut self.buffers[self.current_buffer][self.current_idx] as *mut _; + if self.current_idx + 1 == self.buffers[self.current_buffer].len() { + self.current_idx = 0; + self.current_buffer += 1; + } else { + self.current_idx += 1; + } + Some(r) + } + } +} diff --git a/os8-ref/src/sbi.rs b/os8-ref/src/sbi.rs new file mode 100644 index 0000000..4af7620 --- /dev/null +++ b/os8-ref/src/sbi.rs @@ -0,0 +1,45 @@ +//! SBI call wrappers + +#![allow(unused)] + +const SBI_SET_TIMER: usize = 0; +const SBI_CONSOLE_PUTCHAR: usize = 1; +const SBI_CONSOLE_GETCHAR: usize = 2; +const SBI_SHUTDOWN: usize = 8; + +#[inline(always)] +/// general sbi call +fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize { + let mut ret; + unsafe { + core::arch::asm!( + "ecall", + inlateout("x10") arg0 => ret, + in("x11") arg1, + in("x12") arg2, + in("x17") which, + ); + } + ret +} + +/// use sbi call to set timer +pub fn set_timer(timer: usize) { + sbi_call(SBI_SET_TIMER, timer, 0, 0); +} + +/// use sbi call to putchar in console (qemu uart handler) +pub fn console_putchar(c: usize) { + sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0); +} + +/// use sbi call to getchar from console (qemu uart handler) +pub fn console_getchar() -> usize { + sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0) +} + +/// use sbi call to shutdown the kernel +pub fn shutdown() -> ! { + sbi_call(SBI_SHUTDOWN, 0, 0, 0); + panic!("It should shutdown!"); +} diff --git a/os8-ref/src/sync/condvar.rs b/os8-ref/src/sync/condvar.rs new file mode 100644 index 0000000..f96cd91 --- /dev/null +++ b/os8-ref/src/sync/condvar.rs @@ -0,0 +1,39 @@ +use crate::sync::{Mutex, UPSafeCell}; +use crate::task::{add_task, block_current_and_run_next, current_task, TaskControlBlock}; +use alloc::{collections::VecDeque, sync::Arc}; + +pub struct Condvar { + pub inner: UPSafeCell, +} + +pub struct CondvarInner { + pub wait_queue: VecDeque>, +} + +impl Condvar { + pub fn new() -> Self { + Self { + inner: unsafe { + UPSafeCell::new(CondvarInner { + wait_queue: VecDeque::new(), + }) + }, + } + } + + pub fn signal(&self) { + let mut inner = self.inner.exclusive_access(); + if let Some(task) = inner.wait_queue.pop_front() { + add_task(task); + } + } + + pub fn wait(&self, mutex: Arc) { + mutex.unlock(); + let mut inner = self.inner.exclusive_access(); + inner.wait_queue.push_back(current_task().unwrap()); + drop(inner); + block_current_and_run_next(); + mutex.lock(); + } +} diff --git a/os8-ref/src/sync/mod.rs b/os8-ref/src/sync/mod.rs new file mode 100644 index 0000000..1516557 --- /dev/null +++ b/os8-ref/src/sync/mod.rs @@ -0,0 +1,11 @@ +//! Synchronization and interior mutability primitives + +mod condvar; +mod mutex; +mod semaphore; +mod up; + +pub use condvar::Condvar; +pub use mutex::{Mutex, MutexBlocking, MutexSpin}; +pub use semaphore::Semaphore; +pub use up::UPSafeCell; diff --git a/os8-ref/src/sync/mutex.rs b/os8-ref/src/sync/mutex.rs new file mode 100644 index 0000000..be58f79 --- /dev/null +++ b/os8-ref/src/sync/mutex.rs @@ -0,0 +1,88 @@ +use super::UPSafeCell; +use crate::task::TaskControlBlock; +use crate::task::{add_task, current_task}; +use crate::task::{block_current_and_run_next, suspend_current_and_run_next}; +use alloc::{collections::VecDeque, sync::Arc}; + +pub trait Mutex: Sync + Send { + fn lock(&self); + fn unlock(&self); +} + +pub struct MutexSpin { + locked: UPSafeCell, +} + +impl MutexSpin { + pub fn new() -> Self { + Self { + locked: unsafe { UPSafeCell::new(false) }, + } + } +} + +impl Mutex for MutexSpin { + fn lock(&self) { + loop { + let mut locked = self.locked.exclusive_access(); + if *locked { + drop(locked); + suspend_current_and_run_next(); + continue; + } else { + *locked = true; + return; + } + } + } + + fn unlock(&self) { + let mut locked = self.locked.exclusive_access(); + *locked = false; + } +} + +pub struct MutexBlocking { + inner: UPSafeCell, +} + +pub struct MutexBlockingInner { + locked: bool, + wait_queue: VecDeque>, +} + +impl MutexBlocking { + pub fn new() -> Self { + Self { + inner: unsafe { + UPSafeCell::new(MutexBlockingInner { + locked: false, + wait_queue: VecDeque::new(), + }) + }, + } + } +} + +impl Mutex for MutexBlocking { + fn lock(&self) { + let mut mutex_inner = self.inner.exclusive_access(); + if mutex_inner.locked { + mutex_inner.wait_queue.push_back(current_task().unwrap()); + drop(mutex_inner); + block_current_and_run_next(); + } else { + mutex_inner.locked = true; + } + } + + fn unlock(&self) { + let mut mutex_inner = self.inner.exclusive_access(); + assert!(mutex_inner.locked); + if let Some(waking_task) = mutex_inner.wait_queue.pop_front() { + add_task(waking_task); + } else { + mutex_inner.locked = false; + } + } +} diff --git a/os8-ref/src/sync/semaphore.rs b/os8-ref/src/sync/semaphore.rs new file mode 100644 index 0000000..7f3870f --- /dev/null +++ b/os8-ref/src/sync/semaphore.rs @@ -0,0 +1,45 @@ +use crate::sync::UPSafeCell; +use crate::task::{add_task, block_current_and_run_next, current_task, TaskControlBlock}; +use alloc::{collections::VecDeque, sync::Arc}; + +pub struct Semaphore { + pub inner: UPSafeCell, +} + +pub struct SemaphoreInner { + pub count: isize, + pub wait_queue: VecDeque>, +} + +impl Semaphore { + pub fn new(res_count: usize) -> Self { + Self { + inner: unsafe { + UPSafeCell::new(SemaphoreInner { + count: res_count as isize, + wait_queue: VecDeque::new(), + }) + }, + } + } + + pub fn up(&self) { + let mut inner = self.inner.exclusive_access(); + inner.count += 1; + if inner.count <= 0 { + if let Some(task) = inner.wait_queue.pop_front() { + add_task(task); + } + } + } + + pub fn down(&self) { + let mut inner = self.inner.exclusive_access(); + inner.count -= 1; + if inner.count < 0 { + inner.wait_queue.push_back(current_task().unwrap()); + drop(inner); + block_current_and_run_next(); + } + } +} diff --git a/os8-ref/src/sync/up.rs b/os8-ref/src/sync/up.rs new file mode 100644 index 0000000..039b039 --- /dev/null +++ b/os8-ref/src/sync/up.rs @@ -0,0 +1,31 @@ +//! Uniprocessor interior mutability primitives + +use core::cell::{RefCell, RefMut}; + +/// Wrap a static data structure inside it so that we are +/// able to access it without any `unsafe`. +/// +/// We should only use it in uniprocessor. +/// +/// In order to get mutable reference of inner data, call +/// `exclusive_access`. +pub struct UPSafeCell { + /// inner data + inner: RefCell, +} + +unsafe impl Sync for UPSafeCell {} + +impl UPSafeCell { + /// User is responsible to guarantee that inner struct is only used in + /// uniprocessor. + pub unsafe fn new(value: T) -> Self { + Self { + inner: RefCell::new(value), + } + } + /// Panic if the data has been borrowed. + pub fn exclusive_access(&self) -> RefMut<'_, T> { + self.inner.borrow_mut() + } +} diff --git a/os8-ref/src/syscall/fs.rs b/os8-ref/src/syscall/fs.rs new file mode 100644 index 0000000..1259ee2 --- /dev/null +++ b/os8-ref/src/syscall/fs.rs @@ -0,0 +1,114 @@ +//! File and filesystem-related syscalls + +use crate::fs::make_pipe; +use crate::fs::open_file; +use crate::fs::OpenFlags; +use crate::fs::Stat; +use crate::mm::translated_byte_buffer; +use crate::mm::translated_refmut; +use crate::mm::translated_str; +use crate::mm::UserBuffer; +use crate::task::current_process; +use crate::task::current_user_token; +use alloc::sync::Arc; + +pub fn sys_write(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let process = current_process(); + let inner = process.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release current process TCB manually to avoid multi-borrow + drop(inner); + file.write(UserBuffer::new(translated_byte_buffer(token, buf, len))) as isize + } else { + -1 + } +} + +pub fn sys_read(fd: usize, buf: *const u8, len: usize) -> isize { + let token = current_user_token(); + let process = current_process(); + let inner = process.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if let Some(file) = &inner.fd_table[fd] { + let file = file.clone(); + // release current process TCB manually to avoid multi-borrow + drop(inner); + file.read(UserBuffer::new(translated_byte_buffer(token, buf, len))) as isize + } else { + -1 + } +} + +pub fn sys_open(path: *const u8, flags: u32) -> isize { + let process = current_process(); + let token = current_user_token(); + let path = translated_str(token, path); + if let Some(inode) = open_file(path.as_str(), OpenFlags::from_bits(flags).unwrap()) { + let mut inner = process.inner_exclusive_access(); + let fd = inner.alloc_fd(); + inner.fd_table[fd] = Some(inode); + fd as isize + } else { + -1 + } +} + +pub fn sys_close(fd: usize) -> isize { + let process = current_process(); + let mut inner = process.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + inner.fd_table[fd].take(); + 0 +} + +pub fn sys_pipe(pipe: *mut usize) -> isize { + let process = current_process(); + let token = current_user_token(); + let mut inner = process.inner_exclusive_access(); + let (pipe_read, pipe_write) = make_pipe(); + let read_fd = inner.alloc_fd(); + inner.fd_table[read_fd] = Some(pipe_read); + let write_fd = inner.alloc_fd(); + inner.fd_table[write_fd] = Some(pipe_write); + *translated_refmut(token, pipe) = read_fd; + *translated_refmut(token, unsafe { pipe.add(1) }) = write_fd; + 0 +} + +pub fn sys_dup(fd: usize) -> isize { + let process = current_process(); + let mut inner = process.inner_exclusive_access(); + if fd >= inner.fd_table.len() { + return -1; + } + if inner.fd_table[fd].is_none() { + return -1; + } + let new_fd = inner.alloc_fd(); + inner.fd_table[new_fd] = Some(Arc::clone(inner.fd_table[fd].as_ref().unwrap())); + new_fd as isize +} + +pub fn sys_fstat(_fd: usize, _st: *mut Stat) -> isize { + -1 +} + +pub fn sys_linkat(_old_name: *const u8, _new_name: *const u8) -> isize { + -1 +} + +pub fn sys_unlinkat(_name: *const u8) -> isize { + -1 +} diff --git a/os8-ref/src/syscall/mod.rs b/os8-ref/src/syscall/mod.rs new file mode 100644 index 0000000..509ff1e --- /dev/null +++ b/os8-ref/src/syscall/mod.rs @@ -0,0 +1,100 @@ +//! Implementation of syscalls +//! +//! The single entry point to all system calls, [`syscall()`], is called +//! whenever userspace wishes to perform a system call using the `ecall` +//! instruction. In this case, the processor raises an 'Environment call from +//! U-mode' exception, which is handled as one of the cases in +//! [`crate::trap::trap_handler`]. +//! +//! For clarity, each single syscall is implemented as its own function, named +//! `sys_` then the name of the syscall. You can find functions like this in +//! submodules, and you should also implement syscalls this way. + +const SYSCALL_DUP: usize = 24; +const SYSCALL_UNLINKAT: usize = 35; +const SYSCALL_LINKAT: usize = 37; +const SYSCALL_OPEN: usize = 56; +const SYSCALL_CLOSE: usize = 57; +const SYSCALL_PIPE: usize = 59; +const SYSCALL_READ: usize = 63; +const SYSCALL_WRITE: usize = 64; +const SYSCALL_FSTAT: usize = 80; +const SYSCALL_EXIT: usize = 93; +const SYSCALL_SLEEP: usize = 101; +const SYSCALL_YIELD: usize = 124; +const SYSCALL_GET_TIME: usize = 169; +const SYSCALL_GETPID: usize = 172; +const SYSCALL_GETTID: usize = 178; +const SYSCALL_FORK: usize = 220; +const SYSCALL_EXEC: usize = 221; +const SYSCALL_WAITPID: usize = 260; +const SYSCALL_SPAWN: usize = 400; +const SYSCALL_MUNMAP: usize = 215; +const SYSCALL_MMAP: usize = 222; +const SYSCALL_SET_PRIORITY: usize = 140; +const SYSCALL_TASK_INFO: usize = 410; +const SYSCALL_THREAD_CREATE: usize = 460; +const SYSCALL_WAITTID: usize = 462; +const SYSCALL_MUTEX_CREATE: usize = 463; +const SYSCALL_MUTEX_LOCK: usize = 464; +const SYSCALL_MUTEX_UNLOCK: usize = 466; +const SYSCALL_SEMAPHORE_CREATE: usize = 467; +const SYSCALL_SEMAPHORE_UP: usize = 468; +const SYSCALL_ENABLE_DEADLOCK_DETECT: usize = 469; +const SYSCALL_SEMAPHORE_DOWN: usize = 470; +const SYSCALL_CONDVAR_CREATE: usize = 471; +const SYSCALL_CONDVAR_SIGNAL: usize = 472; +const SYSCALL_CONDVAR_WAIT: usize = 473; + +mod fs; +pub mod process; +mod sync; +mod thread; + +use crate::fs::Stat; +use fs::*; +use process::*; +use sync::*; +use thread::*; + +/// handle syscall exception with `syscall_id` and other arguments +pub fn syscall(syscall_id: usize, args: [usize; 4]) -> isize { + match syscall_id { + SYSCALL_DUP => sys_dup(args[0]), + SYSCALL_LINKAT => sys_linkat(args[1] as *const u8, args[3] as *const u8), + SYSCALL_UNLINKAT => sys_unlinkat(args[1] as *const u8), + SYSCALL_OPEN => sys_open(args[1] as *const u8, args[2] as u32), + SYSCALL_CLOSE => sys_close(args[0]), + SYSCALL_PIPE => sys_pipe(args[0] as *mut usize), + SYSCALL_READ => sys_read(args[0], args[1] as *const u8, args[2]), + SYSCALL_WRITE => sys_write(args[0], args[1] as *const u8, args[2]), + SYSCALL_FSTAT => sys_fstat(args[0], args[1] as *mut Stat), + SYSCALL_EXIT => sys_exit(args[0] as i32), + SYSCALL_SLEEP => sys_sleep(args[0]), + SYSCALL_YIELD => sys_yield(), + SYSCALL_GETPID => sys_getpid(), + SYSCALL_GETTID => sys_gettid(), + SYSCALL_FORK => sys_fork(), + SYSCALL_EXEC => sys_exec(args[0] as *const u8, args[1] as *const usize), + SYSCALL_WAITPID => sys_waitpid(args[0] as isize, args[1] as *mut i32), + SYSCALL_GET_TIME => sys_get_time(args[0] as *mut TimeVal, args[1]), + SYSCALL_MMAP => sys_mmap(args[0], args[1], args[2]), + SYSCALL_MUNMAP => sys_munmap(args[0], args[1]), + SYSCALL_SET_PRIORITY => sys_set_priority(args[0] as isize), + SYSCALL_TASK_INFO => sys_task_info(args[0] as *mut TaskInfo), + SYSCALL_SPAWN => sys_spawn(args[0] as *const u8), + SYSCALL_THREAD_CREATE => sys_thread_create(args[0], args[1]), + SYSCALL_WAITTID => sys_waittid(args[0]) as isize, + SYSCALL_MUTEX_CREATE => sys_mutex_create(args[0] == 1), + SYSCALL_MUTEX_LOCK => sys_mutex_lock(args[0]), + SYSCALL_MUTEX_UNLOCK => sys_mutex_unlock(args[0]), + SYSCALL_SEMAPHORE_CREATE => sys_semaphore_create(args[0]), + SYSCALL_SEMAPHORE_UP => sys_semaphore_up(args[0]), + SYSCALL_ENABLE_DEADLOCK_DETECT => sys_enable_deadlock_detect(args[0]), + SYSCALL_SEMAPHORE_DOWN => sys_semaphore_down(args[0]), + SYSCALL_CONDVAR_CREATE => sys_condvar_create(args[0]), + SYSCALL_CONDVAR_SIGNAL => sys_condvar_signal(args[0]), + SYSCALL_CONDVAR_WAIT => sys_condvar_wait(args[0], args[1]), + _ => panic!("Unsupported syscall_id: {}", syscall_id), + } +} diff --git a/os8-ref/src/syscall/process.rs b/os8-ref/src/syscall/process.rs new file mode 100644 index 0000000..87fade0 --- /dev/null +++ b/os8-ref/src/syscall/process.rs @@ -0,0 +1,158 @@ +//! Process management syscalls + +use crate::config::MAX_SYSCALL_NUM; +use crate::fs::{open_file, OpenFlags}; +use crate::mm::{translated_ref, translated_refmut, translated_str, PageTable, VirtAddr}; +use crate::task::{ + current_process, current_task, current_user_token, exit_current_and_run_next, + suspend_current_and_run_next, TaskStatus, +}; +use crate::timer::get_time_us; +use alloc::string::String; +use alloc::sync::Arc; +use alloc::vec::Vec; + +#[repr(C)] +#[derive(Debug)] +pub struct TimeVal { + pub sec: usize, + pub usec: usize, +} + +#[derive(Clone, Copy)] +pub struct TaskInfo { + pub status: TaskStatus, + pub syscall_times: [u32; MAX_SYSCALL_NUM], + pub time: usize, +} + +pub fn sys_exit(exit_code: i32) -> ! { + // debug!("[kernel] Application exited with code {}", exit_code); + exit_current_and_run_next(exit_code); + panic!("Unreachable in sys_exit!"); +} + +/// current task gives up resources for other tasks +pub fn sys_yield() -> isize { + suspend_current_and_run_next(); + 0 +} + +pub fn sys_getpid() -> isize { + current_task().unwrap().process.upgrade().unwrap().getpid() as isize +} + +/// Syscall Fork which returns 0 for child process and child_pid for parent process +pub fn sys_fork() -> isize { + let current_process = current_process(); + let new_process = current_process.fork(); + let new_pid = new_process.getpid(); + // modify trap context of new_task, because it returns immediately after switching + let new_process_inner = new_process.inner_exclusive_access(); + let task = new_process_inner.tasks[0].as_ref().unwrap(); + let trap_cx = task.inner_exclusive_access().get_trap_cx(); + // we do not have to move to next instruction since we have done it before + // for child process, fork returns 0 + trap_cx.x[10] = 0; + new_pid as isize +} + +/// Syscall Exec which accepts the elf path +pub fn sys_exec(path: *const u8, mut args: *const usize) -> isize { + let token = current_user_token(); + let path = translated_str(token, path); + let mut args_vec: Vec = Vec::new(); + loop { + let arg_str_ptr = *translated_ref(token, args); + if arg_str_ptr == 0 { + break; + } + args_vec.push(translated_str(token, arg_str_ptr as *const u8)); + unsafe { + args = args.add(1); + } + } + if let Some(app_inode) = open_file(path.as_str(), OpenFlags::RDONLY) { + let all_data = app_inode.read_all(); + let process = current_process(); + let argc = args_vec.len(); + process.exec(all_data.as_slice(), args_vec); + argc as isize + } else { + -1 + } +} + +/// If there is not a child process whose pid is same as given, return -1. +/// Else if there is a child process but it is still running, return -2. +pub fn sys_waitpid(pid: isize, exit_code_ptr: *mut i32) -> isize { + let process = current_process(); + // find a child process + + // ---- access current TCB exclusively + let mut inner = process.inner_exclusive_access(); + if !inner + .children + .iter() + .any(|p| pid == -1 || pid as usize == p.getpid()) + { + return -1; + // ---- release current PCB + } + let pair = inner.children.iter().enumerate().find(|(_, p)| { + // ++++ temporarily access child PCB lock exclusively + p.inner_exclusive_access().is_zombie && (pid == -1 || pid as usize == p.getpid()) + // ++++ release child PCB + }); + if let Some((idx, _)) = pair { + let child = inner.children.remove(idx); + // confirm that child will be deallocated after removing from children list + assert_eq!(Arc::strong_count(&child), 1); + let found_pid = child.getpid(); + // ++++ temporarily access child TCB exclusively + let exit_code = child.inner_exclusive_access().exit_code; + // ++++ release child PCB + *translated_refmut(inner.memory_set.token(), exit_code_ptr) = exit_code; + found_pid as isize + } else { + -2 + } + // ---- release current PCB lock automatically +} + +pub fn sys_get_time(_ts: *mut TimeVal, _tz: usize) -> isize { + let _us = get_time_us(); + // unsafe { + // *ts = TimeVal { + // sec: us / 1_000_000, + // usec: us % 1_000_000, + // }; + // } + *translated_refmut(current_user_token(), _ts) = TimeVal { + sec: _us / 1_000_000, + usec: _us % 1_000_000, + }; + 0 +} + +pub fn sys_task_info(_ti: *mut TaskInfo) -> isize { + -1 +} + +pub fn sys_set_priority(_prio: isize) -> isize { + -1 +} + +pub fn sys_mmap(_start: usize, _len: usize, _port: usize) -> isize { + -1 +} + +pub fn sys_munmap(_start: usize, _len: usize) -> isize { + -1 +} + +// +// ALERT: 注意在实现 SPAWN 时不需要复制父进程地址空间，SPAWN != FORK + EXEC +pub fn sys_spawn(_path: *const u8) -> isize { + -1 +} diff --git a/os8-ref/src/syscall/sync.rs b/os8-ref/src/syscall/sync.rs new file mode 100644 index 0000000..57fc2fc --- /dev/null +++ b/os8-ref/src/syscall/sync.rs @@ -0,0 +1,143 @@ +use crate::sync::{Condvar, Mutex, MutexBlocking, MutexSpin, Semaphore}; +use crate::task::{block_current_and_run_next, current_process, current_task}; +use crate::timer::{add_timer, get_time_ms}; +use alloc::sync::Arc; + +pub fn sys_sleep(ms: usize) -> isize { + let expire_ms = get_time_ms() + ms; + let task = current_task().unwrap(); + add_timer(expire_ms, task); + block_current_and_run_next(); + 0 +} + +// LAB5 HINT: you might need to maintain data structures used for deadlock detection +// during sys_mutex_* and sys_semaphore_* syscalls +pub fn sys_mutex_create(blocking: bool) -> isize { + let process = current_process(); + let mutex: Option> = if !blocking { + Some(Arc::new(MutexSpin::new())) + } else { + Some(Arc::new(MutexBlocking::new())) + }; + let mut process_inner = process.inner_exclusive_access(); + if let Some(id) = process_inner + .mutex_list + .iter() + .enumerate() + .find(|(_, item)| item.is_none()) + .map(|(id, _)| id) + { + process_inner.mutex_list[id] = mutex; + id as isize + } else { + process_inner.mutex_list.push(mutex); + process_inner.mutex_list.len() as isize - 1 + } +} + +// LAB5 HINT: Return -0xDEAD if deadlock is detected +pub fn sys_mutex_lock(mutex_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let mutex = Arc::clone(process_inner.mutex_list[mutex_id].as_ref().unwrap()); + drop(process_inner); + drop(process); + mutex.lock(); + 0 +} + +pub fn sys_mutex_unlock(mutex_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let mutex = Arc::clone(process_inner.mutex_list[mutex_id].as_ref().unwrap()); + drop(process_inner); + drop(process); + mutex.unlock(); + 0 +} + +pub fn sys_semaphore_create(res_count: usize) -> isize { + let process = current_process(); + let mut process_inner = process.inner_exclusive_access(); + let id = if let Some(id) = process_inner + .semaphore_list + .iter() + .enumerate() + .find(|(_, item)| item.is_none()) + .map(|(id, _)| id) + { + process_inner.semaphore_list[id] = Some(Arc::new(Semaphore::new(res_count))); + id + } else { + process_inner + .semaphore_list + .push(Some(Arc::new(Semaphore::new(res_count)))); + process_inner.semaphore_list.len() - 1 + }; + id as isize +} + +pub fn sys_semaphore_up(sem_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let sem = Arc::clone(process_inner.semaphore_list[sem_id].as_ref().unwrap()); + drop(process_inner); + sem.up(); + 0 +} + +// LAB5 HINT: Return -0xDEAD if deadlock is detected +pub fn sys_semaphore_down(sem_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let sem = Arc::clone(process_inner.semaphore_list[sem_id].as_ref().unwrap()); + drop(process_inner); + sem.down(); + 0 +} + +pub fn sys_condvar_create(_arg: usize) -> isize { + let process = current_process(); + let mut process_inner = process.inner_exclusive_access(); + let id = if let Some(id) = process_inner + .condvar_list + .iter() + .enumerate() + .find(|(_, item)| item.is_none()) + .map(|(id, _)| id) + { + process_inner.condvar_list[id] = Some(Arc::new(Condvar::new())); + id + } else { + process_inner + .condvar_list + .push(Some(Arc::new(Condvar::new()))); + process_inner.condvar_list.len() - 1 + }; + id as isize +} + +pub fn sys_condvar_signal(condvar_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let condvar = Arc::clone(process_inner.condvar_list[condvar_id].as_ref().unwrap()); + drop(process_inner); + condvar.signal(); + 0 +} + +pub fn sys_condvar_wait(condvar_id: usize, mutex_id: usize) -> isize { + let process = current_process(); + let process_inner = process.inner_exclusive_access(); + let condvar = Arc::clone(process_inner.condvar_list[condvar_id].as_ref().unwrap()); + let mutex = Arc::clone(process_inner.mutex_list[mutex_id].as_ref().unwrap()); + drop(process_inner); + condvar.wait(mutex); + 0 +} + +// LAB5 YOUR JOB: Implement deadlock detection, but might not all in this syscall +pub fn sys_enable_deadlock_detect(_enabled: usize) -> isize { + -1 +} diff --git a/os8-ref/src/syscall/thread.rs b/os8-ref/src/syscall/thread.rs new file mode 100644 index 0000000..bfba822 --- /dev/null +++ b/os8-ref/src/syscall/thread.rs @@ -0,0 +1,86 @@ +use crate::{ + mm::kernel_token, + task::{add_task, current_task, TaskControlBlock}, + trap::{trap_handler, TrapContext}, +}; +use alloc::sync::Arc; + +pub fn sys_thread_create(entry: usize, arg: usize) -> isize { + let task = current_task().unwrap(); + let process = task.process.upgrade().unwrap(); + // create a new thread + let new_task = Arc::new(TaskControlBlock::new( + Arc::clone(&process), + task.inner_exclusive_access() + .res + .as_ref() + .unwrap() + .ustack_base, + true, + )); + let new_task_inner = new_task.inner_exclusive_access(); + let new_task_res = new_task_inner.res.as_ref().unwrap(); + let new_task_tid = new_task_res.tid; + let new_task_trap_cx = new_task_inner.get_trap_cx(); + *new_task_trap_cx = TrapContext::app_init_context( + entry, + new_task_res.ustack_top(), + kernel_token(), + new_task.kernel_stack.get_top(), + trap_handler as usize, + ); + (*new_task_trap_cx).x[10] = arg; + + let mut process_inner = process.inner_exclusive_access(); + // add new thread to current process + let tasks = &mut process_inner.tasks; + while tasks.len() < new_task_tid + 1 { + tasks.push(None); + } + tasks[new_task_tid] = Some(Arc::clone(&new_task)); + // add new task to scheduler + add_task(Arc::clone(&new_task)); + new_task_tid as isize +} + +pub fn sys_gettid() -> isize { + current_task() + .unwrap() + .inner_exclusive_access() + .res + .as_ref() + .unwrap() + .tid as isize +} + +/// thread does not exist, return -1 +/// thread has not exited yet, return -2 +/// otherwise, return thread's exit code +pub fn sys_waittid(tid: usize) -> i32 { + let task = current_task().unwrap(); + let process = task.process.upgrade().unwrap(); + let task_inner = task.inner_exclusive_access(); + let mut process_inner = process.inner_exclusive_access(); + // a thread cannot wait for itself + if task_inner.res.as_ref().unwrap().tid == tid { + return -1; + } + let mut exit_code: Option = None; + let waited_task = process_inner.tasks[tid].as_ref(); + if let Some(waited_task) = waited_task { + if let Some(waited_exit_code) = waited_task.inner_exclusive_access().exit_code { + exit_code = Some(waited_exit_code); + } + } else { + // waited thread does not exist + return -1; + } + if let Some(exit_code) = exit_code { + // dealloc the exited thread + process_inner.tasks[tid] = None; + exit_code + } else { + // waited thread has not exited + -2 + } +} diff --git a/os8-ref/src/task/context.rs b/os8-ref/src/task/context.rs new file mode 100644 index 0000000..44f9813 --- /dev/null +++ b/os8-ref/src/task/context.rs @@ -0,0 +1,33 @@ +//! Implementation of [`TaskContext`] + +use crate::trap::trap_return; + +#[derive(Copy, Clone)] +#[repr(C)] +/// task context structure containing some registers +pub struct TaskContext { + /// Ret position after task switching + pub ra: usize, + /// Stack pointer + pub sp: usize, + /// s0-11 register, callee saved + pub s: [usize; 12], +} + +impl TaskContext { + pub fn zero_init() -> Self { + Self { + ra: 0, + sp: 0, + s: [0; 12], + } + } + + pub fn goto_trap_return(kstack_ptr: usize) -> Self { + Self { + ra: trap_return as usize, + sp: kstack_ptr, + s: [0; 12], + } + } +} diff --git a/os8-ref/src/task/id.rs b/os8-ref/src/task/id.rs new file mode 100644 index 0000000..988cfa6 --- /dev/null +++ b/os8-ref/src/task/id.rs @@ -0,0 +1,262 @@ +use super::ProcessControlBlock; +use crate::config::{KERNEL_STACK_SIZE, PAGE_SIZE, TRAMPOLINE, TRAP_CONTEXT, USER_STACK_SIZE}; +use crate::mm::{MapPermission, PhysPageNum, VirtAddr, KERNEL_SPACE}; +use crate::sync::UPSafeCell; +use alloc::{ + sync::{Arc, Weak}, + vec::Vec, +}; +use lazy_static::*; + +pub struct RecycleAllocator { + current: usize, + recycled: Vec, +} + +impl RecycleAllocator { + pub fn new() -> Self { + RecycleAllocator { + current: 0, + recycled: Vec::new(), + } + } + pub fn alloc(&mut self) -> usize { + if let Some(id) = self.recycled.pop() { + id + } else { + self.current += 1; + self.current - 1 + } + } + pub fn dealloc(&mut self, id: usize) { + assert!(id < self.current); + assert!( + !self.recycled.iter().any(|i| *i == id), + "id {} has been deallocated!", + id + ); + self.recycled.push(id); + } +} + +lazy_static! { + static ref PID_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(RecycleAllocator::new()) }; + static ref KSTACK_ALLOCATOR: UPSafeCell = + unsafe { UPSafeCell::new(RecycleAllocator::new()) }; +} + +pub struct PidHandle(pub usize); + +pub fn pid_alloc() -> PidHandle { + PidHandle(PID_ALLOCATOR.exclusive_access().alloc()) +} + +impl Drop for PidHandle { + fn drop(&mut self) { + PID_ALLOCATOR.exclusive_access().dealloc(self.0); + } +} + +/// Return (bottom, top) of a kernel stack in kernel space. +pub fn kernel_stack_position(kstack_id: usize) -> (usize, usize) { + let top = TRAMPOLINE - kstack_id * (KERNEL_STACK_SIZE + PAGE_SIZE); + let bottom = top - KERNEL_STACK_SIZE; + (bottom, top) +} + +pub struct KernelStack(pub usize); + +pub fn kstack_alloc() -> KernelStack { + let kstack_id = KSTACK_ALLOCATOR.exclusive_access().alloc(); + let (kstack_bottom, kstack_top) = kernel_stack_position(kstack_id); + //println!("kstack_alloc kstack_bottom: {:#x?}, kstack_top: {:#x?}", kstack_bottom, kstack_top); + KERNEL_SPACE.exclusive_access().insert_framed_area( + kstack_bottom.into(), + kstack_top.into(), + MapPermission::R | MapPermission::W, + ); + KernelStack(kstack_id) +} + +impl Drop for KernelStack { + fn drop(&mut self) { + let (kernel_stack_bottom, _) = kernel_stack_position(self.0); + let kernel_stack_bottom_va: VirtAddr = kernel_stack_bottom.into(); + // let kernel_stack_bottom_pa: PhysAddr = kernel_stack_bottom.into(); + // println!("kstack_drop kstack_bottom: va: {:#x?}, pa: {:#x?}", kernel_stack_bottom_va, kernel_stack_bottom_pa); + KERNEL_SPACE + .exclusive_access() + .remove_area_with_start_vpn(kernel_stack_bottom_va.into()); + } +} + +impl KernelStack { + #[allow(unused)] + pub fn push_on_top(&self, value: T) -> *mut T + where + T: Sized, + { + let kernel_stack_top = self.get_top(); + let ptr_mut = (kernel_stack_top - core::mem::size_of::()) as *mut T; + unsafe { + *ptr_mut = value; + } + ptr_mut + } + pub fn get_top(&self) -> usize { + let (_, kernel_stack_top) = kernel_stack_position(self.0); + kernel_stack_top + } +} + +pub struct TaskUserRes { + pub tid: usize, + pub ustack_base: usize, + pub process: Weak, +} + +fn trap_cx_bottom_from_tid(tid: usize) -> usize { + TRAP_CONTEXT - tid * PAGE_SIZE +} + +fn ustack_bottom_from_tid(ustack_base: usize, tid: usize) -> usize { + ustack_base + tid * (PAGE_SIZE + USER_STACK_SIZE) +} + +impl TaskUserRes { + pub fn new( + process: Arc, + ustack_base: usize, + alloc_user_res: bool, + ) -> Self { + let tid = process.inner_exclusive_access().alloc_tid(); + let task_user_res = Self { + tid, + ustack_base, + process: Arc::downgrade(&process), + }; + if alloc_user_res { + task_user_res.alloc_user_res(); + } + task_user_res + } + + pub fn alloc_user_res(&self) { + let process = self.process.upgrade().unwrap(); + let mut process_inner = process.inner_exclusive_access(); + // alloc user stack + let ustack_bottom = ustack_bottom_from_tid(self.ustack_base, self.tid); + let ustack_top = ustack_bottom + USER_STACK_SIZE; + process_inner.memory_set.insert_framed_area( + ustack_bottom.into(), + ustack_top.into(), + MapPermission::R | MapPermission::W | MapPermission::U, + ); + // alloc trap_cx + let trap_cx_bottom = trap_cx_bottom_from_tid(self.tid); + let trap_cx_top = trap_cx_bottom + PAGE_SIZE; + process_inner.memory_set.insert_framed_area( + trap_cx_bottom.into(), + trap_cx_top.into(), + MapPermission::R | MapPermission::W, + ); + } + + fn dealloc_user_res(&self) { + // dealloc tid + let process = self.process.upgrade().unwrap(); + let mut process_inner = process.inner_exclusive_access(); + // dealloc ustack manually + let ustack_bottom_va: VirtAddr = ustack_bottom_from_tid(self.ustack_base, self.tid).into(); + process_inner + .memory_set + .remove_area_with_start_vpn(ustack_bottom_va.into()); + // dealloc trap_cx manually + let trap_cx_bottom_va: VirtAddr = trap_cx_bottom_from_tid(self.tid).into(); + process_inner + .memory_set + .remove_area_with_start_vpn(trap_cx_bottom_va.into()); + } + + #[allow(unused)] + pub fn alloc_tid(&mut self) { + self.tid = self + .process + .upgrade() + .unwrap() + .inner_exclusive_access() + .alloc_tid(); + } + + pub fn dealloc_tid(&self) { + let process = self.process.upgrade().unwrap(); + let mut process_inner = process.inner_exclusive_access(); + process_inner.dealloc_tid(self.tid); + } + + pub fn trap_cx_user_va(&self) -> usize { + trap_cx_bottom_from_tid(self.tid) + } + + pub fn trap_cx_ppn(&self) -> PhysPageNum { + let process = self.process.upgrade().unwrap(); + let process_inner = process.inner_exclusive_access(); + let trap_cx_bottom_va: VirtAddr = trap_cx_bottom_from_tid(self.tid).into(); + process_inner + .memory_set + .translate(trap_cx_bottom_va.into()) + .unwrap() + .ppn() + } + + pub fn ustack_base(&self) -> usize { + self.ustack_base + } + pub fn ustack_top(&self) -> usize { + ustack_bottom_from_tid(self.ustack_base, self.tid) + USER_STACK_SIZE + } +} + +impl Drop for TaskUserRes { + fn drop(&mut self) { + self.dealloc_tid(); + self.dealloc_user_res(); + } +} + +use alloc::alloc::{alloc, dealloc, Layout}; + +#[derive(Clone)] +pub struct KStack(usize); + +const STACK_SIZE: usize = 0x8000; + +impl KStack { + pub fn new() -> KStack { + let bottom = + unsafe { alloc(Layout::from_size_align(STACK_SIZE, STACK_SIZE).unwrap()) } as usize; + KStack(bottom) + } + + pub fn top(&self) -> usize { + self.0 + STACK_SIZE + } +} +use core::fmt::{self, Debug, Formatter}; +impl Debug for KStack { + fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { + f.write_fmt(format_args!("KStack:{:#x}", self.0)) + } +} + +impl Drop for KStack { + fn drop(&mut self) { + unsafe { + dealloc( + self.0 as _, + Layout::from_size_align(STACK_SIZE, STACK_SIZE).unwrap(), + ); + } + } +} diff --git a/os8-ref/src/task/kthread.rs b/os8-ref/src/task/kthread.rs new file mode 100644 index 0000000..9e6955d --- /dev/null +++ b/os8-ref/src/task/kthread.rs @@ -0,0 +1,76 @@ +use super::suspend_current_and_run_next; +use crate::task::{add_task, schedule, TaskContext, TaskControlBlock}; +use alloc::sync::Arc; + +// NOTE: This module is not required to finish the lab5, though you may run +// kernel_stackless_coroutine_test() in kernel main() to see what happens + +#[no_mangle] +pub fn kthread_create(f: fn()) { + println!("kthread_create"); + + // create kernel thread + let new_tcb = TaskControlBlock::create_kthread(f); + // let kernel_stack = new_tcb.get_kernel_stack(); + let new_task = Arc::new(new_tcb); + + // add kernel thread into TASK_MANAGER + // println!("add task"); + add_task(Arc::clone(&new_task)); +} + +#[no_mangle] +pub fn kernel_stackful_coroutine_test() { + println!("kernel_stackful_coroutine_test"); + kthread_create(|| { + let id = 1; + println!("kernel thread {:?} STARTING", id); + for i in 0..10 { + println!("kernel thread: {} counter: {}", id, i); + } + println!("kernel thread {:?} FINISHED", id); + kthread_stop(); + }); + kthread_create(|| { + let id = 2; + println!("kernel thread {:?} STARTING", id); + for i in 0..10 { + println!("kernel thread: {} counter: {}", id, i); + kthread_yield(); + } + println!("kernel thread {:?} FINISHED", id); + kthread_stop(); + }); + kthread_create(|| { + let id = 3; + println!("kernel thread {:?} STARTING", id); + for i in 0..10 { + println!("kernel thread: {} counter: {}", id, i); + kthread_yield(); + } + println!("kernel thread {:?} FINISHED", id); + kthread_stop(); + }); +} + +pub fn kthread_stop() { + do_exit(); +} +#[no_mangle] +pub fn do_exit() { + println!("kthread do exit"); + exit_kthread_and_run_next(0); + panic!("Unreachable in sys_exit!"); +} + +pub fn kthread_yield() { + suspend_current_and_run_next(); +} + +#[no_mangle] +pub fn exit_kthread_and_run_next(exit_code: i32) { + println!("exit_kthread_and_run_next with code: {}", exit_code); + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); +} diff --git a/os8-ref/src/task/manager.rs b/os8-ref/src/task/manager.rs new file mode 100644 index 0000000..cde08ce --- /dev/null +++ b/os8-ref/src/task/manager.rs @@ -0,0 +1,46 @@ +//! Implementation of [`TaskManager`] +//! +//! It is only used to manage processes and schedule process based on ready queue. +//! Other CPU process monitoring functions are in Processor. + + +use super::TaskControlBlock; +use crate::sync::UPSafeCell; +use alloc::collections::VecDeque; +use alloc::sync::Arc; +use lazy_static::*; + +pub struct TaskManager { + ready_queue: VecDeque>, +} + +/// A simple FIFO scheduler. +impl TaskManager { + pub fn new() -> Self { + Self { + ready_queue: VecDeque::new(), + } + } + /// Add process back to ready queue + pub fn add(&mut self, task: Arc) { + self.ready_queue.push_back(task); + } + /// Take a process out of the ready queue + pub fn fetch(&mut self) -> Option> { + self.ready_queue.pop_front() + } +} + +lazy_static! { + /// TASK_MANAGER instance through lazy_static! + pub static ref TASK_MANAGER: UPSafeCell = + unsafe { UPSafeCell::new(TaskManager::new()) }; +} + +pub fn add_task(task: Arc) { + TASK_MANAGER.exclusive_access().add(task); +} + +pub fn fetch_task() -> Option> { + TASK_MANAGER.exclusive_access().fetch() +} diff --git a/os8-ref/src/task/mod.rs b/os8-ref/src/task/mod.rs new file mode 100644 index 0000000..360457a --- /dev/null +++ b/os8-ref/src/task/mod.rs @@ -0,0 +1,158 @@ +//! Implementation of process management mechanism +//! +//! Here is the entry for process scheduling required by other modules +//! (such as syscall or clock interrupt). +//! By suspending or exiting the current process, you can +//! modify the process state, manage the process queue through TASK_MANAGER, +//! and switch the control flow through PROCESSOR. +//! +//! Be careful when you see [`__switch`]. Control flow around this function +//! might not be what you expect. + +mod context; +mod id; +pub mod kthread; +mod manager; +mod process; +mod processor; +pub mod stackless_coroutine; +mod switch; +#[allow(clippy::module_inception)] +mod task; + +pub use crate::syscall::process::TaskInfo; +use crate::{ + fs::{open_file, OpenFlags}, + task::id::TaskUserRes, +}; +use alloc::{sync::Arc, vec::Vec}; +pub use context::TaskContext; +pub use id::{kstack_alloc, pid_alloc, KernelStack, PidHandle}; +pub use kthread::kernel_stackful_coroutine_test; +use lazy_static::*; +pub use manager::add_task; +use manager::fetch_task; +use process::ProcessControlBlock; +pub use processor::{ + current_process, current_task, current_trap_cx, current_trap_cx_user_va, current_user_token, + run_tasks, schedule, take_current_task, +}; +pub use stackless_coroutine::kernel_stackless_coroutine_test; +use switch::__switch; +pub use task::{TaskControlBlock, TaskStatus}; + +pub fn block_current_and_run_next() { + let task = take_current_task().unwrap(); + let mut task_inner = task.inner_exclusive_access(); + let task_cx_ptr = &mut task_inner.task_cx as *mut TaskContext; + task_inner.task_status = TaskStatus::Blocking; + drop(task_inner); + schedule(task_cx_ptr); +} + +/// Make current task suspended and switch to the next task +pub fn suspend_current_and_run_next() { + // There must be an application running. + let task = take_current_task().unwrap(); + + // ---- access current TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + + let task_cx_ptr = &mut task_inner.task_cx as *mut TaskContext; + // Change status to Ready + task_inner.task_status = TaskStatus::Ready; + drop(task_inner); + // ---- release current PCB + + // push back to ready queue. + add_task(task); + // jump to scheduling cycle + schedule(task_cx_ptr); +} + +/// Exit current task, recycle process resources and switch to the next task +pub fn exit_current_and_run_next(exit_code: i32) { + // take from Processor + let task = take_current_task().unwrap(); + // **** access current TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let process = task.process.upgrade().unwrap(); + let tid = task_inner.res.as_ref().unwrap().tid; + // Record exit code + task_inner.exit_code = Some(exit_code); + task_inner.res = None; + + // here we do not remove the thread since we are still using the kstack + // it will be deallocated when sys_waittid is called + drop(task_inner); + drop(task); + // debug!("task {} dropped", tid); + + if tid == 0 { + let mut process_inner = process.inner_exclusive_access(); + // mark this process as a zombie process + process_inner.is_zombie = true; + // record exit code of main process + process_inner.exit_code = exit_code; + + // do not move to its parent but under initproc + // debug!("reparent"); + + // ++++++ access initproc PCB exclusively + { + let mut initproc_inner = INITPROC.inner_exclusive_access(); + for child in process_inner.children.iter() { + child.inner_exclusive_access().parent = Some(Arc::downgrade(&INITPROC)); + initproc_inner.children.push(child.clone()); + } + } + let mut recycle_res = Vec::::new(); + + // debug!("deallocate user res"); + // deallocate user res (including tid/trap_cx/ustack) of all threads + // it has to be done before we dealloc the whole memory_set + // otherwise they will be deallocated twice + for task in process_inner.tasks.iter().filter(|t| t.is_some()) { + let task = task.as_ref().unwrap(); + let mut task_inner = task.inner_exclusive_access(); + if let Some(res) = task_inner.res.take() { + recycle_res.push(res); + } + } + drop(process_inner); + recycle_res.clear(); + let mut process_inner = process.inner_exclusive_access(); + // debug!("deallocate pcb res"); + process_inner.children.clear(); + // deallocate other data in user space i.e. program code/data section + process_inner.memory_set.recycle_data_pages(); + // drop file descriptors + process_inner.fd_table.clear(); + } + // debug!("pcb dropped"); + + // ++++++ release parent PCB + drop(process); + + // we do not have to save task context + let mut _unused = TaskContext::zero_init(); + schedule(&mut _unused as *mut _); +} + +lazy_static! { + /// Creation of initial process + /// + /// the name "initproc" may be changed to any other app name like "usertests", + /// but we have user_shell, so we don't need to change it. + pub static ref INITPROC: Arc = { + let inode = open_file("ch8b_initproc", OpenFlags::RDONLY).unwrap(); + let v = inode.read_all(); + ProcessControlBlock::new(v.as_slice()) + }; +} + +pub fn add_initproc() { + // INITPROC must be referenced at least once so that it can be initialized + // through lazy_static + let _initproc = INITPROC.clone(); +} diff --git a/os8-ref/src/task/process.rs b/os8-ref/src/task/process.rs new file mode 100644 index 0000000..ed84735 --- /dev/null +++ b/os8-ref/src/task/process.rs @@ -0,0 +1,280 @@ +use super::id::RecycleAllocator; +use super::{add_task, pid_alloc, PidHandle, TaskControlBlock}; +use crate::fs::{File, Stdin, Stdout}; +use crate::mm::{translated_refmut, MemorySet, KERNEL_SPACE}; +use crate::sync::{Condvar, Mutex, Semaphore, UPSafeCell}; +use crate::trap::{trap_handler, TrapContext}; +use alloc::string::String; +use alloc::sync::{Arc, Weak}; +use alloc::vec; +use alloc::vec::Vec; +use core::cell::RefMut; + +pub struct ProcessControlBlock { + // immutable + pub pid: PidHandle, + // mutable + inner: UPSafeCell, +} + +// LAB5 HINT: you may add data structures for deadlock detection here +pub struct ProcessControlBlockInner { + pub is_zombie: bool, + pub memory_set: MemorySet, + pub parent: Option>, + pub children: Vec>, + pub exit_code: i32, + pub fd_table: Vec>>, + pub tasks: Vec>>, + pub task_res_allocator: RecycleAllocator, + pub mutex_list: Vec>>, + pub semaphore_list: Vec>>, + pub condvar_list: Vec>>, +} + +impl ProcessControlBlockInner { + #[allow(unused)] + pub fn get_user_token(&self) -> usize { + self.memory_set.token() + } + + pub fn alloc_fd(&mut self) -> usize { + if let Some(fd) = (0..self.fd_table.len()).find(|fd| self.fd_table[*fd].is_none()) { + fd + } else { + self.fd_table.push(None); + self.fd_table.len() - 1 + } + } + + pub fn alloc_tid(&mut self) -> usize { + self.task_res_allocator.alloc() + } + + pub fn dealloc_tid(&mut self, tid: usize) { + self.task_res_allocator.dealloc(tid) + } + + pub fn thread_count(&self) -> usize { + self.tasks.len() + } + + pub fn get_task(&self, tid: usize) -> Arc { + self.tasks[tid].as_ref().unwrap().clone() + } +} + +impl ProcessControlBlock { + pub fn inner_exclusive_access(&self) -> RefMut<'_, ProcessControlBlockInner> { + self.inner.exclusive_access() + } + + // LAB5 HINT: How to initialize deadlock data structures? + pub fn new(elf_data: &[u8]) -> Arc { + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, ustack_base, entry_point) = MemorySet::from_elf(elf_data); + // allocate a pid + let pid_handle = pid_alloc(); + let process = Arc::new(Self { + pid: pid_handle, + inner: unsafe { + UPSafeCell::new(ProcessControlBlockInner { + is_zombie: false, + memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + fd_table: vec![ + // 0 -> stdin + Some(Arc::new(Stdin)), + // 1 -> stdout + Some(Arc::new(Stdout)), + // 2 -> stderr + Some(Arc::new(Stdout)), + ], + tasks: Vec::new(), + task_res_allocator: RecycleAllocator::new(), + mutex_list: Vec::new(), + semaphore_list: Vec::new(), + condvar_list: Vec::new(), + }) + }, + }); + // create a main thread, we should allocate ustack and trap_cx here + let task = Arc::new(TaskControlBlock::new( + Arc::clone(&process), + ustack_base, + true, + )); + // prepare trap_cx of main thread + let task_inner = task.inner_exclusive_access(); + let trap_cx = task_inner.get_trap_cx(); + let ustack_top = task_inner.res.as_ref().unwrap().ustack_top(); + let kernel_stack_top = task.kernel_stack.get_top(); + drop(task_inner); + *trap_cx = TrapContext::app_init_context( + entry_point, + ustack_top, + KERNEL_SPACE.exclusive_access().token(), + kernel_stack_top, + trap_handler as usize, + ); + // add main thread to the process + let mut process_inner = process.inner_exclusive_access(); + process_inner.tasks.push(Some(Arc::clone(&task))); + drop(process_inner); + // add main thread to scheduler + add_task(task); + process + } + + // LAB5 HINT: How to initialize deadlock data structures? + /// Load a new elf to replace the original application address space and start execution + /// Only support processes with a single thread. + pub fn exec(self: &Arc, elf_data: &[u8], args: Vec) { + assert_eq!(self.inner_exclusive_access().thread_count(), 1); + // memory_set with elf program headers/trampoline/trap context/user stack + let (memory_set, ustack_base, entry_point) = MemorySet::from_elf(elf_data); + let new_token = memory_set.token(); + // substitute memory_set + self.inner_exclusive_access().memory_set = memory_set; + // then we alloc user resource for main thread again + // since memory_set has been changed + let task = self.inner_exclusive_access().get_task(0); + let mut task_inner = task.inner_exclusive_access(); + task_inner.res.as_mut().unwrap().ustack_base = ustack_base; + task_inner.res.as_mut().unwrap().alloc_user_res(); + task_inner.trap_cx_ppn = task_inner.res.as_mut().unwrap().trap_cx_ppn(); + // push arguments on user stack + let mut user_sp = task_inner.res.as_mut().unwrap().ustack_top(); + user_sp -= (args.len() + 1) * core::mem::size_of::(); + let argv_base = user_sp; + let mut argv: Vec<_> = (0..=args.len()) + .map(|arg| { + translated_refmut( + new_token, + (argv_base + arg * core::mem::size_of::()) as *mut usize, + ) + }) + .collect(); + *argv[args.len()] = 0; + for i in 0..args.len() { + user_sp -= args[i].len() + 1; + *argv[i] = user_sp; + let mut p = user_sp; + for c in args[i].as_bytes() { + *translated_refmut(new_token, p as *mut u8) = *c; + p += 1; + } + *translated_refmut(new_token, p as *mut u8) = 0; + } + // make the user_sp aligned to 8B for k210 platform + user_sp -= user_sp % core::mem::size_of::(); + // initialize trap_cx + let mut trap_cx = TrapContext::app_init_context( + entry_point, + user_sp, + KERNEL_SPACE.exclusive_access().token(), + task.kernel_stack.get_top(), + trap_handler as usize, + ); + trap_cx.x[10] = args.len(); + trap_cx.x[11] = argv_base; + *task_inner.get_trap_cx() = trap_cx; + } + + // LAB5 HINT: How to initialize deadlock data structures? + /// Fork from parent to child + /// Only support processes with a single thread. + pub fn fork(self: &Arc) -> Arc { + let mut parent = self.inner_exclusive_access(); + assert_eq!(parent.thread_count(), 1); + // clone parent's memory_set completely including trampoline/ustacks/trap_cxs + let memory_set = MemorySet::from_existed_user(&parent.memory_set); + // alloc a pid + let pid = pid_alloc(); + // copy fd table + let mut new_fd_table: Vec>> = Vec::new(); + for fd in parent.fd_table.iter() { + if let Some(file) = fd { + new_fd_table.push(Some(file.clone())); + } else { + new_fd_table.push(None); + } + } + // create child process pcb + let child = Arc::new(Self { + pid, + inner: unsafe { + UPSafeCell::new(ProcessControlBlockInner { + is_zombie: false, + memory_set, + parent: Some(Arc::downgrade(self)), + children: Vec::new(), + exit_code: 0, + fd_table: new_fd_table, + tasks: Vec::new(), + task_res_allocator: RecycleAllocator::new(), + mutex_list: Vec::new(), + semaphore_list: Vec::new(), + condvar_list: Vec::new(), + }) + }, + }); + // add child + parent.children.push(Arc::clone(&child)); + // create main thread of child process + let task = Arc::new(TaskControlBlock::new( + Arc::clone(&child), + parent + .get_task(0) + .inner_exclusive_access() + .res + .as_ref() + .unwrap() + .ustack_base(), + // here we do not allocate trap_cx or ustack again + // but mention that we allocate a new kernel_stack here + false, + )); + // attach task to child process + let mut child_inner = child.inner_exclusive_access(); + child_inner.tasks.push(Some(Arc::clone(&task))); + drop(child_inner); + // modify kernel_stack_top in trap_cx of this thread + let task_inner = task.inner_exclusive_access(); + let trap_cx = task_inner.get_trap_cx(); + trap_cx.kernel_sp = task.kernel_stack.get_top(); + drop(task_inner); + // add this thread to scheduler + add_task(task); + child + } + + pub fn getpid(&self) -> usize { + self.pid.0 + } + + pub fn kernel_process() -> Arc { + let memory_set = MemorySet::kernel_copy(); + let process = Arc::new(ProcessControlBlock { + pid: super::pid_alloc(), + inner: unsafe { + UPSafeCell::new(ProcessControlBlockInner { + is_zombie: false, + memory_set: memory_set, + parent: None, + children: Vec::new(), + exit_code: 0, + fd_table: Vec::new(), + tasks: Vec::new(), + task_res_allocator: RecycleAllocator::new(), + mutex_list: Vec::new(), + semaphore_list: Vec::new(), + condvar_list: Vec::new(), + }) + }, + }); + process + } +} diff --git a/os8-ref/src/task/processor.rs b/os8-ref/src/task/processor.rs new file mode 100644 index 0000000..8308b85 --- /dev/null +++ b/os8-ref/src/task/processor.rs @@ -0,0 +1,121 @@ +//! Implementation of [`Processor`] and Intersection of control flow +//! +//! Here, the continuous operation of user apps in CPU is maintained, +//! the current running state of CPU is recorded, +//! and the replacement and transfer of control flow of different applications are executed. + +use super::__switch; +use super::process::ProcessControlBlock; +use super::{fetch_task, TaskStatus}; +use super::{TaskContext, TaskControlBlock}; +use crate::sync::UPSafeCell; +use crate::trap::TrapContext; +use alloc::sync::Arc; +use lazy_static::*; + +/// Processor management structure +pub struct Processor { + /// The task currently executing on the current processor + current: Option>, + /// The basic control flow of each core, helping to select and switch process + idle_task_cx: TaskContext, +} + +impl Processor { + pub fn new() -> Self { + Self { + current: None, + idle_task_cx: TaskContext::zero_init(), + } + } + fn get_idle_task_cx_ptr(&mut self) -> *mut TaskContext { + &mut self.idle_task_cx as *mut _ + } + pub fn take_current(&mut self) -> Option> { + self.current.take() + } + pub fn current(&self) -> Option> { + self.current.as_ref().map(|task| Arc::clone(task)) + } +} + +lazy_static! { + /// PROCESSOR instance through lazy_static! + pub static ref PROCESSOR: UPSafeCell = unsafe { UPSafeCell::new(Processor::new()) }; +} + +/// The main part of process execution and scheduling +/// +/// Loop fetch_task to get the process that needs to run, +/// and switch the process through __switch +pub fn run_tasks() { + loop { + let mut processor = PROCESSOR.exclusive_access(); + if let Some(task) = fetch_task() { + // println!("task get!"); + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + // access coming task TCB exclusively + let mut task_inner = task.inner_exclusive_access(); + let next_task_cx_ptr = &task_inner.task_cx as *const TaskContext; + task_inner.task_status = TaskStatus::Running; + drop(task_inner); + // release coming task TCB manually + processor.current = Some(task); + // release processor manually + drop(processor); + unsafe { + __switch(idle_task_cx_ptr, next_task_cx_ptr); + } + } else { + println!("no tasks available in run_tasks"); + } + } +} + +/// Get current task through take, leaving a None in its place +pub fn take_current_task() -> Option> { + PROCESSOR.exclusive_access().take_current() +} + +/// Get a copy of the current task +pub fn current_task() -> Option> { + PROCESSOR.exclusive_access().current() +} + +pub fn current_process() -> Arc { + current_task().unwrap().process.upgrade().unwrap() +} + +/// Get token of the address space of current task +pub fn current_user_token() -> usize { + let task = current_task().unwrap(); + task.get_user_token() +} + +/// Get the mutable reference to trap context of current task +pub fn current_trap_cx() -> &'static mut TrapContext { + current_task() + .unwrap() + .inner_exclusive_access() + .get_trap_cx() +} + +pub fn current_trap_cx_user_va() -> usize { + current_task() + .unwrap() + .inner_exclusive_access() + .res + .as_ref() + .unwrap() + .trap_cx_user_va() +} + +/// Return to idle control flow for new scheduling +pub fn schedule(switched_task_cx_ptr: *mut TaskContext) { + let mut processor = PROCESSOR.exclusive_access(); + let idle_task_cx_ptr = processor.get_idle_task_cx_ptr(); + drop(processor); + unsafe { + __switch(switched_task_cx_ptr, idle_task_cx_ptr); + } +} diff --git a/os8-ref/src/task/stackless_coroutine.rs b/os8-ref/src/task/stackless_coroutine.rs new file mode 100644 index 0000000..eb0762e --- /dev/null +++ b/os8-ref/src/task/stackless_coroutine.rs @@ -0,0 +1,125 @@ +// https://blog.aloni.org/posts/a-stack-less-rust-coroutine-100-loc/ +// https://github.com/chyyuu/example-coroutine-and-thread/tree/stackless-coroutine-x86 + +// NOTE: This module is not required to finish the lab5, though you may run +// kernel_stackless_coroutine_test() in kernel main() to see what happens + +use core::future::Future; +use core::pin::Pin; +use core::task::{Context, Poll}; +use core::task::{RawWaker, RawWakerVTable, Waker}; + +extern crate alloc; +use alloc::collections::VecDeque; + +use alloc::boxed::Box; + +enum State { + Halted, + Running, +} + +struct Task { + state: State, +} + +impl Task { + fn waiter<'a>(&'a mut self) -> Waiter<'a> { + Waiter { task: self } + } +} + +struct Waiter<'a> { + task: &'a mut Task, +} + +impl<'a> Future for Waiter<'a> { + type Output = (); + + fn poll(mut self: Pin<&mut Self>, _cx: &mut Context) -> Poll { + match self.task.state { + State::Halted => { + self.task.state = State::Running; + Poll::Ready(()) + } + State::Running => { + self.task.state = State::Halted; + Poll::Pending + } + } + } +} + +struct Executor { + tasks: VecDeque>>>, +} + +impl Executor { + fn new() -> Self { + Executor { + tasks: VecDeque::new(), + } + } + + fn push(&mut self, closure: C) + where + F: Future + 'static, + C: FnOnce(Task) -> F, + { + let task = Task { + state: State::Running, + }; + self.tasks.push_back(Box::pin(closure(task))); + } + + fn run(&mut self) { + let waker = create_waker(); + let mut context = Context::from_waker(&waker); + + while let Some(mut task) = self.tasks.pop_front() { + match task.as_mut().poll(&mut context) { + Poll::Pending => { + self.tasks.push_back(task); + } + Poll::Ready(()) => {} + } + } + } +} + +pub fn create_waker() -> Waker { + // Safety: The waker points to a vtable with functions that do nothing. Doing + // nothing is memory-safe. + unsafe { Waker::from_raw(RAW_WAKER) } +} + +const RAW_WAKER: RawWaker = RawWaker::new(core::ptr::null(), &VTABLE); +const VTABLE: RawWakerVTable = RawWakerVTable::new(clone, wake, wake_by_ref, drop); + +unsafe fn clone(_: *const ()) -> RawWaker { + RAW_WAKER +} +unsafe fn wake(_: *const ()) {} +unsafe fn wake_by_ref(_: *const ()) {} +unsafe fn drop(_: *const ()) {} + +#[no_mangle] +pub fn kernel_stackless_coroutine_test() { + println!("kernel stackless coroutine Begin.."); + let mut exec = Executor::new(); + println!(" Create futures"); + for instance in 1..=3 { + exec.push(move |mut task| async move { + println!(" Kernel Task {}: begin state", instance); + task.waiter().await; + println!(" Kernel Task {}: next state", instance); + task.waiter().await; + println!(" Kernel Task {}: end state", instance); + }); + } + + println!(" Running"); + exec.run(); + println!(" Done"); + println!("kernel stackless coroutine PASSED"); +} diff --git a/os8-ref/src/task/switch.S b/os8-ref/src/task/switch.S new file mode 100644 index 0000000..3f985d2 --- /dev/null +++ b/os8-ref/src/task/switch.S @@ -0,0 +1,34 @@ +.altmacro +.macro SAVE_SN n + sd s\n, (\n+2)*8(a0) +.endm +.macro LOAD_SN n + ld s\n, (\n+2)*8(a1) +.endm + .section .text + .globl __switch +__switch: + # __switch( + # current_task_cx_ptr: *mut TaskContext, + # next_task_cx_ptr: *const TaskContext + # ) + # save kernel stack of current task + sd sp, 8(a0) + # save ra & s0~s11 of current execution + sd ra, 0(a0) + .set n, 0 + .rept 12 + SAVE_SN %n + .set n, n + 1 + .endr + # restore ra & s0~s11 of next execution + ld ra, 0(a1) + .set n, 0 + .rept 12 + LOAD_SN %n + .set n, n + 1 + .endr + # restore kernel stack of next task + ld sp, 8(a1) + ret + diff --git a/os8-ref/src/task/switch.rs b/os8-ref/src/task/switch.rs new file mode 100644 index 0000000..af08289 --- /dev/null +++ b/os8-ref/src/task/switch.rs @@ -0,0 +1,16 @@ +//! Rust wrapper around `__switch`. +//! +//! Switching to a different task's context happens here. The actual +//! implementation must not be in Rust and (essentially) has to be in assembly +//! language (Do you know why?), so this module really is just a wrapper around +//! `switch.S`. + +core::arch::global_asm!(include_str!("switch.S")); + +use super::TaskContext; + +extern "C" { + /// Switch to the context of `next_task_cx_ptr`, saving the current context + /// in `current_task_cx_ptr`. + pub fn __switch(current_task_cx_ptr: *mut TaskContext, next_task_cx_ptr: *const TaskContext); +} diff --git a/os8-ref/src/task/task.rs b/os8-ref/src/task/task.rs new file mode 100644 index 0000000..1591f4d --- /dev/null +++ b/os8-ref/src/task/task.rs @@ -0,0 +1,140 @@ +//! Types related to task management & Functions for completely changing TCB + +use super::id::TaskUserRes; +use super::{kstack_alloc, KernelStack, ProcessControlBlock, TaskContext}; +use crate::trap::TrapContext; +use crate::{mm::PhysPageNum, sync::UPSafeCell}; +use alloc::sync::{Arc, Weak}; +use core::cell::RefMut; + +/// Task control block structure +/// +/// Directly save the contents that will not change during running +pub struct TaskControlBlock { + // immutable + pub process: Weak, + /// Kernel stack corresponding to TID + pub kernel_stack: KernelStack, + // mutable + inner: UPSafeCell, +} + +/// Structure containing more process content +/// +/// Store the contents that will change during operation +/// and are wrapped by UPSafeCell to provide mutual exclusion +pub struct TaskControlBlockInner { + /// The physical page number of the frame where the trap context is placed + pub trap_cx_ppn: PhysPageNum, + /// Save task context + pub task_cx: TaskContext, + /// Maintain the execution status of the current process + pub task_status: TaskStatus, + /// It is set when active exit or execution error occurs + pub exit_code: Option, + /// Tid and ustack will be deallocated when this goes None + pub res: Option, +} + +/// Simple access to its internal fields +impl TaskControlBlockInner { + /* + pub fn get_task_cx_ptr2(&self) -> *const usize { + &self.task_cx_ptr as *const usize + } + */ + pub fn get_trap_cx(&self) -> &'static mut TrapContext { + self.trap_cx_ppn.get_mut() + } + + #[allow(unused)] + fn get_status(&self) -> TaskStatus { + self.task_status + } +} + +impl TaskControlBlock { + pub fn new( + process: Arc, + ustack_base: usize, + alloc_user_res: bool, + ) -> Self { + let res = TaskUserRes::new(Arc::clone(&process), ustack_base, alloc_user_res); + let trap_cx_ppn = res.trap_cx_ppn(); + let kernel_stack = kstack_alloc(); + let kstack_top = kernel_stack.get_top(); + Self { + process: Arc::downgrade(&process), + kernel_stack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + res: Some(res), + trap_cx_ppn, + task_cx: TaskContext::goto_trap_return(kstack_top), + task_status: TaskStatus::Ready, + exit_code: None, + }) + }, + } + } + + /// Get the mutex to get the RefMut TaskControlBlockInner + pub fn inner_exclusive_access(&self) -> RefMut<'_, TaskControlBlockInner> { + let inner = self.inner.exclusive_access(); + // if self.process.upgrade().unwrap().pid.0 > 1 { + // if let Some(res) = inner.res.as_ref() { + // println!("t{}i", res.tid); + // } + // } + inner + } + + pub fn get_user_token(&self) -> usize { + let process = self.process.upgrade().unwrap(); + let inner = process.inner_exclusive_access(); + inner.memory_set.token() + } + + pub fn create_kthread(f: fn()) -> Self { + use crate::mm::PhysAddr; + let process = ProcessControlBlock::kernel_process(); + let process = Arc::downgrade(&process); + + let kernelstack = crate::task::id::KStack::new(); + let kstack_top = kernelstack.top(); + + let mut context = TaskContext::zero_init(); + let context_addr = &context as *const TaskContext as usize; + let pa = PhysAddr::from(context_addr); + let context_ppn = pa.floor(); + + context.ra = f as usize; + context.sp = kstack_top; + + //println!("context ppn :{:#x?}", context_ppn); + + Self { + process, + kernel_stack: KernelStack(kstack_top), + //kstack, + inner: unsafe { + UPSafeCell::new(TaskControlBlockInner { + res: None, + trap_cx_ppn: context_ppn, + task_cx: context, + task_status: TaskStatus::Ready, + exit_code: None, + }) + }, + } + } +} + +#[derive(Copy, Clone, PartialEq)] +/// task status: UnInit, Ready, Running, Exited +pub enum TaskStatus { + UnInit, + Ready, + Running, + Blocking, +} diff --git a/os8-ref/src/timer.rs b/os8-ref/src/timer.rs new file mode 100644 index 0000000..b2fd8eb --- /dev/null +++ b/os8-ref/src/timer.rs @@ -0,0 +1,83 @@ +//! RISC-V timer-related functionality + +use crate::config::CLOCK_FREQ; +use crate::sbi::set_timer; +use crate::sync::UPSafeCell; +use crate::task::{add_task, TaskControlBlock}; +use alloc::collections::BinaryHeap; +use alloc::sync::Arc; +use core::cmp::Ordering; +use lazy_static::*; +use riscv::register::time; + +const TICKS_PER_SEC: usize = 100; +const MILLI_PER_SEC: usize = 1_000; +const MICRO_PER_SEC: usize = 1_000_000; + +/// read the `mtime` register +pub fn get_time() -> usize { + time::read() +} + +/// get current time in microseconds +pub fn get_time_us() -> usize { + time::read() / (CLOCK_FREQ / MICRO_PER_SEC) +} + +/// get current time in milliseconds +pub fn get_time_ms() -> usize { + time::read() / (CLOCK_FREQ / MILLI_PER_SEC) +} + +/// set the next timer interrupt +pub fn set_next_trigger() { + set_timer(get_time() + CLOCK_FREQ / TICKS_PER_SEC); +} + +pub struct TimerCondVar { + pub expire_ms: usize, + pub task: Arc, +} + +impl PartialEq for TimerCondVar { + fn eq(&self, other: &Self) -> bool { + self.expire_ms == other.expire_ms + } +} +impl Eq for TimerCondVar {} +impl PartialOrd for TimerCondVar { + fn partial_cmp(&self, other: &Self) -> Option { + let a = -(self.expire_ms as isize); + let b = -(other.expire_ms as isize); + Some(a.cmp(&b)) + } +} + +impl Ord for TimerCondVar { + fn cmp(&self, other: &Self) -> Ordering { + self.partial_cmp(other).unwrap() + } +} + +lazy_static! { + static ref TIMERS: UPSafeCell> = + unsafe { UPSafeCell::new(BinaryHeap::::new()) }; +} + +pub fn add_timer(expire_ms: usize, task: Arc) { + let mut timers = TIMERS.exclusive_access(); + timers.push(TimerCondVar { expire_ms, task }); +} + +pub fn check_timer() { + let current_ms = get_time_ms(); + let mut timers = TIMERS.exclusive_access(); + while let Some(timer) = timers.peek() { + if timer.expire_ms <= current_ms { + add_task(Arc::clone(&timer.task)); + timers.pop(); + } else { + break; + } + } +} diff --git a/os8-ref/src/trap/context.rs b/os8-ref/src/trap/context.rs new file mode 100644 index 0000000..58e199c --- /dev/null +++ b/os8-ref/src/trap/context.rs @@ -0,0 +1,47 @@ +//! Implementation of [`TrapContext`] + +use riscv::register::sstatus::{self, Sstatus, SPP}; + +#[repr(C)] +/// trap context structure containing sstatus, sepc and registers +pub struct TrapContext { + /// General-Purpose Register x0-31 + pub x: [usize; 32], + /// sstatus + pub sstatus: Sstatus, + /// sepc + pub sepc: usize, + /// Token of kernel address space + pub kernel_satp: usize, + /// Kernel stack pointer of the current application + pub kernel_sp: usize, + /// Virtual address of trap handler entry point in kernel + pub trap_handler: usize, +} + +impl TrapContext { + pub fn set_sp(&mut self, sp: usize) { + self.x[2] = sp; + } + pub fn app_init_context( + entry: usize, + sp: usize, + kernel_satp: usize, + kernel_sp: usize, + trap_handler: usize, + ) -> Self { + let mut sstatus = sstatus::read(); + // set CPU privilege to User after trapping back + sstatus.set_spp(SPP::User); + let mut cx = Self { + x: [0; 32], + sstatus, + sepc: entry, + kernel_satp, + kernel_sp, + trap_handler, + }; + cx.set_sp(sp); + cx + } +} diff --git a/os8-ref/src/trap/mod.rs b/os8-ref/src/trap/mod.rs new file mode 100644 index 0000000..d025b9a --- /dev/null +++ b/os8-ref/src/trap/mod.rs @@ -0,0 +1,133 @@ +//! Trap handling functionality +//! +//! For rCore, we have a single trap entry point, namely `__alltraps`. At +//! initialization in [`init()`], we set the `stvec` CSR to point to it. +//! +//! All traps go through `__alltraps`, which is defined in `trap.S`. The +//! assembly language code does just enough work restore the kernel space +//! context, ensuring that Rust code safely runs, and transfers control to +//! [`trap_handler()`]. +//! +//! It then calls different functionality based on what exactly the exception +//! was. For example, timer interrupts trigger task preemption, and syscalls go +//! to [`syscall()`]. + +mod context; + +use crate::config::TRAMPOLINE; +use crate::syscall::syscall; +use crate::task::{ + current_trap_cx, current_trap_cx_user_va, current_user_token, exit_current_and_run_next, + suspend_current_and_run_next, +}; +use crate::timer::{check_timer, set_next_trigger}; +use riscv::register::{ + mtvec::TrapMode, + scause::{self, Exception, Interrupt, Trap}, + sie, stval, stvec, +}; + +core::arch::global_asm!(include_str!("trap.S")); + +pub fn init() { + set_kernel_trap_entry(); +} + +fn set_kernel_trap_entry() { + unsafe { + stvec::write(trap_from_kernel as usize, TrapMode::Direct); + } +} + +fn set_user_trap_entry() { + unsafe { + stvec::write(TRAMPOLINE as usize, TrapMode::Direct); + } +} + +pub fn enable_timer_interrupt() { + unsafe { + sie::set_stimer(); + } +} + +#[no_mangle] +pub fn trap_handler() -> ! { + set_kernel_trap_entry(); + let scause = scause::read(); + let stval = stval::read(); + match scause.cause() { + Trap::Exception(Exception::UserEnvCall) => { + // jump to next instruction anyway + let mut cx = current_trap_cx(); + cx.sepc += 4; + // get system call return value + let result = syscall(cx.x[17], [cx.x[10], cx.x[11], cx.x[12], cx.x[13]]); + // cx is changed during sys_exec, so we have to call it again + cx = current_trap_cx(); + cx.x[10] = result as usize; + } + Trap::Exception(Exception::StoreFault) + | Trap::Exception(Exception::StorePageFault) + | Trap::Exception(Exception::InstructionFault) + | Trap::Exception(Exception::InstructionPageFault) + | Trap::Exception(Exception::LoadFault) + | Trap::Exception(Exception::LoadPageFault) => { + println!( + "[kernel] {:?} in application, bad addr = {:#x}, bad instruction = {:#x}, core dumped.", + scause.cause(), + stval, + current_trap_cx().sepc, + ); + // page fault exit code + exit_current_and_run_next(-2); + } + Trap::Exception(Exception::IllegalInstruction) => { + println!("[kernel] IllegalInstruction in application, core dumped."); + // illegal instruction exit code + exit_current_and_run_next(-3); + } + Trap::Interrupt(Interrupt::SupervisorTimer) => { + set_next_trigger(); + check_timer(); + suspend_current_and_run_next(); + } + _ => { + panic!( + "Unsupported trap {:?}, stval = {:#x}!", + scause.cause(), + stval + ); + } + } + trap_return(); +} + +#[no_mangle] +pub fn trap_return() -> ! { + set_user_trap_entry(); + let trap_cx_ptr = current_trap_cx_user_va(); + let user_satp = current_user_token(); + extern "C" { + fn __alltraps(); + fn __restore(); + } + let restore_va = __restore as usize - __alltraps as usize + TRAMPOLINE; + unsafe { + core::arch::asm!( + "fence.i", + "jr {restore_va}", + restore_va = in(reg) restore_va, + in("a0") trap_cx_ptr, + in("a1") user_satp, + options(noreturn) + ); + } +} + +#[no_mangle] +pub fn trap_from_kernel() -> ! { + panic!("a trap {:?} from kernel!", scause::read().cause()); +} + +pub use context::TrapContext; diff --git a/os8-ref/src/trap/trap.S b/os8-ref/src/trap/trap.S new file mode 100644 index 0000000..c0e2d15 --- /dev/null +++ b/os8-ref/src/trap/trap.S @@ -0,0 +1,69 @@ +.altmacro +.macro SAVE_GP n + sd x\n, \n*8(sp) +.endm +.macro LOAD_GP n + ld x\n, \n*8(sp) +.endm + .section .text.trampoline + .globl __alltraps + .globl __restore + .align 2 +__alltraps: + csrrw sp, sscratch, sp + # now sp->*TrapContext in user space, sscratch->user stack + # save other general purpose registers + sd x1, 1*8(sp) + # skip sp(x2), we will save it later + sd x3, 3*8(sp) + # skip tp(x4), application does not use it + # save x5~x31 + .set n, 5 + .rept 27 + SAVE_GP %n + .set n, n+1 + .endr + # we can use t0/t1/t2 freely, because they have been saved in TrapContext + csrr t0, sstatus + csrr t1, sepc + sd t0, 32*8(sp) + sd t1, 33*8(sp) + # read user stack from sscratch and save it in TrapContext + csrr t2, sscratch + sd t2, 2*8(sp) + # load kernel_satp into t0 + ld t0, 34*8(sp) + # load trap_handler into t1 + ld t1, 36*8(sp) + # move to kernel_sp + ld sp, 35*8(sp) + # switch to kernel space + csrw satp, t0 + sfence.vma + # jump to trap_handler + jr t1 + +__restore: + # a0: *TrapContext in user space(Constant); a1: user space token + # switch to user space + csrw satp, a1 + sfence.vma + csrw sscratch, a0 + mv sp, a0 + # now sp points to TrapContext in user space, start restoring based on it + # restore sstatus/sepc + ld t0, 32*8(sp) + ld t1, 33*8(sp) + csrw sstatus, t0 + csrw sepc, t1 + # restore general purpose registers except x0/sp/tp + ld x1, 1*8(sp) + ld x3, 3*8(sp) + .set n, 5 + .rept 27 + LOAD_GP %n + .set n, n+1 + .endr + # back to user stack + ld sp, 2*8(sp) + sret