/* SPDX-License-Identifier: (GPL-2.0+ OR MIT) */ /* * Rockchip isp1 driver * Copyright (C) 2017 Rockchip Electronics Co., Ltd. */ /* * TODO: Improve documentation, mostly regarding abbreviation and hardware * specificities. */ #ifndef _RKISP1_CONFIG_H #define _RKISP1_CONFIG_H #include #include #define CIFISP_MODULE_DPCC (1 << 0) #define CIFISP_MODULE_BLS (1 << 1) #define CIFISP_MODULE_SDG (1 << 2) #define CIFISP_MODULE_HST (1 << 3) #define CIFISP_MODULE_LSC (1 << 4) #define CIFISP_MODULE_AWB_GAIN (1 << 5) #define CIFISP_MODULE_FLT (1 << 6) #define CIFISP_MODULE_BDM (1 << 7) #define CIFISP_MODULE_CTK (1 << 8) #define CIFISP_MODULE_GOC (1 << 9) #define CIFISP_MODULE_CPROC (1 << 10) #define CIFISP_MODULE_AFC (1 << 11) #define CIFISP_MODULE_AWB (1 << 12) #define CIFISP_MODULE_IE (1 << 13) #define CIFISP_MODULE_AEC (1 << 14) #define CIFISP_MODULE_WDR (1 << 15) #define CIFISP_MODULE_DPF (1 << 16) #define CIFISP_MODULE_DPF_STRENGTH (1 << 17) #define CIFISP_CTK_COEFF_MAX 0x100 #define CIFISP_CTK_OFFSET_MAX 0x800 #define CIFISP_AE_MEAN_MAX 25 #define CIFISP_HIST_BIN_N_MAX 16 #define CIFISP_AFM_MAX_WINDOWS 3 #define CIFISP_DEGAMMA_CURVE_SIZE 17 #define CIFISP_BDM_MAX_TH 0xFF /* * Black level compensation */ /* maximum value for horizontal start address */ #define CIFISP_BLS_START_H_MAX 0x00000FFF /* maximum value for horizontal stop address */ #define CIFISP_BLS_STOP_H_MAX 0x00000FFF /* maximum value for vertical start address */ #define CIFISP_BLS_START_V_MAX 0x00000FFF /* maximum value for vertical stop address */ #define CIFISP_BLS_STOP_V_MAX 0x00000FFF /* maximum is 2^18 = 262144*/ #define CIFISP_BLS_SAMPLES_MAX 0x00000012 /* maximum value for fixed black level */ #define CIFISP_BLS_FIX_SUB_MAX 0x00000FFF /* minimum value for fixed black level */ #define CIFISP_BLS_FIX_SUB_MIN 0xFFFFF000 /* 13 bit range (signed)*/ #define CIFISP_BLS_FIX_MASK 0x00001FFF /* * Automatic white balance measurments */ #define CIFISP_AWB_MAX_GRID 1 #define CIFISP_AWB_MAX_FRAMES 7 /* * Gamma out */ /* Maximum number of color samples supported */ #define CIFISP_GAMMA_OUT_MAX_SAMPLES 17 /* * Lens shade correction */ #define CIFISP_LSC_GRAD_TBL_SIZE 8 #define CIFISP_LSC_SIZE_TBL_SIZE 8 /* * The following matches the tuning process, * not the max capabilities of the chip. * Last value unused. */ #define CIFISP_LSC_DATA_TBL_SIZE 290 /* * Histogram calculation */ /* Last 3 values unused. */ #define CIFISP_HISTOGRAM_WEIGHT_GRIDS_SIZE 28 /* * Defect Pixel Cluster Correction */ #define CIFISP_DPCC_METHODS_MAX 3 /* * Denoising pre filter */ #define CIFISP_DPF_MAX_NLF_COEFFS 17 #define CIFISP_DPF_MAX_SPATIAL_COEFFS 6 /* * Measurement types */ #define CIFISP_STAT_AWB (1 << 0) #define CIFISP_STAT_AUTOEXP (1 << 1) #define CIFISP_STAT_AFM_FIN (1 << 2) #define CIFISP_STAT_HIST (1 << 3) enum cifisp_histogram_mode { CIFISP_HISTOGRAM_MODE_DISABLE, CIFISP_HISTOGRAM_MODE_RGB_COMBINED, CIFISP_HISTOGRAM_MODE_R_HISTOGRAM, CIFISP_HISTOGRAM_MODE_G_HISTOGRAM, CIFISP_HISTOGRAM_MODE_B_HISTOGRAM, CIFISP_HISTOGRAM_MODE_Y_HISTOGRAM }; enum cifisp_awb_mode_type { CIFISP_AWB_MODE_MANUAL, CIFISP_AWB_MODE_RGB, CIFISP_AWB_MODE_YCBCR }; enum cifisp_flt_mode { CIFISP_FLT_STATIC_MODE, CIFISP_FLT_DYNAMIC_MODE }; /** * enum cifisp_exp_ctrl_autostop - stop modes * @CIFISP_EXP_CTRL_AUTOSTOP_0: continuous measurement * @CIFISP_EXP_CTRL_AUTOSTOP_1: stop measuring after a complete frame */ enum cifisp_exp_ctrl_autostop { CIFISP_EXP_CTRL_AUTOSTOP_0 = 0, CIFISP_EXP_CTRL_AUTOSTOP_1 = 1, }; /** * enum cifisp_exp_meas_mode - Exposure measure mode * @CIFISP_EXP_MEASURING_MODE_0: Y = 16 + 0.25R + 0.5G + 0.1094B * @CIFISP_EXP_MEASURING_MODE_1: Y = (R + G + B) x (85/256) */ enum cifisp_exp_meas_mode { CIFISP_EXP_MEASURING_MODE_0, CIFISP_EXP_MEASURING_MODE_1, }; /*---------- PART1: Input Parameters ------------*/ struct cifisp_window { __u16 h_offs; __u16 v_offs; __u16 h_size; __u16 v_size; } __attribute__ ((packed)); /** * struct cifisp_bls_fixed_val - BLS fixed subtraction values * * The values will be subtracted from the sensor * values. Therefore a negative value means addition instead of subtraction! * * @r: Fixed (signed!) subtraction value for Bayer pattern R * @gr: Fixed (signed!) subtraction value for Bayer pattern Gr * @gb: Fixed (signed!) subtraction value for Bayer pattern Gb * @b: Fixed (signed!) subtraction value for Bayer pattern B */ struct cifisp_bls_fixed_val { __s16 r; __s16 gr; __s16 gb; __s16 b; } __attribute__ ((packed)); /** * struct cifisp_bls_config - Configuration used by black level subtraction * * @enable_auto: Automatic mode activated means that the measured values * are subtracted. Otherwise the fixed subtraction * values will be subtracted. * @en_windows: enabled window * @bls_window1: Measurement window 1 size * @bls_window2: Measurement window 2 size * @bls_samples: Set amount of measured pixels for each Bayer position * (A, B,C and D) to 2^bls_samples. * @cifisp_bls_fixed_val: Fixed subtraction values */ struct cifisp_bls_config { __u8 enable_auto; __u8 en_windows; struct cifisp_window bls_window1; struct cifisp_window bls_window2; __u8 bls_samples; struct cifisp_bls_fixed_val fixed_val; } __attribute__ ((packed)); /** * struct cifisp_dpcc_methods_config - Methods Configuration used by DPCC * * Methods Configuration used by Defect Pixel Cluster Correction * * @method: Method enable bits * @line_thresh: Line threshold * @line_mad_fac: Line MAD factor * @pg_fac: Peak gradient factor * @rnd_thresh: Rank Neighbor Difference threshold * @rg_fac: Rank gradient factor */ struct cifisp_dpcc_methods_config { __u32 method; __u32 line_thresh; __u32 line_mad_fac; __u32 pg_fac; __u32 rnd_thresh; __u32 rg_fac; } __attribute__ ((packed)); /** * struct cifisp_dpcc_methods_config - Configuration used by DPCC * * Configuration used by Defect Pixel Cluster Correction * * @mode: dpcc output mode * @output_mode: whether use hard coded methods * @set_use: stage1 methods set * @methods: methods config * @ro_limits: rank order limits * @rnd_offs: differential rank offsets for rank neighbor difference */ struct cifisp_dpcc_config { __u32 mode; __u32 output_mode; __u32 set_use; struct cifisp_dpcc_methods_config methods[CIFISP_DPCC_METHODS_MAX]; __u32 ro_limits; __u32 rnd_offs; } __attribute__ ((packed)); struct cifisp_gamma_corr_curve { __u16 gamma_y[CIFISP_DEGAMMA_CURVE_SIZE]; } __attribute__ ((packed)); struct cifisp_gamma_curve_x_axis_pnts { __u32 gamma_dx0; __u32 gamma_dx1; } __attribute__ ((packed)); /** * struct cifisp_gamma_corr_curve - Configuration used by sensor degamma * * @curve_x: gamma curve point definition axis for x * @xa_pnts: x increments */ struct cifisp_sdg_config { struct cifisp_gamma_corr_curve curve_r; struct cifisp_gamma_corr_curve curve_g; struct cifisp_gamma_corr_curve curve_b; struct cifisp_gamma_curve_x_axis_pnts xa_pnts; } __attribute__ ((packed)); /** * struct cifisp_lsc_config - Configuration used by Lens shading correction * * refer to REF_01 for details */ struct cifisp_lsc_config { __u32 r_data_tbl[CIFISP_LSC_DATA_TBL_SIZE]; __u32 gr_data_tbl[CIFISP_LSC_DATA_TBL_SIZE]; __u32 gb_data_tbl[CIFISP_LSC_DATA_TBL_SIZE]; __u32 b_data_tbl[CIFISP_LSC_DATA_TBL_SIZE]; __u32 x_grad_tbl[CIFISP_LSC_GRAD_TBL_SIZE]; __u32 y_grad_tbl[CIFISP_LSC_GRAD_TBL_SIZE]; __u32 x_size_tbl[CIFISP_LSC_SIZE_TBL_SIZE]; __u32 y_size_tbl[CIFISP_LSC_SIZE_TBL_SIZE]; __u16 config_width; __u16 config_height; } __attribute__ ((packed)); /** * struct cifisp_ie_config - Configuration used by image effects * * @eff_mat_1: 3x3 Matrix Coefficients for Emboss Effect 1 * @eff_mat_2: 3x3 Matrix Coefficients for Emboss Effect 2 * @eff_mat_3: 3x3 Matrix Coefficients for Emboss 3/Sketch 1 * @eff_mat_4: 3x3 Matrix Coefficients for Sketch Effect 2 * @eff_mat_5: 3x3 Matrix Coefficients for Sketch Effect 3 * @eff_tint: Chrominance increment values of tint (used for sepia effect) */ struct cifisp_ie_config { __u16 effect; __u16 color_sel; __u16 eff_mat_1; __u16 eff_mat_2; __u16 eff_mat_3; __u16 eff_mat_4; __u16 eff_mat_5; __u16 eff_tint; } __attribute__ ((packed)); /** * struct cifisp_cproc_config - Configuration used by Color Processing * * @c_out_range: Chrominance pixel clipping range at output. * (0 for limit, 1 for full) * @y_in_range: Luminance pixel clipping range at output. * @y_out_range: Luminance pixel clipping range at output. * @contrast: 00~ff, 0.0~1.992 * @brightness: 80~7F, -128~+127 * @sat: saturation, 00~FF, 0.0~1.992 * @hue: 80~7F, -90~+87.188 */ struct cifisp_cproc_config { __u8 c_out_range; __u8 y_in_range; __u8 y_out_range; __u8 contrast; __u8 brightness; __u8 sat; __u8 hue; } __attribute__ ((packed)); /** * struct cifisp_awb_meas_config - Configuration used by auto white balance * * @awb_wnd: white balance measurement window (in pixels) * (from enum cifisp_awb_mode_type) * @max_y: only pixels values < max_y contribute to awb measurement, set to 0 * to disable this feature * @min_y: only pixels values > min_y contribute to awb measurement * @max_csum: Chrominance sum maximum value, only consider pixels with Cb+Cr, * smaller than threshold for awb measurements * @min_c: Chrominance minimum value, only consider pixels with Cb/Cr * each greater than threshold value for awb measurements * @frames: number of frames - 1 used for mean value calculation * (ucFrames=0 means 1 Frame) * @awb_ref_cr: reference Cr value for AWB regulation, target for AWB * @awb_ref_cb: reference Cb value for AWB regulation, target for AWB */ struct cifisp_awb_meas_config { /* * Note: currently the h and v offsets are mapped to grid offsets */ struct cifisp_window awb_wnd; __u32 awb_mode; __u8 max_y; __u8 min_y; __u8 max_csum; __u8 min_c; __u8 frames; __u8 awb_ref_cr; __u8 awb_ref_cb; __u8 enable_ymax_cmp; } __attribute__ ((packed)); /** * struct cifisp_awb_gain_config - Configuration used by auto white balance gain * * out_data_x = ( AWB_GEAIN_X * in_data + 128) >> 8 */ struct cifisp_awb_gain_config { __u16 gain_red; __u16 gain_green_r; __u16 gain_blue; __u16 gain_green_b; } __attribute__ ((packed)); /** * struct cifisp_flt_config - Configuration used by ISP filtering * * @mode: ISP_FILT_MODE register fields (from enum cifisp_flt_mode) * @grn_stage1: ISP_FILT_MODE register fields * @chr_h_mode: ISP_FILT_MODE register fields * @chr_v_mode: ISP_FILT_MODE register fields * * refer to REF_01 for details. */ struct cifisp_flt_config { __u32 mode; __u8 grn_stage1; __u8 chr_h_mode; __u8 chr_v_mode; __u32 thresh_bl0; __u32 thresh_bl1; __u32 thresh_sh0; __u32 thresh_sh1; __u32 lum_weight; __u32 fac_sh1; __u32 fac_sh0; __u32 fac_mid; __u32 fac_bl0; __u32 fac_bl1; } __attribute__ ((packed)); /** * struct cifisp_bdm_config - Configuration used by Bayer DeMosaic * * @demosaic_th: threshod for bayer demosaicing texture detection */ struct cifisp_bdm_config { __u8 demosaic_th; } __attribute__ ((packed)); /** * struct cifisp_ctk_config - Configuration used by Cross Talk correction * * @coeff: color correction matrix * @ct_offset_b: offset for the crosstalk correction matrix */ struct cifisp_ctk_config { __u16 coeff0; __u16 coeff1; __u16 coeff2; __u16 coeff3; __u16 coeff4; __u16 coeff5; __u16 coeff6; __u16 coeff7; __u16 coeff8; __u16 ct_offset_r; __u16 ct_offset_g; __u16 ct_offset_b; } __attribute__ ((packed)); enum cifisp_goc_mode { CIFISP_GOC_MODE_LOGARITHMIC, CIFISP_GOC_MODE_EQUIDISTANT }; /** * struct cifisp_goc_config - Configuration used by Gamma Out correction * * @mode: goc mode (from enum cifisp_goc_mode) * @gamma_y: gamma out curve y-axis for all color components */ struct cifisp_goc_config { __u32 mode; __u16 gamma_y[CIFISP_GAMMA_OUT_MAX_SAMPLES]; } __attribute__ ((packed)); /** * struct cifisp_hst_config - Configuration used by Histogram * * @mode: histogram mode (from enum cifisp_histogram_mode) * @histogram_predivider: process every stepsize pixel, all other pixels are * skipped * @meas_window: coordinates of the measure window * @hist_weight: weighting factor for sub-windows */ struct cifisp_hst_config { __u32 mode; __u8 histogram_predivider; struct cifisp_window meas_window; __u8 hist_weight[CIFISP_HISTOGRAM_WEIGHT_GRIDS_SIZE]; } __attribute__ ((packed)); /** * struct cifisp_aec_config - Configuration used by Auto Exposure Control * * @mode: Exposure measure mode (from enum cifisp_exp_meas_mode) * @autostop: stop mode (from enum cifisp_exp_ctrl_autostop) * @meas_window: coordinates of the measure window */ struct cifisp_aec_config { __u32 mode; __u32 autostop; struct cifisp_window meas_window; } __attribute__ ((packed)); /** * struct cifisp_afc_config - Configuration used by Auto Focus Control * * @num_afm_win: max CIFISP_AFM_MAX_WINDOWS * @afm_win: coordinates of the meas window * @thres: threshold used for minimizing the influence of noise * @var_shift: the number of bits for the shift operation at the end of the * calculation chain. */ struct cifisp_afc_config { __u8 num_afm_win; struct cifisp_window afm_win[CIFISP_AFM_MAX_WINDOWS]; __u32 thres; __u32 var_shift; } __attribute__ ((packed)); /** * enum cifisp_dpf_gain_usage - dpf gain usage * @CIFISP_DPF_GAIN_USAGE_DISABLED: don't use any gains in preprocessing stage * @CIFISP_DPF_GAIN_USAGE_NF_GAINS: use only the noise function gains from * registers DPF_NF_GAIN_R, ... * @CIFISP_DPF_GAIN_USAGE_LSC_GAINS: use only the gains from LSC module * @CIFISP_DPF_GAIN_USAGE_NF_LSC_GAINS: use the noise function gains and the * gains from LSC module * @CIFISP_DPF_GAIN_USAGE_AWB_GAINS: use only the gains from AWB module * @CIFISP_DPF_GAIN_USAGE_AWB_LSC_GAINS: use the gains from AWB and LSC module * @CIFISP_DPF_GAIN_USAGE_MAX: upper border (only for an internal evaluation) */ enum cifisp_dpf_gain_usage { CIFISP_DPF_GAIN_USAGE_DISABLED, CIFISP_DPF_GAIN_USAGE_NF_GAINS, CIFISP_DPF_GAIN_USAGE_LSC_GAINS, CIFISP_DPF_GAIN_USAGE_NF_LSC_GAINS, CIFISP_DPF_GAIN_USAGE_AWB_GAINS, CIFISP_DPF_GAIN_USAGE_AWB_LSC_GAINS, CIFISP_DPF_GAIN_USAGE_MAX }; /** * enum cifisp_dpf_gain_usage - dpf gain usage * @CIFISP_DPF_RB_FILTERSIZE_13x9: red and blue filter kernel size 13x9 * (means 7x5 active pixel) * @CIFISP_DPF_RB_FILTERSIZE_9x9: red and blue filter kernel size 9x9 * (means 5x5 active pixel) */ enum cifisp_dpf_rb_filtersize { CIFISP_DPF_RB_FILTERSIZE_13x9, CIFISP_DPF_RB_FILTERSIZE_9x9, }; /** * enum cifisp_dpf_nll_scale_mode - dpf noise level scale mode * @CIFISP_NLL_SCALE_LINEAR: use a linear scaling * @CIFISP_NLL_SCALE_LOGARITHMIC: use a logarithmic scaling */ enum cifisp_dpf_nll_scale_mode { CIFISP_NLL_SCALE_LINEAR, CIFISP_NLL_SCALE_LOGARITHMIC, }; /** * struct cifisp_dpf_nll - Noise level lookup * * @coeff: Noise level Lookup coefficient * @scale_mode: dpf noise level scale mode (from enum cifisp_dpf_nll_scale_mode) */ struct cifisp_dpf_nll { __u16 coeff[CIFISP_DPF_MAX_NLF_COEFFS]; __u32 scale_mode; } __attribute__ ((packed)); /** * struct cifisp_dpf_rb_flt - Red blue filter config * * @fltsize: The filter size for the red and blue pixels * (from enum cifisp_dpf_rb_filtersize) * @spatial_coeff: Spatial weights * @r_enable: enable filter processing for red pixels * @b_enable: enable filter processing for blue pixels */ struct cifisp_dpf_rb_flt { __u32 fltsize; __u8 spatial_coeff[CIFISP_DPF_MAX_SPATIAL_COEFFS]; __u8 r_enable; __u8 b_enable; } __attribute__ ((packed)); /** * struct cifisp_dpf_g_flt - Green filter Configuration * * @spatial_coeff: Spatial weights * @gr_enable: enable filter processing for green pixels in green/red lines * @gb_enable: enable filter processing for green pixels in green/blue lines */ struct cifisp_dpf_g_flt { __u8 spatial_coeff[CIFISP_DPF_MAX_SPATIAL_COEFFS]; __u8 gr_enable; __u8 gb_enable; } __attribute__ ((packed)); /** * struct cifisp_dpf_gain - Noise function Configuration * * @mode: dpf gain usage (from enum cifisp_dpf_gain_usage) * @nf_r_gain: Noise function Gain that replaces the AWB gain for red pixels * @nf_b_gain: Noise function Gain that replaces the AWB gain for blue pixels * @nf_gr_gain: Noise function Gain that replaces the AWB gain * for green pixels in a red line * @nf_gb_gain: Noise function Gain that replaces the AWB gain * for green pixels in a blue line */ struct cifisp_dpf_gain { __u32 mode; __u16 nf_r_gain; __u16 nf_b_gain; __u16 nf_gr_gain; __u16 nf_gb_gain; } __attribute__ ((packed)); /** * struct cifisp_dpf_config - Configuration used by De-noising pre-filter * * @gain: noise function gain * @g_flt: green filter config * @rb_flt: red blue filter config * @nll: noise level lookup */ struct cifisp_dpf_config { struct cifisp_dpf_gain gain; struct cifisp_dpf_g_flt g_flt; struct cifisp_dpf_rb_flt rb_flt; struct cifisp_dpf_nll nll; } __attribute__ ((packed)); /** * struct cifisp_dpf_strength_config - strength of the filter * * @r: filter strength of the RED filter * @g: filter strength of the GREEN filter * @b: filter strength of the BLUE filter */ struct cifisp_dpf_strength_config { __u8 r; __u8 g; __u8 b; } __attribute__ ((packed)); /** * struct cifisp_isp_other_cfg - Parameters for some blocks in rockchip isp1 * * @dpcc_config: Defect Pixel Cluster Correction config * @bls_config: Black Level Subtraction config * @sdg_config: sensor degamma config * @lsc_config: Lens Shade config * @awb_gain_config: Auto White balance gain config * @flt_config: filter config * @bdm_config: demosaic config * @ctk_config: cross talk config * @goc_config: gamma out config * @bls_config: black level subtraction config * @dpf_config: De-noising pre-filter config * @dpf_strength_config: dpf strength config * @cproc_config: color process config * @ie_config: image effects config */ struct cifisp_isp_other_cfg { struct cifisp_dpcc_config dpcc_config; struct cifisp_bls_config bls_config; struct cifisp_sdg_config sdg_config; struct cifisp_lsc_config lsc_config; struct cifisp_awb_gain_config awb_gain_config; struct cifisp_flt_config flt_config; struct cifisp_bdm_config bdm_config; struct cifisp_ctk_config ctk_config; struct cifisp_goc_config goc_config; struct cifisp_dpf_config dpf_config; struct cifisp_dpf_strength_config dpf_strength_config; struct cifisp_cproc_config cproc_config; struct cifisp_ie_config ie_config; } __attribute__ ((packed)); /** * struct cifisp_isp_meas_cfg - Rockchip ISP1 Measure Parameters * * @awb_meas_config: auto white balance config * @hst_config: histogram config * @aec_config: auto exposure config * @afc_config: auto focus config */ struct cifisp_isp_meas_cfg { struct cifisp_awb_meas_config awb_meas_config; struct cifisp_hst_config hst_config; struct cifisp_aec_config aec_config; struct cifisp_afc_config afc_config; } __attribute__ ((packed)); /** * struct rkisp1_isp_params_cfg - Rockchip ISP1 Input Parameters Meta Data * * @module_en_update: mask the enable bits of which module should be updated * @module_ens: mask the enable value of each module, only update the module * which correspond bit was set in module_en_update * @module_cfg_update: mask the config bits of which module should be updated * @meas: measurement config * @others: other config */ struct rkisp1_isp_params_cfg { __u32 module_en_update; __u32 module_ens; __u32 module_cfg_update; struct cifisp_isp_meas_cfg meas; struct cifisp_isp_other_cfg others; } __attribute__ ((packed)); /*---------- PART2: Measurement Statistics ------------*/ /** * struct cifisp_bls_meas_val - AWB measured values * * @cnt: White pixel count, number of "white pixels" found during laster * measurement * @mean_y_or_g: Mean value of Y within window and frames, * Green if RGB is selected. * @mean_cb_or_b: Mean value of Cb within window and frames, * Blue if RGB is selected. * @mean_cr_or_r: Mean value of Cr within window and frames, * Red if RGB is selected. */ struct cifisp_awb_meas { __u32 cnt; __u8 mean_y_or_g; __u8 mean_cb_or_b; __u8 mean_cr_or_r; } __attribute__ ((packed)); /** * struct cifisp_awb_stat - statistics automatic white balance data * * @awb_mean: Mean measured data */ struct cifisp_awb_stat { struct cifisp_awb_meas awb_mean[CIFISP_AWB_MAX_GRID]; } __attribute__ ((packed)); /** * struct cifisp_bls_meas_val - BLS measured values * * @meas_r: Mean measured value for Bayer pattern R * @meas_gr: Mean measured value for Bayer pattern Gr * @meas_gb: Mean measured value for Bayer pattern Gb * @meas_b: Mean measured value for Bayer pattern B */ struct cifisp_bls_meas_val { __u16 meas_r; __u16 meas_gr; __u16 meas_gb; __u16 meas_b; } __attribute__ ((packed)); /** * struct cifisp_ae_stat - statistics auto exposure data * * @exp_mean: Mean luminance value of block xx * @bls_val: BLS measured values * * Image is divided into 5x5 blocks. */ struct cifisp_ae_stat { __u8 exp_mean[CIFISP_AE_MEAN_MAX]; struct cifisp_bls_meas_val bls_val; } __attribute__ ((packed)); /** * struct cifisp_af_meas_val - AF measured values * * @sum: sharpness, refer to REF_01 for definition * @lum: luminance, refer to REF_01 for definition */ struct cifisp_af_meas_val { __u32 sum; __u32 lum; } __attribute__ ((packed)); /** * struct cifisp_af_stat - statistics auto focus data * * @window: AF measured value of window x * * The module measures the sharpness in 3 windows of selectable size via * register settings(ISP_AFM_*_A/B/C) */ struct cifisp_af_stat { struct cifisp_af_meas_val window[CIFISP_AFM_MAX_WINDOWS]; } __attribute__ ((packed)); /** * struct cifisp_hist_stat - statistics histogram data * * @hist_bins: measured bin counters * * Measurement window divided into 25 sub-windows, set * with ISP_HIST_XXX */ struct cifisp_hist_stat { __u16 hist_bins[CIFISP_HIST_BIN_N_MAX]; } __attribute__ ((packed)); /** * struct rkisp1_stat_buffer - Rockchip ISP1 Statistics Data * * @cifisp_awb_stat: statistics data for automatic white balance * @cifisp_ae_stat: statistics data for auto exposure * @cifisp_af_stat: statistics data for auto focus * @cifisp_hist_stat: statistics histogram data */ struct cifisp_stat { struct cifisp_awb_stat awb; struct cifisp_ae_stat ae; struct cifisp_af_stat af; struct cifisp_hist_stat hist; } __attribute__ ((packed)); /** * struct rkisp1_stat_buffer - Rockchip ISP1 Statistics Meta Data * * @meas_type: measurement types (CIFISP_STAT_ definitions) * @frame_id: frame ID for sync * @params: statistics data */ struct rkisp1_stat_buffer { __u32 meas_type; __u32 frame_id; struct cifisp_stat params; } __attribute__ ((packed)); #endif /* _RKISP1_CONFIG_H */ #n539'>539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 
/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2019, Google Inc.
 *
 * thread.cpp - Thread support
 */

