convert workspace to a workspace with a root package

src/lib.rs

@@ -0,0 +1,702 @@
+//! This crate provides a (mostly) safe and ergonomic Rust API for the
+//! [`libcsp` C library](https://github.com/libcsp/libcsp) on top of the
+//! [`libcsp-sys`](https://crates.io/crates/libcsp-sys) crate.
+//!
+//! You can find some more high-level information and examples in the
+//! [main repository](https://egit.irs.uni-stuttgart.de/rust/libcsp-rust).
+#![no_std]
+#[cfg(feature = "alloc")]
+extern crate alloc;
+#[cfg(any(feature = "std", test))]
+extern crate std;
+
+use core::time::Duration;
+
+use num_enum::{IntoPrimitive, TryFromPrimitive};
+
+use bitflags::bitflags;
+use ffi::{csp_conn_s, csp_packet_s, csp_socket_s};
+pub use libcsp_sys as ffi;
+
+#[derive(Debug, PartialEq, Eq, Copy, Clone)]
+pub enum ReservedPort {
+    Cmp = 0,
+    Ping = 1,
+    Ps = 2,
+    Memfree = 3,
+    Reboot = 4,
+    BufFree = 5,
+    Uptime = 6,
+}
+
+#[derive(Debug, PartialEq, Eq, Copy, Clone, TryFromPrimitive, IntoPrimitive)]
+#[repr(i32)]
+pub enum CspError {
+    None = 0,
+    NoMem = -1,
+    Inval = -2,
+    TimedOut = -3,
+    Used = -4,
+    NotSup = -5,
+    Busy = -6,
+    Already = -7,
+    Reset = -8,
+    NoBufs = -9,
+    Tx = -10,
+    Driver = -11,
+    Again = -12,
+    NoSys = -38,
+    Hmac = -100,
+    Crc32 = -102,
+    Sfp = -103,
+}
+
+/// Listen on all ports, primarily used with [csp_bind]
+pub const CSP_ANY: u8 = 255;
+pub const CSP_LOOPBACK: u16 = 0;
+
+bitflags! {
+    pub struct SocketFlags: u32 {
+        const NONE = 0x0000;
+        /// RDP required.
+        const RDPREQ = 0x0001;
+        /// RDP prohibited.
+        const RDPPROHIB = 0x0002;
+        /// HMAC required
+        const HMACREQ = 0x0004;
+        /// HMAC prohibited.
+        const HMACPROHIB = 0x0008;
+        /// CRC32 required.
+        const CRC32REQ = 0x0040;
+        const CRC32PROHIB = 0x0080;
+        const CONN_LESS = 0x0100;
+        /// Copy opts from incoming packets. Only applies to [csp_sendto_reply]
+        const SAME = 0x8000;
+
+        // The source may set any bits
+        const _ = !0;
+    }
+}
+
+bitflags! {
+    pub struct ConnectOpts: u32 {
+        const NONE = SocketFlags::NONE.bits();
+
+        const RDP = SocketFlags::RDPREQ.bits();
+        const NORDP = SocketFlags::RDPPROHIB.bits();
+        const HMAC = SocketFlags::HMACREQ.bits();
+        const NOHMAC = SocketFlags::HMACPROHIB.bits();
+        const CRC32 = SocketFlags::CRC32REQ.bits();
+        const NOCRC32 = SocketFlags::CRC32PROHIB.bits();
+        const SAME = SocketFlags::SAME.bits();
+
+        // The source may set any bits
+        const _ = !0;
+    }
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
+#[repr(u8)]
+pub enum ConnState {
+    Closed = 0,
+    Open = 1,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
+#[repr(u8)]
+pub enum ConnType {
+    Client = 0,
+    Server = 1,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, TryFromPrimitive, IntoPrimitive)]
+#[repr(u32)]
+pub enum RdpState {
+    Closed = 0,
+    SynSent = 1,
+    SynRcvd = 2,
+    Open = 3,
+    CloseWait = 4,
+}
+
+#[derive(Debug, PartialEq, Eq, Copy, Clone, TryFromPrimitive, IntoPrimitive)]
+#[repr(u8)]
+pub enum MsgPriority {
+    Critical = 0,
+    High = 1,
+    Normal = 2,
+    Low = 3,
+}
+
+pub struct CspPacket(pub csp_packet_s);
+
+pub struct CspPacketRef(*mut csp_packet_s);
+
+pub struct CspPacketMut(*mut csp_packet_s);
+
+impl From<CspPacketMut> for CspPacketRef {
+    fn from(value: CspPacketMut) -> Self {
+        Self(value.0)
+    }
+}
+
+impl CspPacketRef {
+    pub fn packet_data(&self) -> &[u8] {
+        unsafe { &(*self.0).packet_data_union.data[..self.packet_length()] }
+    }
+
+    pub fn whole_data(&self) -> &[u8; ffi::CSP_BUFFER_SIZE] {
+        unsafe { &(*self.0).packet_data_union.data }
+    }
+
+    pub fn packet_length(&self) -> usize {
+        unsafe { (*self.0).length.into() }
+    }
+
+    pub fn inner(&self) -> *const csp_packet_s {
+        self.0
+    }
+}
+
+pub struct CspPacketRefGuard(Option<CspPacketRef>);
+
+impl Drop for CspPacketRefGuard {
+    fn drop(&mut self) {
+        if let Some(packet) = self.0.take() {
+            csp_buffer_free(packet)
+        }
+    }
+}
+
+impl CspPacketRefGuard {
+    /// Take the packet out of the guard, preventing it from being freed.
+    pub fn take(mut self) -> CspPacketRef {
+        self.0.take().unwrap()
+    }
+}
+
+impl AsRef<CspPacketRef> for CspPacketRefGuard {
+    fn as_ref(&self) -> &CspPacketRef {
+        self.0.as_ref().unwrap()
+    }
+}
+
+impl CspPacketMut {
+    pub fn packet_data(&self) -> &[u8] {
+        unsafe { &(*self.0).packet_data_union.data[..self.packet_length()] }
+    }
+
+    pub fn whole_data(&self) -> &[u8; ffi::CSP_BUFFER_SIZE] {
+        unsafe { &(*self.0).packet_data_union.data }
+    }
+
+    pub fn packet_length(&self) -> usize {
+        unsafe { (*self.0).length.into() }
+    }
+
+    pub fn inner(&self) -> *const csp_packet_s {
+        self.0
+    }
+
+    pub fn whole_data_mut(&mut self) -> &mut [u8; ffi::CSP_BUFFER_SIZE] {
+        unsafe { &mut (*self.0).packet_data_union.data }
+    }
+
+    pub fn set_data(&mut self, data: &[u8]) -> bool {
+        if data.len() > self.whole_data().len() {
+            return false;
+        }
+        self.whole_data_mut()[0..data.len()].copy_from_slice(data);
+        unsafe {
+            (*self.0).length = data.len() as u16;
+        }
+        true
+    }
+
+    pub fn inner_mut(&self) -> *mut csp_packet_s {
+        self.0
+    }
+}
+
+impl CspPacket {
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl Default for CspPacket {
+    fn default() -> Self {
+        Self(csp_packet_s {
+            packet_info: Default::default(),
+            length: Default::default(),
+            id: Default::default(),
+            next: core::ptr::null_mut(),
+            header: Default::default(),
+            packet_data_union: Default::default(),
+        })
+    }
+}
+
+#[derive(Default)]
+pub struct CspSocket(pub csp_socket_s);
+
+impl CspSocket {
+    pub fn inner_as_mut_ptr(&mut self) -> *mut csp_socket_s {
+        &mut self.0
+    }
+}
+
+/// Rust wrapper for [ffi::csp_init]. Initialize the CSP stack.
+///
+/// # Safety
+///
+/// - You must call this function only once.
+pub unsafe fn csp_init() {
+    // SAFETY: FFI call
+    unsafe {
+        ffi::csp_init();
+    }
+}
+
+/// Rust wrapper for [ffi::csp_bind].
+pub fn csp_bind(socket: &mut CspSocket, port: u8) {
+    // SAFETY: FFI call
+    unsafe {
+        ffi::csp_bind(socket.inner_as_mut_ptr(), port);
+    }
+}
+
+/// Rust wrapper for [ffi::csp_listen].
+pub fn csp_listen(socket: &mut CspSocket, backlog: usize) {
+    // SAFETY: FFI call
+    unsafe {
+        ffi::csp_listen(socket.inner_as_mut_ptr(), backlog);
+    }
+}
+
+/// Rust wrapper for [ffi::csp_route_work].
+pub fn csp_route_work_raw() -> i32 {
+    unsafe { ffi::csp_route_work() }
+}
+
+/// Rust wrapper for [ffi::csp_route_work] which also converts errors to the [CspError] type.
+/// This function will panic if the returned error type is not among the known values of
+/// [CspError].
+///
+/// [csp_route_work_raw] can be used if this is not acceptable.
+pub fn csp_route_work() -> Result<(), CspError> {
+    let result = unsafe { ffi::csp_route_work() };
+    if result == CspError::None as i32 {
+        return Ok(());
+    }
+    Err(CspError::try_from(result)
+        .unwrap_or_else(|_| panic!("unexpected error value {} from csp_route_work", result)))
+}
+
+#[derive(Debug, Copy, Clone)]
+pub struct CspConnRef(*mut csp_conn_s);
+
+impl CspConnRef {
+    pub fn inner(&mut self) -> Option<&csp_conn_s> {
+        // SAFETY: Raw pointer access, we return [None] if the pointers is NULL.
+        unsafe { self.0.as_ref() }
+    }
+
+    pub fn inner_mut(&mut self) -> Option<&mut csp_conn_s> {
+        // SAFETY: Raw pointer access, we return [None] if the pointers is NULL.
+        unsafe { self.0.as_mut() }
+    }
+}
+
+pub struct CspConnGuard(pub CspConnRef);
+
+impl Drop for CspConnGuard {
+    fn drop(&mut self) {
+        csp_close(self.0);
+    }
+}
+
+impl AsRef<CspConnRef> for CspConnGuard {
+    fn as_ref(&self) -> &CspConnRef {
+        &self.0
+    }
+}
+
+impl AsMut<CspConnRef> for CspConnGuard {
+    fn as_mut(&mut self) -> &mut CspConnRef {
+        &mut self.0
+    }
+}
+
+#[derive(Default)]
+pub struct CspInterface(pub ffi::csp_iface_t);
+
+impl CspInterface {
+    pub fn new(host_addr: u16, is_default: bool) -> Self {
+        Self(ffi::csp_iface_t {
+            addr: host_addr,
+            netmask: Default::default(),
+            name: core::ptr::null(),
+            interface_data: core::ptr::null_mut(),
+            driver_data: core::ptr::null_mut(),
+            nexthop: None,
+            is_default: is_default as u8,
+            tx: Default::default(),
+            rx: Default::default(),
+            tx_error: Default::default(),
+            rx_error: Default::default(),
+            drop: Default::default(),
+            autherr: Default::default(),
+            frame: Default::default(),
+            txbytes: Default::default(),
+            rxbytes: Default::default(),
+            irq: Default::default(),
+            next: core::ptr::null_mut(),
+        })
+    }
+}
+
+#[derive(Default)]
+pub struct CspUdpConf(pub ffi::csp_if_udp_conf_t);
+
+impl CspUdpConf {
+    pub fn new(addr: &'static str, lport: u16, rport: u16) -> Self {
+        Self(ffi::csp_if_udp_conf_t {
+            host: addr.as_ptr() as *mut i8,
+            lport: lport.into(),
+            rport: rport.into(),
+            server_handle: Default::default(),
+            peer_addr: libc::sockaddr_in {
+                sin_family: Default::default(),
+                sin_port: Default::default(),
+                sin_addr: libc::in_addr {
+                    s_addr: Default::default(),
+                },
+                sin_zero: Default::default(),
+            },
+            sockfd: Default::default(),
+        })
+    }
+}
+
+pub fn csp_accept_guarded(socket: &mut CspSocket, timeout: Duration) -> Option<CspConnGuard> {
+    Some(CspConnGuard(csp_accept(socket, timeout)?))
+}
+
+/// Rust wrapper for [ffi::csp_accept].
+pub fn csp_accept(socket: &mut CspSocket, timeout: Duration) -> Option<CspConnRef> {
+    let timeout_millis = timeout.as_millis();
+    if timeout_millis > u32::MAX as u128 {
+        return None;
+    }
+    Some(CspConnRef(unsafe {
+        let addr = ffi::csp_accept(socket.inner_as_mut_ptr(), timeout_millis as u32);
+        if addr.is_null() {
+            return None;
+        }
+        addr
+    }))
+}
+
+/// Rust wrapper for [ffi::csp_read].
+pub fn csp_read(conn: &mut CspConnRef, timeout: Duration) -> Option<CspPacketRef> {
+    let timeout_millis = timeout.as_millis();
+    if timeout_millis > u32::MAX as u128 {
+        return None;
+    }
+    let opt_packet = unsafe { ffi::csp_read(conn.0, timeout_millis as u32) };
+    if opt_packet.is_null() {
+        return None;
+    }
+    // SAFETY: FFI pointer.
+    Some(CspPacketRef(unsafe { &mut *opt_packet }))
+}
+
+/// Rust wrapper for [ffi::csp_read] which returns a guarded packet reference. This packet
+/// will cleaned up automatically with [csp_buffer_free] on drop.
+pub fn csp_read_guarded(conn: &mut CspConnRef, timeout: Duration) -> Option<CspPacketRefGuard> {
+    Some(CspPacketRefGuard(Some(csp_read(conn, timeout)?)))
+}
+
+/// Rust wrapper for [ffi::csp_recvfrom].
+pub fn csp_recvfrom(socket: &mut CspSocket, timeout: u32) -> Option<CspPacketRef> {
+    let opt_packet = unsafe { ffi::csp_recvfrom(&mut socket.0, timeout) };
+    if opt_packet.is_null() {
+        return None;
+    }
+    Some(CspPacketRef(unsafe { &mut *opt_packet }))
+}
+
+/// Rust wrapper for [ffi::csp_recvfrom] which returns a guarded packet reference. This packet
+/// will cleaned up automatically with [csp_buffer_free] on drop.
+pub fn csp_recvfrom_guarded(socket: &mut CspSocket, timeout: u32) -> Option<CspPacketRefGuard> {
+    Some(CspPacketRefGuard(Some(csp_recvfrom(socket, timeout)?)))
+}
+
+/// Rust wrapper for [ffi::csp_conn_dport].
+pub fn csp_conn_dport(conn: &CspConnRef) -> i32 {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_conn_dport(conn.0) }
+}
+
+/// Rust wrapper for [ffi::csp_conn_sport].
+pub fn csp_conn_sport(conn: &CspConnRef) -> i32 {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_conn_sport(conn.0) }
+}
+
+/// Rust wrapper for [ffi::csp_conn_dst].
+pub fn csp_conn_dst(conn: &CspConnRef) -> i32 {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_conn_dst(conn.0) }
+}
+
+/// Rust wrapper for [ffi::csp_conn_src].
+pub fn csp_conn_src(conn: &CspConnRef) -> i32 {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_conn_src(conn.0) }
+}
+
+/// Rust wrapper for [ffi::csp_conn_src].
+pub fn csp_conn_flags(conn: &CspConnRef) -> i32 {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_conn_flags(conn.0) }
+}
+
+/// Rust wrapper for [ffi::csp_conn_src] which also tries to convert the options to
+/// a [ConnectOpts] bitfield.
+pub fn csp_conn_flags_typed(conn: &CspConnRef) -> Option<ConnectOpts> {
+    let flags_raw = csp_conn_flags(conn);
+    if flags_raw < 0 {
+        return None;
+    }
+    // SAFETY: FFI call.
+    ConnectOpts::from_bits(flags_raw as u32)
+}
+
+pub fn csp_service_handler(packet: CspPacketRef) {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_service_handler(&mut *packet.0) }
+}
+
+/// Rust wrapper for [ffi::csp_close].
+pub fn csp_close(conn: CspConnRef) -> i32 {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_close(conn.0) }
+}
+
+/// Rust wrapper for [ffi::csp_ping], returns the result code directly.
+pub fn csp_ping_raw(node: u16, timeout: Duration, size: usize, opts: SocketFlags) -> i32 {
+    // SAFETY: FFI call.
+    unsafe {
+        ffi::csp_ping(
+            node,
+            timeout.as_millis() as u32,
+            size as u32,
+            opts.bits() as u8,
+        )
+    }
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct PingError;
+
+/// Rust wrapper for [ffi::csp_ping].
+pub fn csp_ping(
+    node: u16,
+    timeout: Duration,
+    size: usize,
+    opts: SocketFlags,
+) -> Result<Duration, PingError> {
+    let result = csp_ping_raw(node, timeout, size, opts);
+    if result < 0 {
+        return Err(PingError);
+    }
+    Ok(Duration::from_millis(result as u64))
+}
+
+/// Rust wrapper for [ffi::csp_reboot].
+pub fn csp_reboot(node: u16) {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_reboot(node) }
+}
+
+/// Rust wrapper for [ffi::csp_connect].
+pub fn csp_connect(
+    prio: MsgPriority,
+    dst: u16,
+    dst_port: u8,
+    timeout: Duration,
+    opts: ConnectOpts,
+) -> Option<CspConnRef> {
+    // SAFETY: FFI call.
+    let conn = unsafe {
+        ffi::csp_connect(
+            prio as u8,
+            dst,
+            dst_port,
+            timeout.as_millis() as u32,
+            opts.bits(),
+        )
+    };
+    if conn.is_null() {
+        return None;
+    }
+    // SAFETY: We checked that the pointer is valid.
+    Some(CspConnRef(conn))
+}
+
+/// Rust wrapper for [ffi::csp_connect] which returns a guard structure. The connection will be
+/// be closed automatically when the guard structure is dropped.
+pub fn csp_connect_guarded(
+    prio: MsgPriority,
+    dst: u16,
+    dst_port: u8,
+    timeout: Duration,
+    opts: ConnectOpts,
+) -> Option<CspConnGuard> {
+    Some(CspConnGuard(csp_connect(
+        prio, dst, dst_port, timeout, opts,
+    )?))
+}
+
+/// Rust wrapper for [ffi::csp_buffer_get].
+pub fn csp_buffer_get() -> Option<CspPacketMut> {
+    let packet_ref = unsafe {
+        // The size argument is unused
+        ffi::csp_buffer_get(0)
+    };
+    if packet_ref.is_null() {
+        return None;
+    }
+    // SAFETY: We checked that the pointer is valid.
+    Some(CspPacketMut(unsafe { &mut *packet_ref }))
+}
+
+/// Rust wrapper for [ffi::csp_send].
+pub fn csp_send(conn: &mut CspConnRef, packet: impl Into<CspPacketRef>) {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_send(conn.0, packet.into().0) }
+}
+
+/// Rust wrapper for [ffi::csp_conn_print_table].
+pub fn csp_conn_print_table() {
+    // SAFETY: FFI call.
+    unsafe { ffi::csp_conn_print_table() }
+}
+
+/// Rust wrapper for [ffi::csp_buffer_free].
+pub fn csp_buffer_free(packet: impl Into<CspPacketRef>) {
+    // SAFETY: FFI call and the Rust type system actually ensure the correct type
+    // is free'd here, while also taking the packet by value.
+    unsafe { ffi::csp_buffer_free(packet.into().0 as *mut libc::c_void) }
+}
+
+/// Rust wrapper for [ffi::csp_transaction_persistent].
+///
+/// # Parameters
+///
+/// * `in_len`: Use [None] if the length is unknown, and the expected reply length otherwise.
+///
+/// # Returns
+///
+/// 1 or reply size on success, 0 otherwise.
+pub fn csp_transaction_persistent(
+    conn: &mut CspConnRef,
+    timeout: Duration,
+    out_data: &[u8],
+    in_data: &mut [u8],
+    in_len: Option<usize>,
+) -> i32 {
+    unsafe {
+        ffi::csp_transaction_persistent(
+            conn.0,
+            timeout.as_millis() as u32,
+            out_data.as_ptr() as *const core::ffi::c_void,
+            out_data.len() as i32,
+            in_data.as_ptr() as *mut core::ffi::c_void,
+            in_len.map(|v| v as i32).unwrap_or(-1),
+        )
+    }
+}
+
+/// Rust wrapper for [ffi::csp_transaction_w_opts].
+///
+/// # Parameters
+///
+/// * `in_len`: Use [None] if the length is unknown, and the expected reply length otherwise.
+///
+/// # Returns
+///
+/// 1 or reply size on success, 0 otherwise.
+#[allow(clippy::too_many_arguments)]
+pub fn csp_transaction_w_opts(
+    prio: MsgPriority,
+    dst: u16,
+    dst_port: u8,
+    timeout: Duration,
+    out_data: &[u8],
+    in_data: &mut [u8],
+    in_len: Option<usize>,
+    opts: ConnectOpts,
+) -> i32 {
+    unsafe {
+        ffi::csp_transaction_w_opts(
+            prio as u8,
+            dst,
+            dst_port,
+            timeout.as_millis() as u32,
+            out_data.as_ptr() as *const core::ffi::c_void,
+            out_data.len() as i32,
+            in_data.as_ptr() as *mut core::ffi::c_void,
+            in_len.map(|v| v as i32).unwrap_or(-1),
+            opts.bits(),
+        )
+    }
+}
+
+/// Calls [csp_transaction_w_opts] with [ConnectOpts::NONE].
+pub fn csp_transaction(
+    prio: MsgPriority,
+    dst: u16,
+    dst_port: u8,
+    timeout: Duration,
+    out_data: &[u8],
+    in_data: &mut [u8],
+    in_len: Option<usize>,
+) -> i32 {
+    csp_transaction_w_opts(
+        prio,
+        dst,
+        dst_port,
+        timeout,
+        out_data,
+        in_data,
+        in_len,
+        ConnectOpts::NONE,
+    )
+}
+
+pub mod udp {
+    use super::*;
+
+    /// Rust wrapper for [ffi::udp::csp_if_udp_init].
+    pub fn csp_if_udp_init(iface: &mut CspInterface, ifconf: &mut CspUdpConf) {
+        unsafe { ffi::udp::csp_if_udp_init(&mut iface.0, &mut ifconf.0) }
+    }
+}
+
+pub mod iflist {
+    use super::*;
+
+    /// Rust wrapper for [ffi::iflist::csp_iflist_print].
+    pub fn csp_iflist_print() {
+        // SAFETY: FFI call.
+        unsafe { ffi::iflist::csp_iflist_print() }
+    }
+
+    /// Rust wrapper for [ffi::iflist::csp_iflist_add].
+    pub fn csp_iflist_add(iface: &mut CspInterface) -> i32 {
+        unsafe { ffi::iflist::csp_iflist_add(&mut iface.0) }
+    }
+}