[PATCH v1 0/5] media: atomisp: Cleanup and documentation fixes for mmu_public.h

[PATCH v1 0/5] media: atomisp: Cleanup and documentation fixes for mmu_public.h

[Mahad Ibrahim]

This series addresses multiple style and documentation issues in the
AtomISP staging driver, specifically in pci/hive_isp_css_include/host/mmu_public.h.

The series starts by fixing checkpatch warnings regarding redundant
return statements, function signature alignment, and block comment coding
style issues.

It then removes erroneous function documentation where additional parameters
were being shown but the actual function signature did not accept any
such parameters.

Finally, the Doxygen-style comments were converted to the standard
kernel-doc format to adhere to the Linux kernel standards.

Mahad Ibrahim (5):
  media: atomisp: Remove redundant return statement
  media: atomisp: Fix function signature alignment
  media: atomisp: Fix block comment coding style
  media: atomisp: Fix erroneous parameter descriptions
  media: atomisp: Convert comments to kernel-doc

 .../hive_isp_css_include/host/mmu_public.h    | 87 ++++++++-----------
 1 file changed, 38 insertions(+), 49 deletions(-)

-- 
2.47.3

[PATCH v1 1/5] media: atomisp: Remove redundant return statement

[Mahad Ibrahim]

The function mmu_reg_store() returns void. The final return
statement is redundant as it is followed by the closing brace.

Remove the redundant return statement to simplify code and adhere to
kernel coding style.

Signed-off-by: Mahad Ibrahim <mahad.ibrahim.dev@gmail.com>
---
 .../media/atomisp/pci/hive_isp_css_include/host/mmu_public.h     | 1 -
 1 file changed, 1 deletion(-)

diff --git a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
index 1a435a348318..2fc137ef46da 100644
--- a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
+++ b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
@@ -63,7 +63,6 @@ static inline void mmu_reg_store(
 	assert(ID < N_MMU_ID);
 	assert(MMU_BASE[ID] != (hrt_address) - 1);
 	ia_css_device_store_uint32(MMU_BASE[ID] + reg * sizeof(hrt_data), value);
-	return;
 }
 
 /*! Read from a control register of MMU[ID]
-- 
2.47.3

[PATCH v1 2/5] media: atomisp: Fix function signature alignment

[Mahad Ibrahim]

Fix checkpatch.pl warnings regarding lines ending with "(" and improper
spacing for indentation.

This change fixes the function signatures for both function prototypes
and static inline function definations in mmu_public.h.

The kernel coding style prefers arguments to start immediately after
the open parenthesis.

Signed-off-by: Mahad Ibrahim <mahad.ibrahim.dev@gmail.com>
---
 .../hive_isp_css_include/host/mmu_public.h    | 19 +++++--------------
 1 file changed, 5 insertions(+), 14 deletions(-)

diff --git a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
index 2fc137ef46da..90a2e4e8f510 100644
--- a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
+++ b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
@@ -18,9 +18,7 @@
 
  \return none, MMU[ID].page_table_base_index = base_index
  */
-void mmu_set_page_table_base_index(
-    const mmu_ID_t		ID,
-    const hrt_data		base_index);
+void mmu_set_page_table_base_index(const mmu_ID_t ID, const hrt_data base_index);
 
 /*! Get the page table base index of MMU[ID]
 
@@ -29,8 +27,7 @@ void mmu_set_page_table_base_index(
 
  \return MMU[ID].page_table_base_index
  */
-hrt_data mmu_get_page_table_base_index(
-    const mmu_ID_t		ID);
+hrt_data mmu_get_page_table_base_index(const mmu_ID_t ID);
 
 /*! Invalidate the page table cache of MMU[ID]
 
@@ -38,8 +35,7 @@ hrt_data mmu_get_page_table_base_index(
 
  \return none
  */
-void mmu_invalidate_cache(
-    const mmu_ID_t		ID);
+void mmu_invalidate_cache(const mmu_ID_t ID);
 
 /*! Invalidate the page table cache of all MMUs
 
@@ -55,10 +51,7 @@ void mmu_invalidate_cache_all(void);
 
  \return none, MMU[ID].ctrl[reg] = value
  */
