A perpetual WIP PR

CMakeLists.txt

@@ -4,6 +4,9 @@
 
 set(RUST_MODULE_DIR "${CMAKE_CURRENT_LIST_DIR}" CACHE INTERNAL "")
 
+# Initially, we just have a single DT augment file.
+set(DT_AUGMENTS "${CMAKE_CURRENT_LIST_DIR}/dt-rust.yaml" CACHE INTERNAL "")
+
 # Zephyr targets are defined through Kconfig.  We need to map these to
 # an appropriate llvm target triple.  This sets `RUST_TARGET` in the
 # parent scope, or an error if the target is not yet supported by
@@ -54,7 +57,7 @@ endfunction()
 function(get_include_dirs target dirs)
   get_target_property(include_dirs ${target} INTERFACE_INCLUDE_DIRECTORIES)
   if(include_dirs)
-    set(${dirs} ${include_dirs} PARENT_SCOPE)
+    set(${dirs} "${include_dirs}" PARENT_SCOPE)
   else()
     set(${dirs} "" PARENT_SCOPE)
   endif()
@@ -138,6 +141,8 @@ ZEPHYR_DTS = \"${ZEPHYR_DTS}\"
 INCLUDE_DIRS = \"${include_dirs}\"
 INCLUDE_DEFINES = \"${include_defines}\"
 WRAPPER_FILE = \"${WRAPPER_FILE}\"
+BINARY_DIR_INCLUDE_GENERATED = \"${BINARY_DIR_INCLUDE_GENERATED}\"
+DT_AUGMENTS = \"${DT_AUGMENTS}\"
 
 [patch.crates-io]
 ${config_paths}
@@ -161,6 +166,8 @@ ${config_paths}
       INCLUDE_DIRS="${include_dirs}"
       INCLUDE_DEFINES="${include_defines}"
       WRAPPER_FILE="${WRAPPER_FILE}"
+      DT_AUGMENTS="${DT_AUGMENTS}"
+      BINARY_DIR_INCLUDE_GENERATED="${BINARY_DIR_INCLUDE_GENERATED}"
       cargo build
       ${rust_build_type_arg}
 
@@ -201,6 +208,8 @@ ${config_paths}
       INCLUDE_DIRS="${include_dirs}"
       INCLUDE_DEFINES="${include_defines}"
       WRAPPER_FILE="${WRAPPER_FILE}"
+      DT_AUGMENTS="${DT_AUGMENTS}"
+      BINARY_DIR_INCLUDE_GENERATED="${BINARY_DIR_INCLUDE_GENERATED}"
       cargo doc
       ${rust_build_type_arg}
 

dt-rust.yaml

@@ -0,0 +1,173 @@
+# Description of how to augment the devicetree for Rust.
+#
+# Each entry describes an augmentation that will be added to matching nodes in the device tree.
+# The full syntax is described (indirectly) in `zephyr-build/src/devicetree/config.rs`.
+
+# Gpio controllers match for every node that has a `gpio-controller` property.  This is one of the
+# few instances were we can actually just match on a property.
+- name: gpio-controller
+  rules:
+  - type: has_prop
+    value: gpio-controller
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: myself
+        value:
+          args: []
+      device: crate::device::gpio::Gpio
+
+# The gpio-leds node will have #children nodes describing each led.  We'll match on the parent
+# having this compatible property.  The nodes themselves are built out of the properties associated
+# with each gpio.
+- name: gpio-leds
+  rules:
+  - type: compatible
+    value:
+      names:
+      - gpio-leds
+      level: 1
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: phandle
+        value: gpios
+      device: crate::device::gpio::GpioPin
+
+# Flash controllers don't have any particular property to identify them, so we need a list of
+# compatible values that should match.
+- name: flash-controller
+  rules:
+  - type: compatible
+    value:
+      names:
+      - "nordic,nrf52-flash-controller"
+      - "nordic,nrf51-flash-controller"
+      - "raspberrypi,pico-flash-controller"
+      level: 0
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: myself
+        value:
+          args: []
+      device: crate::device::flash::FlashController
+
+# Flash partitions exist as children of a node compatible with "soc-nv-flash" that itself is a child
+# of the controller itself.
+# TODO: Get the write and erase property from the DT if present.
+- name: flash-partition
+  rules:
+  - type: compatible
+    value:
+      names:
+      - "fixed-partitions"
+      level: 1
+  - type: compatible
+    value:
+      names:
+      - "soc-nv-flash"
+      level: 2
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: parent
+        value:
+          level: 3
+          args:
+          - type: reg
+      device: "crate::device::flash::FlashPartition"
+
+# Uart devices.  This just has to be a list of devices that implement this interface.
+- name: uart
+  rules:
+  - type: compatible
+    value:
+      names:
+      - "arm,pl011"
+      # The nordic driver needs to be separate because they have a separate Kconfig for each uart
+      # block.
+      # - "nordic,nrf-uarte"
+      - "zephyr,cdc-acm-uart"
+      level: 0
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: myself
+        value:
+          args: []
+      device: "crate::device::uart::Uart"
+      kconfig: CONFIG_SERIAL
+
+- name: led-strip
+  rules:
+  - type: or
+    value:
+    - type: compatible
+      value:
+        names:
+        - "worldsemi,wd2812-spi"
+        level: 0
+    - type: compatible
+      value:
+        names:
+        - "worldsemi,ws2812-rpi_pico-pio"
+        level: 1
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: myself
+        value:
+          args: []
+      device: "crate::device::led_strip::LedStrip"
+      kconfig: CONFIG_LED_STRIP
+
+- name: pwm-leds
+  rules:
+  - type: compatible
+    value:
+      names:
+      - "pwm-leds"
+      level: 0
+  actions:
+  - type: instance
+    value:
+      raw:
+        type: myself
+        value:
+          args:
+          - type: child_count
+      device: "crate::device::led::Leds"
+
+# This doesn't really belong here, and can be moved once we support modules having their own augment
+# files.
+- name: bbq-kbd-matrix
+  rules:
+  - type: compatible
+    value:
+      names:
+      - "bbq-kbd-matrix"
+      level: 0
+  actions:
+  - type: gpio_pins
+    value:
+      property: "row-gpios"
+      getter: "get_rows"
+  - type: gpio_pins
+    value:
+      property: "col-gpios"
+      getter: "get_cols"
+
+# Generate a pseudo node that matches all of the labels across the tree with their nodes.
+- name: labels
+  rules:
+    - type: root
+  actions:
+  - type: labels
+

