Skip to content

Commit

Permalink
doc: correct markdown issues
Browse files Browse the repository at this point in the history
JIRA: CI-290
  • Loading branch information
maska989 committed Jul 6, 2023
1 parent 242a2c2 commit 8c1034d
Show file tree
Hide file tree
Showing 209 changed files with 6,618 additions and 5,423 deletions.
79 changes: 66 additions & 13 deletions architecture.md
Original file line number Diff line number Diff line change
@@ -1,51 +1,104 @@
# Architecture

The Phoenix-RTOS operating system starting from version 3 is based on microkernel architecture. It means that system consists of microkernel implementing basic primitives and set of servers based on these primitives and communicating over it. The main advantage of such architecture is high scalability. The disadvantage is performance degradation caused by message passing. Message passing demands in some cases memory copying and additional thread context switching.
The Phoenix-RTOS operating system starting from version 3 is based on microkernel architecture.
It means that system consists of microkernel implementing basic primitives and set of servers based on these primitives
and communicating over it.
The main advantage of such architecture is high scalability.
The disadvantage is performance degradation caused by message passing.
Message passing demands in some cases memory copying and additional thread context switching.

The architecture is schematically presented on figure below.

<img src="_images/arch1.png" >

## Microkernel

Microkernel implements minimum set of primitives necessary to implement other operating system components. Phoenix-RTOS microkernel implements four fundamental subsystems - memory management, process and thread management, interprocess communication and low-level I/O for redirecting the interrupts to user-level threads. Microkernel functionalities are accessible for applications through set of system calls. System call (syscall) is the operating system function implemented by the special processor instruction switching the execution privilege mode from user to system. After switching the execution mode from user to system privilege level program is able to execute privileged instructions and access the system memory segments and I/O space.
Microkernel implements minimum set of primitives necessary to implement other operating system components.
Phoenix-RTOS microkernel implements four fundamental subsystems - memory management, process and thread management,
interprocess communication and low-level I/O for redirecting the interrupts to user-level threads. Microkernel
functionalities are accessible for applications through set of system calls. System call (syscall) is the operating
system function implemented by the special processor instruction switching the execution privilege mode from user to
system. After switching the execution mode from user to system privilege level program is able to execute privileged
instructions and access the system memory segments and I/O space.

To understand the microkernel architecture please refer to chapter [Kernel architecture](kernel/README.md).

## Interprocess communication

The main functionality provided by microkernel necessary to implement the operating system is the interprocess communication (IPC). In the figure above microkernel was shown as the bus between other system components and this is the main factor which differentiates the microkernel-based operating system from the traditional monolithic kernel based operating system. All system components interact with each other using message passing. For example file operations are performed by communicating with file servers. Such approach affects tremendously system scalability and modularity. The local communication based on shared memory can be easily extended to the remote communication using network. The modules (servers) implementing specific functionalities can be easily added and removed from the system due to message passing restricting interactions between them to a well-structured format. Servers partition the operating system functionality in the natural way. The message passing should be implemented in such a way that minimizes the communication overhead. Consequently it should be supported by some virtual memory mechanisms like physical memory sharing. In the further considerations it is assumed that messages are sent to the ports registered by servers. Ports together with identifiers of data structures operated by servers (e.g. files) identify operating system objects.

Interprocess communication has been described in [Kernel - Processes and threads - Message passing](kernel/proc/msg.md) chapter.
The main functionality provided by microkernel necessary to implement the operating system is the interprocess
communication (IPC). In the figure above microkernel was shown as the bus between other system components and this
is the main factor which differentiates the microkernel-based operating system from the traditional monolithic kernel
based operating system. All system components interact with each other using message passing. For example file
operations are performed by communicating with file servers. Such approach affects tremendously system scalability and
modularity. The local communication based on shared memory can be easily extended to the remote communication using
network. The modules (servers) implementing specific functionalities can be easily added and removed from the system
due to message passing restricting interactions between them to a well-structured format. Servers partition the
operating system functionality in the natural way. The message passing should be implemented in such a way that
minimizes the communication overhead. Consequently it should be supported by some virtual memory mechanisms like
physical memory sharing. In the further considerations it is assumed that messages are sent to the ports registered by
servers. Ports together with identifiers of data structures operated by servers (e.g. files) identify operating system
objects.

Interprocess communication has been described in [Kernel - Processes and threads - Message passing](kernel/proc/msg.md)
chapter.

## Standard library

Standard library is the set of functions constituting the basic programming environment (providing the basic API) and based on the system calls. API could be compatible with popular programming standards (ANSI C, POSIX etc.) or could be specific for the operating system. Phoenix-RTOS 3 provides its own standard library (`libphoenix`) compatible with ANSI C89 and extended with some specific functions for memory mapping and process and thread management. The library can be extended (in cooperation with servers) with additional functions to provide the POSIX compliant environment. Such environment requires much more memory than basic ANSI C native interface but allows for execution of the popular open-source UN*X applications.
Standard library is the set of functions constituting the basic programming environment (providing the basic API) and
based on the system calls. API could be compatible with popular programming standards (ANSI C, POSIX etc.) or could be
specific for the operating system. Phoenix-RTOS 3 provides its own standard library (`libphoenix`) compatible with ANSI
C89 and extended with some specific functions for memory mapping and process and thread management. The library can be
extended (in cooperation with servers) with additional functions to provide the POSIX compliant environment. Such
environment requires much more memory than basic ANSI C native interface but allows for execution of the popular
open-source UN*X applications.

Standard library has been described in [Standard library](libc/README.md) chapter.

## Servers

In the microkernel architecture servers plays very important role in the whole operating system. They provide functionalities removed from the traditional, monolithic kernel and moved to the user space. Good examples of such functionalities are file management or device management (device drivers). The main method for communicating with server is message passing. Each server allocates and registers set of ports used to receive messages from other system components. For example the file server registers new port in the filesystem space. Device driver registers new name in the `/dev` directory.
In the microkernel architecture servers plays very important role in the whole operating system. They provide
functionalities removed from the traditional, monolithic kernel and moved to the user space. Good examples of
such functionalities are file management or device management (device drivers). The main method for communicating
with server is message passing. Each server allocates and registers set of ports used to receive messages from other
system components. For example the file server registers new port in the filesystem space. Device driver registers
new name in the `/dev` directory.

Server concept and server registering are described in [Kernel - Processes and threads - Servers and namespace](kernel/proc/namespace.md) chapter.
Server concept and server registering are described in
[Kernel - Processes and threads - Servers and namespace](kernel/proc/namespace.md) chapter.

## Device drivers

Device drivers are specific servers responsible for controlling devices. They can implement protocol for I/O operations enabling to use them like files. Special mechanism is used to allow user level processes to communicate with the hardware. In architectures without I/O address space where device registers are accessible in the memory address space the special memory mapping is used. When device uses I/O space (e.g. ports on IA32) special processor flag is set permitting the unprivileged code to access the parts or whole I/O space. The flag is set during runtime using specific system call. Second important issue which should be discussed here is interrupt handling. When device drivers run on user-level, interrupts are redirected to the selected processes and interrupt handling routines are implemented as regular functions.
Device drivers are specific servers responsible for controlling devices. They can implement protocol for I/O operations
enabling to use them like files. Special mechanism is used to allow user level processes to communicate with the
hardware. In architectures without I/O address space where device registers are accessible in the memory address space
the special memory mapping is used. When device uses I/O space (e.g. ports on IA32) special processor flag is set
permitting the unprivileged code to access the parts or whole I/O space. The flag is set during runtime using specific
system call. Second important issue which should be discussed here is interrupt handling. When device drivers run on
user-level, interrupts are redirected to the selected processes and interrupt handling routines are implemented as
regular functions.

To understand the device drivers architecture and method of development of new drivers please refer to chapter [Device drivers](devices/README.md).
To understand the device drivers architecture and method of development of new drivers please refer to chapter
[Device drivers](devices/README.md).

## File servers

File servers are specialized servers implementing filesystem. Similarly to device drivers they implement specific protocol for filesystem operations (for opening, closing, reading and writing files and for operating on directories). Any fileserver can handle any part of the namespace. The selected part of the namespace is assigned to the server by registering its port for the selected directory entry. When applications use the part of the namespace handled by the server during the path resolution procedure, the server`s port is returned in the object identifier and all communication is redirected to the server.
File servers are specialized servers implementing filesystem. Similarly to device drivers they implement specific
protocol for filesystem operations (for opening, closing, reading and writing files and for operating on directories).
Any fileserver can handle any part of the namespace. The selected part of the namespace is assigned to the server by
registering its port for the selected directory entry. When applications use the part of the namespace handled by the
server during the path resolution procedure, the server`s port is returned in the object identifier and all
communication is redirected to the server.

File servers are described in [Filesystems](filesystems/README.md) chapter.

## Emulation servers

Microkernel architecture allows to easily emulate the application environment of existing operating systems (e.g. POSIX). To provide some OS specific mechanisms which are not supported by native Phoenix-RTOS environment (e.g. POSIX pipes, user and groups etc.) emulation servers should be provided. They implement the additional functionality and together with emulation libraries provide the application environment. The communication protocol implemented by these servers is specific for emulated application environment.
Microkernel architecture allows to easily emulate the application environment of existing operating systems
(e.g. POSIX). To provide some OS specific mechanisms which are not supported by native Phoenix-RTOS environment
(e.g. POSIX pipes, user and groups etc.) emulation servers should be provided. They implement the additional
functionality and together with emulation libraries provide the application environment. The communication protocol
implemented by these servers is specific for emulated application environment.

## See also

1. [Table of Contents](README.md)
1. [Table of Contents](README.md)
13 changes: 9 additions & 4 deletions building/project.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Reference project

