cedric pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=604d3ae8a27d4f6661d0606b115e3cf0459c1715
commit 604d3ae8a27d4f6661d0606b115e3cf0459c1715
Author: Ghislain Loaec <glo...@cadoles.com>
Date: Fri Oct 3 11:36:38 2014 +0200
eina: Eina_Cpu / Eina_Thread API documentation
---
src/lib/eina/Eina.h | 2 ++
src/lib/eina/eina_cpu.h | 84 ++++++++++++++++++++++++++++++++++++++++++++++
src/lib/eina/eina_fp.h | 71 +++++++++++++++++++++++++--------------
src/lib/eina/eina_list.h | 2 +-
src/lib/eina/eina_thread.h | 12 +++++++
5 files changed, 145 insertions(+), 26 deletions(-)
diff --git a/src/lib/eina/Eina.h b/src/lib/eina/Eina.h
index 9a8341d..bb6d325 100644
--- a/src/lib/eina/Eina.h
+++ b/src/lib/eina/Eina.h
@@ -66,6 +66,7 @@
* Linux, BSD, Opensolaris and Windows (XP and CE).
*
* The data types that are available are (see @ref Eina_Data_Types_Group):
+ * @li @ref Eina_Fp_Group standard floating point numbers.
* @li @ref Eina_Inline_Array_Group standard array of inlined members.
* @li @ref Eina_Array_Group standard array of @c void* data.
* @li @ref Eina_Hash_Group standard hash of @c void* data.
@@ -86,6 +87,7 @@
* @li @ref Eina_Benchmark_Group helper to write benchmarks.
* @li @ref Eina_Convert_Group faster conversion from strings to integers,
double, etc.
* @li @ref Eina_Counter_Group measures number of calls and their time.
+ * @li @ref Eina_Cpu_Group Cpu and architecture related helpers.
* @li @ref Eina_Error_Group error identifiers.
* @li @ref Eina_File_Group simple file list and path split.
* @li @ref Eina_Lalloc_Group simple lazy allocator.
diff --git a/src/lib/eina/eina_cpu.h b/src/lib/eina/eina_cpu.h
index e31ed76..e871774 100644
--- a/src/lib/eina/eina_cpu.h
+++ b/src/lib/eina/eina_cpu.h
@@ -19,8 +19,30 @@
#ifndef EINA_CPU_H_
#define EINA_CPU_H_
+/**
+ * @addtogroup Eina_Cpu_Group Cpu
+ *
+ * @brief Cpu and architecture related helpers
+ */
+
+/**
+ * @addtogroup Eina_Tools_Group Tools
+ *
+ * @{
+ */
+
+/**
+ * @defgroup Eina_Cpu_Group Cpu
+ *
+ * @{
+ */
+
#include "eina_types.h"
+/**
+ * @typedef Eina_Cpu_Features
+ * Enumerates different hardware architectures.
+ */
typedef enum _Eina_Cpu_Features
{
EINA_CPU_MMX = 0x00000001,
@@ -36,16 +58,78 @@ typedef enum _Eina_Cpu_Features
EINA_CPU_SSE42 = 0x00000200
} Eina_Cpu_Features;
+/**
+ * @brief Global hardware architecture handler
+ *
+ * @return the current cpu features
+ */
EAPI extern Eina_Cpu_Features eina_cpu_features;
+/**
+ * @brief Cpu features accessor
+ *
+ * @return the current cpu features
+ */
EAPI Eina_Cpu_Features eina_cpu_features_get(void);
+
+/**
+ * @brief Get the current number of precessors
+ *
+ * @return the number of processors that are online, that
+ * is available when the function is called.
+ */
EAPI int eina_cpu_count(void);
+
+/**
+ * @brief Get the current virtual page size
+ *
+ * @return the fixed length that represents the smallest unit of data for
memory
+ * allocation performed by the operating system on behalf of the program, and
+ * for transfers between the main memory and any other auxiliary store.
+ */
EAPI int eina_cpu_page_size(void);
+/**
+ * @brief Reverses the byte order of a 16-bit (destination) register.
+ *
+ * @param x The binary word to swap
+ * @return a byte order swapped 16-bit integer.
+ *
+ * On big endian systems, the number is converted to little endian byte order.
+ * On little endian systems, the number is converted to big endian byte order.
+ */
static inline unsigned short eina_swap16(unsigned short x);
+
+/**
+ * @brief Reverses the byte order of a 32-bit (destination) register.
+ *
+ * @param x The binary word to swap
+ * @return a byte order swapped 32-bit integer.
+ *
+ * On big endian systems, the number is converted to little endian byte order.
+ * On little endian systems, the number is converted to big endian byte order.
+ */
static inline unsigned int eina_swap32(unsigned int x);
+
+/**
+ * @brief Reverses the byte order of a 64-bit (destination) register.
+ *
+ * @param x The binary word to swap
+ * @return a byte order swapped 64-bit integer.
+ *
+ * On big endian systems, the number is converted to little endian byte order.
+ * On little endian systems, the number is converted to big endian byte order.
+ */
static inline unsigned long long eina_swap64(unsigned long long x);
#include "eina_inline_cpu.x"
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
+
#endif /* EINA_CPU_H_ */
diff --git a/src/lib/eina/eina_fp.h b/src/lib/eina/eina_fp.h
index 174cf0d..7a169a2 100644
--- a/src/lib/eina/eina_fp.h
+++ b/src/lib/eina/eina_fp.h
@@ -21,19 +21,19 @@
# define EINA_FP_H_
/**
- * @addtogroup Eina_Data_Types_Group Data Types
+ * @addtogroup Eina_Fp_Group Fp
*
- * @{
+ * @brief Floating point numbers data type management.
*/
/**
- * @addtogroup Eina_Containers_Group Containers
+ * @addtogroup Eina_Data_Types_Group Data Types
*
* @{
*/
/**
- * @defgroup Eina_Hash_Group Fp
+ * @defgroup Eina_Fp_Group Fp
*
* @{
*/
@@ -48,45 +48,48 @@ typedef signed int int32_t;
# include <stdint.h>
#endif
+/**
+ * @def EINA_F32P32_PI
+ * @brief Yields the 32-bit PI constant
+ */
#define EINA_F32P32_PI 0x00000003243f6a89
-
/**
* @typedef Eina_F32p32
- * Type for floating point number where the size of the integer part is 32bits
- * and the size of the decimal part is 32bits
+ * Type for floating point number where the size of the integer part is 32-bit
+ * and the size of the decimal part is 32-bit
*/
typedef int64_t Eina_F32p32;
/**
* @typedef Eina_F16p16
- * Type for floating point number where the size of the integer part is 16bits
- * and the size of the decimal part is 16bits
+ * Type for floating point number where the size of the integer part is 16-bit
+ * and the size of the decimal part is 16-bit
*/
typedef int32_t Eina_F16p16;
/**
* @typedef Eina_F8p24
- * Type for floating point number where the size of the integer part is 8bits
+ * Type for floating point number where the size of the integer part is 8-bit
* and the size of the decimal part is 24bits
*/
typedef int32_t Eina_F8p24;
/**
- * @brief Create a new Eina_F32p32 floating point number from standard 32 bits
+ * @brief Create a new Eina_F32p32 floating point number from standard 32-bit
* integer
*
- * @param v 32bits integer value to convert
+ * @param v 32-bit integer value to convert
* @return The value converted into Eina_F32p32 format
*/
static inline Eina_F32p32 eina_f32p32_int_from(int32_t v);
/**
- * @brief Create a new standard 32bits integer from Eina_F32p32 floating point
+ * @brief Create a new standard 32-bit integer from Eina_F32p32 floating point
* number
*
* @param v Eina_F32p32 value to convert
- * @return The value converted into 32bits integer
+ * @return The value converted into 32-bit integer
*/
static inline int32_t eina_f32p32_int_to(Eina_F32p32 v);
@@ -175,7 +178,14 @@ static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a);
*/
static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v);
-// dont use llabs - issues if not on 64bit
+/**
+ * @brief Get the absolute value of an Eina_F32p32 floating point number
+ *
+ * @param a The floating point number
+ * @return The absolute value for the number @p a
+ * @warning Has known issues on 64-bit architecture, prefer
+ * eina_f32p32_fracc_get() instead
+ */
#define eina_fp32p32_llabs(a) ((a < 0) ? -(a) : (a))
/**
@@ -195,24 +205,35 @@ EAPI Eina_F32p32 eina_f32p32_cos(Eina_F32p32 a);
EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a);
+/**
+ * @def EINA_F16P16_ONE
+ *
+ * Yields the maximum 16-bit unsigned integer size (= 65536)
+ */
#define EINA_F16P16_ONE (1 << 16)
+
+/**
+ * @def EINA_F16P16_HALF
+ *
+ * Yields the maximum 16-bit signed integer size (= 32768)
+ */
#define EINA_F16P16_HALF (1 << 15)
/**
- * @brief Create a new Eina_F16p316 floating point number from standard 32 bits
+ * @brief Create a new Eina_F16p316 floating point number from standard 32-bit
* integer
*
- * @param v 32bits integer value to convert
+ * @param v 32-bit integer value to convert
* @return The value converted into Eina_F16p16 format
*/
static inline Eina_F16p16 eina_f16p16_int_from(int32_t v);
/**
- * @brief Create a new standard 32bits integer from Eina_F16p16 floating point
+ * @brief Create a new standard 32-bit integer from Eina_F16p16 floating point
* number
*
* @param v Eina_F16p16 value to convert
- * @return The value converted into 32bits integer
+ * @return The value converted into 32-bit integer
*/
static inline int32_t eina_f16p16_int_to(Eina_F16p16 v);
@@ -315,20 +336,20 @@ static inline unsigned int
eina_f16p16_fracc_get(Eina_F16p16 v);
/**
- * @brief Create a new Eina_F16p316 floating point number from standard 32 bits
+ * @brief Create a new Eina_F16p316 floating point number from standard 32-bit
* integer
*
- * @param v 32bits integer value to convert
+ * @param v 32-bit integer value to convert
* @return The value converted into Eina_F8p24 format
*/
static inline Eina_F8p24 eina_f8p24_int_from(int32_t v);
/**
- * @brief Create a new standard 32bits integer from Eina_F8p24 floating point
+ * @brief Create a new standard 32-bit integer from Eina_F8p24 floating point
* number
*
* @param v Eina_F8p24 value to convert
- * @return The value converted into 32bits integer
+ * @return The value converted into 32-bit integer
*/
static inline int32_t eina_f8p24_int_to(Eina_F8p24 v);
@@ -341,8 +362,7 @@ static inline int32_t eina_f8p24_int_to(Eina_F8p24 v);
static inline Eina_F8p24 eina_f8p24_float_from(float v);
/**
- * @brief Create a new standard float from Eina_F8p24 floating point
- * number
+ * @brief Create a new standard float from Eina_F8p24 floating point number
*
* @param v Eina_F8p24 value to convert
* @return The value converted into float
@@ -472,4 +492,5 @@ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16
a);
/**
* @}
*/
+
#endif
diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h
index a32a114..91de6ea 100644
--- a/src/lib/eina/eina_list.h
+++ b/src/lib/eina/eina_list.h
@@ -1276,7 +1276,7 @@ static inline unsigned int eina_list_count(const
Eina_List *list) EINA_PURE;
* This macro is a shortcut for typing eina_list_data_get(eina_list_last())
* @since 1.8
*/
-static inline void *eina_list_last_data_get(const Eina_List *list)
+static inline void *eina_list_last_data_get(const Eina_List *list);
/**
* @brief Returned a new iterator associated to a list.
diff --git a/src/lib/eina/eina_thread.h b/src/lib/eina/eina_thread.h
index 3e89ea9..3ad5486 100644
--- a/src/lib/eina/eina_thread.h
+++ b/src/lib/eina/eina_thread.h
@@ -42,10 +42,22 @@
* @{
*/
+/**
+ * @typedef Eina_Thread
+ * Type for a generic thread.
+ */
typedef unsigned long int Eina_Thread;
+/**
+ * @typedef Eina_Thread_Cb
+ * Type for the definition of a thread callback function
+ */
typedef void *(*Eina_Thread_Cb)(void *data, Eina_Thread t);
+/**
+ * @typedef Eina_Thead_Priority
+ * Type to enumerate different thread priorities
+ */
typedef enum _Eina_Thread_Priority
{
EINA_THREAD_URGENT,
--
