|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [RFC v2 1/7] sections.h: add sections header to collect all section info
Linux makes extensive use of custom ELF header sections,
documentation for these are well scatterred. Unify this
documentation in a central place.
Signed-off-by: Luis R. Rodriguez <mcgrof@xxxxxxxxxx>
---
Documentation/DocBook/Makefile | 3 +-
Documentation/DocBook/sections.tmpl | 99 ++++++++++++++++
include/linux/sections.h | 224 ++++++++++++++++++++++++++++++++++++
3 files changed, 325 insertions(+), 1 deletion(-)
create mode 100644 Documentation/DocBook/sections.tmpl
create mode 100644 include/linux/sections.h
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index d70f9b68174e..f2dfd46bf30a 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -15,7 +15,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
80211.xml debugobjects.xml sh.xml regulator.xml \
alsa-driver-api.xml writing-an-alsa-driver.xml \
tracepoint.xml gpu.xml media_api.xml w1.xml \
- writing_musb_glue_layer.xml crypto-API.xml iio.xml
+ writing_musb_glue_layer.xml crypto-API.xml iio.xml \
+ sections.xml
include Documentation/DocBook/media/Makefile
diff --git a/Documentation/DocBook/sections.tmpl
b/Documentation/DocBook/sections.tmpl
new file mode 100644
index 000000000000..96d8d88c1b93
--- /dev/null
+++ b/Documentation/DocBook/sections.tmpl
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; []>
+<set>
+ <setinfo>
+ <title>Linux ELF sections</title>
+ <subtitle>
+ Explains Linux ELF sections
+ </subtitle>
+
+ <copyright>
+ <year>2016</year>
+ <holder>Luis R. Rodriguez</holder>
+ </copyright>
+
+ <authorgroup>
+ <author>
+ <firstname>Luis</firstname>
+ <surname>Rodriguez</surname>
+ <affiliation>
+ <address><email>mcgrof@xxxxxxxxxx</email></address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <legalnotice>
+ <para>
+ This documentation is free software; you can redistribute
+ it and/or modify it under the terms of the GNU General Public
+ License version 2 as published by the Free Software Foundation.
+ </para>
+ <para>
+ This documentation is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ </para>
+ <para>
+ You should have received a copy of the GNU General Public
+ License along with this documentation; if not, write to the Free
+ Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ MA 02111-1307 USA
+ </para>
+ <para>
+ For more details see the file COPYING in the source
+ distribution of Linux.
+ </para>
+ </legalnotice>
+
+ <abstract>
+ <para>
+ This book documents the different custom ELF sections used on the Linux
+ kernel and defined on Linux's custom linker script.
+ </para>
+ </abstract>
+ </setinfo>
+ <book id="linux-elf-sections">
+ <bookinfo>
+ <title>Linux kernel ELF sections</title>
+
+ <abstract>
+!Pinclude/linux/sections.h Introduction
+ </abstract>
+ </bookinfo>
+
+ <chapter>
+ <title>Core Linux kernel sections</title>
+!Pinclude/linux/sections.h Core Linux kernel sections
+!Finclude/linux/sections.h SECTION_RODATA
+!Pinclude/linux/sections.h SECTION_TEXT
+!Pinclude/linux/sections.h SECTION_DATA
+ </chapter>
+
+ <chapter>
+ <title>Linux .init* sections</title>
+!Pinclude/linux/sections.h Linux init sections
+!Finclude/linux/sections.h SECTION_INIT_DATA
+!Finclude/linux/sections.h SECTION_INIT_RODATA
+!Finclude/linux/sections.h SECTION_INIT_CALL
+ </chapter>
+
+ <chapter>
+ <title>Linux .exit* sections</title>
+!Pinclude/linux/sections.h Linux exit sections
+!Finclude/linux/sections.h SECTION_EXIT
+!Finclude/linux/sections.h SECTION_EXIT_DATA
+!Finclude/linux/sections.h SECTION_EXIT_CALL
+ </chapter>
+
+ <chapter>
+ <title>Linux .ref* sections</title>
+!Pinclude/linux/sections.h Linux references to init sections
+!Finclude/linux/sections.h SECTION_REF
+!Finclude/linux/sections.h SECTION_REF_DATA
+!Finclude/linux/sections.h SECTION_REF_RODATA
+ </chapter>
+
+ </book>
+</set>
diff --git a/include/linux/sections.h b/include/linux/sections.h
new file mode 100644
index 000000000000..7b47bea4956a
--- /dev/null
+++ b/include/linux/sections.h
@@ -0,0 +1,224 @@
+#ifndef _LINUX_SECTIONS_H
+#define _LINUX_SECTIONS_H
+/*
+ * Linux ELF sections
+ *
+ * Copyright (C) 2016 Luis R. Rodriguez <mcgrof@xxxxxxxxxx>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * Due to this file being licensed under the GPL there is controversy over
+ * whether this permits you to write a module that #includes this file
+ * without placing your module under the GPL. Please consult a lawyer for
+ * advice before doing this.
+ */
+
+/**
+ * DOC: Introduction
+ *
+ * The Linux vmlinux binary uses a custom linker script which adds
+ * some custom specialized ELF sections. This aims to document those
+ * sections. Each section must document the goal of the section, and
+ * address concurrency considerations when applicable.
+ */
+
+/**
+ * DOC: Core Linux kernel sections
+ *
+ * These are the core Linux kernel sections.
+ */
+
+/**
+ * SECTION_RODATA - read only data
+ *
+ * Macro name for code which must be protected from write access.
+ */
+#define SECTION_RODATA .rodata
+
+/**
+ * SECTION_TEXT - kernel code execution section, read-only
+ *
+ * Macro name used to annotate code (functions) used during regular
+ * kernel run time. This is combined with SECTION_RODATA, only this
+ * section also gets execution allowed.
+ *
+ */
+#define SECTION_TEXT .text
+
+/**
+ * SECTION_DATA - for read-write data
+ *
+ * Macro name for read-write data.
+ */
+#define SECTION_DATA .data
+
+/**
+ * DOC: Linux init sections
+ *
+ * These sections are used for code and data structures used during boot or
+ * module initialization. On architectures that support it (x86, x86_64), all
+ * this code is freed up by the kernel right before the fist userspace init
+ * process is called when built-in to the kernel, and if modular it is freed
+ * after module initialization. Since the code is freed so early, in theory
+ * there should be no races against freeing this code with other CPUs. Init
+ * section code and data structures should never be exported with
+ * EXPORT_SYMBOL*() as the code will quickly become unavailable to the kernel
+ * after bootup.
+ */
+
+/**
+ * SECTION_INIT - boot initialization code
+ *
+ * Macro name used to annotate code (functions) used only during boot or driver
+ * initialization.
+ *
+ */
+#define SECTION_INIT .init.text
+
+/**
+ * SECTION_INIT_DATA - boot initialization data
+ *
+ * Macro name used to annotate data structures used only during boot or driver
+ * initialization.
+ */
+#define SECTION_INIT_DATA .init.data
+
+/**
+ * SECTION_INIT_RODATA - boot read-only initialization data
+ *
+ * Macro name used to annotate read-only code (functions) used only during boot
+ * or driver initialization.
+ */
+#define SECTION_INIT_RODATA .init.rodata
+
+/**
+ * SECTION_INIT_CALL - special init call
+ *
+ * Special macro name used to annotate subsystem init call. These calls are
+ * are now grouped by functionality into separate subsections. Ordering inside
+ * the subsections is determined by link order.
+ */
+#define SECTION_INIT_CALL .initcall
+
+/**
+ * DOC: Linux exit sections
+ *
+ * These sections are used to declare a functions and data structures which
+ * are only required on exit, the function or data structure will be dropped
+ * if the code declaring this section is not compiled as a module on
+ * architectures that support this (x86, x86_64). There is no special case
+ * handling for this code when built-in to the kernel.
+ */
+
+/**
+ * SECTION_EXIT - module exit code
+ *
+ * Macro name used to annotate code (functions) used only during module
+ * unload.
+ */
+#define SECTION_EXIT .exit.text
+
+/**
+ * SECTION_EXIT_DATA - module exit data structures
+ *
+ * Macro name used to annotate data structures used only during module
+ * unload.
+ */
+#define SECTION_EXIT_DATA .exit.data
+
+/**
+ * SECTION_EXIT_CALL - special exit call
+ *
+ * Special macro name used to annotate an exit exit routine, order
+ * is important and maintained by link order.
+ */
+#define SECTION_EXIT_CALL .exitcall.exit
+
+/**
+ * DOC: Linux references to init sections
+ *
+ * These sections are used to teach modpost to not warn about possible
+ * misuses of init section code from other sections. If you use this
+ * your use case should document why you are certain such use of init
+ * sectioned code is valid. For more details refer to include/linux/init.h
+ * __ref, __refdata, and __refconst documentation.
+ */
+
+/**
+ * SECTION_REF - code referencing init is valid
+ *
+ * Macro name used to annotate that code (functions) declared with this section
+ * has been vetteed as valid for its reference or use of other code (functions)
+ * or data structures which are part of the init sections.
+ */
+#define SECTION_REF .ref.text
+
+/**
+ * SECTION_REF_DATA - reference data structure are valid
+ *
+ * Macro name used to annotate data structures declared with this section have
+ * been vetteed for its reference or use of other code (functions) or data
+ * structures part of the init sections.
+ */
+#define SECTION_REF_DATA .ref.data
+
+/**
+ * SECTION_REF_RODATA - const code or data structure referencing init is valid
+ *
+ * Macro name used to annotate const code (functions) const data structures
which
+ * has been vetteed for its reference or use of other code (functions) or data
+ * structures part of the init sections.
+ */
+#define SECTION_REF_RODATA .ref.rodata
+
+/**
+ * DOC: Custom Linux sections
+ *
+ * These are very custom Linux sections.
+ */
+
+#ifndef __ASSEMBLY__
+
+/*
+ * Without this you end up with the section macro
+ * as part of the name
+ */
+#define __SECTION_TBL(section, name, level) \
+ #section ".tbl." #name "." #level
+
+/**
+ * SECTION_TBL - Linux linker table section
+ *
+ * @section: respective section
+ * @name: used to describe the use case
+ * @level: the order-level for the linker table
+ *
+ * Macro name used to annotate a linker table. For more details refer to
+ * include/linux/tables.h. Linker tables use standard Linux sections defined
+ * in this file.
+ */
+#define SECTION_TBL(section, name, level) \
+ __SECTION_TBL(section, name, level)
+
+/*
+ * For use on linker scripts and helpers
+ */
+#define ___SECTION_TBL(section, name) \
+ section##.tbl.##name
+/**
+ * SECTION_TBL_ALL - glob to capture all linker table uses for this section
+ *
+ * @section: respective section
+ *
+ * Macro name used by linker script to capture all linker tables uses for
+ * the given section. This is used by include/asm-generic/vmlinux.lds.h
+ */
+#define SECTION_TBL_ALL(section) \
+ ___SECTION_TBL(section,*)
+
+#endif /* __ASSEMBLY__ */
+
+#endif /* _LINUX_SECTIONS_H */
--
2.7.0
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |