 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The BSD Socket API Compliancy Wrapper (NetX™ BSD) supports a subset of the basic BSD Socket API calls (with some limitations) using NetX™ services.
Unsupported Features
BSD with DNS support has not been tested in this version of SSP.
** NetX Duo BSD only
The NetX BSD Support module provides the standard BSD API functions for connecting, binding, listening, sending and receiving. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. Services that are implemented by NetX and NetX Duo BSD begin with nx_, and are listed at the end of this table.
NetX/NetX Duo BSD Support Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| accept | accept(INT sockID, struct sockaddr *ClientAddress, INT *addressLength);TCP server socket waits to make a TCP connection. |
| bsd_initialize | bsd_initialize(NX_IP *default_ip, NX_PACKET_POOL *default_pool, CHAR *bsd_thread_stack_area, ULONG bsd_thread_stack_size, UINT bsd_thread_priority);Sets up BSD Support Module to use NetX and BSD services. (Called by the NetX BSD Support Module automatically.) |
| bind | bind(INT sockID, struct sockaddr *localAddress, INT addressLength);Bind TCP or UDP socket to a local port. |
| connect | connect(INT sockID, struct sockaddr *remoteAddress, INT addressLength);Connect to a TCP peer; if the remoteAddress indicates raw or UDP socket, then if the address is NULL this dis-associates the peer from this socket. |
| fcntl | fcntl(INT sock_ID, UINT flag_type, UINT f_options);Sets socket options for the specified socket. |
| freeaddrinfo | freeaddrinfo(struct addrinfo *res);Releases memory allocated by the getaddrinfo service. |
| getnameinfo | getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags);Converts a socket address to a corresponding host and service string. |
| getpeername | getpeername(INT sockID, struct sockaddr *remoteAddress, INT *addressLength);Return remote peer's IP address and port. |
| getsockname | getsockname(INT sockID, struct sockaddr *localAddress, INT *addressLength);Return the socket's primary IP address and source port. In NetX Duo, this would be the address as index 1 in the IP interface table. |
| getsockopt | getsockopt(INT sockID, INT option_level, INT option_name, VOID *option_value, INT *option_length);Return the status of the specified socket option. |
| getaddrinfo | getaddrinfo(const CHAR *node, const CHAR *service, const struct addrinfo *hints, struct addrinfo **res);Fills in the addrinfo for the indicated node (host) based on hints in the addrinfo input. |
| ioctl | ioctl(INT sockID, INT command, INT *result);Carry out the command on the specified socket. Only two options supported FIONREAD (extract number of bytes on socket queue) and FIONBIO (enable/disable non blocking as per the result flag). |
| inet_addr | inet_addr(const CHAR *buffer);Convert an IP address from a string buffer to a number. |
| inet_ntoa | inet_ntoa(struct in_addr address_to_convert);Convert an IP address to a string. |
| inet_aton | inet_aton(const CHAR * address_buffer_ptr, struct in_addr *addr);Converts hexadecimal characters into an ASCII IP address representation. |
| inet_pton | inet_pton(INT af, const CHAR *src, VOID *dst);Converts an IP address from string to numeric format. |
| inet_ntop | inet_ntop(INT af, const VOID *src, CHAR *dst, socklen_t size);Converts an IP address from numeric format to string presentation. |
| listen | listen(INT sockID, INT backlog);Bind a TCP server socket to a local port on which to listen for connection requests. |
| recvfrom | recvfrom(INT sockID, CHAR *buffer, INT buffersize, INT flags,struct sockaddr *fromAddr, INT *fromAddrLen);Receive up to the specified number of bytes on the specified socket (either UDP or TCP). |
| recv | recv(INT sockID, VOID *rcvBuffer, INT bufferLength, INT flags)Copies up to a specified number of bytes received on the socket into specified location. The given socket can be UDP or TCP, but must be in the connected state. |
| send | send(INT sockID, const CHAR *msg, INT msgLength, INT flags)Send the specified buffer out on the socket; the actual number of bytes sent is returned in msglength. Does not support raw sockets. |
| sendto | sendto(INT sockID, CHAR *msg, INT msgLength, INT flags, struct sockaddr *destAddr, INT destAddrLen);Send the specified buffer out on the socket; the actual number of bytes sent is returned in msglength. The socket must be in a connected state. Supports raw sockets (NetX Duo BSD only). |
| select | select(INT nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);Check all sockets specified in the fd_set inputs to be checked for read request (incoming packets), write request (outgoing packets), and exception request input. |
| soc_close | soc_close( INT sockID);Close the specified socket. |
| socket | socket(INT protocolFamily, INT type, INT protocol);Creates and endpoint for communication and returns a file descriptor for the socket. |
| setsockopt | setsockopt(INT sockID, INT option_level, INT option_name, const VOID *option_value, INT option_length);Enable the input socket option on the socket. |
| fcntl | fcntl(INT sock_ID, UINT flag_type, UINT f_options);Sets flag options for the specified socket. |
| nx_bsd_raw_packet_info_extract** | nx_bsd_raw_packet_info_extract(NX_PACKET *packet_ptr, NXD_ADDRESS *nxd_address, UINT *interface_index);Extracts source IP address and interface index of the IP address in the IP interface table. |
| nx_bsd_socket_set_inherited_settings | nx_bsd_socket_set_inherited_settings(UINT master_sock_id, UINT secondary_sock_id);Apply the socket options of the specified master socket to the specified child secondary socket; requires NX_BSD_INHERIT_LISTENER_SOCKET_SETTINGS be defined. If it is not, this function has no effect. |
| nx_bsd_set_service_list | nx_bsd_set_service_list(struct NX_BSD_SERVICE_LIST *serv_list_ptr, ULONG serv_list_len);Define the service list used by getaddrinfo with the specified service list. |
**This API is only available in NetX Duo FTP Client. For definitions of of NetX Duo specific data types, see the*NetX Duo User Guide for the Renesas Synergy™ Platform*.
To utilize NetX and BSD services, the NetX BSD Support module automatically creates an IP instance, and creates memory space for the internal BSD thread stack. The packet pool can be the IP default packet pool (g_packet_pool0) or by clicking on Add NetX Packet Pool (or Add NetX Duo Packet Pool)> New, a separate packet pool, g_packet_pool1, will be used for BSD packet transmissions. For memory space, the defining parameters are the internal_thread_stack_sizeand internal_thread_priorityproperties of the NetX BSD Support stack element.
Before using NetX BSD services, the application creates one or more sockaddr_in instances local and peer hosts. A server application will only need to create a sock_addr for itself. (These are limited to IPv4 addressing.) For IPv6 addresses (which requires NetX Duo BSD), the application creates one or more sockaddr_in6instances. A socket of type TCP or UDP is created using the socket service; the protocol must be AF_INET for IPv4 or AF_INET6 for IPv6.
For raw packets (NetX Duo BSD only), the socket must be of type AF_PACKET.
Optionally, the application can set socket options such as non-blocking using the fnctl and ioctl services.
For TCP and UDP clients, the socket must bind a local-source port using the bind service. A value of zero for the port in the sockaddr_in the data instance will inform NetX to assign a local port. For the TCP sockets, the client socket connects to a TCP server using the connect service.
Both the UDP and TCP sockets can then send and receive data. Because the BSD is a streaming based protocol, data is delivered to and from the application in user-defined buffers. Internally, NetX sends and transmits data using packets from the packet pools transparently to the application. There is no requirement to release received packets or allocated packets that NetX was not able to send.
To close a client socket, the application calls soc_close. There is no need to unbind the socket when closing it using soc_close.
For TCP servers, the application chooses a local port to listen on by the specified master socket using the listen service. The master socket then checks for connection requests using the select service. When one is detected, it calls the accept service and assigns a secondary socket to handle the connection. In this manner, the BSD can maintain multiple connections simultaneously.
To close a server socket, the application calls soc_close. Unlike NetX TCP sockets, there is no need to call the nx_tcp_server_socket_unlisten or nx_tcp_server_socket_unaccept API on the TCP socket in NetX BSD.
Eliminating an Internal BSD Thread
By default, BSD utilizes an internal thread to perform some of its processing. In systems with tight memory constraints, NetX BSD can be built with NX_BSD_TIMEOUT_PROCESS_IN_TIMER defined, which eliminates the internal BSD thread and alternatively uses an internal timer to perform the same processing. This eliminates the memory required for the internal BSD thread control block and stack. The timer processing is significantly increased and the BSD processing may also execute at a higher priority than needed.
To configure BSD sockets to run in the ThreadX-timer context, define NX_BSD_TIMEOUT_PROCESS_IN_TIMER in the project. If the BSD layer is configured to execute the BSD tasks in the timer context, the following properties of the BSD stack element are ignored:
internal_thread_stack_sizeinternal_thread_priorityNetX BSD with DNS Support
If NX_BSD_ENABLE_DNS is defined, NetX BSD can send DNS queries to obtain hostname or host IP information. This feature requires a NetX DNS Client instance to be previously created. The BSD link to this DNS instance is via an extern NX_DNS *_nx_dns_instance_ptr. When the BSD application calls getnameinfo with an address or getaddrinfo with a hostname, NetX BSD will call various NetX DNS Client services to obtain the host name or IP address, respectively. Refer to the NetX DNS Client User Guide for the Renesas Synergy Platform, available as described at the Reference section at the end of this document, for more details on setting up a DNS Client in an application.
Raw Socket Support (NetX Duo BSD only)
To use raw sockets in the NetX Duo BSD, the NetX Duo library must be compiled with NX_ENABLE_IP_RAW_PACKET_FILTERdefined in the project. By default, it is not defined. To define it, right click on the project in the Synergy Configuration pane> Properties> Cross ARM C Compiler> Preprocessor and add this to the list of defined symbols by clicking on the (+) icon.
The application must then enable raw socket processing for a previously created IP instance by calling the nx_ip_raw_packet_enable service before using NetX Duo BSD services. To create a raw socket in NetX Duo BSD, the application uses the socket service and specifies the protocol family, socket type, and protocol:
sock_1 = socket(INT protocolFamily, INT socket_type, INT protocol)
The NetX BSD supports these values for protocol Family : AF_INET for IPv4 sockets, AF_INET6 for IPv6 sockets, and AF_PACKET for raw sockets. The socket_type must be set to SOCK_RAW. The protocol is application specific.
To send and receive raw packets as well as close a raw socket, the application typically uses the same BSD services as the UDP like sendto, recvfrom, select, andsoc_close. Raw sockets do not support either accept or listen BSD services.
The NetX Duo BSD supports additional raw socket options, includingIP_RAW_RX_NO_HEADER, IP_HDRINCL and IP_RAW_IPV6_HDRINCL. If IP_RAW_RX_NO_HEADER is set, the IPv4 header is removed so that the received data does not contain the IPv4 header, and the reported message length does not include the IPv4 header. For IPv6 sockets, by default the raw socket receive does not include the IPv6 header, equivalent to having the IP_RAW_RX_NO_HEADER option set. The application may use the setsockopt service to clear the IP_RAW_RX_NO_HEADER option. Once the IP_RAW_RX_NO_HEADERoption is cleared, the received IPv6 raw data would include the IPv6 header, and the reported message length includes the IPv6 header. This option has no effect on IPv4 or IPv6 transmitted data.
If IP_HDRINCL is set, the application includes the IPv4 header when sending data. This option has no effect on IPv6 transmission and is not defined by default. If the IP_RAW_IPV6_HDRINCL is set, the application includes the IPv6 header when sending data. This option has no effect on IPv4 transmission and is not defined by default.
IP_HDRINCLand IP_RAW_IPV6_HDRINCL have no effect on IPv4 or IPv6 reception.
Raw Packet Support for PPPoE (NetX Duo BSD only)
To enable the raw packet support for PPPoE, NX_BSD_RAW_PPPOE_SUPPORT must be defined in the project. To define it, right click on the project in the Synergy Configuration pane> Properties> Cross ARM C Compiler> Preprocessor and add this to the list of defined symbols by clicking on the (+) icon. This does not require that the NetX Duo library be rebuilt.
The following command creates a BSD socket to handle PPPoE raw packets:
sockfd = socket(AF_PACKET, SOCK_RAW, protocol);
The current BSD implementation only supports two protocol types in AF_PACKET family:
The data type sockaddr_ll (the ll stands for link layer) is used to specify parameters when sending or receiving PPPoE frames.
struct sockaddr_ll is declared as:
Note that not every field in the structure is used by sendto() or recvfrom(). See the following description on how to set up the sockaddr_ll for sending and receiving PPPoE packets.
A socket created in the AF_PACKET family can be used to send either PPPoE discovery packets or PPP session packets, regardless of the protocol specified. When transmitting a PPPoE packet, application must prepare the buffer that includes properly formatted PPPoE frame, including the MAC headers (destination MAC address, source MAC address, and frame type.) The size of the buffer includes the 14-byte Ethernet header.
In thesockaddr_ll struct, the sll_ifindex is used to indicate the physical interface to be used for sending this packet. The rest of the fields in the structure are not used. Values set to the unused fields are ignored by the BSD internal process.
The following code block illustrates how to transmit a PPPoE packet:
The return value indicates the number of bytes transmitted. Since PPPoE packets are message-based, on a successful transmission, the number of bytes sent matches the size of the packet, including the 14-byte Ethernet header.
PPPoE packets can be received using recvfrom(). The receive buffer must be big enough to accommodate a message of ethernet MTU size. The received PPPoE packet includes a 14-byte ethernet header. On receiving PPPoE packets, PPPoE discovery packets can only be received by socket created with protocol ETHERTYPE_PPPOE_DISC. Similarly, PPP session packets can only be received by socket created with protocol ETHERTYPE_PPPOE_SESS. If multiple sockets are created for the same protocol type, arriving PPPoE packets are forwarded to the socket created first. If the first socket created for the protocol is closed, the next socket in the order of creation is used for receiving these packets.
After a PPPoE packet is received, the following fields in the sockaddr_ll structure are valid:
sll_family: Set by the BSD internal to be AF_PACKETsll_ifindex: Indicates the interface from which the packet is receivedsll_protocol: Set to the type of packet received: ETHERTYPE_PPPOE_DISC or ETHERTYPE_PPPOE_SESSNetX BSD Build Requirements
NetX BSD Socket Options
NetX BSD socket options can be enabled (or disabled) at run time on a per socket basis using the setsockopt service, which takes as one of its inputs option_level. There are two different settings for option_level. The first type is SOL_SOCKET for socket level options. The list of supported options are:
SO_BROADCAST
If set, this enables sending and receiving broadcast packets from NetX sockets. This is the default behavior for NetX Duo. All sockets have this capability.
SO_ERROR
Used to obtain socket status on the previous socket operation of the specified socket, using the getsockoptservice. All sockets have this capability.
SO_KEEPALIVE
If set, this enables the TCP Keep Alive feature. This requires the NetX Duo library to be built with NX_TCP_ENABLE_KEEPALIVE defined (setting the TCP Keepalive property to enabled in the NetX and NetX Duo Common stack element). By default, this feature is disabled.
SO_RCVTIMEO
This sets the wait option in seconds for receiving packets on NetX Duo BSD sockets. The default value is the NX_WAIT_FOREVER (0xFFFFFFFF) or, if non-blocking is enabled, NX_NO_WAIT (0x0).
SO_RCVBUF
This sets the window size of the TCP socket. The default value, NX_BSD_TCP_WINDOW, is set to 64 k for BSD TCP sockets. To set the size over 65535 requires the NetX Duo library to be built with the NX_TCP_ENABLE_WINDOW_SCALINGbe defined (setting the TCP Keepaliveproperty to enabled in the NetX and NetX Duo Common stack element).
SO_REUSEADDR
If set, this enables multiple sockets to be mapped to one port. The typical usage is for the TCP Server socket. This is the default behavior of NetX sockets.
int bsd_errno;
This is explained in NetX BSD Build Requirements section above.
The other type is IP_PROTO for options that are implemented at the IP layer and affect all sockets. The list of run time IP level options is shown below:
IP_MULTICAST_TTL
This sets the time to live for UDP sockets. The default value is NX_IP_TIME_TO_LIVE (0x80) when the socket is created. This value can be overridden by calling setsockoptwith this socket option before calling the socket service.
IP_ADD_MEMBERSHIP
If set, this option enables the BSD socket (applies only to UDP sockets) to join the specified IGMP group.
IP_DROP_MEMBERSHIP
If set, this option enables the BSD socket (applies only to UDP sockets) to leave the specified IGMP group.
The following options are only supported in NetX Duo BSD:
IP_HDRINCL
If this option is set, the calling application must append the IP header and optionally application headers to data being transmitted on raw IPv4 sockets created in BSD. To use this option, raw socket processing must be enabled on the IP task. See the previous section Raw Socket Support for specific details.
IP_RAW_IPV6_HDRINCL
If this option is set, the calling application must append an IPv6 header and optionally application headers to data being transmitted on raw IPv6 sockets created by BSD. To use this option, raw socket processing must be enabled on the IP task. See the previous section Raw Socket Support for specific details.
IP_RAW_RX_NO_HEADER
If cleared, the IPv6 header is included with the received data for raw IPv6 sockets created in BSD. IPv6 headers are removed by default in BSD raw IPv6 sockets, and the packet length does not include the IPv6 header. If set, the IPv4 header is removed from received data on BSD raw sockets of type IPv4. IPv4 headers are included by default in BSD raw IPv4 sockets and packet length includes the IPv4 header. This option has no effect on either IPv4 or IPv6 transmission data. See the previous section Raw Socket Support for specific details on enabling raw packet support.
To retrieve an option setting, call getsockopt for the option name with option_level again set to SOL_SOCKET for socket level options or IP_PROTOfor IP level options.
More details on run time socket level options are available in the NetX™ BSD 4.3 Socket API Wrapper for NetX User's Guide for the Renesas Synergy™ Platform and NetX Duo™ BSD 4.3 Socket API Wrapper for NetX Duo User's Guide for the Renesas Synergy™ Platform documents available as described previously in the Introduction section.
_POSIX_SOURCE among the project preprocessor definitions. This is done by right clicking at the top level of the project, Properties> C/C++ Build> Settings> Cross ARM C Compiler (if using that project platform)> Preprocessor.NetX BSD Build Requirements
Define the following property in the ThreadX Source element:
TX_THREAD_EXTENSION_2 int bsd_errno; By default, all the EXTENSION macros are undefined;bsd_errno can also be defined as TX_THREAD_EXTENSION_1 or TX_THREAD_EXTENSION_0.
NetX BSD Socket Options
NetX BSD socket options can be enabled (or disabled) at run time on a per socket basis using the setsockopt service, which takes as one of its inputs option_level. There are two different settings for option_level. The first type is SOL_SOCKET for socket level options. The list of supported options are:
SO_BROADCAST
If set, this enables sending and receiving broadcast packets from NetX sockets. This is the default behavior for NetX Duo. All sockets have this capability.
SO_ERROR
Used to obtain socket status on the previous socket operation of the specified socket, using the getsockoptservice. All sockets have this capability.
SO_KEEPALIVE
If set, this enables the TCP Keep Alive feature. This requires the NetX Duo library to be built with NX_TCP_ENABLE_KEEPALIVE defined (setting the TCP Keepalive property to enabled in the NetX and NetX Duo Common stack element). By default, this feature is disabled.
SO_RCVTIMEO
This sets the wait option in seconds for receiving packets on NetX Duo BSD sockets. The default value is the NX_WAIT_FOREVER (0xFFFFFFFF) or, if non-blocking is enabled, NX_NO_WAIT (0x0.
SO_RCVBUF
This sets the window size of the TCP socket. The default value, NX_BSD_TCP_WINDOW, is set to 64 k for BSD TCP sockets. To set the size over 65535 requires the NetX Duo library to be built with the NX_TCP_ENABLE_WINDOW_SCALINGbe defined (setting the TCP Keepaliveproperty to enabled in the NetX and NetX Duo Common stack element).
SO_REUSEADDR
If set, this enables multiple sockets to be mapped to one port. The typical usage is for the TCP Server socket. This is the default behavior of NetX sockets.
int bsd_errno;
This is explained in NetX BSD Build Requirements section above.
The other type is IP_PROTO for options that are implemented at the IP layer and affect all sockets. The list of run time IP level options is shown below:
IP_MULTICAST_TTL
This sets the time to live for UDP sockets. The default value is NX_IP_TIME_TO_LIVE (0x80) when the socket is created. This value can be overridden by calling setsockoptwith this socket option before calling the socket service.
IP_ADD_MEMBERSHIP
If set, this option enables the BSD socket (applies only to UDP sockets) to join the specified IGMP group.
IP_DROP_MEMBERSHIP
If set, this option enables the BSD socket (applies only to UDP sockets) to leave the specified IGMP group.
The following options are only supported in NetX Duo BSD:
IP_HDRINCL
If this option is set, the calling application must append the IP header and optionally application headers to data being transmitted on raw IPv4 sockets created in BSD. To use this option, raw socket processing must be enabled on the IP task. See the previous section Raw Socket Support for specific details.
IP_RAW_IPV6_HDRINCL
If this option is set, the calling application must append an IPv6 header and optionally application headers to data being transmitted on raw IPv6 sockets created by BSD. To use this option, raw socket processing must be enabled on the IP task. See the previous section Raw Socket Support for specific details.
IP_RAW_RX_NO_HEADER
If cleared, the IPv6 header is included with the received data for raw IPv6 sockets created in BSD. IPv6 headers are removed by default in BSD raw IPv6 sockets, and the packet length does not include the IPv6 header. If set, the IPv4 header is removed from received data on BSD raw sockets of type IPv4. IPv4 headers are included by default in BSD raw IPv4 sockets and packet length includes the IPv4 header. This option has no effect on either IPv4 or IPv6 transmission data. See the previous section Raw Socket Support for specific details on enabling raw packet support.
To retrieve an option setting, call getsockopt for the option name with option_level again set to SOL_SOCKET for socket level options or IP_PROTOfor IP level options.
More details on run time socket level options are available in the NetX™ BSD 4.3 Socket API Wrapper for NetX User's Guide for the Renesas Synergy™ Platform and NetX Duo™ BSD 4.3 Socket API Wrapper for NetX Duo User's Guide for the Renesas Synergy™ Platform documents available as described previously in the Introduction section.
_POSIX_SOURCE among the project preprocessor definitions. This is done by right clicking at the top level of the project, Properties> C/C++ Build> Settings> Cross ARM C Compiler (if using that project platform)> Preprocessor.MSG_DONTWAIT and MSG_PEEK flags are supported for send, recv, sendto and recvfrom calls.SO_BROADCASTSO_ERRORSO_KEEPALIVESO_RCVTIMEOSO_RCVBUFSO_REUSEADDRIP_RAW_IPV6_HDRINCL (NetX Duo BSD only)IP_ADD_MEMBERSHIPIP_DROP_MEMBERSHIPIP_HDRINCL(NetX Duo BSD only, raw sockets must be enabled)IP_RAW_RX_NO_HEADER (NetX Duo BSD only, raw sockets must be enabled)This section describes how to include either or both the NetX and NetX Duo BSD Support module in an application using the SSP configurator.
To add the NetX/NetX Duo BSD Support module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo BSD Support Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| NetX BSD Support | Threads | New Stack> X-Ware> NetX> Protocols> NetX BSD Support |
| NetX Duo BSD Support | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo BSD Support |
When the NetX and/or NetX Duo BSD Support module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:
The NetX/NetX Duo BSD Support module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the NetX/NetX Duo BSD Support Module
| ISDE Property | Value | Description |
|---|---|---|
| NetX BSD Warning | Enable, Disable Default: Enable | NetX BSD warning selection. |
| Internal thread stack size(bytes) | 2048 | Internal thread stack size selection. |
| Internal thread priority | 3 | Internal thread priority selection. |
| Name of generated initialization function | nx_bsd_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization function. |
In some cases, settings other than the defaults for lower-level modules can be desirable. For example, it might be useful to select different MAC or IP Addresses. The configurable properties for the lower-level stack modules are provided in the following sections for completeness and as a reference.
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the NetX/NetX Duo IP Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ip0 | Module name. |
| IPv4 Address (use commas for separation) | 192,168,0,2 | IPv4 Address selection. |
| Subnet Mask (use commas for separation) | 255,255,255,0 | Subnet Mask selection. |
| Default Gateway Address (use commas for separation) | 0,0,0,0 | Default gateway address selection. |
| **IPv6 Global Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | IPv6 global address selection. |
| **IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) | 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 | IPv6 link local address selection. |
| IP Helper Thread Stack Size (bytes) | 2048 | IP Helper Thread Stack Size (bytes) selection. |
| IP Helper Thread Priority | 3 | IP Helper Thread Priority selection. |
| ARP | Enable | ARP selection. |
| ARP Cache Size in Bytes | 512 | ARP Cache Size in Bytes selection. |
| Reverse ARP | Enable, Disable Default: Disable | Reverse ARP selection. |
| TCP | Enable, Disable Default: Enable | TCP selection. |
| UDP | Enable, Disable Default: Enable | UDP selection. |
| ICMP | Enable, Disable Default: Enable | ICMP selection. |
| IGMP | Enable, Disable Default: Enable | IGMP selection. |
| IP fragmentation | Enable, Disable Default: Disable | IP fragmentation selection. |
| Name of generated initialization function | ip_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization function. |
| Link status change callback | NULL | Link status change callback selection. |
** Indicates properties that are only available in NetX Duo.
Configuration Settings for the NetX/NetX Duo Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name of generated initialization function | nx_common_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Configuration Settings for the NetX/NetX Duo Packet Pool Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_packet_pool0 | Module name. |
| Packet Size in Bytes | 640 | Packet size selection. |
| Number of Packets in Pool | 16 | Number of packets in pool selection. |
| Name of generated initialization function | packet_pool_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
The ETHERC peripheral module uses the PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator Clock tab prior to a build or by using the CGC interface at run-time.
The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required. The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the I2C pins.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals> Connectivity:ETHERC> ETHERC1.RMII |
Pin Configuration Settings for the ETHERC1
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, RMII Default: Disabled | Select RMII as the Operation Mode for ETHERC1. |
| Pin Group Selection | Mixed, _A only Default: _A only | Pin group selection. |
| REF50CK | P701 | REF50CK pin. |
| TXD0 | P700 | TXD0 pin. |
| TXD1 | P406 | TXD1 pin. |
| TXD_EN | P405 | TXD_EN pin. |
| RXD0 | P702 | RXD0 pin. |
| RXD1 | P703 | RXD1 pin. |
| RX_ER | P704 | RX_ER pin. |
| CRS_DV | P705 | CRS_DV pin. |
| MDC | P403 | MDC pin. |
| MDIO | P404 | MDIO pin. |
The steps in using the NetX and NetX Duo BSD Support module in a typical application are:
NetX BSD Client:
nx_ip_status_check API for when the IP instance has a valid IP address.socket API.sockaddr_in for client and server defining IP address and port for client and server.bind API.connect API.getpeername, getsockname services [Optional].send API.recv API.soc_close API.NetX BSD Server:
1. Poll the nx_ip_status_check API for when the IP instance has a valid IP address.
2. Create a master socket using the socket API.
3. Create sockaddr_in defining IP address and port for server.
4. Bind the socket to a port using the bind API.
5. Assign a local source port to listen for client requests using the listen API.
6. Check for socket requests (read, write, exception) using the select API.
7. Accept client requests and hand off the connection to a secondary socket using the accept API.
8. Receive packets using the recv API.
9. Send packets using the send API.
10. Close the socket using the soc_close API.
The following figure illustrates common steps in a typical operational flow diagram:
NetX Duo BSD Client
nx_ip_status_check API for when the IP instance has a valid IP address.socket API.sockaddr_in (or sockaddr_in6 for IPv6) defining IP (or IPv6) address and port for client and server.bind API.connect API.getpeername, getsockname services [Optional]send API.recv and send API.soc_close API.NetX Duo BSD Server
nx_ip_status_check API for when the IP instance has a valid IP address.socket API.sockaddr_in (or sockaddr_in6 for IPv6) defining IP (or IPv6) address and port for server Set socket options using the ioctl, setsockopt APIsbind API.listen API.select API.accept API.recv API.send API.soc_close APIThe following figure illustrates common steps in a typical operational flow diagram:
