Dallas Semiconductor DS80C400 C Libraries Home Page

Main Page   Data Structures   File List   Data Fields   Globals  

rom400_sock.h File Reference


Detailed Description

Socket functions in the DS80C400 ROM.

This library contains functions for TCP, UDP and Multicast sockets, as well as network configuration. The functions in this library are safe to be called from multiple processes at the same time, with the exception of the function ping. Both the traditional Berkeley style socket API and the synchronized socket functions are supported (the Berkeley style API is supported through macros implemented by the synchronized functions).

It is recommended that new applications use the Berkeley style API for portability.

Note that in order to run at 100 Mbs, the DS80C400 must be running at least 25MHz. This can be accomplished on the TINIm400 module by enabling the clock doubler.

For detailed information on the DS80C400 please see the High-Speed Microcontroller User's Guide: DS80C400 Supplement.

#include <stdlib.h>

Go to the source code of this file.

Data Structures

struct  in6_addr
struct  in_addr
struct  pingdata
struct  sockaddr
struct  sockaddr_in

Defines

#define ROM400_SOCK_SYNCH_VERSION   10
#define ROM400_SOCK_VERSION   10
#define SOCKET_TYPE_DATAGRAM   0
#define SOCKET_TYPE_STREAM   1
#define SOCK_DGRAM   0
#define SOCK_STREAM   1
#define PF_INET   4
#define AF_INET   4
#define AF_INET6   6
#define IPPROTO_UDP   0
#define TCP_NODELAY   0
#define SO_LINGER   1
#define SO_TIMEOUT   2
#define SO_BINDADDR   3
#define ETH_STATUS_LINK   1
#define htons(x)   (x)
 Convert a number to network byte order.

#define ntohs(x)   (x)
 Convert a number to host byte order.

#define socket(domain, type, protocol)   syn_socket((type))
 Create a network socket for TCP or UDP communication.

#define closesocket(socket_num)   syn_closesocket((socket_num))
 Closes a specific socket.

#define sendto(socket_num, buffer, length, flags, address, address_length)   syn_sendto(syn_setDatagramAddress((socket_num),1,(address)),(length),(buffer))
 Sends a UDP datagram to a specified address.

#define recvfrom(socket_num, buffer, length, flags, address, address_length)   syn_recvfrom(syn_setDatagramAddress((socket_num),0,(address)),(length),(buffer))
 Receive a UDP datagram.

#define connect(socket_num, address, address_length)   syn_connect((socket_num),(address))
 Connects a TCP socket to a specified address.

#define bind(socket_num, address, address_length)   syn_bind((socket_num),(address))
 Binds a socket to a specified address.

#define listen(socket_num, backlog)   syn_listen((socket_num),(backlog))
 Tells a socket to listen for incoming connections.

#define accept(socket_num, address, address_length)   syn_accept((socket_num),(address))
 Accepts TCP connections on the specified socket.

#define recv(socket_num, buffer, length, flags)   syn_recv((socket_num),(length),(buffer))
 Reads data from a TCP socket.

#define send(socket_num, buffer, length, flags)   syn_send((socket_num),(length),(buffer))
 Sends data to a TCP socket.

#define getsockopt(socket_num, level, name, buffer, length)   syn_getsockopt((socket_num),(name),(buffer))
 Get various socket options.

#define setsockopt(socket_num, level, name, buffer, length)   syn_setsockopt((socket_num),(name),(buffer))
 Set various socket options.

#define getsockname(socket_num, address, address_length)   syn_getsockname((socket_num),(address))
 Gets the local IP and port of a socket.

#define getpeername(socket_num, address, address_length)   syn_getpeername((socket_num),(address))
 Gets the remote address of a connection-based (TCP socket).

#define cleanup(process_id)   syn_cleanup((process_id))
 Close all sockets associated with a task.

#define avail(socket_num)   syn_avail((socket_num))
 Reports number of bytes available on a TCP socket.

#define join(socket_num, address, address_length)   syn_join((socket_num),(address))
 Adds a socket to a specified multicast group.

#define leave(socket_num, address, address_length)   syn_leave((socket_num),(address))
 Removes a socket from the specified multicast group.

#define getnetworkparams(param_buffer)   syn_getnetworkparams((param_buffer))
 Get the IPv4 configuration parameters.

#define setnetworkparams(param_buffer)   syn_setnetworkparams((param_buffer))
 Set the IPv4 configuration parameters.

#define getipv6params(param_buffer)   syn_getipv6params((param_buffer))
 Get the IPv6 address.

#define getethernetstatus()   syn_getethernetstatus()
 Get the ethernet status.

#define gettftpserver(address, address_length)   syn_gettftpserver((address))
 Get the address of the TFTP server.

#define settftpserver(address, address_length)   syn_settftpserver((address))
 Set the address of the TFTP server.

#define getmacid()   syn_getmacid()
 Get the pointer to the MAC ID storage area.

#define setmacid()   syn_setmacid()
 Stores the MAC ID into the MAC ID storage area.

#define sock_version()   syn_version()
 Returns the version number of this socket library.

#define arp_generaterequest(address, address_length)   syn_arp_generaterequest((address))
 Unconditionally generate an ARP request for a given IPv4 address.

#define arp_cacherequest(address, address_length)   syn_arp_cacherequest((address))
 Generate an ARP request for a given IPv4 address and add to the ARP cache.


Functions

char * inet_ntop (int family, void *addr, char *strptr, size_t len)
 Converts a numeric address to a string.

unsigned int inet_pton (int family, char *str, void *addr)
 Converts a string to a numeric IP address.

unsigned long inet_addr (char *inet_string)
 Converts a string representing an IPv4 address to numeric form.

int syn_socket (unsigned int type)
 Create a network socket for TCP or UDP communication.

