pw_random_fuchsia: Create Fuchsia backend for pw_random

Change-Id: I1103ee5560f7f39f0a67a03ee3b0ccf8cc764da9
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/230895
Reviewed-by: Faraaz Sareshwala <[email protected]>
Commit-Queue: Auto-Submit <[email protected]>
Pigweed-Auto-Submit: Ben Lawson <[email protected]>
Lint: Lint 🤖 <[email protected]>
Reviewed-by: Ted Pudlik <[email protected]>

CMakeLists.txt

@@ -129,6 +129,7 @@ add_subdirectory(pw_preprocessor EXCLUDE_FROM_ALL)
 add_subdirectory(pw_protobuf EXCLUDE_FROM_ALL)
 add_subdirectory(pw_protobuf_compiler EXCLUDE_FROM_ALL)
 add_subdirectory(pw_random EXCLUDE_FROM_ALL)
+add_subdirectory(pw_random_fuchsia EXCLUDE_FROM_ALL)
 add_subdirectory(pw_result EXCLUDE_FROM_ALL)
 add_subdirectory(pw_ring_buffer EXCLUDE_FROM_ALL)
 add_subdirectory(pw_router EXCLUDE_FROM_ALL)

PIGWEED_MODULES

@@ -110,6 +110,7 @@ pw_presubmit
 pw_protobuf
 pw_protobuf_compiler
 pw_random
+pw_random_fuchsia
 pw_result
 pw_ring_buffer
 pw_router

docs/module_metadata.json

@@ -445,6 +445,11 @@
       "C++"
     ]
   },
