essence-os/CONTRIBUTING.md

Contributing Guidelines

This project is constantly evolving, and as such, this file may be out of date.

Map

• apps/ Builtin applications.
• boot/ Contains files for booting the operating system.
  • x86/ ...on x86.
    • esfs-stage1.s Loads loader.s from the start of a EsFS volume and passes control to it.
    • esfs-stage2.s Provides basic read-only EsFS functions for loader.s.
    • loader.s Loads the kernel and passes control to it.
    • mbr.s Finds and loads a bootable partition.
    • uefi.c UEFI bootloader first stage.
    • uefi_loader.s UEFI bootloader second stage.
    • vbe.s Sets the VBE graphics mode.
• desktop/ Contains files for Desktop, which provides both the desktop environment, and a layer between applications and the kernel.
  • api.cpp API initialisation and internal messaging.
  • api.s API functions that must be implemented in assembly.
  • calculator.cpp Evaluates basic math expressions.
  • crti.s, ctrn.s Global constructors and destructors setup.
  • cstdlib.cpp Provides the system call interface for the POSIX subsystem.
  • desktop.cpp Desktop. Manages windows and the taskbar.
  • glue.cpp Entry point for applications using the POSIX subsystem.
  • gui.cpp The GUI.
  • icons.header A list of available icons.
  • list_view.cpp A list view control for the GUI.
  • os.header The header file containing the API's definitions.
  • prefix.h The header file prefix for C/C++.
  • renderer.cpp Provides visual style management and software rendering.
  • renderer2.cpp Vector graphics rendering.
  • start.cpp Entry point for all applications.
  • syscall.cpp Kernel system call wrappers.
  • text.cpp Text rendering and text-based GUI elements.
• drivers/ Kernel drivers.
  • acpi.cpp A layer between the kernel and ACPICA. Also starts application processors on SMP systems.
  • ata.cpp A ATA/IDE driver.
  • esfs2.cpp The EssenceFS filesystem driver.
  • fat.cpp The FAT12 filesystem driver.
  • hda.cpp Intel HD Audio driver.
  • pci.cpp Finds devices on the PCI bus.
  • ps2.cpp A driver for PS/2 keyboard and mice.
  • vbe.cpp Basic VBE SVGA driver.
  • vga.cpp Basic VGA driver.
• kernel/ The kernel and its drivers.
  • audio.cpp Audio system.
  • config.mtsrc System configuration. Describes all the modules that should be built, and when they should be loaded.
  • devices.cpp The device and IO manager.
  • elf.cpp Parses and loads ELF executables and kernel modules.
  • graphics.cpp Graphics system. Mostly deprecated.
  • kernel.h Internal kernel definitions. Includes all other source files in the kernel.
  • main.cpp Kernel initilisation and shutdown.
  • memory.cpp Physical, virtual and shared memory management.
  • module.h Kernel API available to driver modules.
  • objects.cpp Manages object and handles shared between the kernel and applications.
  • posix.cpp The (optional) POSIX subsystem.
  • scheduler.cpp A scheduler, and manager of threads and processes.
  • symbols.cpp Locating kernel symbols.
  • synchronisation.cpp Defines synchronisation primitives. Closely linked with the scheduler.
  • syscall.cpp Defers system calls to other parts of the kernel.
  • terminal.cpp Kernel debugging and serial output.
  • vfs.cpp The virtual filesystem.
  • windows.cpp The window manager. Passes messages from HID devices to applications.
  • x86_64.cpp Code for the x64 architecture.
  • x86_64.h Definitions specific to the x64 architecture.
  • x86_64.s Assembly code for the x64 architecture.
• ports/ A mess of ported applications. Enter with caution.
• res/ Resources, such as fonts and visual styles.
  • Fonts Fonts used by the GUI.
  • Icons Icon packs used by the GUI.
  • Sample Images Sample images.
  • Themes Themes for the user interface..
• shared/ Shared code between the componenets of the operating system.
  • arena.cpp Fixed-size allocations.
  • avl_tree.cpp Balanced binary tree, and maps.
  • bitset.cpp Managing sparse bitsets.
  • common.cpp Common functions.
  • format_string.cpp Locale-dependent text formatter.
  • hash.cpp Hash functions.
  • heap.cpp Heap allocator.
  • linked_list.cpp Doubly-linked lists.
  • stb_ds.h, stb_image.h, stb_sprintf.h STB libraries.
  • style_parser.cpp Parsing visual style specifiers.
  • unicode.cpp Functions for managing Unicode and UTF-8 strings.
  • vga_font.cpp A fallback bitmap font.
• util/ Utilities for building the operating system.
  • build.c The build system.
  • esfs2.h A version of EssenceFS for use on linux from the command line.
  • header_generator.c Language independent header generation.
  • render_svg.c Renders SVG icons.

Code Style

Functions and structures names use PascalCase. Variables use camelCase, while constants and macros use SCREAMING_SNAKE_CASE.

Tabs are \t, and are 8 characters in size.

Braces are placed at the end of the line:

if (a > b) {
    ...
}

Blocks are always surrounded by newlines, and always have braces.

int x = 5;

if (x < 6) {
    x++; // Postfix operators are preferred.
}

Exception: If there are lot of short, linked blocks, then they may be written like this-

if (width == DIMENSION_PUSH) { bool a = grid->widths[i] == DIMENSION_PUSH; grid->widths[i] = DIMENSION_PUSH; if (!a) pushH++; }
else if (grid->widths[i] < width && grid->widths[i] != DIMENSION_PUSH) grid->widths[i] = width;
if (height == DIMENSION_PUSH) { bool a = grid->heights[j] == DIMENSION_PUSH; grid->heights[j] = DIMENSION_PUSH; if (!a) pushV++; }
else if (grid->heights[j] < height && grid->heights[j] != DIMENSION_PUSH) grid->heights[j] = height;

