Unresolved symbols

[brmarkus]

The documentation says

make # builds libfacex.a + facex-cli
make example # builds and runs example
make encrypt # builds weight encryption tool
Requirements: GCC with AVX2 support. Nothing else.

Cross-compile for Linux (from WSL)
gcc -O3 -march=x86-64-v3 -mavx2 -mfma -static
-DFACEX_LIB -o libfacex.a src/*.c -lm -lpthread

I'm using "Ubuntu 24.04.4 LTS" with "gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0" - natively, no Docker, no WSL.

I'm using a SoC "Intel(R) Core(TM) Ultra 9 185H".

And calling make from the project's root folder.

The following build command line gets printed as an example:

cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -DFACEX_LIB -c src/facex.c -o facex.o

After getting a couple of compiler warnings the build finally fails with linker errors:

/usr/bin/ld: /tmp/ccl7oGij.o: in function `v2_engine_init':
edgeface_engine_v2.c:(.text+0x36ce): undefined reference to `conv2d_hwc_reorder_weights'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x3719): undefined reference to `conv2d_hwc_reorder_weights'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x374c): undefined reference to `conv2d_hwc_reorder_weights'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x3d4e): undefined reference to `conv2d_hwc_reorder_weights'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x3d7b): undefined reference to `conv2d_hwc_reorder_weights'
/usr/bin/ld: /tmp/ccl7oGij.o:edgeface_engine_v2.c:(.text+0x3db5): more undefined references to `conv2d_hwc_reorder_weights' follow
/usr/bin/ld: /tmp/ccl7oGij.o: in function `v2_engine_forward':
edgeface_engine_v2.c:(.text+0x4d06): undefined reference to `convnext_block'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x595d): undefined reference to `conv2d_hwc'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x5a88): undefined reference to `xca_block'
collect2: error: ld returned 1 exit status
make: *** [Makefile:71: facex-v2] Error 1

I needed to remove/comment out static from those complained undefined reference method definitions:

diff --git a/download_weights.sh b/download_weights.sh
old mode 100644
new mode 100755
diff --git a/src/edgeface_engine.c b/src/edgeface_engine.c
index 1b19781..14abaee 100644
--- a/src/edgeface_engine.c
+++ b/src/edgeface_engine.c
@@ -221,7 +221,7 @@ static void xca_dw_conv_nchw(const float* in_nchw, int C, int H, int W,
     }
 }

-static void xca_block(float* x_hwc, int H, int W, int C,
+/*static*/ void xca_block(float* x_hwc, int H, int W, int C,
                       const float* gamma_xca, const float* gamma,
                       /* DW conv for split heads */
                       int n_dw_splits, const int* dw_split_sizes,
@@ -451,7 +451,7 @@ static void xca_block(float* x_hwc, int H, int W, int C,
  * AVX2 optimized: vectorize across output channels (Cout). */
 /* conv2d_hwc with pre-transposed weights in [Cin*KK, Cout] layout.
  * At load time, call conv2d_hwc_reorder_weights() to transpose OIHW → [Cin*KK, Cout]. */
-static void conv2d_hwc_reorder_weights(float* w, int Cout, int Cin, int KK) {
+/*static*/ void conv2d_hwc_reorder_weights(float* w, int Cout, int Cin, int KK) {
     /* In-place transpose from [Cout, Cin*KK] to [Cin*KK, Cout] */
     float* tmp = (float*)malloc((size_t)Cout * Cin * KK * sizeof(float));
     memcpy(tmp, w, (size_t)Cout * Cin * KK * sizeof(float));
@@ -461,7 +461,7 @@ static void conv2d_hwc_reorder_weights(float* w, int Cout, int Cin, int KK) {
     free(tmp);
 }

-static void conv2d_hwc(const float* in_hwc, int Cin, int H, int W,
+/*static*/ void conv2d_hwc(const float* in_hwc, int Cin, int H, int W,
                        const float* w, /* REORDERED to [Cin*KK, Cout] */
                        const float* b, int Cout, int K, int stride,
                        float* out_hwc) {
@@ -618,7 +618,7 @@ static void _mlp_rows(void* ctx_, int start, int end) {

 /* ============ ConvNeXt Block (HWC in/out, NCHW for DW) ============ */
 /* x[HW,C] → LN → DW Conv → gamma*x → LN → MLP(4 MatMul) → +residual */
-static void convnext_block(float* x_hwc, int H, int W, int C,
+/*static*/ void convnext_block(float* x_hwc, int H, int W, int C,
                            const float* gamma,
                            const float* dw_w, const float* dw_b, int K,
                            const float* ln_w, const float* ln_b,

[brmarkus]

Can't built the examples using make example:

$ make example
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -o facex-example examples/example.c -L. -lfacex -lm -lpthread
examples/example.c: In function ‘main’:
examples/example.c:18:17: error: too few arguments to function ‘facex_init’
   18 |     FaceX* fx = facex_init(weights, NULL);
      |                 ^~~~~~~~~~
In file included from examples/example.c:10:
include/facex.h:46:8: note: declared here
   46 | FaceX* facex_init(const char* embed_weights, const char* detect_weights, const char* license_key);
      |        ^~~~~~~~~~
make: *** [Makefile:51: facex-example] Error 1

Manually calling make mfn-cli works.

[brmarkus]

Tests:

$ ./facex-mfn data/edgeface_xs_fp32.bin
init failed: -12

What does "-12" mean?

$ ./facex-cli
Illegal instruction (core dumped)

Trying to use AVX512 instructions on an SoC without AVX512 instruction set?

$ ./facex-v2 data/edgeface_xs_fp32.bin
init failed: -12

What does "-12" mean?

[brmarkus]

The test target results in undefined reference errors, too:

$ make test
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -o golden-test tests/golden_test.c -L. -lfacex -lm -lpthread
/usr/bin/ld: ./libfacex.a(facex.o): in function `engine_init':
facex.c:(.text+0xf1): undefined reference to `weight_decrypt_inplace'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_init':
facex.c:(.text+0x19947): undefined reference to `detect_init'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_detect':
facex.c:(.text+0x19a51): undefined reference to `detect_run'
/usr/bin/ld: facex.c:(.text+0x19acd): undefined reference to `align_face'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_free':
facex.c:(.text+0x1a157): undefined reference to `detect_free'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_set_score_threshold':
facex.c:(.text+0x1a1b3): undefined reference to `detect_set_score_threshold'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_set_nms_threshold':
facex.c:(.text+0x1a1e3): undefined reference to `detect_set_nms_threshold'
collect2: error: ld returned 1 exit status
make: *** [Makefile:65: golden-test] Error 1

From the Makefile:

# Golden test
test: golden-test$(EXT)
	@echo "Running golden test..."
	@./golden-test$(EXT) data/edgeface_xs_fp32.bin

golden-test$(EXT): tests/golden_test.c libfacex.a
	$(CC) $(CFLAGS) -Iinclude -o $@ $< -L. -lfacex $(LDFLAGS)

Shouldn't src/edgeface_engine.c and/or src/edgeface_engine_v2.c be added to the list of source files (similar to e.g. facex-v2$(EXT))?

[brmarkus]

When commenting-out the AVX512 test in the Makefile then I won't get the "Illegal instruction" signal anymore:

$ ./facex-cli > result.raw
EdgeFace-XS forward: 2.63 ms
Embedding[0..4]: 0.0171 0.0087 -0.0057 0.0307 0.0127

Doing the AVX512 "test" manually reveals:

$ gcc -mavx512f -dM -E - < /dev/null 2>/dev/null | grep -c AVX512F
1

[bauratynov]

Hey @brmarkus — sorry about that, you hit a real bug, fixed in 001e9fc.

What happened: conv2d_hwc_reorder_weights is defined in src/edgeface_engine.c and used from src/edgeface_engine_v2.c (declared extern there). The definition was marked static though, which gives it internal linkage — gcc rightly complained that no other translation unit can see it. Removing the static fixes the cross-file reference. Older GCCs (≤11) sometimes inlined the call into the same TU as a side-effect of LTO and hid the bug; gcc 13 with stricter inter-procedural analysis surfaces it cleanly.

Pull main and rebuild:

git pull
make clean && make

If it still trips, paste the full output — there might be a second symbol I missed.

Bonus tip for the Core Ultra 9 185H: that's Meteor Lake with AVX2 + AVX-VNNI but no AVX-512. Our build script auto-detects and disables the AVX-512 paths, so you get the AVX2 INT8 kernel. The Ultra 9 hits about 3.5 ms / face on a single P-core in our internal benches — quite a bit faster than the Xeon Gold reference. Would love a number from you when you have the build running.

[brmarkus]

Thanks for the update.
As shown by the "patch" above, also other symbols cannot be found (stopping at a failing target; other targets are not tried to get built):

$ make
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -DFACEX_LIB -c src/facex.c -o facex.o
In file included from src/facex.c:18:
src/edgeface_engine.c: In function ‘load_weights’:
src/edgeface_engine.c:80:5: warning: ignoring return value of ‘fread’ declared with attribute ‘warn_unused_result’ [-Wunused-result]
   80 |     fread(w->raw, 1, w->raw_size, f);
      |     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -c src/transformer_ops.c -o transformer_ops.o
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -c src/gemm_int8_4x8c8.c -o gemm_int8_4x8c8.o
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -c src/threadpool.c -o threadpool.o
ar rcs libfacex.a facex.o transformer_ops.o gemm_int8_4x8c8.o threadpool.o
Built libfacex.a
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -o facex-cli src/edgeface_engine.c src/transformer_ops.c src/gemm_int8_4x8c8.c src/threadpool.c src/weight_crypto.c -lm -lpthread
src/edgeface_engine.c: In function ‘load_weights’:
src/edgeface_engine.c:80:5: warning: ignoring return value of ‘fread’ declared with attribute ‘warn_unused_result’ [-Wunused-result]
   80 |     fread(w->raw, 1, w->raw_size, f);
      |     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
src/weight_crypto.c: In function ‘get_machine_id’:
src/weight_crypto.c:191:14: warning: ignoring return value of ‘fgets’ declared with attribute ‘warn_unused_result’ [-Wunused-result]
  191 |     if (f) { fgets(buf, maxlen, f); fclose(f); buf[strcspn(buf,"\n")] = 0; }
      |              ^~~~~~~~~~~~~~~~~~~~~
src/weight_crypto.c: In function ‘weight_encrypt_file’:
src/weight_crypto.c:237:5: warning: ignoring return value of ‘fread’ declared with attribute ‘warn_unused_result’ [-Wunused-result]
  237 |     fread(data, 1, len, fin);
      |     ^~~~~~~~~~~~~~~~~~~~~~~~
Built facex-cli
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -c src/detect.c -o detect.o
ar rcs libdetect.a detect.o
Built libdetect.a
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -DV2_STANDALONE -DFACEX_LIB -Iinclude -o facex-v2 src/edgeface_engine_v2.c src/edgeface_engine.c src/transformer_ops.c src/gemm_int8_4x8c8.c src/threadpool.c -lm -lpthread
src/edgeface_engine_v2.c: In function ‘v2_engine_forward’:
src/edgeface_engine_v2.c:659:40: warning: passing argument 10 of ‘xca_block’ discards ‘const’ qualifier from pointer target type [-Wdiscarded-qualifiers]
  659 |                       s->n_dw_convs, xc->dw_ws, xc->dw_bs, s->xca_dw_kernel,
      |                                      ~~^~~~~~~
src/edgeface_engine_v2.c:64:53: note: expected ‘const float **’ but argument is of type ‘const float * const*’
   64 |                       int n_dw_convs, const float** dw_ws, const float** dw_bs, int dw_K,
      |                                       ~~~~~~~~~~~~~~^~~~~
src/edgeface_engine_v2.c:659:51: warning: passing argument 11 of ‘xca_block’ discards ‘const’ qualifier from pointer target type [-Wdiscarded-qualifiers]
  659 |                       s->n_dw_convs, xc->dw_ws, xc->dw_bs, s->xca_dw_kernel,
      |                                                 ~~^~~~~~~
src/edgeface_engine_v2.c:64:74: note: expected ‘const float **’ but argument is of type ‘const float * const*’
   64 |                       int n_dw_convs, const float** dw_ws, const float** dw_bs, int dw_K,
      |                                                            ~~~~~~~~~~~~~~^~~~~
/usr/bin/ld: /tmp/cciKeEzL.o: in function `v2_engine_forward':
edgeface_engine_v2.c:(.text+0x4d06): undefined reference to `convnext_block'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x595d): undefined reference to `conv2d_hwc'
/usr/bin/ld: edgeface_engine_v2.c:(.text+0x5a88): undefined reference to `xca_block'
collect2: error: ld returned 1 exit status
make: *** [Makefile:71: facex-v2] Error 1

=> convnext_block
=> conv2d_hwc
=> xca_block

-static void xca_block(float* x_hwc, int H, int W, int C,
+/*static*/ void xca_block(float* x_hwc, int H, int W, int C,

-static void conv2d_hwc_reorder_weights(float* w, int Cout, int Cin, int KK) {
+/*static*/ void conv2d_hwc_reorder_weights(float* w, int Cout, int Cin, int KK) {

-static void conv2d_hwc(const float* in_hwc, int Cin, int H, int W,
+/*static*/ void conv2d_hwc(const float* in_hwc, int Cin, int H, int W,

-static void convnext_block(float* x_hwc, int H, int W, int C,
+/*static*/ void convnext_block(float* x_hwc, int H, int W, int C,

Can you also have a look into the failing examples, please?

$ make example
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -o facex-example examples/example.c -L. -lfacex -lm -lpthread
examples/example.c: In function ‘main’:
examples/example.c:18:17: error: too few arguments to function ‘facex_init’
   18 |     FaceX* fx = facex_init(weights, NULL);
      |                 ^~~~~~~~~~
In file included from examples/example.c:10:
include/facex.h:46:8: note: declared here
   46 | FaceX* facex_init(const char* embed_weights, const char* detect_weights, const char* license_key);
      |        ^~~~~~~~~~
make: *** [Makefile:51: facex-example] Error 1

$ make mfn-example
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -o example_mfn examples/example_mfn.c src/facex_mfn.c -lm -lpthread
examples/example_mfn.c: In function ‘main’:
examples/example_mfn.c:26:15: error: storage size of ‘engine’ isn’t known
   26 |     MfnEngine engine;
      |               ^~~~~~
make: *** [Makefile:85: example_mfn] Error 1

There are even more unresolved symbols when trying to get and run the tests:

$ make test
cc -O3 -march=native -mfma -funroll-loops -mavx512f -mavx512vnni -mprefer-vector-width=512 -Iinclude -o golden-test tests/golden_test.c -L. -lfacex -lm -lpthread
/usr/bin/ld: ./libfacex.a(facex.o): in function `engine_init':
facex.c:(.text+0xf1): undefined reference to `weight_decrypt_inplace'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_init':
facex.c:(.text+0x11bb7): undefined reference to `detect_init'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_detect':
facex.c:(.text+0x11cc1): undefined reference to `detect_run'
/usr/bin/ld: facex.c:(.text+0x11d3d): undefined reference to `align_face'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_free':
facex.c:(.text+0x123c7): undefined reference to `detect_free'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_set_score_threshold':
facex.c:(.text+0x12423): undefined reference to `detect_set_score_threshold'
/usr/bin/ld: ./libfacex.a(facex.o): in function `facex_set_nms_threshold':
facex.c:(.text+0x12453): undefined reference to `detect_set_nms_threshold'
collect2: error: ld returned 1 exit status
make: *** [Makefile:65: golden-test] Error 1

It looks like the detection (i.e. not suported AVX512 instructions) seems not working:

$ ./facex-cli
Illegal instruction (core dumped)

When I comment-out the AVX512 "detection" in Makefile, then the executable is running:

## Detect AVX-512
#AVX512 := $(shell $(CC) -mavx512f -dM -E - < /dev/null 2>/dev/null | grep -c AVX512F)
#ifeq ($(AVX512),1)
#  CFLAGS += -mavx512f -mavx512vnni -mprefer-vector-width=512
#endif

$ ./facex-cli
EdgeFace-XS forward: 2.55 ms
Embedding[0..4]: 0.0171 0.0087 -0.0057 0.0307 0.0127