Chapter 190. Configuration
Table of Contents
This chapter shows how to include the mDNS support into an eCos configuration, and how to configure it once installed.
190.1. Configuration Overview
The mDNS Responder is contained in a single eCos
package CYGPKG_NET_MDNS
. However, it depends on the
services of a collection of other packages for complete
functionality. Currently the mDNS Responder implementation is tightly
bound with the lwIP TCP/IP networking stack provided by
the CYGPKG_NET_LWIP
package. The lwIP package
provides the packet buffer support (allocation and access routines) as
well as the underlying multicast UDP transport support.
190.1.1. Quick Start
Incorporating the mDNS Responder into your application is
straightforward. The essential starting point is to incorporate the
mDNS eCos package (CYGPKG_NET_MDNS
) into your
configuration.
This may be achieved directly using ecosconfig add on the command line, or the Build->Packages… menu item within the eCos Configuration Tool.
Alternatively, as a convenience, minimal configuration files
(.ecm
files) have been provided to permit an easy
starting point for creating a configuration incorporating the mDNS
Responder. Two configuration files, mdns_bct
and mdns_minimal
, are provided for those intending to use
the Bonjour Conformance Test (BCT), and these can be found in the
directory
where ECOSPRO
/packages/net/mdns/VERSION
/miscECOSPRO
is the base directory of the eCosPro
installation, and VERSION
is the eCosPro (or
package) version.
The mdns_minimal.ecm
file is provided as an example of a low
footprint configuration for resource limited target platforms. These files
may be used either by providing the configuration file name with
the command line ecosconfig import; or with the
File->Import… menu item within the eCos Configuration
Tool. Both these files are basic, incorporating only those packages
which are essential for mDNS operation.
Note | |
---|---|
When building the tests for a limited RAM platform it may be necessary to build only the mDNS tests. The tests for some standard packages may require too much RAM to successfully link. For example to build the mDNS tests for a low resource platform: $ |
190.1.2. Configuring the mDNS Responder
Once added to the eCos configuration, the mDNS Responder package has a number of configuration options.
-
CYGDAT_NET_MDNS_HOSTNAME
The default mDNS
hostname
used when announcing services is provided as part of the standard eCos CDL, but it is expected that real-world applications will manage (via whatever means is appropriate for the target application/platform) their own defaulthostname
configuration, and will then use the mDNS API as required to configure the requiredhostname
prior to enabling a network interface.The mDNS
hostname
is, when assigned, shared across all the active mDNS network interfaces. This is to ensure that a named service is common across all the configured interfaces.Note The actual
hostname
in use may change asynchronously as part of the handling of mDNS name conflicts and rejections. It is possible for another device to attach to the network and cause a newhostname
to be chosen. Thehostname
callback support allows for application control of the namespace used. By default the mDNS Responder provides a simple conflict resolution approach of appending a suffix with a monotonically increasing number.The DNS-SD standard Appendix D “Choice of Factory-Default Names” suggests that the starting name is a simple, user-friendly, human-decipherable, name; and is not automatically derived from some unique identification (e.g. the OUI MAC address).
-
CYGNUM_MDNS_NUM_SERVICE_VECTORS
The number of “sets of service vectors” that can be supported. Each service vector specifies one or more services. To minimise the memory footprint required to support mDNS, the service descriptors are provided by the controlling application as a set of immutable contiguous descriptors. This option controls the number of such sets (minimum 1) that can be held by the mDNS instance.
The CDL configuration should match the target application requirements, and this setting relates to the number of distinct cyg_mdns_service_register calls that can be made. For most embedded applications a value of
1
should suffice since the services to be advertised are known and fixed. However, if an application needs to register and de-register differing sets of services dynamically then this configuration value needs to reflect the number of distinct service sets required.-
CYGNUM_MDNS_MAX_SERVICE_COUNT
- This option specifies the number (count) of service descriptors allowed in an individual service vector. To minimise the memory footprint required to support mDNS this option allows the number of services per vector to be tuned to reflect the requirements of the application.
-
CYGFUN_MDNS_COMMON_NAME
If enabled this option will use the claimed hostname for all registered services. This requires a much smaller RAM footprint than allowing for per-service labels, and may be required for deeply-embedded, low memory, targets if more than a few services are registered. In some environments it may be sufficient to have a single name used for the host and all the announced services.
Note If this feature is enabled then the mDNS Responder will NOT pass the Bonjour Conformance Test (BCT) since it explicitly requests a service label containing spaces, which will pass but then the BCT it then subsequently raises a FAILURE when it sees the hostname label contain spaces.
-
CYGFUN_MDNS_HINFO_OVERRIDE
- By default the mDNS Responder provides an HINFO record using the CPU name “CPU” and the operating system name “ECOSPRO” when announcing the claimed hostname. If this option is enabled then support is provided to allow the application to provide its own simple HINFO record data structure.
-
CYGNUM_MDNS_ANNOUNCE_COUNT
- The mDNS standard allows for between 2 and 8 announcement packets (with increasing inter-packet delays) to be transmitted when a hostname or service is claimed. Since mDNS is based on UDP multicasts it is possible in a congested system, or for limited bandwidth targets, for packets to be missed. This option allows an increased number of packets to be transmitted to minimise the chances of remote systems missing an announcement.
-
CYGNUM_MDNS_TTL_SERVICE
- This option specifies the default “time to live” (TTL) value in seconds that is published for registered services.
-
CYGNUM_MDNS_TTL_ANNOUNCEMENT
- This option specifies the default “time to live” (TTL) value in seconds for announcements.
-
CYGFUN_MDNS_STATS
If enabled then this option adds code to track information that may be useful when ascertaining the resources required for a configuration or when debugging the mDNS Responder.
The information is held in the exported structure object
cyg_mdns_statistics
. This allows the contents to be manually inspected via a debug tool, or for the application to access the data using the structure definition as provided by the header filemdns.h
.See the Section 190.2.1.2, “Statistics” section for more information on use of this configuration option.
-
CYGDBG_MDNS_DEBUG
- If this option is enabled then it provides access to individually controlled CDL debug options for various sub-systems or package features. This allows the detail and amount of debug information to be controlled.
190.1.3. Configuring the mDNS DNS-SD support
Optional support for the DNS-SD API can be enabled in a configuration
by enabling the CYGIMP_NET_MDNS_DNSSD
option. By
default, for backwards compatibility, this option is disabled. This
ensures the extra memory footprint required to support the DNS-SD API
does not impact existing configurations unless explicitly enabled.
-
CYGIMP_NET_MDNS_DNSSD
- If this feature is enabled then the DNS-SD API is provided to allow client applications to perform service discovery.
-
CYGNUM_MDNS_DNSSD_NUM_CALLBACKS
- This option controls the number of active, concurrent, application callbacks supported by the DNS-SD API. A lower value will help minimise the memory footprint required by the mDNS implementation. The value should be tuned to the application requirements. It is possible for an application to be written requiring only a single active callback handler, though multiple handlers may allow different application sub-systems to be maintaining their own “view” of the specific network services or hosts that the particular sub-system is interested in.
190.2. Tuning
190.2.1. Footprint
The current implementation relies on the lwIP heap for allocating the
response packets. This requires that lwIP has been configured with a
large enough CYGNUM_LWIP_MEM_SIZE
heap size. If
ASSERTS are enabled for the build then failure to allocate the
required response packet space will trigger an assert failure,
otherwise the packet transmission operation will be dropped in that
hope that subsequent operations will succeed once some lwIP heap has
become available.
190.2.1.1. Service Labels
The CYGFUN_MDNS_COMMON_NAME
controls whether a
single, common, name is used to announce the host and all registered
services. This option reduces the RAM footprint required, at the
expense of not supporting per-service labels.
For very simple target applications, where maybe only a single service is being announced, it may be deemed that it is not an issue if the hostname and service-label are the same. However, a conflict with either causing a renaming will therefore affect both the hostname and service-label.
190.2.1.2. Statistics
The CYGFUN_MDNS_STATS
option can be enabled to
allow for information counts and sizes to be gathered during
execution. These statistics can help with the tuning of the mDNS world
during development, since monitoring the minimum and maximum usage
counts of resources along with the error counts can indicate resource
starvation issues.
For the network packet memory tracking, a
common cyg_mdns_statistics_memory
structure is
defined and used for each of the packet size records being tracked:
struct cyg_mdns_statistics_memory { cyg_uint32 count; // number of tracked items cyg_uint16 min; // minimum size seen cyg_uint16 max; // maximum size seen };
For example the basic statistics structure is defined as:
struct cyg_mdns_statistics { struct cyg_mdns_statistics_memory errors; // failed packet allocation information struct cyg_mdns_statistics_memory hostname; // hostname probe/announce packets struct cyg_mdns_statistics_memory service; // service probe/announce packets struct cyg_mdns_statistics_memory responses; // query response packets struct cyg_mdns_statistics_memory tx; // packets transmitted };
The errors
information records the number
of failures to allocate a packet buffer, along with the smallest
allocation attempt that failed reported in
the min
field and the largest allocation
attempt that failed in the max
field.
The hostname
, service
and responses
elements record the number of
buffer allocations made for each of the respective mDNS packet type
generators along with the minimum and maximum sizes seen.
The tx
field tracks the actual
generated packet size as transmitted for all of the packet
generators. The maximum recorded by this statistic will normally be
smaller than the largest of the packet generator maximums since it
tracks the size of packet actually transmitted after any name
compression has been applied.
190.2.1.3. Real-World Example
As an example, with careful tuning, it is possible to implement a simple mDNS Responder and webserver with a very small RAM footprint.
For a Cortex-M3 (STM32F207x) based platform, the default mDNS Responder
configuration occupies ~14K of code and requires less than 512-bytes
of RAM for the mDNS Responder specific
state. If CYGFUN_MDNS_COMMON_NAME
is enabled then
the code occupies less than 14K and requires less than 300-bytes of
RAM to hold the mDNS specific context.
The code (normally ROM) and RAM footprint for a complete application will be higher depending on the eCos features configured and application code requirements (e.g. number and size of thread stacks, network buffers, etc.).
2024-03-18 | eCosPro Non-Commercial Public License |