From f8b1dd41c5047012bcb3f19d03a742f4f90556d4 Mon Sep 17 00:00:00 2001
From: Marian Buschsieweke <marian.buschsieweke@ovgu.de>
Date: Thu, 24 Jun 2021 09:04:27 +0200
Subject: [PATCH] examples/blinky: add a new example app

---
 examples/blinky/Makefile           | 27 ++++++++++++++
 examples/blinky/Makefile.board.dep |  3 ++
 examples/blinky/README.md          |  9 +++++
 examples/blinky/main.c             | 60 ++++++++++++++++++++++++++++++
 4 files changed, 99 insertions(+)
 create mode 100644 examples/blinky/Makefile
 create mode 100644 examples/blinky/Makefile.board.dep
 create mode 100644 examples/blinky/README.md
 create mode 100644 examples/blinky/main.c

diff --git a/examples/blinky/Makefile b/examples/blinky/Makefile
new file mode 100644
index 0000000000..904e9ead10
--- /dev/null
+++ b/examples/blinky/Makefile
@@ -0,0 +1,27 @@
+# name of your application
+APPLICATION = blinky
+
+# If no BOARD is found in the environment, use this default:
+BOARD ?= native
+
+# This has to be the absolute path to the RIOT base directory:
+RIOTBASE ?= $(CURDIR)/../..
+
+# Comment this out to disable code in RIOT that does safety checking
+# which is not needed in a production environment but helps in the
+# development process:
+DEVELHELP ?= 1
+
+# Change this to 0 show compiler invocation lines by default:
+QUIET ?= 1
+
+# Use a peripheral timer for the delay, if available
+FEATURES_OPTIONAL += periph_timer
+
+include $(RIOTBASE)/Makefile.include
+
+ifeq (native,$(BOARD))
+  # For the native board, CLOCK_CORECLOCK is undefined. But we need
+  # a valid number to get the example compiled
+  CFLAGS += -DCLOCK_CORECLOCK=1000000000
+endif
diff --git a/examples/blinky/Makefile.board.dep b/examples/blinky/Makefile.board.dep
new file mode 100644
index 0000000000..0201a59e03
--- /dev/null
+++ b/examples/blinky/Makefile.board.dep
@@ -0,0 +1,3 @@
+ifneq (,$(filter periph_timer,$(FEATURES_USED)))
+  USEMODULE += ztimer_usec
+endif
diff --git a/examples/blinky/README.md b/examples/blinky/README.md
new file mode 100644
index 0000000000..a4e43ec487
--- /dev/null
+++ b/examples/blinky/README.md
@@ -0,0 +1,9 @@
+Blinky!
+=======
+
+This is a basic example that blinks an LED, if available. (If no LED is present or configured, it
+will print "Blink!" via stdio instead.)
+
+This is mostly useful for boards without stdio to check if a new port of RIOT works. For that
+reason, this example has only an optional dependency on timer drivers. Hence, this application only
+needs a working GPIO driver and is likely the first milestone when porting RIOT to new MCUs.
diff --git a/examples/blinky/main.c b/examples/blinky/main.c
new file mode 100644
index 0000000000..038cd27d6d
--- /dev/null
+++ b/examples/blinky/main.c
@@ -0,0 +1,60 @@
+/*
+ * Copyright (C) 2021 Otto-von-Guericke-Universität Magdeburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     examples
+ * @{
+ *
+ * @file
+ * @brief       Blinky application
+ *
+ * @author      Marian Buschsieweke <marian.buschsieweke@ovgu.de>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+#include "board.h"
+#include "periph_conf.h"
+#include "timex.h"
+#include "ztimer.h"
+
+static void delay(void)
+{
+    if (IS_USED(MODULE_ZTIMER)) {
+        ztimer_sleep(ZTIMER_USEC, 1 * US_PER_SEC);
+    }
+    else {
+        /*
+         * As fallback for freshly ported boards with no timer drivers written
+         * yet, we just use the CPU to delay execution and assume that roughly
+         * 20 CPU cycles are spend per loop iteration.
+         *
+         * Note that the volatile qualifier disables compiler optimizations for
+         * all accesses to the counter variable. Without volatile, modern
+         * compilers would detect that the loop is only wasting CPU cycles and
+         * optimize it out - but here the wasting of CPU cycles is desired.
+         */
+        for (volatile uint32_t i = 0; i < CLOCK_CORECLOCK / 20; i++) { }
+    }
+}
+
+int main(void)
+{
+    while (1) {
+        delay();
+#ifdef LED0_TOGGLE
+        LED0_TOGGLE;
+#else
+        puts("Blink! (No LED present or configured...)");
+#endif
+    }
+
+    return 0;
+}