nv-tegra-mirror/linux-nvgpu
1
0
Fork 0
mirror of git://nv-tegra.nvidia.com/linux-nvgpu.git synced 2025-12-22 09:12:24 +03:00
Code Issues Packages Projects Releases Wiki Activity

gpu: nvgpu: add doxygen documentation

Browse Source 
Add Doxygen documentation for the below units
 - log2
 - circ_buf
 - kref
 - list

Jira NVGPU-4417

Change-Id: I93d19a41ab4539cac0ccf514e790c6bb3f85bcc9
Signed-off-by: ajesh <akv@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nvgpu/+/2286888
Reviewed-by: Philip Elcan <pelcan@nvidia.com>
Reviewed-by: Deepak Nibade <dnibade@nvidia.com>
Reviewed-by: mobile promotions <svcmobile_promotions@nvidia.com>
GVS: Gerrit_Virtual_Submit
Tested-by: mobile promotions <svcmobile_promotions@nvidia.com>
This commit is contained in:
ajesh
2020-01-29 12:14:55 +05:30
committed by Alex Waterman
parent bbb63c0a8c
commit 0351154407
4 changed files with 251 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
drivers/gpu/nvgpu/include/nvgpu/kref.h
View File

@@ -31,34 +31,46 @@
#include <nvgpu/utils.h>
struct nvgpu_ref {
/**
* Atomic reference count.
*/
nvgpu_atomic_t refcount;
};
/*
* Initialize object.
* @ref: the nvgpu_ref object to initialize
/**
* @brief Initialize the reference object.
*
* @param ref [in] The nvgpu_ref object to initialize.
*
* Initializes the reference object pointed by \a ref.
*/
static inline void nvgpu_ref_init(struct nvgpu_ref *ref)
{
nvgpu_atomic_set(&ref->refcount, 1);
}
/*
/**
* @brief Increment the reference count.
*
* @param ref [in] The nvgpu_ref object.
*
* Increment reference count for the object
* @ref: the nvgpu_ref object
*/
static inline void nvgpu_ref_get(struct nvgpu_ref *ref)
{
nvgpu_atomic_inc(&ref->refcount);
}
/*
/**
* @brief Decrement the reference count.
*
* @param ref[in] The nvgpu_ref object.
* @param release [in] Pointer to the function that would be invoked to
* clean up the object when the reference count becomes
* zero.
*
* Decrement reference count for the object and call release() if it becomes
* zero.
* @ref: the nvgpu_ref object
* @release: pointer to the function that would be invoked to clean up the
* object when the reference count becomes zero, i.e. the last
* reference corresponding to this object is removed.
*/
static inline void nvgpu_ref_put(struct nvgpu_ref *ref,
void (*release)(struct nvgpu_ref *r))
@@ -70,15 +82,22 @@ static inline void nvgpu_ref_put(struct nvgpu_ref *ref,
}
}
/*
* Decrement reference count for the object, call release() if it becomes
* zero and return the status of the removal.
* @ref: the nvgpu_ref object
* @release: pointer to the function that would be invoked to clean up the
* object when the reference count becomes zero, i.e. the last
* reference corresponding to this object is removed.
* Return 1 if object was removed, otherwise return 0. The user should not
* make any assumptions about the status of the object in the memory when
/**
* @brief Decrement reference count for the object, call release() if it
* becomes zero and return the status of the removal.
*
* @param ref [in] The nvgpu_ref object.
* @param release [in] Pointer to the function that would be invoked to
* clean up the object when the reference count becomes
* zero, i.e. the last reference corresponding to this
* object is removed.
*
* Decrement the reference count for the object pointed by \a ref, invokes the
* callback function \a release if it becomes zero and returns the status of
* the removal.
*
* @return Return 1 if object was removed, otherwise return 0. The user should
* not make any assumptions about the status of the object in the memory when
* the function returns 0 and should only use it to know that there are no
* further references to this object.
*/
@@ -94,10 +113,14 @@ static inline int nvgpu_ref_put_return(struct nvgpu_ref *ref,
return 0;
}
/*
* Increment reference count for the object unless it is zero.
* @ref: the nvgpu_ref object
* Return non-zero if the increment succeeds, Otherwise return 0.
/**
* @brief Increment reference count of the object unless it is zero.
*
* @param ref [in] The nvgpu_ref object.
*
* Increment the reference count of the object unless it is zero.
*
* @return Return non-zero if the increment succeeds, Otherwise return 0.
*/
static inline int nvgpu_ref_get_unless_zero(struct nvgpu_ref *ref)
{

148
drivers/gpu/nvgpu/include/nvgpu/list.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2017-2018, NVIDIA CORPORATION. All rights reserved.
* Copyright (c) 2017-2020, NVIDIA CORPORATION. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
@@ -25,17 +25,39 @@
#include <nvgpu/types.h>
struct nvgpu_list_node {
/*
* Pointer to the previous node.
*/
struct nvgpu_list_node *prev;
/*
* Pointer to the next node.
*/
struct nvgpu_list_node *next;
};
/**
* @brief Initialize a list node.
*
* @param node [in] List node to initialize.
*
* Initializes a list node by setting the prev and next pointer to itself.
*/
static inline void nvgpu_init_list_node(struct nvgpu_list_node *node)
{
node->prev = node;
node->next = node;
}
static inline void nvgpu_list_add(struct nvgpu_list_node *new_node, struct nvgpu_list_node *head)
/**
* @brief Add a new node to the list.
*
* @param node [in] Node to be added.
* @param head [in] Head of the list.
*
* Adds the node \a new_node to the head of the list pointed by \a head.
*/
static inline void nvgpu_list_add(struct nvgpu_list_node *new_node,
struct nvgpu_list_node *head)
{
new_node->next = head->next;
new_node->next->prev = new_node;
@@ -43,7 +65,17 @@ static inline void nvgpu_list_add(struct nvgpu_list_node *new_node, struct nvgpu
head->next = new_node;
}
static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node, struct nvgpu_list_node *head)
/**
* @brief Add a new node to the tail of the list.
*
* @param node [in] Node to be added.
* @param head [in] Tail node of the list where the
* addition has to be done.
*
* Adds the node \a new_node to the tail of the list pointed by \a head.
*/
static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node,
struct nvgpu_list_node *head)
{
new_node->prev = head->prev;
new_node->prev->next = new_node;
@@ -51,6 +83,14 @@ static inline void nvgpu_list_add_tail(struct nvgpu_list_node *new_node, struct
head->prev = new_node;
}
/**
* @brief Delete a node from the list.
*
* @param node [in] Condition variable to wait.
*
* Deletes the node \a node from the list and initialize the node pointers to
* point to itself.
*/
static inline void nvgpu_list_del(struct nvgpu_list_node *node)
{
node->prev->next = node->next;
@@ -58,18 +98,47 @@ static inline void nvgpu_list_del(struct nvgpu_list_node *node)
nvgpu_init_list_node(node);
}
/**
* @brief Check for empty list.
*
* @param head [in] Head node of the list to be checked.
*
* Checks if the list pointed by \a head is empty or not.
*
* @return return true if the list is empty, otherwise return false.
*/
static inline bool nvgpu_list_empty(struct nvgpu_list_node *head)
{
return head->next == head;
}
static inline void nvgpu_list_move(struct nvgpu_list_node *node, struct nvgpu_list_node *head)
/**
* @brief Move a node from the list to head.
*
* @param node [in] Node to move.
* @param head [in] Head of the list.
*
* Moves the node pointed by \a node to the head of the list pointed
* by \a head.
*/
static inline void nvgpu_list_move(struct nvgpu_list_node *node,
struct nvgpu_list_node *head)
{
nvgpu_list_del(node);
nvgpu_list_add(node, head);
}
static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, struct nvgpu_list_node *new_node)
/**
* @brief Replace a node in the list.
*
* @param old_node [in] Node to replace.
* @param new_node [in] Node to replace with.
*
* Replaces the node pointed by \a old_node with the node pointed
* by \a new_node.
*/
static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node,
struct nvgpu_list_node *new_node)
{
new_node->next = old_node->next;
new_node->next->prev = new_node;
@@ -78,23 +147,92 @@ static inline void nvgpu_list_replace_init(struct nvgpu_list_node *old_node, str
nvgpu_init_list_node(old_node);
}
/** @cond DOXYGEN_SHOULD_SKIP_THIS */
/**
* @brief Entry from the list
*
* @param ptr [in] Ptr to the list.
* @param type [in] Type of the entry.
* @param member [in] Name of the list entry in \a type.
*
* Uses token pasting operator to invoke the type and member specific
* function implementation.
*/
#define nvgpu_list_entry(ptr, type, member) \
type ## _from_ ## member(ptr)
/**
* @brief Next entry from the list.
*
* @param pos [in] Position in the list to get the next entry from.
* @param type [in] Type of the entry.
* @param member [in] Name of the list entry in \a type.
*
* Fetches the next entry from the list.
*
* @return The next entry from the list.
*/
#define nvgpu_list_next_entry(pos, type, member) \
nvgpu_list_entry((pos)->member.next, type, member)
/** @endcond DOXYGEN_SHOULD_SKIP_THIS */
/**
* @brief First entry from the list.
*
* @param ptr [in] Pointer to the head.
* @param type [in] Type of the entry.
* @param member [in] Name of the list entry in \a type.
*
* Fetches the first entry from the list.
*
* @return The first entry from the list.
*/
#define nvgpu_list_first_entry(ptr, type, member) \
nvgpu_list_entry((ptr)->next, type, member)
/**
* @brief Last entry from the list.
*
* @param ptr [in] Pointer to list.
* @param type [in] Type of the entry.
* @param member [in] Name of the list entry in \a type.
*
* Fetches the last entry from the list.
*
* @return The last entry from the list.
*/
#define nvgpu_list_last_entry(ptr, type, member) \
nvgpu_list_entry((ptr)->prev, type, member)
/**
* @brief Loop through each entry in the list.
*
* @param pos [in, out] Entry node in the list.
* @param head [in] Pointer to the list.
* @param type [in] Type of the entry.
* @param member [in] Name of the list entry in \a type.
*
* Loops through each entry in the list.
*/
#define nvgpu_list_for_each_entry(pos, head, type, member) \
for ((pos) = nvgpu_list_first_entry(head, type, member); \
&(pos)->member != (head); \
(pos) = nvgpu_list_next_entry(pos, type, member))
/**
* @brief Safe loop through each entry in the list.
*
* @param pos [in, out] Entry node in the list.
* @param n [in, out] Next node in the list.
* @param head [in] Pointer to the list.
* @param type [in] Type of the entry.
* @param member [in] Name of the list entry in \a type.
*
* Loops safely through each entry in the list. For every iteration the next
* entry in the list is also fetched.
*/
#define nvgpu_list_for_each_entry_safe(pos, n, head, type, member) \
for ((pos) = nvgpu_list_first_entry(head, type, member), \
(n) = nvgpu_list_next_entry(pos, type, member); \

26
drivers/gpu/nvgpu/include/nvgpu/posix/circ_buf.h
View File

@@ -1,5 +1,5 @@
/*
* Copyright (c) 2018-2019, NVIDIA CORPORATION. All rights reserved.
* Copyright (c) 2018-2020, NVIDIA CORPORATION. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
@@ -25,7 +25,31 @@
#include <nvgpu/bug.h>
/**
* @brief Return count in buffer.
*
* @param head [in] Head of the buffer.
* @param tail [in] Tail of the buffer.
* @param size [in] Max number of elements in buffer.
*
* Calculates the number of elements present in the circular buffer and
* returns the value.
*
* @return Count of elements in the buffer.
*/
#define CIRC_CNT(head, tail, size) (((head) - (tail)) & ((size)-1U))
/**
* @brief Return space in buffer.
*
* @param head [in] Head of the buffer.
* @param tail [in] Tail of the buffer.
* @param size [in] Max number of elements in buffer.
*
* Calculates the space available in the circular buffer and returns the value.
*
* @return The space available in the buffer.
*/
#define CIRC_SPACE(head, tail, size) CIRC_CNT((tail), ((head)+1U), (size))
#endif /* NVGPU_POSIX_CIRC_BUF_H */

37
drivers/gpu/nvgpu/include/nvgpu/posix/log2.h
View File

@@ -25,6 +25,16 @@
#include <nvgpu/bitops.h>
/**
* @brief Integer logarithm for base 2.
*
* @param x [in] The number to get the log for.
*
* Calculates the log to the base 2 of input value \a x and returns the
* integer value of the same.
*
* @return Integer value of log to the base 2 of input \a x.
*/
#define ilog2(x) ({ \
unsigned long fls_val = nvgpu_fls(x); \
\
@@ -33,6 +43,15 @@
fls_val; \
})
/**
* @brief Round up to the power of two.
*
* @param x [in] Number to round up.
*
* Rounds up the input number \a x to power of two and returns.
*
* @return Input value \a x rounded up to the power of two.
*/
#define roundup_pow_of_two(x) \
({ \
unsigned long ret; \
@@ -46,6 +65,15 @@
ret; \
})
/**
* @brief Round down to the power of two.
*
* @param x [in] Number to round down.
*
* Rounds down the input number \a x to power of two and returns.
*
* @return Input value \a x rounded down to the power of two.
*/
#define rounddown_pow_of_two(x) \
({ \
unsigned long ret; \
@@ -59,6 +87,15 @@
ret; \
})
/**
* @brief Check for power of 2.
*
* @param x [in] Number to check.
*
* Checks if the input value \a x is a power of two or not.
*
* @return True if the input \a x is a power of two, else returns false.
*/
#define is_power_of_2(x) \
(bool)({ \
typeof(x) __x__ = (x); \