embox / embox

Modular and configurable OS for embedded applications

Embox

Embox is a configurable RTOS designed for resource constrained and embedded systems. Embox's main idea is to use Linux software without Linux.

Achievements

• VoIP phone on STM32F7Discovery based on PJSIP project
• Qt on STM32F7Discovery
• OpenCV on STM32F769i board
• A lot of programming languages are available: Python, Lisp, Java (phoneme), TCL, Ruby, Lua, JS, Scheme
• SSHD based on Dropbear project
• Mesa3d
• Quake3
• zeromq, qpid
• ...

Key features

• POSIX-compliant
• C++ support
• File systems: FAT, ext2/3/4, ...
• TCP/IP: BSD sockets; supported protocols: UDP, HTTP, ARP, NTP, ICMP, ...
• Cross-platform: ARM, MIPS, x86, RISC-V, Microblaze, SPARC, PowerPC, E2K
• Popular platforms: STM32, i.MX6, RaPi, ...
• Provides popular desktop software on MCU (e.g. STM32): Qt, OpenCV, PJSIP, dropbear, ...
• Unix-like shell utilities: ls, cat, mount, ...
• Popular programming languages: java, python, lua, tcl, lisp, ruby, js, scheme

Contacts

Mailing lists:

• main (english): [email protected]
• russian: [email protected]

Telegram chats:

• main (english): https://t.me/embox_chat_en
• news: https://t.me/embox_news
• russian: https://t.me/embox_chat

Documentation

• Wiki
• PDF
• GitHub repository with source for docs

Getting started

Here's a quick overview on how to build and run Embox.

Required environment:

• gcc and make
• cross compiler for the target platform

Preparing environment

For Debian-based systems (most packages are installed out of box though):

$ sudo apt-get install build-essential gcc-multilib curl libmpc-dev python

For Arch Linux:

$ sudo pacman -S make gcc-multilib cpio qemu
$ yay -S python2-bin

For MAC OS X (requires MacPorts installed):

$ sudo port install i386-elf-gcc i386-elf-binutils cpio gawk qemu

For any system with Docker (more info on wiki Emdocker):

$ ./scripts/docker/docker_start.sh
$ . ./scripts/docker/docker_rc.sh

Building Embox

First of all:

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

Since Embox is highly configurable project, it is necessary to specify modules to be built and params for them. To build the OS make command is used. All commands described below are called from the embox directory, which includes src/, templates/, ...

Configuring the project

For configuring it is necessary to specify parameters and modules supposed to be included into the system. There are two ways to set up a current config:

• make confload-<template> - build artefacts generated in a fixed place
• ./confset <template> - build artefacts maintained in project dependent working paths

While make confload-<template> is used, files from the template's folder are copied into './conf' folder. You can modify them. While confset <template> is used, files from the template's folder are copied into ./work/<template>/conf folder and a link './conf' is created to ./work/<template>/conf. This usage is suited for quick switching between your templates, because full rebuilds are avoided. Moreover, working conf-settings are retained as well, when you switch build e.g. between real target and qemu and back again. Only downside of using the confset method: more SSD/HDD usage, dependent on number of parallel projects.

Embox has several templates prepared, to list them use the following command:

$ make confload

The simplest way to load a template is to specify its name in the command:

$ ./confset <template>

or

$ make confload-<template>

For the quick overview you can use one of qemu templates that exist for most architectures, that is, x86/qemu for x86:

$ ./confset x86/qemu   (yet no autocomplete/-suggest when only a part is typed: to Do)

or

$ make confload-x86/qemu

Building the image

After configuring the project just run make to build:

$ make

Running on QEMU

The resulting image can now be run on QEMU. The simplest way is to execute ./scripts/qemu/auto_qemu script:

$ sudo ./scripts/qemu/auto_qemu

sudo is requried to setup a TUN/TAP device necessary to emulate networking.

After the system is loaded, you’ll see the embox> prompt, now you are able to run commands. For example, help lists all existing commands.

To test the connection:

ping 10.0.2.16

If everything's fine, you can connect to the Embox terminal via telnet.

To exit Qemu type ctrl + A and X after that.

Debugging

You can use the same script with -s -S -machine accel=tcg flags for debugging:

