[PATCH 3/4] Description of offset header files handling

[Nicholas Mc Guire <der.herr@hofr.at>]

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.herr@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:mec@shout.net>
 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
 Updates by Sam Ravnborg <sam@ravnborg.org>
 Language QA by Jan Engelhardt <jengelh@gmx.de>
 Kbuild support for shipped files Nicholas Mc Guire <der.herr@hofr.at>
+Added description of offset header files Nicholas Mc Guire <der.herr@hofr.at>
 
-=== 11 TODO
+=== 12 TODO
 
-- Generating offset header files.
 - Add more variables to section 7?
 
 
-- 
1.7.10.4