summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-04-04 14:20:48 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-04-12 19:35:00 +0100
commitbeb301c03afa600214bd54753ddc7d60a953c8c4 (patch)
tree11527579eb19d3c460a1f68a48bb3a19729662cb /documentation/dev-manual
parente2232e6813d503db33bb2fc29b57fbb7a0f7bca0 (diff)
downloadpoky-beb301c03afa600214bd54753ddc7d60a953c8c4.tar.gz
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>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml87
1 files changed, 87 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index f9b2910578..a6e14bb93c 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2691,6 +2691,93 @@
2691 </para> 2691 </para>
2692 </section> 2692 </section>
2693 2693
2694 <section id='new-recipe-using-headers-to-interface-with-devices'>
2695 <title>Using Headers to Interface with Devices</title>
2696
2697 <para>
2698 If your recipe builds an application that needs to
2699 communicate with some device or needs an API into a custom
2700 kernel, you will need to provide appropriate header files.
2701 Under no circumstances should you ever modify the existing
2702 <filename>meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc</filename>
2703 file.
2704 These headers are used to build <filename>libc</filename> and
2705 must not be compromised with custom or machine-specific
2706 header information.
2707 If you customize <filename>libc</filename> through modified
2708 headers all other applications that use
2709 <filename>libc</filename> thus become affected.
2710 <note><title>Warning</title>
2711 Never copy and customize the <filename>libc</filename>
2712 header file (i.e.
2713 <filename>meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc</filename>).
2714 </note>
2715 The correct way to interface to a device or custom kernel is
2716 to use a separate package that provides the additional headers
2717 for the driver or other unique interfaces.
2718 When doing so, your application also becomes responsible for
2719 creating a dependency on that specific provider.
2720 </para>
2721
2722 <para>
2723 Consider the following:
2724 <itemizedlist>
2725 <listitem><para>
2726 Never modify
2727 <filename>linux-libc-headers.inc</filename>.
2728 Consider that file to be part of the
2729 <filename>libc</filename> system, and not something
2730 you use to access the kernel directly.
2731 You should access <filename>libc</filename> through
2732 specific <filename>libc</filename> calls.
2733 </para></listitem>
2734 <listitem><para>
2735 Applications that must talk directly to devices
2736 should either provide necessary headers themselves,
2737 or establish a dependency on a special headers package
2738 that is specific to that driver.
2739 </para></listitem>
2740 </itemizedlist>
2741 </para>
2742
2743 <para>
2744 For example, suppose you want to modify an existing header
2745 that adds I/O control or network support.
2746 If the modifications are used by a small number programs,
2747 providing a unique version of a header is easy and has little
2748 impact.
2749 When doing so, bear in mind the guidelines in the previous
2750 list.
2751 <note>
2752 If for some reason your changes need to modify the behavior
2753 of the <filename>libc</filename>, and subsequently all
2754 other applications on the system, use a
2755 <filename>.bbappend</filename> to modify the
2756 <filename>linux-kernel-headers.inc</filename> file.
2757 However, take care to not make the changes
2758 machine specific.
2759 </note>
2760 </para>
2761
2762 <para>
2763 Consider a case where your kernel is older and you need
2764 an older <filename>libc</filename> ABI.
2765 The headers installed by your recipe should still be a
2766 standard mainline kernel, not your own custom one.
2767 </para>
2768
2769 <para>
2770 When you use custom kernel headers you need to get them from
2771 <ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>,
2772 which is the directory with kernel headers that are
2773 required to build out-of-tree modules.
2774 Your recipe will also need the following:
2775 <literallayout class='monospaced'>
2776 do_configure[depends] += "virtual/kernel:do_shared_workdir"
2777 </literallayout>
2778 </para>
2779 </section>
2780
2694 <section id='new-recipe-compilation'> 2781 <section id='new-recipe-compilation'>
2695 <title>Compilation</title> 2782 <title>Compilation</title>
2696 2783