acpica_bindings/lib.rs
1//! # ACPICA bindings
2//! Incomplete rust bindings to Intel's ACPICA kernel subsystem. This crate is very much still under development - I am adding features as they are needed by [my OS project].
3//! If you are using this crate, expect lots of compiler warnings and `todo!`s.
4//!
5//! ## Build Dependencies
6//! This crate builds ACPICA from source, using the [`cc`] crate. This crate requires the presence of a C compiler on the system -
7//! see that crate's documentation for more information.
8//!
9//! The crate also uses unstable rust features, so needs a nightly or beta compiler.
10//!
11//! ## Runtime Dependencies
12//! As the crate is designed to be used in an OS kernel, it has minimal dependencies. The crate does require dynamic memory allocation, however.
13//!
14//! The crate also uses the [`log`] crate for logging.
15//!
16//! ## Usage
17//! The ACPICA kernel subsystem calls into OS code using various functions prefixed with `AcpiOs`. These are translated by this library into calls to methods on the `AcpiHandler` trait. An object implementing this trait must be passed to `register_handler` before any ACPI functionality can be used. Initializing the library could look like this:
18//!
19//! ```rust, ignore
20//! struct HandlerStruct {}
21//!
22//! impl AcpiHandler for HandlerStruct {
23//! // ...
24//! }
25//!
26//! let handler = HandlerStruct {};
27//!
28//! let initialization = register_interface(handler)?;
29//! let initialization = initialization.load_tables()?;
30//! let initialization = initialization.enable_subsystem()?;
31//! let initialization = initialization.initialize_objects()?;
32//! ```
33//!
34//! [my OS project]: https://github.com/MarkRoss470/rust-os
35//! [`cc`]: https://crates.io/crates/cc
36
37#![no_std]
38#![feature(c_variadic)]
39#![feature(pointer_byte_offsets)]
40// Safety best practises
41#![warn(unsafe_op_in_unsafe_fn, clippy::undocumented_unsafe_blocks)]
42#![deny(unsafe_op_in_unsafe_fn, clippy::undocumented_unsafe_blocks)]
43#![deny(clippy::missing_safety_doc)]
44// Public API best practises
45#![deny(
46 missing_debug_implementations,
47 missing_docs,
48 clippy::missing_safety_doc,
49 clippy::missing_panics_doc
50)]
51// Correctness lints
52#![warn(clippy::all, clippy::correctness)]
53// FFI correctness
54#![deny(improper_ctypes, improper_ctypes_definitions)]
55// Pedantic lints
56#![warn(clippy::pedantic)]
57#![allow(clippy::missing_errors_doc, clippy::module_name_repetitions)]
58
59extern crate alloc;
60
61mod bindings;
62mod interface;
63#[cfg(test)]
64pub(crate) mod testing;
65
66pub use interface::*;
67
68/// If no code in the crate calls ACPICA functions when compiling tests, cargo will not link the ACPICA library.
69/// This means that some linker errors will go silently unnoticed until the crate is compiled outside of tests.
70/// This test forces ACPICA to be linked to find these errors.
71#[test]
72#[ignore = "This just forces the compiler to actually link in ACPICA"]
73#[allow(unreachable_code)]
74fn force_link() {
75 use crate::bindings::functions::AcpiDisable;
76
77 panic!("This test should not be run,just compiled");
78 // SAFETY: This code is never reached
79 unsafe { AcpiDisable() };
80}