Embox compilation and flashing

Question

I am interested in attempting to compile, package and flash Embox to an MCU, from either a Windows or Mac machine (cross-compilation), via JTAG, and I have a number of concerns.

Observe what I believe to be the normal way of writing Embox apps and deploying/flashing them to an MCU:

As you can see, in my understanding above:

• Embox source code is compiled (via make) into some file (Object file?), <file>.<ext>
• At the same time, my app's source code is cross-compiled (somehow) into an Object file (myapp.o) that is compatible with Embox
• Some tool combines: (a) the Embox <file>.<ext> produced by make, (b) myapp.o and (c) any other libs I specify. It takes these as inputs and produces a single application image that is ready to be flashed via JTAG

My concerns, also identified in the illustration:

• What is the exact name and file extension of the Embox "artifact" produced by running make on Embox source code? Is this artifact different depending on whether you are on Windows or Mac? What tools besides make are necessary to produce this artifact?
• What is this magic tool that takes in Object/interim files and produces a single app image? What is the exact name and file extension of this app image?
• What tools do I need to cross-compile myapp.c and myapp.h into a myapp.o that is Embox compatible?

Answer 1

I'm one of the Embox developers, who is responsible for build tools.

Basile has given a correct overview of the process as a whole:

• the source is compiled into a relocatable embox.o with ld -r,
• then linked into embox ELF binary,
• ... which in turn is additionally transformed into .bin and .srec that are used for flashing quite often.

Binary artifacts go into build/base/bin.

Let me add few details.

First of all, you'll probably won't need to dig into the details of linking your application against Embox. Instead, the proper way is to integrate your app into Mybuild - the Embox build system - and let it handle low-level linkage details for you. So it's worth building vanilla Embox first and see it running on an emulator.

Building and running Embox for ARM

I would suggest you to start with arm/qemu template. This won't fit into your MCU, but if your application doesn't do something unusual, it would be easier to test it on QEMU before porting it to the target MCU. Anyway, this is a good starting point to check that a dev environment is sane and everything builds OK.

Developing on Linux would really make your life easier, like just sudo apt-get install build-essential plus few packages and installing a cross-compiler. However, if you're going to develop on Windows, you may find this guide useful. In addition, you'll need to patch make to make it work on Windows: Issue 504. And here is how to setup QEMU.

The recommended cross-compiler for ARM is the official GNU Tools for ARM.

So basically, here are steps to prepare a Linux dev machine for building and running Embox for ARM:

sudo add-apt-repository -y ppa:terry.guo/gcc-arm-embedded
sudo apt-get update
sudo apt-get install build-essential gcc-arm-none-eabi u-boot-tools qemu-system

Clone the repository:

git clone https://github.com/embox/embox embox
cd embox

Build arm/qemu:

make confload-arm/qemu
make

confload target initializes a conf/ directory with a predefined template called arm/qemu. conf/ is where a configuration of the target image (Embox + your app) resides.

Run QEMU. There's a handy wrapper for that, that infers the necessary options from the Embox configuration and runs QEMU properly:

sudo ./scripts/qemu/auto_qemu

If everything goes fine, you'll see something like that. Type help to list available commands.

Adding your application as an Embox command

Personally, when trying something new to me I usually "mimic" someone else's approaches to get the first feedback from the application/system. Here, I'd suggest to derive, e.g. an existing cat command, throw everything away from it, effectively turning it into a Hello world application.

For now, create a directory hello in src/cmds and add there two files:

hello.c file

/**
 * Plain C Hello World application.
 */
#include <stdio.h>

int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}

As you can see, this is a regular C program, that doesn't use any Embox-specific APIs. Let's integrate it into Embox now.

Hello.my file

(refer to Cat.my):

package embox.cmd.hello

@AutoCmd
@Cmd(name = "hello",
    help = "<This is what `help hello` will output>",
    man = '''
        <What is shown when running `man hello`>
    ''')
module hello {
    source "hello.c"

    depends embox.compat.libc.all  // for stdio
}

Now add the newly defined module into the configuration.

conf/mods.config file

package genconfig

configuration conf {
    ...

    include embox.cmd.hello.hello
}

Build and run

Run make. This will compile hello.c and link it with Embox appropriately. After that, run it with sudo ./scripts/qemu/auto_qemu and type hello into the embox>prompt.

That's it.

Regarding your questions

To summarize:

Embox source code is compiled (via make) into some file (Object file?), <file>.<ext> At the same time, my app's source code is cross-compiled (somehow) into an Object file (myapp.o) that is compatible with Embox

Both your application and Embox itself are compiled together with a regular (cross-)compiler, defined in conf/build.conf through a CROSS_COMPILE variable.

Some tool combines: (a) the Embox <file>.<ext> produced by make, (b) myapp.o and (c) any other libs I specify. It takes these as inputs and produces a single application image that is ready to be flashed via JTAG

These are linked with ld as part of the build process.

What is the exact name and file extension of the Embox "artifact" produced by running make on Embox source code? Is this artifact different depending on whether you are on Windows or Mac?

The main build artifacts are build/base/bin/embox (ELF) and build/base/bin/embox.bin (binary). If I'm not mistaken, these all have the same extension on all build platforms (well, may be there will be embox.exe instead of embox, but that's unlikely).

What tools besides make are necessary to produce this artifact?

The cross-compiler, essentially. GNU Tools for ARM embedded processors is a good choice.

Plus some quirks in case of Windows (see above).

What is this magic tool that takes in Object/interim files and produces a single app image? What is the exact name and file extension of this app image?

There's no such magic tool. :)

What tools do I need to cross-compile myapp.c and myapp.h into a myapp.o that is Embox compatible?

This is, again, hidden beneath Mybuild. In a nutshell, it:

• compiles myapp.c using the cross-compiler into myapp.o
• if the app is defined as a @AutoCmd module, it:
  • registers the app in a command registry by storing a pointer to main among with some metadata like name
  • strips away the main symbol from the object file to prevent conflicts in case of multiple apps
• links myapp.o as it were a part of Embox into embox.o and then into embox ELF