From 480884860158a0942aa4147c40c56dc9a1d985af Mon Sep 17 00:00:00 2001 From: Todd Poynor Date: Sun, 29 Jul 2018 12:36:41 -0700 Subject: [PATCH] staging: gasket: page table: simplify comments for static functions 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 Signed-off-by: Greg Kroah-Hartman --- 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 6b946a155ee3..b42f6637b909 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. +/* + * 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. * - * 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. * - * 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. - * - * The page table mutex must be held when - * gasket_alloc_extended_entries() is called. - * - * 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) {