Update bindings to v2024.4.0 (#144)

* Update bindings to use OpenVINO v2024.4.0

This consists of using #142:

```
$ cargo xtask update 2024.4.0
$ cargo xtask codegen
$ cargo test
```

The follow-on commits resolve the errors introduced by this update.

* Generate C enums as Rust enums

This change is an effort avoid missing new enum variants if they are
added to OpenVINO's C headers. As it stands now, new variants could be
missed until runtime, when the enum code can't be parsed and the library
panics. Instead, this change generates a Rust `enum` for each C `enum`
so that missing variants become a compile time error; if we update the
bindings but don't handle these, we see a compile-time error.

* Propagate new `ov_*_e` enum changes throughout

The `openvino` crate depended on the previous constants generated by
`bindgen`. This change uses the new Rust `enum`s instead, creating
`From` and `Into` implementations to go between the Rust and C versions.

Why not just pass through the `openvino_sys` enum as-is? The only real
issue currently is documentation: the C headers start documentation with
`<!` which seems a bit weird. I've also fixed up a few grammar problems
in the documentation. But one day we may indeed be able to just reuse
these types.

* Move `version` into its module; add parsing

It wasn't clear to me why the function and the struct were kept in
different places so I moved them together. I also added a
`Version::parts` function.

* Handle tests which depend on v2024.2 breaking change

Any test using `ElementType::U8` will cause problems when run on older
versions of the library. This change manually ignores tests that depend
on this by detecting the library version. For `Tensor`'s doc test, I
chose to use a type not affected by the breaking change to keep things
consistent.

* ci: update versions tested against

* clippy: fix `Into` to `From` recommendations

* fix: tweak version check

* fix: continue ignoring `OV_BOOLEAN` doc comment

See b2bdfb0 for the rationale for this.

* review: print message when test is skipped

Author: abrown

.github/workflows/main.yml

@@ -21,14 +21,14 @@ jobs:
         # found ("dyld: Library not loaded; '@rpath/libopenvino.2310.dylib'"). See
         # https://github.com/abrown/openvino-rs/actions/runs/6423141936/job/17441022932#step:7:154
         os: [ubuntu-20.04, ubuntu-22.04, windows-latest]
-        version: [2023.2.0, 2024.0.0, 2024.1.0]
+        version: [2023.2.0, 2024.1.0, 2024.4.0]
         apt: [false]
         # We also spot-check that things work when installing from APT by adding to the matrix: see
         # https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs#expanding-or-adding-matrix-configurations
-        # APT install and check latest supported version 2024.1.0
+        # APT install and check latest supported version.
         include:
           - os: ubuntu-22.04
-            version: 2024.1.0
+            version: 2024.4.0
             apt: true
     env:
       RUST_LOG: debug

crates/openvino-sys/src/generated/functions.rs

@@ -923,13 +923,29 @@ extern "C" {
         value: f32,
     ) -> ov_status_e;
 }
+extern "C" {
+    #[doc = " @brief Add scale preprocess operation. Divide each channel element of input by different specified value.\n @ingroup ov_prepostprocess_c_api\n @param preprocess_input_process_steps A pointer to ov_preprocess_preprocess_steps_t.\n @param values Scaling values array for each channels\n @param value_size Scaling value size\n @return Status code of the operation: OK(0) for success."]
+    pub fn ov_preprocess_preprocess_steps_scale_multi_channels(
+        preprocess_input_process_steps: *mut ov_preprocess_preprocess_steps_t,
+        values: *const f32,
+        value_size: i32,
+    ) -> ov_status_e;
+}
 extern "C" {
     #[doc = " @brief Add mean preprocess operation. Subtract specified value from each element of input.\n @ingroup ov_prepostprocess_c_api\n @param preprocess_input_process_steps A pointer to ov_preprocess_preprocess_steps_t.\n @param value Value to subtract from each element.\n @return Status code of the operation: OK(0) for success."]
     pub fn ov_preprocess_preprocess_steps_mean(
         preprocess_input_process_steps: *mut ov_preprocess_preprocess_steps_t,
         value: f32,
     ) -> ov_status_e;
 }
