j/Chirp
1
1
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

docs: Fix examples (now passes all doc tests again)

Browse Source
This commit is contained in:
John 2023-08-31 22:39:14 -05:00
parent 31c904f89c
commit 8de4f42ff6
4 changed files with 29 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/cpu.rs
View File

@ -399,9 +399,7 @@ impl CPU {
/// ```rust /// ```rust
/// # use chirp::*; /// # use chirp::*;
/// let mut cpu = CPU::default(); /// let mut cpu = CPU::default();
/// let mut screen = mem!{ /// let mut screen = Screen::default();
/// Screen [0x000..0x100],
/// };
/// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]); /// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]);
/// cpu.singlestep(&mut screen).unwrap(); /// cpu.singlestep(&mut screen).unwrap();
/// assert_eq!(0x202, cpu.pc()); /// assert_eq!(0x202, cpu.pc());
@ -422,9 +420,7 @@ impl CPU {
/// ```rust /// ```rust
/// # use chirp::*; /// # use chirp::*;
/// let mut cpu = CPU::default(); /// let mut cpu = CPU::default();
/// let mut screen = mem!{ /// let mut screen = Screen::default();
/// Screen [0x000..0x100],
/// };
/// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]); /// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]);
/// cpu.multistep(&mut screen, 0x20) /// cpu.multistep(&mut screen, 0x20)
/// .expect("The program should only have valid opcodes."); /// .expect("The program should only have valid opcodes.");
@ -453,11 +449,9 @@ impl CPU {
/// ```rust /// ```rust
/// # use chirp::*; /// # use chirp::*;
/// let mut cpu = CPU::default(); /// let mut cpu = CPU::default();
/// let mut bus = mem!{ /// let mut screen = Screen::default();
/// Screen [0x000..0x100],
/// };
/// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]); /// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]);
/// cpu.tick(&mut bus) /// cpu.tick(&mut screen)
/// .expect("0x00e0 (cls) should be a valid opcode."); /// .expect("0x00e0 (cls) should be a valid opcode.");
/// assert_eq!(0x202, cpu.pc()); /// assert_eq!(0x202, cpu.pc());
/// assert_eq!(1, cpu.cycle()); /// assert_eq!(1, cpu.cycle());
@ -470,9 +464,7 @@ impl CPU {
/// let mut cpu = CPU::default(); /// let mut cpu = CPU::default();
/// # cpu.flags.debug = true; // enable live disassembly /// # cpu.flags.debug = true; // enable live disassembly
/// # cpu.flags.monotonic = true; // enable monotonic/test timing /// # cpu.flags.monotonic = true; // enable monotonic/test timing
/// let mut bus = mem!{ /// let mut bus = Screen::default();
/// Screen [0x0f00..0x1000],
/// };
/// cpu.load_program_bytes(&[ /// cpu.load_program_bytes(&[
/// 0xff, 0xff, // invalid! /// 0xff, 0xff, // invalid!
/// 0x22, 0x02, // jump 0x202 /// 0x22, 0x02, // jump 0x202

32
src/cpu/mem.rs
View File

@ -15,7 +15,7 @@ use std::{
/// Creates a new [Mem], growing as needed /// Creates a new [Mem], growing as needed
/// # Examples /// # Examples
/// ```rust /// ```rust
/// # use chirp::*; /// use chirp::{cpu::mem::Region::*, *};
/// let mut mem = mem! { /// let mut mem = mem! {
/// Charset [0x0000..0x0800] = b"ABCDEF", /// Charset [0x0000..0x0800] = b"ABCDEF",
/// Program [0x0800..0xf000] = include_bytes!("mem.rs"), /// Program [0x0800..0xf000] = include_bytes!("mem.rs"),
@ -33,7 +33,7 @@ impl Grab for Mem {
/// Gets a slice of [Mem] memory /// Gets a slice of [Mem] memory
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new() /// let mem = Mem::new()
/// .add_region_owned(Program, 0..10); /// .add_region_owned(Program, 0..10);
@ -52,7 +52,7 @@ impl Grab for Mem {
/// Gets a mutable slice of [Mem] memory /// Gets a mutable slice of [Mem] memory
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mut mem = Mem::new() /// let mut mem = Mem::new()
/// .add_region_owned(Program, 0..10); /// .add_region_owned(Program, 0..10);
@ -112,7 +112,7 @@ impl Mem {
/// Constructs a new mem /// Constructs a new mem
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new(); /// let mem = Mem::new();
/// assert!(mem.is_empty()); /// assert!(mem.is_empty());
@ -126,7 +126,7 @@ impl Mem {
/// Gets the length of the mem' backing memory /// Gets the length of the mem' backing memory
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new() /// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234); /// .add_region_owned(Program, 0..1234);
@ -141,7 +141,7 @@ impl Mem {
/// Returns true if the backing memory contains no elements /// Returns true if the backing memory contains no elements
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new(); /// let mem = Mem::new();
/// assert!(mem.is_empty()); /// assert!(mem.is_empty());
@ -155,7 +155,7 @@ impl Mem {
/// Grows the Mem backing memory to at least size bytes, but does not truncate /// Grows the Mem backing memory to at least size bytes, but does not truncate
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mut mem = Mem::new(); /// let mut mem = Mem::new();
/// mem.with_size(1234); /// mem.with_size(1234);
@ -165,7 +165,7 @@ impl Mem {
///# Ok(()) ///# Ok(())
///# } ///# }
/// ``` /// ```
fn with_size(&mut self, size: usize) { pub fn with_size(&mut self, size: usize) {
if self.len() < size { if self.len() < size {
self.memory.resize(size, 0); self.memory.resize(size, 0);
} }
@ -180,7 +180,7 @@ impl Mem {
/// Adds a new named range ([Region]) to a [Mem] /// Adds a new named range ([Region]) to a [Mem]
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mut mem = Mem::new(); /// let mut mem = Mem::new();
/// mem.add_region(Program, 0..1234); /// mem.add_region(Program, 0..1234);
@ -199,7 +199,7 @@ impl Mem {
/// Updates an existing [Region] /// Updates an existing [Region]
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mut mem = Mem::new().add_region_owned(Program, 0..1234); /// let mut mem = Mem::new().add_region_owned(Program, 0..1234);
/// mem.set_region(Program, 1234..2345); /// mem.set_region(Program, 1234..2345);
@ -224,7 +224,7 @@ impl Mem {
/// Loads data into a named [Region] /// Loads data into a named [Region]
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new() /// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234) /// .add_region_owned(Program, 0..1234)
@ -244,7 +244,7 @@ impl Mem {
/// Fills a [Region] with zeroes /// Fills a [Region] with zeroes
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new() /// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234) /// .add_region_owned(Program, 0..1234)
@ -255,11 +255,11 @@ impl Mem {
/// ``` /// ```
/// If the region doesn't exist, that's okay. /// If the region doesn't exist, that's okay.
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new() /// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234) /// .add_region_owned(Program, 0..1234)
/// .clear_region(Screen); /// .clear_region(Program);
///# // TODO: test if region actually clear ///# // TODO: test if region actually clear
///# Ok(()) ///# Ok(())
///# } ///# }
@ -274,7 +274,7 @@ impl Mem {
/// Gets a slice of a named [Region] of memory /// Gets a slice of a named [Region] of memory
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mem = Mem::new() /// let mem = Mem::new()
/// .add_region_owned(Program, 0..10); /// .add_region_owned(Program, 0..10);
@ -291,7 +291,7 @@ impl Mem {
/// Gets a mutable slice of a named region of memory /// Gets a mutable slice of a named region of memory
/// # Examples /// # Examples
/// ```rust /// ```rust
///# use chirp::*; /// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> { ///# fn main() -> Result<()> {
/// let mut mem = Mem::new() /// let mut mem = Mem::new()
/// .add_region_owned(Program, 0..10); /// .add_region_owned(Program, 0..10);

4
src/screen.rs
View File

@ -72,9 +72,9 @@ impl Screen {
/// ```rust /// ```rust
///# use chirp::screen::Screen; ///# use chirp::screen::Screen;
/// let mut screen = Screen::new(256); /// let mut screen = Screen::new(256);
/// assert_eq!(1234, screen.len()); /// assert_eq!(256, screen.len());
/// screen.with_size(0); /// screen.with_size(0);
/// assert_eq!(1234, screen.len()); /// assert_eq!(256, screen.len());
/// ``` /// ```
pub fn with_size(&mut self, size: usize) { pub fn with_size(&mut self, size: usize) {
if self.len() < size { if self.len() < size {

12
src/traits/auto_cast.rs
View File

@ -31,11 +31,11 @@ pub trait AutoCast<T>: FallibleAutoCast<T> {
/// ///
/// # May Panic /// # May Panic
/// ///
/// If the type is not [Default], this will panic on error. /// This will panic on error. For a non-panicking implementation, do it yourself.
fn read(&self, addr: impl Into<usize>) -> T { fn read(&self, addr: impl Into<usize>) -> T {
self.read_fallible(addr).unwrap_or_else(|e| panic!("{e:?}")) self.read_fallible(addr).unwrap_or_else(|e| panic!("{e:?}"))
} }
/// Write a T to address `addr` /// Writes a T to address `addr`
/// ///
/// # Will Panic /// # Will Panic
/// ///
@ -63,7 +63,7 @@ pub trait FallibleAutoCast<T>: Grab {
/// - `Self::to_be_bytes` /// - `Self::to_be_bytes`
macro_rules! impl_rw {($($t:ty) ,* $(,)?) =>{ macro_rules! impl_rw {($($t:ty) ,* $(,)?) =>{
$( $(
#[doc = concat!("Read or Write [", stringify!($t), "] at address `addr`, *discarding errors*.\n\nThis will never panic.")] #[doc = concat!("Read or Write [`", stringify!($t), "`] at address `addr`, *discarding errors*.\n\nThis will never panic.")]
impl<T: Grab + FallibleAutoCast<$t>> AutoCast<$t> for T { impl<T: Grab + FallibleAutoCast<$t>> AutoCast<$t> for T {
#[inline(always)] #[inline(always)]
fn read(&self, addr: impl Into<usize>) -> $t { fn read(&self, addr: impl Into<usize>) -> $t {
@ -79,12 +79,12 @@ macro_rules! impl_rw {($($t:ty) ,* $(,)?) =>{
#[inline(always)] #[inline(always)]
fn read_fallible(&self, addr: impl Into<usize>) -> $crate::error::Result<$t> { fn read_fallible(&self, addr: impl Into<usize>) -> $crate::error::Result<$t> {
let addr: usize = addr.into(); let addr: usize = addr.into();
let range = addr..addr + core::mem::size_of::<$t>(); let top = addr + core::mem::size_of::<$t>();
if let Some(bytes) = self.grab(range.clone()) { if let Some(bytes) = self.grab(addr..top) {
// Chip-8 is a big-endian system // Chip-8 is a big-endian system
Ok(<$t>::from_be_bytes(bytes.try_into()?)) Ok(<$t>::from_be_bytes(bytes.try_into()?))
} else { } else {
Err($crate::error::Error::InvalidAddressRange{range: range.into()}) Err($crate::error::Error::InvalidAddressRange{range: (addr..top).into()})
} }
} }
#[inline(always)] #[inline(always)]