1 files changed, 47 insertions, 1 deletions
diff --git a/user/migration/v4_11-to-v5.rst b/user/migration/v4_11-to-v5.rst
index a0cab02..2dc97ec 100644
--- a/user/migration/v4_11-to-v5.rst
+++ b/user/migration/v4_11-to-v5.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
 .. Copyright (C) 2020 Chris Johns
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020 embedded brains GmbH & Co. KG
 
 .. _Migration_4_11_to_5:
 
@@ -69,6 +69,25 @@ 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
 ----------
 
@@ -126,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 );
+    }