Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

hide x86 dispatcher internals #869

Merged
merged 2 commits into from
Jul 16, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ OUTPUT_DIRECTORY = doxygen
OUTPUT_LANGUAGE = English

# We already separate the internal docs.
INTERNAL_DOCS = YES
INTERNAL_DOCS = NO
# Consistency
SORT_MEMBER_DOCS = NO
BRIEF_MEMBER_DESC = YES
Expand All @@ -28,8 +28,10 @@ MARKDOWN_SUPPORT = YES

# xxHash is a C library
OPTIMIZE_OUTPUT_FOR_C = YES
# So we can document the internals
EXTRACT_STATIC = YES
# We hide private part from public document
EXTRACT_STATIC = NO
# We hide private part from public document
EXTRACT_PRIVATE = NO
# Document the macros
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
Expand Down
63 changes: 63 additions & 0 deletions Doxyfile-internal
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Doxygen config for xxHash
DOXYFILE_ENCODING = UTF-8

PROJECT_NAME = "xxHash"
PROJECT_NUMBER = "0.8.2"
PROJECT_BRIEF = "Extremely fast non-cryptographic hash function"
OUTPUT_DIRECTORY = doxygen
OUTPUT_LANGUAGE = English

# We already separate the internal docs.
INTERNAL_DOCS = YES
# Consistency
SORT_MEMBER_DOCS = NO
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES

# Warnings
QUIET = YES
# Until we document everything
WARN_IF_UNDOCUMENTED = NO

# TODO: Add the other files. It is just xxhash.h for now.
FILE_PATTERNS = xxhash.h xxh_x86dispatch.c
# Note: xxHash's source files are technically ASCII only.
INPUT_ENCODING = UTF-8
TAB_SIZE = 4
MARKDOWN_SUPPORT = YES

# xxHash is a C library
OPTIMIZE_OUTPUT_FOR_C = YES
# So we can document the internals
EXTRACT_STATIC = YES
# We show private part in the internal document
EXTRACT_PRIVATE = YES
# Document the macros
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
# Predefine some macros to clean up the output.
PREDEFINED = "XXH_DOXYGEN=" \
"XXH_PUBLIC_API=" \
"XXH_FORCE_INLINE=static inline" \
"XXH_NO_INLINE=static" \
"XXH_RESTRICT=restrict" \
"XSUM_API=" \
"XXH_STATIC_LINKING_ONLY" \
"XXH_IMPLEMENTATION" \
"XXH_PUREF=[[gnu::pure]]" \
"XXH_CONSTF=[[gnu::const]]" \
"XXH_MALLOCF=[[gnu::malloc]]" \
"XXH_ALIGN(N)=alignas(N)" \
"XXH_ALIGN_MEMBER(align,type)=alignas(align) type"

# We want HTML docs
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
# Tweak the colors a bit
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_GAMMA = 100
HTML_COLORSTYLE_SAT = 100

