Merge pull request #26 from Neotron-Compute/release/v0.8.0

Release/v0.8.0

Author: thejpster

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "neotron-common-bios"
-version = "0.7.0"
+version = "0.8.0"
 authors = ["Jonathan 'theJPster' Pallant <[email protected]>"]
 edition = "2018"
 description = "Common BIOS code and API for all Neotron systems."
@@ -13,3 +13,4 @@ readme = "README.md"
 
 [dependencies]
 chrono = { version = "0.4", default-features=false }
+pc-keyboard = "0.7"

README.md

@@ -41,6 +41,18 @@ dual licensed as above, without any additional terms or conditions.
 
 ### Unreleased Changes
 
+* None
+
+### 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` 

src/hid.rs

@@ -24,7 +24,7 @@
 // Imports
 // ============================================================================
 
-// None
+pub use pc_keyboard::KeyCode;
 
 // ============================================================================
 // Constants
@@ -50,253 +50,6 @@ pub enum HidEvent {
 	MouseInput(MouseData),
 }
 
-/// Represents a single key on a standard keyboard.
-///
-/// These keys are labelled according to their function on a standard United
-/// States layout 104-key keyboard. If you have a different layout keyboard,
-/// the symbol printed in the key you pressed may not match the `KeyCode`
-/// value it generates. For example, if you press the `Z` key on a German
-/// keyboard, you will get `KeyCode::Y` because that same key is the `Y` key
-/// on a US keyboard.
-#[repr(u8)]
-#[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord)]
-pub enum KeyCode {
-	/// The left-hand `Alt` key
-	AltLeft,
-	/// The right-hand `Alt` (or `AltGr`) key
-	AltRight,
-	/// The Down cursor key
-	ArrowDown,
-	/// The Left cursor key
-	ArrowLeft,
-	/// The Right cursor key
-	ArrowRight,
-	/// The Up cursor key
-	ArrowUp,
-	/// The `\\|` key
-	BackSlash,
-	/// The `Backspace` (`Bksp` or `<--`) key
-	Backspace,
-	/// The `\`~` key.
-	///
-	/// Left of the `1` key. On a UK keyboard this is `\`¬|`.
-	BackTick,
-	/// The `[{` key
-	BracketSquareLeft,
-	/// The `]}` key
-	BracketSquareRight,
-	/// The `Caps Lock` key
-	CapsLock,
-	/// The `,<` key
-	Comma,
-	/// The left-most `Control` (`Ctrl`) key
-	ControlLeft,
-	/// The right-most `Control` (`Ctrl`) key
-	ControlRight,
-	/// The `Delete` (`Del`) key
-	Delete,
-	/// The `End` key
-	End,
-	/// The `Enter` (`Return`) key, on the right-hand side of the letters.
-	Enter,
-	/// The `Escape` (`Esc`) key
-	Escape,
-	/// The `=+` key
-	Equals,
-	/// The `F1` key
-	F1,
-	/// The `F2` key
-	F2,
-	/// The `F3` key
-	F3,
-	/// The `F4` key
-	F4,
-	/// The `F5` key
-	F5,
-	/// The `F6` key
-	F6,
-	/// The `F7` key
-	F7,
-	/// The `F8` key
-	F8,
-	/// The `F9` key
-	F9,
-	/// The `F10` key
-	F10,
-	/// The `F11` key
-	F11,
-	/// The `F12` key
-	F12,
-	/// The `.>` key
-	Fullstop,
-	/// The `Home` key
-	Home,
-	/// The `Insert` key
-	Insert,
-	/// The `1!` key
-	Key1,
-	/// The `2@` key
-	Key2,
-	/// The `3#` key
-	Key3,
-	/// The `4$` key
-	Key4,
-	/// The `5%` key
-	Key5,
-	/// The `6^` key
-	Key6,
-	/// The `7&` key
-	Key7,
-	/// The `8*` key
-	Key8,
-	/// The `9(` key
-	Key9,
-	/// The `0)` key
-	Key0,
-	/// The `Right-click Menu` key
-	Menus,
-	/// The `-_` key
-	Minus,
-	/// The `0` key on the Numeric Keypad
-	Numpad0,
-	/// The `1` key on the Numeric Keypad
-	Numpad1,
-	/// The `2` key on the Numeric Keypad
-	Numpad2,
-	/// The `3` key on the Numeric Keypad
-	Numpad3,
-	/// The `4` key on the Numeric Keypad
-	Numpad4,
-	/// The `5` key on the Numeric Keypad
-	Numpad5,
-	/// The `6` key on the Numeric Keypad
-	Numpad6,
-	/// The `7` key on the Numeric Keypad
-	Numpad7,
-	/// The `8` key on the Numeric Keypad
-	Numpad8,
-	/// The `9` key on the Numeric Keypad
-	Numpad9,
-	/// The `Enter` key on the Numeric Keypad
-	NumpadEnter,
-	/// The `Num Lock` key on the Numeric Keypad
-	NumpadLock,
-	/// The `/` key on the Numeric Keypad
-	NumpadSlash,
-	/// The `*` key on the Numeric Keypad
-	NumpadStar,
-	/// The `-` key on the Numeric Keypad
-	NumpadMinus,
-	/// The `.` key on the Numeric Keypad
-	NumpadPeriod,
-	/// The `+` key on the Numeric Keypad
-	NumpadPlus,
-	/// The `Page Down` key
-	PageDown,
-	/// The `Page Up` key
-	PageUp,
-	/// The `Pause/Break` key
-	PauseBreak,
-	/// The `Print Screen` (`PrtScr`) key
-	PrintScreen,
-	/// The `Scroll Lock` key
-	ScrollLock,
-	/// The `;:` key
-	SemiColon,
-	/// The left-most shift key
-	ShiftLeft,
-	/// The right-most shift key
-	ShiftRight,
-	/// The `/?` key
-	Slash,
-	/// The `Space` key
-	Spacebar,
-	/// The `Tab` key
-	Tab,
-	/// The `'` key
-	Quote,
-	/// The left-most Windows (or GUI) key
-	WindowsLeft,
-	/// The right-most Windows (or GUI) key
-	WindowsRight,
-	/// The `Aa` key
-	A,
-	/// The `Bb` key
-	B,
-	/// The `Cc` key
-	C,
-	/// The `Dd` key
-	D,
-	/// The `Ee` key
-	E,
-	/// The `Ff` key
-	F,
-	/// The `Gg` key
-	G,
-	/// The `Hh` key
-	H,
-	/// The `Ii` key
-	I,
-	/// The `Jj` key
-	J,
-	/// The `Kk` key
-	K,
-	/// The `Ll` key
-	L,
-	/// The `Mm` key
-	M,
-	/// The `Nn` key
-	N,
-	/// The `Oo` key
-	O,
-	/// The `Pp` key
-	P,
-	/// The `Qq` key
-	Q,
-	/// The `Rr` key
-	R,
-	/// The `Ss` key
-	S,
-	/// The `Tt` key
-	T,
-	/// The `Uu` key
-	U,
-	/// The `Vv` key
-	V,
-	/// The `Ww` key
-	W,
-	/// The `Xx` key
-	X,
-	/// The `Yy` key
-	Y,
-	/// The `Zz` key
-	Z,
-	/// Found on non-US (e.g. UK) keyboards next to the main *Return* key.
-	HashTilde,
-	/// Media transport: previous track
-	PrevTrack,
-	/// Media transport: next track
-	NextTrack,
-	/// Media transport: mute audio
-	Mute,
-	/// Application key: open calculator
-	Calculator,
-	/// Media transport: play audio
-	Play,
-	/// Media transport: stop audio
-	Stop,
-	/// Media transport: turn volume down
-	VolumeDown,
-	/// Media transport: turn volume up
-	VolumeUp,
-	/// Media transport: open browser to homepage
-	WWWHome,
-	/// Keyboard Power On Test passed.
-	///
-	/// Expect this once on start-up.
-	PowerOnTestOk,
-}
-
 /// Represents the movement of a mouse over the previous period of time, and
 /// the current state of the mouse buttons.
 #[repr(C)]

