GCC port merge

.gitignore

@@ -1,6 +1,11 @@
-Debug/
-*.dep
-*.bat
-*.TMP
-*.wspos
 doxygen/html
+
+# Waf lock files
+.lock-waf_*
+
+# Waf's dir it unpacks itself to.
+/waf3-*/
+/.waf3-*/
+
+# All build output
+/build/

.vscode/.gitignore

@@ -0,0 +1,3 @@
+# Ignore the settings file, but a default is provided which should seed this using the
+# config-defaults extension.
+settings.json

.vscode/c_cpp_properties.json

@@ -0,0 +1,14 @@
+{
+    "configurations": [
+        {
+            "name": "default",
+            "includePath": [],
+            "defines": [],
+            "cStandard": "c99",
+            "intelliSenseMode": "gcc-arm",
+            "compileCommands": "${workspaceFolder}/build/compile_commands.json",
+            "mergeConfigurations": true
+        }
+    ],
+    "version": 4
+}

.vscode/extensions.json

@@ -0,0 +1,19 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+    // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+    // List of extensions which should be recommended for users of this workspace.
+    "recommendations": [
+        "dan-c-underwood.arm",
+        "ms-vscode.cpptools-extension-pack",
+        "marus25.cortex-debug",
+        "trond-snekvik.gnu-mapfiles",
+        "keroc.hex-fmt",
+        "zixuanwang.linkerscriptm",
+        "spadin.config-defaults",
+        "mhutchie.git-graph",
+        "eamodio.gitlens",
+        "ms-vscode.vscode-serial-monitor"
+    ],
+    // List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+    "unwantedRecommendations": []
+}

.vscode/launch.json

@@ -0,0 +1,63 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "cwd": "${workspaceFolder}",
+            "executable": "./build/firmware-ascii",
+            "name": "Debug ASCII Board",
+            "request": "launch",
+            "type": "cortex-debug",
+            "device": "ATSAM3U2C",
+            "runToEntryPoint": "main",
+            // "breakAfterReset": true,
+            "showDevDebugOutput": "none",
+            "servertype": "jlink",
+            "svdPath": "${workspaceFolder}/firmware_common/bsp/ATSAM3U2C.svd",
+            "preLaunchTask": "Build firmware"
+        },
+        {
+            "cwd": "${workspaceFolder}",
+            "executable": "./build/firmware-dot-matrix",
+            "name": "Debug Dot Matrix Board",
+            "request": "launch",
+            "type": "cortex-debug",
+            "device": "ATSAM3U2C",
+            "runToEntryPoint": "main",
+            // "breakAfterReset": true,
+            "showDevDebugOutput": "none",
+            "servertype": "jlink",
+            "svdPath": "${workspaceFolder}/firmware_common/bsp/ATSAM3U2C.svd",
+            "preLaunchTask": "Build firmware"
+        },
+        {
+            "name": "waf",
+            "type": "python",
+            "request": "launch",
+            "program": "${workspaceFolder}/waf",
+            "args": [
+                "${input:waf-command}",
+            ],
+            "cwd": "${workspaceFolder}",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+        },
+    ],
+    "inputs": [
+        {
+            "id": "waf-command",
+            "type": "pickString",
+            "description": "Which waf subcommand to run",
+            "default": "build",
+            "options": [
+                "distclean",
+                "configure",
+                "clean",
+                "build",
+                "clean build",
+            ]
+        }
+    ]
+}

.vscode/settings.default.json

@@ -0,0 +1,14 @@
+{
+    "cortex-debug.variableUseNaturalFormat": false,
+    "C_Cpp.autoAddFileAssociations": false,
+    "cortex-debug.liveWatchRefreshRate": 600,
+    // These defaults are based on typical install paths, you may need to update them based on
+    // what version and where you installed things. (they also belong in your user config).
+    // TODO: Would it be okay to auto-set these from waf? Or in the launch config? That might be
+    // too much automatic magic.
+    "cortex-debug.armToolchainPath.windows": "C:\\Program Files (x86)\\Arm GNU Toolchain arm-none-eabi\\13.3 rel1\\bin",
+    "cortex-debug.armToolchainPath.osx": "/Application/ArmGNUToolchain/13.3.rel1/arm-none-eabi/bin",
+    "cortex-debug.JLinkGDBServerPath.windows": "C:\\Program Files\\SEGGER\\JLink\\JLinkGDBServerCL.exe",
+    "cortex-debug.JLinkGDBServerPath.osx": "/Application/SEGGER/JLink/JLinkGDBServerCLExe",
+    "cortex-debug.JLinkGDBServerPath.linux": "/opt/SEGGER/JLink/JLinkGDBServerCLExe",
+}

