15 File System Contract Layers

File System Layers Diagram

---
config:
  layout: dagre
---
flowchart TB

  classDef file fill:#FFFFFF,stroke:#111,stroke-width:3px,color:#111
  classDef source fill:#E9F1FF,stroke:#111,stroke-width:2px,color:#111
  classDef iface fill:#EDE7D4,stroke:#111,stroke-width:2px,color:#111
  classDef backend fill:#F8F8F8,stroke:#111,stroke-width:2px,color:#111

 subgraph MF["inode-table interface / contract"]
    direction TB
        LOCK_FUNCS["inode locking interface<br/><br/>ilock<br/>iunlock"]:::iface
        ICACHE_FUNCS["inode reference/cache interface<br/><br/>iinit<br/>iget<br/>idup<br/>iput<br/>iunlockput<br/>ireclaim"]:::iface
 end

 subgraph M["in-memory inode state"]
    direction LR
        ICACHE["itable<br/><br/>in-use cached inodes"]:::source
        INODE["struct inode<br/><br/>dev<br/>inum<br/>ref<br/>lock<br/>valid<br/>type<br/>major / minor<br/>nlink<br/>size<br/>addrs[]"]:::file
        SB_MEM["struct superblock sb<br/><br/>cached disk-layout metadata"]:::source
 end

 subgraph BF["files / directories / names interface"]
    direction TB
        PATH_FUNCS["Names layer interface<br/><br/>skipelem<br/>namex<br/>namei<br/>nameiparent"]:::iface
        DIR_FUNCS["Directories layer interface<br/><br/>namecmp<br/>dirlookup<br/>dirlink"]:::iface
        DATA_FUNCS["Files layer: content interface<br/><br/>bmap<br/>readi<br/>writei"]:::iface
        META_FUNCS["Files layer: inode interface<br/><br/>ialloc<br/>iupdate<br/>itrunc<br/>stati"]:::iface
 end

 subgraph LF["log transaction interface"]
    direction TB
        LOG_FUNCS["transaction boundary interface<br/><br/>initlog<br/>begin_op<br/>end_op"]:::iface
        LOG_WRITE_FUNCS["physical redo-log interface<br/><br/>log_write<br/>commit<br/>write_log<br/>write_head<br/>install_trans<br/>recover_from_log<br/>read_head"]:::iface
 end

 subgraph LM["in-memory log state"]
    direction LR
        LOG_STATE["struct log<br/><br/>lock<br/>start<br/>outstanding<br/>committing<br/>dev<br/>lh"]:::source
        LOG_HDR_MEM["logheader in memory<br/><br/>n<br/>block[]"]:::source
 end

 subgraph DF["raw block + superblock interface"]
    direction TB
        SUPER_FUNCS["superblock loading interface<br/><br/>readsb<br/>fsinit"]:::iface
        BLOCK_FUNCS["raw block allocator interface<br/><br/>bzero<br/>balloc<br/>bfree"]:::iface
 end

 subgraph BCI["buffer cache interface"]
    direction TB
        BC_FUNCS["buffer cache API interface<br/><br/>binit<br/>bread<br/>bwrite<br/>brelse<br/>bpin<br/>bunpin"]:::iface
 end

 subgraph BCS["buffer cache state"]
    direction LR
        BCACHE["bcache LRU list<br/><br/>cached disk blocks in memory"]:::source
        BUF["struct buf<br/><br/>valid<br/>disk<br/>dev<br/>blockno<br/>refcnt<br/>lock<br/>prev / next<br/>data[BSIZE]"]:::source
 end

 subgraph D["on-disk file-system source + device"]
    direction LR
        SUPER_DISK["super block<br/><br/>disk layout metadata"]:::source
        LOG_DISK["log blocks<br/><br/>header + logged block copies"]:::source
        DINODE["inode blocks<br/><br/>array of struct dinode"]:::source
        BITMAP["free bitmap blocks<br/><br/>block allocation bits"]:::source
        DATA_BLOCKS["data blocks<br/><br/>file bytes<br/>directory dirents<br/>indirect blocks"]:::source
        DISK_DEVICE["virtio block device"]:::backend
 end

    MF -->|keeps references in| M

    BF -->|uses locked inodes from| M
    BF -->|wraps modifying calls in| LF
    BF -->|gets disk blocks via| BC_FUNCS

    DF -->|logs bitmap/superblock writes through| LF
    DF -->|gets raw disk blocks via| BC_FUNCS

    LF -->|tracks active transaction in| LM
    LF -->|write_log writes home blocks to log<br>install_trans copies committed blocks back home| BC_FUNCS

    BC_FUNCS -->|returns locked buffers from| BCACHE
    BCACHE -->|linked list of| BUF
    BUF -->|transferred by virtio_disk_rw<br>reads from and writes to| DISK_DEVICE

    ICACHE -->|holds| INODE
    LOG_STATE -->|contains| LOG_HDR_MEM