system-design: initiative

Author: pavl-g

docs/build-system/README.md

@@ -0,0 +1,24 @@
+# Electrostatic-Drivers Model
+
+The following document presents the problem analysis, decomposition, and the suggested solutions, eventually the proposed system design for this software. 
+
+## Table of contents:
+1) Design Problem Specification.
+	* 1.1 Functional Problem bulk.
+	* 1.2 Functional Problems decomposition.
+	* 1.3 Non-functional Problems.
+2) Components Design Specification.
+	* 2.1 Entity-Structural Components.
+	* 2.2 Machine Components.
+3) System Design Specification.
+	* 3.1 Putting all together.
+4) Detailed Design Specification.
+	* 4.1 Hardware Devices.
+	* 4.2 Wiring hardware devices on motherboards.
+	* 4.3 Software Bus Drivers Structure.
+	* 4.4 Software Bus Device Drivers Structure.
+	* 4.5 Software Character/Block Device Drivers Structure.
+	* 4.6 Initialization Routines.
+	* 4.7 Failure Routines.
+	* 4.8 Fallback Routines and Fallback Criteria.
+	

docs/electro-drivers/README.md

@@ -0,0 +1,55 @@
+# Components Design Specification
+
+**Preface:**
+The components design specification is to provide solutions to the previously stated problem parts in the [problem document](). 
+
+A **component** is a piece of software or a physical hardware or a conceptual model that targets a specific part of the problem; though commonly a component is a piece of software from a high-level perspective.
+
+**Driver component-based diagrams** provide structural overview of the overall system to solve a particular set of problems in the driver development domain.
+
+## Table of contents:
+1) Entity-Structural Components.
+    * Section 1.1: Abstract Definitions and General Layout.
+    * Section 1.2: Defining system parts.
+2) Machine Components.
+    * Section 2.1: Abstract Definitions and General Layout.
+    * Section 2.2: Defining the _Electrostatic-Drivers_ system machine.
+
+## 1) Entity-Structural Components:
+
+### Section 1.1: Abstract Definitions and General Layout
+
+**General definition**: Entity-Structural components design model starts by defining the structural components of the system first; then grouping those components under entities.
+
+**Mathematical Abstraction**: The system structure could be represented as **structural sets of components**; such that each set define **structural properties** in the form of a predicate function, and components from a set must match those properties, otherwise they wouldn't be eligible to be grouped under this structural set.
+
+**Lemma.01**: Let $\Epsilon$ be the entity-structural framework; a set that groups all **the structural sets of the system components**; with a single common property is that they are **structural sets of components**, $\Gamma$ be a structural set of components, $\gamma$ be a component of that structural set, and $P(...)$ be a predicate function defining a property for that component.
+
+* $$ \Epsilon = \bigcup_{i=0}^{n} \Gamma_{i}$$
+* $$ \Gamma = \bigcup_{i=0}^{n} \gamma_{i}$$
+* $$ \gamma = \bigwedge_{i=0}^{n} P_{i}(...)$$
+
+> [!NOTE]
+> All structural sets are in uppercase Greek letters, while structural components are in lowercase Greek letters.
+>
+
+### Section 1.2: Defining system parts
+
+
+
+## 2) Machine Components:
+
+### Section 2.1: Abstract Defintions and General Layout
+
+**General definition**: Machine components design model starts by defining a set of states $Q$; define an initial state $q_0$; a set of final states $F$; a set of alphabets $\Sigma$ representing the input space; a transition function $\delta(s_0, \sigma) \rightarrow s_1$.
+
+**Mathematical Abstraction**: The system automata define how the system transits from a state to another to achieve a specific task; therefore they could be represented as a **set of machines**, with a common single property that they are quintuple state-machines; such that each machine is quintuple of: **(1) A set of states from which the transition function picks up.** **(2) A transition function from a state to another with an input.** **(3) A set of input from which the transition function picks up.** **(4) A start state from which the whole system get turned on.** **(5) A set of final accepting states, at which the system could terminate.** **(6) Other mathematical structures and memory structures that target the non-functional problems.** 
+
+**Lemma.02**: Let $M_c$ be a machine that describes the state transitions for components or structures that were mentioned earlier in **part (01)** of this document; where $c$ is an identifier to that component, whether functional or non-functional; $\delta(q_{i}, \sigma_{i}) \rightarrow q_{i+1}$ be a function that accepts current state, and an input, and transits the machine to the next state; $Q$ be a set of machine states that are associated with each structural component, and from which the transition function $\delta$ selects and outputs to; $\Sigma$ be a set of input alphabets from which the $\delta$ transition function selects as an input; $q_0$ is the initial or the starting state from which the overall machine starts; $F$ be a set of the final accepting states for that machine by which the machine shuts down; $\Gamma$ be an additional structure housing non-functional associations.
+
+
+> [!NOTE]
+> Machines are system components that are used for **initializing**, **allocating memory**, **transmitting and receiving data**, **encoding/decoding and encrypting/decrypting data**, **de-initializing**, and **deallocating resources** for system components. Furthermore, communication with other components is mediated through system machines. Therefore, in a system design; each component is associated with a state machine. A state machine can be further abstracted in the previously mentioned **Entity-Structural Framework** as properties of the structural components.
+>
+
+* $$ M_c = \{ Q, \Sigma, \delta(q_{i}, \sigma_{i}) \rightarrow q_{i+1}, q_0, F, \Gamma\}$$

