samples: blinky: use a gpio_dt_spec

Using a gpio_dt_spec is the current best practice for getting at pins
defined in the DT, because it gets all the boilerplate and flags right
for you. Use that in blinky, keeping the documentation in sync with
the code.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

samples/basic/blinky/README.rst

@@ -6,29 +6,27 @@ Blinky
 Overview
 ********
 
-Blinky is a simple application which blinks an LED forever using the :ref:`GPIO
-API <gpio_api>`. The source code shows how to configure GPIO pins as outputs,
-then turn them on and off.
+The Blinky sample blinks an LED forever using the :ref:`GPIO API <gpio_api>`.
 
-See :ref:`pwm-blinky-sample` for a sample which uses the PWM API to blink an
-LED.
+The source code shows how to:
+
+#. Get a pin specification from the :ref:`devicetree <dt-guide>` as a
+   :c:struct:`gpio_dt_spec`
+#. Configure the GPIO pin as an output
+#. Toggle the pin forever
+
+See :ref:`pwm-blinky-sample` for a similar sample that uses the PWM API instead.
 
 .. _blinky-sample-requirements:
 
 Requirements
 ************
 
-You will see this error if you try to build Blinky for an unsupported board:
-
-.. code-block:: none
-
-   Unsupported board: led0 devicetree alias is not defined
+Your board must:
 
-The board must have an LED connected via a GPIO pin. These are called "User
-LEDs" on many of Zephyr's :ref:`boards`. The LED must be configured using the
-``led0`` :ref:`devicetree <dt-guide>` alias. This is usually done in the
-:ref:`BOARD.dts file <devicetree-in-out-files>` or a :ref:`devicetree overlay
-<set-devicetree-overlays>`.
+#. Have an LED connected via a GPIO pin (these are called "User LEDs" on many of
+   Zephyr's :ref:`boards`).
+#. Have the LED configured using the ``led0`` devicetree alias.
 
 Building and Running
 ********************
@@ -41,4 +39,57 @@ Build and flash Blinky as follows, changing ``reel_board`` for your board:
    :goals: build flash
    :compact:
 
-After flashing, the LED starts to blink. Blinky does not print to the console.
+After flashing, the LED starts to blink. If a runtime error occurs, the sample
+exits without printing to the console.
+
+Build errors
+************
+
+You will see a build error at the source code line defining the ``struct
+gpio_dt_spec led`` variable if you try to build Blinky for an unsupported
+board.
+
+On GCC-based toolchains, the error looks like this:
+
+.. code-block:: none
+
+   error: '__device_dts_ord_DT_N_ALIAS_led_P_gpios_IDX_0_PH_ORD' undeclared here (not in a function)
+
+Adding board support
+********************
+
+To add support for your board, add something like this to your devicetree:
+
+.. code-block:: DTS
+
+   / {
+   	aliases {
+   		led0 = &myled0;
+   	};
+
+   	leds {
+   		compatible = "gpio-leds";
+   		myled0: led_0 {
+   			gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
+                };
+   	};
+   };
+
+The above sets your board's ``led0`` alias to use pin 13 on GPIO controller
+``gpio0``. The pin flags :c:macro:`GPIO_ACTIVE_HIGH` mean the LED is on when
+the pin is set to its high state, and off when the pin is in its low state.
+
+Tips:
+
+- See :dtcompatible:`gpio-leds` for more information on defining GPIO-based LEDs
+  in devicetree.
+
+- If you're not sure what to do, check the devicetrees for supported boards which
+  use the same SoC as your target. See :ref:`get-devicetree-outputs` for details.
+
+- See :zephyr_file:`include/dt-bindings/gpio/gpio.h` for the flags you can use
+  in devicetree.
+
+- If the LED is built in to your board hardware, the alias should be defined in
+  your :ref:`BOARD.dts file <devicetree-in-out-files>`. Otherwise, you can
+  define one in a :ref:`devicetree overlay <set-devicetree-overlays>`.

samples/basic/blinky/src/main.c

@@ -5,8 +5,6 @@
  */
 
 #include <zephyr.h>
-#include <device.h>
-#include <devicetree.h>
 #include <drivers/gpio.h>
 
 /* 1000 msec = 1 sec */
@@ -15,37 +13,30 @@
 /* The devicetree node identifier for the "led0" alias. */
 #define LED0_NODE DT_ALIAS(led0)
 
-#if DT_NODE_HAS_STATUS(LED0_NODE, okay)
-#define LED0	DT_GPIO_LABEL(LED0_NODE, gpios)
-#define PIN	DT_GPIO_PIN(LED0_NODE, gpios)
-#define FLAGS	DT_GPIO_FLAGS(LED0_NODE, gpios)
-#else
-/* A build error here means your board isn't set up to blink an LED. */
-#error "Unsupported board: led0 devicetree alias is not defined"
-#define LED0	""
-#define PIN	0
-#define FLAGS	0
-#endif
+/*
+ * A build error on this line means your board is unsupported.
+ * See the sample documentation for information on how to fix this.
+ */
+static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);
 
 void main(void)
 {
-	const struct device *dev;
-	bool led_is_on = true;
 	int ret;
 
-	dev = device_get_binding(LED0);
-	if (dev == NULL) {
+	if (!device_is_ready(led.port)) {
 		return;
 	}
 
-	ret = gpio_pin_configure(dev, PIN, GPIO_OUTPUT_ACTIVE | FLAGS);
+	ret = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
 	if (ret < 0) {
 		return;
 	}
 
 	while (1) {
-		gpio_pin_set(dev, PIN, (int)led_is_on);
-		led_is_on = !led_is_on;
+		ret = gpio_pin_toggle_dt(&led);
+		if (ret < 0) {
+			return;
+		}
 		k_msleep(SLEEP_TIME_MS);
 	}
 }