int syn_closesocket (int socket_num)
 Closes a specific socket.

int syn_setDatagramAddress (int socket_num, unsigned char sending, struct sockaddr *addr)
 Set the IP address parameter for future datagram calls.

int syn_sendto (int socket_num, unsigned int length, void *buffer)
 Sends a UDP datagram to an address earlier specified by a call to syn_setDatagramAddress.

int syn_recvfrom (int socket_num, unsigned int length, void *buffer)
 Receive a UDP datagram.

int syn_connect (int socket_num, struct sockaddr *address)
 Connects a TCP socket to a specified address.

int syn_bind (int socket_num, struct sockaddr *address)
 Binds a socket to a specified address.

int syn_listen (int socket_num, unsigned int backlog)
 Tells a socket to listen for incoming connections.

int syn_accept (int socket_num, struct sockaddr *address)
 Accepts TCP connections on the specified socket.

int syn_recv (int socket_num, unsigned int length, void *buffer)
 Reads data from a TCP socket.

int syn_send (int socket_num, unsigned int length, void *buffer)
 Sends data to a TCP socket.

int syn_getsockopt (int socket_num, unsigned int name, void *buffer)
 Get various socket options.

int syn_setsockopt (int socket_num, unsigned int name, void *buffer)
 Set various socket options.

int syn_getsockname (int socket_num, struct sockaddr *address)
 Gets the local IP and port of a socket.

int syn_getpeername (int socket_num, struct sockaddr *address)
 Gets the remote address of a connection-based (TCP socket).

int syn_cleanup (unsigned int process_id)
 Close all sockets associated with a task.

int syn_avail (int socket_num)
 Reports number of bytes available on a TCP socket.

int syn_join (int socket_num, struct sockaddr *address)
 Adds a socket to a specified multicast group.

int syn_leave (int socket_num, struct sockaddr *address)
 Removes a socket from the specified multicast group.

int syn_getnetworkparams (void *param_buffer)
 Get the IPv4 configuration parameters.

int syn_setnetworkparams (void *param_buffer)
 Set the IPv4 configuration parameters.

int syn_getipv6params (void *param_buffer)
 Get the IPv6 address.

unsigned int syn_getethernetstatus (void)
 Get the ethernet status.

int syn_gettftpserver (struct sockaddr *address)
 Get the address of the TFTP server.

int syn_settftpserver (struct sockaddr *address)
 Set the address of the TFTP server.

unsigned char * syn_getmacid (void)
 Get the pointer to the MAC ID storage area.

void syn_setmacid (void)
 Stores the MAC ID into the MAC ID storage area.

void clear_param_buffers (void)
 Clears the parameter buffers used by the socket library.

unsigned int syn_version (void)
 Returns the version number of this socket library.

int syn_arp_generaterequest (struct sockaddr *address)
 Generate an ARP request for a given IPv4 address.

int syn_arp_cacherequest (struct sockaddr *address)
 Generate an ARP request for a given IPv4 address and add to the ARP cache.

int acceptqueue (int socket_handle, struct sockaddr *address)
 Returns the number of sockets in the wait queue for this listening socket.

int udpavailable (int socket_handle, struct sockaddr *address)
 Returns whether or not data is available to be read on a datagram socket.

long ping (struct sockaddr *address, unsigned int address_length, unsigned int time_to_live, struct pingdata *response)
 Pings the specified address.

unsigned int eth_readmii (unsigned int phy, unsigned int reg)
 Read a PHY register via MII.

void eth_writemii (unsigned int phy, unsigned int reg, unsigned int val)
 Write a PHY register via MII.

void eth_disablemulticastreceiver (void)
 Disable multicast hardware receiver.


Define Documentation

#define accept socket_num,
address,
address_length       syn_accept((socket_num),(address))
 

Accepts TCP connections on the specified socket.

Accepts a TCP conection on the specified socket. This function moves the first pending connection request from the listen queue into the established state, assigning a new local socket to the connection for communication. accept blocks if there are no pending incoming requests. The socket socket_num must have been created with type SOCKET_TYPE_STREAM, bound to an address using bind, and given a listen queue by calling listen.

Parameters:
socket_num the handle of the socket that will wait for connections
address location to write remote address
address_length the length of the address structure (ignored)
Returns:
New socket handle for communicating with remote socket, or 0x0FFFF for failure
See also:
socket

bind

listen

#define AF_INET   4
 

IPv4 family define, ignored by DS80C400 Silicon Software, but included for compatibility

#define AF_INET6   6
 

IPv6 family define, ignored by DS80C400 Silicon Software, but included for compatibility

#define arp_cacherequest address,
address_length       syn_arp_cacherequest((address))
 

Generate an ARP request for a given IPv4 address and add to the ARP cache.

If the given IP address is not in the ARP cache, generate an ARP request and add it to the cache.

Parameters:
address structure to store the address
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure

#define arp_generaterequest address,
address_length       syn_arp_generaterequest((address))
 

Unconditionally generate an ARP request for a given IPv4 address.

Unconditionally generate an ARP request for a given IPv4 address. This functionality can be used to implement Zeroconf protocols.

Parameters:
address structure to store the address
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure

#define avail socket_num       syn_avail((socket_num))
 

Reports number of bytes available on a TCP socket.

Reports the number of bytes available on a TCP socket. This is the number of bytes that can currently be read using the recv function without blocking.

Parameters:
socket_num the handle of the socket to check for available data
Returns:
The number of bytes available for a recv function call on this socket, or 0x0FFFF on failure.
See also:
recv

#define bind socket_num,
address,
address_length       syn_bind((socket_num),(address))
 

Binds a socket to a specified address.

Assigns a local address and port (stored in the address parameter) to a socket. Binding a socket is necessary for server sockets. For client sockets, use bind if a specific source port is desirable.

Fill address with 0's (for sin_addr and sin_port) to bind to any available local port. Use getsockname to discover which port the socket was bound to.

NOTE: When binding a UDP socket, matching inbound UDP packets will be queued up for the socket. Call recvfrom periodically to avoid the risk of running out of kernel memory.

Parameters:
socket_num socket handle to bind to a local port number
address contains the local address (including port number)
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure.
See also:
listen

getsockname

recvfrom

#define cleanup process_id       syn_cleanup((process_id))
 

Close all sockets associated with a task.

Close all sockets associtaed with a process ID. User applications should call this function whenever a task dies or is killed to ensure all associated resources are freed by the socket layer.

Warning:
The DS80C400 Silicon Software task scheduler does NOT call this function. User applications should call cleanup after each call to task_kill.
Parameters:
process_id Task PID to clean up sockets associated with
Returns:
0 for success, non-zero for failure.

#define closesocket socket_num       syn_closesocket((socket_num))
 

Closes a specific socket.

Closes the specified socket that was created using the socket function.

Parameters:
socket_num the socket handle to close
Returns:
0 for success, non-zero for failure.
See also:
socket

#define connect socket_num,
address,
address_length       syn_connect((socket_num),(address))
 

Connects a TCP socket to a specified address.

Connects to a specified address with a streaming socket. This function can only be used once with each socket. The socket socket_num must have been created with type SOCKET_TYPE_STREAM.

Parameters:
socket_num the socket handle to use to wait for and read a UDP packet
address IP address and port number to create a streaming connection to
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure.
See also:
socket

#define ETH_STATUS_LINK   1
 

Flag for analyzing ethernet status.

See also:
getethernetstatus

 
#define getethernetstatus      syn_getethernetstatus()
 

Get the ethernet status.

Returns the ethernet status byte. This is a bit-wise OR of the following flags:
Flag Value Description
ETH_STATUS_LINK 01h Ethernet link status

Currently, no other flags are defined.

Returns:
Bitmapped ethernet status byte.

#define getipv6params param_buffer       syn_getipv6params((param_buffer))
 

Get the IPv6 address.

Gets the IPv6 address of the ethernet interface. The format for the buffer after this function returns is:
Parameter Offset Length Description
IP6ADDR 0 16 IP address
IP6PREFIX 16 1 IP prefix length

Parameters:
param_buffer pointer to buffer to store IPv6 configuration data
Returns:
0 for success, non-zero for failure
See also:
getnetworkparams

setnetworkparams

 
#define getmacid      syn_getmacid()
 

Get the pointer to the MAC ID storage area.

Returns the pointer to the MAC ID storage area. This area will store the MAC ID after a successful call to setmacid.

Returns:
Pointer to the 400's MAC ID (6 bytes stored at this location)
See also:
setmacid

#define getnetworkparams param_buffer       syn_getnetworkparams((param_buffer))
 

Get the IPv4 configuration parameters.

Get the IPv4 configuration parameters, including IP address, subnet mask, and gateway. The parameters are returned in a buffer in the following form:
Parameter Offset Length Description
(zero) 0 12 Must be 0
IP4ADDR 12 4 IP address
IP4SUBNET 16 4 Subnet mask
IP4PREFIX 20 1 Number of 1 bits in subnet mask
(zero) 21 12 Must be 0
IP4GATEWAY 33 4 Gateway IP address

IPv6 addresses are autoconfigured. To retrieve the IPv6 address, use the getipv6params function.

Parameters:
param_buffer pointer to buffer to store IP configuration data
Returns:
0 for success, non-zero for failure
See also:
setnetworkparams

getipv6params

#define getpeername socket_num,
address,
address_length       syn_getpeername((socket_num),(address))
 

Gets the remote address of a connection-based (TCP socket).

Stores the IP address of the remote socket communicating with the socket specified by socket_num. Use getsockname to get the local port's information.

Parameters:
socket_num handle of the socket to get remote IP and port for
address structure where IP and port will be stored
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure
See also:
getsockname

#define getsockname socket_num,
address,
address_length       syn_getsockname((socket_num),(address))
 

Gets the local IP and port of a socket.

Stores the local IP and port number of the specified socket in the the address parameter. Use getpeername to get the remote port's information for a connection-based (TCP) socket.

Parameters:
socket_num handle of the socket to get local IP and port for
address structure where IP and port will be stored
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure
See also:
getpeername

#define getsockopt socket_num,
level,
name,
buffer,
length       syn_getsockopt((socket_num),(name),(buffer))
 

Get various socket options.

Reads a number of supported socket options. Data written into the buffer depends on the requested socket option.

Name Description Data in buffer
TCP_NODELAY TCP Nagle Enable 1 byte
SO_LINGER Ignored N/A
SO_TIMEOUT Inactivity timeout 4 bytes (milliseconds, MSB first)
SO_BINDADDR Local socket IP 16 bytes

Parameters:
socket_num socket to get option information for
level ignored
name option to get
buffer location where option data will be written
length length of the buffer
Returns:
0 for success, non-zero for failure
See also:
setsockopt

#define gettftpserver address,
address_length       syn_gettftpserver((address))
 

Get the address of the TFTP server.

Returns the address of the server accessed by the TFTP functions. To communicate with a TFTP server, use the functions listed in rom400_tftp.h, the TFTP library.

Parameters:
address structure to store the address of the TFTP server
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure
See also:
settftpserver

#define htons      (x)
 

Convert a number to network byte order.

Converts a word from host byte order to network byte order. On the DS80C400, the orders are the same, so this function does not alter the input data. This function is included for compatibility.

Parameters:
x Input data to convert to network byte order
Returns:
Input data converted to network byte order

#define IPPROTO_UDP   0
 

Protocol ID define, ignored by DS80C400 Silicon Software, but included for compatibility