.vscode/tasks.json

@@ -0,0 +1,28 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build firmware",
+            "type": "process",
+            "command": "python",
+            "args": [
+                "waf",
+                "build",
+                "--keep", // Keep going even if error, ensures all compilation failures are found.
+            ],
+            "isBuildCommand": true,
+            "problemMatcher": {
+                "base": "$gcc",
+                "fileLocation": [
+                    "autoDetect",
+                    "${workspaceFolder}/build/",
+                ]
+            },
+            "options": {
+                "cwd": "${workspaceFolder}",
+            },
+        }
+    ]
+}

docs/setup.md

@@ -0,0 +1,52 @@
+# Setup
+
+[TOC]
+
+## Installation
+
+
+### Required tools
+The following tools are necessary to build the project
+
+- [Python 3](#python-3)
+- [The ARM GNU Toolchain](#arm-gnu-toolchain)
+- [JLink](#jlink)
+- [Git](#git)
+
+#### Python 3
+
+Python 3 is used to run the waf script that controls the configuration and build process of the project
+
+Install the latest version of python 3 for your operating system from [Python.org](https://www.python.org/downloads/). If you have an older version of python 3 that will probably work fine.
+It is recommended to select the option to add python to the path if available during the install.
+
+#### ARM GNU Toolchain
+
+The GNU arm toolchain contains the compiler and other tools necessary to build the project. To install
+
+1. Go to the page for the [ARM GNU Toolchain Download](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
+2. Download the version 13.3.Rel1 of the **ARM-none-eabi** toolchain for your operating system.
+    1. For windows this is the .exe file.
+    2. For macOS this is the .pkg file (make sure to get the correct one for if you are running an x86 or Apple Silicon Mac).
+    3. For debian based linux you can run `sudo apt install gcc-arm-non-eabi` and skip downloading from the website.
+3. Run the installer. On windows when prompted at the end deselect all boxes except for `Add to path`
+
+#### JLink
+
+Segger's JLink tools are necessary to program and debug the board.
+
+1. Go to the page for the [J-Link Downloads](https://www.segger.com/downloads/jlink/)
+2. Download the latest version of J-Link for your operating system.
+3. Run the installer
+4. When prompted to choose a destination select `Update existing install` even if don't have J-Link already installed.
+
+#### Git
+
+Git is the version control platform used to keep track of the project files. Follow the installation instructions for git from the [git-scm](https://git-scm.com/downloads) for your operating system.
+
+##### Windows Specific Instructions
+
+1. Download the latest version of git for windows from the [git-scm's download page](https://git-scm.com/download/win).
+2. Run the installer
+3. When prompted to select an editor for git to use, unless you are already familiar with Vim, it is **highly recommended** to switch to an editor you are familiar and comfortable with.
+4. It is recommended to install the [Windows Terminal App](https://apps.microsoft.com/detail/9n0dx20hk701) from the Microsoft Store

docs/vscode.md

@@ -0,0 +1,20 @@
+
+# Visual Studio Code
+
+[TOC]
+
+## Introduction and Download
+
+Visual Studio Code is a popular, cross platform source-code editor made by Microsoft. It is the recommended editor for EiE, although any other editor may work albeit without the debugger integration. VSCode can be downloaded from [Microsoft](https://visualstudio.microsoft.com/downloads/).
+
+## Extension Setup
+
+EIE has a number of recommended extensions for VSCode. These can be found by searching `@recommended` in the extensions tab on the side bar. Install all the extensions under the Workspace Recommendations dropdown.
+
+If you are unfamiliar with VScode extensions please see [Microsoft's Documentation](https://code.visualstudio.com/docs/editor/extension-marketplace).
+
+## Debugger
+
+After installing the recommended extensions the VScode debugger should work to enable step through debugging on hardware. In the Run and Debug tab on the sidebar the debug profile can be set as either `Debug ASCII Board` or `Debug Dot Matrix Board` to debug your hardware.
+
+If you are unfamiliar with the VScode debugger please see [Microsoft's Documentation](https://code.visualstudio.com/docs/editor/debugging).

firmware_ascii/bsp/eief1-pcb-01.c

@@ -124,22 +124,23 @@ void WatchDogSetup(void)
 */
 void ClockSetup(void)
 {
-  /* Set flash wait states to allow 48 MHz system clock (2 wait states required) */
-  AT91C_BASE_EFC0->EFC_FMR = AT91C_EFC_FWS_2WS;
-
-  /* Activate the peripheral clocks needed for the system */
-  AT91C_BASE_PMC->PMC_PCER = PMC_PCER_INIT;
-
   /* Enable the master clock on the PKC0 clock out pin (PA_27_CLOCK_OUT) */
   AT91C_BASE_PMC->PMC_PCKR[0] = AT91C_PMC_CSS_SYS_CLK | AT91C_PMC_PRES_CLK;
   AT91C_BASE_PMC->PMC_SCER = AT91C_PMC_PCK0;
+  while ( !(AT91C_BASE_PMC->PMC_SR & AT91C_PMC_PCKRDY0) );
 
   /* Turn on the main oscillator and wait for it to start up */
   AT91C_BASE_PMC->PMC_MOR = PMC_MOR_INIT;
   while ( !(AT91C_BASE_PMC->PMC_SR & AT91C_PMC_MOSCXTS) );
 
-  /* Assign main clock as crystal */
+  /* Assign main clock as crystal and wait for switch */
   AT91C_BASE_PMC->PMC_MOR |= (AT91C_CKGR_MOSCSEL | MOR_KEY);
+  while ( !(AT91C_BASE_PMC->PMC_SR & AT91C_PMC_MOSCSELS) );
+
+  /* Set flash wait states to allow 48 MHz system clock (2 wait states required) */
+  /* Note: There is an errata where the flash controller can't operate at sub-5 Mhz with
+     wait states programmed, so this must be done after the clock is bumped to 12 Mhz*/
+  AT91C_BASE_EFC0->EFC_FMR = AT91C_EFC_FWS_2WS;
 
   /* Initialize PLLA and wait for lock */
   AT91C_BASE_PMC->PMC_PLLAR = PMC_PLAAR_INIT;
@@ -154,6 +155,10 @@ void ClockSetup(void)
   /* Initialize UTMI for USB usage */
   AT91C_BASE_CKGR->CKGR_UCKR |= (AT91C_CKGR_UPLLCOUNT & (3 << 20)) | AT91C_CKGR_UPLLEN;
   while ( !(AT91C_BASE_PMC->PMC_SR & AT91C_PMC_LOCKU) ); 
+
+  /* Activate the peripheral clocks needed for the system, must be done
+     last to ensure all clock sources are valid before clocking periphs. */
+  AT91C_BASE_PMC->PMC_PCER = PMC_PCER_INIT;
 
 } /* end ClockSetup */
 

firmware_ascii/bsp/eief1-pcb-01.h

@@ -391,7 +391,7 @@ counter must be set at 1280. */
 
 
 #define MOR_KEY      (u32)(0x37 << 16)
-#define PMC_MOR_INIT (u32)0x0037F019
+#define PMC_MOR_INIT (u32)0x0037F009
 /*
     31 [0] Reserved
     30 [0] "
@@ -424,9 +424,9 @@ counter must be set at 1280. */
     08 [0] "
 
     07 [0] Reserved
-    06 [0] MOSCRCF 8MHz
+    06 [0] MOSCRCF 4MHz (Keep at 4 to match startup)
     05 [0] "
-    04 [1] "
+    04 [0] "
 
     03 [1] MOSCRCEN main on-chip RC osc is on for now
     02 [0] WAITMODE disabled
@@ -1616,7 +1616,7 @@ Tdiv_slclk = 2*(DIV+1)*Tslow_clock.
 */
 
 /* PIO Write Protect Mode Register PIO_WPMR
-Enables the Write Protect if WPKEY corresponds to 0x50494F (�PIO� in ASCII).
+Enables the Write Protect if WPKEY corresponds to 0x50494F ("PIO" in ASCII).
 Though this is defined in the user guide, there is no definition in the processor header file.
 We don't want to lock access to the GPIO registers anyway, so we won't use this for now.
 */