Network Core API#

The application programming interfaces (APIs) to the whole Network core stack are described in this section.

Network Initialization#

General Network Utilities#

ASCII Functions#

Network Buffer#

Network Connection#

Network Timer#

Network Interface#

Ethernet Network Interface#

Wireless Network Interface#

DHCP Client#

DNS Client#

ARP#

NDP#

IGMP#

MLDP#

ICMP#

IPv4#

IPv6#

TCP#

Socket Functions#

BSD Sockets Functions#

Network Application Interface#

Network Initialization API#

Net_Init()#

Description#

Initializes Network stack.

Files#

net.h/net.c

Prototype#

void Net_Init (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of these return error codes from this function :

• RTOS_ERR_NONE

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_SEG_OVF

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_NOT_AVAIL

Returned Value#

None.

Notes / Warnings#

1. Net_Init() must be called:

   (a) Only once from a product's application.

   (b) After product's OS has been initialized.

Net_ConfigureCoreTaskStk()#

Description#

Configures the Network core task's stack.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureCoreTaskStk (CPU_INT32U   stk_size_elements,
                                void        *p_stk)

Arguments#

stk_size_elements

Size, in stack elements, of the task's stack.

p_stk

Pointer to base of the task's stack. If DEF_NULL, stack will be allocated from Common's memory segment.

Returned Value#

None.

Notes / Warnings#

1. This function is optional, if it is not called, the default value will be used.

2. This function MUST be called before the Network module is initialized via the Net_Init() function.

3. In order to change the priority of the Network core task, use the function Net_CoreTaskPrioSet() .

Net_ConfigureCoreSvcTaskStk()#

Description#

Configures the Network service task's stack. The service task is used for core modules like DHCP.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureCoreSvcTaskStk (CPU_INT32U   stk_size_elements,
                                   void        *p_stk)

Arguments#

stk_size_elements

Size, in stack elements, of the task's stack.

p_stk

Pointer to base of the task's stack. If DEF_NULL, stack will be allocated from Common's memory segment.

Returned Value#

None.

Notes / Warnings#

1. This function is optional, if it is not called, the default value will be used.

2. This function MUST be called before the Network module is initialized via the Net_Init() function.

3. In order to change the priority of the Network core task, use the function Net_SvcTaskPrioSet().

Net_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data for the network core.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. DEF_NULL means general purpose heap segment.

Returned Value#

None.

Notes / Warnings#

1. This function is optional, if it is not called, the default value will be used.

2. This function MUST be called before the Network module is initialized via the Net_Init() function.

Net_ConfigureDNS_Client()#

Description#

Configure the DNS Client module parameters.

Files#

net.h/net.c

Prototype#

void  Net_ConfigureDNS_Client(DNSc_CFG  *p_cfg)

Arguments#

p_cfg

Pointer to the structure containing the new DNS client parameters.

Returned Value#

None.

Notes / Warnings#

1. This function is optional, if it is not called, the default value will be used.

2. This function MUST be called before the Network module is initialized via the Net_Init() function.

Net_CoreTaskPrioSet()#

Description#

Assigns a new priority to the Network core task.

Files#

net.h/net.c

Prototype#

void  Net_CoreTaskPrioSet(CPU_INT08U   prio,
                          RTOS_ERR    *p_err)

Arguments#

prio

New priority of the the Network core task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

1. This function cannot be called before the Network module has been initialized via the Net_Init() function.

Net_CoreSvcTaskPrioSet()#

Description#

Assigns a new priority to the Network core service task.

Files#

net.h/net.c

Prototype#

void  Net_CoreSvcTaskPrioSet(CPU_INT08U   prio,
                             RTOS_ERR    *p_err)

Arguments#

prio

New priority of the the Network core service task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

1. This function cannot be called before the Network module has been initialized via the Net_Init() function.

General Network Utilities API#

NetUtil_TS_Get()#

Description#

Gets the current Internet Timestamp.

Files#

net_util.h/net_util.c

Prototype#

NET_TS  NetUtil_TS_Get (void)

Arguments#

Returned Value#

Internet Timestamp.

Notes / Warnings#