# We don't want LaTeX.
GENERATE_LATEX = NO
46 changes: 37 additions & 9 deletions xxh_x86dispatch.c
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,15 @@ extern "C" {
# error "Dispatching is currently only supported on x86 and x86_64."
#endif

/*! @cond Doxygen ignores this part */
#ifndef XXH_HAS_INCLUDE
# ifdef __has_include
# define XXH_HAS_INCLUDE(x) __has_include(x)
# else
# define XXH_HAS_INCLUDE(x) 0
# endif
#endif
/*! @endcond */

/*!
* @def XXH_X86DISPATCH_ALLOW_AVX
Expand Down Expand Up @@ -175,6 +177,7 @@ extern "C" {
*
* @def XXH_TARGET_AVX512
* @brief Like @ref XXH_TARGET_SSE2, but for AVX512.
*
*/
#if defined(__GNUC__)
# include <emmintrin.h> /* SSE2 */
Expand Down Expand Up @@ -205,6 +208,7 @@ extern "C" {
# error "Dispatching is currently not supported for your compiler."
#endif

/*! @cond Doxygen ignores this part */
#ifdef XXH_DISPATCH_DEBUG
/* debug logging */
# include <stdio.h>
Expand All @@ -214,6 +218,7 @@ extern "C" {
# undef NDEBUG /* avoid redefinition */
# define NDEBUG
#endif
/*! @endcond */
#include <assert.h>

#ifndef XXH_DOXYGEN
Expand All @@ -222,23 +227,28 @@ extern "C" {
#include "xxhash.h"
#endif

/*! @cond Doxygen ignores this part */
#ifndef XXH_HAS_ATTRIBUTE
# ifdef __has_attribute
# define XXH_HAS_ATTRIBUTE(...) __has_attribute(__VA_ARGS__)
# else
# define XXH_HAS_ATTRIBUTE(...) 0
# endif
#endif
/*! @endcond */

/*! @cond Doxygen ignores this part */
#if XXH_HAS_ATTRIBUTE(constructor)
# define XXH_CONSTRUCTOR __attribute__((constructor))
# define XXH_DISPATCH_MAYBE_NULL 0
#else
# define XXH_CONSTRUCTOR
# define XXH_DISPATCH_MAYBE_NULL 1
#endif
/*! @endcond */


/*! @cond Doxygen ignores this part */
/*
* Support both AT&T and Intel dialects
*
Expand All @@ -256,9 +266,10 @@ extern "C" {
#else
# define XXH_I_ATT(intel, att) "{" att "|" intel "}\n\t"
#endif
/*! @endcond */

/*!
* @internal
* @private
* @brief Runs CPUID.
*
* @param eax , ecx The parameters to pass to CPUID, %eax and %ecx respectively.
Expand Down Expand Up @@ -301,7 +312,7 @@ static void XXH_cpuid(xxh_u32 eax, xxh_u32 ecx, xxh_u32* abcd)

#if XXH_DISPATCH_AVX2 || XXH_DISPATCH_AVX512
/*!
* @internal
* @private
* @brief Runs `XGETBV`.
*
* While the CPU may support AVX2, the operating system might not properly save
Expand Down Expand Up @@ -335,15 +346,17 @@ static xxh_u64 XXH_xgetbv(void)
}
#endif

/*! @cond Doxygen ignores this part */
#define XXH_SSE2_CPUID_MASK (1 << 26)
#define XXH_OSXSAVE_CPUID_MASK ((1 << 26) | (1 << 27))
#define XXH_AVX2_CPUID_MASK (1 << 5)
#define XXH_AVX2_XGETBV_MASK ((1 << 2) | (1 << 1))
#define XXH_AVX512F_CPUID_MASK (1 << 16)
#define XXH_AVX512F_XGETBV_MASK ((7 << 5) | (1 << 2) | (1 << 1))
/*! @endcond */

/*!
* @internal
* @private
* @brief Returns the best XXH3 implementation.
*
* Runs various CPUID/XGETBV tests to try and determine the best implementation.
Expand Down Expand Up @@ -473,15 +486,17 @@ static int XXH_featureTest(void)

/* === Vector implementations === */

/*! @cond PRIVATE */
/*!
* @internal
* @private
* @brief Defines the various dispatch functions.
*
* TODO: Consolidate?
*
* @param suffix The suffix for the functions, e.g. sse2 or scalar
* @param target XXH_TARGET_* or empty.
*/

#define XXH_DEFINE_DISPATCH_FUNCS(suffix, target) \
\
/* === XXH3, default variants === */ \
Expand Down Expand Up @@ -567,8 +582,10 @@ XXHL128_seed_##suffix(XXH_NOESCAPE const void* XXH_RESTRICT input, size_t len,\
XXH3_initCustomSecret_##suffix); \
}

/*! @endcond */
/* End XXH_DEFINE_DISPATCH_FUNCS */

/*! @cond Doxygen ignores this part */
#if XXH_DISPATCH_SCALAR
XXH_DEFINE_DISPATCH_FUNCS(scalar, /* nothing */)
#endif
Expand All @@ -580,9 +597,11 @@ XXH_DEFINE_DISPATCH_FUNCS(avx2, XXH_TARGET_AVX2)
XXH_DEFINE_DISPATCH_FUNCS(avx512, XXH_TARGET_AVX512)
#endif
#undef XXH_DEFINE_DISPATCH_FUNCS
/*! @endcond */

/* ==== Dispatchers ==== */

/*! @cond Doxygen ignores this part */
typedef XXH64_hash_t (*XXH3_dispatchx86_hashLong64_default)(XXH_NOESCAPE const void* XXH_RESTRICT, size_t);

typedef XXH64_hash_t (*XXH3_dispatchx86_hashLong64_withSeed)(XXH_NOESCAPE const void* XXH_RESTRICT, size_t, XXH64_hash_t);
Expand All @@ -599,9 +618,10 @@ typedef struct {
} XXH_dispatchFunctions_s;

#define XXH_NB_DISPATCHES 4
/*! @endcond */

/*!
* @internal
* @private
* @brief Table of dispatchers for @ref XXH3_64bits().
*
* @pre The indices must match @ref XXH_VECTOR_TYPE.
Expand All @@ -625,12 +645,13 @@ static const XXH_dispatchFunctions_s XXH_kDispatch[XXH_NB_DISPATCHES] = {
#endif
};
/*!
* @internal
* @private
* @brief The selected dispatch table for @ref XXH3_64bits().
*/
static XXH_dispatchFunctions_s XXH_g_dispatch = { NULL, NULL, NULL, NULL };


/*! @cond Doxygen ignores this part */
typedef XXH128_hash_t (*XXH3_dispatchx86_hashLong128_default)(XXH_NOESCAPE const void* XXH_RESTRICT, size_t);

typedef XXH128_hash_t (*XXH3_dispatchx86_hashLong128_withSeed)(XXH_NOESCAPE const void* XXH_RESTRICT, size_t, XXH64_hash_t);
Expand All @@ -643,10 +664,11 @@ typedef struct {
XXH3_dispatchx86_hashLong128_withSecret hashLong128_secret;
XXH3_dispatchx86_update update;
} XXH_dispatch128Functions_s;
/*! @endcond */


/*!
* @internal
* @private
* @brief Table of dispatchers for @ref XXH3_128bits().
*
* @pre The indices must match @ref XXH_VECTOR_TYPE.
Expand All @@ -671,13 +693,13 @@ static const XXH_dispatch128Functions_s XXH_kDispatch128[XXH_NB_DISPATCHES] = {
};

/*!
* @internal
* @private
* @brief The selected dispatch table for @ref XXH3_64bits().
*/
static XXH_dispatch128Functions_s XXH_g_dispatch128 = { NULL, NULL, NULL, NULL };

/*!
* @internal
* @private
* @brief Runs a CPUID check and sets the correct dispatch tables.
*/
static XXH_CONSTRUCTOR void XXH_setDispatch(void)
Expand All @@ -700,6 +722,7 @@ static XXH_CONSTRUCTOR void XXH_setDispatch(void)


/* ==== XXH3 public functions ==== */
/*! @cond Doxygen ignores this part */

static XXH64_hash_t
XXH3_hashLong_64b_defaultSecret_selection(const void* input, size_t len,
Expand Down Expand Up @@ -755,8 +778,11 @@ XXH3_64bits_update_dispatch(XXH_NOESCAPE XXH3_state_t* state, XXH_NOESCAPE const
return XXH_g_dispatch.update(state, (const xxh_u8*)input, len);
}

/*! @endcond */


/* ==== XXH128 public functions ==== */
/*! @cond Doxygen ignores this part */

static XXH128_hash_t
XXH3_hashLong_128b_defaultSecret_selection(const void* input, size_t len,
Expand Down Expand Up @@ -811,6 +837,8 @@ XXH3_128bits_update_dispatch(XXH_NOESCAPE XXH3_state_t* state, XXH_NOESCAPE cons
return XXH_g_dispatch128.update(state, (const xxh_u8*)input, len);
}

/*! @endcond */

#if defined (__cplusplus)
}
#endif
Expand Down
1 change: 1 addition & 0 deletions xxhash.h
Original file line number Diff line number Diff line change
Expand Up @@ -1493,6 +1493,7 @@ struct XXH64_state_s {
#define XXH3_INTERNALBUFFER_SIZE 256

/*!
* @internal
* @brief Default size of the secret buffer (and @ref XXH3_kSecret).
*
* This is the size used in @ref XXH3_kSecret and the seeded functions.
Expand Down