sentry_uapi/
lib.rs

1// SPDX-FileCopyrightText: 2023 Ledger SAS
2// SPDX-License-Identifier: Apache-2.0
3
4//! [![github]](https://github.com/outpost-os/sentry-kernel)&ensp;
5//!
6//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
7//!
8//! <br>
9//!
10//! sentry_uapi is the user API library that delivers a full access to the Sentry kernel
11//! interface.
12//! This crate aim to be used by any Outpost-OS Rust application.
13//!
14//! -**Data types** — Sentry_uapi provices a complete set of data types and
15//!  values that are required in order to properly exchange informations with the Sentry kernel.
16//!  All the data types are stored in the [`mod@systypes`] public module.
17//!
18//! -**Sentry syscalls** — Syscall are defined in a two layers way. The bare syscalls
19//!  are implemented in the [`mod@syscall`] module, while the upper, easy interface
20//!  is out of the scope of this very crate, and written in the shield crate instead.
21
22#![cfg_attr(not(feature = "std"), no_std)]
23
24#[macro_use]
25mod arch;
26
27/// Sentry UAPI C export interface module
28///
29/// # Usage
30///
31/// This module should not be used in a full Rust application, while this is the lonely
32/// accessible interface in C.
33/// This allows a full Rust usage without extern C and thus unsafe calls when
34/// writing Rust application with cargo
35/// interface is used. Sentry kernel interactions should be, instead, made with
36/// a upper interface such as shield.
37///
38pub mod ffi_c;
39
40/// Sentry kernel exchange area manipulation primitives
41///
42/// # Usage
43///
44/// This module should not be used directly unless the [`mod@syscall`] module
45/// interface is used. Sentry kernel interactions should be, instead, made with
46/// an upper interface.
47///
48/// As the exchange area is a special userspace/kernelspace fixed size area
49/// made in order to exchange data between userspace and kernelspace without
50/// manipulating any pointer, this space has a particular meaning and usage, holding
51/// any type of content as a 'retention area' before and after system calls.
52/// This area is exclusive to the current job.
53///
54/// # About unsafe in this module
55///
56/// This module needs to interact with a single, static mutable area where both
57/// kernel and job exchange data. As such, Rust consider any manipulation of this
58/// area as unsafe due to potential multiple references to a static mutable space.
59///
60/// As Sentry kernel ensures that any job being executed has a single thread, no
61/// race condition can happen due to the overall system design. As a consequence, even
62/// if unsafe is used, there is no UB risk when manipulating the exchange area
63/// based on the Operating System architecture.
64///
65mod exchange;
66
67/// Sentry kernel low level syscall implementation
68///
69/// # Usage
70///
71/// This module is responsible for calling the kernel gate through the target
72/// architecture supervisor access opcode, in interaction with the corresponding
73/// arch backend.
74///
75/// There is no abstraction at this module's level and should not be used directly,
76/// but instead with an upper interface such as shield
77///
78/// > **NOTE**: This module may not be kept public forever
79///
80pub mod syscall;
81
82/// Sentry kernelspace/userspace shared types and values
83///
84/// # Usage
85///
86/// This module holds all the Sentry kernel types and values required by all other modules
87/// but also types that need to be used by upper layers in order to properly manipulate
88/// Sentry's syscalls.
89///
90/// This module do not hold any function nor macro, but only all scalar and non-scalar
91/// types for userspace/Sentry-kernel exchanges.
92///
93/// Some types are snake case based because of the C export. None the less,
94/// they will be moved to standard Rust Caml case to stay conform to the
95/// Rust guildelines
96///
97/// > **Note**: there is no bindgen nor cbindgen call in order to ensure FFI
98/// > interface with the C language, to avoid any inter-languages naming and
99/// > complexity (macros cases, static inline case and so on), meaning that
100/// > the corresponding C types are defined in a dedicated include dir
101///
102pub mod systypes;
103
104/// Copy a given generic type from the kernel exchange zone to the given mutable reference
105pub use self::exchange::copy_from_kernel;
106
107/// Copy a given generic type to the kernel exchange zone from the given eference
108pub use self::exchange::copy_to_kernel;
109
110/// Sentry exchangeable opaque trait, only defined for systypes defined types
111///
112/// This trait is declared in order to allow the attribute checking but is not
113/// exported as no upper layer type needs to implement it
114pub use self::exchange::SentryExchangeable;
115
116#[cfg(not(feature = "std"))]
117mod panic;
sentry_uapi/lib.rs

sentry_uapi/
lib.rs
