[1/2] rust: uapi: Add UAPI crate

  This crate mirrors the `bindings` crate, but will contain only UAPI
bindings. Unlike the bindings crate, drivers may directly use this crate
if they have to interface with userspace.

Initially, just bind the generic ioctl stuff.

In the future, we would also like to add additional checks to ensure
that all types exposed by this crate satisfy UAPI-safety guarantees
(that is, they are safely castable to/from a "bag of bits").

Signed-off-by: Asahi Lina <lina@asahilina.net>
---
 rust/.gitignore         |  1 +
 rust/Makefile           | 18 ++++++++++++++++--
 rust/kernel/lib.rs      |  1 +
 rust/uapi/lib.rs        | 27 +++++++++++++++++++++++++++
 rust/uapi/uapi_helper.h |  9 +++++++++
 5 files changed, 54 insertions(+), 2 deletions(-)
  

On 3/29/23 08:40, Asahi Lina wrote:
> This crate mirrors the `bindings` crate, but will contain only UAPI
> bindings. Unlike the bindings crate, drivers may directly use this crate
> if they have to interface with userspace.
> 
> Initially, just bind the generic ioctl stuff.
> 
> In the future, we would also like to add additional checks to ensure
> that all types exposed by this crate satisfy UAPI-safety guarantees
> (that is, they are safely castable to/from a "bag of bits").
> 
> Signed-off-by: Asahi Lina <lina@asahilina.net>
> ---
>  rust/.gitignore         |  1 +
>  rust/Makefile           | 18 ++++++++++++++++--
>  rust/kernel/lib.rs      |  1 +
>  rust/uapi/lib.rs        | 27 +++++++++++++++++++++++++++
>  rust/uapi/uapi_helper.h |  9 +++++++++
>  5 files changed, 54 insertions(+), 2 deletions(-)
> 
> diff --git a/rust/.gitignore b/rust/.gitignore
> index 168cb26a31b9..21552992b401 100644
> --- a/rust/.gitignore
> +++ b/rust/.gitignore
> @@ -2,6 +2,7 @@
>  
>  bindings_generated.rs
>  bindings_helpers_generated.rs
> +uapi_generated.rs
>  exports_*_generated.h
>  doc/
>  test/
> diff --git a/rust/Makefile b/rust/Makefile
> index f88d108fbef0..59a327f0fa1a 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -16,6 +16,9 @@ obj-$(CONFIG_RUST) += alloc.o bindings.o kernel.o
>  always-$(CONFIG_RUST) += exports_alloc_generated.h exports_bindings_generated.h \
>      exports_kernel_generated.h
>  
> +always-$(CONFIG_RUST) += uapi/uapi_generated.rs
> +obj-$(CONFIG_RUST) += uapi.o
> +
>  ifdef CONFIG_RUST_BUILD_ASSERT_ALLOW
>  obj-$(CONFIG_RUST) += build_error.o
>  else
> @@ -288,6 +291,12 @@ $(obj)/bindings/bindings_generated.rs: $(src)/bindings/bindings_helper.h \
>      $(src)/bindgen_parameters FORCE
>  	$(call if_changed_dep,bindgen)
>  
> +$(obj)/uapi/uapi_generated.rs: private bindgen_target_flags = \
> +    $(shell grep -v '^\#\|^$$' $(srctree)/$(src)/bindgen_parameters)

This emits a warning with grep about a numeral unnecessarily escaped as
seen in a patch sent by Vicenzo Palazzo [1].

```
grep: warning: stray \ before #
```