etc/platforms.txt

@@ -1,5 +1,3 @@
--p mps2/an385
--p mps2/an521/cpu0
 -p qemu_cortex_m0
 -p qemu_cortex_m3
 -p qemu_riscv32

samples/blinky/CMakeLists.txt

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(blinky)
+
+rust_cargo_application()

samples/blinky/Cargo.toml

@@ -0,0 +1,20 @@
+# Copyright (c) 2024 Linaro LTD
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+# This must be rustapp for now.
+name = "rustapp"
+version = "0.1.0"
+edition = "2021"
+description = "Blink an LED forever using the GPIO API"
+license = "Apache-2.0 OR MIT"
+
+[lib]
+crate-type = ["staticlib"]
+
+[dependencies]
+zephyr = "0.1.0"
+log = "0.4.22"
+
+[build-dependencies]
+zephyr-build = "0.1.0"

samples/blinky/README.rst

@@ -0,0 +1,97 @@
+.. zephyr:code-sample:: blinky
+   :name: Blinky
+   :relevant-api: gpio_interface
+
+   Blink an LED forever using the GPIO API.
+
+Overview
+********
+
+The Blinky sample blinks an LED forever using the :ref:`GPIO API <gpio_api>`.
+
+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 :zephyr:code-sample:`pwm-blinky` for a similar sample that uses the PWM API instead.
+
+.. _blinky-sample-requirements:
+
+Requirements
+************
+
+Your board must:
+
+#. 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
+********************
+
+Build and flash Blinky as follows, changing ``reel_board`` for your board:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/basic/blinky
+   :board: reel_board
+   :goals: build flash
+   :compact:
+
+After flashing, the LED starts to blink and messages with the current LED state
+are printed on the console. 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/zephyr/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/blinky/build.rs

@@ -0,0 +1,9 @@
+fn main() {
+    // This call will make make config entries available in the code for every device tree node, to
+    // allow conditional compilation based on whether it is present in the device tree.
+    // For example, it will be possible to have:
+    // ```rust
+    // #[cfg(dt = "aliases::led0")]
+    // ```
+    zephyr_build::dt_cfgs();
+}

samples/blinky/prj.conf

@@ -0,0 +1,10 @@
+CONFIG_GPIO=y
+
+CONFIG_RUST=y
+CONFIG_RUST_ALLOC=y
+
+CONFIG_DEBUG=y
+CONFIG_MAIN_STACK_SIZE=8192
+
+# Verify that userspace builds work.
+# CONFIG_USERSPACE=y

samples/blinky/sample.yaml

@@ -0,0 +1,13 @@
+# See doc/develop/test/twister.rst for what is here.
+sample:
+  name: Blinky Sample
+tests:
+  sample.basic.blinky:
+    tags:
+      - LED
+      - gpio
+    filter: dt_enabled_alias_with_parent_compat("led0", "gpio-leds")
+    depends_on: gpio
+    harness: led
+    integration_platforms:
+      - frdm_k64f