On 29.06.2012 18:50, alexdeucher at gmail.com wrote: > From: Alex Deucher <alexander.deucher at 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 at amd.com> For the whole series:
Reviewed-by: Christian K?nig <christian.koenig at 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;