Skip to content

L
linux
Commit 48088486 authored by Todd Poynor's avatar Todd Poynor Committed by Greg Kroah-Hartman
Browse files
Options

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: default avatarTodd Poynor <toddpoynor@google.com>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 73832cf0
Hide whitespace changes
Inline Side-by-side
Showing with 48 additions and 275 deletions
drivers/staging/gasket/gasket_page_table.c
View file @ 48088486
......@@ -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)
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7