What’s in include/uapi of kernel source project?

1. Introduction

The uapi folder is supposed to contain the user space API of the kernel. Then upon kernel installation, the uapi include files become the top level /usr/include/linux/ files.

The other headers in theory are then private to the kernel. This allow clean separation of the user-visible and kernel-only structures which previously were intermingled in a single header file.

the “uapi” include file cleanups. The idea is that the stuff exported to user space should now be found under include/uapi and arch/$(ARCH)/include/uapi.

2. Where

include/uapi corresponding to /user/include/linux/ files.

arch/x86/include/uapi/asm corresponding to /usr/include/x86_64-linux-gnu/asm files.

3. What

Split out the user-space API content of the kernel header files in the include and arch/xxxxxx/include directories, placing that content into corresponding headers created in new uapi/ subdirectories that reside under each of the original directories.

4. Benefit

  • simplifies and reduces the size of the kernel-only headers
  • simplifies the complex interdependencies between headers that are [currently] partly exported to userspace
  • There is one other benefit of the UAPI split that may be of particular interest to the wider Linux ecosystem. By placing all of the user-space API-related definitions into files dedicated solely to that task, it becomes easier to track changes to the APIs that the kernel presents to user space. In the first instance, these changes can be discovered by scanning the git logs for changes in files under the uapi/ subdirectories. Easing the task of tracking user-space APIs would help many other parts of the ecosystem, for example, C library maintainers, scripting language projects that maintain language bindings for the user-space API, testing projects such as LTP, documentation projects such as man-pages, and perhaps even LWN editors preparing summaries of changes in the merge window that occurs at the start of each kernel release cycle.

5. How

The task of disintegrating each of the header files into two pieces is in principle straightforward. In the general case, each header file has the following form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/* Header comments (copyright, etc.) */

#ifndef _XXXXXX_H     /* Guard macro preventing double inclusion */
#define _XXXXXX_H

[User-space definitions]

#ifdef __KERNEL__

[Kernel-space definitions]

#endif /* __KERNEL__ */

[User-space definitions]
  
#endif /* End prevent double inclusion */

Each of the above parts may or may not be present in individual header files, and there may be multiple blocks governed by #ifdef __KERNEL__ preprocessor directives.

The part of this file that is of most interest is the code that falls inside the outermost #ifndef block that prevents double inclusion of the header file. [User-space definitions] should move to the corresponding uapi/ header file. The content inside the #ifdef __KERNEL__ block remains in the original header file, but the #ifdef __KERNEL__ and its accompanying #endif are removed.

A copy of the header comments remains in the original header file, and is duplicated in the new uapi/ header file. In addition, a #include directive needs to be added to the original header file so that it includes the new uapi/ header file, and of course a suitable git commit message needs to be supplied for the change.

The goal is to modify the original header file to look like this:

1
2
3
4
5
6
7
8
9
10
/* Header comments (copyright, etc.) */

#ifndef _XXXXXX_H     /* Guard macro preventing double inclusion */
#define _XXXXXX_H

#include <include/uapi/path/to/header.h>

[Kernel-space definitions]

#endif /* End prevent double inclusion */

The corresponding uapi/ header file will look like this:

1
2
3
4
5
6
7
8
/* Header comments (copyright, etc.) */

#ifndef _UAPI__XXXXXX_H     /* Guard macro preventing double inclusion */
#define _UAPI__XXXXXX_H

[User-space definitions]

#endif /* End prevent double inclusion */

参考资料:

  1. The UAPI header file split
  2. UAPI header file split
  3. What’s in include/uapi of kernel source project