#define join socket_num,
address,
address_length       syn_join((socket_num),(address))
 

Adds a socket to a specified multicast group.

Adds a UDP socket to a specified multicast group. In order to receive multicasts from a group, first bind the socket to the port number that the multicast group is using (it is not sufficient to include it here in order to receive).

Use the leave function to leave a multicast group.

Warning:
IPv6 multicasting is not supported
Parameters:
socket_num handle for the datagram socket that will join a multicast group
address IP address of the multicast group to join
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure.
See also:
leave

#define leave socket_num,
address,
address_length       syn_leave((socket_num),(address))
 

Removes a socket from the specified multicast group.

Removes a UDP socket from the specified multicast group.

Parameters:
socket_num handle for the datagram socket that will leave a multicast group
address IP address of the multicast group to leave
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure.
See also:
join

#define listen socket_num,
backlog       syn_listen((socket_num),(backlog))
 

Tells a socket to listen for incoming connections.

Tells the socket to listen for connections. A queue of length backlog is created for pending (un-accepted connections). It is required to use bind to assign a local port before calling listen. Use accept to move an incoming request to an established state, or wait for incoming connections.

Parameters:
socket_num socket handle that will listen for connections
backlog the maximum number of pending connections (max 16 for the DS80C400)
Returns:
0 for success, non-zero for failure.
See also:
bind

accept

#define ntohs      (x)
 

Convert a number to host byte order.

Converts a word from network byte order to host byte order. On the DS80C400, the orders are the same, so this function does not alter the input data. This function is included for compatibility.

Parameters:
x Input data to convert to network byte order
Returns:
Input data converted to network byte order

#define PF_INET   4
 

IPv4 protocol family define

#define recv socket_num,
buffer,
length,
flags       syn_recv((socket_num),(length),(buffer))
 

Reads data from a TCP socket.

Reads data from a TCP socket. If there is no data available, recv blocks until there is data, subject to the value of SO_TIMEOUT. NOTE: This function reads up to length bytes. Call this function repeatedly if you need to read a minimum number of bytes.

Parameters:
socket_num handle of the streaming socket that will read data
buffer location to write any data read
length maximum amount of data to read
flags ignored
Returns:
The number of bytes read. If the operation times out according to the SO_TIMEOUT, a value of -2 is returned. If another error occurs, -1 is returned. If the socket was closed by the other side, 0 is returned.
See also:
connect

send

#define recvfrom socket_num,
buffer,
length,
flags,
address,
address_length       syn_recvfrom(syn_setDatagramAddress((socket_num),0,(address)),(length),(buffer))
 

Receive a UDP datagram.

Receives a message on the specified socket, and stores the address that sent it. If no data is available, recvfrom blocks subject to the SO_TIMEOUT value. The socket socket_num must have been created with a type SOCKET_TYPE_DATAGRAM. It is required to use bind to assign a local port to the socket, before receiving data. NOTE: This function reads up to length bytes of a datagram. Any data not read in the datagram will be discarded.

Parameters:
socket_num the socket handle to use to wait for and read a UDP packet
buffer the location to write any data read from the datagram socket
length the maximum number of bytes to read from a datagram socket
flags ignored
address location to fill in the address and port of the sender
address_length the length of the address structure (ignored)
Returns:
The number of bytes read. If the operation times out according to the SO_TIMEOUT, a value of -2 is returned. If another error occurs, -1 is returned.
See also:
sendto

socket

bind

#define ROM400_SOCK_SYNCH_VERSION   10
 

Version number associated with this header file. Should be the same as the version number returned by the syn_version function.

See also:
syn_version

#define ROM400_SOCK_VERSION   10
 

Version number associated with this header file. Should be the same as the version number returned by the sock_version function.

See also:
sock_version

#define send socket_num,
buffer,
length,
flags       syn_send((socket_num),(length),(buffer))
 

Sends data to a TCP socket.

Writes data to a TCP socket. The return value of this function is only a local success/failure code, and may not necessarily detect transmission errors.

Parameters:
socket_num handle of the streaming socket that will write data
buffer location of data to write
length number of bytes to write
flags ignored
Returns:
0 for success, non-zero for failure.
See also:
connect

recv

#define sendto socket_num,
buffer,
length,
flags,
address,
address_length       syn_sendto(syn_setDatagramAddress((socket_num),1,(address)),(length),(buffer))
 

Sends a UDP datagram to a specified address.

Sends a UDP datagram to a specified address. The success/failure code this function returns says nothing of if the packet was recieved by the target, only that the socket layer was able to push the data out. The socket socket_num must have been created with a type SOCKET_TYPE_DATAGRAM.

Parameters:
socket_num the socket handle to use to send a UDP packet
buffer the data to send in the datagram packet
length the number of bytes to send in the datagram packet
flags ignored
address the destination address and port
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure.
See also:
recvfrom

socket

 
#define setmacid      syn_setmacid()
 

Stores the MAC ID into the MAC ID storage area.

This is a redirected function. The DS80C400's default implementation of this function searches the 1-Wire for a DS2502U-E48 1-Wire chip which contains a MAC ID. This MAC ID is then stored into the MAC ID storage area, the location of which is stored in a pointer in the export table. Use the getmacid function to return a pointer to the MAC ID storage area.

See also:
getmacid

#define setnetworkparams param_buffer       syn_setnetworkparams((param_buffer))
 

Set the IPv4 configuration parameters.

Set the IPv4 configuration parameters, including IP address, subnet mask, and gateway. Input parameters should be formatted in the following form:
Parameter Offset Length Description
(zero) 0 12 Must be 0
IP4ADDR 12 4 IP address
IP4SUBNET 16 4 Subnet mask
IP4PREFIX 20 1 Number of 1 bits in subnet mask
(zero) 21 12 Must be 0
IP4GATEWAY 33 4 Gateway IP address

