# Phantom architecture review

## Executive summary

The aim of a project is to port PhantomOS to Genode to adapt it to the requirements of modern operating systems and to enhance its security, reliability and extensibility.

## Project description

## Functional requirements

### Platform and environment

1. To be used as platform for SCADA systems
2. Phantom should be able to run on x86 CPUs
3. Environment does not guarantee an absence of power outages

### Requirements

1. System should be able to maintain consistent state of running programs in the presence of power outages and hardware malfunctions
2. The system should provide multiprogramming environment
3. The system should be able to run programs written in at least one mainstream high-level language
4. System should provide POSIX compatibility layer
5. System should be able to communicate with other systems using TCP/IP stack or other network protocols
6. Also system should be able to interact with arbitrary devices

## Business context

### Till the start

1. Phantom OS
- Experimental OS
- Implements orthogonal persistence
- General purpose OS
2. Allows running userspace programs in Phantom language and very basic Java programs using bytecode translation.
3. Phantom VM (PVM) originally supposed to be compatible with JVM and it is planned to add Python support
4. Was actively developing from 2009 to 2011
5. Work continued in 2016 and 2019
6. Founded and being developed by Dmitry Zavalishin, owner of Digital Zone holding.
7. During that time only one developer with plenty of commits by other 4 temporary developers. Generally speaking, only one person knows how system works :)
8. There is no running installations of system at the moment and no clients

### Current work

1. Focus on IoT
2. Shift focus towards security and reliability
3. Provide a basis for a formal verification
4. General aim: adjust the system to modern world and make it usable for, at least, some specific IoT tasks (base of SCADA system)

### Business constraints

1. Time: Till the end of the next semester
2. Money: TBD
3. Team: Me, A. Tormasov as supervisor and D. Zavalishin for consultations
4. Expertise: one 4-th year student and two supervisors with a lot of experience and high expertise in the field. Also other professors of university can help with some particular tasks

### Development constraints

1. Technologies: C language, Genode OS Framework, C++17, java (compiler)
2. Phantom is currently running in 32-bit mode only
3. Legacy: A lot of untested code in C that was written in different time periods
4. Lack of external code reviews and opinions from different developers as well
5. A lot of documentation available, but certain documents are outdated
6. Design decisions
1. Phantom has its own kernel
2. There is no clean way to separate UI from kernel and VM at the moment
3. Global lock during snapshot
4. Drivers are integrated into the kernel
5. Java programs are very limited since the standard library is not available as well as JNI

## Architectural drivers

1. Interoperability
1. interoperability with regular systems

| part | content |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| Source of stimulus | Programmer |
| Stimulus | Wants PhantomOS to be able to communicate with non-Phantom system using TCP/IP stack |
| Environment | Normal execution |
| Artifact | Network driver, network OS components |
| Response | Packets are sent |
| Response measure | Number of packets sent and succesfully processed comparing with the same number on Linux system |

2. interoperability of languages

| part | content |
| ------------------ | -------------------------------------------------------------- |
| Source of stimulus | Programmer |
| Stimulus | Wants run program compiled for JVM |
| Environment | Normal execution |
| Artifact | JVM bytecode translator, Phantom Virtual Machine |
| Response | Code is translated and executed in PVM with the same behaviour |
| Response measure | Tests written for this program are passing |

2. Reliability
1. Should persist restarts, power outages, kernel errors, hardware faults
- Data in the system should be able to persist restarts/unexpected shutdowns and be consistent after them
- Running program should be able to persist restarts/unexpected shutdowns and be able to restore from the last snapshot so that it would be seamless

| part | content |
| ------------------ | ----------------------------------------------------------------------------- |
| Source of stimulus | External factor |
| Stimulus | Causes unexpected restart |
| Environment | Power outage or hardware malfunction |
| Artifact | Whole operating system |
| Response | Userspace programs will start in the state same as right before the shutdown |
| Response measure | Programs execution state and their data are in consistent state after restart |

3. Robustness
1. it should be able to continue running or restart and restore from checkpoint if one or more components of the system malfunctioned

| part | content |
| ------------------ | ----------------------------------------------------------------------------- |
| Source of stimulus | Internal error |
| Stimulus | Causes unexpected restart |
| Environment | Kernel error occured or OS component failure happened |
| Artifact | Whole operating system |
| Response | Userspace programs will start in the state same as right before the shutdown |
| Response measure | Programs execution state and their data are in consistent state after restart |

