O(1) LRU eviction block device cache; move flanterm to its own directory; tidy up some generated documentation

Author: braindigitalis

include/block_cache.h

@@ -0,0 +1,68 @@
+/**
+ * @file block_cache.h
+ * @brief Per-device write-through block cache.
+ *
+ * This cache sits above block device drivers. It caches fixed-size sectors,
+ * evicting the oldest (by last access) when full. Reads and writes are
+ * write-through and counted as accesses. One cache instance is created
+ * per storage device.
+ */
+#pragma once
+#include <kernel.h>
+
+/* Forward declarations */
+typedef struct block_cache block_cache_t;
+
+/**
+ * @brief Create a new cache for a storage device.
+ *
+ * @param dev  Device to attach cache to.
+ * @return     Pointer to cache instance, or NULL on error.
+ */
+block_cache_t *block_cache_create(storage_device_t *dev);
+
+/**
+ * @brief Destroy a cache and free all associated resources.
+ *
+ * @param pcache  Pointer to cache pointer; set to NULL on return.
+ */
+void block_cache_destroy(block_cache_t **pcache);
+
+/**
+ * @brief Read bytes from a cached device.
+ *
+ * Granularity is per sector; the cache works in multiples of the device’s
+ * block size. Reads hitting the cache are served immediately; misses are
+ * read from the device and then cached.
+ *
+ * @param c      Cache instance.
+ * @param lba    Starting sector number.
+ * @param bytes  Number of bytes to read.
+ * @param out    Destination buffer.
+ * @return       1 on success, 0 on failure (fs_set_error() is set).
+ */
+int block_cache_read(block_cache_t *c, uint64_t lba, uint32_t bytes, unsigned char *out);
+
+/**
+ * @brief Write bytes through to a cached device.
+ *
+ * Writes are always passed to the device. The cache is updated (write-allocate)
+ * so subsequent reads will hit.
+ *
+ * @param c      Cache instance.
+ * @param lba    Starting sector number.
+ * @param bytes  Number of bytes to write.
+ * @param src    Source buffer.
+ * @return       1 on success, 0 on failure (fs_set_error() is set).
+ */
+int block_cache_write(block_cache_t *c, uint64_t lba, uint32_t bytes, const unsigned char *src);
+
+/**
+ * @brief Invalidate all entries in a cache.
+ *
+ * Useful when a device is reset or forcibly changed.
+ *
+ * @param c  Cache instance.
+ */
+void block_cache_invalidate(block_cache_t *c);
+

include/filesystem.h

@@ -82,13 +82,15 @@ typedef enum fs_error_t {
 	FS_ERR_LFN_TOO_LONG,
 	FS_ERR_IS_EXFAT,
 	FS_ERR_BAD_CLUSTER,
+	FS_ERR_INTERNAL,
+	FS_ERR_OUT_OF_BOUNDS,
 } fs_error_t;
 
 /**
  * @brief Retrieve a human-readable string for the last filesystem error code.
  *
  * This function maps an fs_error_t code to its corresponding descriptive
- * string. It does not reset or clear the error code — the last error value
+ * string. It does not reset or clear the error code - the last error value
  * is retained until a new filesystem error is set via fs_set_error().
  *
  * @note The validity of the returned error string depends on the result of the
@@ -246,6 +248,8 @@ typedef struct {
 	bool is_optical;
 } storage_device_ui_t;
 
+struct block_cache;
+
 /**
  * @brief Represents a block storage device e.g. a hard disk, DVD-ROM drive, etc.
  * 
@@ -301,8 +305,17 @@ typedef struct storage_device_t {
 	 */
 	void* opaque2;
 
+	/**
+	 * @brief User interface strings, model name, capacity, type
+	 * as human-readable text.
+	 */
 	storage_device_ui_t ui;
 
+	/**
+	 * @brief Block cache for the device
+	 */
+	struct block_cache* cache;
+
 	/**
 	 * @brief Pointer to next storage device, or NULL
 	 */
@@ -668,4 +681,34 @@ uint32_t fs_get_error(void);
  */
 bool install_gpt_esp_rfs_whole_image(const char *devname, const char *esp_image_vfs_path);
 
-void installer();
+/**
+ * @brief Installation stub, installer/main.c
+ */
+void installer();
+
+/**
+ * @brief Enable a block-level cache for a storage device.
+ *
+ * This attaches a new cache instance to the device if one is not already
+ * present. The cache is only created when the device has a valid sector size
+ * and read path. Devices that do not benefit from caching (e.g. ramdisks)
+ * should not call this function.
+ *
+ * @param device  Storage device to enable caching for.
+ * @return        true if a cache was successfully created and attached,
+ *                false if caching could not be enabled (invalid arguments,
+ *                already enabled, or allocation failure).
+ */
+bool storage_enable_cache(storage_device_t *device);
+
+/**
+ * @brief Disable and destroy the cache attached to a storage device.
+ *
+ * If a cache is present on the device it will be destroyed and all resources
+ * freed. After this call, @p sd->cache will be set to NULL. Calling this on
+ * a device without a cache is safe and has no effect.
+ *
+ * @param sd  Storage device to disable caching for.
+ */
+void storage_disable_cache(storage_device_t *sd);
+

include/idt.h

@@ -38,7 +38,7 @@ extern volatile idt_ptr_t idt64;
  * for broadcast and never used. Any CPUs with IDs above 254 are ignored.
  *
  * By sizing arrays to 256, we can index directly by LAPIC ID without needing
- * a LAPIC→OS CPU remapping table. This simplifies per‑CPU structures at the
+ * a LAPIC->OS CPU remapping table. This simplifies per‑CPU structures at the
  * cost of a small amount of extra memory. Future support for >254 LAPIC IDs
  * may require remapping or dynamic allocation.
  */

include/interrupt.h

@@ -72,7 +72,7 @@ typedef struct shared_interrupt_t {
  * handlers for multiple PCI devices on the same line can be tracked and
  * dispatched safely. This is a requirement of shared interrupt delivery.
  *
- * @param n Interrupt number — 0–31 are reserved ISRs; 32+ are IRQs.
+ * @param n Interrupt number - 0–31 are reserved ISRs; 32+ are IRQs.
  * @param handler Function pointer to the interrupt handler.
  * @param device For PCI devices, specify the device node responsible.
  *               Used to manage IRQ sharing.

include/retrofs.h

@@ -1,7 +1,7 @@
 /**
  * @file retrofs.h
  * @author Craig Edwards (craigedwards@brainbox.cc)
- * @brief Core structures, constants, and API definitions for RetroFS — an
+ * @brief Core structures, constants, and API definitions for RetroFS - an
  *        ADFS 'L' format–inspired filesystem for Retro Rocket.
  *
  * RetroFS is a sector-based filesystem inspired by the Acorn ADFS 'L' format.

include/tinyalloc.h

@@ -1,6 +1,6 @@
 /**
  * @file tinyalloc.h
- * @brief Tinyalloc — a small, page-aware heap allocator for Retro Rocket.
+ * @brief Tinyalloc - a small, page-aware heap allocator for Retro Rocket.
  *
  * Provides aligned heap allocation and free operations with
  * low overhead. Intended for kernel use where predictable

os/system/keymaps/en-US.keymap

@@ -111,5 +111,5 @@
 &52 0 0
 &53 . .
 
-# ISO extra key (next to Enter) — unused in US layout
+# ISO extra key (next to Enter) - unused in US layout
 &2B \ |

src/acpi.c

@@ -395,7 +395,7 @@ uacpi_status uacpi_kernel_pci_device_open(uacpi_pci_address address, uacpi_handl
 }
 
 uacpi_status uacpi_kernel_io_map(uacpi_io_addr base, uacpi_size len, uacpi_handle *out_handle) {
-	// For I/O ports, mapping isn't needed — just pass the base through.
+	// For I/O ports, mapping isn't needed - just pass the base through.
 	*out_handle = (uacpi_handle) base;
 	return UACPI_STATUS_OK;
 }

src/ahci.c

@@ -378,13 +378,13 @@ void probe_port(ahci_hba_mem_t *abar, pci_dev_t dev)
 				abar->ghc |= (1 << 1);  // global IE
 
 
-				storage_device_t* sd = NULL;
-				sd = kmalloc(sizeof(storage_device_t));
+				storage_device_t* sd = kmalloc(sizeof(storage_device_t));
 				if (!sd) {
 					return;
 				}
 				sd->opaque1 = i;
 				sd->opaque2 = (void*)abar;
+				sd->cache = NULL;
 				sd->blockread = storage_device_ahci_block_read;
 				sd->blockwrite = storage_device_ahci_block_write;
 				sd->size = dt == AHCI_DEV_SATA ? ahci_read_size(&abar->ports[i], abar) : SIZE_MAX;
@@ -413,6 +413,7 @@ void probe_port(ahci_hba_mem_t *abar, pci_dev_t dev)
 				}
 				kprintf("%s storage, Port #%d: %s\n", dt == AHCI_DEV_SATA ? "SATA" : "ATAPI", i, sd->ui.label);
 				register_storage_device(sd);
+				storage_enable_cache(sd);
 			}
 		}
 		pi >>= 1;

src/basic/datetime.c

@@ -68,12 +68,7 @@ char* basic_get_upstr(struct basic_ctx* ctx)
 			buffer[pos++] = ' ';
 		}
 
-		int n = snprintf(buffer + pos, sizeof(buffer) - pos,
-				 "%lu %s",
-				 parts[i].v, parts[i].label);
-		if (n < 0) {
-			n = 0;
-		}
+		size_t n = snprintf(buffer + pos, sizeof(buffer) - pos, "%lu %s", parts[i].v, parts[i].label);
 		if (n >= sizeof(buffer) - pos) {
 			pos = sizeof(buffer) - 1;
 			break;
@@ -83,7 +78,7 @@ char* basic_get_upstr(struct basic_ctx* ctx)
 	}
 
 	if (!started) {
-		(void)snprintf(buffer, sizeof(buffer), "0 sec");
+		snprintf(buffer, sizeof(buffer), "0 sec");
 	} else {
 		buffer[pos] = '\0';
 	}