diff --git a/LICENSE-MIT b/LICENSE-MIT index ec19225..b59c97c 100644 --- a/LICENSE-MIT +++ b/LICENSE-MIT @@ -1,4 +1,5 @@ -Copyright (c) 2018-2023 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers +Copyright (c) 2018-2024 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers +Copyright (c) 2011-2018 Bill Greiman Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..5dc1a0e --- /dev/null +++ b/NOTICE @@ -0,0 +1,6 @@ +# Copyright Notices + +This is a copyright notices file, as described by the Apache-2.0 license. + +Copyright (c) 2018-2024 Jonathan 'theJPster' Pallant and the Rust Embedded Community developers +Copyright (c) 2011-2018 Bill Greiman diff --git a/README.md b/README.md index 1e3194c..41985d2 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,12 @@ let mut cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(blo * Log over defmt or the common log interface (feature flags). ## No-std usage + This repository houses no examples for no-std usage, however you can check out the following examples: -- [Pi Pico](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/rp-pico/examples/pico_spi_sd_card.rs) -- [STM32H7XX](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc_fat.rs) -- [atsamd(pygamer)](https://github.com/atsamd-rs/atsamd/blob/master/boards/pygamer/examples/sd_card.rs) + +* [Pi Pico](https://github.com/rp-rs/rp-hal-boards/blob/main/boards/rp-pico/examples/pico_spi_sd_card.rs) +* [STM32H7XX](https://github.com/stm32-rs/stm32h7xx-hal/blob/master/examples/sdmmc_fat.rs) +* [atsamd(pygamer)](https://github.com/atsamd-rs/atsamd/blob/master/boards/pygamer/examples/sd_card.rs) ## Todo List (PRs welcome!) @@ -79,12 +81,14 @@ The changelog has moved to [CHANGELOG.md](/CHANGELOG.md) Licensed under either of - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or - http://www.apache.org/licenses/LICENSE-2.0) + ) -- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) +- MIT license ([LICENSE-MIT](LICENSE-MIT) or ) at your option. +Copyright notices are stored in the [NOTICE](./NOTICE) file. + ## Contribution Unless you explicitly state otherwise, any contribution intentionally diff --git a/src/blockdevice.rs b/src/blockdevice.rs index 76bd235..4564457 100644 --- a/src/blockdevice.rs +++ b/src/blockdevice.rs @@ -1,11 +1,12 @@ -//! Block Device support +//! Traits and types for working with Block Devices. //! //! Generic code for handling block devices, such as types for identifying //! a particular block on a block device by its index. -/// Represents a standard 512 byte block (also known as a sector). IBM PC -/// formatted 5.25" and 3.5" floppy disks, SD/MMC cards up to 1 GiB in size -/// and IDE/SATA Hard Drives up to about 2 TiB all have 512 byte blocks. +/// A standard 512 byte block (also known as a sector). +/// +/// IBM PC formatted 5.25" and 3.5" floppy disks, IDE/SATA Hard Drives up to +/// about 2 TiB, and almost all SD/MMC cards have 512 byte blocks. /// /// This library does not support devices with a block size other than 512 /// bytes. @@ -15,15 +16,17 @@ pub struct Block { pub contents: [u8; Block::LEN], } -/// Represents the linear numeric address of a block (or sector). The first -/// block on a disk gets `BlockIdx(0)` (which usually contains the Master Boot -/// Record). +/// The linear numeric address of a block (or sector). +/// +/// The first block on a disk gets `BlockIdx(0)` (which usually contains the +/// Master Boot Record). #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct BlockIdx(pub u32); -/// Represents the a number of blocks (or sectors). Add this to a `BlockIdx` -/// to get an actual address on disk. +/// The a number of blocks (or sectors). +/// +/// Add this to a `BlockIdx` to get an actual address on disk. #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)] pub struct BlockCount(pub u32); @@ -34,7 +37,7 @@ pub struct BlockIter { current: BlockIdx, } -/// Represents a block device - a device which can read and write blocks (or +/// A block device - a device which can read and write blocks (or /// sectors). Only supports devices which are <= 2 TiB in size. pub trait BlockDevice { /// The errors that the `BlockDevice` can return. Must be debug formattable. diff --git a/src/fat/bpb.rs b/src/fat/bpb.rs index cc77900..f06f23e 100644 --- a/src/fat/bpb.rs +++ b/src/fat/bpb.rs @@ -6,9 +6,10 @@ use crate::{ }; use byteorder::{ByteOrder, LittleEndian}; -/// Represents a Boot Parameter Block. This is the first sector of a FAT -/// formatted partition, and it describes various properties of the FAT -/// filesystem. +/// A Boot Parameter Block. +/// +/// This is the first sector of a FAT formatted partition, and it describes +/// various properties of the FAT filesystem. pub struct Bpb<'a> { data: &'a [u8; 512], pub(crate) fat_type: FatType, diff --git a/src/fat/ondiskdirentry.rs b/src/fat/ondiskdirentry.rs index 14be74c..49b8bb2 100644 --- a/src/fat/ondiskdirentry.rs +++ b/src/fat/ondiskdirentry.rs @@ -3,7 +3,10 @@ use crate::{fat::FatType, Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp}; use byteorder::{ByteOrder, LittleEndian}; -/// Represents a 32-byte directory entry as stored on-disk in a directory file. +/// A 32-byte directory entry as stored on-disk in a directory file. +/// +/// This is the same for FAT16 and FAT32 (except FAT16 doesn't use +/// first_cluster_hi). pub struct OnDiskDirEntry<'a> { data: &'a [u8], } @@ -38,8 +41,6 @@ impl<'a> core::fmt::Debug for OnDiskDirEntry<'a> { } } -/// Represents the 32 byte directory entry. This is the same for FAT16 and -/// FAT32 (except FAT16 doesn't use first_cluster_hi). impl<'a> OnDiskDirEntry<'a> { pub(crate) const LEN: usize = 32; pub(crate) const LEN_U32: u32 = 32; diff --git a/src/filesystem/directory.rs b/src/filesystem/directory.rs index 0ed53e8..b965995 100644 --- a/src/filesystem/directory.rs +++ b/src/filesystem/directory.rs @@ -7,8 +7,7 @@ use crate::{Error, RawVolume, VolumeManager}; use super::ToShortFileName; -/// Represents a directory entry, which tells you about -/// other files and directories. +/// A directory entry, which tells you about other files and directories. #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] #[derive(Debug, PartialEq, Eq, Clone)] pub struct DirEntry { @@ -30,7 +29,7 @@ pub struct DirEntry { pub entry_offset: u32, } -/// Represents an open directory on disk. +/// A handle for an open directory on disk. /// /// Do NOT drop this object! It doesn't hold a reference to the Volume Manager /// it was created from and if you drop it, the VolumeManager will think you @@ -70,7 +69,7 @@ impl RawDirectory { } } -/// Represents an open directory on disk. +/// A handle for an open directory on disk, which closes on drop. /// /// In contrast to a `RawDirectory`, a `Directory` holds a mutable reference to /// its parent `VolumeManager`, which restricts which operations you can perform. diff --git a/src/filesystem/files.rs b/src/filesystem/files.rs index 462511a..5e52477 100644 --- a/src/filesystem/files.rs +++ b/src/filesystem/files.rs @@ -3,7 +3,7 @@ use crate::{ Error, RawVolume, VolumeManager, }; -/// Represents an open file on disk. +/// A handle for an open file on disk. /// /// Do NOT drop this object! It doesn't hold a reference to the Volume Manager /// it was created from and cannot update the directory entry if you drop it. @@ -37,7 +37,7 @@ impl RawFile { } } -/// Represents an open file on disk. +/// A handle for an open file on disk, which closes on drop. /// /// In contrast to a `RawFile`, a `File` holds a mutable reference to its /// parent `VolumeManager`, which restricts which operations you can perform. diff --git a/src/filesystem/timestamp.rs b/src/filesystem/timestamp.rs index 3e70cc0..ff2c0be 100644 --- a/src/filesystem/timestamp.rs +++ b/src/filesystem/timestamp.rs @@ -4,9 +4,10 @@ pub trait TimeSource { fn get_timestamp(&self) -> Timestamp; } -/// Represents an instant in time, in the local time zone. TODO: Consider -/// replacing this with POSIX time as a `u32`, which would save two bytes at -/// the expense of some maths. +/// A Gregorian Calendar date/time, in the local time zone. +/// +/// TODO: Consider replacing this with POSIX time as a `u32`, which would save +/// two bytes at the expense of some maths. #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] #[derive(Copy, Clone, PartialOrd, Ord, PartialEq, Eq)] pub struct Timestamp { diff --git a/src/lib.rs b/src/lib.rs index 6466102..f1c4e02 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -135,7 +135,7 @@ macro_rules! warn { // // **************************************************************************** -/// Represents all the ways the functions in this crate can fail. +/// All the ways the functions in this crate can fail. #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] #[derive(Debug, Clone)] pub enum Error @@ -211,7 +211,7 @@ where } } -/// Represents a partition with a filesystem within it. +/// A partition with a filesystem within it. #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub struct RawVolume(SearchId); @@ -236,7 +236,7 @@ impl RawVolume { } } -/// Represents an open volume on disk. +/// An open volume on disk, which closes on drop. /// /// In contrast to a `RawVolume`, a `Volume` holds a mutable reference to its /// parent `VolumeManager`, which restricts which operations you can perform. @@ -354,8 +354,7 @@ pub enum VolumeType { Fat(FatVolume), } -/// A `VolumeIdx` is a number which identifies a volume (or partition) on a -/// disk. +/// A number which identifies a volume (or partition) on a disk. /// /// `VolumeIdx(0)` is the first primary partition on an MBR partitioned disk. #[cfg_attr(feature = "defmt-log", derive(defmt::Format))] diff --git a/src/sdcard/mod.rs b/src/sdcard/mod.rs index d53a15a..6593043 100644 --- a/src/sdcard/mod.rs +++ b/src/sdcard/mod.rs @@ -1,6 +1,4 @@ -//! The SD/MMC Protocol -//! -//! Implements the SD/MMC protocol on some generic SPI interface. +//! Implements the BlockDevice trait for an SD/MMC Protocol over SPI. //! //! This is currently optimised for readability and debugability, not //! performance. @@ -21,7 +19,7 @@ use crate::{debug, warn}; // Types and Implementations // **************************************************************************** -/// Represents an SD Card on an SPI bus. +/// Driver for an SD Card on an SPI bus. /// /// Built from an [`SpiDevice`] implementation and a Chip Select pin. /// @@ -201,7 +199,7 @@ where } } -/// Represents an SD Card on an SPI bus. +/// Inner details for the SD Card driver. /// /// All the APIs required `&mut self`. struct SdCardInner diff --git a/src/volume_mgr.rs b/src/volume_mgr.rs index 15e4f42..98b7781 100644 --- a/src/volume_mgr.rs +++ b/src/volume_mgr.rs @@ -18,8 +18,11 @@ use crate::{ }; use heapless::Vec; -/// A `VolumeManager` wraps a block device and gives access to the FAT-formatted -/// volumes within it. +/// Wraps a block device and gives access to the FAT-formatted volumes within +/// it. +/// +/// Tracks which files and directories are open, to prevent you from deleting +/// a file or directory you currently have open. #[derive(Debug)] pub struct VolumeManager< D,