Merge pull request #15 from Neotron-Compute/add_block_api_back

Author: thejpster

README.md

@@ -46,6 +46,7 @@ dual licensed as above, without any additional terms or conditions.
 * Add `time_ticks_get` and `time_ticks_per_second`
 * Add `bus_interrupt_status`
 * Remove `delay`
+* Add back in the `block_XXX` API for reading/writing Block Devices.
 
 ### v0.6.1
 

src/block_dev.rs

@@ -0,0 +1,88 @@
+//! # Block Devices
+//!
+//! Block Device related types.
+//!
+//! Note that all types in this file *must* be `#[repr(C)]` and ABI stable.
+
+// Copyright (C) The Neotron Developers, 2019-2022
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// ============================================================================
+// Imports
+// ============================================================================
+
+// None
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+// None
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/// The types of block device we support.
+#[repr(C)]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub enum DeviceType {
+	/// An *SD* Card
+	SecureDigitalCard,
+	/// A Hard Drive
+	HardDiskDrive,
+	/// A floppy disk in a floppy disk drive
+	FloppyDiskDrive,
+	/// A compact flash card
+	CompactFlashCard,
+}
+
+/// Information about a block device.
+#[repr(C)]
+#[derive(Clone, PartialEq, Eq, Debug)]
+pub struct DeviceInfo {
+	/// Some human-readable name for this block device (e.g. `SdCard0` or
+	/// `CF1`)
+	pub name: crate::ApiString<'static>,
+	/// The kind of block device this is.
+	pub device_type: DeviceType,
+	/// The size of an addressable block, in bytes.
+	pub block_size: u32,
+	/// The total number of addressable blocks.
+	pub num_blocks: u64,
+	/// Can this device be ejected?
+	pub ejectable: bool,
+	/// Can this device be removed?
+	pub removable: bool,
+	/// Does this have media in it right now?
+	pub media_present: bool,
+	/// Is this media read-only?
+	pub read_only: bool,
+}
+
+/// Uniquely represents a block on a block device.
+#[repr(C)]
+#[derive(Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Debug)]
+pub struct BlockIdx(pub u64);
+
+// ============================================================================
+// Impls
+// ============================================================================
+
+// None
+
+// ============================================================================
+// End of File
+// ============================================================================

src/lib.rs

@@ -27,6 +27,7 @@
 // ============================================================================
 
 pub mod audio;
+pub mod block_dev;
 pub mod bus;
 pub mod hid;
 pub mod i2c;
@@ -514,6 +515,70 @@ pub struct Api {
 	/// set when the interrupt is pending. There is no masking - ignore the bits
 	/// you don't care about.
 	pub bus_interrupt_status: extern "C" fn() -> u32,
+
+	// ========================================================================
+	// Block Device Support
+	// ========================================================================
+	/// Get information about the Block Devices in the system.
+	///
+	/// Block Devices are also known as *disk drives*. They can be read from
+	/// (and often written to) but only in units called *blocks* or *sectors*.
+	///
+	/// The BIOS should enumerate removable devices first, followed by fixed
+	/// devices.
+	///
+	/// The set of devices is not expected to change at run-time - removal of
+	/// media is indicated with a boolean field in the
+	/// `block_dev::DeviceInfo` structure.
+	pub block_dev_get_info: extern "C" fn(device: u8) -> crate::Option<block_dev::DeviceInfo>,
+	/// Eject a disk from the drive.
+	///
+	/// Will return an error if this device is not removable. Does not return an
+	/// error if the drive is already empty.
+	pub block_dev_eject: extern "C" fn(device: u8) -> crate::Result<()>,
+	/// Write one or more sectors to a block device.
+	///
+	/// The function will block until all data is written. The array pointed
+	/// to by `data` must be `num_blocks * block_size` in length, where
+	/// `block_size` is given by `block_dev_get_info`.
+	///
+	/// There are no requirements on the alignment of `data` but if it is
+	/// aligned, the BIOS may be able to use a higher-performance code path.
+	pub block_write: extern "C" fn(
+		device: u8,
+		start_block: block_dev::BlockIdx,
+		num_blocks: u8,
+		data: ApiByteSlice,
+	) -> crate::Result<()>,
+	/// Read one or more sectors to a block device.
+	///
+	/// The function will block until all data is read. The array pointed
+	/// to by `data` must be `num_blocks * block_size` in length, where
+	/// `block_size` is given by `block_dev_get_info`.
+	///
+	/// There are no requirements on the alignment of `data` but if it is
+	/// aligned, the BIOS may be able to use a higher-performance code path.
+	pub block_read: extern "C" fn(
+		device: u8,
+		start_block: block_dev::BlockIdx,
+		num_blocks: u8,
+		data: ApiBuffer,
+	) -> crate::Result<()>,
+	/// Verify one or more sectors on a block device (that is read them and
+	/// check they match the given data).
+	///
+	/// The function will block until all data is verified. The array pointed
+	/// to by `data` must be `num_blocks * block_size` in length, where
+	/// `block_size` is given by `block_dev_get_info`.
+	///
+	/// There are no requirements on the alignment of `data` but if it is
+	/// aligned, the BIOS may be able to use a higher-performance code path.
+	pub block_verify: extern "C" fn(
+		device: u8,
+		start_block: block_dev::BlockIdx,
+		num_blocks: u8,
+		data: ApiByteSlice,
+	) -> crate::Result<()>,
 }
 
 // ============================================================================