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

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;