Program Development

1. Introduction
2. Limitations
3. Program Registration Details
4. Example
5. Program Execution

1. Introduction

Programs can be developed similarly as in a standard PC computer. The dnx RTOS provides standard C API functions that can be used in the same way as in PCs. Besides standard libraries, special libraries are provided, e.g: network, thread, time, and os. For more details reference to the documentation of libraries. Created programs are compiled in the project building time and are integral part of the system, but have different functionality. Each program can be started in many instances and at any time. The user decides which program will be started. Programs integrated in the system are called built-in programs, and can be listed by using procfs file system (typically localized in the /proc/bin directory). The variables of each program are localized in the RAM and are dynamically allocated at program setup. The program code is compiled and is stored in the ROM memory of the microcontroller.

2. Limitations

The dnx RTOS program implementation has some limitations:

  • Global variables are provided by the main global structure and access to those variables are provided by the global pointer. This pointer is individually created for each program instance. To share global variables between the modules of the program, the user has to share the global variable structure in the header that is included in each module. The global variable structure is created between GLOBAL_VARIABLES_SECTION_BEGIN and GLOBAL_VARIABLES_SECTION_END macros, or by using GLOBAL_VARIABLES {}; macro.
  • The global variables cannot be preloaded at program startup. The user has to initialize values of defined global variables if the value other than zero is required.
  • If the user wants to create a constant then it should be inserted beyond the global variable section, because constants are stored in the ROM memory.
  • The main function of the program has to be created by using the PROGRAM_MAIN(), or int_main() macros. Those macros create special hidden variables that are used by the system.
  • Environment variables are not supported.

3. Program Registration Details

As was mentioned above, each program in order to be visible should be registered in the system register. The system register is localized in the ./src/programs/program_registration.c file. This file is created automatically by the build script. No other actions are needed to add a new program to the system. To create a new program just create a new folder in the ./src/programs/ folder and add program’s files and Makefile. The only one note is that the program’s name should be the same as folder name. Program’s Makefile is automatically added to the main system’s Makefile.

4. Example

A simple program is presented in this section.

/**
 * @file    example_program.c
 * @brief   This is simple program example
 */

#include <stdio.h>
#include <stdlib.h>

// global variables
GLOBAL_VARIABLES {
    int my_variable;
    int my_zero;
};


// constants
static const my_constant = 100;


/**
 * @brief Example program main function
 * @param argc        number of arguments
 * @param argv        list of arguments
 */
int_main(example_program, STACK_DEPTH_LOW, int argc, char *argv[])
{
        global->my_variable = my_constant;

        // welcome message
        puts("Hello! This is example program!");

        printf("Program name: %s\n", argv[0]);

        puts("Program arguments:");
        for (int i = 1; i < argc; i++) {
                printf("%d: %s\n", i, argv[i]);
        }

        return EXIT_SUCCESS;
}

5. Program Execution

The implemented program can be executed by using several API functions. From the point of view of the user the program can be started by using the terminal. To do this just enter the program name in the terminal of dnx RTOS and hit enter. To start the program from a code, use specified API functions:

  • system() – standard C function (a part of stdlib.h library);
  • program_new() – the API function of dnx RTOS that provides easier program handling. Function can be found in the dnx/os.h library.

Examples:

// ...

system("example_program param_1 param_n");

// ...
// ...

prog_t *my_program = program_new("example_program param_1 param_n",
                                 "/program/cwd/path",
                                 stdin, stdout, stderr);

// ...

6. Libraries

Libraries are stored in the ./src/lib folder and are automatically added to the system by the script at build process. Libraries are added to the system when contains the Makefile file. To use a library in the program just include their header.