[libbsd 11/22] libbsd.txt: Move initialization description
Sebastian Huber
sebastian.huber at embedded-brains.de
Mon May 23 14:33:34 UTC 2022
---
README.rst | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++
libbsd.txt | 126 -------------------------------------------------
2 files changed, 134 insertions(+), 126 deletions(-)
diff --git a/README.rst b/README.rst
index 9aa424dc..cfdb46b3 100644
--- a/README.rst
+++ b/README.rst
@@ -159,6 +159,140 @@ You can also create and provide your own buildset configuration. But remember
that it's quite easy to break something by disabling the wrong modules. Only
the configurations in the ``buildset`` directory are officially maintained.
+Initialization
+==============
+
+To initialise the LibBSD create a suitable ``rc.conf`` file. The FreeBSD man
+page `RC.CONF(5) <https://www.freebsd.org/cgi/man.cgi?rc.conf>`_ provides the
+details needed to create a suitable format file
+
+You can call one of three functions to run the initialisation once LibBSD has
+initialised:
+
+* ``rtems_bsd_run_etc_rc_conf()``: Run ``/etc/rc.conf``.
+* ``rtems_bsd_run_rc_conf()``: Run a user supplied file.
+* ``rtems_bsd_run_rc_conf_script()``: Run the in memory line feed separated text string.
+
+For exapmle:
+
+.. code-block:: c
+
+ void
+ network_init(void)
+ {
+ rtems_status_code sc;
+
+ sc = rtems_bsd_initialize();
+ assert(sc == RTEMS_SUCCESSFUL);
+
+ rtems_bsd_run_etc_rc_conf(true); /* verbose = true */
+ }
+
+By default the networking support is builtin. Other directives can be added and
+are found in ``machine/rtems-bsd-rc-conf-directives.h``. Please check the file
+for the list.
+
+The following network names are supported:
+
+.. code-block:: none
+
+ cloned_interfaces
+ ifconfig_'interface'
+ defaultrouter
+ hostname
+
+For example:
+
+.. code-block:: none
+
+ #
+ # My BSD initialisation.
+ #
+ hostname="myhost"
+ cloned_interfaces="vlan0 vlan1"
+ ifconfig_re0="inet inet 10.10.10.10 netmask 255.255.255.0"
+ fconfig_vlan0="inet 10.11.10.10 255.255.255.0 vlan 101 vlandev re0"
+ defaultrouter="10.10.10.1"
+
+You can also intialise the LibBSD using code. The following code to
+initialize the LibBSD:
+
+.. code-block:: c
+
+ #include <assert.h>
+ #include <sysexits.h>
+
+ #include <rtems/bsd/bsd.h>
+
+ void
+ network_init(void)
+ {
+ rtems_status_code sc;
+ int exit_code;
+
+ sc = rtems_bsd_initialize();
+ assert(sc == RTEMS_SUCCESSFUL);
+
+ exit_code = rtems_bsd_ifconfig_lo0();
+ assert(exit_code == EX_OK);
+ }
+
+This performs the basic network stack initialization with a loopback interface.
+Further initialization must be done using the standard FreeBSD network
+configuration commands
+`IFCONFIG(8) <http://www.freebsd.org/cgi/man.cgi?query=ifconfig&sektion=8>`_
+using ``rtems_bsd_command_ifconfig()`` and
+`ROUTE(8) <http://www.freebsd.org/cgi/man.cgi?query=route&sektion=8>`_
+using ``rtems_bsd_command_route()``. For an example, please have a look at
+`default-network-init.h <testsuite/include/rtems/bsd/test/default-network-init.h>`_.
+
+Task Priorities and Stack Size
+==============================
+
+The default task priority is 96 for the interrupt server task (name "IRQS"), 98
+for the timer server task (name "TIME") and 100 for all other tasks. The
+application may provide their own implementation of the
+``rtems_bsd_get_task_priority()`` function if different values are desired (for
+example in the translation unit which calls ``rtems_bsd_initialize()``).
+
+The task stack size is determined by the ``rtems_bsd_get_task_stack_size()``
+function which may be provided by the application in case the default is not
+appropriate.
+
+Size for Allocator Domains
+==========================
+
+The size for an allocator domain can be specified via the
+``rtems_bsd_get_allocator_domain_size()`` function. The application may provide
+their own implementation of the ``rtems_bsd_get_allocator_domain_size()``
+function (for example in the module which calls ``rtems_bsd_initialize()``) if
+different values are desired. The default size is 8MiB for all domains.
+
+Redirecting or Disabling the Output
+===================================
+
+A lot of system messages are printed to the ``stdout`` by default. If you want to
+redirect them you can overwrite the default print handler. That can even be done
+before the libbsd initialization to catch all messages. An example would look
+like follows:
+
+.. code-block:: c
+
+ int my_vprintf_handler(int level, const char *fmt, va_list ap) {
+ /* Do something with the messages. */
+
+ return number_of_printed_chars;
+ }
+
+ ...
+ /* In your initialization: */
+ rtems_bsd_vprintf_handler old;
+ old = rtems_bsd_set_vprintf_handler(my_vprintf_handler);
+ ...
+
+As a special case, you can set the ``rtems_bsd_vprintf_handler_mute(...)``
+provided by LibBSD to suppress all output.
+
Branches
========
diff --git a/libbsd.txt b/libbsd.txt
index c20a7083..8d5dec2e 100644
--- a/libbsd.txt
+++ b/libbsd.txt
@@ -7,132 +7,6 @@ RTEMS BSD Library Guide
== Getting Started
-=== BSD Library Initialization ===
-
-To initialise the BSD Library create a suitable rc.conf file. The FreeBSD man
-page rc.conf(5) provides the details needed to create a suitable format file:
-
- https://www.freebsd.org/cgi/man.cgi?rc.conf
-
-You can call one of three functions to run the initialisation once BSD has
-initialised:
-
- - rtems_bsd_run_etc_rc_conf: Run /etc/rc.conf.
- - rtems_bsd_run_rc_conf: Run a user supplied file.
- - rtems_bsd_run_rc_conf_script: Run the in memory line feed separated text string.
-
-For exapmle:
-
- void
- network_init(void)
- {
- rtems_status_code sc;
-
- sc = rtems_bsd_initialize();
- assert(sc == RTEMS_SUCCESSFUL);
-
- rtems_bsd_run_etc_rc_conf(true); /* verbose = true */
-
-}
-
-By default the networking support is builtin. Other directives can be added and
-are found in 'machine/rtems-bsd-rc-conf-directives.h'. Please check the file
-for the list.
-
-The following network names are supported:
-
- cloned_interfaces
- ifconfig_'interface'
- defaultrouter
- hostname
-
-For example:
-
- #
- # My BSD initialisation.
- #
- hostname="myhost"
- cloned_interfaces="vlan0 vlan1"
- ifconfig_re0="inet inet 10.10.10.10 netmask 255.255.255.0"
- fconfig_vlan0="inet 10.11.10.10 255.255.255.0 vlan 101 vlandev re0"
- defaultrouter="10.10.10.1"
-
-You can also intialise the BSD library using code. The following code to
-initialize the BSD library:
-
--------------------------------------------------------------------------------
-#include <assert.h>
-#include <sysexits.h>
-
-#include <rtems/bsd/bsd.h>
-
-void
-network_init(void)
-{
- rtems_status_code sc;
- int exit_code;
-
- sc = rtems_bsd_initialize();
- assert(sc == RTEMS_SUCCESSFUL);
-
- exit_code = rtems_bsd_ifconfig_lo0();
- assert(exit_code == EX_OK);
-}
--------------------------------------------------------------------------------
-
-This performs the basic network stack initialization with a loopback interface.
-Further initialization must be done using the standard BSD network
-configuration commands
-http://www.freebsd.org/cgi/man.cgi?query=ifconfig&sektion=8[IFCONFIG(8)]
-using `rtems_bsd_command_ifconfig()` and
-http://www.freebsd.org/cgi/man.cgi?query=route&sektion=8[ROUTE(8)]
-using `rtems_bsd_command_route()`. For an example please have a look at
-`testsuite/include/rtems/bsd/test/default-network-init.h`.
-
-=== Task Priorities and Stack Size ===
-
-The default task priority is 96 for the interrupt server task (name "IRQS"), 98
-for the timer server task (name "TIME") and 100 for all other tasks. The
-application may provide their own implementation of the
-`rtems_bsd_get_task_priority()` function (for example in the module which calls
-`rtems_bsd_initialize()`) if different values are desired.
-
-The task stack size is determined by the `rtems_bsd_get_task_stack_size()`
-function which may be provided by the application in case the default is not
-appropriate.
-
-=== Size for Allocator Domains ===
-
-The size for an allocator domain can be specified via the
-`rtems_bsd_get_allocator_domain_size()` function. The application may provide
-their own implementation of the `rtems_bsd_get_allocator_domain_size()`
-function (for example in the module which calls `rtems_bsd_initialize()`) if
-different values are desired. The default size is 8MiB for all domains.
-
-=== Redirecting or Disabling the Output ===
-
-A lot of system messages are printed to the stdout by default. If you want to
-redirect them you can overwrite the default print handler. That can even be done
-before the libbsd initialization to catch all messages. An example would look
-like follows:
-
--------------------------------------------------------------------------------
-int my_vprintf_handler(int level, const char *fmt, va_list ap) {
- /* Do something with the messages. */
-
- return number_of_printed_chars;
-}
-
-...
- /* In your initialization: */
- rtems_bsd_vprintf_handler old;
- old = rtems_bsd_set_vprintf_handler(my_vprintf_handler);
-...
--------------------------------------------------------------------------------
-
-As a special case, you can set the `rtems_bsd_vprintf_handler_mute(...)`
-provided by libbsd to suppress all output.
-
== Network Stack Features
http://roy.marples.name/projects/dhcpcd/index[DHCPCD(8)]:: DHCP client
--
2.35.3
More information about the devel
mailing list