[PATCH v3] kbuild: get rid of misleading $(AS) from documents

[PATCH v3] kbuild: get rid of misleading $(AS) from documents

[Masahiro Yamada]

The assembler files in the kernel are *.S instead of *.s, so they must
be preprocessed. Since 'as' of GNU binutils is not able to preprocess,
we always use $(CC) as an assembler driver.

$(AS) is almost unused in Kbuild. As of v5.2, there is just one place
that directly invokes $(AS).

  $ git grep -e '$(AS)' -e '${AS}' -e '$AS' -e '$(AS:' -e '${AS:' -- :^Documentation
  drivers/net/wan/Makefile:  AS68K = $(AS)

The documentation about *_AFLAGS* sounds like the flags were passed
to $(AS). This is somewhat misleading.

Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Reviewed-by: Nathan Chancellor <natechancellor@gmail.com>
---

Changes in v3:
  - Rebase

Changes in v2:
  - Rephrase without using "assembling"

 Documentation/kbuild/kbuild.rst    |  5 ++---
 Documentation/kbuild/makefiles.rst | 12 ++++++------
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index b25548963d70..727520b3d7b1 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -38,12 +38,11 @@ Additional options to the assembler (for built-in and modules).
 
 AFLAGS_MODULE
 -------------
-Additional module specific options to use for $(AS).
+Additional assembler options for modules.
 
 AFLAGS_KERNEL
 -------------
-Additional options for $(AS) when used for assembler
-code for code that is compiled as built-in.
+Additional assembler options for built-in.
 
 KCFLAGS
 -------
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 093f2d79ab95..67e47589d9d2 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -328,7 +328,7 @@ more details, with real examples.
 	variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
 	entire tree.
 
-	asflags-y specifies options for assembling with $(AS).
+	asflags-y specifies assembler options.
 
 	Example::
 
@@ -489,7 +489,7 @@ more details, with real examples.
 	as-instr checks if the assembler reports a specific instruction
 	and then outputs either option1 or option2
 	C escapes are supported in the test instruction
-	Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options
+	Note: as-instr-option uses KBUILD_AFLAGS for assembler options
 
     cc-option
 	cc-option is used to check if $(CC) supports a given option, and if
@@ -905,7 +905,7 @@ When kbuild executes, the following steps are followed (roughly):
 	vmlinux. The usage of $(call if_changed,xxx) will be described later.
 
     KBUILD_AFLAGS
-	$(AS) assembler flags
+	Assembler flags
 
 	Default value - see top level Makefile
 	Append or modify as required per architecture.
@@ -948,16 +948,16 @@ When kbuild executes, the following steps are followed (roughly):
 	to 'y' when selected.
 
     KBUILD_AFLAGS_KERNEL
-	$(AS) options specific for built-in
+	Assembler options specific for built-in
 
 	$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
 	resident kernel code.
 
     KBUILD_AFLAGS_MODULE
-	Options for $(AS) when building modules
+	Assembler options specific for modules
 
 	$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
-	are used for $(AS).
+	are used for assembler.
 
 	From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
 
-- 
2.17.1

Re: [PATCH v3] kbuild: get rid of misleading $(AS) from documents

[Masahiro Yamada]

On Sat, Jul 13, 2019 at 11:46 AM Masahiro Yamada
<yamada.masahiro@socionext.com> wrote:
>
> The assembler files in the kernel are *.S instead of *.s, so they must
> be preprocessed. Since 'as' of GNU binutils is not able to preprocess,
> we always use $(CC) as an assembler driver.
>
> $(AS) is almost unused in Kbuild. As of v5.2, there is just one place
> that directly invokes $(AS).
>
>   $ git grep -e '$(AS)' -e '${AS}' -e '$AS' -e '$(AS:' -e '${AS:' -- :^Documentation
>   drivers/net/wan/Makefile:  AS68K = $(AS)
>
> The documentation about *_AFLAGS* sounds like the flags were passed
> to $(AS). This is somewhat misleading.
>
> Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
> Reviewed-by: Nathan Chancellor <natechancellor@gmail.com>
> ---

Applied to linux-kbuild.



> Changes in v3:
>   - Rebase
>
> Changes in v2:
>   - Rephrase without using "assembling"
>
>  Documentation/kbuild/kbuild.rst    |  5 ++---
>  Documentation/kbuild/makefiles.rst | 12 ++++++------
>  2 files changed, 8 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index b25548963d70..727520b3d7b1 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -38,12 +38,11 @@ Additional options to the assembler (for built-in and modules).
>
>  AFLAGS_MODULE
>  -------------
> -Additional module specific options to use for $(AS).
> +Additional assembler options for modules.
>
>  AFLAGS_KERNEL
>  -------------
> -Additional options for $(AS) when used for assembler
> -code for code that is compiled as built-in.
> +Additional assembler options for built-in.
>
>  KCFLAGS
>  -------
> diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
> index 093f2d79ab95..67e47589d9d2 100644
> --- a/Documentation/kbuild/makefiles.rst
> +++ b/Documentation/kbuild/makefiles.rst
> @@ -328,7 +328,7 @@ more details, with real examples.
>         variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
>         entire tree.
>
> -       asflags-y specifies options for assembling with $(AS).
> +       asflags-y specifies assembler options.
>
>         Example::
>
> @@ -489,7 +489,7 @@ more details, with real examples.
>         as-instr checks if the assembler reports a specific instruction
>         and then outputs either option1 or option2
>         C escapes are supported in the test instruction
> -       Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options
> +       Note: as-instr-option uses KBUILD_AFLAGS for assembler options
>
>      cc-option
>         cc-option is used to check if $(CC) supports a given option, and if
> @@ -905,7 +905,7 @@ When kbuild executes, the following steps are followed (roughly):
>         vmlinux. The usage of $(call if_changed,xxx) will be described later.
>
>      KBUILD_AFLAGS
> -       $(AS) assembler flags
> +       Assembler flags
>
>         Default value - see top level Makefile
>         Append or modify as required per architecture.
> @@ -948,16 +948,16 @@ When kbuild executes, the following steps are followed (roughly):
>         to 'y' when selected.
>
>      KBUILD_AFLAGS_KERNEL
> -       $(AS) options specific for built-in
> +       Assembler options specific for built-in
>
>         $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
>         resident kernel code.
>
>      KBUILD_AFLAGS_MODULE
> -       Options for $(AS) when building modules
> +       Assembler options specific for modules
>
>         $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
> -       are used for $(AS).
> +       are used for assembler.
>
>         From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
>
> --
> 2.17.1
>


-- 
Best Regards
Masahiro Yamada