11.1. RTEMS 4.11 to RTEMS 5

This section provides helpful information when migrating from RTEMS 4.11 to RTEMS 5.

11.1.1. Application Configuration Options

The evaluation of application configuration options in <rtems/confdefs.h> was reworked during the RTEMS 5 development cycle. All options which let the user define data structures were removed, this includes

  • CONFIGURE_HAS_OWN_CONFIGURATION_TABLE,

  • CONFIGURE_HAS_OWN_BDBUF_TABLE,

  • CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE,

  • CONFIGURE_HAS_OWN_FILESYSTEM_TABLE,

  • CONFIGURE_HAS_OWN_INIT_TABLE,

  • CONFIGURE_HAS_OWN_MOUNT_TABLE,

  • CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE, and

  • CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE.

The configuration of SMP schedulers changed. For example, RTEMS_SCHEDULER_EDF_SMP() has now only one parameter. Please read section Clustered Scheduler Configuration in the RTEMS Classic API Guide.

A number of configurations options have moved or are obsolete as a result of internal changes in RTEMS. Some of these will produce a warning indicating the new configuration settings you need to define. If you need to run an application on RTEMS 4.11 and RTEMS 5 the following code example shows how to conditionally define the settings. The example is:

#include <rtems.h>

#if __RTEMS_MAJOR__ < 5
  #define CONFIGURE_MAXIMUM_FIFOS 10
  #define CONFIGURE_MAXIMUM_PIPES 10
#else
  #define CONFIGURE_IMFS_ENABLE_MKFIFO
#endif

#define MAX_FILE_DESCRIPTORS 200
#if __RTEMS_MAJOR__ < 5
  #define CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS MAX_FILE_DESCRIPTORS
#else
  #define CONFIGURE_MAXIMUM_FILE_DESCRIPTORS       MAX_FILE_DESCRIPTORS
#endif

11.1.2. Clock Manager

The directive rtems_clock_get() was removed. See section Transition Advice for the Removed rtems_clock_get() in the RTEMS Classic API Guide for alternatives.

11.1.3. File Descriptors

In RTEMS 5.1, the list of free file descriptors has a LIFO ordering in contrast to previous versions where it was a FIFO. This means if an application regularly opens and closes files (or sockets) it sees the whole range of file descriptors. The reason for this change was to increase the time before file descriptors are reused to more likely catch a file descriptor use after close.

This change may surface application issues. If the configured file descriptor maximum (CONFIGURE_MAXIMUM_FILE_DESCRIPTORS) is greater than the FD_SETSIZE defined by Newlib to 64, then calls to select() are undefined behaviour and may corrupt the thread stack. In particular, FD_SET() may result in an out of bounds access. It is possible to define a custom FD_SETSIZE. The application must ensure that the custom FD_SETSIZE is defined before <sys/select.h> is included in all modules used by the application, for example via a global compiler command line define. This applies also to all third-party libraries used by the application.

11.1.4. Networking

The following code samples provides a simple way to initialise and start networking with the BSD Library’s (libbsd) networking stack. The simplest method to configure the networking stack is to provide a /etc/rc,conf file on your target. If your target has no non-volatile media for a file system create the rc.conf file each time your application starts.

The rc.conf support in libbsd provides a number of needed support settings. We recommend you search for FreeBSD and rc.conf to view the available online documentation that FreeBSD provides.

In this example the network interface is cgem0, replace with your interface name.

static const char* rc_conf =
  "# /etc/rc.conf\n" \
  "hostname=\"rtems5-libbsd\"\n" \
  "ifconfig_cgem0=\"inet 10.1.2.3 netmask 255.255.255.0 rxcsum txcsum\"\n" \
  "ifconfig_cgem0_alias0=\"ether 00:80:81:82:83:84\"\n" \
  "defaultrouter=\"10.1.2.1\"\n" \
  "telnetd_enable=\"YES\"\n";

void start_network(void)
{
  FILE *rc;
  int   r;

  /*
   * Initialise libbsd.
   */
  rtems_bsd_initialize();

  /*
   * Create the /etc/rc,conf, assume /etc exists.
   */
  rc = fopen("/etc/rc.conf", "w");
  if (rc_conf == NULL) {
    printf("error: cannot create /etc/rc.conf\n");
    exit(1);
  }

  fprintf(rc, rc_conf);
  fclose(rc);

  /*
   * Arguments are timeout and trace
   */
  r = rtems_bsd_run_etc_rc_conf(30, false);
  if (r < 0) {
    printf("error: loading /etc/rc.conf failed: %s\n",strerror(errno));
    exit(1);
  }
}

11.1.5. Shell Environment

To address resource leaks in the RTEMS shell, the management of shell environments changed. This change may break existing code. Here is an example how a broken Telnet shell can be fixed:

static void
telnet_shell( char *name, void *arg )
{
    rtems_shell_env_t env;

    /* Previous WRONG approach: memset( &env, 0, sizeof( env) ); */

    /* Correct way to initialize the shell environment */
    rtems_shell_dup_current_env( &env );

    env.devname = name;
    env.taskname = "TLNT";
    env.login_check = NULL;
    env.forever = false;

    rtems_shell_main_loop( &env );
}