Chapter 177. Configuration

This chapter shows how to include the mDNS support into an eCos configuration, and how to configure it once installed.

177.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.

177.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 ECOSPRO/packages/net/mdns/VERSION/misc where ECOSPRO 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]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:

$ mkdir minimal_bct
$ cd minimal_bct
$ ecosconfig new PLATFORM
[ … ecosconfig output elided … ]
$ ecosconfig import $ECOS_REPOSITORY/net/mdns/VERSION/misc/mdns_minimal.ecm
[ … ecosconfig output elided … ]
$ ecosconfig resolve
$ ecosconfig tree
$ make
[ … make output elided … ]
$ cd net/mdns/current
$ make tests
[ … make output elided … ]

177.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 default hostname configuration, and will then use the mDNS API as required to configure the required hostname 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]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 new hostname to be chosen. The hostname 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]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 file mdns.h.

See the Section 177.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.

177.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.

177.2. Tuning

177.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.

177.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.

177.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.

177.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.).