samples: drivers: input: Add gpio-keys wake-up example

The gpio-keys is a standard mechanism in Linux to be used as wake-up
source. This introduces an example to demonstrate how to use such
functionality toguether with power-off API.

Signed-off-by: Gerson Fernando Budke <[email protected]>

samples/drivers/input/gpio_keys/CMakeLists.txt

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(poweroff_wkup_gpio)
+
+target_sources(app PRIVATE src/main.c)

samples/drivers/input/gpio_keys/README.rst

@@ -0,0 +1,51 @@
+.. zephyr:code-sample:: samples_drivers_input_gpio_keys
+   :name: Using GPIO-KEYS to Wake-Up system from a Power-Off state
+   :relevant-api: input_events sys_poweroff
+
+
+Overview
+********
+
+This example explores the system :ref:`poweroff` mode and wake-up sources
+using gpio-keys. The application boots and waits for 10s before putting the
+whole system in power-off mode. When the system is in power-off mode some
+devices may lost the J-TAG/SWD interfaces and, as a consequence, it loses the
+access to the program/debug tap interface. In the same way, user may lost reset
+functionality and the 10s sleep counter helps to keep device in a safe state
+to easy recover from power-off application. For those cases, the only way to
+wake-up the device is using the user button on the board with wake-up
+functionality.
+
+
+Requirements
+************
+
+A GPIO that can be used as wake-up source be defined at devicetree. Some
+platforms may requerie that pinctrl be defined to use such feature. The
+power-off is available when selecting the :kconfig:option:`CONFIG_POWEROFF`
+in the ``prj.conf`` file.
+
+
+Building, Flashing and Running
+******************************
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/input/gpio_keys
+   :board: sam_v71_xult
+   :goals: build flash
+   :compact:
+
+
+Sample Output
+=================
+
+.. code-block:: console
+
+   *** Booting Zephyr OS build zephyr-v3.5.0-583-g91585c5b3720 ***
+   System Wake-Up: Going to Power-Off in 10s
+   ..........
+   Power-Off: Press the user button defined at gpio-key to Wake-Up the system
+   *** Booting Zephyr OS build zephyr-v3.5.0-583-g91585c5b3720 ***
+   System Wake-Up: Going to Power-Off in 10s
+   ..........
+   Power-Off: Press the user button defined at gpio-key to Wake-Up the system

samples/drivers/input/gpio_keys/prj.conf

@@ -0,0 +1,3 @@
+CONFIG_LOG=y
+CONFIG_LOG_MODE_MINIMAL=y
+CONFIG_POWEROFF=y

samples/drivers/input/gpio_keys/sample.yaml

@@ -0,0 +1,14 @@
+sample:
+  name: samples_driver_input_gpio_keys
+tests:
+  sample.driver.input.gpio_keys.pinctrl:
+    tags:
+      - gpio
+      - pm
+      - pinctrl
+      - samples
+    platform_allow:
+      - sam4s_xplained
+      - sam4e_xpro
+      - sam_e70_xplained
+      - sam_v71_xult

samples/drivers/input/gpio_keys/src/main.c

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2023 Gerson Fernando Budke <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/sys/poweroff.h>
+#include <soc.h>
+
+#include <zephyr/logging/log.h>
+LOG_MODULE_REGISTER(gpio_keys, CONFIG_LOG_DEFAULT_LEVEL);
+
+int main(void)
+{
+	printf("System Wake-Up: Going to Power-Off in 10s\n");
+
+	/* WARNING
+	 *
+	 * Some systems may be complete unavailable when in Power-Off. This
+	 * means that in few cases even J-TAG/SWD is unavailable. To keep the
+	 * access to programming and debugging interface the 10s sleep counter
+	 * is provided.
+	 */
+	for (int count = 0; count < 10; ++count) {
+		k_msleep(1000);
+		printf(".");
+	}
+
+	printf("\nPower-Off: Press the user button defined at gpio-key to Wake-Up the system\n");
+	k_msleep(1);
+	sys_poweroff();
+
+	return 0;
+}