|
| 1 | +\ingroup module_hidden |
| 2 | +\page modular-verification-static Modular Verification of Static Functions |
| 3 | + |
| 4 | +\section verification-of-static Modular Verification of Static Functions |
| 5 | + |
| 6 | +\author Kareem Khazem |
| 7 | + |
| 8 | +This page describes how to use CBMC on static functions. |
| 9 | + |
| 10 | +\tableofcontents |
| 11 | + |
| 12 | +CBMC can check libraries and other codebases that expose several |
| 13 | +entry points. To do this, users typically write a *harness* that |
| 14 | +captures the entry points' API contract, and that calls into the API |
| 15 | +with unconstrained values. The example below shows such a library and |
| 16 | +harness: |
| 17 | + |
| 18 | +\code{.c} |
| 19 | +void public_api_function(const int *a, int *b) |
| 20 | +{ |
| 21 | + // ... |
| 22 | + private_function(a, b); |
| 23 | + // ... |
| 24 | +} |
| 25 | + |
| 26 | +static void private_function(const int *a, int *b) |
| 27 | +{ |
| 28 | + // ... |
| 29 | +} |
| 30 | +\endcode |
| 31 | + |
| 32 | +The harness sets up some assumptions and then calls into the API: |
| 33 | + |
| 34 | +\code{.c} |
| 35 | +void public_api_function(int *a, int *b); |
| 36 | + |
| 37 | +void harness() |
| 38 | +{ |
| 39 | + int a, b; |
| 40 | + __CPROVER_assume(a < 10); |
| 41 | + __CPROVER_assume(a >= 0); |
| 42 | + public_api_function(&a, &b); |
| 43 | + __CPROVER_assert(b != a); |
| 44 | +} |
| 45 | +\endcode |
| 46 | + |
| 47 | +The following commands build and check this function: |
| 48 | + |
| 49 | +\code{.sh} |
| 50 | +> goto-cc -c -o library.o library.c |
| 51 | +> goto-cc -c -o harness.o harness.c |
| 52 | +> goto-cc -o to_check.gb library.o harness.o |
| 53 | +> cbmc --function harness to_check.gb |
| 54 | +\endcode |
| 55 | + |
| 56 | +\subsection stubbing-out-static Stubbing out static functions |
| 57 | + |
| 58 | +For performance reasons, it might be desirable to analyze the API |
| 59 | +function independently of the static function. We can analyze the API |
| 60 | +function by "stubbing out" the static function, replacing it with a |
| 61 | +function that does nothing apart from asserting that its inputs satisfy |
| 62 | +the function's contract. ("Stubbing out" a function is sometimes known |
| 63 | +as "modelling" or "abstracting it out".) Add the following to |
| 64 | +`harness.c`: |
| 65 | + |
| 66 | +\code{.c} |
| 67 | +static void private_function(const int *a, int *b) |
| 68 | +{ |
| 69 | + __CPROVER_assert( private_function_precondition ); |
| 70 | + __CPROVER_assume( private_function_postcondition ); |
| 71 | +} |
| 72 | +\endcode |
| 73 | + |
| 74 | +And build as follows, stripping the original static function out of its |
| 75 | +object file: |
| 76 | + |
| 77 | +\code{.sh} |
| 78 | +> goto-cc -c -o library.o library.c |
| 79 | +> goto-instrument --remove-function-body private_function library.o library-no-private.o |
| 80 | +> |
| 81 | +> goto-cc -c -o harness.o harness.c |
| 82 | +> |
| 83 | +> # The stub in the harness overrides the implementation of |
| 84 | +> # private_function whose body has been removed |
| 85 | +> goto-cc -o to_check.gb library-no-private.o harness.o |
| 86 | +> cbmc --function harness to_check.gb |
| 87 | +\endcode |
| 88 | + |
| 89 | +\subsection checking-static Separately checking static functions |
| 90 | + |
| 91 | +We should now also write a harness for `private_function`. However, |
| 92 | +since that function is marked `static`, it is not possible for functions |
| 93 | +in external files to call it. We can write and link a harness by |
| 94 | +stripping the `static` attribute from `private_function` using goto-cc's |
| 95 | +`--export-file-local-symbols` flag. |
| 96 | + |
| 97 | +\code{.sh} |
| 98 | +> goto-cc -c -o --export-file-local-symbols library_with_static.o library.c |
| 99 | +\endcode |
| 100 | + |
| 101 | +`library_with_static.o` now contains an implementation of `private_function()` |
| 102 | +with a mangled name. We can display the mangled name with goto-instrument: |
| 103 | + |
| 104 | +\code{.sh} |
| 105 | +> goto-instrument --show-symbol-table library_with_static.o | grep -B1 -A1 "Pretty name.: private_function" |
| 106 | +Symbol......: __CPROVER_file_local_library_c_private_function |
| 107 | +Pretty name.: private_function |
| 108 | +Module......: private_function |
| 109 | +\endcode |
| 110 | + |
| 111 | +When we write a harness for the static function, we ensure that we call |
| 112 | +the mangled name: |
| 113 | + |
| 114 | +\code{.c} |
| 115 | +void harness() |
| 116 | +{ |
| 117 | + int a, b; |
| 118 | + |
| 119 | + __CPROVER_assume( private_function_precondition ); |
| 120 | + |
| 121 | + // Call the static function |
| 122 | + __CPROVER_file_local_library_c_private_function(&a, &b); |
| 123 | + |
| 124 | + __CPROVER_assert( private_function_postcondition ); |
| 125 | +} |
| 126 | +\endcode |
| 127 | + |
| 128 | +We can then link this harness to the object file with exported symbols |
| 129 | +and run CBMC as usual. |
| 130 | + |
| 131 | +\code{.sh} |
| 132 | +> goto-cc -c -o private_harness.o private_harness.c |
| 133 | +> goto-cc -o to_test.gb private_harness.o library_with_static.o |
| 134 | +> cbmc --function harness to_test.gb |
| 135 | +\endcode |
| 136 | + |
| 137 | +It is possible that CBMC will generate the same mangled name for two |
| 138 | +different static functions. This happens when the functions have the |
| 139 | +same name and are written in same-named files that live in different |
| 140 | +directories. In the following codebase, the two `qux` functions will |
| 141 | +both have their names mangled to `__CPROVER_file_local_b_c_qux`, and |
| 142 | +so any harness that requires both of those files will fail to link. |
| 143 | + |
| 144 | + project |
| 145 | + | |
| 146 | + \_ foo |
| 147 | + | | |
| 148 | + | \_ a.c |
| 149 | + | \_ b.c <- contains static function "qux" |
| 150 | + | |
| 151 | + \_ bar |
| 152 | + | |
| 153 | + \_ c.c |
| 154 | + \_ b.c <- also contains static function "qux" |
| 155 | + |
| 156 | +The solution is to use the `--mangle-suffix` option to goto-cc. This |
| 157 | +allows you to specify a different suffix for name-mangling. By |
| 158 | +specifying a custom, different suffix for each of the two files, the |
| 159 | +mangled names are unique and the files can be successfully linked. |
| 160 | + |
| 161 | +More examples are in `regression/goto-cc-file-local`. |
0 commit comments