Merge pull request #48 from Neotron-Compute/release-0.12

Bump to 0.12.0.
Neotron-Compute · Feb 4, 2024 · 83d0893 · 83d0893
2 parents 76beea6 + 11aa674
commit 83d0893
Show file tree

Hide file tree

Showing 11 changed files with 551 additions and 454 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,89 @@
+# Changelog
+
+## Unreleased Changes
+
+* None
+
+## v0.12.0 - 2023-10-21 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.12.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.12.0) | [Crate](https://crates.io/crates/neotron-common-bios/0.12.0))
+
+* The `video_set_mode` API now takes a framebuffer pointer.
+* The `video_set_framebuffer` API was removed.
+* Made all types FFI safe (use `struct Foo(u8)` not `enum Foo`)
+* Add `MemoryKind::StackFree` and `MemoryKind::StackUsed`
+* `TextForegroundColour` and `TextBackgroundColour` are now enums, not structs with const values.
+
+## v0.11.1 - 2023-10-01 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.11.1) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.11.1) | [Crate](https://crates.io/crates/neotron-common-bios/v0.11.1))
+
+* New `video::Mode::new_with_scaling` method
+* New `video::Scaling` type
+* Marked methods as inline to help avoid thunks when code is in RAM
+
+## v0.11.0 - 2023-07-21 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.11.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.11.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.11.0))
+
+* Add compare_and_swap_bool function
+* Add power_control function
+
+## v0.10.0 - 2023-07-15 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.10.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.10.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.10.0))
+
+* Change palette constants to match the VGA standard.
+
+## v0.9.0 - 2023-07-15 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.9.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.9.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.9.0))
+
+* Use types from [`neotron-ffi`](https://crates.io/crates/neotron-ffi) crate.
+
+## v0.8.0 - 2023-02-12 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.8.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.8.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.8.0))
+
+* `audio_mixer_channel_get_info` now returns an `Option` not `Result`
+* Add `impl From<core::option::Option for Option`
+* Add `impl From<Option for core::option::Option`
+* Add `impl From<core::result::Result for Result`
+* Add `impl From<Result for core::result::Result`
+* Clarify that some parameters are actually expected to be numeric IDs
+* Use [`pc-keyboard::KeyCode`](https://crates.io/crates/pc-keyboard) to define Key Codes.
+
+## v0.7.0 - 2022-11-17 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.7.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.7.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.7.0))
+
+* Change `time_get` to `time_clock_get`
+* Change `time_set` to `time_clock_set`
+* 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.
+* Add idle function.
+* `memory_get_region` returns `Option`, not `Result`
+* Fix epoch used in conversion to chrono timestamp.
+
+## v0.6.1 - 2022-04-18 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.6.1) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.6.1) | [Crate](https://crates.io/crates/neotron-common-bios/v0.6.1))
+
+* No changes - v0.6.0 release was incorrect so re-releasing
+
+## v0.6.0 - 2022-04-18 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.6.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.6.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.6.0))
+
+* Removed 'block_X' APIs
+* Added 'bus_X' APIs
+* Added 'audio_X' APIs
+* Added 'i2c_X' APIs
+* Added 'video_get/set_palette' APIs
+* Added 'delay' API
+
+## v0.5.0 - 2022-04-15 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.5.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.5.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.5.0))
+
+* Added `serial_read` API
+* Added `video_mode_needs_vram` API
+* Added `hid_get_event` API
+* Added `hid_set_leds` API
+* Added `video_wait_for_line` API
+* Added `block_dev_get_info` API
+* Added `block_write` API
+* Added `block_read` API
+* Added `block_verify` API
+
+## v0.4.0 - 2022-04-06 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.4.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.4.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.4.0))
+
+* 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.1.0 - 2022-03-18 ([Source](https://github.com/neotron-compute/neotron-common-bios/tree/v0.1.0) | [Release](https://github.com/neotron-compute/neotron-common-bios/releases/tag/v0.1.0) | [Crate](https://crates.io/crates/neotron-common-bios/v0.1.0))
+
+* First published version. `Cargo.toml` reports at `0.1.0`.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,13 +1,13 @@
 [package]
 authors = ["Jonathan 'theJPster' Pallant <github@thejpster.org.uk>"]
-description = "Common BIOS code and API for all Neotron systems."
+description = "Contains the BIOS API and common routines for all Neotron systems."
 edition = "2018"
 homepage = "https://github.com/neotron-compute/neotron-common-bios"
 license = "GPL-3.0-or-later"
 name = "neotron-common-bios"
 readme = "README.md"
 repository = "https://github.com/neotron-compute/neotron-common-bios.git"
-version = "0.11.1"
+version = "0.12.0"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

diff --git a/README.md b/README.md
@@ -2,21 +2,13 @@
 
 This crate contains the BIOS API and common routines for all Neotron systems.
 
-![Build Status](https://github.com/neotron-compute/Neotron-Common-BIOS/workflows/Build/badge.svg "Github Action Build Status")
-
-![Format Status](https://github.com/neotron-compute/Neotron-Common-BIOS/workflows/Format/badge.svg "Github Action Format Check Status")
-
-## Hardware
-
-Neotron runs on a variety of ARM Cortex-M based systems.
-
 ## Status
 
 This BIOS API crate is a work in progress.
 
 ## License
 
-    Copyright (C) The Neotron Developers, 2019-2022
+    Copyright (C) The Neotron Developers, 2019-2024
 
     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
@@ -35,86 +27,8 @@ 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.
+licensed as above, without any additional terms or conditions.
 
 ## Changelog
 
-### Unreleased Changes
-
-* None
-
-### v0.11.1
-
-* New `video::Mode::new_with_scaling` method
-* New `video::Scaling` type
-* Marked methods as inline to help avoid thunks when code is in RAM
-
-### v0.11.0
-
-* Add compare_and_swap_bool function
-* Add power_control function
-
-### v0.10.0
-
-* Change palette constants to match the VGA standard.
-
-### v0.9.0
-
-* Use types from [`neotron-ffi`](https://crates.io/crates/neotron-ffi) crate.
-
-### v0.8.0
-
-* `audio_mixer_channel_get_info` now returns an `Option` not `Result`
-* Add `impl From<core::option::Option for Option`
-* Add `impl From<Option for core::option::Option`
-* Add `impl From<core::result::Result for Result`
-* Add `impl From<Result for core::result::Result`
-* Clarify that some parameters are actually expected to be numeric IDs
-* Use [`pc-keyboard::KeyCode`](https://crates.io/crates/pc-keyboard) to define Key Codes.
-
-### v0.7.0
-
-* Change `time_get` to `time_clock_get` 
-* Change `time_set` to `time_clock_set` 
-* 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.
-* Add idle function.
-* `memory_get_region` returns `Option`, not `Result`
-* Fix epoch used in conversion to chrono timestamp.
-
-### v0.6.1
-
-* No changes - v0.6.0 release was incorrect so re-releasing
-
-### v0.6.0
-
-* Removed 'block_X' APIs
-* Added 'bus_X' APIs
-* Added 'audio_X' APIs
-* Added 'i2c_X' APIs
-* Added 'video_get/set_palette' APIs
-* Added 'delay' API
-
-### v0.5.0
-
-* Added `serial_read` API
-* Added `video_mode_needs_vram` API
-* Added `hid_get_event` API
-* Added `hid_set_leds` API
-* Added `video_wait_for_line` API
-* Added `block_dev_get_info` API
-* Added `block_write` API
-* Added `block_read` API
-* Added `block_verify` API
-
-### v0.4.0
-
-* 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`.
+See [`CHANGELOG.md`](./CHANGELOG.md).
diff --git a/src/audio.rs b/src/audio.rs
@@ -24,7 +24,7 @@
 // Imports
 // ============================================================================
 
-// None
+use crate::make_ffi_enum;
 
 // ============================================================================
 // Constants
@@ -36,26 +36,24 @@
 // Types
 // ============================================================================
 
-/// Defines the format of each sample (mono, stereo, 8-bit, 16-bit, etc).
-#[repr(u8)]
-#[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub enum SampleFormat {
-	/// 8-bit, signed, mono samples.
+make_ffi_enum!("Defines the format of each sample (mono, stereo, 8-bit, 16-bit, etc).",
+	SampleFormat, FfiSampleFormat, {
+	#[doc = "8-bit, signed, mono samples"]
 	EightBitMono,
-	/// 8-bit, signed, mono samples. Left, then Right.
+	#[doc = "8-bit, signed, mono samples. Left, then Right"]
 	EightBitStereo,
-	/// 16-bit, signed, mono samples. Little-endian.
+	#[doc = "16-bit, signed, mono samples. Little-endian"]
 	SixteenBitMono,
-	/// 16-bit, signed, stereo samples. Little-endian. Left, then Right.
-	SixteenBitStereo,
-}
+	#[doc = "16-bit, signed, stereo samples. Little-endian. Left, then Right"]
+	SixteenBitStereo
+});
 
 /// Configuration for an Audio Output or Input
 #[repr(C)]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Config {
 	/// What format are the samples
-	pub sample_format: SampleFormat,
+	pub sample_format: FfiSampleFormat,
 	/// How many samples are there per second (e.g. 48,000)?
 	///
 	/// Supported values are likely to include some of the following:
@@ -70,17 +68,15 @@ pub struct Config {
 	pub sample_rate_hz: u32,
 }
 
-/// Describes the direction audio is flowing, for a given Audio Mixer Channel.
-#[repr(u8)]
-#[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub enum Direction {
-	/// Audio In, e.g. Line-In
+make_ffi_enum!("Describes the direction audio is flowing, for a given Audio Mixer Channel",
+	Direction, FfiDirection, {
+	#[doc = "Audio In, e.g. Line-In"]
 	Input,
-	/// Audio Out, e.g. Headphone Out
+	#[doc = "Audio Out, e.g. Headphone Out"]
 	Output,
-	/// Internal audio loop-back from an Input to an Output, e.g. Side-tone
-	Loopback,
-}
+	#[doc = "Internal audio loop-back from an Input to an Output, e.g. Side-tone"]
+	Loopback
+});
 
 /// Describes an Audio Mixer Channel.
 ///
@@ -91,7 +87,7 @@ pub struct MixerChannelInfo {
 	/// The name of this Audio Mixer Channel (e.g. `Line In`)
 	pub name: crate::FfiString<'static>,
 	/// Is this an Input or an Output?
-	pub direction: Direction,
+	pub direction: FfiDirection,
 	/// What value of `current_level` gives the loudest audio? All values
 	/// equal to, or above, this value will be equally and maximally loud.
 	pub max_level: u8,

diff --git a/src/block_dev.rs b/src/block_dev.rs
@@ -23,7 +23,7 @@
 // Imports
 // ============================================================================
 
-// None
+use crate::make_ffi_enum;
 
 // ============================================================================
 // Constants
@@ -35,19 +35,17 @@
 // Types
 // ============================================================================
 
-/// The types of block device we support.
-#[repr(C)]
-#[derive(Clone, PartialEq, Eq, Debug)]
-pub enum DeviceType {
-	/// An *SD* Card
+make_ffi_enum!("The types of block device we support",
+DeviceType, FfiDeviceType, {
+	#[doc = "An *SD* Card"]
 	SecureDigitalCard,
-	/// A Hard Drive
+	#[doc = "A Hard Drive"]
 	HardDiskDrive,
-	/// A floppy disk in a floppy disk drive
+	#[doc = "A floppy disk in a floppy disk drive"]
 	FloppyDiskDrive,
-	/// A compact flash card
-	CompactFlashCard,
-}
+	#[doc = "A compact flash card"]
+	CompactFlashCard
+});
 
 /// Information about a block device.
 #[repr(C)]
@@ -57,7 +55,7 @@ pub struct DeviceInfo {
 	/// `CF1`)
 	pub name: crate::FfiString<'static>,
 	/// The kind of block device this is.
-	pub device_type: DeviceType,
+	pub device_type: FfiDeviceType,
 	/// The size of an addressable block, in bytes.
 	pub block_size: u32,
 	/// The total number of addressable blocks.

diff --git a/src/bus.rs b/src/bus.rs
@@ -24,7 +24,7 @@
 // Imports
 // ============================================================================
 
-// None
+use crate::make_ffi_enum;
 
 // ============================================================================
 // Constants
@@ -36,20 +36,18 @@
 // Types
 // ============================================================================
 
-/// The kinds of Peripheral you can put on a Neotron Bus
-#[repr(u8)]
-#[derive(Debug, Clone, Eq, PartialEq)]
-pub enum PeripheralKind {
-	/// A Neotron Bus Slot. The OS will need to read the EEPROM at address
-	/// `0x50 + slot_id` to find out what is fitted (if anything).
+make_ffi_enum!("The kinds of Peripheral you can put on a Neotron Bus",
+	PeripheralKind, FfiPeripheralKind, {
+	#[doc = "A Neotron Bus Slot.\n\nThe OS will need to read the EEPROM at address"]
+	#[doc = "`0x50 + slot_id` to find out what is fitted (if anything)."]
 	Slot,
-	/// A hard-wired SD/MMC Card slot wired for SPI Mode. The interrupt pin is
-	/// wired to "Card Detect" with a pull-up, so the line goes low when a
-	/// card is inserted and goes high when the card is removed.
+	#[doc = "A hard-wired SD/MMC Card slot wired for SPI Mode.\n\nThe interrupt pin is"]
+	#[doc = "wired to *Card Detect* with a pull-up, so the line goes low when a card is "]
+	#[doc = "inserted and goes high when the card is removed."]
 	SdCard,
-	/// This Peripheral ID is reserved for the BIOS to use.
-	Reserved,
-}
+	#[doc = "This Peripheral ID is reserved for the BIOS to use."]
+	Reserved
+});
 
 /// Describes a Neotron Bus Peripheral
 #[repr(C)]
@@ -58,7 +56,7 @@ pub struct PeripheralInfo {
 	/// A name, such as `slot0`
 	pub name: crate::FfiString<'static>,
 	/// The kind of peripheral
-	pub kind: PeripheralKind,
+	pub kind: FfiPeripheralKind,
 }
 
 // ============================================================================