| # 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 | |
| } | |
| } |