GENODE Operating System Framework 16.05 Foundations Norman Feske Contents Contents 1. Introduction9 1.1. Operating-system framework......................... 14 1.2. Licensing and commercial support...................... 16 1.3. About this document.............................. 17 I. Foundations 18 2. Getting started 19 2.1. Obtaining the source code........................... 20 2.2. Source-tree structure.............................. 21 2.3. Using the build system............................. 24 2.4. A simple system scenario........................... 26 2.5. Hello world................................... 29 2.5.1. Using a custom source-code repository............... 29 2.5.2. Source code and build description.................. 29 2.5.3. Building the component........................ 31 2.5.4. Defining a system scenario...................... 31 3. Architecture 34 3.1. Capability-based security........................... 36 3.1.1. Capability spaces, object identities, and RPC objects........ 36 3.1.2. Delegation of authority and ownership............... 37 3.1.3. Capability invocation......................... 38 3.1.4. Capability delegation through capability invocation........ 41 3.2. Recursive system structure........................... 43 3.2.1. Component ownership......................... 43 3.2.2. Tree of components........................... 44 3.2.3. Services and sessions.......................... 44 3.2.4. Client-server relationship....................... 47 3.3. Resource trading................................ 51 3.3.1. Resource assignment.......................... 51 3.3.2. Trading memory between clients and servers............ 55 3.3.3. Component-local heap partitioning................. 57 3.3.4. Dynamic resource balancing..................... 59 3.4. Core - the root of the component tree..................... 61 3.4.1. Dataspaces................................ 61 3.4.2. Region maps.............................. 62 3.4.3. Physical memory allocation (RAM)................. 62 3.4.4. Access to boot modules (ROM).................... 63 2 Contents 3.4.5. Protection domains (PD)........................ 63 3.4.6. Region-map management (RM).................... 64 3.4.7. Processing-time allocation (CPU)................... 65 3.4.8. Access to device resources (IO_MEM, IO_PORT, IRQ)....... 65 3.4.9. Logging (LOG)............................. 67 3.4.10. Event tracing (TRACE)......................... 67 3.5. Component creation.............................. 68 3.5.1. Obtaining the child’s ROM and RAM sessions........... 68 3.5.2. Constructing the child’s address space................ 69 3.5.3. Creating the initial thread....................... 71 3.6. Inter-component communication....................... 74 3.6.1. Synchronous remote procedure calls (RPC)............. 75 3.6.2. Asynchronous notifications...................... 83 3.6.3. Shared memory............................. 86 3.6.4. Asynchronous state propagation................... 88 3.6.5. Synchronous bulk transfer....................... 88 3.6.6. Asynchronous bulk transfer - packet streams............ 90 4. Components 93 4.1. Device drivers.................................. 95 4.1.1. Platform driver............................. 96 4.1.2. Interrupt handling........................... 97 4.1.3. Direct memory access (DMA) transactions............. 97 4.2. Protocol stacks.................................. 101 4.3. Resource multiplexers............................. 103 4.4. Runtime environments and applications................... 105 4.5. Common session interfaces.......................... 107 4.5.1. Read-only memory (ROM)...................... 107 4.5.2. Report.................................. 109 4.5.3. Terminal and UART.......................... 109 4.5.4. Input................................... 110 4.5.5. Framebuffer............................... 111 4.5.6. Nitpicker GUI.............................. 113 4.5.7. Platform................................. 114 4.5.8. Block................................... 114 4.5.9. Regulator................................ 114 4.5.10. Timer................................... 114 4.5.11. NIC.................................... 115 4.5.12. Audio output.............................. 115 4.5.13. File system................................ 118 4.5.14. Loader.................................. 119 4.6. Component configuration........................... 120 3 Contents 4.6.1. Configuration format.......................... 120 4.6.2. Server-side policy selection...................... 120 4.6.3. Dynamic component reconfiguration at runtime.......... 121 4.7. Component composition............................ 122 4.7.1. Sandboxing............................... 122 4.7.2. Component-level and OS-level virtualization............ 124 4.7.3. Interposing individual services.................... 128 4.7.4. Ceding the parenthood........................ 129 4.7.5. Publishing and subscribing...................... 131 4.7.6. Enslaving services........................... 133 5. Development 135 5.1. Source-code repositories............................ 136 5.2. Integration of 3rd-party software....................... 138 5.3. Build system................................... 139 5.3.1. Build directories............................ 139 5.3.2. Target descriptions........................... 140 5.3.3. Library descriptions.......................... 141 5.3.4. Platform specifications......................... 142 5.3.5. Building tools to be executed on the host platform......... 143 5.3.6. Building 3rd-party software...................... 143 5.4. System integration and automated testing.................. 145 5.4.1. Run tool................................. 145 5.4.2. Run-tool configuration examples................... 146 5.4.3. Meaningful default behaviour.................... 148 5.4.4. Run scripts............................... 148 5.4.5. The run mechanism explained.................... 149 5.4.6. Using run scripts to implement test cases.............. 150 5.4.7. Automated testing across base platforms.............. 151 5.5. Git flow...................................... 152 5.5.1. Master and staging........................... 152 5.5.2. Development practice......................... 153 6. System configuration 156 6.1. Nested configuration concept......................... 158 6.2. The init component............................... 161 6.2.1. Session routing............................. 161 6.2.2. Resource quota saturation....................... 164 6.2.3. Handing out slack resources..................... 164 6.2.4. Multiple instantiation of a single ELF binary............ 164 6.2.5. Nested configuration.......................... 165 6.2.6. Assigning subsystems to CPUs.................... 167 4 Contents 6.2.7. Priority support............................. 168 6.2.8. Init verbosity.............................. 168 7. Under the hood 169 7.1. Component-local startup code and linker scripts.............. 170 7.1.1. Linker scripts.............................. 170 7.1.2. Startup code............................... 171 7.2. C++ runtime................................... 175 7.2.1. Rationale behind using exceptions.................. 175 7.2.2. Bare-metal C++ runtime........................ 177 7.3. Interaction of core with the underlying kernel................ 178 7.3.1. Bootstrapping and allocator setup.................. 178 7.3.2. Kernel-object creation......................... 179 7.3.3. Page-fault handling.......................... 180 7.4. Asynchronous notification mechanism.................... 182 7.5. Dynamic linker................................. 185 7.5.1. Building dynamically-linked programs............... 185 7.5.2. Startup of dynamically-linked programs.............. 185 7.5.3. Address-space management..................... 186 7.6. Execution on bare hardware (base-hw).................... 187 7.6.1. Bootstrapping of base-hw....................... 187 7.6.2. Kernel entry and exit.......................... 189 7.6.3. Interrupt handling and preemptive multi-threading........ 189 7.6.4. Split kernel interface.......................... 189 7.6.5. Public part of the kernel interface................... 190 7.6.6. Core-private part of the kernel interface............... 191 7.6.7. Scheduler of the base-hw kernel................... 192 7.6.8. Sparsely populated core address space............... 193 7.6.9. Multi-processor support of base-hw................. 193 7.6.10. Asynchronous notifications on base-hw............... 194 7.7. Execution on the NOVA microhypervisor (base-nova)........... 195 7.7.1. Integration of NOVA with Genode.................. 195 7.7.2. Bootstrapping of a NOVA-based system............... 195 7.7.3. Log output on modern PC hardware................. 196 7.7.4. Relation of NOVA’s kernel objects to Genode’s core services... 197 7.7.5. Page-fault handling on NOVA.................... 199 7.7.6. Asynchronous notifications on NOVA................ 199 7.7.7. IOMMU support............................ 200 7.7.8. Genode-specific modifications of the NOVA kernel........ 201 7.7.9. Known limitations of NOVA..................... 205 5 Contents II. Reference 206 8. Functional specification 207 8.1. API primitives.................................. 209 8.1.1. Capability types............................ 209 8.1.2. Sessions and connections....................... 211 8.1.3. Dataspace interface........................... 214 8.2. Component execution environment..................... 218 8.2.1. Interface to the component’s environment............. 218 8.2.2. Parent interface............................