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
138
139
140
141
142
143

//! HAL component builder

use crate::{
    error::{ComponentInitError, ComponentReadyError, PinRegisterError},
    hal_pin::{HalPin, InputPin, OutputPin},
    HalComponent,
};
use linuxcnc_hal_sys::{hal_init, hal_ready, EINVAL, ENOMEM, HAL_NAME_LEN};
use signal_hook::iterator::Signals;
use std::ffi::CString;

/// HAL component builder
///
/// Create a new HAL component with [`HalComponentBuilder::new`]. Use the builder to register a
/// component with LinuxCNC. Once created, pins can be registered to the component. Finally, call
/// `builder.ready()` to consume the builder and create a [`HalComponent`] ready for use in the
/// component main loop.
#[derive(Debug, PartialEq)]
pub struct HalComponentBuilder {
    /// Component name
    ///
    /// Examples:
    ///
    /// * `wj200_vfd`
    /// * `hy_vfd`
    name: &'static str,

    /// Component ID
    id: i32,
}

impl HalComponentBuilder {
    /// Create a new HAL component builder and begin initialisation
    ///
    /// # Safety
    ///
    /// This calls [`hal_init`] internally, which may panic or leak memory.
    ///
    /// # Errors
    ///
    /// This component will error if the component name is longer than [`HAL_NAME_LEN`], the name
    /// cannot be converted to a valid [`CString`] or the call to [`hal_init`] returns an invalid
    /// ID.
    pub fn new(name: &'static str) -> Result<Self, ComponentInitError> {
        if name.len() > HAL_NAME_LEN as usize {
            println!(
                "Component name must be no longer than {} bytes",
                HAL_NAME_LEN
            );

            Err(ComponentInitError::NameLength)
        } else {
            let name_c = CString::new(name).map_err(|_| ComponentInitError::InvalidName)?;

            let id = unsafe { hal_init(name_c.as_ptr() as *const i8) };

            match id {
                x if x == -(EINVAL as i32) => Err(ComponentInitError::Init),
                x if x == -(ENOMEM as i32) => Err(ComponentInitError::Memory),
                id if id > 0 => {
                    println!("Init component {} with ID {}", name, id);

                    Ok(Self { name, id })
                }
                code => unreachable!("Hit unreachable error code {}", code),
            }
        }
    }

    /// Register an input pin with this component
    ///
    /// The pin name will be prefixed with the component name
    pub fn register_input_pin<P>(
        &mut self,
        pin_name: &'static str,
    ) -> Result<InputPin<P>, PinRegisterError>
    where
        P: HalPin + 'static,
    {
        let full_name = format!("{}.{}", self.name, pin_name);

        let pin = InputPin::<P>::new(full_name.clone(), self.id)?;

        Ok(pin)
    }

    /// Register an output pin with this component
    ///
    /// The pin name will be prefixed with the component name
    pub fn register_output_pin<P>(
        &mut self,
        pin_name: &'static str,
    ) -> Result<OutputPin<P>, PinRegisterError>
    where
        P: HalPin + 'static,
    {
        let full_name = format!("{}.{}", self.name, pin_name);

        let pin = OutputPin::<P>::new(full_name.clone(), self.id)?;

        Ok(pin)
    }

    /// Consume the builder and signal that the component is ready
    ///
    /// This method is called after any pins are registered and consumes the builder into a
    /// [`HalComponent`].
    ///
    /// # Safety
    ///
    /// This method calls the unsafe [`hal_ready`] method internally.
    pub fn ready(self) -> Result<HalComponent, ComponentReadyError> {
        let ret = unsafe { hal_ready(self.id) };

        match ret {
            x if x == -(EINVAL as i32) => Err(ComponentReadyError::Invalid),
            0 => {
                // Register signals so component closes cleanly. These are also required for the component to
                // pass initialisation in LinuxCNC. If LinuxCNC hangs during starting waiting for the component
                // to become ready, signal handlers might not be registered.
                let signals = Signals::new(&[signal_hook::SIGTERM, signal_hook::SIGINT])
                    .map_err(ComponentReadyError::Signals)?;

                println!("Signals registered, component is ready");

                let HalComponentBuilder { name, id, .. } = self;

                Ok(HalComponent { name, id, signals })
            }
            ret => unreachable!("Unknown error status {} returned from hal_ready()", ret),
        }
    }

    /// Get the HAL-assigned ID for this component
    pub fn id(&self) -> i32 {
        self.id
    }

    /// Get the component name
    pub fn name(&self) -> &str {
        self.name
    }
}