dev-manual: Added section on using headers to interface with devices
Fixes [YOCTO #8596] Added a new section to describe the right way to use headers to interface to a device or custom Linux kernel API. Too often a user wants to modify the libc header file, which absolutely wrong. This new section provides some guidance. (From yocto-docs rev: 960c49bf6446398a9efb2d018d09d63b49e97196) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
e2232e6813
commit
beb301c03a
|
@ -2691,6 +2691,93 @@
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
<section id='new-recipe-using-headers-to-interface-with-devices'>
|
||||||
|
<title>Using Headers to Interface with Devices</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If your recipe builds an application that needs to
|
||||||
|
communicate with some device or needs an API into a custom
|
||||||
|
kernel, you will need to provide appropriate header files.
|
||||||
|
Under no circumstances should you ever modify the existing
|
||||||
|
<filename>meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc</filename>
|
||||||
|
file.
|
||||||
|
These headers are used to build <filename>libc</filename> and
|
||||||
|
must not be compromised with custom or machine-specific
|
||||||
|
header information.
|
||||||
|
If you customize <filename>libc</filename> through modified
|
||||||
|
headers all other applications that use
|
||||||
|
<filename>libc</filename> thus become affected.
|
||||||
|
<note><title>Warning</title>
|
||||||
|
Never copy and customize the <filename>libc</filename>
|
||||||
|
header file (i.e.
|
||||||
|
<filename>meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc</filename>).
|
||||||
|
</note>
|
||||||
|
The correct way to interface to a device or custom kernel is
|
||||||
|
to use a separate package that provides the additional headers
|
||||||
|
for the driver or other unique interfaces.
|
||||||
|
When doing so, your application also becomes responsible for
|
||||||
|
creating a dependency on that specific provider.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Consider the following:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>
|
||||||
|
Never modify
|
||||||
|
<filename>linux-libc-headers.inc</filename>.
|
||||||
|
Consider that file to be part of the
|
||||||
|
<filename>libc</filename> system, and not something
|
||||||
|
you use to access the kernel directly.
|
||||||
|
You should access <filename>libc</filename> through
|
||||||
|
specific <filename>libc</filename> calls.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>
|
||||||
|
Applications that must talk directly to devices
|
||||||
|
should either provide necessary headers themselves,
|
||||||
|
or establish a dependency on a special headers package
|
||||||
|
that is specific to that driver.
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For example, suppose you want to modify an existing header
|
||||||
|
that adds I/O control or network support.
|
||||||
|
If the modifications are used by a small number programs,
|
||||||
|
providing a unique version of a header is easy and has little
|
||||||
|
impact.
|
||||||
|
When doing so, bear in mind the guidelines in the previous
|
||||||
|
list.
|
||||||
|
<note>
|
||||||
|
If for some reason your changes need to modify the behavior
|
||||||
|
of the <filename>libc</filename>, and subsequently all
|
||||||
|
other applications on the system, use a
|
||||||
|
<filename>.bbappend</filename> to modify the
|
||||||
|
<filename>linux-kernel-headers.inc</filename> file.
|
||||||
|
However, take care to not make the changes
|
||||||
|
machine specific.
|
||||||
|
</note>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Consider a case where your kernel is older and you need
|
||||||
|
an older <filename>libc</filename> ABI.
|
||||||
|
The headers installed by your recipe should still be a
|
||||||
|
standard mainline kernel, not your own custom one.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When you use custom kernel headers you need to get them from
|
||||||
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>,
|
||||||
|
which is the directory with kernel headers that are
|
||||||
|
required to build out-of-tree modules.
|
||||||
|
Your recipe will also need the following:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
do_configure[depends] += "virtual/kernel:do_shared_workdir"
|
||||||
|
</literallayout>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
<section id='new-recipe-compilation'>
|
<section id='new-recipe-compilation'>
|
||||||
<title>Compilation</title>
|
<title>Compilation</title>
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue