blob: 2549304406c7082e9a4b23a7a21cea83a05f809a [file]
# 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/dist/distribution_manifest.gni")
import("//build/zircon/c_utils.gni")
import("//build/zircon/hermetic_code_blob.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)
#
# * data_deps
# - Optional: This can be used to reach other targets whose metadata
# should travel along with the output of this code_patches() target,
# such as code_patching_hermetic_alternative() targets. Any
# `distribution_entries` metadata (from resource() et al) in $deps
# is blocked from being reached via this target, but $data_deps is not.
# - 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,
[
"deps",
"testonly",
])
}
toolchain_utils_action(main_target) {
forward_variables_from(invoker,
[
"data_deps",
"visibility",
"testonly",
])
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",
]
sources = [ rspfile ]
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, "*")
}
if (defined(invoker.data_deps)) {
distribution_entries_barrier += invoker.data_deps
}
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 are as for hermetic_code_blob().
#
template("code_patching_hermetic_alternative") {
target_label = get_label_info(":$target_name", "label_with_toolchain")
if (defined(invoker.entrypoint)) {
blob_entrypoint = invoker.entrypoint
} else {
blob_entrypoint = target_name
}
if (defined(invoker.output_name)) {
blob_name = invoker.output_name
} else {
blob_name = target_name
}
blob_path = rebase_path("$target_out_dir/$blob_name.bin", root_build_dir)
hermetic_code_blob(target_name) {
forward_variables_from(invoker,
"*",
[
"entrypoint",
"metadata",
])
entrypoint = blob_entrypoint
metadata = {
code_patching_hermetic_alternative_barrier = []
code_patching_hermetic_alternatives = []
distribution_entries_barrier = []
distribution_entries = []
if (defined(invoker.metadata)) {
forward_variables_from(invoker.metadata, "*")
}
code_patching_hermetic_alternatives += [
{
label = target_label
name = blob_name
path = blob_path
},
]
# Behaves like a resource() target, for aggregation within a kernel
# package.
distribution_entries += [
{
source = blob_path
destination = "code-patches/$blob_name"
label = target_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 or
# generated stubs that wish to supply their own case IDs.
# - Type: string
# - Default: "arch/code-patches/case-id-asm.h"
#
# * case_id
# - Optional: The patch case ID, as an assembler expression that can use
# macros from $case_id_header.
# - Type: string
# - Default: "CASE_ID_${OUTPUT_NAME}"
#
# * 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,
[
"testonly",
"visibility",
])
forward_variables_from(invoker,
"*",
[
"aliases",
"case_id",
"case_id_header",
"deps",
"output_name",
"testonly",
"visibility",
])
sources = [ gen_file ]
deps = [
":$gen_target",
"//zircon/kernel/lib/arch:headers",
"//zircon/kernel/lib/code-patching",
]
}
generated_file(metadata_target) {
visibility = [ ":$gen_target" ]
forward_variables_from(invoker, [ "testonly" ])
outputs = [ metadata_file ]
output_conversion = "json"
data_keys = [ "code_patching_hermetic_alternatives" ]
walk_keys = [ "code_patching_hermetic_alternative_barrier" ]
forward_variables_from(invoker, [ "deps" ])
}
action(gen_target) {
visibility = [ ":$main_target" ]
forward_variables_from(invoker, [ "testonly" ])
forward_variables_from(invoker,
[
"aliases",
"case_id",
"case_id_header",
"output_name",
])
if (!defined(output_name)) {
output_name = main_target
}
if (!defined(case_id_header)) {
case_id_header = "arch/code-patches/case-id-asm.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(case_id)) {
args += [
"--case-id",
case_id,
]
}
if (defined(aliases)) {
foreach(alias, aliases) {
args += [
"--aliases",
alias,
]
}
}
}
}
# Defines a patchable function stub with several hermetic alternatives.
#
# This defines a code_patching_hermetic_stub() target, which see, along with a
# code_patching_hermetic_alternative() for each element of $versions, each
# compiled from the same $sources in a different way. The alternatives are
# reached through the main target, so dependents should use only that.
#
# Parameters
#
# * versions
# - Required: Non-empty list of scopes, each defining one alternative.
# - Type: list(scope)
# * name
# - Optional: The alternative's name, as used with
# code_patching::Patcher; this is its file name under "code-patches/"
# in the kernel package.
# - Type: string
# - Default: $output_name
# * subdir
# - Optional: If not "", then "$subdir/" is prepended to $name. This
# must not contain "/".
# - Type: string
# - Default: ""
# * allow_rodata, entrypoint
# - Optional: Overrides $default_allow_rodata or $default_entrypoint
# for this alternative; see hermetic_code_blob().
# * add_configs, remove_configs
# - Optional: Appended after the outer $add_configs and $remove_configs
# for compiling this alternative; see hermetic_code_blob().
# - Type: list(label)
# - Default: []
# * deps
# - Optional: Additional dependencies for this alternative. As in any
# source_set(), the targets in $deps are compiled with their own
# configs, unaffected by $add_configs or $remove_configs here.
# - Type: list(label)
# - Default: []
#
# * default_allow_rodata, default_entrypoint
# - Optional: Defaults for $allow_rodata and $entrypoint on each
# alternative; see hermetic_code_blob(). $default_entrypoint defaults to
# $output_name.
#
# * add_configs, remove_configs
# - Optional: See hermetic_code_blob(). Applied when compiling each
# alternative, before per-version $add_configs and $remove_configs.
#
# * aliases, case_id, case_id_header, metadata, output_name, public,
# public_configs, public_deps, testonly, visibility
# - Optional: See code_patching_hermetic_stub() and hermetic_code_blob().
# $public_configs and $public_deps also apply when compiling each
# alternative.
#
# Other parameters are as for hermetic_code_blob() and source_set() (except
# that $allow_rodata, $configs, $entrypoint, and the `output_*` parameters are
# disallowed), and apply when compiling each alternative ($asmflags, $cflags,
# $defines, $include_dirs, and $inputs also apply when assembling the stub).
#
template("code_patching_hermetic_multiversion") {
assert(defined(invoker.versions), "`versions` is a required parameter")
assert(invoker.versions != [], "`versions` must be non-empty")
assert(!defined(invoker.allow_rodata),
"use `default_allow_rodata` rather than `allow_rodata`")
assert(!defined(invoker.entrypoint),
"use `default_entrypoint` rather than `entrypoint`")
main_target = target_name
if (defined(invoker.output_name)) {
stub_name = invoker.output_name
} else {
stub_name = main_target
}
if (defined(invoker.default_entrypoint)) {
default_entrypoint = invoker.default_entrypoint
} else {
default_entrypoint = stub_name
}
alt_deps = []
foreach(version, invoker.versions) {
if (defined(version.name)) {
alt_name = version.name
} else {
alt_name = stub_name
}
if (defined(version.subdir) && version.subdir != "") {
assert(string_replace(version.subdir, "/", "") == version.subdir,
"`subdir` must not contain '/': $version")
alt_name = "${version.subdir}/$alt_name"
}
alt_target = "$main_target.$alt_name"
alt_deps += [ ":$alt_target" ]
code_patching_hermetic_alternative(alt_target) {
visibility = [ ":*" ]
forward_variables_from(invoker, [ "testonly" ])
output_name = alt_name
forward_variables_from(invoker,
"*",
[
"aliases",
"case_id",
"case_id_header",
"configs",
"default_allow_rodata",
"default_entrypoint",
"metadata",
"output_dir",
"output_extension",
"output_name",
"public",
"public_configs",
"public_deps",
"testonly",
"versions",
"visibility",
])
if (defined(version.entrypoint)) {
entrypoint = version.entrypoint
} else {
entrypoint = default_entrypoint
}
if (defined(version.allow_rodata)) {
allow_rodata = version.allow_rodata
} else if (defined(invoker.default_allow_rodata)) {
allow_rodata = invoker.default_allow_rodata
}
if (!defined(add_configs)) {
add_configs = []
}
if (defined(invoker.public_configs)) {
add_configs += invoker.public_configs
}
if (defined(version.add_configs)) {
add_configs += version.add_configs
}
if (!defined(remove_configs)) {
remove_configs = []
}
if (defined(version.remove_configs)) {
remove_configs += version.remove_configs
}
if (!defined(deps)) {
deps = []
}
if (defined(invoker.public_deps)) {
deps += invoker.public_deps
}
if (defined(version.deps)) {
deps += version.deps
}
}
}
code_patching_hermetic_stub(main_target) {
forward_variables_from(invoker,
[
"testonly",
"visibility",
])
forward_variables_from(invoker,
[
"aliases",
"asmflags",
"case_id",
"case_id_header",
"cflags",
"defines",
"include_dirs",
"inputs",
"metadata",
"output_name",
"public",
"public_configs",
"public_deps",
])
deps = alt_deps
}
}