[PATCH v6 3/4] media: uapi: mediatek: Add MT8188 AIE control definitions

[CK Hu (胡俊光)]

On Fri, 2026-06-05 at 16:29 +0800, Sarang Chaudhari wrote:
> Add AIE (AI Engine) UAPI control definitions and register the
> V4L2_META_FMT_MTFD_RESULT metadata format for the MediaTek face
> detection hardware accelerator.
> 
> This patch adds:
> - include/uapi/linux/mtk_aie_v4l2_controls.h: Custom V4L2 control IDs
>   for AIE initialization and per-frame parameters.
> - V4L2_META_FMT_MTFD_RESULT format in videodev2.h for face detection
>   result metadata output.
> - Format description in v4l2-ioctl.c.
> 
> Signed-off-by: Sarang Chaudhari <sarang.chaudhari at mediatek.com>
> ---
> Changes in v6:
> - Simplify UAPI header to contain only control ID definitions. Full
>   structures kept in kernel-internal header for now, pending UAPI
>   structure redesign per CK Hu's feedback.
> - Drop V4L2_CTRL_TYPE_AIE_INIT and V4L2_CTRL_TYPE_AIE_PARAM from
>   v4l2_ctrl_type enum (use V4L2_CTRL_TYPE_U32 compound control instead).
> - Address CK Hu's review feedback: remove freq_level, improve
>   feature_threshold docs, clarify pyramid multi-scale detection, clarify
>   FLD mode uses FD results via Binary Tree Traversal.
> 
> Changes in v5:
> - Add an introduction for feature_threshold.
> - Rename v4l2_aie_roi to aie_roi_coordinate.
> - Rename v4l2_aie_padding to aie_padding_size.
> - Explain en_padding and the three modes of fd_mode.
> - Move structures from mtk_aie.h to the uapi directory.
> 
> Changes in v4:
> - Document the detail of V4L2_META_FMT_MTFD_RESULT.
> - Add the introduction of related variables.
> 
> Changes in v3: None
> 
> Changes in v2:
> - Fix coding style.
> 
>  drivers/media/v4l2-core/v4l2-ioctl.c       |  1 +
>  include/uapi/linux/mtk_aie_v4l2_controls.h | 23 ++++++++++++++++++++++
>  include/uapi/linux/videodev2.h             |  1 +
>  3 files changed, 25 insertions(+)
>  create mode 100644 include/uapi/linux/mtk_aie_v4l2_controls.h
> 
> diff --git a/drivers/media/v4l2-core/v4l2-ioctl.c b/drivers/media/v4l2-core/v4l2-ioctl.c
> index e50e517..8754098 100644
> --- a/drivers/media/v4l2-core/v4l2-ioctl.c
> +++ b/drivers/media/v4l2-core/v4l2-ioctl.c
> @@ -11,6 +11,7 @@ static void v4l_fill_fmtdesc(struct v4l2_fmtdesc *fmt)
>  	case V4L2_META_FMT_GENERIC_CSI2_16:	descr = "8-bit Generic Meta, 16b CSI-2"; break;
>  	case V4L2_META_FMT_GENERIC_CSI2_20:	descr = "8-bit Generic Meta, 20b CSI-2"; break;
>  	case V4L2_META_FMT_GENERIC_CSI2_24:	descr = "8-bit Generic Meta, 24b CSI-2"; break;
> +	case V4L2_META_FMT_MTFD_RESULT:	descr = "Mediatek Face Detect Result"; break;
>  
>  	default:
>  		/* Compressed formats */
> diff --git a/include/uapi/linux/mtk_aie_v4l2_controls.h b/include/uapi/linux/mtk_aie_v4l2_controls.h
> new file mode 100644
> index 0000000..a8b2927
> --- /dev/null
> +++ b/include/uapi/linux/mtk_aie_v4l2_controls.h
> @@ -0,0 +1,23 @@
> +/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
> +/*
> + * MediaTek AI Engine (AIE) V4L2 control definitions
> + *
> + * Copyright (c) 2020 MediaTek Inc.
> + * Author: Fish Wu <fish.wu at mediatek.com>
> + */
> +
> +#ifndef __UAPI_MTK_AIE_V4L2_CONTROLS_H__
> +#define __UAPI_MTK_AIE_V4L2_CONTROLS_H__
> +
> +#include <linux/videodev2.h>
> +
> +/*
> + * The base for the MediaTek AIE driver controls.
> + * We reserve 16 controls for this driver.
> + */
> +#define V4L2_CID_USER_MTK_FD_BASE	(V4L2_CID_USER_BASE + 0x1fd0)
> +
> +#define V4L2_CID_MTK_AIE_INIT		(V4L2_CID_USER_MTK_FD_BASE + 1)
> +#define V4L2_CID_MTK_AIE_PARAM		(V4L2_CID_USER_MTK_FD_BASE + 2)

Add definition of parameter of V4L2_CID_MTK_AIE_INIT and V4L2_CID_MTK_AIE_PARAM,
so user space would know how to control this driver.
If this patch is not ready to apply. Add 'RFC' prefix in title.

> +
> +#endif /* __UAPI_MTK_AIE_V4L2_CONTROLS_H__ */
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index 7668201..6d6866d 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -10,6 +10,7 @@ struct v4l2_pix_format {
>  #define V4L2_META_FMT_GENERIC_CSI2_16	v4l2_fourcc('M', 'C', '1', 'G') /* 16-bit CSI-2 packed 8-bit metadata */
>  #define V4L2_META_FMT_GENERIC_CSI2_20	v4l2_fourcc('M', 'C', '1', 'K') /* 20-bit CSI-2 packed 8-bit metadata */
>  #define V4L2_META_FMT_GENERIC_CSI2_24	v4l2_fourcc('M', 'C', '1', 'O') /* 24-bit CSI-2 packed 8-bit metadata */
> +#define V4L2_META_FMT_MTFD_RESULT	v4l2_fourcc('M', 'T', 'f', 'd') /* Mediatek face detection result */

Add document to describe the detail of V4L2_META_FMT_MTFD_RESULT. [1] is the example document for V4L2_META_FMT_RPI_FE_CFG.
There are many document in Documentation/userspace-api/media/v4l/ for your reference.
 
[1] https://patchwork.kernel.org/project/linux-media/patch/20241003-rp1-cfe-v6-1-d6762edd98a8@ideasonboard.com/

Regards,
CK

>  #endif
>  
>  /* priv field value to indicates that subsequent fields are valid. */