Chapter 177. Configuration

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

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.

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: 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 … ]
       

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: 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: 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 the Section called 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.

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.

2017-02-09
Documentation license for this page: eCosPro License