4. Performance
1. comparable performance relatively to modern systems

| part | content |
| ------------------ | ---------------------------------------------------------------------------------------- |
| Source of stimulus | User |
| Stimulus | System runs SCADA workloads |
| Environment | Normal operation |
| Artifact | Whole operating system |
| Response | Execution time of operations performed is comparable to other OSs running same workloads |
| Response measure | Execution time on Phantom should be not more than 5% bigger comparing to Linux |

2. small and predictable (as far as possible) restart time
- small and predictable checkpointing time

| part | content |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| Source of stimulus | User |
| Stimulus | Starts the system |
| Environment | Normal operation, attached devices have predictable initialization time |
| Artifact | Whole system |
| Response | The system should finish all initialization procedures in a small and predictable period of time |
| Response measure | The system should start in less than 5 seconds (with adjustments given current hardware configuration) |

5. Scalability
1. system should be able to use hardware accelerators

| part | content |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| Source of stimulus | User |
| Stimulus | Installs the system on the hardware providing any kind of hardware acceleration with corresponding drivers |
| Environment | Normal operation |
| Artifact | Virtual machine, drivers |
| Response | Userspace programs should be able to use hardware acceleration |
| Response measure | Code segments that are using hardware acceleration should be able to use it |

2. system should be able to scale to the given hardware resources

| part | content |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| Source of stimulus | User |
| Stimulus | Installs system on the hardware with different CPU, memory and disk configurations |
| Environment | Normal operation |
| Artifact | Resource management system |
| Response | System should be able to use all available cores, memory and disk space |
| Response measure | Userspace programs will be able to use more memory. More threads should be able to run in parallel |

6. debugability
1. system should provide debugger for userspace programs and kernel as well

| part | content |
| ------------------ | -------------------------------------------------------------------------------------------- |
| Source of stimulus | Developer |
| Stimulus | Wants to debug a program or new system feature |
| Environment | Debugging |
| Artifact | Whole system |
| Response | Debugging interfaces should be provided |
| Response measure | Developer should easily access required debugging information and control the execution flow |

7. extensibility
1. It should be possible to add new driver for new device as a separate component without modifications in the kernel or system in general

| part | content |
| ------------------ | ----------------------------------------------------------------------------------------- |
| Source of stimulus | Developer |
| Stimulus | Wants to add a new driver |
| Environment | Development |
| Artifact | Virtual machine, drivers |
| Response | New driver will be added to the system |
| Response measure | Addition of a new driver should not affect the code of any other components of the system |

2. System should provide opportunity for adding new VM native methods to be called from userspace without modifications in the kernel or system in general

| part | content |
| ------------------ | ----------------------------------------------------------------------------------------- |
| Source of stimulus | Developer |
| Stimulus | Wants to add a new native method for virtual machine |
| Environment | Development |
| Artifact | Virtual machine, required by the method components |
| Response | New method will be added to the system |
| Response measure | Addition of a new method should not affect the code of any other components of the system |

8. security
1. atack on one component of the system should not affect others
- userspace processes should not know about other processes without clear permission
- userspace processes should not communicate with other processes without clear permission

| part | content |
| ------------------ | ---------------------------------------------------------------------- |
| Source of stimulus | Malicious code |
| Stimulus | Is being executed by one of the programs or components of the system |
| Environment | Normal operation |
| Artifact | Affected program and modules it is using |
| Response | Malicious code can't see requested information or permission is denied |
| Response measure | No other modules or programs affected |

## Architecture decisions

- Translators provided for interoperability with other languages
- Why: Required by QAS 1.1.
- Alternatives:
- Implement a specification of JVM. Too much work force is needed not only to implement but also to adapt it to persistence model.
- Use C/C++ for userspace programs. It will introduce too much complications to the development process and number of limitation to the language capabilities as well.
- Orthogonal persistence and checkpointing mechanism
- Why: QASs in sections 2, 3. Also it is used to provide persistence without persistence API.
- Alternatives:
- Provide API to access persistence store. This approach will introduce a lot of problems to the programmer. Also DBs are providing the same functionality in some sense.
- Security, extensibility and certain reliability issues may be solved using Genode
- Why: QASs in sections 5,6,7,8.
- Alternatives:
- Actually, Genode is the only platform that is able to provide such a functionality at the moment. The other option is to implement everything from scratch, but it will definetely cost too much.

## Views

### What components of Phantom OS can be replaced by Genode

### Bytecode translation process