+  "pw_random_fuchsia": {
+    "tagline": "Fuchsia implementation of pw_random",
+    "status": "experimental",
+    "languages": []
+  },
   "pw_result": {
     "tagline": "Error propagation primitives: value-or-error",
     "status": "stable",

pw_build/generated_pigweed_modules_lists.gni

@@ -148,6 +148,7 @@ declare_args() {
   dir_pw_protobuf = get_path_info("../pw_protobuf", "abspath")
   dir_pw_protobuf_compiler = get_path_info("../pw_protobuf_compiler", "abspath")
   dir_pw_random = get_path_info("../pw_random", "abspath")
+  dir_pw_random_fuchsia = get_path_info("../pw_random_fuchsia", "abspath")
   dir_pw_result = get_path_info("../pw_result", "abspath")
   dir_pw_ring_buffer = get_path_info("../pw_ring_buffer", "abspath")
   dir_pw_router = get_path_info("../pw_router", "abspath")
@@ -338,6 +339,7 @@ declare_args() {
     dir_pw_protobuf,
     dir_pw_protobuf_compiler,
     dir_pw_random,
+    dir_pw_random_fuchsia,
     dir_pw_result,
     dir_pw_ring_buffer,
     dir_pw_router,
@@ -518,6 +520,7 @@ declare_args() {
     "$dir_pw_protobuf:tests",
     "$dir_pw_protobuf_compiler:tests",
     "$dir_pw_random:tests",
+    "$dir_pw_random_fuchsia:tests",
     "$dir_pw_result:tests",
     "$dir_pw_ring_buffer:tests",
     "$dir_pw_router:tests",
@@ -698,6 +701,7 @@ declare_args() {
     "$dir_pw_protobuf:docs",
     "$dir_pw_protobuf_compiler:docs",
     "$dir_pw_random:docs",
+    "$dir_pw_random_fuchsia:docs",
     "$dir_pw_result:docs",
     "$dir_pw_ring_buffer:docs",
     "$dir_pw_router:docs",

pw_random/BUILD.gn

@@ -73,5 +73,8 @@ pw_fuzzer("get_int_bounded_fuzzer") {
 }
 
 pw_doc_group("docs") {
-  sources = [ "docs.rst" ]
+  sources = [
+    "backends.rst",
+    "docs.rst",
+  ]
 }

pw_random/backends.rst

@@ -0,0 +1,14 @@
+.. _module-pw_random-backends:
+
+==================
+pw_random backends
+==================
+.. pigweed-module-subpage::
+   :name: pw_random
+
+.. TODO: b/323607687 - Add backend guidance here
+
+.. toctree::
+   :maxdepth: 1
+
+   Fuchsia <../pw_random_fuchsia/docs>

pw_random/docs.rst

@@ -49,3 +49,10 @@ instead of requiring an application to directly poll the hardware RNG peripheral
 when the random data is needed. This would let a device collect entropy when
 idling, improving the latency of potentially performance-sensitive areas where
 random numbers are needed.
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   Backends <backends>

pw_random_fuchsia/BUILD.bazel

@@ -0,0 +1,60 @@
+# Copyright 2024 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+load(
+    "@fuchsia_sdk//fuchsia:defs.bzl",
+    "fuchsia_cc_test",
+    "fuchsia_unittest_package",
+)
+load("//pw_build:compatibility.bzl", "incompatible_with_mcu")
+
+package(default_visibility = ["//visibility:public"])
+
+licenses(["notice"])
+
+cc_library(
+    name = "zircon_random_generator",
+    hdrs = [
+        "public/pw_random_fuchsia/zircon_random_generator.h",
+    ],
+    target_compatible_with = ["@platforms//os:fuchsia"],
+    deps = [
+        "//pw_random",
+        "//pw_span",
+    ],
+)
+
+fuchsia_cc_test(
+    name = "zircon_random_generator_test",
+    srcs = ["zircon_random_generator_test.cc"],
+    target_compatible_with = incompatible_with_mcu(),
+    deps = [
+        ":zircon_random_generator",
+        "//pw_unit_test",
+    ],
+)
+
+fuchsia_unittest_package(
+    name = "test_pkg",
+    package_name = "zircon_random_generator_tests",
+    fuchsia_api_level = "22",
+    tags = ["manual"],
+    unit_tests = [":zircon_random_generator_test"],
+)
+
+# Bazel does not yet support building docs.
+filegroup(
+    name = "docs",
+    srcs = ["docs.rst"],
+)

pw_random_fuchsia/BUILD.gn

@@ -0,0 +1,35 @@
+# Copyright 2024 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+import("//build_overrides/pigweed.gni")
+
+import("$dir_pw_docgen/docs.gni")
+import("$dir_pw_unit_test/test.gni")
+
+pw_test_group("tests") {
+  tests = []
+}
+
+pw_doc_group("docs") {
+  sources = [ "docs.rst" ]
+}
+
+# Satisfy source_is_in_build_files presubmit step
+pw_source_set("satisfy_presubmit") {
+  sources = [
+    "public/pw_random_fuchsia/zircon_random_generator.h",
+    "zircon_random_generator_test.cc",
+  ]
+  visibility = []
+}

pw_random_fuchsia/CMakeLists.txt

@@ -0,0 +1,19 @@
+# Copyright 2024 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+include($ENV{PW_ROOT}/pw_build/pigweed.cmake)
+
+
+
+# CMake does not yet support building docs.

pw_random_fuchsia/OWNERS

@@ -0,0 +1,3 @@
+[email protected]
+[email protected]
+[email protected]

pw_random_fuchsia/docs.rst

@@ -0,0 +1,13 @@
+.. _module-pw_random_fuchsia:
+
+=================
+pw_random_fuchsia
+=================
+.. pigweed-module::
+   :name: pw_random_fuchsia
+
+--------
+Overview
+--------
+The ``pw_random_fuchsia`` module provides an implementation of ``pw::random::RandomGenerator``
+that uses Zircon.

pw_random_fuchsia/public/pw_random_fuchsia/zircon_random_generator.h

@@ -0,0 +1,49 @@
+// Copyright 2024 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+#pragma once
+
+#include <zircon/assert.h>
+#include <zircon/syscalls.h>
+
+#include <climits>
+
+#include "pw_random/random.h"
+#include "pw_span/span.h"
+
+namespace pw::random_fuchsia {
+
+class ZirconRandomGenerator final : public pw::random::RandomGenerator {
+ public:
+  void Get(pw::ByteSpan dest) override {
+    zx_cprng_draw(dest.data(), dest.size());
+  }
+
+  void InjectEntropyBits(uint32_t data, uint_fast8_t num_bits) override {
+    static_assert(sizeof(data) <= ZX_CPRNG_ADD_ENTROPY_MAX_LEN);
+
+    constexpr uint8_t max_bits = sizeof(data) * CHAR_BIT;
+    if (num_bits == 0) {
+      return;
+    } else if (num_bits > max_bits) {
+      num_bits = max_bits;
+    }
+
+    // zx_cprng_add_entropy operates on bytes instead of bits, so round up to
+    // the nearest byte so that all entropy bits are included.
+    const size_t buffer_size = ((num_bits + CHAR_BIT - 1) / CHAR_BIT);
+    zx_cprng_add_entropy(&data, buffer_size);
+  }
+};
+
+}  // namespace pw::random_fuchsia

pw_random_fuchsia/zircon_random_generator_test.cc

@@ -0,0 +1,39 @@
+// Copyright 2024 The Pigweed Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not
+// use this file except in compliance with the License. You may obtain a copy of
+// the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations under
+// the License.
+
+#include "zircon_random_generator.h"
+
+#include "pw_unit_test/framework.h"
+
+namespace pw_random_zircon {
+
+TEST(ZirconRandomGeneratorTest, Get) {
+  // Getting a random number should not crash.
+  std::array<std::byte, 4> value = {std::byte{0}};
+  ZirconRandomGenerator().Get(value);
+}
+
+TEST(ZirconRandomGeneratorTest, InjectEntropyBits) {
+  ZirconRandomGenerator rng;
+  // Injecting 0 bits of entropy should safely do nothing.
+  rng.InjectEntropyBits(/*data=*/1, /*num_bits=*/0);
+  // Injecting too many bits should round down to 32 and not crash.
+  rng.InjectEntropyBits(/*data=*/1, /*num_bits=*/33);
+  // Inject the maximum number of bits.
+  rng.InjectEntropyBits(/*data=*/1, /*num_bits=*/32);
+  rng.InjectEntropyBits(/*data=*/1, /*num_bits=*/8);
+  rng.InjectEntropyBits(/*data=*/1, /*num_bits=*/31);
+}
+
+}  // namespace pw_random_zircon