add to firmware documentation

main
Clyne 1 year ago
parent 82c3bedecb
commit f3c28dd2f1
Signed by: clyne
GPG Key ID: 1B74EE6C49C96795

@ -2,7 +2,7 @@
* @file communication.hpp * @file communication.hpp
* @brief Manages communication with the host computer. * @brief Manages communication with the host computer.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -17,9 +17,17 @@
class CommunicationManager class CommunicationManager
{ {
public: public:
/**
* Starts the communication manager thread (threadComm).
*/
static void begin(); static void begin();
private: private:
/**
* Continuously polls the USB serial connection, handling received commands
* as necessary.
* Does not return.
*/
static void threadComm(void *); static void threadComm(void *);
static std::array<char, 4096> m_thread_stack; static std::array<char, 4096> m_thread_stack;

@ -2,7 +2,7 @@
* @file conversion.hpp * @file conversion.hpp
* @brief Manages algorithm application (converts input samples to output). * @brief Manages algorithm application (converts input samples to output).
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -27,6 +27,10 @@ constexpr unsigned int CONVERSION_THREAD_STACK_SIZE =
class ConversionManager class ConversionManager
{ {
public: public:
/**
* Starts two threads: the privileged monitor thread and the unprivileged
* algorithm execution thread.
*/
static void begin(); static void begin();
// Begins sample conversion. // Begins sample conversion.

@ -2,7 +2,7 @@
* @file elf.h * @file elf.h
* @brief Defines ELF binary format info. * @brief Defines ELF binary format info.
* *
* Free to use, written by Clyne Sullivan. * Public domain, written by Clyne Sullivan.
*/ */
#ifndef STMDSP_ELF_HPP #ifndef STMDSP_ELF_HPP

@ -2,7 +2,7 @@
* @file elfload.hpp * @file elfload.hpp
* @brief Loads ELF binary data into memory for execution. * @brief Loads ELF binary data into memory for execution.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -24,9 +24,26 @@ class ELFManager
public: public:
using EntryFunc = Sample *(*)(Sample *, size_t); using EntryFunc = Sample *(*)(Sample *, size_t);
/**
* Attempts to parse the ELF binary loaded in the file buffer.
* Returns true if successful.
*/
static bool loadFromInternalBuffer(); static bool loadFromInternalBuffer();
/**
* Returns a function pointer to the loaded ELF's entry point.
* Returns nullptr if a valid ELF is not loaded.
*/
static EntryFunc loadedElf(); static EntryFunc loadedElf();
/**
* Returns the address of the ELF file buffer (copy ELF binary to here).
*/
static unsigned char *fileBuffer(); static unsigned char *fileBuffer();
/**
* "Unloads" the loaded binary by invalidating the entry pointer.
*/
static void unload(); static void unload();
private: private:

@ -2,7 +2,7 @@
* @file error.hpp * @file error.hpp
* @brief Tracks and reports non-critical errors. * @brief Tracks and reports non-critical errors.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -31,9 +31,25 @@ class ErrorManager
constexpr static unsigned int MAX_ERROR_QUEUE_SIZE = 8; constexpr static unsigned int MAX_ERROR_QUEUE_SIZE = 8;
public: public:
/**
* Adds the given error to the error queue.
*/
void add(Error error); void add(Error error);
/**
* If condition is false, add the given error to the error queue.
* Returns condition.
*/
bool assert(bool condition, Error error); bool assert(bool condition, Error error);
/**
* Returns true if the error queue is not empty.
*/
bool hasError(); bool hasError();
/**
* Returns the oldest error queue entry after removing it from the queue.
*/
Error pop(); Error pop();
private: private:

@ -2,7 +2,7 @@
* @file handlers.hpp * @file handlers.hpp
* @brief Interrupt service routine handlers. * @brief Interrupt service routine handlers.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -16,12 +16,15 @@
extern "C" { extern "C" {
// Service call handler ("svc" calls)
__attribute__((naked)) __attribute__((naked))
void port_syscall(struct port_extctx *ctxp, uint32_t n); void port_syscall(struct port_extctx *ctxp, uint32_t n);
// Handle memory faults possibly caused by the algorithm.
__attribute__((naked)) __attribute__((naked))
void MemManage_Handler(); void MemManage_Handler();
// Handle execution faults possibly caused by the algorithm.
__attribute__((naked)) __attribute__((naked))
void HardFault_Handler(); void HardFault_Handler();

@ -2,7 +2,7 @@
* @file monitor.hpp * @file monitor.hpp
* @brief Manages the device monitoring thread (status LEDs, etc.). * @brief Manages the device monitoring thread (status LEDs, etc.).
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -19,9 +19,15 @@
class Monitor class Monitor
{ {
public: public:
/**
* Starts the monitor thread.
*/
static void begin(); static void begin();
private: private:
/**
* Updates status LEDs. Does not return.
*/
static void threadMonitor(void *); static void threadMonitor(void *);
static std::array<char, THD_WORKING_AREA_SIZE(256)> m_thread_stack; static std::array<char, THD_WORKING_AREA_SIZE(256)> m_thread_stack;

@ -2,7 +2,7 @@
* @file adc.hpp * @file adc.hpp
* @brief Manages signal reading through the ADC. * @brief Manages signal reading through the ADC.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -22,18 +22,47 @@ class ADC
public: public:
using Operation = void (*)(adcsample_t *buffer, size_t count); using Operation = void (*)(adcsample_t *buffer, size_t count);
/**
* Initializes analog input pins and the microcontoller's ADC peripheral.
*/
static void begin(); static void begin();
/**
* Begins continuous ADC sampling triggered by SClock at the set sampling
* rate.
* @param buffer Pointer to buffer for sample data.
* @param count Number of samples that the buffer can hold.
* @param operation Handler function to operate on filled half-buffers.
*/
static void start(adcsample_t *buffer, size_t count, Operation operation); static void start(adcsample_t *buffer, size_t count, Operation operation);
/**
* Stops the continuous ADC sampling.
*/
static void stop(); static void stop();
/**
* Runs a single conversion on the "alt" inputs (parameter knobs).
* @param id The ID of the desired "alt" input (zero or one).
* @return The sampled value for the given input.
*/
static adcsample_t readAlt(unsigned int id); static adcsample_t readAlt(unsigned int id);
/**
* Sets the desired sampling rate for the ADC to operate at.
*/
static void setRate(SClock::Rate rate); static void setRate(SClock::Rate rate);
/**
* Used to override the handler function for the currently running
* conversion.
*/
static void setOperation(Operation operation); static void setOperation(Operation operation);
private: private:
// ADC driver for signal input.
static ADCDriver *m_driver; static ADCDriver *m_driver;
// ADC driver for "alt" inputs.
static ADCDriver *m_driver2; static ADCDriver *m_driver2;
static const ADCConfig m_config; static const ADCConfig m_config;

@ -1,3 +1,14 @@
/**
* @file cordic.cpp
* @brief Provides mathematical functions for algorithms.
*
* Copyright (C) 2023 Clyne Sullivan
*
* Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program.
* If not, see <https://www.gnu.org/licenses/>.
*/
#include "cordic.hpp" #include "cordic.hpp"
#include "hal.h" #include "hal.h"

@ -1,11 +1,33 @@
/**
* @file cordic.hpp
* @brief Provides mathematical functions for algorithms.
*
* Copyright (C) 2023 Clyne Sullivan
*
* Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program.
* If not, see <https://www.gnu.org/licenses/>.
*/
#ifndef CORDIC_HPP_ #ifndef CORDIC_HPP_
#define CORDIC_HPP_ #define CORDIC_HPP_
/**
* Named after the hardware CORDIC peripheral even though software
* implementations may be used.
*/
namespace cordic { namespace cordic {
// Provides pi in case cordic functions require it.
constexpr double PI = 3.1415926535L; constexpr double PI = 3.1415926535L;
/**
* Prepares cordic functions for use.
*/
void init(); void init();
// mod - Calculates remainder for given fraction.
// cos, sin, tan - The trig functions.
#if !defined(TARGET_PLATFORM_L4) #if !defined(TARGET_PLATFORM_L4)
double mod(double n, double d); double mod(double n, double d);

@ -2,7 +2,7 @@
* @file dac.hpp * @file dac.hpp
* @brief Manages signal creation using the DAC. * @brief Manages signal creation using the DAC.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -18,12 +18,35 @@
class DAC class DAC
{ {
public: public:
/**
* Initializes DAC output pins and peripheral.
*/
static void begin(); static void begin();
/**
* Begins continuous DAC conversion on the given channel, running at the
* current SClock sampling rate.
* @param channel Selected output channel (0 = sig. out, 1 = sig. gen.).
* @param buffer Buffer of sample data to output.
* @param count Number of samples in sample buffer.
*/
static void start(int channel, dacsample_t *buffer, size_t count); static void start(int channel, dacsample_t *buffer, size_t count);
/**
* Stops DAC conversion on the given channel.
*/
static void stop(int channel); static void stop(int channel);
/**
* Determines if signal generator needs more sample data for streamed
* output (i.e. audio file streaming).
* @return >0 if samples needed, <0 on initial run.
*/
static int sigGenWantsMore(); static int sigGenWantsMore();
/**
* Returns true if signal generator is currently running.
*/
static int isSigGenRunning(); static int isSigGenRunning();
private: private:

@ -2,7 +2,7 @@
* @file usbserial.hpp * @file usbserial.hpp
* @brief Wrapper for ChibiOS's SerialUSBDriver. * @brief Wrapper for ChibiOS's SerialUSBDriver.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -17,11 +17,30 @@
class USBSerial class USBSerial
{ {
public: public:
/**
* Prepares for USB serial communication.
*/
static void begin(); static void begin();
/**
* Returns true if input data has been received.
*/
static bool isActive(); static bool isActive();
/**
* Reads received input data into the given buffer.
* @param buffer Buffer to store input data.
* @param count Number of bytes to read.
* @return Number of bytes actually read.
*/
static size_t read(unsigned char *buffer, size_t count); static size_t read(unsigned char *buffer, size_t count);
/**
* Writes data to serial output.
* @param buffer Buffer of output data.
* @param count Number of bytes to write.
* @return Number of bytes actually written.
*/
static size_t write(const unsigned char *buffer, size_t count); static size_t write(const unsigned char *buffer, size_t count);
private: private:

@ -1,5 +1,4 @@
// Run status // Run status
//
enum class RunStatus : char enum class RunStatus : char
{ {
Idle = '1', Idle = '1',

@ -2,7 +2,7 @@
* @file samplebuffer.hpp * @file samplebuffer.hpp
* @brief Manages ADC/DAC buffer data. * @brief Manages ADC/DAC buffer data.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -20,25 +20,79 @@ using Sample = uint16_t;
constexpr unsigned int MAX_SAMPLE_BUFFER_BYTESIZE = sizeof(Sample) * 8192; constexpr unsigned int MAX_SAMPLE_BUFFER_BYTESIZE = sizeof(Sample) * 8192;
constexpr unsigned int MAX_SAMPLE_BUFFER_SIZE = MAX_SAMPLE_BUFFER_BYTESIZE / sizeof(Sample); constexpr unsigned int MAX_SAMPLE_BUFFER_SIZE = MAX_SAMPLE_BUFFER_BYTESIZE / sizeof(Sample);
/**
* Manages a buffer of sample data from the ADC or DAC with facilities to
* work with separate halves of the total buffer (which is necessary when
* streaming data to or from the buffer).
*/
class SampleBuffer class SampleBuffer
{ {
public: public:
// Manage the sample data memory at 'buffer'.
SampleBuffer(Sample *buffer); SampleBuffer(Sample *buffer);
/**
* Fill the current buffer with midpoint (2048/0V) values.
*/
void clear(); void clear();
/**
* Copy 'srcsize' samples from 'data' into the first half of the current
* buffer. Also do equivalent of setModified().
*/
void modify(Sample *data, unsigned int srcsize); void modify(Sample *data, unsigned int srcsize);
/**
* Copy 'srcsize' samples from 'data' into the second half of the current
* buffer. Also do equivalent of setMidmodified().
*/
void midmodify(Sample *data, unsigned int srcsize); void midmodify(Sample *data, unsigned int srcsize);
/**
* Set modified buffer pointer to first half of the current buffer.
*/
void setModified(); void setModified();
/**
* Set modified buffer pointer to second half of the current buffer.
*/
void setMidmodified(); void setMidmodified();
/**
* Return pointer to most recently modified buffer portion.
* Clears this internal pointer when called.
*/
Sample *modified(); Sample *modified();
/**
* Returns pointer to first half of current buffer.
*/
Sample *data(); Sample *data();
/**
* Returns pointer to second half of current buffer.
*/
Sample *middata(); Sample *middata();
/**
* Returns uint8_t-casted pointer to the current buffer.
*/
uint8_t *bytedata(); uint8_t *bytedata();
/**
* Sets the total working size of the current buffer. Current buffer must
* be able to accommodate.
*/
void setSize(unsigned int size); void setSize(unsigned int size);
/**
* Returns the current total working size (number of samples).
*/
unsigned int size() const; unsigned int size() const;
/**
* Returns the current total working size (number of bytes).
*/
unsigned int bytesize() const; unsigned int bytesize() const;
private: private:

@ -2,7 +2,7 @@
* @file samples.hpp * @file samples.hpp
* @brief Provides sample buffers for inputs and outputs. * @brief Provides sample buffers for inputs and outputs.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -14,6 +14,8 @@
#include "samplebuffer.hpp" #include "samplebuffer.hpp"
// Define sample buffers for the input and output signals and the signal
// generator.
class Samples class Samples
{ {
public: public:

@ -2,7 +2,7 @@
* @file sclock.hpp * @file sclock.hpp
* @brief Manages sampling rate clock speeds. * @brief Manages sampling rate clock speeds.
* *
* Copyright (C) 2021 Clyne Sullivan * Copyright (C) 2023 Clyne Sullivan
* *
* Distributed under the GNU GPL v3 or later. You should have received a copy of * Distributed under the GNU GPL v3 or later. You should have received a copy of
* the GNU General Public License along with this program. * the GNU General Public License along with this program.
@ -19,6 +19,7 @@
class SClock class SClock
{ {
public: public:
// These are the supported sampling rates. GUI keeps its own enumeration.
enum class Rate : unsigned int { enum class Rate : unsigned int {
R8K = 0, R8K = 0,
R16K, R16K,
@ -28,11 +29,32 @@ public:
R96K R96K
}; };
/**
* Initializes the sample clock hardware.
*/
static void begin(); static void begin();
/**
* Starts the sample rate clock if it is not already running.
*/
static void start(); static void start();
/**
* Indicate that the caller no longer needs the sample clock.
* This decrements an internal counter that is incremented by start()
* calls; if the counter reaches zero, the clock will actually stop.
*/
static void stop(); static void stop();
/**
* Sets the desired sampling rate, used for the next start() call.
*/
static void setRate(Rate rate); static void setRate(Rate rate);
/**
* Gets the desired sampling rate (SClock::Rate value) casted to an
* unsigned int.
*/
static unsigned int getRate(); static unsigned int getRate();
private: private:

Loading…
Cancel
Save