Metadata-Version: 2.1
Name: fusa_gcc_plugin_generator
Version: 0.3.6
Summary: Synthesizer for valid-apis.json
Home-page: https://gitlab.com/CentOS/automotive/src/fusa-gcc-plugin
Author: Contributors to the fusa-gcc-plugin project
License: LGPL-2.1-or-later
Project-URL: Homepage, https://gitlab.com/CentOS/automotive/src/fusa-gcc-plugin
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Generator

A standalone project to generate `valid_apis.json` to use with the
fusa-gcc-plugin project. This helps developers maintain their own
`valid_apis.json` files with their select subset of APIs that they
want the plugin to allow.

## Inputs

The inputs to the script are captured in the `api-sets` directory. The structure
is basically this:

```
api-sets/
├── math
│   ├── list
│   └── template.c
├── string
│   ├── list
│   └── template.c
└── string-fortified
    ├── cflags
    ├── list
    └── template.c
```

The top level API sets needs to contain subdirectories named after an
api-scope. Within the api-scope subdirectories, there needs to be:

- `list`: file containing a list of the APIs to accept per that api-scope.
- `template.*`: defines how the synthesized source file can be generated
  for the APIs in the list. These generated files are then fed into the
  `fusa-gcc-plugin`. The suffix of the template file can be anything, more
  details can be found in the later sections of this document.
- `cflags`: (Optional) File that contains the list of cflags to use when feeding
  the synthesized files into the `fusa-gcc-plugin`.

The `list` file is a text file that contains the list of APIs to add to the
`valid_apis.json` file and it looks like the following:

```
math,acosf
math,acos
math,acoshf
math,acosh
math,asinf
```

Each line contains two items that are separated by a comma. The first item is
the api-scope (typically this should match the parent subdirectory but it is not
strictly required and can differ if necessary to handle scoping) and the second
item is the function name.

The `template` file should look like a source code file that can be compiled
with gcc.

```
#define _GNU_SOURCE

#include <stdint.h>
#include <math.h>
#include <complex.h>
#include <fenv.h>

int main() {
  return (intptr_t)FUNCTION;
}
```

The `FUNCTION` string is dynamically replaced with the API function name for
each item in the `list` file.

The `cflags` file contains whitespace separated `CFLAGS` that can be added to
the gcc command when dumping the APIs with the `fusa-gcc-plugin`. For example:

```
-D_FORTIFY_SOURCE=3 -O
```

Note that the parser of this file works on simple whitespace splitting so values
with spaces embedded are not possible.

## Running generator.py

To run the script, the fusa-gcc-plugin must be available in the local
environment. You can download and compile that plugin in the parent directory.

It should typically be installed to `/usr/lib64/fusa.so`.

To run the script, basically execute generator.py with python3 (3.9+).

```
python3 generator.py
```

It also accepts some basic input parameters. You can learn more by running it
with `--help`.

```
$ python3 generate.py --help
usage: generate.py [-h] [--plugin-path PLUGIN_PATH] [--api-sets API_SETS]
[--profile {asil-b}] [--output OUTPUT]

Synthesizer for valid_apis.json

options:
  -h, --help            show this help message and exit
  --plugin-path PLUGIN_PATH
                        File path for fusa plugin so file (/usr/lib64/fusa.so)
  --api-sets API_SETS   Root directory of APIs to synthesize (./api-sets)
  --profile {asil-b}    ASIL Profile of output json
  --output OUTPUT       Output directory of results (./output)
```

## Outputs

The `generator.py` script will produce some output files in a directory named
`output` (by default, can be overridden via the script parameters).

Within that directory, a timestamped directory is created (the time the script
is executed), and the results of `generator.py` are stored there.

```
output/
└── 1707480208.6854048
    ├── json-files
    │   ├── math
    │   │   ├── qualify_083804f599ba53ad85722e1ed014e6ca739d43214eada1ad7a2462b952c33472.json
    │   │   ├── qualify_0948e3f6e41fae7c75fd06dbc4fa8ef5882cd4c6976f2800306363f355c46462.json
    │   │   ├── qualify_0b0afeeafb1ae26930d742c882f3f40001b52002f45e00a2e4fd1df15e74f8e9.json
    │   │   ├── [...]
    │   │   └── tmp
    │   │       ├── test-math-acosf.o
    │   │       ├── test-math-acoshf.o
    │   │       ├── test-math-acosh.o
    │   │       ├── [...]
    │   └── string
    │       ├── qualify_11a38c8ad17972d864dbd828e59f161fc2df18aecb6d2120393a2a70f8af1c11.json
    │       ├── qualify_130513b64776ed57ce3634b89558bf427ccd5901e72cdf451de620ef587bff6c.json
    │       ├── qualify_142242c56a1b6cd92771c8c69ca0ac8a5058718ec2fc03a4f616a073a9fc6066.json
    │       ├── [...]
    │       └── tmp
    │           ├── test-string-ffs.o
    │           ├── test-string-memccpy.o
    │           ├── test-string-memchr.o
    │           ├── [...]
    ├── valid_apis.json
    └── synthetic-files
        ├── math
        │   ├── test-math-acos.c
        │   ├── test-math-acosf.c
        │   ├── test-math-acosh.c
        │   ├── [...]
        └── string
            ├── test-string-ffs.c
            ├── test-string-memccpy.c
            ├── test-string-memchr.c
            ├── [...]
```

Under the timestamped output directory, there will sit several subdirectories
and files.

The `synthetic-files` subdirectory that contains the synthesized source files
from the API sets which will be used as input to the fusa-gcc-plugin to dump the
APIs associated.

The `json-files` subdirectory contains the results of running fusa-gcc-plugin on
the synthesized files.

The `valid_apis.json` file is the final output of the generator and is the
result of merging the json files in `json-files` together to create one cohesive
json file as input to the fusa-gcc-plugin.
