Doxygen and improved makefile

.clang-format

@@ -0,0 +1,110 @@
+# Project .clang-format Settings
+# This is a .yaml file.
+
+# The documentation for clang-format can be found on 
+# https://clang.llvm.org/docs/ClangFormat.html
+
+# The style we are using is strongly based on the Google style guide for C++.
+# Notable changes include:
+# ColumnLimit: 100
+# PointerAlignment: Right
+# Cpp11BracedListStyle: false
+
+# For struct initializers the preferred initializer format is:
+# MyStruct my_struct = {
+#   .field1 = 1,  //
+#   .field2 = 2,  //
+# };
+# Note: the need for the comment to force the line break and the trailing comma
+# to force the braces to break.
+# For more details on the initializer style and solution see: 
+# https://stackoverflow.com/questions/33656800/clang-format-line-breaks
+
+Language:        Cpp
+BasedOnStyle:  Google
+AccessModifierOffset: -1
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Left
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: true
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Attach
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: AfterColon
+ColumnLimit:     100
+CommentPragmas:  '^ IWYU pragma:'
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: false
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
+IncludeCategories:
+  - Regex:           '^<.*\.h>'
+    Priority:        1
+  - Regex:           '^<.*'
+    Priority:        2
+  - Regex:           '.*'
+    Priority:        3
+IndentCaseLabels: true
+IndentWidth:     2
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: false
+PenaltyBreakBeforeFirstCallParameter: 1
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Right
+ReflowComments:  true
+SortIncludes:    true
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Auto
+TabWidth:        8
+UseTab:          Never
+

.github/workflows/deploy_doxygen.yml

@@ -0,0 +1,38 @@
+name: Deploy Doxygen Documentation
+
+on:
+  push:
+    branches: [ main ]
+  # Allow manual dispatch
+  workflow_dispatch:
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-20.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Doxygen 1.9.5
+        run: |
+          wget -q https://www.doxygen.nl/files/doxygen-1.9.5.linux.bin.tar.gz
+          tar -xzf doxygen-1.9.5.linux.bin.tar.gz
+          cd doxygen-1.9.5
+          sudo make install
+
+      - name: Install Graphviz
+        run: sudo apt-get install -y graphviz
+
+      - name: Generate Doxygen Documentation
+        run: |
+          doxygen --version  # Verify version
+          doxygen doxygen/Doxyfile
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doxygen/html
+          publish_branch: doxygen-pages
+          force_orphan: true
+          full_commit_message: 'Doxygen: update documentation'

.gitignore

@@ -1,3 +1,5 @@
 build/
 
-.vscode/
+.vscode/
+
+doxygen/html

BCM2711_hardware/inc/arm64_barrier.h

@@ -0,0 +1,57 @@
+#pragma once
+
+/*******************************************************************************************************************************
+ * @file   arm64_barrier.h
+ *
+ * @brief  ARM64 instruction and memory barrier definitions
+ *
+ * @date   2024-12-27
+ * @author Aryan Kashem
+ *******************************************************************************************************************************/
+
+/* Standard library Headers */
+
+/* Inter-component Headers */
+
+/* Intra-component Headers */
+
+/**
+ * @defgroup BCM2711_Hardware BCM2711 Hardware layer
+ * @brief    Abstraction layer for the BCM2711 SOC from Broadcom
+ * @{
+ */
+
+/**
+ * @brief   Data memory barrier. Ensures memory access ordering is correct
+ * @details Typically used when the order of memory accesses (reads and writes) is important to
+ *          avoid pipelining hazards For example, in a multi-core system, a DMB instruction can ensure that
+ *          all previous memory accesses are completed before new memory accesses are initiated, preventing
+ *          issues with out-of-order execution
+ */
+static inline void dmb(void) {
+  asm volatile("dmb sy" ::: "memory");
+}
+
+/**
+ * @brief   Data synchronization barrier. Ensures that all previous memory accesses are completed
+ *          before continuing with the next instruction
+ * @details Typically used to enforce synchronization in multi-core or multi-threaded systems
+ *          For example, in a multi-core system, DSB ensures that stores are propagated to other
+ *          cores before further memory accesses occur
+ */
+static inline void dsb(void) {
+  asm volatile("dsb sy" ::: "memory");
+}
+
+/**
+ * @brief   Instruction synchronization barrier. Ensures all instructions in the pipeline are
+ *          completed before moving on
+ * @details Typically used when it is necessary to ensure that all previous instructions have
+ *          completed before executing further instructions For example, after a context switch, ISB ensures
+ *          that any speculatively executed instructions (like branch predictions) are discarded
+ */
+static inline void isb(void) {
+  asm volatile("isb sy" ::: "memory");
+}
+
+/** @} */

BCM2711_hardware/inc/arm64_io.h

@@ -0,0 +1,35 @@
+#pragma once
+
+/*******************************************************************************************************************************
+ * @file   arm64_io.h
+ *
+ * @brief  ARM64 input/output writing and reading abstraction
+ *
+ * @date   2024-12-27
+ * @author Aryan Kashem
+ *******************************************************************************************************************************/
+
+/* Standard library Headers */
+
+/* Inter-component Headers */
+#include "common.h"
+
+/* Intra-component Headers */
+
+/**
+ * @defgroup BCM2711_Hardware BCM2711 Hardware layer
+ * @brief    Abstraction layer for the BCM2711 SOC from Broadcom
+ * @{
+ */
+
+void write8(u64 address, u8 value);
+void write16(u64 address, u16 value);
+void write32(u64 address, u32 value);
+void write64(u64 address, u64 value);
+
+u8  read8(u64 address);
+u16 read16(u64 address);
+u32 read32(u64 address);
+u64 read64(u64 address);
+
+/** @} */