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

[alexdeuc...@gmail.com]

From: Alex Deucher 

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 
---
 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 0302a9f..528dab1 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 

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

[alexdeucher]

From: Alex Deucher alexander.deuc...@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.deuc...@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 0302a9f..528dab1 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 

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

[Christian König]

On 29.06.2012 18:50, alexdeucher at gmail.com wrote:
> From: Alex Deucher 
>
> 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 
For the whole series:

Reviewed-by: Christian K?nig 


> ---
>   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 

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

[Christian König]

On 29.06.2012 18:50, alexdeuc...@gmail.com wrote:

From: Alex Deucher alexander.deuc...@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.deuc...@amd.com

For the whole series:

Reviewed-by: Christian König christian.koe...@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))
@@ 

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

[alexdeuc...@gmail.com]

From: Alex Deucher 

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 
---
 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 

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

[alexdeucher]

From: Alex Deucher alexander.deuc...@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.deuc...@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