rtems/rtems-libbsd
1
0
Fork 0
mirror of https://git.rtems.org/rtems-libbsd/ synced 2025-10-14 04:59:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

libbsd.txt: Move initialization description

Browse Source
This commit is contained in:
Sebastian Huber
2022-05-23 10:19:40 +02:00
parent 92219bc66e
commit 310f6fb70d
2 changed files with 134 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
README.rst
View File

@@ -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
========

126
libbsd.txt
View File

@@ -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