doc/syscalls/00005_adc.md
The ADC driver allows userspace to measure analog signals. The signals, such as a sensor measurement or voltage level, are usually connected to external pins on the microcontroller, referred to as channels, and this driver supports selecting which channel to measure from. Channels available to userspace are selected by the board configuration, and are indexed starting from zero. The number of bits of data in each sample and the possible voltage range of each sample are chip specific.
The ADC driver is capable of requesting single samples, single samples repeated at a specified frequency, a buffer full of samples at a specified frequency, and continuously sampling at a specified frequency. The minimum and maximum sampling frequencies are chip specific.
0Description: How many ADC channels are supported on this board.
Argument 1: Unused.
Argument 2: unused
Returns: The number of channels on the board, or NODEVICE if this
driver is not present on the board.
1Description: Measure the analog value of a single channel once. The callback will return the sample. This command will succeed even if a callback is not registered yet.
Argument 1: The index of the channel to sample, starting at 0.
Argument 2: unused
Returns: Ok(()) if the command was successful, BUSY if the ADC is
already sampling a channel, and INVAL if the channel index is invalid.
FAIL may also be returned if the hardware has a fault.
2Description: Measure the analog value of a single channel repeatedly. The callback will return each sample value individually. This command will succeed even if a callback is not registered yet.
Argument 1: The index of the channel to sample, starting at 0.
Argument 2: The frequency at which to sample the value.
Returns: Ok(()) if the command was successful, BUSY if the ADC is
already sampling a channel, and INVAL if the channel index is invalid or
the frequency is outside of the acceptable range. FAIL may also be
returned if the hardware has a fault.
3Description: Measure the analog value of a single channel repeatedly,
filling a buffer with data before sending a callback. The callback will
return the buffer of samples. This command will succeed even if a callback
is not registered yet. A buffer must have previously been provided through
an allow call before this command will succeed.
Argument 1: The index of the channel to sample, starting at 0.
Argument 2: The frequency at which to sample the value.
Returns: Ok(()) if the command was successful, BUSY if the ADC is
already sampling a channel, NOMEM if a buffer has not been provided, and
INVAL if the channel index is invalid or the frequency is outside of the
acceptable range. FAIL may also be returned if the hardware has a fault.
4Description: Measure the analog value of a single channel continuously.
Two buffers must be provided by allow calls before this command will
succeed. The buffers will be filled with samples in an alternating fashion,
with the callback returning the buffer full of samples. Special care must
be taken when using this command to ensure that the buffer sizes are large
enough for the specified sampling frequency that all samples can be read
before the next buffer is filled with samples. This command will succeed
even if a callback is not registered yet.
Argument 1: The index of the channel to sample, starting at 0.
Argument 2: The frequency at which to sample the value.
Returns: Ok(()) if the command was successful, BUSY if the ADC is
already sampling a channel, NOMEM if both buffers have not been
provided, and INVAL if the channel index is invalid or the frequency is
outside of the acceptable range. FAIL may also be returned if the
hardware has a fault.
5Description: Stop any active sampling operation. This command is successful even if no sampling operation was in progress.
Argument 1: Unused.
Argument 2: unused
Returns: Ok(()) in all cases.
0Description: Register a callback that will fire when requested samples are ready, replacing any previously registered callback. The samples collected before a callback is fired depends on the command which began the sampling operation. Registering the callback does not start or stop any sampling operations.
Callback signature: The signature of the callback depends on the command used to begin sampling operations. In all cases, the first argument is the type of ADC sampling operation that triggered this callback. If the operation provides individual samples (singly or repeatedly), the second argument will be the channel on which sampling occurred and the third argument will be the sample value. If the operation provides buffered samples (singly or repeatedly), the second argument will contain the channel index in the least significant 8 bits and the length of the buffer in the most significant 24 bits, while the third argument will be a pointer to the buffer filled with samples.
Returns: Ok(()) in all cases.
0Description: Provide a buffer into which samples values can be placed, replacing any previously provided buffer. This buffer will be used for any singly collected buffered data and will be used in addition to the second buffer for repeated buffered sampling. Future ADC operations will continue to use the same buffer.
Returns: Ok(()) in all cases.
1Description: Provide a buffer into which samples values can be placed when repeatedly buffered sampling, replacing any previously provided buffer. This buffer and the other provided buffer will be alternated between. Future ADC operations will continue to use the same buffer.
Returns: Ok(()) in all cases.