Use this method to give the DS80C400 a static IP address. To dynamically configure an IP address, use methods from the DHCP library in rom400_dhcp.h (IP addresses leased by the DHCP client can still be retrieved by calling getnetworkparams).

IPv6 addresses are autoconfigured. To retrieve the IPv6 address, use the getipv6params function.

Parameters:
param_buffer pointer to buffer with IP configuration data
Returns:
0 for success, non-zero for failure
See also:
getnetworkparams

getipv6params

#define setsockopt socket_num,
level,
name,
buffer,
length       syn_setsockopt((socket_num),(name),(buffer))
 

Set various socket options.

Sets a number of supported socket options. Input data in the buffer depends on the desired socket option.

Name Description Data in buffer
TCP_NODELAY TCP Nagle Enable 1 byte
SO_LINGER Ignored N/A
SO_TIMEOUT Inactivity timeout 4 bytes (milliseconds, MSB first)
SO_BINDADDR Read only N/A

Parameters:
socket_num socket to set option information for
level ignored
name option to set
buffer location of option data that will be written
length length of the buffer
Returns:
0 for success, non-zero for failure
See also:
getsockopt

#define settftpserver address,
address_length       syn_settftpserver((address))
 

Set the address of the TFTP server.

Set the address of the server that the TFTP functions will use. The settftpserver function must be used if the address of the TFTP server is not acquired by DHCP or 1-Wire. Once the TFTP server's address is set, use the functions listed in rom400_tftp.h to begin receiving files.

Parameters:
address structure to store the address of the TFTP server
address_length the length of the address structure (ignored)
Returns:
0 for success, non-zero for failure
See also:
gettftpserver

#define SO_BINDADDR   3
 

Argument for socket option. Local binding address.

See also:
getsockopt

setsockopt

#define SO_LINGER   1
 

Argument for socket option. Ignored by DS80C400 ROM.

See also:
getsockopt

setsockopt

#define SO_TIMEOUT   2
 

Argument for socket option. Socket inactivity timeout.

See also:
getsockopt

setsockopt

#define SOCK_DGRAM   0
 

Argument to function socket to create a UDP socket (same as SOCKET_TYPE_DATAGRAM)

See also:
socket

#define SOCK_STREAM   1
 

Argument to function socket to create a TCP socket (same as SOCKET_TYPE_STREAM)

See also:
socket

 
#define sock_version      syn_version()
 

Returns the version number of this socket library.

Returns:
Version number of this SOCK library.

#define socket domain,
type,
protocol       syn_socket((type))
 

Create a network socket for TCP or UDP communication.

Creates a socket for network communication. This function returns a socket handle, but has not specific local address assigned to it. Note that this function calls task_gettaskid through the function redirect table.

Parameters:
domain ignored
type SOCKET_TYPE_DATAGRAM or SOCK_DGRAM for UDP, SOCKET_TYPE_STREAM or SOCK_STREAM for TCP
protocol ignored
Returns:
0x0FFFF for failure, or the socket handle (socket number)
See also:
bind

connect

closesocket

#define SOCKET_TYPE_DATAGRAM   0
 

Argument to function socket to create a UDP socket (same as SOCK_DGRAM)

See also:
socket

#define SOCKET_TYPE_STREAM   1
 

Argument to function socket to create a TCP socket (same as SOCK_STREAM)

See also:
socket

#define TCP_NODELAY   0
 

Argument for socket option. Enables/disables Nagle algorithm.

See also:
getsockopt

setsockopt


Function Documentation

int acceptqueue int    socket_handle,
struct sockaddr   address
 

Returns the number of sockets in the wait queue for this listening socket.

Returns the number of sockets in the queue attempting to connect to this server socket.

Parameters:
socket_handle handle to socket to check for waiting connections
address location where the IP and port number will be written
Returns:
-1 if the socket is not a streaming socket set up to listen 0 or greater for the number of sockets waiting
The IP and port of the socket are returned in address.

void clear_param_buffers void   
 

Clears the parameter buffers used by the socket library.

Clears buffers used to store parameters for the socket library. This function should be called immediately after calling the init_rom function, and before any socket library functions are called.

See also:
init_rom

void eth_disablemulticastreceiver void   
 

Disable multicast hardware receiver.

This function disables the "pass multicast" (PM) bit in the DS80C400 MAC control register. This improves performance if the application doesn't use multicast. This function must be called after initialization of the Ethernet. WARNING: IPv6 requires multicast. Disabling the receiver disables IPv6 address resolution.

unsigned int eth_readmii unsigned int    phy,
unsigned int    reg
 

Read a PHY register via MII.

This function reads a PHY register via the MII interface. See the IEEE 802.3 specification (22.2.4) for a description of the MII management register set.

Parameters:
phy PHY address (0 to 31)
reg register address (0 to 31, 16 through 31 are vendor specific)
Returns:
value read from the register specified

void eth_writemii unsigned int    phy,
unsigned int    reg,
unsigned int    val
 

Write a PHY register via MII.

This function writes a PHY register via the MII interface. See the IEEE 802.3 specification (22.2.4) for a description of the MII management register set.

Parameters:
phy PHY address (0 to 31)
reg register address (0 to 31, 16 through 31 are vendor specific)
val value to write to the specified register

unsigned long inet_addr char *    inet_string
 

Converts a string representing an IPv4 address to numeric form.

Converts the input string into an IPv4 address suitable for setting in a sockaddr_in structure.

Parameters:
inet_string IPv4 address in string form
Returns:
Numberic IPv4 address
See also:
sockaddr_in

char* inet_ntop int    family,
void *    addr,
char *    strptr,
size_t    len
 

Converts a numeric address to a string.

