Skip to main content

capsules_core/
adc.rs

1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Syscall driver capsules for ADC sampling.
6//!
7//! This module has two ADC syscall driver capsule implementations.
8//!
9//! The first, called AdcDedicated, assumes that it has complete (dedicated)
10//! control of the kernel ADC. This capsule provides userspace with
11//! the ability to perform single, continuous, and high speed samples.
12//! However, using this capsule means that no other
13//! capsule or kernel service can use the ADC. It also allows only
14//! a single process to use the ADC: other processes will receive
15//! NOMEM errors.
16//!
17//! The second, called AdcVirtualized, sits top of an ADC virtualizer.
18//! This capsule shares the ADC with the rest of the kernel through this
19//! virtualizer, so allows other kernel services and capsules to use the
20//! ADC. It also supports multiple processes requesting ADC samples
21//! concurrently. However, it only supports processes requesting single
22//! ADC samples: they cannot sample continuously or at high speed.
23//!
24//!
25//! Usage
26//! -----
27//!
28//! ```rust,ignore
29//! # use kernel::static_init;
30//!
31//! let adc_channels = static_init!(
32//!     [&'static sam4l::adc::AdcChannel; 6],
33//!     [
34//!         &sam4l::adc::CHANNEL_AD0, // A0
35//!         &sam4l::adc::CHANNEL_AD1, // A1
36//!         &sam4l::adc::CHANNEL_AD3, // A2
37//!         &sam4l::adc::CHANNEL_AD4, // A3
38//!         &sam4l::adc::CHANNEL_AD5, // A4
39//!         &sam4l::adc::CHANNEL_AD6, // A5
40//!     ]
41//! );
42//! let adc = static_init!(
43//!     capsules_core::adc::AdcDedicated<'static, sam4l::adc::Adc>,
44//!     capsules_core::adc::AdcDedicated::new(
45//!         &mut sam4l::adc::ADC0,
46//!         adc_channels,
47//!         &mut capsules_core::adc::ADC_BUFFER1,
48//!         &mut capsules_core::adc::ADC_BUFFER2,
49//!         &mut capsules_core::adc::ADC_BUFFER3
50//!     )
51//! );
52//! sam4l::adc::ADC0.set_client(adc);
53//! ```
54
55use core::cell::Cell;
56use core::cmp;
57
58use kernel::grant::{AllowRoCount, AllowRwCount, Grant, UpcallCount};
59use kernel::hil;
60use kernel::processbuffer::{ReadableProcessBuffer, WriteableProcessBuffer};
61use kernel::syscall::{CommandReturn, SyscallDriver};
62use kernel::utilities::cells::{OptionalCell, TakeCell};
63use kernel::{ErrorCode, ProcessId};
64
65/// Syscall driver number.
66use crate::driver;
67use crate::virtualizers::virtual_adc::Operation;
68pub const DRIVER_NUM: usize = driver::NUM::Adc as usize;
69
70/// Multiplexed ADC syscall driver, used by applications and capsules.
71///
72/// Virtualized, and can be use by multiple applications at the same time;
73/// requests are queued. Does not support continuous or high-speed sampling.
74pub struct AdcVirtualized<'a> {
75    drivers: &'a [&'a dyn hil::adc::AdcChannel<'a>],
76    apps: Grant<AppSys, UpcallCount<2>, AllowRoCount<0>, AllowRwCount<0>>,
77    current_process: OptionalCell<ProcessId>,
78}
79
80/// ADC syscall driver, used by applications to interact with ADC.
81///
82/// Not currently virtualized: does not share the ADC with other capsules
83/// and only one application can use it at a time. Supports continuous and
84/// high speed sampling.
85pub struct AdcDedicated<'a, A: hil::adc::Adc<'a> + hil::adc::AdcHighSpeed<'a>> {
86    // ADC driver
87    adc: &'a A,
88    channels: &'a [<A as hil::adc::Adc<'a>>::Channel],
89
90    // ADC state
91    active: Cell<bool>,
92    mode: Cell<AdcMode>,
93
94    // App state
95    apps: Grant<App, UpcallCount<2>, AllowRoCount<0>, AllowRwCount<2>>,
96    processid: OptionalCell<ProcessId>,
97    channel: Cell<usize>,
98
99    // ADC buffers
100    adc_buf1: TakeCell<'static, [u16]>,
101    adc_buf2: TakeCell<'static, [u16]>,
102    adc_buf3: TakeCell<'static, [u16]>,
103}
104
105/// ADC modes, used to track internal state and to signify to applications which
106/// state a callback came from
107#[derive(Copy, Clone, Debug, PartialEq)]
108pub(crate) enum AdcMode {
109    NoMode = -1,
110    SingleSample = 0,
111    ContinuousSample = 1,
112    SingleBuffer = 2,
113    ContinuousBuffer = 3,
114}
115
116// Datas passed by the application to us
117pub struct AppSys {
118    pending_command: bool,
119    command: OptionalCell<Operation>,
120    channel: usize,
121}
122
123/// Holds buffers that the application has passed us
124pub struct App {
125    app_buf_offset: Cell<usize>,
126    samples_remaining: Cell<usize>,
127    samples_outstanding: Cell<usize>,
128    next_samples_outstanding: Cell<usize>,
129    using_app_buf0: Cell<bool>,
130}
131
132impl Default for App {
133    fn default() -> App {
134        App {
135            app_buf_offset: Cell::new(0),
136            samples_remaining: Cell::new(0),
137            samples_outstanding: Cell::new(0),
138            next_samples_outstanding: Cell::new(0),
139            using_app_buf0: Cell::new(true),
140        }
141    }
142}
143
144impl Default for AppSys {
145    fn default() -> AppSys {
146        AppSys {
147            pending_command: false,
148            command: OptionalCell::empty(),
149            channel: 0,
150        }
151    }
152}
153/// Buffers to use for DMA transfers.
154///
155/// The size is chosen somewhat arbitrarily, but has been tested. At 175000 Hz,
156/// buffers need to be swapped every 70 us and copied over before the next
157/// swap. In testing, it seems to keep up fine.
158pub const BUF_LEN: usize = 128;
159
160impl<'a, A: hil::adc::Adc<'a> + hil::adc::AdcHighSpeed<'a>> AdcDedicated<'a, A> {
161    /// Create a new `Adc` application interface.
162    ///
163    /// - `adc` - ADC driver to provide application access to
164    /// - `channels` - list of ADC channels usable by applications
165    /// - `adc_buf1` - buffer used to hold ADC samples
166    /// - `adc_buf2` - second buffer used when continuously sampling ADC
167    pub fn new(
168        adc: &'a A,
169        grant: Grant<App, UpcallCount<2>, AllowRoCount<0>, AllowRwCount<2>>,
170        channels: &'a [<A as hil::adc::Adc<'a>>::Channel],
171        adc_buf1: &'static mut [u16; 128],
172        adc_buf2: &'static mut [u16; 128],
173        adc_buf3: &'static mut [u16; 128],
174    ) -> AdcDedicated<'a, A> {
175        AdcDedicated {
176            // ADC driver
177            adc,
178            channels,
179
180            // ADC state
181            active: Cell::new(false),
182            mode: Cell::new(AdcMode::NoMode),
183
184            // App state
185            apps: grant,
186            processid: OptionalCell::empty(),
187            channel: Cell::new(0),
188
189            // ADC buffers
190            adc_buf1: TakeCell::new(adc_buf1),
191            adc_buf2: TakeCell::new(adc_buf2),
192            adc_buf3: TakeCell::new(adc_buf3),
193        }
194    }
195
196    /// Store a buffer we've regained ownership of and return a handle to it.
197    /// The handle can have `map()` called on it in order to process the data in
198    /// the buffer.
199    ///
200    /// - `buf` - buffer to be stored
201    fn replace_buffer(&self, buf: &'static mut [u16]) -> &TakeCell<'static, [u16]> {
202        // We play a little trick here where we always insert replaced buffers
203        // in the last position but pull new buffers (in `take_and_map_buffer`)
204        // from the beginning. We do this to get around Rust ownership rules
205        // when handling errors. When we are doing continuous buffering, we need
206        // to make sure that we re-gain ownership of the buffer passed back from
207        // the ADC driver, AND we have to copy from that buffer the samples the
208        // ADC driver took. To allow us to ensure we re-gain ownership, even if
209        // an error occurs (like the app crashes), we unconditionally save
210        // ownership of the returned buffer first (by calling this function).
211        // However, we also pass zero or one buffers back to the ADC driver, and
212        // we must ensure we do not pass the same buffer right back to the
213        // driver before we have had a chance to save the samples.
214
215        if self.adc_buf3.is_none() {
216            self.adc_buf3.replace(buf);
217        } else {
218            let temp = self.adc_buf3.take();
219            self.adc_buf3.replace(buf);
220
221            // Find a place to insert the buffer we removed from the last slot.
222            if self.adc_buf2.is_none() {
223                temp.map(|likely_buffer| self.adc_buf2.replace(likely_buffer));
224            } else {
225                temp.map(|likely_buffer| self.adc_buf1.replace(likely_buffer));
226            }
227        }
228
229        &self.adc_buf3
230    }
231
232    /// Find a buffer to give to the ADC to store samples in.
233    ///
234    /// - `closure` - function to run on the found buffer
235    fn take_and_map_buffer<F: FnOnce(&'static mut [u16])>(&self, closure: F) {
236        if self.adc_buf1.is_some() {
237            self.adc_buf1.take().map(|val| {
238                closure(val);
239            });
240        } else if self.adc_buf2.is_some() {
241            self.adc_buf2.take().map(|val| {
242                closure(val);
243            });
244        } else if self.adc_buf3.is_some() {
245            self.adc_buf3.take().map(|val| {
246                closure(val);
247            });
248        }
249    }
250
251    /// Collect a single analog sample on a channel.
252    ///
253    /// - `channel` - index into `channels` array, which channel to sample
254    fn sample(&self, channel: usize) -> Result<(), ErrorCode> {
255        // only one sample at a time
256        if self.active.get() {
257            return Err(ErrorCode::BUSY);
258        }
259
260        // convert channel index
261        if channel >= self.channels.len() {
262            return Err(ErrorCode::INVAL);
263        }
264        let chan = &self.channels[channel];
265
266        // save state for callback
267        self.active.set(true);
268        self.mode.set(AdcMode::SingleSample);
269        self.channel.set(channel);
270
271        // start a single sample
272        let res = self.adc.sample(chan);
273        if res != Ok(()) {
274            // failure, clear state
275            self.active.set(false);
276            self.mode.set(AdcMode::NoMode);
277
278            return res;
279        }
280
281        Ok(())
282    }
283
284    /// Collect repeated single analog samples on a channel.
285    ///
286    /// - `channel` - index into `channels` array, which channel to sample
287    /// - `frequency` - number of samples per second to collect
288    fn sample_continuous(&self, channel: usize, frequency: u32) -> Result<(), ErrorCode> {
289        // only one sample at a time
290        if self.active.get() {
291            return Err(ErrorCode::BUSY);
292        }
293
294        // convert channel index
295        if channel >= self.channels.len() {
296            return Err(ErrorCode::INVAL);
297        }
298        let chan = &self.channels[channel];
299
300        // save state for callback
301        self.active.set(true);
302        self.mode.set(AdcMode::ContinuousSample);
303        self.channel.set(channel);
304
305        // start a single sample
306        let res = self.adc.sample_continuous(chan, frequency);
307        if res != Ok(()) {
308            // failure, clear state
309            self.active.set(false);
310            self.mode.set(AdcMode::NoMode);
311
312            return res;
313        }
314
315        Ok(())
316    }
317
318    /// Collect a buffer-full of analog samples.
319    ///
320    /// Samples are collected into the first app buffer provided. The number of
321    /// samples collected is equal to the size of the buffer "allowed".
322    ///
323    /// - `channel` - index into `channels` array, which channel to sample
324    /// - `frequency` - number of samples per second to collect
325    fn sample_buffer(&self, channel: usize, frequency: u32) -> Result<(), ErrorCode> {
326        // only one sample at a time
327        if self.active.get() {
328            return Err(ErrorCode::BUSY);
329        }
330
331        // convert channel index
332        if channel >= self.channels.len() {
333            return Err(ErrorCode::INVAL);
334        }
335        let chan = &self.channels[channel];
336
337        // cannot sample a buffer without a buffer to sample into
338        let mut app_buf_length = 0;
339        let exists = self.processid.map_or(false, |id| {
340            self.apps
341                .enter(id, |_, kernel_data| {
342                    app_buf_length = kernel_data
343                        .get_readwrite_processbuffer(0)
344                        .map_or(0, |b| b.len());
345                    app_buf_length > 0
346                })
347                .map_err(|err| {
348                    if err == kernel::process::Error::NoSuchApp
349                        || err == kernel::process::Error::InactiveApp
350                    {
351                        self.processid.clear();
352                    }
353                })
354                .unwrap_or(false)
355        });
356        if !exists {
357            return Err(ErrorCode::NOMEM);
358        }
359
360        // save state for callback
361        self.active.set(true);
362        self.mode.set(AdcMode::SingleBuffer);
363        let ret = self.processid.map_or(Err(ErrorCode::NOMEM), |id| {
364            self.apps
365                .enter(id, |app, _| {
366                    app.app_buf_offset.set(0);
367                    self.channel.set(channel);
368                    // start a continuous sample
369                    self.adc_buf1.take().map_or(Err(ErrorCode::BUSY), |buf1| {
370                        self.adc_buf2
371                            .take()
372                            .map_or(Err(ErrorCode::BUSY), move |buf2| {
373                                // determine request length
374                                let request_len = app_buf_length / 2;
375                                let (len1, len2) = if request_len <= buf1.len() {
376                                    (app_buf_length / 2, 0)
377                                } else if request_len <= (buf1.len() + buf2.len()) {
378                                    (buf1.len(), request_len - buf1.len())
379                                } else {
380                                    (buf1.len(), buf2.len())
381                                };
382
383                                // begin sampling
384                                app.using_app_buf0.set(true);
385                                app.samples_remaining.set(request_len - len1 - len2);
386                                app.samples_outstanding.set(len1 + len2);
387                                self.adc
388                                    .sample_highspeed(chan, frequency, buf1, len1, buf2, len2)
389                                    .map_or_else(
390                                        |(ecode, buf1, buf2)| {
391                                            // store buffers again
392                                            self.replace_buffer(buf1);
393                                            self.replace_buffer(buf2);
394                                            Err(ecode)
395                                        },
396                                        |()| Ok(()),
397                                    )
398                            })
399                    })
400                })
401                .map_err(|err| {
402                    if err == kernel::process::Error::NoSuchApp
403                        || err == kernel::process::Error::InactiveApp
404                    {
405                        self.processid.clear();
406                    }
407                })
408                .unwrap_or(Err(ErrorCode::NOMEM))
409        });
410        if ret != Ok(()) {
411            // failure, clear state
412            self.active.set(false);
413            self.mode.set(AdcMode::NoMode);
414            self.processid.map(|id| {
415                self.apps
416                    .enter(id, |app, _| {
417                        app.samples_remaining.set(0);
418                        app.samples_outstanding.set(0);
419                    })
420                    .map_err(|err| {
421                        if err == kernel::process::Error::NoSuchApp
422                            || err == kernel::process::Error::InactiveApp
423                        {
424                            self.processid.clear();
425                        }
426                    })
427            });
428        }
429        ret
430    }
431
432    /// Collect analog samples continuously.
433    ///
434    /// Fills one "allowed" application buffer at a time and then swaps to
435    /// filling the second buffer. Upcalls occur when the in use "allowed"
436    /// buffer fills.
437    ///
438    /// - `channel` - index into `channels` array, which channel to sample
439    /// - `frequency` - number of samples per second to collect
440    fn sample_buffer_continuous(&self, channel: usize, frequency: u32) -> Result<(), ErrorCode> {
441        // only one sample at a time
442        if self.active.get() {
443            return Err(ErrorCode::BUSY);
444        }
445
446        // convert channel index
447        if channel >= self.channels.len() {
448            return Err(ErrorCode::INVAL);
449        }
450        let chan = &self.channels[channel];
451
452        // cannot continuously sample without two buffers
453        let mut app_buf_length = 0;
454        let mut next_app_buf_length = 0;
455        let exists = self.processid.map_or(false, |id| {
456            self.apps
457                .enter(id, |_, kernel_data| {
458                    app_buf_length = kernel_data
459                        .get_readwrite_processbuffer(0)
460                        .map_or(0, |b| b.len());
461                    next_app_buf_length = kernel_data
462                        .get_readwrite_processbuffer(1)
463                        .map_or(0, |b| b.len());
464                    app_buf_length > 0 && next_app_buf_length > 0
465                })
466                .map_err(|err| {
467                    if err == kernel::process::Error::NoSuchApp
468                        || err == kernel::process::Error::InactiveApp
469                    {
470                        self.processid.clear();
471                    }
472                })
473                .unwrap_or(false)
474        });
475        if !exists {
476            return Err(ErrorCode::NOMEM);
477        }
478
479        // save state for callback
480        self.active.set(true);
481        self.mode.set(AdcMode::ContinuousBuffer);
482
483        let ret = self.processid.map_or(Err(ErrorCode::NOMEM), |id| {
484            self.apps
485                .enter(id, |app, _| {
486                    app.app_buf_offset.set(0);
487                    self.channel.set(channel);
488                    // start a continuous sample
489                    self.adc_buf1.take().map_or(Err(ErrorCode::BUSY), |buf1| {
490                        self.adc_buf2
491                            .take()
492                            .map_or(Err(ErrorCode::BUSY), move |buf2| {
493                                // determine request lengths
494                                let samples_needed = app_buf_length / 2;
495                                let next_samples_needed = next_app_buf_length / 2;
496
497                                // determine request lengths
498                                let len1;
499                                let len2;
500                                if samples_needed <= buf1.len() {
501                                    // we can fit the entire app_buffer request in the first
502                                    // buffer. The second buffer will be used for the next
503                                    // app_buffer
504                                    len1 = samples_needed;
505                                    len2 = cmp::min(next_samples_needed, buf2.len());
506                                    app.samples_remaining.set(0);
507                                    app.samples_outstanding.set(len1);
508                                } else if samples_needed <= (buf1.len() + buf2.len()) {
509                                    // we can fit the entire app_buffer request between the two
510                                    // buffers
511                                    len1 = buf1.len();
512                                    len2 = samples_needed - buf1.len();
513                                    app.samples_remaining.set(0);
514                                    app.samples_outstanding.set(len1 + len2);
515                                } else {
516                                    // the app_buffer is larger than both buffers, so just
517                                    // request max lengths
518                                    len1 = buf1.len();
519                                    len2 = buf2.len();
520                                    app.samples_remaining.set(samples_needed - len1 - len2);
521                                    app.samples_outstanding.set(len1 + len2);
522                                }
523
524                                // begin sampling
525                                app.using_app_buf0.set(true);
526                                self.adc
527                                    .sample_highspeed(chan, frequency, buf1, len1, buf2, len2)
528                                    .map_or_else(
529                                        |(ecode, buf1, buf2)| {
530                                            // store buffers again
531                                            self.replace_buffer(buf1);
532                                            self.replace_buffer(buf2);
533                                            Err(ecode)
534                                        },
535                                        |()| Ok(()),
536                                    )
537                            })
538                    })
539                })
540                .map_err(|err| {
541                    if err == kernel::process::Error::NoSuchApp
542                        || err == kernel::process::Error::InactiveApp
543                    {
544                        self.processid.clear();
545                    }
546                })
547                .unwrap_or(Err(ErrorCode::NOMEM))
548        });
549        if ret != Ok(()) {
550            // failure, clear state
551            self.active.set(false);
552            self.mode.set(AdcMode::NoMode);
553            self.processid.map(|id| {
554                self.apps
555                    .enter(id, |app, _| {
556                        app.samples_remaining.set(0);
557                        app.samples_outstanding.set(0);
558                    })
559                    .map_err(|err| {
560                        if err == kernel::process::Error::NoSuchApp
561                            || err == kernel::process::Error::InactiveApp
562                        {
563                            self.processid.clear();
564                        }
565                    })
566            });
567        }
568        ret
569    }
570
571    /// Stops sampling the ADC.
572    ///
573    /// Any active operation by the ADC is canceled. No additional callbacks
574    /// will occur. Also retrieves buffers from the ADC (if any).
575    fn stop_sampling(&self) -> Result<(), ErrorCode> {
576        if !self.active.get() || self.mode.get() == AdcMode::NoMode {
577            // already inactive!
578            return Ok(());
579        }
580
581        // clean up state
582        self.processid.map_or(Err(ErrorCode::FAIL), |id| {
583            self.apps
584                .enter(id, |app, _| {
585                    self.active.set(false);
586                    self.mode.set(AdcMode::NoMode);
587                    app.app_buf_offset.set(0);
588
589                    // actually cancel the operation
590                    let rc = self.adc.stop_sampling();
591                    if rc != Ok(()) {
592                        return rc;
593                    }
594
595                    // reclaim buffers
596                    match self.adc.retrieve_buffers() {
597                        Ok((buf1, buf2)) => {
598                            buf1.map(|buf| {
599                                self.replace_buffer(buf);
600                            });
601                            buf2.map(|buf| {
602                                self.replace_buffer(buf);
603                            });
604                            Ok(())
605                        }
606                        Err(ecode) => Err(ecode),
607                    }
608                })
609                .map_err(|err| {
610                    if err == kernel::process::Error::NoSuchApp
611                        || err == kernel::process::Error::InactiveApp
612                    {
613                        self.processid.clear();
614                    }
615                })
616                .unwrap_or(Err(ErrorCode::FAIL))
617        })
618    }
619
620    fn get_resolution_bits(&self) -> usize {
621        self.adc.get_resolution_bits()
622    }
623
624    fn get_voltage_reference_mv(&self) -> Option<usize> {
625        self.adc.get_voltage_reference_mv()
626    }
627}
628
629/// Functions to create, initialize, and interact with the virtualized ADC
630impl<'a> AdcVirtualized<'a> {
631    /// Create a new `Adc` application interface.
632    ///
633    /// - `drivers` - Virtual ADC drivers to provide application access to
634    pub fn new(
635        drivers: &'a [&'a dyn hil::adc::AdcChannel<'a>],
636        grant: Grant<AppSys, UpcallCount<2>, AllowRoCount<0>, AllowRwCount<0>>,
637    ) -> AdcVirtualized<'a> {
638        AdcVirtualized {
639            drivers,
640            apps: grant,
641            current_process: OptionalCell::empty(),
642        }
643    }
644
645    /// Enqueue the command to be executed when the ADC is available.
646    fn enqueue_command(
647        &self,
648        command: Operation,
649        channel: usize,
650        processid: ProcessId,
651    ) -> Result<(), ErrorCode> {
652        if channel < self.drivers.len() {
653            if self.current_process.is_none() {
654                self.current_process.set(processid);
655                let r = self.call_driver(command, channel);
656                if r != Ok(()) {
657                    self.current_process.clear();
658                }
659                self.run_next_command();
660                Ok(())
661            } else {
662                match self
663                    .apps
664                    .enter(processid, |app, _| {
665                        if app.pending_command {
666                            Err(ErrorCode::BUSY)
667                        } else {
668                            app.pending_command = true;
669                            app.command.set(command);
670                            app.channel = channel;
671                            Ok(())
672                        }
673                    })
674                    .map_err(ErrorCode::from)
675                {
676                    Err(e) => Err(e),
677                    Ok(_) => Ok(()),
678                }
679            }
680        } else {
681            Err(ErrorCode::NODEVICE)
682        }
683    }
684
685    /// Run next command in queue, when available
686    fn run_next_command(&self) {
687        let mut command = Operation::OneSample;
688        let mut channel = 0;
689        for app in self.apps.iter() {
690            let processid = app.processid();
691            let start_command = app.enter(|app, _| {
692                if app.pending_command {
693                    app.pending_command = false;
694                    app.command.take().map(|c| {
695                        command = c;
696                    });
697                    channel = app.channel;
698                    self.current_process.set(processid);
699                    true
700                } else {
701                    false
702                }
703            });
704            if start_command {
705                match self.call_driver(command, channel) {
706                    Err(_) => {
707                        self.current_process.clear();
708                    }
709                    Ok(()) => {
710                        break;
711                    }
712                }
713            }
714        }
715    }
716
717    /// Request the sample from the specified channel
718    fn call_driver(&self, command: Operation, channel: usize) -> Result<(), ErrorCode> {
719        match command {
720            Operation::OneSample => self.drivers[channel].sample(),
721        }
722    }
723}
724
725/// Callbacks from the ADC driver
726impl<'a, A: hil::adc::Adc<'a> + hil::adc::AdcHighSpeed<'a>> hil::adc::Client
727    for AdcDedicated<'a, A>
728{
729    /// Single sample operation complete.
730    ///
731    /// Collects the sample and provides a callback to the application.
732    ///
733    /// - `sample` - analog sample value
734    fn sample_ready(&self, sample: u16) {
735        let mut calledback = false;
736        if self.active.get() && self.mode.get() == AdcMode::SingleSample {
737            // single sample complete, clean up state
738            self.active.set(false);
739            self.mode.set(AdcMode::NoMode);
740
741            // perform callback
742
743            self.processid.map(|id| {
744                self.apps
745                    .enter(id, |_app, upcalls| {
746                        calledback = true;
747                        // TODO(Tock 3.0): Upcall index 0 passes a pointer via an upcall for
748                        // buffered sampling. We cannot support this on 64-bit. This upcall
749                        // is deprecated and should be removed. For backwards compatibility
750                        // we include it, but expect users to use upcall index 1.
751                        let _ = upcalls.schedule_upcall(
752                            0,
753                            (
754                                AdcMode::SingleSample as usize,
755                                self.channel.get(),
756                                sample as usize,
757                            ),
758                        );
759                        let _ = upcalls.schedule_upcall(
760                            1,
761                            (
762                                AdcMode::SingleSample as usize,
763                                self.channel.get(),
764                                sample as usize,
765                            ),
766                        );
767                    })
768                    .map_err(|err| {
769                        if err == kernel::process::Error::NoSuchApp
770                            || err == kernel::process::Error::InactiveApp
771                        {
772                            self.processid.clear();
773                        }
774                    })
775            });
776        } else if self.active.get() && self.mode.get() == AdcMode::ContinuousSample {
777            // sample ready in continuous sampling operation, keep state
778
779            // perform callback
780            self.processid.map(|id| {
781                self.apps
782                    .enter(id, |_app, upcalls| {
783                        calledback = true;
784                        // TODO(Tock 3.0): Upcall index 0 passes a pointer via an upcall for
785                        // buffered sampling. We cannot support this on 64-bit. This upcall
786                        // is deprecated and should be removed. For backwards compatibility
787                        // we include it, but expect users to use upcall index 1.
788                        let _ = upcalls.schedule_upcall(
789                            0,
790                            (
791                                AdcMode::ContinuousSample as usize,
792                                self.channel.get(),
793                                sample as usize,
794                            ),
795                        );
796                        let _ = upcalls.schedule_upcall(
797                            1,
798                            (
799                                AdcMode::ContinuousSample as usize,
800                                self.channel.get(),
801                                sample as usize,
802                            ),
803                        );
804                    })
805                    .map_err(|err| {
806                        if err == kernel::process::Error::NoSuchApp
807                            || err == kernel::process::Error::InactiveApp
808                        {
809                            self.processid.clear();
810                        }
811                    })
812            });
813        }
814        if !calledback {
815            // operation probably canceled. Make sure state is consistent. No
816            // callback
817            self.active.set(false);
818            self.mode.set(AdcMode::NoMode);
819
820            // Also make sure that no more samples are taken if we were in
821            // continuous mode.
822            let _ = self.adc.stop_sampling();
823        }
824    }
825}
826
827/// Callbacks from the High Speed ADC driver
828impl<'a, A: hil::adc::Adc<'a> + hil::adc::AdcHighSpeed<'a>> hil::adc::HighSpeedClient
829    for AdcDedicated<'a, A>
830{
831    /// Internal buffer has filled from a buffered sampling operation.
832    /// Copies data over to application buffer, determines if more data is
833    /// needed, and performs a callback to the application if ready. If
834    /// continuously sampling, also swaps application buffers and continues
835    /// sampling when necessary. If only filling a single buffer, stops
836    /// sampling operation when the application buffer is full.
837    ///
838    /// - `buf` - internal buffer filled with analog samples
839    /// - `length` - number of valid samples in the buffer, guaranteed to be
840    ///   less than or equal to buffer length
841    fn samples_ready(&self, buf: &'static mut [u16], length: usize) {
842        let mut unexpected_state = false;
843
844        // Make sure in all cases we regain ownership of the buffer. However,
845        // we also get a reference back to it so we can copy the sampled values
846        // out and to an application.
847        let buffer_with_samples = self.replace_buffer(buf);
848
849        // do we expect a buffer?
850        if self.active.get()
851            && (self.mode.get() == AdcMode::SingleBuffer
852                || self.mode.get() == AdcMode::ContinuousBuffer)
853        {
854            // we did expect a buffer. Determine the current application state
855            self.processid.map(|id| {
856                self.apps
857                    .enter(id, |app, kernel_data| {
858                        // Get both buffers, this shouldn't ever fail since the grant was created
859                        // with enough space. The buffer still may be empty though
860                        let app_buf0 = match kernel_data.get_readwrite_processbuffer(0) {
861                            Ok(buf) => buf,
862                            Err(_) => return,
863                        };
864                        let app_buf1 = match kernel_data.get_readwrite_processbuffer(1) {
865                            Ok(buf) => buf,
866                            Err(_) => return,
867                        };
868                        // determine which app buffer to copy data into and which is
869                        // next up if we're in continuous mode
870                        let use0 = app.using_app_buf0.get();
871                        let (app_buf_ref, next_app_buf) = if use0 {
872                            (&app_buf0, &app_buf1)
873                        } else {
874                            (&app_buf1, &app_buf0)
875                        };
876
877                        // update count of outstanding sample requests
878                        app.samples_outstanding
879                            .set(app.samples_outstanding.get() - length);
880
881                        // provide a new buffer and length request to the ADC if
882                        // necessary. If we haven't received enough samples for the
883                        // current app_buffer, we may need to place more requests. If we
884                        // have received enough, but are in continuous mode, we should
885                        // place a request for the next app_buffer. This is all
886                        // unfortunately made more complicated by the fact that there is
887                        // always one outstanding request to the ADC.
888                        let perform_callback;
889                        if app.samples_remaining.get() == 0 {
890                            // we have already placed outstanding requests for all the
891                            // samples needed to fill the current app_buffer
892
893                            if app.samples_outstanding.get() == 0 {
894                                // and the samples we just received are the last ones
895                                // we need
896                                perform_callback = true;
897
898                                if self.mode.get() == AdcMode::ContinuousBuffer {
899                                    // it's time to switch to the next app_buffer, but
900                                    // there's already an outstanding request to the ADC
901                                    // for the next app_buffer that was placed last
902                                    // time, so we need to account for that
903                                    let samples_needed =
904                                        next_app_buf.enter(|buf| buf.len() / 2).unwrap_or(0);
905                                    app.samples_remaining
906                                        .set(samples_needed - app.next_samples_outstanding.get());
907                                    app.samples_outstanding
908                                        .set(app.next_samples_outstanding.get());
909                                    app.using_app_buf0.set(!app.using_app_buf0.get());
910
911                                    // we also need to place our next request, however
912                                    // the outstanding request already placed for the
913                                    // next app_buffer might have completed it! So we
914                                    // have to account for that case
915                                    if app.samples_remaining.get() == 0 {
916                                        // oh boy. We actually need to place a request
917                                        // for the next next app_buffer (which is
918                                        // actually the current app_buf, but try not to
919                                        // think about that...). In practice, this
920                                        // should be a pretty uncommon case to hit, only
921                                        // occurring if the length of the app buffers
922                                        // are smaller than the length of the adc
923                                        // buffers, which is unsustainable at high
924                                        // sampling frequencies
925                                        let next_next_app_buf = &app_buf_ref;
926
927                                        // provide a new buffer. However, we cannot
928                                        // currently update state since the next
929                                        // app_buffer still has a request outstanding.
930                                        // We'll just make a request and handle the
931                                        // state updating on next callback
932                                        self.take_and_map_buffer(|adc_buf| {
933                                            let samples_needed = next_next_app_buf
934                                                .enter(|buf| buf.len() / 2)
935                                                .unwrap_or(0);
936                                            let request_len =
937                                                cmp::min(samples_needed, adc_buf.len());
938                                            app.next_samples_outstanding.set(request_len);
939                                            let _ = self
940                                                .adc
941                                                .provide_buffer(adc_buf, request_len)
942                                                .map_err(|(_, buf)| {
943                                                    self.replace_buffer(buf);
944                                                });
945                                        });
946                                    } else {
947                                        // okay, we still need more samples for the next
948                                        // app_buffer
949
950                                        // provide a new buffer and update state
951                                        self.take_and_map_buffer(|adc_buf| {
952                                            let request_len = cmp::min(
953                                                app.samples_remaining.get(),
954                                                adc_buf.len(),
955                                            );
956                                            app.samples_remaining
957                                                .set(app.samples_remaining.get() - request_len);
958                                            app.samples_outstanding
959                                                .set(app.samples_outstanding.get() + request_len);
960                                            let _ = self
961                                                .adc
962                                                .provide_buffer(adc_buf, request_len)
963                                                .map_err(|(_, buf)| {
964                                                    self.replace_buffer(buf);
965                                                });
966                                        });
967                                    }
968                                }
969                            } else {
970                                // but there are still outstanding samples for the
971                                // current app_buffer (actually exactly one request, the
972                                // one the ADC is currently acting on)
973                                perform_callback = false;
974
975                                if self.mode.get() == AdcMode::ContinuousBuffer {
976                                    // we're in continuous mode, so we need to start the
977                                    // first request for the next app_buffer
978
979                                    // provide a new buffer. However, we cannot
980                                    // currently update state since the current
981                                    // app_buffer still has a request outstanding. We'll
982                                    // just make a request and handle the state updating
983                                    // on next callback
984                                    self.take_and_map_buffer(|adc_buf| {
985                                        let samples_needed =
986                                            next_app_buf.enter(|buf| buf.len() / 2).unwrap_or(0);
987                                        let request_len = cmp::min(samples_needed, adc_buf.len());
988                                        app.next_samples_outstanding.set(request_len);
989                                        let _ = self
990                                            .adc
991                                            .provide_buffer(adc_buf, request_len)
992                                            .map_err(|(_, buf)| {
993                                                self.replace_buffer(buf);
994                                            });
995                                    });
996                                }
997                            }
998                        } else {
999                            // we need to get more samples for the current app_buffer
1000                            perform_callback = false;
1001
1002                            // provide a new buffer and update state
1003                            self.take_and_map_buffer(|adc_buf| {
1004                                let request_len =
1005                                    cmp::min(app.samples_remaining.get(), adc_buf.len());
1006                                app.samples_remaining
1007                                    .set(app.samples_remaining.get() - request_len);
1008                                app.samples_outstanding
1009                                    .set(app.samples_outstanding.get() + request_len);
1010                                let _ = self.adc.provide_buffer(adc_buf, request_len).map_err(
1011                                    |(_, buf)| {
1012                                        self.replace_buffer(buf);
1013                                    },
1014                                );
1015                            });
1016                        }
1017
1018                        let skip_amt = app.app_buf_offset.get() / 2;
1019
1020                        {
1021                            let app_buf = if use0 { &app_buf0 } else { &app_buf1 };
1022
1023                            // next we should copy bytes to the app buffer
1024                            let _ = app_buf.mut_enter(|app_buf| {
1025                                // Copy bytes to app buffer by iterating over the
1026                                // data.
1027                                buffer_with_samples.map(|adc_buf| {
1028                                    // The `for` commands:
1029                                    //  * `chunks_mut`: get sets of two bytes from the app
1030                                    //                  buffer
1031                                    //  * `skip`: skips the already written bytes from the
1032                                    //            app buffer
1033                                    //  * `zip`: ties that iterator to an iterator on the
1034                                    //           adc buffer, limiting iteration length to
1035                                    //           the minimum of each of their lengths
1036                                    //  * `take`: limits us to the minimum of buffer lengths
1037                                    //            or sample length
1038                                    // We then split each sample into its two bytes and copy
1039                                    // them to the app buffer
1040                                    for (chunk, &sample) in app_buf
1041                                        .chunks(2)
1042                                        .skip(skip_amt)
1043                                        .zip(adc_buf.iter())
1044                                        .take(length)
1045                                    {
1046                                        let mut val = sample;
1047                                        for byte in chunk.iter() {
1048                                            byte.set((val & 0xFF) as u8);
1049                                            val >>= 8;
1050                                        }
1051                                    }
1052                                });
1053                            });
1054                        }
1055                        // update our byte offset based on how many samples we
1056                        // copied
1057                        app.app_buf_offset
1058                            .set(app.app_buf_offset.get() + length * 2);
1059
1060                        // let in_use_buf;
1061                        let (buf_ptr, buf_len, buf_idx) = if use0 {
1062                            (app_buf0.ptr(), app_buf0.len(), 0)
1063                        } else {
1064                            (app_buf1.ptr(), app_buf1.len(), 1)
1065                        };
1066                        // if the app_buffer is filled, perform callback
1067                        if perform_callback {
1068                            // actually schedule the callback
1069                            let len_chan = ((buf_len / 2) << 8) | (self.channel.get() & 0xFF);
1070                            // TODO(Tock 3.0): This passes a pointer via an upcall. We cannot
1071                            // support this on 64-bit. This upcall should be removed.
1072                            let _ = kernel_data.schedule_upcall(
1073                                0,
1074                                (self.mode.get() as usize, len_chan, buf_ptr as usize),
1075                            );
1076                            // Replacement:
1077                            let _ = kernel_data
1078                                .schedule_upcall(1, (self.mode.get() as usize, len_chan, buf_idx));
1079
1080                            // if the mode is SingleBuffer, the operation is
1081                            // complete. Clean up state
1082                            if self.mode.get() == AdcMode::SingleBuffer {
1083                                self.active.set(false);
1084                                self.mode.set(AdcMode::NoMode);
1085                                app.app_buf_offset.set(0);
1086
1087                                // need to actually stop sampling
1088                                let _ = self.adc.stop_sampling();
1089
1090                                // reclaim buffers and store them
1091                                if let Ok((buf1, buf2)) = self.adc.retrieve_buffers() {
1092                                    buf1.map(|buf| {
1093                                        self.replace_buffer(buf);
1094                                    });
1095                                    buf2.map(|buf| {
1096                                        self.replace_buffer(buf);
1097                                    });
1098                                }
1099                            } else {
1100                                // if the mode is ContinuousBuffer, we've just
1101                                // switched app buffers. Reset our offset to zero
1102                                app.app_buf_offset.set(0);
1103                            }
1104                        }
1105                    })
1106                    .map_err(|err| {
1107                        if err == kernel::process::Error::NoSuchApp
1108                            || err == kernel::process::Error::InactiveApp
1109                        {
1110                            self.processid.clear();
1111                            unexpected_state = true;
1112                        }
1113                    })
1114            });
1115        } else {
1116            unexpected_state = true;
1117        }
1118
1119        if unexpected_state {
1120            // Operation was likely canceled, or the app crashed. Make sure
1121            // state is consistent. No callback.
1122            self.active.set(false);
1123            self.mode.set(AdcMode::NoMode);
1124            self.processid.map(|id| {
1125                self.apps
1126                    .enter(id, |app, _| {
1127                        app.app_buf_offset.set(0);
1128                    })
1129                    .map_err(|err| {
1130                        if err == kernel::process::Error::NoSuchApp
1131                            || err == kernel::process::Error::InactiveApp
1132                        {
1133                            self.processid.clear();
1134                        }
1135                    })
1136            });
1137
1138            // Make sure we do not take more samples since we know no app
1139            // is currently waiting on samples.
1140            let _ = self.adc.stop_sampling();
1141
1142            // Also retrieve any buffers we passed to the underlying ADC driver.
1143            if let Ok((buf1, buf2)) = self.adc.retrieve_buffers() {
1144                buf1.map(|buf| {
1145                    self.replace_buffer(buf);
1146                });
1147                buf2.map(|buf| {
1148                    self.replace_buffer(buf);
1149                });
1150            }
1151        }
1152    }
1153}
1154
1155/// Implementations of application syscalls
1156impl<'a, A: hil::adc::Adc<'a> + hil::adc::AdcHighSpeed<'a>> SyscallDriver for AdcDedicated<'a, A> {
1157    /// Method for the application to command or query this driver.
1158    ///
1159    /// - `command_num` - which command call this is
1160    /// - `data` - value sent by the application, varying uses
1161    /// - `_processid` - application identifier, unused
1162    fn command(
1163        &self,
1164        command_num: usize,
1165        channel: usize,
1166        frequency: usize,
1167        processid: ProcessId,
1168    ) -> CommandReturn {
1169        // Return true if this app already owns the ADC capsule, if no app owns
1170        // the ADC capsule, or if the app that is marked as owning the ADC
1171        // capsule no longer exists.
1172        let match_or_empty_or_nonexistant = self.processid.map_or(true, |owning_app| {
1173            // We have recorded that an app has ownership of the ADC.
1174
1175            // If the ADC is still active, then we need to wait for the operation
1176            // to finish and the app, whether it exists or not (it may have crashed),
1177            // still owns this capsule. If the ADC is not active, then
1178            // we need to verify that that application still exists, and remove
1179            // it as owner if not.
1180            if self.active.get() {
1181                owning_app == processid
1182            } else {
1183                // Check the app still exists.
1184                //
1185                // If the `.enter()` succeeds, then the app is still valid, and
1186                // we can check if the owning app matches the one that called
1187                // the command. If the `.enter()` fails, then the owning app no
1188                // longer exists and we return `true` to signify the
1189                // "or_nonexistant" case.
1190                self.apps
1191                    .enter(owning_app, |_, _| owning_app == processid)
1192                    .unwrap_or(true)
1193            }
1194        });
1195        if match_or_empty_or_nonexistant {
1196            self.processid.set(processid);
1197        } else {
1198            return CommandReturn::failure(ErrorCode::NOMEM);
1199        }
1200        match command_num {
1201            // Driver existence check
1202            // TODO(Tock 3.0): TRD104 specifies that Command 0 should return Success, not SuccessU32,
1203            // but this driver is unchanged since it has been stabilized. It will be brought into
1204            // compliance as part of the next major release of Tock. See #3375.
1205            0 => CommandReturn::success_u32(self.channels.len() as u32),
1206
1207            // Single sample on channel
1208            1 => match self.sample(channel) {
1209                Ok(()) => CommandReturn::success(),
1210                e => CommandReturn::failure(if let Ok(err) = ErrorCode::try_from(e) {
1211                    err
1212                } else {
1213                    panic!("ADC: invalid return code")
1214                }),
1215            },
1216
1217            // Repeated single samples on a channel
1218            2 => match self.sample_continuous(channel, frequency as u32) {
1219                Ok(()) => CommandReturn::success(),
1220                e => CommandReturn::failure(if let Ok(err) = ErrorCode::try_from(e) {
1221                    err
1222                } else {
1223                    panic!("ADC: invalid return code")
1224                }),
1225            },
1226
1227            // Multiple sample on a channel
1228            3 => match self.sample_buffer(channel, frequency as u32) {
1229                Ok(()) => CommandReturn::success(),
1230                e => CommandReturn::failure(if let Ok(err) = ErrorCode::try_from(e) {
1231                    err
1232                } else {
1233                    panic!("ADC: invalid return code")
1234                }),
1235            },
1236
1237            // Continuous buffered sampling on a channel
1238            4 => match self.sample_buffer_continuous(channel, frequency as u32) {
1239                Ok(()) => CommandReturn::success(),
1240                e => CommandReturn::failure(if let Ok(err) = ErrorCode::try_from(e) {
1241                    err
1242                } else {
1243                    panic!("ADC: invalid return code")
1244                }),
1245            },
1246
1247            // Stop sampling
1248            5 => match self.stop_sampling() {
1249                Ok(()) => CommandReturn::success(),
1250                e => CommandReturn::failure(if let Ok(err) = ErrorCode::try_from(e) {
1251                    err
1252                } else {
1253                    panic!("ADC: invalid return code")
1254                }),
1255            },
1256
1257            // Get resolution bits
1258            101 => CommandReturn::success_u32(self.get_resolution_bits() as u32),
1259            // Get voltage reference mV
1260            102 => {
1261                if let Some(voltage) = self.get_voltage_reference_mv() {
1262                    CommandReturn::success_u32(voltage as u32)
1263                } else {
1264                    CommandReturn::failure(ErrorCode::NOSUPPORT)
1265                }
1266            }
1267
1268            // default
1269            _ => CommandReturn::failure(ErrorCode::NOSUPPORT),
1270        }
1271    }
1272
1273    fn allocate_grant(&self, processid: ProcessId) -> Result<(), kernel::process::Error> {
1274        self.apps.enter(processid, |_, _| {})
1275    }
1276}
1277
1278/// Implementation of the syscalls for the virtualized ADC.
1279impl SyscallDriver for AdcVirtualized<'_> {
1280    /// Method for the application to command or query this driver.
1281    ///
1282    /// - `command_num` - which command call this is
1283    /// - `channel` - requested channel value
1284    /// - `_` - value sent by the application, unused
1285    /// - `processid` - application identifier
1286    fn command(
1287        &self,
1288        command_num: usize,
1289        channel: usize,
1290        _: usize,
1291        processid: ProcessId,
1292    ) -> CommandReturn {
1293        match command_num {
1294            // This driver exists and return the number of channels
1295            0 => CommandReturn::success_u32(self.drivers.len() as u32),
1296
1297            // Single sample.
1298            1 => {
1299                let res = self.enqueue_command(Operation::OneSample, channel, processid);
1300                if res == Ok(()) {
1301                    CommandReturn::success()
1302                } else {
1303                    match ErrorCode::try_from(res) {
1304                        Ok(error) => CommandReturn::failure(error),
1305                        _ => panic!("ADC Syscall: invalid error from enqueue_command"),
1306                    }
1307                }
1308            }
1309
1310            // Get resolution bits
1311            101 => {
1312                if channel < self.drivers.len() {
1313                    CommandReturn::success_u32(self.drivers[channel].get_resolution_bits() as u32)
1314                } else {
1315                    CommandReturn::failure(ErrorCode::NODEVICE)
1316                }
1317            }
1318
1319            // Get voltage reference mV
1320            102 => {
1321                if channel < self.drivers.len() {
1322                    if let Some(voltage) = self.drivers[channel].get_voltage_reference_mv() {
1323                        CommandReturn::success_u32(voltage as u32)
1324                    } else {
1325                        CommandReturn::failure(ErrorCode::NOSUPPORT)
1326                    }
1327                } else {
1328                    CommandReturn::failure(ErrorCode::NODEVICE)
1329                }
1330            }
1331
1332            _ => CommandReturn::failure(ErrorCode::NOSUPPORT),
1333        }
1334    }
1335
1336    fn allocate_grant(&self, processid: ProcessId) -> Result<(), kernel::process::Error> {
1337        self.apps.enter(processid, |_, _| {})
1338    }
1339}
1340
1341impl hil::adc::Client for AdcVirtualized<'_> {
1342    fn sample_ready(&self, sample: u16) {
1343        self.current_process.take().map(|processid| {
1344            let _ = self.apps.enter(processid, |app, upcalls| {
1345                app.pending_command = false;
1346                let channel = app.channel;
1347                // TODO(Tock 3.0): Upcall index 0 passes a pointer via an upcall for
1348                // buffered sampling. We cannot support this on 64-bit. This upcall
1349                // is deprecated and should be removed. For backwards compatibility
1350                // we include it, but expect users to use upcall index 1.
1351                let _ = upcalls.schedule_upcall(
1352                    0,
1353                    (AdcMode::SingleSample as usize, channel, sample as usize),
1354                );
1355                let _ = upcalls.schedule_upcall(
1356                    1,
1357                    (AdcMode::SingleSample as usize, channel, sample as usize),
1358                );
1359            });
1360        });
1361        self.run_next_command();
1362    }
1363}