1.3 Overall Design Principles

This section describes some of the general principles and policies we followed in designing the components of the OSKit. This section is most relevant for people developing or modifying the toolkit itself; however, this information may also help users of the toolkit to understand it better and to be able to use it more effectively.

• Cleanly separate and clearly flag architecture- and platform-specific facilities. Although the OSKit currently only runs on the x86 architecture, we plan to port it to other architectures such as the StrongARM in the future. (We will also help with ports by others, e.g., to the DEC Alpha.) Architecture-specific and platform-specific features and interfaces are tagged in this document with boxed icons, e.g., (X86) indicating the Intel x86 processor architecture, and (X86 PC) representing x86-based PC platforms.
• Attempt to make the OSKit's interfaces portable even in situations where their implementation can't be. Although by its nature a large percentage of the implementation of the OSKit is inherently machine-dependent, the interfaces to many of its facilities are very generic and should be usable on most any architecture or platform. For example, the OSKit's device driver interfaces are almost completely portable, even though the device drivers themselves generally aren't.
• Document inter-module dependencies within each library. For function libraries, this means documenting the dependencies between individual functions; for component libraries, this means documenting the dependencies between the different components collected in each library. This policy contrasts to most other third-party libraries, which are usually documented ``black box'' fashion: you are given descriptions of the ``public'' interfaces, and that's it. Although with such libraries you could in principle use part of the library independently from the rest or override individual library components with your own implementations, there is no documentation describing how to do so. Even if such documentation existed, these libraries often aren't well enough modularized internally, so replacing one library component would require understanding and dealing with a complicated web of relationships with other components.

  The downside of this policy is that exposing the internal composition of the libraries this way leaves less room for the implementation to change later without affecting the client-visible interfaces. However, we felt that for the purposes of the OSKit, allowing the client more flexibility in using the library is more important than hiding implementation details.

• Where there is already a standard meaning associated with a symbol, use it. For example, our toolkit assumes that putchar() means the same thing as it does under normal POSIX, and is used the same way, even if it works very differently in a kernel environment. Similarly, the toolkit's startup code starts the kernel by calling the standard main() function with the standard argc and argv parameters, even if the kernel was booted straight off the hardware.
• It is generally safe to call initialization routines more than once with no harmful side-effects, except when the documentation says otherwise. Although this is often unnecessary in particular situations, it increases the overall robustness of the components and decreases hair-pulling since clients can always follow the simple rule, ``if in doubt, initialize it.''