From patchwork Sat Jun 17 15:25:41 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 9794603 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 7CE38600F6 for ; Sat, 17 Jun 2017 23:00:07 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6F407283FD for ; Sat, 17 Jun 2017 23:00:07 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 6254E28402; Sat, 17 Jun 2017 23:00:07 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from mother.openwall.net (mother.openwall.net [195.42.179.200]) by mail.wl.linuxfoundation.org (Postfix) with SMTP id 3D1DE283FD for ; Sat, 17 Jun 2017 23:00:06 +0000 (UTC) Received: (qmail 7933 invoked by uid 550); 17 Jun 2017 22:59:58 -0000 Mailing-List: contact kernel-hardening-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-ID: Delivered-To: mailing list kernel-hardening@lists.openwall.com Delivered-To: moderator for kernel-hardening@lists.openwall.com Received: (qmail 25824 invoked from network); 17 Jun 2017 15:26:13 -0000 X-Virus-Scanned: amavisd-new at osg.samsung.com X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Kees Cook , Emese Revfy , kernel-hardening@lists.openwall.com Date: Sat, 17 Jun 2017 12:25:41 -0300 Message-Id: <956283e0d9f9c01a437ab75c5c9a324959ead132.1497713142.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.9.4 In-Reply-To: References: In-Reply-To: References: Sender: Mauro Carvalho Chehab Subject: [kernel-hardening] [PATCH v2 22/31] gcc-plugins.txt: standardize document format X-Virus-Scanned: ClamAV using ClamSMTP Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - promote main title; - use the right markup for footnotes; - use bold markup for files name; - identify literal blocks; - add blank lines to avoid Sphinx to complain; - remove numeration from titles. Signed-off-by: Mauro Carvalho Chehab Acked-by: Kees Cook --- Documentation/gcc-plugins.txt | 58 ++++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.txt index 433eaefb4aa1..8502f24396fb 100644 --- a/Documentation/gcc-plugins.txt +++ b/Documentation/gcc-plugins.txt @@ -1,14 +1,15 @@ +========================= GCC plugin infrastructure ========================= -1. Introduction -=============== +Introduction +============ GCC plugins are loadable modules that provide extra features to the -compiler [1]. They are useful for runtime instrumentation and static analysis. +compiler [1]_. They are useful for runtime instrumentation and static analysis. We can analyse, change and add further code during compilation via -callbacks [2], GIMPLE [3], IPA [4] and RTL passes [5]. +callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. The GCC plugin infrastructure of the kernel supports all gcc versions from 4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a @@ -21,56 +22,61 @@ and versions 4.8+ can only be compiled by a C++ compiler. Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and powerpc architectures. -This infrastructure was ported from grsecurity [6] and PaX [7]. +This infrastructure was ported from grsecurity [6]_ and PaX [7]_. -- -[1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html -[2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API -[3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html -[4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html -[5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html -[6] https://grsecurity.net/ -[7] https://pax.grsecurity.net/ +.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html +.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API +.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html +.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html +.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html +.. [6] https://grsecurity.net/ +.. [7] https://pax.grsecurity.net/ -2. Files -======== -$(src)/scripts/gcc-plugins +Files +===== + +**$(src)/scripts/gcc-plugins** + This is the directory of the GCC plugins. -$(src)/scripts/gcc-plugins/gcc-common.h +**$(src)/scripts/gcc-plugins/gcc-common.h** + This is a compatibility header for GCC plugins. It should be always included instead of individual gcc headers. -$(src)/scripts/gcc-plugin.sh +**$(src)/scripts/gcc-plugin.sh** + This script checks the availability of the included headers in gcc-common.h and chooses the proper host compiler to build the plugins (gcc-4.7 can be built by either gcc or g++). -$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h -$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h -$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h -$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h +**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** + These headers automatically generate the registration structures for GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions from 4.5 to 6.0. They should be preferred to creating the structures by hand. -3. Usage -======== +Usage +===== You must install the gcc plugin headers for your gcc version, -e.g., on Ubuntu for gcc-4.9: +e.g., on Ubuntu for gcc-4.9:: apt-get install gcc-4.9-plugin-dev -Enable a GCC plugin based feature in the kernel config: +Enable a GCC plugin based feature in the kernel config:: CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y -To compile only the plugin(s): +To compile only the plugin(s):: make gcc-plugins