IP Address Configuration

The following sections provide sample code describing how to configure IP address (IPv4 and IPv6).

For a complete guide on IP addressing, refer to section IP Address Programming.

Configuring an IP Address on an Interface

Each network interface must be configured with at least one IP address. It could be an IPv4 or an IPv6 address or both depending on which modules the TCP-IP stack has enabled.

IPv4

For IPv4, the address configuration may be performed using µC/DHCPc or manually during run-time. If run-time configuration is chosen, the following functions may be utilized to set the IPv4, network mask, and gateway addresses for a specific interface.

NetASCII_Str_to_IP NetIPv4_CfgAddrAdd

More than one set of IPv4 addresses may be configured for a specific network interface by calling the functions above. The constant NET_IPv4_CFG_IF_MAX_NBR_ADDR specified in net_cfg.h determines the maximum number of IPv4 addresses that may be assigned to an interface.

Note that on the default interface, the first IPv4 address added will be the default address used for all default IPv4 communication.

The first function aids the developer by converting a string format IPv4 address such as “192.168.1.2” to its hexadecimal equivalent. The second function is used to configure an interface with the specified IPv4, network mask and gateway addresses. An example is shown in listing Listing - IPv4 Address Configuration Example.

IPv4 Address Configuration Example

CPU_BOOLEAN    cfg_success;
NET_IPv4_ADDR  ipv4_addr;
NET_IPv4_ADDR  ipv4_msk;
NET_IPv4_ADDR  ipv4_gateway;
NET_ERR        err;


(void)NetASCII_Str_to_IP((CPU_CHAR*)"192.168.1.2",   &ipv4_addr,    NET_IPv4_ADDR_SIZE, &err);	/* See Note #1 */
(void)NetASCII_Str_to_IP((CPU_CHAR*)"255.255.255.0", &ipv4_msk,     NET_IPv4_ADDR_SIZE, &err);
(void)NetASCII_Str_to_IP((CPU_CHAR*)"192.168.1.1",   &ipv4_gateway, NET_IPv4_ADDR_SIZE, &err);

cfg_success = NetIPv4_CfgAddrAdd(if_nbr,         												/* See Note #2 */
                                 ipv4_addr,      												/* See Note #3 */
                                 ipv4_msk,       												/* See Note #4 */
                                 ipv4_gateway,   												/* See Note #5 */
                                &err);          					 							/* See Note #6 */

NetASCII_Str_to_IP() requires four arguments. The first function argument is a string representing a valid IP address. The second argument is a pointer to the IP address object that will received the conversion result. The third argument is the size of the address object and the last argument is a pointer to a NET_ERR to contain the return error code. Upon successful conversion, the return error will contain the value NET_ASCII_ERR_NONE and the function will return a variable of type NET_IP_ADDR_FAMILY containing the family type (IPv4 or IPv6) of the address converted.
The first argument is the number representing the network interface that is to be configured. This value is obtained as the result of a successful call to NetIF_Add().
The second argument is the NET_IPv4_ADDR value representing the IPv4 address to be configured.
The third argument is the NET_IPv4_ADDR value representing the subnet mask address that is to be configured.
The fourth argument is the NET_IPv4_ADDR value representing the default gateway IPv4 address that is to be configured.
The fifth argument is a pointer to a NET_ERR variable containing the return error code for the function. If the interface address information is configured successfully, then the return error code will contain the value NET_IPv4_ERR_NONE. Additionally, function returns a Boolean value of DEF_OK or DEF_FAIL depending on the result. Either the return value or the NET_ERR variable may be checked for return status; however, the NET_ERR contains more detailed information and should therefore be the preferred check.

IPv6

Currently, the µC/TCP-IP stack only support manual static IPv6 address configuration and IPv6 Stateless Address Auto-Configuration. Dynamic address configuration with DHCPv6 is not yet supported.

Manual Static Address Configuration

the following functions may be utilized to set the IPv6 address for a specific interface:

NetASCII_Str_to_IP
NetIPv6_CfgAddrAdd 
NetIPv6_CfgAddrHookSet

More than one set of IPv6 addresses may be configured for a specific network interface by calling the functions above. The constant NET_IPv6_CFG_IF_MAX_NBR_ADDR specified in net_cfg.h determines the maximum number of IPv6 addresses that may be assigned to an interface.

Note that on the default interface, the first IPv6 address added will be the default address used for all default IPv6 communication.

The first function aids the developer by converting a string format IPv6 address such as “fe80::1111:1111” to its network equivalent. The second function is used to configure an interface with the specified IPv6 address. An example is shown in listing Listing - IPv6 Address Configuration Example.

IPv6 Address Configuration Example

CPU_BOOLEAN    cfg_success;
NET_IPv6_ADDR  ipv6_addr;
NET_FLAGS      ipv6_flags;
NET_ERR        err;
           
           
(void)NetASCII_Str_to_IP((CPU_CHAR *)"fe80::1111:1111", 	/* See Note #1 */
                                     &ipv6_addr, 
                                      NET_IPv6_ADDR_SIZE, 
                                     &err);
 
