samples: threads: cleanups

Align the docs and source code with other changes done to the basic
samples.

Use numbers 0 and 1 to refer to the LEDs consistently. This matches
the generic devicetree aliases used by Zephyr, instead of using USR1
and USR2, which are specific to 96b_carbon.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

Author: mbolivar-nordic

samples/basic/threads/README.rst

@@ -6,29 +6,48 @@ Basic Thread Example
 Overview
 ********
 
-This example demonstrates spawning of multiple threads using K_THREAD_DEFINE.
+This example demonstrates spawning multiple threads using
+:c:func:`K_THREAD_DEFINE`. It spawns three threads. Each thread is then defined
+at compile time using K_THREAD_DEFINE.
 
-The example works by spawning three threads. The first two threads control a
-separate LED. Both of these LEDs (USR1 and USR2) have their individual loop
-control and timing logic defined by separate functions.
+The first two each control an LED. These LEDs, ``led0`` and ``led1``, have
+loop control and timing logic controlled by separate functions.
 
-After either thread toggles its LED, it also pushes information into a
-FIFO identifying which thread toggled its LED and how many times it
-was done.
+- ``blink0()`` controls ``led0`` and has a 100ms sleep cycle
+- ``blink1()`` controls ``led1`` and has a 1000ms sleep cycle
 
-The third thread, ``uart_out()``, uses printk (over the UART) to
-display the information that comes through the FIFO.
+When either of these threads toggles its LED, it also pushes information into a
+:ref:`FIFO <fifos_v2>` identifying the thread/LED and how many times it has
+been toggled.
 
-- blink1() controls the USR1 LED that has a 100ms sleep cycle
-- blink2() controls the USR2 LED that has a 1000ms sleep cycle
+The third thread uses :c:func:`printk` to print the information added to the
+FIFO to the device console.
 
-Each thread is then defined at compile time using K_THREAD_DEFINE.
+Requirements
+************
+
+The board must have two LEDs connected via GPIO pins. These are called "User
+LEDs" on many of Zephyr's :ref:`boards`. The LEDs must be configured using the
+``led0`` and ``led1`` :ref:`devicetree <dt-guide>` aliases, usually in the
+:ref:`BOARD.dts file <devicetree-in-out-files>`.
+
+You will see one of these errors if you try to build this sample for an
+unsupported board:
+
+.. code-block:: none
+
+   Unsupported board: led0 devicetree alias is not defined
+   Unsupported board: led1 devicetree alias is not defined
 
 Building
 ********
 
+For example, to build this sample for :ref:`96b_carbon_board`:
+
 .. zephyr-app-commands::
    :zephyr-app: samples/basic/threads
    :board: 96b_carbon
    :goals: build flash
    :compact:
+
+Change ``96b_carbon`` appropriately for other supported boards.

samples/basic/threads/sample.yaml

@@ -13,5 +13,5 @@ tests:
       type: multi_line
       ordered: false
       regex:
-        - "Toggle USR0 LED(.*)"
-        - "Toggle USR1 LED(.*)"
+        - "Toggled led0; counter=(.*)"
+        - "Toggled led1; counter=(.*)"

samples/basic/threads/src/main.c

@@ -17,6 +17,19 @@
 /* scheduling priority used by each thread */
 #define PRIORITY 7
 