$ sudo ./scripts/qemu/auto_qemu -s -S -machine accel=tcg

After running that QEMU waits for a connection from a gdb-client. Run gdb in the other terminal:

$ gdb ./build/base/bin/embox
...
(gdb) target extended-remote :1234
(gdb) continue

The system starts to load.

At any moment in gdb terminal you can type ctrl + C and see the stack of the current thread (backtrace) or set breakpoints (break <function name>, break <file name>:<line number>).

Other architectures

Embox supports the following CPU architectures: x86, ARM, Microblaze, SPARC, PPC, MIPS.

In order to work with architectures other than x86 you'll need a cross compiler. After installing the cross compiler just repeat the step above, starting with configuring:

make confload-<arch>/qemu
make
sudo ./scripts/qemu/auto_qemu

The output is quite the same as in the case of the x86 architecture.

Networking support

Embox supports networking on qemu x86, ARM, MIPS and Microblaze.

embox's Issues

MMU probe

mmu_probe
Cc: @abusalimov

Documentation testing framework

Describe follow interfaces

1. Traps testing framework
2. MMU testing framework

Physical page allocator vs. MMU mode on

Обдумать следующую проблему:
Включен режим виртуальной памяти. Если маркеры находятся в шапке свободного блока физической памяти, который не отображен в виртуальное адресное пространство, то как прочитать этот маркер?

Пока видится 2 решения:

1. использовать REG_LOAD/REG_STORE для обхода MMU, но не факт что такая возможность есть на всех процессорах.
2. всегда отображать первую страницу свободного блока памяти, но это заполняет виртуальное пространство ненужными страницами, да и вообще сам метод некрасив
   Cc: @fijiol

Split common.h

Now common.h contains several different features such as Debug IO macros, direct access macros and so on. This features must be placed in owm header files.

Desing interface for interrupts testing

Design interface for possibility interrupts functionality testing

Remove (SIMULATION_TRG)

SIMULATION_TRG is old code in project.

x86 porting

Портирование под x86.

remove comercial link from code

Delete some reference to commercial project

SNMP

реализовать Simple Network Management Protocol
Cc: @alexkalmuk, @HAK1R

запуск загруженных образов

запустить загруженный по TFTP образ linux.

loopback device

реализовать loopback network device

SPARC locore problems

Код из основной ветки sparc (бывшая sparc-experimental) работает с ошибками.
Что-то не так с вложенными прерываниями.

move start script

Предлагается перенести стартовый скрипт из дебрей исходников в конфиг, чтобы его можно было рописывать в шаблонах

Есть два варианта

первый (мне он больше нравится + попроще) - завести макроопределение, например. #define START_SCRIPT "...", задаваемое чем-то вроде start_script("...") в конфиге.

Второй - хранить отдельный файл со стартовым скриптом. Тогда можно либо оформить его как отдельный модуль с зависимостью shell (хотя тут мне до конца не понятно, как), либо так же через макроопределение хранить к нему путь
Cc: @abusalimov

Originally assigned to @afomin

Physical page allocator

Предлагается реализовать менеджер физической памяти, использую метод граничных маркеров.
Cc: @fijiol

Annoying build errors

Make outputs the following error messages, but anyway builds the project.

Error: conf directory or files do not exist
Try "make TEMPLATE=<profile> config"
    See templates dir for possible profiles

Stack allocation

How to define memory block for stack? Should it be static or dynamic?
Partially relies on #46.

Documentetion architecture portation process

Describe demands for start project on new platform

Rework system timers

Timers module contains bad code.
May be do timers list instead massive

porting newlib

собственно по сабжу http://sourceware.org/newlib/

Fix r131

Проект не собирается после моего прекрасного коммита (897fe93).
Зацикливается на цели start_script
Cc: @abusalimov

Bad name for some macroses

OVK_REGxxx is bad name style

Building repeatedly configured project

Building repeatedly configured project causes an error to be printed when trying to use backup~ dir as config.

What steps will reproduce the problem?

make TEMPLATE=sparc config
make TEMPLATE=sparc config
make all
make all

What is the expected output? What do you see instead?

The last "make all" outputs the following:

