D R A F T
The OSKit: The Flux Operating System Toolkit
Version 0.97
(SnapShot 20020317)

The Flux Research Group
Department of Computer Science
University of Utah
Salt Lake City, UT, USA 84112
http://www.cs.utah.edu/flux/oskit/
oskit@flux.cs.utah.edu

March 17, 2002
Contents
I  Design and Organization
1 Introduction
 1.1 Goals and Scope
 1.2 Road Map
 1.3 Overall Design Principles
 1.4 Configuring the OSKit
 1.5 Building the OSKit
 1.6 Using the OSKit
2 Execution Environments
 2.1 Introduction
 2.2 Pure Model
 2.3 Impure Model
 2.4 Blocking Model
 2.5 Interruptible Blocking Model
II  Interfaces
3 Introduction to OSKit Interfaces
 3.1 Header File Conventions
 3.2 Common Header Files
4 The Component Object Model
 4.1 Objects and Interfaces
 4.2 Reference and Memory Management Conventions
 4.3 Error Handling
 4.4 Binary Issues
 4.5 Source Issues
 4.6 COM Header Files
 4.7 oskit_iunknown: base interface for all COM objects
 4.8 oskit_stream: standard interface for byte stream objects
 4.9 oskit_listener: callback interface for event notification
 4.10 oskit_listener_mgr: Interface for managing multiple listeners
5 Interface Registration
 5.1 oskit_services: registration database
 5.2 Global Registry
6 Synchronization Interfaces
 6.1 oskit_lock: Thread-safe lock interface
 6.2 oskit_condvar: Condition variable interface
 6.3 oskit_lock_mgr: Lock manager: Interface for creating locks and condition variables
7 Input/Output Interfaces
 7.1 oskit_absio: Absolute I/O Interface
 7.2 oskit_asyncio: Asynchronous I/O Interface
 7.3 oskit_blkio: Block I/O Interface
 7.4 oskit_bufio: Buffer-based I/O interface
 7.5 oskit_netio: Network packet I/O interface
 7.6 oskit_posixio: POSIX I/O interface
 7.7 oskit_ttystream: Interface to Unix TTY-like streams
8 OSKit Device Driver (OS Environment) Framework
 8.1 Introduction
 8.2 Organization
 8.3 Driver Sets
 8.4 Execution Model
 8.5 Performance
 8.6 Device Driver Initialization
 8.7 Device Classification
 8.8 Buffer Management
 8.9 Asynchronous I/O
 8.10 Other Considerations
 8.11 Common Device Driver Interface
 8.12 Driver Memory Allocation
 8.13 DMA
 8.14 I/O Ports
 8.15 Hardware Interrupts
 8.16 Sleep/Wakeup
 8.17 Driver-Kernel Interface: Timing
 8.18 Misc
 8.19 Device Registration
 8.20 Block Storage Device Interfaces
 8.21 Serial Device Interfaces
 8.22 Driver-Kernel Interface: (X86 PC) ISA device registration
9 OSKit File System Framework
 9.1 Introduction
 9.2 oskit_principal: Principal Interface
 9.3 oskit_filesystem: File System Interface
 9.4 oskit_file: File Interface
 9.5 oskit_dir: Directory Interface
 9.6 oskit_openfile: Open File Interface
 9.7 Dependencies on the Client Operating System
10 OSKit Networking Framework
 10.1 Introduction
 10.2 oskit_socket: Socket Interface
11 Flask Security Framework
 11.1 flask_types.h: basic Flask types and constants
 11.2 oskit_security: Security Server Interface
 11.3 oskit_avc: AVC Interface
 11.4 oskit_avc_ss: AVC Interface for the Security Server
12 Miscellaneous OSKit Interfaces
 12.1 oskit_random: Interface for random number generators
III  Function Libraries
13 “Client OS” Library: liboskit_clientos.a
 13.1 Introduction
 13.2 Initialization
 13.3 C Library Environment
 13.4 Memory Interface
14 Minimal C Library: liboskit_c.a
 14.1 Introduction
 14.2 POSIX Interface
 14.3 Unsupported Features
 14.4 Header Files
 14.5 Memory Allocation
 14.6 Standard I/O Functions
 14.7 Initialization
 14.8 Termination Functions
 14.9 Miscellaneous Functions
15 Kernel Support Library: liboskit_kern.a
 15.1 Introduction
 15.2 Machine-independent Facilities
 15.3 (X86) Generic Low-level Definitions
 15.4 (X86 PC) Generic Low-level Definitions
 15.5 (X86) Processor Identification and Management
 15.6 (X86) Base Environment
 15.7 (X86) Base Environment: Segmentation Support
 15.8 (X86) Base Environment: Trap Handling
 15.9 (X86) Base Environment: Page Translation
 15.10 (X86) Base Environment: Protected-mode entry and exit
 15.11 (X86 PC) Base Environment: Physical Memory Management
 15.12 (X86 PC) Base Environment: Interrupt Support
 15.13 (X86 PC) Base Environment: Console Support
 15.14 (X86 PC) MultiBoot Startup
 15.15 (X86 PC) Raw BIOS Startup
 15.16 (X86 PC) DOS Startup
 15.17 Remote Kernel Debugging with GDB
 15.18 Serial-line Remote Debugging with GDB
 15.19 Annotations
 15.20 Boot Module Filesystem
 15.21 Signals
16 Symmetric Multiprocessing: liboskit_smp.a
 16.1 Introduction
 16.2 Supported Systems
 16.3 API reference
17 Kernel Device Driver Support: liboskit_dev.a
 17.1 Introduction
 17.2 Device Registration
 17.3 Naming
 17.4 Memory Allocation
 17.5 Buffer Management
 17.6 Processor Bus Resource Management
