# nasa/eefs architecture

> Architecture diagram of the GitHub repository nasa/eefs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nasa/eefs
- Repository: https://github.com/nasa/eefs

## Overview

##### Project Type and Purpose
- This is an embedded file system project designed for memory devices like EEPROM (and similar non-block oriented memory such as RAM or ROM). It’s intended to be used in embedded systems running OSes like vxWorks and RTEMS or even in environments without an OS.
- The project allows creation of a file system image on a host development machine, which can then be burned into a target—making it ideal for bootloaders or embedded applications with minimal code footprint (e.g., using the “microeefs” interface).

##### Analysis of the File Structure
- Top-level directories include:
- README.md – Provides a high-level overview.
- doc – Contains design and planning documents (e.g., EEPROM File System Design Notes).
- drivers – Contains OS-specific drivers. Note the three subdirectories:
▪ rtems_driver – Implements driver logic for RTEMS.
▪ standalone_driver – Provides an API for systems with no file system.
▪ vxworks_driver – Contains driver source for vxWorks.
- inc – Contains header files that define common types, configuration options, API functions, and the version information.
- libraries – Holds core libraries implementing the actual file system logic:
▪ eepromfs – Primary implementation for the EEPROM file API.
▪ microeefs – A lightweight interface for quick, single-function file lookups (ideal for bootloaders).
▪ page_window – Likely abstracts low-level EEPROM memory handling.
- tools – Contains utility programs for preparing or managing EEFS images:
▪ eefstool – Contains a complete toolset (with Makefiles, source code, and header files) to generate or manipulate EEFS images.
▪ geneepromfs – A similar tool that includes command-line options, configuration, and a parser to generate file system images.

##### Main Components and Their Roles
a. Embedded File System Core:
- Libraries such as eepromfs, microeefs, and page_window represent the “heart” of the file system. They implement the logic to interact with the EEPROM memory.
b. Drivers:
- OS/platform-specific drivers under the drivers/ directory ensure that the file system can interface with diverse environments (RTEMS, vxWorks, and standalone setups).
c. Development Tools:
- Tools such as eefstool and geneepromfs are used on a host system to generate, manage, and test the file system images.
d. API and Configuration:
- The inc directory holds the interface definitions, system configurations, and versioning information vital for both the library functions and driver implementations.
e. Documentation:
- The doc directory (including design notes) supports understanding and maintaining the internal architecture and design decisions.

##### Relationships and Interactions
- The Drivers components (RTEMS, vxWorks, Standalone) interface with the EEFS core libraries (which include the eepromfs logic and, optionally, the microeefs lookup routine).
- The Tools (eefstool and geneepromfs) use the same core libraries (or perhaps closely mimicked APIs) to prepare file system images during development.
- The “inc” directory and configurations are cross-cutting, providing a common API layer used by both the drivers and tools.
- That while the drivers are responsible for runtime file system operations on the actual target hardware, the tools operate during development to build a complete image that is then "burned" into the device.

##### Architectural Patterns / Design Principles
- Modular design: The separation of drivers, libraries, and tools denotes a modular approach that allows each component to be modified or replaced independently.
- Platform abstraction: By having different driver implementations (RTEMS, vxWorks, Standalone), the system abstracts the underlying hardware/OS specifics from the core file system functionality.
- Lightweight interface for bootloaders: The microeefs interface specifically caters to minimal code size and fast lookup—a key attribute in bootstrapping environments.

##### Customization Based on Project Type
- The separation and interaction between the host-side tools and target-side drivers.
- How the core libraries are platform-independent and are used across different environments.
- The “microeefs” interface as a special pathway for bootloader integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "EEFS Core Libraries"
        core_eepromfs["eepromfs"]:::library
        core_microeefs["microeefs"]:::library
        core_page_window["page_window"]:::library
    end

    subgraph "Drivers"
        driver_rtems["RTEMS Driver"]:::driver
        driver_standalone["Standalone Driver"]:::driver
        driver_vxworks["vxWorks Driver"]:::driver
    end

    subgraph "Development Tools"
        tool_eefstool["eefstool"]:::tool
        tool_geneepromfs["geneepromfs"]:::tool
    end

    api_inc["API / Configuration (inc)"]:::api
    doc_doc["Documentation (doc)"]:::doc

    %% Drivers using Core Libraries
    driver_rtems -->|"uses"| core_eepromfs
    driver_rtems -->|"uses"| core_microeefs
    driver_rtems -->|"uses"| core_page_window

    driver_standalone -->|"uses"| core_eepromfs
    driver_standalone -->|"uses"| core_microeefs
    driver_standalone -->|"uses"| core_page_window

    driver_vxworks -->|"uses"| core_eepromfs
    driver_vxworks -->|"uses"| core_microeefs
    driver_vxworks -->|"uses"| core_page_window

    %% Tools building images from Core Libraries
    tool_eefstool -->|"builds"| core_eepromfs
    tool_eefstool -->|"builds"| core_microeefs
    tool_eefstool -->|"builds"| core_page_window

    tool_geneepromfs -->|"builds"| core_eepromfs
    tool_geneepromfs -->|"builds"| core_microeefs
    tool_geneepromfs -->|"builds"| core_page_window

    %% Common API/Configuration used across components
    api_inc ---|"configures"| core_eepromfs
    api_inc ---|"configures"| core_microeefs
    api_inc ---|"configures"| core_page_window
    api_inc ---|"configures"| driver_rtems
    api_inc ---|"configures"| driver_standalone
    api_inc ---|"configures"| driver_vxworks
    api_inc ---|"configures"| tool_eefstool
    api_inc ---|"configures"| tool_geneepromfs

    %% Documentation providing design notes
    doc_doc ---|"documents"| api_inc
    doc_doc ---|"documents"| driver_rtems
    doc_doc ---|"documents"| core_eepromfs

    %% Click Events
    click core_eepromfs "https://github.com/nasa/eefs/blob/master/libraries/eepromfs/eefs_fileapi.c"
    click core_microeefs "https://github.com/nasa/eefs/blob/master/libraries/microeefs/microeefs.c"
    click core_page_window "https://github.com/nasa/eefs/blob/master/libraries/page_window/eeprom_pagewindow.c"
    click driver_rtems "https://github.com/nasa/eefs/blob/master/drivers/rtems_driver/eefsDriver.c"
    click driver_standalone "https://github.com/nasa/eefs/blob/master/drivers/standalone_driver/eefs_filesys.c"
    click driver_vxworks "https://github.com/nasa/eefs/blob/master/drivers/vxworks_driver/eefs_vxworks.c"
    click api_inc "https://github.com/nasa/eefs/blob/master/inc/common_types.h"
    click tool_eefstool "https://github.com/nasa/eefs/tree/master/tools/eefstool"
    click tool_geneepromfs "https://github.com/nasa/eefs/tree/master/tools/geneepromfs"
    click doc_doc "https://github.com/nasa/eefs/blob/master/doc/EEPROM File System Design Notes.docx"

    %% Styles
    classDef library fill:#f9c,stroke:#333,stroke-width:2px;
    classDef driver fill:#bbf,stroke:#333,stroke-width:2px;
    classDef tool fill:#bfb,stroke:#333,stroke-width:2px;
    classDef api fill:#ff9,stroke:#333,stroke-width:2px;
    classDef doc fill:#ccf,stroke:#333,stroke-width:2px;
```