> +$(obj)/uapi/uapi_generated.rs: $(src)/uapi/uapi_helper.h \
> +    $(src)/bindgen_parameters FORCE
> +	$(call if_changed_dep,bindgen)
> +
>  # See `CFLAGS_REMOVE_helpers.o` above. In addition, Clang on C does not warn
>  # with `-Wmissing-declarations` (unlike GCC), so it is not strictly needed here
>  # given it is `libclang`; but for consistency, future Clang changes and/or
> @@ -388,10 +397,15 @@ $(obj)/bindings.o: $(src)/bindings/lib.rs \
>      $(obj)/bindings/bindings_helpers_generated.rs FORCE
>  	$(call if_changed_dep,rustc_library)
>  
> +$(obj)/uapi.o: $(src)/uapi/lib.rs \
> +    $(obj)/compiler_builtins.o \
> +    $(obj)/uapi/uapi_generated.rs FORCE
> +	$(call if_changed_dep,rustc_library)
> +
>  $(obj)/kernel.o: private rustc_target_flags = --extern alloc \
> -    --extern build_error --extern macros --extern bindings
> +    --extern build_error --extern macros --extern bindings --extern uapi
>  $(obj)/kernel.o: $(src)/kernel/lib.rs $(obj)/alloc.o $(obj)/build_error.o \
> -    $(obj)/libmacros.so $(obj)/bindings.o FORCE
> +    $(obj)/libmacros.so $(obj)/bindings.o $(obj)/uapi.o FORCE
>  	$(call if_changed_dep,rustc_library)
>  
>  endif # CONFIG_RUST
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index 7610b18ee642..63f796781b7c 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -43,6 +43,7 @@ pub mod types;
>  #[doc(hidden)]
>  pub use bindings;
>  pub use macros;
> +pub use uapi;
>  
>  #[doc(hidden)]
>  pub use build_error::build_error;
> diff --git a/rust/uapi/lib.rs b/rust/uapi/lib.rs
> new file mode 100644
> index 000000000000..29f69f3a52de
> --- /dev/null
> +++ b/rust/uapi/lib.rs
> @@ -0,0 +1,27 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! UAPI Bindings.
> +//!
> +//! Contains the bindings generated by `bindgen` for UAPI interfaces.
> +//!
> +//! This crate may be used directly by drivers that need to interact with
> +//! userspace APIs.
> +
> +#![no_std]
> +#![feature(core_ffi_c)]
> +// See <https://github.com/rust-lang/rust-bindgen/issues/1651>.
> +#![cfg_attr(test, allow(deref_nullptr))]
> +#![cfg_attr(test, allow(unaligned_references))]
> +#![cfg_attr(test, allow(unsafe_op_in_unsafe_fn))]
> +#![allow(
> +    clippy::all,
> +    missing_docs,
> +    non_camel_case_types,
> +    non_upper_case_globals,
> +    non_snake_case,
> +    improper_ctypes,
> +    unreachable_pub,
> +    unsafe_op_in_unsafe_fn
> +)]
> +
> +include!(concat!(env!("OBJTREE"), "/rust/uapi/uapi_generated.rs"));
> diff --git a/rust/uapi/uapi_helper.h b/rust/uapi/uapi_helper.h
> new file mode 100644
> index 000000000000..301f5207f023
> --- /dev/null
> +++ b/rust/uapi/uapi_helper.h
> @@ -0,0 +1,9 @@
> +/* SPDX-License-Identifier: GPL-2.0 */
> +/*
> + * Header that contains the headers for which Rust UAPI bindings
> + * will be automatically generated by `bindgen`.
> + *
> + * Sorted alphabetically.
> + */
> +
> +#include <uapi/asm-generic/ioctl.h>
> 

Link: https://lore.kernel.org/rust-for-linux/20230302132107.210502-1-vincenzopalazzodev@gmail.com/ [1]

Reviewed-by: Martin Rodriguez Reboredo
  

On Wed, 29 Mar 2023 20:40:18 +0900
Asahi Lina <lina@asahilina.net> wrote:

> This crate mirrors the `bindings` crate, but will contain only UAPI
> bindings. Unlike the bindings crate, drivers may directly use this crate
> if they have to interface with userspace.
> 
> Initially, just bind the generic ioctl stuff.
> 
> In the future, we would also like to add additional checks to ensure
> that all types exposed by this crate satisfy UAPI-safety guarantees
> (that is, they are safely castable to/from a "bag of bits").
> 
> Signed-off-by: Asahi Lina <lina@asahilina.net>
> ---
>  rust/.gitignore         |  1 +
>  rust/Makefile           | 18 ++++++++++++++++--
>  rust/kernel/lib.rs      |  1 +
>  rust/uapi/lib.rs        | 27 +++++++++++++++++++++++++++
>  rust/uapi/uapi_helper.h |  9 +++++++++
>  5 files changed, 54 insertions(+), 2 deletions(-)
> 
> diff --git a/rust/.gitignore b/rust/.gitignore
> index 168cb26a31b9..21552992b401 100644
> --- a/rust/.gitignore
> +++ b/rust/.gitignore
> @@ -2,6 +2,7 @@
>  
>  bindings_generated.rs
>  bindings_helpers_generated.rs
> +uapi_generated.rs
>  exports_*_generated.h
>  doc/
>  test/
> diff --git a/rust/Makefile b/rust/Makefile
> index f88d108fbef0..59a327f0fa1a 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -16,6 +16,9 @@ obj-$(CONFIG_RUST) += alloc.o bindings.o kernel.o
>  always-$(CONFIG_RUST) += exports_alloc_generated.h exports_bindings_generated.h \
>      exports_kernel_generated.h
>  
> +always-$(CONFIG_RUST) += uapi/uapi_generated.rs
> +obj-$(CONFIG_RUST) += uapi.o
> +
>  ifdef CONFIG_RUST_BUILD_ASSERT_ALLOW
>  obj-$(CONFIG_RUST) += build_error.o
>  else
> @@ -288,6 +291,12 @@ $(obj)/bindings/bindings_generated.rs: $(src)/bindings/bindings_helper.h \
>      $(src)/bindgen_parameters FORCE
>  	$(call if_changed_dep,bindgen)
>  
> +$(obj)/uapi/uapi_generated.rs: private bindgen_target_flags = \
> +    $(shell grep -v '^\#\|^$$' $(srctree)/$(src)/bindgen_parameters)
> +$(obj)/uapi/uapi_generated.rs: $(src)/uapi/uapi_helper.h \
> +    $(src)/bindgen_parameters FORCE
> +	$(call if_changed_dep,bindgen)
> +
>  # See `CFLAGS_REMOVE_helpers.o` above. In addition, Clang on C does not warn
>  # with `-Wmissing-declarations` (unlike GCC), so it is not strictly needed here
>  # given it is `libclang`; but for consistency, future Clang changes and/or
> @@ -388,10 +397,15 @@ $(obj)/bindings.o: $(src)/bindings/lib.rs \
>      $(obj)/bindings/bindings_helpers_generated.rs FORCE
>  	$(call if_changed_dep,rustc_library)
>  
> +$(obj)/uapi.o: $(src)/uapi/lib.rs \
> +    $(obj)/compiler_builtins.o \
> +    $(obj)/uapi/uapi_generated.rs FORCE
> +	$(call if_changed_dep,rustc_library)
> +
>  $(obj)/kernel.o: private rustc_target_flags = --extern alloc \
> -    --extern build_error --extern macros --extern bindings
> +    --extern build_error --extern macros --extern bindings --extern uapi
>  $(obj)/kernel.o: $(src)/kernel/lib.rs $(obj)/alloc.o $(obj)/build_error.o \
> -    $(obj)/libmacros.so $(obj)/bindings.o FORCE
> +    $(obj)/libmacros.so $(obj)/bindings.o $(obj)/uapi.o FORCE
>  	$(call if_changed_dep,rustc_library)
>  
>  endif # CONFIG_RUST
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index 7610b18ee642..63f796781b7c 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -43,6 +43,7 @@ pub mod types;
>  #[doc(hidden)]
>  pub use bindings;
>  pub use macros;
> +pub use uapi;
>  
>  #[doc(hidden)]
>  pub use build_error::build_error;
> diff --git a/rust/uapi/lib.rs b/rust/uapi/lib.rs
> new file mode 100644
> index 000000000000..29f69f3a52de
> --- /dev/null
> +++ b/rust/uapi/lib.rs
> @@ -0,0 +1,27 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! UAPI Bindings.
> +//!
> +//! Contains the bindings generated by `bindgen` for UAPI interfaces.
> +//!
> +//! This crate may be used directly by drivers that need to interact with
> +//! userspace APIs.
> +
> +#![no_std]
> +#![feature(core_ffi_c)]
> +// See <https://github.com/rust-lang/rust-bindgen/issues/1651>.
> +#![cfg_attr(test, allow(deref_nullptr))]
> +#![cfg_attr(test, allow(unaligned_references))]
> +#![cfg_attr(test, allow(unsafe_op_in_unsafe_fn))]

Looks like that we should bump our bindgen version.

> +#![allow(
> +    clippy::all,
> +    missing_docs,
> +    non_camel_case_types,
> +    non_upper_case_globals,
> +    non_snake_case,
> +    improper_ctypes,
> +    unreachable_pub,
> +    unsafe_op_in_unsafe_fn
> +)]
> +
> +include!(concat!(env!("OBJTREE"), "/rust/uapi/uapi_generated.rs"));
> diff --git a/rust/uapi/uapi_helper.h b/rust/uapi/uapi_helper.h
> new file mode 100644
> index 000000000000..301f5207f023
> --- /dev/null
> +++ b/rust/uapi/uapi_helper.h
> @@ -0,0 +1,9 @@
> +/* SPDX-License-Identifier: GPL-2.0 */
> +/*
> + * Header that contains the headers for which Rust UAPI bindings
> + * will be automatically generated by `bindgen`.
> + *
> + * Sorted alphabetically.
> + */
> +
> +#include <uapi/asm-generic/ioctl.h>
> 

Best,
Gary