init.h: add some more documentation to __ref* tags

The __ref* tags may have been confusing for new kernel developers (I was confused by them for sure) so adding a few more sentences to comment to clear things up for people who see those for the first time. Signed-off-by: Michal Nazarewicz <m.nazarewicz@samsung.com> Acked-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de> Acked-by: Sam Ravnborg <sam@ravnborg.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

init.h: add some more documentation to __ref* tags
The __ref* tags may have been confusing for new kernel developers (I was confused by them for sure) so adding a few more sentences to comment to clear things up for people who see those for the first time. Signed-off-by: Michal Nazarewicz <m.nazarewicz@samsung.com> Acked-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de> Acked-by: Sam Ravnborg <sam@ravnborg.org> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Michal Nazarewicz · Greg Kroah-Hartman
1 parent c9bfff9c98
Showing 1 changed file with 10 additions and 3 deletions Side-by-side Diff
include/linux/init.h
@@ -46,16 +46,23 @@
 #define __exitdata	__section(.exit.data)
 #define __exit_call	__used __section(.exitcall.exit)
  
-/* modpost check for section mismatches during the kernel build.
+/*
+ * modpost check for section mismatches during the kernel build.
  * A section mismatch happens when there are references from a
  * code or data section to an init section (both code or data).
  * The init sections are (for most archs) discarded by the kernel
  * when early init has completed so all such references are potential bugs.
  * For exit sections the same issue exists.
+ *
  * The following markers are used for the cases where the reference to
  * the *init / *exit section (code or data) is valid and will teach
- * modpost not to issue a warning.
- * The markers follow same syntax rules as __init / __initdata. */
+ * modpost not to issue a warning.  Intended semantics is that a code or
+ * data tagged __ref* can reference code or data from init section without
+ * producing a warning (of course, no warning does not mean code is
+ * correct, so optimally document why the __ref is needed and why it's OK).
+ *
+ * The markers follow same syntax rules as __init / __initdata.
+ */
 #define __ref            __section(.ref.text) noinline
 #define __refdata        __section(.ref.data)
 #define __refconst       __section(.ref.rodata)
...	...	@@ -46,16 +46,23 @@
46	46	#define __exitdata __section(.exit.data)
47	47	#define __exit_call __used __section(.exitcall.exit)
48	48
49		-/* modpost check for section mismatches during the kernel build.
	49	+/*
	50	+ * modpost check for section mismatches during the kernel build.
50	51	* A section mismatch happens when there are references from a
51	52	* code or data section to an init section (both code or data).
52	53	* The init sections are (for most archs) discarded by the kernel
53	54	* when early init has completed so all such references are potential bugs.
54	55	* For exit sections the same issue exists.
	56	+ *
55	57	* The following markers are used for the cases where the reference to
56	58	* the init / exit section (code or data) is valid and will teach
57		- * modpost not to issue a warning.
58		- * The markers follow same syntax rules as __init / __initdata. */
	59	+ * modpost not to issue a warning. Intended semantics is that a code or
	60	+ * data tagged __ref* can reference code or data from init section without
	61	+ * producing a warning (of course, no warning does not mean code is
	62	+ * correct, so optimally document why the __ref is needed and why it's OK).
	63	+ *
	64	+ * The markers follow same syntax rules as __init / __initdata.
	65	+ */
59	66	#define __ref __section(.ref.text) noinline
60	67	#define __refdata __section(.ref.data)
61	68	#define __refconst __section(.ref.rodata)