+#define LED0_NODE DT_ALIAS(led0)
+#define LED1_NODE DT_ALIAS(led1)
+
+/*
+ * Devicetree helper macro which gets the 'flags' cell from a 'gpios'
+ * property, or returns 0 if the property has no 'flags' cell.
+ */
+
+#define FLAGS_OR_ZERO(node)						\
+	COND_CODE_1(DT_PHA_HAS_CELL(node, gpios, flags),		\
+		    (DT_GPIO_FLAGS(node, gpios)),			\
+		    (0))
+
 struct printk_data_t {
 	void *fifo_reserved; /* 1st word reserved for use by fifo */
 	u32_t led;
@@ -25,18 +38,6 @@ struct printk_data_t {
 
 K_FIFO_DEFINE(printk_fifo);
 
-#if DT_PHA_HAS_CELL(DT_ALIAS(led0), gpios, flags)
-#define LED0_FLAGS DT_GPIO_FLAGS(DT_ALIAS(led0), gpios)
-#else
-#define LED0_FLAGS 0
-#endif
-
-#if DT_PHA_HAS_CELL(DT_ALIAS(led1), gpios, flags)
-#define LED1_FLAGS DT_GPIO_FLAGS(DT_ALIAS(led1), gpios)
-#else
-#define LED1_FLAGS 0
-#endif
-
 struct led {
 	const char *gpio_dev_name;
 	const char *gpio_pin_name;
@@ -51,8 +52,11 @@ void blink(const struct led *led, u32_t sleep_ms, u32_t id)
 	int ret;
 
 	gpio_dev = device_get_binding(led->gpio_dev_name);
-	__ASSERT(gpio_dev != NULL, "Error: didn't find %s device\n",
-			led->gpio_dev_name);
+	if (gpio_dev == NULL) {
+		printk("Error: didn't find %s device\n",
+		       led->gpio_dev_name);
+		return;
+	}
 
 	ret = gpio_pin_configure(gpio_dev, led->gpio_pin, led->gpio_flags);
 	if (ret != 0) {
@@ -79,42 +83,52 @@ void blink(const struct led *led, u32_t sleep_ms, u32_t id)
 	}
 }
 
-void blink1(void)
+void blink0(void)
 {
-	const struct led led1 = {
-		.gpio_dev_name = DT_GPIO_LABEL(DT_ALIAS(led0), gpios),
-		.gpio_pin_name = DT_LABEL(DT_ALIAS(led0)),
-		.gpio_pin = DT_GPIO_PIN(DT_ALIAS(led0), gpios),
-		.gpio_flags = GPIO_OUTPUT | LED0_FLAGS,
+	const struct led led0 = {
+#if DT_NODE_HAS_STATUS(LED0_NODE, okay)
+		.gpio_dev_name = DT_GPIO_LABEL(LED0_NODE, gpios),
+		.gpio_pin_name = DT_LABEL(LED0_NODE),
+		.gpio_pin = DT_GPIO_PIN(LED0_NODE, gpios),
+		.gpio_flags = GPIO_OUTPUT | FLAGS_OR_ZERO(LED0_NODE),
+#else
+#error "Unsupported board: led0 devicetree alias is not defined"
+#endif
 	};
 
-	blink(&led1, 100, 0);
+	blink(&led0, 100, 0);
 }
 
-void blink2(void)
+void blink1(void)
 {
-	const struct led led2 = {
-		.gpio_dev_name = DT_GPIO_LABEL(DT_ALIAS(led1), gpios),
-		.gpio_pin_name = DT_LABEL(DT_ALIAS(led1)),
-		.gpio_pin = DT_GPIO_PIN(DT_ALIAS(led1), gpios),
-		.gpio_flags = GPIO_OUTPUT | LED1_FLAGS,
+	const struct led led1 = {
+#if DT_NODE_HAS_STATUS(LED1_NODE, okay)
+		.gpio_dev_name = DT_GPIO_LABEL(LED1_NODE, gpios),
+		.gpio_pin_name = DT_LABEL(LED1_NODE),
+		.gpio_pin = DT_GPIO_PIN(LED1_NODE, gpios),
+		.gpio_flags = GPIO_OUTPUT | FLAGS_OR_ZERO(LED1_NODE),
+#else
+#error "Unsupported board: led1 devicetree alias is not defined"
+#endif
 	};
 
-	blink(&led2, 1000, 1);
+	blink(&led1, 1000, 1);
 }
 
 void uart_out(void)
 {
 	while (1) {
-		struct printk_data_t *rx_data = k_fifo_get(&printk_fifo, K_FOREVER);
-		printk("Toggle USR%d LED: Counter = %d\n", rx_data->led, rx_data->cnt);
+		struct printk_data_t *rx_data = k_fifo_get(&printk_fifo,
+							   K_FOREVER);
+		printk("Toggled led%d; counter=%d\n",
+		       rx_data->led, rx_data->cnt);
 		k_free(rx_data);
 	}
 }
 
-K_THREAD_DEFINE(blink1_id, STACKSIZE, blink1, NULL, NULL, NULL,
+K_THREAD_DEFINE(blink0_id, STACKSIZE, blink0, NULL, NULL, NULL,
 		PRIORITY, 0, 0);
-K_THREAD_DEFINE(blink2_id, STACKSIZE, blink2, NULL, NULL, NULL,
+K_THREAD_DEFINE(blink1_id, STACKSIZE, blink1, NULL, NULL, NULL,
 		PRIORITY, 0, 0);
 K_THREAD_DEFINE(uart_out_id, STACKSIZE, uart_out, NULL, NULL, NULL,
 		PRIORITY, 0, 0);