linuxcnc-hal 0.3.0

A safe, high level interface to LinuxCNC's HAL submodule
Documentation 
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
144
145
146
147
148
149
150
151
152
153
154

//! Error types

use linuxcnc_hal_sys::HAL_NAME_LEN;

/// Errors returned by LinuxCNC bindgen functions

/// Pointer error
#[derive(thiserror::Error, Debug, PartialEq)]
pub enum StorageError {
    /// Pointer is null
    #[error("pointer is null")]
    Null,

    /// Pointer is not aligned
    #[error("pointer is not aligned")]
    Alignment,
}

/// Pin registration error
#[derive(thiserror::Error, Debug, PartialEq)]
pub enum PinRegisterError {
    /// Pin name is too long
    ///
    /// The maximum length is dictated by the [`HAL_NAME_LEN`] constant
    #[error("pin name is too long. Must be no longer than {} bytes", HAL_NAME_LEN)]
    NameLength,

    /// Pin name could not be converted to C string
    #[error("pin name could not be converted to a valid C string")]
    NameConversion,

    /// An error occurred allocating the HAL shared memory storage backing the pin
    #[error("failed to allocate shared memory storage for pin")]
    Storage(StorageError),

    /// An error occurred in the LinuxCNC HAL functions
    ///
    /// This variant is often returned when a HAL function returns
    /// [`EINVAL`](linuxcnc_hal_sys::EINVAL). This error code is returned for various different
    /// reasons. Check the LinuxCNC logs for error messages.
    #[error("HAL method returned invalid (EINVAL) status code")]
    Invalid,

    /// The HAL is locked
    ///
    /// Resources cannot be registered after a component is created
    #[error("HAL is locked")]
    LockedHal,

    /// There is not enough free memory available to allocate storage for this pin
    #[error("not enough free memory to allocate storage")]
    Memory,
}

/// Parameter registration error
#[derive(thiserror::Error, Debug, PartialEq)]
pub enum ParameterRegisterError {
    /// Parameter name is too long
    ///
    /// The maximum length is dictated by the [`HAL_NAME_LEN`] constant
    #[error(
        "Parameter name is too long. Must be no longer than {} bytes",
        HAL_NAME_LEN
    )]
    NameLength,

    /// Parameter name could not be converted to C string
    #[error("Parameter name could not be converted to a valid C string")]
    NameConversion,

    /// An error occurred allocating the HAL shared memory storage backing the parameter
    #[error("failed to allocate shared memory storage for parameter")]
    Storage(StorageError),

    /// An error occurred in the LinuxCNC HAL functions
    ///
    /// This variant is often returned when a HAL function returns
    /// [`EINVAL`](linuxcnc_hal_sys::EINVAL). This error code is returned for various different
    /// reasons. Check the LinuxCNC logs for error messages.
    #[error("HAL method returned invalid (EINVAL) status code")]
    Invalid,

    /// The HAL is locked
    ///
    /// Resources cannot be registered after a component is created
    #[error("HAL is locked")]
    LockedHal,

    /// There is not enough free memory available to allocate storage for this parameter
    #[error("not enough free memory to allocate storage")]
    Memory,
}

/// HAL component initialisation error
#[derive(thiserror::Error, Debug)]
pub enum ComponentInitError {
    /// Component name is too long
    ///
    /// The maximum length is dictated by the [`HAL_NAME_LEN`] constant
    #[error(
        "component name is too long. Must be no longer than {} bytes",
        HAL_NAME_LEN
    )]
    NameLength,

    /// Component name could not be converted to C type
    #[error("component name cannot be converted to valid C string")]
    InvalidName,

    /// There is not enough free memory available to allocate storage for this pin
    #[error("not enough free memory to allocate storage")]
    Memory,

    /// Failed to register signal handlers
    #[error("failed to register signal handlers")]
    Signals(std::io::Error),

    /// Resource (pin, signal, etc) registration failed
    #[error("failed to register resources with component")]
    ResourceRegistration(ResourcesError),

    /// An error occurred when initialising the component with
    /// [`hal_init`](linuxcnc_hal_sys::hal_init)
    #[error("failed to initialise component")]
    Init,

    /// An error occurred when calling [`hal_ready`](linuxcnc_hal_sys::hal_ready) on the component
    #[error("failed to ready component")]
    Ready,
}

/// Resources registration error
#[derive(thiserror::Error, Debug)]
pub enum ResourcesError {
    /// Failed to register a pin with the HAL
    #[error("pin registration failed")]
    Pin(PinRegisterError),

    /// Failed to register a pin with the HAL
    #[error("parameter registration failed")]
    Parameter(ParameterRegisterError),
}

impl From<PinRegisterError> for ResourcesError {
    fn from(e: PinRegisterError) -> Self {
        Self::Pin(e)
    }
}

impl From<ParameterRegisterError> for ResourcesError {
    fn from(e: ParameterRegisterError) -> Self {
        Self::Parameter(e)
    }
}