make all
Error: conf directory or files do not exist
Try "make TEMPLATE=<profile> config"
    See templates dir for possible profiles
make -C ./ PROJECT_NAME=backup~ build_target;   make -C ./
PROJECT_NAME=sparc_release build_target;
make[1]: Entering directory `/home/karkaroff/workspace/ovk/embox'
Error: conf directory or files do not exist
Try "make TEMPLATE=<profile> config"
    See templates dir for possible profiles
make[1]: Leaving directory `/home/karkaroff/workspace/ovk/embox'
make[1]: Entering directory `/home/karkaroff/workspace/ovk/embox'
Build complete
make[1]: Leaving directory `/home/karkaroff/workspace/ovk/embox'

Originally assigned to @afomin

EMBuild Makefiles HOWTO

Describe EMBOX build system API (make-side packages, mods, dependency resolving, flags and so on).

hal/image proposition for linkage info

As far as linking the final image tightly relies on arch part, the latter should provide a facility to access linkage information, e.g. about sections, memory regions, stack, and so on.

EMBuild does not work on GNU make 3.80

1. Checkout
2. Создание конфига (make config TEMPLATE=sparc)
3. Сборка проекта(make all)

Появляется ошибка

mk/embuild.mk:22: *** missing `endif'.  Stop.

У меня Windows XP pro SP3. Поставил GSTools, Subclipse, cygwin с gcc-core v.3.4.4, gcc-mingw-core, make, cmake.
Cc: @anton-bondarev, @batsun, @abusalimov

[microblaze arch] setjump hasn't been implemented yet

Design 'setjmp' and 'longjmp' function in microblaze environment.
And achieve to setjmp test passes correctly

[testing framework] Implement traps testlib for microblaze

Implement traps testlib for microblaze. Design test for checking it. Test soft_traps must pass.

Implement traps testlib for sparc.

Implement traps testlib for sparc. Test soft_traps must pass.

Originally assigned to @batsun

SPARC locore - trap_setup_end - arbitrary "rett" into invalid window

19:41 sikmir: не всё хорошо с сетью всё таки в не обсолете...
 я: хм
  а что там еще?
19:43 sikmir: то что мы видили это ерунда, я убрал, а косяк что пинги то ходют, а если по тфтп валиться где и раньше на /* see you soon! */^M
jmp %t_pc^M
4400b2e0: 81 c4 40 00 jmp %l1
rett %t_npc^M
4400b2e4: 81 cc 80 00 rett %l2
19:44 я: а регистры пишет?
19:45 sikmir: INS LOCALS OUTS GLOBALS
0: 00000000 F34000C1 4401E800 00000000
1: 440812B4 4400EA8C 440812B4 44091DD0
2: 440810C0 4400EA90 440810C0 00000000
3: 000000CC 00000010 000000CC 00000000
4: 00000000 00000002 00000000 00000000
5: C0A8003B 00000800 00000000 00000000
6: 44091D70 00000008 44091CC0 00000000
7: 4400EA68 00000004 4400B20C 00000000

psr: F34000C1 wim: 00000004 tbr: 44000060 y: 00000000
  6 error mode
19:46 похоже это на команде ret
19:47 я: да, rett в инвалидное окно

Cc: @sikmir

Setting different types of images

Add possibility to set output images: srec? disassembler and so on
Cc: @abusalimov

Change location for test framework

Move headers to hal/test folder

Mapping ancillary tables into virtual address space

Подумать, следует ли отображать в память служебные таблицы, например, таблицы самого MMU.
Скорее всего этот вопрос будет решаться для каждой архитектуры в отдельности.

spin_lock is used in wrong way

functions 'spin_lock' and 'spin_unlock' in net_pack_manager.c are used with wrong interface

    unsigned long sp;
    spin_lock(sp);

must be

    unsigned long sp;
    spin_lock(&sp);

TFTP

To achieve loading files via TFTP.
The connected themes:

1. A problem of the big packages in hw, TFTP packet's length is 516 byte (while it is possible to take less).
2. Completion file system.
3. Debugging sockets.

Desing interface for traps testing

Design interface for possibility testing traps functionality.

Regression testing scripts

Похоже, нет ясного понимания, что требуется от системы регрессионного тестирования. По крайней мере, то, что предлагал Антон, то, как это понял я, и тот код, который написал Леха, слабо коррелируют между собой. Поскольку работающая версия должна появиться к вечеру понедельника, предлагаю здесь зафиксировать саму задачу и в темпе ее реализовать.
Cc: @anton-bondarev, @afomin

Compiling with gcc4 for SPARC

Сборка проекта новым компилятором под SPARC производит неработающий код.
В секции .rodata образа лежат нули.
Также, по всей видимости, поменялась семантика атрибутов alias и weakref.

Mods framework and API docs

Describe EMBOX Mods framework (C-side binding and API).

refactoring ICMP/ping

отрефакторить и доработать icmp протокол

Impelement ipl_interface in microblaze architecture

ipl_xxx interface doesn't correspond ipl_xxx interface from HAL.

Simplify new test creation

Suppose I am a hardware engineer.

Why should I learn what is Mods and how Dependency Injection works?
Why should I rename Makefile_template to Makefile?
Why should I edit Makefile at all?

I just want to add a new test. And nothing more.

Testing data transmitting with test_soft_traps handler

Transmit test_variable using data pointer

Originally assigned to @batsun

upgrade config and build system

Требуется сохранять структуру шаблона в папке conf.

• Добавить возможность сохранения конфига в шаблон и возможность сборки только одного шаблона, а не всех из папки conf.

Идея следующая:

./conf/
       build.conf
       lds.conf
       ...
       patch1/
               (? build.conf, ...)
               patch.conf (включает все файлы патча)
               patch1_bla.conf
               patch1_blabla.conf
               patch1_blablabla.conf
       patch2/
               ...
       patch3/
               ...
       ...

Предлагается собирать конфигурацию base и конфигурации для каждого патча отдельно
Cc: @abusalimov

Originally assigned to @afomin

"Ctrl-c" interruption for comands.

Analogue of the bash ctrl+c for the embox commands.
After pressing ctrl-c the executing command would be interrupted.

By Kryachko Alexey, Okhotsky Maxim.

'make all' on the unconfigured project

What steps will reproduce the problem?

run 'make all' on the unconfigured project

Human-readable error message is expected.

Instead you can see:

make all
gcc -E -Wp, -P -undef -nostdinc -I./conf -D__MODS_MK__ \
    -MMD -MT build/codegen/mods.mk -MF build/codegen/mods.mk.d ./mk/confmacro.S \
        | sed 's/$N/\n/g' > build/codegen/mods.mk
./mk/confmacro.S:39:21: error: mods.conf: Нет такого файла или каталога
gcc -E -Wp, -P -undef -nostdinc -I./conf -D__BUILD_MK__ \
    -MMD -MT build/codegen/build.mk -MF build/codegen/build.mk.d
./mk/confmacro.S \
        | sed 's/$N/\n/g' > build/codegen/build.mk
./mk/confmacro.S:12:22: error: build.conf: Нет такого файла или каталога
./mk/confmacro.S:18:24: error: options.conf: Нет такого файла или каталога
Listing packages
Processing packages
Listing essentials
Listing mods
Listing libs
Processing all units
Processing mod deps
./src/tests/mmu/Makefile:1: EMBuild warning:: Undefined dependencies for
mod embox.test.mmu_enable:: embox.hal.test.mmu embox.hal.mm.mmu
./src/tests/soft_traps/Makefile:1: EMBuild warning:: Undefined dependencies
for mod embox.test.soft_traps:: embox.hal.test.traps
Done.
Error: conf directory or files do not exist
Try "make TEMPLATE=<profile> config"
    See templates dir for possible profiles
make: *** [check_conf_dir] Ошибка 1

echo -e on different systems

Некоторые версии echo не воспринимают ключ -e, хотя при этом верно интерпретируют управляющие символы.

Add posibility to setup stack parameters

Added possibility setting stack parameters in configuration files.

1. Stack size.
2. Address or section.

If we set section for stack we can check suit or not our stack into our memory map
Cc: @abusalimov

Change location environment header

Move environment header to hal/env folder

ARM7 porting

портирование под arm9
Cc: @AntonKozlov

Desing interface for mmu testing

Design interface for possibility mmu functionality testing