Converts a numeric IP address to a presentable format as a null terminated string. IPv4 addresses are formatted such as in "192.0.1.1". IPv6 addresses are formatted such as in "b803:8a11:0000:2121:fec5:0601:aa01:0102". Note that the '::' shortcut is not supported--a '0000' must be fully specified.

Parameters:
family AF_INET or AF_INET6
addr pointer to numeric representation of IP address
strptr storage location for presentation string
len size of storage area for strptr
Returns:
Reference to strptr, or NULL if the family is not recognized or if there is not enough space as declared by len
See also:
inet_pton

unsigned int inet_pton int    family,
char *    str,
void *    addr
 

Converts a string to a numeric IP address.

Converts a string represenation of an IP address into numeric format. IPv4 addresses are expected to be input in a format such as in "192.0.1.1". IPv6 addresses are expected to be formatted such as in "b8:03:8a:11:00:00:21:21:fe:c5:06:01:aa:01:01:02".

Parameters:
family AF_INET or AF_INET6
str address string to translate
addr pointer to storage for numeric representation of IP address
Returns:
1 for successful translation. 0 if the format was invalid, or the family was not recognized.
See also:
inet_ntop

long ping struct sockaddr   address,
unsigned int    address_length,
unsigned int    time_to_live,
struct pingdata *    response
 

Pings the specified address.

Sends an ICMP echo request (ping) to a specified address. Note that this function is NOT safe to be called from multiple processes at the same time.

Parameters:
address IP address to send an ICMP echo request to
address_length the length of the address structure (ignored)
time_to_live packets send by ping have this "time to live" setting
response data structure to fill in returned data (this argument must not be NULL)
Returns:
response time in milliseconds (0 means less than 1ms), or -1L for failure
The ping return data structure is defined as follows: reserved - Reserved field ip_header - The IP header of the return packet icmp_header - The ICMP header of the return packet icmp_data - The ICMP data portion of the return packet (should be 0x20,0x21,0x22,...,0x3f)

int syn_accept int    socket_num,
struct sockaddr   address
 

Accepts TCP connections on the specified socket.

Accepts a TCP conection on the specified socket. This function moves the first pending connection request from the listen queue into the established state, assigning a new local socket to the connection for communication. accept blocks if there are no pending incoming requests. The socket socket_num must have been created with type SOCKET_TYPE_STREAM, bound to an address using bind, and given a listen queue by calling listen.

Parameters:
socket_num the handle of the socket that will wait for connections
address location to write remote address
Returns:
New socket handle for communicating with remote socket, or -1 for failure
See also:
socket

bind

listen

int syn_arp_cacherequest struct sockaddr   address
 

Generate an ARP request for a given IPv4 address and add to the ARP cache.

If the given IP address is not in the ARP cache, generate an ARP request and add it to the cache.

Parameters:
address structure to store the address
Returns:
0 for success, non-zero for failure

int syn_arp_generaterequest struct sockaddr   address
 

Generate an ARP request for a given IPv4 address.

Unconditionally generate an ARP request for a given IPv4 address. This functionality can be used to implement Zeroconf protocols.

Parameters:
address structure to store the address
Returns:
0 for success, non-zero for failure

int syn_avail int    socket_num
 

Reports number of bytes available on a TCP socket.

Reports the number of bytes available on a TCP socket. This is the number of bytes that can currently be read using the recv function without blocking.

Parameters:
socket_num the handle of the socket to check for available data
Returns:
The number of bytes available for a recv function call on this socket, or -1 on failure.
See also:
recv

int syn_bind int    socket_num,
struct sockaddr   address
 

Binds a socket to a specified address.

Assigns a local address and port (stored in the address parameter) to a socket. Binding a socket is necessary for server sockets. For client sockets, use bind if a specific source port is desirable.

Fill address with 0's (for sin_addr and sin_port) to bind to any available local port. Use getsockname to discover which port the socket was bound to.

NOTE: When binding a UDP socket, matching inbound UDP packets will be queued up for the socket. Call recvfrom periodically to avoid the risk of running out of kernel memory.

Parameters:
socket_num socket handle to bind to a local port number
address contains the local address (including port number)
Returns:
0 for success, non-zero for failure.
See also:
listen

getsockname

recvfrom

int syn_cleanup unsigned int    process_id
 

Close all sockets associated with a task.

Close all sockets associtaed with a process ID. User applications should call this function whenever a task dies or is killed to ensure all associated resources are freed by the socket layer.

Warning:
The DS80C400 Silicon Software task scheduler does NOT call this function. User applications should call cleanup after each call to task_kill.
Parameters:
process_id Task PID to clean up sockets associated with
Returns:
0 for success, non-zero for failure.

int syn_closesocket int    socket_num
 

Closes a specific socket.

Closes the specified socket that was created using the socket function.

Parameters:
socket_num the socket handle to close
Returns:
0 for success, non-zero for failure.
See also:
socket

int syn_connect int    socket_num,
struct sockaddr   address
 

Connects a TCP socket to a specified address.

Connects to a specified address with a streaming socket. This function can only be used once with each socket. The socket socket_num must have been created with type SOCKET_TYPE_STREAM.

Parameters:
socket_num the socket handle to use to wait for and read a UDP packet
address IP address and port number to create a streaming connection to
Returns:
0 for success, non-zero for failure.
See also:
socket

unsigned int syn_getethernetstatus void   
 

Get the ethernet status.

Returns the ethernet status byte. This is a bit-wise OR of the following flags:
Flag Value Description
ETH_STATUS_LINK 01h Ethernet link status

Currently, no other flags are defined.

Returns:
Bitmapped ethernet status byte.

int syn_getipv6params void *    param_buffer
 

Get the IPv6 address.

Gets the IPv6 address of the ethernet interface. The format for the buffer after this function returns is:
Parameter Offset Length Description
IP6ADDR 0 16 IP address
IP6PREFIX 16 1 IP prefix length