#include <libcamera/base/thread.h>

#include <atomic>
#include <list>
#include <sys/syscall.h>
#include <sys/types.h>
#include <unistd.h>

#include <libcamera/base/event_dispatcher.h>
#include <libcamera/base/event_dispatcher_poll.h>
#include <libcamera/base/log.h>
#include <libcamera/base/message.h>
#include <libcamera/base/mutex.h>

/**
 * \page thread Thread Support
 *
 * libcamera supports multi-threaded applications through a threading model that
 * sets precise rules to guarantee thread-safe usage of the API. Additionally,
 * libcamera makes internal use of threads, and offers APIs that simplify
 * interactions with application threads. Careful compliance with the threading
 * model will ensure avoidance of race conditions.
 *
 * Every thread created by libcamera is associated with an instance of the
 * Thread class. Those threads run an internal event loop by default to
 * dispatch events to objects. Additionally, the main thread of the application
 * (defined as the thread that calls CameraManager::start()) is also associated
 * with a Thread instance, but has no event loop accessible to libcamera. Other
 * application threads are not visible to libcamera.
 *
 * \section thread-objects Threads and Objects
 *
 * Instances of the Object class and all its derived classes are thread-aware
 * and are bound to the thread they are created in. They are said to *live* in
 * a thread, and they interact with the event loop of their thread for the
 * purpose of message passing and signal delivery. Messages posted to the
 * object with Object::postMessage() will be delivered from the event loop of
 * the thread that the object lives in. Signals delivered to the object, unless
 * explicitly connected with ConnectionTypeDirect, will also be delivered from
 * the object thread's event loop.
 *
 * All Object instances created internally by libcamera are bound to internal
 * threads. As objects interact with thread event loops for proper operation,
 * creating an Object instance in a thread that has no internal event loop (such
 * as the main application thread, or libcamera threads that have a custom main
 * loop), prevents some features of the Object class from being used. See
 * Thread::exec() for more details.
 *
 * \section thread-signals Threads and Signals
 *
 * When sent to a receiver that does not inherit from the Object class, signals
 * are delivered synchronously in the thread of the sender. When the receiver
 * inherits from the Object class, delivery is by default asynchronous if the
 * sender and receiver live in different threads. In that case, the signal is
 * posted to the receiver's message queue and will be delivered from the
 * receiver's event loop, running in the receiver's thread. This mechanism can
 * be overridden by selecting a different connection type when calling
 * Signal::connect().
 *
 * \section thread-reentrancy Reentrancy and Thread-Safety
 *
 * Through the documentation, several terms are used to define how classes and
 * their member functions can be used from multiple threads.
 *
 * - A **reentrant** function may be called simultaneously from multiple
 *   threads if and only if each invocation uses a different instance of the
 *   class. This is the default for all member functions not explictly marked
 *   otherwise.
 *
 * - \anchor thread-safe A **thread-safe** function may be called
 *   simultaneously from multiple threads on the same instance of a class. A
 *   thread-safe function is thus reentrant. Thread-safe functions may also be
 *   called simultaneously with any other reentrant function of the same class
 *   on the same instance.
 *
 * - \anchor thread-bound A **thread-bound** function may be called only from
 *   the thread that the class instances lives in (see section \ref
 *   thread-objects). For instances of classes that do not derive from the
 *   Object class, this is the thread in which the instance was created. A
 *   thread-bound function is not thread-safe, and may or may not be reentrant.
 *
 * Neither reentrancy nor thread-safety, in this context, mean that a function
 * may be called simultaneously from the same thread, for instance from a
 * callback invoked by the function. This may deadlock and isn't allowed unless
 * separately documented.
 *
 * A class is defined as reentrant, thread-safe or thread-bound if all its
 * member functions are reentrant, thread-safe or thread-bound respectively.
 * Some member functions may additionally be documented as having additional
 * thread-related attributes.
 *
 * Most classes are reentrant but not thread-safe, as making them fully
 * thread-safe would incur locking costs considered prohibitive for the
 * expected use cases.
 */

