how to properly "export" a new header file to user space?

May 18, 2016

      just want to make i'm using the new UAPI infrastructure properly,
since i remember the old days of stuffing "header-y" all over the
place in Kbuild files.

  say i want to add a new driver to the kernel, so i create the
directory /drivers/rday, and add some code and i create a header file,
"rday1.h", that will be used by both my kernel code *and* needs to be
included by user space code as well.

  normally, i could just leave that header file in that directory, and
let the source file use:

  #include "rday1.h"

but if i want that header file visible in user space, as i read it, i
can create a new directory at the top level of the kernel source:

  include/uapi/rday/

inside of which i can place the file "rday1.h", which has the
following consequences.

  first, given this code in the top-level Makefile:

    # Use USERINCLUDE when you must reference the UAPI directories only.
    USERINCLUDE    := \
                -I$(srctree)/arch/$(hdr-arch)/include/uapi \
                -Iarch/$(hdr-arch)/include/generated/uapi \
                -I$(srctree)/include/uapi \
                -Iinclude/generated/uapi \
                -include $(srctree)/include/linux/kconfig.h

    # Use LINUXINCLUDE when you must reference the include/ directory.
    # Needed to be compatible with the O= option
    LINUXINCLUDE    := \
                -I$(srctree)/arch/$(hdr-arch)/include \
                -Iarch/$(hdr-arch)/include/generated/uapi \
                -Iarch/$(hdr-arch)/include/generated \
                $(if $(KBUILD_SRC), -I$(srctree)/include) \
                -Iinclude \
                $(USERINCLUDE)

my own kernel code should now use the include directive:

  #include <rday/rday1.h>

which should properly locate that header file. and, second, user space
code can use the same directive as long as i extend the user space
header file search path to include "<kernel-source-tree/include/uapi",
correct?

  am i thinking about this the right way? i'm using the model under
drivers/mtd, where one sees examples like:

  nand/fsmc_nand.c:#include <mtd/mtd-abi.h>
  ubi/cdev.c:#include <mtd/ubi-user.h>

with directory contents:

$ tree include/uapi/mtd
include/uapi/mtd
├── inftl-user.h
├── Kbuild
├── mtd-abi.h
├── mtd-user.h
├── nftl-user.h
└── ubi-user.h
$

  i also note that include/uapi/mtd includes header files meant to be
included *only* from user space, such as mtd-user.h, which is fine.

  so is this the correct approach? or am i missing something easier?

rday

p.s. i also note the Kbuild file "include/uapi/mtd/Kbuild", for use if
i want to export those headers with:

  $ make headers_install

but if i don't want to export my own header files that way, i see no
need to add a Kbuild file, at least not for the moment. thoughts?

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================