Merge pull request #7 from Neotron-Compute/region_api_update

Region API update

Author: thejpster

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "neotron-common-bios"
-version = "0.1.0"
+version = "0.4.0-alpha"
 authors = ["Jonathan 'theJPster' Pallant <[email protected]>"]
 edition = "2018"
 description = "Common BIOS code and API for all Neotron systems."

README.md

@@ -36,3 +36,15 @@ This BIOS API crate is a work in progress.
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
+
+## Changelog
+
+### Unreleased Changes
+
+* Changed `memory_get_region` to return a `MemoryRegion`
+* Changed `video_set_framebuffer` to take a `*const u8` not `*mut u8` - as the
+  BIOS doesn't change video RAM.
+
+### v0.3.0
+
+* First published version. `Cargo.toml` reports at `0.1.0`.

src/lib.rs

@@ -31,7 +31,7 @@ pub use types::*;
 pub use version::Version;
 
 /// BIOS API semantic version for the API defined in this crate.
-pub const API_VERSION: Version = Version::new(0, 3, 0);
+pub const API_VERSION: Version = Version::new(0, 4, 0);
 
 /// The BIOS API.
 ///
@@ -147,36 +147,38 @@ pub struct Api {
 	pub video_get_framebuffer: extern "C" fn() -> *mut u8,
 	/// Set the framebuffer address.
 	///
-	/// Tell the BIOS where it should start fetching pixel or textual data
-	/// from (depending on the current video mode).
+	/// Tell the BIOS where it should start fetching pixel or textual data from
+	/// (depending on the current video mode).
 	///
 	/// This value is forgotten after a video mode change and must be
 	/// re-supplied.
-	pub video_set_framebuffer: extern "C" fn(*mut u8) -> crate::Result<()>,
-	/// Find out how large a given region of memory is.
 	///
-	/// The first region is the 'application region' and is defined to always
-	/// start at address `0x2000_0400` (that is, 1 KiB into main SRAM) on a
-	/// standard Cortex-M system. This application region stops just before
-	/// the BIOS reserved memory, at the top of the internal SRAM.
+	/// Once the BIOS has handed over to the OS, it will never write to video
+	/// memory, only read.
+	///
+	/// # Safety
+	///
+	/// The region pointed to by `start_address` must be large enough to contain
+	/// however much video memory is required by both the current video mode,
+	/// and whatever video modes you subsequently change into.
+	pub video_set_framebuffer: unsafe extern "C" fn(start_address: *const u8) -> crate::Result<()>,
+	/// Find out about regions of memory in the system.
+	///
+	/// The first region (index `0`) must be the 'application region' which is
+	/// defined to always start at address `0x2000_0400` (that is, 1 KiB into
+	/// main SRAM) on a standard Cortex-M system. This application region stops
+	/// just before the BIOS reserved memory, typically at the top of the
+	/// internal SRAM.
 	///
 	/// Other regions may be located at other addresses (e.g. external DRAM or
 	/// PSRAM).
 	///
-	/// The OS will always load non-relocatable applications into the bottom
-	/// of Region 0. It can allocate OS specific structures from any other
-	/// Region (if any), or from the top of Region 0 (although this reduces
-	/// the maximum application space available). The OS will prefer lower
-	/// numbered regions (other than Region 0), so faster memory should be
-	/// listed first.
-	///
-	/// If the region number given is invalid, the function returns `(null,
-	/// 0)`.
-	pub memory_get_region: extern "C" fn(
-		region: u8,
-		out_start: *mut *mut u8,
-		out_len: *mut usize,
-	) -> crate::Result<()>,
+	/// The OS will always load non-relocatable applications into the bottom of
+	/// Region 0. It can allocate OS specific structures from any other Region
+	/// (if any), or from the top of Region 0 (although this reduces the maximum
+	/// application space available). The OS will prefer lower numbered regions
+	/// (other than Region 0), so faster memory should be listed first.
+	pub memory_get_region: extern "C" fn(region_index: u8) -> crate::Result<types::MemoryRegion>,
 }
 
 // End of file

src/types.rs

@@ -126,6 +126,28 @@ pub struct Time {
 	pub nsecs: u32,
 }
 
+/// The kinds of memory we know about
+#[repr(C)]
+#[derive(Debug, Clone)]
+pub enum MemoryKind {
+	/// Read-write memory
+	Ram,
+	/// Read-only memory
+	Rom,
+}
+
+/// Represents a region in memory.
+#[repr(C)]
+#[derive(Debug, Clone)]
+pub struct MemoryRegion {
+	/// The address the region starts at
+	pub start: *mut u8,
+	/// The length of the region
+	pub length: usize,
+	/// The kind of memory found at this region
+	pub kind: MemoryKind,
+}
+
 // ============================================================================
 // Impls
 // ============================================================================
@@ -302,6 +324,35 @@ impl From<&Time> for chrono::DateTime<chrono::Utc> {
 	}
 }
 
+// MemoryKind
+
+impl core::fmt::Display for MemoryKind {
+	fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+		write!(
+			f,
+			"{}",
+			match self {
+				MemoryKind::Rom => "ROM",
+				MemoryKind::Ram => "RAM",
+			}
+		)
+	}
+}
+
+// MemoryRegion
+
+impl core::fmt::Display for MemoryRegion {
+	fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+		write!(
+			f,
+			"{} KiB {} @ {:p}",
+			self.length / 1024,
+			self.kind,
+			self.start
+		)
+	}
+}
+
 // ============================================================================
 // End of File
 // ============================================================================