|
1 | 1 | // This file is a part of the IncludeOS unikernel - www.includeos.org |
2 | 2 | // |
3 | | -// Copyright 2015 Oslo and Akershus University College of Applied Sciences |
| 3 | +// Copyright 2015-2017 Oslo and Akershus University College of Applied Sciences |
4 | 4 | // and Alfred Bratterud |
5 | 5 | // |
6 | 6 | // Licensed under the Apache License, Version 2.0 (the "License"); |
|
16 | 16 | // limitations under the License. |
17 | 17 |
|
18 | 18 | #pragma once |
19 | | -#ifndef HW_DRIVE_HPP |
20 | | -#define HW_DRIVE_HPP |
| 19 | +#ifndef HW_BLOCK_DEVICE_HPP |
| 20 | +#define HW_BLOCK_DEVICE_HPP |
21 | 21 |
|
22 | | -#include <memory> |
23 | 22 | #include <cstdint> |
24 | 23 | #include <delegate> |
| 24 | +#include <memory> |
25 | 25 |
|
26 | | -namespace hw |
27 | | -{ |
28 | | - |
29 | | - /** |
30 | | - * Abstract interface for block devices of various driver types |
31 | | - **/ |
32 | | - class Block_device { |
33 | | - public: |
34 | | - using block_t = uint64_t; //< Disk device block size |
35 | | - using buffer_t = std::shared_ptr<uint8_t>; |
36 | | - |
37 | | - // Delegate for result of reading a disk sector |
38 | | - //using on_read_func = delegate<void(buffer_t)>; |
39 | | - using on_read_func = delegate<void(buffer_t)>; |
| 26 | +namespace hw { |
40 | 27 |
|
41 | | - using Device_id = int; |
| 28 | +/** |
| 29 | + * This class is an abstract interface for block devices |
| 30 | + */ |
| 31 | +class Block_device { |
| 32 | +public: |
| 33 | + using block_t = uint64_t; //< Representation for a device's block size |
| 34 | + using buffer_t = std::shared_ptr<uint8_t>; //< Representation for a block device's buffer |
| 35 | + using Device_id = int32_t; //< Representation for a block device's identifier |
| 36 | + using on_read_func = delegate<void(buffer_t)>; //< Delegate for result of reading from a block device |
42 | 37 |
|
43 | | - static const char* device_type() |
44 | | - { return "Block device"; } |
| 38 | + /** |
| 39 | + * Method to get the type of device |
| 40 | + * |
| 41 | + * @return The type of device as a C-String |
| 42 | + */ |
| 43 | + static const char* device_type() noexcept |
| 44 | + { return "Block device"; } |
45 | 45 |
|
46 | | - virtual std::string device_name() const = 0; |
| 46 | + /** |
| 47 | + * Method to get the name of the device |
| 48 | + * |
| 49 | + * @return The name of the device as a std::string |
| 50 | + */ |
| 51 | + virtual std::string device_name() const = 0; |
47 | 52 |
|
48 | | - Device_id id() const { return id_; } |
| 53 | + /** |
| 54 | + * Method to get the device's identifier |
| 55 | + * |
| 56 | + * @return The device's identifier |
| 57 | + */ |
| 58 | + Device_id id() const noexcept |
| 59 | + { return id_; } |
49 | 60 |
|
50 | | - /** Human-readable name of this disk controller */ |
51 | | - virtual const char* driver_name() const noexcept = 0; |
| 61 | + /** |
| 62 | + * Get the human-readable name of this device's controller |
| 63 | + * |
| 64 | + * @return The human-readable name of this device's controller |
| 65 | + */ |
| 66 | + virtual const char* driver_name() const noexcept = 0; |
52 | 67 |
|
53 | | - /** The size of the disk in whole sectors */ |
54 | | - virtual block_t size() const noexcept = 0; |
| 68 | + /** |
| 69 | + * Get the size of the device as total number of blocks |
| 70 | + * |
| 71 | + * @return The size of the device as total number of blocks |
| 72 | + */ |
| 73 | + virtual block_t size() const noexcept = 0; |
55 | 74 |
|
56 | | - /** Returns the optimal block size for this device */ |
57 | | - virtual block_t block_size() const noexcept = 0; |
| 75 | + /** |
| 76 | + * Get the optimal block size for this device |
| 77 | + * |
| 78 | + * @return The optimal block size for this device |
| 79 | + */ |
| 80 | + virtual block_t block_size() const noexcept = 0; |
58 | 81 |
|
59 | | - /** |
60 | | - * Read block(s) from blk and call func with result |
61 | | - * A null-pointer is passed to result if something bad happened |
62 | | - * Validate using !buffer_t: |
63 | | - * if (!buffer) |
64 | | - * error("Device failed to read sector"); |
65 | | - **/ |
66 | | - virtual void read(block_t blk, on_read_func func) = 0; |
67 | | - virtual void read(block_t blk, size_t count, on_read_func) = 0; |
| 82 | + /** |
| 83 | + * Read a block of data asynchronously from the device |
| 84 | + * |
| 85 | + * @param blk |
| 86 | + * The block of data to read from the device |
| 87 | + * |
| 88 | + * @param reader |
| 89 | + * An operation to perform asynchronously |
| 90 | + * |
| 91 | + * @note A nullptr is passed to the reader if an error occurred |
| 92 | + * @note Validate the reader's input |
| 93 | + * |
| 94 | + * @example |
| 95 | + * if (buffer == nullptr) { |
| 96 | + * error("Device failed to read sector"); |
| 97 | + * } |
| 98 | + */ |
| 99 | + virtual void read(block_t blk, on_read_func reader) = 0; |
68 | 100 |
|
69 | | - /** read synchronously the block @blk */ |
70 | | - virtual buffer_t read_sync(block_t blk) = 0; |
71 | | - virtual buffer_t read_sync(block_t blk, size_t count) = 0; |
| 101 | + /** |
| 102 | + * Read blocks of data asynchronously from the device |
| 103 | + * |
| 104 | + * @param blk |
| 105 | + * The starting block of data to read from the device |
| 106 | + * |
| 107 | + * @param count |
| 108 | + * The number of blocks to read from the device |
| 109 | + * |
| 110 | + * @param reader |
| 111 | + * An operation to perform asynchronously |
| 112 | + * |
| 113 | + * @note A nullptr is passed to the reader if an error occurred |
| 114 | + * @note Validate the reader's input |
| 115 | + * |
| 116 | + * @example |
| 117 | + * if (buffer == nullptr) { |
| 118 | + * error("Device failed to read sector"); |
| 119 | + * } |
| 120 | + */ |
| 121 | + virtual void read(block_t blk, size_t count, on_read_func reader) = 0; |
72 | 122 |
|
73 | | - virtual void deactivate() = 0; |
| 123 | + /** |
| 124 | + * Read a block of data synchronously from the device |
| 125 | + * |
| 126 | + * @param blk |
| 127 | + * The block of data to read from the device |
| 128 | + * |
| 129 | + * @return A buffer containing the data or nullptr if an error occurred |
| 130 | + */ |
| 131 | + virtual buffer_t read_sync(block_t blk) = 0; |
74 | 132 |
|
75 | | - virtual ~Block_device() noexcept = default; |
| 133 | + /** |
| 134 | + * Read blocks of data synchronously from the device |
| 135 | + * |
| 136 | + * @param blk |
| 137 | + * The starting block of data to read from the device |
| 138 | + * |
| 139 | + * @param count |
| 140 | + * The number of blocks to read from the device |
| 141 | + * |
| 142 | + * @return A buffer containing the data or nullptr if an error occurred |
| 143 | + */ |
| 144 | + virtual buffer_t read_sync(block_t blk, size_t count) = 0; |
76 | 145 |
|
77 | | - protected: |
78 | | - Block_device(); |
| 146 | + /** |
| 147 | + * Method to deactivate the block device |
| 148 | + */ |
| 149 | + virtual void deactivate() = 0; |
79 | 150 |
|
80 | | - private: |
81 | | - int id_; |
82 | | - }; //< class Drive |
| 151 | + /** |
| 152 | + * Default destructor |
| 153 | + */ |
| 154 | + virtual ~Block_device() noexcept = default; |
| 155 | +protected: |
| 156 | + Block_device(); |
| 157 | +private: |
| 158 | + Device_id id_; |
| 159 | +}; //< class Block_device |
83 | 160 |
|
84 | 161 | } //< namespace hw |
85 | 162 |
|
86 | | -#endif //< HW_DRIVE_HPP |
| 163 | +#endif //< HW_BLOCK_DEVICE_HPP |
0 commit comments