-static inline void mmu_reg_store(
-    const mmu_ID_t		ID,
-    const unsigned int	reg,
-    const hrt_data		value)
+static inline void mmu_reg_store(const mmu_ID_t ID, const unsigned int reg, const hrt_data value)
 {
 	assert(ID < N_MMU_ID);
 	assert(MMU_BASE[ID] != (hrt_address) - 1);
@@ -73,9 +66,7 @@ static inline void mmu_reg_store(
 
  \return MMU[ID].ctrl[reg]
  */
-static inline hrt_data mmu_reg_load(
-    const mmu_ID_t		ID,
-    const unsigned int	reg)
+static inline hrt_data mmu_reg_load(const mmu_ID_t ID, const unsigned int reg)
 {
 	assert(ID < N_MMU_ID);
 	assert(MMU_BASE[ID] != (hrt_address) - 1);
-- 
2.47.3

[PATCH v1 3/5] media: atomisp: Fix block comment coding style

[Mahad Ibrahim]

Fix checkpatch.pl warnings regarding block comments.

Add missing asterisks to block comments to adhere to the kernel coding
style.

Signed-off-by: Mahad Ibrahim <mahad.ibrahim.dev@gmail.com>
---
 .../hive_isp_css_include/host/mmu_public.h    | 74 ++++++++++---------
 1 file changed, 40 insertions(+), 34 deletions(-)

diff --git a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
index 90a2e4e8f510..c3495ec4835c 100644
--- a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
+++ b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
@@ -11,45 +11,50 @@
 #include "device_access.h"
 #include "assert_support.h"
 
-/*! Set the page table base index of MMU[ID]
-
- \param	ID[in]				MMU identifier
- \param	base_index[in]		page table base index
-
- \return none, MMU[ID].page_table_base_index = base_index
+/*
+ *! Set the page table base index of MMU[ID]
+ *
+ *\param	ID[in]				MMU identifier
+ *\param	base_index[in]		page table base index
+ *
+ *\return none, MMU[ID].page_table_base_index = base_index
  */
 void mmu_set_page_table_base_index(const mmu_ID_t ID, const hrt_data base_index);
 
-/*! Get the page table base index of MMU[ID]
-
- \param	ID[in]				MMU identifier
- \param	base_index[in]		page table base index
-
- \return MMU[ID].page_table_base_index
+/*
+ *! Get the page table base index of MMU[ID]
+ *
+ *\param	ID[in]				MMU identifier
+ *\param	base_index[in]		page table base index
+ *
+ *\return MMU[ID].page_table_base_index
  */
 hrt_data mmu_get_page_table_base_index(const mmu_ID_t ID);
 
-/*! Invalidate the page table cache of MMU[ID]
-
- \param	ID[in]				MMU identifier
-
- \return none
+/*
+ *! Invalidate the page table cache of MMU[ID]
+ *
+ *\param	ID[in]				MMU identifier
+ *
+ *\return none
  */
 void mmu_invalidate_cache(const mmu_ID_t ID);
 
-/*! Invalidate the page table cache of all MMUs
-
- \return none
+/*
+ *! Invalidate the page table cache of all MMUs
+ *
+ *\return none
  */
 void mmu_invalidate_cache_all(void);
 
-/*! Write to a control register of MMU[ID]
-
- \param	ID[in]				MMU identifier
- \param	reg[in]				register index
- \param value[in]			The data to be written
-
- \return none, MMU[ID].ctrl[reg] = value
+/*
+ *! Write to a control register of MMU[ID]
+ *
+ *\param	ID[in]				MMU identifier
+ *\param	reg[in]				register index
+ *\param value[in]			The data to be written
+ *
+ *\return none, MMU[ID].ctrl[reg] = value
  */
 static inline void mmu_reg_store(const mmu_ID_t ID, const unsigned int reg, const hrt_data value)
 {
@@ -58,13 +63,14 @@ static inline void mmu_reg_store(const mmu_ID_t ID, const unsigned int reg, cons
 	ia_css_device_store_uint32(MMU_BASE[ID] + reg * sizeof(hrt_data), value);
 }
 
-/*! Read from a control register of MMU[ID]
-
- \param	ID[in]				MMU identifier
- \param	reg[in]				register index
- \param value[in]			The data to be written
-
- \return MMU[ID].ctrl[reg]
+/*
+ *! Read from a control register of MMU[ID]
+ *
+ *\param	ID[in]				MMU identifier
+ *\param	reg[in]				register index
+ *\param value[in]			The data to be written
+ *
+ *\return MMU[ID].ctrl[reg]
  */
 static inline hrt_data mmu_reg_load(const mmu_ID_t ID, const unsigned int reg)
 {
-- 
2.47.3

[PATCH v1 4/5] media: atomisp: Fix erroneous parameter descriptions

[Mahad Ibrahim]

The function mmu_get_page_table_base_index() accepts only one argument
mmu_ID_t, the block comment for it shows an erroneous additional
argument base_index[in]. Similarly, mmu_reg_load() only accepts two
arguments, however the block comment explaining it shows an erroneous
argument 'value[in]'.

Remove incorrect documentation lines.

Signed-off-by: Mahad Ibrahim <mahad.ibrahim.dev@gmail.com>
---
 .../media/atomisp/pci/hive_isp_css_include/host/mmu_public.h    | 2 --
 1 file changed, 2 deletions(-)

diff --git a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
index c3495ec4835c..611755e88e9f 100644
--- a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
+++ b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
@@ -25,7 +25,6 @@ void mmu_set_page_table_base_index(const mmu_ID_t ID, const hrt_data base_index)
  *! Get the page table base index of MMU[ID]
  *
  *\param	ID[in]				MMU identifier
- *\param	base_index[in]		page table base index
  *
  *\return MMU[ID].page_table_base_index
  */
@@ -68,7 +67,6 @@ static inline void mmu_reg_store(const mmu_ID_t ID, const unsigned int reg, cons
  *
  *\param	ID[in]				MMU identifier
  *\param	reg[in]				register index
- *\param value[in]			The data to be written
  *
  *\return MMU[ID].ctrl[reg]
  */
-- 
2.47.3

[PATCH v1 5/5] media: atomisp: Convert comments to kernel-doc

[Mahad Ibrahim]

Existing comments in mmu_public.h used Doxygen syntax and had
inconsistent formatting.

Convert the function documentation to the standard kernel-doc format to
adhere to the Linux kernel coding style.

Signed-off-by: Mahad Ibrahim <mahad.ibrahim.dev@gmail.com>
---
 .../hive_isp_css_include/host/mmu_public.h    | 59 +++++++++----------
 1 file changed, 27 insertions(+), 32 deletions(-)

diff --git a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
index 611755e88e9f..b321f4101193 100644
--- a/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
+++ b/drivers/staging/media/atomisp/pci/hive_isp_css_include/host/mmu_public.h
@@ -11,49 +11,45 @@
 #include "device_access.h"
 #include "assert_support.h"
 
-/*
- *! Set the page table base index of MMU[ID]
- *
- *\param	ID[in]				MMU identifier
- *\param	base_index[in]		page table base index
+/**
+ * mmu_set_page_table_base_index() - Set the page table base index of MMU[ID]
+ * @ID:				MMU identifier
+ * @base_index:			page table base index
  *
- *\return none, MMU[ID].page_table_base_index = base_index
+ * Return: none, MMU[ID].page_table_base_index = base_index
  */
 void mmu_set_page_table_base_index(const mmu_ID_t ID, const hrt_data base_index);
 
-/*
- *! Get the page table base index of MMU[ID]
+/**
+ * mmu_get_page_table_base_index() - Get the page table base index of MMU[ID]
+ * @ID:				MMU identifier
  *
- *\param	ID[in]				MMU identifier
- *
- *\return MMU[ID].page_table_base_index
+ * Return: MMU[ID].page_table_base_index
  */
 hrt_data mmu_get_page_table_base_index(const mmu_ID_t ID);
 
-/*
- *! Invalidate the page table cache of MMU[ID]
- *
- *\param	ID[in]				MMU identifier
+/**
+ * mmu_invalidate_cache() - nvalidate the page table cache of MMU[ID]
+ * @ID:				MMU identifier
  *
- *\return none
+ * Return: none
  */
 void mmu_invalidate_cache(const mmu_ID_t ID);
 
-/*
- *! Invalidate the page table cache of all MMUs
+/**
+ * mmu_invalidate_cache_all() - Invalidate the page table cache of all MMUs
  *
- *\return none
+ * Return: none
  */
 void mmu_invalidate_cache_all(void);
 
-/*
- *! Write to a control register of MMU[ID]
- *
- *\param	ID[in]				MMU identifier
- *\param	reg[in]				register index
- *\param value[in]			The data to be written
+/**
+ * mmu_reg_store() - Write to a control register of MMU[ID]
+ * @ID:				MMU identifier
+ * @reg:			register index
+ * @value:			The data to be written
  *
- *\return none, MMU[ID].ctrl[reg] = value
+ * Return: none, MMU[ID].ctrl[reg] = value
  */
 static inline void mmu_reg_store(const mmu_ID_t ID, const unsigned int reg, const hrt_data value)
 {
@@ -62,13 +58,12 @@ static inline void mmu_reg_store(const mmu_ID_t ID, const unsigned int reg, cons
 	ia_css_device_store_uint32(MMU_BASE[ID] + reg * sizeof(hrt_data), value);
 }
 
-/*
- *! Read from a control register of MMU[ID]
- *
- *\param	ID[in]				MMU identifier
- *\param	reg[in]				register index
+/**
+ * mmu_reg_load() - Read from a control register of MMU[ID]
+ * @ID:				MMU identifier
+ * @reg:			register index
  *
- *\return MMU[ID].ctrl[reg]
+ * Return: MMU[ID].ctrl[reg]
  */
 static inline hrt_data mmu_reg_load(const mmu_ID_t ID, const unsigned int reg)
 {
-- 
2.47.3