src/lib.rs

@@ -89,17 +89,17 @@ pub struct Api {
 	/// that is an Operating System level design feature. These APIs just
 	/// reflect the raw hardware, in a similar manner to the registers exposed
 	/// by a memory-mapped UART peripheral.
-	pub serial_get_info: extern "C" fn(device: u8) -> crate::Option<serial::DeviceInfo>,
+	pub serial_get_info: extern "C" fn(device_id: u8) -> crate::Option<serial::DeviceInfo>,
 	/// Set the options for a given serial device. An error is returned if the
 	/// options are invalid for that serial device.
-	pub serial_configure: extern "C" fn(device: u8, config: serial::Config) -> crate::Result<()>,
+	pub serial_configure: extern "C" fn(device_id: u8, config: serial::Config) -> crate::Result<()>,
 	/// Write bytes to a serial port. There is no sense of 'opening' or
 	/// 'closing' the device - serial devices are always open. If the return
 	/// value is `Ok(n)`, the value `n` may be less than the size of the given
 	/// buffer. If so, that means not all of the data could be transmitted -
 	/// only the first `n` bytes were.
 	pub serial_write: extern "C" fn(
-		device: u8,
+		device_id: u8,
 		data: ApiByteSlice,
 		timeout: crate::Option<Timeout>,
 	) -> crate::Result<usize>,
@@ -110,7 +110,7 @@ pub struct Api {
 	/// could be received - only the first `n` bytes were (and hence only the
 	/// first `n` bytes of the given buffer now contain data).
 	pub serial_read: extern "C" fn(
-		device: u8,
+		device_id: u8,
 		data: ApiBuffer,
 		timeout: crate::Option<Timeout>,
 	) -> crate::Result<usize>,
@@ -320,7 +320,7 @@ pub struct Api {
 	///
 	/// I²C Bus 0 should be the one connected to the Neotron Bus.
 	/// I²C Bus 1 is typically the VGA DDC bus.
-	pub i2c_bus_get_info: extern "C" fn(i2c_bus: u8) -> crate::Option<i2c::BusInfo>,
+	pub i2c_bus_get_info: extern "C" fn(bus_id: u8) -> crate::Option<i2c::BusInfo>,
 	/// Transact with a I²C Device on an I²C Bus
 	///
 	/// * `i2c_bus` - Which I²C Bus to use
@@ -341,7 +341,7 @@ pub struct Api {
 	/// # Ok::<(), neotron_common_bios::Error>(())
 	/// ```
 	pub i2c_write_read: extern "C" fn(
-		i2c_bus: u8,
+		bus_id: u8,
 		i2c_device_address: u8,
 		tx: ApiByteSlice,
 		tx2: ApiByteSlice,
@@ -353,7 +353,7 @@ pub struct Api {
 	// ========================================================================
 	/// Get information about the Audio Mixer channels
 	pub audio_mixer_channel_get_info:
-		extern "C" fn(audio_mixer_id: u8) -> crate::Result<audio::MixerChannelInfo>,
+		extern "C" fn(audio_mixer_id: u8) -> crate::Option<audio::MixerChannelInfo>,
 	/// Set an Audio Mixer level
 	pub audio_mixer_channel_set_level:
 		extern "C" fn(audio_mixer_id: u8, level: u8) -> crate::Result<()>,
@@ -530,12 +530,12 @@ pub struct Api {
 	/// 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>,
+	pub block_dev_get_info: extern "C" fn(device_id: 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<()>,
+	pub block_dev_eject: extern "C" fn(device_id: u8) -> crate::Result<()>,
 	/// Write one or more sectors to a block device.
 	///
 	/// The function will block until all data is written. The array pointed
@@ -545,7 +545,7 @@ pub struct Api {
 	/// 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,
+		device_id: u8,
 		start_block: block_dev::BlockIdx,
 		num_blocks: u8,
 		data: ApiByteSlice,
@@ -559,7 +559,7 @@ pub struct Api {
 	/// 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,
+		device_id: u8,
 		start_block: block_dev::BlockIdx,
 		num_blocks: u8,
 		data: ApiBuffer,
@@ -574,7 +574,7 @@ pub struct Api {
 	/// 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,
+		device_id: u8,
 		start_block: block_dev::BlockIdx,
 		num_blocks: u8,
 		data: ApiByteSlice,