summaryrefslogtreecommitdiffstats
path: root/qemu/scripts/clean-includes
blob: 72b47f17f97d864420ee4c94ddb2e64396182e71 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
#!/bin/sh -e
#
# Clean up QEMU #include lines by ensuring that qemu/osdep.h
# is the first include listed in .c files, and no headers provided
# by osdep.h itself are redundantly included in either .c or .h files.
#
# Copyright (c) 2015 Linaro Limited
#
# Authors:
#  Peter Maydell <peter.maydell@linaro.org>
#
# This work is licensed under the terms of the GNU GPL, version 2
# or (at your option) any later version. See the COPYING file in
# the top-level directory.

# Usage:
#   clean-includes [--git subjectprefix] file ...
# or
#   clean-includes [--git subjectprefix] --all
#
# If the --git subjectprefix option is given, then after making
# the changes to the files this script will create a git commit
# with the subject line "subjectprefix: Clean up includes"
# and a boilerplate commit message.
#
# Using --all will cause clean-includes to run on the whole source
# tree (excluding certain directories which are known not to need
# handling).

# This script requires Coccinelle to be installed.

# .c files will have the osdep.h included added, and redundant
# includes removed.
# .h files will have redundant includes (including includes of osdep.h)
# removed.
# Other files (including C++ and ObjectiveC) can't be handled by this script.

# The following one-liner may be handy for finding files to run this on.
# However some caution is required regarding files that might be part
# of the guest agent or standalone tests.

# for i in `git ls-tree --name-only HEAD`  ; do test -f $i && \
#   grep -E '^# *include' $i | head -1 | grep 'osdep.h' ; test $? != 0 && \
#   echo $i ; done


GIT=no

# Extended regular expression defining files to ignore when using --all
XDIRREGEX='^(tests/tcg|tests/multiboot|pc-bios|disas/libvixl)'

if [ $# -ne 0 ] && [ "$1" = "--git" ]; then
    if [ $# -eq 1 ]; then
        echo "--git option requires an argument"
        exit 1
    fi
    GITSUBJ="$2"
    GIT=yes
    shift
    shift
fi

if [ $# -eq 0 ]; then
    echo "Usage: clean-includes [--git subjectprefix] [--all | foo.c ...]"
    echo "(modifies the files in place)"
    exit 1
fi

if [ "$1" = "--all" ]; then
    # We assume there are no files in the tree with spaces in their name
    set -- $(git ls-files '*.[ch]' | grep -E -v "$XDIRREGEX")
fi

# Annoyingly coccinelle won't read a scriptfile unless its
# name ends '.cocci', so write it out to a tempfile with the
# right kind of name.
COCCIFILE="$(mktemp --suffix=.cocci)"

trap 'rm -f -- "$COCCIFILE"' INT TERM HUP EXIT

cat >"$COCCIFILE" <<EOT
@@
@@

(
+ #include "qemu/osdep.h"
 #include "..."
|
+ #include "qemu/osdep.h"
 #include <...>
)
EOT


for f in "$@"; do
  case "$f" in
    *.inc.c)
      # These aren't standalone C source files
      echo "SKIPPING $f (not a standalone source file)"
      continue
      ;;
    *.c)
      MODE=c
      ;;
    *include/qemu/osdep.h | \
    *include/qemu/compiler.h | \
    *include/standard-headers/ )
      # Removing include lines from osdep.h itself would be counterproductive.
      echo "SKIPPING $f (special case header)"
      continue
      ;;
    *include/standard-headers/*)
      echo "SKIPPING $f (autogenerated header)"
      continue
      ;;
    *.h)
      MODE=h
      ;;
    *)
      echo "WARNING: ignoring $f (cannot handle non-C files)"
      continue
      ;;
  esac

  if [ "$MODE" = "c" ]; then
    # First, use Coccinelle to add qemu/osdep.h before the first existing include
    # (this will add two lines if the file uses both "..." and <...> #includes,
    # but we will remove the extras in the next step)
    spatch  --in-place --no-show-diff --cocci-file "$COCCIFILE" "$f"

    # Now remove any duplicate osdep.h includes
    perl -n -i -e 'print if !/#include "qemu\/osdep.h"/ || !$n++;' "$f"
  else
    # Remove includes of osdep.h itself
    perl -n -i -e 'print if !/\s*#\s*include\s*(["<][^>"]*[">])/ ||
                            ! (grep { $_ eq $1 } qw ("qemu/osdep.h"))' "$f"
  fi

  # Remove includes that osdep.h already provides
  perl -n -i -e 'print if !/\s*#\s*include\s*(["<][^>"]*[">])/ ||
                          ! (grep { $_ eq $1 } qw (
           "config-host.h" "config-target.h" "qemu/compiler.h"
           <setjmp.h> <stdarg.h> <stddef.h> <stdbool.h> <stdint.h> <sys/types.h>
           <stdlib.h> <stdio.h> <string.h> <strings.h> <inttypes.h>
           <limits.h> <unistd.h> <time.h> <ctype.h> <errno.h> <fcntl.h>
           <sys/stat.h> <sys/time.h> <assert.h> <signal.h>
           "sysemu/os-posix.h, sysemu/os-win32.h "glib-compat.h"
           "qemu/typedefs.h"
            ))' "$f"

done

if [ "$GIT" = "yes" ]; then
    git add -- "$@"
    git commit --signoff -F - <<EOF
$GITSUBJ: Clean up includes

Clean up includes so that osdep.h is included first and headers
which it implies are not included manually.

This commit was created with scripts/clean-includes.

EOF

fi
ara></listitem> <listitem><para>Usage of freed/destroyed objects</para></listitem> </itemizedlist> </para> <para> debugobjects is not changing the data structure of the real object so it can be compiled in with a minimal runtime impact and enabled on demand with a kernel command line option. </para> </chapter> <chapter id="howto"> <title>Howto use debugobjects</title> <para> A kernel subsystem needs to provide a data structure which describes the object type and add calls into the debug code at appropriate places. The data structure to describe the object type needs at minimum the name of the object type. Optional functions can and should be provided to fixup detected problems so the kernel can continue to work and the debug information can be retrieved from a live system instead of hard core debugging with serial consoles and stack trace transcripts from the monitor. </para> <para> The debug calls provided by debugobjects are: <itemizedlist> <listitem><para>debug_object_init</para></listitem> <listitem><para>debug_object_init_on_stack</para></listitem> <listitem><para>debug_object_activate</para></listitem> <listitem><para>debug_object_deactivate</para></listitem> <listitem><para>debug_object_destroy</para></listitem> <listitem><para>debug_object_free</para></listitem> <listitem><para>debug_object_assert_init</para></listitem> </itemizedlist> Each of these functions takes the address of the real object and a pointer to the object type specific debug description structure. </para> <para> Each detected error is reported in the statistics and a limited number of errors are printk'ed including a full stack trace. </para> <para> The statistics are available via /sys/kernel/debug/debug_objects/stats. They provide information about the number of warnings and the number of successful fixups along with information about the usage of the internal tracking objects and the state of the internal tracking objects pool. </para> </chapter> <chapter id="debugfunctions"> <title>Debug functions</title> <sect1 id="prototypes"> <title>Debug object function reference</title> !Elib/debugobjects.c </sect1> <sect1 id="debug_object_init"> <title>debug_object_init</title> <para> This function is called whenever the initialization function of a real object is called. </para> <para> When the real object is already tracked by debugobjects it is checked, whether the object can be initialized. Initializing is not allowed for active and destroyed objects. When debugobjects detects an error, then it calls the fixup_init function of the object type description structure if provided by the caller. The fixup function can correct the problem before the real initialization of the object happens. E.g. it can deactivate an active object in order to prevent damage to the subsystem. </para> <para> When the real object is not yet tracked by debugobjects, debugobjects allocates a tracker object for the real object and sets the tracker object state to ODEBUG_STATE_INIT. It verifies that the object is not on the callers stack. If it is on the callers stack then a limited number of warnings including a full stack trace is printk'ed. The calling code must use debug_object_init_on_stack() and remove the object before leaving the function which allocated it. See next section. </para> </sect1> <sect1 id="debug_object_init_on_stack"> <title>debug_object_init_on_stack</title> <para> This function is called whenever the initialization function of a real object which resides on the stack is called. </para> <para> When the real object is already tracked by debugobjects it is checked, whether the object can be initialized. Initializing is not allowed for active and destroyed objects. When debugobjects detects an error, then it calls the fixup_init function of the object type description structure if provided by the caller. The fixup function can correct the problem before the real initialization of the object happens. E.g. it can deactivate an active object in order to prevent damage to the subsystem. </para> <para> When the real object is not yet tracked by debugobjects debugobjects allocates a tracker object for the real object and sets the tracker object state to ODEBUG_STATE_INIT. It verifies that the object is on the callers stack. </para> <para> An object which is on the stack must be removed from the tracker by calling debug_object_free() before the function which allocates the object returns. Otherwise we keep track of stale objects. </para> </sect1> <sect1 id="debug_object_activate"> <title>debug_object_activate</title> <para> This function is called whenever the activation function of a real object is called. </para> <para> When the real object is already tracked by debugobjects it is checked, whether the object can be activated. Activating is not allowed for active and destroyed objects. When debugobjects detects an error, then it calls the fixup_activate function of the object type description structure if provided by the caller. The fixup function can correct the problem before the real activation of the object happens. E.g. it can deactivate an active object in order to prevent damage to the subsystem. </para> <para> When the real object is not yet tracked by debugobjects then the fixup_activate function is called if available. This is necessary to allow the legitimate activation of statically allocated and initialized objects. The fixup function checks whether the object is valid and calls the debug_objects_init() function to initialize the tracking of this object. </para> <para> When the activation is legitimate, then the state of the associated tracker object is set to ODEBUG_STATE_ACTIVE. </para> </sect1> <sect1 id="debug_object_deactivate"> <title>debug_object_deactivate</title> <para> This function is called whenever the deactivation function of a real object is called. </para> <para> When the real object is tracked by debugobjects it is checked, whether the object can be deactivated. Deactivating is not allowed for untracked or destroyed objects. </para> <para> When the deactivation is legitimate, then the state of the associated tracker object is set to ODEBUG_STATE_INACTIVE. </para> </sect1> <sect1 id="debug_object_destroy"> <title>debug_object_destroy</title> <para> This function is called to mark an object destroyed. This is useful to prevent the usage of invalid objects, which are still available in memory: either statically allocated objects or objects which are freed later. </para> <para> When the real object is tracked by debugobjects it is checked, whether the object can be destroyed. Destruction is not allowed for active and destroyed objects. When debugobjects detects an error, then it calls the fixup_destroy function of the object type description structure if provided by the caller. The fixup function can correct the problem before the real destruction of the object happens. E.g. it can deactivate an active object in order to prevent damage to the subsystem. </para> <para> When the destruction is legitimate, then the state of the associated tracker object is set to ODEBUG_STATE_DESTROYED. </para> </sect1> <sect1 id="debug_object_free"> <title>debug_object_free</title> <para> This function is called before an object is freed. </para> <para> When the real object is tracked by debugobjects it is checked, whether the object can be freed. Free is not allowed for active objects. When debugobjects detects an error, then it calls the fixup_free function of the object type description structure if provided by the caller. The fixup function can correct the problem before the real free of the object happens. E.g. it can deactivate an active object in order to prevent damage to the subsystem. </para> <para> Note that debug_object_free removes the object from the tracker. Later usage of the object is detected by the other debug checks. </para> </sect1> <sect1 id="debug_object_assert_init"> <title>debug_object_assert_init</title> <para> This function is called to assert that an object has been initialized. </para> <para> When the real object is not tracked by debugobjects, it calls fixup_assert_init of the object type description structure provided by the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem by calling debug_object_init and other specific initializing functions. </para> <para> When the real object is already tracked by debugobjects it is ignored. </para> </sect1> </chapter> <chapter id="fixupfunctions"> <title>Fixup functions</title> <sect1 id="debug_obj_descr"> <title>Debug object type description structure</title> !Iinclude/linux/debugobjects.h </sect1> <sect1 id="fixup_init"> <title>fixup_init</title> <para> This function is called from the debug code whenever a problem in debug_object_init is detected. The function takes the address of the object and the state which is currently recorded in the tracker. </para> <para> Called from debug_object_init when the object state is: <itemizedlist> <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> </itemizedlist> </para> <para> The function returns 1 when the fixup was successful, otherwise 0. The return value is used to update the statistics. </para> <para> Note, that the function needs to call the debug_object_init() function again, after the damage has been repaired in order to keep the state consistent. </para> </sect1> <sect1 id="fixup_activate"> <title>fixup_activate</title> <para> This function is called from the debug code whenever a problem in debug_object_activate is detected. </para> <para> Called from debug_object_activate when the object state is: <itemizedlist> <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem> <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> </itemizedlist> </para> <para> The function returns 1 when the fixup was successful, otherwise 0. The return value is used to update the statistics. </para> <para> Note that the function needs to call the debug_object_activate() function again after the damage has been repaired in order to keep the state consistent. </para> <para> The activation of statically initialized objects is a special case. When debug_object_activate() has no tracked object for this object address then fixup_activate() is called with object state ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether this is a legitimate case of a statically initialized object or not. In case it is it calls debug_object_init() and debug_object_activate() to make the object known to the tracker and marked active. In this case the function should return 0 because this is not a real fixup. </para> </sect1> <sect1 id="fixup_destroy"> <title>fixup_destroy</title> <para> This function is called from the debug code whenever a problem in debug_object_destroy is detected. </para> <para> Called from debug_object_destroy when the object state is: <itemizedlist> <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> </itemizedlist> </para> <para> The function returns 1 when the fixup was successful, otherwise 0. The return value is used to update the statistics. </para> </sect1> <sect1 id="fixup_free"> <title>fixup_free</title> <para> This function is called from the debug code whenever a problem in debug_object_free is detected. Further it can be called from the debug checks in kfree/vfree, when an active object is detected from the debug_check_no_obj_freed() sanity checks. </para> <para> Called from debug_object_free() or debug_check_no_obj_freed() when the object state is: <itemizedlist> <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> </itemizedlist> </para> <para> The function returns 1 when the fixup was successful, otherwise 0. The return value is used to update the statistics. </para> </sect1> <sect1 id="fixup_assert_init"> <title>fixup_assert_init</title> <para> This function is called from the debug code whenever a problem in debug_object_assert_init is detected. </para> <para> Called from debug_object_assert_init() with a hardcoded state ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug bucket. </para> <para> The function returns 1 when the fixup was successful, otherwise 0. The return value is used to update the statistics. </para> <para> Note, this function should make sure debug_object_init() is called before returning. </para> <para> The handling of statically initialized objects is a special case. The fixup function should check if this is a legitimate case of a statically initialized object or not. In this case only debug_object_init() should be called to make the object known to the tracker. Then the function should return 0 because this is not a real fixup. </para> </sect1> </chapter> <chapter id="bugs"> <title>Known Bugs And Assumptions</title> <para> None (knock on wood). </para> </chapter> </book>