Understanding Project Files in Embedded Development

Hello everyone, I am Pi Zi Heng, a serious tech person. Today, I will talk about project files in embedded development.

In the previous two lessons, I introduced two typical input files in embedded development: source files (.c/.h/.s) and linker files (.icf). I want to ask again, are there any other input files? The answer is yes, but this time there is really only one, the protagonist of this article, the project file, which is also considered a half input file. Why is it called half? Because the project file not only contains the input information specified by the developer but also includes a lot of other auxiliary debugging input/output information, making it a crucial file in embedded development. This article focuses on the input information related to the developer’s application in the project file. Once you have this input information, along with the previously introduced source and linker files, you will have all the information needed for the application, which you can use to generate an unambiguous executable image binary.

With the development of embedded software engineering and the increasing complexity of requirements, modern IDEs have also become more powerful. The rapid iteration of IDE versions is overwhelming; Keil MDK has entered the 5.0 era, and IAR EWARM has reached the 8.0 era. Each IDE has its strengths, but the content I will discuss today is the basic functions that every IDE must have. Let’s continue with IAR EWARM as an example to start today’s content:

1. Standard IDE Functions

Before starting today’s topic, I think it is necessary to briefly explain the functions that a standard IDE should have. Modern IDEs are generally composed of components, with each stage of embedded development corresponding to respective components that fulfill the requirements of each stage.

1.1 IDE Components

A standard embedded development process should include at least six stages, and IAR has one or more components for each stage:

• Input (IAR Editor): Edit source code files.
• Compile (ICCARM, IASMARM): Compile source code files to generate executable binary machine code.
• Analyze (C-STAT, MISRA-C): Check potential issues in the code during compilation.
• Link (ILINK): Link executable binary machine code to the specified ARM memory address.
• Download (I-jet, flashloader): Download the linked executable binary machine code into the chip’s internal non-volatile memory.
• Debug (C-SPY, C-RUN): Online debug the execution status of the code in the chip.

The project file is mainly used to record and integrate all the development requirements of the above six stages.

1.2 IDE File Types

Since there are many components in an IDE, there will also be different types of files to store the information required by these components. IAR supports a wide range of file extension types, and here I will only list the extensions of the project files created in the root directory of your project:

.eww           // Workspace file
.ewp           // IAR Embedded Workbench project
.ewd           // Project settings for C-SPY
.ewt           // Project settings for C-STAT and C-RUN
.dep           // Dependency information

The content of this article is all contained in the .ewp file, which records the essential input information specified by the developer for the application. Without this information, the application project is incomplete. In other words, if you have all the source files and linker files for the application but lack the .ewp file, the final generated image binary file may be different.

Note: For more supported file extension types by IAR, please refer to the “File types” section in the document located at IAR software installation directory\IAR Systems\Embedded Workbench xxx\arm\doc\EWARM_IDEGuide.ENU.pdf.

2. Analyzing the Project (ewp) File

Having laid the groundwork for many IDE/project basic concepts, it’s time to get straight to the point. What input information specified by the developer does the main character of this article, the ewp project file, contain? I will reveal it from three aspects:

2.1 Source File Organization

For a slightly more complex embedded project, the number of application code lines should be counted in hundreds or thousands (referring only to the files and code created by the developer). When organizing code, we certainly won’t just create one .c file, as a single file would lead to unclear functional module structure, making project management and maintenance inconvenient.

When we create multiple files for the project, a necessary issue arises: the reference path issue (thus the path information is the first input information I want to discuss). When the number of source files is large, we typically create different folders to group source files with similar functions together. When the compiler starts compiling the .c source files, it will search for header files included in the include statements. Friends familiar with C language know the usage of the following two different include statements:

#include <file.h>           // Include header file from compiler's library (IDE installation path)
#include "file.h"           // Include header file from the current project (project path)

Therefore, the ewp file will include path information, and all paths should be listed under Options->C/C++ Compiler->Preprocessor in the Additional include directories section. This path can be an absolute path on the current PC or a relative path based on the ewp file. To ensure that the project can compile normally on any PC at any location, it is recommended to list all paths using the following relative path method:

ewp current path: $PROJ_DIR$/
ewp subdirectory path: $PROJ_DIR$/xxFolder/
ewp parent directory path: $PROJ_DIR$/../

Speaking of path issues, I would like to introduce a classic directory organization method for embedded project files:

\projectDir
           \doc                            -- Place project documents here
           \bsp                            -- Place bsp (board support) related source files here
                  \linker                    -- Project linker files
                  \src                       -- Board-level related source files (e.g., pinout, clock, etc.)
                  \builds\xxBuild\.ewp       -- Project ewp file
                  .eww                       -- Project workspace file
           \src                            -- Place bsp unrelated source files here
                  \platform                  -- Chip header files and CMSIS files
                  \drivers                   -- Chip internal and external device drivers
                  \include                   -- Header files to be referenced by all sources
                  \startup                   -- Standard startup code
                  \utilities                 -- Standard utility functions
                  \middleware                -- Independent middleware
                  \components                -- Board-level peripheral component drivers
                  \application               -- Main logic code for the current application

2.2 Global Macro Definitions

Friends who often use conditional compilation know the relationship between workspace files and project files. A project usually has only one .eww file but may have multiple .ewp files, as source code often contains conditional compilation. Sometimes we configure different settings for the project to compile different results (speed priority/area priority, feature control…), and these configurations are implemented through global macro definitions. Open Options->C/C++ Compiler->Preprocessor and write the global macros you need to define in the box:

MACRO1            // Equivalent to #define MACRO1 (1) in the source file
MACRO2=2          // Equivalent to #define MACRO2 (2) in the source file

