From dca817ce7721fdd6d501d5199534c97f9e7b438a Mon Sep 17 00:00:00 2001 From: Anand Gandhimathi Date: Mon, 12 Mar 2012 17:28:45 -0700 Subject: [PATCH] gfx: hdmi: Convert API interface documentation to kernel doc Added comments for all the functions following the template mentioned in kernel documentation Signed-off-by: Chen Hu Signed-off-by: Kirill A. Shutemov --- .../mrst/drv/otm_hdmi/os/android/android_hdmi.c | 221 ++++++++++---- .../mrst/drv/otm_hdmi/pil/common/otm_hdmi.c | 339 ++++++++++++++------- 2 files changed, 401 insertions(+), 159 deletions(-) diff --git a/drivers/staging/mrst/drv/otm_hdmi/os/android/android_hdmi.c b/drivers/staging/mrst/drv/otm_hdmi/os/android/android_hdmi.c index 1397899..9057958 100644 --- a/drivers/staging/mrst/drv/otm_hdmi/os/android/android_hdmi.c +++ b/drivers/staging/mrst/drv/otm_hdmi/os/android/android_hdmi.c @@ -107,14 +107,6 @@ static const struct { }; /* Function declarations for interrupt routines */ -/* - * android_hdmi_irq_callback: - * Description:IRQ interrupt bottomhalf handler callback. This callback - * will be called for hdmi plug/unplug interrupts. - * Parameters : irq: IRQ number - * data: hdmi_priv data - * Return : IRQ_HANDLED - */ static irqreturn_t android_hdmi_irq_callback(int irq, void *data); static irqreturn_t __hdmi_irq_handler_bottomhalf(void *data); @@ -183,6 +175,16 @@ static unsigned char default_edid[] = { *in HPD (1) or not (0)*/ static int edid_ready_in_hpd = 0; +/** + * This function handles bottom half of HDMI hotplug interrupts + * @data : android hdmi private structure + * + * Returns the behavior of the interrupt handler + * IRQ_HANDLED - if interrupt handled + * This function handles bottom half of HDMI hotplug interrupts. + * IRQ interrupt bottomhalf handler callback. This callback + * will be called for hdmi plug/unplug interrupts + */ static irqreturn_t __hdmi_irq_handler_bottomhalf(void *data) { struct android_hdmi_priv *hdmi_priv = data; @@ -322,6 +324,17 @@ static int hdmi_ddc_read_write(bool read, #define android_hdmi_enc_helper_funcs mdfld_hdmi_helper_funcs #define android_hdmi_enc_funcs psb_intel_lvds_enc_funcs +/** + * This function initializes the hdmi driver called during bootup + * @dev : handle to drm_device + * @mode_dev : device mode + * + * Returns nothing + * + * This function initializes the hdmi driver called during bootup + * which includes initializing drm_connector, drm_encoder, hdmi audio + * and msic and collects all information reqd in hdmi private. + */ void android_hdmi_driver_init(struct drm_device *dev, void *mode_dev) { @@ -385,7 +398,19 @@ void android_hdmi_driver_init(struct drm_device *dev, pr_debug("%s X", __func__); } - +/** + * This function setups the interrupt handler for hotplug + * @dev : handle to drm_device + * + * Returns nothing + * + * This function enables the interrupt handler to handle + * incoming Hot plug events and prints an error message + * incase of failure to initialize the hotplug interrupt + * request. + * The hotplug interrupt should be enabled after the + * psb_fbdev_init (after all drm_ object is ready) + */ void android_hdmi_enable_hotplug(struct drm_device *dev) { struct drm_psb_private *dev_priv = dev->dev_private; @@ -400,13 +425,14 @@ void android_hdmi_enable_hotplug(struct drm_device *dev) } } -/* - * android_hdmi_irq_callback: - * Description: IRQ interrupt bottomhalf handler callback. This callback - * will be called for hdmi plug/unplug interrupts. - * Parameters : irq: IRQ number - * data: hdmi_priv data - * Return : IRQ_HANDLED +/** + * IRQ interrupt bottomhalf handler callback. + * @irq : IRQ number + * @data : hdmi_priv data + * + * Returns IRQ_HANDLED when the interrupt has been handled. + * IRQ interrupt bottomhalf handler callback. + * This callback will be called for hdmi plug/unplug interrupts. */ static irqreturn_t android_hdmi_irq_callback(int irq, void *data) { @@ -415,6 +441,15 @@ static irqreturn_t android_hdmi_irq_callback(int irq, void *data) return __hdmi_irq_handler_bottomhalf(data); } +/** + * This function sets the hdmi driver during bootup + * @dev : handle to drm_device + * + * Returns nothing + * + * This function is called from psb driver to setup the + * hdmi driver. Called only once during boot-up of the system + */ void android_hdmi_driver_setup(struct drm_device *dev) { struct drm_psb_private *dev_priv = dev->dev_private; @@ -514,6 +549,16 @@ typedef struct { static otm_cmdline_mode cmdline_mode = { 0, 0, 0, 0, 0, 0, 0 }; +/** + * This function is used by external tools to force modes + * @cmdoption : cmd line option parameter + * + * Returns -1 on error 0 on success -2 on invalid output + * This function gets the input parameters mentioned and sets the + * driver to the mentioned mode. These utility functions are + * for validating the various modes and useful for compliance + * testing as well as easy debug + */ int otm_cmdline_parse_option(char *cmdoption) { int ret = 0; @@ -560,6 +605,16 @@ int otm_cmdline_parse_option(char *cmdoption) } EXPORT_SYMBOL_GPL(otm_cmdline_parse_option); +/** + * This function is used by external tools to force the vic# + * @vic : vic number + * + * Returns 0 on success and -1 on invalid input vic + * This function gets the input parameters mentioned and sets the + * driver to the mentioned vic number. These utility functions are + * for validating the various modes and useful for compliance + * testing as well as easy debug + */ int otm_cmdline_set_vic_option(int vic) { int i = 0; @@ -586,6 +641,13 @@ int otm_cmdline_set_vic_option(int vic) } EXPORT_SYMBOL_GPL(otm_cmdline_set_vic_option); +/** + * This function is used by tools to print the cmdline options + * + * Returns nothing + * This function is used by external tools to print + * the cmdline options passed through tools + */ void otm_print_cmdline_option(void) { if (1 == cmdline_mode.specified) { @@ -608,8 +670,20 @@ void otm_print_cmdline_option(void) } EXPORT_SYMBOL_GPL(otm_print_cmdline_option); -/* +/** * DRM connector helper routine. + * @connector : drm_connector handle + * @mode : drm_display_mode handle + * + * Returns integer values which tell whether the hdmi mode + * is valid or not + * MODE_CLOCK_LOW - mode clock less than min pixel clock value + * MODE_CLOCK_HIGH - mode clock greater than min pixel clock value + * MODE_BAD - mode values are incorrect + * MODE_OK - mode values are correct + * MODE_NO_DBLESCAN - double scan mode not supported + * MODE_NO_INTERLACE - interlace mode not supported + * This is the DRM connector helper routine */ int android_hdmi_mode_valid(struct drm_connector *connector, struct drm_display_mode *mode) @@ -663,6 +737,15 @@ int android_hdmi_mode_valid(struct drm_connector *connector, return MODE_OK; } +/** + * This function maps the timings to drm_display_mode + * @timings : This holds the timings information + * @dev : drm_device handle + * + * Returns the mapped drm_display_mode + * This function maps the timings in EDID information + * to drm_display_mode and returns the same + */ static struct drm_display_mode *android_hdmi_get_drm_mode_from_pdt(const otm_hdmi_timing_t *timings, struct drm_device *dev) @@ -727,6 +810,13 @@ static struct drm_display_mode return mode; } +/** + * This function adds the cea modes in block 1 of EDID + * @connector : handle to drm_connector + * @edid : holds edid information + * + * Returns the number of modes added + */ static int android_hdmi_add_cea_edid_modes(struct drm_connector *connector, struct edid *edid) { @@ -784,6 +874,18 @@ exit: return false; } +/** + * This function adds the edid information from cmdline + * @context : handle hdmi_context + * @connector : handle drm_connector + * @hdisplay : width + * @vdisplay : height + * @vrefresh : refresh rate + * + * Returns true if mode added, false if not added + * This function is used to set the user requested mode + * into the mode list + */ static bool android_hdmi_add_noedid_mode( void *context, struct drm_connector *connector, @@ -812,7 +914,12 @@ exit: } #endif -/* Calculate refresh rate from mode */ +/** + * Calculate refresh rate from mode + * @mode : handle to drm_display_mode + * + * Returns the calculated refresh rate + */ static int calculate_refresh_rate(struct drm_display_mode *mode) { int refresh_rate = 0; @@ -827,6 +934,18 @@ static int calculate_refresh_rate(struct drm_display_mode *mode) return refresh_rate; } +/** + * DRM get modes helper routine + * @connector : handle to drm_connector + * + * Returns the number of modes added + * This is a helper routines for DRM get modes. + * This function gets the edid information from the external sink + * device using i2c when connected and parses the edid information + * obtained and adds the modes to connector list + * If sink device is not connected, then static edid timings are + * used and those modes are added to the connector list + */ int android_hdmi_get_modes(struct drm_connector *connector) { struct drm_device *dev = connector->dev; @@ -986,9 +1105,8 @@ edid_is_ready: return ret - i; } -/* - * Description: helper function to print the display mode details. - * +/** + * helper function to print the display mode details. * @mode: drm display mode to print * * Returns: none. @@ -1017,10 +1135,8 @@ static int __f5994(int dotclock) return DIV_ROUND_UP(dotclock*1000, 1001); } -/* - * Description: helper function to convert drm_display_mode to - * otm_hdmi_timing. - * +/** + * helper function to convert drm_display_mode to otm_hdmi_timing. * @otm_mode: otm hdmi mode to be populated * @drm_mode: drm_display_mode * @@ -1092,13 +1208,14 @@ static void __android_hdmi_drm_mode_to_otm_timing(otm_hdmi_timing_t *otm_mode, #define OTM_HDMI_MDFLD_MIPI_NATIVE_VDISPLAY 800 #define OTM_HDMI_MDFLD_PFIT_WIDTH_LIMIT 1024 -/* - * Description: crtc mode set for hdmi pipe. - * - * @crtc: crtc - * @mode: mode requested - * @adjusted_mode: adjusted mode - * @x, y, old_fb: old frame buffer values used for flushing old plane. +/** + * crtc mode set for hdmi pipe. + * @crtc : crtc + * @mode :mode requested + * @adjusted_mode:adjusted mode + * @x :x value + * @y :y value + * @old_fb : old frame buffer values for flushing old planes * * Returns: 0 on success * -EINVAL on NULL input arguments @@ -1254,9 +1371,8 @@ int android_hdmi_crtc_mode_set(struct drm_crtc *crtc, return 0; } -/* - * Description: encoder mode set for hdmi pipe. - * +/** + * encoder mode set for hdmi pipe. * @encoder: hdmi encoder * @mode: mode requested * @adjusted_mode: adjusted mode @@ -1328,9 +1444,8 @@ void android_hdmi_enc_mode_set(struct drm_encoder *encoder, return; } -/* - * Description: save the register for HDMI display - * +/** + * save the register for HDMI display * @dev: drm device * * Returns: none. @@ -1356,9 +1471,8 @@ void android_hdmi_save_display_registers(struct drm_device *dev) return; } -/* - * Description: restore the register and enable the HDMI display - * +/** + * Restore the register and enable the HDMI display * @dev: drm device * * Returns: none. @@ -1383,9 +1497,8 @@ void android_hdmi_restore_and_enable_display(struct drm_device *dev) (data & HPD_SIGNAL_STATUS)); } -/* - * Description: disable HDMI display - * +/** + * disable HDMI display * @dev: drm device * * Returns: none. @@ -1406,10 +1519,8 @@ void android_disable_hdmi(struct drm_device *dev) return; } -/* - * Description: hdmi helper function to detect whether hdmi/dvi - * is connected or not. - * +/** + * hdmi helper function to detect whether hdmi/dvi is connected or not. * @connector: hdmi connector * * Returns: connector_status_connected if hdmi/dvi is connected. @@ -1475,9 +1586,8 @@ enum drm_connector_status android_hdmi_detect(struct drm_connector *connector) } } -/* - * Description: hdmi helper function to manage power to the display (dpms) - * +/** + * hdmi helper function to manage power to the display (dpms) * @encoder: hdmi encoder * @mode: dpms on or off * @@ -1502,7 +1612,7 @@ void android_hdmi_dpms(struct drm_encoder *encoder, int mode) #endif } -/** +/* * * Internal scripts wrapper functions. * @@ -1519,11 +1629,10 @@ void android_hdmi_dpms(struct drm_encoder *encoder, int mode) #ifdef OTM_HDMI_UNIT_TEST /** - * test_otm_hdmi_report_edid_full() - Report current EDID information - * - * This routine simply dumps the EDID information + * test_otm_hdmi_report_edid_full() - Report current EDID information * - * Returns - nothing + * This routine simply dumps the EDID information + * Returns - nothing */ void test_otm_hdmi_report_edid_full(void) { diff --git a/drivers/staging/mrst/drv/otm_hdmi/pil/common/otm_hdmi.c b/drivers/staging/mrst/drv/otm_hdmi/pil/common/otm_hdmi.c index 6582579..1ecfd2e 100644 --- a/drivers/staging/mrst/drv/otm_hdmi/pil/common/otm_hdmi.c +++ b/drivers/staging/mrst/drv/otm_hdmi/pil/common/otm_hdmi.c @@ -86,7 +86,7 @@ /* TODO: Leave it here or move to some .h? */ #define OTM_HDMI_NAME "OTM HDMI" -/** +/* * Table of attributes */ otm_hdmi_attribute_t otm_hdmi_attributes_table @@ -159,6 +159,14 @@ static otm_hdmi_ret_t __program_clocks(hdmi_context_t *ctx, unsigned int dclk) return rc; } +/** + * This function called by edid_print tool internally + * @ctx : hdmi context handle + * @edid : edid information + * + * Returns nothing. Called by edid_print tool to print + * edid information to dmesg for debugging purposes + */ static void __hdmi_report_edid(hdmi_context_t *ctx, edid_info_t *edid) { int i = 0; @@ -219,6 +227,16 @@ static void __hdmi_report_edid(hdmi_context_t *ctx, edid_info_t *edid) LOG_PRINT(LOG_LEVEL_HIGH, "----------------------\n"); } +/** + * This function overrides the edid information with static timings + * @ctx : hdmi context handle + * @edid : edid information + * @safe : boolean for edid option + * + * Returns OTM_HDMI_SUCCESS or OTM_HDMI_ERR_INTERNAL + * + * This function overrides the edid information with static timings + */ static otm_hdmi_ret_t __hdmi_edid_override(hdmi_context_t *ctx, edid_info_t *edid, bool safe) @@ -291,13 +309,13 @@ exit: } /** - * otm_hdmi_edid_parse() - fill capability table - * @ctx: hdmi context - * @use_edid: True or False + * otm_hdmi_edid_parse() - fill capability table + * @context: hdmi context + * @use_edid: True or False * - * This routine files capability table. + * Returns - check otm_hdmi_ret_t * - * Returns - check otm_hdmi_ret_t + * This routine files capability table. */ otm_hdmi_ret_t otm_hdmi_edid_parse(void *context, otm_hdmi_use_edid_t use_edid) { @@ -410,11 +428,11 @@ exit: } /** - * otm_hdmi_timing_from_cea_modes() - get timings for cea modes - * @buffer: the extension block buffer - * @timings: the result CEA timings extacted from the buffer + * otm_hdmi_timing_from_cea_modes() - get timings for cea modes + * @buffer: the extension block buffer + * @timings: the result CEA timings extacted from the buffer * - * Returns - the number of modes in the timings + * Returns - the number of modes in the timings */ int otm_hdmi_timing_from_cea_modes(unsigned char *buffer, otm_hdmi_timing_t *timings) @@ -440,9 +458,9 @@ int otm_hdmi_timing_from_cea_modes(unsigned char *buffer, return edid_parse_pd_timing_from_cea_block(edid, buffer, timings); } -/* +/** * otm_hdmi_get_mode_timings() - get timings of a mode, given: - * @ctx : HDMI context + * @context : HDMI context * @hdisplay: mode width * @vdisplay: mode height * @vrefresh: mode refresh rate @@ -473,7 +491,14 @@ exit: return NULL; } -/* This routine fills given table with timings according to current unit version +/** + * This function fills the given table with timings + * @unit_id : hdmi unit revision id + * @table : handle to table to be filled + * @max_size : max number of entries in the table + * @reference : is this table reference table? + * + * This routine fills given table with timings according to current unit version * and subsequent use of table */ static int __init_tx_modes(hdmi_unit_revision_id_t unit_id, @@ -550,13 +575,13 @@ exit: } /** - * otm_hdmi_phy_enable() - PHY power programming wrapper - * @ctx: hdmi context - * @status: status + * otm_hdmi_phy_enable() - PHY power programming wrapper + * @context: hdmi context + * @status: status * - * This routine is PHY power programming wrapper + * Returns - check otm_hdmi_ret_t * - * Returns - check otm_hdmi_ret_t + * This routine is PHY power programming wrapper */ #ifdef OTM_HDMI_FIXME static otm_hdmi_ret_t __hdmi_phy_enable(void *context, bool status) @@ -607,7 +632,14 @@ exit: return rc; } -/* Enable hdmi HW device */ +/** + * __hdmi_enable - enable HDMI HW device + * @ctx: hdmi context + * + * Returns - check otm_hdmi_ret_t + * + * Enable hdmi HW device + */ static otm_hdmi_ret_t __hdmi_enable(hdmi_context_t *ctx) { otm_hdmi_ret_t rc = OTM_HDMI_SUCCESS; @@ -675,6 +707,14 @@ static bool __poll_timeout(void *poll_timer) I2C_SW_TIMEOUT; } +/** + * This function initializes hdmi_context + * @context : opaque hdmi_context + * @pdev : pci_device + * + * Returns check otm_hdmi_ret_t + * Initializes hdmi_context + */ static otm_hdmi_ret_t __hdmi_context_init(void *context, struct pci_dev *pdev) { otm_hdmi_ret_t rc = OTM_HDMI_SUCCESS; @@ -742,6 +782,13 @@ exit: return rc; } +/** + * otm_hdmi_deinit - deinit called during shutdown + * @context :opaque hdmi_context + * + * Returns nothing. de-initializes and frees pointers + * Called during power down + */ void otm_hdmi_deinit(void *context) { otm_hdmi_ret_t rc = OTM_HDMI_SUCCESS; @@ -832,7 +879,15 @@ bool otm_hdmi_power_rails_on(void) return ipil_hdmi_power_rails_on(); } -/* get pixel clock range */ +/** + * get pixel clock range + * @pc_min : min pixel clock + * @pc_max : max pixel clock + * + * Returns check otm_hdmi_ret_t + * This functions returns the minimum and maximum + * pixel clock values + */ otm_hdmi_ret_t otm_hdmi_get_pixel_clock_range(unsigned int *pc_min, unsigned int *pc_max) { @@ -844,17 +899,16 @@ otm_hdmi_ret_t otm_hdmi_get_pixel_clock_range(unsigned int *pc_min, return OTM_HDMI_SUCCESS; } -/* - * Description: hdmi interrupt handler (upper half). - * handles the interrupts by reading hdmi status register - * and waking up bottom half if needed. - * +/** + * hdmi interrupt handler (upper half). * @irq: irq number * @data: data for the interrupt handler * * Returns: IRQ_HANDLED on NULL input arguments, and if the * interrupt is not HDMI HPD interrupts. * IRQ_WAKE_THREAD if this is a HDMI HPD interrupt. + * hdmi interrupt handler (upper half). handles the interrupts + * by reading hdmi status register and waking up bottom half if needed. */ static irqreturn_t __hdmi_irq_handler(int irq, void *data) { @@ -865,15 +919,15 @@ static irqreturn_t __hdmi_irq_handler(int irq, void *data) } /** - * otm_hdmi_setup_irq - install HPD IRQ call back - * @context: hdmi device context - * @pdev: pci device - * @phdmi_irq_cb: function pointer for hotplug/unplug IRQ callbacks. - * data: data for irq callback + * otm_hdmi_setup_irq - install HPD IRQ call back + * @context: hdmi device context + * @pdev: pci device + * @phdmi_irq_cb: function pointer for hotplug/unplug IRQ callbacks. + * @data: data for irq callback * - * Perform HPD IRQ call back initialization + * Perform HPD IRQ call back initialization * - * Returns - check otm_hdmi_ret_t + * Returns - check otm_hdmi_ret_t */ otm_hdmi_ret_t otm_hdmi_setup_irq(void *context, struct pci_dev *pdev, irqreturn_t (*phdmi_irq_cb) (int, void*), @@ -910,16 +964,16 @@ exit: } /** - * otm_hdmi_device_init - init hdmi device driver - * @context: hdmi device context - * @pdev: pci device + * otm_hdmi_device_init - init hdmi device driver + * @context: hdmi device context + * @pdev: pci device * - * Perform HDMI device initialization which includes 3 steps: - * 1) otm context create, - * 2) os specific context init, - * 3) device enable + * Perform HDMI device initialization which includes 3 steps: + * 1) otm context create, + * 2) os specific context init, + * 3) device enable * - * Returns - check otm_hdmi_ret_t + * Returns - check otm_hdmi_ret_t */ otm_hdmi_ret_t otm_hdmi_device_init(void **context, struct pci_dev *pdev) { @@ -1026,6 +1080,14 @@ exit: return rc; } +/** + * Returns if the given values is preferred mode or not + * @hdisplay : width + * @vdisplay : height + * @refresh : refresh rate + * + * Returns true if preferred mode else false + */ bool otm_hdmi_is_preferred_mode(int hdisplay, int vdisplay, int refresh) { if (hdisplay == IPIL_PREFERRED_HDISPLAY && @@ -1036,6 +1098,14 @@ bool otm_hdmi_is_preferred_mode(int hdisplay, int vdisplay, int refresh) return false; } +/** + * Set raw edid to the hdmi context + * @context : opaque hdmi_context + * @raw_edid : raw edid information + * + * Returns - check otm_hdmi_ret_t + * Copy raw edid to the hdmi context + */ otm_hdmi_ret_t otm_hdmi_set_raw_edid(void *context, char *raw_edid) { hdmi_context_t *ctx = (hdmi_context_t *)context; @@ -1049,6 +1119,14 @@ otm_hdmi_ret_t otm_hdmi_set_raw_edid(void *context, char *raw_edid) return OTM_HDMI_SUCCESS; } +/** + * Get raw edid to the hdmi context + * @context : opaque hdmi_context + * @raw_edid : raw edid information + * + * Returns - check otm_hdmi_ret_t + * Retrieves raw edid in the hdmi context + */ otm_hdmi_ret_t otm_hdmi_get_raw_edid(void *context, char **raw_edid) { hdmi_context_t *ctx = (hdmi_context_t *)context; @@ -1061,6 +1139,13 @@ otm_hdmi_ret_t otm_hdmi_get_raw_edid(void *context, char **raw_edid) return OTM_HDMI_SUCCESS; } +/** + * Check if monitor connected is hdmi + * @context : opaque hdmi_context + * + * Returns true if hdmi else false + * Check if monitor connected is hdmi + */ bool otm_hdmi_is_monitor_hdmi(void *context) { hdmi_context_t *ctx = (hdmi_context_t *)context; @@ -1071,7 +1156,13 @@ bool otm_hdmi_is_monitor_hdmi(void *context) return ctx->edid_int.hdmi; } -/* +/** + * HDMI video mute handling + * @ctx : hdmi_context + * @type : mute + * @source : mute source + * + * Returns true if hdmi else false * HDMI video mute handling */ static void hdmi_mute(hdmi_context_t *ctx, @@ -1103,8 +1194,13 @@ static void hdmi_mute(hdmi_context_t *ctx, mutex_unlock(&ctx->mute_sema); } -/* - * __check_opd_support() +/** + * Checks the output pixel depth + * @depth : pixel depth + * @depth_30 : ycbcr422 boolean + * @depth_36 : ycbcr444 boolean + * + * Returns check otm_hdmi_ret_t. Checks the output pixel depth */ static otm_hdmi_ret_t __check_opd_support(otm_hdmi_output_pixel_depth_t depth, bool depth_30, @@ -1130,8 +1226,12 @@ static otm_hdmi_ret_t __check_opd_support(otm_hdmi_output_pixel_depth_t depth, return rc; } -/* - * __check_pixel_depth_cfg() +/** + * Checks the pixel depth configuration + * @opf : output pixel format + * @opd : output pixel depth + * + * Returns check otm_hdmi_ret_t. Checks the pixel depth config */ static otm_hdmi_ret_t __check_pixel_depth_cfg( otm_hdmi_output_pixel_format_t opf, @@ -1142,8 +1242,13 @@ static otm_hdmi_ret_t __check_pixel_depth_cfg( return rc ? OTM_HDMI_SUCCESS : OTM_HDMI_ERR_INTERNAL; } -/* - * __check_opf_support() +/** + * Checks the output pixel format + * @format : output pixel format + * @yuv444 : is pixel format yuv444 + * @yuv422 : is pixel format yuv422 + * + * Returns check otm_hdmi_ret_t. Checks the output pixel format */ static otm_hdmi_ret_t __check_opf_support(otm_hdmi_output_pixel_format_t format, bool yuv444, @@ -1171,8 +1276,12 @@ static otm_hdmi_ret_t __check_opf_support(otm_hdmi_output_pixel_format_t format, return rc; } -/* - * __set_attr_csc() +/** + * set color space conversion + * @ctx : hdmi_context + * + * Returns check otm_hdmi_ret_t. Sets the color space + * conversion attribute */ static otm_hdmi_ret_t __set_attr_csc(hdmi_context_t *ctx) { @@ -1198,15 +1307,17 @@ exit: } /** - * otm_hdmi_attr_set_validate - validates the attribute to - * be written or not. + * validates the attribute to be written or not. + * @id : attribute id + * @value : value to be set to the attribute * - * Write's the attributes value. + * Write's the attributes value. + * validates the attribute to be written or not. * - * Returns - - * OTM_HDMI_SUCCESS - if the attribute value is writable. - * OTM_HDMI_ERR_INTERNAL - if the attribute value is non-writable. - * OTM_HDMI_ERR_FAILED - if the attribute is not in range. + * Returns - + * OTM_HDMI_SUCCESS - if the attribute value is writable. + * OTM_HDMI_ERR_INTERNAL - if the attribute value is non-writable. + * OTM_HDMI_ERR_FAILED - if the attribute is not in range. */ static otm_hdmi_ret_t otm_hdmi_attr_set_validate(otm_hdmi_attribute_id_t id, void *value) @@ -1277,7 +1388,8 @@ exit: * @param [in] id : attribute id * @param [in] data : user provided buffer with attribute value * @param [in] internal : internal [driver] or external [app] call - + * + * Setting given attribute * Note: Some attributes settings can not be applied until mode change was done. * Hence such attributes are set logically and the actual HW will be set during * mode change. @@ -1630,15 +1742,15 @@ exit: EXPORT_SYMBOL(otm_hdmi_set_attribute); /** - * otm_hdmi_attr_get_validate - validates the attribute - * to be read or not. + * validates the attribute to be read or not. + * @id : attribute id to be validated * - * Read's the attributes flag value. + * Read's the attributes flag value. * - * Returns - - * OTM_HDMI_SUCCESS - if the attribute is readable. - * OTM_HDMI_ERR_INTERNAL - if the attribute is non-readable. - * OTM_HDMI_ERR_FAILED - if the attribute is not in range. + * Returns - + * OTM_HDMI_SUCCESS - if the attribute is readable. + * OTM_HDMI_ERR_INTERNAL - if the attribute is non-readable. + * OTM_HDMI_ERR_FAILED - if the attribute is not in range. */ static otm_hdmi_ret_t otm_hdmi_attr_get_validate(otm_hdmi_attribute_id_t id) { @@ -1671,11 +1783,14 @@ exit: return rc; } -/* - * Getting given attribute - * @param [in ] id : attribute id - * @param [out] data : user provided buffer for attribute details - * @param [in ] log : a hint wether port driver should log the call +/** + * Getting given attribute + * @context :opaque hdmi context + * @id : attribute id + * @attribute :user provided buffer for attribute details + * @log : a hint wether port driver should log the call + * + * Returns otm_hdmi_ret_t check. Getting given attribute values */ otm_hdmi_ret_t otm_hdmi_get_attribute(void *context, otm_hdmi_attribute_id_t id, @@ -1702,7 +1817,10 @@ exit: EXPORT_SYMBOL(otm_hdmi_get_attribute); /** - * Attribute name getting routine + * Attribute name getting routine + * @id : attribute id + * + * Returns attribute name corresponding to id */ char *__pd_attr_get_name(otm_hdmi_attribute_id_t id) { @@ -1716,7 +1834,17 @@ char *__pd_attr_get_name(otm_hdmi_attribute_id_t id) EXPORT_SYMBOL(__pd_attr_get_name); /** - * Generic attribute declaration routine + * Generic attribute declaration routine + * @table : attribute table to be updated + * @id : id to be updated to the table + * @type : attribute type + * @flags : attribute flags + * @name : attribute name + * @value : attribute default value + * @min : min value possible for the attribute + * @max : max value possible for the attribute + * + * Returns check otm_hdmi_ret_t */ static otm_hdmi_ret_t __pd_attr_declare(otm_hdmi_attribute_t *table, otm_hdmi_attribute_id_t id, @@ -1767,9 +1895,11 @@ static otm_hdmi_ret_t __pd_attr_declare(otm_hdmi_attribute_t *table, } /** - * otm_hdmi_declare_attributes - init hdmi global attributes table + * otm_hdmi_declare_attributes - init hdmi global attributes table + * @declare : declare attribute + * @get_name : name of the attribute * - * Returns - check otm_hdmi_ret_t + * Returns - check otm_hdmi_ret_t */ otm_hdmi_ret_t otm_hdmi_declare_attributes(pd_attr_declare_t declare, pd_attr_get_name_t get_name) @@ -1965,13 +2095,14 @@ otm_hdmi_ret_t otm_hdmi_declare_attributes(pd_attr_declare_t declare, } EXPORT_SYMBOL(otm_hdmi_declare_attributes); -/* +/** * Description: crtc mode set function for hdmi. * - * @context: hdmi_context - * @mode: mode requested - * @adjusted_mode: adjusted mode - * @fb_width, fb_height:allocated frame buffer dimensions + * @context :hdmi_context + * @mode :mode requested + * @adjusted_mode :adjusted mode + * @fb_width :allocated frame buffer dimensions + * @fb_height :allocated frame buffer dimensions * @pclk_khz: tmds clk value for the best pll and is needed for audio. * This field has to be moved into OTM audio * interfaces when implemented @@ -2055,16 +2186,16 @@ otm_hdmi_ret_t otm_hdmi_crtc_mode_set(void *context, otm_hdmi_timing_t *mode, return rc; } -/* - * Description: encoder mode set function for hdmi. enables phy. - * set correct polarity for the current mode. - * +/** + * encoder mode set function for hdmi * @context: hdmi_context * @mode: mode requested * @adjusted_mode: adjusted mode * * Returns: OTM_HDMI_SUCCESS on success * OTM_HDMI_ERR_INVAL on NULL input arguments + * encoder mode set function for hdmi. enables phy. + * set correct polarity for the current mode. */ otm_hdmi_ret_t otm_hdmi_enc_mode_set(void *context, otm_hdmi_timing_t *mode, otm_hdmi_timing_t *adjusted_mode) @@ -2104,12 +2235,13 @@ otm_hdmi_ret_t otm_hdmi_enc_mode_set(void *context, otm_hdmi_timing_t *mode, return rc; } -/* - * Description: restore HDMI registers and enable the display - * - * @context: hdmi_context +/** + * Restore HDMI registers and enable the display + * @context :hdmi_context + * @connected :hdmi connected or not * * Returns: none + * Restore HDMI registers and enable the display */ void otm_hdmi_restore_and_enable_display(void *context, bool connected) { @@ -2135,12 +2267,13 @@ void otm_hdmi_restore_and_enable_display(void *context, bool connected) } } -/* - * Description: save HDMI display registers - * - * @context: hdmi_context +/** + * save HDMI display registers + * @context :hdmi_context + * @connected :hdmi connected or not * * Returns: none + * save HDMI display registers */ void otm_hdmi_save_display_registers(void *context, bool connected) { @@ -2160,12 +2293,12 @@ void otm_hdmi_save_display_registers(void *context, bool connected) } } -/* - * Description: disable HDMI display - * +/** + * disable HDMI display * @context: hdmi_context * * Returns: none + * disable HDMI display */ void otm_disable_hdmi(void *context) { @@ -2181,7 +2314,7 @@ void otm_disable_hdmi(void *context) } } -/** +/* * * Internal scripts wrapper functions. * @@ -2194,11 +2327,11 @@ void otm_disable_hdmi(void *context) #ifdef OTM_HDMI_UNIT_TEST /** - * test_otm_hdmi_report_edid() - Report current EDID information + * test_otm_hdmi_report_edid() - Report current EDID information * - * This routine simply dumps the EDID information + * This routine simply dumps the EDID information * - * Returns - nothing + * Returns - nothing */ void test_otm_hdmi_report_edid(void) { @@ -2222,14 +2355,14 @@ EXPORT_SYMBOL_GPL(test_otm_hdmi_report_edid); #ifdef OTM_HDMI_UNIT_TEST /** - * get_hdmi_context() - Getting hdmi_context + * get_hdmi_context() - Getting hdmi_context * - * This routine gives a handle to hdmi_context - * to be used with other function calls like - * set_attribute which requires hdmi_context - * as one of the params + * This routine gives a handle to hdmi_context + * to be used with other function calls like + * set_attribute which requires hdmi_context + * as one of the params * - * Returns - hdmi_context + * Returns - hdmi_context */ void *otm_hdmi_get_context(void) { -- 2.7.4