Parameters:
param_buffer pointer to buffer to store IPv6 configuration data
Returns:
0 for success, non-zero for failure
See also:
getnetworkparams

setnetworkparams

unsigned char* syn_getmacid void   
 

Get the pointer to the MAC ID storage area.

Returns the pointer to the MAC ID storage area. This area will store the MAC ID after a successful call to setmacid.

Returns:
Pointer to the 400's MAC ID (6 bytes stored at this location)
See also:
setmacid

int syn_getnetworkparams void *    param_buffer
 

Get the IPv4 configuration parameters.

Get the IPv4 configuration parameters, including IP address, subnet mask, and gateway. The parameters are returned in a buffer in the following form:
Parameter Offset Length Description
(zero) 0 12 Must be 0
IP4ADDR 12 4 IP address
IP4SUBNET 16 4 Subnet mask
IP4PREFIX 20 1 Number of 1 bits in subnet mask
(zero) 21 12 Must be 0
IP4GATEWAY 33 4 Gateway IP address

IPv6 addresses are autoconfigured. To retrieve the IPv6 address, use the getipv6params function.

Parameters:
param_buffer pointer to buffer to store IP configuration data
Returns:
0 for success, non-zero for failure
See also:
setnetworkparams

getipv6params

int syn_getpeername int    socket_num,
struct sockaddr   address
 

Gets the remote address of a connection-based (TCP socket).

Stores the IP address of the remote socket communicating with the socket specified by socket_num. Use getsockname to get the local port's information.

Parameters:
socket_num handle of the socket to get remote IP and port for
address structure where IP and port will be stored
Returns:
0 for success, non-zero for failure
See also:
getsockname

int syn_getsockname int    socket_num,
struct sockaddr   address
 

Gets the local IP and port of a socket.

Stores the local IP and port number of the specified socket in the the address parameter. Use getpeername to get the remote port's information for a connection-based (TCP) socket.

Parameters:
socket_num handle of the socket to get local IP and port for
address structure where IP and port will be stored
Returns:
0 for success, non-zero for failure
See also:
getpeername

int syn_getsockopt int    socket_num,
unsigned int    name,
void *    buffer
 

Get various socket options.

Reads a number of supported socket options. Data written into the buffer depends on the requested socket option.

Name Description Data in buffer
TCP_NODELAY TCP Nagle Enable 1 byte
SO_LINGER Ignored N/A
SO_TIMEOUT Inactivity timeout 4 bytes (milliseconds, MSB first)
SO_BINDADDR Local socket IP 16 bytes

This function assumes there is enough room in buffer to store the requested data.

Parameters:
socket_num socket to get option information for
name option to get
buffer location where option data will be written
Returns:
0 for success, non-zero for failure
See also:
setsockopt

int syn_gettftpserver struct sockaddr   address
 

Get the address of the TFTP server.

Returns the address of the server accessed by the TFTP functions. To communicate with a TFTP server, use the functions listed in rom400_tftp.h, the TFTP library.

Parameters:
address structure to store the address of the TFTP server
Returns:
0 for success, non-zero for failure
See also:
settftpserver

int syn_join int    socket_num,
struct sockaddr   address
 

Adds a socket to a specified multicast group.

Adds a UDP socket to a specified multicast group. In order to receive multicasts from a group, first bind the socket to the port number that the multicast group is using (it is not sufficient to include it here in order to receive).

Use the leave function to leave a multicast group.

Warning:
IPv6 multicasting is not supported
Parameters:
socket_num handle for the datagram socket that will join a multicast group
address IP address of the multicast group to join
Returns:
0 for success, non-zero for failure.
See also:
leave

int syn_leave int    socket_num,
struct sockaddr   address
 

Removes a socket from the specified multicast group.

Removes a UDP socket from the specified multicast group.

Parameters:
socket_num handle for the datagram socket that will leave a multicast group
address IP address of the multicast group to leave
Returns:
0 for success, non-zero for failure.
See also:
join

int syn_listen int    socket_num,
unsigned int    backlog
 

Tells a socket to listen for incoming connections.

Tells the socket to listen for connections. A queue of length backlog is created for pending (un-accepted connections). It is required to use bind to assign a local port before calling listen. Use accept to move an incoming request to an established state, or wait for incoming connections.

Parameters:
socket_num socket handle that will listen for connections
backlog the maximum number of pending connections (max 16 for the DS80C400)
Returns:
0 for success, non-zero for failure.
See also:
bind

accept

int syn_recv int    socket_num,
unsigned int    length,
void *    buffer
 

Reads data from a TCP socket.

Reads data from a TCP socket. If there is no data available, recv blocks until there is data, subject to the value of SO_TIMEOUT. NOTE: This function reads up to length bytes. Call this function repeatedly if you need to read a minimum number of bytes.

Parameters:
socket_num handle of the streaming socket that will read data
length maximum amount of data to read
buffer location to write any data read
Returns:
The number of bytes read. If the operation times out according to the SO_TIMEOUT, a value of -2 is returned. If another error occurs, -1 is returned. If the socket was closed by the other side, 0 is returned.
See also:
connect

send

int syn_recvfrom int    socket_num,
unsigned int    length,
void *    buffer
 

Receive a UDP datagram.

Receives a message on the specified socket, and stores the address that sent it in the address structure set by an earlier call to syn_setDatagramAddress. If no data is available, syn_recvfrom blocks subject to the SO_TIMEOUT value. The socket socket_num must have been created with a type SOCKET_TYPE_DATAGRAM. It is required to use syn_bind to assign a local port to the socket, before receiving data. NOTE: This function reads up to length bytes of a datagram. Any data not read in the datagram will be discarded.

