KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
blockdev.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  kos/blockdev.h
4  Copyright (C) 2012, 2013 Lawrence Sebald
5 */
6 
7 #ifndef __KOS_BLOCKDEV_H
8 #define __KOS_BLOCKDEV_H
9 
10 #include <sys/cdefs.h>
11 __BEGIN_DECLS
12 
13 #include <stdint.h>
14 #include <sys/types.h>
15 
16 /** \file kos/blockdev.h
17  \brief Definitions for a simple block device interface.
18 
19  This file contains the definition of a very simple block device that is to
20  be used with filesystems in the kernel. This device interface is designed to
21  abstract away direct hardware access and make it easier to interface the
22  various filesystems that we may add support for to multiple potential
23  devices.
24 
25  The most common of these devices that people are probably interested in
26  directly would be the Dreamcast SD card reader, and that was indeed the
27  primary impetus to this device structure. However, it could also be used
28  to support a file-based disk image or any number of other devices.
29 
30  \author Lawrence Sebald
31 */
32 
33 /** \brief A simple block device.
34 
35  This structure represents a single block device. Each block device should be
36  associated with exactly one filesystem and is used to actually read the data
37  from the disk (or other device) where it is stored.
38 
39  By using a block device with any new filesystems, we can abstract away a few
40  things so that filesystems can be used with a variety of different
41  "devices", such as the SD card reader for the Dreamcast or a disk image file
42  of some sort.
43 
44  \headerfile kos/blockdev.h
45 */
46 typedef struct kos_blockdev {
47  void *dev_data; /**< \brief Internal device data. */
48  uint32_t l_block_size; /**< \brief Log base 2 of the bytes per block. */
49 
50  /** \brief Initialize the block device.
51 
52  This function should do any necessary initialization to use the block
53  device passed in.
54 
55  \param d The device to initialize.
56  \retval 0 On success.
57  \retval -1 On failure. Set errno as appropriate.
58  */
59  int (*init)(struct kos_blockdev *d);
60 
61  /** \brief Shut down the block device.
62 
63  This function should do any teardown work that is needed to clean up
64  the block device.
65 
66  \param d The device to shut down.
67  \retval 0 On success.
68  \retval -1 On failure. Set errno as appropriate.
69  */
70  int (*shutdown)(struct kos_blockdev *d);
71 
72  /** \brief Read a number of blocks from the device.
73 
74  This function should read the specified number of device blocks into
75  the given buffer. The buffer will already be allocated by the caller.
76 
77  \param d The device to read from.
78  \param block The first block to read.
79  \param count The number of blocks to read.
80  \param buf The buffer to read into.
81  \retval 0 On success.
82  \retval -1 On failure. Set errno as appropriate.
83  */
84  int (*read_blocks)(struct kos_blockdev *d, uint64_t block, size_t count,
85  void *buf);
86 
87  /** \brief Write a number of blocks to the device.
88 
89  This function should write the specified number of device blocks onto
90  the device from the given buffer.
91 
92  \param d The device to write to.
93  \param block The first block to write.
94  \param count The number of blocks to write.
95  \param buf The buffer to write from.
96  \retval 0 On success.
97  \retval -1 On failure. Set errno as appropriate.
98  */
99  int (*write_blocks)(struct kos_blockdev *d, uint64_t block, size_t count,
100  const void *buf);
101 
102  /** \brief Count the number of blocks on the device.
103 
104  This function should return the total number of blocks on the device.
105  There is no expectation of the device to keep track of which blocks are
106  in use or anything else of the sort.
107 
108  \param d The device to read the block count from.
109  \return The number of blocks that the device has.
110  */
111  uint64_t (*count_blocks)(struct kos_blockdev *d);
112 
113  /** \brief Flush the write cache (if any) of the device.
114 
115  This function shall signal to the device that any write caches that are
116  present on the device shall be flushed so that all data written to this
117  point shall persist to the underlying storage.
118 
119  \param d The device to flush caches on.
120  \retval 0 On success.
121  \retval -1 On failure. Set errno as appropriate.
122  */
123  int (*flush)(struct kos_blockdev *d);
125 
126 __END_DECLS
127 
128 #endif /* !__KOS_BLOCKDEV_H */
A simple block device.
Definition: blockdev.h:46
int(* flush)(struct kos_blockdev *d)
Flush the write cache (if any) of the device.
Definition: blockdev.h:123
uint64_t(* count_blocks)(struct kos_blockdev *d)
Count the number of blocks on the device.
Definition: blockdev.h:111
int(* write_blocks)(struct kos_blockdev *d, uint64_t block, size_t count, const void *buf)
Write a number of blocks to the device.
Definition: blockdev.h:99
uint32_t l_block_size
Log base 2 of the bytes per block.
Definition: blockdev.h:48
int(* shutdown)(struct kos_blockdev *d)
Shut down the block device.
Definition: blockdev.h:70
int(* read_blocks)(struct kos_blockdev *d, uint64_t block, size_t count, void *buf)
Read a number of blocks from the device.
Definition: blockdev.h:84
int(* init)(struct kos_blockdev *d)
Initialize the block device.
Definition: blockdev.h:59
void * dev_data
Internal device data.
Definition: blockdev.h:47
struct kos_blockdev kos_blockdev_t
A simple block device.