/**
 * @file pifile.h
 * @author Giovanni Bajo <giovannibajo@gmail.com>
 * @brief Load a PI-mapped file
 * @ingroup asset
 * 
 * This module exports a virtual filesystem called "pi:/" that allows to
 * access a portion of the bus as if it was a file (PI-mapped files).
 * 
 * This is sometimes needed for specific use cases, for instance:
 * 
 * * Flashcarts might allow to load data from the SD card directly into
 *   the internal SDRAM, which is mapped to the PI bus. If you want then
 *   to access the file, you can use the "pi:/" filesystem.
 * * Some applications might embed data directly into the ROM without using
 *   the DragonFS, and they might want to access it directly from the PI bus
 *   as if the data was a file.
 * 
 * Normally, you should use the DragonFS filesystem to embed assets in ROM,
 * which is more flexible, but this could be useful for specific cases.
 * 
 * To open a file from the PI bus, use the standard fopen function with
 * a filename starting with "pi:/". For instance, to open a file at address
 * 0x10400000 with length 0xF000, use "pi:/10400000:F000". Alternatively,
 * you can use the #pifile_open function to open the file.
 * 
 * Notice that the specified address must be a PI bus address (not a CPU
 * virtual address). All accesses will be performed using DMA so the
 * full 32-bit PI address space is accessible.
 *
 */

#ifndef LIBDRAGON_PIFILE_H
#define LIBDRAGON_PIFILE_H

#include "n64types.h"
#include <stdio.h>

/**
 * @brief Initialize the PI file system
 * 
 * This function initializes the PI file system. After calling this function,
 * the "pi:/" filesystem will be available to open files via fopen().
 */
void pifile_init(void);

/**
 * @brief Open a file from the PI bus given a base address and size
 * 
 * This function opens a "file" on the PI bus. Since it does not rely on 
 * a filesystem, the "file" is just described as a base address and size.
 *
 * The file is opened in read-only mode. Read-write mode is currently not supported.
 * 
 * @param[in] base      Base address of the file
 * @param[in] size      Size of the file
 * @param[in] flags     Flags to open the file with, for future use. Use 0.
 * 
 * @return FILE*        FILE pointer to use with standard C functions (fread, fclose)
 */
FILE *pifile_open(pi_addr_t base, size_t size, uint32_t flags);

#endif
