[PATCH 08/13] staging: gasket: page table: simplify comments for static functions
From: Todd Poynor
Date: Sun Jul 29 2018 - 15:37:15 EST
From: Todd Poynor <toddpoynor@xxxxxxxxxx>
Static functions don't need kernel doc formatting, can be simplified.
Reformat comments that can be single-line. Remove extraneous text.
Signed-off-by: Todd Poynor <toddpoynor@xxxxxxxxxx>
---
drivers/staging/gasket/gasket_page_table.c | 323 +++------------------
1 file changed, 48 insertions(+), 275 deletions(-)
diff --git a/drivers/staging/gasket/gasket_page_table.c b/drivers/staging/gasket/gasket_page_table.c
index 6b946a155ee3a..b42f6637b909b 100644
--- a/drivers/staging/gasket/gasket_page_table.c
+++ b/drivers/staging/gasket/gasket_page_table.c
@@ -635,27 +635,9 @@ int gasket_page_table_system_status(struct gasket_page_table *page_table)
return GASKET_STATUS_ALIVE;
}
-/* Internal functions */
-
-/* Mapping functions */
/*
* Allocate and map pages to simple addresses.
- * @pg_tbl: Gasket page table pointer.
- * @host_addr: Starting host virtual memory address of the pages.
- * @dev_addr: Starting device address of the pages.
- * @cnt: Count of the number of device pages to map.
- *
- * Description: gasket_map_simple_pages calls gasket_simple_alloc_pages() to
- * allocate the page table slots, then calls
- * gasket_perform_mapping() to actually do the work of mapping the
- * pages into the the simple page table (device translation table
- * registers).
- *
- * The sd_mutex must be held when gasket_map_simple_pages() is
- * called.
- *
- * Returns 0 if successful or a non-zero error number otherwise.
- * If there is an error, no pages are mapped.
+ * If there is an error, no pages are mapped.
*/
static int gasket_map_simple_pages(
struct gasket_page_table *pg_tbl, ulong host_addr, ulong dev_addr,
@@ -685,22 +667,7 @@ static int gasket_map_simple_pages(
/*
* gasket_map_extended_pages - Get and map buffers to extended addresses.
- * @pg_tbl: Gasket page table pointer.
- * @host_addr: Starting host virtual memory address of the pages.
- * @dev_addr: Starting device address of the pages.
- * @num_pages: The number of device pages to map.
- *
- * Description: gasket_map_extended_buffers calls
- * gasket_alloc_extended_entries() to allocate the page table
- * slots, then loops over the level 0 page table entries, and for
- * each calls gasket_perform_mapping() to map the buffers into the
- * level 1 page table for that level 0 entry.
- *
- * The page table mutex must be held when
- * gasket_map_extended_pages() is called.
- *
- * Returns 0 if successful or a non-zero error number otherwise.
- * If there is an error, no pages are mapped.
+ * If there is an error, no pages are mapped.
*/
static int gasket_map_extended_pages(
struct gasket_page_table *pg_tbl, ulong host_addr, ulong dev_addr,
@@ -756,32 +723,11 @@ static int gasket_map_extended_pages(
/*
* Get and map last level page table buffers.
- * @pg_tbl: Gasket page table pointer.
- * @ptes: Array of page table entries to describe this mapping, one per
- * page to map.
- * @slots: Location(s) to write device-mapped page address. If this is a simple
- * mapping, these will be address translation registers. If this is
- * an extended mapping, these will be within a second-level page table
- * allocated by the host and so must have their __iomem attribute
- * casted away.
- * @host_addr: Starting [host] virtual memory address of the buffers.
- * @num_pages: The number of device pages to map.
- * @is_simple_mapping: 1 if this is a simple mapping, 0 otherwise.
- *
- * Description: gasket_perform_mapping calls get_user_pages() to get pages
- * of user memory and pin them. It then calls dma_map_page() to
- * map them for DMA. Finally, the mapped DMA addresses are written
- * into the page table.
*
- * This function expects that the page table entries are
- * already allocated. The level argument determines how the
- * final page table entries are written: either into PCIe memory
- * mapped space for a level 0 page table or into kernel memory
- * for a level 1 page table.
- *
- * The page pointers are saved for later releasing the pages.
- *
- * Returns 0 if successful or a non-zero error number otherwise.
+ * slots is the location(s) to write device-mapped page address. If this is a
+ * simple mapping, these will be address translation registers. If this is
+ * an extended mapping, these will be within a second-level page table
+ * allocated by the host and so must have their __iomem attribute casted away.
*/
static int gasket_perform_mapping(
struct gasket_page_table *pg_tbl, struct gasket_page_table_entry *ptes,
@@ -866,21 +812,9 @@ static int gasket_perform_mapping(
return 0;
}
-/**
+/*
* Allocate page table entries in a simple table.
- * @pg_tbl: Gasket page table pointer.
- * @dev_addr: Starting device address for the (eventual) mappings.
- * @num_pages: Count of pages to be mapped.
- *
- * Description: gasket_alloc_simple_entries checks to see if a range of page
- * table slots are available. As long as the sd_mutex is
- * held, the slots will be available.
- *
- * The page table mutex must be held when
- * gasket_alloc_simple entries() is called.
- *
- * Returns 0 if successful, or non-zero if the requested device
- * addresses are not available.
+ * The page table mutex must be held by the caller.
*/
static int gasket_alloc_simple_entries(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_pages)
@@ -893,29 +827,19 @@ static int gasket_alloc_simple_entries(
return 0;
}
-/**
- * Allocate slots in an extended page table.
- * @pg_tbl: Gasket page table pointer.
- * @dev_addr: Starting device address for the (eventual) mappings.
- * @num_pages: Count of pages to be mapped.
- *
- * Description: gasket_alloc_extended_entries checks to see if a range of page
- * table slots are available. If necessary, memory is allocated for
- * second level page tables.
- *
- * Note that memory for second level page tables is allocated
- * as needed, but that memory is only freed on the final close
- * of the device file, when the page tables are repartitioned,
- * or the the device is removed. If there is an error or if
- * the full range of slots is not available, any memory
- * allocated for second level page tables remains allocated
- * until final close, repartition, or device removal.
+/*
+ * Allocate slots in an extended page table. Check to see if a range of page
+ * table slots are available. If necessary, memory is allocated for second level
+ * page tables.
*
- * The page table mutex must be held when
- * gasket_alloc_extended_entries() is called.
+ * Note that memory for second level page tables is allocated as needed, but
+ * that memory is only freed on the final close of the device file, when the
+ * page tables are repartitioned, or the the device is removed. If there is an
+ * error or if the full range of slots is not available, any memory
+ * allocated for second level page tables remains allocated until final close,
+ * repartition, or device removal.
*
- * Returns 0 if successful, or non-zero if the slots are
- * not available.
+ * The page table mutex must be held by the caller.
*/
static int gasket_alloc_extended_entries(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_entries)
@@ -958,21 +882,9 @@ static int gasket_alloc_extended_entries(
return 0;
}
-/**
+/*
* Allocate a second level page table.
- * @pg_tbl: Gasket page table pointer.
- * @pte: Extended page table entry under/for which to allocate a second level.
- * @slot: [Device] slot corresponding to pte.
- *
- * Description: Allocate the memory for a second level page table (subtable) at
- * the given level 0 entry. Then call dma_map_page() to map the
- * second level page table for DMA. Finally, write the
- * mapped DMA address into the device page table.
- *
- * The page table mutex must be held when
- * gasket_alloc_extended_subtable() is called.
- *
- * Returns 0 if successful, or a non-zero error otherwise.
+ * The page table mutex must be held by the caller.
*/
static int gasket_alloc_extended_subtable(
struct gasket_page_table *pg_tbl, struct gasket_page_table_entry *pte,
@@ -1017,15 +929,9 @@ static int gasket_alloc_extended_subtable(
return 0;
}
-/* Unmapping functions */
/*
* Non-locking entry to unmapping routines.
- * @pg_tbl: Gasket page table structure.
- * @dev_addr: Starting device address of the pages to unmap.
- * @num_pages: The number of device pages to unmap.
- *
- * Description: Version of gasket_unmap_pages that assumes the page table lock
- * is held.
+ * The page table mutex must be held by the caller.
*/
static void gasket_page_table_unmap_nolock(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_pages)
@@ -1041,14 +947,7 @@ static void gasket_page_table_unmap_nolock(
/*
* Unmap and release pages mapped to simple addresses.
- * @pg_tbl: Gasket page table pointer.
- * @dev_addr: Starting device address of the buffers.
- * @num_pages: The number of device pages to unmap.
- *
- * Description: gasket_simple_unmap_pages calls gasket_perform_unmapping() to
- * unmap and release the buffers in the level 0 page table.
- *
- * The sd_mutex must be held when gasket_unmap_simple_pages() is called.
+ * The page table mutex must be held by the caller.
*/
static void gasket_unmap_simple_pages(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_pages)
@@ -1059,20 +958,9 @@ static void gasket_unmap_simple_pages(
pg_tbl->base_slot + slot, num_pages, 1);
}
-/**
+/*
* Unmap and release buffers to extended addresses.
- * @pg_tbl: Gasket page table pointer.
- * @dev_addr: Starting device address of the pages to unmap.
- * @addr: Starting device address of the buffers.
- * @num_pages: The number of device pages to unmap.
- *
- * Description: gasket_extended_unmap_pages loops over the level 0 page table
- * entries, and for each calls gasket_perform_unmapping() to unmap
- * the buffers from the level 1 page [sub]table for that level 0
- * entry.
- *
- * The page table mutex must be held when
- * gasket_unmap_extended_pages() is called.
+ * The page table mutex must be held by the caller.
*/
static void gasket_unmap_extended_pages(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_pages)
@@ -1106,28 +994,7 @@ static void gasket_unmap_extended_pages(
/*
* Unmap and release mapped pages.
- * @pg_tbl: Gasket page table pointer.
- * @ptes: Array of page table entries to describe the mapped range, one per
- * page to unmap.
- * @slots: Device slots corresponding to the mappings described by "ptes".
- * As with ptes, one element per page to unmap.
- * If these are simple mappings, these will be address translation
- * registers. If these are extended mappings, these will be witin a
- * second-level page table allocated on the host, and so must have
- * their __iomem attribute casted away.
- * @num_pages: Number of pages to unmap.
- * @is_simple_mapping: 1 if this is a simple mapping, 0 otherwise.
- *
- * Description: gasket_perform_unmapping() loops through the metadata entries
- * in a last level page table (simple table or extended subtable),
- * and for each page:
- * - Unmaps the page from DMA space (dma_unmap_page),
- * - Returns the page to the OS (gasket_release_page),
- * The entry in the page table is written to 0. The metadata
- * type is set to PTE_FREE and the metadata is all reset
- * to 0.
- *
- * The page table mutex must be held when this function is called.
+ * The page table mutex must be held by the caller.
*/
static void gasket_perform_unmapping(
struct gasket_page_table *pg_tbl, struct gasket_page_table_entry *ptes,
@@ -1165,17 +1032,6 @@ static void gasket_perform_unmapping(
/*
* Free a second level page [sub]table.
- * @pg_tbl: Gasket page table pointer.
- * @pte: Page table entry _pointing_to_ the subtable to free.
- * @slot: Device slot holding a pointer to the sublevel's contents.
- *
- * Description: Safely deallocates a second-level [sub]table by:
- * - Marking the containing first-level PTE as free
- * - Setting the corresponding [extended] device slot as NULL
- * - Unmapping the PTE from DMA space.
- * - Freeing the subtable's memory.
- * - Deallocating the page and clearing out the PTE.
- *
* The page table mutex must be held before this call.
*/
static void gasket_free_extended_subtable(
@@ -1202,12 +1058,7 @@ static void gasket_free_extended_subtable(
memset(pte, 0, sizeof(struct gasket_page_table_entry));
}
-/*
- * Safely return a page to the OS.
- * @page: The page to return to the OS.
- * Returns true if the page was released, false if it was
- * ignored.
- */
+/* Safely return a page to the OS. */
static bool gasket_release_page(struct page *page)
{
if (!page)
@@ -1229,13 +1080,10 @@ static inline bool gasket_addr_is_simple(
/*
* Validity checking for simple addresses.
- * @pg_tbl: Gasket page table pointer.
- * @dev_addr: The device address to which the pages will be mapped.
- * @num_pages: The number of pages in the range to consider.
*
- * Description: This call verifies that address translation commutes (from
- * address to/from page + offset) and that the requested page range starts and
- * ends within the set of currently-partitioned simple pages.
+ * Verify that address translation commutes (from address to/from page + offset)
+ * and that the requested page range starts and ends within the set of
+ * currently-partitioned simple pages.
*/
static bool gasket_is_simple_dev_addr_bad(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_pages)
@@ -1269,13 +1117,11 @@ static bool gasket_is_simple_dev_addr_bad(
}
/*
- * Verifies that address translation commutes (from address to/from page +
- * offset) and that the requested page range starts and ends within the set of
- * currently-partitioned simple pages.
+ * Validity checking for extended addresses.
*
- * @pg_tbl: Gasket page table pointer.
- * @dev_addr: The device address to which the pages will be mapped.
- * @num_pages: The number of second-level/sub pages in the range to consider.
+ * Verify that address translation commutes (from address to/from page +
+ * offset) and that the requested page range starts and ends within the set of
+ * currently-partitioned extended pages.
*/
static bool gasket_is_extended_dev_addr_bad(
struct gasket_page_table *pg_tbl, ulong dev_addr, uint num_pages)
@@ -1331,15 +1177,8 @@ static bool gasket_is_extended_dev_addr_bad(
}
/*
- * Checks if a range of PTEs is free.
- * @ptes: The set of PTEs to check.
- * @num_entries: The number of PTEs to check.
- *
- * Description: Iterates over the input PTEs to determine if all have been
- * marked as FREE or if any are INUSE. In the former case, 1/true is returned.
- * Otherwise, 0/false is returned.
- *
- * The page table mutex must be held before this call.
+ * Check if a range of PTEs is free.
+ * The page table mutex must be held by the caller.
*/
static bool gasket_is_pte_range_free(
struct gasket_page_table_entry *ptes, uint num_entries)
@@ -1356,10 +1195,7 @@ static bool gasket_is_pte_range_free(
/*
* Actually perform collection.
- * @pg_tbl: Gasket page table structure.
- *
- * Description: Version of gasket_page_table_garbage_collect that assumes the
- * page table lock is held.
+ * The page table mutex must be held by the caller.
*/
static void gasket_page_table_garbage_collect_nolock(
struct gasket_page_table *pg_tbl)
@@ -1384,14 +1220,7 @@ static void gasket_page_table_garbage_collect_nolock(
}
/*
- * Converts components to a device address.
- * @pg_tbl: Gasket page table structure.
- * @is_simple: nonzero if this should be a simple entry, zero otherwise.
- * @page_index: The page index into the respective table.
- * @offset: The offset within the requested page.
- *
- * Simple utility function to convert (simple, page, offset) into a device
- * address.
+ * Convert (simple, page, offset) into a device address.
* Examples:
* Simple page 0, offset 32:
* Input (0, 0, 32), Output 0x20
@@ -1429,14 +1258,7 @@ static ulong gasket_components_to_dev_address(
}
/*
- * Gets the index of the address' page in the simple table.
- * @pg_tbl: Gasket page table structure.
- * @dev_addr: The address whose page index to retrieve.
- *
- * Description: Treats the input address as a simple address and determines the
- * index of its underlying page in the simple page table (i.e., device address
- * translation registers.
- *
+ * Return the index of the page for the address in the simple table.
* Does not perform validity checking.
*/
static int gasket_simple_page_idx(
@@ -1447,14 +1269,7 @@ static int gasket_simple_page_idx(
}
/*
- * Gets the level 0 page index for the given address.
- * @pg_tbl: Gasket page table structure.
- * @dev_addr: The address whose page index to retrieve.
- *
- * Description: Treats the input address as an extended address and determines
- * the index of its underlying page in the first-level extended page table
- * (i.e., device extended address translation registers).
- *
+ * Return the level 0 page index for the given address.
* Does not perform validity checking.
*/
static ulong gasket_extended_lvl0_page_idx(
@@ -1465,14 +1280,7 @@ static ulong gasket_extended_lvl0_page_idx(
}
/*
- * Gets the level 1 page index for the given address.
- * @pg_tbl: Gasket page table structure.
- * @dev_addr: The address whose page index to retrieve.
- *
- * Description: Treats the input address as an extended address and determines
- * the index of its underlying page in the second-level extended page table
- * (i.e., host memory pointed to by a first-level page table entry).
- *
+ * Return the level 1 page index for the given address.
* Does not perform validity checking.
*/
static ulong gasket_extended_lvl1_page_idx(
@@ -1483,13 +1291,10 @@ static ulong gasket_extended_lvl1_page_idx(
}
/*
- * Determines whether a host buffer was mapped as coherent memory.
- * @pg_tbl: gasket_page_table structure tracking the host buffer mapping
- * @host_addr: user virtual address within a host buffer
+ * Return whether a host buffer was mapped as coherent memory.
*
- * Description: A Gasket page_table currently support one contiguous
- * dma range, mapped to one contiguous virtual memory range. Check if the
- * host_addr is within start of page 0, and end of last page, for that range.
+ * A Gasket page_table currently support one contiguous dma range, mapped to one
+ * contiguous virtual memory range. Check if the host_addr is within that range.
*/
static int is_coherent(struct gasket_page_table *pg_tbl, ulong host_addr)
{
@@ -1505,16 +1310,7 @@ static int is_coherent(struct gasket_page_table *pg_tbl, ulong host_addr)
return min <= host_addr && host_addr < max;
}
-/*
- * Records the host_addr to coherent dma memory mapping.
- * @gasket_dev: Gasket Device.
- * @size: Size of the virtual address range to map.
- * @dma_address: Dma address within the coherent memory range.
- * @vma: Virtual address we wish to map to coherent memory.
- *
- * Description: For each page in the virtual address range, record the
- * coherent page mgasket_pretapping.
- */
+/* Record the host_addr to coherent dma memory mapping. */
int gasket_set_user_virt(
struct gasket_dev *gasket_dev, u64 size, dma_addr_t dma_address,
ulong vma)
@@ -1541,16 +1337,7 @@ int gasket_set_user_virt(
return 0;
}
-/*
- * Allocate a block of coherent memory.
- * @gasket_dev: Gasket Device.
- * @size: Size of the memory block.
- * @dma_address: Dma address allocated by the kernel.
- * @index: Index of the gasket_page_table within this Gasket device
- *
- * Description: Allocate a contiguous coherent memory block, DMA'ble
- * by this device.
- */
+/* Allocate a block of coherent memory. */
int gasket_alloc_coherent_memory(struct gasket_dev *gasket_dev, u64 size,
dma_addr_t *dma_address, u64 index)
{
@@ -1613,15 +1400,7 @@ int gasket_alloc_coherent_memory(struct gasket_dev *gasket_dev, u64 size,
return -ENOMEM;
}
-/*
- * Free a block of coherent memory.
- * @gasket_dev: Gasket Device.
- * @size: Size of the memory block.
- * @dma_address: Dma address allocated by the kernel.
- * @index: Index of the gasket_page_table within this Gasket device
- *
- * Description: Release memory allocated thru gasket_alloc_coherent_memory.
- */
+/* Free a block of coherent memory. */
int gasket_free_coherent_memory(struct gasket_dev *gasket_dev, u64 size,
dma_addr_t dma_address, u64 index)
{
@@ -1647,13 +1426,7 @@ int gasket_free_coherent_memory(struct gasket_dev *gasket_dev, u64 size,
return 0;
}
-/*
- * Release all coherent memory.
- * @gasket_dev: Gasket Device.
- * @index: Index of the gasket_page_table within this Gasket device
- *
- * Description: Release all memory allocated thru gasket_alloc_coherent_memory.
- */
+/* Release all coherent memory. */
void gasket_free_coherent_memory_all(
struct gasket_dev *gasket_dev, u64 index)
{
--
2.18.0.345.g5c9ce644c3-goog