The main repository of Phoenix-RTOS is the [phoenix-rtos-project](https://github.com/phoenix-rtos/phoenix-rtos-project.git). The project consists of the following Github submodule repositories.
The main repository of Phoenix-RTOS is the
[phoenix-rtos-project](https://github.com/phoenix-rtos/phoenix-rtos-project.git).
The project consists of the following Github submodule repositories.

- [libphoenix](https://github.com/phoenix-rtos/libphoenix.git) </br>
Standard C library. Written from scratch for Phoenix-RTOS
Expand All @@ -23,7 +25,8 @@ The main repository of Phoenix-RTOS is the [phoenix-rtos-project](https://github
- [phoenix-rtos-ports](https://github.com/phoenix-rtos/phoenix-rtos-ports.git) </br>
Linux (and potentially other OSes) applications ported to Phoenix-RTOS
- [phoenix-rtos-posixsrv](https://github.com/phoenix-rtos/phoenix-rtos-posixsrv.git) </br>
POSIX server; userspace server that is providing additional POSIX features not provided by the kernel itself (e.g. pipes)
POSIX server; userspace server that is providing additional POSIX features not provided by the kernel itself (e.g.
pipes)
- [phoenix-rtos-tests](https://github.com/phoenix-rtos/phoenix-rtos-tests.git) </br>
Tests based on our own framework
- [phoenix-rtos-usb](https://github.com/phoenix-rtos/phoenix-rtos-usb.git) </br>
Expand All @@ -47,11 +50,13 @@ There are also other directories and files directly in `phoenix-rtos-project`.

- `scripts` - bash scripts for running Phoenix-RTOS on simulators (e.g. QEMU),

- `build.project` - bash include file, defines how to build the whole system, it is included by phoenix-rtos-build/build.sh,
- `build.project` - bash include file, defines how to build the whole system, it is included by
phoenix-rtos-build/build.sh,

- `busybox-config` - configuration for busybox (baseline Linux based toolkit and shell),

- `docker-build.sh` - script for building using docker (docker allows user to not have toolchain on his or her development PC).
- `docker-build.sh` - script for building using docker (docker allows user to not have toolchain on his or
her development PC).

## See also

Expand Down
18 changes: 13 additions & 5 deletions building/script.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,20 @@
# Building script

To build Phoenix-RTOS system image build.sh script is used. The simplest way to build the image is the following command.
To build Phoenix-RTOS system image build.sh script is used. The simplest way to build the image is the
following command.

```bash
TARGET=ia32-generic-qemu phoenix-rtos-build/build.sh all
```

As you can see there can be other arguments like `all`.

You can also use the `clean` argument to clean last build artifacts.

```bash
TARGET=ia32-generic-qemu phoenix-rtos-build/build.sh clean all
```

When you want to compile only the new changes and save time you don't have to use it.

The `all` argument specifies that all system components for a given target should be compiled (excluding tests).
Expand All @@ -30,20 +34,24 @@ The available components are listed below:

For example, in ia32-generic-qemu target `all` means `core fs image project ports`.</br>
For the other targets `all` can be different components configurations. </br>
You can also choose what components do you want to build, for example the following command will build a system image without test and ports components.
The `ports` component compiling process can take a while. If you need to build the system image quickly, you can use the command above.
You can also choose what components do you want to build, for example the following command will build a system image
without test and ports components.
The `ports` component compiling process can take a while. If you need to build the system image quickly, you can use the
command above.

```bash
TARGET=ia32-generic-qemu phoenix-rtos-build/build.sh core fs image project test
```

For ia32-generic-qemu target, running the system in a separate window isn't the only option. There is the possibility to run it in a terminal, in that case, you have to set a few other variables.
For ia32-generic-qemu target, running the system in a separate window isn't the only option. There is the possibility to
run it in a terminal, in that case, you have to set a few other variables.

```bash
TARGET=ia32-generic-qemu CONSOLE=serial ./phoenix-rtos-build/build.sh all
```

After the build completes, the disk image and all files needed to run it will be created and placed in the _boot directory.
After the build completes, the disk image and all files needed to run it will be created and placed in the _boot
directory.

## See also

Expand Down
6 changes: 4 additions & 2 deletions corelibs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@

Phoenix-RTOS provides libraries, which enable the development of applications.

The source code is available in the [phoenix-rtos-corelibs](https://github.com/phoenix-rtos/phoenix-rtos-corelibs) Github repository.
The example of usage can be found in the `_user` directory, placed in [phoenix-rtos-project](https://github.com/phoenix-rtos/phoenix-rtos-project).
The source code is available in the [phoenix-rtos-corelibs](https://github.com/phoenix-rtos/phoenix-rtos-corelibs)
Github repository.
The example of usage can be found in the `_user` directory, placed in
[phoenix-rtos-project](https://github.com/phoenix-rtos/phoenix-rtos-project).

Read more about reference project repository [here](../project.md).

Expand Down
Loading

0 comments on commit 8c1034d

Please sign in to comment.