Function names are always descriptive, and use prepositions and conjuctions if neccesary.

EsFileReadAll // Symbols provided by the API are prefixed with Es-.
EsDrawSurface
EsMemoryZero

Variable names are usually descriptive, but sometimes shortened names are used for short-lived variables.

EsMessage m = {};
m.type = OS_MESSAGE_MEASURE;
EsMessagePost(&m);

Operators are padded with spaces on either side.

bounds.left = (grid->bounds.left + grid->bounds.right) / 2 - 4;

A space should be placed between a cast and its expression.

int x = (float) y;

Although the operating system is written in C++, most C++ features are avoided. However, the kernel uses a lot of member functions.

struct Window {
    void Update(bool fromUser);
    void SetCursorStyle(OSCursorStyle style);
    void NeedWMTimer(int hz);
    void Destroy();
    bool Move(OSRectangle &newBounds);
    void ClearImage();

    Mutex mutex; // Mutex for drawing to the window. Also needed when moving the window.
    Surface *surface;
    OSPoint position;
    size_t width, height;
    ...
}

Default arguments often provided as functions grow over time.

There is no limit on function size. However, you should avoid regularly exceeding 120 columns.

Pointers are declared like this: Type *name;.

Identifiers may be prefixed with i, e or c to indicate inclusive, exclusive or C-style-zero-terminated-string respectively.

Kernel and Driver Development

See module.h for definitions available to driver developers. See drivers/fat.cpp and drivers/ata.cpp for simple examples of the driver API.

The following subroutines may be of interest:

void KWaitMicroseconds(uint64_t mcs); // Spin until a given number of microseconds have elapsed.
void EsPrint(const char *format, ...); // Print a message to serial output. (Ctrl+Alt+3 in Qemu)
void KernelPanic(const char *format, ...); // Print a message and halt the OS.
Defer(<statement>); // Defer a statement. Deferred statements will be executed in reverse order when they go out of scope.
size_t EsCStringLength(const char *string); // Get the length of a zero-terminated string.
void EsMemoryCopy(void *destination, const void *source, size_t bytes); // Copy memory forwards.
void EsMemoryZero(void *destination, size_t bytes); // Zero a buffer.
void EsMemoryMove(void *start, void *end, intptr_t amount, bool zeroEmptySpace); // Move a memory region left (amount < 0) or right (amount > 0).
int EsMemoryCopy(const void *a, const void *b, size_t bytes); // Compare two memory regions. Returns 0 if equal.
uint8_t EsSumBytes(uint8_t *source, size_t bytes); // Calculate the 8-bit sum of the bytes in a buffer.
size_t EsStringFormat(char *buffer, size_t bufferLength, const char *format, ...); // Format a string. Returns the length.
uint8_t EsGetRandomByte(); // Get a non-secure random byte.
void EsSort(void *base, size_t count, size_t size, int (*compare)(const void *, const void *, void *), void *callbackArgument); // Sort an array of count items of size size.
uint32_t CalculateCRC32(void *buffer, size_t length); // Calculate the CRC32 checksum of a buffer.
void ProcessorEnableInterrupts(); // Enable interrupts.
void ProcessorDisableInterrupts(); // Disable interrupts. Critical interrupts, such as TLB shootdown IPIs, will remain enabled.
void ProcessorOut<x>(uint16_t port, uint<x>_t value); // Write to an IO port.
uint<x>_t ProcessorIn<x>(uint16_t port); // Read from an IO port.
uint64_t ProcessorReadTimeStamp(); // Read the time stamp in ticks. acpi.timestampTicksPerMs gives the number of ticks per millisecond.
bool KRegisterIRQ(uintptr_t interruptIndex, IRQHandler handler, void *context, const char *cOwner); // Register an IRQ handler. Returns false if the IRQ could not be registered. The handler should return false if its devices was not responsible for the IRQ.
void *MMMapPhysical(MMSpace *space /* = kernelMMSpace */, uintptr_t offset, size_t bytes); // Memory mapped IO.
void *EsHeapAllocate(size_t size, bool zero); // Allocate memory from the heap.
void EsHeapFree(void *pointer); // Free memory from the heap.
bool KThreadCreate(const char *cName, void (*startAddress)(uintptr_t), uintptr_t argument = 0); // Create a thread.

Synchronisation:

void Mutex::Acquire();
void Mutex::Release();
void Mutex::AssertLocked();

void Spinlock::Acquire(); // Disables interrupts.
void Spinlock::Release();
void Spinlock::AssertLocked();

bool Event::Set();
void Event::Reset();
bool Event::Pool();
bool Event::Wait(uintptr_t timeoutMs); // Return false on timeout.
// event.autoReset determines whether the event will automatically reset after Poll() or Wait() return.

Linked lists:

LinkedList<T>::InsertStart(LinkedItem<T> *item); // Insert an item at the start of a linked list.
LinkedList<T>::InsertEnd(LinkedItem<T> *item); // Insert an item at the end of a linked list.
LinkedList<T>::Remove(LinkedItem<T> *item); // Remove an item from a linked list.

struct LinkedList<T> {
    LinkedItem<T> *firstItem; // The start of the linked list.
    LinkedItem<T> *lastItem; // The end of the linked list.
    size_t count; // The number of items in the linked list.
}

struct LinkedItem<T> {
    LinkedItem<T> *previousItem; // The previous item in the linked list.
    LinkedItem<T> *nextItem; // The next item in the linked list.
    LinkedList<T> *list; // The list the item is in.
T *thisItem; // A pointer to the item itself.
}

Contributors

Put your name here!

• nakst
• Brett R. Toomey
• vtlmks
• Aleksander Birkeland