1. "The Timestamp is a right-justified, 32-bit timestamp in milliseconds since midnight UT [Universal Time]" (RFC #791, Section 3.1 'Options : Internet Timestamp').

2. The developer is responsible for providing a real-time clock with correct time-zone configuration to implement the Internet Timestamp, if possible.

NetUtil_TS_Get_ms()#

Description#

Gets the current millisecond timestamp.

Files#

net_util.h/net_util.c

Prototype#

NET_TS_MS  NetUtil_TS_Get_ms (void)

Arguments#

Returned Value#

Timestamp (in milliseconds).

Notes / Warnings#

1. (a)

   1. Although RFC #2988, Section 4 states that "there is no requirement for the clock granularity G used for computing [TCP] RTT measurements ... experience has shown that finer clock granularities (<= 100 msec) perform somewhat better than more coarse granularities".

   2. (a) RFC #2988, Section 2.4 states that "whenever RTO is computed, if it is less than 1 second then the RTO SHOULD be rounded up to 1 second".

      (b) RFC #1122, Section 4.2.3.1 states that "the recommended ... RTO ... upper bound should be 2*MSL" where RFC #793, Section 3.3 'Sequence Numbers : Knowing When to Keep Quiet' states that "the Maximum Segment Lifetime (MSL) is ... to be 2 minutes".

      (c) Therefore, the developer is responsible for providing a timestamp clock with adequate resolution to satisfy the clock granularity (see Note #1(a)) & adequate range to satisfy the minimum/maximum TCP RTO values (see Note #1(b)).

      Therefore, the required upper bound is :

      2 * MSL = 2 * 2 minutes = 4 minutes = 240 seconds

   (b) Therefore, the developer is responsible for providing a timestamp clock with adequate resolution to satisfy the clock granularity (see Note #1(a)) & adequate range to satisfy the minimum/maximum TCP RTO values (see Note #1(b)).

NET_UTIL_HOST_TO_NET_16()#

Convert 16-bit integer values from CPU host-order to network-order.

Files#

net_util.h

Prototype#

          NET_UTIL_HOST_TO_NET_16(val);

Arguments#

val

16-bit integer data value to convert.

Returned Value#

16-bit integer value in network-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 16-bit integer must start on appropriately-aligned CPU addresses. This means that all 16-bit words must start on addresses that are multiples of 2 bytes.

NET_UTIL_HOST_TO_NET_32()#

Convert 32-bit integer values from CPU host-order to network-order.

Files#

net_util.h

Prototype#

          NET_UTIL_HOST_TO_NET_32(val);

Arguments#

val

32-bit integer data value to convert.

Returned Value#

32-bit integer value in network-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 32-bit integer must start on appropriately-aligned CPU addresses. This means that all 32-bit words must start on addresses that are multiples of 4 bytes.

NET_UTIL_NET_TO_HOST_16()#

Convert 16-bit integer values from network-order to CPU host- order.

Files#

net_util.h

Prototype#

          NET_UTIL_NET_TO_HOST_16(val);

Arguments#

val

16-bit integer data value to convert.

Returned Value#

16-bit integer value in CPU host-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 16-bit integer must start on appropriately-aligned CPU addresses. This means that all 16-bit words must start on addresses that are multiples of 2 bytes.

NET_UTIL_NET_TO_HOST_32()#

Convert 32-bit integer values from network-order to CPU host- order.

Files#

net_util.h

Prototype#

          NET_UTIL_NET_TO_HOST_32(val);

Arguments#

val

32-bit integer data value to convert.

Returned Value#

32-bit integer value in CPU host-order.

Required Configuration#

None.

Notes / Warnings#

For microprocessors that require data access to be aligned to appropriate word boundaries, val and any variable to receive the returned 32-bit integer must start on appropriately-aligned CPU addresses. This means that all 32-bit words must start on addresses that are multiples of 4 bytes.

ASCII Functions API#

NetASCII_IPv4_to_Str()#

Description#

Converts a network protocol IPv4 address in host-order into an IPv4 address ASCII string in dotted-decimal notation.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_IPv4_to_Str (NET_IPv4_ADDR   addr_ip,
                            CPU_CHAR       *p_addr_ip_ascii,
                            CPU_BOOLEAN     lead_zeros,
                            RTOS_ERR       *p_err)

Arguments#

addr_ip

IPv4 address.

p_addr_ip_ascii

Pointer to an ASCII character array that will receive the return IPv4.

lead_zeros

• DEF_NO Do NOT prepend leading zeros to each decimal octet value.

• DEF_YES Prepend leading zeros to each decimal octet value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

1. (a)

   1. RFC #1983 states that "dotted decimal notation ... refers [to] IPv4 addresses of the form A.B.C.D; where each letter represents (in decimal) one byte of a four byte IP address."

   2. In other words, the dotted-decimal IP address notation separates four decimal octet values by the dot, or period, character ('.'). Each decimal value represents one octet of the IP address starting with the most significant octet in network-order.

      IP Address Examples : 192.168.1.64 = 0xC0A80140

   (b)

   1. The return dotted-decimal IPv4 address ASCII string formats EXACTLY four decimal values separated by EXACTLY three dot characters and terminated with the NULL character.

   2. The size of the ASCII character array that will receive the returned IP address ASCII string SHOULD be greater than or equal to NET_ASCII_LEN_MAX_ADDR_IP.

2. (a) Leading zeros option prepends leading '0's prior to the first non-zero digit in each decimal octet value. The number of leading zeros is such that the decimal octet's number of decimal digits is equal to the maximum number of digits (3).

   (b) If leading zeros option DISABLED and the decimal value of the octet is zero, then one digit of '0' value is formatted.

NetASCII_IPv6_to_Str()#

Description#

Converts a network protocol IPv6 address in host-order into an IPv6 address ASCII string in dotted-decimal notation.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_IPv6_to_Str (NET_IPv6_ADDR  *p_addr_ip,
                            CPU_CHAR       *p_addr_ip_ascii,
                            CPU_BOOLEAN     hex_lower_case,
                            CPU_BOOLEAN     lead_zeros,
                            RTOS_ERR       *p_err)

Arguments#

p_addr_ip

Pointer to IPv6 address.

p_addr_ip_ascii

Pointer to an ASCII character array that will receive the return IPv6 address.

hex_lower_case

• DEF_YES, hexadecimal value will be in lower case

• DEF_NO, otherwise.

lead_zeros

Prepend leading zeros option (see Note #2) :

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

NetASCII_MAC_to_Str()#

Description#

Converts an Ethernet MAC address into an Ethernet MAC address ASCII string.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_MAC_to_Str (CPU_INT08U   *p_addr_mac,
                           CPU_CHAR     *p_addr_mac_ascii,
                           CPU_BOOLEAN   hex_lower_case,
                           CPU_BOOLEAN   hex_colon_sep,
                           RTOS_ERR     *p_err)

Arguments#

p_addr_mac

Pointer to a memory buffer that contains the MAC address.

p_addr_mac_ascii

Pointer to an ASCII character array that will receive the return MAC

hex_lower_case

• DEF_NO Format alphabetic hexadecimal characters in upper case.

• DEF_YES Format alphabetic hexadecimal characters in lower case.

hex_colon_sep

• DEF_NO Separate hexadecimal values with a hyphen character.

• DEF_YES Separate hexadecimal values with a colon character.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

1. (a)

   1. RFC #1700, Section 'ETHERNET VENDOR ADDRESS COMPONENTS' states that "Ethernet addresses ... should be written hyphenated by octets (e.g., 12-34-56-78-9A-BC)".

   2. In other words, the (Ethernet) MAC address notation separates six hexadecimal octet values by the hyphen character ('-') or by the colon character (':'). Each hexadecimal value represents one octet of the MAC address starting with the most significant octet in network-order.

   (b)

   1. The return MAC address ASCII string formats EXACTLY six hexadecimal values separated by EXACTLY five hyphen characters or colon characters and terminated with the NULL character.

   2. The size of the ASCII character array that will receive the returned MAC address ASCII string MUST be greater than or equal to NET_ASCII_LEN_MAX_ADDR_MAC.

2. (a) The size of the memory buffer that contains the MAC address SHOULD be greater than or equal to NET_ASCII_NBR_OCTET_ADDR_MAC.

NetASCII_Str_to_IP()#

Description#

Converts a string representation of an IP address (IPv4 or IPv6) to its TCP/IP stack intern representation.

Files#

net_ascii.h/net_ascii.c

Prototype#

NET_IP_ADDR_FAMILY  NetASCII_Str_to_IP (CPU_CHAR    *p_addr_ip_ascii,
                                        void        *p_addr,
                                        CPU_INT08U   addr_max_len,
                                        RTOS_ERR    *p_err)

Arguments#

p_addr_ip_ascii

Pointer to an ASCII string that contains a decimal IP address.

p_addr

Pointer to the variable that will received the converted IP address.

addr_max_len

Size of the variable that will received the converted IP address:

• NET_IPv4_ADDR_SIZE

• NET_IPv6_ADDR_SIZE

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

The IP family of the converted address, if no errors:

• NET_IP_ADDR_FAMILY_IPv4

• NET_IP_ADDR_FAMILY_IPv6

Otherwise,

NET_IP_ADDR_FAMILY_UNKNOWN

Notes / Warnings#

None.

NetASCII_Str_to_IPv4()#

Description#

Converts an IPv4 address ASCII string in dotted-decimal notation to a network protocol IPv4 address in host-order.

Files#

net_ascii.h/net_ascii.c

Prototype#

NET_IPv4_ADDR  NetASCII_Str_to_IPv4 (CPU_CHAR  *p_addr_ip_ascii,
                                     RTOS_ERR  *p_err)

Arguments#

p_addr_ip_ascii

Pointer to an ASCII string that contains a dotted-decimal IPv4 address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

Host-order IPv4 address represented by ASCII string, if NO error(s). NET_IPv4_ADDR_NONE, otherwise.

Notes / Warnings#

1. (a)

   1. RFC #1983 states that "dotted decimal notation ... refers [to] IP addresses of the form A.B.C.D; where each letter represents, in decimal, one byte of a four byte IP address".

   2. In other words, the dotted-decimal IP address notation separates four decimal octet values by the dot (or period) character ('.'). Each decimal value represents one octet of the IP address starting with the most significant octet in network-order.

      IP Address Examples : 192.168.1.64 = 0xC0A80140

   (b) Therefore, the dotted-decimal IP address ASCII string MUST :

   1. Include ONLY decimal values and the dot, or period, character ('.') ; ALL other characters are trapped as invalid, including any leading or trailing characters.

   2. Include UP TO four decimal values separated by UP TO three dot characters and MUST be terminated with the NULL character.

   3. Ensure that each decimal value's number of decimal digits, including leading zeros, does NOT exceed the maximum number of digits(10).

      (A) However, any decimal value's number of decimal digits, including leading zeros, MAY be less than the maximum number of digits.

   4. Ensure that each decimal value does NOT exceed the maximum value for its form:

      1. a.b.c.d - 255.255.255.255

      2. a.b.c - 255.255.65535

      3. a.b - 255.16777215

      4. a - 4294967295

2. To avoid possible integer arithmetic overflow, the IP address octet arithmetic result MUST be declared as an integer data type with a greater resolution (i.e., greater number of bits) than the IP address octet data type(s).

NetASCII_Str_to_IPv6()#

Description#

Converts an IPv6 address ASCII string in common-decimal notation to a network protocol IPv6 address in host-order.

Files#

net_ascii.h/net_ascii.c

Prototype#

NET_IPv6_ADDR  NetASCII_Str_to_IPv6 (CPU_CHAR  *p_addr_ip_ascii,
                                     RTOS_ERR  *p_err)

Arguments#

p_addr_ip_ascii

Pointer to an ASCII string that contains a common-decimal IPv6 address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

Host-order IPv6 address represented by ASCII string, if NO error(s). NET_IPv6_ADDR_NONE, otherwise.

Notes / Warnings#

None.

NetASCII_Str_to_MAC()#

Description#

Converts an Ethernet MAC address ASCII string to an Ethernet MAC address.

Files#

net_ascii.h/net_ascii.c

Prototype#

void  NetASCII_Str_to_MAC (CPU_CHAR    *p_addr_mac_ascii,
                           CPU_INT08U  *p_addr_mac,
                           RTOS_ERR    *p_err)

Arguments#

p_addr_mac_ascii

Pointer to an ASCII string that contains a MAC address.

p_addr_mac

Pointer to a memory buffer that will receive the converted MAC address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

None.

Notes / Warnings#

1. (a)

   1. RFC #1700, Section 'ETHERNET VENDOR ADDRESS COMPONENTS' states that "Ethernet addresses ... should be written hyphenated by octets (e.g., 12-34-56-78-9A-BC)".

   2. In other words, the (Ethernet) MAC address notation separates six hexadecimal octet values by the hyphen character ('-') or by the colon character (':'). Each hexadecimal value represents one octet of the MAC address starting with the most significant octet in network-order.

   (b) Therefore, the MAC address ASCII string MUST :

   1. Include ONLY hexadecimal values and the hyphen character ('-') or the colon character (':') ; ALL other characters are trapped as invalid, including any leading or trailing characters.

   2. Include EXACTLY six hexadecimal values separated by EXACTLY five hyphen characters or colon characters and MUST be terminated with the NULL character.

   3. Ensure that each hexadecimal value's number of digits does NOT exceed the maximum number of digits (2.).

      (A) However, any hexadecimal value's number of digits MAY be less than the maximum number of digits.

2. (a) The size of the memory buffer that will receive the converted MAC address MUST be greater than or equal to NET_ASCII_NBR_OCTET_ADDR_MAC.

   (b) MAC address memory buffer array accessed by octets.

   (c) MAC address memory buffer array cleared in case of any error(s).

Network Buffer API#

NetBuf_PoolStatGet()#

Description#

Gets the network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_PoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

• Network buffer statistics pool, if NO error(s).

• NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_PoolStatResetMaxUsed()#

Description#

Resets the network buffer statistics pool's maximum number of used entries.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_PoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

NetBuf_RxLargePoolStatGet()#

Description#

Gets the large receive network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_RxLargePoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

Large receive network buffer statistics pool, if NO error(s). NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_RxLargePoolStatResetMaxUsed()#

Description#

Resets the large receive network buffer statistics pool's maximum number of entries used.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_RxLargePoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

NetBuf_TxLargePoolStatGet()#

Description#

Gets the large transmit network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_TxLargePoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

• Large transmit network buffer statistics pool, if NO error(s).

• NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_TxLargePoolStatResetMaxUsed()#

Description#

Resets the large receive network buffer statistics pool's maximum number of entries used.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_TxLargePoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

NetBuf_TxSmallPoolStatGet()#

Description#

Gets the small transmit network buffer statistics pool.

Files#

net_buf.h/net_buf.c

Prototype#

NET_STAT_POOL  NetBuf_TxSmallPoolStatGet (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to get network buffer statistics.

Returned Value#

• Small transmit network buffer statistics pool, if NO error(s).

• NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetBuf_TxSmallPoolStatResetMaxUsed()#

Description#

Resets the small transmit network buffer statistics pool's maximum number of entries used.

Files#

net_buf.h/net_buf.c

Prototype#

void  NetBuf_TxSmallPoolStatResetMaxUsed (NET_IF_NBR  if_nbr)

Arguments#

if_nbr

Interface number to reset network buffer statistics.

Returned Value#

None.

Notes / Warnings#

None.

Network Connection API#

NetConn_CfgAccessedTh()#

Description#

Configures the network connection access promotion threshold.

Files#

net_conn.h/net_conn.c

Prototype#

CPU_BOOLEAN  NetConn_CfgAccessedTh (CPU_INT16U  nbr_access)

Arguments#

nbr_access

Desired number of accesses before network connection is promoted.

Returned Value#

• DEF_OK, network connection access promotion threshold configured.

• DEF_FAIL, otherwise.

Notes / Warnings#

None.

NetConn_PoolStatGet()#

Description#

Gets the network connection statistics pool.

Files#

net_conn.h/net_conn.c

Prototype#

NET_STAT_POOL  NetConn_PoolStatGet (void)

Arguments#

Returned Value#

• Network connection statistics pool, if NO error(s).

• NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetConn_PoolStatResetMaxUsed()#

Description#

Resets the network connection statistics pool's maximum number of entries used.

Files#

net_conn.h/net_conn.c

Prototype#

void  NetConn_PoolStatResetMaxUsed (void)

Arguments#

Returned Value#

None.

Notes / Warnings#

None.

Network Timer API#

NetTmr_PoolStatGet()#

Description#

Gets the network timer statistics pool.

Files#

net_tmr.h/net_tmr.c

Prototype#

NET_STAT_POOL  NetTmr_PoolStatGet (void)

Arguments#

Returned Value#

Network timer statistics pool, if NO error(s). NULL statistics pool, otherwise.

Notes / Warnings#

1. NetTmr_PoolStatGet() blocked until network initialization completes.

2. 'NetTmr_PoolStat' MUST ALWAYS be accessed exclusively in critical sections.

NetTmr_PoolStatResetMaxUsed()#

Description#

Resets the network timer statistics pool's maximum number of entries used.

Files#

net_tmr.h/net_tmr.c

Prototype#

void  NetTmr_PoolStatResetMaxUsed (void)

Arguments#

Returned Value#

None.

Notes / Warnings#

1. NetTmr_PoolStatResetMaxUsed() blocked until network initialization completes.

   However, since 'NetTmr_PoolStat' is reset when network initialization completes; NO error is returned.

Network Interface API#

NetIF_Add()#

Description#

Add & initialize a specific instance of a network interface.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_NBR  NetIF_Add (void      *p_if_api,
                       void      *p_dev_api,
                       void      *p_dev_bsp,
                       void      *p_dev_cfg,
                       void      *p_ext_api,
                       void      *p_ext_cfg,
                       RTOS_ERR  *p_err)

Arguments#

p_if_api

Pointer to specific network interface API.

p_dev_api

Pointer to specific network device driver API.

p_dev_bsp

Pointer to specific network device board-specific API.

p_dev_cfg

Pointer to specific network device hardware configuration.

p_ext_api

Pointer to specific network extension layer API.

p_ext_cfg

Pointer to specific network extension layer configuration.

p_err

Pointer to variable that will receive the return error code from this function :

• RTOS_ERR_NONE

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_NO_MORE_RSRC

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

Returned Value#

• Interface number of the added interface, if NO error(s).

• NET_IF_NBR_NONE, otherwise.

Notes / Warnings#

The first network interface added and started is the default interface used for all default communication.

When a PHY layer is present, the PHY API and configuration need to be indicate in the p_ext_api and p_ext_cfg arguments.

NetIF_AddrHW_Get()#

Description#

Gets the network interface's hardware address.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_AddrHW_Get (NET_IF_NBR   if_nbr,
                        CPU_INT08U  *p_addr_hw,
                        CPU_INT08U  *p_addr_len,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get the hardware address.

p_addr_hw

Pointer to a variable that will receive the hardware address.

p_addr_len

Pointer to a variable that will receive the address length.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

The hardware address is returned in network-order; i.e., the pointer to the hardware address points to the highest-order octet.

NetIF_AddrHW_IsValid()#

Description#

Validates the network interface's hardware address.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_AddrHW_IsValid (NET_IF_NBR   if_nbr,
                                   CPU_INT08U  *p_addr_hw,
                                   RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to validate the hardware address.

p_addr_hw

Pointer to an interface's hardware address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• DEF_YES, if hardware address is valid.

• DEF_NO, otherwise.

Notes / Warnings#

The hardware address MUST be in network-order; i.e., the pointer to the hardware address MUST point to the highest-order octet.

NetIF_AddrHW_Set()#

Description#

Sets the network interface's hardware address.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_AddrHW_Set (NET_IF_NBR   if_nbr,
                        CPU_INT08U  *p_addr_hw,
                        CPU_INT08U   addr_len,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to set the hardware address.

p_addr_hw

Pointer to the hardware address.

addr_len

Length of the hardware address.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

1. The hardware address MUST be in network-order; i.e., the pointer to the hardware address MUST point to the highest-order octet.

2. The interface MUST be stopped BEFORE setting a new hardware address, which does NOT take effect until the interface is re-started.

NetIF_CfgPerfMonPeriod()#

Description#

Configures the Network Interface Performance Monitor Handler time (i.e., scheduling period).

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_CfgPerfMonPeriod (CPU_INT16U  time_ms)

Arguments#

time_ms

Desired value for Network Interface Performance Monitor Handler time (in milliseconds).

Returned Value#

• DEF_OK, Network Interface Performance Monitor Handler time is configured.

• DEF_FAIL, otherwise.

Notes / Warnings#

Configured time does NOT reschedule the next performance monitor handling; it configures the scheduling of all subsequent performance monitor handling.

NetIF_CfgPhyLinkPeriod()#

Description#

Configures the Network Interface Physical Link State Handler time (i.e., scheduling period).

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_CfgPhyLinkPeriod (CPU_INT16U  time_ms)

Arguments#

time_ms

Desired value for Network Interface Physical Link State Handler time (in milliseconds).

Returned Value#

• DEF_OK, Network Interface Physical Link State Handler timeout configured.

• DEF_FAIL, otherwise.

Notes / Warnings#

Configured time does NOT reschedule the next physical link state handling; it configures the scheduling of all subsequent physical link state handling.

NetIF_GetExtAvailCtr()#

Description#

Returns the number of external interface configured.

Files#

net_if.h/net_if.c

Prototype#

CPU_INT08U  NetIF_GetExtAvailCtr (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

Number of external interfaces available.

Notes / Warnings#

None.

NetIF_GetNbrBaseCfgd()#

Description#

Gets the interface base number (first interface ID).

Files#

net_if.h/net_if.c

Prototype#

NET_IF_NBR  NetIF_GetNbrBaseCfgd (void)

Arguments#

None.

Returned Value#

Interface base number.

Notes / Warnings#

None.

NetIF_GetRxDataAlignPtr()#

Description#

Gets and places aligned pointer into a receive application data buffer.

Files#

net_if.h/net_if.c

Prototype#

void  *NetIF_GetRxDataAlignPtr (NET_IF_NBR   if_nbr,
                                void        *p_data,
                                RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get a receive application buffer's aligned data pointer.

p_data

Pointer to receive application data buffer to get an aligned pointer into.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• Pointer to aligned receive application data buffer address, if NO error(s).

• Pointer to NULL, otherwise.

Notes / Warnings#

1. (a)

   1. (A) Optimal alignment between application data buffer(s) and network interface's network buffer data area(s) is NOT guaranteed and is only possible if the following condition is true :

      1. Network interface's network buffer data area(s) MUST be aligned to a multiple of the CPU's data word size.

      (B) Otherwise, a single and fixed alignment between application data buffer(s) and network interface's buffer data area(s) is NOT possible.

   2. (A) Even when application data buffers and network buffer data areas are aligned in the best case; optimal alignment is NOT guaranteed for every read/write of data to/from application data buffers and network buffer data areas.

      For any single read/write of data to/from application data buffers and network buffer data areas, optimal alignment only occurs if the following conditions are true :

      1. Data read/written to/from application data buffer(s) to network buffer data area(s) MUST start on addresses with the same relative offset from CPU word-aligned addresses.

         In other words, the modulus of the specific read/write address in the application data buffer with the CPU's data word size MUST be equal to the modulus of the specific read/write address in the network buffer data area with the CPU's data word size.

         This condition MIGHT NOT be satisfied whenever :

         1. Data is read/written to/from fragmented packets

         2. Data is NOT maximally read/written to/from stream-type packets (e.g., TCP data segments)

         3. Packets include variable number of header options (e.g., IP options)

      (B) However, even though optimal alignment between application data buffers and network buffer data areas is NOT guaranteed for every read/write; optimal alignment SHOULD occur more frequently leading to improved network data throughput.

   (b) Since the first aligned address in the application data buffer may be 0 to (CPU_CFG_DATA_SIZE - 1) octets after the application data buffer's starting address, the application data buffer SHOULD allocate and reserve an additional (CPU_CFG_DATA_SIZE - 1) number of octets.

   However, the application data buffer's effective, usable size is still limited to its original declared size (before reserving additional octets) and SHOULD NOT be increased by the additional, reserved octets.

NetIF_GetTxDataAlignPtr()#

Description#

Gets and places the aligned pointer into a transmit application data buffer.

Files#

net_if.h/net_if.c

Prototype#

void  *NetIF_GetTxDataAlignPtr (NET_IF_NBR   if_nbr,
                                void        *p_data,
                                RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get a transmit application buffer's aligned data pointer.

p_data

Pointer to transmit the application data buffer into which to get an aligned pointer.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• Pointer to aligned transmit application data buffer address, if NO error(s).

• Pointer to NULL, otherwise.

Notes / Warnings#

1. (a)

   1. (A) Optimal alignment between application data buffer(s) and network interface's network buffer data area(s) is NOT guaranteed and is only possible if the following condition is true :

      1. Network interface's network buffer data area(s) MUST be aligned to a multiple of the CPU's data word size.

      (B) Otherwise, a single and fixed alignment between application data buffer(s) and network interface's buffer data area(s) is NOT possible.

   2. (A) Even when application data buffers and network buffer data areas are aligned in the best case; optimal alignment is NOT guaranteed for every read/write of data to/from application data buffers and network buffer data areas.

      For any single read/write of data to/from application data buffers and network buffer data areas, optimal alignment only occurs if all of the following conditions are true :

      1. Data read/written to/from application data buffer(s) to network buffer data area(s) MUST start on addresses with the same relative offset from CPU word-aligned addresses.

      In other words, the modulus of the specific read/write address in the application data buffer with the CPU's data word size MUST be equal to the modulus of the specific read/write address in the network buffer data area with the CPU's data word size.

      This condition MIGHT NOT be satisfied whenever :

      1. Data is read/written to/from fragmented packets

      2. Data is NOT maximally read/written to/from stream-type packets (e.g. TCP data segments)

      3. Packets include variable number of header options (e.g. IP options)

      (B) However, even though optimal alignment between application data buffers and network buffer data areas is NOT guaranteed for every read/write; optimal alignment SHOULD occur more frequently leading to improved network data throughput.

   (b) Since the first aligned address in the application data buffer may be 0 to (CPU_CFG_DATA_SIZE - 1) octets after the application data buffer's starting address, the application data buffer SHOULD allocate and reserve an additional (CPU_CFG_DATA_SIZE - 1) number of octets.

NetIF_IO_Ctrl()#

Description#

1. Handles the network interface and/or device specific (I/O) control(s) :

   (a) Device link :

   1. Get the device link info

   2. Get the device link state

   3. Update the device link state

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_IO_Ctrl (NET_IF_NBR   if_nbr,
                     CPU_INT08U   opt,
                     void        *p_data,
                     RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to handle the (I/O) controls.

opt

Desired I/O control option code to perform. Additional control options may be defined by the device driver :

• NET_IF_IO_CTRL_LINK_STATE_GET Get the device's current physical link state, 'UP' or 'DOWN'.

• NET_IF_IO_CTRL_LINK_STATE_GET_INFO Get the device's detailed physical link state information.

• NET_IF_IO_CTRL_LINK_STATE_UPDATE Update the device's current physical link state.

• NET_IF_IO_CTRL_EEE_GET_INFO Retrieve information if EEE is enabled or not.

• NET_IF_IO_CTRL_EEE Enable/Disable EEE support on the interface.

p_data

Pointer to variable that will receive possible I/O control data.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

1. 'p_data' MUST point to a variable or memory buffer that is sufficiently sized AND aligned to receive any return data. The options are as follows :

   (a) NET_IF_IO_CTRL_LINK_STATE_GET:

   1. For Ethernet or Wireless interface: p_data MUST point to a CPU_BOOLEAN variable.

   (b) NET_IF_IO_CTRL_LINK_STATE_GET_INFO NET_IF_IO_CTRL_LINK_STATE_UPDATE

   1. For an Ethernet interface: p_data MUST point to a variable of data type NET_DEV_LINK_ETHER.

   2. For a Wireless interface: p_data MUST point to a variable of data type NET_DEV_LINK_WIFI.

NetIF_ISR_Handler()#

Description#

Handle network interface's device interrupt service routine (ISR) function(s).

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_ISR_Handler (NET_IF_NBR         if_nbr,
                         NET_DEV_ISR_TYPE   type,
                         RTOS_ERR          *p_err)

Arguments#

if_nbr

Network interface number to handle ISR(s).

type

Device interrupt type(s) to handle :

• NET_DEV_ISR_TYPE_UNKNOWN Handle unknown device ISR(s).

• NET_DEV_ISR_TYPE_RX Handle device receive ISR(s).

• NET_DEV_ISR_TYPE_RX_OVERRUN Handle device receive overrun ISR(s).

• NET_DEV_ISR_TYPE_TX_RDY Handle device transmit ready ISR(s).

• NET_DEV_ISR_TYPE_TX_COMPLETE Handle device transmit complete ISR(s).

p_err

Pointer to variable that will receive the return error code from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_INVALID_STATE

Returned Value#

none.

Notes / Warnings#

Device driver(s)' Board Support Package (BSP) Interrupt Service Routine (ISR) handler(s). This function is a network interface (IF) to network device function & SHOULD be called only by appropriate network device driver ISR handler function(s).

NetIF_IsEn()#

Description#

Validates the network interface as enabled.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsEn (NET_IF_NBR   if_nbr,
                         RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• DEF_YES, network interface is valid and enabled.

• DEF_NO, network interface is invalid or disabled.

Notes / Warnings#

None.

NetIF_IsEnCfgd()#

Description#

Validates the configured network interface as enabled.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsEnCfgd (NET_IF_NBR   if_nbr,
                             RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• DEF_YES, network interface is valid and enabled.

• DEF_NO, network interface is invalid or disabled.

Notes / Warnings#

None.

NetIF_IsValid()#

Description#

Validates the network interface number.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsValid (NET_IF_NBR   if_nbr,
                            RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

• DEF_YES, network interface number is valid.

• DEF_NO, network interface number is invalid / NOT yet configured.

Notes / Warnings#

None.

NetIF_IsValidCfgd()#

Description#

Validates the configured network interface number.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_IsValidCfgd (NET_IF_NBR   if_nbr,
                                RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to validate.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

• DEF_YES, network interface number is valid.

• DEF_NO, network interface number is invalid / NOT yet configured or reserved.

Notes / Warnings#

None.

NetIF_LinkStateGet()#

Description#

Gets the network interface's last known physical link state.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_LINK_STATE  NetIF_LinkStateGet (NET_IF_NBR   if_nbr,
                                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get last known physical link state.

p_err

Pointer to variable that will receive the return error code from this function :

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• NET_IF_LINK_UP, if NO error(s) and network interface's last known physical link state was 'UP'.

• NET_IF_LINK_DOWN, otherwise.

Notes / Warnings#

NetIF_LinkStateGet() only returns a network interface's last known physical link state since enabled network interfaces' physical link states are only periodically updated.

NetIF_LinkStateSubscribe()#

Description#

Subscribes to get notified when an interface link state changes.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_LinkStateSubscribe (NET_IF_NBR                    if_nbr,
                                NET_IF_LINK_SUBSCRIBER_FNCT   fcnt,
                                RTOS_ERR                     *p_err)

Arguments#

if_nbr

Network interface number to check the link state.

fcnt

Function to call when the link changes.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

NetIF_LinkStateUnsubscribe()#

Description#

Removes the subscribe function from the link state changes subscription list.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_LinkStateUnsubscribe (NET_IF_NBR                    if_nbr,
                                  NET_IF_LINK_SUBSCRIBER_FNCT   fcnt,
                                  RTOS_ERR                     *p_err)

Arguments#

if_nbr

Specify the Network Interface number to remove the link state check function.

fcnt

Function to remove from subscription list.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_POOL_FULL

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_LinkStateWaitUntilUp()#

Description#

Waits for a network interface's link state to be 'UP'.

Files#

net_if.h/net_if.c

Prototype#

CPU_BOOLEAN  NetIF_LinkStateWaitUntilUp (NET_IF_NBR   if_nbr,
                                         CPU_INT16U   retry_max,
                                         CPU_INT32U   time_dly_ms,
                                         RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to check link state.

retry_max

Maximum number of consecutive wait retries.

time_dly_ms

Transitory delay value, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_NET_IF_LINK_DOWN

Returned Value#

• NET_IF_LINK_UP, if NO error(s) and network interface's link state is 'UP'.

• NET_IF_LINK_DOWN, otherwise.

Notes / Warnings#

If a non-zero number of retries is requested, a non-zero time delay SHOULD also be requested; otherwise, all retries will likely fail immediately since no time will elapse to allow the network interface's link state to successfully be 'UP'.

NetIF_MTU_Get()#

Description#

Gets the network interface's MTU.

Files#

net_if.h/net_if.c

Prototype#

NET_MTU  NetIF_MTU_Get (NET_IF_NBR   if_nbr,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get MTU.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• Network interface's MTU, if NO error(s).

• 0, otherwise.

Notes / Warnings#

None.

NetIF_MTU_Set()#

Description#

Sets the network interface's MTU.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_MTU_Set (NET_IF_NBR   if_nbr,
                     NET_MTU      mtu,
                     RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to set MTU.

mtu

Desired maximum transmission unit size to configure.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_NbrGetFromName()#

Description#

Get network interface number from it's name.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_NBR  NetIF_NbrGetFromName (CPU_CHAR  *p_name)

Arguments#

p_name

Pointer to a string containing interface controller's name.

Returned Value#

Network interface number associated with controller name.

Notes / Warnings#

None.

NetIF_Start()#

Description#

Start a network interface.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_Start (NET_IF_NBR   if_nbr,
                   RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to start.

p_err

Pointer to variable that will receive the return error code from this function :

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_TYPE

• RTOS_ERR_NOT_INIT

• RTOS_ERR_TX

• RTOS_ERR_ALREADY_EXISTS

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_RX

• RTOS_ERR_SEG_OVF

• RTOS_ERR_NOT_SUPPORTED

• RTOS_ERR_NOT_READY

• RTOS_ERR_OS_SCHED_LOCKED

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_WOULD_OVF

• RTOS_ERR_NET_IF_LINK_DOWN

• RTOS_ERR_OS_OBJ_DEL

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_WOULD_BLOCK

• RTOS_ERR_NET_NEXT_HOP

• RTOS_ERR_INVALID_STATE

• RTOS_ERR_ABORT

• RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

NetIF_Stop()#

Description#

Stop a network interface.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_Stop (NET_IF_NBR   if_nbr,
                  RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to stop.

p_err

Pointer to variable that will receive the return error code from this function :

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_INVALID_STATE

Returned Value#

none.

Notes / Warnings#

None.

NetIF_TxSuspendTimeoutGet_ms()#

Description#

Gets the network interface transmit suspend timeout value.

Files#

net_if.h/net_if.c

Prototype#

CPU_INT32U  NetIF_TxSuspendTimeoutGet_ms (NET_IF_NBR   if_nbr,
                                          RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to get timeout value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

• Network transmit suspend timeout value (in milliseconds), if NO error(s).

• 0, otherwise.

Notes / Warnings#

None.

NetIF_TxSuspendTimeoutSet()#

Description#

Sets the network interface transmit suspend timeout value.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_TxSuspendTimeoutSet (NET_IF_NBR   if_nbr,
                                 CPU_INT32U   timeout_ms,
                                 RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number to set timeout value.

timeout_ms

Timeout value (in milliseconds).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_TypeGet()#

Description#

Gets the network interface's type.

Files#

net_if.h/net_if.c

Prototype#

NET_IF_TYPE  NetIF_TypeGet (NET_IF_NBR   if_nbr,
                            RTOS_ERR    *p_err)

Arguments#

if_nbr

Network interface number to get the type.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

Network interface's type :

• NET_IF_TYPE_ETHER

• NET_IF_TYPE_WIFI

• NET_IF_TYPE_NONE, in case of error

Notes / Warnings#

None.

NetIF_WaitSetupReady()#

Description#

Wait for the network interface setup to be complete.

Files#

net_if.h/net_if.c

Prototype#

void  NetIF_WaitSetupReady (NET_IF_NBR        if_nbr,
                            NET_IF_APP_INFO  *p_info,
                            CPU_INT32U        timeout_ms,
                            RTOS_ERR         *p_err)

Arguments#

if_nbr

Network interface number on which to wait.

p_info

Pointer to structure in which the setup information will be copied. DEF_NULL, to not receive the setup information.

timeout_ms

Timeout, in milliseconds. A value of 0 will never timeout.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_ABORT

Returned Value#

None.

Notes / Warnings#

None.

Ethernet Network Interface API#

NET_CTRLR_ETHER_REG()#

Description#

Registers a Ethernet controller to the platform manager.

Files#

net_if_ether.h

Prototype#

NET_CTRLR_ETHER_REG(name, ctlr_info_ptr)

Arguments#

name

Unique name for the Ethernet controller. It is recommended to follow the standard "etherX" where X is a digit.

ctlr_info_ptr

Pointer to the Ethernet controller information structure of type NET_IF_ETHER_CTRLR_INFO.

Returned Value#

None.

Notes / Warnings#

This macro should normally be called from the BSP.

NetIF_Ether_Add()#

Description#

Add & initialize a specific instance of a network Ethernet interface.

Files#

net_if_ether.h/net_if_ether.c

Prototype#

NET_IF_NBR  NetIF_Ether_Add (CPU_CHAR        *p_name,
                             NET_IF_BUF_CFG  *p_buf_cfg,
                             MEM_SEG         *p_mem_seg,
                             RTOS_ERR        *p_err)

Arguments#

p_name

String identifier for the Ethernet interface to add.

p_buf_cfg

Pointer to buffer configuration.

p_mem_seg

Memory segment from which internal data will be allocated. If DEF_NULL, it will be allocated from the global heap.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_NO_MORE_RSRC

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

Returned Value#

Interface number of the added interface, if NO error(s). NET_IF_NBR_NONE, otherwise.

Notes / Warnings#

When a non-null buffer configuration is passed, a copy of the device configuration that come from the BSP is completed. It is recommended to reduce the memory usage to modify the static configuration specified in the BSP.

NetIF_Ether_Start()#

Description#

Start an Ethernet type interface :

Files#

net_if_ether.h/net_if_ether.c

Prototype#

void  NetIF_Ether_Start (NET_IF_NBR         if_nbr,
                         NET_IF_ETHER_CFG  *p_cfg,
                         RTOS_ERR          *p_err)

Arguments#

if_nbr

Network interface number to start.

p_cfg

Pointer to interface configuration. DEF_NULL, to just start the interface without Address or DHCP setup.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_TYPE

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

• RTOS_ERR_NOT_SUPPORTED

• RTOS_ERR_OS_SCHED_LOCKED

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_FAIL

• RTOS_ERR_WOULD_OVF

• RTOS_ERR_NET_IF_LINK_DOWN

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_WOULD_BLOCK

• RTOS_ERR_INVALID_STATE

• RTOS_ERR_ABORT

• RTOS_ERR_TIMEOUT

• RTOS_ERR_NOT_INIT

• RTOS_ERR_TX

• RTOS_ERR_ALREADY_EXISTS

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_NET_STR_ADDR_INVALID

• RTOS_ERR_RX

• RTOS_ERR_NOT_READY

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_OS_OBJ_DEL

• RTOS_ERR_NET_NEXT_HOP

• RTOS_ERR_IS_OWNER

Returned Value#

None.

Notes / Warnings#

None.

Wireless Network Interface API#

NET_CTRLR_WIFI_SPI_REG()#

Description#

Registers a WiFi controller to the platform manager. Those kind of WiFi Controllers are outside the MCU and connected via a SPI interface to the MCU.

Files#

net_if_wifi.h

Prototype#

NET_CTRLR_WIFI_SPI_REG(part_name, spi_name, part_info_ptr, bsp_api_ptr, slave_id)

Arguments#

part_name

Unique name for the WiFi controller/part. It is recommended to follow the standard "wifiX" where X is a digit.

spi_name

Unique name for the SPI bus to use for the WiFi slave. The SPI bus must already have been registered to the Platform Manager. It is recommended to follow the standard "spiX" where X is a digit.

part_info_ptr

Pointer to the WiFi part hardware information structure of type NET_IF_WIFI_PART_INFO.

bsp_api_ptr

Pointer to the BSP API structure for the WiFi controller.

slave_id

Slave ID of the WiFi controller on the SPI bus.

Returned Value#

None.

Notes / Warnings#

This macro should normally be called from the BSP.

NetIF_WiFi_Add()#

Description#

Add & initialize a specific instance of a network WiFi interface.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

NET_IF_NBR  NetIF_WiFi_Add (       CPU_CHAR        *p_name,
                            const  NET_IF_BUF_CFG  *p_cfg,
                                   void            *p_ext_cfg,
                                   MEM_SEG         *p_mem_seg,
                                   RTOS_ERR        *p_err)

Arguments#

p_name

String identifier for the WiFi interface to add.

p_cfg

Pointer to buffer configuration.

p_ext_cfg

Pointer to extended configuration. DEF_NULL, if not need by WiFi part.

p_mem_seg

Memory segment from which internal data will be allocated. If DEF_NULL, it will be allocated from the global heap.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_NO_MORE_RSRC

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

Returned Value#

• Interface number of the added interface, if NO error(s).

• NET_IF_NBR_NONE, otherwise.

Notes / Warnings#

None.

NetIF_WiFi_CreateAP()#

Description#

Creates a wireless access point.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_CreateAP (NET_IF_NBR                  if_nbr,
                           NET_IF_WIFI_NET_TYPE        net_type,
                           NET_IF_WIFI_DATA_RATE       data_rate,
                           NET_IF_WIFI_SECURITY_TYPE   security_type,
                           NET_IF_WIFI_PWR_LEVEL       pwr_level,
                           NET_IF_WIFI_CH              ch,
                           NET_IF_WIFI_SSID            ssid,
                           NET_IF_WIFI_PSK             psk,
                           RTOS_ERR                   *p_err)

Arguments#

if_nbr

Wireless network interface number.

net_type

Wireless network type:

• NET_IF_WIFI_NET_TYPE_INFRASTRUCTURE

• NET_IF_WIFI_NET_TYPE_ADHOC

data_rate

Wireless date rate to configure:

• NET_IF_WIFI_DATA_RATE_AUTO

• NET_IF_WIFI_DATA_RATE_1_MBPS

• NET_IF_WIFI_DATA_RATE_2_MBPS

• NET_IF_WIFI_DATA_RATE_5_5_MBPS

• NET_IF_WIFI_DATA_RATE_6_MBPS

• NET_IF_WIFI_DATA_RATE_9_MBPS

• NET_IF_WIFI_DATA_RATE_11_MBPS

• NET_IF_WIFI_DATA_RATE_12_MBPS

• NET_IF_WIFI_DATA_RATE_18_MBPS

• NET_IF_WIFI_DATA_RATE_24_MBPS

• NET_IF_WIFI_DATA_RATE_36_MBPS

• NET_IF_WIFI_DATA_RATE_48_MBPS

• NET_IF_WIFI_DATA_RATE_54_MBPS

• NET_IF_WIFI_DATA_RATE_MCS0

• NET_IF_WIFI_DATA_RATE_MCS1

• NET_IF_WIFI_DATA_RATE_MCS2

• NET_IF_WIFI_DATA_RATE_MCS3

• NET_IF_WIFI_DATA_RATE_MCS4

• NET_IF_WIFI_DATA_RATE_MCS5

• NET_IF_WIFI_DATA_RATE_MCS6

• NET_IF_WIFI_DATA_RATE_MCS7

• NET_IF_WIFI_DATA_RATE_MCS8

• NET_IF_WIFI_DATA_RATE_MCS9

• NET_IF_WIFI_DATA_RATE_MCS10

• NET_IF_WIFI_DATA_RATE_MCS11

• NET_IF_WIFI_DATA_RATE_MCS12

• NET_IF_WIFI_DATA_RATE_MCS13

• NET_IF_WIFI_DATA_RATE_MCS14

• NET_IF_WIFI_DATA_RATE_MCS15

security_type

Wireless security type:

• NET_IF_WIFI_SECURITY_OPEN

• NET_IF_WIFI_SECURITY_WEP

• NET_IF_WIFI_SECURITY_WPA

• NET_IF_WIFI_SECURITY_WPA2

pwr_level

Wireless radio power to configure:

• NET_IF_WIFI_PWR_LEVEL_LO

• NET_IF_WIFI_PWR_LEVEL_MED

• NET_IF_WIFI_PWR_LEVEL_HI

ch

Channel of the wireless network to create:

• NET_IF_WIFI_CH_1

• NET_IF_WIFI_CH_2

• NET_IF_WIFI_CH_3

• NET_IF_WIFI_CH_4

• NET_IF_WIFI_CH_5

• NET_IF_WIFI_CH_6

• NET_IF_WIFI_CH_7

• NET_IF_WIFI_CH_8

• NET_IF_WIFI_CH_9

• NET_IF_WIFI_CH_10

• NET_IF_WIFI_CH_11

• NET_IF_WIFI_CH_12

• NET_IF_WIFI_CH_13

• NET_IF_WIFI_CH_14

ssid

SSID of the access point to create.

psk

Pre-shared key of the access point.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_WiFi_GetPeerInfo()#

Description#

Gets the peer info connected to the access point (when acting as an access point).

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

CPU_INT16U  NetIF_WiFi_GetPeerInfo (NET_IF_NBR          if_nbr,
                                    NET_IF_WIFI_PEER   *p_buf_peer,
                                    CPU_INT16U          buf_peer_len_max,
                                    RTOS_ERR           *p_err)

Arguments#

if_nbr

Wireless network interface number.

p_buf_peer

Pointer to the buffer to save the peer information.

buf_peer_len_max

Length in bytes of p_buf_peer.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

Number of peers on the network and that are set in the buffer.

Notes / Warnings#

None.

NetIF_WiFi_Join()#

Description#

Joins a wireless access point.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_Join (NET_IF_NBR                  if_nbr,
                       NET_IF_WIFI_NET_TYPE        net_type,
                       NET_IF_WIFI_DATA_RATE       data_rate,
                       NET_IF_WIFI_SECURITY_TYPE   security_type,
                       NET_IF_WIFI_PWR_LEVEL       pwr_level,
                       NET_IF_WIFI_SSID            ssid,
                       NET_IF_WIFI_PSK             psk,
                       RTOS_ERR                   *p_err)

Arguments#

if_nbr

Wireless network interface number.

net_type

Wireless network type:

• NET_IF_WIFI_NET_TYPE_INFRASTRUCTURE

• NET_IF_WIFI_NET_TYPE_ADHOC

data_rate

Wireless date rate to configure:

• NET_IF_WIFI_DATA_RATE_AUTO

• NET_IF_WIFI_DATA_RATE_1_MBPS

• NET_IF_WIFI_DATA_RATE_2_MBPS

• NET_IF_WIFI_DATA_RATE_5_5_MBPS

• NET_IF_WIFI_DATA_RATE_6_MBPS

• NET_IF_WIFI_DATA_RATE_9_MBPS

• NET_IF_WIFI_DATA_RATE_11_MBPS

• NET_IF_WIFI_DATA_RATE_12_MBPS

• NET_IF_WIFI_DATA_RATE_18_MBPS

• NET_IF_WIFI_DATA_RATE_24_MBPS

• NET_IF_WIFI_DATA_RATE_36_MBPS

• NET_IF_WIFI_DATA_RATE_48_MBPS

• NET_IF_WIFI_DATA_RATE_54_MBPS

• NET_IF_WIFI_DATA_RATE_MCS0

• NET_IF_WIFI_DATA_RATE_MCS1

• NET_IF_WIFI_DATA_RATE_MCS2

• NET_IF_WIFI_DATA_RATE_MCS3

• NET_IF_WIFI_DATA_RATE_MCS4

• NET_IF_WIFI_DATA_RATE_MCS5

• NET_IF_WIFI_DATA_RATE_MCS6

• NET_IF_WIFI_DATA_RATE_MCS7

• NET_IF_WIFI_DATA_RATE_MCS8

• NET_IF_WIFI_DATA_RATE_MCS9

• NET_IF_WIFI_DATA_RATE_MCS10

• NET_IF_WIFI_DATA_RATE_MCS11

• NET_IF_WIFI_DATA_RATE_MCS12

• NET_IF_WIFI_DATA_RATE_MCS13

• NET_IF_WIFI_DATA_RATE_MCS14

• NET_IF_WIFI_DATA_RATE_MCS15

security_type

Wireless security type:

• NET_IF_WIFI_SECURITY_OPEN

• NET_IF_WIFI_SECURITY_WEP

• NET_IF_WIFI_SECURITY_WPA

• NET_IF_WIFI_SECURITY_WPA2

pwr_level

Wireless radio power to configure:

• NET_IF_WIFI_PWR_LEVEL_LO

• NET_IF_WIFI_PWR_LEVEL_MED

• NET_IF_WIFI_PWR_LEVEL_HI

ssid

SSID of the access point to join.

psk

Pre-shared key of the access point.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

Before join an access point, the access point should have been found during a previous scan.

NetIF_WiFi_Leave()#

Description#

Leaves the access point previously joined.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_Leave (NET_IF_NBR   if_nbr,
                        RTOS_ERR    *p_err)

Arguments#

if_nbr

Wireless network interface number.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

NetIF_WiFi_Scan()#

Description#

Scans the available wireless access point.

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

CPU_INT16U  NetIF_WiFi_Scan (       NET_IF_NBR         if_nbr,
                                    NET_IF_WIFI_AP    *p_buf_scan,
                                    CPU_INT16U         buf_scan_len_max,
                             const  NET_IF_WIFI_SSID  *p_ssid,
                                    NET_IF_WIFI_CH     ch,
                                    RTOS_ERR          *p_err)

Arguments#

if_nbr

Wireless network interface number.

p_buf_scan

Pointer to a buffer that will receive available access point.

buf_scan_len_max

Maximum number of access point that can be stored

p_ssid

Pointer to a strubg that contains the SSID to scan. DEF_NULL to scan for all access point.

ch

Channel number:

• NET_IF_WIFI_CH_ALL

• NET_IF_WIFI_CH_1

• NET_IF_WIFI_CH_2

• NET_IF_WIFI_CH_3

• NET_IF_WIFI_CH_4

• NET_IF_WIFI_CH_5

• NET_IF_WIFI_CH_6

• NET_IF_WIFI_CH_7

• NET_IF_WIFI_CH_8

• NET_IF_WIFI_CH_9

• NET_IF_WIFI_CH_10

• NET_IF_WIFI_CH_11

• NET_IF_WIFI_CH_12

• NET_IF_WIFI_CH_13

• NET_IF_WIFI_CH_14

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_NOT_READY

Returned Value#

Number of wireless access points found.

Notes / Warnings#

None.

NetIF_WiFi_Start()#

Description#

Start an WiFi type interface

Files#

net_if_wifi.h/net_if_wifi.c

Prototype#

void  NetIF_WiFi_Start (NET_IF_NBR        if_nbr,
                        NET_IF_WIFI_CFG  *p_cfg,
                        RTOS_ERR         *p_err)

Arguments#

if_nbr

Network interface number to start.

p_cfg

Pointer to interface configuration. DEF_NULL, to just start the interface without Address or DHCP setup.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_TYPE

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

• RTOS_ERR_NOT_SUPPORTED

• RTOS_ERR_OS_SCHED_LOCKED

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_FAIL

• RTOS_ERR_WOULD_OVF

• RTOS_ERR_NET_IF_LINK_DOWN

• RTOS_ERR_INVALID_HANDLE

• RTOS_ERR_WOULD_BLOCK

• RTOS_ERR_INVALID_STATE

• RTOS_ERR_ABORT

• RTOS_ERR_TIMEOUT

• RTOS_ERR_NOT_INIT

• RTOS_ERR_TX

• RTOS_ERR_ALREADY_EXISTS

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_NET_STR_ADDR_INVALID

• RTOS_ERR_RX

• RTOS_ERR_NOT_READY

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_OS_OBJ_DEL

• RTOS_ERR_NET_NEXT_HOP

• RTOS_ERR_IS_OWNER

Returned Value#

None.

Notes / Warnings#

None.

DHCP Client API#

DHCPc_IF_Add()#

Description#

Attaches an interface to the DHCP module and starts the DHCP process on this interface.

Files#

dhcp_client.h/dhcp_client.c

Prototype#

void  DHCPc_IF_Add (NET_IF_NBR   if_nbr,
                    DHCPc_CFG   *p_cfg,
                    RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number on which DHCP must be performed.

p_cfg

Pointer to the DHCP configuration for the given interface.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_ALREADY_EXISTS

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

DHCPc_IF_Reboot()#

Description#

Reboots the DHCP Client process.

Files#

dhcp_client.h/dhcp_client.c

Prototype#

void  DHCPc_IF_Reboot (NET_IF_NBR   if_nbr,
                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number on which the DHCP process must be rebooted.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_INVALID_STATE

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

The reboot process will be completed automatically by the DHCP client process when an interface link state changes. This API is provided if more flexibility is required by the customer application.

DHCPc_IF_Remove()#

Description#

Stops and removes the DHCP operation on the given network interface.

Files#

dhcp_client.h/dhcp_client.c

Prototype#

void  DHCPc_IF_Remove (NET_IF_NBR   if_nbr,
                       RTOS_ERR    *p_err)

Arguments#

if_nbr

Interface number on which the DHCP process must be stopped.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

DNS Client API#

DNSc_CacheClrAll()#

Description#

Flushes the DNS cache.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CacheClrAll (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_INIT

Returned Value#

None.

Notes / Warnings#

None.

DNSc_CacheClrHost()#

Description#

Removes a host from the cache.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CacheClrHost (CPU_CHAR  *p_host_name,
                         RTOS_ERR  *p_err)

Arguments#

p_host_name

Pointer to a string that contains the host name to remove from the cache.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_INIT

• RTOS_ERR_NET_OP_IN_PROGRESS

• RTOS_ERR_NOT_FOUND

Returned Value#

None.

Notes / Warnings#

None.

DNSc_CfgServerByAddr()#

Description#

Configures the DNS server to use by default with an address structure.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CfgServerByAddr (NET_IP_ADDR_OBJ  *p_addr,
                            RTOS_ERR         *p_err)

Arguments#

p_addr

Pointer to the structure that contains the IP address of the DNS server.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

DNSc_CfgServerByStr()#

Description#

Configures the DNS server to use by default using a string.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CfgServerByStr (CPU_CHAR  *p_server,
                           RTOS_ERR  *p_err)

Arguments#

p_server

Pointer to a string that contains the IP address of the DNS server.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NET_STR_ADDR_INVALID

Returned Value#

None.

Notes / Warnings#

None.

DNSc_GetHost()#

Description#

Converts a string representation of a host name to its corresponding IP address using DNS service.

Files#

dns_client.h/dns_client.c

Prototype#

DNSc_STATUS  DNSc_GetHost (CPU_CHAR         *p_host_name,
                           NET_IP_ADDR_OBJ  *p_addr_tbl,
                           CPU_INT08U       *p_addr_nbr,
                           DNSc_FLAGS        flags,
                           DNSc_REQ_CFG     *p_cfg,
                           RTOS_ERR         *p_err)

Arguments#

p_host_name

Pointer to a string that contains the host name.

p_addr_tbl

Pointer to the array that will receive the IP address(es).

p_addr_nbr

Pointer to a variable that contains how many addresses can be contained in the array.

flags

DNS client flag:

p_cfg

Pointer to a request configuration. Should be set to overwrite the default DNS configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_INIT

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_BLK_ALLOC_CALLBACK

• RTOS_ERR_SEG_OVF

• RTOS_ERR_OS_SCHED_LOCKED

• RTOS_ERR_NOT_AVAIL

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_POOL_EMPTY

• RTOS_ERR_OS_OBJ_DEL

• RTOS_ERR_WOULD_BLOCK

• RTOS_ERR_ABORT

• RTOS_ERR_TIMEOUT

Returned Value#

Resolution status: DNSc_STATUS_PENDING Host resolution is pending, call again to see the status. (Processed by DNSc's task) DNSc_STATUS_RESOLVED Host is resolved. DNSc_STATUS_FAILED Host resolution has failed.

• DNSc_STATUS_PENDING: Host resolution is pending, call again to see the status. (Processed by DNSc's task)

• DNSc_STATUS_RESOLVED: Host is resolved.

• DNSc_STATUS_FAILED: Host resolution has failed.

Notes / Warnings#

None.

DNSc_GetHostAddrs()#

Description#

Get a list of IP addresses assigned to a host.

Files#

dns_client.h/dns_client.c

Prototype#

DNSc_STATUS DNSc_GetHostAddrs (CPU_CHAR          *p_host_name,
                               NET_HOST_IP_ADDR **p_addrs,
                               CPU_INT08U        *p_addr_nbr,
                               DNSc_FLAGS         flags,
                               DNSc_REQ_CFG      *p_cfg,
                               RTOS_ERR          *p_err)

Arguments#

p_host_name

Pointer to a string that contains the host name.

p_addrs

Pointer to link list that will receive the IP address(es).

p_addr_nbr

Pointer to a variable that contains how many addresses can be returned.

flags

DNS client flag:

p_cfg

Pointer to a request configuration. Should be set to overwrite the default DNS configuration.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

DNSc_FreeHostAddrs()#

Description#

Free Host addresses allocated by DNSc_GetHostAddrs() .

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_CacheClrAll (RTOS_ERR  *p_err)

Arguments#

p_addr

Pointer to the host addresses link-list to free.

Returned Value#

None.

Notes / Warnings#

None.

DNSc_GetServerByAddr#

Description#

Gets the default DNS server in a address object format.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_GetServerByAddr (NET_IP_ADDR_OBJ  *p_addr,
                            RTOS_ERR    *p_err)

Arguments#

p_addr

Pointer to the structure that will receive the IP address of the DNS server.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_FOUND

Returned Value#

None.

Notes / Warnings#

None.

DNSc_GetServerByStr()#

Description#

Gets the default DNS server in string format.

Files#

dns_client.h/dns_client.c

Prototype#

void  DNSc_GetServerByStr (CPU_CHAR    *p_str,
                           CPU_INT08U   str_len_max,
                           RTOS_ERR    *p_err)

Arguments#

p_addr

Pointer to the structure that will receive the IP address of the DNS server.

str_len_max

Maximum string length.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_FOUND

Returned Value#

None.

Notes / Warnings#

None.

ARP API#

NetARP_CacheGetAddrHW()#

Description#

1. Gets the hardware address that corresponds to a specific ARP cache's protocol address by following these steps :

   (a) Acquire the network lock.

   (b) Search the ARP Cache List for ARP cache with the desired protocol address.

   (c) If the corresponding ARP cache is found, get/return the hardware address.

   (d) Release network lock.

Files#

net_arp.h/net_arp.c

Prototype#

NET_CACHE_ADDR_LEN  NetARP_CacheGetAddrHW (NET_IF_NBR           if_nbr,
                                           CPU_INT08U          *p_addr_hw,
                                           NET_CACHE_ADDR_LEN   addr_hw_len_buf,
                                           CPU_INT08U          *p_addr_protocol,
                                           NET_CACHE_ADDR_LEN   addr_protocol_len,
                                           RTOS_ERR            *p_err)

Arguments#

if_nbr

Network interface number.

p_addr_hw

Pointer to a memory buffer that will receive the hardware address :

addr_hw_len_buf

Length of hardware address memory buffer (in octets).

p_addr_protocol

Pointer to the specific protocol address to search for corresponding hardware address.

addr_protocol_len

Length of protocol addresses (in octets).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_FOUND

• RTOS_ERR_NET_ADDR_UNRESOLVED

• RTOS_ERR_INVALID_STATE

Returned Value#

• Length of returned hardware address, if available.

• 0, otherwise.

Notes / Warnings#

1. (a)

   1. The size of the memory buffer that will receive the returned hardware address MUST be greater than or equal to NET_IF_HW_ADDR_LEN_MAX.

   2. The length of any returned hardware address is equal to NET_IF_HW_ADDR_LEN_MAX.

   3. Address memory buffer array cleared in case of any error(s).

      (A) Address memory buffer array SHOULD be initialized to return a NULL address PRIOR to all validation or function handling in case of any error(s).

   (b) The length of the protocol address MUST be equal to NET_IPv4_ADDR_SIZE and is included for correctness and completeness.

2. ARP addresses handled in network-order :

   (a) 'p_addr_hw' returns a hardware address in network-order.

   (b) 'p_addr_protocol' MUST points to a protocol address in network-order.

3. While an ARP cache is in 'PENDING' state, the hardware address is NOT yet resolved, but it MAY be resolved in the near future by an awaited ARP Reply.

NetARP_CachePoolStatGet()#

Description#

Gets the ARP statistics pool.

Files#

net_arp.h/net_arp.c

Prototype#

NET_STAT_POOL  NetARP_CachePoolStatGet (void)

Arguments#

Returned Value#

• ARP statistics pool, if NO error(s).

• NULL statistics pool, otherwise.

Notes / Warnings#

None.

NetARP_CachePoolStatResetMaxUsed()#

Description#

Resets ARP statistics pool's maximum number of entries used.

Files#

net_arp.h/net_arp.c

Prototype#

void  NetARP_CachePoolStatResetMaxUsed (void)

Arguments#

None.

Returned Value#

None.

Notes / Warnings#

None.

NetARP_CacheProbeAddrOnNet()#

Description#

1. Transmits an ARP Request to probe the local network for a specific protocol address :

   (a) Acquire network lock.

   (b) Remove the ARP cache with desired protocol address from ARP Cache List, if available.

   (c) Configure the ARP cache :

   1. Get the default-configured ARP cache

   2. ARP cache state

   (d) Transmit the ARP Request to probe local network for desired protocol address.

   (e) Release the network lock.

2. NetARP_CacheProbeAddrOnNet() SHOULD be used in conjunction with NetARP_CacheGetAddrHW() to determine if a specific protocol address is available on the local network :

   (a) After successfully transmitting an ARP Request to probe the local network.

   (b) After some time delay(s) [on the order of ARP Request timeouts & retries].

   (c) Check ARP Cache for the hardware address of a host on the local network that corresponds to the desired protocol address.

   See also NetARP_CacheGetAddrHW() and NetARP_TxReqGratuitous() .