jirislaby / clang-struct

clang-struct – Indexed Structures of the Kernel

clang-struct is a clang plugin which indexes structures, its members, and member uses into an sqlite3 database. clang-struct is primarily aimed, but not limited, to index the Linux kernel. When the code is indexed, it is easy to find unused members of structures or even whole structures.

Building

Proceed with the standard cmake steps like:

mkdir build
cd build
cmake -G Ninja ..
ninja

Filling in the Database

Manually

1. Run db_filler
2. Run several clang -cc1 -analyze -load clang-struct.so -analyzer-checker jirislaby.StructMembersChecker source.c processes.
3. Stop db_filler by a TERM/INT signal

In a Batch

A batch runner (to do all the steps) is also available in scripts/run_commands.pl. It needs compile_commands.json generated in the kernel using make compile_commands.json. For example this will generate the database:

make O=../build configure_the_kernel_as_usual
make O=../build compile_commands.json
cd ../build
export PATH=<path_to_clang-struct_scripts>:$PATH
export LD_LIBRARY_PATH=<path_to_clang-struct.so>
run_commands.pl

Looking at the Results

CLI – the Database

The resulting database is named structs.db. There are several views available, see the output of sqlite3 structs.db .schema. The content can be investigated for example by running these under sqlite3 structs.db:

SELECT * FROM use_view;
SELECT * FROM unused_view;

Web Frontend

Also a web frontend exists in frontend/. It's written in Ruby on Rails. Bundler is supposed to take care of bringing it up:

bundle install
bundle exec rails credentials:edit
bundle exec rake assets:precompile
bundle exec rails server -e production

Note that libyaml-devel and ruby-devel packages are likely needed for install to succeed.

Docker Image

Feel free to pull and run also a docker image. It contains a pre-built database for the latest major Linux kernel release.

docker pull jirislaby/ror-clang-struct
docker run -p 3000:3000 -e RAILS_MASTER_KEY=753e802f52bb90408604adbb90e0d0aa jirislaby/ror-clang-struct

Then visit http://localhost:3000.

clang-struct's Issues

<unnamed> member uses even though they are named

select * from use_view where struct = 'execlist_ctx_descriptor_format' and src like '%i915%execl%';

gives:

┌─────────┬────────────────────────────────┬───────────┬─────────────────────────────────────┬───────────────────┬──────┬──────────┐
│   id    │             struct             │  member   │                 src                 │     location      │ load │ implicit │
├─────────┼────────────────────────────────┼───────────┼─────────────────────────────────────┼───────────────────┼──────┼──────────┤
│ 3704268 │ execlist_ctx_descriptor_format │ <unnamed> │ drivers/gpu/drm/i915/gvt/execlist.c │ 66:1365-66:1392   │ 1    │ 0        │

don't create entries repeatedly

Especially sources.

Add parent id to struct

To track embedded structures comfortably (maybe with recursive queries).

store version/hash and currently used .config

So that we know... (And use the hash when linking to kernel.org.)

nested structures in packed ones are packed too

struct X {
  struct Y {
    int a;
  };
} __packed;

Y is packed too.

If a struct contains `reserved` or `pad`, stamp is as ABI

reserved, pad, __be, ... is all ABI and others cannot be "unused".

Consider those with ignore-case.

If a structure is defined inside macro, it's of less interest

Like those bs of TRACE_EVENT.

recursive queries don't work for `struct_group_tagged`

struct_group_tagged like used in struct page_pool_params in https://github.com/torvalds/linux/blob/v6.9/include/net/page_pool/types.h#L59, causes the recursive queries like in /structs/33447 to loop forever.
It's due to naive logic in the query and inability to jump to children/parents (see #6).

In that query, we alternate adding both structs from the struct_group_tagged as they both have same presumed location.