zircon/kernel/lib/code-patching/code-patching.gni

# Copyright 2020 The Fuchsia Authors
#
# Use of this source code is governed by a MIT-style
# license that can be found in the LICENSE file or at
# https://opensource.org/licenses/MIT

import("//build/zircon/c_utils.gni")
import("//build/zircon/zircon_cpu.gni")

## This file provides the templates needed to extract code-patching directives
## stored in a special ELF section, and needed to specify code patching
## alternatives and the functions to be later patched by those alternatives.
##
## Example usage:
## ```
##  # Two possible patches for memset.
##  code_patching_hermetic_alternative("memset_slow") {
##    sources = ["memset_slow.c"]
##  }
##
##  code_patching_hermetic_alternative("memset_fast") {
##     sources = ["memset_fast.S"]
##  }
##
##  # Generates an object file that defines a stub `memset` - requiring later
##  # patching - filled with traps and just large enough to fit any of the
##  # associated alternatives.
##  code_patching_hermetic_stub("memset") {
##
##    # Aggregates metadata on alternatives.
##    deps = [":memset_slow", ":memset_fast"]
##  }
## ```
##

# Extracts the content of the ".code-patches" sections from the linking
# target reached by in $deps.
#
# There is no particular output file this target produces as its API.
# Instead, having this target in $deps of a kernel_package() ensures the
# file "code-patches.bin" appears in the package file tree.
#
# Parameters
#
#   * deps
#     - Required: Must reach exactly one linking target as per metadata
#       barriers used by link_output_rspfile(), which see.  The code
#       consuming the "code-patches.bin" file from the kernel package is
#       expected to know what single ELF file the address constants in that
#       file refer to, so it doesn't make sense to have more than one
#       linkable target that might have ".code-patches" section data to
#       extract.
#     - Type: list(label)
#
#   * metadata, testonly, visibility
#     - See action().
#
template("code_patches") {
  assert(defined(invoker.deps), "`deps` is a required parameter")

  main_target = target_name
  output_file = "$target_out_dir/$target_name.bin"
  rspfile_target = "_code_patches.rsp.${target_name}"
  rspfile = "${target_gen_dir}/${target_name}.code_patches.rsp"

  link_output_rspfile(rspfile_target) {
    visibility = [ ":$main_target" ]
    outputs = [ rspfile ]
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "deps",
                           ])
  }

  toolchain_utils_action(main_target) {
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "visibility",
                           ])
    outputs = [ output_file ]

    # Nothing prevents link_output_rspfile() from collecting multiple
    # binary files here if $deps reaches more than one without barrier.
    # This is verboten and will just make objcopy die from having too many
    # positional arguments after @rspfile expansion, so there's no need to
    # check for it otherwise (which would require a wrapper script).
    utils = [ "objcopy" ]
    script = true
    args = [
      "--dump-section=.code-patches=" + rebase_path(outputs[0], root_build_dir),
      "@" + rebase_path(rspfile, root_build_dir),
      "/dev/null",
    ]

    deps = [ ":$rspfile_target" ]

    metadata = {
      # Behaves like a resource() target, for aggregation within a kernel
      # package.
      distribution_entries_barrier = []
      distribution_entries = []

      if (defined(invoker.metadata)) {
        forward_variables_from(invoker.metadata, "*")
      }

      distribution_entries += [
        {
          source = rebase_path(outputs[0], root_build_dir)
          destination = "code-patches.bin"
          label = get_label_info(":$main_target", "label_with_toolchain")
        },
      ]
    }
  }
}

# Defines a "hermetic leaf" code patching alternative, which is defined by the
# following properties (enforced at link-time):
#
# * the named function (`entrypoint`) is first in the link order and all of the
#   sources/deps together form a closed set that is collectively hermetic;
# * no non-code (rodata or writable data) sections;
# * no dynamic relocations.
#
# Used in conjunction with code_patching_hermetic_stub() (see below), several
# alternatives may be defined so that code patching logic can make a runtime
# decision of which one of these should be used.
#
# It produces a raw binary content of a position-indepdendent executable,
# output to `target_out_dir` with an extension of "bin".
#
# Parameters
#
#   * entrypoint
#     - Optional: The name of the symbol (or C function) providing this
#       alternative and defined in `sources`.
#     - Type: string
#     - Default: $target_name.
#
# Other parameters are as for executable(), except for the `output_*`
# parameters.
#
template("code_patching_hermetic_alternative") {
  image_target = target_name
  executable_target =
      "_code_patching_hermetic_alternative.$target_name.executable"

  if (defined(invoker.entrypoint)) {
    entrypoint = invoker.entrypoint
  } else {
    entrypoint = target_name
  }

  executable(executable_target) {
    forward_variables_from(invoker, [ "testonly" ])
    visibility = [ ":*" ]

    forward_variables_from(invoker,
                           "*",
                           [
                             "output_name",
                             "output_dir",
                             "output_extension",
                             "entrypoint",
                             "visibility",
                             "testonly",
                           ])

    output_name = entrypoint
    output_dir = target_out_dir

    configs += [ "//zircon/kernel/lib/code-patching:hermetic-leaf.config" ]
    configs += [ "//build/config/zircon:static-pie-link" ]
    configs -= [ "//build/config/zircon:static-pie-link" ]

    ldflags = [ "-Wl,-defsym,HERMETIC_LEAF_ENTRY=$entrypoint" ]
  }

  image_binary(image_target) {
    forward_variables_from(invoker,
                           [
                             "visibility",
                             "testonly",
                           ])
    deps = [ ":$executable_target" ]
    output_name = entrypoint
    output_dir = target_out_dir
    output_extension = "bin"

    output_path = rebase_path("$output_dir/$output_name.$output_extension",
                              root_build_dir)
    image_label = get_label_info(":$image_target", "label_with_toolchain")

    # We expect no dynamic relocations.
    pure = true

    metadata = {
      code_patching_hermetic_alternative_barrier = []
      code_patching_hermetic_alternatives = [
        {
          label = image_label
          name = entrypoint
          path = output_path
        },
      ]

      # Behaves like a resource() target, for aggregation within a kernel
      # package.
      distribution_entries_barrier = []
      distribution_entries = [
        {
          source = output_path
          destination = "code-patches/$entrypoint"
          label = image_label
        },
      ]
    }
  }
}