Parameters:
socket_num the socket handle to use to wait for and read a UDP packet
length the maximum number of bytes to read from a datagram socket
buffer the location to write any data read from the datagram socket
Returns:
The number of bytes read. If the operation times out according to the SO_TIMEOUT, a value of -2 is returned. If another error occurs, -1 is returned.
See also:
syn_sendto

syn_socket

syn_bind

int syn_send int    socket_num,
unsigned int    length,
void *    buffer
 

Sends data to a TCP socket.

Writes data to a TCP socket. The return value of this function is only a local success/failure code, and may not necessarily detect transmission errors.

Parameters:
socket_num handle of the streaming socket that will write data
length number of bytes to write
buffer location of data to write
Returns:
0 for success, non-zero for failure.
See also:
connect

recv

int syn_sendto int    socket_num,
unsigned int    length,
void *    buffer
 

Sends a UDP datagram to an address earlier specified by a call to syn_setDatagramAddress.

Sends a UDP datagram to an address earlier specified by a call to syn_setDatagramAddress. The success/failure code this function returns says nothing of if the packet was recieved by the target, only that the socket layer was able to push the data out. The socket socket_num must have been created with a type SOCKET_TYPE_DATAGRAM.

Parameters:
socket_num the socket handle to use to send a UDP packet
length the number of bytes to send in the datagram packet
buffer the data to send in the datagram packet
Returns:
0 for success, non-zero for failure.
See also:
syn_recvfrom

syn_socket

syn_setDatagramAddress

int syn_setDatagramAddress int    socket_num,
unsigned char    sending,
struct sockaddr   addr
 

Set the IP address parameter for future datagram calls.

In order to keep the functions in this library multi-process-safe, datagram functions syn_sendto and syn_recvfrom cannot have as many parameters as their traditional counterparts. This function sets the pointer to the address structure that will be used as the address parameter for functions syn_sendto and syn_recvfrom.

Note that the Berkeley style API is now supported and is multi-process safe.

Parameters:
socket_num Socket number to set address for
sending Set to 0 if this is an address for receiving, Set to 1 if this is an address for sending
addr Address structure that will be used in future calls to syn_sendto or syn_recvfrom.
Returns:
socket_num (for Macro purposes)
See also:
syn_sendto

syn_recvfrom

void syn_setmacid void   
 

Stores the MAC ID into the MAC ID storage area.

This is a redirected function. The DS80C400's default implementation of this function searches the 1-Wire for a DS2502U-E48 1-Wire chip which contains a MAC ID. This MAC ID is then stored into the MAC ID storage area, the location of which is stored in a pointer in the export table. Use the getmacid function to return a pointer to the MAC ID storage area.

See also:
getmacid

int syn_setnetworkparams void *    param_buffer
 

Set the IPv4 configuration parameters.

Set the IPv4 configuration parameters, including IP address, subnet mask, and gateway. Input parameters should be formatted in the following form:
Parameter Offset Length Description
(zero) 0 12 Must be 0
IP4ADDR 12 4 IP address
IP4SUBNET 16 4 Subnet mask
IP4PREFIX 20 1 Number of 1 bits in subnet mask
(zero) 21 12 Must be 0
IP4GATEWAY 33 4 Gateway IP address

Use this method to give the DS80C400 a static IP address. To dynamically configure an IP address, use methods from the DHCP library in rom400_dhcp.h (IP addresses leased by the DHCP client can still be retrieved by calling getnetworkparams).

IPv6 addresses are autoconfigured. To retrieve the IPv6 address, use the getipv6params function.

Parameters:
param_buffer pointer to buffer with IP configuration data
Returns:
0 for success, non-zero for failure
See also:
getnetworkparams

getipv6params

int syn_setsockopt int    socket_num,
unsigned int    name,
void *    buffer
 

Set various socket options.

Sets a number of supported socket options. Input data in the buffer depends on the desired socket option.

Name Description Data in buffer
TCP_NODELAY TCP Nagle Enable 1 byte
SO_LINGER Ignored N/A
SO_TIMEOUT Inactivity timeout 4 bytes (milliseconds, MSB first)
SO_BINDADDR Read only N/A

Parameters:
socket_num socket to set option information for
name option to set
buffer location of option data that will be written
Returns:
0 for success, non-zero for failure
See also:
getsockopt

int syn_settftpserver struct sockaddr   address
 

Set the address of the TFTP server.

Set the address of the server that the TFTP functions will use. The settftpserver function must be used if the address of the TFTP server is not acquired by DHCP or 1-Wire. Once the TFTP server's address is set, use the functions listed in rom400_tftp.h to begin receiving files.

Parameters:
address structure to store the address of the TFTP server
Returns:
0 for success, non-zero for failure
See also:
gettftpserver

int syn_socket unsigned int    type
 

Create a network socket for TCP or UDP communication.

Creates a socket for network communication. This function returns a socket handle, but has not specific local address assigned to it. Note that this function calls task_gettaskid through the function redirect table.

Parameters:
type SOCKET_TYPE_DATAGRAM or SOCK_DGRAM for UDP, SOCKET_TYPE_STREAM or SOCK_STREAM for TCP
Returns:
-1 for failure, or the socket handle (socket number)
See also:
bind

connect

closesocket

unsigned int syn_version void   
 

Returns the version number of this socket library.

Returns:
Version number of this SOCK library.

int udpavailable int    socket_handle,
struct sockaddr   address
 

Returns whether or not data is available to be read on a datagram socket.

Returns 1 if there is data available to be read on a UDP socket.

Parameters:
socket_handle handle to socket to check for available datagrams
address location where the IP and port number will be written
Returns:
-1 if the socket is not a datagram socket 0 if no datagram packets are available 1 if a datagram is available
The IP and port of the socket are returned in address.


Copyright 2004 Dallas Semiconductor, Inc.. Documentation generated by Doxygen.