Project 5.03 Section 5 ⚡ Embedded Relevance: High Overloading Name Mangling extern "C" Linker Symbols FreeRTOS

5.03 C++ Name Mangling, Type Ambiguity & Integrating C RTOS APIs with extern "C"

Executive Summary: Analyzing function overloading in C++. We examine compiler name mangling, resolving ambiguous type promotions, and how to use extern "C" to bridge modern C++ applications with C-based microcontroller HALs and RTOS kernels (e.g. FreeRTOS, STM32 HAL).

💻 1. Annotated Source Code

#include <iostream>
#include <string>
using namespace std;

int getResult(int num1, int num2);
string getResult(string str1, string str2);
int getResult(int num);  

int main() {

	int resultNum = getResult(30, 20);
	string nameResult = getResult("John", "Baugh");
	int cubeResult = getResult(5);

	cout << "result num is " << resultNum << endl;
	cout << "name result is " << nameResult << endl;
	cout << "cube result is " << cubeResult << endl;

	return 0;
}

int getResult(int num1, int num2) {
	return num1 * num2;
}

string getResult(string str1, string str2) {
	return str1 + " " + str2;
}

int getResult(int num) {
	return num * num * num;
}

📐 2. Architecture & UML Class Model

📐 Function Overloading & C++ Name Mangling Architecture

+ Public - Private # Protected

<<compilation-unit>> OverloadDispatchTable Mangled Symbol Table

Attributes / Data Members

(none / stateless)

Operations / Methods

+print(val: int) : void[_Z5printi]

+print(val: double) : void[_Z5printd]

+print(val: string) : void[_Z5printNSt7__cxx1112basic_string...]

+extern "C" c_compatible_print(val: int) : void[c_compatible_print]

📚 3. Core C++ Concepts Deep-Dive

1. Function Overloading Resolution

Functions can share the same name if their parameter lists differ in count, types, or constness. Return type alone is insufficient to overload a function.

2. C++ Name Mangling

To differentiate overloaded functions at the object-file level, the C++ compiler encodes parameter types into the symbol name in the compiled binary (e.g., _Z8transmiti vs _Z8transmitPKc).

⚡ 4. Embedded Systems & Hardware Reality

1. Interfacing with C Microcontroller HALs (`extern "C"`)

Most hardware vendor libraries (STM32 CubeHAL, ESP-IDF, FreeRTOS) are written in C. Because C compilers do not mangle symbol names, C++ code calling C functions—or C code calling C++ interrupt handlers—must be wrapped in extern "C" to disable name mangling.

💡 5. Production-Ready Embedded Refactoring

Robust C/C++ compatible header wrapper:

💡 Production-Ready Refactor

#ifdef __cplusplus
extern "C" {
#endif

// Hardware ISR handler (must match C symbol name for vector table)
void USART1_IRQHandler(void);

// FreeRTOS Task Entry Point
void vSensorTask(void* pvParameters);

#ifdef __cplusplus
}
#endif

📝 Knowledge Verification Quiz

Test your understanding of the C++ concepts and embedded microcontroller trade-offs covered in this guide. Click any option for instant feedback.

Q1. Why does C++ perform 'name mangling' on function symbols?

A To encode parameter types into symbol names, allowing linkers to distinguish between overloaded functions with the same name

B To encrypt proprietary algorithm code

C To compress binary Flash file sizes

D To force functions to run at higher CPU priorities

Detailed Explanation: Name mangling generates unique symbol names based on function signatures, enabling the linker to bind overloaded function calls accurately.

Q2. What is the purpose of 'extern "C"' when writing C++ firmware?

A It disables C++ name mangling for enclosed functions, enabling seamless linking with C libraries and hardware ISR vector tables

B It forces the compiler to compile in C89 mode only

C It allocates functions in external Flash memory

D It allows C++ classes to have virtual destructors

Detailed Explanation: extern "C" instructs the C++ compiler to emit unmangled C symbol names, enabling interoperability with C HALs and hardware vector tables.

Q3. Can two functions differ ONLY by their return type be overloaded in C++?

A No, return type alone is not sufficient to differentiate overloaded functions in C++

B Yes, the compiler determines which to call based on the assignment target

C Yes, but only if both functions are constexpr

D Yes, if compiled with -O3

Detailed Explanation: C++ requires parameter lists to differ; return type alone cannot be used by the compiler to resolve function calls.

Q4. What happens if a hardware Interrupt Service Routine (e.g. SysTick_Handler) in C++ is NOT declared extern "C"?

A The linker fails to match the mangled C++ symbol with the raw symbol in the vector table, causing the default handler or HardFault to execute

B The CPU clock stops

C The compiler automatically fixes the symbol

D The interrupt runs twice as fast

Detailed Explanation: The vector table in startup assembly references SysTick_Handler. A mangled C++ symbol (like _Z15SysTick_Handlerv) will not match, leaving the interrupt bound to the default unhandled loop.