#[non_exhaustive]pub enum Error {
Show 38 variants
Init(i32),
Start(i32),
CallbackFaults(u32),
TaskName,
TaskUnavailable,
TaskCreate,
TaskCreateWhileStopping,
CpuMonitoring,
CpuMonitoringCycle(u32),
CpuMonitoringPeriodSize(u32),
AudioSystemExists,
AudioSystemPoisoned,
CommandLine(i32),
CommandLineNul,
SampleRate,
SettingsRefused(&'static str),
PruNumber(i32),
MultiplexerChannels(i32),
MultiplexerPru(i32),
MultiplexerWithoutAnalog,
MultiplexerAnalogChannels(i32),
LineOutLevel(i32),
HeadphoneLevel(i32),
AudioInputGain(i32),
MuteSpeakers(i32),
MidiPortName,
MidiUnavailable,
MidiCreate,
MidiOpen(i32),
MidiValue {
value: u16,
max: u16,
kind: &'static str,
},
MidiQueueFull,
MidiThread,
FftUnavailable,
FftCreate {
length: usize,
},
FftSignalLen {
expected: usize,
actual: usize,
},
FftSpectrumLen {
expected: usize,
actual: usize,
},
FftLength {
value: usize,
},
Decibels,
}Expand description
Errors returned by the Bela audio system lifecycle.
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
Init(i32)
Bela_initAudio failed with the contained return code.
The initialisation it failed partway through is not undone, so
this is fatal to the process rather than to the one attempt:
every later Bela::new returns
AudioSystemPoisoned.
Start(i32)
Bela_startAudio failed with the contained return code.
CallbackFaults(u32)
The run ended with the contained number of callbacks refused for breaking the protocol the render states rely on.
libbela made a callback somewhere the crate could not hand out
the references BelaApplication
promises — several render calls with the same thread number,
or a render_post arriving while one was still in flight, which
a stop requested mid-block can produce. Each such callback was
skipped and a stop requested, so the audio that was rendered is
sound and the run ended early rather than going wrong.
Reported by Bela::until_stopped
and the run methods built on it, so that a run which ended
this way is not mistaken for one that was asked to stop. See
Bela::callback_faults.
TaskName
An auxiliary task name contained a NUL byte.
This build has no libbela, so no auxiliary task can be
created.
Off the device target only, where the library is not linked. Says nothing about the name or the board: a device build never sees it.
TaskCreate
Bela_createAuxiliaryTask failed.
A board declining to create the task — told apart from
TaskUnavailable because the two are
recovered from differently: this one is worth reporting to
whoever is holding the board, and that one is what every host
build says.
TaskCreateWhileStopping
An auxiliary task was created while an audio system was being torn down, which would have deleted it again immediately.
This is what a cleanup callback gets: it runs inside that
teardown.
CpuMonitoring
Bela_cpuMonitoringInit failed.
CpuMonitoringCycle(u32)
The requested CPU monitoring acquisition cycle does not fit in a
C int, which is how libbela takes it.
CpuMonitoringPeriodSize(u32)
CPU monitoring was requested with a period size outside the
range where libbela runs render on the thread it measures.
AudioSystemExists
Another Bela audio system already exists in
this process.
The C API is a process-wide singleton, so a second one would share — and reset — the state the first is using.
AudioSystemPoisoned
An earlier Bela_initAudio in this process failed partway
through, and no audio system can be built after that.
libbela is left believing the audio system is up and offers no
way to put it back: Bela_cleanupAudio segfaults on that path.
So this is refused rather than attempted — going ahead means a
segfault inside libbela, which is what the error replaces.
Terminal for the process, and only for the process: the board is
untouched, so a new one gets a working audio system straight
away. See Bela::new.
CommandLine(i32)
An argument was not one of Bela’s standard command-line options.
Carries what Bela_getopt_long returned: '?' for an
unrecognised option or one missing its value, which getopt has
already reported on standard error naming the argument, or an
internal option code when libbela rejected a standard option it
did recognise — a --json-file it could not read, say.
CommandLineNul
A command-line argument contained a NUL byte, which a C string cannot carry.
SampleRate
The settings resolved to an audio sample rate of zero, which libbela reports as a codec that is not enabled.
Zero is the only rate refused here, which is why this carries
nothing: --sample-rate reads its value with atof, so
anything that is not a number arrives as 0, and a negative rate
is clamped to the same 0 by the parser. The message libbela
prints for it — Error: audio sampling rate is 0. Is the codec enabled?, followed by one about a cape — describes hardware for
a number the command line supplied.
One of the checks Bela::new_with_args
makes before Bela_initAudio, where this would otherwise be an
Init that costs the process every later audio
system.
SettingsRefused(&'static str)
The application refused the resolved settings, with the reason it gave.
What
BelaApplication::validate_settings
returned Err with, carried as it stands. That hook is asked
once the settings are fully resolved and before anything has
been done about them, so this costs the attempt and nothing
else: the process can go on to build an audio system with
settings the application does accept.
A &'static str rather than a message of the application’s own
making, which keeps this type Copy and allocation-free — an
application that needs to carry more than a sentence out of a
refusal can put it somewhere of its own before returning.
PruNumber(i32)
The settings named a PRU other than 0 or 1, which are the two libbela can run the audio code on.
Checked before Bela_initAudio, which refuses the same values
and leaves the process unable to build another audio system.
MultiplexerChannels(i32)
The settings asked for a number of multiplexer channels libbela does not take: it accepts 0, which is off, and 2, 4 or 8.
Checked before Bela_initAudio; see
Bela::new_with_args for what the
crate does and does not check about --mux-channels.
MultiplexerPru(i32)
The multiplexer was asked for while the audio code was pointed at a PRU other than 1, carried here.
PRU 0 is a valid setting on its own; only the multiplexer needs PRU 1, which is why the two are separate errors.
MultiplexerWithoutAnalog
The multiplexer was asked for with the analog inputs disabled.
This is the combination that gets past every check libbela makes
on the ARM side and dies in the PRU firmware instead — Invalid PRU configuration settings, PRU timeout, McASP error, abort, with the process ending from inside libbela and nothing
returned to the caller. Refusing it beforehand is the only place
it can be reported at all.
MultiplexerAnalogChannels(i32)
The multiplexer was asked for with a number of analog input channels other than the 8 it needs, carried here.
--analog-channels snaps what it is given to 8, 4 or 2, so this
reports the number the settings resolved to rather than the one
that was written on the command line. It is not only about
asking for too few:
Settings::num_analog_in_channels
is passed on as it stands, and 16 is as much a refusal as 4.
Checked before Bela_initAudio, which refuses the same thing in
PRU::initialise and leaves the process unable to build another
audio system.
LineOutLevel(i32)
Bela_setLineOutLevel failed with the contained return code,
e.g. for a channel the codec does not have.
HeadphoneLevel(i32)
Bela_setHpLevel failed with the contained return code, e.g.
for a channel the codec does not have.
AudioInputGain(i32)
Bela_setAudioInputGain failed with the contained return code.
MuteSpeakers(i32)
Bela_muteSpeakers failed with the contained return code.
MidiPortName
A MIDI port name contained a NUL byte.
This build has no libbelaextra, so no MIDI port can be opened.
Off the device target only, where the library is not linked. Says nothing about the port or the board: a device build never sees it.
MidiCreate
A Midi object could not be created.
The shim’s allocation failed, which is a board reporting that it
would not give this program a Midi object — told apart from
MidiUnavailable because the two are
recovered from differently: this one is worth reporting to
whoever is holding the board, and that one is what every host
build says.
MidiOpen(i32)
A MIDI port could not be opened, with what the shim reported.
bela_sys::BELA_MIDI_NO_SUCH_PORT for a name no port has —
the names are the ones midi_ports lists,
which carry the subdevice — and a negative errno when ALSA
refused the device itself, -16 for a port something else
already holds. The two are told apart rather than sharing -1,
which would be the first of them and EPERM.
bela_sys::BELA_MIDI_ALREADY_OPEN is the third value the
shim can report and cannot arrive here: this crate opens each
port on an object of its own, and drops it when the open fails.
MidiValue
A MIDI value did not fit the type it was converted into.
Carries what was given, the largest that type takes — 127 for a data byte, 15 for a channel, 16383 for a pitch bend — and what the type is. The wire has no room for more, and masking the extra bits off would turn a number that was wrong into a different number that is not.
The name is there because a note and a velocity are two numbers in the same range, which is the whole reason they are separate types: an error that only said “127” would put them back together.
Fields
MidiQueueFull
A render thread queued more MIDI messages between drains than
MidiOutput::capacity allows.
The message was not queued, and nothing else was affected. This says the program outran the budget it declared and nothing about the device: neither Bela’s output pipe nor ALSA reports anything this crate could pass on.
MidiThread
MIDI was sent from a thread that cannot send it.
MidiOutput::send and
flush write to Bela’s pipe through
an EVL out-of-band call, which only a thread EVL knows about can
make. This crate’s answer is the thread that opened the port: a
write from any other reports success, delivers nothing, and
leaves the output stream misaligned for the rest of the run, so
it is refused instead.
This build has no NE10, so no FFT can be planned.
Off the device target only, where the library is not linked. Says nothing about the length or the board: a device build never sees it.
Meeting this while trying to test DSP on a laptop is expected,
and RealFft documents the way around it: a
trait the program owns, with a host implementation beside the
device one.
FftCreate
NE10 declined to build a plan of the contained length.
An allocation failure, since the length reaching it is already
one it takes — FftLength is what rules
the rest out. The length is carried because ? is where it
would otherwise be lost.
FftSignalLen
A transform was given a signal buffer of the wrong length.
Exact, not “at least”: a longer buffer is refused too, because a caller who sized one differently meant something by it. The call did nothing, and both buffers are as they were.
FftSpectrumLen
A transform was given a spectrum buffer of the wrong length.
Told apart from FftSignalLen because
the two are recovered from differently — one resizes a window,
the other a spectrum — and a caller that wants to tell them
apart should not have to compare strings to do it.
FftLength
A transform length that is not one this crate supports.
What FftLength::try_from answers with;
FftLength::new says the same thing
with None. A power of two from 8 to 65536 is the range, and
the bottom of it is where NE10 stops writing inside the buffers
it is given rather than a matter of taste.
Decibels
A level or gain was not a number of decibels libbela can convert
into register values: not finite, or larger in magnitude than
MAX_DECIBELS.
The conversion on the C side is a cast to int, which is
undefined behaviour for those values, so they are refused before
the call rather than passed on.
Trait Implementations§
impl Copy for Error
impl Eq for Error
Source§impl Error for Error
impl Error for Error
1.30.0 · Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()