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}