Description of offset header files handling
This adds a section on offset header files handling in Kbuild.
This patch is against linux 3.18.0-rc1
Signed-off-by: Nicholas Mc Guire <der.h...@hofr.at>
---
Documentation/kbuild/makefiles.txt | 123 ++++++++++++++++++++++++++++++++++--
1 file changed, 117 insertions(+), 6 deletions(-)
diff --git a/Documentation/kbuild/makefiles.txt
b/Documentation/kbuild/makefiles.txt
index 3697be4..364f466 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -51,8 +51,9 @@ This document describes the Linux kernel Makefiles.
=== 8 Kbuild Variables
=== 9 Makefile language
- === 10 Credits
- === 11 TODO
+ === 10 Generating offset header files
+ === 11 Credits
+ === 12 TODO
=== 1 Overview
@@ -1033,7 +1034,7 @@ When kbuild executes, the following steps are followed
(roughly):
In this example, the file target maketools will be processed
before descending down in the subdirectories.
- See also chapter XXX-TODO that describe how kbuild supports
+ See also chapter 10 that describe how kbuild supports
generating offset header files.
@@ -1449,17 +1450,127 @@ time the left-hand side is used.
There are some cases where "=" is appropriate. Usually, though, ":="
is the right choice.
-=== 10 Credits
+=== 10 Generating offset header files
+
+The problem: Given the following structure:
+
+ Example:
+ typedef struct
+ {
+ int a;
+ int b;
+ } some_thing;
+
+ If as asm function is receiving a pointer of a some_thing structure
+ then we have the problem of the elements offset in the structure
+ are not accessible in the assembler code.
+
+ If the pointer were passed in through r0 then access to the elements
+ a and b would need to have the offsets hard coded like:
+
+ Example:
+ ldr r1, [r0, #0] // read a
+ ldr r2, [r0, #4] // read b
+
+ but you do not want to hard-code them in maintainable code so the
+ offsets need to be deduced from the C-code and made available for use
+ in the assembler code in some symbolic manner.
+
+ Example:
+ ldr r1, [r0, #THING_A]
+ ldr r2, [r0, #THING_B]
+
+ The Kbuild system provides methods to calculate the necessary offsets
+ from the C and stores them in a generated header file as preprocessor
+ constants which allows to write maintainable and readable assembler code.
+
+ The elements that are needed in assembler code are placed in a C-file
+ arch/ARCHkernel/asm-offsets_{32,64}.c which is then processed into a
+ assembler file (by calling gcc -S) and from this Kbuild then extracts
+ the defines and places them into the generated asm-offsets.h
+
+ Example:
+ arch/x86/kernel/asm-offsets_64.c
+ <snip>
+ ...
+ #define ENTRY(entry) OFFSET(pt_regs_ ## entry, pt_regs, entry)
+ ENTRY(bx);
+ ...
+ <snip>
+
+ from this the pt_regs_bx offset is generated and stored in
+ the asm-offsets.s as verbose asm from the top level Kbuild file
+ (arch/$(SRCARCH)/kernel/asm-offsets.s: arch/$(SRCARCH)/kernel/asm-offsets.c)
+
+ Example:
+ ->pt_regs_bx $40 offsetof(struct pt_regs, bx) #
+ # 0 "" 2
+ # 51 "arch/x86/kernel/asm-offsets_64.c" 1
+
+ This intermediate assembler file is then processed by a somewhat brute-force
+ (or elegant - depending on how much you like sed) sed script in the top
+ level Kbuild file to generate the asm-offsets.h file
+
+ define sed-y
+ "/^->/{s:->#\(.*\):/* \1 */:; \
+ s:^->\([^ ]*\) [\$$#]*\([-0-9]*\) \(.*\):#define \1 \2 /* \3 */:; \
+ s:^->\([^ ]*\) [\$$#]*\([^ ]*\) \(.*\):#define \1 \2 /* \3 */:; \
+ s:->::; p;}"
+ endef
+
+ The generated files include a header generated by the Kbuild file indicating
+ that is is generated and should not be modified and then contains the
+ set of #define and as documentation the C-structure element e.g.
+
+ #define pt_regs_bx 40 /* offsetof(struct pt_regs, bx) # */
+
+ Example: arch/x86/power/hibernate_asm_64.S
+ ...
+ #include <asm/asm-offsets.h>
+ #include <asm/processor-flags.h>
+
+ ENTRY(swsusp_arch_suspend)
+ movq $saved_context, %rax
+ movq %rsp, pt_regs_sp(%rax)
+ ...
+
+ To now add a generated offset one needs to edit the C-file in
+ arch/$(SRCARCH)/kernel/asm-offsets.c respectively if it is only
+ for the 32 or 64 bit build in the asm-offsets_32/64.c and include
+ the respective structure/element one needs access to.
+
+ The syntax for this is
+ OFFSET(MACRONAME, STRUCTURE, ELEMENT);
+
+ Example:
+ <snip>
+ ...
+ #include <asm/thread_info.h>
+ ...
+ void common(void) {
+ BLANK();
+ OFFSET(TI_flags, thread_info, flags);
+ <snip>
+
+ The BLANK(); macro is used to make the generated header file more
+ readable and as the name indicates will insert a blank line.
+
+ The dependency tracking is done through Kbuild so if a structure that
+ is included in arch/ARCH/kernel/asm_offsets.c or in the 32/64 bit
+ variants then asm_offsets.h is regenerated correctly.
+
+
+=== 11 Credits
Original version made by Michael Elizabeth Chastain, <mailto:m...@shout.net>
Updates by Kai Germaschewski <k...@tp1.ruhr-uni-bochum.de>
Updates by Sam Ravnborg <s...@ravnborg.org>
Language QA by Jan Engelhardt <jeng...@gmx.de>
Kbuild support for shipped files Nicholas Mc Guire <der.h...@hofr.at>
+Added description of offset header files Nicholas Mc Guire <der.h...@hofr.at>
-=== 11 TODO
+=== 12 TODO
-- Generating offset header files.
- Add more variables to section 7?
--
1.7.10.4
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
