scripts: New clean-header-guards.pl

scripts: New clean-header-guards.pl

The conventional way to ensure a header can be included multiple times
is to bracket it like this:

    #ifndef HEADER_NAME_H
    #define HEADER_NAME_H
    ...
    #endif

where HEADER_NAME_H is a symbol unique to this header.

The endif may be optionally decorated like this:

    #endif /* HEADER_NAME_H */

Unconventional ways present in our code:

* Identifiers reserved for any use:
    #define _FILEOP_H

* Lowercase (bad idea for object-like macros):
    #define __linux_video_vga_h__

* Roundabout ways to say the same thing (and hide from grep):
    #if !defined(__PPC_MAC_H__)
    #endif /* !defined(__PPC_MAC_H__) */

* Redundant values:
    #define HW_ALPHA_H 1

* Funny redundant values:
    # define PXA_H                 "pxa.h"

* Decorations with bangs:

    #endif /* !QEMU_ARM_GIC_INTERNAL_H */

  The negation actually makes sense, but almost all our header guard
  #endif decorations don't negate.

* Useless decorations:

   #endif  /* audio.h */

Header guards are not the place to show off creativity.  This script
normalizes them to the conventional way, and cleans up whitespace
while there.  It warns when it renames guard symbols, and explains how
to find occurences of these symbols that may have to be updated
manually.

Another issue is use of the same guard symbol in multiple headers.
That's okay only for headers that cannot be used together, such as the
*-user/*/target_syscall.h.  This script can't tell, so it warns when
it sees a reuse.

The script also warns when preprocessing a header with its guard
symbol defined produces anything but whitespace.

The next commits will put the script to use.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Richard Henderson <rth@twiddle.net>