/**
 * \file base/thread.h
 * \brief Thread support
 */

namespace libcamera {

LOG_DEFINE_CATEGORY(Thread)

class ThreadMain;

/**
 * \brief A queue of posted messages
 */
class MessageQueue
{
public:
	/**
	 * \brief List of queued Message instances
	 */
	std::list<std::unique_ptr<Message>> list_;
	/**
	 * \brief Protects the \ref list_
	 */
	Mutex mutex_;
	/**
	 * \brief The recursion level for recursive Thread::dispatchMessages()
	 * calls
	 */
	unsigned int recursion_ = 0;
};

/**
 * \brief Thread-local internal data
 */
class ThreadData
{
public:
	ThreadData()
		: thread_(nullptr), running_(false), dispatcher_(nullptr)
	{
	}

	static ThreadData *current();

private:
	friend class Thread;
	friend class ThreadMain;

	Thread *thread_;
	bool running_;
	pid_t tid_;

	Mutex mutex_;

	std::atomic<EventDispatcher *> dispatcher_;

	ConditionVariable cv_;
	std::atomic<bool> exit_;
	int exitCode_;

	MessageQueue messages_;
};

/**
 * \brief Thread wrapper for the main thread
 */
class ThreadMain : public Thread
{
public:
	ThreadMain()
	{
		data_->running_ = true;
	}

protected:
	void run() override
	{
		LOG(Thread, Fatal) << "The main thread can't be restarted";
	}
};

static thread_local ThreadData *currentThreadData = nullptr;
static ThreadMain mainThread;

/**
 * \brief Retrieve thread-local internal data for the current thread
 * \return The thread-local internal data for the current thread
 */
ThreadData *ThreadData::current()
{
	if (currentThreadData)
		return currentThreadData;

	/*
	 * The main thread doesn't receive thread-local data when it is
	 * started, set it here.
	 */
	ThreadData *data = mainThread.data_;
	data->tid_ = syscall(SYS_gettid);
	currentThreadData = data;
	return data;
}

/**
 * \class Thread
 * \brief A thread of execution
 *
 * The Thread class is a wrapper around std::thread that handles integration
 * with the Object, Signal and EventDispatcher classes.
 *
 * Thread instances by default run an event loop until the exit() function is
 * called. The event loop dispatches events (messages, notifiers and timers)
 * sent to the objects living in the thread. This behaviour can be modified by
 * overriding the run() function.
 *
 * \section thread-stop Stopping Threads
 *
 * Threads can't be forcibly stopped. Instead, a thread user first requests the
 * thread to exit and then waits for the thread's main function to react to the
 * request and return, at which points the thread will stop.
 *
 * For threads running exec(), the exit() function is used to request the thread
 * to exit. For threads subclassing the Thread class and implementing a custom
 * run() function, a subclass-specific mechanism shall be provided. In either
 * case, the wait() function shall be called to wait for the thread to stop.
 *
 * Due to their asynchronous nature, threads are subject to race conditions when
 * they stop. This is of particular importance for messages posted to the thread
 * with postMessage() (and the other mechanisms that rely on it, such as
 * Object::invokeMethod() or asynchronous signal delivery). To understand the
 * issues, three contexts need to be considered:
 *
 * - The worker is the Thread performing work and being instructed to stop.
 * - The controller is the context which instructs the worker thread to stop.
 * - The other contexts are any threads other than the worker and controller
 *   that interact with the worker thread.
 *
 * Messages posted to the worker thread from the controller context before
 * calling exit() are queued to the thread's message queue, and the Thread class
 * offers no guarantee that those messages will be processed before the thread
 * stops. This allows threads to stop fast.
 *
 * A thread that requires delivery of messages posted from the controller
 * context before exit() should reimplement the run() function and call
 * dispatchMessages() after exec().
 *
 * Messages posted to the worker thread from the other contexts are asynchronous
 * with respect to the exit() call from the controller context. There is no
 * guarantee as to whether those messages will be processed or not before the
 * thread stops.
 *
 * Messages that are not processed will stay in the queue, in the exact same way
 * as messages posted after the thread has stopped. They will be processed when
 * the thread is restarted. If the thread is never restarted, they will be
 * deleted without being processed when the Thread instance is destroyed.
 */

/**
 * \brief Create a thread
 */
Thread::Thread()
{
	data_ = new ThreadData;
	data_->thread_ = this;
}

Thread::~Thread()
{
	delete data_->dispatcher_.load(std::memory_order_relaxed);
	delete data_;
}

/**
 * \brief Start the thread
 */
void Thread::start()
{
	MutexLocker locker(data_->mutex_);

	if (data_->running_)
		return;

	data_->running_ = true;
	data_->exitCode_ = -1;
	data_->exit_.store(false, std::memory_order_relaxed);

	thread_ = std::thread(&Thread::startThread, this);
}

void Thread::startThread()
{
	struct ThreadCleaner {
		ThreadCleaner(Thread *thread, void (Thread::*cleaner)())
			: thread_(thread), cleaner_(cleaner)
		{
		}
		~ThreadCleaner()
		{
			(thread_->*cleaner_)();
		}

		Thread *thread_;
		void (Thread::*cleaner_)();
	};

	/*
	 * Make sure the thread is cleaned up even if the run() function exits
	 * abnormally (for instance via a direct call to pthread_cancel()).
	 */
	thread_local ThreadCleaner cleaner(this, &Thread::finishThread);

	data_->tid_ = syscall(SYS_gettid);
	currentThreadData = data_;

	run();
}

/**
 * \brief Enter the event loop
 *
 * This function enters an event loop based on the event dispatcher instance for
 * the thread, and blocks until the exit() function is called. It is meant to be
 * called within the thread from the run() function and shall not be called
 * outside of the thread.
 *
 * \return The exit code passed to the exit() function
 */
int Thread::exec()
{
	MutexLocker locker(data_->mutex_);

	EventDispatcher *dispatcher = eventDispatcher();

	locker.unlock();

	while (!data_->exit_.load(std::memory_order_acquire))
		dispatcher->processEvents();

	locker.lock();

	return data_->exitCode_;
}

/**
 * \brief Main function of the thread
 *
 * When the thread is started with start(), it calls this function in the
 * context of the new thread. The run() function can be overridden to perform
 * custom work, either custom initialization and cleanup before and after
 * calling the Thread::exec() function, or a custom thread loop altogether. When
 * this function returns the thread execution is stopped, and the \ref finished
 * signal is emitted.
 *
 * Note that if this function is overridden and doesn't call Thread::exec(), no
 * events will be dispatched to the objects living in the thread. These objects
 * will not be able to use the EventNotifier, Timer or Message facilities. This
 * includes functions that rely on message dispatching, such as
 * Object::deleteLater().
 *
 * The base implementation just calls exec().
 */
void Thread::run()
{
	exec();
}

void Thread::finishThread()
{
	data_->mutex_.lock();
	data_->running_ = false;
	data_->mutex_.unlock();

	finished.emit();
	data_->cv_.notify_all();
}

/**
 * \brief Stop the thread's event loop
 * \param[in] code The exit code
 *
 * This function interrupts the event loop started by the exec() function,
 * causing exec() to return \a code.
 *
 * Calling exit() on a thread that reimplements the run() function and doesn't
 * call exec() will likely have no effect.
 *
 * \context This function is \threadsafe.
 */
void Thread::exit(int code)
{
	data_->exitCode_ = code;
	data_->exit_.store(true, std::memory_order_release);

	EventDispatcher *dispatcher = data_->dispatcher_.load(std::memory_order_relaxed);
	if (!dispatcher)
		return;

	dispatcher->interrupt();
}

/**
 * \brief Wait for the thread to finish
 * \param[in] duration Maximum wait duration
 *
 * This function waits until the thread finishes or the \a duration has
 * elapsed, whichever happens first. If \a duration is equal to
 * utils::duration::max(), the wait never times out. If the thread is not
 * running the function returns immediately.
 *
 * \context This function is \threadsafe.
 *
 * \return True if the thread has finished, or false if the wait timed out
 */
bool Thread::wait(utils::duration duration)
{
	bool hasFinished = true;

	{
		MutexLocker locker(data_->mutex_);

		if (duration == utils::duration::max())
			data_->cv_.wait(locker, [&]() { return !data_->running_; });
		else
			hasFinished = data_->cv_.wait_for(locker, duration,
							  [&]() { return !data_->running_; });
	}

	if (thread_.joinable())
		thread_.join();

	return hasFinished;
}

/**
 * \brief Check if the thread is running
 *
 * A Thread instance is considered as running once the underlying thread has
 * started. This function guarantees that it returns true after the start()
 * function returns, and false after the wait() function returns.
 *
 * \context This function is \threadsafe.
 *
 * \return True if the thread is running, false otherwise
 */
bool Thread::isRunning()
{
	MutexLocker locker(data_->mutex_);
	return data_->running_;
}

/**
 * \var Thread::finished
 * \brief Signal the end of thread execution
 */

/**
 * \brief Retrieve the Thread instance for the current thread
 * \context This function is \threadsafe.
 * \return The Thread instance for the current thread
 */
Thread *Thread::current()
{
	ThreadData *data = ThreadData::current();
	return data->thread_;
}

/**
 * \brief Retrieve the ID of the current thread
 *
 * The thread ID corresponds to the Linux thread ID (TID) as returned by the
 * gettid system call.
 *
 * \context This function is \threadsafe.
 *
 * \return The ID of the current thread
 */
pid_t Thread::currentId()
{
	ThreadData *data = ThreadData::current();
	return data->tid_;
}

/**
 * \brief Retrieve the event dispatcher
 *
 * This function retrieves the internal event dispatcher for the thread. The
 * returned event dispatcher is valid until the thread is destroyed.
 *
 * \context This function is \threadsafe.
 *
 * \return Pointer to the event dispatcher
 */
EventDispatcher *Thread::eventDispatcher()
{
	if (!data_->dispatcher_.load(std::memory_order_relaxed))
		data_->dispatcher_.store(new EventDispatcherPoll(),
					 std::memory_order_release);

	return data_->dispatcher_.load(std::memory_order_relaxed);
}

/**
 * \brief Post a message to the thread for the \a receiver
 * \param[in] msg The message
 * \param[in] receiver The receiver
 *
 * This function stores the message \a msg in the message queue of the thread
 * for the \a receiver and wake up the thread's event loop. Message ownership is
 * passed to the thread, and the message will be deleted after being delivered.
 *
 * Messages are delivered through the thread's event loop. If the thread is not
 * running its event loop the message will not be delivered until the event
 * loop gets started.
 *
 * When the thread is stopped, posted messages may not have all been processed.
 * See \ref thread-stop for additional information.
 *
 * If the \a receiver is not bound to this thread the behaviour is undefined.
 *
 * \context This function is \threadsafe.
 *
 * \sa exec()
 */
void Thread::postMessage(std::unique_ptr<Message> msg, Object *receiver)
{
	msg->receiver_ = receiver;

	ASSERT(data_ == receiver->thread()->data_);