+extern "C" {
+    #[doc = " @brief Add mean preprocess operation. Subtract each channel element of input by different specified value.\n @ingroup ov_prepostprocess_c_api\n @param preprocess_input_process_steps A pointer to ov_preprocess_preprocess_steps_t.\n @param values Value array to subtract from each element.\n @param value_size Mean value size\n @return Status code of the operation: OK(0) for success."]
+    pub fn ov_preprocess_preprocess_steps_mean_multi_channels(
+        preprocess_input_process_steps: *mut ov_preprocess_preprocess_steps_t,
+        values: *const f32,
+        value_size: i32,
+    ) -> ov_status_e;
+}
 extern "C" {
     #[doc = " @brief Crop input tensor between begin and end coordinates.\n @ingroup ov_prepostprocess_c_api\n @param preprocess_input_process_steps A pointer to ov_preprocess_preprocess_steps_t.\n @param begin Pointer to begin indexes for input tensor cropping.\n Negative values represent counting elements from the end of input tensor\n @param begin_size The size of begin array\n @param end Pointer to end indexes for input tensor cropping.\n End indexes are exclusive, which means values including end edge are not included in the output slice.\n Negative values represent counting elements from the end of input tensor\n @param end_size The size of end array\n @return Status code of the operation: OK(0) for success."]
     pub fn ov_preprocess_preprocess_steps_crop(

crates/openvino-sys/src/generated/types.rs

@@ -1,86 +1,129 @@
 /* automatically generated by rust-bindgen 0.70.1 */
 
-#[doc = "!< SUCCESS"]
-pub const ov_status_e_OK: ov_status_e = 0;
-#[doc = "!< GENERAL_ERROR"]
-pub const ov_status_e_GENERAL_ERROR: ov_status_e = -1;
-#[doc = "!< NOT_IMPLEMENTED"]
-pub const ov_status_e_NOT_IMPLEMENTED: ov_status_e = -2;
-#[doc = "!< NETWORK_NOT_LOADED"]
-pub const ov_status_e_NETWORK_NOT_LOADED: ov_status_e = -3;
-#[doc = "!< PARAMETER_MISMATCH"]
-pub const ov_status_e_PARAMETER_MISMATCH: ov_status_e = -4;
-#[doc = "!< NOT_FOUND"]
-pub const ov_status_e_NOT_FOUND: ov_status_e = -5;
-#[doc = "!< OUT_OF_BOUNDS"]
-pub const ov_status_e_OUT_OF_BOUNDS: ov_status_e = -6;
-#[doc = "!< UNEXPECTED"]
-pub const ov_status_e_UNEXPECTED: ov_status_e = -7;
-#[doc = "!< REQUEST_BUSY"]
-pub const ov_status_e_REQUEST_BUSY: ov_status_e = -8;
-#[doc = "!< RESULT_NOT_READY"]
-pub const ov_status_e_RESULT_NOT_READY: ov_status_e = -9;
-#[doc = "!< NOT_ALLOCATED"]
-pub const ov_status_e_NOT_ALLOCATED: ov_status_e = -10;
-#[doc = "!< INFER_NOT_STARTED"]
-pub const ov_status_e_INFER_NOT_STARTED: ov_status_e = -11;
-#[doc = "!< NETWORK_NOT_READ"]
-pub const ov_status_e_NETWORK_NOT_READ: ov_status_e = -12;
-#[doc = "!< INFER_CANCELLED"]
-pub const ov_status_e_INFER_CANCELLED: ov_status_e = -13;
-#[doc = "!< INVALID_C_PARAM"]
-pub const ov_status_e_INVALID_C_PARAM: ov_status_e = -14;
-#[doc = "!< UNKNOWN_C_ERROR"]
-pub const ov_status_e_UNKNOWN_C_ERROR: ov_status_e = -15;
-#[doc = "!< NOT_IMPLEMENT_C_METHOD"]
-pub const ov_status_e_NOT_IMPLEMENT_C_METHOD: ov_status_e = -16;
-#[doc = "!< UNKNOW_EXCEPTION"]
-pub const ov_status_e_UNKNOW_EXCEPTION: ov_status_e = -17;
+#[repr(i32)]
 #[doc = " @enum ov_status_e\n @ingroup ov_base_c_api\n @brief This enum contains codes for all possible return values of the interface functions"]
-pub type ov_status_e = ::std::os::raw::c_int;
-#[doc = "!< Undefined element type"]
-pub const ov_element_type_e_UNDEFINED: ov_element_type_e = 0;
-#[doc = "!< Dynamic element type"]
-pub const ov_element_type_e_DYNAMIC: ov_element_type_e = 1;
-pub const ov_element_type_e_OV_BOOLEAN: ov_element_type_e = 2;
-#[doc = "!< bf16 element type"]
-pub const ov_element_type_e_BF16: ov_element_type_e = 3;
-#[doc = "!< f16 element type"]
-pub const ov_element_type_e_F16: ov_element_type_e = 4;
-#[doc = "!< f32 element type"]
-pub const ov_element_type_e_F32: ov_element_type_e = 5;
-#[doc = "!< f64 element type"]
-pub const ov_element_type_e_F64: ov_element_type_e = 6;
-#[doc = "!< i4 element type"]
-pub const ov_element_type_e_I4: ov_element_type_e = 7;
-#[doc = "!< i8 element type"]
-pub const ov_element_type_e_I8: ov_element_type_e = 8;
-#[doc = "!< i16 element type"]
-pub const ov_element_type_e_I16: ov_element_type_e = 9;
-#[doc = "!< i32 element type"]
-pub const ov_element_type_e_I32: ov_element_type_e = 10;
-#[doc = "!< i64 element type"]
-pub const ov_element_type_e_I64: ov_element_type_e = 11;
-#[doc = "!< binary element type"]
-pub const ov_element_type_e_U1: ov_element_type_e = 12;
-#[doc = "!< u4 element type"]
-pub const ov_element_type_e_U4: ov_element_type_e = 13;
-#[doc = "!< u8 element type"]
-pub const ov_element_type_e_U8: ov_element_type_e = 14;
-#[doc = "!< u16 element type"]
-pub const ov_element_type_e_U16: ov_element_type_e = 15;
-#[doc = "!< u32 element type"]
-pub const ov_element_type_e_U32: ov_element_type_e = 16;
-#[doc = "!< u64 element type"]
-pub const ov_element_type_e_U64: ov_element_type_e = 17;
-#[doc = "!< nf4 element type"]
-pub const ov_element_type_e_NF4: ov_element_type_e = 18;
-#[doc = "!< f8e4m3 element type"]
-pub const ov_element_type_e_F8E4M3: ov_element_type_e = 19;
-#[doc = "!< f8e5m2 element type"]
-pub const ov_element_type_e_F8E5M3: ov_element_type_e = 20;
-#[doc = " @enum ov_element_type_e\n @ingroup ov_base_c_api\n @brief This enum contains codes for element type."]
-pub type ov_element_type_e = ::std::os::raw::c_uint;
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub enum ov_status_e {
+    #[doc = "!< SUCCESS"]
+    OK = 0,
+    #[doc = "!< GENERAL_ERROR"]
+    GENERAL_ERROR = -1,
+    #[doc = "!< NOT_IMPLEMENTED"]
+    NOT_IMPLEMENTED = -2,
+    #[doc = "!< NETWORK_NOT_LOADED"]
+    NETWORK_NOT_LOADED = -3,
+    #[doc = "!< PARAMETER_MISMATCH"]
+    PARAMETER_MISMATCH = -4,
+    #[doc = "!< NOT_FOUND"]
+    NOT_FOUND = -5,
+    #[doc = "!< OUT_OF_BOUNDS"]
+    OUT_OF_BOUNDS = -6,
+    #[doc = "!< UNEXPECTED"]
+    UNEXPECTED = -7,
+    #[doc = "!< REQUEST_BUSY"]
+    REQUEST_BUSY = -8,
+    #[doc = "!< RESULT_NOT_READY"]
+    RESULT_NOT_READY = -9,
+    #[doc = "!< NOT_ALLOCATED"]
+    NOT_ALLOCATED = -10,
+    #[doc = "!< INFER_NOT_STARTED"]
+    INFER_NOT_STARTED = -11,
+    #[doc = "!< NETWORK_NOT_READ"]
+    NETWORK_NOT_READ = -12,
+    #[doc = "!< INFER_CANCELLED"]
+    INFER_CANCELLED = -13,
+    #[doc = "!< INVALID_C_PARAM"]
+    INVALID_C_PARAM = -14,
+    #[doc = "!< UNKNOWN_C_ERROR"]
+    UNKNOWN_C_ERROR = -15,
+    #[doc = "!< NOT_IMPLEMENT_C_METHOD"]
+    NOT_IMPLEMENT_C_METHOD = -16,
+    #[doc = "!< UNKNOW_EXCEPTION"]
+    UNKNOW_EXCEPTION = -17,
+}
+#[repr(u32)]
+#[doc = " @enum ov_element_type_e\n @ingroup ov_base_c_api\n @brief This enum contains codes for element type, which is aligned with ov::element::Type_t in\n src/core/include/openvino/core/type/element_type.hpp"]
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub enum ov_element_type_e {
+    #[doc = "!< Undefined element type"]
+    UNDEFINED = 0,
+    #[doc = "!< Dynamic element type"]
+    DYNAMIC = 1,
+    OV_BOOLEAN = 2,
+    #[doc = "!< bf16 element type"]
+    BF16 = 3,
+    #[doc = "!< f16 element type"]
+    F16 = 4,
+    #[doc = "!< f32 element type"]
+    F32 = 5,
+    #[doc = "!< f64 element type"]
+    F64 = 6,
+    #[doc = "!< i4 element type"]
+    I4 = 7,
+    #[doc = "!< i8 element type"]
+    I8 = 8,
+    #[doc = "!< i16 element type"]
+    I16 = 9,
+    #[doc = "!< i32 element type"]
+    I32 = 10,
+    #[doc = "!< i64 element type"]
+    I64 = 11,
+    #[doc = "!< binary element type"]
+    U1 = 12,
+    #[doc = "!< u2 element type"]
+    U2 = 13,
+    #[doc = "!< u3 element type"]
+    U3 = 14,
+    #[doc = "!< u4 element type"]
+    U4 = 15,
+    #[doc = "!< u6 element type"]
+    U6 = 16,
+    #[doc = "!< u8 element type"]
+    U8 = 17,
+    #[doc = "!< u16 element type"]
+    U16 = 18,
+    #[doc = "!< u32 element type"]
+    U32 = 19,
+    #[doc = "!< u64 element type"]
+    U64 = 20,
+    #[doc = "!< nf4 element type"]
+    NF4 = 21,
+    #[doc = "!< f8e4m3 element type"]
+    F8E4M3 = 22,
+    #[doc = "!< f8e5m2 element type"]
+    F8E5M3 = 23,
+    #[doc = "!< string element type"]
+    STRING = 24,
+    #[doc = "!< f4e2m1 element type"]
+    F4E2M1 = 25,
+    #[doc = "!< f8e8m0 element type"]
+    F8E8M0 = 26,
+}
+#[doc = " @brief encryption_func is a function pointer that encrypt or decrypt the input memory, example of this function is\n codec(const char* input, const size_t in_size, const char* output, size_t* out_size)\n This function needs to be called twice,\n the first call to obtain out_size (the size of output buffer), the second call to obtain output buffer.\n The first call output is nullptr, before the second call, the caller needs to apply for output\n memory based on the out_size returned by the first call.\n the memory of parameter output is allocated and released by the caller.\n @param input The pointer to the input buffer.\n @param in_size The size of input.\n @param output The pointer to the encrypted/decrypted buffer.\n @param out_size The size of output."]
+pub type encryption_func = ::std::option::Option<
+    unsafe extern "C" fn(
+        arg1: *const ::std::os::raw::c_char,
+        arg2: usize,
+        arg3: *mut ::std::os::raw::c_char,
+        arg4: *mut usize,
+    ),
+>;
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub struct ov_encryption_callbacks {
+    pub encrypt_func: encryption_func,
+    pub decrypt_func: encryption_func,
+}
+#[allow(clippy::unnecessary_operation, clippy::identity_op)]
+const _: () = {
+    ["Size of ov_encryption_callbacks"][::std::mem::size_of::<ov_encryption_callbacks>() - 16usize];
+    ["Alignment of ov_encryption_callbacks"]
+        [::std::mem::align_of::<ov_encryption_callbacks>() - 8usize];
+    ["Offset of field: ov_encryption_callbacks::encrypt_func"]
+        [::std::mem::offset_of!(ov_encryption_callbacks, encrypt_func) - 0usize];
+    ["Offset of field: ov_encryption_callbacks::decrypt_func"]
+        [::std::mem::offset_of!(ov_encryption_callbacks, decrypt_func) - 8usize];
+};
 #[doc = " @struct ov_dimension\n @ingroup ov_dimension_c_api\n @brief This is a structure interface equal to ov::Dimension"]
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
@@ -207,13 +250,16 @@ pub struct ov_profiling_info_t {
     #[doc = "!< Node type."]
     pub node_type: *const ::std::os::raw::c_char,
 }
-#[doc = "!< A node is not executed."]
-pub const ov_profiling_info_t_Status_NOT_RUN: ov_profiling_info_t_Status = 0;
-#[doc = "!< A node is optimized out during graph optimization phase."]
-pub const ov_profiling_info_t_Status_OPTIMIZED_OUT: ov_profiling_info_t_Status = 1;
-#[doc = "!< A node is executed."]
-pub const ov_profiling_info_t_Status_EXECUTED: ov_profiling_info_t_Status = 2;
-pub type ov_profiling_info_t_Status = ::std::os::raw::c_uint;
+#[repr(u32)]
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub enum ov_profiling_info_t_Status {
+    #[doc = "!< A node is not executed."]
+    NOT_RUN = 0,
+    #[doc = "!< A node is optimized out during graph optimization phase."]
+    OPTIMIZED_OUT = 1,
+    #[doc = "!< A node is executed."]
+    EXECUTED = 2,
+}
 #[allow(clippy::unnecessary_operation, clippy::identity_op)]
 const _: () = {
     ["Size of ov_profiling_info_t"][::std::mem::size_of::<ov_profiling_info_t>() - 48usize];
@@ -403,33 +449,39 @@ pub struct ov_preprocess_preprocess_steps {
 }
 #[doc = " @struct ov_preprocess_preprocess_steps_t\n @ingroup ov_prepostprocess_c_api\n @brief type define ov_preprocess_preprocess_steps_t from ov_preprocess_preprocess_steps"]
 pub type ov_preprocess_preprocess_steps_t = ov_preprocess_preprocess_steps;
-#[doc = "!< Undefine color format"]
-pub const ov_color_format_e_UNDEFINE: ov_color_format_e = 0;
-#[doc = "!< Image in NV12 format as single tensor"]
-pub const ov_color_format_e_NV12_SINGLE_PLANE: ov_color_format_e = 1;
-#[doc = "!< Image in NV12 format represented as separate tensors for Y and UV planes."]
-pub const ov_color_format_e_NV12_TWO_PLANES: ov_color_format_e = 2;
-#[doc = "!< Image in I420 (YUV) format as single tensor"]
-pub const ov_color_format_e_I420_SINGLE_PLANE: ov_color_format_e = 3;
-#[doc = "!< Image in I420 format represented as separate tensors for Y, U and V planes."]
-pub const ov_color_format_e_I420_THREE_PLANES: ov_color_format_e = 4;
-#[doc = "!< Image in RGB interleaved format (3 channels)"]
-pub const ov_color_format_e_RGB: ov_color_format_e = 5;
-#[doc = "!< Image in BGR interleaved format (3 channels)"]
-pub const ov_color_format_e_BGR: ov_color_format_e = 6;
-#[doc = "!< Image in GRAY format (1 channel)"]
-pub const ov_color_format_e_GRAY: ov_color_format_e = 7;
-#[doc = "!< Image in RGBX interleaved format (4 channels)"]
-pub const ov_color_format_e_RGBX: ov_color_format_e = 8;
-#[doc = "!< Image in BGRX interleaved format (4 channels)"]
-pub const ov_color_format_e_BGRX: ov_color_format_e = 9;
+#[repr(u32)]
 #[doc = " @enum ov_color_format_e\n @ingroup ov_prepostprocess_c_api\n @brief This enum contains enumerations for color format."]
-pub type ov_color_format_e = ::std::os::raw::c_uint;
-#[doc = "!< linear algorithm"]
-pub const ov_preprocess_resize_algorithm_e_RESIZE_LINEAR: ov_preprocess_resize_algorithm_e = 0;
-#[doc = "!< cubic algorithm"]
-pub const ov_preprocess_resize_algorithm_e_RESIZE_CUBIC: ov_preprocess_resize_algorithm_e = 1;
-#[doc = "!< nearest algorithm"]
-pub const ov_preprocess_resize_algorithm_e_RESIZE_NEAREST: ov_preprocess_resize_algorithm_e = 2;
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub enum ov_color_format_e {
+    #[doc = "!< Undefine color format"]
+    UNDEFINE = 0,
+    #[doc = "!< Image in NV12 format as single tensor"]
+    NV12_SINGLE_PLANE = 1,
+    #[doc = "!< Image in NV12 format represented as separate tensors for Y and UV planes."]
+    NV12_TWO_PLANES = 2,
+    #[doc = "!< Image in I420 (YUV) format as single tensor"]
+    I420_SINGLE_PLANE = 3,
+    #[doc = "!< Image in I420 format represented as separate tensors for Y, U and V planes."]
+    I420_THREE_PLANES = 4,
+    #[doc = "!< Image in RGB interleaved format (3 channels)"]
+    RGB = 5,
+    #[doc = "!< Image in BGR interleaved format (3 channels)"]
+    BGR = 6,
+    #[doc = "!< Image in GRAY format (1 channel)"]
+    GRAY = 7,
+    #[doc = "!< Image in RGBX interleaved format (4 channels)"]
+    RGBX = 8,
+    #[doc = "!< Image in BGRX interleaved format (4 channels)"]
+    BGRX = 9,
+}
+#[repr(u32)]
 #[doc = " @enum ov_preprocess_resize_algorithm_e\n @ingroup ov_prepostprocess_c_api\n @brief This enum contains codes for all preprocess resize algorithm."]
-pub type ov_preprocess_resize_algorithm_e = ::std::os::raw::c_uint;
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub enum ov_preprocess_resize_algorithm_e {
+    #[doc = "!< linear algorithm"]
+    RESIZE_LINEAR = 0,
+    #[doc = "!< cubic algorithm"]
+    RESIZE_CUBIC = 1,
+    #[doc = "!< nearest algorithm"]
+    RESIZE_NEAREST = 2,
+}

crates/openvino-sys/src/lib.rs

@@ -18,7 +18,7 @@
 //!     buildNumber: std::ptr::null(),
 //! };
 //! let code = unsafe { openvino_sys::ov_get_openvino_version(&mut ov_version) };
-//! assert_eq!(code, 0);
+//! assert_eq!(code, openvino_sys::ov_status_e::OK);
 //! let version_ptr = { ov_version }.buildNumber;
 //! let string_version = unsafe { CStr::from_ptr(version_ptr) }.to_string_lossy().into_owned();
 //! unsafe { openvino_sys::ov_version_free(std::ptr::addr_of_mut!(ov_version)) };