1 files changed, 90 insertions, 12 deletions
diff --git a/user/migration/v4_11-to-v5.rst b/user/migration/v4_11-to-v5.rst
index 4329771..2dc97ec 100644
--- a/user/migration/v4_11-to-v5.rst
+++ b/user/migration/v4_11-to-v5.rst
@@ -1,6 +1,7 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
 .. Copyright (C) 2020 Chris Johns
+.. Copyright (C) 2020 embedded brains GmbH & Co. KG
 
 .. _Migration_4_11_to_5:
 
@@ -10,33 +11,83 @@ RTEMS 4.11 to RTEMS 5
 This section provides helpful information when migrating from RTEMS 4.11 to
 RTEMS 5.
 
-Configuration
--------------
+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``,
 
-A number of configurations macros have moved as a result of internal changes in
-RTEMS. Some of these will produce a warning indicating the new configuration
-setings you need to define. If you need to run an application on RTEMS 4.11 and
-RTEMS 5 the following code exmaple shows how to conditionally define the
-settings. The example is:
+* ``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
+      #define CONFIGURE_MAXIMUM_FIFOS 10
+      #define CONFIGURE_MAXIMUM_PIPES 10
     #else
-     #define CONFIGURE_IMFS_ENABLE_MKFIFO
+      #define CONFIGURE_IMFS_ENABLE_MKFIFO
     #endif
 
     #define MAX_FILE_DESCRIPTORS 200
     #if __RTEMS_MAJOR__ < 5
-     #define CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS MAX_FILE_DESCRIPTORS
+      #define CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS MAX_FILE_DESCRIPTORS
     #else
-     #define CONFIGURE_MAXIMUM_FILE_DESCRIPTORS       MAX_FILE_DESCRIPTORS
+      #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
 ----------
 
@@ -94,3 +145,30 @@ interface name.
         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 );
+    }