Dallas Semiconductor DS80C400 C Libraries Home Page

Main Page | Modules | Data Structures | Directories | 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  sockaddr
struct  in_addr
struct  in6_addr
struct  sockaddr_in
struct  pingdata

Defines

#define ROM400_SOCK_VERSION   12
#define ROM400_SOCK_SYNCH_VERSION   ROM400_SOCK_VERSION
#define SOCKET_TYPE_DATAGRAM   0
#define SOCKET_TYPE_STREAM   1
#define SOCK_DGRAM   SOCKET_TYPE_DATAGRAM
#define SOCK_STREAM   SOCKET_TYPE_STREAM
#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 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 syn_listen(socket_num, backlog)   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 syn_cleanup(process_id)   cleanup((process_id))
 Close all sockets and free the parameter buffer associated with a task.
#define syn_avail(socket_num)   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 syn_getnetworkparams(param_buffer)   getnetworkparams((param_buffer))
 Get the IPv4 configuration parameters.
#define syn_setnetworkparams(param_buffer)   setnetworkparams((param_buffer))
 Set the IPv4 configuration parameters.
#define syn_getipv6params(param_buffer)   getipv6params((param_buffer))
 Get the IPv6 address.
#define syn_getethernetstatus()   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 syn_version()   sock_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.
#define syn_closesocket(socket_num)   closesocket((socket_num))
 Closes a specific socket.
#define syn_getmacid()   getmacid()
 Get the pointer to the MAC ID storage area.
#define syn_setmacid()   setmacid()
 Stores the MAC ID into the MAC ID storage area.

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_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 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 cleanup (unsigned int process_id)
 Close all sockets and free the parameter buffer associated with a task.
int 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 getnetworkparams (void *param_buffer)
 Get the IPv4 configuration parameters.
int setnetworkparams (void *param_buffer)
 Set the IPv4 configuration parameters.
int getipv6params (void *param_buffer)
 Get the IPv6 address.
unsigned int 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.
void clear_param_buffers (void)
 Clears the parameter buffers used by the socket library.
unsigned int sock_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.
int closesocket (int socket_num)
 Closes a specific socket.
unsigned char * getmacid (void)
 Get the pointer to the MAC ID storage area.
void setmacid (void)
 Stores the MAC ID into the MAC ID storage area.
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.
int unbind (int socket_num)
 Unbind a bound socket.
int setsockowner (int socket_num, unsigned int process_id)
 Sets the socket's owner to a different task ID.
unsigned long eth_readcsr (unsigned int reg)
 Read a MAC CSR register.
void eth_writecsr (unsigned int reg, unsigned long val)
 Write a MAC CSR register.


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 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 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 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 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   ROM400_SOCK_VERSION
 

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

See also:
syn_version

#define ROM400_SOCK_VERSION   12
 

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 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   SOCKET_TYPE_DATAGRAM
 

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

See also:
socket

#define SOCK_STREAM   SOCKET_TYPE_STREAM
 

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

See also:
socket

#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 syn_avail socket_num   )     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 syn_cleanup process_id   )     cleanup((process_id))
 

Close all sockets and free the parameter buffer associated with a task.

Close all sockets associated with a process ID and free the parameter buffer.

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, 0 for current process.
Returns:
0 for success, non-zero for failure.

#define syn_closesocket socket_num   )     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 syn_getethernetstatus  )     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 syn_getipv6params param_buffer   )     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 syn_getmacid  )     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 syn_getnetworkparams param_buffer   )     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 syn_listen socket_num,
backlog   )     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 syn_setmacid  )     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 syn_setnetworkparams param_buffer   )     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 syn_version  )     sock_version()
 

Returns the version number of this socket library.

Returns:
Version number of this SOCK library.

#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.

int 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 cleanup unsigned int  process_id  ) 
 

Close all sockets and free the parameter buffer associated with a task.

Close all sockets associated with a process ID and free the parameter buffer.

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, 0 for current process.
Returns:
0 for success, non-zero for failure.
See also:
setsockowner

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

int 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

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 long eth_readcsr unsigned int  reg  ) 
 

Read a MAC CSR register.

This function reads a MAC CSR register from the DS80C400. See the data sheet and user's guide for more information about the CSR registers.

Parameters:
reg register address (0 to 0x2c in steaps of 4)
Returns:
value read from the register specified
See also:
eth_writecsr

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_writecsr unsigned int  reg,
unsigned long  val
 

Write a MAC CSR register.

This function writes a MAC CSR register. See the DS80C400 data sheet and user's guide for more information about the CSR registers.

Parameters:
reg register address (0 to 0x2c in steaps of 4)
val value to write to the specified register
See also:
eth_readcsr

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 int 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 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* 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 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

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

int 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

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)

void 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 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 setsockowner int  socket_num,
unsigned int  process_id
 

Sets the socket's owner to a different task ID.

Sets the socket owner to a different task ID. This is useful where program code relies on cleanup to deallocate a process' resources, or in cases where ownership of a socket needs to be moved to a child process. Note that the new process ID is not checked for validity and it is possible to assign a socket to a non-existent task.

Parameters:
socket_num socket handle
process_id the task PID of the new socket owner
Returns:
0 for success, non-zero for failure.
See also:
cleanup

unsigned int sock_version void   ) 
 

Returns the version number of this socket library.

Returns:
Version number of this SOCK library.

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_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

unbind

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

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_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:
sendto

socket

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:
recvfrom

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, so user software should never have to call this function.

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

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

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.

int unbind int  socket_num  ) 
 

Unbind a bound socket.

Removes a local address and port from a socket that was assigned to it using bind.

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


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