ymfm-sys 0.2.0

Rust bindings to the ymfm FM sound chip emulation library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

use std::cell::RefCell;

use crate::ffi;

pub type ReadDataHandler = Box<dyn Fn(ffi::AccessClass, u32, u32) -> Vec<u8>>;
pub type WriteDataHandler = Box<dyn FnMut(ffi::AccessClass, u32, &[u8])>;
pub type ExternalWriteHandler = Box<dyn FnMut(ffi::AccessClass, u32, u8)>;

/// User-provided ymfm interface handlers. Each callback is optional; omitted
/// callbacks use the corresponding no-op/default behavior.
#[derive(Default)]
pub struct InterfaceHandler {
    pub advance_clock: Option<Box<dyn FnMut(i64) -> u8>>,
    pub read_data: Option<ReadDataHandler>,
    pub write_data: Option<WriteDataHandler>,
    pub ymfm_external_read: Option<Box<dyn FnMut(ffi::AccessClass, u32) -> u8>>,
    pub ymfm_external_write: Option<ExternalWriteHandler>,
    pub ymfm_is_busy: Option<Box<dyn Fn() -> bool>>,
    pub ymfm_set_busy_end: Option<Box<dyn FnMut(u32)>>,
    pub ymfm_set_timer: Option<Box<dyn FnMut(u32, i32)>>,
    pub ymfm_update_irq: Option<Box<dyn FnMut(bool)>>,
}

/// Opaque callback adapter owned by the native chip instance.
pub struct InterfaceCallbacks {
    handler: RefCell<InterfaceHandler>,
}

impl InterfaceCallbacks {
    /// Create a callback adapter containing the supplied host handlers.
    pub fn new(handler: InterfaceHandler) -> Self {
        Self {
            handler: RefCell::new(handler),
        }
    }
}

/// Create an adapter whose callbacks all use their default behavior.
pub(crate) fn default_callbacks() -> Box<InterfaceCallbacks> {
    Box::new(InterfaceCallbacks::new(InterfaceHandler::default()))
}

/// Forward ymfm's IRQ state change to the host callback, if configured.
pub(crate) fn ymfm_update_irq(callbacks: &InterfaceCallbacks, asserted: bool) {
    if let Some(handler) = callbacks.handler.borrow_mut().ymfm_update_irq.as_mut() {
        handler(asserted);
    }
}

/// Advance host-side time and return the timer-expiry bit mask from the callback.
/// Returns `0` when no callback is configured.
pub(crate) fn advance_clock(callbacks: &InterfaceCallbacks, clocks: i64) -> u8 {
    callbacks
        .handler
        .borrow_mut()
        .advance_clock
        .as_mut()
        .map_or(0, |handler| handler(clocks))
}

/// Forward ymfm's BUSY deadline to the host callback, if configured.
pub(crate) fn ymfm_set_busy_end(callbacks: &InterfaceCallbacks, clocks: u32) {
    if let Some(handler) = callbacks.handler.borrow_mut().ymfm_set_busy_end.as_mut() {
        handler(clocks);
    }
}

/// Ask the host whether the emulated device is BUSY.
/// Returns `false` when no callback is configured.
pub(crate) fn ymfm_is_busy(callbacks: &InterfaceCallbacks) -> bool {
    callbacks
        .handler
        .borrow()
        .ymfm_is_busy
        .as_ref()
        .is_some_and(|handler| handler())
}

/// Forward a timer number and duration to the host callback, if configured.
pub(crate) fn ymfm_set_timer(callbacks: &InterfaceCallbacks, tnum: u32, duration_in_clocks: i32) {
    if let Some(handler) = callbacks.handler.borrow_mut().ymfm_set_timer.as_mut() {
        handler(tnum, duration_in_clocks);
    }
}

/// Read one byte from ymfm's external memory or I/O interface.
/// Returns `0` when no callback is configured.
pub(crate) fn ymfm_external_read(
    callbacks: &InterfaceCallbacks,
    access: ffi::AccessClass,
    offset: u32,
) -> u8 {
    callbacks
        .handler
        .borrow_mut()
        .ymfm_external_read
        .as_mut()
        .map_or(0, |handler| handler(access, offset))
}

/// Read a block from host-managed external data.
/// Returns zero-filled data when no callback is configured.
pub(crate) fn read_data(
    callbacks: &InterfaceCallbacks,
    access: ffi::AccessClass,
    base: u32,
    length: u32,
) -> Vec<u8> {
    callbacks.handler.borrow().read_data.as_ref().map_or_else(
        || vec![0; length as usize],
        |handler| handler(access, base, length),
    )
}

/// Forward one byte written through ymfm's external memory or I/O interface.
pub(crate) fn ymfm_external_write(
    callbacks: &InterfaceCallbacks,
    access: ffi::AccessClass,
    offset: u32,
    data: u8,
) {
    if let Some(handler) = callbacks.handler.borrow_mut().ymfm_external_write.as_mut() {
        handler(access, offset, data);
    }
}

/// Forward a block write to host-managed external data, if configured.
pub(crate) fn write_data(
    callbacks: &InterfaceCallbacks,
    access: ffi::AccessClass,
    base: u32,
    data: &[u8],
) {
    if let Some(handler) = callbacks.handler.borrow_mut().write_data.as_mut() {
        handler(access, base, data);
    }
}