Skip to content

Doxygen fixes in block devices #9334

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 11, 2019
Merged

Doxygen fixes in block devices #9334

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7dde677
Some Doxygen fixes in MBRBlockDevice and BlockDevice
Jan 10, 2019
73ac904
Doxygen changes to ProfilingBlockDevice and SlicingBlockDevice.
Jan 10, 2019
1066258
minor editorial tweaks
Jan 10, 2019
51168ee
Merge branch 'yossi_write-a-thon2' of github.com:yossi2le/mbed-os int…
Jan 10, 2019
6954c39
Update BlockDevice.h
GuyWi Jan 10, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions features/storage/blockdevice/BlockDevice.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,12 +49,12 @@ class BlockDevice {

/** Return the default block device
*
* Returns the default BlockDevice base on configuration json.
* Returns the default block device based on the configuration JSON.
* Use the components in target.json or application config to change
* the default block device.
*
* An application can override all target settings by implementing
* BlockDevice::get_default_instance() themselves - the default
* BlockDevice::get_default_instance() - the default
* definition is weak, and calls get_target_default_instance().
*/
static BlockDevice *get_default_instance();
Expand Down Expand Up @@ -90,8 +90,8 @@ class BlockDevice {
*
* @param buffer Buffer to write blocks to
* @param addr Address of block to begin reading from
* @param size Size to read in bytes, must be a multiple of read block size
* @return 0 on success, negative error code on failure
* @param size Size to read in bytes, must be a multiple of the read block size
* @return 0 on success or a negative error code on failure
*/
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size) = 0;

Expand All @@ -103,8 +103,8 @@ class BlockDevice {
*
* @param buffer Buffer of data to write to blocks
* @param addr Address of block to begin writing to
* @param size Size to write in bytes, must be a multiple of program block size
* @return 0 on success, negative error code on failure
* @param size Size to write in bytes, must be a multiple of the program block size
* @return 0 on success or a negative error code on failure
*/
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size) = 0;

Expand All @@ -114,8 +114,8 @@ class BlockDevice {
* unless get_erase_value returns a non-negative byte value
*
* @param addr Address of block to begin erasing
* @param size Size to erase in bytes, must be a multiple of erase block size
* @return 0 on success, negative error code on failure
* @param size Size to erase in bytes, must be a multiple of the erase block size
* @return 0 on success or a negative error code on failure
*/
virtual int erase(bd_addr_t addr, bd_size_t size)
{
Expand All @@ -130,8 +130,8 @@ class BlockDevice {
* the device is not busy.
*
* @param addr Address of block to mark as unused
* @param size Size to mark as unused in bytes, must be a multiple of erase block size
* @return 0 on success, negative error code on failure
* @param size Size to mark as unused in bytes, must be a multiple of the erase block size
* @return 0 on success or a negative error code on failure
*/
virtual int trim(bd_addr_t addr, bd_size_t size)
{
Expand Down Expand Up @@ -179,7 +179,7 @@ class BlockDevice {
* that value can be programmed without another erase.
*
* @return The value of storage when erased, or -1 if you can't
* rely on the value of erased storage
* rely on the value of the erased storage
*/
virtual int get_erase_value() const
{
Expand Down
68 changes: 11 additions & 57 deletions features/storage/blockdevice/MBRBlockDevice.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,52 +41,6 @@ enum {
/** Block device for managing a Master Boot Record
* https://en.wikipedia.org/wiki/Master_boot_record
*
* Here is an example of partitioning a heap backed block device
* @code
* #include "mbed.h"
* #include "HeapBlockDevice.h"
* #include "MBRBlockDevice.h"
*
* // Create a block device with 64 blocks of size 512
* HeapBlockDevice mem(64*512, 512);
*
* // Partition into two partitions with ~half the blocks
* MBRBlockDevice::partition(&mem, 1, 0x83, 0*512, 32*512);
* MBRBlockDevice::partition(&mem, 2, 0x83, 32*512);
*
* // Create a block device that maps to the first 32 blocks (excluding MBR block)
* MBRBlockDevice part1(&mem, 1);
*
* // Create a block device that maps to the last 32 blocks
* MBRBlockDevice part2(&mem, 2);
* @endcode
*
* Here is a more realistic example where the MBRBlockDevice is used
* to partition a region of space on an SD card. When plugged into a computer,
* the partitions will be recognized appropriately.
* @code
* #include "mbed.h"
* #include "SDBlockDevice.h"
* #include "MBRBlockDevice.h"
* #include "FATFileSystem.h"
*
* // Create an SD card
* SDBlockDevice sd(s0, s1, s2, s3);
*
* // Create a partition with 1 GB of space
* MBRBlockDevice::partition(&sd, 1, 0x83, 0, 1024*1024);
*
* // Create the block device that represents the partition
* MBRBlockDevice part1(&sd, 1);
*
* // Format the partition with a FAT filesystem
* FATFileSystem::format(&part1);
*
* // Create the FAT filesystem instance, files can now be written to
* // the FAT filesystem in partition 1
* FATFileSystem fat("fat", &part1);
* @endcode
*
* @note
* The MBR partition table is relatively limited:
* - At most 4 partitions are supported
Expand All @@ -98,12 +52,12 @@ class MBRBlockDevice : public BlockDevice {
*
* @param bd Block device to partition
* @param part Partition to use, 1-4
* @param type 8-bit partition type to identitfy partition's contents
* @param start Start block address to map to block 0 of partition,
* negative addresses are calculated from the end of the
* @param type 8-bit partition type to identify partition contents
* @param start Start block address to map to block 0 of partition.
* Negative addresses are calculated from the end of the
* underlying block devices. Block 0 is implicitly ignored
* from the range to store the MBR.
* @return 0 on success or a negative error code on failure
* @return 0 on success or a negative error code on failure.
* @note This is the same as partition(bd, part, type, start, bd->size())
*/
static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start);
Expand All @@ -112,15 +66,15 @@ class MBRBlockDevice : public BlockDevice {
*
* @param bd Block device to partition
* @param part Partition to use, 1-4
* @param type 8-bit partition type to identitfy partition's contents
* @param type 8-bit partition type to identify partition contents
* @param start Start block address to map to block 0 of partition,
* negative addresses are calculated from the end of the
* underlying block devices. Block 0 is implicitly ignored
* from the range to store the MBR.
* @param stop End block address to mark the end of the partition,
* this block is not mapped, negative addresses are calculated
* @param stop End block address to mark the end of the partition.
* This block is not mapped: negative addresses are calculated
* from the end of the underlying block device.
* @return 0 on success or a negative error code on failure
* @return 0 on success or a negative error code on failure.
*/
static int partition(BlockDevice *bd, int part, uint8_t type, bd_addr_t start, bd_addr_t stop);

Expand Down Expand Up @@ -158,7 +112,7 @@ class MBRBlockDevice : public BlockDevice {
* @param buffer Buffer to read blocks into
* @param addr Address of block to begin reading from
* @param size Size to read in bytes, must be a multiple of read block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);

Expand All @@ -169,7 +123,7 @@ class MBRBlockDevice : public BlockDevice {
* @param buffer Buffer of data to write to blocks
* @param addr Address of block to begin writing to
* @param size Size to write in bytes, must be a multiple of program block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);

Expand All @@ -180,7 +134,7 @@ class MBRBlockDevice : public BlockDevice {
*
* @param addr Address of block to begin erasing
* @param size Size to erase in bytes, must be a multiple of erase block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int erase(bd_addr_t addr, bd_size_t size);

Expand Down
22 changes: 3 additions & 19 deletions features/storage/blockdevice/ProfilingBlockDevice.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,22 +32,6 @@ namespace mbed {


/** Block device for measuring storage operations of another block device
*
* @code
* #include "mbed.h"
* #include "HeapBlockDevice.h"
* #include "ProfilingBlockDevice.h"
*
* // Create a heap block device and profiling block device
* HeapBlockDevice mem(64*512, 512);
* ProfilingBlockDevice profiler(&mem);
*
* // do block device work....
*
* printf("read count: %lld\n", profiler.get_read_count());
* printf("program count: %lld\n", profiler.get_program_count());
* printf("erase count: %lld\n", profiler.get_erase_count());
* @endcode
*/
class ProfilingBlockDevice : public BlockDevice {
public:
Expand Down Expand Up @@ -86,7 +70,7 @@ class ProfilingBlockDevice : public BlockDevice {
* @param buffer Buffer to read blocks into
* @param addr Address of block to begin reading from
* @param size Size to read in bytes, must be a multiple of read block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);

Expand All @@ -97,7 +81,7 @@ class ProfilingBlockDevice : public BlockDevice {
* @param buffer Buffer of data to write to blocks
* @param addr Address of block to begin writing to
* @param size Size to write in bytes, must be a multiple of program block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);

Expand All @@ -108,7 +92,7 @@ class ProfilingBlockDevice : public BlockDevice {
*
* @param addr Address of block to begin erasing
* @param size Size to erase in bytes, must be a multiple of erase block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int erase(bd_addr_t addr, bd_size_t size);

Expand Down
24 changes: 3 additions & 21 deletions features/storage/blockdevice/SlicingBlockDevice.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,24 +32,6 @@
namespace mbed {

/** Block device for mapping to a slice of another block device
*
* @code
* #include "mbed.h"
* #include "HeapBlockDevice.h"
* #include "SlicingBlockDevice.h"
*
* // Create a block device with 64 blocks of size 512
* HeapBlockDevice mem(64*512, 512);
*
* // Create a block device that maps to the first 32 blocks
* SlicingBlockDevice slice1(&mem, 0*512, 32*512);
*
* // Create a block device that maps to the last 32 blocks
* SlicingBlockDevice slice2(&mem, 32*512);
*
* // Create a block device that maps to the middle 32 blocks
* SlicingBlockDevice slice3(&mem, 16*512, -16*512);
* @endcode
*/
class SlicingBlockDevice : public BlockDevice {
public:
Expand Down Expand Up @@ -92,7 +74,7 @@ class SlicingBlockDevice : public BlockDevice {
* @param buffer Buffer to read blocks into
* @param addr Address of block to begin reading from
* @param size Size to read in bytes, must be a multiple of read block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);

Expand All @@ -103,7 +85,7 @@ class SlicingBlockDevice : public BlockDevice {
* @param buffer Buffer of data to write to blocks
* @param addr Address of block to begin writing to
* @param size Size to write in bytes, must be a multiple of program block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);

Expand All @@ -114,7 +96,7 @@ class SlicingBlockDevice : public BlockDevice {
*
* @param addr Address of block to begin erasing
* @param size Size to erase in bytes, must be a multiple of erase block size
* @return 0 on success, negative error code on failure
* @return 0 on success or a negative error code on failure
*/
virtual int erase(bd_addr_t addr, bd_size_t size);

Expand Down