KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
fs_romdisk.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 kos/fs_romdisk.h
4 (c)2001 Megan Potter
5
6*/
7
8/** \file kos/fs_romdisk.h
9 \brief ROMFS virtual file system.
10 \ingroup vfs_romdisk
11
12 This file contains support for the romdisk VFS. This VFS allows you to make
13 Linux-style ROMFS images and either embed them into your binary or load them
14 at runtime from some other source (such as a CD-ROM). These images are made
15 with the genromfs program that is included in the utils portion of the tree.
16
17 You can choose to automount one ROMFS image by embedding it into your binary
18 and using the appropriate flags (INIT_DEFAULT by itself or INIT_FS_ROMDISK with other flags)
19 when calling the KOS_INIT_FLAGS() macro with a custom flag selection. The embedded ROMFS
20 will mount itself on /rd.
21
22 \warning
23 An embedded romdisk image is linked to your executable and cannot be evicted from
24 system RAM!
25
26 Mounting additional images that you load from some other sources (such as a modified BIOS)
27 on whatever mountpoint you want, is also possible. Using fs_romdisk_mount() and passing a
28 pointer to the location of a romdisk image will mount it.
29
30 \remark
31 Mounted images will reside in system RAM for as long as your program is running
32 or until you unmount them with fs_romdisk_unmount(). The size of your generated
33 ROMFS image must be kept below 16MB, with 14MB being the maximum recommended size,
34 as your binary will also reside in RAM and you need to leave some memory available
35 for it. Generating files larger than the available RAM will lead to system crashes.
36
37 A romdisk filesystem image can be created by adding "KOS_ROMDISK_DIR=" to your Makefile
38 and pointing it to the directory contaning all the resources you wish to have embeded in
39 filesystem image. A rule to create the image is provided in the rules provided in Makefile.rules,
40 the created object file must be linked with your binary file by adding romdisk.o to your
41 list of objects.
42
43 \see INIT_FS_ROMDISK
44 \see KOS_INIT_FLAGS()
45
46 \author Megan Potter
47*/
48
49#ifndef __KOS_FS_ROMDISK_H
50#define __KOS_FS_ROMDISK_H
51
52#include <kos/cdefs.h>
53#include <stdbool.h>
54#include <stdint.h>
55__BEGIN_DECLS
56
57#include <kos/fs.h>
58
59/** \defgroup vfs_romdisk Romdisk
60 \brief VFS driver for accessing romdisks binaries
61 \ingroup vfs
62
63 @{
64*/
65
66/** \cond */
67/* Initialize the file system */
68void fs_romdisk_init(void);
69
70/* De-init the file system; also unmounts any mounted images. */
71void fs_romdisk_shutdown(void);
72/** \endcond */
73
74/* NOTE: the mount/unmount are _not_ thread safe as regards doing multiple
75 mounts/unmounts in different threads at the same time, and they don't
76 check for open files currently either. Caveat emptor! */
77
78/** \brief Mount a ROMFS image as a new filesystem.
79
80 This function will mount a ROMFS image that has been loaded into memory to
81 the specified mountpoint.
82
83 \param mountpoint The directory to mount this romdisk on
84 \param img The ROMFS image
85 \param own_buffer If false, you are still responsible for img, and
86 must free it if appropriate. If true, img will be
87 freed when it is unmounted
88 \retval 0 On success
89 \retval -1 If fs_romdisk_init not called
90 \retval -2 If img is invalid
91 \retval -3 If a malloc fails
92*/
93int fs_romdisk_mount(const char * mountpoint, const uint8_t *img, bool own_buffer);
94
95/** \brief Unmount a ROMFS image.
96
97 This function unmounts a ROMFS image that has been previously mounted with
98 fs_romdisk_mount(). This function does not check for open files on the fs,
99 so make sure that all files have been closed before calling it. If the VFS
100 owns the buffer (own_buffer was true when you called the mount function)
101 then this function will also free the buffer.
102
103 \param mountpoint The ROMFS to unmount
104 \retval 0 On success
105 \retval -1 On error
106
107 \par Error Conditions:
108 \em ENOENT - no such ROMFS was mounted
109*/
110int fs_romdisk_unmount(const char * mountpoint);
111
112/** @} */
113
114__END_DECLS
115
116#endif /* __KOS_FS_ROMDISK_H */
117
Various common macros used throughout the codebase.
Virtual filesystem support.
int fs_romdisk_mount(const char *mountpoint, const uint8_t *img, bool own_buffer)
Mount a ROMFS image as a new filesystem.
int fs_romdisk_unmount(const char *mountpoint)
Unmount a ROMFS image.