# Defines a function stub that is intended to be linked against and patched
# later. Specifically, it is indended that it will be patched by one of the
# code_patching_hermetic_alternative() targets in its dependency graph. The
# function will have a size equal to the largest of its associated alternatives
# and will initially be filled with trap instructions.
#
# This target should be regarded as an opaque source_set() that defines this
# function alone.
#
# Parameters
#
#   * output_name
#     - Optional: The name of the function stub to generate, which must be a
#       valid C identifier.
#     - Type: string
#     - Default: $target_name.
#
#   * deps
#     - Required: Dependencies to reach all
#       code_patching_hermetic_alternative() targets the stub may resolve to at
#       runtime.
#     - Type: list(label)
#
#   * case_id_header
#     - Optional: a header path that defines patch case IDs. These IDs are
#       expected to be of the form "CASE_ID_${OUTPUT_NAME}", where
#       "${OUTPUT_NAME}" is the upper-cased transformation of "${output_name}".
#       This parameter is only expected to be explicitly set for tests that
#       wish to supply their own case IDs.
#     - Type: string
#     - Default: "arch/code-patches/case-id.h"
#
#   * aliases
#     - Optional: A list of weak symbols to define as aliases to the associated
#       function.
#     - Type: list(string)
#
# Other parameters are as for source_set().
#
template("code_patching_hermetic_stub") {
  main_target = target_name
  gen_target = "_code_patching_hermetic_stub.gen.$main_target"
  metadata_target = "_code_patching_hermetic_stub.json.$main_target"

  gen_file = "$target_gen_dir/$main_target.S"
  metadata_file = "$target_gen_dir/$main_target.json"

  source_set(main_target) {
    forward_variables_from(invoker,
                           "*",
                           [
                             "visibility",
                             "testonly",
                             "case_id_header",
                             "output_name",
                             "deps",
                             "aliases",
                           ])
    forward_variables_from(invoker,
                           [
                             "visibility",
                             "testonly",
                           ])

    sources = [ gen_file ]
    deps = [
      ":$gen_target",
      "//zircon/kernel/lib/arch:headers",
      "//zircon/kernel/lib/code-patching:headers",
    ]
  }

  generated_file(metadata_target) {
    visibility = [ ":$gen_target" ]
    outputs = [ metadata_file ]

    output_conversion = "json"
    data_keys = [ "code_patching_hermetic_alternatives" ]
    walk_keys = [ "code_patching_hermetic_alternative_barrier" ]

    forward_variables_from(invoker,
                           [
                             "deps",
                             "testonly",
                           ])
  }

  action(gen_target) {
    visibility = [ ":$main_target" ]
    forward_variables_from(invoker,
                           [
                             "testonly",
                             "output_name",
                             "case_id_header",
                             "aliases",
                           ])
    if (!defined(output_name)) {
      output_name = main_target
    }

    if (!defined(case_id_header)) {
      case_id_header = "arch/code-patches/case-id.h"

      # Public to propagate to :main_target.
      public_deps = [ "//zircon/kernel/arch/$zircon_cpu/code-patches:headers" ]
    }

    outputs = [ gen_file ]
    sources = [ metadata_file ]
    deps = [ ":$metadata_target" ]

    depfile = "$gen_file.d"
    script = "//zircon/kernel/lib/code-patching/hermetic-stub.py"
    args = [
      "--name",
      output_name,
      "--header",
      case_id_header,
      "--metadata-file",
      rebase_path(metadata_file, root_build_dir),
      "--depfile",
      rebase_path(depfile, root_build_dir),
      "--outfile",
      rebase_path(outputs[0], root_build_dir),
    ]

    if (defined(aliases)) {
      foreach(alias, aliases) {
        args += [
          "--aliases",
          alias,
        ]
      }
    }
  }
}