Add devicetree support to Rust on Zephyr

MAINTAINERS.yml

@@ -3039,6 +3039,17 @@ Retention:
   labels:
     - "area: Retention"
 
+Rust:
+  status: maintained
+  maintainers:
+    - d3zd3z
+  files:
+    - cmake/modules/rust.cmake
+    - lib/rust/
+    - samples/rust/
+  labels:
+    - "area: Rust"
+
 Samples:
   status: maintained
   maintainers:

cmake/modules/rust.cmake

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Rust make support
+
+# 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
+# Rust.
+function(_rust_map_target)
+  # Map Zephyr targets to LLVM targets.
+  if(CONFIG_CPU_CORTEX_M)
+    if(CONFIG_CPU_CORTEX_M0 OR CONFIG_CPU_CORTEX_M0PLUS OR CONFIG_CPU_CORTEX_M1)
+      set(RUST_TARGET "thumbv6m-none-eabi" PARENT_SCOPE)
+    elseif(CONFIG_CPU_CORTEX_M3)
+      set(RUST_TARGET "thumbv7m-none-eabi" PARENT_SCOPE)
+    elseif(CONFIG_CPU_CORTEX_M4)
+      if(CONFIG_FP_HARDABI OR FORCE_FP_HARDABI)
+        set(RUST_TARGET "thumbv7em-none-eabihf" PARENT_SCOPE)
+      else()
+        set(RUST_TARGET "thumbv7em-none-eabi" PARENT_SCOPE)
+      endif()
+    elseif(CONFIG_CPU_CORTEX_M23)
+      set(RUST_TARGET "thumbv8m.base-none-eabi" PARENT_SCOPE)
+    elseif(CONFIG_CPU_CORTEX_M33 OR CONFIG_CPU_CORTEX_M55)
+      # Not a typo, Zephyr, uses ARMV7_M_ARMV8_M_FP to select the FP even on v8m.
+      if(CONFIG_FP_HARDABI OR FORCE_FP_HARDABI)
+        set(RUST_TARGET "thumbv8m.main-none-eabihf" PARENT_SCOPE)
+      else()
+        set(RUST_TARGET "thumbv8m.main-none-eabi" PARENT_SCOPE)
+      endif()
+
+      # Todo: The M55 is thumbv8.1m.main-none-eabi, which can be added when Rust
+      # gain support for this target.
+    else()
+      message(FATAL_ERROR "Unknown Cortex-M target.")
+    endif()
+  elseif(CONFIG_RISCV)
+    if(CONFIG_RISCV_ISA_RV64I)
+      # TODO: Should fail if the extensions don't match.
+      set(RUST_TARGET "riscv64imac-unknown-none-elf" PARENT_SCOPE)
+    elseif(CONFIG_RISCV_ISA_RV32I)
+      # TODO: We have multiple choices, try to pick the best.
+      set(RUST_TARGET "riscv32i-unknown-none-elf" PARENT_SCOPE)
+    else()
+      message(FATAL_ERROR "Rust: Unsupported riscv ISA")
+    endif()
+  else()
+    message(FATAL_ERROR "Rust: Add support for other target")
+  endif()
+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)
+  else()
+    set(${dirs} "" PARENT_SCOPE)
+  endif()
+endfunction()
+
+function(rust_cargo_application)
+  # For now, hard-code the Zephyr crate directly here.  Once we have
+  # more than one crate, these should be added by the modules
+  # themselves.
+  set(LIB_RUST_CRATES zephyr zephyr-sys zephyr-build)
+
+  get_include_dirs(zephyr_interface include_dirs)
+
+  get_target_property(include_dirs, zephyr_interface INTERFACE_INCLUDE_DIRECTORIES)
+  get_property(include_defines TARGET zephyr_interface PROPERTY INTERFACE_COMPILE_DEFINITIONS)
+  message(STATUS "Includes: ${include_dirs}")
+  message(STATUS "Defines: ${include_defines}")
+
+  _rust_map_target()
+  message(STATUS "Building Rust llvm target ${RUST_TARGET}")
+
+  # TODO: Make sure RUSTFLAGS is not set.
+
+  # TODO: Let this be configurable, or based on Kconfig debug?
+  set(RUST_BUILD_TYPE debug)
+  set(BUILD_LIB_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${RUST_TARGET}/${RUST_BUILD_TYPE}")
+
+  set(CARGO_TARGET_DIR "${CMAKE_CURRENT_BINARY_DIR}/rust/target")
+  set(RUST_LIBRARY "${CARGO_TARGET_DIR}/${RUST_TARGET}/${RUST_BUILD_TYPE}/librustapp.a")
+  set(SAMPLE_CARGO_CONFIG "${CMAKE_CURRENT_BINARY_DIR}/rust/sample-cargo-config.toml")
+
+  # The generated C binding wrappers. These are bindgen-generated wrappers for the inline functions
+  # within Zephyr.
+  set(WRAPPER_FILE "${CMAKE_CURRENT_BINARY_DIR}/rust/wrapper.c")
+
+  # To get cmake to always invoke Cargo requires a bit of a trick.  We make the output of the
+  # command a file that never gets created.  This will cause cmake to always rerun cargo.  We
+  # add the actual library as a BYPRODUCTS list of this command, otherwise, the first time the
+  # link will fail because it doesn't think it knows how to build the library.  This will also
+  # cause the relink when the cargo command actually does rebuild the rust code.
+  set(DUMMY_FILE "${CMAKE_BINARY_DIR}/always-run-cargo.dummy")
+
+  # For each module in zephyr-rs, add entry both to the .cargo/config template and for the
+  # command line, since either invocation will need to see these.
+  set(command_paths)
+  set(config_paths "")
+  message(STATUS "Processing crates: ${ZEPHYR_RS_MODULES}")
+  foreach(module IN LISTS LIB_RUST_CRATES)
+    message(STATUS "module: ${module}")
+    set(config_paths
+      "${config_paths}\
+${module}.path = \"${ZEPHYR_BASE}/lib/rust/${module}\"
+")
+    list(APPEND command_paths
+      "--config"
+      "patch.crates-io.${module}.path=\\\"${ZEPHYR_BASE}/lib/rust/${module}\\\""
+      )
+  endforeach()
+
+  # Write out a cargo config file that can be copied into `.cargo/config.toml` (or made a
+  # symlink) in the source directory to allow various IDE tools and such to work.  The build we
+  # invoke will override these settings, in case they are out of date.  Everything set here
+  # should match the arguments given to the cargo build command below.
+  file(WRITE ${SAMPLE_CARGO_CONFIG} "
+# This is a generated sample .cargo/config.toml file from the Zephyr build.
+# At the time of generation, this represented the settings needed to allow
+# a `cargo build` command to compile the rust code using the current Zephyr build.
+# If any settings in the Zephyr build change, this could become out of date.
+[build]
+target = \"${RUST_TARGET}\"
+target-dir = \"${CARGO_TARGET_DIR}\"
+
+[env]
+BUILD_DIR = \"${CMAKE_CURRENT_BINARY_DIR}\"
+DOTCONFIG = \"${DOTCONFIG}\"
+ZEPHYR_DTS = \"${ZEPHYR_DTS}\"
+INCLUDE_DIRS = \"${include_dirs}\"
+INCLUDE_DEFINES = \"${include_defines}\"
+WRAPPER_FILE = \"${WRAPPER_FILE}\"
+BINARY_DIR_INCLUDE_GENERATED = \"${BINARY_DIR_INCLUDE_GENERATED}\"
+
+[patch.crates-io]
+${config_paths}
+")
+
+  # The library is built by invoking Cargo.
+  add_custom_command(
+    OUTPUT ${DUMMY_FILE}
+    BYPRODUCTS ${RUST_LIBRARY} ${WRAPPER_FILE}
+    COMMAND
+      ${CMAKE_EXECUTABLE}
+      env BUILD_DIR=${CMAKE_CURRENT_BINARY_DIR}
+      DOTCONFIG=${DOTCONFIG}
+      ZEPHYR_DTS=${ZEPHYR_DTS}
+      INCLUDE_DIRS="${include_dirs}"
+      INCLUDE_DEFINES="${include_defines}"
+      WRAPPER_FILE="${WRAPPER_FILE}"
+      BINARY_DIR_INCLUDE_GENERATED=${BINARY_DIR_INCLUDE_GENERATED}
+      cargo build
+      # TODO: release flag if release build
+      # --release
+
+      # Override the features according to the shield given. For a general case,
+      # this will need to come from a variable or argument.
+      # TODO: This needs to be passed in.
+      # --no-default-features
+      # --features ${SHIELD_FEATURE}
+
+      # Set a replacement so that packages can just use `zephyr-sys` as a package
+      # name to find it.
+      ${command_paths}
+      --target ${RUST_TARGET}
+      --target-dir ${CARGO_TARGET_DIR}
+    COMMENT "Building Rust application"
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  )
+
+  add_custom_target(librustapp ALL
+    DEPENDS ${DUMMY_FILE}
+  )
+
+  target_link_libraries(app PUBLIC -Wl,--allow-multiple-definition ${RUST_LIBRARY})
+  add_dependencies(app librustapp)
+
+  # Presumably, Rust applications will have no C source files, but cmake will require them.
+  # Add an empty file so that this will build.  The main will come from the rust library.
+  target_sources(app PRIVATE ${ZEPHYR_BASE}/lib/rust/main.c ${WRAPPER_FILE})
+  set_source_files_properties(
+    ${WRAPPER_FILE}
+    COMPILE_FLAGS "-I${ZEPHYR_BASE}/lib/rust/zephyr-sys"
+  )
+endfunction()

cmake/modules/zephyr_default.cmake

@@ -112,6 +112,7 @@ list(APPEND zephyr_cmake_modules kconfig)
 list(APPEND zephyr_cmake_modules arch_v2)
 list(APPEND zephyr_cmake_modules soc_v1)
 list(APPEND zephyr_cmake_modules soc_v2)
+list(APPEND zephyr_cmake_modules rust)
 
 foreach(component ${SUB_COMPONENTS})
   if(NOT ${component} IN_LIST zephyr_cmake_modules)

doc/CMakeLists.txt

@@ -12,7 +12,7 @@ message(STATUS "Zephyr base: ${ZEPHYR_BASE}")
 #-------------------------------------------------------------------------------
 # Options
 
-set(SPHINXOPTS "-j auto -W --keep-going -T" CACHE STRING "Default Sphinx Options")
+set(SPHINXOPTS "-j 4 -W --keep-going -T" CACHE STRING "Default Sphinx Options")
 set(SPHINXOPTS_EXTRA "" CACHE STRING "Extra Sphinx Options (added to defaults)")
 set(LATEXMKOPTS "-halt-on-error -no-shell-escape" CACHE STRING "Default latexmk options")
 set(DT_TURBO_MODE OFF CACHE BOOL "Enable DT turbo mode")

doc/develop/languages/index.rst

@@ -8,3 +8,4 @@ Language Support
 
    c/index.rst
    cpp/index.rst
+   rust/index.rst

doc/develop/languages/rust/index.rst

@@ -0,0 +1,163 @@
+.. _language_rust:
+
+Rust Language Support
+#####################
+
+Rust is a systems programming language focused on safety, speed, and
+concurrency. Designed to prevent common programming errors such as
+null pointer dereferencing and buffer overflows, Rust emphasizes
+memory safety without sacrificing performance. Its powerful type
+system and ownership model ensure thread-safe programming, making it
+an ideal choice for developing reliable and efficient low-level code.
+Rust's expressive syntax and modern features make it a robust
+alternative for developers working on embedded systems, operating
+systems, and other performance-critical applications.
+
+Enabling Rust Support
+*********************
+
+Currently, Zephyr supports applications written in Rust and C.  The
+enable Rust support, you must select the :kconfig:option:`CONFIG_RUST`
+in the application configuration file.
+
+The rust toolchain is separate from the rest of the Zephyr SDK.   It
+is recommended to use the `rustup`_ tool to install the rust
+toolchain.  In addition to the base compiler, you will need to install
+core libraries for the target(s) you wish to compile on.  It is
+easiest to determine what needs to be installed by trying a build.
+The diagnostics from the rust compilation will indicate the rust
+command needed to install the appropriate target support:
+
+.. _rustup: https://rustup.rs/
+
+.. code-block::
+
+   $ west build ...
+   ...
+   error[E0463]: can't find crate for `core`
+     |
+   = note: the `thumbv7m-none-eabi` target may not be installed
+   = help: consider downloading the target with `rustup target add thumb7m-none-eabi`
+
+In this case, the given ``rustup`` command will install the needed
+target support.  The target needed will depend on both the board
+selected, as well as certain configuration choices (such as whether
+floating point is enabled).
+
+Writing a Rust Application
+**************************
+
+See :zephyr_file:`samples/rust` for examples of an application.
+
+CMake files
+-----------
+
+The application should contain a :file:`CMakeFiles.txt`, similar to
+the following:
+
+.. code-block:: cmake
+
+   cmake_minimum_required(VERSION 3.20.0)
+
+   find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+   project(hello_world)
+
+   rust_cargo_application()
+
+Cargo files
+-----------
+
+Rust applications are built with Cargo.  The Zephyr build system will
+configure and invoke cargo in your application directory, with options
+set so that it can find the Zephyr support libraries, and that the
+output will be contained within the Zephyr build directory.
+
+The :file:`Cargo.toml` will need to have a ``[lib]`` section that sets
+``crate-type = ["staticlib"]``, and will need to include ``zephyr =
+"0.1.0"`` as a dependency.  You can use crates.io and the Crate
+ecosystem to include any other dependencies you need.  Just make sure
+that you use crates that support building with no-std.
+
+Application
+-----------
+
+The application source itself should live in file:`src/lib.rs`.  A few
+things are needed.  A minimal file would be:
+
+.. code-block:: rust
+
+   #![no_std]
+
+   extern crate zephyr;
+
+   #[no_mangle]
+   extern "C" fn rust_main() {
+   }
+
+The ``no_std`` declaration is needed to prevent the code from
+referencing the ``std`` library.  The extern reference will cause the
+zephyr crate to be brought in, even if nothing from it is used.
+Practically, any meaningful Rust application on Zephyr will use
+something from this crate, and this line is not necessary.  Lastly,
+the main declaration exports the main symbol so that it can be called
+by C code.  The build ``rust_cargo_application()`` cmake function will
+include a small C file that will call into this from the C main
+function.
+
+Zephyr Functionality
+********************
+
+The bindings to Zephyr for Rust are under development, and are
+currently rather minimalistic.
+
+Bool Kconfig settings
+---------------------
+
+Boolean Kconfig settings can be used from within Rust code.  Due to
+design constraints by the Rust language, settings that affect
+compilation must be determined before the build is made.  In order to
+use this in your application, you will need to use the
+``zephyr-build`` crate, provided, to make these symbols available.
+
+To your ``Cargo.toml`` file, add the following:
+
+.. code-block:: toml
+
+   [build-dependencies]
+   zephyr-build = "0.1.0"
+
+Then, you will need a ``build.rs`` file to call the support function.
+The following will work:
+
+.. code-block:: rust
+
+   fn main() {
+       zephyr_build::export_bool_kconfig();
+   }
+
+At this point, it will be possible to use the ``cfg`` directive in
+Rust on boolean Kconfig values.  For example:
+
+.. code-block:: rust
+
+   #[cfg(CONFIG_SCHED_DUMB)]
+   one_declaration;
+
+   #[cfg(not(CONFIG_SCHED_DUMB)]
+   other_declaration;
+
+Other Kconfig settings
+----------------------
+
+All bool, numeric and string Kconfig settings are accessible from the
+``zephyr::kconfig`` module.  For example:
+
+.. code-block:: rust
+
+   let ceiling = zephyr::kconfig::CONFIG_PRIORITY_CEILING - 1;
+
+Other functionality
+-------------------
+
+Access to other functionality within zephyr is a work-in-progress, and
+this document will be updated as that is done.