AVR Driver Documentation Updates (#285)

MegaAVR and OnBoardLED driver documentation.

Issue: #284

.vscode/settings.json

@@ -20,15 +20,14 @@
     "editor.trimAutoWhitespace": true,
     "editor.autoClosingQuotes": "always",
     "editor.autoClosingBrackets": "always",
-    "editor.wordBasedSuggestions": true,
+    "editor.wordBasedSuggestions": "matchingDocuments",
     "editor.insertSpaces": false,
     "editor.autoIndent": "advanced",
     "editor.detectIndentation": true,
     "editor.codeLens": true,
     "editor.columnSelection": false,
     "editor.colorDecorators": true,
     "editor.cursorBlinking": "blink",
-    "editor.lightbulb.enabled": true,
     "editor.lineNumbers": "on",
     "editor.suggest.showFunctions": true,
     "diffEditor.codeLens": true,

projects/demo_avr_cpp/gpio.cpp

@@ -16,18 +16,31 @@ extern "C"
 
 #include "gpio.h"
 
-/* Outside declaration of the member function of class onBoardLed */
+/* Outside declaration of the member function of class onBoardLed: Utilized by the specific register allocation for the onboard LED */
 onBoardLed::onBoardLed()
 {
 	gpio_pin_alloc(&led13, PORTB, 5);
 }
 
+/**
+ * @brief the setting up of the onboard-LED
+ *
+ * This function configures the specific GPIO pin for the onboard-LED as an output
+ * This function also sets the LED state to low (off)
+ */
+
 void onBoardLed::setup()
 {
 	gpio_pin_mode(&led13, out);
 	gpio_pin_clear(&led13);
 }
 
+/**
+ * @brief The toggling of the onboard LED
+ *
+ * This function toggles the state of the onboard LED on and off
+ */
+
 void onBoardLed::toggle()
 {
 	gpio_pin_toggle(&led13);

projects/demo_avr_cpp/gpio.h

@@ -10,6 +10,13 @@
 
 #pragma once
 
+/**
+ * @brief Class representing an on-board LED controlled via GPIO.
+ *
+ * This class provides methods to initialize the LED, set it up as an output,
+ * and toggle its state.
+ */
+
 class onBoardLed
 {
 	private:

projects/demo_avr_cpp/project.cpp

@@ -21,15 +21,15 @@ extern "C"
 	#include <hal/gpio.h>
 }
 
-#include "gpio.h"
+#include "gpio.h" // This has custom GPIO header functions
 
 
-class onBoardLed led;
+class onBoardLed led; 
 
 /* Use EXPORT_C macro for calling cpp function in c file */
 EXPORT_C(void plug())
 {
-	bootstrap();
+	bootstrap(); // calls the system initial bootstrap
 	driver_setup_all();
 
 	/* call the constructor and setup member of led object */
@@ -47,13 +47,13 @@ void delay(unsigned long d)
 {
 	unsigned long c;
 	for(c = 0; c < d; c++)
-		asm volatile("nop");
+		asm volatile("nop"); // provides the assembly instructions to create a general delay
 }
 
 static unsigned char i = 0;
-EXPORT_C(void play())
+EXPORT_C(void play()) // the calling of the continues function check
 {
-	wdog_guard(WDT_64MS, true, NULL);
+	wdog_guard(WDT_64MS, true, NULL); // safety feature if the core hangs or creates interruptions
 
 	/* call the toggle member of led object */
 	led.toggle();

src/driver/onboardled/onboardled.c

@@ -23,6 +23,15 @@ static gpio_port_t *obledPort;
 static swdev_t *obled_sp;
 static lock_t obledlock;
 
+/**
+ * @brief Toggle the state of the onboard LED.
+ *
+ * This function toggles the state of the onboard LED by each GPIO pin
+ * It also works accordinlg with locks to protect the state
+ *
+ * @return status_t: Status of the operation
+ */
+
 status_t onboardled_toggle(void)
 {
 	status_t ret = success;
@@ -39,6 +48,14 @@ status_t onboardled_toggle(void)
 	return ret;
 }
 
+/**
+ * @brief Turning on the onboard LED
+ *
+ * This function turns on the onboard LED by setting each of the GPIO pin to high
+ *
+ * @return status_t: Status of the operation
+ */
+
 status_t onboardled_on(void)
 {
 	status_t ret = success;
@@ -55,6 +72,14 @@ status_t onboardled_on(void)
 	return ret;
 }
 
+/**
+ * @brief Turning off the onboard LED
+ *
+ * This function turns on the onboard LED by setting each of the GPIO pin to low (clearing)
+ *
+ * @return status_t: Status of the operation
+ */
+
 status_t onboardled_off(void)
 {
 	status_t ret = success;
@@ -71,6 +96,14 @@ status_t onboardled_off(void)
 	return ret;
 }
 
+/**
+ * @brief Initializes the onboard LED driver
+ *
+ * This function initializes the onboard LED driver by allocating GPIO ports for the LED.
+ *
+ * @return status_t: Status of the initialization
+ */
+
 static status_t onboardled_setup(void)
 {
 	vret_t vres;
@@ -107,6 +140,15 @@ static status_t onboardled_setup(void)
 	return ret;
 }
 
+/**
+ * @brief Cleanup and exit the onboard LED driver.
+ *
+ * This function frees allocated GPIO ports and resources associated with the
+ * onboard LED driver.
+ *
+ * @return status_t: Status of the cleanup and exit
+ */
+
 static status_t onboardled_exit(void)
 {
 	status_t ret = success;
@@ -125,4 +167,4 @@ static status_t onboardled_exit(void)
 	return ret;
 }
 
-INCLUDE_DRIVER(OBrdLED, onboardled_setup, onboardled_exit, 0, 255, 255);
+INCLUDE_DRIVER(OBrdLED, onboardled_setup, onboardled_exit, 0, 255, 255);

src/platform/mega_avr/README.md

@@ -0,0 +1,27 @@
+# MegaAVR Family
+This folder contains platform specific programs for MegaAVR family of controllers.
+
+## Some differences between the two AVR microcontrollers:
+
+| Controller | CPU | Memory (SRAM) | Flash | EEPROM | GPIO |
+|---|---|---|---|---|---|
+| AtMega328P | AVR5-8b | 2KB | 32KB | 1KB | 23 |
+| AtMega2560 | AVR6-8b | 8KB | 256KB | 4KB | 86 |
+
+## Directories Overview
+| Folder                | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| [common](common)      | Holds common code shared between platforms.|
+| [atmega328p](atmega328p) | Houses platform-specific programs for Atmega328p. Contains: Architecture Specifics,  Platform Includes, Platform Clock, and Resources|
+| [atmega2560](atmega2560) | Houses platform-specific programs for Atmega2560. Contains: Architecture Specifics,  Platform Includes, Platform Clock, and Resources|
+
+### [common](common)
+
+Contains code shared between Atmega328p and Atmega2560.
+
+| Subfolder       | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| [arch](common/arch)    | CPU architecture related src|
+| [hal](common/hal)      | Hardware abstraction layer src|
+| [include](common/include) | Includes for platform header|
+| [platform](common/platform) | Platform specific src|