> ## Documentation Index
> Fetch the complete documentation index at: https://docs.t3gemstone.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MATHLIB

> Using mathematical functions with acceleration chips

<Tip>C7-based MCU projects using the MATHLIB library leverage the AI Accelerator (C7x DSP / MMA) unit
within the processor. This allows mathematical operations, vector calculations, and compute-intensive
functions to be executed with hardware acceleration, significantly increasing application performance.</Tip>

## Example Project

A working example project that you can examine as a reference for MATHLIB library integration is
provided in the `MCU` directory within T3 Gemstone's GitHub `examples` repository.

While inside the `devbox shell` within the examples repository, you should run the following command.

```bash theme={"system"}
PROJECT=mcu task clean build
```

The `mathlib_demo.out` file located in `examples/mcu/mathlib_demo/j722s-evm/c75ss0-0_freertos/ti-c7000` and
`examples/mcu/mathlib_demo/j722s-evm/c75ss1-0_freertos/ti-c7000` is now ready to run on the C7 cores.

To run it on the development board, you can follow the steps in the
[Running the compiled project at the U-Boot stage](/en/boards/o1/peripherals/mcu#2-8-running-the-compiled-project-at-the-u-boot-stage) section.

In this example project, the generated outputs are transmitted via the UART1 interface.
(You can find the related pin connections in the [Pinout documentation](/en/boards/o1/peripherals/introduction#1-pinout).)

The terminal output of the MATHLIB example project is as follows.

```bash theme={"system"}

-----------------------------
  T3 Gemstone MATHLIB Test   
-----------------------------

acos(   1.00000) =   nane-308
acos(  0.970942) =   0.241660
acos(  0.885456) =   0.483319
acos(  0.748511) =   0.724983
acos(  0.568065) =   0.966644
acos(  0.354605) =    1.20830
acos(  0.120537) =    1.44997
acos( -0.120537) =    1.69163
acos( -0.354605) =    1.93329
acos( -0.568065) =    2.17495
acos( -0.748511) =    2.41661
acos( -0.885456) =    2.65827
acos( -0.970942) =    2.89993
acos(  -1.00000) =    3.14159
acos(   1.00000) =   nane-308
acos(  0.970942) =   0.241660
acos(  0.885456) =   0.483319
acos(  0.748511) =   0.724983
acos(  0.568065) =   0.966644
acos(  0.354605) =    1.20830
acos(  0.120537) =    1.44997
acos( -0.120537) =    1.69163
acos( -0.354605) =    1.93329
acos( -0.568065) =    2.17495
acos( -0.748511) =    2.41661
acos( -0.885456) =    2.65827
acos( -0.970942) =    2.89993
acos(  -1.00000) =    3.14159
```

## Integrating into an Existing MCU Project via MakeFile

To integrate the Mathlib library into your existing MCU project, you need to define the root directory
path of the SDK and the `.cpp` file you will use.

```makefile theme={"system"}
SDK_ROOT_PATH := ${MCU_PLUS_SDK_PATH}/..

FILES_cpp := \
	mathlib_demo.cpp \
```

Then, you should add MATHLIB's `src` directory to the list of included folders (`INCLUDES_common` variable) as follows.

```makefile theme={"system"}
-I${SDK_ROOT_PATH}/mathlib/src \
```

You must add the following necessary definitions to the compiler FLAGS parameters (`CFLAGS_common` variable) for
the library to compile correctly.

```makefile theme={"system"}
-DMCU_PLUS_SDK \
-DBUILD_C7X \
-DSOC=j722s \
--silicon_version=7524 \
```

You should add MATHLIB's compiled library directory to the library path definitions (`LIBS_PATH_common` variable).

```makefile theme={"system"}
-i${SDK_ROOT_PATH}/mathlib/lib/Release \
```

You need to add the name of the mathlib library to the list of included library files (`LIBS_common` variable) as follows.

```makefile theme={"system"}
-lMATHLIB_C7524.lib \
```

To enable the compilation of .cpp files in the project, the following additions must be made right below the line
where `OBJS` and `DEPS` definitions are made.

```makefile theme={"system"}
OBJS += $(FILES_cpp:%.cpp=%.obj)
DEPS := $(FILES:%.cpp=%.dpp)
vpath %.cpp $(FILES_PATH)

$(OBJDIR)/%.obj %.obj: %.cpp
	@echo  Compiling: j722s:c75ss0-0:freertos:ti-c7000 $(OUTNAME): $<
	$(CC) $(CFLAGS) $(INCLUDES) $(DEFINES) -ppd=$(OBJDIR)/$(basename $@).dpp -ppa -fr=$(OBJDIR)/ -fp=$<
```

Upon completion of these steps, the MATHLIB library will be successfully integrated into the project via Makefile.

## Integrating MATHLIB into an Existing CPP File

After completing the necessary configurations via Makefile, to use the MATHLIB library, you need to include
its header file in the .cpp file within your project. Following this step, you can directly use MATHLIB's
functions and definitions within your existing project.

You can access all modules available in the MATHLIB library via
[this link](https://software-dl.ti.com/jacinto7/esd/processor-sdk-rtos-j722s/latest/exports/docs/mathlib/docs/user_guide/modules.html).

```cpp theme={"system"}
#include <mathlib.h>
```

With this process, the MATHLIB integration will be complete.