If you don't know it, it's hard to figure out the difference between
the linux-headers folder and the include/standard-headers folder.
So let's add a short explanation to clarify the difference.

Suggested-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
v1 of this was from Thomas; I suggested some expanded wording
and since that made the patch pretty much entirely my text
Thomas suggested I send this under my name.
---
 scripts/update-linux-headers.sh | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/scripts/update-linux-headers.sh b/scripts/update-linux-headers.sh
index fea4d6eb655..d23851e1d3b 100755
--- a/scripts/update-linux-headers.sh
+++ b/scripts/update-linux-headers.sh
@@ -9,6 +9,22 @@
 #
 # This work is licensed under the terms of the GNU GPL version 2.
 # See the COPYING file in the top-level directory.
+#
+# The script will copy the headers into two target folders:
+#
+# - linux-headers/ for files that are required for compiling on a
+#   Linux host.  Generally we have these so we can use kernel structs
+#   and defines that are more recent than the headers that might be
+#   in /usr/include/linux on the host system.  Usually this script
+#   can do simple file copies for these headers.
+#
+# - include/standard-headers/ for files that are used for guest
+#   device emulation and are required on all hosts.  For instance, we
+#   get our definitions of the virtio structures from the Linux
+#   kernel headers, but we need those definitions regardless of which
+#   host OS we are building on.  This script has to be careful to
+#   sanitize the headers to remove any use of Linux-specifics such as
+#   types like "__u64".  This work is done in the cp_portable function.
 
 tmpdir=$(mktemp -d)
 linux="$1"
-- 
2.25.1

On 09/12/2021 20.45, Peter Maydell wrote:
> If you don't know it, it's hard to figure out the difference between
> the linux-headers folder and the include/standard-headers folder.
> So let's add a short explanation to clarify the difference.
> 
> Suggested-by: Thomas Huth <thuth@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> v1 of this was from Thomas; I suggested some expanded wording
> and since that made the patch pretty much entirely my text
> Thomas suggested I send this under my name.
> ---
>   scripts/update-linux-headers.sh | 16 ++++++++++++++++
>   1 file changed, 16 insertions(+)
> 
> diff --git a/scripts/update-linux-headers.sh b/scripts/update-linux-headers.sh
> index fea4d6eb655..d23851e1d3b 100755
> --- a/scripts/update-linux-headers.sh
> +++ b/scripts/update-linux-headers.sh
> @@ -9,6 +9,22 @@
>   #
>   # This work is licensed under the terms of the GNU GPL version 2.
>   # See the COPYING file in the top-level directory.
> +#
> +# The script will copy the headers into two target folders:
> +#
> +# - linux-headers/ for files that are required for compiling on a
> +#   Linux host.  Generally we have these so we can use kernel structs
> +#   and defines that are more recent than the headers that might be
> +#   in /usr/include/linux on the host system.  Usually this script
> +#   can do simple file copies for these headers.
> +#
> +# - include/standard-headers/ for files that are used for guest
> +#   device emulation and are required on all hosts.  For instance, we
> +#   get our definitions of the virtio structures from the Linux
> +#   kernel headers, but we need those definitions regardless of which
> +#   host OS we are building on.  This script has to be careful to
> +#   sanitize the headers to remove any use of Linux-specifics such as
> +#   types like "__u64".  This work is done in the cp_portable function.

Thanks!

Reviewed-by: Thomas Huth <thuth@redhat.com>

On Thu, Dec 09 2021, Peter Maydell <peter.maydell@linaro.org> wrote:

> If you don't know it, it's hard to figure out the difference between
> the linux-headers folder and the include/standard-headers folder.
> So let's add a short explanation to clarify the difference.
>
> Suggested-by: Thomas Huth <thuth@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> v1 of this was from Thomas; I suggested some expanded wording
> and since that made the patch pretty much entirely my text
> Thomas suggested I send this under my name.
> ---
>  scripts/update-linux-headers.sh | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

On Thu, Dec 09, 2021 at 07:45:32PM +0000, Peter Maydell wrote:
> If you don't know it, it's hard to figure out the difference between
> the linux-headers folder and the include/standard-headers folder.
> So let's add a short explanation to clarify the difference.
> 
> Suggested-by: Thomas Huth <thuth@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

A couple of minor tweaks: what matters is which platform
we are building for I think.

> ---
> v1 of this was from Thomas; I suggested some expanded wording
> and since that made the patch pretty much entirely my text
> Thomas suggested I send this under my name.
> ---
>  scripts/update-linux-headers.sh | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/scripts/update-linux-headers.sh b/scripts/update-linux-headers.sh
> index fea4d6eb655..d23851e1d3b 100755
> --- a/scripts/update-linux-headers.sh
> +++ b/scripts/update-linux-headers.sh
> @@ -9,6 +9,22 @@
>  #
>  # This work is licensed under the terms of the GNU GPL version 2.
>  # See the COPYING file in the top-level directory.
> +#
> +# The script will copy the headers into two target folders:
> +#
> +# - linux-headers/ for files that are required for compiling on a

I think it's more of a "for a Linux host"

> +#   Linux host.  Generally we have these so we can use kernel structs
> +#   and defines that are more recent than the headers that might be
> +#   in /usr/include/linux 

I'd just say "installed". Path does not matter.

>on the host system.  Usually this script
> +#   can do simple file copies for these headers.
> +#
> +# - include/standard-headers/ for files that are used for guest
> +#   device emulation and are required on all hosts.  For instance, we
> +#   get our definitions of the virtio structures from the Linux
> +#   kernel headers, but we need those definitions regardless of which
> +#   host OS we are building on.

we are building for

>  This script has to be careful to
> +#   sanitize the headers to remove any use of Linux-specifics such as
> +#   types like "__u64".  This work is done in the cp_portable function.
>  
>  tmpdir=$(mktemp -d)
>  linux="$1"
> -- 
> 2.25.1

Peter Maydell <peter.maydell@linaro.org> writes:

> If you don't know it, it's hard to figure out the difference between
> the linux-headers folder and the include/standard-headers folder.
> So let's add a short explanation to clarify the difference.
>
> Suggested-by: Thomas Huth <thuth@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

-- 
Alex Bennée

On Thu, 9 Dec 2021 at 19:45, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> If you don't know it, it's hard to figure out the difference between
> the linux-headers folder and the include/standard-headers folder.
> So let's add a short explanation to clarify the difference.
>
> Suggested-by: Thomas Huth <thuth@redhat.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> v1 of this was from Thomas; I suggested some expanded wording
> and since that made the patch pretty much entirely my text
> Thomas suggested I send this under my name.

Applied to target-arm.next with the minor tweaks MST suggested applied.

thanks
-- PMM