From 805fae5babd2845bddea8ba2d5d168f8767555b3 Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Fri, 10 Mar 2023 11:29:58 +0100 Subject: [PATCH] Update README files This patch removes outdated information and improves the language of various README files. --- README | 14 +++++----- repos/base-nova/README | 7 +---- repos/base-okl4/README | 7 +---- repos/base-okl4/contrib/generated/README | 8 ++---- repos/base-okl4/tool/README | 3 --- repos/base-pistachio/README | 4 +-- repos/base/README | 30 +++++++++------------ repos/base/include/README | 3 --- repos/base/lib/README | 1 - repos/base/lib/mk/README | 34 ++++++++---------------- repos/base/src/README | 1 - repos/dde_ipxe/README | 8 +++--- repos/dde_rump/README | 2 +- repos/demo/src/lib/mini_c/README | 4 +-- repos/gems/README | 11 ++++---- repos/libports/README | 16 +++++------ repos/ports/README | 8 +++--- 17 files changed, 59 insertions(+), 102 deletions(-) delete mode 100644 repos/base-okl4/tool/README delete mode 100644 repos/base/include/README delete mode 100644 repos/base/lib/README delete mode 100644 repos/base/src/README diff --git a/README b/README index ccfac2e3db..8917ab2583 100644 --- a/README +++ b/README @@ -4,15 +4,17 @@ ================================= -This is the source tree of the reference implementation of the Genode OS -architecture. For a general overview about the architecture, please refer to -the project's official website: +This is the source code of Genode, which is a framework for creating +component-based operating systems. It combines capability-based security, +microkernel technology, sandboxed device drivers, and virtualization with +a novel operating system architecture. For a general overview about the +architecture, please refer to the project's official website: -:Official project website for the Genode OS Framework: +:Website for the Genode OS Framework: [https://genode.org/documentation/general-overview] -The current implementation can be compiled for 8 different kernels: Linux, +Genode-based operating systems can be compiled for a variety of kernels: Linux, L4ka::Pistachio, L4/Fiasco, OKL4, NOVA, Fiasco.OC, seL4, and a custom "hw" microkernel for running Genode without a 3rd-party kernel. Whereas the Linux version serves us as development vehicle and enables us to rapidly develop the @@ -22,7 +24,7 @@ one. If a microkernel pretended to be fit for all use cases, it wouldn't be "micro". Hence, all microkernels differ in terms of their respective features, complexity, and supported hardware architectures. -Genode allows the use of each of the kernels listed above with a rich set of +Genode allows for the use of each of the supported kernels with a rich set of device drivers, protocol stacks, libraries, and applications in a uniform way. For developers, the framework provides an easy way to target multiple different kernels instead of tying the development to a particular kernel technology. For diff --git a/repos/base-nova/README b/repos/base-nova/README index 5222292c52..938a359142 100644 --- a/repos/base-nova/README +++ b/repos/base-nova/README @@ -1,10 +1,5 @@ This repository contains the port of Genode to the NOVA microhypervisor. -For more information on this base platform, please refer to the official -website. +For more information on this kernel, please refer to the official website. :[http://hypervisor.org]: Official website for the NOVA microhypervisor. - -For information on using Genode on NOVA, please revisit the documentation at -'base-nova/doc/nova.txt': - diff --git a/repos/base-okl4/README b/repos/base-okl4/README index e3da3ffa9a..8105383eae 100644 --- a/repos/base-okl4/README +++ b/repos/base-okl4/README @@ -1,6 +1 @@ -This repository contains the implementation of Genode for the OKL4 -kernel version 2.1. For further information, please refer to the -following website: - -:[http://genode.org/documentation/articles/genode-on-okl4 - Bringing Genode to OKL4]: - This article explains the OKL4-specific porting work. +This repository contains the support of Genode for the OKL4 kernel version 2.1. diff --git a/repos/base-okl4/contrib/generated/README b/repos/base-okl4/contrib/generated/README index 9094cae310..f307febbf1 100644 --- a/repos/base-okl4/contrib/generated/README +++ b/repos/base-okl4/contrib/generated/README @@ -1,8 +1,4 @@ This directory and its subdirectories contain machine-generated code, produced when building the OKL4 kernel with its native Scons build environment. - -It is not part of the Genode project and remains under the licence of the OKL4 kernel. - -You can obtain the OKL4 kernel version 2.1.1. here: - -[http://www.ok-labs.com - Open Kernel Labs] +It is not part of the Genode project and remains under the licence of the OKL4 +kernel. diff --git a/repos/base-okl4/tool/README b/repos/base-okl4/tool/README deleted file mode 100644 index 2287bccb39..0000000000 --- a/repos/base-okl4/tool/README +++ /dev/null @@ -1,3 +0,0 @@ -This directory contains the following utilities for working with Genode -on OKL4. - diff --git a/repos/base-pistachio/README b/repos/base-pistachio/README index 8d8d81f71a..92ca674872 100644 --- a/repos/base-pistachio/README +++ b/repos/base-pistachio/README @@ -1,3 +1 @@ -This repository contains the L4ka::Pistachio-specific implementation of Genode. -Please see the documentation at 'base-pistachio/doc/pistachio.txt' for further -instructions on building and using Genode on the L4ka::Pistachio kernel. +This repository contains the L4ka::Pistachio-specific parts of Genode. diff --git a/repos/base/README b/repos/base/README index 6356c8599f..4c9f74bf56 100644 --- a/repos/base/README +++ b/repos/base/README @@ -1,19 +1,18 @@ -This is generic part of the Genode implementation. It consists of two parts: +This is the generic Genode base system, which consists of two parts: -:_Core_: is the ultimate root of the Genode application tree - and provides abstractions for the lowest-level hardware resources - such as RAM, ROM, CPU, and generic device access. All generic parts of Core - can be found here - for system-specific implementations refer to the - appropriate 'base-' directory. +:_Core_: is the root of the Genode component tree. It provides abstractions for + the lowest-level hardware resources such as RAM, ROM, CPU, and device access. + All generic parts of core can be found here. For kernel-specific parts, + refer to the appropriate 'base-' directory. -:_Base libraries and protocols_: that are used by each Genode component +:_Base libraries and interfaces: that are used by each Genode component to interact with other components. This is the glue that holds everything together. -_Core_ may export information about the hardware platform by an ROM -called 'platform_info'. Depending on the platform, e.g. ARM or x86 or riscv, -and depending on the boot mode and boot loader and kernel, some nodes may not -be populated. +Depending on the used kernel, core may export information about the hardware +platform as a ROM called 'platform_info'. For example, if the ACPI RSDT and +XSDT physical pointer are reported by the used kernel and/or bootloader, core +provides this information in the ROM as follows. ! ! @@ -22,9 +21,6 @@ be populated. ! ! -If the ACPI RSDT and XSDT physical pointer is reported by the used kernel -and/or bootloader, _Core_ may provide this information by the ROM. - -If the graphic device is initialised and can be directly used by a framebuffer -driver, _Core_ may provide the physical pointer to the framebuffer, the -resolution and color depth in bits. +If the graphics device is initialised and can be directly used by a +framebuffer driver, core provides the physical pointer to the framebuffer, the +resolution, and color depth in bits. diff --git a/repos/base/include/README b/repos/base/include/README deleted file mode 100644 index b17d4a69b5..0000000000 --- a/repos/base/include/README +++ /dev/null @@ -1,3 +0,0 @@ -This directory contains include files of interfaces that are exported -by components to be used by other components. Each subdirectory corresponds -to the component exporting the interface. diff --git a/repos/base/lib/README b/repos/base/lib/README deleted file mode 100644 index 8b5b8affc6..0000000000 --- a/repos/base/lib/README +++ /dev/null @@ -1 +0,0 @@ -This directory holds library-description files. diff --git a/repos/base/lib/mk/README b/repos/base/lib/mk/README index 6e3381812a..d829a9ce54 100644 --- a/repos/base/lib/mk/README +++ b/repos/base/lib/mk/README @@ -1,24 +1,12 @@ -This directory contains library description files. Each '.mk' file -holds the instruction for building the library ''. These makefiles are -never used directly but they are called from the build system when required. -When called, the build system passes the following variables: +This directory contains library-description files. Each _.mk_ file +contains the instructions for building the library __. The .mk files +are never used directly but they are implicitely processed by the build +system. -:'BASE_DIR': This is the base directory of the source tree. - -Source codes are specified by setting the 'SRC_CC' and 'SRC_C' variables. -The source code locations must be specified via 'vpath'. -A library can include other libraries by setting the 'LIBS' -variable. - -Each '.mk' file must include the 'lib.mk' role file: - -! include $(BASE_DIR)/mk/lib.mk - -Libraries implementing one and the same library interface may have specific -implementations for different platforms. Such platform-specific '.mk' -files should be placed into corresponding subdirectories. For example, the -'linux'-specific implementation of the 'server' library resides in the 'linux/' -subdirectory. The build system automatically searches the right '.mk' -file by evaluating the 'SPECS' configuration variable. If 'SPECS' is set to -'host linux', the build system will look into the directories './', './host', -and './linux'. +Libraries implementing one interface may have specialized implementations for +different CPU architectures. Such architecture-specific _.mk_ files +are located in corresponding _spec/_ subdirectories. For example, the .mk +files of ARM-specific library variants reside in the _spec/arm/_ subdirectory. +The build system automatically finds the appropriate _.mk_ file by +evaluating the 'SPECS' build-configuration variable. Whenever the 'SPECS' +variable contains 'arm', the build system considers the _spec/arm/_ directory. diff --git a/repos/base/src/README b/repos/base/src/README deleted file mode 100644 index 3dbaa0f09a..0000000000 --- a/repos/base/src/README +++ /dev/null @@ -1 +0,0 @@ -This directory contains all source codes. diff --git a/repos/dde_ipxe/README b/repos/dde_ipxe/README index 18902f7a1d..0796410e01 100644 --- a/repos/dde_ipxe/README +++ b/repos/dde_ipxe/README @@ -1,4 +1,4 @@ -This repository contains the Device Driver Environment for the +This repository contains the device-driver environment (DDE) for the "donator OS" iPXE available from http://ipxe.org/. For building DDE iPXE, you first need to fetch and patch the original @@ -7,14 +7,14 @@ sources. The 'prepare_port' tool automates this task. Just issue: ! ./tool/ports/prepare_port dde_ipxe Now, you need to include the DDE iPXE repository into your Genode -build process. Just add the path to this directory to the +build configuration by adding the path to this directory to the 'REPOSITORIES' declaration of the 'etc/build.conf' file within your build directory, for example ! REPOSITORIES += $(GENODE_DIR)/repos/dde_ipxe -After successful build the DDE iPXE based ethernet driver is located -at 'bin/nic_drv'. +After a successful build the DDE iPXE based ethernet driver is located +at 'bin/ipxe_nic_drv'. The driver optionally reports the following information under the label "devices" if requested in the config as depicted. diff --git a/repos/dde_rump/README b/repos/dde_rump/README index 7c39e76e6f..7cb461cdae 100644 --- a/repos/dde_rump/README +++ b/repos/dde_rump/README @@ -28,7 +28,7 @@ to your _etc/build.conf_ file of you build directory. Finally, -! make lib/vfs/rump +! make lib/vfs_rump called from your build directory will build the plugin. diff --git a/repos/demo/src/lib/mini_c/README b/repos/demo/src/lib/mini_c/README index 57c6253879..ef71352bf6 100644 --- a/repos/demo/src/lib/mini_c/README +++ b/repos/demo/src/lib/mini_c/README @@ -1,5 +1,5 @@ Mini C library -This library only provides the libc support for libz and libpng. +This library only rudimentary libc support for libz and libpng. Most functions are not implemented. The implemented functions might be -slightly incompatible to a real libc. Please use this library with caution! +slightly incompatible to a real libc. diff --git a/repos/gems/README b/repos/gems/README index 989acfb255..8817aceca0 100644 --- a/repos/gems/README +++ b/repos/gems/README @@ -1,6 +1,5 @@ -This directory is a source-code repository containing Genode-specific -services and applications. In contrast to the components that come with -the 'os' repository, programs contained in 'gems' are able to leverage -the functionalities provided by higher-level repositories such as 'libports'. -To use the 'gems' repository, make sure to also add those repositories to your -build configuraion. +This directory is a source-code repository containing Genode-specific services +and applications. In contrast to the components hosted in the 'os' repository, +programs contained in 'gems' are able to leverage the functionalities provided +by higher-level repositories such as 'libports'. To use the 'gems' repository, +make sure to also add those repositories to your build configuraion. diff --git a/repos/libports/README b/repos/libports/README index 9ea5a469a7..1560836c86 100644 --- a/repos/libports/README +++ b/repos/libports/README @@ -1,12 +1,12 @@ -This directory contains ports of popular 3rd-party software to Genode. +This directory contains ports of 3rd-party libraries to Genode. Usage ----- The tool './tool/ports/prepare_port' in the toplevel directory automates the -task of downloading and preparing the library source codes. You can select -individual packages that have to be prepared by specifying their base names +task of downloading and preparing the 3rd-party source codes. One can select +individual ports that have to be prepared by specifying their base names (without the version number) as command-line argument. For example, the following command prepares both the C library and the Freetype library: ! ./tool/ports/prepare_port libc freetype @@ -28,11 +28,7 @@ files. How does 'libports' relate to the other repositories? ----------------------------------------------------- -Most libraries hosted in the 'libports' repository expect a complete C library, -which is provided with the 'libc' package. Please do not forget to prepare the -libc package when using any of the other libports packages. The libc, in turn, -depends on the 'os' repository for its back end. Because the 'os' repository is -the home of the dynamic linker, libraries contained in 'libports' are safe to -assume the presence of the dynamic linker and, thus, should be built as shared -libraries. +Most libraries hosted in the 'libports' repository expect a complete C +library, which is provided via the 'libc' port. The libc, in turn, depends on +the 'os' repository for its back end. diff --git a/repos/ports/README b/repos/ports/README index e86e9dea7f..2e2862effd 100644 --- a/repos/ports/README +++ b/repos/ports/README @@ -1,13 +1,13 @@ -This directory contains ports of popular 3rd-party applications to Genode. +This directory contains ports of 3rd-party applications to Genode. -The 'ports' repository follows the line of the 'libports' repository. +The 'ports' repository follows the patterns of the 'libports' repository. For instructions about downloading and building 3rd-party applications, -please refer to 'libports/README'. +please refer to _libports/README_. Dependencies from other repositories ------------------------------------ -Application provided by the 'ports' repository typically expect a rich +Applications provided by the 'ports' repository typically expect a rich runtime environment, including shared libraries provided by the 'libports' repository. Hence, 'ports' depends on 'libports'.