From d4575d8d8236f3f68b3a9136fed262fbaa118ae4 Mon Sep 17 00:00:00 2001 From: Rico Date: Sat, 25 Mar 2017 16:38:17 -0400 Subject: [PATCH] hw: Add API documentation to the block device interface --- api/hw/block_device.hpp | 175 +++++++++++++++++++++++++++++----------- 1 file changed, 126 insertions(+), 49 deletions(-) diff --git a/api/hw/block_device.hpp b/api/hw/block_device.hpp index 4f76c8c163..49af64d754 100644 --- a/api/hw/block_device.hpp +++ b/api/hw/block_device.hpp @@ -1,6 +1,6 @@ // This file is a part of the IncludeOS unikernel - www.includeos.org // -// Copyright 2015 Oslo and Akershus University College of Applied Sciences +// Copyright 2015-2017 Oslo and Akershus University College of Applied Sciences // and Alfred Bratterud // // Licensed under the Apache License, Version 2.0 (the "License"); @@ -16,71 +16,148 @@ // limitations under the License. #pragma once -#ifndef HW_DRIVE_HPP -#define HW_DRIVE_HPP +#ifndef HW_BLOCK_DEVICE_HPP +#define HW_BLOCK_DEVICE_HPP -#include #include #include +#include -namespace hw -{ - - /** - * Abstract interface for block devices of various driver types - **/ - class Block_device { - public: - using block_t = uint64_t; //< Disk device block size - using buffer_t = std::shared_ptr; - - // Delegate for result of reading a disk sector - //using on_read_func = delegate; - using on_read_func = delegate; +namespace hw { - using Device_id = int; +/** + * This class is an abstract interface for block devices + */ +class Block_device { +public: + using block_t = uint64_t; //< Representation for a device's block size + using buffer_t = std::shared_ptr; //< Representation for a block device's buffer + using Device_id = int32_t; //< Representation for a block device's identifier + using on_read_func = delegate; //< Delegate for result of reading from a block device - static const char* device_type() - { return "Block device"; } + /** + * Method to get the type of device + * + * @return The type of device as a C-String + */ + static const char* device_type() noexcept + { return "Block device"; } - virtual std::string device_name() const = 0; + /** + * Method to get the name of the device + * + * @return The name of the device as a std::string + */ + virtual std::string device_name() const = 0; - Device_id id() const { return id_; } + /** + * Method to get the device's identifier + * + * @return The device's identifier + */ + Device_id id() const noexcept + { return id_; } - /** Human-readable name of this disk controller */ - virtual const char* driver_name() const noexcept = 0; + /** + * Get the human-readable name of this device's controller + * + * @return The human-readable name of this device's controller + */ + virtual const char* driver_name() const noexcept = 0; - /** The size of the disk in whole sectors */ - virtual block_t size() const noexcept = 0; + /** + * Get the size of the device as total number of blocks + * + * @return The size of the device as total number of blocks + */ + virtual block_t size() const noexcept = 0; - /** Returns the optimal block size for this device */ - virtual block_t block_size() const noexcept = 0; + /** + * Get the optimal block size for this device + * + * @return The optimal block size for this device + */ + virtual block_t block_size() const noexcept = 0; - /** - * Read block(s) from blk and call func with result - * A null-pointer is passed to result if something bad happened - * Validate using !buffer_t: - * if (!buffer) - * error("Device failed to read sector"); - **/ - virtual void read(block_t blk, on_read_func func) = 0; - virtual void read(block_t blk, size_t count, on_read_func) = 0; + /** + * Read a block of data asynchronously from the device + * + * @param blk + * The block of data to read from the device + * + * @param reader + * An operation to perform asynchronously + * + * @note A nullptr is passed to the reader if an error occurred + * @note Validate the reader's input + * + * @example + * if (buffer == nullptr) { + * error("Device failed to read sector"); + * } + */ + virtual void read(block_t blk, on_read_func reader) = 0; - /** read synchronously the block @blk */ - virtual buffer_t read_sync(block_t blk) = 0; - virtual buffer_t read_sync(block_t blk, size_t count) = 0; + /** + * Read blocks of data asynchronously from the device + * + * @param blk + * The starting block of data to read from the device + * + * @param count + * The number of blocks to read from the device + * + * @param reader + * An operation to perform asynchronously + * + * @note A nullptr is passed to the reader if an error occurred + * @note Validate the reader's input + * + * @example + * if (buffer == nullptr) { + * error("Device failed to read sector"); + * } + */ + virtual void read(block_t blk, size_t count, on_read_func reader) = 0; - virtual void deactivate() = 0; + /** + * Read a block of data synchronously from the device + * + * @param blk + * The block of data to read from the device + * + * @return A buffer containing the data or nullptr if an error occurred + */ + virtual buffer_t read_sync(block_t blk) = 0; - virtual ~Block_device() noexcept = default; + /** + * Read blocks of data synchronously from the device + * + * @param blk + * The starting block of data to read from the device + * + * @param count + * The number of blocks to read from the device + * + * @return A buffer containing the data or nullptr if an error occurred + */ + virtual buffer_t read_sync(block_t blk, size_t count) = 0; - protected: - Block_device(); + /** + * Method to deactivate the block device + */ + virtual void deactivate() = 0; - private: - int id_; - }; //< class Drive + /** + * Default destructor + */ + virtual ~Block_device() noexcept = default; +protected: + Block_device(); +private: + Device_id id_; +}; //< class Block_device } //< namespace hw -#endif //< HW_DRIVE_HPP +#endif //< HW_BLOCK_DEVICE_HPP