# Filesystem API

API for implementing new file systems in ModuOS.

## Overview

To add a new filesystem, implement these functions and register with VFS.

## Required Functions

### Mount/Unmount

```c
int fs_mount(int drive_index, uint32_t partition_lba);
int fs_unmount(int handle);
```

**Parameters**:
- `drive_index`: Physical drive number
- `partition_lba`: Partition start sector
- `handle`: Filesystem handle

**Returns**: Handle on success, negative on error

### File Operations

```c
int fs_read_file(int handle, const char *path, void *buffer,
                 size_t buffer_size, size_t *bytes_read);

/* Note: filesystem drivers receive *real* filesystem paths like `/ModuOS/...`.
 * The special `$/...` namespace router is handled at a higher layer (fd/devfs path routing).
 */

int fs_stat(int handle, const char *path, fs_file_info_t *info);

int fs_file_exists(int handle, const char *path);
```

### Directory Operations

```c
int fs_list_directory(int handle, const char *path);

int fs_directory_exists(int handle, const char *path);
```

## Data Structures

### File Info

```c
typedef struct {
    char name[260];           // Filename
    uint32_t size;            // Size in bytes
    int is_directory;         // 1=directory, 0=file
    uint32_t cluster;         // FS-specific data
} fs_file_info_t;
```

## Example: Minimal Filesystem

```c
// myfs.h
#ifndef MYFS_H
#define MYFS_H

int myfs_mount(int drive_index, uint32_t partition_lba);
int myfs_unmount(int handle);
int myfs_read_file(int handle, const char *path, void *buffer, 
                   size_t buffer_size, size_t *bytes_read);

#endif

// myfs.c
int myfs_mount(int drive_index, uint32_t partition_lba) {
    // 1. Read filesystem metadata
    // 2. Validate filesystem
    // 3. Allocate handle
    // 4. Return handle
}

int myfs_read_file(int handle, const char *path, void *buffer,
                   size_t buffer_size, size_t *bytes_read) {
    // 1. Parse path
    // 2. Locate file in filesystem
    // 3. Read file data
    // 4. Copy to buffer
    // 5. Return bytes read
}
```

## Registering Filesystem

Add to `fs.c`:
```c
switch (type) {
    case FS_TYPE_FAT32:
        return fat32_mount(drive_index, partition_lba);
    case FS_TYPE_ISO9660:
        return iso9660_mount(drive_index, partition_lba);
    case FS_TYPE_MYFS:
        return myfs_mount(drive_index, partition_lba);
}
```

## Next Steps

- [File Systems](File-Systems.md) - Filesystem overview
- [MDFS](MDFS/Overview.md) - MDFS-specific documentation
- [Storage Drivers](Storage-Drivers.md) - Storage access