Home

Dynamic C TCP/IP User`s Manual Volume I

1. _PRIMARY STATIC IP 10 10 6 100 PRIMARY NETMASK MEE ee EE MY GATEWAY LOs AO ti MY NAMESERVER ROMEO OS IE WIFI USE WPA FC WIFI SSID rabbitTest FC WIFI ROAM ENABLE 1 FC WIFI ROAM BEACON MISS 20 FC WIFI MODE IFPARAM WIFI INFRASTRUCTURE FC WIFI REGION IFPARAM WIFI REGION AMERICAS FC WIFI ENCRYPTION IFPARAM WIFI ENCR TKIP 1 In general usage the term WPA encryption sometimes refers to WPA using TKIP 20 rabbit com TCP IP Initialization To specify a WPA passphrase or Pre Shared Key FC WIFI WPA PSK PASSPHRASE myPassphrase To specify the WPA Pre Shared Key itself FC WIFI WPA PSK HEXSTR 1122334455667788990011223344556677889900112233445566778899001122 2 4 1 5 Infrastructure WPA2 CCMP Encryption Configuration Pre Shared Key WPA2 is a more secure replacement for WEP This implementation uses the Advanced Encryption Standard AES based algorithm also known as CCMP Counter Mode with Cipher Block Chaining Message Authentication Code Protocol cipher suite The Rabbit Wi Fi driver supports CCMP WPA2 encryption with Pre Shared Keys PSK These keys can be specified as a 256 bit key or as a passphrase that is expanded into a key
2. define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define PRIMARY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 define MY NAMESERVER 10 10 6 1 define WIFI USE WPA define IFC WIFI SSID rabbitTest define IFC WIFI ROAM ENABLE 1 define IFC WIFI ROAM BEACON MISS 20 define IFC WIFI MODE IFPARAM WIFI INFRASTRUCTURE define IFC WIFI REGION IFPARAM WIFI REGION AMERICAS define IFC WIFI ENCRYPTION IFPARAM WIFI ENCR TKIP You will also need to define WPA s pre shared key mode This can be done by specifying a passphrase that the driver will expand to a 256 bit key or by specifying the 256 bit key itself Note that expanding a passphrase takes a significant amount of time at startup up to about 20 seconds Define WIFI VERBOSE PASSPHRASE to see status messages when the key is generated from the passphrase To specify the WPA passphrase you will need something like the following define IFC WIFI WPA PSK PASSPHRASE myPassphrase To specify the WPA Pre Shared Key itself use the following define IFC WIFI WPA PSK HEXSTR 1122334455667788990011223344556677889900112233445566778899001122 Alternatively you can configure within the Defines window TCPCONFIG 1
3. 3 2 2 1 User Supplied Buffers Starting with Dynamic C version 7 05 a user can associate his own buffer with a TCP or UDP socket The memory for the buffer must be allocated by the user This can be done with xalloc which returns a pointer to the buffer This buffer will be tied to a socket by a call to an extended open function tcp extlisten tcp extopen or udp_extopen Each function requires a long pointer to the buffer and its length be passed as parameters 3 3 Opening TCP Sockets There are two ways to open a TCP socket passive and active Passive open means that the socket is made available for connections originated from another host This type of open is commonly used for Internet servers that listen on a well known port like 80 for HTTP Hypertext Transfer Protocol servers Active open is used when the controller board is establishing a connection with another host which is hopefully listening on the specified port This is typically used when the controller board is to be a client for some other server The distinction between passive and active open is lost as soon as the connection is fully established When the connection is established both hosts operate on a peer to peer basis The distinction between who is client and who is server is entirely up to the application TCP itself does not make a distinction 3 3 1 Pass
4. PRIMARY STATIC IP 10 10 6 100 PRIMARY NETMASK 255 255 255 0 MY GATEWAY 10 10 6 1 MY NAMESERVER 10 10 6 1 FC WIFI SSID rabbitTest FC WIFI ROAM ENABLE 1 FC WIFI ROAM BEACON MISS 20 FC WIFI MODE IFPARAM WIFI INFRASTRUCTURE FC WIFI REGION IFPARAM WIFI REGION AMERICAS FC WIFI ENCRYPTION IFPARAM WIFI ENCR NONE TCP IP Manual Vol 1 rabbit com 17 2 4 1 2 Ad hoc Open No Encryption Configuration Another simple way to configure a Wi Fi network interface is to use an open configuration in ad hoc mode An ad hoc Wi Fi network does not require an access point or Wi Fi router to operate Instead the Wi Fi devices communicate directly with each other This is useful for an isolated Wi Fi network but it is not typically used when devices need to communicate outside of their own network Note that all Wi Fi devices on an ad hoc network need to match these settings in particular the SSID and the channel number must be the same To configure within your program copy and paste the following into your sample program and modify as necessary define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define
5. ATH NOENTRIES insufficient space in either the router or ARP cache tables LIBRARY ARP LIB 180 rabbit com TCP IP Manual Vol 1 router del all void router del all void DESCRIPTION Delete all router table entries This will make any host that is not on the local subnet inaccessi ble This function is usually called in preparation for adding a new router entry LIBRARY ARP LIB router delete ATHandle router delete longword ipaddr DESCRIPTION Delete a router from the router table All instances of the router s IP address are deleted and the ARP cache table entry is flushed PARAMETER ipaddr IP address of the router This address should be on the local subnet since non local routers are not supported RETURN VALUE Positive value completed successfully ATH NOTFOUND specified entry did not exist LIBRARY ARP LIB TCP IP Manual Vol 1 rabbit com 181 router f or ATHandle router for longword ipaddr byte router used byte r iface DESCRIPTION Return the ARP cache table entry corresponding to the router that handles the given IP address If there is a pre configured router for the given address it is selected Otherwise routers discov ered via DHCP or ICMP router discovery are searched with the highest preference being se lected Failing this if there is a point to point interface this is selected as the default An alternative mode of calling this function is invoke
6. TCP IP Manual Vol 1 rabbit com 149 ifup cont d PARAMETER iface Interface number Use one of the definitions e IF DEFAULT e IF ETHO e IF ETHI e IF WIFIO e I F PPPOEO e IF PPPOEL e IF PPPO 5 If the interface does not exist then you will get a compile time error F DEFAULT refers to the default interface which will be equivalent to the first of the other interface identifiers in the above list which exists RETURN VALUE IFCTL OK ifOK IFCTL FAIL if error IFCTL PEND if OK but not complete LIBRARY NET LIB SEE ALSO ifconfig ifdown ifstatus 150 rabbit com TCP IP Manual Vol 1 ine t_addr longword inet_addr char dotted ip string DESCRIPTION Converts an IP address from dotted decimal IP format to its binary representation No check is made as to the validity of the address PARAMETERS dotted ip string Dotted decimal IP string e g 10 10 6 100 RETURN VALUE 0 Failure Binary representation of dotted ip string Success LIBRARY IP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO inet ntoa TCP IP Manual Vol 1 rabbit com 151 inet ntoa char tinet ntoa char s longword ip DESCRIPTION Converts a binary IP address to its dotted decimal format e g inet ntoa s 0x0a0a0664 returns a pointer to 10 10 6 100 PARAMETERS s Location to place the dotted decimal string A suff
7. TCP IP Manual Vol 1 rabbit com 223 sock recv int sock_recv sock_type s char buffer int len DESCRIPTION After a UDP socket is initialized with udp open and sock recv_init sock recv scans the buffers for any datagram received by that socket This function is not available starting with Dynamic C 7 05 see Section 3 5 PARAMETERS s Pointer to a UDP socket buffer Buffer to put datagram maxlength Length of buffer RETURN VALUE gt 0 Length of datagram 0 No datagram found 1 Receive buffer not initialized with sock recv init LIBRARY DCRTCP LIB SEE ALSO sock recy from sock recy init 224 rabbit com TCP IP Manual Vol 1 EXAMPLE USING SOCK_RECV Old way of setting network addresses are commented out define MY IP ADDRESS 10 10 6 100 define MY NETMASK 255 255 255 0 New way of setting network addresses define TCPCONFIG 1 memmap xmem fuse ser sep lib define SAMPLE 401 udp Socket data Chaz joilojowit SLP g main word templen char spare 1500 soek mi if lude open amp data SAMPLE O0xffffttft SAMPLE NULL puts Could not open broadcast socket exit 3 set large buffer mode lir SOCK recy imie Sdaca loigisux sizeof bigisux i puts Could not enable large buffers exit 3 sock mode amp data UDP MODE NOCHK turn off checksums while 1 Cep tick NOLL De ir templen seck r
8. IFS NAMESERVER SET aton 192 68 1 123 IFS NAMESERVER ADD aton 192 68 1 124 IFS_UP FS END This call to ifconfig brings the first Ethernet interface down if it is not already inactive then it configures the home IP address netmask router gateway and two nameservers Then the interface is made active IFS UP IFS END isreguired to terminate the parameter list Debugging note if you experience an error dialog indicating bad parameter passed to I O func tion this is often caused by this function encountering a bad parameter In this case it is easier to debug if you temporarily define NET_VERBOSE at the top of your application code This will cause this function to print some more details about the parameter that it found to be in er ror The parameter numbers refer to IFS IFG parameter identifiers not to the sub parameters of the identifiers In the above example IFS_DOWN would be considered the first parameter and IFS_UP would be the 7th not the 12th Most errors are caused by e passing an int when a long is expected so be sure to add the appropriate cast in your code e forgetting to terminate the parameter list with IFS END g g p li TCP IP Manual Vol 1 rabbit com 123 ifconfig cont d PARAMETERS iface Interface number Use one of the definitions e IF DEFAULT e IF ETHO e IF ETHI e IF WIFIO e IF PPPOEO e IF PPPOEL
9. Nevertheless there are some useful debugging functions included in ARP LIB Starting with Dynamic C 7 20 the internal ARP processing was converted to non blocking style This has no direct impact on applications except that there will be lower maximum latency in tcp_tick calls The ARP functions are all named starting with arp arpcache arpresolve or router router printall isauseful function for debugging router table problems for example in the case where connections to hosts which are not on local subnets appear to be failing 5 2 Configuration Macros for ARP ARP_LONG EXPIRY Number of seconds that a normal entry stays current Defaults to 1200 ARP_SHORT_EXPIRY Number of seconds that a volatile entry stays current Defaults to 300 ARP_PURGE_TIME Number of seconds until a flushed entry is actually deleted Defaults to 7200 TCP IP Manual Vol 1 rabbit com 77 ARP_PERSISTENCE Number of retries allowed for an active ARP resolve request to come to fruition Default s to 4 If no response is received after this many requests then the host is assumed to be dead Set to a number between 0 and 7 This number relates to the total time spent waiting for a response as follows timeout 2 ARP_PERSISTENCE 1 For example for 0 the time out is 1 second For 4 it is 31 seconds For 7 it is 255 seconds If you set this to 8 or higher then ARP will persist forever retrying at 128 second intervals ARP_NO_ANNOUNCE Con
10. PARAMETERS host string Pointer to text string to convert RETURN VALUE O Failure 10 The IP address host string resolves to LIBRARY DNS LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO _arp_ resolve inet addr inet ntoa TCP IP Manual Vol 1 rabbit com 175 resolve cancel int resolve cancel int handle DESCRIPTION Cancels the resolve request represented by the given handle If the handle is 0 then this function cancels all outstanding resolve requests PARAMETERS handle Handle that represents a DNS lookup process or 0 to cancel all outstanding resolve requests RETURN VALUE RESOLVE SUCCESS The resolve request has been cancelled and is no longer valid RESOLVE HANDLENOTVALID There is no request for the given handle RESOLVE NONAMESERVER No nameserver has been defined LIBRARY DNS LIB SEE ALSO resolve name start resolve name check resolv 176 rabbit com TCP IP Manual Vol 1 re solve n ame che ck int resolve name check int handle longword resolved ip DESCRIPTION Checks if the DNS lookup represented by the given handle has completed On success it fills in the resolved IP address in the space pointed to by resolved_ip PARAMETERS handle Handle that represents a DNS lookup process resolved ip A pointer to a user supplied 1ongword where the resolved IP address will be placed RETURN VALUE RESOLVE SUCCESS T
11. ttl Time To Live This is a value between 1 and 255 A value of zero is also accepted but will have undesirable consequences LIBRARY NET LIB SEE ALSO sock set tos 230 rabbit com TCP IP Manual Vol 1 sockstate char sockstate void s DESCRIPTION Returns a string that gives the current state for a socket PARAMETERS s Pointer to a socket RETURN VALUE An ASCII message which represents the current state of the socket These strings should not be modified Listen indicates a passively opened socket that is waiting for a connection SynSent and SynRcvd are connection phase intermediate states Established states that the connection is complete Wy EstClosing FinWaitl FinWait2 CloseWait Closing LastAck TimeWait and CloseMSL are connection termination intermediate states Closed indicates that the connection is completely closed UDP Socket is always returned for UDP sockets because they are stateless Not an active socket is a default value used when the socket is not recognized as UDP or TCP BAD more than one bit set LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock established sock datareadv EXAMPLE Gaz ez ifdef DEBUG if p sockstate s joint Socket state ds Ss Vat e YE endif DEBUG TCP IP Manual Vol 1 rabbit com 231 sock tbleft int sock tbleft void s DESCRIPTION Gets the num
12. TCP IP Manual Vol 1 rabbit com 89 For example SEscript ATDT5551212 CONNECT ogin Joe User word secret PPP The sequence is 1 Send ATDT5551212 dials up an ISP 2 Wait for the word CONNECT 3 An empty send string means don t send anything and wait for the next expect string 4 Wait for login or Login By leaving off the L either one will match 5 Send Joe User Note that this token is contained in single quotes because it contains a space 6 Wait for password or Password 7 Send the password 8 Wait for the sequence PPP This indicates a PPP session has started 7 6 4 1 Additional Rules for Send Expect Scripts e A carriage return character ASCII 13 is automatically sent after each send token e An ampersand amp at the start of an expect token indicates that the driver should wait indefinitely for that token to be received This is useful when waiting to answer a call e g to set the modem to answer and wait indefinitely for a connection ATSO 1 amp CONNECT e As mentioned above an empty token is immediately skipped This allows for a chain of expect tokens to be used e The macro PSS MODEM CONNECT WAIT determines the total time for the script If this is exceeded a timeout failure will occur and the interface will fail to come up Using the ampersand modifier resets this timeout Note that the IFS_PPP_
13. sethostid longword sethostid longword ip DESCRIPTION This function changes the system s current IP address Changing this address will disrupt exist ing TCP or UDP sessions You should close all sockets before calling this function Normally there is no need to call this function The macro MY IP ADDRESS defines an initial IP address for this host or you can define USE_DHCP to obtain a dynamically assigned address In either case it is not recommended to use this function to change the address PARAMETERS ip New IP address RETURN VALUE New IP address LIBRARY IP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO gethostid TCP IP Manual Vol 1 rabbit com 189 sethostname char sethostname char name DESCRIPTION Sets the host portion of our name PARAMETERS name Pointer to the new host name RETURN VALUE Pointer to internal hostname buffer on success NULL on error if hostname is too long LIBRARY BSDNAME LIB 190 rabbit com TCP IP Manual Vol 1 sock abort void sock_abort void s DESCRIPTION Close a connection immediately Under TCP this is done by sending a RST reset Under UDP there is no difference between sock close and sock abort PARAMETERS s Pointer to a socket RETURN VALUE None LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock close tcp_open TCP IP Manual Vol 1 rabbit com 191 sock a
14. ss see see se ee ee Re 205 sock flushnexXt esse sees see ee 206 SOCK Ui EE eta ei 207 SOCK RE EE EE 208 SOCK SfaCe EE ER as eA 209 SOCK ME si ao Nei eM EEN 210 sock init or ent 211 sock mode 212 sock ooflush ees sesse see see ee 214 SOCK 7 3 a 0 GR 215 sock preread ese sees ee ee 216 SOCK SPUL LE ENE RS EER ek Se hee 217 SOCK pute 218 Tere di zbleft EE EE N 219 SOCK TDSIZE si 220 sock rbused iese ee ee ee 221 sock read si EE 222 sock_readable ee ee ee 223 Tere di oe AE EE EE 224 sock recV Tom 226 sock frecv 101 227 sock resolved ninen 228 TCP IP User s Manual SOCK set E 229 sock sel EE 230 Sockstate ee Seege ed 231 sock left 232 Sock tbsize ER ORE EE N 233 sock tbused ebe ES es EE Eg ef 234 sock tel Es A Ee de 235 sock wait closed 236 sock wait established 0 237 sock waiting see ee Re ER ee EE 238 sock wait input esse ese see ek GR RE 239 sock writable sereset 240 SOCK WTI iii n kati 241 sock xfastread sse se RA Re ee Ee 242 sock xfastwrite ese se ee Re RE 243 EE 244 tep clearreserVe ee ee ee Re Ge 245 ep Eng ai ce gie ge Ee gee 246 tep extlisten 0 ee ee ee Re RR Ge 247 E e 248 tep keepalive ee ee Re Re RA GR 249 top ER EE EE OE EE N 250 e BCEE 252 TCP _TESCTVEPOTT 0 esse esse eretia 254 EP EUGK ES EE ETA 255 udp bypass ap 256 udp close i e EE Ee resect ese ge Eg 257 udp XtODEN ee ee ee Re RR RR 258 Udp open ie EERS
15. 10 10 6 100 PRIMARY NETMASK 255 255 255 0 MY GATEWAY ER EE te MY NAMESERVER 10 10 6 1 Another way to change the default configuration is to create a library called custom _ config lib In this library you can place your own custom configurations which will not be overwritten by Dynamic C since this is not a released library To create custom config lib you can use tcp config libasa template Modify the definitions to suit your network environment You must change the configuration numbers i e the value of TCPCONFIG to be greater than or equal to 100 Numbers less than 100 are expected to be in tcp config lib numbers over 99 cause custom config lib to be included If you are using a Dynamic C version prior to 9 30 then the other thing you must do before using your own custom configurations is to add the library name custom_config 1ib to the lib dir file in the base Dynamic C installation directory This is just a text file which you can edit with the Dynamic C text editor Locate the line that contains tcp_config lib Repeat this line and modify one of the line copies to point to your custom config lib file You will not have to restart Dynamic C for this change to take effect A new release of Dynamic C will overwrite the lib dir file so you will need to perform this edit for each release Starting with Dynamic C 9 30 lib dir references entire directories automatically so it is not necessary to edit it
16. N ET LIB SEE ALSO ip timer expired Pointer to a socket Number of seconds for the time out if seconds is zero never time out 156 rabbit com TCP IP Manual Vol 1 is valid iface int is valid iface int iface This function returns a boolean indicator of whether the given interface number is valid for the Interface number Use one of the definitions 0 DESCRIPTION configuration PARAMETER iface e IF ETHO e IF ETHI e IF WIF e IF PPPOEO S IF PPPOE e IF PPPO 5 RETURN VALUE 0 Interface is valid 0 Interface does not exist LIBRARY NET LIB SEE ALSO ifconfig ifup ifdown ifstatus TCP IP Manual Vol 1 rabbit com 157 void ModemClose void DESCRIPTION Closes the serial driver down LIBRARY MOD EM LIB ModemClose ModemConnected int ModemConnected void DESCRIPTION Returns true if the DCD line is asserted meaning the modem is connected to a remote carrier RETURN VALUE 1 DCD line is active 0 DCD inactive nothing connected LIBRARY MOD EM LIB 158 rabbit com TCP IP Manual Vol 1 ModemExpect int ModemExpect char send string unsigned long timeout DESCRIPTION Listens for a specific string to be sent by the modem PARAMETERS Send string A NULL terminated string to listen for timeout Maximum wait in milliseconds for a character RETURN VALUE 1 The expected string was
17. tion sock established To handle this case call sock_bytesready to deter mine if there is data to be read from the buffer Multiple calls to tcp_1listen to the same local port port are acceptable and consti tute the mechanism for supporting multiple incoming connections to the same local port Each time another host attempts to open a session on that particular port another one of the listens will be consumed until such time as all listens have become established sessions and subsequent remote host attempts will receive a reset PARAMETERS s Pointer to a socket lport Port to listen on the local port number remip IP address of the remote host to accept connections from or 0 for all port Port to accept connections from or 0 for all datahandler Function to call when data is received NULL for placing data in the sock et s receive buffer Prior to Dynamic C 7 30 some details for implementa tion of this service had not been finalized Insert a value of NULL if you are using a version of Dynamic C prior to 7 30 reserved Set to 0 for now This parameter is for compatibility and possible future use RETURN VALUE 0 Failure 1 Success LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tep extlisten 250 rabbit com TCP IP Manual Vol 1 EXAMPLE USING TCP_LISTEN Old way of setting network addresses is commented out define MY IP ADDRESS 10 10 6 100 define MY NETMASK 255 2
18. RABBIT Dynamic C TCP IP User s Manual Volume 1 019 0143 J The latest revision of this manual is available on the Rabbit Web site www rabbit com for free unregistered download TCP IP Manual Vol 1 rabbit com i Dynamic C TCP IP User s Manual Volume 1 Part Number 019 0143 e Printed in the U S A Digi International Inc 2007 2009 e All rights reserved Digi International Inc reserves the right to make changes and improvements to its products without providing notice Trademarks Rabbit and Dynamic C are registered trademarks of Digi International Inc Windows is a registered trademark of Microsoft Corporation rabbit com Table of Contents Introd NCHON EE 1 TCP IP Initialization see ee 3 2 1 TCP IP Stack Configuration see see see 3 2 1 1 Multiple Interface Support 3 2 1 2 Interface Selection Macros 5 2 1 2 1 Link Layer Drivers 6 2 1 3 Single Interface Support 7 2 1 3 1 Configuration Macros for Link Layer Driver Single Interface 7 2 1 4 TCP IP Stack Initialization y 2 2 Interface Configuration ees esse se ee ee ee 8 2 2 1 Configuration Overview 8 2 2 2 Sources of Configuration Information 9 2 2 2 1 Predefined Configurations 9 2 2 2 2 Static Configuration 10 2 2 2 3 Dynamic Configuration via the Network cs dein ee 11 2 2 2 4 Runtime Confi
19. Vol 1 rabbit com 27 available than what are listed here Please look at the beginning of the file Lib tcpip bootp lib for more information USE DHCP If this macro is defined the target uses BOOTP and or DHCP to configure the required parameters This macro must be defined to use DHCP services DHCP_CHECK If defined and USE_DHCP is defined then the target will check for the existence of another host already using an offered IP address using ARP If the host exists then the offer will be declined If this happened most DHCP servers would log a message to the administrator since it may represent a misconfiguration If not defined then the target will request the first offered address without checking DHCP CLASS ID Rabbit2000 TCPIP Rabbit Test 1 0 0 This macro defines a class identifier by which the OEM can identify the type of configuration parameters expected DHCP servers can use this information to direct the target to the appropriate configuration file The standard format hardware vendor product code firmware version is recommended DHCP CLIENT ID clientid char ptr DHCP CLIENT ID LEN clientid length Define a client identifier string Since the client ID can contain binary data the length of this string must be specified as well This string MUST be unique amongst all clients in an administrative domain thus in practice the client ID must be individually set for each client e g via front panel configuration It i
20. a buffer could not be allocated 10 Success LIBRARY UDP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO udp_extopen TCP IP Manual Vol 1 rabbit com 261 udp_peek int udp peek udp Socket s odp datagram info udi DESCRIPTION Look into the UDP socket receive buffer to see if there is a datagram ready to be read using udp recvfrom This function does not remove the datagram from the buffer but it allows the application to determine the full details about the next datagram including whether the da tagram was broadcast The returned data is put in udi udi must point to a valid data structure or be NULL The data structure is typedef struct longword remip Remote host IP address word remport Remote host port number int len Length of datagram byte flags Bit mask defined below byte iface Interface number udp datagram info The flags field may have one of the following values UDI ICMP ERROR This is an ICMP error entry UDI TOS MASK Type of service bit mask UDI BROADCAST LL Received on broadcast link layer address UDI BROADCAST IP Received on broadcast network IP address PARAMETERS s UDP socket to check udi Where to store the returned information RETURN VALUE 1 A normal datagram is in the receive buffer 0 No datagram waiting 3 ICMP error message in receive buffer will only be returned if udi is
21. a buffer could not be allocated LIBRARY UDP LIB SEE ALSO udp open sock resolved TCP IP Manual Vol 1 rabbit com 259 udp_open int udp_open udp Socket s word lport longword remip word port dataHandler t datahandler DESCRIPTION This function opens a UDP socket on the given local port 1port If the remote IP address is specified remi p then only UDP datagrams from that host will be accepted The remote end of the connection is specified by remip and port The following table explains the possible combinations and what they mean REMIP Effect of REMIP value The connection completes when the first datagram is received supplying both the remote IP address and the remote port number Only datagrams received from that IP port address will be accepted All remote hosts can send datagrams to the socket All outgoing datagrams will be sent to the broadcast address on the specified port The port parameter is ignored If the remote IP address is a valid IP address and the remote port 26 received supplying the remote port number point is 0 the connection will complete when the first datagram is If the remote IP address and the remote port are both specified when the function is called the connection is complete at that If the remote host is set to a particular address either host may initiate traffic Multiple calls to udp open with remip set to zero is a useful way o
22. connection between two peers on what is otherwise a broadcast 1 e any to any medium Nevertheless the existence of PPPoE was largely dictated by the needs of ISPs who wished to continue using their existing infrastructure based on the earlier generation of dial in connections The advent of high speed ADSL etc modems that had an Ethernet connection to the user s network made PPPoE an attractive proposition If your application requires connection to an ISP via an ADSL modem then you will most likely need to support PPPoE PPPoE also requires a physical layer negotiation to precede the normal PPP negotiations This is known as the access concentrator discovery phase discovery for short PPPoE makes a distinction between PPPoE servers and PPPoE clients however PPP makes no distinction you can think of PPP as also standing for Peer to Peer Protocol The PPPoE server is known as the access concentrator The Dynamic C TCP IP libraries do not support acting as the access concentrator only the PPPoE client mode is supported This is the most common case since the DSL modem is always configured as an access concentrator 2 6 Configuration Macro Reference This section arranges the configuration macros according to the function they perform 2 6 1 Removing Unnecessary Functions The following macros default to being undefined i e the functionality is included by default You can define one or more of these macros to fr
23. e IF PPPO 5 e IF ANY If the interface does not exist then you will get a compile time error F DEFAULT refers to the default interface which will be equivalent to the first of the other interface identifiers in the above list which exists IF ANY may be used only for the parameters which are not specific to any particular interface It can also be used where applicable to mean all in terfaces if the operation would make sense when applied to all interfaces Parameters 2 through n are polymorphic like printf parameters Parameters are provided in groups usually pairs with the first parameter in the group being one of a documented set of identifiers and any subse quent parameters in the group being the value specific to that identifier The data type for bool parameter really means an integer whose value is 0 for false or non zero for true PARAMETER IDENTIFIERS FOR IFCONFIG IFS_END Marks the end of the parameter list The list of parameter groups MUST be terminated using the identifier IFS END IFS_UP Bring up interface IFS DOWN Bring down interface 124 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFS IPADDR Set home IP address longword Setting the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface w
24. no check is performed Otherwise the ARP table entry is checked to see that it is the correct entry for the specified IP address RETURN VALUE Positive value Completed successfully The return value will be the same as the ath parameter ATH AGAIN Not yet completed try again later ATH FAILED Completed in error Address cannot be resolved because of a network config uration problem ATH TIMEDOUT Resolve timed out No response from addressee within the configured time limit ATH INVALID The ath parameter was not a valid handle ATH OBSOLETE The given handle was valid but obsoleted by a more recent entry Restart using arpresolve start ATH MISMATCH The ipaddr parameter was not zero and the IP address does not match the table entry LIBRARY ARP LIB 106 rabbit com TCP IP Manual Vol 1 arpresolve ipaddr longword arpresolve ipaddr ATHandle ath DESCRIPTION Given an ARP table handle return the IP address of the corresponding table entry PARAMETER ath ARP Table Handle obtained from e g router for RETURN VALUE 0 An error occurred such as an invalid or obsolete handle OxFFFFFFFF The handle refers to either the broadcast address or to a point to point entry whose IP address is not defined Else An IP address This may be 127 0 0 1 for the loopback entry LIBRARY ARP LIB TCP IP Manual Vol 1 rabbit com 107 arpre
25. range 0 107 int tx power reserved uint8 country infol WLN COUNTRY STRLENI reserved int link reserved win status The association state is indicated by one of the following macros LN ST STOPPED Wi Fi driver is stopped LN ST SCANNING Currently performing a scan LN ST ASSOC ESS Associated with an AP JLN ST AUTH ESS Authenticated with an AP JLN ST JOIN IBSS Joined an existing ad hoc network JLN ST S TART I BSS Started an ad hoc network T COMMANDS FOR MANAGING WEP SHARED AND WPA PRE SHARED KEYS IFS WIFI WEP KEYNUM Set which of four WEP keys to use 0 3 IFG WIFI_WEP_KEYNUM Get WEP key number that is active int The win status structure is documented with the parameter in ifconfig 140 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFS WIFI WEP KEY BIN Set WEP key to 5 or 13 bytes using 3 parameters 1 WEP key number to set int 0 3 2 Length in bytes e IFPARAM WIFI WEP KEY40 5 byte key e IFPARAM W F _WEP_KEY104 13 byte key 3 Pointer to WEP key value byte IFG WIFI_WEP_KEY BIN Get value of specified WEP key using 3 parameters 1 WEP key number specified int 0 3 2 Pointer to location to store length of WEP key int 3 Pointer to location to store key value byte IFS WIFI WEP KEY HEXSTR Set WEP key to 10 or 26 character hex string Set value of WEP key specified
26. root ca cert FC WIFI IDENTITY MyClientIdent SSL USE AES TCP IP Manual Vol 1 rabbit com 23 2 4 1 7 Infrastructure WPA Enterprise using PEAP and TKIP Encryption To configure within your program copy and paste the following into your sample program and modify as necessary for your situation define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define _ PRIMARY NETMASK 255 250 LEES OM define MY GATEWAY 10 10 26 define MY NAMESERVER 110 10 6 1 tdefine WIFI USE WPA tdefine IFC WIFI SSID rabbitTest tdefine IFC WIFI ROAM ENABLE 1 tdefine IFC WIFI ROAM BEACON MISS 20 define IFC WIFI MODE IFPARAM WIFI INFRASTRUCTURE define IFC WIFI REGION IFPARAM WIFI REGION AMERICAS tdefine FC WIFI ENCRYPTION IFPARAM WIFI ENCR TKIP The above defines are identical to using TKIP with PSK define WPA USE EAP WPA USE EAP PEAP ximport certs root pem root ca cert define IFC WIFI CA CERT XIM root ca cert define IFC WIFI IDENTITY my userld define IFC WIFI PASSWORD my passwOrd Because it is necessary to ximport SSL certificates for use with this encryption method it is not possible to completely configure WPA Enterprise with
27. 101 arpcache load cont RETURN VALUE Positive value Success ATH NOROUTER The specified router entry number is invalid This can be because the router used parameter is bad or because the router entry has a mismatching ATH ATH INVALID Invalid table handle passed or unused entry ATH OBSOLETE The given handle was valid but obsoleted by a more recent entry No change made LIBRARY ARP LIB 102 rabbit com TCP IP Manual Vol 1 arpcache search ATHandle arpcache search longword ipaddr int virt DESCRIPTION Return handle that refers to the ARP cache table entry for the given IP address This does not do any resolving It only consults the existing cache entries The returned handle is guaranteed to be valid at least until the next call to tcp_ tick Usually the handle will be valid for con siderably longer however it is possible for the handle to become obsolete if the cache entry is re used for a different address The caller should be able to deal with this possibility The entry returned for the broadcast address is guaranteed to be permanent PARAMETERS ipaddr IP address to locate in the cache This may be 1L to locate the broadcast entry or our own IP address to return the loopback entry virt 0 Do not return the broadcast or loopback entries 1 Allow the broadcast or loopback entries RETURN VALUE Positive value Handle to the entry ATH NOTFOUND No entry ex
28. 162 ModemStartPPP ee ee ee 162 multicast joinSTOUP esse sesse see Re 163 multicast Jeavegroun esse sesse esse 164 sl RR OE DR Ee 165 TOMS N GE EE Re ies fas 166 pd getaddress isi se ez 167 pd havelink occ ene sa RARR GR AE RE 168 pd pOwerdown moms se se ee RR RE 169 pd PowerUp oer e 170 et 171 PRP actives iss EE Es Gee nies 172 PPPnegotiatelP ee see ee ee ee 172 PPPsetAuthenticatee 2 sem 173 PPPsetAuthenticator eee 173 PPPshutdown e se ee ee ee 174 PSOCKet 2 25 ER SE GE je 174 ves AE EE N 175 resolve Cancel 176 resolve name check 177 resolve name start 178 i ESE SE EE ER cies Heh WIR eA 179 router add RE EE RE EE 180 router del all 181 roufer delete ENE EE diets 181 TOUtET TOE as DE Deer hees se ee gee 182 router for face sesse sesse eke ee 183 router PHIM Hse tii SE ee 185 router printall esse see se eke 186 send DINGE RES EE EE 187 setdomainnamMe esse es se ee se ke 188 Sethostid es EE RR De cao 189 sethostname Lee se ee Ge ke 190 dek od N 191 sock Alive iz ii A i PG 192 sock aread sist anh ae 193 SOCK awmte EE N EE 194 socksaxread ss EDE tend Ee Ee adit 195 sock AX WHITE es eee 196 sock bytesreadY iese see ee ee 197 Ts ed N Ee AT 198 sock datareadv ese sees see ee 199 SEET 200 SOCK ETOT EE EE wien vs 201 sock established ee ee 202 sock fastread ee ee ee ee 203 sock fastWwiite sesse see see ee 204 sock flush
29. 42 skeleton program i e side Pe esse SEE Gee Ee AND Eg 65 N TCP BUR SIZE sesse ese see se ese see se ese ee De ee SEG gee sn 40 TCP_CONNTIMEOUT m sesse seek ee ee ee 44 Nagle algorithm mm eenenennenznznz 80 224 TCP FASTSOCKETS em ese sesse seek ee ee Ge ee 46 NET ADD ENTROPY A 46 TCP LAZYUPD EE 45 83 NET COARSELOCK esse see ese se ee ee ee ee ee ee 46 top MaxBufSize Los ee se RA GR RA RR Ge ee ee 40 network addressing ees ee ee ee Ge RARR 89 TCP_MAXPENDING ees see sesse ee ee ee ee ee ee 41 TCP MAXRTO A 44 O TCP MINRTO i heh 45 82 Optimizations se sek ee Re GR Ge Ge ee Ge Gee ee eke 77 enee TCP OPENTIMEOUT An 44 P ECP SAC E 45 TCP _SYNQTIMEOUT nn 44 packet EE ie ee 47 acknowledgement E 78 80 TOP EE 47 PLOCESSING Lia RE OE EE e 66 TCP TWTIMEOUT iese ee ee ed 44 83 SIES EE EE 79 276 rabbit com Index JEPCONFIG iseer e NG ERG Ge ES 9 42 DD ede OR EEN e 77 88 CICK TALES N see ed a ee ees 66 U UDP broadcast packet see ee ee GR RA GR RA 61 performance EE EES EER Ee EE 61 UDP socket le E 61 FUNCTIONS ee se AR Re GR Re Re ee ee ee 61 open and CLOSE iseer ESE EER Ee EF SEER Ee ke 63 ede i 64 A AA LE N N OE 63 UDP BUF SIZE ese sesse ese ee ee se ee ee ee ge ee Ge Re ee 40 UDP he 47 UDP Ua bl WE 47 USE DHCP A on ee ee Oe eg 36 USE ETHERNET lem iese sees sesse ee see ee ee ee see ee ee 5 42 USE PPOR i i ee ee 5 USE PPP SERIAL iese see sees ee se ese ee ee ee ee
30. 5 43 99 USE PPPOE ete acted ein tatty eech ate 43 98 USE RESERVEDPORTS iese see see ee ese see ee 58 USE SNMP ea nnno 36 USE WED E 5 W VEER RE EK EET 16 TCP IP Manual Vol 1 rabbit com 277 278 rabbit com Index RABBIT Dynamic C TCP IP Functions Listed Alphabetically Symbols _abort_socks AE EA 107 _arp send gratuitous sesse see ee 122 Ed RE N N 124 i e EA EE IE 183 Rd ME N 199 arp getArpData sse esse eke ee 116 arp_getArpGateData iese sees 116 ee OE EO geg 117 arpcache_create io EE NES 108 arpca tie Delt ons gg eg 109 AMP CACHE NWA ese s ses ERA kid 110 arpcache_iface ss Sk a 111 arpcache_ipaddr seke RE ie 112 arpcache_load se RES ed 113 arpcache_search susse eks Gee 115 arpresolve CHECK iss dese 118 arpresolve ipaddr sesse ENE 119 arpresolve Start iese esse ee ee 120 arpresolve start iface iese ees 121 ACON sanse reei EE A 123 dhcep_acquire E 125 dhcp get timezone iese see ee 126 nl 127 getdomainname LL seeeennnnnzzz 128 POTOSI as kan eks EE es 129 gethostname sse se ee ee 130 getpeername Ee Sk de 181 getsockname ege ege ege 132 ei N 133 PONG RE EA EE 134 ORR es ee ede ie eed 135 S 158 ifpending E 159 EE EE OE N 160 EE 161 inet addi sa ees de De ede ee 163 TNE ie SERE N ee 164 ip_iface AE AE magis eikiemedie 165 ip print ifs oes NE Ee eed 166 ip timer expired L ussussi unzanisazananzata 167 ip timer
31. 6 3 VO Functions for UDP Sockets 50 61 Multicasting 33 Ese Es Ee Ee es Ee Es 81 3 7 UDP Socket Functions pre 7 05 51 6 1 1 Multicast Addresses 81 3 7 1 VO Functions for UDP Sockets 51 6 1 2 Host Group Membership 81 3 7 2 Opening and Closing a UDP Socket 51 62IGMP E 82 3 7 3 Writing to a UDP Socket 51 6 3 Multicast Macro ees ese ee ee ee ee ee 82 3 7 4 Reading From a UDP Socket 52 375 Sone MANN from the older UDP CNR RE 83 API to the new UDP API 52 7 1 PPP LibrarieS ern nn 83 3 8 Skeleton Program semen 53 7 2 External Modem Library een 84 3 8 1 TCP IP Stack Initialization 53 7 3 Operation Details for PPP over Serial 84 3 8 2 Packet Processing sse 54 7 3 1 The Modem Interface 84 3 9 TCP IP Daemon ep Deckt 54 7 3 1 1 Rabbit Pin Connections to Mo 3 9 1 tep_tick for Robust Applications 54 dem RE ER ai 85 3 9 2 Global Timer Variables 55 7 3 2 Flow Control ese se ee 85 3 10 State Based Program Design 55 7 4 Operation Details for PPPOE esse sees 86 3 10 1 Blocking vs Non Blocking 56 7 5 Link Control Protocol Options 86 3 10 1 1 Non Blocking Functions 56 7 6 Configuring DPP 87 3 10 1 2 Blocking Functions 56 7 6 1 Serial Port Selection sesse see 87 3 11 TCP and UDP Data Handlers 57 7 6
32. GE EE Se EE ER i ESE ee eg 260 udp Peek EER ED ik kk eege EG 262 Wp TOC ysl eile re Mt ds ade ee 263 udp reCVITOM ees ese ee ee GR RR 264 udp send EE ESE ES BEE Ee GE 265 udpsendto isse 266 udp waitopen esse ee ese ee Re RR RR 267 udp waitsend se ee RR ER 268 udp XsendtOs iss EE es ES 269 virtual et ss ese ives De RR EE 270 Wifi ssid to SAP ese EE ER EES ee Ee 271 iS AE RE MES EN 273 vi TCP IP User s Manual 1 Introduction This manual is intended for embedded system designers and support professionals who are using a Rabbit based controller board Most of the information contained here is meant for use with Ethernet or WiFi enabled boards but using only serial communication is also an option Knowledge of networks and TCP IP Transmission Control Protocol Internet Protocol is assumed For an overview of these two topics a separate manual is provided An Introduction to TCP IP A basic understanding of HTML HyperText Markup Language is also assumed For information on this subject there are numerous sources on the Web and in any major book store The Dynamic C implementation of TCP IP comprises several libraries The main library is DCRTCP LIB As of Dynamic C 7 05 this library is a light wrapper around DNS LIB IP LIB NET LIB TCP LIB and UDP LIB These libraries implement DNS Domain Name Server IP TCP and UDP User Datagram Protocol This along with the libraries ARP LIB ICMP LIB IGMP LIB
33. LIBRARY MODEM LIB ModemStartPPP void ModemStartPPP void DESCRIPTION Hands control of the serial line over to the PPP driver LIBRARY MODEM LIB 162 rabbit com TCP IP Manual Vol 1 multicast joingroup int multicast joingroup int iface longword ipaddr DESCRIPTION This function joins the specified multicast group class D IP address from 224 0 0 0 to 239 255 255 255 on the specified interface For an Ethernet interface it configures the hard ware to accept multicast packets for the specified address Note that this function is called automatically when udp_open is used to open a multicast address PARAMETER iface Interface on which to join the group Use one of the definitions e IF ETHO e IF ETH e IF WIFIO e IF DEFAULT ipaddr Multicast group to join RETURN VALUE 0 Success 1 Failure e g ipaddr is not a multicast address or not enough available ARP entries to hold the group LIBRARY IGMP LIB TCP IP Manual Vol 1 rabbit com 163 multicast leavegroup int multicast leavegroup int iface longword ipaddr DESCRIPTION This function leaves the specified multicast group class D IP address from 224 0 0 0 to 239 255 255 255 on the specified interface For an Ethernet interface it configures the hard ware to no longer accept multicast packets for the specified address This function will leave the group no matter how many multicast joingro
34. MODE DICMP PARAMETERS S mode RETURN VALUE Marks this socket as the default receiver of ICMP messages which cannot be assigned to a particular UDP socket This would be used for UDP sockets that are used with many different sendto addresses since the ICMP message may refer to a message sent some time ago with different destination address than the most recent Only one UDP socket should be set with this mode Equivalent Macros udp set nodicmp s andudp set dicmp s Pointer to a socket New mode for specified socket Resulting mode flags SEE ALSO inet addr LIBRARV NET LIB Prior to DC 7 05 this was DCRTCP LIB TCP IP Manual Vol 1 rabbit com 213 sock noflush void sock_noflush tcp Socket s DESCRIPTION This function prevents the next write to the socket from transmitting a data segment It needs to be issued before each write function in which it is desired not to transmit It can be used to make more efficient use of network bandwidth when the Nagle algorithm is turned off for the socket If Nagle is on then there is not much benefit to using this function PARAMETERS s Pointer to a socket RETURN VALUE None LIBRARY TCP LIB SEE ALSO sock flush sock flushnext sock fastwrite sock write 214 rabbit com TCP IP Manual Vol 1 sock perror void sock perror void s const char prefix DESCRIPTION Prints out the most recent error messages for a socket and clear the
35. MODEMESCAPE Will escape sequence lt delay gt lt delay gt be added before sending send expect or han gup strings bool IFS_PPP_HANGUP Optional string to send to modem to shut it down in send expect format See IFS PPP SENDEXPECT for more information IFG PPP HANGUP Get optional string char PARAMETER IDENTIFIERS FOR DMA The following two parameter identifiers rely on the existence of DMA channels thus are only for PPP or VSPD interfaces on Rabbit 4000 or newer Rabbit processors IFS_USE_DMA Use the specified DMA channel instead of the serial port e dma_chan_t specifies channel for source e dma_chan_t specifies channel for destination e word specifies I O port address IFS_USE_SERIAL Use the serial port directly This undoes the effect of IFS USE DMA Any PPP over asynchronous serial or VSPD Virtual Stream Packet Driver interface may be switched between its normal fixed async serial port and a pair of DMA channels allocated to the application via the DMAalloc function in DMA LIB The DMA channels should not be modified by the application while in use by the network library When specifying DMA channels type dma chan t you also provide a third word param eter that specifies the I O register to be the source and destination for incoming and outgoing data respectively This does not need to be a serial port data register but it usually would be Currently only interna
36. PEAP using the Project Defines However as long as you include something similar to this ximport statement in your program ximport certs root pem root ta cert you can provide the rest of the configuration in the Project Defines Here is an example copy and paste into the Defines window and modify as necessary TCPCONFIG _PRIMARY_STATIC_IP _ PRIMARY NETMASK MY GATEWAY MY NAMESERVER WIFI_USE_WPA FC_WIFI_SSID FC_WIFI_ROAM ENABLE FC WIFI ROAM BEACON MI FC WIFI MODE FC WIFI REGION FC WIFI ENCRVPTION WPA USE EAP FC WIFI IDENTITV FC WIFI PASSWORD FC WIFI CA CERT XIM 110 10 6 100 2594259620060 rabbitTest 20 IFPARAM WIFI INFRASTRUCTURE IFPARAM WIFI_REGION AMERICAS IFPARAM WIFI ENCR TKIP WPA USE EAP PEAP my userld my passwOrd root ca cert 24 rabbit com TCP IP Initialization 2 4 1 8 Specifying a Pre Shared Key There are two ways to specify a pre shared key either by specifying the 256 bit pre shared key directly in hex format or by entering a passphrase A passphrase is the most common method All Wi Fi devices that accept a passphrase use a standard algorithm to generate the pre shared ke
37. PRIMARY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 define MY NAMESERVER 10 10 6 1 define WIFI SSID rabbitTest define IFC_WIFI_ROAM ENABLE 1 define IFC_WIFI_ROAM BEACON MISS 20 define IFC WIFI CHANNEL 1 tdefine IFC WIFI MODE IFPARAM WIFI ADHOC tdefine IFC WIFI REGION IFPARAM WIFI REGION AMERICAS tdefine IFC WIFI ENCRVPTION IFPARAM WIFI ENCR NONE Alternatively you can configure within the Defines window Here is an example to copy and paste into the Defines window and modify as necessary TCPCONFIG 1 _PRIMARY STATIC IP 10 10 6 100 _ PRIMARY NETMASK Web GEO MY GATEWAY WO LO sGr MY NAMESERVER 110 10641 FC WIFI SSID rabbitTest FC WIFI ROAM ENABLE 1 FC WIFI ROAM BEACON MISS 20 FC_WIFI_CHANNEL 1 FC_WIFI_MODE IFPARAM WIFI_ADHOC FC WIFI REGION IFPARAM WIFI REGION AMERICAS FC WIFI ENCRYPTION IFPARAM WIFI ENCR NONE r 18 rabbit com TCP IP Initialization 2 4 1 3 Infrastructure WEP Encryption Configuration WEP is an encryption method for Wi Fi networks It is now considered insecure but it is commonly supported by Wi Fi devices To use WEP all devices including the access point or Wi Fi router will need to be configured with the same WEP keys a
38. RABBIT 4 Optimizing TCP IP Performance Once you have a TCP IP application coded and working it is worthwhile to tune the application to get the best possible performance There is usually a trade off between performance and memory usage If more memory is available you can specify larger data buffers to improve overall performance Conversely if performance is already adequate you can reduce buffer sizes to make room for more application function ality Some performance improvements can be made without large increases in memory usage To make these improvements you will need to understand how TCP IP and the properties of the network work and inter act This is a complex subject which is well covered in various texts This section concentrates on the characteristics of the Dynamic C TCP IP stack Most of the discussion is centered around Dynamic C ver sion 7 30 but many of the principles apply to earlier releases The discussion also concentrates on TCP UDP is also mentioned where appropriate however UDP performance is mainly determined by the appli cation so there are not as many tuning controls available in the Dynamic C libraries for tuning UDP perfor mance The type of application has a large bearing on the performance tuning options which will be most appro priate Here are some basic types of application which have different performance requirements e Bulk Loader an application which periodically uploads large amounts of da
39. TCP IP Manual Vol 1 rabbit com 127 ifconfig cont d IFG ICMP CONFIG Is ping configure enabled bool IFG ICMP CONFIG OK Was ping configured successfully bool IFS ICMP CONFIG RESET After ping configured okay allow new ping configure IFS DEBUG Set debug level int Sets a global variable debug_on 0 to print only a few messages up to 5 to print suc cessively more messages This parameter does not care about the value of iface because it is not specific to an interface IFG DEBUG Get debug level int This parameter does not care about the value of 1face because it is not specific to an in terface IFS IF CALLBACK Set interface up down callback or NULL void SO The interface up down callback function is called with two parameters ifcallback int iface int up where iface is the interface number and up is non zero if the interface has just come up or zero if it has just come down You must define USE IF CALLBACK before use dertcp lib to use this functionality PARAMETER IDENTIFIERS FOR DHCP The DHCP parameters are only available if USE DHCP is defined and will only work if the interface is qualified for DHCP The IFS_ DHCP parameter will cause acquisition or release of the specified interface IFS DHCP Use DHCP to configure this interface bool 0 for false non zero for true IFG DHCP Get DHCP setting bool IFG DHCP O
40. The great majority of applications should not use this func tion If ARP bypass is in effect for a UDP socket then udp_sendto will never return the 2 re turn code The destination interface is also forced to be IF DEFAULT If the supplied hardware address is accessible from a non default interface only then you will need to manually set the s gt iface field PARAMETERS s UDP socket eth Pointer to override address If NULL then resume normal operation 1 e use ARP to resolve Ethernet addresses Note that the specified Ethernet ad dress must be in static storage since only the pointer is stored LIBRARY UDP LIB SEE ALSO udp sendto udp waitsend sock resolved 256 rabbit com TCP IP Manual Vol 1 udp_close void udp close udp Socket ds DESCRIPTION This function closes a UDP connection Starting with Dynamic C 7 30 this function performs the actions necessary to leave a host group when closing a multicast socket It is IGMPv2 com pliant PARAMETERS ds Pointer to socket s data structure LIBRARY UDP LIB TCP IP Manual Vol 1 rabbit com 257 udp_extopen int udp_extopen udp Socket s int iface word lport longword remip word port dataHandler t datahandler long buffer int buflen DESCRIPTION This function is an extended version of udp open It opens a socket on a given network interface i face on a given local port lport If the remote IP address is specified re
41. bytes in the next datagram to be read If it is a datagram with no data an empty datagram then it will return 0 If there are no datagrams waiting then it returns 1 PARAMETERS s Pointer to a socket RETURN VALUE 1 No bytes waiting to be read 0 If in ASCII mode and a blank line is waiting to be read for DC 7 05 and later a UDP datagram with 0 bytes of data is waiting to be read 20 The number of bytes waiting to be read LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock established sockstate TCP IP Manual Vol 1 rabbit com 197 sock close void sock close void s DESCRIPTION Close an open socket The socket cannot be reused until it is completely closed In the case of UDP the socket is closed immediately TCP being a connection oriented proto col must negotiate the close with the remote computer You can tell a TCP socket is closed by tcp _tick s NULL or by running sock wait closed s In emergency cases it is possible to abort the TCP connection rather than close it Although not recommended for normal transactions this service is available and is used by all TCP IP sys tems PARAMETERS s Pointer to a socket LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock abort sock tick sock wait closed tep open udp open 198 rabbit com TCP IP Manual Vol 1 sock datareadv int sock datareadv void s DESCRIPTION Return
42. delay time for lazy update ms This is used to slightly delay window updates and empty acknowledgments to the peer in the hope of being able to tag extra data along with otherwise empty segments This improves performance by allowing better interleaving of application processing with TCP activity and sending fewer empty segments This delay interval is also used when we need to retransmit owing to a temporary shortage of Ethernet transmit buffers Defaults to 5 ms DNS_RETRY_TIMEOUT 2000 by default Specifies the number of milliseconds to wait before retrying a DNS request If a request to a nameserver times out then the next nameserver is tried If that times out then the next one is tried in order until it wraps around to the first nameserver again or runs out of retries DNS_NUMBER_RETRIES 2 by default Specifies the number of times a request will be retried after an error or a timeout The first attempt does not constitute a retry A retry only occurs when a request has timed out or when a nameserver returns an unintelligible response That is if a host name is looked up and the nameserver reports that it does not exist and then the DNS resolver tries the same host name with or without the default domain that does not constitute a retry DNS MIN KEEP COMPLETED 10000 by default Specifies the number of milliseconds a completed request is guaranteed to be valid for resolve name check After this time the entry in the internal ta
43. down IF UP Starts bringing interface down using normal graceful procedure IF COMING DOWN Forces down cuts short any normal termination procedure PARAMETER iface Interface number Use one of the definitions e IF DEFAULT e IF ETHO e IF ETHI e IF WIFIO e I F PPPOEO e IF PPPOEI1 e IF PPPO 5 If the interface does not exist you will get a compile time error F DEFAULT refers to the default interface which will be equivalent to the first of the other interface identifiers in the above list which exists RETURN VALUE IFCTL_OK if OK FCTL FAIL if error IFCTL PEND if OK but not complete LIBRARY NET LIB SEE ALSO ifconfig ifup ifstatus ifpending 146 rabbit com TCP IP Manual Vol 1 ifpending int ifpending int iface DESCRIPTION Returns indication of whether the specified interface is up down pending up or pending down This gives more than if status which only indicates the current state up or down NOTE ANDing the return value with 0x01 indicates a pending condition ANDing with 0x02 is equivalent to the return from ifstatus except that ifstatus returns 1 instead of pa Example assume IF DEFAULT is down Bring it up ifconfig IF DEFAULT IFS UP IFS END while ifpending IF DEFAULT IF COMING UP tcp tick NULL if ifpending I
44. dp Buffer to put the string len Max length of buffer RETURN VALUE 0 The buffer is empty or no r or n was read plus the buffer has room and the connection can get more data 20 The length of the string 1 Function was called with a UDP socket valid for Dynamic C 7 05 and later LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock puts sock putc sock gete sock read sock write EXAMPLE sock model s TEP MODE ASE do Li SOCK lycesxeacdy 2 gt 0 d SOCK seal s butter SLPAOI Site is Bees burter Is while cep tick s be 208 rabbit com TCP IP Manual Vol 1 sock i face byte sock iface void s DESCRIPTION Retrieve the interface number of an open socket May return 1 PARAMETER s Pointer to open TCP or UDP socket RETURN VALUE Interface number O IF MAX 1 IF ANY If the socket is unbound LIBRARY NET LIB SEE ALSO tcp extopen udp extopen tcp extlisten IF ANY for unbound sockets TCP IP Manual Vol 1 rabbit com 209 sock init int sock_init void DESCRIPTION This function initializes the packet driver and DCRTCP using the compiler defaults for config uration This function should be called before using other DCRTCP functions The return value indicates if sock init was successful If it returns 0 then everything was successful If it returns 1 then the packet driver initialization failed Note tha
45. ee 107 4 4 1 Bulk Loader Applications 75 AAS Casual Server Applications yansa 76 er A ee 108 4 4 3 Master Controller Applications 76 arpresolve start iface eee 109 4 4 4 Web Server Applications 76 _arp send gratuitouS siese sesse ese 110 4 4 5 Protocol Translator Applications 76 e 111 5 Network Addressing ARP amp DNS 77 hk Pings cenit N OK N 112 5 1 ARP Functions ees see see ee ee ee 77 dhep acte 113 5 2 Configuration Macros for ARD 77 dhep get timezone en 114 5 3 DNS FUnCHORS esse RE 79 GE ge 5 4 Configuration Macros for DNS Lookups 79 getdomainname iese see ee ee 116 6 IGMP and Multicasting ee 81 pethostid si DR ee 117 iv TCP IP User s Manual getpeername Lena 119 getsockname 6 ee ee ee 120 ton sis bees EE Sei EE ah 121 SES RE dE NEE 122 ICONE Xi ia ei a soe ees 123 leren ee Zeit Keen Nacsa ds Ate ed ag 146 IP PENGUIN g iri ie i e e eg 147 EE CN 148 Ed si i i 149 iet addis ennes pe A es 151 iet MOa RO N EL 152 IP ELE 153 Oto E CH 154 ip timer evpired iese see ee ee 155 ip timer Dit etes Ee SES ges 156 is valid ifane 157 ModemClose e se se ee ee se ie 158 ModemConnected ie see se ee 158 Modembspect ee ee ee ee 159 ModemHangup me ses sesse ee ee Ee 159 Modemlnit i s sesse SERE GERS EE SE Ee se Ge 160 ModemO en ees see ee ee 160 Modembeady e see see ee 161 ModemRinging iese see see ee ee 161 ModemSend ec esse se se ee ee se ie
46. ent data segment sizes than the default Generally whichever side has the smallest MTU will place a limit on the segment size This is negotiated via the TCP MSS Maximum Segment Size option In your program rather than hard coding the optimum chunk size you can define a symbol as follows define TCP CHUNK SIZE MAX MTU 40 Where MAX MTU is a symbol defined by the library to be the actual MTU in effect For multiple inter faces it is probably better to use the minimum value of any interface You can find out the current MTU for an interface using ifconfig iface IFG MTU amp mtu IFS END which will read the MTU for interface 1face into the integer variable mtu Most of the time the TCP socket MSS will be equal to the fixed value above In cases where it is smaller there will not be a noticeable decrease in efficiency Once you determine the appropriate chunk size use sock awrite or sock axwrite for extended memory data with the specified chunk size except possibly for the last chunk The function sock awrite and friends are available starting with Dynamic C 7 30 They have the advantage that the data is completely buffered or not at all sock _fastwrite may buffer less than the requested amount which means that your application needs to keep track of the current position in the data being sent sock awrite does not do things by halves so it is easier to keep track in the app
47. errors This calls sockerr andprintf soit should only be called for debugging a new application The output is in the format TCP UDP socket ipaddr port gt ipaddr port msgl msg2 where msg1 and possibly msg2 are the most recent error messages The initial string is TCP or UDP for open sockets or may be Closed if the socket is currently closed either TCP or UDP Up to two error codes may be queued to a socket If there are no errors nothing is printed PARAMETERS s Pointer to TCP or UDP socket prefix Pointer to text to add to generated messages or NULL LIBRARY NETERRNO LIB SEE ALSO sock error sockerr TCP IP Manual Vol 1 rabbit com 215 sock preread int sock_preread tcp Socket s byte dp int len DESCRIPTION This function reads up to len bytes from the socket into the buffer dp The bytes are not re moved from the socket s buffer This function is only valid with TCP sockets PARAMETERS s Pointer to a socket structure dp Buffer to preread into len Maximum number of bytes to preread RETURN VALUE 0 No data waiting 1 Error 20 Number of preread bytes LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock fastread sock fastwrite sock read sock write 216 rabbit com TCP IP Manual Vol 1 sock putc byte sock putc tcp Socket ze byte c DESCRIPTION A single character is placed on the output buffer In the case
48. established The purpose of this function is to simplify the application logic in programs which interleave TCP IP functions with other processing i e non blocking style NOTE it is an error to pass a UDP socket to this function UDP sockets are connectionless so there is no concept of waiting for a connection PARAMETER s TCP socket pointer This should be a TCP socket which was opened using tcp listen tcp extlisten tcp open or tcp_extopen RETURN VALUE 0 socket is not waiting In this case then next tests that the application should perform are a sock established if this returns TRUE a connection is currently estab lished The application can now communicate using sock read sock write etc then finally call sock close b sock alive if this returns FALSE then the socket was aborted by the peer The application may re open or re listen the socket c Otherwise the socket was established but is now closing because the peer closed its side of the connection The application MAY be able to read and or write to the socket depending on protocol however the amount of readable data will be limited The ap plication should call sock _close orsock abort In cases a and c a socket should not be re opened until tcp tick on that sock et returns 0 Note that 0 is returned for invalid sockets e g UDP sockets or sockets that are closed non zero the socket is waiting for
49. flush sock puts and sometimes sock putc when passed a in PARAMETERS s Pointer to a socket RETURN VALUE None LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock write sock fastread sock read sockerr sock flush sock flushnext 206 rabbit com TCP IP Manual Vol 1 sock getc int sock getc tcp Socket s DESCRIPTION Gets the next character from the socket NOTE This function blocks Starting with Dynamic C 7 05 this function is only valid with TCP sockets Prior to 7 05 this function could not be used on UDP sockets after sock recv init was called PARAMETERS s Pointer to a socket RETURN VALUE Character read or 1 if error LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock putc sock gets sock puts sock read sock write EXAMPLE Co 4 iit soek bytesready s gt 0 Pi seleksie sels DI mile ep cick Ss g TCP IP Manual Vol 1 rabbit com 207 sock gets int sock_gets tcp Socket s char dp int len DESCRIPTION Read a string from a socket and replace the CR or LF with a 0 If the string is longer than len the string is null terminated and any remaining characters will be returned on the next sock gets call This function is only valid for TCP sockets To use sock gets you must first set ASCII mode using the function sock mode or the macrotcp_set_ascii PARAMETERS s Pointer to a socket
50. for the addition of the custom library To use custom configurations that you define the only thing necessary in each sample program is to change the definition of the TCPCONFIG macro to indicate the appropriate configuration e g define TCPCONFIG 100 use dcrtcp lib 2 2 2 2 Static Configuration This is conceptually the easiest means of configuration however it is primarily suitable for testing purposes or possibly as a fallback in case other configuration techniques do not yield a result in a reasonable amount of time Prior to version 7 30 the only interface was configured by defining a fixed set of macros before including dcrtcp 1ib The most common definitions were limited to MY IP ADDRESS MY NETMASK MY GATEWAY and MY NAMESERVER At runtime the functions tcp config sethostid and sethostname override the configuration macros Version 7 30 still allows use of these macros for backwards compatibility however it is recommended that the new style of static configuration be used for new applications The new configuration style uses macros called IFCONFIG where 5 is replaced by the interface name e g IFCONFIG ETHO for the 10 rabbit com TCP IP Initialization first Ethernet port IFCONFIG ALL contains configuration items that are not specific to any particular interface The value of the IFCONFIG macro is actually a list of items
51. hostname is tried by itself If that also fails the lookup fails Ifhostname does contain a then hostname is looked up by itself If it does not exist the default domain is appended and that combination is tried If that also fails the lookup fails If hostname ends with a then the default domain is not appended The host name is con sidered fully qualified The lookup is attempted without the ending and if that fails no other combinations are attempted This function returns a handle that must be used in the subsequent resolve name check and resolve cancel functions PARAMETERS hostname Host name to convert to an IP address RETURN VALUE 20 Handle for calls to resolve name check and resolve cancel RESOLVE NOENTRIES Could not start the resolve process because there were no resolve en tries free RESOLVE LONGHOSTNAME The given hostname was too large RESOLVE NONAMESERVER No nameserver has been defined LIBRARY DNS LIB SEE ALSO resolve name check resolve cancel resolve 178 rabbit com TCP IP Manual Vol 1 rip char rip char string DESCRIPTION Strips newline n and or carriage return r from a string Only the first n and r characters are replaced with XOs The resulting string beyond the first XO character is undefined PARAMETERS string Pointer to a string RETURN VALUE Pointer to
52. in the first parameter int to 10 or 26 char hex string stored at the second parameter char IFG WIFI WEP KEY HEXSTR Get value of WEP key specified in the first parameter int Store hex string in the second parameter char IFS_WIFI_WPA_PSK_PASSPHRASE Set the WPA PSK to hash based on a null terminated ASCII string of up to 63 characters char and the SSID Set the SSID before setting the passphrase After generating the key you canuse IFG WIFI WPA PSK HEXSTR to get the key as a 64 character hex string for use with IFS WIFI WPA PSK HEXSTR Note that if you change the SSID after setting the passphrase you will need to reset the passphrase by us ing the IFS WIFI WPA PSK PASSPHRASE command again WPA pre shared keys PSK are used for WPA PSK authentication and for TKIP and CCMP encryption Setting the key with a passphrase can take 20 seconds on an RCM4400W Setting the key directly as hex is much more efficient IFS_WIFI_WPA_PSK_HEXSTR Set WPA PSK to 64 character hex string char 65 FS WIFI WPA PSK HEXSTR takes a null terminated ASCII string of 64 hex digits and uses it for the key IFG WIFI_WPA_PSK_HEXSTR Get WPA PSK as a 64 character hex string char 65 TCP IP Manual Vol 1 rabbit com 141 ifconfig cont d IFS WIFI WPA PSK BIN Set 32 byte WPA PSK byte 32 IFG WIFI WPA PSK BIN Get 32 byte WPA PSK byte 32 COMMANDS F
53. in the syntactic form of a C parameter list For example if the old style configuration for Ethernet was define MY IP ADDRESS 10 10 6 100 define MY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 then the new replacement would be define IFCONFIG ETHO X Fo IPADDR aton 10 10 6 100 FS NETMASK aton 255 256 255 0 IFS ROUTER SET aton 10 10 6 17 N IFS UP The replacement looks more complex but this is because the macro value must be valid C syntax for a parameter list The IFS UP parameter at the end of the above example is a new feature for interfaces they can be dynamically brought up and down The default state for an interface is down which is why an explicit IFS UP is required The backslashes at the end of each line are used to continue the macro definition over more than one line The format of the static initialization macros will make more sense if you examine the documentation for the ifconfig function You will see that the macro definition is merely plugged in to the parameter list for an ifconfig call 2 2 2 3 Dynamic Configuration via the Network The Dynamic C TCP IP stack supports DHCP Dynamic Host Configuration Protocol or BOOTP Bootstrap Protocol for dynamic configuration DHCP is a more modern replacement for BOOTP which was originally designed to support bootstrap of diskless w
54. interface then an ARP resolve request is issued through that interface If the address is not on the local subnet then a router table entry with router on the given interface is used and no network activity is necessary unless the router itself is not resolved in which case its resolution is commenced If ipaddr is zero then the broadcast entry is returned since this is required for DHCP when our IP address is not yet known This function is identical to arpresolve start ifthe iface parameter is set to IF ANY PARAMETERS ipaddr IP address of host whose hardware address is to be resolved iface Specific interface or IF ANY to get the library to select the most appro priate interface A specific interface forces the use of that interface even if there is no route available This function should only be used to override the normal interface selection procedure RETURN VALUE Positive value Success This value is actually the ATH of the ARP cache table entry which is or will be used it should be passed to subsequent calls to arpresolve check ATH NOENTRIES No space is available in the table and none of the entries could be purged because they were all marked as permanent or router entries E ATH NOROUTER No router gateway is configured for the specified address which is not on the local subnet of the specified interface LIBRARV ARP LIB SEE ALSO arpresolve start TCP IP Ma
55. is an example to copy and paste into the Defines window and modify as necessary TCPCONFIG 1 _ PRIMARY STATIC IP 10 10 6 100 _ PRIMARY NETMASK 255 255 255 0 MY GATEWAY 10 10 6 1 MY NAMESERVER 10 10 6 1 FC WIFI SSID rabbitTest FC_WIFI_ROAM ENABLE 1 FC_WIFI_ROAM BEACON MISS 20 FC_WIFI_MODE IFPARAM WIFI_INFRASTRUCT FC WIFI REGION IFPARAM WIFI REGION AME FC_WIFI_ENCRYPTION IFPARAM WIFI_ENCR FC WIFI WEP KEYNUM 0 FC WIFI WEP KEVO H JI ti CAS 77 EXSTR 0123456789abcdef0123456789 TCP IP Manual Vol 1 rabbit com 19 2 4 1 4 Infrastructure WPA TKIP Encryption Configuration Pre Shared Key Wi Fi Protected Access WPA along with Temporal Key Integrity Protocol TKIP replaces the less secure WEP encryption method The Rabbit Wi Fi driver supports WPA encryption in pre shared key PSK mode This key can be specified as a 256 bit key or as a passphrase that is expanded into a key The code for WPA TKIP is compiled when you define the macro WIFI USE WPA To configure within your program copy and paste the following into your sample program and modify as necessary
56. is less need to perform error handling after other calls to TCP IP functions For example the sock fastread function normally returns a non negative value but it can return 1 if there is a problem with the socket An application function which calls sock fastread needs to check for this code however it can choose to merely return to the caller the main loop if this code is detected rather than handling the error at the point where it was first detected This works because if sock fastread returns 1 tcp tick will return zero for that socket 3 9 2 Global Timer Variables The TCP IP stack depends on the values for MS TIMER and SEC TIMER Problems may be encoun tered if the application program changes these values during execution 3 10 State Based Program Design An efficient design strategy is to create a state machine within a function and pass the socket s data struc ture as a function parameter This method allows you to handle multiple sockets without the services of a multitasking kernel This is the way the HTTP LIB functions are organized Many of the common Inter net protocols fit well into this state machine model The general states are Waiting to be initialized Waiting for a connection Connected states that perform the real work Waiting for the socket to be closed An example of state based programming is SAMPLES TCPIP STATE C This program is a basic Web server that s
57. isp com define EMAIL TO you wherever com define SMTP SERVER smtp isp com 7 3 1 1 Rabbit Pin Connections to Modem The modem control library MODEM LIB defines default connections to the Rabbit as follows Table 7 1 Rabbit Pin Assignments for Modem Connection RS232 Signal Rabbit Pin Direction DTR PB6 out RTS PB7 out CTS PBO in DCD PB2 in RI PB3 in DSR PB4 in TD PC2 out RD PC3 in 7 3 2 Flow Control Hardware flow control is implemented for the Rabbit PPP system It follows the RS232 convention of using Ready To Send RTS and Clear To Send CTS lines Flow control is not required for speeds up to and including 115200 bps The internal character processing is fast enough that the controller does not have to throttle incoming data flow However the modem or peer may need to throttle transmitted data It is recommended that the RTS modem to controller line be connected for modems that cannot handle a continuous data stream at the specified rate You can also connect the CTS controller to modem line but the controller will merely assert this line continuously To enable or disable hardware flow control call ifconfig withthe IFS PPP FLOWCONTROL parameter identifier You should also specify IFS PPP RTSPIN and IFS PPP CTSPIN parameter identifiers TCP IP Manual Vol 1 rabbit com 85 7 4 Operation Deta
58. it was transmitted we assume that the one way trip is half of the RTT The last character is received at t 1175ms with the reference t 0 taken as the first character transmission time The acknowledgment of the last character which completes the transac tion is received at t 1400ms In the Nagle case the last character is received at t 1375 and the final acknowledgment at t 1650 In this example the peer received all 10 characters 200ms later when Nagle was used It can be seen that at a slight cost in increased delay a great saving in total data transmission was made If the above example was extended to hundreds or thousands of characters then the additional delay would remain constant at a few hundred ms whereas the network bandwidth would be better utilized by a factor approaching five In conclusion leave Nagle on unless you absolutely must have the lowest delay between transmission and reception of data If you turn Nagle off ensure that your application is disciplined enough to write the larg est blocks it can For example if you have to send an 8 byte value as a unit construct the full 8 bytes as a single block then write them all in a single sock fastwrite call rather than calling sock fastwrite with two 4 byte calls or worse 8 single byte calls A useful alternative to turning Nagle off is to control packetization using calls to sock flush sock noflush and sock flushnext These functions allow the applica
59. macro definitions for boot time initialization Table 7 5 Macros for PPP Initialization for Serial Data Type s Macro Name Macro Description for Macro Parms IFS PPP SPEED Set serial PPP speed bps longword IFS PPP RTSPIN Define the RTS pin int char int IFS PPP CTSPINI Define the CTS pin int int l Use parallel port D instead of parallel port C for IFS PPP USEPORTD R bool a serial ports A and B IFS PPP FLOWCONTROL Turn hardware flow control on or off bool An optional string to send to the modem after IFS_PPP_HANGUP char SM PPP shuts down When enabled sends modem escape sequences before send expect or hangup sequence is IFS PPP MODEMESCAPE lt delay gt lt delay gt This is recognized by bool almost all modems to force them into command mode A formatted send and expect sequence for IFS PPP SENDEXPECT Sa char R dialing and shell login IFS PPP USEMODEM Specify whether to use modem dialout string bool All of these IFS PPP macros have IFG PPP versions that allow an application to look at the cur rent properties The parameter for the IFS PPP SENDEXPECT option is a string containing a send expect script to run when the PPP connection comes up It is a series of tokens separated by spaces alternating between a string to transmit and a string to expect back
60. multiple PPP serial interfaces are required use for example define USE PPP SERIAL 0x0C which as the bitwise combination of 0x04 and 0x08 specifies SERC IF PPP2 and SERD IF PPP3 7 6 2 PPPoE Port Selection Since all Rabbit based controller boards currently have at most a single Ethernet driver chip only a single PPPoE interface is available however it can be shared with non PPPoE Ethernet over the same hardware that is non PPPoE Ethernet will use interface IF ETHO while PPPoE will use IF PPPOEO TCP IP Manual Vol 1 rabbit com 87 7 6 3 ifconfig Options for PPP The ifconfig parameter identifiers described in this section pertain to any PPP interface whether serial or Ethernet There are a considerable number of options pertinent to PPP over asynchronous serial PPPoE does not as yet require any special configuration options because of its relative simplicity The parameter identifiers listed here are passed to the if config function They can also be used in the appropriate IFCONFIG PPP macro definitions to ensure that the interface s are initialized cor rectly at boot time For example a run time change to the userid and password might be coded as follows ifconfig IF PPP2 IFS PPP REMOTEAUTH myUserid myPassword FS END The same definition for boot time initialization might be coded as tdefine IFCONFI
61. of n the buffer is flushed as de scribed under sock flushnext No other ASCII character expansion is performed Note that sock putc uses sock write and thus may block if the output buffer is full See sock write for more details Starting with Dynamic C 7 05 this function is only valid with TCP sockets PARAMETERS s Pointer to a socket c Character to send RETURN VALUE The character c LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock read sock write sock fastread sock fastwrite sock mode TCP IP Manual Vol 1 rabbit com 217 sock puts int sock_puts tcp Socket s byte dp DESCRIPTION A string is placed on the output buffer and flushed as described under sock flushnext If the socket is in ASCII mode CR and LF are appended to the string No other ASCII character expansion is performed In binary mode the string is sent as is Note that sock puts uses sock write and thus may block if the output buffer is full See sock write for more details Starting with Dynamic C 7 05 this function is only valid with TCP sockets PARAMETERS s Pointer to a socket dp Buffer to read the string from RETURN VALUE 20 Length of string in dp 1 Function was called with a UDP socket valid for Dynamic C 7 05 and later LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock gets sock putc sock getc sock read sock write 218 rabbit com TC
62. orudp sendto may not be transmitted be cause the destination hardware address is not known If the current destination IP address of the socket is zero i e the socket is passively opened this function returns zero since datagrams cannot be transmitted from a passively opened sock et Ifudp bypass arp is in effect the return value from this function is unaffected how ever datagrams will still be sent to the specified hardware address since the normal resolve pro cess is bypassed Note that a hardware address may become invalid after being valid since the underlying ARP table may need to purge the entry This would be rare but if any UDP application needs to en sure that all packets are actually transmitted which is a questionable goal since UDP is unreli able then this function should be consulted before each send If this function returns 0 then the UDP socket should be re opened The hardware address may also be invalidated if udp sendto is called with a different destination IP address that has not been determined based on an incoming datagram This function is not required for TCP sockets since the TCP library handles these details inter nally PARAMETER s Pointer to open TCP or UDP socket RETURN VALUE 0 Destination hardware address not valid 10 Destination hardware address resolved OK LIBRARY NET LIB SEE ALSO udp_extopen arpresolve start arpresolve check udp waitopen udp_sendto
63. prior to inclusion of dcrtcp lib It is defined using the given values of the pre version 7 30 macros MY IP ADDRESS MX GATEWAY etc The IFCONFIG macros can be defined to be an arbitrary number of ifconfig parameters For example define IFCONFIG ETHON FS IPADDR aton 10 10 6 100 X FS NETMASK OXFFFFFFOOUL N IFS ROUTER ADD aton 10 10 6 1 X IFS ROUTER ADD STATIC aton 10 10 6 111 N aton 10 10 6 0 0xFFFFFFOOuL X FS DEBUG 5 ES ICMP CONFIG 1 N IFS UP Gi ri Gi ri sets up local IP address and netmask two routers turns the verbose level all the way up allows ping configure and finally specifies that the interface be brought up at boot time The final IFS UP is important if it is omitted then the interface will not be brought up at boot time you will need to call i fup explicitly after sock init For a full list of the parameters that you can specify in an IFCONFIG macro please see the documentation for ifconfig 2 6 7 Time Outs and Retry Counters RETRAN STRAT TIME This is used for several purposes It is the minimum time granularity in milliseconds of the retransmit process No time out is set less than this value It defaults to 10 ms TCP OPENTIMEOUT Defines the time out value in milliseconds for active open processing Defaults to 31000 ms TCP CONNTIMEOUT Defines th
64. receive a large number of packets without necessarily acknowledging them all In fact TCP only has 66 rabbit com Optimizing TCP IP Performance to acknowledge the most recent packet the sender can assume that all earlier packets are implicitly acknowledged How does all this apply to sizing of TCP socket buffers It basically means that there is little point in mak ing the buffers both transmit and receive larger than the expected maximum DBP of the communications channel For connections which are expected to traverse the Internet you may need quite large buffers For local Ethernet only the buffers need not be larger than say two packets The maximum packet size is a compromise between performance and memory usage The largest packet supported by dertcp lib is 1500 bytes which is dictated by the limits of Ethernet Dynamic C s default packet size is 600 bytes Using large packet sizes improves performance for bulk data transfer but has little effect for interactive traffic Performance is improved for large packet sizes mainly because there is less CPU overhead per byte There is a roughly fixed amount of CPU time required to process each packet This is obviously better utilized if there are a large number of bytes per packet When using Ethernet the Rabbit processor is limited in its overall TCP IP throughput by CPU power 10Base T Ethernet is capable of IMB sec for TCP sockets however the Rabbit 2000 running at 21 MHz will on
65. received 0 A timeout occurred before receiving the string LIBRARY MODEM LIB ModemHangup int ModemHangup void DESCRIPTION Sends ATH and ATZ commands RETURN VALUE 1 Success 0 Modem not responding LIBRARY MODEM LIB TCP IP Manual Vol 1 rabbit com 159 ModemInit int ModemInit void DESCRIPTION Resets modem with AT ATZ commands RETURN VALUE 1 Success 0 Modem not responding LIBRARY MODEM LIB ModemOpen int ModemOpen unsigned long baud DESCRIPTION Starts up communication with an external modem PARAMETERS baud The baud rate for communicating with the modem RETURN VALUE 1 External modem detected 0 Not connected to external modem LIBRARY MODEM LIB 160 rabbit com TCP IP Manual Vol 1 ModemReady int ModemReady void DESCRIPTION Returns true if the DSR line is asserted RETURN VALUE 1 DSR line is active 0 DSR inactive nothing connected LIBRARY MODEM LIB ModemRinging int ModemRinging void DESCRIPTION Returns true if the RI line is asserted meaning that the line is ringing RETURN VALUE 1 RI line is active 0 RI inactive nothing connected LIBRARY MODEM LIB TCP IP Manual Vol 1 rabbit com 161 ModemSend void ModemSend char send string DESCRIPTION Sends a string to the modem PARAMETERS send string A NULL terminated string to be sent to the modem
66. remport Port number of the remote host millisecs Number of milliseconds to wait for hardware address resolution Reason able values are between 50 and 750 milliseconds RETURN VALUE 20 Number of bytes sent 1 Failure invalid UDP socket etc 2 Failure timed out no datagram sent LIBRARY UDP LIB SEE ALSO udp_sendto udp recvfrom udp bypass arp 268 rabbit com TCP IP Manual Vol 1 udp_xsendto int udp_xsendto udp Socket s long buffer int len longword remip word remport DESCRIPTION Send a single UDP datagram on a UDP socket It will send the datagram to the IP address spec ified by remip and the port specified by remport Note that this function can be used even on a socket that has been connected to a remote host and port This function is identical to udp sendto except that the data address is specified as a physical address PARAMETERS s UDP socket on which to send the datagram buffer Buffer that contains the UDP datagram len Length of the UDP datagram remip IP address of the remote host remport Port number of the remote host RETURN VALUE 20 Number of bytes sent 1 Failure 2 Failure hardware address not resolved LIBRARY UDP LIB SEE ALSO udp_send udp_recv udp_recvfrom udp_open udp_sendto TCP IP Manual Vol 1 rabbit com 269 virtual _ eth int virtual_eth word real_iface longword ipaddr longword netmask void resv DESCRIPTION Create
67. socket using sock fastwrite and other non blocking write functions The available trans mit buffer space may be determined by sock tbleft function When TCP DH ESTAB is invoked the transmit buffer is normally completely empty so the callback can write a reasonable amount of data to start with The TCP DH INDATA event callback is invoked after the incoming data has been stored in the socket buffer It is only invoked if there is new data available from the peer The 11 Gather structure is set up with one or two physical address pointers to the new data and the logical pointer points to the IP header of the most recent datagram which provided the new data Usually there will be only one physical address however there may be two if the socket buffer happens to wrap around at that point The callback will need to be coded to handle this possibility if it is accessing the data directly out of the xmem buffer The TCP DH INDATA callback is allowed to modify the new data in place if desired This may be used to provide transparent decryption or similar services There are some restrictions which apply to callback code Primarily it is not allowed to invoke tcp tick directly or indirectly since that will cause recursion into tcp_ tick It will be possible to call sock fastwrite orudp sendto e g to generate some sort of response Since sock fastwrite needs to buffer data there is a possibility that there may be i
68. that can be sent or received A root data buffer of this size is allocated for DNS support DNS SOCK BUF SIZE 1024 by default Specifies the size in bytes of an xmem buffer for the DNS socket Note that this means that the DNS socket does not use a buffer from the socket buffer pool 2 6 5 Network Configuration Prior to Dynamic C 7 30 These macros should only be used for releases of Dynamic C prior to version 7 30 They are supported in newer releases of Dynamic C for backward compatibility however new applications should use the new style of configuration outlined in Network Configuration Starting with Dynamic C 7 30 on page 31 Use of the runtime functions mentioned in this section is deprecated in favor of ifconfig MY DOMAIN This macro is the initial value for the domain portion of the controller s address At runtime it can be overwritten by tcp config and setdomainname MAX DOMAIN LENGTH Specify the maximum domain name length including any concatenated host name Defaults to 128 MY GATEWAY This macro gives the default value for the controllers default gateway At runtime it can be overwritten by tep contig MY_IP_ADDRESS This macro is the default IP address for the controller At runtime it can be overwritten by tcp_config andsethostid MY NAMESERVER This macro is the default value for the primary name server At runtime it can be overwritten by tep contig MY NETMASK This macro is the default net
69. the interface number 1 byte RETURN VALUE Positive value Handle to the entry ATH UNUSED The table entry was unused AT H NVALID The ath parameter was not a valid handle or was a broadcast multicast or loopback handle ATH_OBSOLETE The given handle was valid but obsoleted by a more recent entry LIBRARY ARP LIB TCP IP Manual Vol 1 rabbit com 99 arpcache ipaddr ATHandle arpcache ipaddr ATHandle ath longword ipaddr DESCRIPTION Copy the IP address from the given ARP cache table entry into the specified area If the ath parameter refers to a broadcast entry then the subnet broadcast IP is returned PARAMETERS ath ARP cache table entry ipaddr Address of where to store the IP address 4 bytes RETURN VALUE Positive value Handle to the entry ATH UNUSED The table entry was unused ATH INVALID The ath parameter was nota valid handle or was a point point broadcast multicast or loopback handle ATH OBSOLETE The given handle was valid but obsoleted by a more recent entry T LIBRARY ARP LIB 100 rabbit com TCP IP Manual Vol 1 arpcache load ATHandle arpcache load ATHandle ath byte hwa byte iface word flags byte router used DESCRIPTION Load an entry in the ARP cache table The entry must have been created using arpcache create or be an existing valid entry located via arpcache search This function is primaril
70. this virtual interface This should be passed to any other function that requires the interface number to be specified LIBRARY NET LIB SEE ALSO ifconfig 270 rabbit com TCP IP Manual Vol 1 wif i s s id to s tr far char wifi ssid to str char far dest char far ssid int len DESCRIPTION This function creates a null terminated string of printable characters from a given SSID Since the SSID can contain any byte including nulls and characters gt 0x7F you can use wifi ssid to stri to create a printf safe string PARAMETERS dest Pointer to a 33 byte buffer to receive the printable string ssid Pointer to a 0 to 32 byte SSID len Length of SSID RETURN VALUE Returns pointer to user supplied 33 byte buffer dest containing printf safe string NOTE To perform the conversion in place re use the buffer int i char b 33 ifconfig IF WIFIO IFG WIFI SSID amp i b IFS END printf SSID sis n wifi said to str b b diy LIBRARY WIFI WLN API LIB SEE ALSO ifconfig IFG WIFI SSID option TCP IP Manual Vol 1 rabbit com 271 272 rabbit com TCP IP Manual Vol 1 Index Numerics D 2MS I tees RE eae 266 daemons 3 way handshake iese ees se ee Re ee ee ee ee 57 ode SR ea e een EE 267 data handler callbacks s m ee ee ee Ge RARR 69 A DCRTCP DEBUG ee ee ee 45 ARP CONFLICT CALLBACK see 90 DERTCP VERBOSE sis
71. to 4 or 0 On a Rabbit 3000 board the value will be 6 or 0 An additional macro USING PPP is also defined if any of the PPP type interfaces are in use Unlike the above macros this macro is either defined or not defined so the correct test is ifdef 6 rabbit com TCP IP Initialization 2 1 3 Single Interface Support Backwards compatibility exists for applications compiled with earlier versions of Dynamic C If none of the USE macros are defined then the old behavior pre Dynamic C 7 30 is used which is to include one and only one link layer driver 2 1 3 1 Configuration Macros for Link Layer Driver Single Interface CH Do not define either of these macros if any of the USE macros are defined PKTDRV This macro specifies the packet driver to use Include one of the following statements in your application define PKTDRV realtek lib Touse Ethernet define PKTDRV ppp lib Touse PPP serial or Ethernet PPPOE This macro is defined to use PPP over Ethernet when PKTDRV is set to ppp Lib For other packet drivers this define has no effect but should not be defined in order to avoid problems with future Dynamic C releases define PPPOI GI 2 1 4 TCP IP Stack Initialization The function sock init must be called near the start of your main function in order to initialize the TCP IP stack The return value from sock init must indicate success before calling any o
72. to configure a Wi Fi network interface is to use an open configuration This means that no encryption or authentication is used This example is configured for infrastructure mode which means that you will also need a Wi Fi access point or Wi Fi router Note that your wireless access point will need to match these settings in particular the SSID must be the same and the AP must not have encryption enabled To configure within your program copy and paste the following into your sample program and modify as necessary define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define PRIMARY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 define MY NAMESERVER 10 10 6 1 define IFC WIFI SSID rabbitTest define IFC WIFI ROAM ENABLE 1 define IFC_WIFI_ROAM BEACON MISS 20 define IFC WIFI MODE IFPARAM WIFI INFRASTRUCT define IFC WIFI REGION IFPARAM WIFI REGION AMERICAS define IFC WIFI ENCRYPTION IFPARAM WIFI ENCR NONE Alternatively you can configure within the Defines window Here is an example to copy and paste into the Defines window and modify as necessary TCPCONFIG 1
73. used exclusively in server mode 1 e TCP sockets opened passively then the cache does not have to be very big If on the other hand the controller is going to actively establish sessions with a number of hosts then the cache should be big enough to contain an entry for each host such that entries do not get pushed out for at least a few minutes The ARP Table also contains special entries for routers that are on the local Ethernet These entries are important since they represent entries for all hosts that are not on the local LAN segment subnet The default sizing rule for the ARP Table allocates an entry for each interface including point to point plus 5 entries for each Ethernet interface in use The single entry for each interface is basically reserved for routers on the assumption that each interface will probably require a router to allow connections to hosts which are farther afield The additional 5 entries for Ethernet are for non router hosts that the controller board will need to talk to TCP IP Manual Vol 1 rabbit com 73 This implies that 5 connections to hosts on the Ethernet subnet can be supported simultaneously without any of the entries being pushed out If the table is full connection to a 6th host can be made with the least recently used host entry being pushed out to make room If your application connects with say ten hosts in random order it is likely that the ARP Table will need to be increased in
74. uses 4 bits to specify different types of service For normal service all 4 bits are zero Different applications will want different types of service For example SNMP might set the maximize reliability bit whereas FTP would want maximize throughput e IPTOS DEFAULT is normal service e IPTOS CHEAP minimizes monetary cost e IPTOS RELIABLE maximizes reliability e IPTOS CAPACIOUS maximizes throughput TCP IP Manual Vol 1 rabbit com 35 e IPTOS FAST minimizes delay e IPTOS SECURE maximizes security Note that you may not OR these values together You must pick one only TTL Time to Live specifies how many routers a packet may visit before it is discarded or how many seconds it can remain in the network whichever comes first TCP TTL Default TTL of TCP segments This value is from Internet STD0002 Defaults to 64 TCP_TOS Default type of service for TCP Defaults to IPTOS DEFAULT UDP TTL Default TTL of UDP datagrams This value is from Internet STD0002 Defaults to 64 UDP_TOS Default type of service for UDP Defaults to IPTOS DEFAULT ICMP_TOS Default type of service for ICMP Defaults to IPTOS DEFAULT 2 6 10 Wi Fi Configuration Macros To configure a Rabbit device for a Wi Fi network connection you will need to define a number of macros As shown in Wi Fi Compile Time Configuration on page 17 these can be defined in either the C program or the D
75. 1 42 SOCK BUF SIZE see esse ss sesse ee se ee ee se og se 40 program debugging o see Re Re Re Re ee 45 socket removing unwanted functionality eee eee 35 abort EE 107 timers and Counters 0 0 eek se ee Ge ee AR be 44 e E 55 TOS and RN KEE 46 data structure esse ee see se ee Ge ee ee ee GR eke 54 MAX COOKIES rarka pariar ERRE 41 default mode ii i EE es EE ee see ese Dee 60 MAX DOMAIN LENGTH co esse esse se see see 42 ee 54 MAX NAMESERVERS ccceccesceeeeeeeeeeeeeeeeees 41 empty line vs empty buffer Lee 209 MAX RESERVEPORTS es sesse se see se ene se ene ee 4 ee 73 224 MAX SOCKET LOCKS oc ese sesse see se ee ee ee 39 73 stack MAX SOCKETS ees sesse see see se ee ee ek ek ee GR eke 39 Configuration esse sesse se ee Ge ee ee ee Ge eke 3 8 MAX STRING eee ee se ee Ge Ge ee AR Ge GR ke 41 initializatien 53 sie aE EE RE et 7 MAX TCP SOCKET BUFFERS 39 260 MAX UDP SOCKET BUFFERS ee 40 T GREEN GRAN i ke a p AICP eG EE 53 modem library KEE SE 96 ACV OPEN sis scssscdetncgste deacegentonapsansivatitevdenieaioestens 57 MSS maximum segment size Lm 40 control functions iese see ee ee ee ek ek ee 58 MTU ae EE 216 WED BA OOG N N eee 60 multicasting EE EE 93 270 blocking ie ee 69 multitasking issie ek ES ge Rage ig ES Ee NESER ee 73 non blocking L 68 MY DOMAIN un 40 42 listen Queue se ie REELE GE SO ele 58 MY GATEWAY En 42 PASSIVE OPEN re 56 MY IP ADDRESS Lm ese ee ee ese ee ee gee 42 TCP IP egener GATE OE 66 MY _NETMASK un
76. 1 Eo SOCket So lkenz 2 define MAX BUFSIZE char bufl MAX BUFSIZE i i i i f E Gat D D 1 1 al IE The function that actually ona ME BASIE El auto int length 2 ADDRESS 0 1056521 WS OO Oke Ore Oly TEE EE 2048 2 buf2 MAX BUFSIZE does the TCP work ll eco Socket te me m Gimes om space avaliable cep liscen e POTE WO O NULL 3 wait for a connection mb let tel Sock lnycesmeachy S amp amp 0 Sock establishes give other tasks time to do things while we are waiting yield Wile soek esiesloll i sineel s space avaliable imit transfer size if space avaliab space avaliab getsome data length SOCK ia slit tement gt 0 4 buf length SOC iclolleutic e to MAX BUFSIZE leave room for NO le gt MAX BUFSIZE 1 le MAX BUFSIZE 1 Seveacd S lout space _ewvellialole p did we receive any data NOME print it to the Stdio window primei MS lowe y send it back out to the user s telnet session sock fastwrite will work we verified the space beforehand soek rastin lte Ss bur yield SOCK close Ss p return ip length give other tasks time to run 62 rabbit com TCP and UDP Socket Interface Program Name costate_tcp c continued TCP IP Manual Vol 1 rabbit com 63 64 rabbit com TCP and UDP Socket Interface
77. 1 13 IFPARAM WIFI REGION MEXICO INDOORS 1 11 IFPARAM WIFI REGION MEXICO OUTDOORS 9 11 Setting the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted IFG_WIFI_REGION Get region number int See set command for more information IFG WIFI REGION INFO Get region settings wifi region The wifi region structure contains the following elements typedef struct char id IFPARAM WIFI REGION char country 16 description of region int first channel int last channel unsigned int channel mask int max pwr dBm int max pwr index wifi region IFS WIFI MODE Set operating mode int Valid parameters are e IFPARAM WIFI ADHOC e IFPARAM WIFI INFRASTRUCTUR GI Setting the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted 136 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFG WIFI MODE Get operating mode int IFS WIFI CHANNEL Set channel int See TFS WIFI REGION for more information about available chan nels If using infrastructure mode can be set to 0 for automatic channel selection Setting
78. 19 getsockname int getsockname sock type ze void dest int len DESCRIPTION Gets the controller s IP address and port information for a particular socket PARAMETERS s Pointer to the socket dest Pointer to sockaddr to hold the socket information for the local end of the socket The data structure is typedef struct sockaddr word s type reserved word s port port or 0 not connected longword s ip IP addr or 0 if not connected byte s_spares 6 notused for tcp ip connections 1 len Pointer to the length of sockaddr A NULL pointer can be used to repre sent the sizeof struct sockaddr BSDNAME LIB will assume 14 bytes if a NULL pointer is passed RETURN VALUE 0 Success 1 Failure LIBRARY BSDNAME LIB SEE ALSO getpeername 120 rabbit com TCP IP Manual Vol 1 htonl longword htonl longword value DESCRIPTION This function converts a host ordered double word to a network ordered double word This function is necessary if you are implementing standard internet protocols because the Rabbit does not use the standard for network byte ordering The network orders bytes with the most significant byte first and the least significant byte last On the Rabbit the bytes are in the oppo site order PARAMETERS value Host ordered double word RETURN VALUE Host word in network format e g htonl 0x44332211 returns 0x11223344 LIBRARY NET LIB Prior to DC 7 05 t
79. 2 PPPoE Port Selection 87 3 11 1 UDP Data Handler 59 7 6 3 ifconfig Options for PPP 88 3 11 2 TCP Data Handler ee 59 7 6 4 ifconfig Options for Serial PPP 89 3 12 Multitasking and TCP IP ee ee 61 7 6 4 1 Additional Rules for Send Ex 3 DT UEOOSAE ESE ad 61 pect Scripts ses ei Rek 90 3 12 1 1 Interrupt Driven or DMA 7 6 5 Starting and Stopping PPP Interfaces Driven Network Interface s 61 91 3 12 1 2 Polled Mode Only Network In 8 Function Reference ese ee 93 terface S A ia ea isa 61 54109 Caoperilive EN 62 e ske i ath ele 95 Wa arpcache create 96 4 Optimizing TCP IP Performance 65 arpcache IUS ies ged EG eren 97 4 1 DBP and Sizing of TCP Buffers 0 66 arpeache Nwas ie GE ee 98 4 2 TCP Performance Tuning en 68 arpcache iface iese ee ek ee 99 4 2 1 The Nagle Algorithm 68 f A22 Time Oul Settings miannan 69 arpcache ipaddr esse sesse ee ee ee 100 42 2 1 Time Out Setting Constants 70 arpcache load RE si Gee Re EE Ee 101 4 2 3 Reserved Ports semen 72 arpcache search en 103 4 2 4 Type of Service TOS Le 73 arp gGetAmmfiata eee esse sesse esse ee 104 4 2 5 ARP Cache Considerations 73 arp getArpGateData esse sesse 104 4 3 Writing a Fast UDP Reguest Response Server EE RSA AA DE ON 105 74 Ke arpresolve check 106 4 4 Tips and Tricks for TCP Applications 74 arpresolve Ipaddt ees ee
80. 5 255 0 Then given a destination IP address which is not on the local subnet 10 10 6 0 the rout er will be selected according to the following algorithm if address is 10 99 57 use 10 10 6 3 else if address is 10 99 use 10 10 6 2 else use 10 10 6 1 Note that IFS ROUTER SET is basically the same as IFS ROUTER SET STATIC except that the subnet and mask parameters are automatically set to zero Most simple net works with a single router to non local subnets will use a single LFS_ROUTER_SET This parameter does not care about the value of iface because it is not specific to an in terface IFS_ROUTER_ADD Add general router longword This parameter identifier does not care about the value of iface because it is not specific to an interface IFS ROUTER ADD STATIC Add static router IP address of router longword subnet served longword subnet mask longword See IFS ROUTER SET STATIC for a definition of static router This parameter does not care about the value of iface because it is not specific to an in terface rabbit com TCP IP Manual Vol 1 ifconfig cont d IFS_ROUTER_DEL Delete router longword If identifier s parameter 0 delete all routers This parameter does not care about the value of iface because it is not specific to an in terface IFG ROUTER DEFAULT Get default router longword The interface paramet
81. 55 255 0 New method of setting network addresses define TCPCONFIG 1 memmap xmem Zuse dertcp lib perine TELNET PORT 23 SACLE cep Sockec sp Chaz wse iriely telnets int port ECO SOCKSt sis dee Chew loivititeie SiL2 Lime SiEAiEUSS s amp telnetsock tep listcem S Port Ohl O NULL On while lsock Esicalolisiase sj ce soek lsvieesrecclw 2 IL i tcp tick NULL puts Receiving incoming connection SOCK model S WP MODE ASC SOCK jpues s WNellcome to a aale telnet sever sock ur sen line you type will be printed ony this screen once you hit return other guy closes connection except if we timeout do ii soek lycesxeacdy Ss gt 0 d SOCK GStS S luxrer sizeof die si IL 5 Pd AG EE ie b waile tep ielk 8 main SOCK Zen telnets TELNET PORT 9 exit 0 TCP IP Manual Vol 1 rabbit com 251 tcp_open int tcp_open tcp Socket s word lport longword remip word port dataHandler t datahandler DESCRIPTION This function actively creates a session with another machine After a call to tcp open the function sock established orthemacro sock wait established must be called to poll the connection until a session is fully established It is possible for a connection to be opened written to and closed between two calls to the func tion sock established To handle this case call so
82. CP stack to begin with This is still useful in the case that one of the other configuration techniques can at least get to a working state For example directed ping can assign an IP address You could then use the same host to telnet into the new IP address in order to set other items like the netmask and router 2 2 3 Media Access Control MAC Address Rarely ISPs require that the user provide them with a MAC address for their device Run the utility program Samples tcpip display mac c to display the MAC address of your controller board The MAC address is also required for directed PING configure as well as some other bootstrap techniques MAC addresses are often written as a sequence of six two digit hexadecimal numbers separated by colons e g 00 90 20 33 00 A3 This distinguishes them from IP addresses which are written with dotted decimal numbers MAC addresses are completely unrelated to IP addresses IP addresses uniquely identify each host on the global Internet MAC addresses uniquely identify Ethernet hardware on a particular Ethernet LAN 14 rabbit com TCP IP Initialization segment Although only technically required to be unique on a LAN segment in practice MAC addresses are globally unique and can thus be used to uniquely identify a particular Ethernet adapter The usual reason for an ISP requiring a MAC address is if the ISP uses DHCP to dynamically assign IP addresses Most ISPs use PPP Point to Point Protocol whic
83. DR always sets the DHCP fallback address but you can also use the IFS_DHCP_FB_IPADDR parameter to set the fallback address without ever changing the i f status IFG DHCP FB IPADDR Get the DHCP fallback IP address longword See the description above for IFS DHCP FB IPADDR for more information IFG DHCP FELLBACK Get whether DHCP actually had to use fallbacks bool TCP IP Manual Vol 1 rabbit com 129 ifconfig cont d IFS_DHCP_OPTIONS Set DHCP custom options int char int DHCP custom options processing First parameter int is length of options list The sec ond parameter char points to that options list This is a byte array containing values from the DHCP_VN_ definitions in BOOTP LIB these are taken from the list in RFC2132 Also option 0 is used to indicate the boot file name If the boot file name is provided then the TFTP server IP address can be obtained from the di gt bootp_host field of the structure provided to the callback see below This options list must be in static storage since only the pointer is saved The third parameter may be NULL or is a pointer to a callback function to process the custom options The callback function has the following prototype int my _ callback int iface DHCPInfo di int opt int len char data iface interface number di DHCP information struct Read only except you can mod if
84. E DNS The application program has to do two things to resolve a host name 1 Call resolve name start to start the process 2 Call resolve name check to check for a response Call resolve cancel to cancel a pending lookup 5 4 Configuration Macros for DNS Lookups DISABLE DNS If this macro is defined DNS lookups will not be done The DNS subsystem will not be com piled in saving some code space and memory DNS_MAX RESOLVES 4 by default This is the maximum number of concurrent DNS queries It specifies the size of an internal table that is allocated in xmem DNS MAX NAME 64 by default Specifies the maximum size in bytes of a host name that can be resolved This number includes any appended default domain and the NULL terminator Backwards compati bility exists for the MAX DOMAIN LENGTH macro Its value will be overridden with the value DNS MAX NAME if it is defined For temporary storage a variable of this size must be placed on the stack in DNS processing Normally this is not a problem However for u C OS II with a small stack and a large value for DNS MAX NAME this could be an issue DNS MAX DATAGRAM SIZE 512 by default Specifies the maximum length in bytes of a DNS datagram that can be sent or received A root data buffer of this size is allocated for DNS support DNS_RETRY_TIMEOUT 2000 by default Specifies the number of milliseconds to wait before r
85. F DEFAULT IF UP came up OK else failed to come up PARAMETERS iface Interface number Use one of the definitions e IF DEFAULT e IF ETHO e IF ETHI e IF WIFIO F PPPOEO e IF PPPOE1 e IF PPPO 5 If the interface does not exist vou will get a compile time error F DEFAULT refers to the default interface which will be equivalent to the first of the other interface identifiers in the above list which exists RETURN VALUE 0 If interface is currently down and not pending up 1 If interface is currently down and pending up 2 If interface is currently up and not pending down 3 If interface is currently up and pending down Rather than the above constants you should use the macros IF DOWN IF COMING UP IF UP and IF COMING DOWN LIBRARY NET LIB SEE ALSO ifconfig ifdown ifup ifstatus TCP IP Manual Vol 1 rabbit com 147 ifstatus int ifstatus int iface DESCRIPTION This macro returns the status of the specified interface PARAMETER iface Interface number Use one of the definitions e IF DEFAULT e IF ETHO e IF ETHI e IF WIFIO e I F PPPOEO e IF PPPOE1 e IF PPPO 5 If the interface does not exist then vou will get a compile time error F DEFAULT refers to the default interface which will be equivalent to the first of the other interface identifiers in the abov
86. G PPP2 N other parameters X IFS PPP REMOTEAUTH mvUserid myPassword other parameters The general PPP properties set during initialization are Table 7 4 Macros for PPP Initialization Serial and Ethernet Macro Name Macro Description lid dead IFS PPP ACCEPTIP Accept peer s idea of our local IP address bool IFS PPP REMOTEIP Trv to set IP address of peer longword IFS PPP ACCEPTDNS Accept a DNS server IP address from peer bool TES PPP REMOTED Set DNS server IP addresses for peer longword SS primary and secondary longword Called when a peer attempts to IFS PPP AUTHCALLBACK me aa authenticate int IFS PPP INIT Sets up PPP with default parameters none Sets username and password to give to IFS PPP REMOTEAUTH OE char char Reguired username and password for incoming peer IFS P U P LOCALAUTH char char All of these IFS PPP macros except the initialization and callback have IFG PPP versions that allow an application to look at the current properties 88 rabbit com PPP Driver 7 6 4 ifconfig Options for Serial PPP The ifconfig parameter identifiers described in this section pertain to serial PPP interfaces only If you specify these options for PPPoE interfaces they will be quietly ignored They may also be specified in the appropriate IFCONFIG PPP
87. GR RR GR RA T 186 Modeminit iese ee ee RA GR RA 172 id AE AE EE a 187 ModemOpen eee sees ee ge ee ek ke ee 172 resolye cancelen is ie 188 ModemReadv um see es se ee eke 173 resolve name check eee 189 ModemRinging eee ses see se ee ee se ee 173 resolve name start eerren 190 Modem Send 174 router add es EE ESE Ee ma Ee 192 ModemStartPPP 174 i uter del all EE ae Ee tlie 193 Multicast Touter delete uie See Re SE AR GE ents 193 Multicast jOINQTOUP iese ese ees see ee ee 175 router Tor Le ee ee Re GR ER RA GR RR 194 multicast leavegroup iee sees se see eee 176 router for Tage ss EERS SKEER EE Ee 195 Ping FOULED PIE 2 50 05 a a ED ER TREE ie 197 elke E 124 router printall L ese see ese ek Ge Ge ee ee 198 B OE N EO EE 183 setdomainname LL se se ee ek Ge ie 200 send RE 199 e EE 201 PPP sethostname 0 0 ceeeseeceseeseeeecseeeeeceaeeeees 202 PPP acti EE HE 184 Udp bypass Arp Less 268 PPPnegotiatelP ee ee ee Ge 184 Configuration PPPsetAuthenticatee mn 185 ie vel OE AO eb 135 PPPsetAuthenticator se 185 tep COMA eier iet 258 PPPshutdown see ee Ge ge ee ek ke 186 Wall oe EE EE N EE 26 Socket Configuration Data Conversion sock mode ee ese ee ee ee ee ek ke 224 EE EE 123 SOCK set OS ER REEKSE GE ER Ee Re 241 oe al ere rere A rere ee OE 133 SOCK Set Milli i irgiel 242 ICONS isir N a e 134 tep clearreserve e ee ee ee 257 E E 163 tcp reserveport oo siese ee ee ee ee 266 inet MOS s
88. K Get whether DHCP actually configured OK bool IFS DHCP TIMEOUT Set DHCP overall timeout in seconds int 128 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFG DHCP TIMEOUT Get DHCP overall timeout in seconds int IFS_DHCP_QUERY Set whether DHCP uses INFORM bool This parameter specifies that DHCP INFORM message is used for Ethernet interfaces and is applicable if the IP address is configured other than by DHCP The parameter is always TRUE for PPP interfaces IFG DHCP OUERY Get whether DHCP uses INFORM bool IFS DHCP DOMAIN Set whether to use domain and or hostname information bool IFG DHCP DOMAIN Get flag setting bool IFS DHCP FALLBACK Set whether DHCP allows fallback to static configuration bool IFG DHCP FALLBACK Does DHCP allow fallback to static configuration bool IFS DHCP FB IPADDR Set the DHCP fallback IP address longword The DHCP fallback address parameters are used in preference to IFS_IPADDR the current address This indicates the static IP address to use in case DHCP could not be used to configure the interface The action of IFS _IPADDR depends on the current interface state If the i f has the IFS DHCP flag set then this parameter sets only the fallback IP address without chang ing the current i f status Otherwise the i f is reconfigured with the new address immedi ately which may require it to be brought down then up IFS_ IPAD
89. Macros tcp set binarv s andtcp set ascii s TCP MODE NAGLE default TCP MODE NONAGLE The Nagle algorithm may substantially reduce network traffic with little negative effect on a user In some situations the Nagle algorithm even improves application perfor mance The default is TCP MODE NAGLE This mode only affects TCP connections Equivalent Macros tcp set nagle s andtcp set nonagle s 212 rabbit com TCP IP Manual Vol 1 sock mode cont d UDP MODES UDP MODE CHK UDP MODE NOCHK Checksums are required for TCP but not for UDP The default is UDP MODE CHK If you are providing a checksum at a higher level the low level checksum may be re dundant The checksum for UDP can be disabled by selecting the UDP_MODE_NOCHK flag Note that you do not control whether the remote computer will send checksums If that computer does checksum its outbound data DCRTCP LIB will check the re ceived packet s checksum Equivalent Macros udp set chk s andudp set nochk s UDP MODE NOICMP default UDP MODE ICMP Marks this socket for receipt of ICMP error messages The messages are queued like normal received datagrams and read using udp recvfrom which returns 3 when ICMP messages are returned instead of normal datagrams Only ICMP messages which are relevant to the current binding of the socket are queued Equivalent Macros udp set noicmp s andudp set icmp s UDP MODE NODICMP default UDP
90. Note that the code for this encryption method is not compiled unless you define the macros WIFI_USE WPA and WIFI AES ENABLED To configure within your program copy and paste the following into your sample program and modify as necessary for your situation define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define PRIMARY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 define MY NAMESERVER 10 10 6 1 define WIFI USE WPA define WIFI_AES ENABLED define IFC WIFI SSID rabbitTest define IFC WIFI ROAM ENABLE 1 define IFC_WIFI_ROAM BEACON MISS 20 define IFC WIFI MODE IFPARAM WIFI INFRASTRUCTURE tdefine IFC WIFI REGION IFPARAM WIFI REGION AMERICAS tdefine IFC WIFI ENCRYPTION IFPARAM WIFI ENCR CCMP You will also need to define WPA2 s pre shared key mode This can be done by specifying a passphrase that the driver will expand to a 256 bit key or by specifying the 256 bit key itself Note that expanding a passphrase takes a significant amount of time at startup up to about 20 seconds Define WIFI VERBOSE PASSPHRASE to see status messages when the key is generated from the passphrase To specify the WPA2 passphrase you wil
91. OR WI FI ROAMING IFS WIFI ROAM ENABLE Set roaming state on off bool IFG WIFI ROAM ENABLE Get roaming enabled state bool IFS WIFI ROAM BEACON MISS Set number of beacons that must be missed consecutively before a scan for a new access point is initiated int IFG WIFI_ROAM BEACON MISS Get number of beacons that must be missed consecutively before a scan for a new access point is initiated int COMMANDS FOR WPA WPA2 IN ENTERPRISE MODE IFS WIFI WPA PROTOCOL IFG WIFI WPA PROTOCOL Set Get acceptable security protocol s word word Default is to support both WPA and WPA2 e IFPARAM W e IFPARAM W e IFPARAM W e IFPARAM W 1 WPA PROTOCOL WPA WPA aka IEEE 802 11i D3 0 I WPA PROTOCOL WPA2 WPA2 aka IEEE 802 11i D9 0 I_ WPA PROTOCOL RSN WPA2 aka IEEE 802 11i D9 0 1 WPA PROTOCOL ALL A bitwise combination of all protocols D F D D IFS WIFI PAIRWISE ENCRYPTION IFG WIFI_PAIRWISE ENCRYPTION Set Get Wi Fi pairwise encryption types word word T Valid values are e IFPARAM WIFI ENCR TKIP ValidifWIFI USE WPA is defined e IFPARAM WIFI_ENCR_CCMP Valid if both USE_WPA and VIFI AES ENABLED are defined e IFPARAM WIFI ENCR NONE Use only Group Keys deprecated should not be included if APs support pairwise keys H 142 rabbit com TCP IP Manu
92. P IP Manual Vol 1 sock rbleft int sock_rbleft void s DESCRIPTION Determines the number of bytes available in the receive buffer PARAMETERS s Pointer to a socket RETURN VALUE Number of bytes available in the receive buffer LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock rbsize sock rbused sock tbsize sock tbused sock tbleft TCP IP Manual Vol 1 rabbit com 219 sock rbsize int sock_rbsize void s DESCRIPTION Determines the size of the receive buffer for the specified socket PARAMETERS s Pointer to a socket RETURN VALUE The size of the receive buffer LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock rbleft sock rbused sock tbsize sock tbused sock tbleft 220 rabbit com TCP IP Manual Vol 1 sock rbused int sock rbused void s DESCRIPTION Returns the number of bytes in use in the receive buffer for the specified socket PARAMETERS s Pointer to a socket RETURN VALUE Number of bytes in use LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock rbleft sock tbsize sock tbused sock tbleft TCP IP Manual Vol 1 rabbit com 221 sock read int sock read Cep Socket s byte dp int Leni DESCRIPTION Reads up to Len bytes from dp on socket s This function will busy wait until either Len bytes are read or there is an error condition If sock vield has been called the user defined functio
93. PP LIB psocket void psocket void Sei DESCRIPTION Given an open UDP or TCP socket the IP address of the remote host is printed out to the Stdio window in dotted IP format followed by a colon and the decimal port number on that machine This routine can be useful for debugging your programs PARAMETERS s Pointer to a socket RETURN VALUE None LIBRARY BSDNAME LIB 174 rabbit com TCP IP Manual Vol 1 resolve longword resolve char host string DESCRIPTION Converts a text string which contains either the dotted IP address or host name into the long word containing the IP address In the case of dotted IP no validity check is made for the ad dress NOTE this function blocks Names are currently limited to 64 characters If it is necessary to lookup larger names include the following line in the application program define DNS MAX NAME lt len in chars gt If DISABLE DNS has been defined resolve will not do DNS lookup If you are trying to resolve a host name you must set up at least one name server You can set the default name server by defining the MY NAMESERVER macro at the top of your program When you call resolve it will contact the name server and request the IP address If there is an error resolve will return OL To simply convert dotted IP to longword see inet addr For a sample program see the Example Using tcp open listed under tcp open
94. PPP Since multiple interfaces are supported your application should call ifconfig to change PPP inter face parameters at run time or define suitable IFCONFIG PPP macros for boot time configuration of each PPP interface both serial and PPPoE You select serial port hardware to use with PPP by defining USE PPP SERIAL before including dcrtcp lib Similarly you select PPPoE by defining USE_PPPOE before including dertcp lib 7 6 1 Serial Port Selection PPP over asynchronous serial requires a suitable Rabbit serial port to be selected You can use any of the available ports since they all support asynchronous communications The serial port selection is entirely dynamic however there is a fixed mapping between interface numbers and serial port hardware IF PPPO always represents serial port A IF PPP1 is always serial port B and so on The serial port hardware to use is determined by the USE PPP SERIAL macro which your application defines in order to specify PPP serial interfaces USE PPP SERIAL is set to a bitwise OR combination of numbers representing the desired serial port s Ports are assigned according to the following table Table 7 3 Bitmap Values for USE_PPP_SERIAL Interface Number Serial Port Bitmap Value IF PPPO SERA 0x01 IF PPPI SERB 0x02 IF PPP2 SERC 0x04 IF PPP3 SERD 0x08 IF PPP4 SERE 0x10 IF PPPS SERF 0x20 If
95. RR constant as defined in NETERRNO LIB This code is set as the error code for each socket that was affected iface Specific interface on which active connections are to be aborted or pass IF_ANY to abort connections on all active interfaces RETURN VALUE 0 LIBRARY net lib SEE ALSO sock abort sock error TCP IP Manual Vol 1 rabbit com arpcache create ATHandle arpcache create longword ipaddr DESCRIPTION Create a new entry in the ARP cache table for the specified IP address If a matching entry for that address already exists then that entry is returned Otherwise a new entry is initialized and returned If a new entry is created then an old entry may need to be purged If this is not possi ble then ATH NOENTRIES is returned PARAMETER ipaddr IP address of entry RETURN VALUE Positive value Success ATH NOENTRIES No space is available in the table and none of the entries could be purged because they were all marked as permanent or router entries LIBRARY ARP LIB 96 rabbit com TCP IP Manual Vol 1 arpcache flush ATHandle arpcache flush ATHandle ath DESCRIPTION Mark an ARP cache table entry for flushing This means that the given table entry will be the first entry to be re used for a different IP address if necessary Any entry including permanent and router entries may be flushed except for the broadcast entry PARAMETER ARP table handle obtained fro
96. SHOLD Get fragment threshold int IFS WIFI RTS THRESHOLD Set RTS request to send threshold valid values are 1 2347 IFG WIFI_RTS THRESHOLD Get RTS threshold int 138 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFS WIFI SCAN Initiate a Wi Fi scan of all valid channels for the current region A pointer to a scan call back function is the only parameter The callback function must have the following func tion prototype root void scan callback far wifi scan data data When the scan has completed the scan callback function is called The Wi Fi scan can be done without taking the interface down but it will briefly interrupt the network connec tivity as it scans the channels on the wireless network The scan data is provided to the callback function in its data parameter The wifi scan data structure has the following definition typedef struct int count wifi win scan bss baal WIFI SCAN NUM wifi scan data WIFI SCAN NUM issetto 16 in wifi wln api lib count contains the number of ac cess points that were detected bss is an array where each element corresponds to a de tected access point wifi wln scan bss has the following definition typedef struct uint8 ssid WLN SSID SIZE network name up to 32 bytes long int ssid len number of bytes in the SSID int channel Wi Fi net
97. SIZE In Dynamic C versions 6 56 and earlier tcp MaxBufSize determines the size of the input and output buffers for TCP and UDP sockets The sizeof tcp Socket will be about 200 bytes more than double tcp MaxBufSize The optimum value for local Ethernet connections is greater than the Maximum Segment Size MSS The MSS is 1460 bytes You may want to lower tcp MaxBufSize which defaults to 2048 bytes to reduce RAM usage It can be reduced to as little as 600 bytes tcp MaxBufSize will work slightly differently in Dynamic C versions 6 57 and higher In these later versions the buffer for the UDP socket will be tcp_MaxBufSize 2 which is twice as large as before UDP BUF SIZE Starting with Dynamic C 7 05 TCP and UDP socket buffers are sized separately UDP BUF SIZE defines the buffer sizes for UDP sockets It defaults to 4096 bytes Backwards compatibility exists with earlier version of Dynamic C if SOCK BUF SIZE is defined UDP BUF SIZE is assigned the value of SOCK BUF SIZE IfSOCK BUF SIZE is not defined but tcp MaxBufSize is then UDP BUF SIZE will be assigned the value of tcp MaxBufSize 2 ETH MTU Define the Maximum Transmission Unit for Ethernet and PPPoE interfaces The default is 600 but may be increased to a maximum of 1500 subject to root data memory limitations PPPoE always uses a value that is 8 les
98. SOCKS ESOC SEEK men if host resolve ADDRESS jovies Coula mor resolwe Mose exit 3 POE Soit PORT jg printi Ac ee 1ng to open SS on port Uar ADDRESS port lir Hen Open EcSOck 0 Most Ort NULL bi d puts Unable to open TCP session exit G printf Waiting a maximum of Su seconds for connection w to be established nirc ese lean while enee established etsek CE SOCK oycesreaciy esoclk 1 i See ekk NULG puts Socket is established sock close sesoek exit 0 TCP IP Manual Vol 1 rabbit com 253 tcp_reserveport void tcp reserveport word port DESCRIPTION This function allows a connection to be established even if there is not yet a socket available This is done by setting a parameter in the TCP header during the connection setup phase that indicates 0 bytes of data can be received at the present time The requesting end of the connec tion will wait until the TCP header parameter indicates that data will be accepted The 2MSL waiting period for closing a socket is avoided by using this function The penalty of slower connection times on a controller that is processing a large number of con nections is offset by allowing the program to have less sockets and consequently less RAM us age PARAMETERS port Port to use RETURN VALUE None LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tcp open tcp
99. Socket VO es TAMA 205 h st BFOUD i esse ee ee ee Ge RA GR RA GR tran nanna enza 93 SOCK SHEET EE RE Ee ee De 206 l sock axread ee ee ee Re Re 207 sock AXWTite uie ee 208 ICMP TOS iese dee seges Be seen ede Bees eg Gee De Re DEGREE 47 sock fastread uie ee ee 215 TE EE EE AE EE Ed 4 SOCK fAStWTite use ee 216 TEC ONFIG ER RE OE EE 43 EE EE N 217 id RE RE gege geen 93 sock flushnext ee ee ee Ee Ge Re 218 interfaces sock gete N 219 Cophetratpeg iii iii i ve 8 14 SOCK Gets Loss sneenennenzznsnznznnezzznsnsnnenan 220 enable disable support L nn 5 sock preread ee ee 228 SE RE N OE EE kite 7 SOCK pute ius ee ee 229 sum of physical sesse se se ee eek ee Ge ek Ge Re Ge 6 TE EE N 230 supported types oo eie see ee ee ee ee ee 3 sock stead 7 EE Ee Eie en 234 IP addresses E N N NN 253 broadcast packets iese ee ee Re 61 63 sock xfastread ee ee 254 E E 9 42 sock _xfastwrite ee ee 255 directed ping wisk ik EE nie Liber see 13 sock Yield creci e EE gee EE 256 dynamic configuration ss se seek ee ee ek ee 11 top extlisten ee ee nieee 259 last used DHCP server sesse se ese ee ek ee ee Ge 38 ICP EXIOPEN EE 260 last usedBOOTP TFTP server esse ees 38 tep EE 262 EE EE AE OE Ad 11 38 OP OPEN ee ee ee ee 264 MAN SELVEL ER EL atau N Eg RE 39 TCP IP Stack origin of received datagram esse ese see se eek 64 OE SEE MM GIET 222 runtime configuration sse ese eek se ee GR ee 12 sock init or est 223 settin
100. TE This function will block for 10 ms to let the chip start up PARAMETERS nic The NIC to power up Use a value of 0 if only one NIC is present RETURN VALUE 0 Success 10 Error LIBRARY PKTDRV LIB SEE ALSO pd_powerdown 170 rabbit com TCP IP Manual Vol 1 _ping int ping longword host ip longword sequence number DESCRIPTION Generates an ICMP request for host NOTE this is a macro that calls send ping PARAMETERS host_ip IP address to send ping sequence number User defined sequence number RETURN VALUE 0 Success 1 Failure unable to resolve hardware address 1 Failure unable to transmit ICMP request LIBRARY ICMP LIB SEE ALSO _chk ping send ping TCP IP Manual Vol 1 rabbit com 171 PPPactive int PPPactive void DESCRIPTION Returns boolean value indicating if there is currently an active link to a peer RETURN VALUE gt 0 Active link to peer 0 No active link LIBRARY PPP LIB PPPnegotiatelP void PPPnegotiateIP unsigned long local ip unsigned long remote ip DESCRIPTION Sets PPP driver to negotiate IP addresses for itself and the remote peer Otherwise the svstem will relv on the remote peer to set addresses PARAMETERS local ip IP number to use for this PPP connection remote ip IP number that the remote peer should be set to RETURN VALUE None LIBRARV PPP LIB 172 rabbit com TCP IP Manual Vol 1 PPPsetAuthenticatee vo
101. The WIFI KEY macros were deprecated in Dynamic C 10 40 IFC WIFI WEP KEVO HEXSTR IFC WIFI WEP KEY1 HEXSTR IFC_WIFI_WEP KEY2 _HEXSTR IFC WIFI _WEP KEY3 _ HEXSTR Specifies the possible WEP keys to use for WEP encryption They default to undefined These keys can be either 40 bit or 104 bit i e a string of either 10 or 26 hex characters Note that you do not necessarily need to define all four WEP keys You can typically just define one key make sure it matches the key used on all other devices and set IFC WIFI WEP KEYNUM to point to the correct key Ifboth IFC WIFI WEP KEY HEXSTRand IFC WIFI WEP KEY BIN are defined fora particular key the HEX version will be used IFC WIFI WPA PSK PASSPHRASE TKIP encryption requires a passphrase or a key This macro allows you to define a passphrase with an ASCII string The Wi Fi driver will expand the passphrase into a key using a standard algorithm This process takes up to 20 seconds The same passphrase must be configured on all devices on the same Wi Fi network The macro WIFI PSK PASSPHRASE was deprecated in Dynamic C 10 40 IFC_WIFI_WPA_PSK_HEXSTR Instead of a passphrase you can specify a key directly for TKIP encryption The key must be given as a series of hex digits within an ASCII string The key must be 256 bits or 64 hex digits Specifying the key directly means that a passphrase does n
102. USEMODEM specifies that PPP assumes that it is talking to a modem When the interface is being brought up it will first run through the send expect script After the script completes PPP will assume that it can launch straight into LCP If this is not appropriate do not use IFS PPP SENDEXPECT or IFS PPP USEMODEM Instead use the facilities of MODEM LIB to per form an appropriate login to the ISP Only when this is complete should you call i fup Use of MODEM LIB entails some limitations e Only one PPP serial interface can use MODEM LIB e You need to configure MODEM LIB to match the serial port you are using for PPP e Ensure that you specify an IFCONFIG PPP default such that the interface remains down at boot time In other words do not append IFS UP to the IFCONFIG PPP definition 90 rabbit com PPP Driver 7 6 5 Starting and Stopping PPP Interfaces The details of establishing and tearing down PPP links are handled by sock init and tcp _tick as are all other TCP IP functions To start a PPP interface i fup is used just as it is for non PPPoE Ethernet interfaces One difference that you should note is that the interface will not usually be up after i fup returns The function ifup only sets the process in motion which takes much longer for PPP than it does for non PPPoE Ethernet Your appli
103. Use TF ANY if the socket is to accept connections from anv interface Otherwise connections will be accepted only from the specified interface Prior to Dvnamic C 7 30 this parameter was not implemented and should be IF DEFAULT lport Port to listen on remip IP address to accept connections from or 0 for all port Port to accept connections from or 0 for all datahandler Function to call when data is received NULL for placing data in the sock et s receive buffer Prior to Dynamic C 7 30 some details for implementa tion of this service had not been finalized Insert a value of NULL if you are using a version of Dynamic C prior to 7 30 reserved Set to 0 for now This parameter is for compatibility and possible future use buffer Address of user supplied socket buffer in xmem This is the return value of xalloc Ifbuffer is 0 the socket buffer for this socket is pulled from the buffer pool defined by the macro MAX TCP SOCKET BUFFERS buflen Length of user supplied socket buffer RETURN VALUE 0 Failure 1 Success LIBRARY TCP LIB TCP IP Manual Vol 1 rabbit com 247 tcp_extopen int tcp_extopen tcp Socket s int iface word lport longword remip word port dataHandler t datahandler long buffer int buflen DESCRIPTION Actively creates a session with another machine The buf fer and buf len parameters allow a user to supply a socket buffer instead of using a socket buffer from the pool t
104. Y TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock read sock fastwrite sock fastread sockerr sock flush sock flushnext udp send udp sendto TCP IP Manual Vol 1 rabbit com 241 sock xfastread int sock_xfastread tcp Socket ze long dp long len DESCRIPTION Reads up to Len bytes from dp on socket s If possible this function fills the buffer otherwise only the number of bytes immediately available if any are returned This function is only valid for TCP sockets For UDP sockets use udp_recv or udp_recvfrom This function is identical to sock _fastread except that it reads into an extended mem ory buffer PARAMETERS s Pointer to socket dp Buffer to place bytes that are read as an xmem address obtained from for example xalloc len Maximum number of bytes to write to the buffer RETURN VALUE Number of bytes read or 1 if there was an error LIBRARY TCP LIB SEE ALSO sock read sock fastwrite sock write sockerr udp recy udp recvfrom sock fastread 242 rabbit com TCP IP Manual Vol 1 sock xfastwrite int sock_xfastwrite tcp Socket s long dp long len DESCRIPTION Writes up to len bytes from dp to socket s This function writes as many bytes possible to the socket and returns that number of bytes This function is only valid for TCP sockets For UDP sockets use udp send orudp sendto This function is identical to sock fastwritel except that an extended m
105. _loycesready emy soeke l 1 sock gets butter MAX BUFFER In this case sock gets will not block because it will be called only when there is a complete new line terminated record to read 56 rabbit com TCP and UDP Socket Interface 3 11 TCP and UDP Data Handlers Starting with Dynamic C 7 301 your application can specify data handler callback functions for TCP and UDP sockets The data handler callback may be specified as a parameter to the tcp open tcp extopen tcp listen tcp extlisten udp open udp extopen and udp waitopen functions The UDP data handler callback is always available The TCP handler is only available if you define TCP_DATAHANDLER before including dcrtcp 1ib Both types of callback use the same function pro totype however the parameters are interpreted slightly differently The prototype for a suitable callback function is int mv data handler int event void socket 11 Gather g void info event indicates the type of callback It is one of a predefined set of constants specified in the table below socket is a pointer to the socket structure TCP or UDP g contains a number of fields which may be accessed to find additional information including the data stream or packet info points to a structure which depends on the type of socket udp datagram info if the socket is UDP or NULL for TCP sockets 1 Data handler pointers were provide
106. a connection The application should keep calling tcp tick until this function returns 0 LIBRARY NET LIB SEE ALSO Cep open tcp listen sock close sock_abort tcp tick sock established sock alive 238 rabbit com TCP IP Manual Vol 1 sock wait input void sock wait input void s int seconds int fptr int status DESCRIPTION Waits until input exists for functions such as sock read and sock gets As de scribed under sock mode if in ASCII mode sock wait input only returns when a complete string exists or the buffer is full It returns immediately for UDP sockets On an error the macro jumps to a local user supplied sock err label If fotr returns non zero the macro returns This macro has been deprecated in Dynamic C version 7 20 PARAMETERS s Pointer to a socket seconds Number of seconds to wait before timing out A value of zero indicates the macro should never time out A good value to use is sock delav a sys tem variable set on configuration Typically sock delay is about 20 seconds but can be set to something else in main fptr Function to call repeatedly while waiting status A pointer to the status word If this parameter is NULL no status number will be available but the macro will otherwise function normally Typical ly the pointer will point to a local signed integer that is used only for status status may be tested to determine how the socket was ended A value of l me
107. a new virtual ethernet interface You must define VIRTUAL ETH to a positive number 1 6 for this function to work The macro VIRTUAL ETH gives the maximum number of vir tual interfaces Virtual ethernet interfaces have some restrictions e You cannot use DHCP e Broadcast multicast packets are not received e Some ifconfig settings such as MTU size are not settable e Once a virtual interface is created it cannot be destroyed In practice this means that all virtual interfaces should be created at boot time after sock init The virtual interface will be created in the same up down state as the real interface Changes to the up down state of the real interface will affect all virtual interfaces tied to that interface The callback function for a virtual interface is set to NULL PARAMETERS real_iface The real interface to use This must be IF_ETHO or may be IF ETHI for boards with two Ethernet chips ipaddr The IP address to assign this interface This must not be the same as the IP address of any other interface netmask Netmask to use If zero then the netmask of the real interface will be used resv Pointer reserved for future use Pass as NULL RETURN VALUE 1 Failed because VIRTUAL_ETH was not defined or the number of virtual interfaces ex ceeds the value specified by VIRTUAL ETH orthe real iface parameter was not val id Otherwise returns the interface number to use for
108. a particular socket it will first process packets and then check the indicated socket for an established connection tcp tick returns zero when the socket is completely closed You can use this return value after call ing sock close to determine if the socket is completely closed sock close amp my socket while tcp tick amp my socket you can do other things here while waiting for the socket to be completely closed The status functions can be used to avoid blocking when using sock_write and some of the other I O functions As illustrated in the following code you can make sure that there is enough room in the buf fer before adding data with a blocking function iit SOCK cloleite lemy sockee Size d SOCK write Guy eeng Joblit EDE BLES The following block of code ensures that there is a string terminated with a new line in the buffer or that the buffer is full before calling sock gets sock mode my socket TCP MODE ASCII ii soek byrcesready emy sockee I sock gets buffer MAX BUFFER TCP IP Manual Vol 1 rabbit com 47 3 4 3 VO Functions for TCP Sockets These functions handle all I O for a TCP socket e sock aread e sock preread e sock awrite e sock putc e sock axread e sock puts e sock axwrite e sock read e sock fastread e sock write e sock fastwrite e sock xfastread e sock getc e sock xfastwrite e sock gets There are two modes of reading a
109. a ri 45 ARP LONG EXPIRY iets oes ee 89 DHCP CHEGK E 36 ARP NO ANNOUNCE m 90 DHCP CLASS Ui 37 ARP PERSISTENCE EE ERG 90 DHCP CLIENT ID 37 ARP PURGE TIME i te data 89 DHOP CLIENT ID LEN mmm 37 ARP ROUTER TABLE SIE 41 90 DHCP CLIENT ID MAC ees see se ee ee ee ee se ee 37 ARP SHORT EXPIRY onnenn 89 DHCP USE BOOTP eee ese sesse ene se ek eek eek ee 36 ARP TABLE gust 41 90 DHCP USE TFTP ou iese sesse se ee ese ene se ek eke RR ee 37 gt ie DISABLE DNS semm sees see ee eek ek ee Ge 35 91 B DISABLE TOP ies eers eta sa ses de gese ee ee 35 DNS is Ee eg ed eg 91 bandwidth ike SERE ae ER ER Ee GER Ge Ee DERE Ek EE 77 93 DNS MAX DATAGRAM SIE 41 91 BOOTP DHCP DNS MAX NAME i e ee ee ee ee ie 41 91 bootpdat EE EERS EER GE ta ee 39 DNS MAX RESOLVES iese ees ee 41 91 _bootpdone Lloret 38 DNS MIN KEEP COMPLETED iese 45 92 Med OE NE 39 DNS NUMBER RETRIES iese sees ees 45 92 bOOtphost ee 38 DNS RETRY TIMEOUT lee 45 91 M R EE OE SEENEN 37 DNS SOCK BUF SUE 42 92 Ri EE aser 38 drivers _bootptimeout eeue eek kke steres neee 38 link hi a EEN EE EN 6 EG AE NE EG 38 ed ER N EO EE 38 E dheptl AE RE Alec EE 38 l dhept2 PO 38 ephemeral connection uu eke RR RE nn od smtpsrv Een 39 SOT MESSABOS EE 227 ISUTVIVEBOOtp 1 ss ki sikka fees OE N 37 ETH MAXBUFS en Al broadcast packets 53 61 63 270 272 274 277 ETH MTU egener Nee 40 buffer SI ES AE NEE OE EO R 56 Ethernet le 3 C Ethernet Transmission Unit L senenenzzn 216 call
110. ace May be 0 0 0 0 if interface is not currently active Mask Local subnet mask Up Indicates status one of Yes interface currently active No currently inactive NYU Not Yet Up i e coming up NYD Not Yet Down i e coming down Type Interface type one of eth normal Ethernet ppp PPP over serial port pppoe PPP over Ethernet MTU Maximum transmission unit Flags A list of the following characters x this is the default interface IF DEFAULT D Use DHCP DD Currently configured via DHCP S allow IP addr configuration via directed ping ICMP echo SS IP address currently set via directed ping 1 IGMP version 1 router present on this interface Peer router IP address of peer node for PPP or PPPoE or address of default router on this interface for Ethernet type May be blank or 0 0 0 0 if no peer or rout er is available LIBRARY IP LIB 154 rabbit com TCP IP Manual Vol 1 ip timer expired word ip timer expired void s DESCRIPTION Check the timer inside the socket structure that was setbv ip timer init PARAMETER s Pointer to a socket RETURN VALUE 0 If not expired 1 If expired LIBRARY NET LIB SEE ALSO ip timer i tri TCP IP Manual Vol 1 rabbit com 155 void ip timer init void s word seconds DESCRIPTION ip timer init Set a timer inside the socket structure PARAMETER s seconds RETURN VALUE None LIBRARY
111. ading of the network interface s Recall that the number of 2K and 4K stacks is defined by STACK CNT 2K and STACK_CNT_4K respectively The size of the idle and the statistics tasks stacks are defined by OS TASK IDLE STK SIZE and OS TASK STAT STK SIZE respectively Of all the STACK CNT macros only the STACK CNT 4K or for memory constrained applications the STACK_CNT_2K macro should be defined to have a non zero value 3 12 1 2 Polled Mode Only Network Interface s The information in this section applies to TCP IP applications which use only polled mode network inter faces Polled mode network interface s include external Ethernet devices such as the ASIX chip which is used in the RCM4200 and RCM4300 board families Use of the TCP IP stack requires a uC OS2 II task to have a minimum stack size of 2K A particularly stack intensive u C OS II application may require TCP IP using tasks to have a minimum stack size of 4K TCP IP Manual Vol 1 rabbit com 61 Recall that the number of 2K and 4K stacks is defined by STACK CNT 2K and STACK CNT 4K respectively 3 12 2 Cooperative Multitasking The following program demonstrates the use of multiple TCP sockets with costatements Program Name costate_tcp c define MY I define MY NETMASK define MY GATEWAY define TCPCONFIG 1 kurzer PERMINS 81818 define PORT2 8889 define SOCK BUF SIZE define MAX SOCKETS 2 memmap xmem Zuse dertcp lib cee SOCkSic eebe
112. aemon tcp_tick tcp tick isa fundamental function for the TCP IP library It has two uses it drives the back ground processing necessary to maintain up to date information and it may also be used to test TCP socket state The latter use is described in the next section Note that tcp_tick does more than just TCP processing it is also necessary for UDP and other inter nal protocols such as ARP and ICMP It also as of Dynamic C 7 30 controls interface status The computing time consumed by each call to tcp_tick varies Rough numbers are less than a milli second if there is nothing to do tens of milliseconds for typical packet processing and hundreds of milli seconds under exceptional circumstances In general the more active sockets that are in use simultaneously the longer it will take for tcp_tick to complete however there is not much increase for reasonable numbers of sockets It is recommended that you call tcp tick at the head of the main application processing loop If you have any other busy wait loops in your application you should arrange for tcp_ tick to be called in each such loop TCP IP library functions that are documented as blocking will always include calls to tcp tick so you do not have to worry about it Library functions which are documented as non blocking eg sock_fastread do not in general call tcp_tick so your application will need to do it Some of the provided appl
113. ailed because hardware address not resolved LIBRARY UDP LIB SEE ALSO udp_sendto udp_recv udp_recvfrom udp_open TCP IP Manual Vol 1 rabbit com 265 udp_sendto int udp_sendto udp Socket s char buffer int len longword remip word remport DESCRIPTION Sends a single UDP datagram on a UDP socket It will send the datagram to the IP address and port specified by remip and remport Note that this function can be used on a socket that has been connected to a different remote host and port PARAMETERS s Pointer to socket s data structure buffer Buffer that contains the UDP datagram len Length of the UDP datagram remip IP address of the remote host remport Port number of the remote host RETURN VALUE 20 Success number of bytes sent 1 Failure 2 Failed because hardware address not resolved LIBRARY UDP LIB SEE ALSO udp send udp xsendto udp_recv udp recvfrom udp open 266 rabbit com TCP IP Manual Vol 1 udp_waitopen int udp waitopen udp Socket ze int iface word lport longword remip word port dataHandler t datahandler long buffer int buflen longword millisecs DESCRIPTION This function is identical to udp_extopen except that it waits a specified amount of time for the hardware address of the destination to be resolved While waiting this function calls tcp tick PARAMETERS s iface lport remip port datahandler buffer buflen millis
114. al Vol 1 ifconfig cont d IFS WIFI EAP METHODS IFG WIFI EAP METHODS Set Get acceptable EAP method longword longword The parameter is a bitmask with one of the following values Note that methods that do not have compiled in support via the WPA USE EAP macro will be ignored Currently we only support EAP TYPE TLS andEAP TYPE PEAP Valid values are e IFPARAM EAP PEAP This parameter selects PEAP MSCHAPV2 Using this method requires the statement define WPA USE EAP WPA USE EAP PEAP e IFPARAM EAP TLS This parameter selects EAP TLS Using this method reguires the statement define WPA USE EAP WPA USE EAP TLS IFS WIFI IDENTITX IFG WIFI IDENTITX Set Get identity string for EAP char char IFS WIFI ANONYMOUS IDENTITY IFG WIFI ANONYMOUS IDENTITY Set Get anonymous identity string for outer EAP char char IFS_WIFI_PASSWORD IFG WIFI PASSWORD Set Get password string for EAP char char IFS WIFI EAP PSK PASSPHRASE Set Wi Fi EAP PSK using passphrase char IFS WIFI EAP PSK HEXSTR IFG WIFI EAP PSK HEXSTR Set Get Wi Fi EAP PSK using 64 char hex string char char IFS WIFI EAP PSK BIN IFG WIFI EAP PSK BIN Set Get Wi Fi EAP PSK using 32 byte array byte byte TCP IP Manual Vol 1 rabbit com 143 ifconfig cont d IFS WIFI SUBJECT MATCH Set substring to
115. alization 2 2 2 Sources of Configuration Information The Dynamic C TCP IP stack obtains configuration information from one or more of the following sources e Use one of the predefined configurations in tcp_config 1ib static or dynamic e Macro definitions before use dcrtcp 1ib static configuration e Bootstrap network protocols such as BOOTP and DHCP dynamic configuration e Runtime function calls such as ifconfig version 7 30 and sethostid previous versions e Directed ping IP address assignment new in version 7 30 e Console based configuration e g zconsole lib As application designer you have to decide which of these configuration techniques is right for your project Entirely static configuration is typically used for initial application development and testing Most of the TCP IP sample programs use static configuration for simplicity in getting started Applications which are intended for real world use should allow at least one form of dynamic configuration The particular form of configuration that is supported will depend on the complexity of the application as well as the expected network or operational environment in which the application will run 2 2 2 1 Predefined Configurations Since networking configuration can be fairly complicated Dynamic C version 7 30 has the concept of canned or predefined configurations This has the advantage of reducing the number of macro definitions at the top
116. and PPP LIB are the transport and network layers of the TCP IP protocol stack The Dynamic C libraries that implement application layer protocols are e BOOTP LIB e FTP SERVER LIB e FTP L ENT LIB e HTTP LIB e HTTP CLIENT LIB e POP3 LI e SMNP LI e SMTP LI e TFTP LI e VSERIAL LIB D D D D Except for BOOTP which is described in this manual the application layer protocols are described in Dynamic C TCP IP User Manual Vol 2 All user callable functions are listed and described in their appropriate chapter Example programs throughout the manual illustrate the use of all the different protocols The sample code also provides tem plates for creating servers and clients of various types To address embedded system design needs additional functionality has been included in Dynamic C s implementation of TCP IP There are step by step instructions on how to create HTML forms allowing remote access and manipulation of information There is also a serial based console that can be used with TCP IP to open up legacy systems for additional control and monitoring The console may also be used for configuration when a serial port is available The console and HTML forms are discussed in the Dynamic C TCP IP User Manual Vol 2 Multiple interfaces are supported starting with Dynamic C version 7 30 TCP IP Manual Vol 1 rabbit com 1
117. ans a proper close while a 1 value indicates a reset or abort RETURN VALUE None LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB TCP IP Manual Vol 1 rabbit com 239 sock writable int sock writable void s DESCRIPTION This function determines whether a socket may have data written to it using e g sock fastwrite orudp sendto The parameter may be either a TCP socket or a UDP socket The return value is more than a simple boolean it also indicates the amount of data the socket is guaranteed to accept witha sock fastwrite call that immediately follows NOTE a TCP socket may be writable before it is established In this case any written data is transferred as soon as the connection is established PARAMETER s TCP or UDP socket pointer RETURN VALUE If parameter is a TCP socket tcp Socket 0 socket is not writable It was closed by the application or it may have been aborted by the peer non zero the socket is writable The amount of data that the socket would accept is this value minus 1 which may turn out to be zero if the socket s buffer is temporarily full On a freshly established socket and at any other time when all data has been acknowl edged by the peer the return value minus one indicates the maximum socket transmit buffer size If parameter is a UDP socket udp Socket 0 socket is not open non zero socket is open This value minus 1 equals the maximum size data
118. are PPPoE effectively sets up a virtual point to point link between two devices on the same Ethernet LAN segment IF PPPO IF_PPP1 IF PPP2 IF PPP3 IF PPPA IF_PPP5 These macros represent asynchronous serial ports used for PPP IF PPPO always refers to serial port A IF PPPI refers to serial port B etc Most boards will avoid using serial port A since it is most often used for Dvnamic C debugging and program download IF PPPX This is an alias for the first PPP interface The first PPP interface is selected as the first valid interface in the following order IF PPPOEO IF PPPOE1 IF PPPO IF PPPI etc through to IF PPP5 IF WIFIO IF WIFIl These macros represent Wi Fi interfaces Only IF WIFI0 is supported at this time IF_DEFAULT This is an alias for the default interface You can explicitly define this macro prior to including dertcp lib to select a default interface The Dynamic C TCP IP libraries do not make use of F DEFAULT with the important exception of DHCP DHCP only works on the default interface If you do not explicitly define IF DEFAULT it is chosen as the first valid interface in the following order IF PPPX see above IF WIFIO IF ETHO If you explicitly define IF DEFAULT then you must define it to a hard coded integer value not one of the IF macros since the IF macros are not defined until
119. articular it can be used to make sure it is okay to call the wifi ioctl function for most commands If your application needs to check the interface status which is recommended for PPP over serial or PPPoE then it can either poll the status using the above functions or it can register a callback function which is automatically called whenever the interface changes status To register a callback function you call ifconfig withthe IFS IF CALLBACK as the parameter identifier and the address of your callback function as the parameter value 2 3 2 Bringing an Interface Up You can call ifup orifconfig withthe IFS UP parameter identifier The advantage of using ifconfig is that you can specify an interface number of IF_ ANY which brings all interfaces up together When the i fup call returns the interface may not have completed coming up This is notably the case for PPP interfaces which require a number of protocol negotiation packets to be sent and received In addition PPP over serial may require additional time to reset a modem dial out to an ISP and possibly respond to the ISP s login procedure All this could take considerable time so the i fup function does not wait around for the process to complete to allow the application to proceed with other work On return from the i fup call an application must test for completion using the functions described in the previous section TCP IP Ma
120. ate network addresses for your device and define TCPCONFI G to access the desired configuration information Run the program and try to run ping 10 10 6 101 from a command line on a computer on the same physical network replacing 10 10 6 101 with your value for MY IP ADDRESS 3 8 1 TCP IP Stac k Initialization The main function first initializes the TCP IP stack with a call to sock init This call initializes internal data structures and enables the Ethernet chip which will take a couple of seconds with the RealTek chip At this point the TCP IP stack is ready to handle incoming packets TCP IP Manual Vol 1 rabbit com 53 3 8 2 Packet Processing Incoming packets are processed whenever tcp_tick is called The user callable functions that call tcp tick are tcp open udp_open sock read sock write sock close and sock abort Some of the higher level protocols e g HTTP LIB will call tcp tick automati cally Call tcp_tick periodically in your program to ensure that the TCP IP stack has had a chance to pro cess packets A rule of thumb is to call tcp _tick around 10 times per second although slower or faster call rates should also work The Ethernet interface chip has a large buffer memory and TCP IP is adaptive to the data rates that both ends of the connection can handle thus the system will generally keep working over a wide variety of tick rates 3 9 TCP IP D
121. backs F 6E EE ated dae teats 88 interface Status sissies RE REEN ES GERS eye ER tati 15 Function Reference IP address conflict ees ee ee ee ee ee 90 Addressing TCP and UDP dita handles EE EE EE 69 _arp_resolve En 117 checksums ee ee RA GR RA GR RARR GR ER ee ee 225 arp send gratultous ueee ee ee 122 communication channel ee ee RA RR AG 77 arp getArpData en 116 arp getArpGateData ees se ee ee 116 arpcache create oo ee se RR RR ee 108 arpcache flush soisi 109 arpcache hWa LL see ee RA GR AR RR ee 110 TCP IP Manual Vol 1 rabbit com 273 arpcache ipaddr o ee ee ee 112 Interface arpcache load Less Ge se Re Ge ee 113 tse E 158 arpcache search ees se se se ek Ge ee 115 ifpendini issie es ees be see besoe eg Se ts 159 arpresolve check Lev see se ee Ge ee 118 EE OE ea EE NE ines 160 arpresolve ipaddr Lee 119 DAUD EE EE ER 161 arpresolve start esse ses see se Re Ge se ee 120 UD APACE AO EA ER 165 arpresolve start iface iese ese ee ek ee 121 ip e E CN 166 dhep AC GUIT N Ie 125 is valid iface me ee ek Ge 169 dhcp get timezone lee 126 Ted did MA tare 221 dhep release L ee Re Re 127 te ES Ee Ee N 282 getdomainname LL se se se ek ee 128 Modem due G MA 129 ModemClose sem ee se ee ek 170 pethostndme iss asa esi 130 ModemConnected ees ee 170 getpeerafme sis se neriie 131 ModemEXpect Lm ses se se ee ek eke 171 getsockname m see ee Ge Ge ee Ge 132 ModemHangup we se esse se ee ek eke 171 psocket E Ee
122. be matched against the subject of the authentication server certificate char The subject string is in following format for example C US ST CA L Davis CN Test1 AS emailAddress testl_as rabbit com so this parameter string could be set to L Davis CN Test to allow all access servers with a location of Davis and a common name starting with Test IFS WIFI ALTSUBJECT MATCH Set semicolon separated string of entries to be matched against the alternative subject name of the authentication server certificate char If this string is set the server certificate is only accepted if it contains one of the entries in an alternative subject name extension altSubjectName string is in following format TYPE VALUE Example EMAIL server example com Example DNS server example com DNS server2 example com Following types are supported EMAIL DNS URI COMMANDS FOR CERTIFICATES AND KEYS The following parameters are for convenience when hard coding certificates e g from ximported files Pass a zero longword as the parameter in order to delete any resources that were allocated on a previous call since the library manages the SSL_Cert_t structures that are created IFS WIFI CA CERT IFG WIFI CA CERT Set Get CA certificate ISSL Cert t far SSL Cert tfar The authentication server is not verified if no CA certificate is provided in the Set com mand which introduces risk of access server spo
123. bed by 4 numbers the local and remote IP addresses 32 bits each and the local and remote port numbers 16 bits each Connections that do not traverse the Internet e g between two hosts on an isolated LAN are still unique within the attached network UDP sockets do not have the global uniqueness property since they are not connection oriented For UDP a socket really refers to just the local side For practical purposes a socket is a structure in RAM that contains all the necessary state information TCP sockets are considerably larger than UDP sockets since there is more connection state information to maintain TCP sockets also require both a receive and a transmit buffer whereas UDP sockets require only a receive buffer With Dynamic C version 6 57 each socket must have an associated tcp Socket structure of 145 bytes oraudp Socket structure of 62 bytes The I O buffers are in extended memory For Dynamic C 7 30 these sizes are 136 bytes and 44 bytes respectively For earlier versions of Dynamic C than 6 57 each socket must have a tcp Socket data structure that holds the socket state and I O buffers These structures are by default around 4200 bytes each The major ity of this space is used by the input and output buffers 3 1 1 Port Numbers Both TCP and UDP sockets make use of port numbers Port numbers are a convenient method of allowing several simultaneous connections to exist between the same two hosts Port numbers a
124. ber of bytes left in the transmit buffer If you do not wish to block you may first query how much space is available for writing by calling this function before generating data that must be transmitted This removes the need for your application to also buffer data PARAMETERS s Pointer to a socket RETURN VALUE Number of bytes left in the transmit buffer LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock rbsize sock rbused sock rbleft sock tbsize sock tbused EXAMPLE ii sock tolere s gt 10 I we can send up to 10 bytes without blocking or overflowing 232 rabbit com TCP IP Manual Vol 1 sock tbsize int sock_tbsize void s DESCRIPTION Determines the size of the transmit buffer for the specified socket PARAMETERS s Pointer to a socket RETURN VALUE The size of the transmit buffer LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock rbsize sock rbused sock rbleft sock tbleft sock tbused TCP IP Manual Vol 1 rabbit com 233 sock tbused int sock tbused void s DESCRIPTION Gets the number of bytes in use in the transmit buffer for the specified socket PARAMETERS s Pointer to a socket RETURN VALUE Number of bytes in use LIBRARV NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock rbsize sock rbused sock rbleft sock tbsize sock tbleft 234 rabbit com TCP IP Manual Vol 1 sock tick void
125. ble corresponding to this request can be reused for a subsequent request 2 6 8 Program Debugging TCP_STATS Enable TCP socket statistics collection This causes some additional fields to be defined in the TCP socket structure which are updated with various counters This is mainly for internal debugging DCRTCP_DEBUG If defined allow Dynamic C debugging in all TCP IP libraries This allows you to trace into library functions in case you are finding difficulty in solving a TCP IP problem Remember to remove this definition when compiling for a production environment 34 rabbit com TCP IP Initialization DCRTCP VERBOSE If defined enable debugging messages to be printed by the library to the Dynamic C stdout window This can be very informative when you are trying to see how the TCP IP libraries work Unfortunately the string messages take up a lot of root code space so you may need to increase the DATAORG value in the BIOS Otherwise you can be more selective about which messages are printed by defining VERBOSE macros for individual libraries DCRTCP_ VERBOSE merely turns on all the individual library verbose definitions See dcrtcp lib source for a listing of the available debug and verbose macros Note that the number of messages printed depends on the value of a global variable debug on If this variable is 0 only a few messages are printed If set to higher numbers up to 5 then successively mo
126. btaining information Please see BOOTP DHCP Control Macros on page 27 for details As of Dynamic C 7 30 DHCP or BOOTP can be used only on the default interface i e the interface that is specified by the value of IF DEFAULT If you are using more than one interface then you should ensure that IF DEFAULT is set correctly To successfully use DHCP configuration ensure all of the following conditions are met Only the first condition applies prior to 7 30 e define USE DHCP before including dertcp lib e Ensure IF DEFAULT is indicating the desired interface e Define an IFCONFIG macro to include the IFS_DHCP parameter ID For example if the Ethernet interface is to be used for DHCP the following code is required for DHCP define USE DHCP define IF_DEFAULT 0 not necessary unless also using PPP define IFCONFIG ETHO IFS DHCP 1 IFS_UP Zuse dcrtcp lib You may also use the predefined configuration number 3 which is DHCP define TCPCONFIG 3 use dcrtcp lib This configuration sets all reguired macros for DHCP or BOOTP to work Naturally there must be a DHCP server available on the interface The DHCP server must be set up to contain all the reguired configuration options however setting up the DHCP server is outside the scope of this document since there are many different DHCP servers in use The sample program Sampl
127. cation should be aware of this since you will not be able to open sockets on an interface that is not fully enabled If necessary you can poll the interface to wait for it to come up While polling you must call tcp _tick regularly This is because it is actually the processing driven from tcp tick that drives the whole PPP negotiation machinery The correct way to poll an interface is given by the following code fragment This code includes tests for the possibility that the interface may not be able to come up e g because of a time out ifup IF PPP2 while ifpending IF PPP2 1 tcp tick if lifstatus IF PPP2 printf Failed n A similar consideration applies for bringing the interface down ifdown IF PPP2 while ifpending IF PPP2 3 tcp tick Note that there is no need to test for an interface failing to come down however the tear down process may take a short time If you wait for the interface to come down before restarting it then there is a better chance that the link will come back up successfully since the peer will have been notified properly NOTE For PPP links with IFS PPP USEMODEM in effect the process of bringing the inter face up and down will include the modem dial out and hang up procedure If you had USEMODEM in effect when connecting but turned it off during the connection then ifdown will not perform modem hang up You will need to manual
128. ck bytesready to deter mine if there is data to be read from the buffer PARAMETERS s Pointer to a socket structure lport Our local port Use zero for the next available port in the range 1025 65536 A few applications will require you to use a particular local port number but most network applications let you use almost any port with a certain set of restrictions For example FINGER or TELNET clients can use any local port value so pass the value of zero for 1port and let DCRTCP LIB pick one for you remip IP address to connect to port Port to connect to datahandler Function to call when data is received NULL for placing data in the sock et s receive buffer Prior to Dynamic C 7 30 some details for implementa tion of this service had not been finalized Insert a value of NULL if you are using a version of Dynamic C prior to 7 30 RETURN VALUE 0 Unable to resolve the remote computer s hardware address 10 otherwise LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tep listen 252 rabbit com TCP IP Manual Vol 1 EXAMPLE USING TCP_OPEN Old way of setting network addresses is commented out define MY IP ADDRESS 10 10 6 100 define MY NETMASK 255 255 255 0 New of setting network addresses define TCPCONFIG 1 memmap xmem Zuse dertcp lib molerime ADDRESS AO MOE NS define PORT 200 main word status word port longword host ECO
129. close and reopen to make it ready for another source 3 7 3 Writing to a UDP Socket Prior to Dynamic C 7 05 the normal socket functions used for writing to a TCP socket will work for a UDP socket but since UDP is a significantly different service the result could be different Each atomic write sock putc sock puts sock write orsock fastwrite places its data into a single UDP packet Since UDP does not guarantee deliverv or ordering of packets the data received mav be different either in order or content than the data sent Packets mav also be duplicated if thev cross anv gatewavs A duplicate packet mav be received well after the original TCP IP Manual Vol 1 rabbit com 51 3 7 4 Reading From a UDP Socket There are two ways to read UDP packets prior to Dynamic C 7 05 The first method uses the same read functions that are used for TCP sock getc sock gets sock read and sock fastread These functions will read the data as it came into the socket which is not necessar ilv the data that was written to the socket The second mode of operation for reading uses the sock recv init sock recv and sock recv from functions The sock recv init function installs a large buffer area that gets divided into smaller buffers Whenever a datagram arrives it is stuffed into one of these new buffers The sock recv and sock recv from functions scan these buffers After calling sock recv init on the socket you shoul
130. connection was made This could be due to routing difficulties such as an inability to resolve the remote computer s hardware address with ARP Even if non zero is returned the connection will not be immediately established You will need to check the socket status as described in the next section 3 3 3 Waiting for Connection Establishment When you open a TCP socket either passively or actively you must wait for a complete TCP connection to be established This is technically known as the 3 way handshake As the name implies at least 3 pack ets must be exchanged between the peers Only after completion of this process which takes at least one round trip time does the connection become fully established such that application data transfer can pro ceed Unfortunately the 3 way handshake may not always succeed the network may get disconnected the peer may cancel the connection or the peer might even crash The handshake may also complete but the peer could immediately close or cancel the connection These possibilities need to be correctly handled in a robust application The consequences of not doing this right include locked up sockets i e inability to accept further connections or protocol failures The following code outlines the correct way to accept connections and to recover in case of errors ic tees opealemy SEEKS ooa printf Failed to open n else whale Nsock established emy Socker i li leco cick e
131. cp extopen is an extended version of tcp open s Pointer to socket s data structure iface Local interface on which to open the socket Use IF_ANY if interface is to be selected automatically based on the destination IP address lport Our port zero for the next one available in the range 1025 65536 remip IP address to connect to port Port to connect to datahandler Function to call when data is received NULL for placing data in the sock et s receive buffer Prior to Dynamic C 7 30 some details for implementa tion of this service had not been finalized Insert a value of NULL if you are using a version of Dynamic C prior to 7 30 buffer Address of user supplied socket buffer in xmem This is the return value of xalloc Ifbuffer is 0 the socket buffer for this socket is pulled from the buffer pool defined by the macro MAX TCP SOCKET BUFFERS buflen Length of user supplied socket buffer RETURN VALUE 0 Error unable to resolve the remote computer s hardware address 0 Success LIBRARY TCP LIB SEE ALSO tcp open 248 rabbit com TCP IP Manual Vol 1 tcp keepalive int tcp_keepalive tcp Socket ze long timeout DESCRIPTION Enable or disable TCP keepalives on a specified socket The socket must already be open Kee palives will then be sent after timeout seconds of inactivity It is highly recommended to keep timeout as long as possible to reduce the load on the network Ideally
132. d 2 IGMP cli ents will work with both version 1 and 2 IGMP routers Most users should just choose version 2 IGMP VI ROUTER PRESENT TIMEOUT Defaults to 400 When IGMPv 2 is supported a timer is set to this many seconds every time the board sees an IGMPv1 message from an IGMP router As long as there is time left on the timer the board acts as an IGMPv1 host If the timer expires the board returns to acting as an IGMPv2 host IGMP UNSOLICITED REPORT INTERVAL Defaults to 100 deciseconds 10 seconds This value is specified in deciseconds It determines the maximum random interval between the initial join report for a multicast group and the sec ond join report 82 rabbit com IGMP and Multicasting 7 PPP Driver The PPP packet driver is a set of libraries in Dynamic C that allows the user to establish a PPP Point to Point Protocol link over a full duplex serial line between a Rabbit based controller and another system that supports PPP You may also establish PPP links over Ethernet PPPoE A common use of the PPP protocol is the transfer of IP packets between a remote host and an Internet Ser vice Provider ISP over a modem connection The PPP packet driver supports the transfer of Internet Pro tocol IP data and is compatible with all TCP IP libraries for the Rabbit Establishing PPP links has become easier and more flexible You can have as many different PPP inter faces as you have available serial and Eth
133. d eege 277 Udp SENATO EE 278 udp_waitopen see eise OE EE 279 dh ed ei ee ee 280 udp_xsendto EE 281 UDP Socket VO pre DC 7 05 ye di es EE DE e 236 soek een HEEN 238 TCP IP Manual Vol 1 rabbit com 285 286 rabbit com
134. d if ipaddr is zero In this case the de fault router for the specified interface r_iface is returned Ir iface is NULL then the default interface is assumed IF DEFAULT the only interface supported at present F DEFAULT may refer to the primary Ethernet NIC or a PPP connection that uses a serial port or the primary Ethernet NIC PARAMETERS ipaddr IP address of the host which is not on the local subnet router used fnot NULL the byte at this location is set to the index of the router in the router table r iface Ifnot NULL the byte at this location is set to the interface number that can access the router RETURN VALUE Positive value completed successfully ATH NOROUTER no suitable router found Either no router is configured or the given IP ad dress is on the local subnet LIBRARY ARP LIB 182 rabbit com TCP IP Manual Vol 1 router for i face ATHandle router for iface longword ipaddr word router used word r iface word siface DESCRIPTION Return the ARP cache table entrv corresponding to the router which handles the given IP ad dress on a specific interface If the siface parameter is IF ANY then return the ARP cache table entry corresponding to the router which handles the given IP address If there is a preconfigured router for the given address it is selected Otherwise routers discovered via DHCP or ICMP router discovery are searched with the highest pr
135. d not use sock getc sock read or sock fastread The sock recv function scans the buffers for any datagrams received by that socket If there is a datagram the length is returned and the user buffer is filled otherwise sock recv returns zero The sock recv from function works like sock_recv but it allows you to record the IP address where the datagram originated If you want to reply you can open a new UDP socket with the IP address modified by sock_recv_from 3 7 5 Porting Programs from the older UDP API to the new UDP API To update applications written with the older style UDP API use the mapping information in the follow ing table UDP API prior to Dynamic C 7 05 UDP API starting with Dynamic C 7 05 MAX UDP SOCKET BUFFERS and MAX TCP SOCKET BUFFERS MAX SOCKETS SOCK BUF SIZE UDP BUF SIZE and TCP BUF SIZE udp open udp open sock write sock fastwrite udp send orudp sendto udp recv orudp_recvfrom sock read blocking function Gaonblocking fineugne sock fastread udp_recv orudp_recvfrom eee Bee tae sock recv udp recv sock recv from udp recvfrom sock close sock close or udp close sock bvtesreadv sock bvtesreadv sock dataready sock dataready 52 rabbit com TCP and UDP Socket Interface 3 8 Skeleton Program T
136. d to the tcp open etc functions prior to this release however the interface was not documented and does not work in the way described herein TCP IP Manual Vol 1 rabbit com 57 The Il Gather structure is defined and documented in N typedef struct byte iface byte spare word lenl void datal word len2 long data2 word len3 long data3 11 Gather The udp datagram info is defined in UDP L tion if Destination interface ET LIB It is printed here for reference Length of root data section Root data e g link IP transport headers Length of first xmem section First xmem data extent physical address Length of second xmem section Second xmem data extent physical address B It is documented with the udp peek func For UDP sockets the callback is invoked for each packet received by the socket For TCP sockets the callback is invoked whenever new data is available that could otherwise be returned by sock fastread The advantages of using the data handler callback are Less application overhead calling sock _dataready or sock fastread Data copy to root buffers can be avoided Ability to transform data in the socket buffer e g decryption For UDP may avoid the need to copy incoming data into the socket receive buffer Minimizes latency between tcp_tick receive processing and application processing Allows event driven programming sty
137. de void s word mode DESCRIPTION Change some of the socket options Depending on whether s is a TCP or UDP socket you may pass OR d combinations of the following flags in the mode parameter For a TCP socket only the TCP MODE flags are relevant For a UDP socket only the UDP MODE 7 flags are rel evant Do not use the wrong flags for the given socket type It is more convenient faster and safer to use the macro equivalent if it is only desired to change one mode at a time If you use this function then you must specify the setting of all relevant flags TCP or UDP The macros do not do socket locking so strictly speaking uC OS II users should call this function rather than use the macros TCP MODES TCP MODE ASCII TCP MODE BINARY default TCP and UDP sockets are usually in binary mode which means an arbitrary stream of bytes is allowed TCP is treated as a byte stream and UDP is treated as records filled with bytes The default is TCP_MODE BINARY By changing the mode to TCP MODE ASCII some of the DCRTCP LIB functions will see a stream of re cords terminated with a newline character In ASCII mode sock_bytesready will return 1 until a newline terminated string is in the buffer or the buffer is full sock_puts will append a newline to any output sock_gets which should only be used in ASCII mode removes the new line and null terminates the string Equivalent
138. dertcp lib is included Since the actual numbers assigned to each interface depend on the values of the USE macros you must be careful when doing this The only time you may want to explicitly define IF DEFAULT is when you are using both PPP and non PPPoE Ethernet and you want to use DHCP on the Ethernet interface IF ANY This is not an interface as such It is a special value used to denote any or all interfaces where applicable This macro should be used only where a function documents that its use is acceptable For example the tcp_extlisten function accepts IF ANY as an interface parameter which tells it to listen for incoming connections on any available interface 4 rabbit com TCP IP Initialization 2 1 2 Interface Selection Macros As each physical interface has its own macro each type of interface has a corresponding macro The macro value determines which physical interfaces of the same type will be supported by the stack Setting the macro to zero disables support for that type of interface i e no physical interfaces of that type will be supported If the macros are not defined in the application program they will be set to zero internally USE_ETHERNET This macro allows support of non PPPoE Ethernet It can be set to 0x01 0x02 or 0x03 Most boards only support 0x01 meaning the first non PPPoE Ethernet device Boards with two Ethernet devices can set this macro to 0x02 referring
139. e The interfaces available to your application will depend on the hardware configuration of the target board All Rabbit based boards have at least four asynchronous serial ports so PPP over serial is always available Many boards have an Ethernet port If an Ethernet port is available then it may be used for normal Ethernet or PPP over Ethernet PPPoE No Rabbit based board has more than one Ethernet port however Dynamic C 7 30 contains support for a second Ethernet interface if and when such a board becomes available TCP IP Manual Vol 1 rabbit com 3 Your application uses configuration macros to select the interface s to use for TCP IP Each hardware interface will have an interface number assigned The interface number is not used directly instead your application should use the macros defined for this purpose If you are writing general purpose routines then you should include ifdef tests for the interface macro if you need to refer to it This is because the macros are not necessarily defined for non existent interfaces The macros are IF ETHO IF ETH1 These macros represent Ethernet ports that are not using PPP IF ETHO refers to the first Ethernet port and IF ETHI to the second IF PPPOEO IF PPPOE1 These macros represent Ethernet ports used for PPP over Ethernet IF PPPOEO refers to the first and currently only Ethernet port PPPoE and regular Ethernet can co exist on the same Ethernet hardw
140. e PPP peer address Returns 0 if no connection longword IFS_PPP_PASSIVE Set passive mode for PPP bool If TRUE then interface will wait indefinitely for a con nection after its initial connection attempt IFG PPP PASSIVE Is passive mode set for PPP bool THE FOLLOWING PARAMETER IDENTIFIERS ARE FOR MODEMS ON PPP INTERFACES IFS PPP SENDEXPECT A series of strings to send and then expect each separated by a carriage return ir char Setting send expect automatically turns on IFS PPP USEMODEM See the documenta tion for chat_init for details on the syntax for these strings The specified strings MUST be in static storage since only the pointers are stored rather than copying the strings Note that two substitution parameters are available 0 may be used to insert the current user name as set using the TZFS PPP REMOTEAUTH command and 1 is the corre sponding password This is useful if your logon script uses the same userid password as is used by PPP during its authentication PAP stage IFG PPP SENDEXPECT char IFS_PPP_USEMODEM Specify whether to use modem dialout string bool IFG PPP USEMODEM Is modem dialout string going to be used bool IFS PPP MODEMESCAPE Specify whether or not to add an escape sequence lt delay gt lt delay gt before sending send expect or hangup strings bool TCP IP Manual Vol 1 rabbit com 133 ifconfig cont d IFG PPP
141. e can be busy In these cases the TCP stack needs to try again a short time later The second use is to allow time for further information to come in from the network before transmitting otherwise empty packets TCP has two main reasons for transmitting packets with no data content The first is acknowledgement of incoming data when we have nothing to send and the other is to update our receive window to the peer The receive window tells the peer how much data it can transmit which we can store in our socket receive buffer This window needs to be updated not only when we receive data but also when the application reads data out of the receive buffer Rather than send these empty packets as soon as possible it is often profitable to wait a short time In the case of window updates this can allow the application to write some data after the read which updated the window The data can be sent with the window update which improves efficiency because one packet can do the work of two For receive data acknowledgements the same trick can be applied i e piggy backing on some additional data TCP IP Manual Vol 1 rabbit com 71 These optimizations can be taken advantage of quite often with most applications so it is worth while specifying the lazy update time out to be at least a few ms Lowering the lazy update interval can slightly improve latency and throughput on high speed 1 e local Ethernet connections 4 2 3 Reserved Ports As ment
142. e list which exists RETURN VALUE 0 Interface is currently down 10 Interface is currentiv up active LIBRARV NET LIB SEE ALSO ifconfig ifup ifdown ifpending 148 rabbit com TCP IP Manual Vol 1 int ifup int iface DESCRIPTION This function attempts to activate the specified interface The action depends on the previous ifup status reported by ifpending Return Value of ifpending Action Taken by ifup IF UP None returns IFCTL OK IF COMING UP None returns IFCTL PEND IF_DOWN Starts bringing interface up using normal procedure IF COMING DOWN Depends on interface capabilities but note that in prac tice this always returns IFCTL FAIL If the interface is currently coming down the action taken when i fup is called depends on the interface Some interfaces may not allow the interface to come back up in this condition in which case IFCTL FAIL will be returned Try again later when the interface is fully down or you can call i fdown to force the interface down immediately If the interface allows changing requested state when coming down then the return value will be either IFCTL PEND or IFCTL_OK Currently the only inter face types which do not come down instantly are PPP over async serial and PPPoE These do NOT currently implement calling i fup when they are pending down
143. e time out value in milliseconds during open or close negotiation Defaults to 13000 ms TCP_SYNQTIMEOUT Defines the time out value in milliseconds for pending connection Defaults to 90000 ms TCP_TWTIMEOUT Define time to linger in TIMEWATT state milliseconds It should be from 5 to 4 minutes 2MSL but it s not really practical for us Two seconds will hopefully handle the case where ACK must be retransmitted but can t protect future connections on the same port from old packets Defaults to 2000 ms KEEPALIVE NUMRETRYS Number of times to retry the TCP keepalive Defaults to 4 TCP IP Manual Vol 1 rabbit com 33 KEEPALIVE WAITTIME Time in seconds to wait for the response to a TCP keepalive Defaults to 60 seconds TCP MAXRTO Set an overall upper bound for the retransmit timeout in milliseconds Defaults to 50 000 ms TCP_MINRTO Set a lower bound for the retransmit timeout in units of milliseconds Prior to Dynamic C 9 01 the default value for this macro was 250 ms 1 4 second Starting with Dynamic C 9 01 stack improvements allowed the default value to be reduced to 10 ms In either case beware of reducing this value since modern hosts try to ack only every second segment If our RTO is too small we will unnecessarily retransmit if we don t get the ack for the first of the two segments especially on a fast LAN where the RTT measurement will want to make us set a small time out TCP LAZYUPD Set a
144. ease or no lease was acquired LIBRARY BOOTP LIB TCP IP Manual Vol 1 rabbit com 115 getdomainname char getdomainname char name int length DESCRIPTION Gets the current domain name For example if the controller s internet address is test mynet work com then mynetwork is the domain portion of the name The domain name can be changed by the setdomainname function PARAMETERS name Buffer to place the name length Maximum length of the name or zero to get a pointer to the internal do main name string Do not modify this string RETURN VALUE If length 21 Pointerto name If length is not long enough to hold the domain name a NULL string is written to name If length 0 Pointer to internal string containing the domain name Do not modify this string LIBRARY BSDNAME LIB SEE ALSO setdomainname gethostname sethostname getpeernam getsockname L EXAMPLE main sock_init printf Using s for a domain n getdomainname NULL 0 116 rabbit com TCP IP Manual Vol 1 gethostid longword gethostid void DESCRIPTION Return the IP address of the controller in host format RETURN VALUE IP address in host format or zero if not assigned or not valid LIBRARY IP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sethostid EXAMPLE main char buffer 512 sock init printf My IP address is s n inet ntoa buffer get
145. ecs RETURN VALUE Pointer to socket Local interface on which to open the socket This parameter is supported as of Dynamic C 7 30 With earlier version of DC this parameter should be IF DEFAULT Local port Acceptable remote ip or 0 for all Acceptable remote port or 0 for all Function to call when data is received NULL for placing data in the sockets receive buffer Address of user supplied socket buffer in xmem 0 to use a buffer from the socket buffer pool Length of user supplied socket buffer Maximum milliseconds to wait for the hardware address to be resolved gt 0 Successfully opened socket 0 Timed out without resolving address 1 Error opening socket e g buffer could not be allocated LIBRARY UDP LIB SEE ALSO udp extopen sock resolved TCP IP Manual Vol 1 rabbit com 267 udp_waitsend int udp waitsend udp Socket s char buffer int len longword remip word remport word millisecs DESCRIPTION This is identical to udp_sendto except that it will block for up to the specified amount of time waiting for the hardware address to be resolved Normally you should not have to specify more than 100 ms for the time out If it takes longer than this the destination is probably un available PARAMETERS s UDP socket on which to send the datagram buffer Buffer that contains the UDP datagram len Length of the UDP datagram remip IP address of the remote host
146. ecv daca Spare Sizet Spare something received 7 printf Got Su byte packet n templen TCP IP Manual Vol 1 rabbit com 225 sock recv f rom int sock recv from sock type ze long hisip word hisport char buffer int len DESCRIPTION After a UDP socket is initialized with udp open and sock recv_init sock recv from scans the buffers for any datagram received by that socket and iden tifies the remote host s address This function is not available starting with Dynamic C 7 05 see Section 3 5 PARAMETERS s Pointer to UDP socket hisip IP of remote host according to UDP header hisport Port of remote host buffer Buffer to put datagram in len Length of buffer RETURN VALUE gt 0 Length of datagram received 0 No datagram 1 Receive buffer was not initialized with sock recv init LIBRARY DCRTCP LIB SEE ALSO sock recv sock recy init 226 rabbit com TCP IP Manual Vol 1 sock recv init int sock recv init sock type s void space word len DESCRIPTION This function is not available starting with Dynamic C 7 05 see Section 3 5 The basic socket reading functions sock read sock fastread etc are not ad eguate for all your UDP needs The most basic limitation is their inability to treat UDP as a re cord service A record service must receive distinct datagrams and pass them to the user program as such You must know the length of the received data
147. ee up code and data memory space DISABLE DNS This macro disables DNS lookup This prevents a UDP socket for DNS from being allocated 26 rabbit com TCP IP Initialization thus saving memory Users may still call resolve with an IP address provided that the ad dress is in dotted decimal form i e does not require a real DNS lookup DISABLE UDP This macro disables all UDP functionality including DNS SNMP TFTP and DHCP BOOTP You can define this to save a small amount of code if your application only needs to be a TCP server or a TCP client that does not need to do name lookups This macro is available starting with Dynamic C 7 30 DISABLE TCP This macro disables all TCP functionality including HTTP web server SMTP mail and oth er TCP based protocols You can define this to save a substantial amount of code if your appli cation only needs UDP This macro is available starting with Dynamic C 7 30 2 6 2 Including Additional Functions The following macros default to being undefined i e the functionality is not included by default USE_DHCP This macro is required when DHCP or BOOTP functionality is desired USE SNMP Define this to be the version number of SNMP Simple Network Management Protocol to be supported Currently the only allowable value is 1 USE MULTICAST This macro will enable multicast support In particular the extra checks necessary for accepting multicast datagrams will be enabled and joini
148. eference being selected Failing this if there is a point to point in terface this is selected as the default If the specified IP address already has an entry in the ARP cache table and there is a router al ready defined for that address then the current router is returned This overrides any other se lection process Where multiple routers can be used to access the given IP address the one whose entry has the most specific netmask is used If the netmasks are equal then an arbitrary entry is used An alternative mode of calling this function is invoked if ipaddr is zero In this case the de fault router for the specified interface i e siface is returned If siface is IF ANY then the most general router entry is returned i e the overall default If siface is a virtual ethernet interface then if there is no specific router defined then the rout er for the underlying real interface will be used This may not be satisfactory if the router is not on the subnet defined for the virtual interface Thus if non overlapping subnets are used then the virtual interface should have a valid router explicitly defined PARAMETERS ipaddr IP address of the host which is not on the local subnet or zero to find a de fault router router used fnot NULL the word at this location is set to the index of the router in the router table r iface If ipaddr is non zero this is an output parameter If not NULL the w
149. efine the maximum number of DNS servers Defaults to 2 MAX COOKIES Define the maximum number of cookies that a server can send to or receive from a client Defaults to 1 TCP_MAXPENDING Define the maximum number of pending TCP connections allowed in the active list Defaults to 20 MAX RESERVEPORTS Defines the maximum number of TCP port numbers that may be reserved Defaults to 5 if USE_RESERVEDPORTS is defined which is defined by default For more information about USE_RESERVEDPORTS and setting up a listen queue please see Specifying a Listen Queue on page 46 DNS MAX RESOLVES 4 by default This is the maximum number of concurrent DNS gueries It specifies the size of an internal table that is allocated in xmem DNS MAX NAME 64 by default Specifies the maximum size in bytes of a host name that can be resolved This number includes any appended default domain and the NULL terminator Backwards compatibility exists for the MAX DOMAIN LENGTH macro Its value will be overridden with the value DNS_MAX NAME if it is defined 30 rabbit com TCP IP Initialization For temporary storage a variable of this size must be placed on the stack in DNS processing Normally this is not a problem However for wC OS II with a small stack and a large value for DNS MAX NAME this could be an issue DNS MAX DATAGRAM SIZE 512 by default Specifies the maximum length in bytes of a DNS datagram
150. efines window An important point to remember is that the configuration of TCP IP applies equally well to Wi Fi devices as it does to Ethernet devices TCPCONFIG This macro works the same for a Wi Fi interface as it does for an Ethernet interface Use the value 1 fora static TCP IP network configuration or 5 for a DHCP dynamic configuration IFC_WIFI_SSID default rabbitTest This is the SSID Service Set Identifier or name of the wireless network that you want your Rabbit device to connect to All other devices on your wireless network including your access point or wireless router must have this same name The macro WIFI SSID was deprecated in Dynamic C 10 40 IFC_WIFI_ROAM ENABLE default 1 This turns roaming on or off IFC_WIFI_ROAM BEACON MISS default 20 This sets the number of beacons that are missed continuously in order for scanning for a better access point and subsequent association to take place 36 rabbit com TCP IP Initialization IFC WIFI MODE default IFPARAM WIFI INFRASTRUCTURE Specifies the network architecture mode for your wireless network This macro has two possible values IFPARAM WIFI INFR means that the device will attach to an infrastructure network An infrastructure network includes at least one access point that coordinates communication on the wireless network IFPARAM WIFI ADHOC means that the device will use an ad hoc mode network An ad hoc network does not have an access po
151. efits that TCP cannot provide one benefit is that UDP can broadcast to more than one peer and another is that UDP preserves the concept of record boundaries which can be useful for some applications TCP is a connection oriented protocol Two peers establish a TCP connection which persists for the exclusive use of the two parties until it is mutually closed in the usual case UDP is connectionless There is no special start up or tear down required for UDP communications You can send a UDP packet at any time to any destination Of course the destination may not be ready to receive UDP packets so the appli cation has to handle this possibility In spite of being connectionless we still sometimes refer to UDP connections or sessions with the understanding that the connection is a figment of your application s imagination This chapter describes how to implement your own application level protocols on top of TCP or UDP The Dynamic C TCP IP libraries can also be examined for further hints as to how to code your application For example HTTP LIB contains the source for an HTTP web server TCP IP Manual Vol 1 rabbit com 41 3 1 What is a Socket Both TCP and UDP make extensive use of the term socket A TCP socket represents the connection state between the local host and the remote peer When talking about TCP connections that traverse the Internet a socket is globally unique because it is descri
152. emory data source is used PARAMETERS s Pointer to socket dp Buffer containing data to be written as an xmem address obtained from for example xalloc len Maximum number of bytes to write to the socket RETURN VALUE Number of bytes written or 1 if there was an error LIBRARY TCP LIB SEE ALSO sock write sock fastread sock read sockerr sock flush sock flushnext udp send udp sendto sock fastwrite TCP IP Manual Vol 1 rabbit com 243 sock yield int sock_yield Cep Socket ze void fn DESCRIPTION This function if called prior to one of the blocking functions will cause fn the user defined function that is passed in as the second parameter to be called repeatedly while the blocking function is in a busywait state PARAMETERS s Pointer to a TCP socket fn User defined function RETURN VALUE 0 LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB 244 rabbit com TCP IP Manual Vol 1 tcp clearreserve void tcp clearreserve word port DESCRIPTION This function causes DCRTCP to handle a socket connection to the specified port normally This undoes the action taken by tcp reserveport PARAMETERS port Port to use RETURN VALUE None LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tcp open tcp listen tcp reserveport TCP IP Manual Vol 1 rabbit com 245 tcp config void tcp config char name char value DESCRIPTION Set
153. er sizeor buriree I die lem oj d buffer len 0 eg Lat VS Durrer wale EGO ciek s e TCP IP Manual Vol 1 rabbit com 203 sock fastwrite int sock_fastwrite tcp Socket s byte dp int len DESCRIPTION Writes up to len bytes from dp to socket s This function writes as many bytes as possible to the socket and returns that number of bytes Starting with Dynamic C 7 05 this function is only valid for TCP sockets For UDP sockets use udp send orudp sendto When using a UDP socket prior to DC 7 05 sock_fastwrite will send one record if len lt ETH MTU 20 8 ETH MTU is the Ethernet Maximum Transmission Unit 20 is the IP header size and 8 is the UDP header size By default this is 572 bytes If len is greater than this number then the func tion does not send the data and returns 1 Otherwise the UDP datagram would need to be frag mented For TCP the new data is queued for sending and sock fastwrite returns the number of bytes that will be sent The data may be transmitted immediately if enough data is in the buf fer or sufficient time has expired or the user has explicitly used sock flushnext to in dicate this data should be flushed immediately In either case no guarantee of acceptance at the other end is possible PARAMETERS s Pointer to a socket dp Buffer to be written len Maximum number of bytes to write to the socket RETURN VALUE 20 Success number o
154. er may be either a specific interface number to get the default rout er for that interface or IF ANY which will retrieve an overall default router IFS_HWA Set the hardware address byte Setting the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted IFG HWA Get the hardware address byte IFS NAMESERVER SET Delete all nameservers then set this one longword This parameter does not care about the value of 1face because it is not specific to an in terface IFS NAMESERVER ADD Add nameserver longword This parameter does not care about the value of 1face because it is not specific to an in terface IFS NAMESERVER DEL Delete nameserver longword This parameter does not care about the value of iface because it is not specific to an in terface IFS ICMP CONFIG Allow arp s ping to configure IP address bool If DHCP and ping configure are both set then the completion of DHCP will automatically turn off ping configure If DHCP fails then ping configure will be allowed after the set time out for DHCP Ping config cannot override DHCP until DHCP has timed out This is the case whenever a DHCP lease is obtained whether or not at sock init time This parameter may be set for IF ANY i e all interfaces
155. ernet ports You can also run PPP over serial and or Ethernet at the same time as ordinary non PPPoE Ethernet 7 1 PPP Libraries The PPP driver is in three library files though it is mainly controlled via the ifconfig function and friends PPP is mainly controlled via the if config function at runtime and IFCONFIG PPP con figuration macros at compile time PPP LIB Contains routines to handle the link negotiation LCP authentication PAP and IP negotiation IPCP These are the three main sub protocols of PPP PPP LIB calls routines in the other two libraries to handle the lower level physical layer PPPLINK LIB Contains handlers for the asynchronous serial physical layer namely the interrupt service rou tine for transmitting and receiving characters over the serial link It also handles the insertion and detection of escape characters and CRC generation and checking PPPOE LIB Contains handlers for the PPPoE physical layer which is mainly the access concentrator dis covery mechanism and the addition of the PPPoE header to Ethernet packets This library calls the Ethernet driver library to handle the Ethernet physical layer TCP IP Manual Vol 1 rabbit com 83 7 2 External Modem Library A fourth library MODEM LIB contains functions for controlling an external modem through a full RS232 link MODEM LIB should not be required for most ISP connections since most ISPs these days auto detect the use o
156. ert my client cert Because it is necessary to ximport SSL certificates for use with this encryption method it is not possible to completely configure WPA Enterprise with EAP TLS and CCMP using the Project Defines However as long as you include something like these two ximport statements in your program ximport cert ximport cert ts root pem root ca ert ts my_client pem my client cert you can provide the rest of the configuration in the Project Defines Here is an example copy and paste into the Defines window and modify as necessary TCPCONFIG 1 _PRIMARY STATIC IP 1010 62 100 _ PRIMARY NETMASK 255a2599 255 0 MY GATEWAY 10 1066 MY NAMESERVER TOs a EAR WIFI_USE_WPA WIFI_AES ENABLED FC WIFI SSID rabbitTest FC WIFI ROAM ENABLE 1 FC WIFI ROAM BEACON MISS 20 FC_WIFI_MODE IFPARAM WIFI_INFRASTRUCTURE FC WIFI REGION IFPARAM WIFI REGION AMERICAS FC WIFI ENCRYPTION IFPARAM WIFI ENCR CCMP WPA USE EAP WPA USE EAP TLS FC WIFI WPA PROTOCOL IFPARAM WIFI WPA PROTOCOL WPA2 FC WIFI CLIENT CERT XIM my client cert my client cert FC WIFI CA CERT XIM
157. ery second packet received or after a short time out see TCP LAZYUPD Normally this will happen within the default value time interval so there will be no unnecessary retransmission 70 rabbit com Optimizing TCP IP Performance TCP_TWTIMEOUT This defaults to 2000 ms 2 seconds This is one area where embedded system requirements conflict somewhat with recommendations in the standards documents The time wait time out is a waiting period that is necessary when a socket is closed This waiting period is supposed to be twice the maximum lifetime of any packet in the network The maximum packet lifetime is 255 seconds so the time wait time out should be about 8 minutes The purpose of the waiting time is to allow both ends of the connection to be satisfied that their respective peer has agreed to the close and acknowledged it This wait time only affects the closed socket i e the unique socket combination of IP addresses and port numbers It means that when a socket is closed the same socket cannot be re opened until at least 8 min utes have passed This is usually no problem for systems that have large memories to hold the state of recently closed sock ets For an embedded system which has a limited pool of sockets and limited memory for storing connec tion states this wait time is inconvenient since the socket structure cannot be re used until the time wait period has expired The default time wait period is thus set to 2 sec
158. es ENE SR ERG Rds Re AEN 164 Socket Connection EE 177 abort SOCKS EE 107 GC 178 SOCK ADOT eech N EE OE TEE 203 ul EE OER 191 SOCK CLOSE ER EE IE 210 Ethernet sock established see ee ee 214 pd getaddress ee ee ee Re Ge 179 sock waiting sees ee seek GR RR RR 250 pd havelink en 180 tep keepalive Lee 261 pd powerdown ses ee ee ee Re Ge 181 Socket VO Buffer pd POWETUD ee sees se ee ee Re ee RA Ga 182 sock Tbleft ESE DE EE EE ee 231 Initialization Ted dii EE AE 232 SOCK GE 222 sock Tbused es es ee Bee SE EE 233 sock init or exit Lew ee ee 223 sock tbleft oo ee se Re RR Re RR ee 244 od did ER RE 247 ld dii RR EE AE N 245 sock tbused ss ee ee RR RR 246 274 rabbit com Index Socket Status sock fastread s sem ese ee ee ek ke 215 ip timer expired oo eee se ee ee ee ee 167 sock fastwrite Lower 216 ip tier E 168 Soek read ici dct e Ge GE RE 234 SOCK AVE ie ee entrati f N es 204 SOCK EO RE ER AE OE EO 236 sock _bytesready o se ee ee ee 209 sock recy TOM waits istantanja ai 238 sock dataready 211 sock recy Imit Leelee seek ee ee ek ke Ge 239 rd dr RE RE N 213 SOCK Write see ee Re ee Mo 253 sock perror ess eeeenrenzenzzntenzznnzznnzzni 227 udp close Lu ee ee ee ee Re RA 269 sock readable Lena 235 UdP OPEN xs isse ER ES Eg ees 272 sock resolved ie ee ee ee 240 Wi Fi sock writable Lm see Ge se ek ee 252 WiN OE EE 26 SOCK ER OE NON 212 wifi ssid to att 283 dr RR OE N EE 243 top HEK oe ee zona 27 H TCP
159. es tcpip dhcp c uses dynamic configuration in a basic TCP IP program that will initialize the TCP IP interface and allow the device to be pinged from another computer on the network It demonstrates DHCP features such as releasing and re acquiring IP addresses and downloading a configuration file 2 2 2 4 Runtime Configuration Using ifconfig ifconfig isa function introduced in version 7 30 This function does many things and is the recommended replacement for some of the functions marked as deprecated including tcp_config ifconfig performs most of the work for all the other configuration techniques For example static configuration via the IFCONFIG_ macros basically calls ifconfig with the specified parameters substituted in 12 rabbit com TCP IP Initialization ifconfig takes a variable number of parameters like printf however the parameter list is terminated with the special IFS_END symbol For example to use if config to set the same parameters as described above for the static configuration ifconfig IF ETHO IFS IPADDR aton 10 10 6 100 FS NETMASK aton 255 255 255 0 IFS ROUTER SET aton 10 10 6 1 IFS UE FS END Note that this is the same as substitution of the IFCONFIG macro e g ifconfig IF ETHO IFCONFIG ETHO IFS END ifconfig
160. et parameter was invalid 0 Insufficient free space in the transmit buffer to satisfy the request or Len was zero Try again later since the peer will eventually acknowledge the receipt of previous data freeing up transmit buffer space len The len parameter is returned if there was sufficient data in the socket transmit buffer to satisfy the request LIBRARY TCP LIB SEE ALSO sock fastread sock xfastread sock fastwrite sock xfastwrite sock axread sock aread sock awrite 196 rabbit com TCP IP Manual Vol 1 sock bytesready int sock_bytesready void s DESCRIPTION For TCP sockets If the socket is in binary mode sock bvtesreadv returns the number of bytes waiting to be read If there are no bytes waiting it returns 1 In ASCII mode sock bytesready returns 1 if there are no bytes waiting to be read or the line that is waiting is incomplete no line terminating character has been read The number of bytes waiting to be read will be returned given one of the following conditions e the buffer is full e the socket has been closed no line terminating character can be sent e acomplete line is waiting In ASCII mode a blank line will be read as a complete line with length 0 which will be the value returned sock bvtesreadv handles ASCII mode sockets better than sock dataready since it can distinguish between an empty line on the socket and an empty buffer For UDP sockets Returns the number of
161. etrying a DNS request If a request to a nameserver times out then the next nameserver is tried If that times out then the next one is tried in order until it wraps around to the first nameserver again or runs out of re tries TCP IP Manual Vol 1 rabbit com 79 DNS_NUMBER_RETRIES 2 by default Specifies the number of times a request will be retried after an error or a time out The first attempt does not constitute a retry A retry only occurs when a request has timed out or when a nameserver returns an unintelligible response That is if a host name is looked up and the nameserver reports that it does not exist and then the DNS resolver tries the same host name with or without the default domain that does not constitute a retry DNS MIN KEEP COMPLETED 10000 by default Specifies the number of milliseconds a completed request is guaranteed to be valid for resolve name check After this time the entry in the internal table corre sponding to this request can be reused for a subsequent request DNS SOCK BUF SIZE 1024 by default Specifies the size in bytes of an xmem buffer for the DNS socket Note that this means that the DNS socket does not use a buffer from the socket buffer pool 80 rabbit com Network Addressing ARP amp DNS 6 IGMP and Multicasting The Internet Group Management Protocol IGMP and multicasting are supported by the Dynamic C TCP IP stack starting with version 7 30 6 1 Multicasting Multicas
162. events are for significant changes in the TCP socket state You can use these events to perform customized handling of socket open and close Apart from TCP DH INDATA and TCP DH ICMPMSG the 11 Gather structure is not passed g is set to NULL Currently the info parameter is always null for TCP sockets If your callback function does not understand a particular event type or is not interested it should return zero This will allow for upward compatibility if new callback events are introduced For convenience in coding the callback you can use the user data field in the tcp Socket structure to hold some application specific data which is to be associated with a socket instance There is no API for access ing this field just use s gt user_ data This field is only available if you have defined TCP_DATAHANDLER and only for TCP sockets not UDP TCP IP Manual Vol 1 rabbit com 59 There is no guarantee on the order in which events will arrive for a socket The exceptions are that TCP DH LISTEN or TCP DH OPEN will always be first and TCP DH CLOSED will always be last There is no guarantee that the callback will be invoked with TCP DH INCLOSE or TCP DH OUTCLOSE before TCP DH CLOSED TCP DH OUTBUF indicates that some previously transmitted data has been acknowleged by the peer Generally this means that there is more space available in the transmit buffer The callback can write data to the
163. f PPP and do not require any special logon screen navigation Basic dial up to an ISP is handled directly by if config settings which do not require any special modem control providing that your modem has a Hayes compatible interface MODEM LIB is not directly related to PPP It allows ASCII strings to be sent to and received from the modem Typically these strings are AT commands and modem responses If you have special requirements for establishing communications with an ISP that cannot be handled by the default PPP library methods you will need to explicitly include MODEM LIB and write a program to establish the communications link The program will typically need to command the modem to dial out wait for a valid connection send a user ID and password to the ISP and validate the response After this has completed successfully PPP can be started using the i fup function For a complete description of ifup and other Dynamic C TCP IP functions please see the Dynamic C TCP IP User Manual Vol I NOTE MODEM LIB is currently limited to controlling a single modem The modem serial port and control lines are defined using macro constants which should match with the definitions of the PPP interface The sample program Samples PPP modem_test c shows the general idea for using MODEM LIB 7 3 Operation Details for PPP over Serial The first s
164. f accepting multiple incoming sessions Although multiple calls to udp open may normally be made with the same 1port num ber only one udp open should be made on a particular lport if the remip is set to 1 Essentially the broadcast and nonbroadcast protocols cannot co exist Be sure that you have allocated enough UDP socket buffers with MAX UDP SOCKET BUFFERS Note that this macro defaults to 0 so any usage of udp open requires a definition of MAX UDP SOCKET BUFF ERS in your program 260 rabbit com TCP IP Manual Vol 1 udp open cont This function also works with multicast addresses If remip is a multicast address then pack ets sent with this function will go to the multicast address and packets received will also be from that multicast address Also if enabled IGMP will be used to join the multicast groups The group will be left when the socket is closed Note that if port is 0 and remip is a multi cast address the port will not be filled in on the first received datagram that is the socket is non binding to the port PARAMETERS s lport remip port datahandler RETURN VALUE Pointer to a UDP socket Local port Acceptable remote IP 0 to connect on first datagram or 1 for broadcast Acceptable remote port or 0 to connect on first datagram Function to call when data is received NULL for placing data in the sock et s receive buffer 0 Failure e g
165. f bytes written 1 Error LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock write sock fastread sock read sockerr sock flush sock flushnext udp send udp sendto sock xfastwrite 204 rabbit com TCP IP Manual Vol 1 sock flush void sock flush tcp Socket s DESCRIPTION sock flush will flush the unwritten portion of the TCP buffer to the network No guar antee is given that the data was actually delivered In the case of a UDP socket no action is tak en sock flushnext is recommended over sock flush PARAMETERS s Pointer to a socket RETURN VALUE None LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock flushnext sock fastwrite sock write sockerr TCP IP Manual Vol 1 rabbit com 205 sock flushnext void sock flushnext Cep Socket s DESCRIPTION Writing to TCP sockets does not guarantee that the data are actually transmitted or that the re mote computer will pass that data to the other client in a timely fashion Using a flush function will guarantee that DCRTCP LI B places the data onto the network No guarantee is made that the remote client will receive that data sock flushnext is the most efficient of the flush functions It causes the next function that sends data to the socket to flush meaning the data will be transmitted immediately Several functions imply a flush and do not require an additional
166. f the following are obviously applicable e IPTOS CHEAP minimize monetary cost Used for bulk transfers where speed or reliability are not of concern and you are paying by the packet e IPTOS RELIABLE maximize reliability e IPTOS CAPACIOUS maximize throughput e IPTOS FAST minimize delay e IPTOS SECURE maximize security IP does not guarantee that the TOS setting will improve the objective performance however it at least guarantees that performance will not be any worse than if the default TOS was selected In other words it doesn t hurt to specify TOS and it may even help TOS can be set on a packet by packet basis however the TCP stack only allows a TOS to be set for a socket TCP or UDP which is used for all packets until changed The function sock set tos is used to set the TOS field 4 2 5 ARP Cache Considerations ARP Address Resolution Protocol is only relevant for non PPPoE Ethernet not PPP interfaces Although it works in the background mainly to translate IP addresses into Ethernet MAC addresses there are some considerations which apply to TCP and UDP performance There is a limited size cache of address mapping entries known as the ARP Table The cache is necessary in order to avoid network traffic each time a socket connection is established It must be sized appropri ately to avoid cache misses as much as possible If the controller board is to be
167. f you apply one of the PPP specific parameters to a non PPP interface IFS PPP INIT Sets up PPP with default parameters This should be used before any other PPP setting parameters IFS_PPP_SPEED Set serial PPP speed in bits per second longword IFG PPP SPEED Get serial PPP speed longword IFS PPP ACCEPTIP Accept peer s idea of our local IP address bool IFG PPP ACCEPTIP Are we accepting peer s idea of our local IP address bool IFS_PPP_REMOTEIP Try to set peer s IP address longword IFG PPP REMOTEIP Will we try to set peer s IP address longword IFS PPP ACCEPTDNS Accept a DNS server IP address from peer bool IFG PPP ACCEPTDNS Will we accept a DNS server IP address from peer bool IFS PPP REMOTEDNS Set DNS server IP addresses for peer primary longword secondary longword IFG PPP REMOTEDNS Get DNS server IP addresses primary longword and secondary longword IFS PPP AUTHCALLBACK Called when a peer attempts to authenticate int The authentication callback is invoked with the following parameters int auth cb char user int userlen char pass int passlen The parameters indicate userid password and their lengths not null terminated The call back should return 1 if OK 0 if not authorized TCP IP Manual Vol 1 rabbit com 131 ifconfig cont d IFS PPP REMOTEAUTH Sets username and password to give to peer char char IFG PPP REMOTEAUTH Get user
168. figuration items not defined by default Do not announce our hardware address at sock init This macro is undefined by default Do not uncomment it in NET LIB Instead define it in your mainline C program before including the networking libraries ARP CONFLICT CALLBACK Define a function to call in case of IP address conflict This function takes a arp Header pointer as the first and only parameter It should return one of e 0 do not take any action e OxFFFFFFFF abort all open sockets with NETERR IPADDR CONFLICT e other new IP address to use Open sockets aborted with NETERR IPADDR CHANGE This macro is undefined by default Do not uncomment it in NET LIB Instead define it in your mainline C program before including the networking libraries ARP_TABLE SIZE Define to the number of ARP table entries The default is set to the number of interfaces plus 5 entries for every non PPPoE Ethernet interface The maximum allowable value is 200 ARP_ROUTER_TABLE SIZE Define the maximum number of routers Defaults to the number of interfaces plus an extra en try for each non PPPoE Ethernet 78 rabbit com Network Addressing ARP amp DNS 5 3 DNS Functions Starting with Dynamic C 7 05 non blocking DNS lookups are supported Prior to DC 7 05 there was only the blocking function resolve Compatibility has been preserved for resolve MAX DOMAIN LENGTH and DISABL
169. g or DHCP then further directed ping or DHCP configurations for that interface are not allowed If desired at runtime you can issue ifconfig IF ETHO IFS ICMP CONFIG RESET IFS END to allow another directed ping configure 2 2 2 6 Remote Configuration via Advanced Device Discovery Protocol ADDP The ADDP lib library contains a UDP based daemon that will listen for requests from an ADDP client such as the Digi Device Discovery utility included in the Utilities ADDP directory of your Dynamic C installation The Discovery utility runs on a Windows PC and can discover ADDP enabled devices on the local network and modify their network configuration with the appropriate password The sample program Samples tcpip addp c demonstrates using the Discovery utility to remotely configure a device that can store its network configuration in the UserBlock non volatile storage and then use that stored configuration at startup to configure the network interface 2 2 2 7 Console Configuration Via Zconsole lib The zconsole lib library contains routines for allowing an external serial or telnet terminal to issue configuration commands Basically the commands call ifconfig to perform the actual requests or obtain information Using a dumb terminal connection over a serial port presents no special difficulties for network configuration Using telnet over the internet obviously requires a working T
170. g tO ZETO EE 56 tep tiek ie ee ee ee 267 GEE EE ER E 9 UDP Socket VO Zconsole configuration 2 0 e ee ee 14 udp CLOSE ie ee nn 269 ISPs and MAC addresses L se ee ee ee 14 udp eXtODEN iese ee ee RA GR RA 270 K UdP OPEN ini ie EE 272 udp peek i ae 274 KEEPALIVE NUMRETRYS iese see ee ere ese 44 U P rech veecscscsssessescsecscsescesscsescsceesscseeeees 275 KEEPALIVE WAITTIME ossessi 44 udp recvfrom iese ee ee ee ee RA GR RA 276 udp Sen iii N EE Ee 277 L wep Senile SEENEN SE LTE ee 78 88 udp waitopen iese ee ee Re Ee GR RA 279 skin Er divers 6 udp waitsend ss sse ee ee ee RA GR RA n 9221 IN dp Xsendto sia EES ERS EG S ERG Ek eR s De 281 UDP Socket VO pre DC 7 05 TCP IP Manual Vol 1 rabbit com 275 M TOS science isn aac 85 performance optimizing owen ke 77 MAC address EE 14 85 PR DR Age 7 macros port numbers ooo ee eek GR RA RR AR Re Re Re Ee ee 54 ARP EE 89 PPP driver eerste 95 BOOTP DHCP en 36 EE A0 buffer resource sizing we se ek Ge Ge ee ee ee 39 ii a L A oc arctan eee 91 R including additional functionality 36 interface configuration sees ese seek ek Ge ee ke 4 RETRAN STRAT TIME sees 44 82 interface configuration 7 30 and later 42 FOE eent dee N EE 89 90 94 B RE 78 interface selection se se ee ee ee Re Re RR Gee 5 link layer driver oe eee se se se ek Ge ee ee Ge Ge ee ek ek ee 7 S miscellaneous eee Ge ee GR Gee ee eke 46 network configuration pre 20
171. gram and the sender if you opened in broadcast mode You may also receive the datagrams very guickly so you must have a mechanism to buf fer them Once a socket is opened with udp open you canuse sock recv init to initialize that socket for sock recv and sock recv from Notethat sock recv and related functions are incompatible with sock read sock fastread sock gets andsock_getc Once you have used sock recv init voucan no longer use the older style calls sock recv init installs a large buffer area which gets segmented into smaller buffers Whenever a UDP datagram arrives DCRTCP LIB stuffs that datagram into one of these new buffers The new functions scan those buffers You must select the size of the buffer you submit to sock recv_init make it as large as possible say 4K 8K or 16K For a sample program see Example using sock recv listed under sock_recv PARAMETERS s Pointer to a UDP socket space Buffer of temporary storage space to store newly received packets len Size of the buffer RETURN VALUE 0 LIBRARY DCRTCP LIB SEE ALSO sock recv from sock recv TCP IP Manual Vol 1 rabbit com 227 sock resolved int sock resolved void s DESCRIPTION Check whether the socket has a valid destination hardware address This is typically used for UDP sockets but may also be used for TCP sockets If this function returns zero FALSE then any datagrams you send using udp_send
172. gram pay load that would be sent without fragmentation at the IP level Note the maximum payload depends on the interface that is selected Since this is not known a priori the interface with the largest MTU is arbitrarily selected LIBRARY NET LIB SEE ALSO tep open tep listen sock close sock abort tcp_tick sock established sock alive sock waiting sock readable udp open udp sendto 240 rabbit com TCP IP Manual Vol 1 sock write int sock_write tcp Socket s byte dp int len DESCRIPTION Writes up to Len bytes from dp to socket s This function busy waits until either the buffer is completely written or a socket error occurs If sock vield has been called the user de fined function that is passed to it will be called in a tight loop while sock write is busy waiting For UDP sock write will send one or more records For TCP the new data may be transmitted if enough data is in the buffer or sufficient time has expired or the user has explicitly used sock flushnext to indicate this data should be flushed immediately In either case there is no guarantee of acceptance at the other end Starting with Dynamic C 7 05 this function is only valid for TCP sockets For UDP sockets use udp_send orudp_sendto PARAMETERS s Pointer to a socket dp Pointer to a buffer len Maximum number of bytes to write to the buffer RETURN VALUE Number of bytes written or 1 on an error LIBRAR
173. guration Using if EG EN Oe See EE 12 2 2 2 5 Directed Ping 13 2 2 2 6 Remote Configuration via Ad vanced Device Discovery Protocol AD D I EE AE EN 14 2 2 2 7 Console Configuration Via Zconsole Ub ee ee see ee 14 2 2 3 Media Access Control MAC Address 14 2 3 Dynamically Starting and Stopping Interfaces 15 2 3 1 Testing Interface Status 15 2 3 2 Bringing an Interface Up 15 2 3 3 Bringing an Interface Down 16 2 4 Setting Up Wi Fi Interfaces sesse see ee 16 2 4 1 Wi Fi Compile Time Configuration 17 2 4 1 1 Infrastructure Open No En cryption Configuration 17 2 4 1 2 Ad hoc Open No Encryption Configuration e enennnnnnnn 18 2 4 1 3 Infrastructure WEP Encryption Configuration e eenennznnzzni 19 2 4 1 4 Infrastructure WPA TKIP En cryption Configuration Pre Shared Key 20 2 4 1 5 Infrastructure WPA2 CCMP Encryption Configuration Pre Shared ew e EE EA EE 21 2 4 1 6 Infrastructure WPA Enterprise using EAP TLS and CCMP Encryption 22 2 4 1 7 Infrastructure WPA Enterprise using PEAP and TKIP Encryption 24 2 4 1 8 Specifying a Pre Shared Key 25 2 4 1 9 Ad hoc WPA TKIP or WPA2 CCMP Encryption Configura tion RE 25 2 4 2 Wi Fi Runtime Configuration 25 2 4 2 1 Runtime Configuration Starting with Dynamic C 10 40 L 25 2 5 Setting Up PPP Interfaces eee 25 2 5 1 PPP over Asynchronous Serial 25 2 5 2 PPP ove
174. h does not care about MAC addresses DHCP can use the MAC address to determine that the same device is connecting and assign it the same IP address as before 2 3 Dynamically Starting and Stopping Interfaces Starting with version 7 30 Dynamic C allows interfaces to be individually brought up and down by calling the ifup ifdown or ifconfig functions The initial desired state of the interface is specified using the IFCONFIG macros By default interfaces are not brought up when sock init is called at boot time Only if the IFCONFIG macro contains an IFS_UP directive will the interface be brought up at boot time Most applications should not need to dynamically change the interface status The exception to this may be PPP over serial interfaces where a modem is used to dial out to an ISP on demand 2 3 1 Testing Interface Status There are two functions for testing the current status of an interface ifstatus andifpending The function if status merely returns a boolean value indicating whether the interface is up If the return value is true non zero then the interface is ready for normal TCP IP communications Otherwise the interface is not yet available it may either be down or in the process of coming up ifpending gives more information its return value indicates not only the current state but also if the state is in the process of changing This function is very handy when using WiFi in p
175. he address was resolved The given handle will no longer be valid af ter this value is returned DO ESOLVE AGAIN The resolve process has not completed call this function again ESOLVE FAILED The DNS server responded that the given host name does not exist The given handle will no longer be valid if RESOLVE FAILED is returned RESOLVE TIMEDOUT The request has been cancelled because a response from the DNS server was not received before the last time out expired The given handle will no longer be valid after this value is returned DO T RESOLVE HANDLENOTVALID There is no DNS lookup occurring for the given handle RESOLVE NONAMESERVER No nameserver has been defined LIBRARY DNS LIB SEE ALSO resolve name start resolve cancel resolve TCP IP Manual Vol 1 rabbit com 177 resolve name s tart int resolve name start char hostname DESCRIPTION Starts the process of resolving a host name into an IP address The given host name is limited to DNS MAX NAME characters which is 64 by default 63 characters the NULL terminator CH Ifa default domain is to be added then the two strings together are limited to DNS_MAX NAME Ifhostname does not contain a then the default domain MY DOMAIN if provided is ap pended to hostname If hostname with the appended default domain does not exist
176. he following program is a general outline for a Dynamic C TCP IP program The first couple of defines set up the default IP configuration information The memmap line causes the program to compile as much code as it can in the extended code window The use line causes the compiler to compile in the Dynamic C TCP IP code using the configuration data provided above it Program Name Samples tcpip icmp pingme c Starting with Dynamic C 7 30 the network addresses are initialized by defining the following macro to identify the desired configuration in the file tcp config lib sy define TCPC Prior to Dyna your local IP administrator S define M define M define M memmap xmem use dertcp main SOEK init ror ee ONFIG 1 static configuration of single Ethernet interface mic C 7 30 you must change the following values to whatever address netmask and gateway are Contact your network for these numbers y TP ADDRESS 110 10763101 Y NETMASK 112667 256 2550 Y GATEWAY 10 10 6 19 Lila 5 TOO tiek NUET To run this program start Dynamic C and open the Samples TCPIP ICMP PINGME C file If you are using a Dynamic C version prior to 7 30 edit the MY IP ADDRESS MY NETMASK and MY GATEWAY macros to reflect the appropriate values for your device Otherwise edit your tcpconfig lib orcustom_config 1ib file with appropri
177. his was DCRTCP LIB SEE ALSO htons ntohl ntohs TCP IP Manual Vol 1 rabbit com 121 htons word htons word value DESCRIPTION Converts host ordered word to a network ordered word This function is necessary if you are implementing standard internet protocols because the Rabbit does not use the standard for net work byte ordering The network orders bytes with the most significant byte first and the least significant byte last On the Rabbit the bytes are in the opposite order within each 16 bit sec tion PARAMETERS value Host ordered word RETURN VALUE Host ordered word in network ordered format e g htons 0x1122 returns 0x2211 LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO htonl ntohl ntohs 122 rabbit com TCP IP Manual Vol 1 ifconfig int ifconfig int iface DESCRIPTION This function sets and gets network parameters at runtime An arbitrary number of parameters may be set or retrieved in one call This function replaces tcp_config for setting network parameters at runtime In addition it allows retrieval of parameters and supports multiple interfaces An arbitrary number of pa rameters may be set or retrieved in one call Example ifconfig IF_ETHO IFS DOWN FS IPADDR aton 10 10 6 100 FS NETMASK OxFFFFFFOOuL IFS ROUTER SET aton 10 10 6 1
178. hostid TCP IP Manual Vol 1 rabbit com 117 gethostname char gethostname char name int length DESCRIPTION Gets the host portion of our name For example if the controller s internet address is test mynetwork com the host portion of the name would be test The host name can be changed by the sethostname function PARAMETERS name Buffer to place the name length Maximum length of the name or zero for the internal host name buffer Do not modify this buffer RETURN VALUE length 21 Return name length 0 Return internal host name buffer do not modify LIBRARV BSDNAME LIB 118 rabbit com TCP IP Manual Vol 1 getpeername int getpeername sock type ze void dest int len DESCRIPTION Gets the peer s IP address and port information for the specified socket PARAMETERS S dest len RETURN VALUE 0 Success 1 Failure LIBRARY BSDNAME LIB SEE ALSO getsockname Pointer to the socket Pointer to sockaddr to hold the socket information for the remote end of the socket The data structure is typedef struct sockaddr word s_type reserved word s port port or 0 not connected longword s_ip IP addr or 0 if not connected byte s_spares 6 notused for tcp ip connections Pointer to the length of sockaddr A NULL pointer can be used to repre sent the sizeof struct sockaddr TCP IP Manual Vol 1 rabbit com 1
179. hould work with most browsers It allows a single connection at a time but can be extended to allow multiple connections In general when defining the set of states for a socket connection you will need to define a state for each point where the application needs to wait for some external event At a minimum this will include states when waiting for e session establishment e new received data e space in the transmit buffer for write data e session termination For non trivial application protocols the states in between session establishment and session termination may need to be embellished into a set of sub states which reflect the stage of processing of input or output Sometimes input and output states may need to overlap If they do not then you typically have a step by step protocol Otherwise you have an application that uses receive and transmit independently Step by step protocols are easier to implement since there is no need to be able to overlap two or more sets of state TCP IP Manual Vol 1 rabbit com 55 For read states which are waiting for some data to come in from the peer you will typically call one of the non blocking socket read functions to see if there is any data available If you are expecting a fixed length of data e g a C structure encoded in the TCP data stream then it is most convenient to use the sock aread function which was introduced in Dynamic C 7 30 Otherwise if you cannot te
180. hroughput This is achieved by using the largest practical buffer sizes processing data in the largest possible chunks and minimizing data copying Since the Rabbit processor is CPU bound when dealing with high speed transfers over Ethernet every time the data is handled it reduces the ultimate throughput The Nagle algorithm should be left ON Time outs should be set to generously high values to avoid unnec essary retransmissions The TOS should be set to IPTOS CAPACIOUS Bulk TCP transfers are most efficient when the packet size is the largest possible The largest packet size is limited to the MTU size of the network connection You can assume that 600 bytes is a reasonable MTU for Internet connections You can use up to 1500 for all supported interface types except PPPoE which is limited to 1492 however it is best to use 600 if Internet connections are expected If the Internet MTU is in fact less than the expected value then packets may become fragmented which lowers efficiency You cannot do much about this except reduce the MTU When the MTU is determined the maximum TCP packet data length will usually be the MTU minus 40 The 40 bytes are for the IP and TCP header overhead For a 600 byte MTU the maximum TCP data seg ment size will be 560 Thus TCP performance will be best if data is handled in multiples of 560 bytes It is not quite this simple however When a TCP connection is opened both sides can agree to use differ
181. ication protocols such as HTTP and FTP have their own tick functions e g http handler and ftp tick When you call such a function there is no need to call tcp tick since the other tick function will always do this for you 3 9 1 tcp_tick for Robust Applications It goes without saying that your application should be designed to be robust You should be aware that an open TCP socket may become disconnected at any time The disconnection can arise because of a time out caused by network problems or because the peer application sent a RST reset flag to abort the connec tion the interface went down or even because another part of your application called sock abort Your application should check for this condition preferably in the main socket processing loop by calling tcp tick with the socket address Since tcp_tick needs to be called regularly this does not add much overhead if you have a single socket For applications which manage multiple sockets you can use the sock alive function new for Dynamic C 7 30 If tcp tick or sock alive returns zero for a socket then the socket may be re opened after your application recovers 54 rabbit com TCP and UDP Socket Interface Regular checking of socket status is also convenient in that it can simplify the rest of your application In effect checking socket status in your main application loop concentrates socket error handling at a single point in the code There
182. icient buffer size would be 16 bytes ip The IP address to convert RETURN VALUE Pointer to the dotted decimal string pointed to by s LIBRARY IP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO inet addr 152 rabbit com TCP IP Manual Vol 1 ip iface byte ip iface longword ipaddr int local only DESCRIPTION Given an IP address this function return the interface number for that address If ipaddr is an address on one of the local subnets then the interface to that subnet is returned If the address is not local then the local only parameter determines the result If local_only is 1 then IF ANY will be returned for a non local address Otherwise the router for function is invoked to find the correct router the interface for the router is returned PARAMETERS ipaddr IP address of an external host local_only 0 allow non local addresses returns interface for router 1 return IF ANY for non local addresses RETURN VALUE Interface number 0 1 LIBRARY IP LIB SEE ALSO router for F_MAX 1 of possibly 1 IF ANY 0xFF TCP IP Manual Vol 1 rabbit com 153 ip print ifs void ip print ifs void DESCRIPTION Print all interface table entries This is for debugging only since the results are printed to the Dynamic C Stdio window There are 8 fields for each interface entry The interface number IP addr The local home IP address of this interf
183. id PPPsetAuthenticatee char username char password DESCRIPTION Sets up the driver to send a PAP authentication message to a peer when requested PARAMETERS username password RETURN VALUE None LIBRARY PPP LIB The username to send to the peer The argument string is not copied so it must stay constant The password to send to the peer The argument string is not copied so it must stay constant PPPsetAuthenticator void PPPsetAuthenticator char username char password DESCRIPTION Sets up the driver to require a PAP authentication message from a peer Negotiation will fail un less the peer sends the specified username password pair This function is generally used when the Rabbit is acting as a dial in server PARAMETERS username password RETURN VALUE None LIBRARY PPP LIB The user name that the peer must match for the link to proceed The argu ment string is not copied so it must stay constant The password that the peer must match for the link to proceed The argu ment string is not copied so it must stay constant TCP IP Manual Vol 1 rabbit com 173 PPPshutdown int PPPshutdown unsigned long timeout DESCRIPTION Sends a Link Terminate Request packet Waits for link to be torn down PARAMETERS timeout Number of milliseconds to wait before giving up on a response from the peer RETURN VALUE 1 Shutdown succeeded 0 Shutdown timed out LIBRARY P
184. ig parameter identifiers for Wi Fi Enterprise mode authentication 2 5 Setting Up PPP Interfaces PPP interfaces are slightly more complicated to configure than non PPPoE Ethernet They also generally take more time to become established The advantage of PPP is that it can be made to run over a wide variety of physical layer hardware on Rabbit based boards this includes the asynchronous serial ports as well as Ethernet using PPPoE Use of PPP over asynchronous serial allows boards with no Ethernet hardware to communicate using TCP IP protocols Starting with Dynamic C version 7 30 the process of establishing a PPP link has been more tightly integrated into the library using the i fup ifdown ifconfig functions Prior to 7 30 your application had to be hard coded to use either Ethernet PPP or PPPoE PPP Driver on page 83 explains the details of establishing PPP interfaces The following sections provide an overview 2 5 1 PPP over Asynchronous Serial There are two basic scenarios for use of PPP over asynchronous serial shortened here to just PPP The first is a direct hard wired connection to another machine The second is a connection to an ISP Internet TCP IP Manual Vol 1 rabbit com 25 Service Provider via a modem Modem connections introduce another layer of complexity in that the modem itself must be instructed to connect to the desired peer s modem most often via the PSTN Public Switched Telephone Network M
185. ill be 28 rabbit com TCP IP Initialization assigned the value of MAX SOCKETS for backwards compatibility If neither macro is defined MAX TCP SOCKET BUFFERS defaults to 4 MAX UDP SOCKET BUFFERS Starting with Dynamic C version 7 05 this macro determines the maximum number of UDP sockets with preallocated buffers It defaults to 0 SOCK BUF SIZE deprecated This macro determines the size of the socket buffers A TCP socket will have two buffers of size SOCK BUF SIZEJ2 for send and receive A UDP socket will have a single buffer of size SOCK BUF SIZE Both types of sockets take the same total amount of buffer space This macro has been replaced by TCP_BUF SIZE and UDP BUF SIZE TCP BUF SIZE Starting with Dynamic C 7 05 TCP and UDP socket buffers are sized separately TCP BUF SIZE defines the buffer sizes for TCP sockets It defaults to 4096 bytes Backwards compatibility exists with earlier version of Dynamic C if SOCK BUF SIZE is defined TCP BUF SIZE is assigned the value of SOCK BUF SIZE If SOCK BUF SIZE is not defined but tcp MaxBufSize is then TCP BUF SIZE will be assigned the value of tcp MaxBufSize 2 tcp MaxBufSize deprecated This use of this macro is deprecated in Dynamic C version 6 57 and higher it has been replaced by SOCK_BUF_
186. ill have been aborted The action of IFS _IPADDR depends on the current interface state If the i f has the IFS DHCP flag set then this parameter sets only the fallback IP address without chang ing the current i f status Otherwise the i f is reconfigured with the new address immedi ately which may require it to be brought down then up IFS_ I PADDR always sets the DHCP fallback address but you can also use the IFS_DHCP_FB_IPADDR parameter to set the fallback address without ever changing the i f status IFG IPADDR Get home IP address longword IFS_NETMASK Set netmask longword IFG NETMASK Get netmask longword IFS_MTU Set maximum transmit unit MTU word IFG MTU Get MTU word IFS ROUTER SET Delete all routers then set this one as a default router longword This parameter does not care about the value of iface because it is not specific to an in terface TCP IP Manual Vol 1 rabbit com 125 ifconfig cont d IFS ROUTER SET STATIC Set static router IP address of router longword subnet served longword subnet mask longword Static router means a router that handles routing to a specified subnet destination When a router is selected for a given IP address the most specific static router will be used For example given the following setup Router Subnet Mask 10 10 6 1 0 0 10 10 6 2 10 99 0 0 255 255 0 0 10 10 6 3 10 99 57 0 255 25
187. ils for PPPoE PPPoE avoids most of the complexities of PPP over serial This is because the hardware Ethernet is easy to set up and no modems are involved Actually you might have something called a DSL modem or sim ilar but this type of modem does not have to do dial up in the usual sense PPPoE is selected by defining the symbol USE PPPOE to be a non zero value Currently the only value supported is 1 with 2 reserved for future controller boards that have a second Ethernet chip If you define USE_PPPOE then you should also define IFCONFIG_PPPOEO to contain initialization options passed to ifconfig When PPPoE is specified the interface is referred to by IF_PPPOEO IF_PPPOE1 is reserved for future boards 7 5 Link Control Protocol Options Link Control Protocol is the first sub protocol used on a PPP link The following LCP options are sup ported by the Rabbit PPP system Table 7 2 Configuration Options Geis fee Meaning of Option Type 01 MRU Maximum Receive Unit 02 ACCM Async Control Character Map 03 Auth Authentication Type PAP only 05 Magic Number 07 PFC Protocol Field Compression 08 ACFC Address and Control Field Compression For more information on these options refer to RFC 1661 The Point to Point Protocol PPP at http www faqs org rfcs rfcl661 html 86 rabbit com PPP Driver 7 6 Configuring
188. ing longword host longword countnum byte ttl byte tos longword theid DESCRIPTION Generates an ICMP request for host PARAMETERS host IP address to send ping countnum User defined count number ttl Time to live for the packets hop count 255 is a standard value for this field See sock set tt1 for details tos Type of service on the packets See sock_set_tos for details theid The identifier that was sent out RETURN VALUE 0 Success 1 Failure unable to resolve hardware address 1 Failure unable to transmit ICMP request LIBRARY ICMP LIB SEE ALSO _chk ping ping sock set ttl sock set tos TCP IP Manual Vol 1 rabbit com 187 setdomainname char setdomainname char name DESCRIPTION The domain name returned by getdomainname and used for resolve is set to the value in the string pointed to by name Changing the contents of the string after a setdomainname will change the value of the system domain string It is not recommend ed Instead dedicate a static location for holding the domain name setdomainname NULL isan acceptable way to remove any domain name and subse quent resolve calls will not attempt to append a domain name PARAMETERS name Pointer to string RETURN VALUE Pointer to string that was passed in LIBRARY BSDNAME LIB SEE ALSO getdomainname sethostname gethostname getpeernam getsockname T 188 rabbit com TCP IP Manual Vol 1
189. ing sent where one big packet would be preferable The main reason to override the default and disable the Nagle algorithm is for applications that require the least possible delay between writing data to the socket and its receipt by the peer application This comes at the expense of efficiency so you should carefully consider whether the application really requires the slight reduction in delay When Nagle is turned off using the macro tcp_set_nonagle amp socket transmit processing is changed so that TCP tries to transmit a packet for each call of a socket write function such as sock fastwrite If Nagle is on which is the default state or can be set using tcp set nagle amp socket a new packet will only be sent if there is no outstanding unacknowledged data Thus on a slow network where acknowledgements from the peer take a substantial amount of time to arrive fewer packets will be sent because there is a greater chance that there is some unacknowledged data The difference may be illustrated by the following example suppose that a TCP socket connection is cur rently established and quiescent i e there is no outstanding data to be acknowledged everything is up to date The network round trip time is 550ms The application writes ten single characters to the socket at 100ms intervals each With Nagle turned off ten packets will be sent at approximately 100ms intervals Each packet will contain a 40 byte header IP and TCP wi
190. ing that holds the IP address to convert RETURN VALUE 0 Error string has invalid format gt 0 Success long value of IP address LIBRARY IP LIB TCP IP Manual Vol 1 rabbit com 111 _chk ping longword chk ping longword host ip longword sequence number DESCRIPTION Checks for any outstanding ping replies from host chk ping should be called frequently with a host IP address If an appropriate packet is found from that host IP address the sequence number is returned through sequence number The time difference between our request and their response is returned in milliseconds PARAMETERS host_ip IP address to receive ping reply from sequence number Sequence number of reply RETURN VALUE Time in milliseconds from the ping request to the host s ping reply If chk ping returns OxffffEFffL there were no ping receipts on this current call LIBRARY ICMP LIB SEE ALSO ping send ping 112 rabbit com TCP IP Manual Vol 1 dhcp acquire int dhcp acquire void DESCRIPTION This function acquires a DHCP lease that has not yet been obtained or has expired or was re linquished using dhcp_ release Normally DHCP leases are renewed automatically however if the DHCP server is down for an extended period then it might not be possible to re new the lease in time in which case the lease expires and TCP IP should not be used When the lease expires tcp tick will return 0 and the global variable f
191. int all devices on the wireless network simply communicate directly with each other al The macro W _ MODE was deprecated in Dynamic C 10 40 IFC_WIFI_CHANNEL Sets the channel 1 14 to use for an ad hoc network The macro WIFI OWNCHANNEL was deprecated in Dynamic C 10 40 IFC WIFI REGION default IFPARAM WIFI REGION AMERICAS This macro sets the channel range and maximum power limit for the region selected Different regions have different regulations on Wi Fi communication This macro can have the value e IFPARAM WIFI REGION AMERICAS Americas including the US ch 1 11 e IFPARAM WIFI REGION AUSTRALIA Australia ch 1 11 e IFPARAM WIFI REGION CANADA Canada ch 1 11 e IFPARAM WIFI REGION CHINA China ch l 11 e IFPARAM WIFI REGION EMEA Europe Middle East Africa ch 1 13 e IFPARAM WIFI REGION FRANCE France ch 10 13 e IFPARAM WIFI REGION ISRAEL Israel ch 3 11 e IFPARAM WIFI REGION JAPAN Japan ch l 13 e IFPARAM WIFI REGION MEXICO_INDOORS Mexico indoors ch 1 11 e IFPARAM WIFI REGION MEXICO OUTDOORS Mexico outdoors ch 9 11 The macro WIFI REGION REQ was deprecated in Dynamic C 10 40 IFC WIFI ENCRYPTION default IFPARAM WIFI ENCR NONE This parameter controls the type of enc
192. interval increases Throughput is always less than bandwidth for finite TCP IP Manual Vol 1 rabbit com 65 time intervals or practical protocols since there is usually some overhead to establish the connection in the first place as well as overhead during the transmission itself The latency of a channel can have several definitions For our purposes it is the minimum possible time delay between sending of a message its receipt by the other end and the reception of a reply in other words the round trip time RTT On electrical and radio channels the latency is related to the physical length of the link and the speed of light On channels which are more complex than a simple electrical con nection there may also be intermediate nodes which buffer the data being transmitted this can add delays which are much larger than the speed of light between the end nodes Note that round trip times are important for most communications protocols not only do we want to send data but we also want to receive an acknowledgment that the other end received the data Some examples of real networks may be helpful here Note that the values given for RTT are approxima tions since they depend on the length of the connection the sizes of packets sent or intermediate nodes Throughput is specified for an infinite time interval assuming TCP over IP with 600 bytes of data per packet and no data in the acknowledgment The RTT figure assumes the same size pac
193. ion of this structure is typedef struct word myport Originating port on this host byte icmp type One of the ICMPTYPE values byte icmp code The corresponding ICMP code udp icmp message Please see sock mode for more information about the modes UDP_MODE_ICMP and UDP MODE DICMP PARAMETERS s Pointer to socket s data structure buffer Buffer where the UDP datagram will be stored len Maximum length of the buffer remip IP address of the remote host of the received datagram remport Port number of the remote host of the received datagram RETURN VALUE 20 Number of bytes received 1 No datagram waiting 2 Error not a UDP socket 3 The returned buffer contains an ICMP error which was queued previously LIBRARY UDP LIB SEE ALSO udp_recv udp send udp sendto udp open udp peek 264 rabbit com TCP IP Manual Vol 1 udp_send int udp_send udp Socket s char buffer int len DESCRIPTION Sends a single UDP datagram on a UDP socket It will not work for a socket for which the remip parameter to udp open was 0 unless a datagram has first been received on the socket If the remip parameter to udp open was 1 the datagram will be send to the broadcast address PARAMETERS s Pointer to socket s data structure buffer Buffer that contains the UDP datagram len Length of the UDP datagram RETURN VALUE 20 Number of bytes sent 1 Failure 2 F
194. ioned in the TCP TWTIMEOUT description you can specify that certain TCP port numbers have the special property of being reserved If a port is reserved it has two effects e A number of pending connections can be queued while a socket connection is established The pending connections form a FIFO queue with the longest outstanding pending connection becoming active after the current connection is closed e The time wait time out is truncated when the current connection is closed Together these increase the performance of passively opened sockets which are designed to implement server functions such as FTP and HTTP servers Reserving a port has no effect on actively opened sockets De clients and does not affect its performance during the life of each connection The functions tcp_reserveport and tcp clearreserve respectively enable and disable a TCP port number from being treated in this manner 72 rabbit com Optimizing TCP IP Performance 4 2 4 Type of Service TOS Type Of Service is an IP Internet Protocol header field that causes routers in the Internet to handle pack ets according to the specified service level TOS has not been widely deployed in the past but recently Internet routers have been able to take advantage of the TOS field TOS generally takes one and only one of a pre specified number of values The currently available val ues are e IPTOS DEFAULT the default used when none o
195. ipit deeg RD EE 168 i valid TAGS esse gesek Rds eed 169 ModemClose see Ee ese Ee 170 ModemConnected ees see ee 170 ModemExpect dee EG 171 ode feu iss sesse iese es 171 Modemlnit ius tiese ke SR DES EE Re 172 ModemOpen E 172 ModemReady iese sesse ee 173 ModemRinging iese ENE gen 173 ModemSend eise see ee 174 ModemStartPPP ees ee ee 174 multicast jOiNgrOUP esse ee 175 multicast leavegroup ccceeee 176 ENEE 177 fa sirain rde aias 178 pd_getaddress uses Ede Ed 179 GE EE 180 pd_powerdown sees se see ee 181 pd_powerup EE iskaikbiiskjiiiid 182 PRP ASV E 184 E E 184 PPPsetAuthenticatee 0000 185 PPPsetAuthenticator ss semen 185 io od EE 186 psocket iese dee ie ee oe 186 TCP IP Manual Vol 1 rabbit com 279 R SOCK teadable EERS EE 235 TEEOIVE ons ee GN EG ie 187 SOCK WEL eege 236 resolve_cancel AR kas 188 sock recy from aansien EE 238 resolve name check esse 189 sock _recv_init iese dee 239 resolve name start eise ee ese se ee 190 sock _resolved eni REKE 240 EE ee ed 191 SOCK BEE IOS geesde 241 POMERAT Ee 192 SOCK set ttl Zeie 242 HEE dell GUN esse 193 sock tbleft eege 244 router_delete sacisesccasapsdssasessecadesecca 193 ee diie iS ncesananoeinks 245 TOUTT TOP aas esse toksen EE S 194 Sock TURE sutiukazzetitasitkasze tika eebuza 246 router_for_iface iese seeks Se De 195 BOCK tiek iseer ERROR Eed 247 router Bride ie Re EG 197 soek
196. is more than a simple boolean it also indicates the amount of data the socket is guaranteed to deliver witha sock fastread call that immediately follows provided that the buffer length is at least that long Note a TCP socket may be readable after it is closed since there may be pending data in the buffer that has not been read by the application and it is also possible for the peer to keep send ing data PARAMETERS s TCP or UDP socket pointer RETURN VALUE If parameter is a TCP socket tcp Socket 0 socket is not readable It was aborted by the application or the peer has closed the socket and all pending data has been read by the application This can be used as a de finitive EOF indication for a receive stream non zero the socket is readable The amount of data that the socket would deliver is this value minus 1 which may turn out to be zero if the socket s buffer is temporarily empty or the socket is not yet connected to a peer If parameter is a UDP socket udp_Socket 0 socket is not open non zero socket is open This value minus equals the size of the next datagram in the receive buffer that would be returned by udp_ recvfrom etc Note that ICMP er ror messages are also considered if the socket is set up to receive ICMP messages LIBRARY NET LIB SEE ALSO tcp open tep listen sock close sock abort tep tick sock established sock alive sock waiting sock writable udp open udp recvfrom
197. is necessary if you are im plementing standard internet protocols because the Rabbit does not use the standard for network byte ordering The network orders bytes with the most significant byte first and the least signif icant byte last On the Rabbit the bytes are in the opposite order PARAMETERS value Network ordered word RETURN VALUE Network ordered word in host ordered format e g ntohs 0x2211 returns 0x1122 LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO htonl ntohl htons 166 rabbit com TCP IP Manual Vol 1 pd_getaddress void pd getaddress int nic void buffer DESCRIPTION This function copies the Ethernet address aka the MAC address into the buffer PARAMETERS nic Starting with Dynamic C 7 30 this parameter identifies an Ethernet inter face Use a value of 0 if only one NIC is present buffer Place to copy address to Must be at least 6 byes RETURN VALUE None LIBRARY PKTDRV LIB EXAMPLE main char out lS SOEK imie pd getaddress 0 buf printf Your Link Address is 02x 02x 02x 02x 02x 02x Aa lowit Ol Jowell bu burla bu jaj BuEISIY Ee TCP IP Manual Vol 1 rabbit com 167 pd_havelink int pd_havelink int nic DESCRIPTION Determines if the physical layer link is established for the specified NIC PARAMETERS nic The NIC to check Use a value of 0 if only one NIC is present RETURN VALUE 0 There is no link 10 The link is e
198. isalso used to obtain current configuration items at runtime For example longword ipaddr ifconfig IF ETHO IFG IPADDR amp ipaddr IFS END gets the current IP address of the first Ethernet interface into the variable ipaddr The first parameter of ifconfig is the interface number For certain settings this can also be IF_ANY which means apply the settings to all applicable interfaces The parameters following the first are an arbitrary number of tuples consisting of a parameter identifier followed by the value s for that parameter if any The list of parameters must be terminated by a special identifier IFS END See the documentation for ifconfig fora complete list of parameter identifiers with their expected values 2 2 2 5 Directed Ping This style of configuration also known as ICMP configuration is limited to setting the IP address of the interface It only works on non PPPoE Ethernet interfaces To specify directed ping configuration use the FS ICMP CONFIG parameter ID ina call to ifconfig or in the definition of the IFCONFIG macro for the interface For example define IFCONFIG ETHO IFS ICMP PING 1 for a static configuration or ifconfig IF ETHO IFS ICMP CONFIG 1 IFS END at runtime Note that you can use both directed ping and DHCP on the same interface but direc
199. ists for the given IP address LIBRARY ARP LIB TCP IP Manual Vol 1 rabbit com 103 arp getArpData ATEntry arp_getArpData void DESCRIPTION Return address of arp data RETURN VALUE address LIBRARY ARP LIB arp getArpGateData ATEntry arp getArpGateData void DESCRIPTION Return address of arp gate datall RETURN VALUE address LIBRARY ARP LIB 104 rabbit com TCP IP Manual Vol 1 _arp resolve int arp resolve longword ina eth address ethap int nowait DESCRIPTION Gets the Ethernet address for the given IP address This function is deprecated starting with Dy namic C 7 20 PARAMETERS ina The IP address to resolve to an Ethernet address ethap The buffer to hold the Ethernet address nowait If 0 return within 750 ms else if 0 wait up to 5 seconds trying to resolve the address RETURN VALUE 1 Success 0 Failure LIBRARY ARP LIB TCP IP Manual Vol 1 rabbit com 105 arpresolve check ATHandle arpresolve checkt ATHandle ath longword ipaddr DESCRIPTION Check up on status of resolve process initiated by arpresolve start This function should be called regularly to ensure that an ARP table handle is pointing to the correct entry and that the entry is still current This caller must call tcp_tick if spinning on this function PARAMETERS ath ARP Table Handle obtained from arpresolve start ipaddr IP address specified to arpresolve_ start Ifthis is zero
200. it should be no shorter than 2 hours After the timeout is sent and KEEPALIVE WAITTIME seconds pass another keepalive will be sent in case the first was lost This will be retried KEEPALIVE NUMRETRYS times Both of these macros can be defined at the top of your pro gram overriding the defaults of 60 seconds and 4 retries Using keepalives is not a recommended procedure Ideally the application using the socket should send its own keepalives tcp keepalive is provided because telnet and a few other network protocols do not have a method of sending keepalives at the application level PARAMETERS s Pointer to a socket timeout Period of inactivity in seconds before sending a keepalive or 0 to turn off keepalives RETURN VALUE 0 Success 1 Failure LIBRARY TCP LIB SEE ALSO sock fastread sock fastwrite sock write sockerr TCP IP Manual Vol 1 rabbit com 249 tcp listen int tcp listen Cep Socket s word lport longword remip word port dataHandler t datahandler word reserved DESCRIPTION This function tells DCRTCP LIB that an incoming session for a particular port will be accept ed After a call to tcp listen the function sock established or the macro sock wait established must be called to poll the connection until a session is fully established It is possible for a connection to be opened written to and closed between two calls to the func
201. its for the default interface to come active or fail If the default interface fails to start then exit is called This function is primarily for debugging and sample code since there is an indeterminate wait for the interface to start Production applications may not wish to incur this delay at startup and also they should handle network errors in a manner other that exit since exit is really only useful in a debug environment In particular if the interface is a Wi Fi interface then this function will wait until the interface is associated with an access point If it appears to wait indefinitely then there is probably an error in the configuration such as a mis typed SSID or incorrect security keys NOTE Don t use this function if you intend the network interface to be down after sock init PARAMETER verbose Non zero to print handy message on success Message shows IP address and netmask of default interface Also will print messages at intervals while the interface is in a pending state This can happen if the interface takes a long time to come up In the case of an Ethernet interface if you accidentally leave the cable unplugged then this function will loop forever printing messages at a default 5 second interval RETURN VALUE None May exit NETERR IFDOWN if error LIBRARY NET LIB SEE ALSO sock init ifpending tep tick TCP IP Manual Vol 1 rabbit com 211 sock mode word sock mo
202. ive Open To passively open a socket call tcp listen ortcp extlisten then wait for someone to contact your device You supply the listen function with a pointer toa tcp Socket data structure the local port number others will be contacting on your device and possibly the IP address and port number that will be acceptable for the peer If you want to be able to accept connections from any IP address or any port number set one or both to zero To handle multiple simultaneous connections each new connection will require its own tcp Socket and a separate call to one of the listen functions but using the same local port number lport value The listen function will immediately return and you must poll for the incoming connection You can manually poll the socket using sock established The proper procedure for fielding incoming connections is described below 44 rabbit com TCP and UDP Socket Interface 3 3 2 Active Open When your Web browser retrieves a page it actively opens one or more connections to the server s pas sively opened sockets To actively open a connection call tcp open or tcp _extopen which use parameters that are similar to the ones used in the listen functions Supply exact parameters for remip and port which are the IP address and port number you want to connect to the 1port parameter can be zero causing an unused local port between 1024 and 65535 to be selected If the open function returns zero no
203. kets Table 4 1 Channel Characteristics for Selected Networks Type Bandwidth Byte sec RTT msec Ee ere 1 25M 0 6 IM ere 8N1 serial 5760 Se es oh a over 1 5Mbit 187k n The above table does not count any delay in the host which generates the response nor any delay passing through the Internet These represent minimum possible RT TS 4 1 DBP and Sizing of TCP Buffers An important guantity derived from the above is known as Delay Bandwidth Product DBP As the name suggests this is the product of bandwidth and RTT and has units of bytes It represents the maximum amount of data and overhead that can exist in the network at any point in time This number has impli cations for sizing of TCP socket buffers The DBP for local 10Base T Ethernet is about 750 bytes For local Ethernet connections the DBP is about the same as the packet size of the transmitted data For wider area networks that have significant propagation delays the DBP can increase substantially For example satellite links can add several 100 s of milliseconds to the RTT If the bandwidth is high enough the DBP can exceed the packet size by orders of magnitude This means that several packets may be in transit at the same time The DBP is important for TCP connections This is because TCP is able to transmit a large number of packets into the network without having to wait for an acknowledgement for each one Similarly a TCP can
204. l I O registers are supported for this function The application is responsible for setting serial port parameters as desired When using DMA channels the network library routines do not make any changes to or make any assumptions about the underlying I O port The same applies to the DMA channel For example the appli cation is responsible for enabling the external DMA request line if for example it is desired to implement hardware transmit flow control Use of a DMA channel reduces the amount of CPU overhead taken up servicing interrupts This allows higher communication rates or allows the application to perform more useful work in the same time If the DMA channels are released via IFS USE SERIAL then it is the application s responsi bility to re use or unallocate the DMA channels as desired 134 rabbit com TCP IP Manual Vol 1 ifconfig cont d PARAMETER IDENTIFIERS FOR WI FI INTERFACES The following parameter identifiers are only for Wi Fi interfaces You will get a runtime error non zero return code if you apply one of the Wi Fi specific parameters to a non Wi Fi inter face See the Wi Fi Configuration documentation in tcp config lib for details on configuring the Wi Fi interface IFS_WIFI_SSID Set the SSID for the Wi Fi device int byte Since the SSID can contain any byte including nulls it s necessary to provide the length along with the SSID See wifi ssid to str forcreating a nul
205. l need something like the following define IFC WIFI WPA PSK PASSPHRASE myPassphrase To specify the WPA2 Pre Shared Key itself use the following define IFC WIFI WPA PSK HEXSTR 1122334455667788990011223344556677889900112233445566778899001122 TCP IP Manual Vol 1 rabbit com 21 Alternatively you can configure within the Defines window TCPCONFIG 1 PRIMARY STATIC IP 10 10 6 100 PRIMARY NETMASK 255 255 255 0 MY GATEWAY 10 10 6 1 MY NAMESERVER 10 10 6 1 WIFI USE WPA WIFI AES ENABLED FC WIFI SSID rabbitTest FC WIFI ROAM ENABLE 1 FC WIFI ROAM BEACON MISS 20 FC WIFI MODE IFPARAM WIFI INFRASTRUCTURE FC WIFI REGION IFPARAM WIFI REGION AMERICAS FC WIFI ENCRYPTION IFPARAM WIFI ENCR CCMP Again you will need to specify a WPA2 passphrase or Pre Shared Key To specify the WPA2 passphrase use the following FC WIFI WPA PSK PASSPHRASE myPassphrase To specify the WPA Pre Shared Key itself use the following FC WIFI WPA PSK HEXSTR 1122334455667788990011223344556677889900112233445566778899001122 2 4 1 6 Infrastructure WPA Enterprise using EAP TLS and CCMP Encryptio
206. l terminated print able version of the SSID with nulls and non printable characters byte values 0x00 0x20 and 0x7F OxFF replaced with Setting the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted IFG WIFI_SSID Get the currently configured SSID int byte See the set command for more informa tion on the SSID IFS WIFI MULTI DOMAIN Enable multi domain bool This only works on APs with 802 11d Setting the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted IFG WIFI MULTI DOMAIN Is multi domain enabled bool TCP IP Manual Vol 1 rabbit com 135 ifconfig cont d IFS WIFI REGION Set regulatory region int Valid parameters and the channels they allow are IFPARAM WIFI REGION AMERICAS 1 11 IFPARAM WIFI REGION AUSTRALIA l 11 IFPARAM WIFI REGION CANADA l 11 IFPARAM WIFI REGION CHINA l 11 IFPARAM WIFI REGION EMEA l 13 FPARAM WIFI REGION FRANCE 10 13 IFPARAM_WIFI_REGION_ISRAEL 3 11 IFPARAM WIFI REGION JAPAN
207. le The following table lists the parameters to the callback for each event type Table 3 1 Parameters for Each Type of Callback event s g info notes UDP DH INDATA udp Socket pkt data UDI Normal received data UDP DH ICMPMSG udp Socket pkt data UDI ENEE Z gt socket TCP DH LISTEN tcp Socket NULL NULL EE eg SSC P_ tcp extlisten TCP DH OPEN top Socket NULL NULL oe Ope Ca ee a top extopen TCP DH ESTAB tep Socket NULL NULL 3 way handshake complete ready for data transfer TCP DH INDATA tcp_Socket seg data NULL Incoming stream data TCP DH OUTBUF EE NULL rece tant Dunes ala acknowledged by peer 58 rabbit com TCP and UDP Socket Interface Table 3 1 Parameters for Each Type of Callback event s g info notes No further incoming data peer sent FIN Kal TCP DH INCLOSI cp Socket NULL NULL GI S l N S No further outgoing data application TCP DH OUTCLOSI tep Socket NULL NULL closed socket sent FIN TCP_DH_CLOSED tep Socket NULL NULL Socket completely closed TCP_DH_ABORT tcp Socket NULL NULL Application called sock abort TCP DH RESET Cp Socket NULL NULL Peer sent RST flag TCP DH ICMPMSG tcp_Socket pkt data NULL ES associat Waits socket Other 9 9 9 Reserved for future u
208. lication Because it will not do small data moves it is also slightly more efficient in terms of CPU time TCP IP Manual Vol 1 rabbit com 75 4 4 2 Casual Server Applications A casual server is a term we use for applications that need to respond to occasional requests for informa tion or commands without large data transfers Although the amount of data transfer is limited the appli cation still needs to be as responsive as possible Example applications of this type include machine building and power controllers Interactive servers are also included such as telnet The main goal here is to achieve low latency 4 4 3 Master Controller Applications Master controllers are responsible for coordinating access to a number of other devices via TCP IP or other types of communication or acting as an access concentrator Data transfer may be low to moder ate Latency should be minimized 4 4 4 Web Server Applications The TCP IP libraries include web server software HTTP LIB takes advantage of the TCP library to get good performance Your application can still affect web server performance since it may be responsible for generating content via CGI callback functions Web servers have much the same characteristics as bulk loaders however they are such a common case that they deserve special treatment 4 4 5 Protocol Translator Applications A protocol translator basically converts between a TCP data stream and
209. listen tcp clearreserve 254 rabbit com TCP IP Manual Vol 1 tcp tick int tcp_tick void ts DESCRIPTION This function is a single kernel routine designed to quickly process packets and return as soon as possible tcp_tick performs processing on all sockets upon each invocation checking for new packets processing those packets and performing retransmissions on lost data On most other computer systems and other kernels performing these required operations in the background is often done by a task switch DCRTCP LIB does not use a tasker for its basic operation although it can adopt one for the user level services Although you may ignore the returned value of tcp_tick it is the easiest method to de termine the status of the given socket PARAMETERS s Pointer to a socket If a NULL pointer is passed in the returned value should be ignored RETURN VALUE 0 Connection reset or closed by other host or NULL was passed in 10 Connection is fine LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tcp_open sock close sock abort TCP IP Manual Vol 1 rabbit com 255 udp bypass arp void udp bypass arp udp Socket s eth address eth DESCRIPTION Override the normal Address Resolution Protocol for this UDP socket This is sometimes nec essary for special purposes such as if the Ethernet address is to remain fixed or if the Ethernet address is not obtainable using ARP
210. live int sock_alive tcp Socket s DESCRIPTION This function performs the same test as tcp_tick s i e it checks the status of the socket and returns 0 if the socket is fully closed The processing overhead of tcp tick is avoided for cases where several sockets need to be checked in succession When this function returns zero for a socket the socket is then ready for a new call to tcp _open ortcp listen and friends PARAMETER s TCP socket pointer RETURN VALUE 0 Connection reset or fully closed Socket ready for re use in another connection 10 Connection is opening established listening or in the process of closing LIBRARY NET LIB SEE ALSO tep open tcp listen sock close sock abort tep tick 192 rabbit com TCP IP Manual Vol 1 sock aread int sock_aread Cep Socket s byte dp int len DESCRIPTION Read exactly len bytes from the socket or if that amount of data is not yet available do not read anything Unlike sock fastread this function will never return less than the re quested amount of data This can be useful when the application knows that it will be receiving a fixed amount of data but does not wish to handle the arrival of only part of the data as it would have to do if sock fastread was used len must be less than or equal to the socket receive buffer size otherwise sock fastread must be used This function is only valid for TCP sockets It is available sta
211. ll how much data will be required to go to the next state then you will have to call sock preread to check the current data without prematurely extracting it from the socket receive buffer For write states you can just keep calling sock fastwrite until all the data for this state is written If you have a fixed amount of data sock awrite is more convenient since you do not have to keep track of partially written data 3 10 1 Blocking vs Non Blocking There is a choice between blocking and non blocking functions when doing socket I O 3 10 1 1 Non Blocking Functions The sock fastread and sock preread functions read all available data in the buffers and return immediately Similarly the sock fastwrite function fills the buffers and returns the num ber of characters that were written When using these functions you must ensure that all of the data were written completely offset 0 while offset lt len bwees written SOCK tastwriecel s burrorrset len oirrsete iit bytes written lt 0 error handling ILESEE T mea written 3 10 1 2 Blocking Functions The other functions sock_getc sock gets sock putc sock puts sock read and sock write do not return until they have completed or there is an error If it is important to avoid blocking you can check the conditions of an operation to ensure that it will not block Soek mode s0Cket LEP EMODE Asem Ud ir seel
212. ly hang up the modem or possibly just renegotiate from the LCP phase if this is what you intended by call ing ifup TCP IP Manual Vol 1 rabbit com 91 92 rabbit com PPP Driver 8 Function Reference This section contains descriptions for all user callable functions in DCRTCP LIB Starting with Dynamic C 7 05 DCRTCP DNS LIB P LIB NET LIB TCP LIB UDP LIB LIB is a light wrapper around This update requires no changes to existing code Descriptions for select user callable functions in ARP LIB BSDNAME ICMP LI IGMP LI PPP LIB XMEM LI LIB B B B are also included here Note that ARP LIB from DCRTCP LIB CMP LIB and BSDNAME LIB are automatically tuse d Functions are listed alphabetically and by category grouped by the task performed TCP IP Manual Vol 1 rabbit com 93 94 rabbit com Function Reference _abort_ socks int _abort_socks byte reason byte iface DESCRIPTION Abort all open TCP and UDP sockets This routine may be called if the network becomes un available for example because a DHCP address lease expired or because an IP address conflict was encountered This function is generally intended for internal library use but may be invoked by applications in special circumstances PARAMETERS reason Reason code A suitable NETE
213. ly be able to transmit at about 270kB sec when sending 1500 byte packets Receive rate is slightly slower at about 220kB sec This scales approximately linearly with respect to CPU clock speed as well as application use of the CPU In short current Rabbit based boards cannot use the full bandwidth of a local Ethernet link The situation changes for PPP over serial In this case the serial port bandwidth is less than the rate at which packets can be generated or received Also PPP is typically used to access peers over the Internet so there may be a much larger DBP than for a pure point to point link For PPP serial links smaller packet sizes e g 256 bytes are satisfactory for bulk data transfers without impacting interactive traffic should that be required Socket buffer sizes should be determined based on the expected Internet RTTs which may be 1 second or more For a 57 6kbps serial link the DBP is 5000 bytes for 1 second RTT thus the socket buffers should be about this size for receive and transmit TCP is adaptive to changing network conditions For example the RTT can vary considerably at different times of day and communication channels can become congested TCP is designed to cope with these con ditions without exacerbating any existing problems however socket buffer and packet sizes are usually constants for the application so they need to be selected with due consideration to the most common condi tions 1 Assuming there is
214. m e g arpcache search ath RETURN VALUE Positive value Success D The table entry was unused ATH UNUSE ATH INVALID the ath parameter was not a valid handle ATH OBSOLETE The given handle was valid but obsoleted by a more recent entry No change made LIBRARY ARP LIB 97 TCP IP Manual Vol 1 rabbit com arpcache hwa ATHandle arpcache hwa ATHandle ath byte hwa DESCRIPTION Copy the Ethernet hardware address from the given ARP cache table entry into the specified area PARAMETERS ath ARP cache table entry hwa Address of where to store the hardware address 6 bytes RETURN VALUE Positive value Handle to the entry T ATH UNUSED The table entry was unused ATH INVALID The ath parameter was not a valid handle ATH OBSOLETE The given handle was valid but obsoleted by a more recent entry No change made LIBRARY ARP LIB 98 rabbit com TCP IP Manual Vol 1 arpcache iface ATHandle arpcache iface ATHandle ath byte iface DESCRIPTION Copy the interface number from the given ARP cache table entry into the specified area If the ath parameter refers to a broadcast or loopback entry then i face is set to F DEFAULT and ATH INVALID is returned since we can t really determine which of the interfaces to broadcast from PARAMETERS ath ARP cache table entry iface Address of where to store
215. macros that define the IP address netmask gateway and nameserver This section will describe the setup of Wi Fi both at compile time and runtime The configuration macros used in the code in this section are described in Wi Fi Configuration Macros on page 36 The Wi Fi interface is considered up i fpending returns that the interface is up and the link LED is on in the following conditions e If connecting to an AP using no encryption then the link is up when 802 11 association has completed e If connecting to an AP with TKIP WPA or CCMP WPA2 encryption the link is up after the 802 111 handshake has completed successfully This means that the pre shared key must be correct before the link is considered up e If connecting to an AP with WEP encryption then the link is up when 802 11 association has completed whether or not the WEP key is correct This means that a WEP connection can show as being up even though the key is wrong This is because unlike TKIP or CCMP WEP does not provide a way of knowing whether or not the key used is correct 16 rabbit com TCP IP Initialization 2 4 1 Wi Fi Compile Time Configuration The examples given here cover both Wi Fi modes ad hoc and infrastructure Note that a Wi Fi interface can be configured for DHCP support but the examples in this section will show only static configuration 2 4 1 1 Infrastructure Open No Encryption Configuration The simplest way
216. mask for the controller At runtime it can be overwritten by top contig dg 2 6 6 Network Configuration Starting with Dynamic C 7 30 These macros should only be used with Dynamic C 7 30 or later TCPCONFIG Define to the number of a predefined configuration in tcp config lib numbers less than 100 or custom config lib numbers greater or equal to 100 Defaults to 0 which means no predefined configuration TCP IP Manual Vol 1 rabbit com 31 USE ETHERNET Define to 0 or leave undefined if Ethernet is not reguired Define to 1 if the first Ethernet port is to be used Defaults to 0 This macro does not include PPPoE interfaces USE PPP SERIAL Define to a bitwise OR combination of e SERA 0x01 Serial port A IF PPPO e SERB 0x02 Serial port B IF _PPP1 e SERC 0x04 Serial port C IF PPP2 e SERD 0x08 Serial port D IF PPP3 e SERE 0x10 Serial port E IF PPP4 e SERF 0x20 Serial port F IF PPP5 Defaults to 0 i e no PPP over serial USE_PPPOE Define in the same way as USE_ETHERNET except that PPPoE is used on the specified Ethernet port Defaults to 0 i e no PPPoE interfaces USE_WIFI Define to 1 if Wi Fi is required Defaults to 0 IFCONFIG ALL IFCONFIG DEFAULT IFCONFIG ETHO IFCONFIG PPPO 5 IFCONFIG PPPOEO IFCONFIG WIFIO All the above IFCONFIG macros are defined in a similar manner IFCONFIG ALL is reserved for configuration items that are not specific to any par
217. mip then only UDP datagrams from that host will be accepted The remote end of the connection is specified by remip and port The following table ex plains the possible combinations and what they mean REMIP Effect of REMIP value The connection completes when the first datagram is received supplying both the remote IP address and the remote port number Only datagrams received from that IP port address will be accepted All remote hosts can send datagrams to the socket All outgoing 1 datagrams will be sent to the broadcast address unless udp sendto specifies otherwise If the remote IP address is a valid IP address and the remote port is 0 the connection will complete when the first datagram is si received supplying the remote port number If the remote IP address and the remote port are both specified when the function is called the connection is complete at that point The buffer and buflen parameters allow a user to supply a socket buffer instead of using a socket buffer from the pool If remip is non zero then the process of resolving the correct destination hardware address is started Datagrams cannot be sent until sock resolved returns TRUE If you attempt to send datagrams before this then the datagrams may not get sent The exception to this is if remip is 1 broadcast in which case datagrams may be sent immediately after calling this function This function also works with multicas
218. multiple fragments This can be useful on busy or noisy networks The range is 256 2346 or 0 which means no fragmentation The macro WIFI FRAG THRESH was deprecated in Dynamic C 10 40 IFC_WIFI_RTS THRESHOLD default 0 Set the RTS threshold the frame size at which the RTS CTS mechanism is used This is sometimes useful on busy or noisy networks Its range is 0 2347 where 0 is the default i e no RTS CTS The macro WIFI RTS THRESH was deprecated in Dynamic C 10 40 SSL_USE_AES This is required for EAP TLS since it uses SSL internally WIFI_USE_WPA Define this macro to use the WPA functionality in the Wi Fi driver This is necessary to enable TKIP encryption Because the WPA code has a significant size it is not compiled by default WPA_USE_EAP Set to a bitwise OR combination of the following e WPA USE EAP TLS e WPA USE EAP PEAP which specifies the Wi Fi Enterprise authentication method to use currently either EAP TLS or PEAP Use of this macro will bring in a lot of library code to support Enterprise level authentication and key management This will require configuration of the access point as well as a separate machine to be used as an Authentication Server e g a RADIUS server 40 rabbit com TCP IP Initialization RABBIT 3 TCP and UDP Socket Interface TCP Transmission Control Protocol and UDP User Datagram Protocol are both transport layer pro
219. n To configure within your program copy and paste the following into your sample program and modify as necessary define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define PRIMARY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 define MY NAMESERVER 10 10 6 1 define WIFI USE WPA define WIFI_AES ENABLED define IFC WIFI SSID rabbitTest define IFC WIFI ROAM ENABLE 1 define IFC WIFI ROAM BEACON MISS 20 define IFC WIFI MODE IFPARAM WIFI INFRASTRUCTURE define IFC WIFI REGION IFPARAM WIFI REGION AMERICAS define IFC WIFI ENCRYPTION IFPARAM WIFI ENCR CCMP The above defines are identical to using CCMP with PSK 22 rabbit com TCP IP Initialization tdefine WPA USE tdefine IFC W F ximport ce ximport ce r E EAP WPA USE _WPA_PROTOCOL ts root pem root ca cert G EAP TLS IFPARAM WIF _WPA_PROTOCOL_WPA2 M root ca cert define IFC WIFI CLIENT CERT X define IFC WIFI CA CERT X FI IDENTITY MyCl define IFC W define SSL USE AES ienti Ident ts my_client pem my client cert M my client c
220. n a connection to that port number is requested the 3 way handshaking is done even if there is not yet a socket available When replying to the connection request the window parameter in the TCP header is set to zero meaning I can take no bytes of data at this time The other side of the connection will wait until the value in the window parameter indicates that data can be sent Using the companion function tcp clearreserve port number causes TCP IP to treat a connection request to the port in the conventional way The macro USE_RESERVEDPORTS is defined by default It allows the use of these two functions When using tcp reserveport the 2MSL maximum segment lifetime waiting period for closing a socket is avoided 3 4 TCP Socket Functions There are many functions that can be applied to an open TCP socket They fall into three main categories Control Status and I O 3 4 1 Control Functions for TCP Sockets These functions change the status of the socket or its I O buffer e sock abort toep extlisten e sock close e tep extopen e sock flush e tcp listen e sock flushnext e tcp open The open and listen functions have been explained in previous sections Call sock close toenda connection This call mav not immediatelv close the connection because it may take some time to send the request to end the connection and receive the acknowledgements If you want to be sure that the connection is completel
221. n eege eren 279 SOCK EE deesdae des Ke De 231 udp _waitsend sessies se sesde 280 ye di ie RES dieiis 232 udp_xsendto sis EES iwa 281 SGI TUNG wesanashialtenevisaieaunaneiieves 233 V sock_read ese Sa ER 234 virtual GUN ee oe ee ee 282 280 rabbit com W ER 283 TCP IP Manual Vol 1 rabbit com 281 282 rabbit com RABBIT Dynamic C TCP IP Functions Listed by Category Addressing EE 193 EE 117 sl dE AE AE 194 _arp send gratuitous iese esse eke ee 122 router_for_iface Ge RR ie de 195 arp_getArpData woes sei ee 116 POUT PINE N i si a 197 arp getArpGateData esse ese see ee ee 116 router printall esse EN Re be ig 198 arpcache_create iss see SEERDE 108 GE 200 arpcache_ EE 109 SOGRU EE 201 arpcache_ hwa vasssscacsvsdsseesvenssacessedeventons 110 sethostname g eegente 202 arpe che MACE eN DERE 111 udp bypass ALP oo cccccccccceeeseeserteeeeeeees 268 arpcache_ipaddr iss eie EER Ee 112 B l arpcach load Mes fdik 113 Configuration E PORTER Gage 115 E 135 EE NEL EE 118 tep e EEN 258 arpresolve_ipaddr seacesccecuonrensdediccssxecuss 119 Data Conversion arpresolVe Start En 120 le EE EE 123 arpresolve start iface en 121 ie EE EE Seele 133 dhep aCduire En 125 OTE EO ek OE 134 dhep_get_timeZOne en 126 EE addr l is kai ga ed ee 163 dhep release En 127 ie EE 164 getdomainname En 128 ed AR OE 177 gethostid EE 129 ad OE oe ee ee ee ee ed 178 gethostRame En 130 l OE N Ed 191 getpeername oe nee es GEE be ie 131 getsock
222. n that is passed to it will be called in a tight loop while sock read is busy waiting Starting with Dynamic C 7 05 this function is only valid for TCP sockets For UDP sockets use udp recv orudp_recvfrom Prior to 7 05 this function cannot be used on UDP sockets after sock recv init is called PARAMETERS s Pointer to a socket dp Buffer to store bytes that are read len Maximum number of bytes to write to the buffer RETURN VALUE 20 Success number of bytes read 1 Error LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock fastread sock fastwrite sock write sockerr udp recy udp_recvfrom EXAMPLE Note that sock fastread and sock read do not necessarily return a complete or single line they return blocks of bytes In comparison sock getc returns a single byte at a time and thus yields poor performance do len sock bvtesreadv s if len gt 0 if len gt sizeof buffer 1 Iftoo many bytes read some len sizeof buffer 1 now read the rest next time sock read s buffer len buffer len 0 printf Ss buffer while tcp tick s 222 rabbit com TCP IP Manual Vol 1 sock readable int sock readable void s DESCRIPTION This function determines whether a socket may have data read from it using for example sock fastread orudp_recvfrom The parameter may be either a TCP socket or a UDP socket The return value
223. name and password given to peer char char 77 IFS_PPP_LOCALAUTH Required username and password for incoming peer char char IFG PPP LOCALAUTH char char IFS_PPP_RTSPIN Define the RTS pin int char int The parameters for the RTS CTS pin assignments are RTS int port_address char shadow_reg int port_pin CTS int port_address int port_pin where port_address is the parallel port internal I O address e g PEDR for port E shadow reg is the appropriate shadow register for the parallel port data register e g amp PEDRShadow for port E port pin is a number from 0 7 indicating the pin number of the port IFG PPP RTSPIN Get RTS pin definitions int char int 7 IFS PPP CTSPIN Define the CTS pin int int See description for IFS PPP RTSPIN IFG PPP CTSPIN Get CTS pin definitions int int IFS PPP FLOWCONTROL Turn hardware flow control on or off bool IFG PPP FLOWCONTROL Get hardware flow control setting bool IFS PPP USEPORTD Use parallel port D instead of parallel port C for serial ports A amp B bool IFG PPP USEPORTD Are we using parallel port D instead of C bool 132 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFS_PPP_USEPORTE Use parallel port E instead of parallel port C for serial ports E amp F bool Rabbit 4000 only IFG PPP USEPORTE Are we using parallel port E instead of C bool IFG PPP PEERADDR Get th
224. name ees ees NG is Ge ee 132 Ethernet BEDE eet 186 pd_getaddress EE 179 Ee RE OR ai 187 pd havelimk SE 180 EE 188 pd_powerdown sesse se sesse He sek Sk Kees 181 resolve_name check OE 189 PO_POWETUP sesissenzisuszaniineszanzaessenzieszes 182 resolve name start s ss seseenenzzznnnni 190 EEN POMS add ie ER ie 192 WS EE SET ee 193 sock init ege 222 sock init OP BEE stets ege 223 TCP IP Manual Vol 1 rabbit com 283 BOGIES E 247 Interface he E 158 TDCI de ee ea 159 Du L ee DE 160 AE A 161 d OE EE 165 ip print ifs EE N 166 is_valid_iface rise dd ed Gee 169 oe MADE EE Ee OIE 221 viral eth oe N 282 Modem ModemClose Es Ge ee RS 170 ModemConnected ss sek AE AN SN EE 170 ModemExpect issie seke NE ER EEN 171 ModemHangup sees ee ia 171 Modemlnit ass seen vas ee NEEM 172 ModemOpen seke RE Ke 172 ModemReady iese EK Ged 173 ModemRinging ie Gees ie Se N gee SE ee 173 ModemSend asses REK ee kaz 174 ModemStartPPP ie eie Seegen 174 Multicast multicast joingroup i e ee esse ee ee 175 multicast leavegroup ss seeenenznnnn 176 Ping Chk PID AE EE ee anneni 124 Er N ER N 183 Send EE OE N 199 PPP ME 184 PP PHS COU E 184 PPPsetAuthenticatee ssseeeenenznnnn 185 PPPsetAuthenticator iee esse sees se ee 185 PPPshutdown oes asses SKREE EE ESE 186 Socket Configuration BOCK mode aie ER ANENE ee 224 SOCK Set Eeer 241 ee af ai N dia dua 242 top E 251 tep_reservepotrt ia l 266 Socket Connection abor
225. nd writing to TCP sockets ASCII and binarv Bv default a socket is opened in binary mode but you can change the mode with a call to sock mode When a socket is in ASCII mode it is assumed that the data is an ASCII stream with record boundaries on the newline characters for some of the functions This behavior means sock bvtesreadv will return 20 onlv when a complete newline terminated string is in the buffer or the buffer is full The sock puts function will automatically place a newline character at the end of a string and the sock gets function will strip the newline character Do not use sock gets in binary mode 48 rabbit com TCP and UDP Socket Interface 3 5 UDP Socket Overview The UDP protocol is useful when sending messages where either a lost message does not cause a system failure or is handled by the application Since UDP is a simple protocol and you have control over the retransmissions you can decide if you can trade low latency for high reliability Broadcast Packets UDP can send broadcast packets i e to send a packet to a number of computers on the same network This is accomplished by setting the remote IP address to 1 in either a call to udp_open ora call to udp sendto When used properly broadcasts can reduce overall network traffic because information does not have to be duplicated when there are multiple destinations Checksums There is an optional checksum field inside the UDP heade
226. negative for west positive for east of Greenwich If the return value is 1 then the result will be set using the hard coded val ue from the macro TIMEZONE converted to seconds by multiplying by 3600 or zero if this macro is not defined RETURN VALUE 0 Time zone obtained from DHCP 1 Time zone not valid or not yet obtained or not using DHCP LIBRARY BOOTP LIB 114 rabbit com TCP IP Manual Vol 1 dhcp release int dhcp release void DESCRIPTION This function relinquishes a lease obtained from a DHCP server This allows the server to re use the IP address that was allocated to this target After calling this function the global variable for the IP address is set to 0 and it is not possible to call any other TCP IP function which re quires a valid IP address Normally dhcp release would be used on networks where only a small number of IP addresses are available but there are a large number of hosts which need sporadic network access This function is non blocking since it only sends one packet to the DHCP server and expects no response RETURN VALUE 0 OK lease was relinquished 1 Not released because an address is currently being acquired or because a boot file from the BOOTP or DHCP server is being downloaded or because some other network resource is in use e g open TCP socket Call dhcp release again after the resource is freed 1 Not released because DHCP was not used to obtain a l
227. netmask describes the so called subnet which is addressable on that interface The subnet basically describes the community of host addresses that can talk directly to this host without requiring data to pass through a packet router Point to point links only need an IP address since there is only one other host by definition IP address and netmask are the most important configuration items however many other items are needed for successful networking For anything but strictly local communication a router or gateway host must be known The router has the important task of forwarding messages between the local host and the outside world e hosts that are not on the local subnet Routers are associated with particular interfaces Each interface will generally require a different router however in the majority of cases only one interface will actually be used to talk to non local hosts so only one router will be required to service all requests for non local host addresses Some of the configuration items are not specific to any particular interface For example DNS Domain Name System servers are known by their IP address DNS servers are used to translate human readable domain names e g www rabbit com into machine readable IP addresses 1 The configuration macros MY_IP ADDRESS and MY NETMASK have been deprecated in favor of PRIMARY STATIC IPand PRIMARY NETMASK respectively 8 rabbit com TCP IP Initi
228. ng and leaving multicast groups and informing the Ethernet hardware about it will be added USE_IGMP If this macro is defined the USE_ MULTICAST macro is automatically defined This macro enables sending reports on joining multicast addresses and responding to IGMP queries by multicast routers Unlike USE MULTICAST this macro must be defined to be 1 or 2 This indicates which version of IGMP will be supported Note however that both version 1 and 2 IGMP clients will work with both version 1 and 2 IGMP routers Most users should just choose version 2 USE LINKLOCAL This macro enables the use of link local addresses 169 254 1 0 to 169 254 254 255 for zero configuration networking With USE LINKLOCAL defined any time you set an Ethernet or Wi Fi interface s IP address to something on the link local subnet 169 254 x x the TCP IP stack will automatically select an available address and handle address conflicts with other devices on the network Link local addressing can be used with a static IP configuration or as the fallback address when a DHCP server is unavailable 2 6 3 BOOTP DHCP Control Macros Various macros control the use of DHCP Apart from setting these macros before use dcrtcp lib there is typically very little additional work that needs to be done to use DHCP BOOTP services Most of the work is done automatically when you call sock init to initialize TCP IP There are more control macros TCP IP Manual
229. no other traffic on the Ethernet and that collisions are rare This is rarely the case so a 50 80 uti lization of bandwidth is considered the maximum desirable Ethernet load TCP IP Manual Vol 1 rabbit com 67 4 2 TCP Performance Tuning TCP is a well designed protocol and provides nearly optimum performance over a wide range of condi tions Obtaining the best possible performance requires the application to co operate with TCP by setting the correct options if the defaults are not optimal making the most efficient use of the socket API func tions and providing appropriate memory and CPU resources The available performance related options are e Whether to use the Nagle algorithm e Settings for time out values e Whether to define a pending connection queue reserved port e Setting the IP Type Of Service field e Packet buffer and MTU sizes e ARP cache size for Ethernet Sizing of buffers was discussed in the previous section The following sections discuss the other perfor mance controls 4 2 1 The Nagle Algorithm The Nagle algorithm is an option for TCP sockets It modifies the transmit processing for a socket but has no effect on receive processing The TCP IP library allows Nagle to be applied on a per socket basis Most applications should leave the Nagle algorithm enabled for each TCP socket which is the default This provides the best utilization of bandwidth since it prevents many small packets from be
230. not NULL LIBRARY UDP LIB SEE ALSO udp_recvfrom 262 rabbit com TCP IP Manual Vol 1 udp_recv int udp_recv udp Socket s char buffer int len DESCRIPTION Receives a single UDP datagram on a UDP socket If the buffer is not large enough for the da tagram the datagram is truncated and the remainder discarded PARAMETERS s Pointer to socket s data structure buffer Buffer where the UDP datagram will be stored len Maximum length of the buffer RETURN VALUE 20 Number of bytes received 1 No datagram waiting lt 1 Error LIBRARY UDP LIB SEE ALSO udp_recvfrom udp send udp sendto udp open TCP IP Manual Vol 1 rabbit com 263 udp_recvfrom int udp recvfrom udp Socket s char buffer int len longword remip word remport DESCRIPTION Receive a single UDP datagram on a UDP socket remip and remport should be pointers to the locations where the remote IP address and remote port from which the datagram originated are placed If the buffer is not large enough for the datagram then the datagram will be truncated with the remainder being discarded Ifand only ifthe UDP_MODE ICMP orUDP_MODE DICMP modes are set for this socket then a return code of 3 indicates that an ICMP error message is being returned in the buffer instead of a normal datagram In this case buf fer will contain fixed data in the form of a structure of type udp icmp message The definit
231. nsufficient room in the transmit buffer for the generated response Thus the callback will need to be carefully coded to avoid getting into a buffer deadlock situation if it generates responses It will also need to co ordinate with the rest of the application since the application will otherwise have to contend with the possibility of arbitrary data being inserted in the write stream by the callback NOTE The application must call sock fastread or other read functions to actually remove data from the TCP socket receive buffer unless the data handler callback is coded to call sock fastread itself If neither the data handler nor the rest of the application actu ally read the received data then the TCP connection will become blocked in the read direc tion 60 rabbit com TCP and UDP Socket Interface 3 12 Multitasking and TCP IP Dynamic C s TCP IP implementation is compatible with both LC OS II and with the language constructs that implement cooperative multitasking costatements and cofunctions Note that TCP IP is not compati ble with the slice statement 3 12 1 uC OS II The TCP IP stack may be used with the L C OS II real time kernel The line use ucos2 lib must appear before the line use dcrtcp lib in the application program Also be sure to call OSInit before calling sock init Dynamic C version 7 05 and later requires the macro MAX SOCKET LOCKS for uC OS II support If it is not defined it will defa
232. nual Vol 1 rabbit com 109 _arp_send_ gratuitous int arp send gratuitous word iface DESCRIPTION When a host sends an ARP reguest to resolve its own IP address it is called gratuitous ARP In the ARP reguest packet the source IP address and destination IP address are filled with the same source IP address itself The destination MAC address is the Ethernet broadcast address FF FF FF FF FF FF Gratuitous ARP is used for the following 1 Ina properly configured network there will not be an ARP reply for a gratuitous ARP re quest But if another host in the network is also configured with the same IP address as the source host then the source host will get an ARP reply In this way a host can determine wheth er another host is also configured with its IP address 2 When the network interface card in a system is changed the MAC address to its IP address mapping is changed In this case when the host is rebooted it will send an ARP request packet for its own IP address As this is a broadcast packet all the hosts in the network will receive and process this packet They will update their old mapping in the ARP cache with this new map ping PARAMETER iface Interface number RETURN VALUE 1 Success 0 Failure LIBRARY ARP LIB 110 rabbit com TCP IP Manual Vol 1 aton longword aton char text DESCRIPTION Converts a b c d or a b c d to a 32 bit long value PARAMETER text Pointer to str
233. nual Vol 1 rabbit com 15 For the interface to come up completely your application must call tcp tick regularly while waiting for it If you can afford to block until the interface is up then use code similar to the following ifup IF PPP2 Wait for the interface to have any status other than down coming up while ifpending IF PPP2 1 tcp_tick if ifstatus IF PPP2 printf PPP2 is up now n else printf PPP2 failed to come up n 2 3 3 Bringing an Interface Down You can call ifdown or ifconfig withthe IFS DOWN parameter identifier The advantage of using ifconfig is that you can specify an interface number of IF ANY which brings all interfaces down together As for i fup ifdown does not necessarily complete immediately on return PPP requires link tear down messages to be sent to the peer and acknowledged Thus similar considerations apply to bringing an interface down as they do for bringing it up ifdown will always succeed eventually Unlike i fup which can possibly fail to bring the interface up if down will always eventually return success i e it is not possible for an interface to be left hanging up If the PPP link tear down does not get an acknowledgment from the peer then the process times out and the link is forced down 2 4 Setting Up Wi Fi Interfaces Wi Fi has some specific configuration macros in addition to the basic TCP IP
234. ny soekae d printf Failed to establish n break ic SOCK Ssicelolisineel my soeckeej q printf Established OK n do whatever needs to be done Notice the tcp tick amp my socket call inside the while loop This is necessary in order to test whether the handshake was aborted by the peer or timed out At the end of the loop sock established tests whether the handshake did indeed complete If so then the socket is ready for data flow Otherwise the socket should be re opened The same basic procedure applies for pas sively opened sockets i e tcp listen TCP IP Manual Vol 1 rabbit com 45 3 3 4 Specifying a Listen Queue A tcp Socket structure can handle only a single connection at any one time However a passively opened socket may be required to handle many incoming connection requests without undue delay To help smoothly process successive connection requests with a single listening socket you can specify that certain TCP port numbers have an associated pending connection queue If there is no queue then incoming requests will be cancelled if the socket is in use If there is a queue then the new connections will be queued until the current active connection is terminated To accept new connection requests when the passively opened socket is currently connected use the func tion tcp reserveport It takes one parameter the port number where you want to accept connec tions Whe
235. of each TCP IP program as well as eliminating the need for copy paste of a lot of settings from one program to the next Using the predefined configurations is very easy simply define a single macro called TCPCONFIG at the top of each program The macro is defined to an integer which selects one of the predefined configurations in tcp config lib For example define TCPCONFIG 1 use dcrtcp lib causes the first predefined configuration to be used Most of the sample TCP IP programs refer to one of the predefined configurations It is fairly likely unfortunately that none of the configurations will work with your network For example the default IP address of 10 10 6 100 may not be allowed on your LAN If this is the case you can define the default IP address in your application or in the Defines tab of the Project Options dialog box To configure within your program copy and paste the following into your code and modify as necessary define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define PRIMARY NETMASK 2552992990 define MY GATEWAY AO ce oe define MY NAMESERVER MYO H Ad TCP IP Manual Vol 1 rabbit com 9 To configure within the Project Options dialog box copy and paste the following into the Defines window and modify as necessary TCPCONFIG 1 _PRIMARY STATIC IP
236. ofing IFS WIFI CA CERT PATH Set CA certificate as a Zserver resource path char 144 rabbit com TCP IP Manual Vol 1 ifconfig cont d IFS WIFI CLIENT CERT IFG WIFI CLIENT CERT Set Get client certificate ISSL Cert t far SSL_Cert_t far IFS WIFI CLIENT CERT PATH Set client certificate as Zserver file char char The first parameter is for the certificate and the second one is for the private kev If the certificate parameter is NULL then delete resources IFS WIFI CA CERT XIM Set CA certificate as ximport DER PEM format longword IFS WIFI CLIENT CERT XIM Set client certificate and private key as two ximport DER PEM format files longword longword The first parameter is the certificate the second one is for the private key RETURN VALUE 0 Success gt 0 identifer of first parameter group that encountered an error 1 iface parameter is invalid An exception runtime error is raised if the parameter list contains an invalid parameter number LIBRARY NET LIB SEE ALSO Sock init tep config ip print iis ifstatus ifpendin TCP IP Manual Vol 1 rabbit com 145 ifdown int ifdown int iface DESCRIPTION This function attempts to deactivate the specified interface The action depends on the previous status reported bv ifpending ifpending Action IF DOWN None returns IFCTL OK IF COMING UP Cancels bringing up starts
237. onds in the Dynamic C TCP IP libraries This will work perfectly well for local Ethernet connections where the maximum packet lifetime is of the order of milli seconds For Internet connections this may be a bit short but will generally be satisfactory If in fact the time wait period is too short the worst that will happen is that one of the peers will be unsure about whether the other end got the last segment of data and confusion may happen if old packets from this connection happen to arrive after the close This latter case is unlikely to happen but if it does then it will eventually be resolved when the socket connection process times out If you want your application to be more robust you can increase this value 8 minutes is an extremely con servative value Most implementations shorten this to 2 minutes or 30 seconds since packets are extremely unlikely to survive more than 15 seconds Note that this value is only used if you do not specify the tcp_reserveport option for the local port of a passively opened connection If you specify reserveport then the time wait period is set to zero TCP_LAZYUPD This defaults to 5 ms and is used for several purposes The first use is to reschedule transmission attempts that could not be processed owing to local resource shortages For example if a previous packet is still being transmitted via a slow PPP interface the current packet may need to be delayed Similarly the Ethernet hardwar
238. or the IP address will be reset to 0 At some later time this function can be called to try to obtain an IP address This function blocks until the lease is renewed or the process times out RETURN VALUE 0 OK lease was not expired or an IP address lease was acquired with the same IP address as previously obtained 1 An error occurred no IP address is available TCP IP functionality is thus not available Usual causes of an error are timeouts because a DHCP or BOOTP server is not available within the timeout specified by the global variable _bootptimeout default 30 sec onds 1 Lease was re acquired however the IP address differs from the one previously obtained All existing sockets must be re opened Normally DHCP servers are careful to reassign the same IP address previously used by the client however this is sometimes not possible LIBRARY BOOTP LIB TCP IP Manual Vol 1 rabbit com 113 dhcp get timezone int dhcp get timezone long seconds DESCRIPTION This function returns the time zone offset provided by the DHCP server if any or uses the fall back time zone defined by the TIMEZONE macro Note that TIMEZONE is expressed in hours whereas the return result is in seconds PARAMETERS seconds Pointer to result longword If the return value is 0 OK then this will be set to the number of seconds offset from Coordinated Universal Time UTC The value will be
239. ord at this location is set to the interface number that can access the router siface Specific interface or IF ANY to select the best router for the given IP ad dress TCP IP Manual Vol 1 rabbit com 183 RETURN VALUE router for iface cont d Positive value Completed successfully ATH NOROUTI LIBRARV ARP LIB SEE ALSO router add ER No suitable router found Either no router is configured or the given IP ad dress is on the local subnet of the specified interface or no router on the specified interface can handle the address based on the router network netmask information in the router table 184 rabbit com TCP IP Manual Vol 1 router print int router print byte r DESCRIPTION Print a router table entry indexed by r This is for debugging only since the results are printed to the Dynamic C stdio window r may be obtained from the router for function by passing amp r as the router used parameter to that function If the specified router entry is not in use nothing is printed and the return value is non zero Otherwise the information is printed and zero returned See router printall fora description of the output fields printed PARAMETER r Router table index A number from 0 through ARP ROUTER TABLE SIZE l RETURN VALUE 0 Success information printed to stdio window 10 Entry is not in use LIBRARY ARP LIB SEE ALSO router
240. orkstations Use of these protocols can completely eliminate the need for static configuration The library BOOTP LIB allows a target board to be a BOOTP or DHCP client The protocol used depends on what type of server is installed on the local network BOOTP and DHCP servers are usually centrally located on a local network and operated by the network administrator Note that initialization may take longer when using DHCP as opposed to static configuration but this depends on your server Also note that if the interface goes down for any reason the application will need to bring the interface back up and redo any changes to the default configuration such as setting IFS_DHCP_ TIMEOUT This behavior differs from the behavior of a PC which will automatically bring the interface back up Both protocols allow a number of configuration parameters to be sent to the client including e client s IP address e net mask e list of gateways e host and default domain names e list of name servers BOOTP assigns permanent IP addresses DHCP can lease an IP address to a host 1 e assign the IP address for a limited amount of time There are two user callable functions regarding IP address leases TCP IP Manual Vol 1 rabbit com 11 dhcp_release and dhcp acquire described in Function Reference on page 93 In addition there are a number of macros and global variables available for modifying behavior and o
241. ost often ISPs also have special requirements for establishing PPP links which are often unrelated to PPP itself For example many ISPs require navigation of login scripts which are basically intended for human users With hard wired connections e g RS232 cables with null modems or crossed over connections the process of establishing a PPP link is relatively simple and reliable Bringing such a PPP link up involves opening the serial port sending and receiving PPP link negotiation messages known as LCP Link Control Protocol sending and receiving authentication messages PAP Password Authentication Protocol then finally sending and receiving Internet Protocol Control Messages IPCP If all negotiations are successful the link is then ready for TCP IP traffic If the link is established via a modem then an extra layer of activity must precede the initial PPP negotiation This is outside the scope of PPP since it is really related to the establishment of a physical layer The TCP IP library gives you the option of incorporating the modem connection phase into the process of bringing the interface up and down If preferred the modem phase can be performed entirely separately from the i fup ifdown process This may be necessary if there are special requirements for connecting to the ISP 2 5 2 PPP over Ethernet PPPoE is often considered a hack It seems superfluous to define a protocol that establishes a logical
242. ot need to be expanded thus speeding startup time IMPORTANT When statically configuring a Rabbit Wi Fi device specify either the pre shared key with IFC WIFI WPA PSK HEXSTR or the passphrase with FC WIFI WPA PSK PASSPHRASE but NOT BOTH If you do specify both then FC WIFI WPA PSK HEXSTR will take precedence that is if you have a correct passphrase but an incorrect pre shared key then the incorrect pre shared key will be used The macro WIFI PSK _ HEX was deprecated in Dynamic C 10 40 IFC_WIFI_WPA_PROTOCOL Set to bitwise OR of the following e IFPARAM WIFI WPA PROTOCOL WPA2 e IFPARAM WIFI WPA PROTOCOL WPA 38 rabbit com TCP IP Initialization to support WPA2 RSN Robust Security Network with CCMP or WPA the original TKIP based WiFi Protected Access IFC WIFI CLIENT CERT XIM Set to two parameters first parameter is public certificate of this client machine for EAP TLS Second parameter is for the corresponding private key These are generally ximported files which are the der or pem certificate private key files Currently the private key file must not itself be encrypted This is only used for EAP TLS Note if certificates have been generated by the Rabbit Certificate Utility then you should ximport the lt basename gt s pem and lt basename gt key pem files where lt basename gt is the file name you selected for
243. printall TCP IP Manual Vol 1 rabbit com 185 router printall int router printall void DESCRIPTION Print all router table entries This is for debugging only since the results are printed to the Dy namic C stdio window If no routers exist in the table nothing is printed and the return value is non zero There are 6 fields for each router entry Router Table Entry Field Description of Field The entry number A list of the following characters P this entry pre configured T transient entry Flags D added by DHCP BOOTP R added by ICMP redirect 2 router not reachable H router s hardware address resolved Either the router s IP address or an indication that the entry is a Add z er Sch point to point link i f Interface number For pre configured entries indicates the network s which are served by this entry the Mask indicates which bits of the IP Net preference address are used to match with the network address For non pre configured entries this is the preference value assigned For pre configured entries the bitmask to apply to IP addresses Mask exp sec when matching against the above network Otherwise is the expiry time from the present in seconds of a transient entry RETURN VALUE 0 Success information printed to stdio window 0 No routers in the table LIBRARY ARP LIB 186 rabbit com TCP IP Manual Vol 1 Send ping int send p
244. ptr Function to call repeatedly while waiting This is a user supplied function status Pointer to a status word RETURN VALUE None LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB 236 rabbit com TCP IP Manual Vol 1 sock wait established void sock wait established void s int seconds int fptr int status DESCRIPTION This macro waits until a connection is established for the specified TCP socket or aborts if a time out occurs It returns immediately for UDP sockets On an error the macro jumps to the local user supplied sock err label If fotr returns non zero the macro returns This macro has been deprecated in Dynamic C version 7 20 PARAMETERS s Pointer to a socket seconds Number of seconds to wait before timing out A value of zero indicates the macro should never time out A good value to use is sock delav a sys tem variable set on configuration Typically sock delav is about 20 seconds but can be set to something else in main fptr Function to call repeatedly while waiting This is a user supplied function status Pointer to a status word RETURN VALUE None LIBRARV NET LIB Prior to DC 7 05 this was DCRTCP LIB TCP IP Manual Vol 1 rabbit com 237 sock waiting int sock_waiting tcp Socket s DESCRIPTION This function determines whether a TCP socket is waiting for a connection establishment It re turns TRUE non zero if and only if the socket is open but not YET
245. r This field verifies the header and the data This feature can be disabled on a reliable network where the application has the ability to detect transmission errors Disabling the UDP checksum can increase the performance of UDP packets moving through the TCP IP stack This feature can be modified by sock mode s UDP MODE CHK enable checksums sock mode s UDP MODE NOCHK disable checksums The first parameter is a pointer to the socket s data structure either tcp Socket orudp Socket In Dynamic C version 7 20 some convenient macros offer a safer faster alternative to using sock model They are udp_set_chk s andudp set nochk s Improved Interface With Dynamic C version 7 05 there is a redesigned UDP API The new interface is incompatible with the previous one UDP Socket Functions 7 05 and later on page 50 covers the new interface and UDP Socket Functions pre 7 05 on page 51 covers the previous one See Porting Programs from the older UDP API to the new UDP API on page 52 for information on porting an older program to the new UDP interface TCP IP Manual Vol 1 rabbit com 49 3 6 UDP Socket Functions 7 05 and later Starting with Dynamic C 7 05 the UDP implementation is a true record service It receives distinct data grams and passes them as such to the user program The socket I O functions available for TCP sockets will no longer work for UDP sockets 3 6 1 Control Functions for UDP Socke
246. r Ethernet esse sesse ese see ee 26 2 6 Configuration Macro Retference 26 2 6 1 Removing Unnecessary Functions 26 2 6 2 Including Additional Functions 27 2 6 3 BOOTP DHCP Control Macros 27 2 6 4 Buffer and Resource Sizing 28 2 6 5 Network Configuration Prior to Dynamic C 130 31 2 6 6 Network Configuration Starting with Dynamic C 130 31 2 6 7 Time Outs and Retry Counters 33 2 6 8 Program Debugging esse see 34 2 6 9 Miscellaneous Macros 35 2 6 9 1 TOS and TTL ou eee 35 2 6 10 Wi Fi Configuration Macros 36 3 TCP and UDP Socket Interface 41 3 1 What is a Bockel 42 3 1 1 Port Numbers sses 42 3 2 Allocating TCP and UDP Sockets 43 3 2 1 Allocating Socket Buffers 43 3 2 2 Socket Buffer Sizes esse ee 44 3 2 2 1 User Supplied Buffers 44 3 3 Opening TCP Sockets ie ese se ee 44 3 3 1 Passive Open Lower 44 3 3 2 Active Open ee ee ee Re RE 45 3 3 3 Waiting for Connection Establishment 45 3 3 4 Specifying a Listen Queue 46 3 4 TCP Socket Functions eee 46 3 4 1 Control Functions for TCP Sockets 46 3 4 2 Status Functions for TCP Sockets 47 3 4 3 I O Functions for TCP Sockets 48 3 5 UDP Socket Overview ss sees ee see ee 49 3 6 UDP Socket Functions 7 05 and later 50 3 6 1 Control Functions for UDP Sockets 50 3 6 2 Status Function for UDP Sockets 50 TCP IP User s Manual 3
247. rabbit com Introduction 2 TCP IP Initialization This chapter describes the configuration macros data structures and functions used to configure and initialize the Dynamic C TCP IP stack Starting with Dynamic C version 7 30 the stack supports multiple interfaces Interface configuration is described in Interface Configuration on page 8 The Dynamic C TCP IP stack supports IP version 4 Although multiple interfaces are supported the TCP IP stack does not support packet routing at the IP level 2 1 TCP IP Stack Configuration You need to know certain things to configure the stack You need to know which interfaces will be used and how many You also need to determine the necessary software functionality For example will there be DNS lookups Are TCP and UDP protocols both necessary Will DHCP be used The ability to remove unneeded features via conditional compilation has been enhanced starting with Dynamic C 7 30 This is accomplished with the configuration macros described in Removing Unnecessary Functions on page 26 and Including Additional Functions on page 27 2 1 1 Multiple Interface Support The supported interfaces are e Ethernet e PPP Point to Point Protocol over a serial link e PPP over Ethernet e Wi Fi 802 11b 802 11g The interfaces must be on distinct non overlapping subnets In particular each interface must be assigned a unique IP address known as the home IP address for that interfac
248. rd TCP IP Manual Vol 1 rabbit com 137 IFS WIFI TX RATE Set maximum transmit rate as a multiple of 100 kbps int Use the macros below or their integer equivalents Available on 802 11b and 802 11g hardware IFPAI IFPAI IFPAI IFPAI IFPAI RAM RAM RAM RAM ifconfig cont d RAM WIFI TX RATE ANY 0 WIFI TX RATE 1 10 1 0 Mbps WIFI TX RATE 2 20 2 0 Mbps WIFI TX RATE 5 5 55 5 5 Mbps WIFI TX RATE 11 110 11 0 Mbps Available on 802 11g hardware only IFPAI IFPAI IFPAI IFPAI IFPAI IFPAI IFPAI IFPAI RAM 7 TX RATI RAM 7 TX RATE RAM 7 TX RATE m H e H 6 60 6 0 Mbps 9 90 9 0 Mbps 12 120 12 0 Mbps RAM 7 TX RATE n RAM 7 TX RATE RAM 7 TX RATE RAM 7 TX RATE RAM 7 RY RY RY RY RY RY Hd Hi TX RATE ri fait aa ri IFG WIFI_TX_RATE Get maximum transmit rate setting int IFS WIFI TX POWER 18 180 18 0 Mbps 24 240 24 0 Mbps 36 360 36 0 Mbps 48 480 48 0 Mbps 54 540 54 0 Mbps Set maximum Tx power valid values are 0 15 IFG WIFI_TX_POWER Get maximum Tx power setting int IFS WIFI FRAG THRESHOLD Set fragment threshold valid values are 256 2346 IFG WIFI FRAG THRE
249. re detailed messages are printed You can set this variable directly at the start of your main function or preferably use T ifconfig IF ANY IFS D BUG 5 TES END 2 6 9 Miscellaneous Macros TCP FASTSOCKETS Define to 1 if sockets connected to reserved ports can be closed without the usual 2MSL delay The default is set to 1 define to 0 to override this NET ADD ENTROPY Define this macro to allow network packet arrival times from any interface to be a source of random number seeds See RAND LIB for further information NET COARSELOCK This macro is only used when uC OS II is active It affects the definition of 2 other macros LOCK SOCK s and UNLOCK SOCK s If NET_COARSELOCK is not defined the lock unlock macros are individual socket locks for use on socket transmit receive buffers and the socket structure itself If it is defined the lock unlock macros are global locks TCP NO CLOSE ON LAST READ If defined then support halt close i e sock close only closes the transmit side of the socket but allows indefinite receives until the peer closes This prevents the normal close timeout from being set Also when reading if the socket is half closed by the peer then the socket will be automatically closed from this side if this define is not set 2 6 9 1 TOS and TTL TOS and TTL are fields in the IP header TOS short for Type of Service
250. re also used to pro vide well known starting points for common protocols For example TCP port number 23 is used for standard telnet connections In general port numbers below 1024 are used for standard services Numbers between 1024 and 65535 are used for connections of a temporary nature Often the originator of a connec tion will select one of the temporary port numbers for its end of the connection with the well known num ber for the other end which is often some sort of server TCP and UDP port numbers are not related and operate in an independent space However the well known port numbers for TCP and UDP services often match if the same sort of protocol can be made to run over TCP or UDP When you open a socket using the TCP IP libraries you can specify a particular port number to use or you can allow the library to pick a temporary port number for an ephemeral connection 42 rabbit com TCP and UDP Socket Interface 3 2 Allocating TCP and UDP Sockets In all versions of Dynamic C TCP and UDP socket structures must be allocated in static data storage This is simply accomplished by declaring a static variable of type tcp Socket or udp Socket static tcp Socket static udp_ Socket my sock my udp sock arrayl20 3 2 1 Allocating Socket Buffers Starting with Dynamic C version 7 05 there are two macros that define the number of sockets available These macros do not determine ho
251. ro is also required for EAP TLS The userID may be set to a dummy value depending on the requirements of the Authentication Server IFC_WIFI_PASSWORD Define a password for PEAP This is not used for EAP TLS define IFC WIFI PASSWORD my passw0ra IFC WIFI AUTHENTICATION default IFPARAM WIFI AUTH ANY Specifies the authentication mode to use for this Wi Fi network It accepts a combination with multiple values ORed together of the following values e IFPARAM WIFI AUTH ANY Use any method TCP IP Manual Vol 1 rabbit com 39 e IFPARAM WIFI AUTH OPEN Use open authentication e IFPARAM WIFI AUTH SHAREDKEY Use WEP shared key authentication e IFPARAM WIFI AUTH WPA PSK Use WPA pre shared key TKIP CCMP the macro WIFI USE WPA must be defined to use this parameter This implies the IEEE 802 111 Personal operating mode e IFPARAM WIFI AUTH WPA 8021X Use IEEE 802 1X EAP authentication This implies the IEEE 802 11i Enterprise operating mode For more information on Wi Fi Enterprise refer to An Introduction to Wi Fi available online and with the Dynamic C distribution The macro WIFI AUTH MODE was deprecated in Dynamic C 10 40 IFC_WIFI_FRAG THRESHOLD default 0 Set the fragmentation threshold Frames or packets that are larger than this threshold are split into
252. rting with DC 7 30 PARAMETERS s Pointer to a TCP socket dp Buffer to place bytes that are read len Number of bytes to copy to the buffer RETURN VALUE 1 len is greater than the total socket receive buffer size hence this request could never be satis fied in one call 2 The socket is closed or closing but insufficient data is in the buffer to satisfy the request 3 len lt 0 or the socket parameter was invalid 0 Insufficient data is in the buffer to satisfy the request or Len was zero Try again later since the socket is still able to receive data from the peer len The len parameter is returned if there was sufficient data in the socket buffer to satisfy the request LIBRARY TCP LIB SEE ALSO sock fastread sock xfastread sock fastwrite sock xfastwrite sock axread sock awrite sock axwrite TCP IP Manual Vol 1 rabbit com 193 sock awrite int sock_awrite tcp Socket s byte dp int len DESCRIPTION Write exactly len bytes to the socket or if that amount of data can not be written do not write anything Unlike sock fastwrite this function will never return less than the request ed amount of data This can be useful when the application needs to write a fixed amount of data but does not wish to handle the transmission of only part of the data as it would have to do if sock fastwrite was used len must be less than or equal to the socket transmit buffer size otherwise sock fastwrite mus
253. ryption used Select one of the following e IFPARAM W e IFPARAM W e IFPARAM W e IFPARAM W to use this parameter e IFPARAM WIFI ENCR_CCMP Use WPA2 encryption both W WIFI AES ENABLED must be defined to use this parameter The macro _WIFI_ WEP FLAG was deprecated in Dynamic C 10 40 ENCR_ANY Use any type of encryption ENCR NONE No encryption used ENCR WEP Use WEP encryption CR TKIP Use WPA encryption the macro WIFI_USE_WPA must be defined mm tjo t roi G We E WPA and IFC_WIFI_WEP_KEYNUM default 0 Select the WEP key to use when using WEP encryption This macro can have the value 0 1 2 or 3 which corresponds to the WEP key macros IFC WIFI WEP KEY described next al The macro W USEKEY was deprecated in Dynamic C 10 40 IFC_WIFI_WEP_KEYO BIN TCP IP Manual Vol 1 rabbit com 37 IFC_WIFI_WEP_KEY1_ BIN IFC_WIFI_WEP_KEY2 BIN IFC_WIFI_WEP_KEY3 BIN Specifies the possible WEP keys to use for WEP encryption They default to undefined These keys can be either 40 bit or 104 bit i e 5 bytes or 13 bytes and must be a comma separated list of byte values The IFC WIFI WEP KEY BIN macro that is used depends on the value of FC WIFI WEP KEYNUM
254. s NOT recommended to program a hard coded string as for class ID Note that RFC2132 recommends that the first byte of the string should be zero if the client ID is not actually the hardware type and address of the client see next DHCP CLIENT ID MAC If defined this overrides DHCP CLIENT ID and automatically sets the client ID string to be the hardware type 1 for Ethernet and MAC address as suggested by RFC2132 2 6 4 Buffer and Resource Sizing MAX SOCKETS deprecated This macro defines the number of sockets that will be allocated not including the socket for DNS lookups It defaults to 4 If libraries such as HTTP LIB or FTP SERVER LIB are used you must provide enough sockets in MAX SOCKETS for them also This macro has been replaced by MAX TCP SOCKET BUFFERS and MAX UDP SOCKET BUFFERS MAX SOCKET LOCKS For uC OS II support This macro defines the number of socket locks to allocate It defaults to MAX TCP SOCKET BUFFERS MAX UDP SOCKET BUFFERS This macro is necessary because we can no longer calculate the number of socket locks needed based on the number of socket buffers now that the user can manage their own socket buffers MAX TCP SOCKET BUFFERS Starting with Dynamic C version 7 05 this macro determines the maximum number of TCP sockets with preallocated buffers If MAX SOCKETS is defined then MAX TCP SOCKET BUFFERS w
255. s TCP IP stack parameters at runtime It should not be called with open sockets Note that there are specific and safer functions for modifying some of the common parame ters This function is deprecated and will be removed in a future release The recommended replace ment function is ifconfig PARAMETERS name Setting to be changed The possible parameters are MY IP ADDRESS host IP address use sethostid instead MY NETMASK MY GATEWAY host s default gateway MY NAMESERVER host s default nameserver MY HOSTNAME MY DOMAINNAME host s domain name use setdomainname in stead value The value to assign to name RETURN VALUE None LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tcp open sock close sock abort sethostid setdomainname sethostname 246 rabbit com TCP IP Manual Vol 1 tcp extlisten int tcp_extlisten Cep Socket s int iface word lport longword remip word port dataHandler t datahandler word reserved long buffer int buflen DESCRIPTION This function tells DCRTCP that an incoming session for a particular port will be accepted The buffer and buflen parameters allow a user to supply a socket buffer instead of using a socket buffer from the pool tcp extlisten is an extended version of Cep listen PARAMETERS s Pointer to the socket s data structure iface Local interface on which to open the socket
256. s joined automatically when the remote IP address passed to udp open isa valid multicast address A host group may also be joined by a call to multicast joingroup Leaving a host group is done automatically when udp close is called Like joining leaving a group may be done explicitly by an application by calling an API function in this case multicast leavegroup TCP IP Manual Vol 1 rabbit com 81 6 2 IGMP As long as all multicast traffic is local e on the same LAN IGMP is not needed IGMP is used for reporting host group memberships to any routers in the neighborhood The library IGMP LIB conforms to RFC 2236 for IGMPv2 hosts 6 3 Multicast Macros As mentioned above the use of IGMP is not required for multicast support on a LAN You may select only multicast support by defining USE MULTICAST USE MULTICAST This macro will enable multicast support In particular the extra checks necessary for accepting multicast datagrams will be enabled and joining and leaving multicast groups and informing the Ethernet hardware about it will be added USE_IGMP If this macro is defined the USE MULTICAST macro is automatically defined This macro en ables sending reports on joining multicast addresses and responding to IGMP queries by multi cast routers Unlike USE MULTICAST this macro must be defined to be 1 or 2 This indicates which version of IGMP will be supported Note however that both version 1 an
257. s than this figure For maximum throughput on an Ethernet link use the largest value 1500 Note that in DC version 7 30 a macro will be defined which is set to the larger of ETH MTU and PPP MTU This macro is called MAX MTU and is used for sizing the receive buffer for incoming packets from all interfaces TCP IP Manual Vol 1 rabbit com 29 PPP MTU Define the maximum transmission receive unit for PPP over serial links This defaults to the same as ETH MTU ifit is defined or 600 This macro is new for 7 30 ETH MAXBUFS Define the maximum number of incoming packets that may be buffered Defaults to 10 The buffers are shared between all interfaces in spite of the name The total amount of root data storage for incoming packets depends on the configured mix of interface types but is MAX MTU 22 ETH MAXBUFS for just Ethernet without PPPoE This will default to 6220 bytes if the defaults are selected ARP TABLE SIZE Define to the number of ARP table entries The default is set to the number of interfaces plus 5 entries for every Ethernet interface excluding PPPoE The maximum allowable value is 200 ARP ROUTER TABLE SIZE Define the maximum number of routers Defaults to the number of interfaces plus an extra entry for each Ethernet excluding PPPoE MAX STRING Define the maximum number of characters for a hostname or for a mail server when using the function smtp setserver Defaults to 50 MAX NAMESERVERS D
258. s the number of bytes waiting to be read If the socket is in ASCII mode this function returns zero if a newline character has not been read or the buffer is not full For UDP sockets the function returns the number of bytes in the next datagram This function cannot tell the difference between no bytes to read and either a blank line or a UDP datagram with no data For this reason use sock bvtesreadv instead PARAMETERS s Pointer to a socket RETURN VALUE 0 No bytes to read or newline not yet read if the socket is in ASCII mode or for DC 7 05 and later if a UDP datagram has 0 bytes of data waiting to be read 20 Number of bytes ready to read LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock bytesready TCP IP Manual Vol 1 rabbit com 199 sockerr char sockerr void s DESCRIPTION Gets the last ASCII error message recorded for the specified socket Use of this function will introduce a lot of string constants in root memory For production programs it is better to use error numbers without translation to strings PARAMETERS s Pointer to a socket RETURN VALUE Pointer to the string that represents the last error message for the socket NULL pointer if there have been no errors If the symbol SOCKERR NO RETURN NULL is defined then if no error occurred the string OK will be returned instead of a NULL pointer The error messages are read only do not modify
259. s well as the same SSID WEP allows multiple keys to be defined all devices will need to be configured to use the same key number WEP keys are used for WEP shared key authentication and for WEP encryption The Wi Fi driver stores up to 4 different WEP keys 0 to 3 of either 5 or 13 bytes To configure within your program copy and paste the following into your sample program and modify as necessary define TCPCONFIG 1 define PRIMARY STATIC IP 10 10 6 100 define PRIMARY NETMASK 255 255 255 0 define MY GATEWAY 10 10 6 1 define MY NAMESERVER 10 10 6 1 define IFC WIFI SSID rabbitTest define IFC WIFI ROAM ENABLE 1 define IFC WIFI ROAM BEACON MISS 20 define IFC WIFI MODE IFPARAM WIFI INFRASTRUCTURE define IFC WIFI REGION IFPARAM WIFI REGION AMER define IFC WIFI ENCRYPTION IFPARAM WIFI ENCR WEP define IFC WIFI WEP KEYNUM 0 define IFC WIFI WEP KEYO HEXSTR alternate method to define a WEP key defin e FC WIF WEP KEXO BIN 0x01 0x01 0x 0x 23 0x4 23 0x4 5 5 0x67 0 0x67 0 x89 x89 CAS 0123456789abcdef0123456789 Oxab Oxcd Oxef Alternatively you can configure within the Defines window Here
260. se Callback should always return zero 3 11 1 UDP Data Handler For UDP sockets the callback is invoked as soon as a new datagram is demultiplexed to the socket For event type UDP DH INDATA the 11 Gather struct is set up with the interface number and pointers to the data in the receive buffers not the UDP socket receive buffer since the data has not yet been copied there The info structure is a pointer to udp datagram info UDI whichis set up with the usual udp_peek information such as the host IP address and port number and whether the datagram is in fact an ICMP error message If an ICMP message is received the event type is set to UDP DH ICMPMSG The callback should return 0 to continue with normal processing 1 e add the datagram to the socket buf fer or 1 to indicate that the datagram has been processed and should not be added to the socket buffer The data pointers in the 11 Gather structure are the physical address and length of one or two datagram fragments in the main network receive buffers Currently only one address will be provided since datagrams are reassembled before passing to the UDP handler There is also a root data pointer in the 11 Gather structure that is set to point to the IP and UDP headers of the datagram 3 11 2 TCP Data Handler The TCP data handler is only available if you define TCP_ DATAHANDLER It is invoked with a large number of different event types Most of the
261. size If in doubt increase the table size since each entry only takes up about 32 bytes 4 3 Writing a Fast UDP Request Response Server UDP is a lightweight protocol wrapper that adds port number multiplexing and checksums to basic IP packets Being lightweight it is capable of being very fast with low CPU overhead UDP is often selected for custom application protocols that do not need the reliable stream oriented connections of TCP UDP is connectionless however application designers can think in terms of client server or transaction based programming A popular design for UDP servers is to have the controller board listen for incoming datagrams Each incoming message is processed and an immediate reply is sent It is left up to the client to retransmit messages if it did not receive a reply in the expected time frame The server however is extremely simple to implement which allows it to serve more clients than a TCP based server could man age Starting with Dynamic C 7 30 a data handler facility has been added to UDP as well as TCP sockets The data handler is especially efficient for UDP since it allows the datagram to be processed without any copying to the socket buffer The UDP data handler is a callback function whose address is supplied on the udp_extopen call For simple request response applications the only application requirements are to define the data handler and call tcp_tick repeatedly in a loop after se
262. sock tick void s int optional status ptr DESCRIPTION This macro calls tcp tick to quickly check incoming and outgoing data and to manage all the open sockets If our particular socket s is either closed or made inoperative due to an error condition sock tick setsthevalueof toptional status ptr ifthe pointer is not NULL to 1 then jumps to a local user supplied label sock err If the socket connec tion is fine and the pointer is not NULL optional_status_ptr is set to 0 PARAMETERS s Pointer to a socket optional status ptr Pointer to status word RETURN VALUE None LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB TCP IP Manual Vol 1 rabbit com 235 sock wait closed void sock wait closed void s int seconds int fptr int status DESCRIPTION This macro waits until a TCP connection is fully closed Returns immediately for UDP sockets On an error the macro jumps to a local user supplied sock err label If fotr returns non zero the macro returns with the status word set to the value of fptr s return value This macro has been deprecated in Dynamic C version 7 20 PARAMETERS s Pointer to a socket seconds Number of seconds to wait before timing out A value of zero indicates the macro should never time out A good value to use is sock delay a sys tem variable set on configuration Typically sock delay is about 20 seconds but can be set to something else in main f
263. solve start ATHandle arpresolve start longword ipaddr DESCRIPTION Start resolve process for the given IP address This may return immediately if the IP address is in the ARP cache table and still valid Otherwise if the IP address is on the local subnet then an ARP resolve request is issued through the appropriate interface If the address is not on the local subnet then a router table entry is used and no network activity is necessary unless the router itself is not resolved in which case its resolution commences PARAMETER ipaddr IP address of host whose hardware address is to be resolved RETURN VALUE Positive value Success The value is actually the ATH of the ARP cache table entry which is or will be used This value should be passed to subsequent calls to arpresolve check ATH NOENTRIES No space is available in the table and none of the entries could be purged because they were all marked as permanent or router entries ATH NOROUTER No router gateway is configured for the specified address which is not on the local subnet LIBRARY ARP LIB 108 rabbit com TCP IP Manual Vol 1 arpresolve start iface ATHandle arpresolve start iface longword ipaddr word iface DESCRIPTION Start resolve process for the given IP address This may return immediately if the IP address is in the ARP cache table and still valid Otherwise if the IP address is on the local subnet of the specified
264. some other type of data stream for example asynchronous serial data The data may flow in either or both directions This type of application has the most stringent requirements on both throughput and latency This is because the incoming stream may not be amenable to any sort of flow control it is necessary for TCP to keep up with a possibly high data rate Also the more timely the transmission of data the more useful the protocol translator 76 rabbit com Optimizing TCP IP Performance DE 5 Network Addressing ARP amp DNS ARP Address Resolution Protocol and DNS Domain Name System perform translations between vari ous network address formats ARP converts between IP addresses and usually Ethernet hardware addresses DNS converts between human readable domain names such as ftp mydomain org and IP addresses ARP and DNS are not closely related protocols but they are lumped together in this chapter for conve nience In the Dynamic C TCP IP libraries ARP LIB handles ARP proper as well as router gateway functionality 5 1 ARP Functions ARP Address Resolution Protocol is used on non PPPoE Ethernet interfaces ARP is used to determine the hardware address of network interface adapters Most of the ARP functionality operates in the back ground and is handled by the TCP IP libraries Most applications should not need to deal with ARP and indeed some of the ARP functions are quite complex to use correctly
265. sort of environment For this reason it is best to use the default settings for general purpose applications since the defaults work well in worst case settings without affecting best case performance unduly TCP is internally adaptive to network bandwidth and RTT which are the main variables Some of the time out settings only apply to an initial guess of the network characteristics TCP will converge to the correct values in a short time Specifying a good initial guess will help TCP in the initial stages of establishing a socket connection 4 2 2 1 Time Out Setting Constants The following constants can be defined before including dcrtcp 1ib They specify various time inter vals that have a bearing on connection performance RETRAN STRAT TIME This defaults to 10 ms It specifies the minimum time interval between testing for retransmissions of data for a particular TCP socket This not only provides an upper bound for packet transmission rate but also cuts down on CPU overhead Since retransmissions are basically driven from tcp_tick the less time used in tcp tick processing the more time is left for your application Note that the actual minimum retransmit interval is defined by TCP MINRTO this setting only affects the testing interval Retransmissions are only required when there is an unexpected surge in network congestion which causes packets to be delayed well beyond the average or even dropped It is not recommended
266. ss protocol hence sock established always returns 1 for UDP sockets PARAMETERS s Pointer to a socket RETURN VALUE 0 Not established 1 Established LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock bytesready sockstate 202 rabbit com TCP IP Manual Vol 1 sock fas tread int sock fastread tcp Socket s byte dp int len DESCRIPTION Reads up to Len bytes from dp on socket s If possible this function fills the buffer otherwise only the number of bytes immediately available if any are returned Starting with Dynamic C 7 05 this function is only valid for TCP sockets For UDP sockets useudp recv orudp recvfrom Prior to 7 05 this function cannot be used on UDP sockets after sock recv init is called PARAMETERS s Pointer to a socket dp Buffer to put bytes that are read len Maximum number of bytes to write to the buffer RETURN VALUE gt 0 Success number of bytes read 1 Error LIBRARY TCP LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO sock read sock fastwrite sock write sockerr udp recv udp recvfrom sock xfastwrite sock aread sock axread EXAMPLE Note that sock fastread and sock read do not necessarily return a complete or single line they return blocks of bytes In comparison sock getc returns a single byte at a time and thus yields poor performance do je cais tunectionm goes mor block len SOCK tastread s butt
267. stablished LIBRARY PKTDRV LIB 168 rabbit com TCP IP Manual Vol 1 pd_powerdown int pd powerdown int nic DESCRIPTION Power down the interface hardware by turning off as many services as possible When the NIC is in powerdown mode it is very important to not call any TCP IP Ethernet etc functions as they will obviously fail and the results will be undefined pd powerup should be the very next network function called to re enable the NIC WARNING When used to power down a wireless chipset IF WIF10 interface then this will result in loss of association with the access point In effect the network interface will come down Thus it is highly recommended to bring the interface down before calling this power down func tion See the POWERDOWN C sample in Samples RCM4400W TCPIP for an example of how to do this PARAMETERS nic The interface to powerdown Currently only some Ethernet chipsets are applicable IF ETHO and some Wi Fi chipsets such as on the RCM4400W If the interface does not support this function then it will be ignored RETURN VALUE 0 Success 10 Error LIBRARY PKTDRV LIB SEE ALSO pd_powerup TCP IP Manual Vol 1 rabbit com 169 pd_powerup int pd powerup int nic DESCRIPTION Power up the NIC undoing the sleepy mode changes made by pd_powerdown After this function has returned success Ethernet and TCP IP function may be called again NO
268. t SOCKS sccis nsien 107 SOCK ADOT E 203 tea 210 SOCK Gebeier 214 Sock Waiting osse see ee N EN 250 tep_keepalive ses ed Go 261 Socket VO Buffer sock rbleft EE N 231 ee de dei EE OE bi ad OE IE 232 ee die EE rails f 233 SOCK L geet ee 244 BORK E 245 SOCK eege 246 Socket Status ip _timer_expired soes seesand 167 ip timer init occas ie ese EEN Re SEE AG 168 Sock AMINES ee RE SN ARE Ge 204 SOCK eo EE AA N EO 209 SOCK datareadV esse KERE KEN AREAS Ge 211 SOCK EO ee N Ge 213 ee de EE AE it da 227 Sock readabl soes RA ENGEN 235 sock _resolved sees ERK Ki ie 240 Ska Sa asa EE DEGREE 252 TOTE a a eE 212 e ie a dg 243 tep ie EE OO 267 TCP Socket VO Sock arcad EE 205 rabbit com e E 206 ee dies AL N GE 239 Sock axr ad EE Oe 207 Mad BOCK _axwrite ee 208 WEE sock _fastread es RE EER Ee de 215 Ee 209 sock_fastwrite eds eise KERSE NE 216 SOCK IUS soe se AS 217 ee ad iS OE AO ka 218 sock gete aas RE N ee 219 ee di EE Ee ee 220 soek nofl sh issue ske MEE ee 226 sock_preread Ee Rede adida 228 SOCK EE eeng Ee 229 CH 230 sock te d EE 234 sock write egene 253 sock_xfastread en ee 254 SOCK _xfastwrite EE OE ik obd 255 sock_yield i ske RE kd 256 tep EISE enge Seege Ge jid 259 top SKC E 260 tep EE RE OE OE iku 262 tep Open ee EG be 264 UDP Socket VO udp CLOSE RE ON N 269 udp_extopen E E 270 udp OPE tana ki ns Ge aeia 212 MAD peek see EG tibda 274 lk ede EO OP OE IE 275 dp POC VION ES eeedEeeggbuege 276 udp_sen
269. t addresses If remip is a multicast address then pack ets sent with this function will go to the multicast address and packets received will also be from that multicast address Also if enabled IGMP will be used to join the multicast groups The group will be left when the socket is closed Note that if port is 0 and remip is a multicast address the port will not be filled in on the first received datagram that is the socket is non binding to the port 258 rabbit com TCP IP Manual Vol 1 PARAMETERS S iface lport remip port datahandler buffer buflen RETURN VALUE 0 Success udp_extopen cont Pointer to socket Local interface on which to open the socket Use IF_ANY if the socket is to accept datagrams from any interface Otherwise datagrams will be ac cepted only from the specified interface This parameter is supported as of Dynamic C 7 30 With earlier version of DC this parameter should be Local port F D EFAULT Acceptable remote IP or 0 for all Acceptable remote port or 0 for all Function to call when data is received NULL for placing data in the sock et s receive buffer Address of user supplied socket buffer in xmem If buffer is 0 the socket buffer for this socket is pulled from the buffer pool defined by the BUFF ERS macro MAX UDP SOCKET 1 Length of user supplied socket buffer 0 Failure error opening socket e g
270. t be used This function is only valid for TCP sockets It is available starting with DC 7 30 PARAMETERS s Pointer to a TCP socket dp Buffer containing data to write len Number of bytes to write to the socket buffer RETURN VALUE 1 len is greater than the total socket receive buffer size hence this request could never be satisfied in one call 2 The socket has been closed for further transmissions e g because sock close has already been called 3 len lt 0 or the socket parameter was invalid 0 Insufficient free space in the transmit buffer to satisfy the request or Len was zero Try again later since the peer will eventually acknowledge the receipt of previous data freeing up transmit buffer space len The len parameter is returned if there was sufficient data in the socket transmit buffer to satisfy the request LIBRARY TCP LIB SEE ALSO sock fastread sock xfastread sock fastwrite sock xfastwrite sock axread sock aread sock axwrite 194 rabbit com TCP IP Manual Vol 1 sock axread int sock axread tcp Socket ze long dp int Leni DESCRIPTION Reads exactly Len bytes from the socket or if that amount of data is not yet available do not read anything This function is available starting with DC 7 30 It is identical to sock_aread except that the destination buffer is in xmem PARAMETERS s Pointer to a TCP socket dp Buffer to place bytes that are read len Number of bytes to copy
271. t the network interface will not necessarily be available immediately after sock init is called even if you are simply using an Ethernet interface with a static con figuration This is especially true if you are using DHCP If you need to make a network con nection directly after calling sock init then you will probably want to use code like the following sock init while ifpending IF DEFAULT IF COMING UP tcp tick NULL The while loop will not finish until the interface has either completely come up or has failed see the documentation for i fpending for more information If you use ucos2 lib be sure to call OSInit before calling sock init RETURN VALUE 0 OK 1 Ethernet packet driver initialization failed Other reserved LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB 210 rabbit com TCP IP Manual Vol 1 sock init or exit void sock init or exit int verbose DESCRIPTION This is a convenience function intended mainly for sample code which starts a network inter face It is equivalent to the following sequence if sock_init 0 exit NETERR FDOWN while ifpending IF DEFAULT IF COMING UP tcp tick NULL if ifpending F DEFAULT l IF UP exit NETERR IFDOWN In other words it attempts to initialize the network stack via sock init It then wa
272. ta such as a log to a server e Casual Server one which just needs to process occasional commands which come in from the network This includes interactive servers such as telnet e Master Controller one which sends short data bursts to a number of slave controllers which must be sent and processed in a timely manner e Web Server a web enabled appliance e Protocol Translator accepts stream of data perhaps serial and converts to a TCP data stream or vice versa All these application types have different requirements for the basic properties of a communications chan nel namely bandwidth throughput and latency The bandwidth of a channel is the maximum sustained rate of end to end data transmission in bytes per second A full duplex channel has the same bandwidth in each direction independent of data traffic flow ing in the opposite direction In a half duplex channel the total bandwidth is divided between both direc tions Ethernet is usually half duplex in that an Ethernet chip cannot send and receive at the same time however some types of Ethernet can run full duplex The throughput of a channel is related to bandwidth but is used to express the amount of useful data that can be transmitted through the channel in a fixed specified amount of time using a practical transport protocol i e a protocol which adds some overhead to each message Throughput generally improves as the bandwidth rises and as the time
273. ted ping is not limited to just the default interface If both directed ping and DHCP are allowed on a particular interface the first one wins Directed ping works as follows The interface is brought up but has no assigned IP address so it cannot be used for normal traffic If the interface receives an ICMP echo request i e ping which is directed to the interface s MAC address then the destination IP address in the ICMP packet is assigned to the interface as its home IP address After that point the interface is configured and is available for normal traffic The weakness of directed ping is that only the IP address is provided The netmask must be pre configured or obtained by other means Technically directed ping violates some tenets of the Internet standards however it can be useful in controlled environments TCP IP Manual Vol 1 rabbit com 13 The MAC address of the board must be known see below for directed ping to work The host which initiates the ICMP echo request must have its ARP table statically configured with the target MAC address On Unix and Windows hosts the appropriate command sequence is arp s lt IP address gt lt MAC address gt followed by ping lt IP address gt The actual format of the MAC address depends on the operating system Most hosts will recognize a format like 00 09 A0 20 00 997 The IP address is in dotted decimal notation Once the interface is configured by directed pin
274. tep is to configure whatever transport medium will be used for the PPP connection For directly connecting a serial line to the peer the two serial data lines TX and RX may be adequate however the most common situation will be some sort of modem 7 3 1 The Modem Interface The interface between a modem and a controller is either a true RS232 interface or a variation on RS232 that uses TTL voltage levels for all of the signals The latter are used by board mounted modem modules If an external modem is used an RS232 transceiver chip is needed to convert RS232 voltages to logic sig nals and vice versa A full RS232 connection has 3 outputs and 5 inputs from the controller s point of view In RS232 terminology the controller is referred to as the DTE Data Terminal Equipment Modems and other peripherals are referred to as DCE s Data Communications Equipment The specifics of a dial up PPP connection are dependent on the modem hardware and the ISP There are some settings that require information obtainable only from the ISP like a phone number a username a password etc 84 rabbit com PPP Driver The sample programs for use with a modem Samples PPP MODEM c define macros used by modem lib Contact your ISP to substitute the correct string values for any of these macros needed by your application define DIALUP NAME username define DIALUP NUMBER 5551212 define DIALUP PASSWORD password define EMAIL FROM rabbit
275. th a single byte of data A total of 410 bytes will be sent With Nagle on the first character written at time zero will cause a 41 byte packet to be sent The acknowledgment of this first packet will not arrive for another 550ms In the meantime the application writes an additional 5 characters at 100ms intervals Since there is outstanding unacknowledged data the 68 rabbit com Optimizing TCP IP Performance first character these characters are not sent immediately They are buffered waiting for an acknowledg ment from the peer When the first character s acknowledgment comes in at 550ms there is no outstanding unack ed data the additional 5 characters have not yet been sent so they do not count as unack ed data Now the TCP stack will send the 5 additional characters in a single packet at approximately t 550ms While that packet is in transit 4 more characters are written by the application Again these characters will be buffered since characters 2 through 6 have not been acknowledged Only when the next acknowl edgment is received will these 4 characters be sent The total number of packets sent is 3 with 1 5 and 4 bytes of data This translates to 130 bytes in total Obviously the total number of bytes transmitted including overhead is far less when Nagle is used 130 compared with 410 bytes One can also examine how this looks from the point of view of the peer In the non Nagle case each character is received 275ms after
276. the client certificate For example if the file name was client then ximport certs clients pem my client cert ximport certs clientkey pem my client key define IFC WIFI CLIENT CERT XIM my client cert my client key IFC WIFI CA CERT XIM root ca cert Set to the ximported file containing the trusted certificate authority for validating the Authentication Server s public certificate This may be a pem or der format file This is used for EAP TLS and should also be used for PEAP since PEAP uses TLS under the covers In either case it is important to be able to verify the authenticity of the Authentication Server itself This is done by having the trusted CA certificate available Note if you generated your own Certificate Authority CA using the Rabbit Certificate Utility then you should ximport the lt basename gt der or lt basename gt pem file for the CA For example if the file name was my ca then ximport private my_ca der root_ca_cert define IFC_WIFI_CA_CERT_XIM root_ca_cert IFC_WIFI_IDENTITY Define an identity for PEAP Using this macro sets both the inner and outer identity to the same value define IFC_WIFI_IDENTITY MyClientIdent If your application requires a different outer plaintext identity then your application will need to use the ifconfig function directly This mac
277. the modified string LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB EXAMPLE setmode s TCP MODE ASC IS sock puts s rip questionable string NOTE In ASCII mode sock puts adds n rip is used to make certain the string does not already have a newline character Remember rip modifies the source string not a copy TCP IP Manual Vol 1 rabbit com 179 router add ATHandle router_add longword ipaddr byte iface longword subnet longword mask word flags DESCRIPTION Add a router to the router table The same router can be added multiple times with different subnet and mask Normally only one entry is needed in order to access non local subnets this entry should be specified with a zero mask The hardware address of the router is not immedi ately resolved however this can be done explicitly by calling arpresolve start with the same IP address Otherwise the router will be resolved only when it first becomes necessary PARAMETERS ipaddr IP address of the router This address should be on the local subnet since non local routers are not supported iface Interface to use to access this router or IF DEFAULT subnet Subnet accessible through this entry mask Subnet mask for this entry flags Flags word set to zero non zero reserved for internal use RETURN VALUE Positive value completed successfully The return value is the ARP cache table entry for this router
278. the value of this parameter may require the interface to be brought down tempo rarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted IFG WIFI CHANNEL Get current channel setting int IFS WIFI ENCRYPTION Set encryption word Setting the value of this parameter may reguire the interface to be brought down temporarily If this is necessary it will be brought up again before return however any sockets that were open on that interface will have been aborted Valid values are e IFPARAM WIFI ENCR ANY e IFPARAM WIFI ENCR NON e IFPARAM WIFI ENCR WEP ti IfWIFI USE WPA is defined e IFPARAM WIFI ENCR TKIP IfWIFI USE WPA and WIFI AES ENABLED are defined e IFPARAM WIFI ENCR CCMP IFG WIFI ENCRYPTION Get encryption setting word IFS WIFI AUTHENTICATION Set authentication method to use word Valid values are e IFPARAM WIFI AUTH ANY e IFPARAM WIFI AUTH OPEN e IFPARAM WIFI AUTH SHAREDKEY F F e IFPARAM W AUTH WPA PSK e IFPARAM W AUTH WPA 8021X Note that when using WEP encryption open authentication is actually more secure than shared key authentication IFG_WIFI_AUTHENTICATION Get current authentication setting wo
279. them LIBRARY NETERRNO LIB SEE ALSO sock error sock perror EXAMPLE Claaie jap if p sockerr s princi Socker closed wich error Ss abet eh 200 rabbit com TCP IP Manual Vol 1 sock error int sock error void Se int clear DESCRIPTION Return the most recent error number for the specified socket which may be a TCP or UDP sock et Up to two error codes may be queued to a socket PARAMETERS s socket clear 0 do not clear the returned error condition 1 clear the returned error from the socket You can call this function again to get the next older error code if any RETURN VALUE 0 No error T 10 One of the N TERR_ constants defined in NETERRNO LIB LIBRARY NETERRNO LIB SEE ALSO sockerr sock perror TCP IP Manual Vol 1 rabbit com 201 sock established int sock_established void s DESCRIPTION TCP connections require a handshaked open to ensure that both sides recognize a connection Whether the connection was initiated with tcp open ortcp listen sock established will continue to return 0 until the connection is established at which time it will return 1 It is not enough to spin on this after a listen because it is possible for the socket to be opened written to and closed between two checks sock bvtesreadv can be called with sock established to handle this case UDP is a connectionle
280. ther TCP IP functions with the possible exception of ifconfig IMPORTANT If you are using LC OS II then you must ensure that OSInit is called before calling sock init The function sock init performs the following actions and does not return until complete or an error was encountered e Calls subsystem initialization for ARP TCP UDP and DNS if applicable e Tests to see whether sock init was run previously If so then it returns OK Otherwise the fol lowing steps are executed e Initialize the packet driver basically this resets the hardware and clears out the packet receive buffer pool e Clears the router and other server tables e Interfaces are initialized using the settings specified in the IFCONFIG macros or predefined config urations WiFi takes longer to initialize than the other supported interfaces and potentially much longer if there is no AP within range which is analogous to not plugging in the Ethernet cable If all of the above completed successfully the return code is set to 0 Otherwise the return code will be non zero however you can still proceed if the return code is 2 since this indicates that DHCP failed but fallbacks were used Other return codes indicate that the network is not usable TCP IP Manual Vol 1 rabbit com 7 After sock init returns OK the non PPPoE Ethernet interface should be ready for traffic if it is intended to be up initially PPP interfaces ma
281. ticular interface number IFCONFIG DEFAULT is applied to the default interface IF DEFAULT if there is no specific IFCONFIG for the default interface These macros must be defined as a C parameter list fragment This is because the macro value is substituted into a call to ifconfig at initialization time sock init For example the fragment of code that initializes the non PPPoE Ethernet interface looks somewhat like the following ifdef IF_ETHO ifdef IFCONFIG ETHO ifconfig IF ETHO IFCONFIG ETHO IFS END else tif IF DEFAULT IF ETHO ifconfig IF DEFAULT IFCONFIG DEFAULT IFS END tendif tendif tendif fel The entire fragment is processed only if IF ETHO is defined i e you have specified that the non PPPoE Ethernet interface is to be used Inside this if the IFCONFIG ETHO macro has been defined then it is 32 rabbit com TCP IP Initialization substituted into an ifconfig call for IF ETHO Otherwise if IF ETHO is the default i e equal to F DEFAULT then the IFCONFIG DEFAULT macro is substituted into the ifconfig call H Note that for backwards compatibilitv IFCONFIG DEFAULT is alwavs defined to something if it was not explicitly defined
282. ting is a form of limited broadcast UDP is used to send datagrams to all hosts that belong to what is called a host group A host group is a set of zero or more hosts identified by the same destination IP address The following statements apply to host groups e Anyone can join or leave a host group at will e There are no restrictions on a host s location e There are no restrictions on the number of members that may belong to a host group e A host may belong to multiple host groups e Non group members may send UDP datagrams to the host group Multicasting is useful when data needs to be sent to more than one other device For instance if one device is responsible for acquiring data that many other devices need then multicasting is a natural fit Note that using multicasting as opposed to sending the same data to individual devices uses less network bandwidth 6 1 1 Multicast Addresses A multicast address is a class D IP address i e the high order four bits are 1110 Addresses range from 224 0 0 0 to 239 255 255 255 The address 224 0 0 0 is guaranteed not to be assigned to any group and 224 0 0 1 is assigned to the permanent group of all IP hosts including gateways This is used to address all multicast hosts on a directly connected network 6 1 2 Host Group Membership Any datagram sent to a multicast address is received by all hosts that have joined the multicast group asso ciated with that address A host group i
283. tion fairly fine con trol over when TCP sends packets Basically sock noflush is used to set a lock on the socket that prevents TCP from sending packets containing new data After sock noflush you can call sock fastwrite or other write functions The new data will not be sent until the socket is unlocked with a call to sock flush sock flushnext unlocks the socket but TCP does not send any data until the next write function is called 4 2 2 Time Out Settings There are many time out settings in TCP These are necessary because the TCP socket needs to be able to take meaningful actions when things take longer than expected For good performance it is also some times necessary for the socket to delay slightly some action that it could otherwise perform immediately The time out settings currently apply to all sockets they cannot be applied selectively because they are in the form of macro constants In general you can improve overall TCP performance by reducing some of the time out settings however there is a law of diminishing returns and you can also start to reduce overall efficiency What may be good settings for a local Ethernet connection may be very poor for an Internet connection Note that if you opti mize time out settings for a particular network environment you will need to document this so that your TCP IP Manual Vol 1 rabbit com 69 end users do not inadvertently use your application in the wrong
284. tly the same functions that han dle TCP socket I O e sock fastread e sock read e sock fastwrite e sock recv e sock getc e sock recv from e sock gets e sock recv init e sock preread e sock write e sock putc e udp close e sock puts e udp open Notice that there are three additional I O functions that are only available for use with UDP sockets sock recv sock recv from and sock recv init The status and control functions that are available for TCP sockets also work for UDP sockets with the exception of the open functions tcp listen andtcp open 3 7 2 Opening and Closing a UDP Socket udp open takes a remote IP address and a remote port number If thev are set to a specific value all incoming and outgoing packets are filtered on that value i e you talk only to the one remote address If the remote IP address is set to 1 the UDP socket receives packets from any valid remote address and outgoing packets are broadcast If the remote IP address is set to 0 no outgoing packets may be sent until a packet has been received This first packet completes the socket filling in the remote IP address and port number with the return address of the incoming packet Multiple sockets can be opened on the same local port with the remote address set to 0 to accept multiple incoming connections from separate remote hosts When you are done communicating on a socket that was started with a 0 IP address you can close it with sock
285. to cols TCP is used when a reliable stream oriented transport is required for data flowing between two hosts on a network UDP is a record oriented protocol which is used when lower overhead is more impor tant than reliability The acronym UDP is sometimes expanded as unreliable datagram protocol although in practice UDP is quite reliable especially over a local Ethernet LAN segment The Dynamic C TCP IP libraries implement TCP and UDP over IP Internet Protocol IP is a network layer protocol that in turn uses lower levels known as link layer protocols such as Ethernet and PPP Point to Point Protocol The link layer protocols depend on a physical layer such as 10BaseT for Ether net or asynchronous RS232 for PPP over serial In the other direction various protocols use TCP This includes the familiar protocols HTTP SMTP mail and FTP Other protocols use UDP DNS and SNMP to name a couple TCP handles a lot of messy details which are necessary to ensure reliable data flow in spite of possible deficiencies in the network such as lost or re ordered packets For example TCP will automatically retransmit data that was not acknowl edged by the peer within a reasonable time TCP also paces data transmission so that it does not overflow the peer s receive buffers which are always finite and does not overload intermediate nodes routers in the network UDP leaves all of these details to the application however UDP has some ben
286. to reduce this setting but you could increase it to about 100ms to cut down on tcp _tick overhead without materially affecting most applications TCP_MINRTO Prior to Dynamic C 9 01 this macro defaulted to 250 ms the default was changed to 10 ms This value specifies the actual minimum time between TCP retransmissions Reducing this will not affect perfor mance in a properly functioning network and may in fact worsen efficiency Only in a network that is dropping a high percentage of packets will this setting have any real effect On local Ethernet connections genuine packet drops will be practically non existent The most likely cause of delays is if a host CPU is tied up and unable to perform network processing On Internet connections setting a retransmit time shorter than the default value is just as likely to worsen the congestion which is causing packets to be dropped in the first place The only case where this value might be profitably reduced is the case of a point to point link where there is a lot of packet loss maybe because the RS232 wiring is routed near an industrial welder In this case any packet loss may be assumed to be because of noise or interference not because of router congestion In the Internet most packet loss is because of router congestion in which case there is nothing to be gained by reducing TCP_MINRTO Another reason for not reducing this setting is that modern TCP IP implementations only acknowledge ev
287. to the buffer RETURN VALUE 1 len is greater than the total socket receive buffer size hence this request could never be satis fied in one call 2 The socket is closed or closing but insufficient data is in the buffer to satisfy the request 3 len lt 0 or the socket parameter was invalid 0 Insufficient data is in the buffer to satisfy the request or Len was zero Try again later since the socket is still able to receive data from the peer len The len parameter is returned if there was sufficient data in the socket buffer to satisfy the request LIBRARY TCP LIB SEE ALSO sock fastread sock xfastread sock fastwrite sock xfastwrite sock aread sock awrite sock axwrite TCP IP Manual Vol 1 rabbit com 195 sock axwri te int sock_axwrite Cep Socket s long dp int len DESCRIPTION Write exactly len bytes to the socket or if that amount of data can not be written do not write anything This function is available starting with DC 7 30 It is identical to sock awrite except that the source buffer is in xmem Parameters s Pointer to a TCP socket dp Buffer containing data to write len Number of bytes to write to the socket buffer RETURN VALUE 1 len is greater than the total socket receive buffer size hence this request could never be satisfied in one call 2 The socket has been closed for further transmissions e g because sock close has already been called 3 len lt 0 or the sock
288. to the second Ethernet device or 0x03 to allow use of both devices USE PPP SERIAL This macro allows support of PPP over asynchronous serial It can be set to e 0x01 serial port A e 0x02 serial port B e 0x04 serial port C e 0x08 serial port D e 0x10 serial port E available on Rabbit 3000 and above e 0x20 serial port F available on Rabbit 3000 and above Or anv bitwise combination of these values Serial port C is the default but you may use any of the others Please note that if you use serial port A the programming port Dynamic C will not be able to communicate with the target You may also need to define other macros to allow correct functioning of the serial port hardware e g hardware flow control USE_PPPOE This macro allows support of PPP over Ethernet It is set in the same way as USE_ ETHERNET The bitmask indicates which Ethernet devices are to be used for PPP over Ethernet USE_WIFI This macro allows support of Wi Fi It can be set to 0x01 or 0x02 TCP IP Manual Vol 1 rabbit com 5 2 1 2 1 Link Layer Drivers The USE configuration macros described in Interface Selection Macros on page 5 cause the appropriate link layer drivers to be included If none of the USE macros are defined and the macro PKTDRV is also not defined realtek 1 ib will be used Some board types cause a driver other than realtek lib to be used e g if the board is the RCM3200 or the RCM3210 the packet dri
289. ts These functions change the status of the socket or its I O buffer e udp close e udp extopen e udp open 3 6 2 Status Function for UDP Sockets These functions return useful information about the status of either a socket or its I O buffers e sock bytesready e sock dataready 9 sock berg e sock rbsize e sock rbused e udp peek For a UDP socket sock bvtesreadv returns the number of bytes in the next datagram in the socket buffer or 1 if no datagrams are waiting Note that a return of 0 is valid since a datagram can have 0 bytes of data 3 6 3 I O Functions for UDP Sockets These functions handle datagram at a time I O e udp recy e udp recvfrom e udp send e udp_sendto The write function udp_sendto allows the remote IP address and port number to be specified The read function udp recvfrom identifies the IP address and port number of the host that sent the datagram There is no longer a UDP read function that blocks until data is ready 50 rabbit com TCP and UDP Socket Interface 3 7 UDP Socket Functions pre 7 05 This interface is basically the TCP socket interface with some additional functions for simulating a record service Some of the TCP socket functions work differently for UDP because of its connectionless state The descriptions for the applicable functions detail these differences 3 7 1 I O Functions for UDP Sockets Prior to Dynamic C 7 05 the functions that handle UDP socket I O are mos
290. tting up the TCP IP stack and opening the UDP socket The sample program Samples tcpip udp udp_echo_dh c shows how to implement a simple UDP echo server using the technique described in this section 4 4 Tips and Tricks for TCP Applications This section contains miscellaneous suggestions for getting the most out of your TCP based applications Application design requirements that affect TCP performance include e the responsiveness and throughput requirements of the application e how often tcp_tick can be called e whether socket is used in ASCII or binary mode e whether multitasking or big loop programming style The list of application types at the beginning of this chapter is used as a basis for discussion Your applica tion may neatly fit into one of these categories or it may be a combination of several In either case you should try to follow the programming guidelines unless you are fairly experienced with the Dynamic C TCP IP libraries 74 rabbit com Optimizing TCP IP Performance 4 4 1 Bulk Loader Applications This type of application is idle from the TCP IP point of view most of the time but this is punctuated by periods of intensive data transfer Applications which exhibit this characteristic include data loggers and file transfer agents e g FTP server or client Sending email via SMTP also comes under this category The main application requirement is good utilization of the available bandwidth i e highest t
291. udp bypass arp 228 rabbit com TCP IP Manual Vol 1 sock set tos void sock set tos void s byte tos DESCRIPTION Set the IP Type Of Service field in outgoing packets for this socket The given TOS will be in effect until the socket is closed When a socket is opened or re opened the TOS will be set to the default TCP TOS or UDP TOS as appropriate If not overridden the defaults are zero IPTOS DEFAULT in both cases PARAMETERS s Pointer to open TCP or UDP socket tos Type Of Service This should be one of the following values e IPTOS DEFAULT Default service e IPTOS CHEAP Minimize monetary cost e IPTOS RELIABLE Maximize reliability e IPTOS CAPACIOUS Maximize throughput e IPTOS FAST Minimize delay e IPTOS SECURE Maximize security Other value may be used since TOS is just a number between 0 and 255 but this should only be done for experimental purposes LIBRARY NET LIB SEE ALSO sock set ttl TCP IP Manual Vol 1 rabbit com 229 sock set ttl void sock_set_ttl void s byte ttl DESCRIPTION Set the IP Time To Live field in outgoing packets for this socket The given TTL will be in effect until the socket is closed When a socket is opened or re opened the TTL will be set to the default TCP TTL or UDP TTL as appropriate If not overridden the defaults are 64 in both cases PARAMETERS s Pointer to open TCP or UDP socket
292. ult to MAX TCP SOCKET BUFFERS TOTAL UDP SOCKET BUFFERS which is MAX UDP SOCKET BUFFERS 1 if there are DNS lookups Buffers xalloc d for socket I O should be accounted for in MAX SOCKET LOCKS 3 12 1 1 Interrupt Driven or DMA Driven Network Interface s The information in this section applies to TCP IP applications which use interrupt driven or DMA driven network interfaces Interrupt driven and DMA driven network interface s include Rabbit s built in Ethernet as well as WiFi and serial PPP interfaces Note that DMA driven network interfaces are also interrupt driven because they generate an interrupt when block transfers are completed It is strongly recommended that all uC OS2 II tasks including idle and statistics tasks should use 4K stacks This recommendation is made because a network related interrupt may occur when any task is running and the network interface ISRs can be stack intensive Note that in addition to saving the CPU s entire registers state the potentially long running network ISRs may re enable interrupts to reduce the latency of other same interrupt priority level ISRs Although not recommended a severely memory constrained TCP IP application that is otherwise not stack intensive may be able to function adequately with 2K stacks for all tasks Such memory constrained TCP IP applications use of 2K stacks should be thoroughly tested with heavy emphasis on stress lo
293. up calls were made on that group However note that this function will not actually leave a group for which there are UDP sock ets However when those UDP sockets close the group will be left Note that this function is called automatically when a multicast UDP socket is closed PARAMETER iface Interface on which to leave the group Use one of the definitions e IF ETHO e IF ETHI e IF WIFIO e IF DEFAULT ipaddr Multicast group to leave RETURN VALUE 0 Success 1 Failure e g ipaddr is not a multicast address LIBRARY IGMP LIB 164 rabbit com TCP IP Manual Vol 1 ntohl longword ntohl longword value DESCRIPTION Converts network ordered long word to host ordered long word This function is necessary if you are implementing standard internet protocols because the Rabbit does not use the standard for network byte ordering The network orders bytes with the most significant byte first and the least significant byte last On the Rabbit the bytes are in the opposite order PARAMETERS value Network ordered long word RETURN VALUE Network ordered long word in host ordered format e g ntohl 0x44332211 returns 0x11223344 LIBRARY NET LIB Prior to DC 7 05 this was DCRTCP LIB SEE ALSO tons ntohs htonl TCP IP Manual Vol 1 rabbit com 165 ntohs word ntohs word value DESCRIPTION Converts network ordered word to host ordered word This function
294. ver library asix libwillreplace realtek lib CH The following table tells which link layer drivers will be used when a USE macro is defined to a value greater than zero Table 2 1 Libraries Included When USE_ Macro Value gt Zero Configuration Macro Realtek lib Ppp lib Ppplink lib Pppoe lib WiFiG lib USE ETHERNET yes no no no no USE PPP SERIAL no yes yes no no USE PPPOE yes yes no yes no USE WIE no no no no yes ora substitute packet driver library based on board type As the table reveals using PPP over Ethernet causes realtek lib ppp lib and pppoe lib to be included Multiple drivers may also be included by defining multiple interfaces The following macros are defined for applications to perform conditional compilation that depends on the drivers actually included e USING ETHERNET e USING PPP SERIAL e USING PPPOE e USING WIF e USING WIFIG These macros are alwavs defined but will have a zero value if the driver was not included Thus the conditional compilation should use the if operator not tti fdef For example tif USING PPP SERIAL Do something special for PPP over serial tendif The value assigned to the USING macro is the number of hardware interfaces of that type that are available On a Rabbit 2000 board USING PPP SERIAL will be defined
295. w many sockets you can allocate but they do limit how many sockets you can successfully use Each socket requires some resources which are not automatically available just because you declare a tcp Socket structure The additional resources are receive transmit buffers which are allocated in extended memory and also socket semaphores if you are using LC OS II The relevant macros are MAX TCP SOCKET BUFFERS Determines the maximum number of TCP sockets with preallocated buffers The default is 4 A buffer is tied to a socket with the first call to tcp_open ortcp listen Ifyou use tcp_extopen ortcp extlisten then these buffer resources are not used up but only if you allocate your own buffers using xalloc MAX UDP SOCKET BUFFERS Determines the maximum number of UDP sockets with preallocated buffers The default is 0 A buffer is tied to a socket with the first call to udp open If you use udp_extopen then these buffer resources are not used up but only if you allocate your own buffers using xalloc Note that DNS does not need a UDP socket buffer since it manages its own buffer Prior to version 7 30 DHCP and TFTP LIB each need one UDP socket buffer Starting with version 7 30 DHCP manages its own socket buffers Prior to Dynamic C version 7 05 MAX SOCKETS defined the number of sockets that could be allocated not including the socket for DNS lookups If you use libraries such as HTTP LIB or FTP SERVER LIB
296. wait olosed iss EKS 248 router_printall sesse ske gese SE AE 198 sock wait established 249 S sock Walt MPU sesse eie 251 setdomainname sdocsccedesssnecsasisnnesiens 200 sock EE OE Ee Fe 250 E E 201 sock_writable ass ne ski Ede NG 252 sethostname APE ER ON 202 SOCK WES oase RE iN See 253 sock_abort ed ER es ee 203 sock xfastread iese ees ee ee 254 BOCK VEE EG 204 soek _xfastwrite ss Sak 255 SOCK ER N ERA 205 sock yield osse EE 256 Sock GW iG OO N 206 SOCKETT sikka ei jakkorda 212 BEE Nee EKEN 207 ee ee EE ba e 243 sock _axwrite ee es eN GE de 208 T sock_bytesready ege 209 te EE 257 SOCKS COGS eebe deeg 210 tep_config eege 258 soek dataready ieke dese 211 a E 259 T ak eie GR N N 213 tep de es AO OE N 260 sock established sis Ede 214 a BE 261 sock_fastread EE 215 te EE 262 sock fastwrite ccccsscecessseeees 216 ED OER eds ee Gee be pie 264 ae Ed EE EE 217 tep_reservepotrt os Gees ira See ie De 266 sock flushnext EEN 218 PO EE E AE 267 yt di ii arr a da dl 219 U BOCK de AR EE OR 220 udp_bypass_arp asses Se RSA 268 sock_iface ee RE di si 221 udp_celose sai Ee ER 269 SOCK ML lii N N De 222 udp_extopen ese oe GER Geren 270 sock init OF E sesse kke NEER 223 MAD DAE isa ee ee ee de 272 A E ta L 224 Gdp peek sireisas 274 sock Metteg 226 UdP TEV enee e 275 Sock GION RE OE qaddu 227 udp_recvfrom gedoe gend 276 sock_preread erer 228 dp SEMA enee 277 sock pute ON 229 udp_sendto eegen 278 SOCK UNG eege 230 WA _waitope
297. work channel 1 13 mac addr bss addr BSS ID the AP s MAC address tiintl6 bes caps reserved uint8 wpa infolWLN WPAIE SIZE reserved uint8 erp info reserved uintl6 rates reserved uint16 rates basic reserved uintl6 atim reserved int tx tate max transmission rate in 100 kbps int rx signal received signal strength wifi wln scan bss See the WiFiScan c sample program for an example of using IFS WIFI SCAN TCP IP Manual Vol 1 rabbit com 139 ifconfig cont d IFG WIFI STATUS Get current MAC status The IFG WIFI STATUS command returns the current Wi Fi MAC status into the user supplied buffer or data structure area The buffer must be large enough to hold the entire wln status structure size can be checked with sizeof wln status The win status structure has the following definition typedef struct wln state state Association state see below uint8 ssidIWLN SSID SIZE Current service set ID SSID int ssid len Service set ID length int channel Current channel 1 13 mac_addr bss_addr BSS ID AP MAC address uint16 bas caps reserved uint8 wpa infolWLN WPAIE SIZE reserved uint32 authen reserved uint32 encrypt reserved int tx rate transmit rate in 100 kbps int rx rate Last received rate in 100 kbps int rx signal Last received signal strength
298. y closed before continuing call tcp_tick with the socket structure s address When tcp tick returns zero then the socket is completely closed Please note that if there is data left to be read on the socket the socket will not completely close Call sock abort to cancel an open connection This function will cause a TCP reset to be sent to the other end and all future packets received on this connection will be ignored For performance reasons data may not be immediately sent from a socket to its destination If your appli cation requires the data to be sent immediately you can call sock flush This function will try sending any pending data immediately If you know ahead of time that data needs to be sent immediately 46 rabbit com TCP and UDP Socket Interface call sock flushnext on the socket This function will cause the next set of data written to the socket to be sent immediately and is more efficient than sock flush 3 4 2 Status Functions for TCP Sockets These functions return useful information about the status of either a socket or its I O buffers e sock alive e sock rbsize e sock bytesready e sock rbused e sock dataready e sock tbleft e sock established e sock thsaze e sock iface e sock tbused e sock rbleft tcp tick tcp tick is the daemon that drives the TCP IP stack but it also returns status information When you supply tcp_tick witha pointer toa tcp Socket a structure that identifies
299. y from the passphrase and the SSID That is all Wi Fi devices including Access Points that are configured with the same passphrase and the same SSID will generate the same pre shared key IMPORTANT When statically configuring a Rabbit Wi Fi device you should specify either the pre shared key with WIFI PSK HEX or the passphrase with WIFI PSK PASSPHRASE but NOT BOTH If you do specify both then WIFI PSK HEX will take precedence that is if you have a correct passphrase but an incorrect pre shared key then the incorrect pre shared key will be used 2 4 1 9 Ad hoc WPA TKIP or WPA2 CCMP Encryption Configuration The Wi Fi driver does not support the use of ad hoc mode with WPA TKIP or WPA2 CCMP encryption Ad hoc mode with encryption is not well supported by Wi Fi devices in general There are multiple standards for supporting encryption on ad hoc mode but none of them are widely implemented If you desire encryption for your Wi Fi network then we strongly recommend using infrastructure mode with one or more access points 2 4 2 Wi Fi Runtime Configuration There are two runtime functions for Wi Fi configuration 2 4 2 1 Runtime Configuration Starting with Dynamic C 10 40 Dynamic C 10 40 introduces an expanded ifconfig function that includes Wi Fi configuration parameters All Wi Fi programs should switch to using ifconfig for configuring Wi Fi at runtime Dynamic C 10 54 introduces ifconf
300. y intended for internal use by the ARP library although advanced ap plications could also use it Most applications should not need to call this function directly PARAMETERS ath hwa iface flags router used Handle for the entry Hardware Ethernet address or NULL Pass NULL if the current hardware address is not to be changed Interface to use IF_DEFAULT to use default or not change current set ting Flags for entry one or more of the following values OR d together e ATE PERMANENT permanent entry e ATE RESOLVING initiate network resolve for this entry hwa is ignored if this flag is set e ATE RESOLV e ATE ROUTER ENT this is a router entry T D this entry now resolved e ATE FLUSH mark this entry for flush e ATE VOLATILE set short timeout for this entry e ATE ROUTER HOP this entry uses the specified router as the first hop hwa ignored e ATE REDIRECTED this entry redirected by ICMP Only one of ATE ROUTER ENT or ATE ROUTER HOP should be set For either of these the next parameter indicates the router table entry to use Only one of ATE RESOLVING or ATE RESOLVED should be set Router table entry Only used if one of ATE ROUTER ENT or ATE ROUTER HOP is set in the flags parameter TCP IP Manual Vol 1 rabbit com
301. y not be fully started even if requested to be up initially PPP interfaces can take a substantial amount of time to come up especially if modem dial out is in use You can wait for a particular interface to come up by polling the interface status using ifstatus or preferably ifpending 2 2 Interface Configuration Prior to Dynamic C version 7 30 only a single network interface was supported Configuration of the interface was performed by defining a set of macros such as MY IP ADDRESS l as well as by calling various configuration functions such as sethostid With Dynamic C 7 30 s support of multiple interfaces the macro style configuration becomes impractical and the configuration functions generally would require an additional parameter the interface number Version 7 30 implements a slightly different method of configuration but maintains compatibility with the old style of configuration for simple applications that require only a single interface It is recommended that new applications use the new style of configuration even if multiple interface support is not required This will ease the integration of future Dynamic C upgrades 2 2 1 Configuration Overview To run the TCP IP stack a host i e the controller board needs to know its unique home IP address for each interface Interfaces that connect to broadcast networks e g Ethernet or Wi Fi must also have a netmask assigned The combination of IP address and
302. y the data field if desired See the definition of this struct in NET LIB for details opt DHCP option number DHCP VN or 0 for the boot file name len length of option data in bytes data pointer to data for this option Read only The callback is only invoked for options which were requested and which were not han dled internally such as DHCP_VN_SUBNET The return value from the callback should be zero for future compatibility The callback should not make any long computations blocking calls or call any other TCP IP functions since it would delay the main applica tion If uC OS is in use it should also be re entrant and definitely not call any tcp ip func tions Note that the following options are always retrieved and MUST NOT be provided in the options list e All DHCP protocol options 50 61 e DHCP VN SUBNET e DHCP VN TIMEOFF The other options are only forbidden if DHCP NUM ROUTERS etc is defined non zero e DHCP VN ROUTER DHCP VN DNS e DHCP VN SMTPSRV D D HCP VN NTPSRV HCP VN COOKIE IFG DHCP OPTIONS Get DHCP custom options int char IFG DHCP INFO Get DHCP information or NULL if not qualified DHCPInfo rabbit com TCP IP Manual Vol 1 ifconfig cont d PARAMETER IDENTIFIERS FOR PPP The following parameter identifiers are for PPP interfaces only You will get a runtime error non zero return code i
303. you must provide enough sockets in MAX SOCKETS for them also In Dynamic C 7 05 and later if MAX SOCKETS is defined in an application program MAX TCP _SOCKET BUFFERS will be assigned the value of MAX SOCKETS If you are using L C OS II then there is a further macro which must be set to the correct value MAX SOCKET LOCKS This must count every socket TCP plus UDP including those used internally by the libraries If you cannot calculate this exactly then it is best to err on the side of caution by overesti mating The actual socket semaphore structure is not all that big less than 70 bytes The default value for MAX SOCKET LOCKS is the sum of MAX TCP SOCKET BUFFERS and MAX UDP SOCKET BUFFERS plus 1 if DNS is being used TCP IP Manual Vol 1 rabbit com 43 3 2 2 Socket Buffer Sizes Starting with Dynamic C version 7 05 TCP and UDP I O buffers are sized separately using TCP BUF SIZE Determines the TCP buffer size Defaults to 4096 bytes UDP BUF SIZE Determines the UDP buffer size Defaults to 4096 bytes Compatibility is maintained with earlier versions of Dynamic C If SOCK BUF SIZE is defined TCP BUF SIZE and UDP BUF SIZE will be assigned the value of SOCK BUF SIZE If SOCK BUF SIZE is not defined but tcp MaxBufSize is then TCP BUF SIZE and UDP BUF SIZE will be assigned the value of tcp MaxBufSize 2

Dynamic C TCP/IP User`s Manual Volume I

Contents

Download Pdf Manuals

Related Search

Related Contents