ipv6_flags = 0;                                             
DEF_BIT_SET(ipv6_flags, NET_IPv6_FLAG_BLOCK_EN);            /* See Note #2 */
DEF_BIT_SET(ipv6_flags, NET_IPv6_FLAG_DAD_EN);              /* See Note #3 */
 
cfg_success = NetIPv6_CfgAddrAdd(if_nbr,         			/* See Note #4 */
                                &ipv6_addr,      			/* See Note #5 */
                                 64,             			/* See Note #6 */
                                 ipv6_flags,                /* See Note #7 */  
                                &err);           			/* See Note #8 */

See NetASCII_Str_to_IP for more details.
Set Address Configuration as blocking.
Enable DAD with Address Configuration.
The first argument is the number representing the network interface that is to be configured. This value is obtained as the result of a successful call to NetIF_Add().
The second argument is the pointer to the NET_IPv6_ADDR value representing the IPv6 address to be configured.
The third argument is the IPv6 prefix length of the address to be configured.
The fourth argument is a set of network flags holding options specific to the address configuration process.
The fifth argument is a pointer to a NET_ERR variable containing the return error code for the function. If the interface address information is configured successfully, then the return error code will contain the value NET_IPv6_ERR_NONE. Additionally, function returns a Boolean value of DEF_OK or DEF_FAIL depending on the result. Either the return value or the NET_ERR variable may be checked for return status; however, the NET_ERR contains more detailed information and should therefore be the preferred check.

As shown in Listing - IPv6 Address Configuration Example, the NetIPv6_CfgAddrAdd() function can take as argument a set of network flags. The following options are available :

Flags	Description
`NET_IPv6_FLAG_BLOCK_EN`	Enables blocking mode.
`NET_IPv6_FLAG_DAD_EN`	Enables Duplication Address Detection (DAD) with the address configuration process.

It is therefore possible to make the function blocking or not, or to enable Duplication Address Detection with the address configuration.

If the function is made none blocking, it is possible to set a hook function to advertise the application when the address configuration process has finished. The API function NetIPv6_CfgAddrHookSet can be used to set the hook function. Refer to section IPv6 Static Address Configuration Hook Function for all the details on the hook function format and usage. Listing - Non-Blocking IPv6 Address Configuration Example shows an example of a non-blocking IPv6 static address configuration.

Listing - Non-Blocking IPv6 Address Configuration Example

CPU_BOOLEAN    cfg_success;
NET_IPv6_ADDR  ipv6_addr;
NET_FLAGS      ipv6_flags;
NET_ERR        err;
           
           
(void)NetASCII_Str_to_IP((CPU_CHAR *)"fe80::1111:1111", 	/* Convert IPv6 string address to 128 bit address.      */
                                     &ipv6_addr, 
                                      NET_IPv6_ADDR_SIZE, 
                                     &err);

NetIPv6_AddrAutoCfgHookSet(if_nbr,                          /* Set hook function to received addr cfg result.       */
                          &App_AddrCfgResult,				/* TODO update pointer to hook fnct implemented in App. */
                          &err);  
 
ipv6_flags = 0;                                             
DEF_BIT_CLR(ipv6_flags, NET_IPv6_FLAG_BLOCK_EN);            /* Set Address Configuration as non-blocking.           */
DEF_BIT_SET(ipv6_flags, NET_IPv6_FLAG_DAD_EN);              /* Enable DAD with Address Configuration.               */
 
cfg_success = NetIPv6_CfgAddrAdd(if_nbr,         			/* Add a statically-configured IPv6 host address to ... */
                                &ipv6_addr,      			/* ... the interface.                                   */
                                 64,             			
                                 ipv6_flags,               
                                &err);

Stateless Address Auto-Configuration

The IPv6 protocol defines an address Auto-Configuration procedure allowing a network interface to set itself an IPv6 Link-Local address based on its Interface ID. The Auto-Configuration process will also query the local network to found an IPv6 router that could send prefix information to set an IPv6 global address.

The µC/TCP-IP stack supports only the EUI-64 format for interface ID. This format creates a 64 bits ID based on the 48 bits MAC address of the interface. Those 64 bits will become the 64 least significant bits of the IPv6 addresses configured with the Stateless Auto-Configuration process.

The following functions may be used to configure the IPv6 Stateless Auto-Configuration process:

NetIPv6_AddrAutoCfgEn

NetIPv6_AddrAutoCfgDis

NetIPv6_AddrAutoCfgHookSet

The IPv6 Auto-Configuration procedure inside the µC/TCP-IP stack is a non-blocking process. To recover the result of the Auto-Configuration, a hook function can be configured that will be called by the TCP/IP stack when the Auto-Configuration has finished. The API function used to set the hook function is NetIPv6_AddrAutoCfgHookSet. Refer to section IPv6 Stateless Address Auto-Configuration Hook Function for all the details on the Auto-Configuration hook function format and usage and refer to section Sample applications for examples of Auto-Configuration.