drm/amd/display: Improve spelling, grammar, and formatting of amdgpu_dm.c comments

static int amdgpu_dm_init(struct amdgpu_device *adev);

static void amdgpu_dm_fini(struct amdgpu_device *adev);

/* initializes drm_device display related structures, based on the information

/*

 * initializes drm_device display related structures, based on the information

 * provided by DAL. The drm strcutures are: drm_crtc, drm_connector,

 * drm_encoder, drm_mode_config

 *

	struct drm_crtc *crtc;

	struct amdgpu_crtc *amdgpu_crtc;

	/*

	 * following if is check inherited from both functions where this one is

	 * used now. Need to be checked why it could happen.

	 */

	if (otg_inst == -1) {

		WARN_ON(1);

		return adev->mode_info.crtcs[0];

	}

	/* wakeup usersapce */

	/* wake up userspace */

	if (amdgpu_crtc->event) {

		/* Update to correct count/ts if racing with vblank irq */

		/* Update to correct count(s) if racing with vblank irq */

		drm_crtc_accurate_vblank_count(&amdgpu_crtc->base);

		drm_crtc_send_vblank_event(&amdgpu_crtc->base, amdgpu_crtc->event);

}

/* Init display KMS

/*

 * Init display KMS

 *

 * Returns 0 on success

 */

		mutex_unlock(&aconnector->hpd_lock);

	}

	/* Force mode set in atomic comit */

	/* Force mode set in atomic commit */

	for_each_new_crtc_in_state(dm->cached_state, crtc, new_crtc_state, i)

		new_crtc_state->active_changed = true;

	sink = aconnector->dc_link->local_sink;

	/* Edid mgmt connector gets first update only in mode_valid hook and then

	/*

	 * Edid mgmt connector gets first update only in mode_valid hook and then

	 * the connector sink is set to either fake or physical sink depends on link status.

	 * don't do it here if u are during boot

	 * Skip if already done during boot.

	 */

	if (aconnector->base.force != DRM_FORCE_UNSPECIFIED

			&& aconnector->dc_em_sink) {

		/* For S3 resume with headless use eml_sink to fake stream

		 * because on resume connecotr->sink is set ti NULL

		/*

		 * For S3 resume with headless use eml_sink to fake stream

		 * because on resume connector->sink is set to NULL

		 */

		mutex_lock(&dev->mode_config.mutex);

		if (sink) {

			if (aconnector->dc_sink) {

				amdgpu_dm_update_freesync_caps(connector, NULL);

				/* retain and release bellow are used for

				 * bump up refcount for sink because the link don't point

				 * to it anymore after disconnect so on next crtc to connector

				/*

				 * retain and release below are used to

				 * bump up refcount for sink because the link doesn't point

				 * to it anymore after disconnect, so on next crtc to connector

				 * reshuffle by UMD we will get into unwanted dc_sink release

				 */

				if (aconnector->dc_sink != aconnector->dc_em_sink)

		return;

	if (aconnector->dc_sink == sink) {

		/* We got a DP short pulse (Link Loss, DP CTS, etc...).

		 * Do nothing!! */

		/*

		 * We got a DP short pulse (Link Loss, DP CTS, etc...).

		 * Do nothing!!

		 */

		DRM_DEBUG_DRIVER("DCHPD: connector_id=%d: dc_sink didn't change.\n",

				aconnector->connector_id);

		return;

	mutex_lock(&dev->mode_config.mutex);

	/* 1. Update status of the drm connector

	 * 2. Send an event and let userspace tell us what to do */

	/*

	 * 1. Update status of the drm connector

	 * 2. Send an event and let userspace tell us what to do

	 */

	if (sink) {

		/* TODO: check if we still need the S3 mode update workaround.

		 * If yes, put it here. */

		/*

		 * TODO: check if we still need the S3 mode update workaround.

		 * If yes, put it here.

		 */

		if (aconnector->dc_sink)

			amdgpu_dm_update_freesync_caps(connector, NULL);

	struct drm_connector *connector = &aconnector->base;

	struct drm_device *dev = connector->dev;

	/* In case of failure or MST no need to update connector status or notify the OS

	 * since (for MST case) MST does this in it's own context.

	/*

	 * In case of failure or MST no need to update connector status or notify the OS

	 * since (for MST case) MST does this in its own context.

	 */

	mutex_lock(&aconnector->hpd_lock);

					break;

			}

			/* check if there is new irq to be handle */

			/* check if there is new irq to be handled */

			dret = drm_dp_dpcd_read(

				&aconnector->dm_dp_aux.aux,

				dpcd_addr,

	struct dc_link *dc_link = aconnector->dc_link;

	bool is_mst_root_connector = aconnector->mst_mgr.mst_state;

	/* TODO:Temporary add mutex to protect hpd interrupt not have a gpio

	/*

	 * TODO:Temporary add mutex to protect hpd interrupt not have a gpio

	 * conflict, after implement i2c helper, this mutex should be

	 * retired.

	 */

	int_params.requested_polarity = INTERRUPT_POLARITY_DEFAULT;

	int_params.current_polarity = INTERRUPT_POLARITY_DEFAULT;

	/* Actions of amdgpu_irq_add_id():

	/*

	 * Actions of amdgpu_irq_add_id():

	 * 1. Register a set() function with base driver.

	 *    Base driver will call set() function to enable/disable an

	 *    interrupt in DC hardware.

	int_params.requested_polarity = INTERRUPT_POLARITY_DEFAULT;

	int_params.current_polarity = INTERRUPT_POLARITY_DEFAULT;

	/* Actions of amdgpu_irq_add_id():

	/*

	 * Actions of amdgpu_irq_add_id():

	 * 1. Register a set() function with base driver.

	 *    Base driver will call set() function to enable/disable an

	 *    interrupt in DC hardware.

	 *    coming from DC hardware.

	 *    amdgpu_dm_irq_handler() will re-direct the interrupt to DC

	 *    for acknowledging and handling.

	 * */

	 */

	/* Use VSTARTUP interrupt */

	for (i = DCN_1_0__SRCID__DC_D1_OTG_VSTARTUP;

	adev->ddev->mode_config.preferred_depth = 24;

	adev->ddev->mode_config.prefer_shadow = 1;

	/* indicate support of immediate flip */

	/* indicates support for immediate flip */

	adev->ddev->mode_config.async_page_flip = true;

	adev->ddev->mode_config.fb_base = adev->gmc.aper_base;

	plane->base.type = mode_info->plane_type[plane_id];

	/*

	 * HACK: IGT tests expect that each plane can only have one

	 * HACK: IGT tests expect that each plane can only have

	 * one possible CRTC. For now, set one CRTC for each

	 * plane that is not an underlay, but still allow multiple

	 * CRTCs for underlay planes.

	if ((link->connector_signal & (SIGNAL_TYPE_EDP | SIGNAL_TYPE_LVDS)) &&

	    link->type != dc_connection_none) {

		/* Event if registration failed, we should continue with

		/*

		 * Event if registration failed, we should continue with

		 * DM initialization because not having a backlight control

		 * is better then a black screen.

		 */

}

/* In this architecture, the association

/*

 * In this architecture, the association

 * connector -> encoder -> crtc

 * id not really requried. The crtc and connector will hold the

 * display_index as an abstraction to use with DAL component

 * amdgpu_display_funcs functions

 *****************************************************************************/

/**

/*

 * dm_bandwidth_update - program display watermarks

 *

 * @adev: amdgpu_device pointer

	if (adev->mode_info.funcs == NULL)

		adev->mode_info.funcs = &dm_display_funcs;

	/* Note: Do NOT change adev->audio_endpt_rreg and

	/*

	 * Note: Do NOT change adev->audio_endpt_rreg and

	 * adev->audio_endpt_wreg because they are initialised in

	 * amdgpu_device_init() */

	 * amdgpu_device_init()

	 */

#if defined(CONFIG_DEBUG_KERNEL_DC)

	device_create_file(

		adev->ddev->dev,

{

	plane_state->src_rect.x = state->src_x >> 16;

	plane_state->src_rect.y = state->src_y >> 16;

	/*we ignore for now mantissa and do not to deal with floating pixels :(*/

	/* we ignore the mantissa for now and do not deal with floating pixels :( */

	plane_state->src_rect.width = state->src_w >> 16;

	if (plane_state->src_rect.width == 0)

	int r = amdgpu_bo_reserve(rbo, false);

	if (unlikely(r)) {

		// Don't show error msg. when return -ERESTARTSYS

		/* Don't show error message when returning -ERESTARTSYS */

		if (r != -ERESTARTSYS)

			DRM_ERROR("Unable to reserve buffer: %d\n", r);

		return r;

	return ret;

}

/*****************************************************************************/

static void update_stream_scaling_settings(const struct drm_display_mode *mode,

					   const struct dm_connector_state *dm_state,

					   struct dc_stream_state *stream)

	switch (bpc) {

	case 0:

		/* Temporary Work around, DRM don't parse color depth for

		/*

		 * Temporary Work around, DRM doesn't parse color depth for

		 * EDID revision before 1.4

		 * TODO: Fix edid parsing

		 */

	} while (timing_out->display_color_depth > COLOR_DEPTH_888);

}

/*****************************************************************************/

static void

fill_stream_properties_from_drm_display_mode(struct dc_stream_state *stream,

	for (i = 0; i < context->stream_count ; i++) {

		if (!context->streams[i])

			continue;

		/* TODO: add a function to read AMD VSDB bits and will set

		/*

		 * TODO: add a function to read AMD VSDB bits and set

		 * crtc_sync_master.multi_sync_enabled flag

		 * For now its set to false

		 * For now it's set to false

		 */

		set_multisync_trigger_params(context->streams[i]);

	}

				head);

	if (preferred_mode == NULL) {

		/* This may not be an error, the use case is when we we have no

		/*

		 * This may not be an error, the use case is when we have no

		 * usermode calls to reset and set mode upon hotplug. In this

		 * case, we call set mode ourselves to restore the previous mode

		 * and the modelist may not be filled in in time.

	bool connected;

	struct amdgpu_dm_connector *aconnector = to_amdgpu_dm_connector(connector);

	/* Notes:

	/*

	 * Notes:

	 * 1. This interface is NOT called in context of HPD irq.

	 * 2. This interface *is called* in context of user-mode ioctl. Which

	 * makes it a bad place for *any* MST-related activit. */

	 * makes it a bad place for *any* MST-related activity.

	 */

	if (aconnector->base.force == DRM_FORCE_UNSPECIFIED &&

	    !aconnector->fake_enable)

{

	struct dc_link *link = (struct dc_link *)aconnector->dc_link;

	/* In case of headless boot with force on for DP managed connector

	/*

	 * In case of headless boot with force on for DP managed connector

	 * Those settings have to be != 0 to get initial modeset

	 */

	if (link->connector_signal == SIGNAL_TYPE_DISPLAY_PORT) {

			(mode->flags & DRM_MODE_FLAG_DBLSCAN))

		return result;

	/* Only run this the first time mode_valid is called to initilialize

	/*

	 * Only run this the first time mode_valid is called to initilialize

	 * EDID mgmt

	 */

	if (aconnector->base.force != DRM_FORCE_UNSPECIFIED &&

static const struct drm_connector_helper_funcs

amdgpu_dm_connector_helper_funcs = {

	/*

	 * If hotplug a second bigger display in FB Con mode, bigger resolution

	 * If hotplugging a second bigger display in FB Con mode, bigger resolution

	 * modes will be filtered by drm_mode_validate_size(), and those modes

	 * is missing after user start lightdm. So we need to renew modes list.

	 * are missing after user start lightdm. So we need to renew modes list.

	 * in get_modes call back, not just return the modes count

	 */

	.get_modes = get_modes,

 * TODO: these are currently initialized to rgb formats only.

 * For future use cases we should either initialize them dynamically based on

 * plane capabilities, or initialize this array to all formats, so internal drm

 * check will succeed, and let DC to implement proper check

 * check will succeed, and let DC implement proper check

 */

static const uint32_t rgb_formats[] = {

	DRM_FORMAT_RGB888,

	aconnector->hpd.hpd = AMDGPU_HPD_NONE; /* not used */

	mutex_init(&aconnector->hpd_lock);

	/* configure support HPD hot plug connector_>polled default value is 0

	/*

	 * configure support HPD hot plug connector_>polled default value is 0

	 * which means HPD hot plug not supported

	 */

	switch (connector_type) {

}

/* Note: this function assumes that dc_link_detect() was called for the

/*

 * Note: this function assumes that dc_link_detect() was called for the

 * dc_link which will be represented by this aconnector.

 */

static int amdgpu_dm_connector_init(struct amdgpu_display_manager *dm,

	target_vblank = target - (uint32_t)drm_crtc_vblank_count(crtc) +

			amdgpu_get_vblank_counter_kms(crtc->dev, acrtc->crtc_id);

	/* TODO This might fail and hence better not used, wait

	/*

	 * TODO This might fail and hence better not used, wait

	 * explicitly on fences instead

	 * and in general should be called for

	 * blocking commit to as per framework helpers

	amdgpu_bo_unreserve(abo);

	/* Wait until we're out of the vertical blank period before the one

	/*

	 * Wait until we're out of the vertical blank period before the one

	 * targeted by the flip

	 */

	while ((acrtc->enabled &&

	}

}

/**

/*

 * amdgpu_dm_crtc_copy_transient_flags - copy mirrored flags from DRM to DC

 * @crtc_state: the DRM CRTC state

 * @stream_state: the DC stream state.

		if (drm_atomic_crtc_needs_modeset(new_crtc_state) && dm_old_crtc_state->stream)

			manage_dm_interrupts(adev, acrtc, false);

	}

	/* Add check here for SoC's that support hardware cursor plane, to

	 * unset legacy_cursor_update */

	/*

	 * Add check here for SoC's that support hardware cursor plane, to

	 * unset legacy_cursor_update

	 */

	return drm_atomic_helper_commit(dev, state, nonblock);

				 * this could happen because of issues with

				 * userspace notifications delivery.

				 * In this case userspace tries to set mode on

				 * display which is disconnect in fact.

				 * dc_sink in NULL in this case on aconnector.

				 * display which is disconnected in fact.

				 * dc_sink is NULL in this case on aconnector.

				 * We expect reset mode will come soon.

				 *

				 * This can also happen when unplug is done

		if (!acrtc || drm_atomic_crtc_needs_modeset(new_crtc_state))

			continue;

		/* Skip any thing not scale or underscan changes */

		/* Skip anything that is not scaling or underscan changes */

		if (!is_scaling_state_different(dm_new_con_state, dm_old_con_state))

			continue;

	drm_atomic_helper_cleanup_planes(dev, state);

	/* Finally, drop a runtime PM reference for each newly disabled CRTC,

	/*

	 * Finally, drop a runtime PM reference for each newly disabled CRTC,

	 * so we can put the GPU into runtime suspend if we're not driving any

	 * displays anymore

	 */

}

/*

 * This functions handle all cases when set mode does not come upon hotplug.

 * This include when the same display is unplugged then plugged back into the

 * same port and when we are running without usermode desktop manager supprot

 * This function handles all cases when set mode does not come upon hotplug.

 * This includes when a display is unplugged then plugged back into the

 * same port and when running without usermode desktop manager supprot

 */

void dm_restore_drm_connector_state(struct drm_device *dev,

				    struct drm_connector *connector)

		dm_force_atomic_commit(&aconnector->base);

}

/*`

/*

 * Grabs all modesetting locks to serialize against any blocking commits,

 * Waits for completion of all non blocking commits.

 */

	struct drm_crtc_commit *commit;

	long ret;

	/* Adding all modeset locks to aquire_ctx will

	/*

	 * Adding all modeset locks to aquire_ctx will

	 * ensure that when the framework release it the

	 * extra locks we are locking here will get released to

	 */

		if (!commit)

			continue;

		/* Make sure all pending HW programming completed and

		/*

		 * Make sure all pending HW programming completed and

		 * page flips done

		 */

		ret = wait_for_completion_interruptible_timeout(&commit->hw_done, 10*HZ);

	struct dc_stream_state *new_stream;

	int ret = 0;

	/*TODO Move this code into dm_crtc_atomic_check once we get rid of dc_validation_set */

	/* update changed items */

	/*

	 * TODO Move this code into dm_crtc_atomic_check once we get rid of dc_validation_set

	 * update changed items

	 */

	for_each_oldnew_crtc_in_state(state, crtc, old_crtc_state, new_crtc_state, i) {

		struct amdgpu_crtc *acrtc = NULL;

		struct amdgpu_dm_connector *aconnector = NULL;

		/* TODO This hack should go away */

		if (aconnector && enable) {

			// Make sure fake sink is created in plug-in scenario

			/* Make sure fake sink is created in plug-in scenario */

			drm_new_conn_state = drm_atomic_get_new_connector_state(state,

 								    &aconnector->base);

			drm_old_conn_state = drm_atomic_get_old_connector_state(state,

			/*

			 * we can have no stream on ACTION_SET if a display

			 * was disconnected during S3, in this case it not and

			 * was disconnected during S3, in this case it is not an

			 * error, the OS will be updated after detection, and

			 * do the right thing on next atomic commit

			 * will do the right thing on next atomic commit

			 */

			if (!new_stream) {

	/*

	 * For full updates case when

	 * removing/adding/updating  streams on once CRTC while flipping

	 * removing/adding/updating streams on one CRTC while flipping

	 * on another CRTC,

	 * acquiring global lock  will guarantee that any such full

	 * update commit