docs/electro-drivers/components.md

@@ -0,0 +1,117 @@
+# Design Problem Specification
+
+**Preface:**  
+The problem statement is to provide:  
+1. Controlling a conventional I/O interface over another I/O interface; commonly known as **"I/O Emulation"**.  
+2. Writing Serial and Parallel programming interfaces for Embedded Bare-Metal MCU over the Super I/O Chips controllers. (Deferred for later revisit).  
+
+---
+
+## Table of Contents
+1. Design Problem Specification  
+   * 1.1 Functional Problem Bulk  
+   * 1.2 Functional Problems Decomposition  
+   * 1.3 Non-functional Problems  
+   * 1.4 Problem-Problems Relationship  
+2. Design Implications
+   * 2.1 Modus Ponens
+   * 2.2 Modus Tollens
+
+---
+
+## 1) Design Problem Specification:
+
+### Section 1.1: Functional Problem Bulk
+
+Functional problem formula:  
+
+$$
+P_{functional} = \{ P_{I/O\ Emulation\ of\ IO-2\ interface\ over\ I/O-1\ interface},\ 
+P_{Compatible\ I/O\ architectures} \}
+$$  
+
+> [!NOTE]  
+> * $P_{Compatible\ I/O\ architectures}$: is defined as a functional problem that arises as a result of various manufacturers for the same category of devices (e.g., Super I/O Chips), and even the variations across the same device family.  
+
+---
+
+### Section 1.2: Functional Problems Decomposition
+
+This section attempts to further break the large bulk of problems into manageable sub-problems.  
+The final sub-problems set is a subset of the original bulk set presented in **Section 1.1**.  
+
+Functional problems decomposition formula:  
+
+$$
+P_{functional} = \{ P_{I/O\ Emulator\ Interface},\ 
+P_{I/O\ Emulated\ Interface},\ 
+P_{Emulation\ Kernel\ Engine},\ 
+P_{Emulation\ User\ Engine} \}
+$$  
+
+> [!NOTE]  
+> * $P_{I/O\ Emulator\ Interface}$: is defined as the hardware-software interface through which the emulation is facilitated. It could be an input or an output interface; being an **Emulator** interface denotes that it sends the emulation commands to the emulation engine components to emulate another I/O interface.  
+> * $P_{I/O\ Emulated\ Interface}$: is defined as the hardware-software interface which is emulated by the emulation engine. It could be an input or an output interface; being an **Emulated** interface denotes dependence on the **Emulation Engine** and compatibility upon the **Emulator** interface, as the **emulated** interface receives input from the **Emulation Engine**.  
+
+---
+
+### Section 1.3: Non-functional Problems
+
+This section extracts the part that examines non-functional requirements.  
+These parts of the problem are not playing an explicit role in the functional requirements scheme, but rather level up the safety, reliability, robustness, resilience, and security, contributing to the overall software performance.  
+
+Non-functional problems formula:  
+
+$$
+P_{Non-functional} = \{
+P_{I/O\ resources\ shared\ acquisition},\ 
+P_{I/O\ Locked\ threaded\ init},\ 
+P_{I/O\ Locked\ error\ handling},\ 
+P_{I/O\ init\ fallback\ to\ compatible\ devices},\ 
+P_{I/O\ R/W\ Clock\ Cycle},\ 
+P_{Programmed\ threaded\ interrupted\ I/O},\ 
+P_{I/O\ resources\ release},\ 
+P_{I/O\ device\ de-init},\ 
+P_{Linux\ VFS},\ 
+P_{Emulation\ VM} \}
+$$  
+
+---
+
+### Section 1.4: Problem-Problems Relationship
+
+Representing relationships among different problems is an essential task to understand the overall system behavior, and thus map the components to their problems later. Relationships can be represented using relations mapping; there is a bijective, injective, and surjective mappings.  
+
+Functional and non-functional problems are closely related to one another; therefore the following relation mappings could be attained:  
+
+* Let $M_{IO}(p)$ be a set of ordered pairs that maps a functional problem to other non-functional problems; such that $p$ is an input/output interface problem for a physical or virtual I/O device.  
+
+$$
+M_{IO}(p) = \{
+(P_{p}, P_{I/O\ resources\ shared\ acquisition}),\ 
+(P_{p}, P_{I/O\ Locked\ threaded\ init}),\ 
+(P_{p}, P_{I/O\ Locked\ error\ handling}),\ 
+(P_{p}, P_{I/O\ init\ fallback\ to\ compatible\ devices}),\ 
+(P_{p}, P_{I/O\ R/W\ Clock\ Cycle}),\ 
+(P_{p}, P_{Programmed\ threaded\ interrupted\ I/O}),\ 
+(P_{p}, P_{I/O\ resources\ release}),\ 
+(P_{p}, P_{I/O\ device\ de-init}),\ 
+(P_{p}, P_{Linux\ VFS}),\ 
+(P_{p}, P_{Emulation\ VM}) \}
+$$  
+
+* Let $M_{Engine}(p)$ be a set of ordered pairs that maps a functional problem to other non-functional problems; such that $p$ is an engine interface problem for providing the emulation of an I/O interface over the other; an engine could be a **user-space** engine or a **kernel-space** engine.  
+
+$$
+M_{Engine}(p) = \{
+(P_{p}, P_{I/O\ R/W\ Clock\ Cycle}),\ 
+(P_{p}, P_{Linux\ VFS}),\ 
+(P_{p}, P_{Char/Block\ Devices}),\
+(P_{p}, P_{Emulation\ VM}),\ 
+(P_{p}, P_{I/O\ Operation\ Lifecycle}) \}
+$$  
+
+
+## 2) Design Implications:
+
+-- Deferred --

docs/electro-drivers/problem.md

@@ -0,0 +1,24 @@
+# Linux Kernel Driver Model
+
+The following document briefly describes the core Linux Kernel Driver Model for which hardware devices are wired with both device drivers and bus drivers, and the interactions between the user-space API and the kernel-space API to synchronize and control the hardware devices.
+
+## Table of contents:
+1. Preface
+2. Architectural Diagram.
+   * 2.1 Board diagram.
+   * 2.2 Dot component-based diagram.
+   * 2.3 Automata diagram.
+   * 2.4 Formal Quantificational Logic.
+3. Terminology.
+4. Data Structures, functions, and macros.
+   * 4.1 Driver Modules.
+   * 4.2 Specialized Drivers.
+   * 4.3 Bus Drivers.
+   * 4.4 Device Drivers and devices.
+   * 4.5 Why bus drivers abstractions?
+   * 4.6 The core Driver Module Loader.
+5. Core Implementation.
+   * 5.1 Core algorithms to load/unload modules.
+   * 5.2 Tree traversal algorithms for bus drivers.
+   * 5.3 Pattern matching algorithms for devices and device drivers.
+