Skip to main content

zwave_host/
nvm.rs

1//! NVM backup: the controller's whole memory image (network, nodes, routes),
2//! enough to replace a dead stick without re-pairing.
3
4use crate::controller::Controller;
5use crate::Error;
6use std::time::Duration;
7use tracing::info;
8use zwave_serial::message::{nvm, nvm_request, nvm_write, NvmResponse};
9use zwave_serial::{DataFrame, FunctionId as F};
10
11/// Largest image accepted (the biggest current controller NVM is well under this).
12pub const MAX_NVM: usize = 4 * 1024 * 1024;
13const CHUNK: u8 = 48;
14
15impl Controller {
16    /// Reads the controller's NVM image. Uses the extended or the 16-bit NVM
17    /// operations on 700 and 800 series sticks and the external NVM
18    /// functions on the 500 series. Normal operation pauses while it runs.
19    pub async fn backup_nvm(&self) -> Result<Vec<u8>, Error> {
20        let caps = &self.inner.caps;
21        let image = if caps.supports(F::EXTENDED_NVM_OPERATIONS) {
22            self.backup_700(true).await?
23        } else if caps.supports(F::NVM_OPERATIONS) {
24            self.backup_700(false).await?
25        } else if caps.supports(F::EXT_NVM_READ_LONG_BUFFER) && caps.supports(F::GET_NVM_ID) {
26            self.backup_500().await?
27        } else {
28            return Err(Error::Controller(
29                "the controller offers no NVM backup function".into(),
30            ));
31        };
32        info!(bytes = image.len(), "NVM backup read");
33        Ok(image)
34    }
35
36    async fn nvm_op(
37        &self,
38        extended: bool,
39        op: u8,
40        len: u8,
41        offset: u32,
42    ) -> Result<NvmResponse, Error> {
43        let r = self
44            .inner
45            .api
46            .request(
47                nvm_request(extended, op, len, offset),
48                Duration::from_secs(5),
49            )
50            .await?;
51        NvmResponse::parse(&r.payload, extended).map_err(|e| Error::Controller(e.to_string()))
52    }
53
54    async fn backup_700(&self, extended: bool) -> Result<Vec<u8>, Error> {
55        let open = self.nvm_op(extended, nvm::OPEN, 0, 0).await?;
56        if open.status != nvm::STATUS_OK {
57            return Err(Error::Controller(format!(
58                "NVM open failed: {:#04x}",
59                open.status
60            )));
61        }
62        let size = open.offset_or_size as usize;
63        let size = if size == 0 && !open.data.is_empty() {
64            open.data
65                .iter()
66                .fold(0usize, |a, &b| (a << 8) | usize::from(b))
67        } else {
68            size
69        };
70        if size == 0 || size > MAX_NVM {
71            let _ = self.nvm_op(extended, nvm::CLOSE, 0, 0).await;
72            return Err(Error::Controller(format!("NVM size {size} out of range")));
73        }
74        let mut image = Vec::with_capacity(size);
75        let result = async {
76            while image.len() < size {
77                let want = CHUNK.min((size - image.len()).min(255) as u8);
78                let r = self
79                    .nvm_op(extended, nvm::READ, want, image.len() as u32)
80                    .await?;
81                if r.status != nvm::STATUS_OK && r.status != nvm::STATUS_EOF {
82                    return Err(Error::Controller(format!(
83                        "NVM read failed: {:#04x}",
84                        r.status
85                    )));
86                }
87                if r.data.is_empty() {
88                    break;
89                }
90                let take = r.data.len().min(size - image.len());
91                image.extend_from_slice(&r.data[..take]);
92                if r.status == nvm::STATUS_EOF {
93                    break;
94                }
95            }
96            Ok(())
97        }
98        .await;
99        let close = self.nvm_op(extended, nvm::CLOSE, 0, 0).await;
100        result?;
101        close?;
102        Ok(image)
103    }
104
105    async fn backup_500(&self) -> Result<Vec<u8>, Error> {
106        let id = self
107            .inner
108            .api
109            .request(
110                DataFrame::request(F::GET_NVM_ID, vec![]),
111                Duration::from_secs(2),
112            )
113            .await?;
114        let code = *id
115            .payload
116            .get(2)
117            .ok_or(Error::Controller("NVM id too short".into()))?;
118        if !(0x0e..=0x16).contains(&code) {
119            return Err(Error::Controller(format!(
120                "unknown NVM size code {code:#04x}"
121            )));
122        }
123        let size = 1usize << code;
124        let mut image = Vec::with_capacity(size);
125        while image.len() < size {
126            let len = 64.min(size - image.len()) as u16;
127            let off = image.len() as u32;
128            let p = vec![
129                (off >> 16) as u8,
130                (off >> 8) as u8,
131                off as u8,
132                (len >> 8) as u8,
133                len as u8,
134            ];
135            let r = self
136                .inner
137                .api
138                .request(
139                    DataFrame::request(F::EXT_NVM_READ_LONG_BUFFER, p),
140                    Duration::from_secs(5),
141                )
142                .await?;
143            if r.payload.is_empty() {
144                return Err(Error::Controller("empty NVM read".into()));
145            }
146            let take = r.payload.len().min(size - image.len());
147            image.extend_from_slice(&r.payload[..take]);
148        }
149        Ok(image)
150    }
151}
152
153impl Controller {
154    /// Writes a backup image back to the controller and restarts it.
155    ///
156    /// A backup from another series (700 or 800) or SDK is converted first
157    /// ([`crate::nvm3::convert`]); one whose protocol format is newer than
158    /// the controller reads is refused. The controller restarts afterwards, so this
159    /// `Controller` must be dropped and a new one started.
160    pub async fn restore_nvm(&self, image: &[u8]) -> Result<(), Error> {
161        let caps = &self.inner.caps;
162        let extended = if caps.supports(F::EXTENDED_NVM_OPERATIONS) {
163            true
164        } else if caps.supports(F::NVM_OPERATIONS) {
165            false
166        } else {
167            return Err(Error::Controller(
168                "this controller offers no NVM restore (700 or 800 series only)".into(),
169            ));
170        };
171        let current = self.backup_nvm().await?;
172        // Converted to this controller's series and SDK where they differ.
173        let image = crate::nvm3::convert(image, &current).map_err(Error::Controller)?;
174        let image = &image[..];
175        let open = self.nvm_op(extended, nvm::OPEN, 0, 0).await?;
176        if open.status != nvm::STATUS_OK {
177            return Err(Error::Controller(format!(
178                "NVM open failed: {:#04x}",
179                open.status
180            )));
181        }
182        let result = async {
183            for (i, chunk) in image.chunks(usize::from(CHUNK)).enumerate() {
184                let offset = (i * usize::from(CHUNK)) as u32;
185                let r = self
186                    .inner
187                    .api
188                    .request(nvm_write(extended, offset, chunk), Duration::from_secs(5))
189                    .await?;
190                let r = NvmResponse::parse(&r.payload, extended)
191                    .map_err(|e| Error::Controller(e.to_string()))?;
192                if r.status != nvm::STATUS_OK && r.status != nvm::STATUS_EOF {
193                    return Err(Error::Controller(format!(
194                        "NVM write at {offset:#x} failed: {:#04x}",
195                        r.status
196                    )));
197                }
198            }
199            Ok(())
200        }
201        .await;
202        let close = self.nvm_op(extended, nvm::CLOSE, 0, 0).await;
203        result?;
204        close?;
205        self.inner
206            .api
207            .execute(zwave_serial::Request::ack_only(DataFrame::request(
208                F::SOFT_RESET,
209                vec![],
210            )))
211            .await?;
212        info!(
213            bytes = image.len(),
214            "NVM restored; the controller is restarting"
215        );
216        Ok(())
217    }
218}