The global macro information is the second input information I want to discuss. If the global macro information is missing, sometimes the project compilation will not report an error because the compiler defaults undefined macros to 0 when processing conditional compilation statements in common usage. However, it will report an error when processing conditional compilation statements in common usage, so it is recommended to use the second conditional compilation usage to avoid global macro issues.

// Common usage
#if MACRO
    // your code block 1
#else
    // your code block 2
#endif

// Recommended usage
#if !defined(MACRO)
    #error "No valid MACRO defined!"
#elif (MACRO == 1)
    // your code block 1
#else
    // your code block 2
#endif

2.3 Compilation Options

Compilation options include all the information required by the compiler. The code must be compiled by the compiler to generate binary machine code, and different compiler option configurations will generate different machine code. So what options need to be specified? Open the project Options tab and set the following items:

Note: For more explanations of options in the ewp file, please refer to the General Options and Compiler Options sections in the document located at IAR software installation directory\IAR Systems\Embedded Workbench xxx\arm\doc\EWARM_IDEGuide.ENU.pdf.

The compilation setting information is the third input information I want to discuss. When you organize the source files in the project and set the correct global macro definitions and compilation options, congratulations, your application design work is basically complete.

3. Creating a Demo Project

To facilitate the subsequent course, I will create a demo project at the end of this lesson. Here is the information for the demo project:

IDE:        IAR EWARM v8.11.2
Device:     NXP MKL25Z128VLH4
project layout:
    \D\myProject\bsp\builds\demo\demo.ewp
    \D\myProject\bsp\linker\iar\KL25Z128xxx4_flash.icf
    \D\myProject\bsp\src\startup_MKL25Z4.s   (only keep the first 16 system interrupts)
    \D\myProject\bsp\src\system_MKL25Z4.c   (only to disable WDOG)
    \D\myProject\bsp\src\system_MKL25Z4.h
    \D\myProject\bsp\helloArm.eww
    \D\myProject\src\platfrom\CMSIS
    \D\myProject\src\platfrom\devices\MKL25Z4
    \D\myProject\src\startup\reset.s
    \D\myProject\src\startup\startup.c
    \D\myProject\src\startup\startup.h
    \D\myProject\src\application\main.c
    \D\myProject\src\application\task.c
    \D\myProject\src\application\task.h

// main.c
//////////////////////////////////////////////////////////
#include "task.h"
const uint32_t s_constant = 0x7f;
int main(void)
{
    uint32_t l_variable = 0x7f;
    if (s_constant == l_variable)
    {
        normal_task();
        ram_task();
        heap_task();
    }
    while (1);
}

// task.c
//////////////////////////////////////////////////////////
#include "task.h"
static    uint32_t s_variable0;
__no_init uint32_t n_variable1;
static    uint32_t s_variable2 = 0x5a;
static uint8_t s_array[16];
void normal_task(void)
{
    s_variable0 *= 2;
}
__ramfunc void ram_task(void)
{
    n_variable1++;
}
void heap_task(void)
{
    uint8_t *heap = (uint8_t *)malloc(16 * sizeof(uint8_t));
    if (heap != NULL)
    {
        memset(heap, 0xa5+s_variable2, 16);
        memcpy(s_array, heap, 16);
        s_variable0 = (uint32_t)heap;
        free(heap);
    }
}

Extra Tips

We have arrived at the extra time with Pi Zi Heng. Observant friends may notice two blue items in the table, and yes, today’s extra content is related to those blue items.

Tip 1: Running on Heterogeneous Dual-Core

Currently, embedded products are becoming increasingly complex, and the performance requirements for MCUs are also rising. Major ARM manufacturers are continuously launching more powerful ARM MCU products, with ultra-high frequencies, dual-core, and quad-core MCUs becoming common. For some heterogeneous dual-core MCU products, there may be a requirement during development: you have a middleware that will be called by both cores simultaneously, and the instruction sets of the two different cores may be inconsistent. How can this issue be resolved? Some may think of compiling a binary for each core and placing it in different memory locations, with each core pointing to its corresponding binary at runtime. This is one solution, but it wastes storage space and can lead to confusion and miscalls. Is there a better way?

To enable software reuse on Cortex-M, ARM has designed the Cortex-M processor with processor downward compatibility and software binary upward compatibility. In simple terms, code compiled on a lower version processor can run on a higher version processor. Therefore, the solution is to compile the middleware using the lower version core in the heterogeneous dual-core, allowing this middleware to be called by both cores.

Tip 2: Generate PIC Code

Friends who often deal with bootloaders know that after the code is linked to generate the binary file, this binary cannot be placed anywhere; it must be placed at the location specified by the linker file. If the position is incorrect, it may lead to execution errors. The reason is that the compiler does not always assemble all functions into position-independent code due to certain strategies when assembling the source code. If we use IDE compilation options to assemble the middleware into PIC code, we can directly include the middleware’s binary in the project and use the linker’s custom section feature to place it at any location. Finally, we just need to establish a function pointer address list based on the binary’s starting address to call this middleware without obstacles.

Tip 3: Include .c Files

In project development, we often create multiple projects under one workspace because different projects require different .c files to achieve different functionalities. So, can we create only one project to achieve different functionalities? Of course! Usually, we only use the #include “xx.h” statement in .c files to include header files. However, we can also include .c files like this: #include “xx.c”. Just be careful not to include .c files in .h files (unless that .h will only be included by one .c file). If you think outside the box, you could even do it so that the project only needs to add one .c file, while all other .c files are included by that added .c file in a single-level (only single-level) reference.

Thus, I have introduced the project file in embedded development. Where is the applause~~~