8596 2015-10-28 09:50:54 +0000 Document proper way of adding a userspace header for the kernel 2017-08-09 22:51:04 +0000 1 1 9 Documentation General Docs docs-general unspecified x86 Multiple RESOLVED FIXED 09 August 2017: RESOLVED Medium enhancement 2.4 1 bluelightning mark.hatle bluelightning mark.hatle pokylinux sgw srifenbark --- --- Done (doc changes complete) oldest_to_newest 55883 0 bluelightning 2015-10-28 09:50:54 +0000 Occasionally we get questions about how to add a header to the kernel that user-space applications will be able to include. Often people think the way to do it is to add it to linux-libc-headers, but as meta/recipes-kernel/linux-libc-headers/linux-libc-headers.inc points out, this then makes the libc machine-specific which is usually not a good thing to do. However apart from the note at the top of linux-libc-headers.inc which mostly tells people what *not* to do, we have nothing to tell people how they *should* do this in detail and why. This really needs to go into one of the manuals, but I'm unsure as to whether it belongs in the BSP guide, the ref manual, the kernel manual, or somewhere else. We also need someone to provide the solid background material (which is unfortunately not me in this case). 55884 1 bluelightning 2015-10-28 10:02:16 +0000 This should cover what you need to do to get the header into the generated SDK as well. 55926 2 srifenbark 2015-10-28 14:23:10 +0000 Is this situation limited to making sure your user-space application has the header? If so, perhaps creating a sub-section in the Application Development manual in Chapter 3 (http://www.yoctoproject.org/docs/2.0/adt-manual/adt-manual.html#adt-prepare). Scott 55932 3 bluelightning 2015-10-28 15:02:35 +0000 It's usually driven by adding some associated kernel functionality (e.g. a driver of some sort) so that's why I was thinking the BSP / kernel docs. 63364 4 srifenbark 2016-06-27 18:24:15 +0000 I would say the kernel manual. So Paul... who would be the person that knows this and could provide me with information? Scott 64747 5 srifenbark 2016-08-01 19:12:24 +0000 Setting to NEEDINFO. 67128 6 pokylinux 2016-10-11 10:40:12 +0000 I am not sure this should go here. Maybe we should open another bug? A certain Yocto version comes with certain versions of the kernel and linux-libc-headers. Let's say kernel version 4.1.x and linux-libc-headers_4.1.bb . If you change the kernel version supposedly wrong libc headers are picked up without any warning. (4.4.x kernel 4.1.x linux-libc-headers). To use the supposedly right linux-libc-headers (4.4.x kernel 4.4.x linux-libc-headers) you need to do some extra steps: e.g. in your machine.conf: # kernel version KERNEL_VERSION_PATCHLEVEL="4.4" KERNEL_SUBLEVEL="6" PREFERRED_VERSION_linux-yocto-custom = ${KERNEL_VERSION_PATCHLEVEL}.${KERNEL_SUBLEVEL}%" # kernel headers version LINUXLIBCVERSION ?= "${KERNEL_VERSION_PATCHLEVEL}" and then you need a new version of meta/recipes-kernel/linux-libc-headers e.g. in your layer something like: recipes-kernel/linux-libc-headers/linux-libc-headers_4.4.bb 67134 7 mark.hatle 2016-10-11 13:07:15 +0000 The linux-libc-headers should -never- be used to interface with drivers or other components. This is intended to set the API for the system libc. There are often other interfaces specified, but until they have been standardized for a while they are always subject to change. Instead the right way to handle this is to provide a separate package that provides the additional headers for driver or other unique interfaces. The application is then responsible for depending on that specific provider. So in short, my recommendation is: 1) users should -never- modify linux-libc-headers. Consider this to be part of the libc of the system, and not something used to access the kernel directly. (Access should be via specific libc calls.) 2) applications that must talk directly to devices should either provide necessary headers themselves, or depend on a special headers package specific to that driver. Occasionally someone will want to modify an existing header to add an ioctl, network type or similar. If these modifications are only used by a small number of programs -- providing a unique version of a header is fairly easy and low impact. The items above apply. If for some reason these changes need to modify the behavior of the libc, and subsequently all other applications on the system -- then doing a .bbappend to modify the linux-kernel-headers is appropriate, but care should be taken to not make the changes dependent upon a specific BSP. 67149 8 srifenbark 2016-10-11 16:55:16 +0000 Paul - can we push this bug out to post 2.2? Scott 67152 9 bluelightning 2016-10-11 19:43:30 +0000 Yes we can - I've just moved it to 2.3, removed the NEEDINFO and reassigned it to you. 67305 10 bluelightning 2016-10-17 19:28:02 +0000 (In reply to comment #6) > A certain Yocto version comes with certain versions of the kernel and > linux-libc-headers. Let's say kernel version 4.1.x and > linux-libc-headers_4.1.bb . > > If you change the kernel version supposedly wrong libc headers are picked up > without any warning. (4.4.x kernel 4.1.x linux-libc-headers). > > To use the supposedly right linux-libc-headers (4.4.x kernel 4.4.x > linux-libc-headers) you need to do some extra steps ... You say "supposedly right" but I'm fairly sure it's not necessary for linux-libc-headers to be upgraded in lock-step with the kernel. AIUI linux-libc-headers need only be upgraded when a kernel interface that the C library needs to use has changed. I don't know but I suspect that the fact that we set OLDEST_KERNEL to "3.2.0" by default will also have an effect on how much of that gets used. That's something we should cover in the manual as well - once we get some clarification from someone with more concrete knowledge on the subject than myself. 67307 11 pokylinux 2016-10-17 19:55:15 +0000 I would assume, that as long as nobody calls new system calls or ioctls there is no problem, but if there is a kernel version with a new syscall or new ioctls, we don't have the right kernel headers and someone calls them things will crash. What do we gain by building e.g. a 4.8 kernel with 4.1 exported header files instead of 4.8 kernel exported header files? They are being built anyhow. Why build on purpose the wrong ones? If you look at the packages of your favourite Linux distro you should find for each kernel package also a corresponding kernel header package. [1] https://www.kernel.org/doc/Documentation/kbuild/headers_install.txt 67308 12 bluelightning 2016-10-17 20:20:41 +0000 "Someone" would have to be the C library though. Nothing else should be using linux-libc-headers. The reason why you wouldn't want to be messing around with linux-libc-headers unless you absolutely have to is outlined in the linux-libc-headers recipe. It's not going to matter if you only ever target one machine, but if you're producing a BSP that's supposed to be usable alongside others, and your BSP has its own linux-libc-headers recipe to "match up" with the kernel, then you're going to be introducing machine-specific changes into the toolchain which is supposed to remain the same for different machines with the same architecture. 67567 13 srifenbark 2016-10-25 20:16:55 +0000 Setting at 2.3 M2 70283 14 srifenbark 2017-01-31 16:24:25 +0000 Set target to 2.3 M3 71111 15 pokylinux 2017-03-07 17:06:49 +0000 Here the problem can be seen: https://bugzilla.yoctoproject.org/show_bug.cgi?id=10457 Someone applies a patch which is actually only needed for > 4.8 linux-libc-headers ? It breaks if you use e.g. 4.4. linux-libc-headers. 71269 16 srifenbark 2017-03-14 18:00:26 +0000 Hi, So I am trying to understand the issues here a bit more and it seems that the original intent of the bug was to document the right way to add a user-space header for use with the kernel. Furthermore, the need seems to be driven through wanting to add some associated kernel functionality, which leads me to believe we want to update the kernel manual. The rest of the discussion seems to be centered around trying to match up the correct versions of the linux-libc-headers with the actual kernel being used and the consequential cases of breaking things if that is not done properly. I don't get this stuff very well -- is it all related? Is what Mark said in Comment 7 the "right way" to add a user-space header for use with the kernel? Is that the bottom line to addressing this issue for the docs? What about the other stuff regarding matching kernels to headers? Thanks, Scott 71480 17 srifenbark 2017-03-20 18:38:20 +0000 Changing to NEEDINFO. Need some feedback on my questions. 71810 18 mark.hatle 2017-03-28 14:03:38 +0000 See original Description and comment #12. The simple answer -- you do NOT screw with the existing kernel headers. You provide a new package that provides these wonderful magic headers you want. Anything else is incorrect, as userspace and the kernel should be separate for the issues outlined in comment #12. 71967 19 sjolley.yp.pm 2017-03-31 15:43:26 +0000 It appears Mark has answered. 72089 20 srifenbark 2017-04-04 21:41:52 +0000 Hi Mark and Paul, I created a new section in the dev manual where we talk about writing recipes as a first crack at this topic. I felt a new section would be best as it seems it is an application thing and not a kernel thing per discussion with Mark. The section is here - http://www.yoctoproject.org/docs/2.3/dev-manual/dev-manual.html#new-recipe-using-headers-to-interface-with-devices. I got the information from a number of places (the bug comments, the warnings and such at the start of the linux-libc-headers.inc file, and an email with Mark asking for some more information. The draft is just that ... a draft. I don't know if I hit all the points we want to cover and the warnings, which seem to be plentiful. I am not clear on the dependency information and other stuff either that the developer would need to complete the picture beyond creating the new header file. There is information at the end of the section from the lib header file that I copied in there but did not understand enough of it to elaborate. Please read this over and we can clean it up. Once it is good, I can get it into the sdk manual as well, which has a very similar section. Thanks, Scott 75633 21 mark.hatle 2017-08-03 21:58:48 +0000 Sorry I never responded. I reviewed the changes and they look fine to me. 75793 22 srifenbark 2017-08-09 22:51:04 +0000 Setting to RESOLVED and marking the doc flag to done. Scott