Re: [PATCH 01/10] drm/radeon: document radeon_device.c (v2)

["Christian König" <deathsimple@vodafone.de>]

On 29.06.2012 18:50, alexdeucher@gmail.com wrote:
> From: Alex Deucher <alexander.deucher@amd.com>
>
> Adds documentation to most of the functions in
> radeon_device.c
>
> v2: split out general descriptions as per Christian's
> comments.
>
> Signed-off-by: Alex Deucher <alexander.deucher@amd.com>
For the whole series:

Reviewed-by: Christian König <christian.koenig@amd.com>


> ---
>   drivers/gpu/drm/radeon/radeon_device.c |  313 +++++++++++++++++++++++++++++++-
>   1 files changed, 310 insertions(+), 3 deletions(-)
>
> diff --git a/drivers/gpu/drm/radeon/radeon_device.c b/drivers/gpu/drm/radeon/radeon_device.c
> index f654ba8..926d7e8 100644
> --- a/drivers/gpu/drm/radeon/radeon_device.c
> +++ b/drivers/gpu/drm/radeon/radeon_device.c
> @@ -96,8 +96,12 @@ static const char radeon_family_name[][16] = {
>   	"LAST",
>   };
>   
> -/*
> - * Clear GPU surface registers.
> +/**
> + * radeon_surface_init - Clear GPU surface registers.
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Clear GPU surface registers (r1xx-r5xx).
>    */
>   void radeon_surface_init(struct radeon_device *rdev)
>   {
> @@ -119,6 +123,13 @@ void radeon_surface_init(struct radeon_device *rdev)
>   /*
>    * GPU scratch registers helpers function.
>    */
> +/**
> + * radeon_scratch_init - Init scratch register driver information.
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Init CP scratch register driver information (r1xx-r5xx)
> + */
>   void radeon_scratch_init(struct radeon_device *rdev)
>   {
>   	int i;
> @@ -136,6 +147,15 @@ void radeon_scratch_init(struct radeon_device *rdev)
>   	}
>   }
>   
> +/**
> + * radeon_scratch_get - Allocate a scratch register
> + *
> + * @rdev: radeon_device pointer
> + * @reg: scratch register mmio offset
> + *
> + * Allocate a CP scratch register for use by the driver (all asics).
> + * Returns 0 on success or -EINVAL on failure.
> + */
>   int radeon_scratch_get(struct radeon_device *rdev, uint32_t *reg)
>   {
>   	int i;
> @@ -150,6 +170,14 @@ int radeon_scratch_get(struct radeon_device *rdev, uint32_t *reg)
>   	return -EINVAL;
>   }
>   
> +/**
> + * radeon_scratch_free - Free a scratch register
> + *
> + * @rdev: radeon_device pointer
> + * @reg: scratch register mmio offset
> + *
> + * Free a CP scratch register allocated for use by the driver (all asics)
> + */
>   void radeon_scratch_free(struct radeon_device *rdev, uint32_t reg)
>   {
>   	int i;
> @@ -162,6 +190,20 @@ void radeon_scratch_free(struct radeon_device *rdev, uint32_t reg)
>   	}
>   }
>   
> +/*
> + * radeon_wb_*()
> + * Writeback is the the method by which the the GPU updates special pages
> + * in memory with the status of certain GPU events (fences, ring pointers,
> + * etc.).
> + */
> +
> +/**
> + * radeon_wb_disable - Disable Writeback
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Disables Writeback (all asics).  Used for suspend.
> + */
>   void radeon_wb_disable(struct radeon_device *rdev)
>   {
>   	int r;
> @@ -177,6 +219,14 @@ void radeon_wb_disable(struct radeon_device *rdev)
>   	rdev->wb.enabled = false;
>   }
>   
> +/**
> + * radeon_wb_fini - Disable Writeback and free memory
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Disables Writeback and frees the Writeback memory (all asics).
> + * Used at driver shutdown.
> + */
>   void radeon_wb_fini(struct radeon_device *rdev)
>   {
>   	radeon_wb_disable(rdev);
> @@ -187,6 +237,15 @@ void radeon_wb_fini(struct radeon_device *rdev)
>   	}
>   }
>   
> +/**
> + * radeon_wb_init- Init Writeback driver info and allocate memory
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Disables Writeback and frees the Writeback memory (all asics).
> + * Used at driver startup.
> + * Returns 0 on success or an -error on failure.
> + */
>   int radeon_wb_init(struct radeon_device *rdev)
>   {
>   	int r;
> @@ -355,6 +414,15 @@ void radeon_gtt_location(struct radeon_device *rdev, struct radeon_mc *mc)
>   /*
>    * GPU helpers function.
>    */
> +/**
> + * radeon_card_posted - check if the hw has already been initialized
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Check if the asic has been initialized (all asics).
> + * Used at driver startup.
> + * Returns true if initialized or false if not.
> + */
>   bool radeon_card_posted(struct radeon_device *rdev)
>   {
>   	uint32_t reg;
> @@ -404,6 +472,14 @@ bool radeon_card_posted(struct radeon_device *rdev)
>   
>   }
>   
> +/**
> + * radeon_update_bandwidth_info - update display bandwidth params
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Used when sclk/mclk are switched or display modes are set.
> + * params are used to calculate display watermarks (all asics)
> + */
>   void radeon_update_bandwidth_info(struct radeon_device *rdev)
>   {
>   	fixed20_12 a;
> @@ -424,6 +500,15 @@ void radeon_update_bandwidth_info(struct radeon_device *rdev)
>   	}
>   }
>   
> +/**
> + * radeon_boot_test_post_card - check and possibly initialize the hw
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Check if the asic is initialized and if not, attempt to initialize
> + * it (all asics).
> + * Returns true if initialized or false if not.
> + */
>   bool radeon_boot_test_post_card(struct radeon_device *rdev)
>   {
>   	if (radeon_card_posted(rdev))
> @@ -442,6 +527,16 @@ bool radeon_boot_test_post_card(struct radeon_device *rdev)
>   	}
>   }
>   
> +/**
> + * radeon_dummy_page_init - init dummy page used by the driver
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Allocate the dummy page used by the driver (all asics).
> + * This dummy page is used by the driver as a filler for gart entries
> + * when pages are taken out of the GART
> + * Returns 0 on sucess, -ENOMEM on failure.
> + */
>   int radeon_dummy_page_init(struct radeon_device *rdev)
>   {
>   	if (rdev->dummy_page.page)
> @@ -460,6 +555,13 @@ int radeon_dummy_page_init(struct radeon_device *rdev)
>   	return 0;
>   }
>   
> +/**
> + * radeon_dummy_page_fini - free dummy page used by the driver
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Frees the dummy page used by the driver (all asics).
> + */
>   void radeon_dummy_page_fini(struct radeon_device *rdev)
>   {
>   	if (rdev->dummy_page.page == NULL)
> @@ -472,6 +574,23 @@ void radeon_dummy_page_fini(struct radeon_device *rdev)
>   
>   
>   /* ATOM accessor methods */
> +/*
> + * ATOM is an interpreted byte code stored in tables in the vbios.  The
> + * driver registers callbacks to access registers and the interpreter
> + * in the driver parses the tables and executes then to program specific
> + * actions (set display modes, asic init, etc.).  See radeon_atombios.c,
> + * atombios.h, and atom.c
> + */
> +
> +/**
> + * cail_pll_read - read PLL register
> + *
> + * @info: atom card_info pointer
> + * @reg: PLL register offset
> + *
> + * Provides a PLL register accessor for the atom interpreter (r4xx+).
> + * Returns the value of the PLL register.
> + */
>   static uint32_t cail_pll_read(struct card_info *info, uint32_t reg)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -481,6 +600,15 @@ static uint32_t cail_pll_read(struct card_info *info, uint32_t reg)
>   	return r;
>   }
>   
> +/**
> + * cail_pll_write - write PLL register
> + *
> + * @info: atom card_info pointer
> + * @reg: PLL register offset
> + * @val: value to write to the pll register
> + *
> + * Provides a PLL register accessor for the atom interpreter (r4xx+).
> + */
>   static void cail_pll_write(struct card_info *info, uint32_t reg, uint32_t val)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -488,6 +616,15 @@ static void cail_pll_write(struct card_info *info, uint32_t reg, uint32_t val)
>   	rdev->pll_wreg(rdev, reg, val);
>   }
>   
> +/**
> + * cail_mc_read - read MC (Memory Controller) register
> + *
> + * @info: atom card_info pointer
> + * @reg: MC register offset
> + *
> + * Provides an MC register accessor for the atom interpreter (r4xx+).
> + * Returns the value of the MC register.
> + */
>   static uint32_t cail_mc_read(struct card_info *info, uint32_t reg)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -497,6 +634,15 @@ static uint32_t cail_mc_read(struct card_info *info, uint32_t reg)
>   	return r;
>   }
>   
> +/**
> + * cail_mc_write - write MC (Memory Controller) register
> + *
> + * @info: atom card_info pointer
> + * @reg: MC register offset
> + * @val: value to write to the pll register
> + *
> + * Provides a MC register accessor for the atom interpreter (r4xx+).
> + */
>   static void cail_mc_write(struct card_info *info, uint32_t reg, uint32_t val)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -504,6 +650,15 @@ static void cail_mc_write(struct card_info *info, uint32_t reg, uint32_t val)
>   	rdev->mc_wreg(rdev, reg, val);
>   }
>   
> +/**
> + * cail_reg_write - write MMIO register
> + *
> + * @info: atom card_info pointer
> + * @reg: MMIO register offset
> + * @val: value to write to the pll register
> + *
> + * Provides a MMIO register accessor for the atom interpreter (r4xx+).
> + */
>   static void cail_reg_write(struct card_info *info, uint32_t reg, uint32_t val)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -511,6 +666,15 @@ static void cail_reg_write(struct card_info *info, uint32_t reg, uint32_t val)
>   	WREG32(reg*4, val);
>   }
>   
> +/**
> + * cail_reg_read - read MMIO register
> + *
> + * @info: atom card_info pointer
> + * @reg: MMIO register offset
> + *
> + * Provides an MMIO register accessor for the atom interpreter (r4xx+).
> + * Returns the value of the MMIO register.
> + */
>   static uint32_t cail_reg_read(struct card_info *info, uint32_t reg)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -520,6 +684,15 @@ static uint32_t cail_reg_read(struct card_info *info, uint32_t reg)
>   	return r;
>   }
>   
> +/**
> + * cail_ioreg_write - write IO register
> + *
> + * @info: atom card_info pointer
> + * @reg: IO register offset
> + * @val: value to write to the pll register
> + *
> + * Provides a IO register accessor for the atom interpreter (r4xx+).
> + */
>   static void cail_ioreg_write(struct card_info *info, uint32_t reg, uint32_t val)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -527,6 +700,15 @@ static void cail_ioreg_write(struct card_info *info, uint32_t reg, uint32_t val)
>   	WREG32_IO(reg*4, val);
>   }
>   
> +/**
> + * cail_ioreg_read - read IO register
> + *
> + * @info: atom card_info pointer
> + * @reg: IO register offset
> + *
> + * Provides an IO register accessor for the atom interpreter (r4xx+).
> + * Returns the value of the IO register.
> + */
>   static uint32_t cail_ioreg_read(struct card_info *info, uint32_t reg)
>   {
>   	struct radeon_device *rdev = info->dev->dev_private;
> @@ -536,6 +718,16 @@ static uint32_t cail_ioreg_read(struct card_info *info, uint32_t reg)
>   	return r;
>   }
>   
> +/**
> + * radeon_atombios_init - init the driver info and callbacks for atombios
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Initializes the driver info and register access callbacks for the
> + * ATOM interpreter (r4xx+).
> + * Returns 0 on sucess, -ENOMEM on failure.
> + * Called at driver startup.
> + */
>   int radeon_atombios_init(struct radeon_device *rdev)
>   {
>   	struct card_info *atom_card_info =
> @@ -569,6 +761,15 @@ int radeon_atombios_init(struct radeon_device *rdev)
>   	return 0;
>   }
>   
> +/**
> + * radeon_atombios_fini - free the driver info and callbacks for atombios
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Frees the driver info and register access callbacks for the ATOM
> + * interpreter (r4xx+).
> + * Called at driver shutdown.
> + */
>   void radeon_atombios_fini(struct radeon_device *rdev)
>   {
>   	if (rdev->mode_info.atom_context) {
> @@ -578,17 +779,50 @@ void radeon_atombios_fini(struct radeon_device *rdev)
>   	kfree(rdev->mode_info.atom_card_info);
>   }
>   
> +/* COMBIOS */
> +/*
> + * COMBIOS is the bios format prior to ATOM. It provides
> + * command tables similar to ATOM, but doesn't have a unified
> + * parser.  See radeon_combios.c
> + */
> +
> +/**
> + * radeon_combios_init - init the driver info for combios
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Initializes the driver info for combios (r1xx-r3xx).
> + * Returns 0 on sucess.
> + * Called at driver startup.
> + */
>   int radeon_combios_init(struct radeon_device *rdev)
>   {
>   	radeon_combios_initialize_bios_scratch_regs(rdev->ddev);
>   	return 0;
>   }
>   
> +/**
> + * radeon_combios_fini - free the driver info for combios
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Frees the driver info for combios (r1xx-r3xx).
> + * Called at driver shutdown.
> + */
>   void radeon_combios_fini(struct radeon_device *rdev)
>   {
>   }
>   
> -/* if we get transitioned to only one device, tak VGA back */
> +/* if we get transitioned to only one device, take VGA back */
> +/**
> + * radeon_vga_set_decode - enable/disable vga decode
> + *
> + * @cookie: radeon_device pointer
> + * @state: enable/disable vga decode
> + *
> + * Enable/disable vga decode (all asics).
> + * Returns VGA resource flags.
> + */
>   static unsigned int radeon_vga_set_decode(void *cookie, bool state)
>   {
>   	struct radeon_device *rdev = cookie;
> @@ -600,6 +834,14 @@ static unsigned int radeon_vga_set_decode(void *cookie, bool state)
>   		return VGA_RSRC_NORMAL_IO | VGA_RSRC_NORMAL_MEM;
>   }
>   
> +/**
> + * radeon_check_arguments - validate module params
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Validates certain module parameters and updates
> + * the associated values used by the driver (all asics).
> + */
>   void radeon_check_arguments(struct radeon_device *rdev)
>   {
>   	/* vramlimit must be a power of two */
> @@ -666,6 +908,15 @@ void radeon_check_arguments(struct radeon_device *rdev)
>   	}
>   }
>   
> +/**
> + * radeon_switcheroo_set_state - set switcheroo state
> + *
> + * @pdev: pci dev pointer
> + * @state: vga switcheroo state
> + *
> + * Callback for the switcheroo driver.  Suspends or resumes the
> + * the asics before or after it is powered up using ACPI methods.
> + */
>   static void radeon_switcheroo_set_state(struct pci_dev *pdev, enum vga_switcheroo_state state)
>   {
>   	struct drm_device *dev = pci_get_drvdata(pdev);
> @@ -686,6 +937,15 @@ static void radeon_switcheroo_set_state(struct pci_dev *pdev, enum vga_switchero
>   	}
>   }
>   
> +/**
> + * radeon_switcheroo_can_switch - see if switcheroo state can change
> + *
> + * @pdev: pci dev pointer
> + *
> + * Callback for the switcheroo driver.  Check of the switcheroo
> + * state can be changed.
> + * Returns true if the state can be changed, false if not.
> + */
>   static bool radeon_switcheroo_can_switch(struct pci_dev *pdev)
>   {
>   	struct drm_device *dev = pci_get_drvdata(pdev);
> @@ -703,6 +963,18 @@ static const struct vga_switcheroo_client_ops radeon_switcheroo_ops = {
>   	.can_switch = radeon_switcheroo_can_switch,
>   };
>   
> +/**
> + * radeon_device_init - initialize the driver
> + *
> + * @rdev: radeon_device pointer
> + * @pdev: drm dev pointer
> + * @pdev: pci dev pointer
> + * @flags: driver flags
> + *
> + * Initializes the driver info and hw (all asics).
> + * Returns 0 for success or an error on failure.
> + * Called at driver startup.
> + */
>   int radeon_device_init(struct radeon_device *rdev,
>   		       struct drm_device *ddev,
>   		       struct pci_dev *pdev,
> @@ -846,6 +1118,14 @@ int radeon_device_init(struct radeon_device *rdev,
>   
>   static void radeon_debugfs_remove_files(struct radeon_device *rdev);
>   
> +/**
> + * radeon_device_fini - tear down the driver
> + *
> + * @rdev: radeon_device pointer
> + *
> + * Tear down the driver info (all asics).
> + * Called at driver shutdown.
> + */
>   void radeon_device_fini(struct radeon_device *rdev)
>   {
>   	DRM_INFO("radeon: finishing device.\n");
> @@ -867,6 +1147,16 @@ void radeon_device_fini(struct radeon_device *rdev)
>   /*
>    * Suspend & resume.
>    */
> +/**
> + * radeon_suspend_kms - initiate device suspend
> + *
> + * @pdev: drm dev pointer
> + * @state: suspend state
> + *
> + * Puts the hw in the suspend state (all asics).
> + * Returns 0 for success or an error on failure.
> + * Called at driver suspend.
> + */
>   int radeon_suspend_kms(struct drm_device *dev, pm_message_t state)
>   {
>   	struct radeon_device *rdev;
> @@ -941,6 +1231,15 @@ int radeon_suspend_kms(struct drm_device *dev, pm_message_t state)
>   	return 0;
>   }
>   
> +/**
> + * radeon_resume_kms - initiate device resume
> + *
> + * @pdev: drm dev pointer
> + *
> + * Bring the hw back to operating state (all asics).
> + * Returns 0 for success or an error on failure.
> + * Called at driver resume.
> + */
>   int radeon_resume_kms(struct drm_device *dev)
>   {
>   	struct drm_connector *connector;
> @@ -983,6 +1282,14 @@ int radeon_resume_kms(struct drm_device *dev)
>   	return 0;
>   }
>   
> +/**
> + * radeon_gpu_reset - reset the asic
> + *
> + * @rdev: radeon device pointer
> + *
> + * Attempt the reset the GPU if it has hung (all asics).
> + * Returns 0 for success or an error on failure.
> + */
>   int radeon_gpu_reset(struct radeon_device *rdev)
>   {
>   	int r;