18 Unix User-Mode Environment: liboskit_unix.a
 18.1 Introduction
 18.2 Converting your OSKit kernel to run on Unix
 18.3 Building for Unix user-mode
 18.4 Running OSKit kernels with Unix support
19 OSKit “Quick Start” Library: liboskit_startup.a
 19.1 Introduction
 19.2 General
 19.3 Disk and Filesystem
 19.4 Network
 19.5 Misc
IV  Component Libraries
20 POSIX Interface Library: liboskit_posix.a
 20.1 Introduction
 20.2 Modified Functions
 20.3 POSIX Message Queue and Semaphore
 20.4 POSIX Signals
 20.5 Client Operating System Dependencies
 20.6 Extended API functions
21 FreeBSD C Library: liboskit_freebsd_c.a
 21.1 Introduction
 21.2 POSIX Interface
 21.3 Malloc Support
 21.4 Signal Support
 21.5 Missing Functionality
 21.6 errno.h
 21.7 Client Operating System Dependencies
 21.8 Library Initialization
22 FreeBSD Math Library: liboskit_freebsd_m.a
 22.1 Introduction
 22.2 Functions
23 Filesystem Namespace: liboskit_fsnamespace.a
 23.1 Introduction
24 Runtime Linker/Loader: liboskit_rtld.a
 24.1 Introduction
25 List-based Memory Manager: liboskit_lmm.a
 25.1 Introduction
 25.2 Memory regions
 25.3 Example use
 25.4 Restrictions and guarantees
 25.5 Sanity checking
 25.6 API reference
26 Address Map Manager: liboskit_amm.a
 26.1 Introduction
 26.2 Addresses and attributes
 26.3 Address maps and entries
 26.4 Simple interface
 26.5 Generic interface
 26.6 Generic interface example
 26.7 External dependencies
 26.8 API reference
27 Simple Virtual Memory: liboskit_svm.a
 27.1 Introduction
 27.2 API reference
28 (X86)NetBSD UVM: liboskit_netbsd_uvm.a
 28.1 Introduction
 28.2 Restrictions
 28.3 Virtual Address Space Layout
 28.4 Memory Interface
 28.5 Threads
 28.6 Page Faults
 28.7 Virtual memory system calls
 28.8 API reference
29 POSIX Threads: liboskit_threads.a
 29.1 Introduction
 29.2 Examples and Caveats
 29.3 POSIX Threads Reference
 29.4 Oskit API Extensions
 29.5 Thread-safe Adaptors
 29.6 InterThread Communication
 29.7 CPU Inheritance Framework
30 (X86)Simple Process: liboskit_sproc.a
 30.1 Introduction
 30.2 Example
 30.3 Requirements
 30.4 System Calls
 30.5 API reference
31 Memory Debugging Utilities: liboskit_memdebug.a
 31.1 Introduction
 31.2 Debugging versions of standard routines
 31.3 Additional Debugging Utilities
32 Profiling Support: liboskit_gprof.a
 32.1 Introduction
 32.2 Caveats
 32.3 API reference
 32.4 Using gprof
 32.5 Files
 32.6 Changing parameters and other FAQs
33 Disk Partition Interpreter: liboskit_diskpart.a
 33.1 Introduction
 33.2 Supported Partitioning Schemes
 33.3 Example Use
 33.4 Restrictions
 33.5 API reference
34 File System Reader: liboskit_fsread.a
 34.1 Introduction
 34.2 External dependencies
 34.3 Limitations
 34.4 API reference
35 Executable Program Interpreter: liboskit_exec.a
 35.1 Header Files
 35.2 Types
 35.3 Function Reference
36 Linux File Systems: liboskit_linux_fs.a
37 NetBSD File Systems: liboskit_netbsd_fs.a
38 Memory File System: liboskit_memfs.a
39 FreeBSD Networking: liboskit_freebsd_net.a
 39.1 Introduction
 39.2 Header Files
 39.3 Interfaces
40 BOOTP Support: liboskit_bootp.a
 40.1 Introduction
 40.2 External Dependencies
 40.3 API reference
41 HPFQ: Hierarchical Network Link Sharing: liboskit_hpfq.a
 41.1 Introduction
 41.2 Configuration
 41.3 Usage
 41.4 API reference
 41.5 External Requirements and Constructors
 41.6 pfq_sched: Interface to PFQ Schedulers
 41.7 pfq_leaf: Interface to PFQ Leaf Nodes
42 Packet Dispatcher: liboskit_pd.a
 42.1 Introduction
 42.2 Example Use
 42.3 Restrictions
 42.4 Sanity checking
 42.5 API reference
43 Linux Driver Set: liboskit_linux_dev.a
 43.1 Initialization and Registration
 43.2 Obtaining object references
 43.3 Introduction
 43.4 Partially-compliant Drivers
 43.5 Internals
 43.6 Block device drivers
 43.7 Network drivers
 43.8 SCSI drivers
44 FreeBSD Driver Set: liboskit_freebsd_dev.a
 44.1 Introduction
 44.2 Supported Devices
 44.3 Header Files
 44.4 Interfaces
 44.5 “Back door” Interfaces
45 Video Support: liboskit_video.a
 45.1 Introduction
 45.2 X11 S3 Video Library
 45.3 Svgalib Video Library
V  Utilities
46 Network Booting
 46.1 Introduction
 46.2 Implementation Issues and Requirements
 46.3 Using NetBoot
VI  The Legal Stuff
47 Copyrights and Licenses
 47.1 Copyrights & Licenses
 47.2 Contributors
 47.3 Acknowledgements
Bibliography
Index