mirror of
https://github.com/saymrwulf/xous-core.git
synced 2026-11-16 08:38:26 +00:00
re-organize code so that the APIs are up top
This commit is contained in:
parent
f9e17f7a63
commit
f1b9212b75
1 changed files with 118 additions and 118 deletions
|
|
@ -53,6 +53,124 @@ use xous::MemoryRange;
|
|||
|
||||
pub const BIO_SERVER_NAME: &'static str = "_BIO server_";
|
||||
|
||||
/// A platform-neutral API for the BIO. Intended to be usable in both baremetal and `std` environments
|
||||
pub trait BioApi<'a> {
|
||||
/// Initializes a core with the given `code`, loading into `offset`, with a given
|
||||
/// core configuration. This does not start the core running: that needs to be
|
||||
/// done with a separate `set_core_state` call.
|
||||
///
|
||||
/// Returns a `u32` which is the frequency in Hz of the actual quantum interval that
|
||||
/// the core is running at. It's `None` if an external pin is configured as the quantum source.
|
||||
fn init_core(
|
||||
&mut self,
|
||||
core: BioCore,
|
||||
code: &[u8],
|
||||
offset: usize,
|
||||
config: CoreConfig,
|
||||
) -> Result<Option<u32>, BioError>;
|
||||
|
||||
/// Releases the core. As a side effect, the core is stopped.
|
||||
fn de_init_core(&mut self, core: BioCore) -> Result<(), BioError>;
|
||||
|
||||
/// Updates the frequency of the cores, used to calculate dividers etc.
|
||||
/// Returns the previous frequency used by the system. Setting this
|
||||
/// allows the sleep/wake clock manager to do a best-effort rescaling of the
|
||||
/// clock dividers for each core as DVFS is applied for power savings.
|
||||
///
|
||||
/// This API call does not actually *set* the frequency of the BIO complex -
|
||||
/// that is handled by the clock manager. This merely informs the BIO driver
|
||||
/// that the clocks may have changed.
|
||||
fn update_bio_freq(&mut self, freq: u32) -> u32;
|
||||
|
||||
/// Returns the frequency, in Hz, of the incoming clock to the BIO cores.
|
||||
fn get_bio_freq(&self) -> u32;
|
||||
|
||||
/// Returns the currently running frequency of a given BIO core. This API
|
||||
/// exists because `update_bio_freq()` call will result in the dividers being
|
||||
/// adjusted in an attempt to maintain the target quantum; however, there will
|
||||
/// often be some error between what was requested and the actual achievable
|
||||
/// frequency of the quantum interval.
|
||||
fn get_core_freq(&self, core: BioCore) -> Option<u32>;
|
||||
|
||||
/// The index of `which` corresponds to each of the cores, 0-3.
|
||||
fn set_core_state(&mut self, which: [CoreRunSetting; 4]) -> Result<(), BioError>;
|
||||
|
||||
/// Returns a `usize` which should be turned into a CSR as *mut u32 by the caller
|
||||
/// this can then be dereferenced using UTRA abstractions to access the following
|
||||
/// registers:
|
||||
/// - SFR_FLEVEL
|
||||
/// - SFR_TXF#
|
||||
/// - SFR_RXF#
|
||||
/// - SFR_EVENT_SET
|
||||
/// - SFR_EVENT_CLR
|
||||
/// - SFR_EVENT_STATUS
|
||||
///
|
||||
/// The handle can only access one of the FIFOs, but it has access to all the other
|
||||
/// registers regardless of the FIFO.
|
||||
///
|
||||
/// The handle has a `Drop` implementation that releases it when it goes out of scope.
|
||||
///
|
||||
/// Safety: this has to be wrapped in an object that derives a CSR that also tracks
|
||||
/// the lifetime of this object, to prevent `Drop` from being called at the wrong time.
|
||||
///
|
||||
/// Returns `None` if no more handles are available
|
||||
unsafe fn get_core_handle(&self, fifo: Fifo) -> Result<Option<CoreHandle>, BioError>;
|
||||
|
||||
/// This call sets up the BIO's IRQ routing. It doesn't actually claim the IRQ
|
||||
/// or install the handler - that's up to the caller to do with Xous API calls.
|
||||
fn setup_irq_config(&mut self, config: IrqConfig) -> Result<(), BioError>;
|
||||
|
||||
/// Allows BIO cores to DMA to/from the windows specified in `windows`. DMA filtering is
|
||||
/// on by default with no windows allowed.
|
||||
fn setup_dma_windows(&mut self, windows: DmaFilterWindows) -> Result<(), BioError>;
|
||||
|
||||
/// Sets up the BIO I/O configuration
|
||||
fn setup_io_config(&mut self, config: IoConfig) -> Result<(), BioError>;
|
||||
|
||||
/// Sets up a FIFO event trigger
|
||||
fn setup_fifo_event_triggers(&mut self, config: FifoEventConfig) -> Result<(), BioError>;
|
||||
|
||||
/// Returns a version code for the underlying hardware.
|
||||
fn get_version(&self) -> u32;
|
||||
}
|
||||
|
||||
#[macro_export]
|
||||
/// This macro takes three identifiers and assembly code:
|
||||
/// - name of the function to call to retrieve the assembled code
|
||||
/// - a unique identifier that serves as label name for the start of the code
|
||||
/// - a unique identifier that serves as label name for the end of the code
|
||||
/// - a comma separated list of strings that form the assembly itself
|
||||
///
|
||||
/// *** The comma separated list must *not* end in a comma. ***
|
||||
///
|
||||
/// The macro is unable to derive names of functions or identifiers for labels
|
||||
/// due to the partially hygienic macro rules of Rust, so you have to come
|
||||
/// up with a list of unique names by yourself.
|
||||
macro_rules! bio_code {
|
||||
($fn_name:ident, $name_start:ident, $name_end:ident, $($item:expr),*) => {
|
||||
pub fn $fn_name() -> &'static [u8] {
|
||||
extern "C" {
|
||||
static $name_start: *const u8;
|
||||
static $name_end: *const u8;
|
||||
}
|
||||
// skip the first 4 bytes, as they contain the loading offset
|
||||
unsafe { core::slice::from_raw_parts($name_start.add(4), ($name_end as usize) - ($name_start as usize) - 4)}
|
||||
}
|
||||
|
||||
core::arch::global_asm!(
|
||||
".align 4",
|
||||
concat!(".globl ", stringify!($name_start)),
|
||||
concat!(stringify!($name_start), ":"),
|
||||
".word .",
|
||||
$($item),*
|
||||
, ".align 4",
|
||||
concat!(".globl ", stringify!($name_end)),
|
||||
concat!(stringify!($name_end), ":"),
|
||||
".word .",
|
||||
);
|
||||
};
|
||||
}
|
||||
|
||||
#[derive(Debug, Copy, Clone, num_derive::FromPrimitive, num_derive::ToPrimitive)]
|
||||
pub enum BioOp {
|
||||
InitCore,
|
||||
|
|
@ -397,121 +515,3 @@ impl Drop for CoreHandle {
|
|||
.unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
/// A platform-neutral API for the BIO. Intended to be usable in both baremetal and `std` environments
|
||||
pub trait BioApi<'a> {
|
||||
/// Initializes a core with the given `code`, loading into `offset`, with a given
|
||||
/// core configuration. This does not start the core running: that needs to be
|
||||
/// done with a separate `set_core_state` call.
|
||||
///
|
||||
/// Returns a `u32` which is the frequency in Hz of the actual quantum interval that
|
||||
/// the core is running at. It's `None` if an external pin is configured as the quantum source.
|
||||
fn init_core(
|
||||
&mut self,
|
||||
core: BioCore,
|
||||
code: &[u8],
|
||||
offset: usize,
|
||||
config: CoreConfig,
|
||||
) -> Result<Option<u32>, BioError>;
|
||||
|
||||
/// Releases the core. As a side effect, the core is stopped.
|
||||
fn de_init_core(&mut self, core: BioCore) -> Result<(), BioError>;
|
||||
|
||||
/// Updates the frequency of the cores, used to calculate dividers etc.
|
||||
/// Returns the previous frequency used by the system. Setting this
|
||||
/// allows the sleep/wake clock manager to do a best-effort rescaling of the
|
||||
/// clock dividers for each core as DVFS is applied for power savings.
|
||||
///
|
||||
/// This API call does not actually *set* the frequency of the BIO complex -
|
||||
/// that is handled by the clock manager. This merely informs the BIO driver
|
||||
/// that the clocks may have changed.
|
||||
fn update_bio_freq(&mut self, freq: u32) -> u32;
|
||||
|
||||
/// Returns the frequency, in Hz, of the incoming clock to the BIO cores.
|
||||
fn get_bio_freq(&self) -> u32;
|
||||
|
||||
/// Returns the currently running frequency of a given BIO core. This API
|
||||
/// exists because `update_bio_freq()` call will result in the dividers being
|
||||
/// adjusted in an attempt to maintain the target quantum; however, there will
|
||||
/// often be some error between what was requested and the actual achievable
|
||||
/// frequency of the quantum interval.
|
||||
fn get_core_freq(&self, core: BioCore) -> Option<u32>;
|
||||
|
||||
/// The index of `which` corresponds to each of the cores, 0-3.
|
||||
fn set_core_state(&mut self, which: [CoreRunSetting; 4]) -> Result<(), BioError>;
|
||||
|
||||
/// Returns a `usize` which should be turned into a CSR as *mut u32 by the caller
|
||||
/// this can then be dereferenced using UTRA abstractions to access the following
|
||||
/// registers:
|
||||
/// - SFR_FLEVEL
|
||||
/// - SFR_TXF#
|
||||
/// - SFR_RXF#
|
||||
/// - SFR_EVENT_SET
|
||||
/// - SFR_EVENT_CLR
|
||||
/// - SFR_EVENT_STATUS
|
||||
///
|
||||
/// The handle can only access one of the FIFOs, but it has access to all the other
|
||||
/// registers regardless of the FIFO.
|
||||
///
|
||||
/// The handle has a `Drop` implementation that releases it when it goes out of scope.
|
||||
///
|
||||
/// Safety: this has to be wrapped in an object that derives a CSR that also tracks
|
||||
/// the lifetime of this object, to prevent `Drop` from being called at the wrong time.
|
||||
///
|
||||
/// Returns `None` if no more handles are available
|
||||
unsafe fn get_core_handle(&self, fifo: Fifo) -> Result<Option<CoreHandle>, BioError>;
|
||||
|
||||
/// This call sets up the BIO's IRQ routing. It doesn't actually claim the IRQ
|
||||
/// or install the handler - that's up to the caller to do with Xous API calls.
|
||||
fn setup_irq_config(&mut self, config: IrqConfig) -> Result<(), BioError>;
|
||||
|
||||
/// Allows BIO cores to DMA to/from the windows specified in `windows`. DMA filtering is
|
||||
/// on by default with no windows allowed.
|
||||
fn setup_dma_windows(&mut self, windows: DmaFilterWindows) -> Result<(), BioError>;
|
||||
|
||||
/// Sets up the BIO I/O configuration
|
||||
fn setup_io_config(&mut self, config: IoConfig) -> Result<(), BioError>;
|
||||
|
||||
/// Sets up a FIFO event trigger
|
||||
fn setup_fifo_event_triggers(&mut self, config: FifoEventConfig) -> Result<(), BioError>;
|
||||
|
||||
/// Returns a version code for the underlying hardware.
|
||||
fn get_version(&self) -> u32;
|
||||
}
|
||||
|
||||
#[macro_export]
|
||||
/// This macro takes three identifiers and assembly code:
|
||||
/// - name of the function to call to retrieve the assembled code
|
||||
/// - a unique identifier that serves as label name for the start of the code
|
||||
/// - a unique identifier that serves as label name for the end of the code
|
||||
/// - a comma separated list of strings that form the assembly itself
|
||||
///
|
||||
/// *** The comma separated list must *not* end in a comma. ***
|
||||
///
|
||||
/// The macro is unable to derive names of functions or identifiers for labels
|
||||
/// due to the partially hygienic macro rules of Rust, so you have to come
|
||||
/// up with a list of unique names by yourself.
|
||||
macro_rules! bio_code {
|
||||
($fn_name:ident, $name_start:ident, $name_end:ident, $($item:expr),*) => {
|
||||
pub fn $fn_name() -> &'static [u8] {
|
||||
extern "C" {
|
||||
static $name_start: *const u8;
|
||||
static $name_end: *const u8;
|
||||
}
|
||||
// skip the first 4 bytes, as they contain the loading offset
|
||||
unsafe { core::slice::from_raw_parts($name_start.add(4), ($name_end as usize) - ($name_start as usize) - 4)}
|
||||
}
|
||||
|
||||
core::arch::global_asm!(
|
||||
".align 4",
|
||||
concat!(".globl ", stringify!($name_start)),
|
||||
concat!(stringify!($name_start), ":"),
|
||||
".word .",
|
||||
$($item),*
|
||||
, ".align 4",
|
||||
concat!(".globl ", stringify!($name_end)),
|
||||
concat!(stringify!($name_end), ":"),
|
||||
".word .",
|
||||
);
|
||||
};
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue