mirror/gossamer
3
0
Fork 0
mirror of https://github.com/joeycastillo/gossamer.git synced 2025-10-29 11:10:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

big doxygen improvements

Browse Source
This commit is contained in:
joeycastillo 2024-10-14 20:50:36 -04:00
parent 9f4ca52184
commit bc5829b32a
25 changed files with 251 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Doxyfile
View File

@ -122,7 +122,8 @@ INPUT = ./common \
./drivers \
./peripherals \
./main.c \
./README.md
./README.md \
./mainpage.md
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c \
*.cc \
@ -209,11 +210,7 @@ HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_EXTRA_STYLESHEET =
HTML_EXTRA_FILES =
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80
HTML_TIMESTAMP = NO
HTML_DYNAMIC_MENUS = YES
HTML_DYNAMIC_SECTIONS = NO
@ -240,8 +237,6 @@ QHP_SECT_FILTER_ATTRS =
QHG_LOCATION =
GENERATE_ECLIPSEHELP = NO
ECLIPSE_DOC_ID = org.doxygen.Project
DISABLE_INDEX = NO
GENERATE_TREEVIEW = NO
ENUM_VALUES_PER_LINE = 4
TREEVIEW_WIDTH = 250
EXT_LINKS_IN_WINDOW = NO
@ -336,7 +331,11 @@ SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED = OPAMP \
DAC
DAC \
SLCD \
I2S \
HAS_PTC \
APP_USES_TINYUSB
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
@ -386,4 +385,12 @@ MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration options related to doxygen-awesome
#---------------------------------------------------------------------------
GENERATE_TREEVIEW = YES # optional. Also works without treeview
DISABLE_INDEX = NO
FULL_SIDEBAR = NO
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5

2
README.md
View File

@ -1,4 +1,4 @@
/// @mainpage
@title README
gossamer: a very lightweight firmware framework for SAMD and SAML chips
=======================================================================

12
common/adc.h
View File

@ -1,7 +1,4 @@
/**
* @file adc.h
* @brief Analog to Digital Converter
*/
////< @file adc.h
/*
* MIT License
*
@ -32,6 +29,11 @@
#include <stdbool.h>
/**
* @addtogroup adc Analog to Digital Converter
* @brief Functions for using the ADC peripheral
* @{
*/
/**
* @brief Initializes the ADC peripheral, but does not enable it.
* @details This function sets up some sensible defaults for basic use cases:
@ -86,3 +88,5 @@ uint16_t adc_get_analog_value_for_channel(uint8_t channel);
* @brief Disables the ADC peripheral
*/
void adc_disable(void);
/** @} */

21
common/app.h
View File

@ -1,7 +1,4 @@
/**
* @file app.h
* @brief Gossamer application framework
*/
////< @file app.h
/*
* MIT License
*
@ -35,6 +32,14 @@
#include "sam.h"
#include "pins.h"
/** @addtogroup app Gossamer application framework
* @brief This section describes the application framework that you will use to write your firmware.
* @details All Gossamer applications are built by implementing the three functions described in this section.
* There is an optional fourth function that relates to the SAM L21 and L22's BACKUP mode,
* but you do not need to implement it unless you are using the BACKUP mode functionality.
* @{
*/
/** @brief A function you will implement to initialize your application's low-
* level setup. The app_init function is called after system clocks are
* initialized, and before anything else.
@ -45,9 +50,9 @@
* some peripherals before entering STANDBY mode, and re-enable them
* after waking up. In essence, you should set up anything that will
* run forever in app_init, whereas anything that could get turned off
* in the course of execution should be set up in app_setup.
* @note If your application plans to use the real-time clock perhiperal, you
* probably want to call the `rtc_init` function here.
* in the course of execution should be set up in app_setup. If your
* application plans to use the real-time clock perhiperal, you probably
* want to call the `rtc_init` function here.
*/
void app_init(void);
@ -87,3 +92,5 @@ bool app_loop(void);
* any other USB-related tasks you need to run.
*/
void yield(void);
/** @} */

13
common/dac.h
View File

@ -1,7 +1,4 @@
/**
* @file dac.h
* @brief Digital to Analog Converter
*/
////< @file dac.h
/*
* MIT License
*
@ -31,6 +28,12 @@
#include <stdint.h>
#include <stdbool.h>
/**
* @addtogroup dac Digital to Analog Converter
* @brief Functions for configuring and using the DAC peripheral.
* @{
*/
// channel mask enum for dac_enable
typedef enum {
DAC_CHANNEL_NONE = 0,
@ -69,3 +72,5 @@ void dac_set_analog_value(uint16_t channel, uint16_t value);
* @warning Currently only supports the DAC on VOUT[0]
*/
void dac_disable(uint16_t channel);
/** @} */

11
common/delay.h
View File

@ -1,13 +1,16 @@
/**
* @file delay.h
* @brief Delay routines
*/
////< @file delay.h
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#pragma once
/**
* @brief delay Delay routines
* @brief Functions for delaying execution using the SYSTICK peripheral.
* @{
*/
/**
* @brief Initializes the system tick peripheral. This is required to use the delay functions.
* @details The system tick only runs while the CPU is running, and does not fire in STANDBY mode.

9
common/dma.h
View File

@ -1,3 +1,4 @@
////< @file dma.h
/*
* MIT License
*
@ -35,6 +36,12 @@
#include <stdbool.h>
#include "dma_util.h"
/**
* @addtogroup dma Direct Memory Access Controller
* @brief WIP functions for configuring and using the Direct Memory Access controller.
* @{
*/
#ifndef _SAMD51_
typedef struct {
@ -104,3 +111,5 @@ DmacDescriptor *dma_add_descriptor(gossamer_dma_job_t *dmaJob, void *src, void *
bool dma_start_job(gossamer_dma_job_t *dmaJob);
#endif
/** @} */

5
common/dma_util.h
View File

@ -1,5 +1,4 @@
#ifndef DMA_UTIL_H_INCLUDED
#define DMA_UTIL_H_INCLUDED
#pragma once
#include "sam.h"
@ -106,5 +105,3 @@ typedef enum {
} dma_status_t;
#endif
#endif // DMA_UTIL_H_INCLUDED

13
common/eic.h
View File

@ -1,7 +1,4 @@
/**
* @file eic.h
* @brief External Interrupt Controller
*/
////< @file eic.h
/*
* MIT License
*
@ -31,6 +28,12 @@
#include <stdint.h>
#include <stdbool.h>
/**
* @addtogroup eic External Interrupt Controller
* @brief Functions for configuring and using the External Interrupt Controller.
* @{
*/
///@brief An enum defining the types of interrupt trigger you wish to scan for.
typedef enum eic_interrupt_trigger_t {
INTERRUPT_TRIGGER_NONE = 0,
@ -93,3 +96,5 @@ void eic_configure_callback(eic_cb_t callback);
/** @brief Disables the external interrupt controller.
*/
void eic_disable(void);
/** @} */

15
common/evsys.h
View File

@ -1,8 +1,4 @@
/**
* @file evsys.h
* @brief Event System
* @note The Event System has no _init or _enable functions. It is always running.
*/
////< @file evsys.h
/*
* MIT License
*
@ -32,6 +28,13 @@
#include <stdint.h>
#include <stdbool.h>
/**
* @addtogroup evsys Event System
* @brief Functions for configuring and using the Event System.
* @note The Event System has no _init or _enable functions. It is always running.
* @{
*/
/**
* @brief Configures an event channel to route an event from a generator to a user.
* @param channel The event channel to configure. The number of channels varies by device, but all should have at least six channels.
@ -41,3 +44,5 @@
* @param asynchronous Whether the event should use the asynchronous path or the synchronous path.
*/
void evsys_configure_channel(uint8_t channel, uint8_t generator, uint8_t user, bool run_in_standby, bool asynchronous);
/** @} */

4
common/hal_gpio.h
View File

@ -1,7 +1,3 @@
/**
* @file hal_gpio.h
* @brief GPIO Macros
*/
/*
* Copyright (c) 2014-2016, Alex Taradov <alex@taradov.com>
* All rights reserved.

13
common/i2c.h
View File

@ -1,7 +1,4 @@
/**
* @file i2c.h
* @brief I2C Peripheral
*/
////< @file i2c.h
/*
Cribbed from the Castor & Pollux Gemini firmware:
https://github.com/wntrblm/Castor_and_Pollux/
@ -18,6 +15,12 @@
#include <stdbool.h>
#include <stddef.h>
/**
* @addtogroup i2c Inter-IC Communications Peripheral
* @brief The I2C peripheral is used for communication with I2C devices over SDA and SCL pins.
* @{
*/
typedef enum {
I2C_RESULT_SUCCESS = 0,
I2C_RESULT_ERR_ADDR_NACK = -1,
@ -100,3 +103,5 @@ i2c_result_t i2c_read_instance(uint8_t sercom, uint8_t address, uint8_t* data, s
* @param sercom The SERCOM of the I2C peripheral, as numbered in the data sheet.
*/
void i2c_disable_instance(uint8_t sercom);
/** @} */

13
common/i2s.h
View File

@ -1,7 +1,4 @@
/**
* @file i2s.h
* @brief Inter-IC Sound interface (SAM D21 only)
*/
////< @file i2s.h
/*
* MIT License
*
@ -32,6 +29,12 @@
#include <stdbool.h>
#include "sam.h"
/**
* @addtogroup i2s Inter-IC Sound interface
* @brief Functions for configuring and using the I2S peripheral (SAM D21 only).
* @{
*/
#ifdef I2S
typedef enum {
@ -53,3 +56,5 @@ void i2s_init(uint8_t instance, uint16_t sampleRate, uint8_t bitsPerSample, i2s_
void i2s_enable_receiver(uint8_t instance);
#endif
/** @} */

15
common/opamp.h
View File

@ -1,7 +1,4 @@
/**
* @file opamp.h
* @brief Operational Amplifier Peripheral
*/
////< @file opamp.h
/*
* MIT License
*
@ -31,6 +28,12 @@
#include <stdint.h>
#include <stdbool.h>
/**
* @addtogroup opamp Operational Amplifier
* @brief Functions for configuring and using the operational amplifier on the SAM L21.
* @{
*/
#ifdef OPAMP
#define OPAMP_MUXNEG_NEG (0)
@ -169,4 +172,6 @@ void opamp_set_analog_connection(uint16_t instance, bool connected);
*/
void opamp_disable(uint16_t instance);
#endif
#endif
/** @} */

14
common/ptc.h
View File

@ -1,7 +1,4 @@
/**
* @file ptc.h
* @brief Peripheral Touch Controller
*/
////< @file ptc.h
/*
* FreeTouch, a QTouch-compatible library - tested on ATSAMD21 only!
* The MIT License (MIT)
@ -33,6 +30,13 @@
#include <stdint.h>
#include "sam.h"
/**
* @addtogroup ptc Peripheral Touch Controller
* @brief Functions for configuring and using the Peripheral Touch Controller.
* @details Based on Adafruit's FreeTouch library.
* @{
*/
#ifdef _SAMD21_
#include "component/samd21_ptc_component.h"
#define HAS_PTC 1
@ -111,3 +115,5 @@ void ptc_enable(uint8_t channel);
uint16_t ptc_get_value(uint8_t channel);
#endif
/** @} */

14
common/rtc.h
View File

@ -1,7 +1,4 @@
/**
* @file rtc.h
* @brief Real-Time Clock
*/
////< @file rtc.h
/*
* MIT License
*
@ -31,6 +28,13 @@
#include <stdint.h>
#include <stdbool.h>
/**
* @addtogroup rtc Real-Time Clock
* @brief Functions for configuring and using the Real-Time Clock peripheral.
* @details Gossamer supports use of the RTC peripheral in MODE2 (calendar) mode only.
* @{
*/
#define RTC_REFERENCE_YEAR (2020)
typedef union {
@ -102,3 +106,5 @@ void rtc_disable_alarm_interrupt(void);
* of the RTC peripheral's INTFLAG register.
*/
void rtc_configure_callback(rtc_cb_t callback);
/** @} */

4
common/sercom.h
View File

@ -1,7 +1,3 @@
/**
* @file sercom.h
* @brief Private functions for helping with SERCOM management.
*/
/*
* MIT License
*

15
common/slcd.h
View File

@ -1,7 +1,4 @@
/**
* @file slcd.h
* @brief Segment Liquid Crystal Display (SLCD) peripheral driver (SAM L22 only)
*/
////< @file slcd.h
/*
* MIT License
*
@ -33,6 +30,12 @@
#include <stddef.h>
#include "system.h"
/**
* @addtogroup slcd Segment LCD driver
* @brief Functions for configuring and using the SAM L22's Segment LCD peripheral.
* @{
*/
#ifdef SLCD
typedef enum {
@ -232,4 +235,6 @@ void slcd_set_circular_shift_animation_enabled(bool enabled);
void slcd_disable(void);
#endif // SLCD
#endif // SLCD
/** @} */

13
common/spi.h
View File

@ -1,7 +1,4 @@
/**
* @file spi.h
* @brief SPI Peripheral
*/
////< @file spi.h
/*
Cribbed from the Castor & Pollux Gemini firmware:
https://github.com/wntrblm/Castor_and_Pollux/
@ -16,6 +13,12 @@
#include <stdbool.h>
#include <stddef.h>
/**
* @addtogroup spi SPI Peripheral
* @brief The SPI peripheral is used for synchronous serial communication with other devices.
* @{
*/
typedef enum {
SPI_MODE_PERIPHERAL = 2,
SPI_MODE_CONTROLLER = 3,
@ -91,3 +94,5 @@ uint8_t spi_transfer_instance(uint8_t sercom, uint8_t data);
* @param sercom The SERCOM instance to disable.
*/
void spi_disable_instance(uint8_t sercom);
/** @} */

13
common/system.h
View File

@ -1,7 +1,3 @@
/**
* @file system.h
* @brief Gossamer system routines
*/
/*
* MIT License
*
@ -74,7 +70,12 @@ extern const uint8_t Num_SERCOM_Instances;
////< @file system.h
/// @{
/**
* @addtogroup system System Internals
* @brief Functions for configuring the system and putting it in standby mode.
* @{
*/
/** @brief Initializes the system clocks and performs any required system-wide setup.
* @details Gossamer aims for consistency at system startup, no matter which
* chip you are working with. To that end:
@ -130,4 +131,4 @@ void _enable_48mhz_gclk1(void);
*/
void _enter_standby_mode(void);
/// @}
/** @} */

13
common/tc.h
View File

@ -1,7 +1,4 @@
/**
* @file tc.h
* @brief Timer/Counter Peripheral
*/
////< @file tc.h
/*
* MIT License
*
@ -33,6 +30,12 @@
#include "sam.h"
#include "system.h"
/**
* @addtogroup tc Timer/Counter
* @brief Functions for configuring and using the Timer/Counter peripherals.
* @{
*/
typedef enum {
TC_PRESCALER_DIV1 = 0,
TC_PRESCALER_DIV2 = 1,
@ -291,3 +294,5 @@ void tc_retrigger(uint8_t instance);
* @param instance The TC peripheral instance as numbered in the data sheet, or 0.
*/
void tc_disable(uint8_t instance);
/** @} */

13
common/tcc.h
View File

@ -1,7 +1,4 @@
/**
* @file tcc.h
* @brief Timer/Counter for Control Applications (TCC) Peripheral
*/
////< @file tcc.h
/*
* MIT License
*
@ -32,6 +29,12 @@
#include <stdbool.h>
#include "sam.h"
/**
* @addtogroup tcc Timer/Counter for Control Applications
* @brief Functions for configuring and using the TCC peripheral, a more advanced timer/counter.
* @{
*/
typedef enum {
TCC_PRESCALER_DIV1 = 0,
TCC_PRESCALER_DIV2 = 1,
@ -233,3 +236,5 @@ void tcc_update(uint8_t instance);
* @param instance The TCC peripheral instance as numbered in the data sheet, or 0.
*/
void tcc_disable(uint8_t instance);
/** @} */

55
common/uart.h
View File

@ -1,16 +1,26 @@
/**
* @file uart.h
* @brief UART Peripheral
* @details The UART peripheral is used for serial communication over TX and RX pins.
* Note that Gossaermer's UART implementation is interrupt-driven, which is
* different from the SPI and I2C peripherals. If you want to use the UART,
* you MUST implement the following function, replacing 'N' with the SERCOM
* number you are using:
* ```void irq_handler_sercomN(void) { uart_irq_handler(N); }```
* This interrupt handler will allow the UART to buffer incoming data to a
* FIFO, which is what you're actually reading from when you call `uart_read`.
* @warning If you don't implement the interrupt handler, your application will hang,
* and you'll be confused until you read this line! (or in my case, write it)
////< @file uart.h
/*
* MIT License
*
* Copyright (c) 2024 Joey Castillo
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#pragma once
@ -19,6 +29,22 @@
#include <stdbool.h>
#include <stddef.h>
/**
* @addtogroup uart UART Peripheral
* @brief The UART peripheral is used for serial communication over TX and RX pins.
* @details Note that Gossaermer's UART implementation is interrupt-driven, which is
* different from the SPI and I2C peripherals. If you want to use the UART,
* you MUST implement the following function, replacing 'N' with the SERCOM
* number you are using:
* ```void irq_handler_sercomN(void) { uart_irq_handler(N); }```
* This interrupt handler will allow the UART to buffer incoming data to a
* FIFO, which is what you're actually reading from when you call `uart_read`.
* @warning If you don't implement the interrupt handler, your application will hang,
* and you'll be confused until you read this line! (or in my case, write it)
* @{
*/
/// @brief UART transmit pinout options
typedef enum {
UART_TXPO_0 = 0,
UART_TXPO_2,
@ -26,6 +52,7 @@ typedef enum {
UART_TXPO_NONE = 0xff
} uart_txpo_t;
/// @brief UART receive pinout options
typedef enum {
UART_RXPO_0 = 0,
UART_RXPO_1,
@ -153,3 +180,5 @@ void uart_disable_instance(uint8_t sercom);
* @param sercom SERCOM number
*/
void uart_irq_handler(uint8_t sercom);
/** @} */

10
common/usb.h
View File

@ -1,3 +1,4 @@
////< @file usb.h
/*
* MIT License
*
@ -30,6 +31,13 @@
#include <stdbool.h>
#include "tusb.h"
/**
* @addtogroup usb Universal Serial Bus
* @brief Functions for configuring and using the USB peripheral.
* @details Gossamer uses the TinyUSB stack for USB support.
* @{
*/
/** @brief Initializes the USB preipheral, and assigns the USB pins to their
* relevant functions. In the process, this function also sets up the
* 48 MHz DFLL clock on GCLK1.
@ -71,4 +79,6 @@ bool usb_is_enabled(void);
*/
void usb_disable(void);
/** @} */
#endif

23
mainpage.md Normal file
View File

@ -0,0 +1,23 @@
@mainpage
Gossamer is an extremely lightweight framework for developing bare-metal firmware applications for the Microchip SAM D and SAM L series chips. Before you get started, you might want to take a look at the \ref README.md.
After that, you can get a sense for how to implement an app with the \ref app.
You'll also want to know some stuff about the \ref system.
From there, check out all the peripherals available on most chips:
* \ref adc
* \ref dac
* \ref eic
* \ref i2c
* \ref rtc
* \ref spi
* \ref uart
* \ref usb
There are also special peripherals that are only available on certain chips:
* The \ref slcd on the SAM L22
* The \ref opamp on the SAM L21