Cross-checking Configuration

In many cases, we can add identical cross-checks to the original C and the transpiled Rust code, e.g., when the C code is naively translated to the perfectly equivalent Rust code, and everything just works. However, this might not always be the case, and we need to handle mismatches such as:

• Type mismatches between C and Rust, e.g., a C const char (with or without an attached length parameter) being translated to a str. Additionally, if a string+length value pair (with the types const char and size_t) gets translated to a single str, we may want to omit the cross-check on the length parameter.
• Whole functions added or removed by the transpiler or refactoring tool, e.g., helpers.

Note that this list is not exhaustive, so there may be many more cases of mismatches.

To handle all these cases, we need a language that lets us add new cross-checks, or modify or delete existing ones.

The cross-check language

The cross-check metadata is stored as a YAML encoding of an array of configuration entries. Each configuration entry describes the configuration for that specific check.

An example configuration file for a function foo with 3 arguments a, alen and b looks something like:

main.c:
  - item: defaults
    disable_xchecks: true
  - item: function
    name: foo
    disable_xchecks: false
    args:
      a: default
      alen: none
      b: default
    return: no
main.rs:
  - item: function
    name: foo
    args:
      a: default
      b: default
    return: no

Inline vs external configuration

We can store the cross-check configuration entries in a few places:

• Externally in separate configuration files.
• Inline in the source code, attached to the checked functions and structures.

Each approach has advantages and drawbacks.Inline configuration entries are simpler to maintain, but do not scale as well to larger codebases or more complex cross-check configuration entries.Conversely, external configuration entries are more flexible and can potentially express complex configurations in a cleaner and more elegant way, but can easily get out of sync with their corresponding source code.We currently support both approaches, with external configuration settings taking priority over inline attributes where both are present.

In the current implementation of the Rust cross-checker, inline configuration settings are passed to the enclosing scope's #[cross_check] attribute, e.g.:

#![allow(unused_variables)]
fn main() {
#[cross_check(yes, entry(djb2="foo"))]
fn bar() { }
#[cross_check(yes, entry(fixed=0x1234))]
fn baz() { }
}

Configuration file format

At the top level, each configuration file is a YAML associative array mapping file names to their configuration entries.Each array element maps a file name (represented as a string) to a list of individual items, each item representing a Rust/C scope entity, i.e., function or structure.Each item is encoded in YAML as an associative array.All items have a few common array members:

• item specifies the type of the current item, e.g., function, struct or others.
• name specifies the name of the item, i.e., the name of the function or structure.

Function cross-check configuration

Function cross-checks are configured using entries with item: function.Function entries support the following fields:

Structure cross-check configuration

Structure entries configure cross-checks for Rust structure, tuple and enumeration types, and are tagged with item: struct.For a general overview of cross-checking for structures (aggregate types), see the hashing documentation.Structure entries support the following fields:

The field_hasher and custom_hash provide two alternative methods of customizing the hashing algorithm for a given structure: users may either provide a custom implementation of CrossCheckHasher and pass that to field_hasher, or implement a hashing function and pass it to custom_hash. The two alternatives are mostly equivalent, and users may use whichever is more convenient. Additionally, users can choose to completely disable the automatic derivation of CrossCheckHash, and manually implement CrossCheckHasher for some of the types instead.

Cross-check types

There are several types of cross-check implemented in the compiler:

Each cross-check is encoded in YAML as either a single word with the type, e.g., default, or a single-element associative array mapping the type to its argument, e.g., { fixed: 0x1234 }.

More cross-check types may be added as needed.

Custom hash functions for structures

If custom_hash: { custom: "hash_foo" } is a configuration entry for structure Foo, then the compiler will insert a call to hash_foo to perform the cross checks. This function should have the following signature:

#![allow(unused_variables)]
fn main() {
fn hash_foo<XCHA, XCHS>(foo: &Foo, depth: usize) -> u64 { ... }
}

The hash function receives a reference to a Foo object and a maximum depth, and should return the 64-bit hash value for the given object.

Custom hash functions for structure fields

If bar: { custom: "hash_bar" } is a configuration entry for field bar, then the compiler will insert a call to hash_bar to compute the hash for bar. This function should have the following signature:

#![allow(unused_variables)]
fn main() {
fn hash_bar<XCHA, XCHS, S, F>(h: &mut XCHA, foo: &S, bar: &F, depth: usize)
       where XCHA: cross_check_runtime::hash::CrossCheckHasher { ... }
}

The function receives the following arguments:

• The current aggregate hasher for this structure. The function can call the hasher's write_u64 function as many times as needed.
• The structure containing this field. This argument has generic type S, so the same function can be reused for different structures.
• The field itself, with generic type F. The function may require additional type bounds for F to make it compatible with its callers.
• The maximum hashing depth (explained in the hashing documentation).
• The type parameters XCHA and XCHS bound to the current aggregate and simple value hasher for the current invocation.

This function should not return the hash value of the field. Instead, the function should call the hasher's write_u64 method directly.

Per-file default settings

The special defaults item type specifies the default cross-check settings for all items in a file.We currently support the following entries:

More examples

](https://c2rust.com/manual/docs/#more-examples)[

Function example

Example configuration for a function baz1(a, b):

main.rs:
  - item: function
    name: baz1
    entry: { djb2: "baz" }    // Cross-check the function as "baz"
    args:
      a: { custom: "foo(a)" } // Cross-check a as foo(a)
      b: none                 // Do not cross-check b
    entry_extra:              // Cross-check foo(b) with a FUNCTION_ARG tag
      - { custom: "foo(b)", tag: FUNCTION_ARG }
      - { custom: "a" }       // Cross-check the value "a" with UNKNOWN_TAG

Structure example

Example configuration for a structure Foo (illustrated on an object foo of type Foo):

main.rs:
  - item: struct
    name: Foo
    field_hasher: "FooHasher"  // Use FooHasher as the aggregate hasher
    fields:
      a: { fixed: 0x12345678 } // Use 0x12345678 as the hash of foo.a
      b: { custom: "hash_b" }  // Hash foo.b using hash_b(foo.b)
      c: none                  // Ignore foo.c when hashing foo

Inline cross-check configuration

In addition to the external configuration format, a subset of cross-checks can also be configured inline in the program source code. The compiler plugin provides a custom #[cross_check] attribute used to annotate functions, structures and fields with custom cross-check metadata.

Inline function configuration

The #[cross_check] function attribute currently supports the following arguments:

Function example

#![allow(unused_variables)]
fn main() {
#[cross_check(yes, entry(djb2="foo"))] // Cross-check this function as "foo"
fn foo1() {
  #[cross_check(none)]
  fn bar() { ... }
  bar();
  #[cross_check(yes, all_args(default), args(a(fixed=0x123)))]
  fn baz(a: u8, b: u16, c: u32) { ... }
  baz(1, 2, 3);
}
}

Inline structure configuration

The compiler plugin also supports a subset of the full external configuration settings as #[cross_check] arguments:

The #[cross_check] attribute can also be attached to structure fields to configure hashing:

Structure example

#![allow(unused_variables)]
fn main() {
#[cross_check(field_hasher="MyHasher")]
struct Foo {
  #[cross_check(none)]
  foo: u64,
  #[cross_check(fixed=0x1234)]
  bar: String,
  #[cross_check(custom_hash="hash_baz")]
  baz: String,
}
}

Caveats

](https://c2rust.com/manual/docs/#caveats)[

Duplicate items

At any level or scope, there may be duplicate items, i.e., multiple items with the same names.It is not clear at this point how to best handle this case, since we have several conflicting requirements.On the one hand, we may wish to allow the configuration for one source file to be spread across multiple configuration files, and entries from later configuration files to be appended or replace entries from earlier files.On the other hand, we may have identically-named structures or functions in nested scopes that we want to configure separately. For an example, consider the following code:

fn foo(x: u32) -> u32 {
    if x > 22 {
        fn bar(x: u32) -> u32 {
            x - 22
        };
        bar(x)
    } else {
        fn bar(x: u32) -> u32 {
            x + 34
        }
        bar(x)
    }
}

In this example, there are two distinct foo::bar functions, and we wish to configure them separately.However, at the top level of a file, there may only be one foo function, so we can merge all entries for foo together. Alternatively, we could check for multiple top-level items with the same name and exit with an error if we encounter any duplicates.

Configuration priority

Currently, if a certain cross-check is configured using both an external entry and an inline #[cross_check(…)] attribute, the external entry takes priority. Alternatively, we may reverse this priority, or exit with an error if both are present.

Scope configuration inheritance

The configuration settings described above apply to the scope of an item. While most settings apply exclusively to the scope itself (for example, args and all_args settings only apply to the current function, e.g., foo above and not any of the bar functions) and not any of its nested sub-items, there are a few that apply to everything inside the scope. These attributes are internally "inherited" from each scope by its child scopes. Currently, the only inherited attributes are disable_xchecks (so that disabling cross-checks for a module or function disables them for everything inside that function), ahasher and shasher.

Custom cross-check parameters

Custom cross-check definitions have a different format for each language. The rustc plugin accepts any Rust expression that is valid on function entry as a custom cross-check.

The clang plugin, on the other hand, only accepts a limited subset of C expressions: each cross-check specification contains the name of the function to call, optionally followed by a list of parameters to pass to the function, e.g., function or function(arg1, arg2, …). Each parameter is the name of a global variable or function argument, and is optionally preceded by & (to pass the parameter by address instead of value) or by * (to dereference the value if it is a pointer).

Anonymous structures

C allows developers to define anonymous structures that define the type for a single value, e.g.:

struct {
  int x;
} y;

For a variety of reasons, we need to assign names to these structures ourselves.The most important reason is that we need to identify these structures in the external configuration files.We assign the names using one of the following formats, depending on the context where the anonymous structure is defined:

Examples

struct Foo {
  struct {                  // This gets named `Foo$field$x`
    int x;
  }
};
struct { int a; }           // This gets the `foo$result` name
foo(struct { int b; } x) { // The `x` argument type gets the `foo$arg$x` name
}