.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2020 Chris Johns
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)

.. _Migration_4_11_to_5:

RTEMS 4.11 to RTEMS 5
=====================

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

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,
:c:func:`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:

.. code-block:: c

    #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

Clock Manager
-------------

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

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.

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 :file:`/etc/rc,conf`
file on your target. If your target has no non-volatile media for a file system
create the :file:`rc.conf` file each time your application starts.

The :file:`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.

.. code-block:: c

    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);
      }
    }

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:

.. code-block:: c

    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 );
    }