diff --git a/bmap-parser/src/bmap.rs b/bmap-parser/src/bmap.rs index 1ce56dd..785f3cd 100644 --- a/bmap-parser/src/bmap.rs +++ b/bmap-parser/src/bmap.rs @@ -2,6 +2,7 @@ use strum::{Display, EnumDiscriminants, EnumString}; use thiserror::Error; mod xml; +/// Hash type to be used to build the checksum at blocks. #[derive(Copy, Clone, Debug, PartialEq, Eq, EnumString, Display)] #[strum(serialize_all = "lowercase")] #[non_exhaustive] @@ -9,6 +10,7 @@ pub enum HashType { Sha256, } +/// Value holder for the block's checksum. #[derive(Copy, Clone, Debug, PartialEq, Eq, EnumDiscriminants)] #[non_exhaustive] pub enum HashValue { @@ -16,12 +18,14 @@ pub enum HashValue { } impl HashValue { + /// Returns the hash type used in the HashValue. pub fn to_type(&self) -> HashType { match self { HashValue::Sha256(_) => HashType::Sha256, } } + /// Returns the value of the checksum in the HashValue. pub fn as_slice(&self) -> &[u8] { match self { HashValue::Sha256(v) => v, @@ -29,6 +33,7 @@ impl HashValue { } } +/// Reference to a mapped block of data that contain its checksum. #[derive(Clone, Debug, PartialEq, Eq)] pub struct BlockRange { offset: u64, @@ -37,6 +42,7 @@ pub struct BlockRange { } impl BlockRange { + /// Returns the checksum of the data mapped in the range of the block. pub fn checksum(&self) -> HashValue { self.checksum } @@ -50,6 +56,7 @@ impl BlockRange { } } +/// Contains the bmap file information, including a vector of blocks. #[derive(Clone, Debug)] pub struct Bmap { image_size: u64, @@ -61,6 +68,7 @@ pub struct Bmap { } impl Bmap { + /// Returns a BmapBuilder. pub fn builder() -> BmapBuilder { BmapBuilder::default() } @@ -77,6 +85,7 @@ impl Bmap { self.block_size } + /// Returns the number of blocks. pub fn blocks(&self) -> u64 { self.blocks } @@ -85,34 +94,47 @@ impl Bmap { self.mapped_blocks } + /// Returns the type of Hash used for the checksum. pub fn checksum_type(&self) -> HashType { self.checksum_type } + /// Returns an iterator of BlockRange. pub fn block_map(&self) -> impl ExactSizeIterator + Iterator { self.blockmap.iter() } + + /// Returns the total size of mapped memory, it can be bigger than the image size. pub fn total_mapped_size(&self) -> u64 { self.block_size * self.mapped_blocks } } +/// The error type returned by BmapBuilder. +/// +/// This error indicates that the Bmap could not be built correctly. It also points at the field that originated the error. #[derive(Clone, Debug, Error)] pub enum BmapBuilderError { #[error("Image size missing")] MissingImageSize, #[error("Block size missing")] MissingBlockSize, + /// Error that indicates the number of blocks is missing. #[error("Blocks missing")] MissingBlocks, + /// Error that indicates the number of mapped blocks is missing. #[error("Mapped blocks missing")] MissingMappedBlocks, #[error("Checksum type missing")] MissingChecksumType, + /// Error that indicates there are not BlockRanges in the vector. #[error("No block ranges")] NoBlockRanges, } +/// Intermediary tool to generate Bmap. +/// +/// Contains the same data fields as a Bmap, but most of them as Option. Allowing a progressive parsing and then a casting into Bmap. #[derive(Clone, Debug, Default)] pub struct BmapBuilder { image_size: Option, @@ -149,6 +171,7 @@ impl BmapBuilder { self } + /// Add a BlockRange to the vector indicating start, end and checksum. Needs Blocksize and Image to be set first. Returns the BmapBuilder. pub fn add_block_range(&mut self, start: u64, end: u64, checksum: HashValue) -> &mut Self { let bs = self.block_size.expect("Blocksize needs to be set first"); let total = self.image_size.expect("Image size needs to be set first"); @@ -157,6 +180,7 @@ impl BmapBuilder { self.add_byte_range(offset, length, checksum) } + /// Add a BlockRange to the vector indicating offset, length and checksum. Returns the BmapBuilder. pub fn add_byte_range(&mut self, offset: u64, length: u64, checksum: HashValue) -> &mut Self { let range = BlockRange { offset, @@ -167,6 +191,7 @@ impl BmapBuilder { self } + /// Returns a Bmap or an Error as a Result. pub fn build(self) -> Result { let image_size = self.image_size.ok_or(BmapBuilderError::MissingImageSize)?; let block_size = self.block_size.ok_or(BmapBuilderError::MissingBlockSize)?; diff --git a/bmap-parser/src/discarder.rs b/bmap-parser/src/discarder.rs index f9907d2..410275f 100644 --- a/bmap-parser/src/discarder.rs +++ b/bmap-parser/src/discarder.rs @@ -6,7 +6,7 @@ use std::io::Result as IOResult; use std::pin::Pin; use std::task::{Context, Poll}; -/// Adaptor that implements SeekForward on types only implementing Read by discarding data +/// Adaptor that implements SeekForward on types only implementing Read by discarding data. pub struct Discarder { reader: R, } diff --git a/bmap-parser/src/lib.rs b/bmap-parser/src/lib.rs index 9e81a64..ed3405b 100644 --- a/bmap-parser/src/lib.rs +++ b/bmap-parser/src/lib.rs @@ -1,3 +1,5 @@ +//! Bmap is a library for Rust that allows you to copy files +//! or flash block devices safely. mod bmap; pub use crate::bmap::*; mod discarder; @@ -36,6 +38,7 @@ impl AsyncSeekForward for T { } } +/// The error type returned by copy functions. #[derive(Debug, Error)] pub enum CopyError { #[error("Failed to Read: {0}")] @@ -48,6 +51,9 @@ pub enum CopyError { UnexpectedEof, } +/// Copy a file into another or flash a block device, using a Bmap file. +/// +/// For each block checks its checksum. pub fn copy(input: &mut I, output: &mut O, map: &Bmap) -> Result<(), CopyError> where I: Read + SeekForward, diff --git a/bmap-rs/src/main.rs b/bmap-rs/src/main.rs index 5d1f3e6..3fc4ec0 100644 --- a/bmap-rs/src/main.rs +++ b/bmap-rs/src/main.rs @@ -1,3 +1,6 @@ +//! Bmap-rs is an application that handles the use of bmap crate. +//! +//! It allows you to copy files or flash block devices safely. use anyhow::{anyhow, bail, ensure, Context, Result}; use async_compression::futures::bufread::GzipDecoder; use bmap_parser::{AsyncDiscarder, Bmap, Discarder, SeekForward};