Home

Treck TCP/IP User Manual

1. 6 82 Bile System IMAGE netos ea nep eor e rE EEEE o OnE SETER 6 83 tETftpdinit RS ite tenere eret wih aeolian aon nares 6 83 th itp SHE XEC WIG 5230 oe pereo D PH eU Ud reet 6 84 tf Pit pAUSer Start M eee 6 85 CEM AAU SEES COP ioni ro tier Pre E ET 6 87 File system interface eee eese eee eee eee eese seen sensi tn stant tn stas ta sense tn siss 6 88 Entry points from the FTP server to the file system esses 6 88 Entry points from the FTP client to the file system ssesss 6 89 Entry points from the TFTP server to the file system 6 89 ttESChangeDIE s score extend eere cited ects ove Ce ited en nes 6 90 ttE S ChanseParentDIr 5er HERE eee REED POUR ADDERE R 6 91 io CLOSED C 6 92 2004 Treck Incorporated tHE S OI CS ESS Bu EP A RS ER SET 6 93 tfESDel teble itte te Eo eroe e EE Eee eta tes Yo ee Rer 6 94 tEESEl shEie un eccentric en o ro eec ed 6 95 ttESGet NextDIFEDGy tiroteo oer e ERE Fe pne desea 6 96 t PSGetUmqueFileN tie uienic caneret siete Eon unanime 6 97 LES Get W fordert Dir gc E tels 6 98 tESMAKGDIE 2 n e recen tre e E e tte ed 6 99 ES poeta Ae oan RI yep ist o en ir mt 6 100 HE S Opeth al T C O 6 101 tfFSReadFile iii 6 102 tfESReadEIleRecotd ht tre teet iere 6 103 TFSREMOVEDIT RERO RC 6 105 tfESRenameFile 5 ertet E
2. Complete Internet Solutions Technical Support 5041 Lamart Drive 240 Riverside California 92507 Phone 909 787 7056 Fax 909 787 8803 Corporate Headquarters Treck Inc 431 Ohio Pike Suite 210 North Cincinnati Ohio 45255 Phone 513 528 5732 Fax 513 528 5740 www treck com Contents Introduction to TCRP IP ccccccsssscscssscccsscssssssscsscsccscesseeesees Lol Short Background of the Internet nee 1 3 What isa Protocol enini ioni ER REE 1 4 The TCP IP Protocol Stack 2c eie rti e eee 1 5 The Ethernet Protocol sise avis nine eere cete edes 1 6 Twisted Pair Ethernet teer rct eet tie e Rs 1 10 Collision Detect and Recovery iicaounne eicere 1 12 Ethernet Capacity in aeter mend n ER aera 1 12 Ethernet Hardware Addressing ieissar soiis 1 13 Special Bits of an Ethernet Address sse 1 15 Obtaining an Ethernet Address Block sees 1 15 Ethernet Frame Formats rien eode oda e eco et 1 16 The Address Resolution Protocol ARP sens 1 17 ARP Implementation cic ittis herr ee hne ete e se e Cas 1 18 ARP Encapsulation and Identification eene 1 18 ARP Protocol Format 4 inte eere ei e ede ee 1 20 Big Endian Little Endian nn 1 22 The Point to Point Protocol PPP aeree eene eee eere nennen 1 24 Link Control Protocol eee wet ne tee e d 1 25 PPP Encapsulation ect neue dea tee aa 1 25 The Proto
3. Datagram Header Datagram Data Area Fig 1 29 General form of an IP datagram IP specifies the header format including the source and destination IP addresses IP does not specify the format of the data area it can be used to transport arbitrary data 1 38 2004 Treck Incorporated Introduction to TCP IP Datagram Format Now that we have described the general layout of an IP datagram we can look at the contents in more detail Figure 1 30 shows the arrangement fields in a datagram 2222 2233 1111 2222 6789 0123 4567 8901 Total Length 0000 0000 0011 1111 0123 4567 8901 2345 VER HLEN TOS Identification Total Length Protocol Header Checksum Source IP Address Destination IP Address IP Options If Any Followed by DATA Fig 1 30 Internet Datagram Format Basic Unit of Transfer in a TCP IP Internet Because datagram processing occurs in software the contents and format are not restricted by any hardware For instance the first 4 bit field in a datagram VER contains the version of the IP protocol that was used to create the datagram It is used to verify that the sender receiver and any routers in between them agree on the format of the datagram All IP software is required to check the version field before processing a datagram to ensure it matches the format the software expects If standards change machines will reject datagrams with protocol v
4. MSG WAITALL MSG OOB or 0 2004 Treck Incorporated Returns Value gt 0 TM SOCKET ERROR Error codes Value TM EWOULDBLOCK TM BINVAL TM ENOBUFS TM EBADF TM EMSGSIZE TM EHOSTUNREACH Programmer s Reference Meaning Number of bytes transmitted queued Treck will free the user buffers An error occurred The user can retrieve the error code with the tfGetSocketError socketDescriptor Meaning Not enough room to queue the data in the socket send queue User still owns his buffer and is responsible for re sending later on One of the parameters is bad i e userBufferPtr or userDataPtr or userDataLength or user free function is 0 userDataLength is 1 or flags has a bit that is not allowed Not enough memory to allocate the Treck headers The socket descriptor is invalid The data length was bigger than the send queue No route to host 5 113 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfZeroCopyUserBufferSendTo include lt trsocket h gt nt tfZeroCopyUserBufferSendTo nt socketDescriptor har userBufferPtr har userDataPtr nt userDataLength tUserFreeFuncPtr userFreer nt flags onst struct sockaddr toAddressPtr nt toAddressLength unction He Q HT EH Q Q H RT Function description Data Socket Send Allows the user to send data on a socket directly from user owned data buffers without having to copy the data Upon return from this routine the user
5. eere eee ee eee eene eese enenatis tassa snn 2 6 SOCKEL AEE tetas nto eC QU EC 2 6 junge 2 6 MG SUSU as ER 2 6 Ere p ER TE A 2 6 onu eas 2 7 2l ues cbesiavats 2 7 OI PP EE 2 7 png 2 7 TECVITOLI a eset Deae roba estes ite tele idet et T tee Ee 2 7 dil 2 Example Code mM 2 8 UDP Cle a entendre E iets ceeds 2 8 ID IV 2 10 CPC Bell RE EE EE EC 2 12 2004 Treck Incorporated TOP Edi MS 2 14 Treck SVSECHIS Gone ER enti REOR Perl C vifa dd sisse cT Treck Real Time TCP IP Systems eee eese eee tentent ntnnnn 3 3 L cking Cn 3 3 Ie dcum 3 1 Timet Syste sens nent estrada telat E E EEE EEEE cea 3 8 Integrating Treck Real Time Protocols Into Your Environment 4 1 Integrating Treck Real Time Protocols Into Your Environment ss 4 3 Step 1 Determining How to Use the Protocols in Your System 4 4 Do you want to have Treck run as its own task or in the context of other tasks asa shared Mbtary ient o dp inerte 4 4 Step 2 Setting TRSYSTEM H for Various Compile Time Switches 4 6 Performance Macros ccccccscessessseeseccecseccecsececenseceaeseeesseeereeeeseeeeneseneeess 4 6 TM BYPASS ETHER EL arietes tee e roti rer o rene 4 6 TMEJP ERAGMENT nie
6. int errorCode fe initialization lqmEnabledStatus 0 linkBadStatus 0 linkQualityMonitorRegisteredStatus 0 start Treck errorCode tfStartTreck initialize PPP 7 112 2004 Treck Incorporated Optional Protocols wu myLinkQualityMonitor linkLayerHandle tfUseAsyncPpp ttUserLnkNotifyFuncPtr myPppLinkNotify add the PPP interface interfaceHandle tfAddInterface name of the device NMYDEVICE 001 Link Layer to use linkLayerHandle initialize LOM with a 3 second retransmission timer errorCode tfUsePppLqm interfaceHandle ttUser32Bit 3000 set PPP options for negotiation errorCode tfPppSetOption interfaceHandle open the PPP interface errorCode tfOpenInterface interfaceHandle main polling loop while 1 if lqmEnabledStatus 1 if linkQualityMonitorRegisteredStatus 0 linkQualityMonitorRegisteredStatus 1 after LOM is enabled register the link quality monitor errorCode tfLqmRegisterMonitor interfaceHandle ttLamMonitorFuncPtr LOM HYSTERESIS MAX FAILURES LOM HYSTERESIS SAMPLES if errorCode TM ENOERROR C fSPrintF errorMsgBuf tfLqmRegisterMonitor failed tfStrError errorCode 7 113 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKer
7. B3D1 This is the interesting part of what the checksum does Once the value has been calculated the system takes the ones complement of that result The ones complement is a function that takes the value of the result in binary and essentially switches the value If the binary unit has a value of 1 it becomes 0 And if the binary unit has a value of 0 it becomes 1 That value then becomes the value for the checksum field 1 42 2004 Treck Incorporated Introduction to TCP IP The receiver also uses the ones complement function when checking the information that was received After the value is calculated and all the necessary carries are done the system then takes the ones complement of the number This number will always be equal to zero To illustrate this point Computing 4500 000E 0001 0000 FF11 B3D1 Checksum Field 0102 0304 0102 0305 1FFFE Our result is larger than 16 bits so we must perform the carry function 1FFFE 0001 FFFF Now we must perform the ones complement FFFF 0000 When the checksum is configured as we mentioned earlier the value of the checksum is set to 0 Then after the addition is done the result is then sent to the receiver in the checksum field The receiver then calculates the data for itself The result that the receiver gets should be equal to zero If this is the case th
8. PEE 6 5 ETAPA GI ISTE SUIS NR ER ent 6 6 tE PinpOpenStatt entere ten teet art eir een ee Pede de eerte dues 6 8 DNS Resolver qe 6 10 Ib reato E 6 10 TInitialization functolls Len leider eese er TEPES a 6 10 User Interface D 6 10 Nou Blocking MOdE 5 ie rope beret oras UPPER OUTRE DR 6 11 Mail Exchanger MX Records eite I ieseana 6 11 db inibi PEE 6 13 t DnsGetHostAddr sise dense wt een ere tede rette 6 14 t DnsGetHostByNAme arre Dro dr nine IE pales 6 15 tiDnsGetMailHst e 6 16 ttDnsGetNextMAallEloSL utet tent rr n retire ERE RE eens tienne 6 17 tEDnsSet Opto reines vite ede tee reete ede te eeu cua 6 18 EDnSSel SeEVel Le deep rr DO eret tene eds 6 19 FTPD Application Program Interface esses eren tnnnne 6 20 MVS e Mem P md 6 20 User Interface oen ce trier nc ota cd units 6 20 File System Interface from the FTP server s 6 21 dgio lU do Cuir T noverek pE 6 23 ECA epigr EET 6 24 tHE pdU Set Stop eerte etre nere re use itr ere recte eee eee det ed dua 6 27 FTP Client Application Program Interface nr 6 28 User Interface D E 6 28 Bale Sy Sten Teta CS ner terr ioco tre PIECE ex tee RET lesse ius 6 30 FADOT DD 6 33 EECA OG 2s rete orate ttu te e nte iba te esteso elise aie 6 34 thE tp sii 2355 0 ty 6 36 HELEN OS SR TEE 6 37 iP tp Con
9. Requested action aborted local error in processing Requested file action aborted exceed storage allocation Request action not taken insufficient storage space in system Requested file action not taken file unavailable Requested action not taken file name not allowed Syntax error command unrecognized Syntax error in parameters or arguments Command not implemented for that parameter Service not available closing TELNET connection Not logged in Treck Real Time TCP IP User s Manual tfFtpCdup include lt trsocket h gt int tfFtpCdup ttUserFtpHandle ftpSessionPtr Function description Changes directory on the remote file system to the current directory s parent directory Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK TM EACCES TM ENOTCONN TM BINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP NOTLOGIN TM FTP NAVAIL TM FTP NOCMD This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Not logged in Requested action not taken file unavailable Command not implement
10. Returns The PPP Client link layer handle or NULL if there is an error 7 100 2004 Treck Incorporated Optional Protocols tfUseAsyncServerPpp include lt trsocket h gt ttUserLinkLayer tfUseAsyncServerPpp ttUserLnkNotifyFuncPtr linkNotifyFuncPtr Function Description This function is used to initialize the asynchronous PPP server link layer When link up or link down events occur the stack will call the function passed in If you do not need notification of events then the parameter should be set to TM LNK NOTIFY FUNC NULL PTR Your prototype for your notification function should look like this void myPppNotifyFunction ttUserInterface interfaceHandle int flags This function is called with the interface handle and a flag The flag is set to one of the following TM LL OPEN COMPLETE PPP Device is ready to accept data from the user TM LL CLOSE STARTED PPP Device has started to close this link TM LL CLOSE COMPLETE PPP Device has closed TM LL LCP UP LCP negotiation has completed TM LL PAP UP PAP authentication has completed TM LL CHAP UP CHAP authentication has completed TM LL LOM UP LOM is enabled on the link TM LL LOM DISABLED LOM is disabled on the link TM LL LOM LINK BAD Link quality is bad user recovery should be attempted These events may be used to monitor the status of the PPP connection The PPP connection should not be used before a TM LL OPEN COMPLETE event is r
11. Task Suspend and Resume uC OS does implement counting semaphores so all we need to do here is create a mapping between Treck semaphores and uC OS semaphores uC OS sema phores are pointers to an OS EVENT type and should be stored in the genVoidParmPtr portion of the ttUserGenericUnion data type To create a counting semaphore we simply call OSSemCreate 0 This creates a counting semaphore that is initialized to zero All counting semaphores that Treck uses must be initialized to zero To pend on a counting semaphore we simply call OSSemPend with a sema phore that was created To post on a counting semaphore we simply call OSSemPost with a semaphore that was created tfKernelTaskYield does not need to do anything with uC OS because uC OS is fully preemptive and every task has a unique priority This function should just be a stub function B 4 2004 Treck Incorporated RTOS Notes ISR Interface uC OS does not have anyway to install Interrupt Service Routines We have put a routine in the uC OS ports that we supply called OSInstallISR This function is NOT supplied with uC OS This function is very processor specific If you are not using a Treck port of uC OS but are using a Treck device driver then you should add this function for your processor Note that all ISR routines that call Treck or uC OS must call OSIntEnter upon entry and OS ntExit upon leaving Since uC OS does not have event flags and it is okay to post on
12. inet addr 255 255 255 0 0 1 Note tfConfigInterface is deprecated for the first multihome Please use tfOpenInterface for the first configuration on an interface 5 164 2004 Treck Incorporated Programmer s Reference DHCP or BOOTP configuration tfOpenInterface with a TM DEV IP DHCP respectively TM_DEV_IP_BOOTP flag will send a DHCP respectively BOOTP request to a DHCP BOOTP server and will return with a TM_EINPROGRESS errorCode Note that tfUseDhcp respectively tfUseBootp needs to have been called prior to calling tfOpenInterface otherwise the call will fail with error code TM EPERM An example of a configuration using the DHCP protocol would be errorCode tfOpenInterface myInterfaceHandle ttUserIpAddress 0 ttUserIpAddress 0 TM_DEV_IP_DHCP 1 Checking on completion of DHCP or BOOTP configuration Synchronous check The user can make multiple calls to tfOpenInterface to determine when the configuration has completed Additional calls to tfOpenInterface will return TM EALREADY as long as the BOOTP DHCP server has not replied tfOpenInterface will return TM ENOERROR if the BOOTP DHCP server has replied and the configuration has completed e Asynchronous check To avoid this synchronous poll the user can provide a user call back function to tfUseDhcp respectively tfUseBootp which will be called upon completion of tfOpenInterface See tfUseDhcp respectively tfUseBootp for
13. ttUserInterface interfaceHandle int optionName void TM FAR optionValuePtr int optionLength Function Description Configure SLIP options OptionValuePtr points to a variable of type as described below OptionLenth contains the sizeof that variable The only option supported is TM SLIP OPT SEND BUF SIZE optionName TM SLIP OPT SEND BUF SIZE Description Length of data buffered by the SLIP link layer but not beyond the end of a packet before the device driver send function is called Default 1 byte Data Type unsigned short Parameters Parameter Description interfaceHandle Interface handle of the SLIP interface we want to set the option on optionName The option to set See above optionValuePtr The pointer to a user variable into which the option value is set User variable is of data type described above optionLength Size of the user variable which is the size of the option data type 5 205 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value 0 TM_ENOBUFS TM EINVAL TM EPERM TM EPROTONOSUPPORT 5 206 2004 Treck Incorporated Meaning Success Insufficient memory to complete operation Invalid option length for option or invalid option value for option Device interface is not a SLIP interface Option name not supported Programmer s Reference tfUseSlip include lt trsocket h gt ttUserLinkLayer tfUseSlip void i Function
14. 2 Fig 1 39 Sliding Window Protocol The first half of this illustration shows a sliding window protocol with an eight packet window The second part of the illustration shows the window sliding so that packet 9 can be sent when an acknowledgement has been received for packet 1 Remember Only unacknowledged packets are retransmitted When we say a packet is unacknowledged it means the packet has been transmitted but no acknowledgement has been received Technically the number of packets that can be unacknowledged at any given time is constrained to the window size and is limited to a small fixed number For example as in our illustration a window that has the size of eight the sender has permission to transmit 8 packets before it receives an acknowledgement Once the sender has received an acknowledgement for the first packet the window essentially slides and sends the next packet The window continues to slide as long as acknowledgements are received 1 55 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The performance of sliding window protocols depends on the window size and the speed at which the network accepts packets In our next illustration you can see an operation of a sliding window protocol when sending three packets Note that the sender transmits all the packets before receiving any acknowledgments With a window size of a sliding window protocol is the same as our simple positive ac
15. 3 2 Register CHAP authenticate function errorCode tfChapRegisterAuthenticate interfaceHandle myChapAuthenticate assert errorCode TM ENOERROR 3 2 Register MS CHAP authenticate function ifdef TM USE PPP MSCHAP errorCode tfMsChapRegisterAuthenticate interfaceHandle myMsChapAuthenticate assert errorCode TM ENOERROR dendif TM USE PPP MSCHAP Open the interface errorCode tfOpenInterface interfaceHandle ifIPAddr mask configFlags 7 106 2004 Treck Incorporated Optional Protocols scatteredBufferCount int myPapAuthenticate char username char password 1 search authenticator s database to get the password of this username if the password matches return 1 else password doesn t match return 0 j char myChapAuthenticate char username 1 search authenticator s database to get the password of this username return the password pointer j ifdef TM USE PPP MSCHAP char myMsChapAuthenticate char username int lenPtr 1 search authenticator s database to get the password of this username calculate the UNICODE password length in octets and put the value in lenPtr return the password pointer endif TM USE PPP MSCHAP Peer Part linkLayerHandle tfUseAsyncPpp ttLnkNotifyFuncPtr tfPppLinkNotify interfaceHandle tfUseXxxDriver TEST linkLayerHandle amp errorCode 1 Peer allows the authenticator to set
16. Setup Ctrl connection to FTP server B ftpHandleB setupFtpCtr1 192 168 1 200 Set FTP session A operating in passive mode void tfFtpTurnPasv ftpHandleA TM FTP PASSIVE MODE ON STOR file will be transferred from server B to server A T void tfFtpStor ftpHandleA ftpHandleB testFtpFile testFtpFile return Example for one server passive mode operation STOR include trsocket h include lt stdio h gt FF for printf void main void ttUserFtpHandle ftpHandle 6 69 Treck Real Time TCP IP User s Manual Start the Treck stack Setup Ctrl connection to FTP server ftpHandle setupFtpCtrl 192 168 1 100 Set FTP session operating in passive mode void tfFtpTurnPasv ftpHandle TM FTP PASSIVE MODE ON I STOR file will be transferred from client to server void tfFtpStor ftpHandle 0 testFtpFile testFtpFile return For function prototype setupFtpCtrl please refer to example of Two FTP Server Passive Mode 6 70 Application Reference TFTP Client Application Program Interface Description The TFTP Client Application Program Interface allows the user to retrieve files from and store files to a remote TFTP server User interface The user interface allows the user to get and put files from a remote TFTP server User Interface Five calls are provided in the TFTP Client User Interface tfTftpGe
17. Verify the socket was created correctly If not return immediately if testSocket TM SOCKET ERROR returnVal tfGetSocketError testSocket errorStr tfStrError returnVal goto tcpClientEnd 2 12 2004 Treck Incorporated Introduction to BSD Sockets Connect to the server errorCode connect testSocket amp destAddr sizeof destAddr Verify that we connected correctly if errorCode lt 0 returnVal tfGetSocketError testSocket errorStr tfStrError returnVal goto tcpClientEnd While we haven t yet sent enough packets while counter lt TM_PACKETS_TO_SEND Send another packet to the destination specified above errorCode send testSocket testBuffer TM_BUF_SIZE 0 Check if there was an error while sending If so break from the loop if errorCode lt 0 returnVal tfGetSocketError testSocket errorStr tfStrError returnVal break Increment the number of packets sent by 1 counter tcpClientEnd Make sure we have a socket before closing it if testSocket 1 Close the socket tfClose testSocket return returnVal 2 13 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TCP Server This is the most complicated of the examples It creates a socket binds that socket to a port and configures it as a listening socket This allows it to receive incoming connections It
18. return errorCode 4 67 2004 Treck Incorporated Treck Real Time TCP IP User s Manual An Example of using the driver s buffer to receive a frame and passing it directly to the protocol stack Notice that the bufHandlePtr is NULL This is how the stack knows who created the buffer being received int myDeviceReceive ttUserInterface interfaceHandle char TM FAR TM FAR dataPtr int TM FAR dataLength ttUserBufferPtr bufHandlePtr Save the pointer to the beginning of the data dataPtr deviceRecvDataPtr Save the length dataLength deviceDataLength IMPORTANT NULL OUT THE BUFFER HANDLE bufHandlePtr ttUserBufferPtr 0 return TM_DEV_OKAY Tip Typically the user calls fGetEthernetBuffer or tfGetDriverBuffer routine to pre allocate the receive buffers to receive into This way the driver if it is capable can store the data directly into a protocol stack buffer This eliminates the extra call to the driver to free the receive buffer that the driver passed it The trquicc c driver contains this method Special case when the user uses the Treck pool to be able to get a Treck buffer and to copy the received data to it within the receive ISR Recall that in that case the user has called zfPoolCreate in the device driver open function The driver receive function is very simple The driver receive function could either be ffPoolReceive i e be the driver receive function pointer parameter
19. struct tsUserPacket pktuLinkNextPtr tt8BitPtr pktuLinkDataPtr ttPktLen pktuLinkDataLength ttPktLen pktuChainDataLength int pktuLinkExtraCount ttUserPacket typedef ttUserPacket ttUserPacketPtr where ttUserPacket fields Description ptkuLinkNextPtr points to the next ttUserPacket structure pktuLinkDataPtr points to the data in the current link pktuLinkDataLength contains the length of the data in the current link pktuLinkChainDataLength contains the total length of the scattered data Its value is ony valid in the first link pktuLinkExtraCount contains the number of extra links besides the first one Its value is only valid in the first link The modified user device driver send function will loop through all the links of the scattered frame in order to send a complete frame 4 78 2004 Treck Incorporated Integrating into Your Environment tfUselnterfaceOneScatSend The Treck stack need to be made aware that the modified driver send function need to be used instead of the default driver send function So after the call to tfAddInterface and before the call to tfOpenInterface the user need to call tfUseInterfaceOneScatSend int tfUseInterfaceOneScatSend ttUserInterface interfaceHandle ttDevOneScatSendFunc devOneScatSendFunc Where devOneScatSendFunc type is defined as follows typedef int ttDevOneScatSendFuncPtr ttUserInterface interfaceHandle ttUserPacketPtr p
20. tfTeldOpened Call provided by the user and called by the telnet server The telnet server calls t TeldOpened to inform the user that a specified telnet client has established a new connection to the telnet server tfTeldIncoming Call provided by the user and called by the telnet server The telnet server calls tfTeldincoming to give data received from a specified telnet client to the user The telnet server performs the NVT conversion before handing the data to the user tfTeldClosed Call provided by the user and called by the telnet server The telnet server calls tfTeldClosed to inform the user that a specified telnet client closed the connection 6 115 Treck Real Time TCP IP User s Manual tfTeldClosed include lt trsocket h gt void tfTeldClosed ttUserTeldHandle teldHandle Function description The user provides this function It is called from the telnet server to let the user know that the telnet client has closed the telnet connection Parameters Parameter Description teldHandle Unique identifier for a telnet connection Returns Nothing 6 116 Application Reference tfTeldincoming include trsocket h int tfTeldIncoming ttUserTeldHandle teldHandle char teldRecvBufPtr int teldBytes int eolFlag Function description The user provides this function It is called from the telnet server to pass incoming data from the specified telnet client to the user If eolFlag
21. ttUserPacketPtr recvPacketUPtr char bufferPtr int extraCount extraCount 1 recvPacketUPtr ttUserPacketPtr recvMessageHandle bufferPtr amp bufferArray 0 tm_assert testzUdp msgLength recvPacketUPtr gt pktuChainDataLength tm_assert testzUdp msgLength lt sizeof bufferArray tm_assert testzUdp dataPtr recvPacketUPtr gt pktuLinkDataPtr do tm assert testzUdp msgLength gt recvPacketUPtr gt pktuLinkDataLength tm_assert testzUdp recvPacketUPtr gt pktuLinkDataPtr 5 106 2004 Treck Incorporated ttUser8BitPtr O Programmer s Reference tm _bcopy recvPacketUPtr gt pktuLinkDataPtr bufferPtr recvPacketUPtr gt pktuLinkDataLength bufferPtr recvPacketUPtr gt pktuLinkDataLength msgLength recvPacketUPtr gt pktuLinkDataLength recvPacketUPtr recvPacketUPtr gt pktuLinkNextPtr extraCount while msgLength ttPktLen 0 amp amp recvPacketUPtr ttUserPacketPtr 0 tm_assert testzUdp msgLength 0 recvPacketUPtr ttUserPacketPtr recvMessageHandle tm_assert testzUdp extraCount recvPacketUPtr gt pktuLinkExtraCount Note See also tfZeroCopySendTo Returns Value 0 gt 0 1 tfZeroCopyRecvFrom will fail if TM EBADF TM EINVAL TM EMSGSIZE TM EPROTOTYPE TM EWOULDBLOCK Meaning EOF Number of bytes received An error has occurred The socket descriptor is invalid One of the parameters is invalid The socket r
22. An Ethernet uses a 48 bit addressing scheme Each computer that attached to an Ethernet network is assigned a unique 48 bit number that is known as its Ethernet Address To assign an Ethernet address Ethernet hardware manufacturers request blocks of Ethernet addresses and assign them in sequence as they manufacture Ethernet interface hardware Therefore no two hardware interfaces have the same Ethernet address The first 24 bits in an Ethernet Frame are the manufacturer s ID 48 bits Manufacturer ID Sequence Numbers 24 bits 24 bits Fig 1 7 Ethernet Addressing Scheme Usually the Ethernet address is fixed in machine readable code on the host interface hardware Because Ethernet addresses belong to hardware devices they are sometimes called hardware address or Physical Addresses Note Physical addresses are associated with the Ethernet interface hardware moving the hardware interface to a new machine or replacing a hardware interface that has failed changes that machines physical address Knowing that Ethernet physical addresses can change will make it clear why higher levels of the network software are designed to accommodate such changes The host interface hardware examines packets and determines which packets should be sent to the host Remember that each interface receives a copy of every packet even those addressed to other machines The host interface uses the destination address field in the packet as a filter T
23. Default 64 Our IP source address Default first multi home IP address on the outgoing interface Change the default IP TTL for outgoing multicast datagrams Specify a configured IP address that will uniquely identify the outgoing interface for multicast datagrams sent on this socket A zero IP address parameter indicates that we want to reset a previously set outgoing interface for multicast packets sent on that socket Add group multicast IP address to given interface see struct ip_mreq data type below Delete group multicast IP address 5 51 2004 Treck Incorporated Treck Real Time TCP IP User s Manual from given interface see struct ip_mreq data type below 5 52 2004 Treck Incorporated ip_mreq structure definition Programmer s Reference struct ip mreq struct in_addr imr_multiaddr struct in_addr imr_interface ip_mreq structure Members Member imr_multiaddr imr_interface Description IP host group address that the user wants to join leave IP address of the local interface that the host group address is to be joined on or is to leave from If imr_interface is zero then the default local interface selected with tfSetMcastInterface will be used instead The following options are recognized at the TCP level Options marked with an asterix can only be changed prior to establishing a TCP connection IP_PROTOTCP protocolLevel options TCP_KEEPALIVE TCP MAXRT Description
24. Maximum number of ARP entries in the ARP cache Each entry consumes about 100 bytes Lower this value if your heap space is low DEFAULT 64 Boolean to indicate whether the ARP logic should store all ARP mappings broadcast on the local network even if we were not waiting for a reply or if the request was not for us Set this option value TM OPTION ROUTE MAX ENTRIES TM OPTION ROUTER AGE LIMIT TM OPTION RIP ENABLE TM OPTION RIP SEND MODE TM OPTION RIP RECV MODE TM OPTION IP FORWARDING TM OPTION IP FRAGMENT TM OPTION IP TTL TM OPTION IP TOS TM OPTION IP FRAG TTL TM OPTION IP DBCAST FORWARD Programmer s Reference to 0 if your heap space is low DEFAULT 1 on Maximum number of dynamic route entries in the routing table DEFAULT 10 The maximum of time in seconds that a Router entry is kept DEFAULT 600 Boolean to enable disable the RIPv2 Listener once it has been started DEFAULT 0 To start RIP the user should call tfUseRip described below The mode used to send RIP packets see below Default TM RIP 2 BROADCAST The mode used to receive RIP packets see below DEFAULT TM RIP 1 TM RIP 2 A boolean to enable IP forwarding DEFAULT 0 A boolean to enable directed broadcast forwarding DEFAULT 0 A boolean to enable IP fragmentation DEFAULT 1 The initial time to live for IP datagrams DEFAULT 64 The default Type Of Service for IP datagrams DEFAULT 0 Frag
25. Note TM USE DRV ONE SCAT SEND need to be defined in trsystem h Note This call is not supported on Point to Point interfaces and is not supported in combination with an interface transmit queue Parameters Parameter Description interfaceHandle The interface handle of the device to send data through devOneScatSendFunc A function pointer to the device driver s send function that handles scattered data within a frame in a single call Returns Value Meaning 0 Success TM EINVAL devOneScatSendFunc is null TM EPERM The interface has already been opened or the interface is a point to point interface SLIP PPP ora transmit queue has been configured on the interface 5 184 2004 Treck Incorporated Programmer s Reference devOneScatSendFunc type is defined as follows int devOneScatSendFunc ttUserInterface interfaceHandle ttUserPacketPtr packetUPtr devOneScatSendFunc Parameters Parameter Description interfaceHandle The interface handle of the device to send data through packetUPtr Pointer to a structure ttUserPacket that contains all the information on the frame to be sent ttUserPacket Fields ttUserPacket field Description ptkuLinkNextPtr Points to the next ttUserPacket structure pktuLinkDataPtr Points to the data in the current link pktuLinkDataLength Contains the length of the data in the current link pktuLinkChainDataLength Contains the total length of the scattered data Its value is on
26. Sets the idle time in seconds for a TCP connection before it starts sending keep alive probes It cannot be set below the default value Note that keep alive probes will be sent only ifthe SO KEEPALIVE socket option is enabled Default 7 200 seconds Sets the amount of time in seconds before the connection is broken once TCP starts retransmitting or probing a zero window when the peer does not respond A TCP MAXRT value of 0 means to use the system default and 1 means to retransmit forever If a positive value is specified it may be rounded up to the connection next retransmission time 5 53 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TCP MAXSEG 5 54 2004 Treck Incorporated Note that unless the TCP_MAXRT value is 1 wait forever the connection can also be broken if the number of maximum retransmissions has been reached TM TCP MAX REXMIT See TM TCP MAX REXMIT below Default 0 Which means use system default of TM TCP MAX REXMIT times network computed round trip time for an established connection for a non established connection since there is no computed round trip time yet the connection can be broken when either 75 seconds or when TM TCP MAX REXMIT times default network round trip time have elapsed whichever occurs first Sets the maximum TCP segment size sent on the network Note that the TCP MAXSEG value is the maximum amount of data including TCP options bu
27. When the dialer has finished either through completion or error the user is notified through a notification function which is passed in when the dialer is enabled Example Here is an example of a device dialing and logging in to and ISP Local Remote ATDT5551212 CONNECT 14400 Login username Password password Welcome 7 46 2004 Treck Incorporated Optional Protocols This session could be accomplished with the following code Initialize the dialer tfUseDialer interfaceHandle dialerNotify pe client send ATDT5551212 gt server send CONNECT14400 30 second time out 5 retries fail if ERROR returned FL tfDialerAddSendExpect interfaceHandle ATDT5551212 CONNECT14400 ERROR 5 r 30 TM DIALER FAIL ON ERROR server send Login gt client send username interfaceHandle username Login char 0 0 60 0 server send Password gt client send password tfDialerAddExpectSend interfaceHandle password Password char 0 0 60 0 server send Welcome gt client send nothing successful server send Invalid Login client send nothing failure ri tfDialerAddExpectSend interfaceHandle wu Welcome Invalid Login 0 60 TM DIALER FAIL ON ERROR Dialing starts now tfOpenInterface interface handle 7 47 2004 Treck Incorporat
28. af void main void int errorCode int failed struct sockaddr_in addr unsigned long ipAddr int sd int len int recvdLength int sentLength failed 0 sd TM_SOCKET_ERROR recvdLength TM_SOCKET_ERROR sentLength TM_SOCKET_ERROR ipAddr OUL Amount of data to send and receive len sizeof bufferArray Example setting the tick length at 10 milliseconds errorCode tfInitTreckOptions TM_OPTION_TICK_LENGTH unsigned long 10 if errorCode TM_ENOERROR printf tfInitTreckOptions failed dWn errorcode failed 1 if failed 0 Start the Treck initialization errorcode tfStartTreck if errorcode TM_ENOERROR amp amp failed 0 printf tfStartTreck failed d n errorcode failed 1 if failed 0 Open a UDP socket sd socket PF_INET SOCK_DGRAM IP_PROTOUDP 4 41 2004 Treck Incorporated Treck Real Time TCP IP User s Manual if sd TM_SOCKET_ERROR amp amp failed 0 Retrieve the socket error for failed socket call errorCode tfGetSocketError sd printf socket failed d n errorCode failed 1 if failed 0 Bind the UDP socket to a well known UDP port addr sin_family PF_INET addr sin_port TM_PORT_LOOPBACK_TEST addr sin_addr s_addr 0 errorCode bind sd struct sockaddr TM_FAR amp addr sizeof struct sockaddr in if errorCode TM_SOCKET
29. fileSystemFlags blockingState fsUsernamePtr fsPasswordPtr This function creates a new FTP client session This session may be used for multiple consecutive connections to multiple servers This call returns a handle that should be used for all future commands associated with this session When the session is complete the user should call tfFtpFreeSession to free the resources used by this session The user can specify whether this session should be blocking or non blocking by setting blockingState accordingly TM_BLOCKING_ON and TM BLOCKING OFF respectively Parameters Parameter fileSystemFlags blockingState fsUsernamePtr fsPasswordPtr Returns Value 0 ttUserFtpHandle Description Flags to be passed to the local file system when it is opened Specifies the blocking mode TM BLOCKING ON or TM BLOCKING OFF Username used to log on to local file system Password used to log on to local file system Meaning Error creating new FTP session Handle associated with the newly created FTP session 6 49 Treck Real Time TCP IP User s Manual tfFtpNoop include lt trsocket h gt int tfFtpNoop ttUserFtpHandle ftpSessionPtr Function description This function sends the NOOP command to the FTP server which does nothing This command is most frequently used to keep an idle FTP connection open Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM
30. tfOpenInterface context2InterfaceHandle2 for tfSetCurrentContext contextHandlel tfTimerExecute if tfCheckReceiveInterface contextlInterfaceHandlel TM ENOERROR tfRecvInterface contextlInterfaceHandlel if tfCheckReceiveInterface contextlInterfaceHandle2 TM_ENOERROR tfRecvInterface contextlInterfaceHandle2 lt Non blocking application code for context 1 gt tfSetCurrentContext contextHandle2 tfTimerExecute if tfCheckReceiveInterface context2InterfaceHandlel TM_ENOERROR A 13 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfRecvInterface context2InterfaceHandlel if tfCheckReceiveInterface context2InterfaceHandle2 TM_ENOERROR tfRecvInterface context2InterfaceHandle2 Non blocking application code for context 2 gt Note 1 that this sample code does not check for error for ease of reading Note 2 For more than 2 contexts it would make sense to save the context variables and interface handles in a 2 dimensional array and loop on the array indices Non preemptive kernel In this case the applications can run in blocking mode 1 Each application task will have to set its Treck context prior to making the first Treck call 2 Inside each tfKernel call the user will have to save the current Treck context before calling the OS and then restore the Treck context upon return from the OS call
31. tfOpenInterface to configure an IP address on the interface Note that tfConfigInterface tfOpenInterface is unchanged if errorCode TM ENOERROR ipAddress inet_addr 208 229 201 110 netMask htonl Oxffffff00 255 255 255 192 4 Config the Interface errorCode tfOpenInterface interfaceHandle ipAddress netMask 4 80 2004 Treck Incorporated Integrating into Your Environment TM_DEV_SCATTER_SEND_ENB tfSendCompletePacketinterface The default device driver interface does not allow the user to specify which frame have been sent by the device driver The stack assumes that the frames have been sent in the order of transmission to the device driver send function When using a the modified single call device driver send interface the user has the choice of either calling tfSendCompleteInterface for each frame that has been sent out or tfSendCompletePacketInterface specifying the frame that has just been sent out The later choice is useful for device driver where frames might not be sent out in the order they were transmitted tfSendCompletePacketInterface is similar to tfSendCompletelnterface but takes the frame handle passed to the modified device driver send function as a parameter void tfSendCompletePacketInterfac ttUserInterface interfaceHandle ttUserPacketPtr packetPtr int devDriverLockFlag Limitations The single scattered send call is not supported on point to
32. ttUser32Bit ntTcpBytesInSendQ ttUser32Bit ntTcpRecvQSize ttUser32Bit ntTcpSendQSize struct sockaddr_storage ntTcpLocalSockAddr ttUser16Bit ntTcpOwnerCount struct sockaddr_storage ntTcpPeerSockAddr ttUser16Bit ntTcpFlags ttUser32Bit ntTcpRto ttUser32Bit ntTcpReXmitCnt ttUser32Bit ntTcpSndUna ttUser32Bit ntTcplss ttUser32Bit ntTcpSndNxt ttUser32Bit ntTcpMaxSndNxt ttUser32Bit ntTcplrs ttUser32Bit ntTcpSndWL 1 ttUser32Bit ntTcpSndWL2 6 152 Application Reference ttUser32Bit ntTcpMaxSndWnd ttUser32Bit ntTcpRevNxt ttUser32Bit ntTcpRcvWnd ttUser32Bit ntTcpRevAdv ttUser32Bit ntTcpCwnd ttUser32Bit ntTcpSsthresh ttUser16Bit ntTcpBackLog ttUser8Bit ntTcpDupAck ttUser8Bit ntIcpAcksAfterRexmit ttUser8Bit ntTcpState ttUser8Bit ntTcpFiller 3 ttNtTcpEntry typedef ttNtTcpEntry ttNtTcpEntryPtr Many of this structure s members follow RFC 793 section 3 2 Terminology Where applicable the original name used in the RFC is indicated Users are referred to RFC 793 for more information on these variables 6 153 Treck Real Time TCP IP User s Manual Member ntTcpSockDesc ntTcpBytesInRecvQ ntTcpBytesInSendQ ntTcpRecvQSize ntTcpSendQSize ntTcpLocalSockAddr ntIcpOwnerCount ntIcpPeerSockAddr ntTcpFlags ntTcpRto ntIcpReXmitCnt ntTcpSndUna ntToplss ntTcpSndNxt ntTcpMaxSndNxt ntTcplrs ntTcpSndWL1 ntTcpSndWL2 ntTcpMaxSndWnd ntTcpRevNxt ntTcpRcvWnd n
33. 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfFreePppLqm int tfFreePppLqm ttUserInterface interfaceHandle Function Description tfFreePppLqm does the reverse of tfUsePppLqm i e it disables LQM on the link deallocates any memory allocated by LQM and removes any associated timers Parameters Parameter Description interfaceHandle The PPP interface handle as returned by tfAddInterface Returns Value Meaning 0 Success TM_EINVAL The interface handle is invalid 7 118 2004 Treck Incorporated Optional Protocols tfLqmRegisterMonitor int tfLqmRegisterMonitor ttUserInterface interfaceHandle ttLqmMonitorFuncPtr monitorFuncPtr ttUserl6Bit hysteresisMaxFailures ttUserl6Bit hysteresisSamples Function Description tfLqmRegister Monitor enables the user to specify a policy for determining link quality specifically by registering a user defined link quality monitoring function tfLqmRegisterMonitor should be called after the call to tfUsePppLqm for each distinct PPP interface that the user wants to monitor link quality on It is highly recommended that you use a LQR timer to pace the sending of LQRs otherwise if the link is very bad incoming your link quality monitoring function won t be called frequently enough to allow you recover the link in a timely fashion since without a LQR timer it is only called when a LOR is received The user defined link quality monitoring funct
34. AOA PIENE E 7 51 IGMP Protocol 7 53 Tintroduictt OMe DE 7 53 D SCED OD rei rante HERR I tin ester uiuit 1 33 Enabling the IGMP Codes eterne reete ont 7 53 Sending Multicast Packets citri re a rte reciban 1 53 SP dcm 7 53 IP Outgoing Interface for Multicast Packets sss 7 54 IP TTL for Multicast Packets 52er recente etie teens 7 54 Mapping Multicast Addresses to Layer 2 Hardware Addresses 7 54 IGMP Protocol 2 0 ccsvssescectiel cove det aioe esdesrecds eeteehs vests ose sheen coeeendevient ests 7 54 Receiving UDP Multicast Packets sse 7 54 Joining Host Group retirer Rer oet ne fe ree verra eter teca 7 54 Leaving d HoSU CITOUD 25e es M vin etae Febre eve hun 7 55 Treck Stack Initialization of the IGMP Protocol s 7 55 MARANA OS sects sts cosets des vag intento erdt da muere LU 1 55 rin osi ari Cee 7 56 tiSetMCcastinterfdee sco D betta ostio rE oio eE EE SIERA EEn 7 58 fue 7 59 One IP address aote ati rto reprae beber eR UFU ERE ERERERE 7 59 Multiple IP addresses i52 eterne Shai pt teo ritos etd menu 7 60 LA D Eten bett sce sues ae EIL MEE 7 61 PIDB eiue eee er irent eec rue rede asser ute beer eges eb nent eine 7 61 TraceRoute ML 7 61 I eco c E 7 61 Private IP Addressing n ero tre EO PO Po ERU Rees
35. Alternatively the following macro can be used to retrieve the pointer deviceDriverPointer tm device get pointer interfaceHandle 4 72 2004 Treck Incorporated Integrating into Your Environment Device driver ISR Handler The user should keep a global mapping between an interrupt vector and corresponding interface handle so that the user can retrieve the corresponding device driver pointer with the tfDeviceGetPointer API 4 73 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Adding and Configuring your New Device Driver Now that you have your device driver code you need to tell the protocol stack about it There are two calls to inform the stack about your driver These calls should be made after you have called ffStartTreck and before any sockets calls These two calls are comprised of an add tfAddInterface and open tfOpenInterface The following example shows how to inform the protocol stack of the new device driver Location to store Link Layer Handle into ttUserLinkLayer ethernetLinkLayer Location to save Interface Handle into ttUserInterface myInterfaceHandle ethernetLinkLayer tfUseEthernet myInterfaceHandle tfAddInterface name of the device MYDEVICE 001 Link Layer to use ethernetLinkLayer Open Function myDeviceOpen Close Functio
36. Device Driver API Where Used int tfDeviceStorePointer Device driver open function ttUserInterface interfaceHandle ttvoidPtr deviceDriverPtr int tfDeviceStorePointer Device driver close function ttUseInterface interfaceHandle ttVoidPtr ttDeviceGetPointer Any device driver function ttUserInterface interfaceHandle Summary of Device Driver API s that are provided to allow a device driver to be shared by several Ethernet interfaces Device driver open function First make sure that you move all device driver local variables to a structure In the open function allocate such a structure and give the pointer to the Treck TCP IP stack so that it can be stored on the interface i e errorCode tfDeviceStorePointer interfaceHandle deviceDriverPointer Device driver close function In the device driver close function call tfDeviceClearPointer to dissociate the device driver structure from the interface handle deviceDriverPointer tfDeviceClearPointer interfaceHandle Then if the returned deviceDriverPointer is non null free the allocated structure pointed to by deviceDriverPointer Any device driver function When the device driver needs access to local structure tfDeviceGetPointer should be called Given an interface handle tfDeviceGetPointer will retrieve the pointer to the device driver structure deviceDriverPointer tfDeviceGetPointer interfaceHandle It will return a non zero pointer on success
37. Enable the reception of the Ethernet multicast addresses pointed to by optionPtr optionPtr points to a list of 48 bit multicast Ethernet addresses and optionLen contains the number of multicast Ethernet addresses optionPtr points to If optionLen is non zero The driver will enable reception of the optionLen multicast addresses in the list pointed to by optionPtr If optionLen is zero the driver will disable all multicast reception The driver will enable reception of all multicast addresses and should ignore the optionPtr and optionLen arguments Meaning Success Driver specific error code 7 57 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSetMcastinterface include lt trsocket h gt int tfSetMcastInterface ttUserInterface interfaceHandle unsigned char mhomeIndex Function Description This function allows can specify a default interface to be used to send multicast destination IP packets This default interface will be used to send outgoing multicast packets when the user program does not specify an interface i e the user did not use the IPO MULTICAST IF option on the socket Parameters Parameter Description interfaceHandle The interface handle of the default interface to be used as output interface for outgoing multicast packets Returns Value Meaning 0 Success TM ENETDOWN Interface not configured yet TM EADDRNOTAVAIL Interface does not have the multicast enabled flag set
38. TM DIR LONG or TM DIR SHORT Note that if pathNamePtr points to a directory name then the matching pattern is If pathNamePtr points to then the user working directory should be open and the matching pattern is Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin pathNamePtr Pointer to a null terminated string containing pathname flag Either TM DIR LONG or TM DIR SHORT Returns Value Meaning void 0 Failure dirDataPtr Pointer to newly allocated directory data structure 6 100 Application Reference tfF SOpenFile include lt trsocket h gt void tfFSOpenFile void userDataPtr char pathNamePtr int flag int type int structure Function description Given the unique user data pointer as returned by tfFSUserLogin and a file name this function opens the file for either read if flag is TM FS READ write if flag is TM FS WRITE or append if flag is TM FS APPEND The parameter type specifies if file type is ASCII TM TYPE ASCII or binary TM TYPE BINARY Parameter structure specifies if the file structure is stream TM STRU STREAM or record TM STRU RECORD This function allo cates a file data structure to store the file pointer file type file structure etc Note This call should fail if the file name is a directory Parameters Parameter Description userDataPtr Pointer to user data structure as
39. TM EALREADY Default multicast interface already set TM EINVAL Invalid interface handle 7 58 2004 Treck Incorporated Optional Protocols NAT The point of NAT is to free a network from certain limitations of IP such as the requirement for each machine to have a fixed unique address It is primarily used when there is only one IP address to be shared by several machines or there are multiple IP addresses that need to be flexibly assigned to multiple machines either the machines change often or the set of IP addresses may change This module enables the Treck TCP IP stack to become a NAT Router which acts as a link between public and private networks Resources inside the private network clients and servers are identified differently on the two networks A common example is a home or office LAN with a private addressing scheme and the public Internet with publicly assigned IP addresses ote is not a security feature and is not a substiture for a firewa NAT router should only be used between networks of equal trust levels All initialization of a NAT router implementation of the Treck stack is first done just as if the there were no NAT feature and the stack were acting as a transpar ent router This includes functions like tfUseEthernet tfAddInterface and tfOpenInterface Then the NAT configuration functions are called First tfNatConfig is called on each public interface Then different functions are called depending
40. TM EBADF TM EINVAL Programmer s Reference Some sent data has been received and acked by the peer The user can issue tfGetSendCompltBytes to retrieve the actual amount of bytes that have been received and acked since the last call to tfGetSendCompltBytes Our peer has shutdown the connection sent a FIN No more new data will be coming The user needs to empty its receive queue using any of the recv calls and then close the connection using tfClose Indicates that there is more room on the send queue The user can now send more data on the connection given by the socketDescriptor An error has occured on the connection The user can issue a send or recv call to retrieve the error as described in the send and recv sections Note that recv will return all outstanding incoming data before returning the error The user should then issue tfClose to close the connection The peer has sent a RESET The user needs to issue tfClose to close the socket The user issued tfClose has now completed Meaning Success An error has occurred The socket descriptor is invalid socketCBFuncPtr is NULL and eventF lags is non zero 5 119 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfRegisterSocketCBParam include lt trsocket h gt int tfRegisterSocketCBParam int socketDescriptor ttUserSocketCBParamFuncPtr socketCBParamFuncPtr void socketUserPtr int eventFlags Function Descr
41. The Information Field The information field contains the packet sent down by the network level As is usual in stacked protocols PPP encapsulates the packet without interpreting it Unless otherwise established by peer to peer negotiation the default Maximum Receive Unit length for the information field is 1500 bytes including any padding but excluding the Protocol field The Padding Field The padding field supports protocols and equipment that prefer or require that the overall packet length be extended to a 32 bit boundary or be otherwise fixed Its use is not mandatory except as implied by configuration options negotiated between the peers in the link 1 26 2004 Treck Incorporated Introduction to TCP IP PPP Link Operation Before user information can be sent across a point to point link each of the two endpoint systems comprising the desired link must test the link and negotiate how the link will be configured and maintained These functions are performed using the Link Control Protocol The PPP software on each peer endpoint system creates packets for this purpose framed with the standard PPP protocol field Once the link has been established each peer authenticates the other if so requested Finally PPP must send Network Control Protocol packets to negotiate the network layer protocol s that will be supported in this link Once the link has been established and both peers have agreed to support a given network
42. To manipulate options at any other level protocolLevel is the protocol number of the protocol that controls the option For example to indicate that an option is to be interpreted by the TCP protocol protocolLevel is set to the TCP protocol number The parameters option ValuePtr and optionlength are used to access option values for setsockopt optionName and any specified options are passed un interpreted to the appropriate protocol module for interpretation The include file lt trsocket h gt contains definitions for the options described below Most socket level options take an int pointer for option ValuePtr For setsockopt the integer value pointed to by the option ValuePtr parameter should be non zero to enable a boolean option or zero if the option is to be disabled SO_LINGER uses a struct linger parameter that specifies the desired state of the option and the linger interval see below struct linger is defined in lt trsocket h gt struct linger contains the following members onoff on l off 0 1 linger linger time in seconds 5 48 2004 Treck Incorporated Programmer s Reference The following options are recognized at the socket level SOL_SOCKET protocolLevel options SO_DONTROUTE SO_KEEPALIVE SO LINGER SO OOBINLINE SO REUSEADDR SO RCVLOWAT SO SNDLOWAT SO RCVBUF SO SNDBUF TM SO RCVCOPY Description Enable disable routing bypass for outgoing messages Default 0 Enable disable keep connect
43. Value Meaning TM ENOERROR Success TM WOULDBLOCK This FTP session is non blocking and the call did not complete TM EACCES Previous command did not com plete TM ENOTCONN The user is not currently connected to a FTP server TM BINVAL Invalid FTP session pointer TM FTP SYNTAXCMD Syntax error command unrecog nized TM FTP SYNTAXARG Syntax error in parameters or arguments TM FTP NOCMD Command not implemented TM FTP SERVNAVAIL Service not available closing TELNET connection 6 46 tfFtpLogin include lt trsocket h gt Application Reference int tfFtpLogin ttUserFtpHandle ftpSessionPtr char userNamePtr char passwordNamePtr char accountNamePtr Function description Attempts to log on and authenticate to the remote FTP server Parameters Parameter fipSessionPtr userNamePtr passwordNamePtr accountNamePtr Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM _EINVAL TM FTP SYNTAXCMD TM FTP SERVNAVAIL TM FTP NEEDPASS TM FTP NEEDACCTLOGIN TM FTP BADCMDSEQ Description FTP session handle Username string Password string Account string 1f needed Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server Invalid FTP session pointer Syntax error command unrecog nized Service not available closing TELNET connection User
44. a task until the send complete event has been notified You must choose if you want a task to block until data has been sent or poll to see if data has been sent The choice that you make defines which of the functions ffCheckSentInterface or tfWaitSentInterface that you will use Note tfNotifyInterfaceIsr need to be used whether the user chooses to use tfCheckSentInterface polling method or tfWaitSentInterface pending method If you do not have an RTOS you cannot use fWaitSentInterface If you do have an RTOS you can use tfWaitSentInterface but only if you define the TM TASK SEND macro in trsystem h Tip It is not required to use the functions tfNotifytInterfacelsr tfCheckSentInterface and tfWaitSentInterface as long as you can guarantee that the tfSendCompleteInterface call is made when the device driver has sent the data Remember that tfSendCompleteInterface may not be called from an interrupt handler Now let s look at send complete processing Send complete means that the sending frame is not in use by the driver anymore Here is send complete processing from a separate task void sendCompleteTask void while 1 Wait for the send complete event from an ISR tfWaitSentInterface myInterfaceHandle Tell the stack that the driver is done with the current frame Wu tfSendCompleteInterface myInterfaceHandle TM DEV SEND COMPLETE APP 4 57 2004 Treck Incorporated Treck Real Time TCP IP User s
45. authenticator s IP address to the known value errorCode tfPppSetOption interfaceHandle int TM_PPP_IPCP_PROTOCOL TM_PPP_OPT_ALLOW TM_IPCP_IP_ADDRESS char amp serverIPAddr JE 192 168 0 2 4 7 107 2004 Treck Incorporated Treck Real Time TCP IP User s Manual assert errorCode TM ENOERROR 2 Peer allows the authenticator to set peer s IP address to any non zero address the authenticator wants errorCode tfPppSetOption interfaceHandle int TM_PPP_IPCP_PROTOCOL TM_PPP_OPT_WANT TM_IPCP_IP_ADDRESS char amp zeroIPAddr F0 0 050 4 assert errorCode TM ENOERROR 3 Peer allows MSCHAPv1 only chapValue int TM PPP CHAP PROTOCOL net work order 3 1 Allow CHAP protocol errorCode tfPppSetOption interfaceHandle int TM_PPP_LCP_PROTOCOL TM_PPP_OPT_ALLOW TM_LCP_AUTH_PROTOCOL char amp chapValue 2 assert errorCode TM_ENOERROR 3 2 Delete standard CHAP algorithm TM_CHAP_MD5 char chapAlgorithm TM_CHAP_MD5 errorCode tfPppSetOption interfaceHandle int TM_PPP_CHAP_PROTOCOL TM_PPP_OPT_ALLOW TM_CHAP_ALG_DEL char amp chapAlgorithm 1 TM ENOERROR assert errorCode 3 3 Adds MS CHAP v1 algorithm TM CHAP MSV1 ifdef TM USE PPP MSCHAP chapAlgorithm TM CHAP MSVI1 7 108 2004 Treck Incorporated Optional Protocols errorCode tfPppSetOption interfaceHandle int TM_
46. calling tfloctlInterface and specifying the flag TM DEV IOCTL REFILL POOL FLAG It is recommended that when using the Treck buffer pool you use both methods to refill the pool Tip You will only be using a subset of the functions listed on this page You will find that the hardest part about the device driver having to read and interpret the device data sheet A key thing to remember here is that it is easier than it looks Just take it one step at a time and before you know it you will have your device driver up and running tfNotifyInterfacelsr tfNotifyInterfaceTask tfCheckReceiveInterface tfWaitReceiveInterface and tfRecvInterface Functions This group of functions is used to allow the user to notify the stack that a receive complete event has occurred so that the event can be processed at main task level instead of from the ISR In other words the first four functions are used to tell the user when to call tfRecvInterface tfRecvInterface may NOT be called directly from an interrupt handler The ffNotifyInterfaceIsr function Is used to notify the stack from an ISR that there is data waiting to be received The fNotifyInterface Task function is used to notify the stack from a task that there is data waiting to be received Usually only fNVotifyInterfacelsr is needed On some occasions there is a need to let the stack know that there is more data to be received in the context of a task instead of an ISR and this is the reason
47. default to the device IP MTU Returns Value Meaning 0 Success TM EINVAL DestIpAddress parameter is zero TM EPERM Route is direct No path MTU discovery is ever going to take place TM EHOSTUNREACH No route to destination IP address TM ENOBUFS Not enough memory to allocate new routing entry 5 219 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetArpEntryBylpAddr include lt trsocket h gt int tfGetArpEntryByIpAddr ttUserlpAddress arplpAddress char physAddrPtr int physAddrLength Function Description This function is used retrieve an entry from the ARP cache by looking up the entry by the IP address This function will allow the user to manipulate the ARP cache beyond standard means Normally the TCP IP stack maintains the ARP cache Parameters Parameter Description arplpAddress The IP address to use to lookup the entry by physAddrPtr The Pointer to the buffer where to store the physical address physAddrLength The length of the physical address buffer Returns Value Meaning 0 Success TM BINVAL Bad parameter TM ENOENT No ARP entry found with this IP address 5 220 2004 Treck Incorporated Programmer s Reference tfGetArpEntryByPhysAddr include lt trsocket h gt int tfGetArpEntryByPhysAddr char physAddrPtr int physAddrLen ttUserIpAddress arplpAddressPtr Function Description This function is used retrieve an entry from the ARP cache by looking up th
48. int testSocket unsigned int counter struct sockaddr_in destAddr int errorCode int returnVal counter 0 returnVal 0 Specify the address family destAddr sin_family AF_INET Specify the destination port destAddr sin_port htons TM DEST PORT Specify the destination IP address destAddr sin addr s addr inet addr TM DEST ADDR Create a socket testSocket socket AF INET SOCK DGRAM IPPROTO UDP Verify the socket was created correctly If not return immediately ar if testSocket TM SOCKET ERROR returnVal tfGetSocketError testSocket errorStr tfStrError returnVal goto udpClientEnd 2 8 2004 Treck Incorporated Introduction to BSD Sockets While we haven t yet sent enough packets while counter lt TM_PACKETS_TO_SEND Send another packet to the destination specified above errorCode sendto testSocket testBuffer TM_BUF_SIZE 0 amp destAddr sizeof destAddr Check if there was an error while sending If so break from the loop Ry if errorcode lt 0 returnVal tfGetSocketError testSocket errorStr tfStrError returnVal break Increment the number of packets sent by 1 counter udpClientEnd Make sure the socket exists before we close it if testSocket 1 Close the socket tfClose testSocket return returnVal 2 9 2004 Treck Incorporated Treck Real Time TCP
49. on demand to allow forwarding of subsequent packets If the user does not want to enable or configure the interface then the call back function should return a non zero error code In that case the stack will send a host unreachable ICMP error message as if no call back function had been registered If the user wants to enable or configure the interface then the call back function should return TM ENOERROR In that case the Treck stack will silently drop the packet without sending an ICMP error message allowing the sender to try and send more data Parameters Parameter Description ipForwCBFuncPtr Pointer to user call back function that returns an integer as described above and that takes two parameters of type ttUserlpAddress the first one being the source IP address in network byte order of the IP datagram to be forwarded and the second one being its destination IP address in network byte order Function prototype for the user supplied IP forward call back function int ipForwCBFunc ttUserIpAddress srcIpAddress ttUserlpAddress destIpAddress Returns Value Meaning TM ENOERROR This function always returns TM ENOERROR 5 89 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfResetConnection include lt trsocket h gt int tfResetConnection int socketDescriptor Function Description This function is used to abort a connection on a socket It only works with TCP STREAM sockets and sends
50. recvfrom This function allows the user to receive data from a specified UDP socket whether or not it is connected It may not be used for TCP sockets as they require a connection close This function closes read deletes a socket that has been allocated with the socket call If the socket is connected it closes the connection before deleting it Because the close call is frequently used for more than one purpose closing open files for example it is renamed tfClose in the Treck stack to avoid conflicts with the preexisting function 2 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Example Code The following are simplified examples of using the Sockets API to create Internet connectivity in an application They are all available on the Treck protocols CD in the examples directory Four examples are given UDP Client UDP Server TCP Client and TCP Server All of the examples are coded in blocking mode UDP Client This first example shows how to code a UDP client A socket is created and sendto is called the specified number of times Note that bind is never called For outgoing connections bind is not necessary as the stack will pick a random port and an appropriate IP address include lt trsocket h gt define TM_BUF_SIZE 1400 define TM_PACKETS_TO_SEND 10 define TM_DEST_ADDR 100051 define TM_DEST_PORT 9999 char testBuffer TM BUF SIZE char errorStr int udpClient void
51. the Device driver ISR is a little bit different and is described below Device driver ISR The user should keep a global mapping between an interrupt vector and a pair interface handle context instead of just a global mapping between an interrupt vector and an interface handle In the device driver ISR the user should save the current context then the user should set the Treck context as found in the global mapping described here and call tfDeviceGetPointer in order to access the device driver specific data Before returning from the ISR the user should set the context to the saved value at the beginning of the ISR function A 15 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfinitTreckMultipleContext include lt trsocket h gt void tfinitTreckMultipleContext void Function Description This function is used to initialize multiple context global variables valid across all contexts This function should be called prior to any other Tubo Treck TCP IP stack functions when using multiple instances of the stack Parameters None Returns None A 16 2004 Treck Incorporated Configuration Notes tfCreateTreckContext include lt trsocket h gt ttUserContext tfCreateTreckContext void Function Description This function creates a Treck context for an instance of the Treck TCP IP stack It will allocate a structure containing all Treck variables for a context and returns a pointer t
52. the router uses ICMP to inform the original source that a problem has occurred and trusts that host administrators will cooperate with network administrators to locate and repair the problem 1 45 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ICMP Message Delivery ICMP messages require two levels of encapsulation as Figure 1 31 shows Each ICMP message travels across the Internet in the data portion of an IP datagram which itself travels across each physical network in the data portion of a frame Datagrams carrying ICMP messages are routed exactly like datagrams carrying information for users there is no additional reliability or priority Thus error messages themselves may be lost or discarded Furthermore in an already congested network the error messages may cause additional congestion An exception is made to the error handling procedures if an IP datagram carrying an ICMP message causes an error The exception established to avoid the problem of having error messages about error messages specifies that ICMP messages are not generated from errors that result from datagrams carrying ICMP error messages ICMP Header ICMP Data Datagram Header Datagram Data Area Frame Data Area Fig 1 31 Two Levels of ICMP Encapsulation The ICMP message is encapsulated in an IP datagram and then is encapsulated into a frame datagram To identify the ICMP the datagram protocol field con
53. was too long TM EPROTOTYPE TCP protocol requires usage of send not tfSendToInterface TM EWOULDBLOCK The socket is marked as non blocking and the send operation would block TM EINVAL One of the parameters is bad the interface handle or multihome index is invalid or the bufferPtr is null or bufferLength is zero 5 94 2004 Treck Incorporated Programmer s Reference tfSocketArrayWalk include lt trsocket h gt int tfSocketArrayWalk ttWalkCBFuncPtr callBackFuncPtr ttUserVoidPtr argPtr Function Description This function is used to walk the list of open sockets calling the user supplied call back function passing the socket descriptor and user argument argPtr to it until we reach the end of the list or the user call back function returns an error whichever comes first Return error value from the call back function to the user Parameters Parameter Description callBackFuncPtr The function pointer to the user function to call for each open socket See below for function prototype argPtr User pointer to be passed back to the call back function Function prototype for the user supplied call back function int callBackFunc int socketDescriptor ttUserVoidPtr argPtr Returns Value Meaning 0 Success TM EINVAL The callback function pointer is null Other As returned by the user call back function 5 95 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSocketScat
54. 10 Sets the LCP retransmission timeout in seconds Default 3 seconds Setting this option enables link quality monitoring The option value is specified in hundredths of a second and it configures the maximum time to delay i e LOR timer period between sending Link Quality Report mes sages refer to RFC 1989 Reporting Period field of the Quality Protocol Configura tion Option This option can be set for either the local or the remote end of the link however the direction in which it applies is the opposite of what one would expect when remoteLocalFlag is set to TM PPP OPT WANT this specifies an option value that we want the remote end of the link to use and when remoteLocalFlag is set to TM PPP OPT ALLOW 7 89 2004 Treck Incorporated Treck Real Time TCP IP User s Manual this specifies an option value that we will allow the remote end to configure us to use If a non zero option value is specified the LQR timer is started with the specified timeout period to pace the sending of Link Quality Report messages and this timer is restarted whenever a Link Quality Report mes sage is sent If the specified option value is 0 no LQR timer is used but instead a Link Quality Report mes sage is sent as a response every time one is received from the peer At least one side of the link must use the LQR timer to pace the sending of Link Quality Report messages when link quality monitoring is enabled th
55. 128 bytes TI C3x and C5x DSP platforms only If this option is enabled all socket data will be sent and received in byte unpacked format If this option is disabled all socket data will be sent in a byte packed format as received from the network Default 0 disable SO REUSEADDR indicates that the rules used in validating addresses supplied in a bind call should allow reuse of local addresses SO KEEPALIVE enables the periodic transmission of messages every 2 hours on a connected socket If the connected party fails to respond to these messages the connection is consid ered broken SO DONTROUTE indicates that outgoing messages should bypass the standard routing facilities Instead messages are directed to the appropriate network interface according to the network portion of the destination address SO LINGER controls the action taken when unsent messages are 5 15 2004 Treck Incorporated Treck Real Time TCP IP User s Manual queued on a socket and a close on the socket is performed If the socket promises reliable delivery of data and SO_LINGER is set the system will block the process on the close of the socket attempt until it is able to transmit the data or until it decides it is unable to deliver the information a timeout period termed the linger interval is specified in the setsockopt call when SO LINGER is requested If SO LINGER is disabled and a close on the socket is issued the system will process the close of th
56. 256 hosts allocate 21 bits to the network and only 8 bits to the host Note that the IP address has been defined in such a way that it is possible to extract the host or network portions quickly Routers which use the network portion of an address when deciding where to send a packet depend on efficient extraction to achieve high speed Network and Broadcast Addresses We have already said that the major advantage of encoding network information in Internet addresses is that it makes efficient routing possible Another advantage is that Internet addresses can refer to networks as well as hosts By convention host 0 is never assigned to an individual host Instead an IP address with host 0 is used to refer to the network itself Another significant advantage of the Internet addressing scheme is that it includes a broadcast address that refers to all hosts on the network According to the standard any host containing all s is reserved for broadcast On many network technologies broadcasting can be as efficient as normal transmission on others broadcasting is supported by the network software but requires substantially more delay than a single transmission Some networks do not support broadcast at all Therefore having an IP address does not guarantee the availability or efficiency of broadcast delivery 1 29 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Limited Broadcast Technically the broadcast address we
57. 9 tiUseCollision Detection isi er er IUE 7 10 tfUserStartArpSetd cernes tente nn ertet ve a SE vot ee Eee EE ns 7 13 BOOTP Automatic Configuration API eese eee 7 16 Ibm regio M 7 16 itContGetBOoOotEnlEy soon eph ur EX FOU EOE DEEE SEEE 7 18 jn 15e o 7 19 BOOTP relay agent eese esee eese eee ee seen tn iiias 7 21 tiStartBootRelayA gent eterne teret eterne pete tiens 7 21 1tStopBootRelayAgetit 2 iren reef RP Oe rers 7 23 DHCP Automatic Configuration API eese esee eene tnnnne 7 24 IDeSCHDUIO Gone necu i LLL mi a errr UH 7 24 DHCP FODN Option etii eet ainda edere eb esee pere vc Penes 7 277 itContGetBOoOLEDIEy Josie m adt re Ow Ore RR EORR 7 29 tHDhCpComtSset E 7 30 US DIe o A detener LE 7 32 tfUserSetEq n eire ceteri rarit eret tet npe eed ee eens 7 34 DHCP User Controlled Configuration API sens 7 35 DeSCriptiOn PR 7 35 DHCP FODN ODpLUOD oec detenti teres tercer oret ro Dre ER Ere RES een 7 38 ttfDhcpUserCietBootEntrty erii testes aah eren eee nete sitet 7 40 itDhopUserRelease NE nn ra Meet 7 41 tHDHCPUSEESet P ett 7 42 2004 Treck Incorporated dB he v ETS sir EE 7 44 DD AMC Ec 7 46 t DialerAddExpectSend ice steve rie nin aces eere tee Peta 7 48 t DialerAddSendEXpeet Ji aeter o ero DH tetes 7 49
58. Description This function is used to initialize the SLIP link layer Parameters None Returns The SLIP link layer handle or NULL if there is an error 5 207 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ARP Routing Table API tfAddArpEntry include lt trsocket h gt int tfAddArpEntry ttUserlpAddress arplpAddress char physAddrPtr int physAddrLength Function Description This function is used add an entry to the ARP cache This function will allow the user to manipulate the ARP cache beyond standard means Normally the TCP IP stack maintains the ARP cache Parameters Parameter Description arplpAddress The IP address to add to the ARP cache physAddrPtr A pointer to the character array that contains the physical address physAddrLength The length of the physical address Returns Value Meaning 0 Success TM _EINVAL Bad parameter 5 208 2004 Treck Incorporated Programmer s Reference tfAddDefaultGateway include lt trsocket h gt int tfAddDefaultGateway ttUserInterface interfaceld ttUserlpAddress gatewayIpAddress Function Description This function is used to add the system default gateway for all interfaces Parameters Parameter Description interfaceld The device entry gatewaylpAddress The default gateway IP address in Network Byte Order Returns Value Meaning 0 Success TM ENOBUFS Not enough buffer to allocate a routing entry TM EALREADY A default gatew
59. ECHO Echo DISCARD Discard FTP File Transfer Protocol TELNET Fig 1 42 Example of Well Known Ports The HLEN field contains an integer value that specifies the length of the segment header in 32 bit multiples It is needed because the OPTIONS field varies in length depending on which options have been included The 6 bit field marked as RESERVED is reserved for future use Some segments carry only acknowledgements while others carry data Others carry requests to establish or close a connection TCP software uses the field CODE BITS to determine the purpose and contents of the segment These six bits tell how to interpret other fields in the header according to the table in Figure 1 43 Bit Left to Right Meaning if Bit is set to 1 URG Urgent pointer field is valid ACK Acknowledgement field is valid PSH This segment requests a push SYN Reset the connection FIN Sender has reached the end of its byte stream Fig 1 43 Components of the Code Bits Header Field 1 58 2004 Treck Incorporated Introduction to TCP IP TCP software advertises how much data it is willing to accept every time it sends a segment by specifying its buffer size in the WINDOW field This field contains a 16 bit integer in network standard byte order Window advertisements accompany all segments including those carrying data as well as those carrying only an acknowledgement TCP IP and Client Server Relationships The TCP
60. ENOERROR Success TM WOULDBLOCK This FTP session is non blocking and the call did not complete TM EACCES Previous command did not com plete TM ENOTCONN The user is not currently connected to a FTP server TM BINVAL Invalid FTP session pointer TM FTP SYNTAXCMD Syntax error command unrecog nized tfFtpPort include lt trsocket h gt int ttUserFtpHandle ttUserIpPort Function description Application Reference ftpSessionPtr This function sets the local port number that incoming data connections should use Parameters Parameter fipSessionPtr fipPortNo Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTLOGIN TM ENOTCONN TM_EINVAL Description FTP session handle Port number to use for incoming data connections Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently logged in The user is not currently connected to a FTP server Invalid FTP session pointer Treck Real Time TCP IP User s Manual tfFtpPwd include lt trsocket h gt int tfFtpPwd ttUserFtpHandle ftpSessionPtr char bufferPtr int bufferSize Function description Returns present working directory on remote file system Parameters Parameter fipSessionPtr bufferPtr bufferSize Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM ENOTLOGIN TM _EINVAL TM F
61. FAR bufferPtr 5 97 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value gt 0 TM SOCKET ERROR tfSocketScatteredSendTo will fail if TM EWOULDBLOCK TM_EINVAL TM_ENOBUFS TM EBADF TM EMSGSIZE TM EPROTOTYPE TM EHOSTUNREACH TM ENOENT TM ENXIO TM EIO Other error code 5 98 2004 Treck Incorporated Meaning Number of bytes transmitted queued Treck will free the user buffers Call failed The user can retrieve the error code with the tfGetSocketError socketDescriptor API See below for table of possible error codes Not enough room to queue the data in the socket send queue User still owns the data user buffers and is responsible for resending them later on One of the parameters is bad i e userBlockPtr is null or userBlockCount is less or equal to 0 or userFreeFunction is null or socket is a TCP socket with toAddressPtr being non zero or flags is not zero or MSG DONTWAIT Not enough memory to allocate the Treck headers The socket descriptor is invalid The data length was bigger than the send queue or the data length caused the IP datagram to be bigger than the IP MTU and IP fragmentation is not allowed Attempt to send on a connected TCP socket No route to host No interface could be found to send the packet out limited broadcast destination IP address Outgoing interface is closed Interface transmit queue if full only if interface
62. Function description Data Socket Send Allows the user to send data on a socket directly from user owned data buffers without having to copy the data Upon return from this routine the user no longer owns its buffer The only exception is when TM SOCKET ERROR is returned and the errorCode retrieved with tfGetSocketError is TM EWOULDBLOCK In that case the user still owns its buffer and should try and re send the same buffer later on The userFreeFunction will be called by the Treck stack for each user buffer 1f an error other than TM EWOULDBLOCK occurs or when the data has been sent out on the network and the device driver no longer need to access the data in the user buffer It is the user s responsibility to ensure that the user free function is re entrant as it could potentially be called from different threads unless the user uses a different free function per user application thread and the user does not use a Treck transmit task and does not use a Treck send complete task Example of ZeroCopyUserBufferSend usage is shown in the loop back test module txscatlp c Parameters Parameter Description socketDescriptor As returned by a socket call userBufferPtr pointer to user buffer to be used when calling the user free function userDataPtr pointer to user data userDataLength size of user data userFreeFunction User free function called by the stack when the buffer is no longer accessed by the stack flags MSG DONTWAIT MSG DONTROUTE
63. HDRINCL option cannot be set on non raw sockets Specified interface not yet configured Multicast host group already added to the interface Not enough memory to add new multicast entry Attempted to delete a non existent multicast entry on the specified interface 5 59 2004 Treck Incorporated Treck Real Time TCP IP User s Manual shutdown include lt trsocket h gt int shutdown int socketDescriptor int howToShutdown Function Description Shutdown a socket in read write or both directions determined by the parameter howToShutdown Parameters Parameter Description socketDescriptor The socket to shutdown howToShutdown Direction 0 Read 1 Write 2 Both Returns Value Meaning 0 Success 1 An error occurred shutdown will fail if TM_EBADF The socket descriptor is invalid TM EINVAL One of the parameters is invalid TM_EOPNOTSUPP Invalid socket type can only shutdown TCP sockets TM_ESHUTDOWN Socket is already closed or is in the process of closing 5 60 2004 Treck Incorporated Programmer s Reference socket include lt trsocket h gt int socket int family int type int protocol i Function Description socket creates an endpoint for communication and returns a descriptor The family parameter specifies a communications domain in which communication will take place this selects the protocol family that should be used The protocol family is generally the same
64. IP User s Manual UDP Server This code is a very simple UDP server It creates a socket binds it to the desired port it is not necessary to supply an IP address the stack will pick one This is very useful for making code portable and then receives data Upon receipt of the data the sourceAddr structure is filled out with the originating IP Address and port of the incoming packet include lt trsocket h gt define TM_BUF_SIZE 1500 define TM_DEST_PORT 9999 char testBuffer TM BUF SIZE char errorStr int udpServer void int testSocket struct sockaddr_in sourceAddr struct sockaddr_in destAddr int errorCode int addrLen int returnVal returnVal 0 Specify the address family destAddr sin_family AF_INET Specify the dest port this being the server the destination port is the one we ll bind to ry destAddr sin port htons TM DEST PORT Specify the destination IP address our IP address Setting this value to 0 tells the stack that we don t care what IP address we use it should pick one For systems with one IP address this is the easiest approach Wy destAddr sin addr s addr 0 The third value is the specific protocol we wish to use We pass in a 0 because the stack is capable of figuring out which protocol to used based on the second parameter SOCK DGRAM UDP SOCK STREAM TCP testSocket socket AF_INET SOCK_DGRAM 0 Make sure the
65. IP protocol stack is designed around the concept of client machines that receive service from other machines on a network For example a personal computer that accesses the Internet through a LAN Local Area Network gateway relies on that gateway server to talk TCP IP across the Internet on its behalf With that in mind we can analyze the TCP IP stack and find that each successively higher layer is a client to the layer beneath it Application Requests Provides Services Services Transport Requests 4 Provides Services Services Network Requests Provides Services Services Data Link Requests Provides Services Services Physical Fig 1 44 Client Server Relationships in TCP IP IP is a client of the data link layer software It uses that software s services to achieve its physical transmission of packets UDP and TCP are clients of IP They use they use the IP routing mechanisms to move messages across a switched network 1 59 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Summary Anything that depends on the transmission of data from one terminal to another can efficiently use TCP IP to get it there reliably When ARPANET was established the need for reliable transmission was a must By today s standards TCP IP has become the leading means of getting information from one place to another 1 60 2004 Treck Incorporated Introduction t
66. Index flags 0 or a combination of TM DHCPF INIT REBOOT TM DHCPF REQUESTED IP ADDRESS TM DHCPF SUPPRESS CLIENT ID 7 30 2004 Treck Incorporated requestedIpAddress clientIdPtr clientIdLength Returns Value TM ENOERROR Optional Protocols TM DHCPF FQDN ENABLE TM DHCPF FQDN PARTIAL TM DHCPF FQDN PARTIAL is ignored if clientIdPtr is NULL The FQDN option must be set separately from other DHCP options The only other flag allowed with TM DHCPF FQDN ENABLE is TM DHCPF FQDN PARTIAL User requested IP address in network byte order Pointer to client ID When flags is set to IM DHCPF FOQDN ENABLE the FQDN domain name will be stored in this parameter a character pointer If it is NULL the global FQDN in tvFqdnStruct will be used instead Length of client ID When flag is set to IM DHCPF FOQDN ENABLE FQDN domain name length Meaning success 7 31 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUseDhcp include lt trsocket h gt int tfUseDhcp ttUserInterface interfaceHandle ttDevNotifyFuncPtr devNotifyFuncPtr Function Description This function is used to initialize the DHCP client interface and should be called between tfAddInterface and tfOpenInterface to allow configuration using the DHCP client protocol If the second parameter is non null then upon completion of tfOpenInterface the function that it points to will be
67. Interrupts are not firing The interrupt fires once but then is not dismissed correctly and will not fire again Edge vs level triggered interrupts If an interrupt is set to be edge triggered it is possible that an incoming interrupt will be missed Some chips will not interrupt again until the previous interrupt has been cleared This will cause the chip to not send or receive data or to suddenly stop sending and receiving data Some chips require you to copy while inside the ISR before they will dismiss the ISR For example the 3C509 and Crystal CS8900 Ethernet chips have this requirement If this is the case you should make use of the Treck Driver Pool API C 9 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Ensure that you are communicating correctly with the chip If it is not being set up correctly it will not function Make sure that the chip is set up correctly Even if you are communicating with it verify that the registers are being initialized correctly tfRecvInterface is not being called in the application Driver stops sending and or receiving data Make sure that interrupts are being triggered correctly That is it is possible for an edge triggered interrupt to be missed Some chips will not continue operation until you have cleared the interrupt causing the chip to cease working The receive ring is not being refilled correctly This can cause a chip to stop receiving data as it
68. Link Quality Report message 7 123 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfPppSendEchoRequest int tfPppSendEchoRequest ttUserInterface interfaceHandle ttUser8Bit echoRequestId const char dataPtr int dataLen ttEchoReplyFuncPtr echoReplyFuncPtr Function Description ttPppSendEchoRequest sends a LCP Echo Request message and then later will call the user defined function specified by echoReplyFuncPtr to process received LCP Echo Reply messages For each Echo Request message sent there should be one Echo Reply message received containing the same data that was in the Echo Request possibly truncated depending on what was negotiated for TM LCP MAX RECV UNIT If you do not want to process received LCP Echo Reply messages set echoReplyFuncPtr to TM PPP ECHO REPLY FUNC NULL PTR It is important to note that the user is responsible for matching Echo Request messages with their associated Echo Reply messages No attempt is made in this function to keep track of Echo Request messages that have been sent for later matching them up with received Echo Reply messages However the echoRequestld parameter is provided to assist the user in performing this matching The correct usage of this parameter is described in RFC 1661 as follows On transmission the Identifier field MUST be changed whenever the content of the Data field changes and whenever a valid reply has been received for a
69. Mixing Some mixing of the two schemes is possible For example you can configure static associations after a NAPT interface is configured if you have multiple IP s though of course you are using only one for NAPT Be sure to call tfNatConfigStatic only after tfNatConfigNapt Ping Ping using ICMP echo is supported via Static and Dynamic IP address associations Outbound Ping will also work on NAPT configurations that 1s a private client pinging a public server Inner servers cannot be pinged however If one were to try one would only ping the NAT router via its public interface So this would not detect whether the inner server was up or not just that the NAT router were up TraceRoute Unix traceroute or Windows tracert uses unsolicited UDP datagrams and ICMP error messages to detect routing pathways It will work over static and dynamic connections in either direction and NAPT in the outbound direction One cannot thoroughly TraceRoute to an inner server however just to the NAT router as with Ping FTP Servers This NAPT implementation goes to athletic lengths to accommodate FTP servers either outside or inside as much as any other server is supported inside Special handling is made of every outbound FTP PORT command and PASV reply 227 NAT translates the private IP addresses and port numbers in those messages into public values Proxy or 3rd party FTP transfers are not supported Non PORT non PASV transfers are not s
70. ONE SCAT DRV SEND and TM USE SCAT DRV RECV need to be defined If either one of these macros is not defined then tfUseScatIntfDriver will revert to tfUseIntfDriver When using the loop back driver scattered or non scattered version some macro definitions configurations are necessary to insure that the loop back driver is used and not bypassed for a given destination IP address peer IP address Peer IP address Steps to ensure the loop back driver is used configured in the stack Define TM LOOP TO DRIVER or Define TM SINGLE INTERFACE HOME not configured in the stack Define TM DEV IP NO CHECK Ifthe link layer is Ethernet then a proxy arp entry should be added for the peer IP address 5 194 2004 Treck Incorporated Parameters Parameter namePtr linkLayerHandle drvAddErrorPtr Returns Programmer s Reference Description The callers name for the device each call to tfUseScatIntfDriver must use a unique name The name length cannot exceed TM MAX DEVICE NAME 1 13 bytes The link layer layer 2 protocol handle that this interface will use This 1s returned by tfUseEthernet tfUseAsyncPpp or tfUseSlip A pointer to an int that will contain an error if one occurred An Interface Handle or a NULL handle when an error occurs If an error occurs the error is stored in drvAddError Ptr ErrorCode TM EINVAL TM EALREADY TM ENOBUFS Description One of the parameters is invalid Device wi
71. One question that you may have is How large can a datagram be Unlike physical network frames that must be recognized by hardware datagrams are handled by software They can be any length the protocol designers choose The current datagram format allows for 16 bits to the total length field limiting the datagram to at most 65 535 bytes More fundamental limits on datagram size arise in practice We know that as datagrams move from one machine to another the underlying physical network must always transport them To make internet transportation efficient we would like to guarantee that each datagram travels in a distinct physical frame The idea of carrying one datagram in one network frame is called encapsulation To the underlying network a datagram is like any other message sent from one machine to another The hardware does not recognize the datagram format nor does it understand the IP destination address Therefore when one machine sends an IP datagram to another the entire datagram travels in the data portion of the network frame 1 40 2004 Treck Incorporated Introduction to TCP IP Understanding Checksums Introduction A checksum allows information to follow a set of guidelines that is pertinent to the correct sending and receiving of data Checksums are used in several different types of protocols For example UDP TCP and IP all use variations of a checksum A good way to understand the meaning and the use of the
72. Operation Sender Hardware Address Bytes 4 5 Sender IP Address Bytes 0 1 Sender IP Address Bytes 2 3 Target Hardware Address Bytes 0 1 Target Hardware Address Bytes 2 5 Target IP Address Bytes 0 3 Fig 1 9 Ethernet and IEEE 802 3 Source Destination Address Fields Obtaining an Ethernet Address Block To obtain an Ethernet address block for your company you need to contact IEEE Standards or visit their website at http standards ieee org faqs OUL html This will provide information on getting a Company ID OUI 1 15 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Ethernet Frame Format The Ethernet should be thought of as a link level connection among machines Thus it makes sense to view the data transmitted as a frame The term frame originated from communication over serial lines in which the sender frames the data by adding special characters before and after the transmitted data Ethernet frames are variable lengths with no frame smaller than 64 bytes or larger than 1518 bytes header data and CRC As in all packet switched networks each Ethernet frame includes a field that contains the address of its destination Figure 1 10 shows that the Ethernet frame format contains the physical source address as well as the destination address Destination Source Frame Preamble Addresk Addres Type Frame Data CRC 8 bytes 6 bytes 6 bytes 2bytes 46 1500 bytes 4 b
73. Optional e driverClose Optional e driverloctl Optional e driverGetPhysicalAddress Only for Ethernet e driverSend e driverReceive e driverFreeReceiveBuffer Optional e drverlsrHandler Optional For Ethernet device drivers The Treck stack provides the following additional optional functions tfGetEthernetBuffer e tfFreeDriverBuffer For all device drivers the Treck stack provides the following additional functions e tfGetDriverBuffer More general than tfGetEthernetBuffer e tfFreeDriverBuffer 4 46 2004 Treck Incorporated Integrating into Your Environment Some Ethernet chips for example the Crystal LAN cs8900 won t dismiss a receive interrupt until the data is copied If this is the case you will need to get a buffer from within the ISR to copy the data into The Treck stack does provide a set of tools to allow you to get a Treck buffer from within the ISR e tfPoolCreate e tfPoolIsrGetBuffer e tfPoolReceive e tfPoolDelete Note Calling tfPoolIsrGetBuffer effectively removes a Treck buffer from the available pool of buffers A call to tfRecvInterface will return that buffer to the pool but only if the flag TM POOL REFILL IN LINE was specified in the call to tfPoolCreate when allocating the pool Otherwise all of the Treck pool buffers will get used up and your device driver won t be able to receive any more packets You can also refill the Treck buffer pool by periodically
74. PRETI GR e MUR e PEE RIVOS 5 231 HER ernelBttot oir reir Ire E HERE YER ERE onere vor reien 5 232 LR ernel Efe e nocet 5 233 tfKernellInitialize sssessseeseeseeee eene enne nnne 5 234 tt KernelInstalIsrHahdler 5 eco Ev bes 5 235 tfKernelIsrPostEvent ccccccecsccesccesececseceeecesecesseceseecsaesesseseeseseeeeeeeses 5 236 t ernelMalloe RS Rene ren tre De CEOs 5 237 tfKernelPendCountSem ss 5 238 tiRernelP ndE vent uias REOR ATHEN eb pUS 5 239 tfKernelPostCountSem ccccccccessccsscessecesscesseceseeceseecsseeesseseessseeseeeesas 5 240 tt KerneIReleaseGritiCal us e rrr hive aoe Ws eris 5 241 tfKernelSetCritical us 5 242 tiKemel SheapCreate 5 enis pese tete eite nerve sure pote dp eee dt 5 243 tfKernelTaskPostEvent esses ener 5 244 there MAS VICI ee enero e es ce 5 245 EK ta SU WV ATI SET nn ets dessine Heures Ind 5 246 Compiler Library Replacement Functions ss 5 247 M MOIRES EE 5 247 MEMSO ottenere t eam ES 5 248 HANDSOME Dust eroi et E Ea dirette ee 5 249 SPPE eM T 5 250 2004 Treck Incorporated LISSCANR eec E E PE A AEEA EE 5 252 Ln hs Oc 5 254 LS EG 1 RE P 5 255 jiji ein EE 5 256 jp OD M need 5 257 epe NR 5 258 PES tH EOL MD dees 5 259 MASH OP EL 5 260 Application R ler nbe series cents as cesstetenessnseattes Ou PING Application Program Interface sense 6 4 D SCHPUON Re tin Rd memes menti 6 4 piura cL
75. Remember tfRecvInterface may not be called from an interrupt handler An example of using these calls for receive processing from a separate task is as follows void recvTask void while 1 Wait for the receive event from an ISR tfWaitReceiveInterface myInterfaceHandle Move the data into the stack tfRecvInterface myInterfaceHandle An example of using these calls for receive processing from a main line loop is as follows void main void ttUserInterface interfaceHandle int errorCode errorCode tfStartTreck treckStarted 1 Other main processing like adding and opening an interface for 4 48 2004 Treck Incorporated Integrating into Your Environment Check if Treck timers have expired tfTimerExecute Check for received packets if tfCheckReceiveInterface myInterfaceHandle TM ENOERROR Call the stack to move the data from the driver and process it Bu tfRecvInterface myInterfaceHandle Application code An example ISR handler for both of the methods would look something like this devicelsrHandler void int receivedPacketCount Store number of packets ready to be received in receivedPacketCount x Notify the stack that data is waiting to be processed x tfNotifyInterfaceIsr myInterfaceHandle receivedPacketCount 0 0 OUL 4 49 2004 Treck Incorporated Treck Real Time TCP IP User s
76. TM DEV OPTIONS RECV COPY Make the Treck stack inside the tfRecvInterface function copy received driver buffers whose sizes are smaller than the value pointed to by option ValuePtr into a newly allocated buffer Option is disal lowed on a point to point i e SLIP or PPP interface since the SLIP and PPP link layer copy the data into a newly allocated buffer Data Type unsigned short TM DEV OPTIONS SCAT RECV LENGTH Valid only if TM USE DRV SCAT RECV is defined Set the minimum number of bytes at the head of a packet that have to be contiguous If a scattered recv buffer 1s received from the driver with a first link length below that minimum that minimum number of bytes but no more than the total length of the buffer is copied into a new stack allocated buffer Default value is IM DEV DEF RECV CONT HDR LENGIH 5 154 2004 Treck Incorporated TM DEV OPTIONS XMIT TASK TM TM EV OPTIONS BOOT TIMEOUT EV OPTIONS BOOT RETRIES Programmer s Reference Turn on off usage of a transmit task Default is off Option can only be used when device interface is not opened configured Cannot turn on this option if the device interface transmit queue is used Data Type unsigned short Base number of seconds for a BOOTP DHCP request timeout BOOTP DHCP timeouts increase with each retransmission so if this value is set to two seconds the first timeout will be two seconds the second will be four seconds the t
77. TM EAP USE PROTO 1 The specified EAP authentication protocol should be used when authenticating a peer Must be one of TM_EAP IDENTITY TM _ EAP MD5 CHALLENGE TM EAP REQ PROTO 1 The specified EAP authentication protocol is required the authenticator must use this protocol when authenticating the local host Must be one of TM_EAP IDENTITY TM EAP MD5 CHALLENGE TM EAP SESSION TIMEOUT 1 Sets the maximum length of an EAP session in seconds If the session has not completed in this time authentication has failed Default 120 seconds TM EAP IDENT TIMEOUT 1 Sets the Identity Request retransmission time in seconds Default 3 seconds 7 82 2004 Treck Incorporated TM EAP IDENT RETRIES 1 TM EAP IDENT STR Any TM EAP MD5 TIMEOUT 1 TM EAP MD5 RETRIES 1 TM EAP MD5 USERNAME Any TM EAP MD5 PASSWORD Any TM EAP MD5 AUTHNAME Any Returns Value TM ENOERROR TM EINVAL TM ENOPROTOOPT Optional Protocols Sets the maximum number of Identity Requests that will be sent without a response Default 10 Sets the MD5 Challenge retransmission time in seconds Default 3 seconds Sets the maximum number of MD5S Challenge Requests that will be sent without a response Default 10 Sets the MD5 Challenge username to be used when authenticating to a peer Sets the MD5 Challenge password to be used when authenticating to a peer Sets the MD5 Challenge name to be used when acting as an authenticator Meaning Opti
78. This FTP session is non blocking and the call did not complete Previous command did not com plete TM EACCES TM ENOTCONN TM ENOTLOGIN TM BINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL The user is not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Treck Real Time TCP IP User s Manual tfFtpAppe include lt trsocket h gt int tfFtpRetr ttUserFtpHandle ftpUserHandleA ttUserFtpHandle ftpUserHandleB char TM FAR fromFileNamePtr char TM FAR toFileNamePtr Function description This function is used to append data to a file on remote FTP server correspond ing to ftpUserHandleA This function is implemented for both passive mode and normal mode and also works with both one FTP server model and two FTP servers model e One server model If the fipUserHandleB parameter is NULL then the one server model is used and the operation could be either in server active mode or server passive mode By default the server is in active mode The user needs to call tfFtpTurnPasv with the TM FTP PASSIVE MODE ON flag to turn the server in passive mode e Two server model If the fipUserHandleB parameter is non null then the two server model is used and the first session s
79. Those ports are taken from the inclusive range For PORT mode transfers to work you should have NAPT configured for the same public IP address The data connection initiated by the private server will have a private port of 20 and a synthetic public port Though unconventional this does not appear to thwart the FTP client on SunOS at least Non PORT non PASV transfers are not supported i e with the sendport option in some Unix FTP clients turned off Parameters Parameter Description interfaceHandle Interface handle of the public NAT device on which to configure an FTP server ipPublic The FTP server s public IP address network byte order ipPrivate The FTP server s private IP address network byte order portPublicMin Inclusive range of synthetic ports TM SINGLE INTERFACE HOME to be used for PASV portPublicMax Connections to the inner FTP server similar to NAPT synthetic ports ports are in host byte order 7 68 2004 Treck Incorporated Returns Value TM ENOMEM TM ENOERROR TM BINVAL Optional Protocols Meaning Insufficient memory or too many triggers already Newly allocated trigger ip s and ports initialized Erroneous use for details enable TM NAT TRACE 7 69 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNatConfigStatic include lt trsocket h gt int tfNatConfigStatic ttUserInterface interfaceHandle ttUserlIpAddress ipPublic ttUserlIpAddress ipPrivate Function De
80. USER Should the password for this user be empty this function should return TM CHAP NULL PASSWORD Parameters Parameter Description interfaceHandle The interface for which to use this authentication routine authFunctionPtr The pointer to the function to authenticate the remote user Returns Value Meaning 0 Success TM EINVAL The interface handle is invalid 7 79 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfMsChapRegisterNewPassword include lt trsocket h gt int tfMsChapRegisterNewPassword ttUserInterface interfaceHandle ttMsChapAuthenticateFunctPtr authFunctionPtr Function Description This function works with MS CHAP only It is used by the peer when it receives message from the authenticator that an expired password was used The peer will call the authFunctionPtr registered here to get a new password and then send Change Password packet to the authenticator in order to finish the authentication processing The prototype for the authentication function is defined in previous page Parameters Parameter Description interfaceHandle The interface for which to use this authentication routine authFunctionPtr The pointer to the function to authenticate the remote user Returns Value Meaning 0 Success TM_EINVAL The interface handle is invalid 7 80 2004 Treck Incorporated Optional Protocols tfEapMd5RegisterAuthenticate int tfEapMd5RegisterAuthenticate ttUserInterface inter
81. User s Manual tfStrCat int tfStrCat char stringD const char strings Function Description This function takes the content of one string and appends it to another The user of this function must make certain the contents of both strings will fit in the size allotted for the fist This function accomplishes this by overwriting the null character at the end of the first string with the first character in the second Parameters Parameter Description stringD The string to be appended strings The string appended to stringD Returns stringD 5 254 2004 Treck Incorporated Programmer s Reference tfStrChr int tfStrChr const char stringPtr int character Function Description This function searches for the low ordered byte of an integer in a string Parameters Parameter Description stringPtr Pointer to the string being searched character The integer containing the byte for which tfStrChar is searching Returns A pointer to the first match If there are no matches this function returns a null pointer 5 255 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfStrCmp int tfStrCmp const char stringPtrl const char stringPtr2 Function Description This function alphabetically compares two strings Parameters Parameter Description stringPtr1 A string stringPtr2 A string Returns Value Meaning Less than Zero stringPtr1 is less than stringPtr2 Zero stringP
82. Value Meaning Valid pointer Pointer to the result string NULL One of the parameters is bad 6 140 Application Reference tfNtGetArpHeaderStr char tfNtGetArpHeaderStr char buffer int sizePtr Description Get a string as the ARP table header with major fields Parameters Parameter Description Buffer buffer to hold the result string Its size should be TM NT ENTRY STR LEN SizePtr In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Returns Value Meaning Valid pointer Pointer to the result string NULL One of the parameters is bad 6 141 Treck Real Time TCP IP User s Manual tfNtGetTcpHeaderStr char tfNtGetTcpHeaderStr char Buffer int SizePtr Description Get a string as the TCP socket table header with major fields Parameters Parameter Description buffer buffer to hold the result string Its size should be TM NT ENTRY STR LEN sizePtr In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Returns Value Meaning Valid pointer Pointer to the result string NULL One of the parameters is bad 6 142 2004 Treck Incorporated Application Reference tfNtGetUdpHeaderStr char tfNtGetUdHeaderStr char Buffer int SizePtr Description Get a string as the UDP socket table header with major fields Parameters Parameter De
83. a bug such as mentioned immediately above temporarily putting critical sections around your entire driver send or receive function may indicate which function the error is in By moving the critical sections C 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual around you may be able to narrow down the area in which the error is occurring If you decide to do this be wary of printf statements or the like which may unexpectedly re enable interrupts 15 Double check every item in the list of common symptoms Don t assume anything don t trust your memory Everybody has made this mistake Be very careful to check everything in the list and don t make any assumptions about how you have coded something Check it C 6 2004 Treck Incorporated Debugging a Device Driver Common Symptoms and Their Causes Running Out of Memory Not calling tfSendCompleteInterface every time TM USER BUFFER LAST is passed into the driver send routine A problem with the receive ring logic For example a bug could cause a receive ring to be refilled even though the ring is already has empty buffers In this case the empty buffers would all be lost Notifying the stack of an incorrect number of received packets Though this problem will most frequently just cause the receive ring to fill up and never be emptied making the chip unable to receive any further data there are cases where it could lead to loss of memory A m
84. a counting semaphore from an ISR the functions tfKernelCreateE vent tfKernelPendEvent and KernelPostEvent use uC OS counting semaphores You can use the same code as you used in KernelCreateCountSem tfKernelPendCountSem and tfKernelPostCountSem Hooking up the Timer The best way to hook a timer to Treck from uC OS is to create a separate timer task This task simply calls TimerUpdate tfTimerExecute then OSTimeDelay 1 The OSTimeDelay 1 causes us to delay for one RTOS clock tick This task should be the highest priority of any task calling the Treck stack Task Usage All uC OS tasks are different priorities With uC OS you should have one timer task one receive task per interface and your application tasks For best performance you should create one receive task per device that calls WaitReceivelnterface and tfRecvInterface The receive tasks should have a higher priority than the application tasks but lower than the timer task B 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual RTOS Application Note for AMX 86 AMX 86 is a Commercial Off The Shelf COTS real time operating system from Kadak Products Ltd It contains counting semaphores and memory allocation AMX is broken up into two variants These are commonly referred to as the AJ Kernel and CJ Kernel AMX 86 is the AJ kernel thus all the calls to the operating system are prefixed with aj Initialization AMX 86 does not require
85. a non blocking connect call that returns TM SOCKET ERROR the user can poll for completion by calling tfGetSocketError until tfGetSocketError no longer returns TM EINPROGRESS If connect fails the socket is no longer usable and must be closed connect cannot be called again on the socket Parameters Parameter Description socketDescriptor The socket descriptor to assign a name port number to addressPtr The pointer to the structure containing the address to connect to for TCP For UDP it is the default address to send to and the only address to receive from addressLength The length of the address structure Returns Value Meaning 0 Success l An error occurred connect can fail for any of the following reasons TM EADDRINUSE The socket address is already in use TM EADDRNOTAVAIL The specified address is not available on the remote local machine TM EPFNOSUPPORT Addresses in the specified address family cannot be used with this socket TM EINPROGRESS The socket is non blocking and the current connection attempt has not yet been completed TM EALREADY connect has already been called on the socket Only one connect call is allowed on a socket 5 9 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM EBADF TM ECONNREFUSED TM EPERM TM_EINVAL TM EHOSTUNREACH TM ETIMEDOUT 5 10 2004 Treck Incorporated socketDescriptor 1s not a valid descriptor The attempt to connect was forcefully
86. addresses between 169 254 1 0 and 169 254 254 255 To configure an interface with an AUTO IP address 1 Starting the configuration The user need to call tfOpenInterface using a zero IP address zero IP netmask and setting the TM DEV IP USER BOOT flag in the flags parameter as shown in the example below Note that 1f the interface had already been opened on multi home index 0 and not closed this step can be omitted Selecting an IP address and starting the collision detection Next the user need to call tfAutoIpPickIpAddress to pick an AUTO IP address then call tfUseCollisionDetection passing that IP address and a call back function information that will be stored in the Treck stack Next the user need to call tfUserStartArpSend so that the Treck stack can start sending ARP probes to check for collisions on the IP address tfConfigAutolp provided as an example in examples VWxautoip c and described below does all this Finishing the configuration or trying another IP address The call back function will be called if either a collision has been detected non zero errorCode or when the timeout for sending the probes has expired with no collision zero errorCode If no collision has been detected then the user should call tfFinishOpenInterface with the selected AUTO IP address if tfOpenInterface with the TM DEV IP USER BOOT flag had been called earlier mhome index 0 configuration as shown in step 1 otherwise tfConfig
87. any special initialization therefore the tfKernellIniticalize should be a stub function Memory Allocation and Free AMX 86 includes dynamic memory allocation via the calls ajmget and ajmfre tfKernelMalloc should call ajmget to allocate a block of memory and tfKernelFree should call ajmfre to free a block of memory Critical Section Handling AMX 86 is used with the Intel x86 processor family For both Microsoft and Borland compilers we have included inline assembly in trmacro h to set and release critical sections If you are using another compiler you can define the macros tm kernel set critical and tm kernel release critical in trsystem h to be the appropriate inline assembly for your compiler for setting and releasing critical sections Error Logging and Warning Information Logging AMX 86 does not have any error reporting mechanism Since this is the case tfKernelError and tfKernelWarning should be written to write out to a display serial port or a predefined area of memory that can be examined via a debugger In the case of tfKernelError it should cause a CPU reset after displaying the error message Task Suspend and Resume AMX 86 does implement counting semaphores so all we need to do here is create a mapping between Treck semaphores and AMX 86 semaphores AMX 86 semaphores are pointers to an AMX ID type and should be stored in the genVoidParmPtr portion of the ttUserGenericUnion data type To create a counting semaphore we si
88. are e It can be posted to before it is pended on e Only one task waiting on the primitive will be re scheduled when a post occurs e The primitive is not tied to a specific task Note If your RTOS does not provide a counting semaphore but does have an event flag please use the implementation provided in kernel trcousem c or kernel trctsem2 c Follow the instructions given in the file you picked and in Appendix B An example of why we need this feature is as follows 1 The user calls the socket API recv in blocking mode 2 There is no data to receive so the Treck stack starts to call the pend routine 3 A context switch occurs for a receive task before the user task finished the pend call 4 The receive task processes the incoming packet and queues it to the socket the user had opened and calls post 5 A context switch then occurs back to the user task that will then finish calling pend Without the ability to post before the pend the user task calling recv will wait forever The other option is to call pend in a critical section which is VERY undesirable for a real time system A counting semaphore with an associated counter initialized to zero solves this problem so we use this primitive for task suspend and resume 4 28 2004 Treck Incorporated Integrating into Your Environment We must first look at the data type that is used to carry the counting semaphore For this we use a union of all basic types
89. as the address family for the addresses supplied in later operations on the socket These families are defined in the include file lt trsocket h gt If protocol has been specified but no exact match for the tuplet family type and protocol is found then the first entry containing the specified family and type with zero for protocol will be used The currently understood format is PF_INET for ARPA Internet protocols The socket has the indicated type which specifies the communication semantics Currently defined types are SOCK STREAM SOCK DGRAM SOCK RAW ASOCK STREAM type provides sequenced reliable two way connection based byte streams An out of band data transmission mechanism is supported A SOCK DGRAM socket supports datagrams connectionless unreliable messages of a fixed typically small maximum length a SOCK_DGRAM user is required to read an entire packet with each recv call or variation of recv call otherwise an error code of TM EMSGSIZE is returned protocol specifies a particular protocol to be used with the socket Normally only a single protocol exists to support a particular socket type within a given protocol family However multiple protocols may exist in which case a particular protocol must be specified in this manner The protocol number to use is particular to the communication domain in which communication is to take place If the caller specifies a protocol then it will be packaged into a socket level op
90. band data So with TCP the out of band data byte s are not sent ahead of the data stream but the TCP protocol can notify the remote TCP ahead of time that some out of band data byte s exist What TCP does is mark the byte stream where urgent data ends and set the Urgent flag bit in the TCP header flag field as long as it is sending data before or up to the last byte of out of band data In your application you can send out of band data by calling the send function with the MSG OOB flag All the bytes of data sent that way using send with the MSG OOB flag are out of band data bytes Note that if you call send several times with out of band data TCP will always keep track of where the last out of band byte of data is in the byte data stream and flag this byte as the last byte of urgent data To receive out of band data please see the recv section ofthis manual Parameters Parameter Description socketDescriptor The socket descriptor to use to send data bufferPtr The buffer to send bufferLength The length of the buffer to send flags See below 5 44 2004 Treck Incorporated Programmer s Reference The flags parameter is formed by ORing one or more of the following MSG DONTWAIT MSG_OOB MSG DONTROUTE Returns Value gt 0 1 send will fail if TM_EBADF TM_EINVAL TM_ENOBUFS TM EHOSTUNREACH TM EMSGSIZE TM EWOULDBLOCK TM ENOTCONN TM ESHUTDOWN Do not wait for data send to complete but rather
91. being used locally or LOM is disabled on the link 7 126 2004 Treck Incorporated Optional Protocols tf_qmGetLocalLqrTimerPeriod ttUser32Bit tfLqmGetLocalLqrTimerPeriod ttUserInterface interfaceHandle Function Description tfLqmGetLocalLqrTimerPeriod returns the negotiated period of our local LQR timer in milliseconds or 0 if we aren t using a LOR timer Parameters Parameter Description interfaceHandle The PPP interface handle as returned by tfAddInterface Returns Value Meaning 0 Either LOM is disabled on the link or we do not use a LQR timer 0 The negotiated period in millisec ond of our local LQR timer This will not be the same as the current LQR timer period if you have called tfLqmSetLqrTimerPeriod to change the LQR timer period 7 127 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tf_qmGetPeerLqrTimerPeriod ttUser32Bit tfLqmGetPeerLqrTimerPeriod ttUserInterface interfaceHandle Function Description tfLqmGetPeerLqrTimerPeriod returns the negotiated period of the peer s LQR timer in milliseconds or 0 if the peer isn t using a LQR timer Parameters Parameter Description interfaceHandle The PPP interface handle as returned by tfAddInterface Returns Value Meaning 0 Either LOM is disabled on the link or the peer does not use a LOR timer 0 The negotiated period in millisec onds of the peer s LQR timer 7 128 2004 Treck Incorporated O
92. by disabling interrupts while working on a shared data area or a shared resource Since a non preemptive operating system is by definition non preemptive we do not require that protection in this environment If you have other real time needs this may not be the operating system for you 3 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual In a preemptive operating system environment we do need to concern ourselves with the possibility that we may be preempted or swapped out by another task or interrupt service routine ISR In embedded environments we cannot have long critical sections otherwise this would inhibit our ability to operate in real time This is what our locking system is concerned with With our locking system we are able to protect a section of code over long periods of time without having the interrupts disabled on the system for long periods of time With networking it is impossible to achieve 100 percent re entrancy of the code without locking An example of this would be an application task trying to receive data at the same time as a higher priority task is trying to store data in the receive queue We are forced to protect the application task while it is updating its pointers to the receive queue otherwise the user may be returned a corrupt pointer or even worse the corrupt pointer is put into the socket entry For a non preemptive operating system this is never an issue because each task is operat
93. by hardware For addresses designers of TCP IP chose a scheme similar to physical network addressing in which each host on the Internet is assigned a 32 bit integer address called its ZP Address The clever part of IP addressing is that the integers are carefully chosen to make routing efficient An IP address encodes the identification of the network to which a host attaches as well as the identification of a unique host on that network We can follow some guidelines to break this up and analyze the format for following the rules of IP addressing Class Network Host In the simplest case each host attached to an Internet is assigned a 32 bit universal identifier as its Internet address The bits of IP addresses for all hosts on a given network share a common prefix as mentioned earlier 1 28 2004 Treck Incorporated Introduction to TCP IP Each address is a pair both network and host on that network Given an IP address its class can be determined from the three high order bits with two bits being sufficient to distinguish among the three primary classes Class A addresses which are used for a small amount of networks that have more than 65 536 hosts devote 7 bits to network and 24 bits to the host Class B addresses which are used for intermediate size networks that have between 256 and 65 536 hosts allocate 14 bits to the network and 16 bits to the host Class C addresses which are used for networks with less than
94. called Function prototype for the user supplied notify function void devNotifyFunc ttUserInterface interfaceHandle int errorCode This function will be called with the interfaceHandle passed to tfOpenInterface and with an error code value which is zero on success Example of a call with a non null second parameter Given interfaceHandle as returned by tfAddInterface and the user defined interface notify function devNotifyFunc void devNotifyFunc ttUserInterface interfaceHandle int errorCode tfUseDhcp interfaceHandle devNotifyFunc Example of a call with a null second parameter If the user does not wish to be notified of tfOpenInterface completion then he can use the predefined NULL function pointer tfUseDhcp interfaceHandle TM DEV NOTIFY FUNC NULL PTR 7 32 2004 Treck Incorporated Parameters Parameter interfaceHandle devNotifyFuncPtr Returns Value 0 TM_EINVAL TM EMFILE TM ADDRINUSE Optional Protocols Description The interface handle as returned by tfAddInterface A pointer to a function that will be called upon completion of tfOpenInterface for a DHCP configuration Meaning Success The interface handle parameter is invalid Not enough sockets to open the BOOTP client UDP socket Another socket is already bound to the BOOTP client UDP port 7 33 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUserSetFqdn int tfUs
95. calls tfAddInterface specifying a null device driver recv function Add the Interface interfaceHandle tfAddInterface OUICC SCCI linkLayerHandle tfDevEtherOpen tfDevEtherClose tfDevEtherSend ttDevRecvFuncPtr 0 tfDevFreeRecvBuffer tfDevioctl tfDevGetPhyAddr amp errorCode Next User calls the new tfUseInterfaceScatRecv API to specify the device driver scattered buffer recv function errorCode tfUseInterfaceScatRecv ttUserInterface interfaceHandle ttDevScatRecvFunc tfDevEtherScatRecvFunc If the call does not fail then the user can now call tfConfigInterface tfOpenInterface to configure an IP address on the interface Note that tfConfigInterface tfOpenInterface is unchanged if errorCode TM ENOERROR ipAddress inet_addr 208 229 201 110 netMask htonl Oxffffff00 255 255 255 0 Config the Interface errorCode tfConfigInterface interfaceHandle 4 86 2004 Treck Incorporated Integrating into Your Environment ipAddress netMask TM_DEV_SCATTER_SEND_ENB Sy 0 I Next the user calls tfRecvScatInterface instead of tfRecvInterface No copy loop back driver For testing purposes a loop back device driver has been added below link layer that uses single scattered device driver send calls and scattered device driver recv calls ttUserInterface tfUseScatIntfDriver char namePtr ttUserLinkLayer linkLaye
96. cannot disable the Treck stack dynamic memory allocation see TM DISABLE DYNAMIC MEMORY above since the Treck simple heap can only handle freeing blocks that are bigger than 4096 bytes For the same reason you cannot call tf FreeDynamicMemory if you define this macro TM SHEAP SIZE If you do define TM USE SHEAP then you also have to define TM SHEAP SIZE to give the size in bytes ofthe Treck simple heap array TM DYNAMIC CREATE SHEAP Normally the Treck simple heap 1s implemented as a static array However you can override this behavior by defining the macro TM DYNAMIC CREATE SHEAP in your trsystem h file in which case you decide how you want to implement it 1 e dynamic memory allocation specific to your RTOS by customizing the API tfKernelSheapCreate 4 14 2004 Treck Incorporated Integrating into Your Environment Complier Qualification TM_FAR This macro is used to allow access to far data on an Intel processor normally running in real mode It should be defined to far if you need to access far data For other processors it should not be defined TM_CODE_FAR This macro is used to allow access to far code sections on an Intel processor If the stack is compiled in small model you may have functions that are in other code segments that are called by the Treck protocol stack In this case you should define this macro to be far For other processors it should not be defined TM_INTERRUPT interrupt If you have a
97. checksum is to analyze the format Look at the chart below we can see that the format of an IP header provides us with certain information VER Total Length Identification FLG Total Length TTL Protocol Header Checksum Source IP Address Destination IP Address IP Options If Any Followed by DATA For our example we will plug in the following information for each of these fields 4 5 0 14 1 255 0 VER Veserion HLEN Header Length TOS Type of Service Total Length Indentification FLG Flag Fragment Offset TTL Time to Live Protocol Header Checksum Source IP Address 1 2 3 4 Destination IP Address 1 2 3 5 1 41 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Explanation of Checksums If you notice the value for the header checksum equals 0 To begin with the value for the checksum is always set to zero and then simple addition is done Now if we take the values in hexadecimal and simply add them we get a result That result is then plugged back into the original checksum computation and then sent This is all done in the format of 16 bit words Computing 4500 000E 0001 0000 FF11 0000 0102 0304 0102 0305 14C2D Our result is larger than 16 bits so we must perform the carry function 14C2D 0001 4C2E Now we must perform the ones complement 4C2D
98. client ID When flag is set to TM DHCPF FQDN ENABLE FQDN domain name length Meaning Success Bad parameter Call can only be made in INIT state prior to calling ffDhepUserStart Not enough memory 7 43 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDhcpUserStart include lt trsocket h gt int tfDhcpUserStart ttUserInterface interfaceHandle int userIndex ttUserDhcpNotifyFuncPtr dhcpNotifyFuncPtr Function Description This function allows the user to reserve a DHCP address on the Ethernet interface for another interface i e PPP for example Prior to this call the ethernet interface has to have been configured possibly using DHCP as well See tfOpenInterface for details This function starts sending a DHCP request on the Ethernet interface handle parameter The index corresponds to a unique user DHCP request It has to be between 0 and tvMaxUserDhcpEntries 1 Note that tvMaxUserDhcpEntries default value is 0 and has to be changed with a tfInitSetTreckOptions with option name TM OPTION DHCP MAX ENTRIES to a value equal to the number of DHCP IP addresses that we want to reserve for our other interface s prior to this call dhepNotifyFunc is a user supplied call back function which will be called when either the DHCP request has been successful or has timed out or when a previously leased DHCP address has been cancelled by the server If tfDhcp
99. could run out of memory since the remote TCP will delay sending ACKs Note that care should be taken not to use tfZeroCopySend when sending small buffers since we do not try and regroup small buffers with tfZeroCopySend Default value is 128 bytes SO UNPACKEDDATA TI C3x and C5x DSP platforms only If this option is enabled all socket data will be sent and received in byte unpacked format Ifthis option is disabled all socket data will be sent in a byte packed format as received from the network Default 0 disable SO REUSEADDR indicates that the rules used in validating addresses supplied in a bind call should allow reuse of local addresses SO KEEPALIVE enables the periodic transmission of messages on a connected socket If the connected party fails to respond to these messages the connection is considered broken SO DONTROUTE indicates that outgoing messages should bypass the standard routing facilities Instead messages are directed to the appropriate network interface according to the network portion of the destination address SO LINGER controls the action taken when unsent messages are queued on a socket and a close on the socket is performed If the socket promises reliable delivery of data and SO LINGER is set the system will block the process on the close of the socket attempt until it is able to transmit the data or decides it is unable to deliver the information A timeout period termed the linger interval is specified
100. errorcode tfInitTreckOptions TM OPTION DHCP MAX ENTRIES unsigned long numberSerialLines If no error errorCode tfStartTreck Add all your link layers and interfaces For Ethernet call ethernetLinkLayerHandle tfUseEthernet thernetInterfaceHandle tfAddInterface namePtr ethernetLinkLayerhandle 9j For PPP call tfUseAsyncServerPpp once and tfAddInterface for each serial line Save each PPP serial lines interface handle returned by each tfAddInterface in a table Configure the Ethernet interface with either a static IP address and IP netmask or using DHCP as shown in the Automatic Configuration paragraph above If using DHCP wait for the tfOpenInterface to complete 7 35 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Ask for a DHCP address on the Ethernet interface for one PPP interface client errorCode tfDhcpUserStart thernetInterfaceHandle userIndex dhcpNotifyFunc userIndex must be initialized to zero for the first query first PPP interface 1 for a second query etc A zero return value indicates that the DHCP request has completed successfully A TM EINPROGRESS return value indicates that a DHCP configure or request has been sent and this is OK A TM EALREADY return value indicates that a DHCP discover request has al ready been sent because of a previous call to tfDhcpUserStart If errorCode is TM EINPROGRESS or TM EALREADY wai
101. ffNotifyInterfaceTask is provided The tfCheckReceivelInterface function is used to poll the device layer for receive events The tfWaitReceiveInterface function is used to block a task until the event has occurred You must choose if you want a task to block until data has been received or poll to see if data has been received The choice that you make defines which of the functions fWaitReceivelnterface or 4 47 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfCheckReceivelnterface that you will use Note tfNotifyInterfaceIsr and or tfNotifyInterfaceTask need to be used whether the user chooses to use tf CheckReceiveInterface polling method or tfWaitReceivelnterface pending method If you do not have an RTOS you cannot use fWaitReceivelnterface If you do have an RTOS you can use tfWaitReceivelnterface but only if you define the TM TASK RECV macro in trsystem h Note Our device driver interface does NOT allow you to process packets directly from an ISR The major reason that we do not allow this is because our stack is designed for real time systems Under real time constraints we need to keep interrupt latency to a minimum It is not required to use the functions ffNotifyInterfacelIsr or and tfNotifyInterface Task tf CheckReceiveInterface and tfWaitReceiveInterface as long as you can guarantee that the tfRecvInterface call is made when there are packets to be received from the device driver
102. first 5 167 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM DEV IP USER BOOT Allow the user to temporarily configure the interface with a zero IP address to allow the user to use a proprietary protocol to retrieve an IP address from the network TM DEV IP NO CHECK Allow the Treck stack to function in promiscuous mode where all packets received by this interface will be handed to the application without checking for an IP address match on the incoming interface Returns Value Meaning 0 Success TM EADDRNOTAVAIL Attempt to configure the device with a broadcast address TM EINPROGRESS tfOpenInterface call has not completed This error will be returned for a DHCP or BOOTP configuration for example TM ENOBUFS Not enough memory to complete operation TM EINVAL Bad parameter Note that a zero IP address 1s allowed for Ethernet if the BOOTP or DHCP flag is on or for PPP otherwise a TM EINVAL errorCode is returned TM EALREADY A previous call to tfOpenInterface has not yet completed TM EPERM User attempted to configure an IP address via DHCP respectively BOOTP without having called tfUseDhcp respectively tfUseBootp successfully first TM EMFILE Not enough sockets to open the BOOTP client UDP socket TM IPDEV BOOTP or TM IP DEV DHCP configurations only 5 168 2004 Treck Incorporated TM_ADDRINUSE TM_ETIMEDOUT TM EAGAIN Other Programmer s Reference Another socket
103. for number RecvPackets numberSendCompletePackets and numberBytesSent may be 0 5 161 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns None Note This function should be called only once per Isr tfNotifyInterfacelsr replaces both tfNotifyReceivelnterfacelsr and tfNotifySentInterfacelsr 5 162 2004 Treck Incorporated Programmer s Reference tfNotifyInterfaceTask include trsocket h void tfNotifyInterfaceTask ttUserInterface interfaceHandle int numberRecvPackets int numberSendCompletePackets unsigned long numberBytesSent unsigned long flag Function Description This function notifies the stack with both the number of packets received and the number of packets transmitted by the chip This function is to be called by the user inside a Task rather than an ISR with the appropriate number of received and sent packets This will in turn cause the stack to notify the user s application about what has occurred In the case of received packets tfCheckReceiveInterface will return 0 once for each received packets if the user is in polling mode In blocking mode tfWaitReceiveInterface will return once for each received packet For sent packets tfCheckSentInterface will return 0 once for each sent packet in polling mode or tfWaitSentInterface will return once for each sent packet in blocking mode These functions only notify the user of a sent packet in the case that the accumulated num
104. for the stack An error occurred with one or more of the socket calls within the function the buffer is not large enough to hold the received file The TFTP server returned an Undefined error code message in the error packet TM TFTP NOTFOUND The TFTP server returned a File not found message in the error packet The TFTP server returned a No such user message in the error packet The TFTP server returned an Illegal TFTP 6 73 Treck Real Time TCP IP User s Manual operation message in the error packet TM TFTP BADID The TFTP server returned an Unknown transfer ID message in the error packet TM TFTP ACCESS The TFTP server returned an Access viola tion message in the error packet TM TFTP NOSPACE The TFTP server returned a Disk full alloc exceeded message in the error packet TM TFTP FILEEXISTS The TFTP server returned a File already exists message in the error packet 6 74 Application Reference tfTftpinit include lt trsocket h gt void tfTftpInit void Function description This function initializes various data associated with the TFTP client It must be called before any other TFTP client API call Parameters None Returns None Treck Real Time TCP IP User s Manual tfTftpPut include lt trsocket h gt int tfTftpPut char filename struct sockaddr remote_addr char tftpbuf unsigned long int bufsize unsigned short int mode in
105. function is used to initialize the Ethernet Link Layer Parameters None Returns The Ethernet link layer handle or NULL if there is an errorNull Link Layer API 5 201 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Null Link Layer API tfUseNullLinkLayer include lt trsocket h gt ttUserLinkLayer tfUseNullLinkLayer void Function Description This function is used to initialize the Null Link Layer Parameters None Returns The Null link layer handle or NULL if there is an error 5 202 2004 Treck Incorporated Programmer s Reference SLIP Link Layer API tfGetSlipPeerlpAddress include lt trsocket h gt int tfGetSlipPeerIpAddress ttUserInterface interfaceHandle ttUserIpAddress ifIpAddress Function Description This function is used to get the SLIP address that the remote SLIP has used This function should be called after tfOpenInterface has completed successfully If a default gateway needs to be added for that interface then the retrieved IP address should be used to add a default gateway through the corresponding interface If a static route needs to be added for that interface then the retrieved IP address should be used to add a static route through the corresponding interface Parameters Parameter Description interfaceHandle The interface Handle to get the Peer IP address from ifIpAddressPtr The pointer to the buffer where the Peer slip IP address will b
106. if your processor is big endian or little endian Endian refers to the byte order of integers both long and short on the processor For more information on the difference between big and little endian please see the chapter Introduction to TCP IP TM_LITTLE_ENDIAN This macro is used to let the stack know at compile time that the processor is a little endian processor If you choose to use this macro on a big endian processor you will see your packets with the word fields reversed TM_BIG_ENDIAN This macro is used to let the stack know at compile time that the processor is a big endian processor If you choose to use this macro on a little endian processor you will see your packets with the word fields reversed Memory Allocation TM_USE_SHEAP If the user defines this macro the stack allocates its blocks of memory from the Treck simple heap static array using the simple heap allocation routine tfSheapMalloc instead of calling the RTOS ffKernelMalloc Similarly the Treck stack will release an allocated block of memory of size bigger than 4096 bytes by calling the Treck simple heap free routine zfS heap Free instead of calling the RTOS ffKernelFree The user will define this macro if the user s RTOS does not provide heap management routines or if the user does not want the Treck stack to allocate its blocks of memory from the RTOS heap Note that if you define this macro and thereby do use the Treck stack simple heap you
107. int tfTestUserExecute ttUserTestHandle testSessionHandle Function description Called in non blocking mode to execute an iteration of the current test using the session handle returned from tfTestTreck If tfTestUserExecute returns TM EWOULDBLOCK the test has not yet completed any other return value indicates that the test is complete and tf TestUserExecute should not be called with this session handle again This function should never be called in blocking mode Parameters Parameter Description testSessionHandle Session handle returned from tfTestTreck Returns Value Meaning TM ENOERROR The current test has completed successfully TM EWOULDBLOCK The current test has not yet completed The user should call tf TestUserExecute again TM EINVAL Invalid session handle TM EIO Incoming data failed validation 6 136 Application Reference Netstat Introduction The netstat tool outputs useful information retrieved from the stack such as the routing table the ARP table the UDP socket table and the TCP vector table A user can pick the information he is interested in and output it in the prefered way through the call back functions The netstat API consists of a set of data structures a function tfNetStat that enumerates the table entries a callback interfaces ttNtEntryCBFuncPtr that handles each entry and a set of helper functions The helper functions facilitate the writing of user call back functions They p
108. is an extension of TLI that allows access to both TCP IP and NetBios Overview of How Sockets Works BSD Sockets generally relies upon client server architecture For TCP communications one host listens for incoming connection requests When a request arrives the server host will accept it at which point data can be transferred between the hosts UDP is also allowed to establish a connection though it is not required Data can simply be sent to or received from a host The Sockets API makes use of two mechanisms to deliver data to the application level ports and sockets Ports and sockets are one of the most misunderstood concepts in sockets programming All TCP IP stacks have 65 536 ports for both TCP and UDP There is a full compliment of ports for UDP numbered 0 65535 and another full compliment with the same numbering scheme for TCP The two sets do not overlap Thus communication over both TCP and UDP can take place on port 15 for example at the same time A port is not a physical interface it is a concept that simplifies the concept of Internet communications for humans Upon receiving a packet the protocol stack directs it to the specific port If there is no application listening on that port the packet is discarded and an error may be returned to the sender However applications 2 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual can create sockets which allow them to attach to a port Once
109. is that when any Class C network grows to more than 255 hosts 1t must have its address changed to a Class B address Note If a host computer moves from one network to another its IPaddress must change 1 30 2004 Treck Incorporated Introduction to TCP IP Dotted Decimal Notation When communicating to humans in either technical documents or through application programs IP addresses are written as four decimal integers separated by decimal points Each integer gives the value of one byte of the IP address For example 10000000 00001010 00000010 00011110 is written 128 10 2 30 When we express IP addresses we will use dotted decimal notation This table summarizes the range of values for each class of IP addresses Class Lowest Address Highest Address 1 0 0 1 126 255 255 254 128 1 0 1 191 255 255 254 192 0 1 1 223 255 255 254 224 0 0 0 239 255 255 255 240 0 0 0 247 255 255 255 Fig 1 20 IP Address Denotations Loopback Address In Figure 1 20 we see that not all possible addresses have been assigned to classes For example address 127 0 0 0 a value from the class A range is reserved for loopback and is intended for use in testing TCP IP and for inter process communication on the local machine When any program uses the loopback address for the destination the computer returns the data without sending the traffic across any network A host or router should never propagate routing or reachabili
110. just described is called a directed broadcast address because it contains both a valid network ID and the broadcast host ID A directed broadcast can be interpreted unambiguously at any point on the Internet because it uniquely identifies the target network in addition to specifying broadcasts on that network Directed broadcast addresses provide a powerful and somewhat dangerous mechanism that allows a remote system to send a single packet that will be broadcast on the specified network From an addressing point of view the chief disadvantage of directed broadcast is that it requires knowledge of the network address A limited broadcast address provides a broadcast address for the local network independent of the assigned IP address The local broadcast address consists of 32 5 it is sometimes called the all 5 broadcast address A host may use the limited broadcast address as part of a start up procedure before it learns its IP address or the IP address for the local network Once the host learns the correct IP address for the local network it should use the directed broadcast As a general rule TCP IP protocols restrict broadcasting to the smallest possible set of machines Drawbacks in Internet Addressing Encoding network information in an Internet address does have some disadvantages The most obvious disadvantage is that addresses refer to network connections not to the host computer Another weakness of the Internet addressing scheme
111. layer protocol on this link datagrams from that network layer protocol may be sent over the link The link will remain available for communications until it is explicitly closed This can happen at the LCP or NCP level either by administrator intervention or through a time out interrupt Specific network layer protocols can be enabled and disabled on the link at any time without affecting the capability of the PPP link to support other network layer protocol transmissions 1 27 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Understanding IP Addresses This section describes the underlying concepts if IP addresses We will discuss the format of an IP address the concepts of a sub netting and super netting and why we use them Let s first look at basic IP address formatting IP Address Format IP addresses are a standard 32 bits long Figure 1 19 shows the format of an IP address 208 229 201 0 Fig 1 19 Sample IP Address Format The class field can be defined by the first three numbers of the IP address In our example the number would be 208 There are three types of classes They are Class A Class B and Class C Think of an Internet as a large network like any other physical network The difference is that the Internet is a virtual structure that is implemented entirely in software This allows the designers to choose packet formats and sizes addresses delivery techniques and so on Nothing is dictated
112. must be configured There are three types of Inner Servers TCP FTP and UDP In each case an inner private IP address and port number are associated with an outer public IP and port Clients on the public network call the public values NAT translates this traffic to the private server s values NAPT and Inner Server support only TCP and UDP traffic Multiple IP addresses The two types of resources in this environment are Static and Dynamic public IP address assignments A Static assignment associates one public IP address at a time with one private address permanently A Dynamic assignment does so automatically as needed New dynamic address associations are initiated only by outbound TCP SYN packets or by any outbound packets of another protocol for example UDP DNS or ICMP Ping A Dynamic assignment expires when no packets have crossed for a certain amount of time default 15 minutes TM NTRTTL DYNAMIC in trmacro h Expired Dynamic associations become available for use by other private parties As individual TCP and UDP sessions are not tracked on a Dynamic assignment the timeout does not discriminate connection status or traffic type Static assignments would be useful for servers on the inside network or for users who require consistent full featured access to the public network Dynamic and Static assignments support almost all IP traffic including TCP UDP and ICMP 7 60 2004 Treck Incorporated Optional Protocols
113. no longer owns its buffer The only exception is when TM SOCKET ERROR is returned and the errorCode retrieved with ffGetSocketError is TM EWOULDBLOCK In that case the user still owns its buffer and should try and re send the same buffer later on The userFreeFunction will be called by the Treck stack for each user buffer if an error other than TM EWOULDBLOCK occurs or when the data has been sent out on the network and the device driver no longer need to access the data in the user buffer It is the user s responsibility to ensure that the user free function Is re entrant as it could potentially be called from different threads unless the user uses a different free function per user application thread and the user does not use a Treck transmit task and does not use a Treck send complete task Example of tfZeroCopyUserBufferSendTo usage is shown in the loop back test module txscatlp c 5 114 2004 Treck Incorporated Parameters Parameter socketDescriptor userBufferPtr userDataPtr userDataLength userFreeFunction flags Returns Value gt 0 TM SOCKET ERROR Error codes Value TM EWOULDBLOCK TM BINVAL TM ENOBUFS TM EBADF TM EMSGSIZE TM EHOSTUNREACH Programmer s Reference Description As returned by a socket call pointer to user buffer to be used when calling the user free function pointer to user data size of user data User free function called by the stack when the buffer is no longer accessed b
114. not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Command not implemented for that parameter Service not available closing TELNET connection Treck Real Time TCP IP User s Manual TM_FTP_FILENAVAIL Requested file action not taken file unavailable TM FTP NAVAIL Requested action not taken file unavailable TM FTP NEEDACCTFILE Need account for storing files TM FTP FILENAME Request action not taken file name not allowed TM FTP NOTLOGIN Not logged in Application Reference tfFtpRetr include lt trsocket h gt int tfFtpRetr f ttUserFtpHandle ftpUserHandleA ttUserFtpHandle ftpUserHandleB char TM FAR fromFileNamePtr char TM FAR toFileNamePtr Function Description This function is used to retrieve a file from remote FTP server corresponding to ftpUserHandleA This function is implemented for both passive mode and normal mode and also works with both one FTP server model and two FTP servers model e One server model If the fipUserHandleB parameter is NULL then the one server model is used and the operation could be either in server active mode or server passive mode By default the server is in active mode The user needs to call tfFtpTurnPasv with the TM FTP PASSIVE MODE ON flag to turn the server in passive mode e Two server mode
115. number of milliseconds to wait This task should be the highest priority of any task calling the Treck stack Task Usage All AMX 86 tasks are different priorities With AMX 86 you should have one timer task one receive task per interface and your application tasks For best performance you should create one receive task per device that calls tfWaitReceivelnterface and tfRecvInterface The receive tasks should have a higher priority than the application tasks but lower than the timer task AMX 86 System Configuration Module With the system configuration tool for AMX 86 you will need to define the maxi mum number of semaphores and tasks The maximum number of tasks is calcu lated from the following formula MaxTasks ReceiveTasks SendCompleteTaskst XmitTasks TimerTask ApplicationTasks The absolute maximum number of semaphores needed by the is calculated via the following formula MaxSemaphores NumberInterfaces NumberTasksPerInterface Max Tasks NumberTasksPerInterface is the number of tasks that are dedicated to interface B 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual processing The maximum this can be is 3 RecvTask SendCompleteTask XmitTask This is controlled via defines in trsystem h Maximum Stack Size should not exceed 2048 Selecting too small of a stack can lead to unpredictable behavior Treck does not require any AMX timers since we are using a separate Timer task B 8 2004 Treck In
116. of the fil Character and length parameters was reversed Parameters Parameter Description buffer Beginning of area to fill fillCharacter What to fill the area with length Length of area to fill Returns Number of bytes filled 5 248 2004 Treck Incorporated Programmer s Reference tfQSort include lt trsocket h gt void tfOSort void a unsigned int Ti unsigned int es ttCmpFuncPtr cmpFuncPtr Function Description tfQsort sorts the array pointed to by a There are n elements of size es in this array These elements are sorted according to a comparison function pointed to by cmpFuncPtr This function is defined as typedef int ttCmpFuncPtr const void parmPtrl const void parmPtr2 This function should take the two parameters parmPtr1 and parmPtr2 and should return if the first element is greater than the second 0 if they are equal or 1 if the first element is less than the second Parameters Parameter Description a Pointer to the array to be sorted n Number of elements in the above array es Size of each element in the array cmpFuncPtr Pointer to the function used to compare array elements Returns Nothing 5 249 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSPrintF int tfSPrintF char buffer const char format Function Description This function writes formatted data to an array using the following format specifiers Examples call
117. of the user data in the user buffer and the user data length in the user buffer 5 187 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ttDruBlock fields Description druDataPtr points to beginning of data druDataLength indicates the data length druBufferPtr pointer to be passed to the device driver free function if user sets the flag to TM DEV SCAT RECV USER BUFFER in the driver recv call function See flagPtr below druStackBufferPtr pointer to stack pre allocated user buffer if user sets the flag to TM DEV SCAT RECV STACK BUFFER in the driver recv call function See flagPtr below If the device driver scattered recv function sets flagPtr to TM DEV SCAT RECV STACK BUFFER then druStackBufferPtr should point to a buffer pointed to by the first parameter of either tfGetEthernetBuffer or tfGetDriverBuffer and the stack will be responsible for freeing that buffer when the stack is done processing that buffer If the device driver scattered recv function sets flagPtr to TM DEV SCAT RECV USER BUFFER then druBufferPtr points to a user allocated buffer When the stack is done processing that buffer the stack will call the device driver free function as set in tfAddInterface The user is responsible for managing the memory containing the array of ttDruBlock It is guaranteed that when the stack calls the modified driver recv function on an interface the array of ttDruBlock previously given to t
118. on the type of NAT implementation One IP address The two types of resources when there is only one public IP address to work with are NAPT and Inner Servers Several machines can access a public network through a NAT router using a single public IP address This is technically NAPT the P refers to the tricks of port number translation that are used to distinguish several processes on several machines inside the private network Normally TCP and UDP port numbers distingish several processes but only on one machine tfNatConfigNapt assigns a range of synthetic port numbers to a public address on a public NAT interface NAT draws from those ports to support every TCP and UDP connection that crosses the stack between private and public networks actually between a public network and any other 7 59 2004 Treck Incorporated Treck Real Time TCP IP User s Manual NAT connections are timed out based on traffic See NAT NTRTTL constants in trmacro h Default timeouts are Incomplete TCP connections 1 minute Completed TCP connections 24 hours Terminated TCP connections 1 minute unmade FTP PORT connections 5 minutes UDP DNS queries 1 minute non DNS UDP queries 5 minutes ICMP packets with identifier 5 minutes NAPT only supports connections initiated outbound private client public server In order for a server on the private network to be accessible to a client on the public network in a NAPT environment an Inner Server
119. options at the socket level protocolLevel is specified as SOL SOCKET To manipulate options at any other level protocolLevel is the protocol number of the protocol that controls the option For example to indicate that an option is to be interpreted by the TCP protocol protocolLevel is set to the TCP protocol number For getsockopt the parameters option ValuePtr and optionLengthPtr identify a buffer in which the value s for the requested option s are to be returned For getsockopt optionLengthPtr is a value result parameter initially containing the size of the buffer pointed to by optionValuePtr and modified on return to indicate the actual size of the value returned optionName and any specified options are passed un interpreted to the appropriate protocol module for interpretation The include file lt trsocket h gt contains definitions for the options described below Options vary in format and name Most socket level options take an int for option ValuePtr SO LINGER uses a struct linger parameter that specifies the desired state of the option and the linger interval see below struct linger is defined in lt trsocket h gt struct linger contains the following members onoff on l off 0 l linger linger time in seconds The following options are recognized at the socket level SOL_SOCKET protocolLevel options Description SO_ACCEPTCON Enable disable listening for connections listen turns on this option SO_DONTROUTE E
120. or PPP interface user application task or recv task or timer task does not have to wait inside the device driver send function for the device to be ready to transmit No Transit No overhead The sending thread i e user Task No application task or recv task Transmit or timer task has to wait ina Queue busy loop inside the device driver send function for the device to be ready to transmit This is minimal with an Ethernet device While the sending thread is waiting no other task can access any other device driver function In particular the recv task could not access the driver recv function E 4 56 2004 Treck Incorporated Integrating into Your Environment tfNotifyInterfacelsr tfCheckSentInterface tfWaitSentInterface and tfSendCompleteInterface Functions This group of functions is used to allow the user to notify the stack that a send complete event has occurred so that the event can be processed at main task level instead of from the ISR In other words the first three functions are used to tell the user when to call tfSendCompleteInterface tfSendCompletelnterface may not be called directly from an interrupt handler The fNotifyInterfacelsr function is used to notify the stack from an ISR that the data buffer is not in use by the device driver anymore The CheckSentInterface function is used to poll the device layer for send complete notify events The fWaitSentInterface function is used to block
121. or socket is already bound TM_EINPROGRESS tfBindNoCheck is already running 5 72 2004 Treck Incorporated Programmer s Reference tfBlockingState include lt trsocket h gt int tfBlockingState int socketDescriptor int blockingState Function Description This function is used to set blocking or non blocking on a socket as the default mode of operation This can be overridden with the MSG DONTWAIT flags on subsequent calls The tfloctl call with the FJONBIO request can be used instead of the tfBlockingState call Parameters Parameter Description socketDescriptor The socket descriptor to set the non blocking flag on blockingState One of the following TM BLOCKING OFF TM BLOCKING ON Returns Value Meaning 0 Success 1 Error tfBlockingState can fail for the following reason TM_ EBADF The socket descriptor is invalid TM EINVAL blockingState parameter is invalid 5 73 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfFlushRecvQ include lt trsocket h gt int tfFlushRecvQ int socketDescriptor Function Description This function flushes the socket receive buffer for the specified socket This can be useful with UDP sockets to flush queued packets that are too big for the application to process i e when the call to recvfrom returns TM EMSGSIZE Note that this function flushes all packets queued to be received on the specified socket Parameters Parameter Descrip
122. our software we utilize the TCP IP or Internet protocol suite set of rules These rules are outlined in loose specifications called Request for Comments RFC s An RFC is submitted by anyone who thinks that some change or addition to the Internet protocol suite needs to happen This proposed RFC is sent to the appropriate working group at the Internet Engineering Task Force IETF for comments by others who are involved with that working group If others in the working group agree with the proposed idea then they may ask for some changes and adopt the RFC as a Standards Track document If they reject the idea then the RFC can still be published as an Informational RFC Standards Track documents describe what the protocol should do in all implementations Informational RFC s describe what a vendor would like others to implement There are other types of RFC s but most are beyond the scope of this document You can visit the IETF web site at http www ietf org If you are looking for a particular RFC it is always easier to locate the repository closest to you via a web search engine such as Altavista Infoseek and Yahoo 1 4 2004 Treck Incorporated Introduction to TCP IP The TCP IP Protocol Stack A stack architecture divides out the functionality of a data communications capability into several separate layers Each layer then communicates with its peer layer on remote machine or on the same machine Rather tha
123. prototype for the link quality monitoring function specified by monitorFuncPtr is defined as follows ttUser8Bit myLinkQualityMonitor ttUserInterface interfaceHandle int reasonCode unsigned long timeElapsedMsec ttLqrCountDeltasPtr countDeltasPtr ttConstLqrCountsPtr countsPtr ttUser32Bit outLqrs ttUser32Bit outPackets ttUser32Bit outOctets reasonCode can take on the values TM LOM MONITOR LQR or TM LQM MONITOR TIMEOUT depending on whether the reason for the callback is that a Link Quality Report message was received TM LOM MONITOR _LQR or that the timeout occurred before the solic ited expected Link Quality Report message was received TM LQM MONITOR TIMEOUT timeElapsedMsec is the time elapsed in milliseconds since the last time the link quality monitoring function was called outLqrs is the count of LQRs sent outPackets is the count of packets sent and outOctets is the count of bytes sent NOTE since these are unsigned 32 bit counters they may wrap around to 0 When reasonCode is set to TM LOM MONITOR LQR 1 countDeltasPtr points to the absolute counts of packets and bytes sent and received as reported by the peer in the received Link Quality Report message since the last time the link quality monitoring function was called N countsPtr points to the relative counts of packets and bytes sent and received as reported by the peer in the received Link Quality Report message You must not change any of t
124. re enable interrupt when posting on an event therefore causing our counter update in tfNotifyInterfacelsr to become non re entrant Example void myDevicelsrHandler void int recvPacketCount int sendCompletePacketCount unsigned long totalBytesSent recvPacketCount 0 sendCompletePacketCount 0 totalBytesSent 0 Check for receive interrupt if receivedData Accumulate number of packets ready to be received recvPacketCount Check for send complete interrupt if sendComplete 4 69 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Accumulate number of packets that have been transmitted sendCompletePacketCount Accumulate sent packet data sizes totalBytesSent packetDataSize Call this function only once tfNotifyInterfaceIsr myInterfaceHandle receivedPacketCount sendCompletePacketCount totalBytesSent OUL Dismiss the interrupt Special case when the user uses the Treck pool to be able to get a Treck buffer and to copy the received data to it within the receive ISR Recall that in that case the user has called PoolCreate in the device driver open function The user calls PoollsrGetBuffer inside the ISR to get a pre allocated Treck buffer from the Treck pool so that the incoming network data can be copied inside the ISR Example myInterfaceHandle initialized in deviceOpen static ttUserInterface myInterfaceHan
125. rejected The calling program should close the socket descriptor and issue another socket call to obtain a new descriptor before attempting another connect call Cannot call connect after listen call One of the parameters is invalid No route to the host we want to connect to The calling program should close the socket descriptor and should issue another socket call to obtain a new descriptor before attempting another connect call Connection establishment timed out without establishing a connection The calling program should close the socket descriptor and issue another socket call to obtain a new descriptor before attempting another connect call Programmer s Reference getpeername include lt trsocket h gt int getpeername int socketDescriptor Struct sockaddr fromAddressPtr int addressLengthPtr Function Description This function returns the IP address Port number of the remote system to which the socket 1s connected Parameters Parameter Description socketDescriptor The socket descriptor that we wish to obtain information about fromAddressPtr A pointer to the address structure that we wish to store this information into addressLengthPtr The length of the address structure Returns Value Meaning 0 Success l An error occurred getpeername can fail for any ofthe following reasons TM EBADF socketDescriptor is not a valid descriptor TM ENOTCONN The socket is not connected
126. should return TM CHAP NULL PASSWORD Parameters Parameter Description interfaceHandle The interface for which to use this authentication routine authFunctionPtr The pointer to the function to authenticate the remote user Returns Value Meaning 0 Success TM EINVAL The interface handle is invalid 7 78 2004 Treck Incorporated Optional Protocols tfMsChapRegisterAuthenticate include lt trsocket h gt int tfMsChapRegisterAuthenticate ttUserInterface interfaceHandle ttMsChapAuthenticateFunctPtr authFunctionPtr Function Description This function works with MS CHAP only You need to define TM USE PPP MSCHAP in trsystem h to use MS CHAP When acting as a PPP server a function must be called to validate an incoming authentication request This function is passed the username and will return the secret pass word and the secret length for this particular username Chap module will further compute the challenge using this secret and compare with the chal lenge given by the peer If both challenge match the peer 1s positively authenti cated otherwise the peer is denied The prototype for the authentication function 1s defined to be char myMsChapAuthenticate char username int secretLenPtr which returns the secret corresponding to this username and the length of secret will be returned in secretLenPtr If the user name passed to myChapAuthenticate is invalid this function should return TM CHAP INVALID
127. since the current task could be pre empted by a higher priority task during the OS call int tfKernel ttUserContext contextHandle contextHandle tfGetCurrentContext lt Make the OS call gt tfSetCurrentContext contextHandle Preemptive Kernel In this case the OS could switch out a task at any time 1 Ifthe user can modify the OS and can save the current Treck context on a task stack prior to a task being switched out and restore the task Treck context when the task runs then the applications can also run in blocking mode as described in the previous section a Each application task will have to set its Treck context prior to making the first Treck call b The user will need to modify the OS and save the current Treck context on a task stack prior to a task being switched out and restore the task Treck context when the task is scheduled to run A 14 2004 Treck Incorporated Configuration Notes If the user cannot modify the OS then all the applications will have to run in non blocking mode from a single Treck task All the calls to the Treck stack will be made from a main loop from within that single task as described in the No OS section above Device Driver Modifications Each device driver should be modified as described in the Further Device Driver Modifications to allow a device driver to be shared by several Ethernet Interfaces section of chapter 4 of this manual The modification to
128. socket was created successfully if testSocket TM_SOCKET_ERROR returnVal tfGetSocketError testSocket errorStr tfStrError returnVal 2 10 2004 Treck Incorporated Introduction to BSD Sockets goto udpServerEnd Bind the socket to the port and address at which we wish to receive data ey errorCode bind testSocket amp destAddr sizeof destAddr Check for an error in bind if errorCode lt 0 returnVal tfGetSocketError testSocket errorStr tfStrError returnVal goto udpServerEnd Do this forever while 1 Get the size of the sockaddr_in structure addrLen sizeof sourceAddr Receive data The values passed in are We receive said data on testSocket The data is stored in testBuffer We can receive up to TM_BUF_SIZE bytes There are no flags we care to set Store the IP address port the data came from in sourceAddr Store the length of the data stored in sourceAddr in addrLen The length that addrLen is set to when it s passed in is used to make sure the stack doesn t write more bytes to sourceAddr than it should Ey ee X X 0X FH errorCode recvfrom testSocket testBuffer TM BUF SIZE 0 amp sourceAddr amp addrLen Make sure there wasn t an error in recvfrom if errorCode 0 returnVal tfGetSocketError testSocket errorStr tfStrError returnVal break udpServerEnd Make sure we have an
129. test wees easseenes sedg Eve spese da 5 108 t ZeroCopySend IO rerit EEr a FHn P EE EE SEEPS TESE ESES 5 110 t ZeroCopyUserBulterSend nitrate hee tenete eae 5 112 tfZeroCopyUserBufferSendTo sssssssseeeeeeneennns 5 114 API Call Back Function Registration ss 5 116 E REBEISCESOCKetC B soesoenan eea Erer eE EEEa Eea eue cbe tpeenteoness 5 116 tfRegisterSocketCDBbParam ies eerie terrse eee dtes secta te ak 5 120 Treck Initialization Functions ecce eese ee eere eene eee en nnne n net tnue 5 122 tnit Wreck Options rp 5 122 tS SEITE CK OP EONS ne ere en tu eere Eo eeareeteoasa 5 126 LISA TSK ER ee ass Pee ee e 5 129 Device Interface APE scssccstscivecsscsnscsscccesscesveccuccsevseuseveess 5 130 tEAddInterface cao ROUTE HUN TIER EIUS 5 130 tfAddInterfaceMhomeA ddress sese 5 133 tfCheckRecetrvelntertfaee sr o reete RE ERE CO E eire 5 135 tfCheckSentInterface ccc cccccesceesecseecesecescecseecsseeeeeecseceseeesseeesaeenseees 5 136 tfCheckXmuitlnterttace aureo d tein RR ERE ERE ten 5 137 tfCloseInterface ottenere rere e pH FEI dn 5 138 tiConfig Interface ee eerte nen e reed ert meris ee dede eee te d 5 139 tf DeviceClearPointet uices rer te tee a RE Ete ta 5 143 tilDeviceGetPoIntet iai a v viene eee eee EA HER CREER 5 144 tfDeviceStorePointer ssesssssseseee eee 5 145 ttFimishOpenlInterface 2 arte detente eee eee cede atu 5 146
130. tfFreeDrverBuffet 2 rrr riter terr ent aeter pan 5 147 tfGretDriverBullet e oe eren icr HUI ERUNT EE ONERE ret NTE 5 148 2004 Treck Incorporated tfGetBroadcastAddress cccicscsscccssesecevecevesscnceevecsesncesugevpusecsveedevsecnccsdsessenes 5 149 SERGE D NNA KnT E EET 5 150 tiGetIpAddtess cca vise dra es EEr e ode i Tei DR ER EEEO ESES 5 151 amp fGetNetMAask 5 eere Ro eb perenne d 5 152 ttInterfaceGet VirtualCharinel 3 een rrt HE Hee E EE vr ni 5 153 ftirterface Set ODLDIODS nd dette tirent 5 154 tt Interfaceset VartualChannel sn tro rre itte eei e rr 5 157 ktlsiterfaceS DIN OCR no urere p Hr RARO TXFOF UI Ere EEE SE 5 158 tfloctlInterface sevo EE aba EMI teen Er ONIS 5 159 HNotity Inte Haee ISE 5st trt tiere eei uice rati Pe de 5 161 tiNotify interface l aSk sises erret eere ne ette etae tete eat 5 163 t NotityReceivelInterface sE uui Irc tte Etre ti rere HH rtg 5 164 t NotifySentInterfacelIsr ses messieurs 5 164 HEMP CMTC TAGS eme died ltd 5 164 LIPODICTEALS cootra mme ei 5 170 t PoolDelete u oni uU n rue eter 5 172 tfPoolIsrEreeBUffet i et RR aue av ba eR EE 5 173 tfPoolIsrGetBuffer cer rrt iter rint En ERR PEERS 5 174 LIPOOIREC IVE Re cm nt de 5 175 tiRecy Interfaces ee oet ea armenta ee 5 176 amp tRecvScaltltterfa e icio e ee DR RU HERE 5 177 itSendCompleteInterface a eicere rte rre rester 5 178 tfSendCompletePacketInterface essen 5 179 bits COTES o oce ce e
131. tfTeldSendQueueBytes ttUserTeldHandle teldHandle Function Description This function returns the number of bytes currently in the TCP socket send queue for the Telnet session identified by teldHandle Parameters Parameter Description teldHandle Telnet handle unique identifier for a telnet connection Returns Value Meaning gt 0 The number of bytes currently in the TCP socket send queue for the specified Telnet session 1 An error occurred Invalid telnet handle specified 6 119 Treck Real Time TCP IP User s Manual tfTeldSendQueueSize include lt trsocket h gt int tfTeldSendQueueSize ttUserTeldHandle teldHandle Function Description This function returns the total size of the TCP socket send queue for the Telnet session identified by teldHandle Parameters Parameter Description teldHandle Telnet handle unique identifier for a telnet connection Returns Value Meaning gt 0 The total size of the TCP socket send queue for the specified Telnet session 1 An error occurred Invalid telnet handle specified 6 120 Application Reference tfTeldUserClose include lt trsocket h gt int tfTeldUserClose ttUserTeldHandle teldHandle Function description This function allows the user to force the telnet server to close the specified telnet connection Parameters Parameter Description teldHandle Telnet handle Unique identifier for a telnet connection Returns Value
132. the socket for the duration of the call Parameters Parameter socketDescriptor bufferPtr bufferLength Returns Value gt 0 zj tfWrite will fail if TM_EBADF TM_ENOBUFS TM EHOSTUNREACH TM EMSGSIZE TM EWOULDBLOCK 5 68 2004 Treck Incorporated Description The socket descriptor to use to send data The buffer to send The length of the buffer to send Meaning Number of bytes actually sent on the socket An error occurred The socket descriptor is invalid There was insufficient user memory available to complete the operation Non TCP socket only No route to destination host The socket requires that message to be sent atomically and the message was too long The socket is marked as non blocking and the write operation would block Programmer s Reference writev include lt trsocket h gt int writev int socketDescriptor const struct iovec iov int iovcnt Function Description writev functions as a scatter write because the written data can be placed in multiple buffers writev attempts to write data to the socket socketDescriptor by gathering the data from into the iovcnt buffers specified by the members of the iov array iov 0 iov 1 iov iovent 1 The iovec structure contains the following members caddr tiov base intiov len Each iovec entry specifies the base address and length of an area in memory from where data should be gathered w
133. the Treck stack to send one or more ARP requests with the configured IP address as the source address The user will pass the interface handle the IP address to check for collision a maximum number of ARP probes requests the interval of time between ARP probes requests and a timeout parameter We send an ARP probe request on the interface s specified by the interface handle create a timer and return If numberArpProbes is bigger than one then the Treck stack in the context of the timer task will send numberArpProbes 1 additional ARP probes requests every time the arpProbelInterval expires e tfUseCollisionDetection has to be called before tfUserStartArpSend is called e Ifa matching ARP reply request probe is received before all ARP probes have been sent the Treck stack will stop sending any more ARP probes cancel the timer and call the user call back function with a TM EADDRINUSE error code If a matching ARP reply request is received before all ARP requests have been sent the Treck stack will stop sending any more ARP probes cancel the timer and call the user call back function with a TM EADDRINUSE error code e When the timeout parameter expires the Treck stack will stop sending any more ARP probe s request s cancel the timer and will call the user call back function passed by the user in tfUseCollisionDetection with a TM ENOERROR error code 7 13 2004 Treck Incorporated Treck Real Time TCP IP Us
134. the device interface send queue The packet is sent in the context of the caller of this function Parameters Parameter Description interfaceHandle The Interface Handle of the device to which to send data Returns Value Meaning 0 Success TM ENOENT No packet was ready to be transmitted TM ENXIO Device interface was not opened or configured TM EIO Device driver send function returned an error The Treck stack freed the packet since the device driver send failed 5 199 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Ethernet Link Layer API tfGetEthernetBuffer include lt trsocket h gt char tfGetEthernetBuffer ttUserBufferPtr userBufferPtr Function Description This function is used to get a buffer from the system for the user to use for an Ethernet device The data pointer is offset by two bytes to allow the data portion to be long word aligned It is not required for a user to use our buffer pool because some devices may not support it Parameters Parameter Description userBufferPtr A pointer to a ttUserBuffer variable that the user buffer handle is stored Returns A char to the beginning of the data area to store the received data into or a NULL pointer if there is no memory to complete the operation 5 200 2004 Treck Incorporated Programmer s Reference tfUseEthernet include lt trsocket h gt ttUserLinkLayer tfUseEthernet void Function Description This
135. the remote file system Rename a remote file Aborts the transfer in progress Deletes a remote file Removes a remote directory Creates a directory Retrieves the present working directory Retrieves a directory listing Returns information about the system hosting the remote file system Retrieves help from the FTP server about a command Sets the FTP transfer mode Does nothing used to keep an idle connection open Sets the port used for incoming data connec tions Returns the full text reply from the last executed command Called only in non blocking mode Should be called periodically to allow the FTP client to 6 31 Treck Real Time TCP IP User s Manual continue to process requests Return Codes All of the functions in the FTP Client API return standard error codes In cases where the call itself succeeded but the FTP server returned an error a different but mutually exclusive set of error codes are used These constants are included with each of the user interface calls below and all begin with TM_FTP For further information on the meaning of these codes please see RFC 640 Application Reference tfFtpAbor include lt trsocket h gt int tfFtpAbor ttUserFtpHandle ftpSessionPtr Function description This function aborts the current file transfer in process Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK
136. the unique user data pointer as returned by tfFSUserLogin and a file data pointer as returned by tfFSOpenFile this function reads until it reaches bufferSize bytes or end of record whichever comes first If end of record has been reached it stores 1 in the integer pointed to by eorPtr otherwise it stores 0 If the file system does not support records then the system end of line i e lt CR gt lt LF gt for DOS lt LF gt for Unix is used for the end of record This routine should convert every end of line i e lt CR gt lt LF gt for DOS LF for Unix to an end of record i e store 1 in eorPtr when the end of line character s have been read the end of line character s themselves should not be copied into the buffer pointed to by bufferPtr To indicate that end of file was reached this routine stores 0 in eorPtr and returns 0 to indicate that no characters were read Note that if 1 is stored in eorPtr this does not indicate end of file since when a blank line consisting of nothing but the end of line characters i e lt CR gt lt LF gt occurs in the middle of an ASCII text file this routine returns 0 to indicate that no characters were read since the end of line characters are stripped out and are not copied into the buffer pointed to by bufferPtr and stores 1 in eorPtr to indicate end of record Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin fileDataPtr Pointer to f
137. then calls accept which will block until an incoming connection request is received When accept returns the sourceAddr structure will have been filled out with the originating IP Address and port of the incoming connection request accept creates a new socket which is then used to receive data until the connection is closed by the other side When this happens the application goes back to waiting for an incoming connection request include lt trsocket h gt define TM_BUF_SIZE 1400 define TM_DEST_PORT 9999 char testBuffer TM BUF SIZE char strError int tcpServer void int listenSocket int newSocket struct sockaddr in sourceAddr struct sockaddr in destAddr int errorCode int addrLen int returnVal returnVal 0 Specify the address family destAddr sin_family AF_INET Specify the dest port this being the server the destination port is the one we ll bind to Wy destAddr sin port htons TM DEST PORT Specify the destination IP address our IP address Setting this value to 0 tells the stack that we don t care what IP address we use it should pick one For systems with one IP address this is the easiest approach Py destAddr sin addr s addr inet addr 0 Create a socket listenSocket socket AF INET SOCK STREAM IPPROTO TCP Make sure the socket was created successfully if listenSocket TM SOCKET ERROR returnVal tfGetSocketError listenSo
138. then you can pass a 0 flags value and set Max buffers per frame to be one 1 What if I do not know my IP address netmask and want to retrieve them from the net You can use the Treck stack BOOTP or DHCP protocols Note Please refer to the BOOTP or DHCP section in Appendix B and to BOOTP or DHCP function reference calls in Appendix A 4 75 2004 Treck Incorporated Treck Real Time TCP IP User s Manual What if I do not know my IP address netmask and want to retrieve them from the net but do not wish to use the 7reck BOOTP or DHCP protocols To be able to open an interface without setting an IP address in the routing table call fOpenInterface using the TM DEV IP USER BOOT flag as follows errorCode tfOpenInterface interfaceHandle OUL UL TM_DEV_IP_USER_BOOT 1 Note that if you device driver support scatter send you can OR that flag to the TM DEV IP USER BOOT flag and change the last parameter accordingly You can then open a socket and try and send data through that interface calling the function ffSendTolInterface tfSendToInterface is identical to sendto but takes 2 extra arguments the interfaceHandle as returned by tfAddInterface and a multi home index 0 in our case toAddress sin addr s addr OxFFFFFFFFUL len tfSendToInterface desc buf 512 0 struct sockaddr TM FAR amp toAddress sizeof struct sockaddr interfaceHandle 0 You can also use the regular recv
139. to the device driver send function ard tfXmitInterface myInterfaceHandle tfUseInterfaceXmitQueue tfloctlInterface Functions only for non serial devices If you do not want the overhead ofa transmit task to send data to the device driver then you can use a Treck device transmit queue interface This method allows the driver to return an error in case the chip is not ready to transmit In that case a pointer to the buffer that could not be transmitted along with its length and flag is stored in an empty slot in the Treck device transmit queue The device transmit queue should be big enough to hold pointers to all the buffers that will be sent by the application The size of the data sent by an application is limited by the socket send queue size So an interface transmit queue should be big enough to hold pointers to buffers sent from all the application sockets through that particular interface The space allocation overhead for a x entries device transmit queue is 12 x 8 bytes So for a device transmit queue containing 1000 slots the overhead is 8012 bytes What happens if the interface transmit queue is not big enough If the device transmit queue is not big enough to hold all the buffer pointers that the device driver could not send the Treck stack will drop the packets corresponding to the buffers that could not be queued If the user uses the device driver scattered send capability some Ethernet frames could therefore be
140. to the user 5 76 2004 Treck Incorporated Programmer s Reference tfGetOobDataOffset include lt trsocket h gt int tfGetOobDataOffset int socketDescriptor Function Description This function is used to get the offset of the out of band data sitting in the receive queue This allows the user to determine where the out of band data is located in the stream The tfloctl call with the SOIOCATMARK request can be used instead ofthe tfGetOobDataOffset call but the tIfoctl call only tells us whether we are at the out of band byte mark whereas the tfGetOobDataOffset call gives us the offset to the out of band byte See recv call for out of band data description Parameters Parameter Description socketDescriptor The socket descriptor to get the number of bytes in the data stream to the out of band data offset Returns Number of out of band offset 1 if call failed tfGetOobDataOffset can fail for the following reasons TM EBADF The socket descriptor is invalid TM EINVAL No Out of Band Data is waiting to be read 5 77 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetSendCompltBytes include trsocket h int tfGetSendCompltBytes int socketDescriptor Function Description This function is used to get the number of sent bytes that have been acked since the last call to tfGetSendCompltBytes call by the peer on a TCP socket Parameters Parameter Description socketDescriptor
141. to be called when a match on an ARP request or ARP reply or ARP probe occurs The interface handle passed to the call back function is the interface handle passed to the tfUserStartArpSend function The call back function can also be called if the timeout given to the tfUserStartArpSend expires before an ARP request or reply occurs The user will pass the IP address to check a call back function and a parameter to be passed as is to the call back function 7 10 tfUseCollisionDetection will first check the ARP cache for a match on the IP address to see whether another host is already using that IP address If a match is found it will return TM EADDRINUSE to indicate that another host is using the IP address In that case the collision detection will stop right away tfUseCollistionDetection will add an entry for that IP address in the global collision detection list When incoming ARP requests and replies come the ARP sender IP address will be checked for a match with this entry in that list If an ARP reply or request or probe only if interface is not configured is received while the IP address is being checked for collision then the Treck stack will call the call back function in the context of the recv task with TM EADDRINUSE error code If the tfUserStartArpSend timeout expires before the Treck stack 2004 Treck Incorporated Optional Protocols receives any ARP reply request then the Treck stack will call the c
142. under which packets can be discarded IP is sucha fundamental part of the design that a TCP IP Internet is sometimes called an P based technology IP is designed for routing traffic between networks or across a network of networks An application running on a client machine generates messages or data to be sent to a machine located on another network IP receives these messages from the transport layer software residing on a server that provides a gateway from the LAN Local Area Network or WAN World Area Network onto the Internet or other TCP IP network Not all terminals on the network are end user machines or gateways to LANs and WANs Some terminals are devoted to routing packets along various potential pathways from the sending terminal to the receiving terminal The Internet Datagram On a physical network the unit of transfer is a frame that contains a header and data where the header gives information such as the physical source and destination addresses The Internet calls its basic transfer unit an nternet datagram sometimes referred to as an P datagram or merely a datagram Like a typical physical network frame a datagram is divided into header and data areas Also like a frame the datagram header contains the source and destination addresses and a field type that identifies the contents of the datagram The difference is that the datagram header contains IP addresses whereas the frame header contains physical addresses
143. use of these functions is required e tfRecvinterface e tfSendCompletelnterface tfXmitInterface and tfInterfaceSpinLock are used only if the user uses a separate transmit task to send packets in the context of the transmit task and to let the separate transmit task yield the CPU from the device driver send function while waiting for the device to be ready to transmit e tfXmitinterface e tfinterfaceSpinLock 4 45 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfInterfaceSetOptions is used by the user to set interface specific options such as turning on a transmit task for that interface or making ffRecvInterface copy device driver buffers whose size are below a specified option threshold as outlined below e tfinterfaceSetOptions tfUselnterfaceXmitQueue and tfloctlInterface are called by the user when he wishes to use a transmit queue to queue the buffers to a Treck device driver transmit buffer queue as opposed to using the overhead of a transmit task Note that the 2 methods are exclusive You need to decide whether you want to use a transmit queue or a transmit task or none of the above In addition you cannot use a device driver transmit queue for a serial device interface 1 e with SLIP or PPP e tfUselnterfaceXmitQueue only for non serial devices and with no transmit task e tfloctlInterface Here is a summary of functions that you may have to write in your device driver e driverOpen
144. used to begin a Critical section Parameters None Returns Nothing 5 242 2004 Treck Incorporated Programmer s Reference tfKernelSheapCreate include lt trsocket h gt ttUser32Bit tfKernelSheapCreate void Function Description RTOS SPECIFIC Normally the Treck simple heap is implemented as a static array However you can dynamically allocate it by defining the macro TM DYNAMIC CREATE SHEAP in your trsystem h file in which case you implement tfKernelSheapCreate to perform the allocation The size of the simple heap allocated by this function must be TM SHEAP SIZE and it must start on a 32 bit address boundary Parameters None Returns A pointer to the beginning of the Treck simple heap This address must be 32 bit aligned and must point to a block of memory which is TM SHEAP SIZE bytes in size 5 243 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelTaskPostEvent include lt trsocket h gt void tfKernelIsrPostEvent ttUserGenericUnionPtr eventPtr Function Description RTOS SPECIFIC This function is used to resume waiting tasks that were waiting on this event It is called from a task Parameters Parameter Description eventPtr The event to post on Returns Nothing 5 244 2004 Treck Incorporated Programmer s Reference tfKernelTaskYield include lt trsocket h gt void tfKernelTaskYield void Function Description RTOS SP
145. used to configure the compile time switches for the Treck protocol stack It should be considered the master configuration file In this file you will find macros to define things such as optimization endian and defaults for run time parameters used by the protocol stack You may find that you do not need to modify this file if your environment is already defined in the TRSYSTEM H file When you are integrating to your hardware platform and hooking the protocol stack up to your kernel this will be the only file that you need modify If you decide to turn on macros that are defined in this file you can do it at the top of the file The following are options that you may decide to turn on or off Performance Macros TM_BYPASS_ETHER_LL This performance macro is used to in line the Ethernet processing When this macro is enabled it allows us to process Ethernet packets much faster than sending them to a separate link layer The disadvantage to using this macro is that it costs a little more code space to do the Ethernet processing If you are not using Ethernet then you do not want to have this macro defined TM_IP_FRAGMENT If this macro definition is removed from rsystem h the IP fragmentation code is not compiled in If you expect to send IP fragments you need to keep this macro in system h Otherwise you can remove the TM IP FRAGMENT macro from trsystem h thereby reducing code size TM IP REASSEMBLY If this macro definition
146. value from network byte order to host byte order Parameters Parameter Description longValue The value to convert Returns The converted value 5 30 2004 Treck Incorporated Programmer s Reference ntohs include lt trsocket h gt unsigned short ntohs unsigned short shortValue Function Description This function converts a short value from network byte order to host byte order Parameters Parameter Description shortValue The value to convert Returns The converted value 5 31 2004 Treck Incorporated Treck Real Time TCP IP User s Manual readv include lt trsocket h gt int readv int socketDescriptor struct iovec iov int iovcnt Function Description readv functions as a scatter read because the received data can be placed in multiple buffers readv attempts to read data from the socket socketDescriptor and places the input data into the iovcnt buffers specified by the members of the iov array iov 0 iov 1 iov iovcnt 1 The iovec structure contains the following members caddr t 1ov base int iov len Each iovec entry specifies the base address and length of an area in memory where data should be placed readv always fills one buffer completely before proceeding to the next On success readv returns the number of bytes actually read and placed in the buffer this number may be less than the total of all ofthe iov len values A value of 0 is returned when an end of
147. wait for data send to complete but rather return immediately The SO DONTROUTE option is turned on for the duration of the operation Only diagnostic or routing programs use it Meaning Number of bytes actually sent on the socket An error occurred Destination host is down The socket descriptor is invalid There was insufficient user memory available to complete the operation One of the parameters is invalid the bufferPtr is NULL the bufferLength is lt 0 an unsupported flag is set toPtr is NULL or toLength contains an invalid length No route to destination host The socket requires that message be sent atomically and the message was too long TCP protocol requires usage of send not sendto The socket is marked as non blocking and the send operation would block 5 47 2004 Treck Incorporated Treck Real Time TCP IP User s Manual setsockopt include lt trsocket h gt int setsockopt int socketDescriptor int protocolLevel int optionName const char optionValue int optionLength Function Description setsockopt is used manipulate options associated with a socket Options may exist at multiple protocol levels they are always present at the uppermost socket level When manipulating socket options the level at which the option resides and the name of the option must be specified To manipulate options at the socket level protocolLevel is specified as SOL SOCKET
148. well This is why we transfer packets using the Big Endian method The Internet standard for byte order specifies that the most significant byte is sent first i e Big Endian style If one considers the successive bytes in a packet as it travels from one machine to another a binary integer in that packet has its most significant byte nearest the beginning of the packet and its least significant byte nearest the end of the packet Motorola processors are typically Big Endian types while Intel processors are typically Little Endian types We transfer packets using the Big Endian format 1 22 2004 Treck Incorporated Introduction to TCP IP Short Integer 16 Bits Long Integer 32 Bits MSB LSB 12 34 56 78 Fig 1 14 Difference Between Big Endian amp Little Endian MSB Most Significant Byte LSB Least Significant Byte To illustrate the difference between Big Endian and Little Endian look at Figure 1 15 If we store the number 0x12345678 at memory location 2000 it would look like this Memory Location Big Endian Little Endian 2000 12 78 Fig 1 15 Example of a Number Stored in a Big and Little Endian Processor 1 23 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The Point to Point Protocol PPP PPP or Point to Point protocol is designed to transport datagrams from multiple protocols over point to point links in a dynamically changing network As a result
149. will be the same across reboots provided that the user uses the same type of configuration and same index If the user specifies TM DHCPF FQDN ENABLE in flags then clientIdPtr is used to indicate the DHCP FQDN option domain name If flags is set to TM DHCPF FQDN ENABLE and clientldPtr is NULL the global FODN configured by tfUserSetFqdn will be used instead Note that the TM DHCPF FQDN ENABLE option cannot be set at the same time as the other flags except TM DHCP FQDN PARTIAL Parameters Parameter Description interfaceHandle Ethernet interface handle userIndex User Index between 0 and tvMaxUserDhcpEntries 1 7 42 2004 Treck Incorporated flags requestedIpAddress clientldPtr clientIdLength Returns Value TM ENOERROR TM_EINVAL TM EPERM TM ENOBUFS Optional Protocols 0 or a combination of TM DHCPF INIT REBOOT TM DHCPF REQUESTED IP ADDRESS TM DHCPF SUPPRESS CLIENT ID TM DHCPF FQDN ENABLE TM DHCPF FQDN PARTIAL TM DHCPF FQDN PARTIAL is ignored if clientIdPtr is NULL The FQDN option must be set separately from other DHCP options The only other flag allowed with TM DHCPF FQDN ENABLE is TM DHCPF FQDN PARTIAL User requested IP address in network byte order Pointer to client ID When flags is set to TM DHCPF FQDN ENABLE the FQDN domain name will be stored in this parameter a character pointer If it is NULL the global FQDN in tvFqdnStruct will be used instead Length of
150. with errnum Parameters Parameter Description errorcode An error value Returns error message 5 259 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfStrLen int tfStrLen const char strPtr Function Description This function returns the length of string pointed to by strPtr Parameters Parameter Description strPtr Pointer to the string Returns The length of the string pointed to by strPtr 5 260 2004 Treck Incorporated Application Reference Treck Real Time TCP IP User s Manual 6 2 Application Reference Function List PING API tfPingClose tfPingGetStatistics tfPingOpenStart DNS Resolver tfDnsInit tfDnsGetHostAddr tfDnsGetHostByName tfDnsGetMailHost tfDnsGetNextMailHost tfDnsSetOption tfDnsSetServer FTPD API tfFtpdUserExecute tfFtpdUserStart tfFtpdUserStop FTP tfFtpAbor tfFtpAppe tfFtpCdup tfFtpClose tfFtpConnect tfFtpCwd tfFtpDele tfFtpDirList tfFtpFreeSession tfFtpGetReplyText tfFtpHelp tfFtpLogin tfFtpMkd tfFtpNewSession tfFtpNoop tfFtpPort tfFtpPwd tfFtpQuit tfFtpRein tfFtpRename tfFtpRetr tfFtpRmd tfFtpStor tfFtpTurnPasv tfFtpSyst tfFtpType tfFtpUserExecute Application Reference TFTP tfTftpGet tfTftpInit tfTftpPut tfTftpSetTimeout tfTftpUserExecute TFTPD fTftpdInit fTftpdUserExecute fTftpdUserStart fTftpdUserStop t t t t File System Interface tfFSChangeDir fFSChangeParentDir fFSCloseDir fFSClos
151. 004 Treck Incorporated Set this option value to a non zero value to enable sending the Time stamp option Default 1 Set this option value to zero to disable the TCP slow start algorithm Default 1 Sets the TCP delay ack time in milliseconds Default 200 milliseconds Sets the maximum number of retransmissions without any response from the remote before TCP gives up and aborts the connection See also TCP MAXRTabove Default 12 Sets the maximum numbers of keep alive probes without any response from the remote before TCP gives up and aborts the connection See also TCP KEEPALIVE above Default 8 Sets the maximum amount of time TCP will wait for the remote side to close after it initiated a close Default 600 seconds Sets the maximum amount of time TCP will wait in the TIME WAIT state once it has initiated a close of the connection Default 60 seconds Sets the TCP default retransmission timeout value in milliseconds used when no network round trip time has been computed yet Default 3 000 milliseconds Sets the minimum retransmission timeout in milliseconds The network computed retransmission timeout is bound by TM TCP RTO MIN and TM TCP RTO MAX Default 100 milliseconds Sets the maximum retransmission timeout in milliseconds The network computed retransmission timeout is bound by TM TCP RTO MIN and TM RTO MAX Default 64 000 milliseconds TM TCP PROBE MIN TM TCP PROBE MAX TM TCP KEEPALIVE INT
152. 1s the address of the gateway For direct routes this address is set to the IP address of the 6 14 ntRteHwAddress ntRteHwLength ntRteClonePrefixLength ntRteMtu ntRteHops ntRteTtl ntRteFlags Application Reference corresponding interface just to indicate that it is a direct route This follows the UNIX convention ntRteGwSockAddr ss_family indicates the family of the address ntRteGwSockAddr addr ipv6 or ntRteGwSockAddr addr ipv4 has the actual IP Address of the gateway This field is valid if the routing entry is a local route in which case it is the hardware address of the target host This field is valid if the routing entry is a local route in which case it is thelength of the hardware address of the target host Prefix length for cloning a local host routing entry Mtu for the routing entry Maximum hops for the routing entry Lifetime of the routing entry in milliseconds an special value is reserved for infinite TM RTE INF as defined in trsocket h Routing flags see the table for routing flags 6 149 Treck Real Time TCP IP User s Manual Routing flags The ntRteFlags can be an ored value of one or more of the following value Possible values of ntRteFlags TM NT RTE UP TM NT RTE HOST TM NT RTE GW TM NT RTE DYNAMIC TM NT RTE REJECT rejected TM NT RTE CLONABLE TM NT RTE CLONED TM NT RTE STATIC 6 150 symbol U H Description route is up if not set
153. 32BIT ALIGNMENT Uncomment TM NEED ETHER 32BIT ALIGNMENT and uncomment TM USE DRV SCAT RECV without using ffUseInterfaceScatRecv if you want tfRecvInterface to make the TCP IP header aligned on a 4 byte boundary if it is not aligned coming from a single buffer in the Ethernet device driver receive function Predefined Processor Macros TM INTEL X86 TM MOTOROLA CPU32 TM MOTOROLA 68K TM MOTOROLA PPC TM TMS320 C3 TM TMS320 C3 BIG ENDIAN For TI C3 like DSP with byte order reversed TM TMS320 C5 TM TMS320 C6 TM ARM7 TM EZ80 These macros are used to specify the processor you are using and your environment They simply set up the proper word order or endian for the processor 4 16 2004 Treck Incorporated Integrating into Your Environment Compiler Specification These optional macros are used to define the compiler that you are using They are used to allow in line assembly for the critical sections and assembly cores for one s compliment checksums on some platforms Not all of the supported compilers are listed here because some of them are automatically determined during compilation see the TRMACRO H file TM_COMPILER_GHS_ARM This is used for the Green Hills ARM compiler TM COMPILER_GHS_PPC This is used for the Green Hills PowerPC compiler TM_COMPILER_SDS This is used for the SDS 68K compiler TM_COMPILER_DDI_PPC This is used for the Diab Data Power PC compiler TM COMPILER MRI 68K This is used fo
154. ABLE_ANSI_LINE_FILE This macro is only relevant when TM ERROR CHECKING is define d in which case the tm assert macro uses the ANSI LINE and FILE macros if available to print the source line number and source file name identifying where in the code an assertion failure occurred Uncomment the TM DISABLE ANSI LINE FILE macro if your compiler does not support the ANSI LINE and FILE macros TM_DISABLE_TCP_RFC2414 Enable this macro if you want to disable the TCP Initial Send Window Increase as described in RFC 2414 TM_DISABLE_TCP_RFC2581 Enable this macro if you want to remove the TCP congestion control update to RFC2001 as described in RFC2581 wireless TCP option only TM_DISABLE_TCP_RFC3042 Enable this macro if you want to remove the Limited Transmit Algorithm that enhances TCP s Loss Recovery as described in RFC3042 wireless TCP option only TM_DEV_SEND_OFFLOAD Enable this macro if you want to use the device driver TCP segmentation checksum offload capabilities 4 9 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM_DEV_RECV_OFFLOAD Enable this macro if you want to use the device driver recv packet checksum offload capabilities TM_USER_OCS Enable this macro to use a user defined checksum routine e g in Assembly Rather than the standard C routine TM_PC_LINT Enable this macro if you are using Gimpel Software s PC lint to check the Treck stack code TM_TCP_ANVL Uncomment this mac
155. AP Enable this macro to enable Extensible Authentication Protocol with PPP TM_USE_IPHC Enable this macro to enable IP header compression RFC 2507 with PPP TM_USER_PACKET_DATA_ALLOC If the user defines this macro packet data buffer allocation will be done by the stack using the macros tm_alloc_packet_data_buffer and tm_free_packet_data_buffer which then also need to be defined by the user This can be used to have Treck TCP IP allocate packet data buffers in fast on chip RAM which can significantly improve throughput NOTE If the user uses a preemptive kernel i e TM_TRECK_PREEMPTIVE_KERNEL is defined in trsystem h it is the user s responsibility to ensure that the functions called by tm_alloc_packet_data_buffer and tm_free_packet_data_buffer are re entrant as they could potentially be called from different threads TM_USE_VCHAN Enable this macro to support splitting out IPv4 and IPv6 traffic in the send path to separate virtual channels to simulate multiple hosts as multiple IP aliases Note that this is incompatible with the default mode of IPv6 operation therefore IPv6 prefix discovery must be disabled TM_OPTIMIZE_MANY_MHOMES Enable this macro to speed up lookup in the recieve path of IP aliases config ured on the interface This is intended for situations where the user has config ured many i e gt 50 IP aliases on a single interface TM_USE_NETSTAT Define this macro if you want to use the netstat tool f
156. ARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP FILENAVAIL TM FTP NAVAIL TM FTP NOTLOGIN 6 40 This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Requested file action not taken file unavailable Requested action not taken file unavailable Not logged in Application Reference tfFtpDirList include lt trsocket h gt int tfFtpDirList ttUserFtpHandle ftpSessionPtr char pathNamePtr int directoryFlag ttFtpCBFuncPtr ftpDirCBFuncPtr Function description This function retrieves a directory listing for a specified directory on remote file system When this data is received a user supplied function is called The prototype for the callback function is int ftpCBFunc ttUserFtpHandle ftpSessionPtr char bufferPtr int bufferSize Parameters Parameter Description fipSessionPtr FTP session handle pathNamePtr Directory name directoryFlag Indicates whether a short TM DIR SHORT or long TM DIR LONG directory listing is desired fipDirCBFuncPtr The function pointer of the user function to call when the directory listing is received See above for function pr
157. An error occurred If an error occurred the socket error can be retrieved by calling tfGetSocketError and using TM SOCKET ERROR as the socket descriptor parameter select will fail if TM EBADF One of the socket descriptors is bad 5 42 2004 Treck Incorporated Programmer s Reference send include lt trsocket h gt int send int socketDescriptor char bufferPtr int bufferLength int flags Function Description send is used to transmit a message to another transport end point send may be used only when the socket is in a connected state socketDescriptor is a socket created with socket Ifthe message is too long to pass atomically through the underlying protocol non TCP protocol then the error TM EMSGSIZE is returned and the message is not transmitted A return value of 1 indicates locally detected errors only A positive return value does not implicitly mean the message was delivered but rather that it was sent Blocking socket send if the socket does not have enough buffer space available to hold the message being sent send blocks Non blocking stream TCP socket send if the socket does not have enough buffer space available to hold the message being sent the send call does not block It can send as much data from the message as can fit in the TCP buffer and returnes the length of the data sent If none of the message data fits then is returned with socket error being set to TM EWO
158. Because we use this to hold the counting semaphore we are able to integrate to any RTOS Kernel This union is defined in the file TRSOCKET H as follows typedef union tuUserGenericUnion unsigned long gen32bitParm long genSlongParm void TM_FAR genVoidParmPtr unsigned short genl6BitParm unsigned int genUintParm int genIntParm unsigned char gen8BitParm char genCharParm ttUserGenericUnion By using the UserGenericUnion data type you will be able to pass your counting semaphore between Treck protocols and your RTOS A set of three functions provides access between the Treck protocol stack and your RTOS These functions are used to create pend on and post on a counting semaphore that will be used by the protocol stack Because a task cannot pend more than once at any given time and because the Treck stack re uses unused counting semaphores dynamically the maximum number of counting semaphores that will be needed would be equal to the number of tasks that are calling Treck The RTOS functions below are only examples You will need to map these calls into your own RTOS If you are not using an RTOS then these functions should be stubs The ffKernelCreateCountSem function is used to create a counting semaphore that is provided by the operating system with an associated counter initialized to zero If the counting semaphores are created at compile time with your operating system then you simply pass one of these back to
159. C 227 Entering Passive Mode A1 A2 A3 A4 a1 a2 C gt A Connect to HOST A PORT a C gt A RETR Treck Real Time TCP IP User s Manual Example Example for two server passive mode operation STOR include lt trsocket h gt include lt stdio h gt 4 for printf ttUserFtpHandle setupFtpCtrl char ipaddr int retCode ttUserFtpHandle ftpHandle Create New Session for FTP server ftpHandle tfFtpNewSession 0 TM BLOCKING ON fsusername fspassword if ftpHandle ttUserFtpHandle 0 printf Mn Failed to create FTP session else Connect to FTP server retCode tfFtpConnect ftpHandle ipaddr if retCode TM ENOERROR printf n Failed to connect FTP server a void tfFtpFreeSession ftpHandle ftpHandle ttUserFtpHandle 0 else Login to FTP server retCode tfFtpLogin ftpHandle ftpusername ftppassword if retCode TM ENOERROR printf n Failed to login on FTP server void tfFtpClose ftpHandle void tfFtpFreeSession ftpHandle ftpHandle ttUserFtpHandle 0 else 6 68 Application Reference printf n Successfully setup CTRL conn to FTP t Y return ftpHandle void main void ttUserFtpHandle ftpHandleA ttUserFtpHandle ftpHandleB Start the Treck stack Setup Ctrl connection to FTP server A ftpHandleA setupFtpCtrl 192 168 1 100 m
160. CP config request with AUTH PAP 2 Peer NAKs it with MS CHAPv1 3 Authenticator processes the NAK packet and sends LCP config request with AUTH CHAP not MS CHAPv1 because server prefers CHAP more 4 Peer NAKs it with MS CHAPv1 5 Authenticator processes the NAK packet and sends LCP config request with AUTH2MS CHAPvI 6 Peer ACKs it Authenticator Part linkLayerHandle tfUseAsyncServerPpp ttLnkNotifyFuncPtr tfPppLinkNotify interfaceHandle tfUseXxxDriver TEST linkLayerHandle amp errorCode 1 Authenticator wants IP to be 192 168 0 2 Au thenticator already knows its IP address errorCode tfPppSetOption interfaceHandle int TM_PPP_IPCP_PROTOCOL TM_PPP_OPT_WANT TM_IPCP_IP_ADDRESS char amp ifIPAddr 192 168 0 2 4 assert errorCode TM ENOERROR 2 Authenticator wants PAP CHAP MSCHAPv1 and in this order papValue int TM PPP PAP PROTOCOL net work order 7 104 chapValue int TM PPP CHAP PROTOCOL 2004 THCK In srperat d Optional Protocols 2 1 want PAP protocol errorCode tfPppSetOption interfaceHandle int TM_PPP_LCP_PROTOCOL TM_PPP_OPT_WANT TM_LCP_AUTH_PROTOCOL char amp papValue 2 assert errorCode TM ENOERROR 2 2 want CHAP protocol errorCode tfPppSetOption interfaceHandle int TM_PPP_LCP_PROTOCOL TM PPP OPT WANT TM LCP AUTH PROTOCOL char amp chapValue 2 assert errorCode TM ENOERR
161. Control Message Protocol provides for the extra normal communication among routers and hosts it is an integral required part of IP The User Datagram Protocol UDP The User Datagram Protocol or UDP is the primary mechanism that application programs use to send datagrams to other application programs UDP messages contain both destination port numbers and source port numbers in addition to the data being sent This makes it possible for the UDP software at the destination to deliver information to the correct recipient and for the recipient to send a reply UDP utilizes the underlying IP to transport information from one machine to another By using the IP format for delivery UDP inherits the same characteristics of an IP message It is an unreliable connectionless datagram service For example it does not use acknowledgments to makes sure messages have arrived It does not order incoming messages and it does not provide feedback to control the rate at which information passes between machines From this we can gather that UDP messages can be lost duplicated or arrive out of order We also know that packets can be sent faster than the recipient can process them To reiterate The User Datagram Protocol UDP provides an unreliable connectionless delivery service using IP to transport messages between machines It uses IP to carry messages but utilizes the distinction among multiple destinations An application program that relies on UDP
162. Cr B 5 Hooking up the Timer siete nait nde ascension B 5 Task WSABS sn SP teh retirent e tete ee CL B 5 RTOS Application Note for AMX 86 mnenenennennntes B 6 MAURY ZETA ors PEE B 6 Memory Allocation and Free esses B 6 Critical Section Handling retro reo eret err e ERR B 6 Error Logging and Warning Information Logging seess B 6 Task Suspend and Resume cccceceesecsseeseceeeeseeeeceseeeceeeeseceseeeeeeeeeeeeenes B 6 ISR Interface ses uii niter Deere ain ee Ee de eiue dude B 7 Hooking up the Timer iue trt dent bp idees B 7 EEC IUIUS B 7 AMX 86 System Configuration Module sse B 7 Appendix C Debugging ss sssssscssscisessssicssessssosessssscseessssscssess ol Debugging a Device Driver sscsssssessssssseesssessessseesesssecsecssesssesseseees C 3 How to debug a device driver sse C3 Common Symptoms and Their Causes C 7 Running Out of Memory 5 nreteeretpip rte erento Pe pce Eris Peas tsisa C7 Corrupted Memory retener eue ive nade sputo ubere ce EE Ue Ere C 8 Receiving Corrpted Data terere er tute eb tene C 8 Kernel Error Send Too Much Scattered Data sss C 8 Kernel Error Attempt to free more than alloc a buffer C9 Ping and UDP work but TCP does not C9 Ping works but UDP and TCP do not C9 2004 Treck Incorporated Driver Will Not Send and or Receive Data Drive
163. Description This function converts an IP address from the decimal dotted notation to an unsigned long Parameters Parameter Description ipAddressDottedStringPtr The dotted string 1 e 208 229 201 4 Returns Value Meaning 1 Error Other The IP Address in Network Byte Order 5 26 2004 Treck Incorporated Programmer s Reference inet_aton include lt trsocket h gt unsigned long inet_aton Char ipAddressDottedStringPtr i Function Description This function converts an IP address from the decimal dotted notation to an unsigned long Parameters Parameter Description ipAddress DottedStringPtr The dotted string i e 208 229 201 4 Returns Value Meaning 0 Error Other The IP Address in Network Byte Order 5 27 2004 Treck Incorporated Treck Real Time TCP IP User s Manual inet_ntoa include lt trsocket h gt Char inet_ntoa struct in_addr inAddr Function Description This function converts an IP address structure the sin addr element of the sockaddr in structure to an ASCII string in dotted decimal notation Note inet ntoa is not reentrant It is only provided for BSD support Users should use the equivalent reentrant function called tfInetToAscii Parameters Parameter Description inetAddr Structure containing the address to convert Returns Value Meaning 0 Error Other ASCII string of the IP address in dotted decimal notation 5 28 2004 Treck Incorporated Progra
164. DevRecvFuncPtr drvRecvFuncPtr ttDevFreeRecvFuncPtr drvFreeRecvBufFuncPtr TtDevioctlFuncPtr drvlIoctlFuncPtr tDevGetPhyAddrFuncPtr drvGetPhyAddrFuncPtr nt drvAddErrorPtr SRS ict Ne Function Description This function is the main function to use when adding an interface to the Treck TCP IP system Note Interfaces are added in the CLOSED state An example would be as follows myInterfaceHandle tfAddInterface NE2000 001 etherLinkLayerHandle ne2kOpen ne2kClose ne2kSend ne2kReceive ttDevFreeRecvFuncPtr 0 ne2kloctl ne2kGetPhyAddr amp errorCode 5 130 2004 Treck Incorporated Parameters Parameter namePtr linkLayerHandle drvOpenFuncPtr drvCloseFuncPtr drvSendFuncPtr drvRecvFuncPtr drvFreeRecvBufFuncPtr drvloctlFuncPtr drvGetPhyAddrFuncPtr drvAddErrorPtr Programmer s Reference Description The callers name for the device each call to tfAddInterface must use a unique name The name length cannot exceed TM MAX DEVICE NAME 1 13 bytes The link layer layer 2 protocol handle that this interface will use This is returned by tfUseEthernet tfUseAsyncPpp tfUseAsyncServerPPP or tfUseSlip A function pointer to the device drivers open function A function pointer to the device drivers close function A function pointer to the device driver s send routine A function pointer to the device driver s recv routine A function pointer a device driver functio
165. ECIFIC This function is used to yield the CPU It is called from a task Returns Nothing 5 245 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelWarning include lt trsocket h gt void tfKernelWarning char functionName char errorMessage Function Description RTOS SPECIFIC This function is used to report a non fatal warning The system should continue normally Parameters Parameter Description functionName The Null terminated string contain ing the function name where the error occurred errorMessage The Null terminated string contain ing the error message Returns Nothing 5 246 2004 Treck Incorporated Programmer s Reference Compiler Library Replacement Functions tfMemCpy include lt trsocket h gt void t fMemCpy void destination const void source unsigned length Function Description This function is used to copy data i e memcpy Parameters Parameter Description destination Beginning of destination source Beginning of source length Length of area to copy Returns Number of bytes copied 5 247 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfMemSet include lt trsocket h gt void tfMemSet void buffer unsigned char fillCharacter unsigned length Ju Function Description This function is used to fill an area of memory i e set all of the bytes to 0x00 In versions 2 0 and earlier the order
166. ERNEL AMX X86 eiit eee meret eene ies sedens 4 18 TM KERNEL THREADX CPU32 eese 4 18 TM KERNEL DOS X86 nuire cene tete eet Dye dee Percent 4 18 TM KERNEL CMX CT6X iter PRI HEU RR OerteroeOR 4 18 TM KERNEL NONE EZ23 eerte eee eerte nece rece pan 4 18 TM KERNEL NONE HSS 5 eire npe n PERO e RR EROTS 4 18 TM KERNEL RZK E780 sue metiers 4 18 TM KERNEL REALOS ER ott p oao ekes 4 18 TM KERNEL TI DSP BIOS senem deret ederent 4 18 TM KERNEL WIN32 X86 5 5 onem pe etre rtp etos 4 18 TM KERNEL VISUAL X86 oreet recensito nee econo 4 18 TM KERNEL LINUX APP s sssssessseesesesesenseseneneesenensnonsenenens 4 18 Step 3 Creating the Build Command BAT ss 4 19 Tier 1 Setting up the compiler and library utility primitives 4 19 Tier 2 Compile Library all the Treck code 4 20 Tier 3 Setting up the Automated Build System 4 21 Step 4 Creating an RTOS Kernel Interface ss 4 22 Tint BZA OM us eo mte beret pe te OR ep tale CREER AERE ad 4 23 Memory Allocation and Free essent 4 24 Meck Simple Hea MM 4 24 TM USE SHEAP 6 5 05 uen deren mener dei ene gun 4 24 TM SHEAP SIZES ennemie te tee 4 24 TM SHEAP MIN BLOCK SIZE 4 4 24 TM DYNAMIC CREATE SHEAP eere 4 25 TM SHEAP NUM PAGE 1 issues 4 25 tflcernelSlieapCTeale on ee er in Pt remis 4 25 Critical Section Handling seen enero pee ince cese 4 26 2004 Treck Inco
167. File Delete a file tfFSGetNextDirEntry Get the next directory entry in the directory open with tfFSOpenDir either a long listing of the directory entry including volumes sub directories and file names or a short listing of the directory file name only depending on how the directory was open tfFSGetUniqueFileName Given a file name return a unique file name in the current directory i e if the file name already exists make up a new name that is unique in the current directory tfFSGetWorkingDir Get user working directory tfFSMakeDir Create specified directory tfFSOpenDir Open specified directory or directory corresponding to a specified pattern to allow getting a long or short listing of the directory or of the directory entries matching the specified pattern tfFSOpenFile Open a file creating it 1f it does not exist for read write or append specifying type ASCII or binary structure stream or record tfFSReadFile Read n bytes from a file into a buffer 6 88 Application Reference tfF SReadFileRecord Read a record from a file up to n bytes Indicates whether EOR has been reached tfFSRemoveDir Remove specified directory tfFSRenameFile Rename a file tfFSStructureMount Mount the user to a new file system data structure tfFSSystem Return the system name tfFSUserAllowed Indicates whether a specified user is allowed on the system tfFSUserLogin Login a user if password is valid tfFSUserLogout Logout
168. HAUGATPEDIY RE 5 208 ttAddDetfaultGratewdy 5 2 eei eoo te el ite rte exea CREE 5 209 tA ddMICastROoULe oce en er OR WERE eee 5 210 ttAddProxyATSpEnl0ty euet eder eR PE ed ern tien 5 212 t tAddStatic ROU G S deiecti ge go 5 213 1fDelArpEutryBylIpAddt ei geret tr ert Pee dads 5 214 tfDelArpEntryByPhysAddr 5 215 t1tDe lD faultGiatewdy ure ee re OP ESEE eE ear tS 5 216 tfDelProxy ArpEntry sheet intimement 5 217 tfDelStaticRoute esses sees eene ethernet inneren nnns 5 218 ttDisablePathMtUlbiSQ hoec eee tr T ri eh oan 5 219 tfGetArpEntryByIpAddt 2 niter rte edente rpg 5 220 tfGetArpEntryByPhysAddr essere 5 221 ttGetDefaultCi te way uia oscura eerte DER EU EFE i 5 222 LRTDESTE ISSN ee tee ne a een en 5 223 THRE Sister IPROLWGB sinocni esee ereere eee e e Dp EREMO IREO US 5 224 DIST f Bee ES 5 225 Timer Interface ADT 1 ener ententes eua Ee noce srs 5 226 HARTE E do OU LEE eater Sous cote tei ive o drehen t re e den 5 226 ttIxmerUpdate eo eere beer ert on tbe s e RS 5 227 ti Wimmer Update lst sement tics M elected 5 228 Kernel RTOS Interface 0 cssccssssccscssccssseecsssscecscscccsssecsssssesssceccsesees 5 229 ttKernelCreateCountSett e eere eren de 5 229 tfKernelCreateEvent esses eene ener enhn 5 230 ttKernelD leteCountiSem sc retesi A
169. HCP request is successful the user can retrieve the IP address and parameters given by the DHCP server userBtEntryPtr tfDhcpUserGetBootEntry ethernetInterfaceHandle userIndex If the DHCP request has been successful this function will return a pointer to a boot structure null otherwise The userBtEntryPtr is a pointer to a structure defined in trsocket h In particular the userBtEntryPtr will contain The allocated IP address in the field userBtEntryPtr gt btuYiaddr Network subnet mask in the field userBtEntryPtr gt btuNetMask Default router entry in the field userBtEntryPtr gt btuDefRouter Primary Domain name server userBtEntryPtr gt btuDns IServerIpAddress Secondary Domain name server userBtEntryPtr 7 btuDns2ServerlpAddress An array of TM DHCP NBNS NUM SERVER NetBios name servers IPv4 addresses returned in the NBNS option userBtEntryPtr gt btuNetBiosNumNameServers By default TM DHCP NBNS NUM SERVER is equal to 2 allowing the storage of 2 name servers The number of NetBios name servers userBtEntryPtr gt btuNetBiosNumNameServers The user should save the userBtEntryPtr in its PPP table where it previously stored the corresponding PPP interface handle pppinterfaceld The user can now assign that IP address to its future serial line PPP client by calling errorCode tfPppSetOption pppinterfaceld TM PPP IPCP PROTOCOL TM PPP OPT ALLOW TM IPCP IP ADDRESS const char TM FAR amp userBtEnt
170. ILNET for the Military used TCP IP for network communication Now that the military was on its own network ARPA decided to encourage universities to use the new TCP IP protocols and utilize the new ARPANET At most universities at that time the computer science departments were using the UNIX operating system ARPA then funded a project to adapt the TCP IP protocol suite to the BSD Berkeley Software Distribution UNIX operating system and provided a low cost means to allow the universities to connect to the ARPANET The BSD variant of UNIX also had many new tools for the TCP IP Protocol Suite that was integrated with it These tools allowed the user to use simple UNIX commands to move files across the network with ease It was so simple to use that it became popular very quickly The BSD UNIX also included a new application program interface API to allow programmers to access the TCP IP protocols This new API was called sockets and allowed the user a uniform way to program network applications without regard to the type of computer that it was running on This allowed researchers to write new programs and protocols to run on top of the TCP IP protocol Since BSD UNIX was so popular within computer science departments TCP IP was also used for local area networking The ARPANET became so popular that in 1986 the National Science Foundation funded the first wide area backbone network called NSFNET This new backbone network allowed even more educati
171. IP address pointer TM EWOULDBLOCK DNS lookup in progress The user should continue to call tfDnsGetHostName with the same parameters until it returns a value other than TM EWOULDBLOCK Only returned in non blocking mode TM ENOERROR DNS lookup successful IP address stored in ipAddressPtr Treck Real Time TCP IP User s Manual tfDnsGetMailHost int const char ttUserlpAddressPtr unsigned short Function Description tfDnsGetMailHost hostnameStr ipAddressPtr mxPrefPtr This function retrieves the IP address of the first MX record for this hostname Parameters Parameter hostnameStr ipAddressPtr mxPrefPtr Returns Value TM _EINVAL TM EWOULDBLOCK TM ENOERROR Description Hostname to resolve Set to the IP address of the mail host Set to the preference value of this mail host Meaning Invalid host name string or IP address pointer DNS lookup in progress The user should continue to call tfDnsGetHostName with the same parameters until it returns a value other than TM EWOULDBLOCK DNS lookup successful IP address stored in ipAddressPtr Application Reference tfDnsGetNextMailHost int tfDnsGetNextMailHost const char hostnameStr ttUserlpAddress lastIpAddress unsigned short lastPreference ttUserIpAddressPtr ipAddressPtr unsigned short mxPrefPtr Function Description This function returns the IP address for the next mail exchanger for this hostname
172. IP stack to send RIP requests Send RIP version 1 packets Multicast RIP version 2 packets Broadcast RIP version 2 packets Meaning Ignore incoming RIP packets Accept RIP version 1 packets Accept RIP version 2 packets Accept both RIP version 1 and version 2 packets Meaning Success The option or its value is invalid Programmer s Reference tfStartTreck include lt trsocket h gt int tfStartTreck void i Function Description tfStartTreck is used by the user to initialize the Treck protocol stack This involves initializing all the global variables and getting system resources Note The only Treck call that can be made prior to calling tfStartTreck is tfInitTreckOptions Parameters None Returns Value Meaning 0 Success TM ENOBUFS No memory to complete the operation TM EPERM The timer tick length has not been initialized Use the tfInitTreckOptions call to initialize it TM EFAULT Code is compiled with the wrong network byte order switch If you had the TM LITTLE ENDIAN switch defined in trsystem h undefine it If you had not defined it define it 5 129 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Device Interface API tfAddinterface include lt trsocket h gt TtUserInterface tfAddInterface char namePtr ttUserLinkLayer linkLayerHandle ttDevOpenCloseFuncPtr drvOpenFuncPtr ttDevOpenCloseFuncPtr drvCloseFuncPtr TtDevSendFuncPtr drvSendFuncPtr Tt
173. IP address be set to anything except 0 0 0 0 7 94 2004 Treck Incorporated For example Optional Protocols ttUserlIpAddress remotelpAddress remotelpAddress inet_addr tfPppSetOption 0 00 07 interfaceHandle TM PPP IPCP PROTOCOL TM PPP OPT ALLOW TM IPCP IP ADDR ESS const char amp remotelpAddress 4 If tfPppSetOption is called with an IP Address optionName remoteLocalFlag TM PPP OPT ALLOW and option ValuePtr points to an IP address whose value is not 0 0 0 0 two situations may occur The remote will be allowed to set its IP DNS IP address to this value or will be returned this value if it requests 0 0 0 0 PAP TM PPP PAP PROTOCOL Option Name TM PAP USERNAME TM PAP PASSWORD TM PAP RETRY TM PAP TIMEOUT Meaning Sets the username to use with PAP Client Default NONE Sets the password to use with PAP Default NONE Sets the maximum number of PAP authentication requests that will be sent without receiving an ACK NAK remoteLocalFlag has no effect Default 10 Sets the PAP retransmission timeout value in seconds remoteLocalFlag has no effect Default 3 Seconds 7 95 2004 Treck Incorporated Treck Real Time TCP IP User s Manual CHAP TM_PPP_CHAP_PROTOCOL Option Name TM_CHAP_USERNAME TM CHAP SECRET TM CHAP RETRY TM CHAP TIMEOUT TM CHAP ALG ADD TM CHAP ALG DEL Returns Value 0 TM ENOPROTOPT TM BINVAL 7 96 2004 Treck Incorpo
174. Interface Initialization The function ffKernellInitialize is used to initialize the Treck kernel interface It is not needed for all RTOS Kernels The system calls this function prior to any other kernel calls You should think of this function as a way to get things initialized for your environment If this function is not needed it should be a stub function Example void tfKernelInitialize void Initialize the Treck to Kernel Interface return 4 23 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Memory Allocation and Free The functions ffKernelMalloc and tfKernelFree are used to allocate and free memory that is to be used by the Treck protocol stack They are the same definition as the ANSI malloc and free functions We have provided these functions to give you the flexibility to use the memory allocation that you want for your environment You can use your RTOS malloc and free These functions are used to pass memory blocks to the Treck Memory System Unless you have disabled the dynamic memory feature the Treck Memory System will not free these blocks unless they are larger than the Treck Memory System keeps track of By definition there will be more mallocs than frees however as time progresses there will be fewer and fewer mallocs Examples void TM_FAR tfKernelMalloc unsigned size return malloc size void tfKernelFree void TM_FAR memoryBlock free memoryBlock Tr
175. Interface should be called instead If a collision has been detected then the user should cancel the collision detection by calling tfCancelCollisionDetection on the current IP address and try another IP address by calling tfConfigAutolp or similar function again The tfAutolpFinish call back function provided as an example in examples txautoip c and shown below does all this It also cancels the collision detection 1f no collision occurred Monitoring the network for collision after finishing the configura tion After the interface has been successfully configured the user should still monitor the network for collision This could be done by not canceling the collision detection in the call back function and modifying the call back function to handle a collision detection when the interface has been configured 7 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Enabling AUTO IP The following macro must be uncommented out in trsystem h so that the AUTO IP code can be enabled define TM USE AUTO IP Example The following code sample can also be found in examples txautoip c errorCode tfOpenInterface interfaceHandle 0 0 TM_DEV_IP_USER_BOOT 1 0 if errorCode TM_ENOERROR errorCode tfConfigAutoIp interfaceHandle 0 int tfConfigAutolp ttUserInterface interfaceHandle int mhomeIndex ttUserGenericUnion autoIpParam ttUserIpAddress ipAddress int errorCode do Pick
176. LEN In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Description Pointer to the result string One of the parameters is bad 6 145 Treck Real Time TCP IP User s Manual tfNtTcpEntryToStr char ttNtTcpEntryPtr char int Description tfNtTcpEntryToStr NtTcpEntryPtr buffer sizePtr Converts a TCP entry into a string that has the major fields in Parameters Parameter ntTcpEntryPtr buffer sizePtr Returns Value Valid pointer NULL 6 146 Description TCP entry to be converted buffer to hold the result string Its size should be TM NT ENTRY STR LEN In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Meaning Pointer to the result string One of the parameters is bad Application Reference tfNtUdpEntryToStr char tfNtUdpEntryToStr ttNtUdpEntryPtr ntUdpEntryPtr char buffer int sizePtr Description Converts a UDP entry into a string that has the major fields in Parameters Parameter description ntUdpEntryPtr UDP entry to be converted buffer buffer to hold the result string Its size should be TM NT ENTRY STR LEN sizePtr In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Returns Return value Description Valid pointer Pointer to the result
177. MBER TM LCP MAX FAILURES TM LCP MAX RECV UNIT TM LCP ACCM TM LCP AUTH PROTOCOL 7 88 2004 Treck Incorporated Len 1 Meaning A boolean value specifiying whether address field compression should be used Default OFF A boolean value specifying whether protocol field compression should be used Default OFF A boolean value indicating whether to specify a magic number Default OFF Sets the maximum number of LCP configuration failures This determines the maximum number of configuration NAKs that will be sent before we reject an option Default 5 Specifies the largest MRU that we will allow and the default MRU that we want to use Default 1500 Specifies the async control character map that we want to use and if we want to allow the remote side to be able to set his ACCM Default Oxffffffff Use when authenticating to our peer and vice versa e g PAP or CHAP Possible values are TM PPP PAP PROTOCOL TM PPP CHAP PROTOCOL TM LCP TERM RETRY TM LCP CONFIG RETRY TM LCP TIMEOUT TM LCP QUALITY PROTOCOL Optional Protocols TM PPP EAP PROTOCOL Default No authentication Sets the maximum number of Terminate requests that the local peer will send without receiving a Terminate Ack before terminating the connection Default 3 Sets the maximum number of LCP config requests that will be sent without receiving a LCP ack nak reject remoteLocalFlag has no effect Default
178. Manual An example of using these calls for send complete processing from a main line loop is as follows void main void Other main processing like initialization adding opening an interface y for Other main processing like timer recv Check for sent packets if tfCheckSentInterface myInterfaceHandle TM_ENOERROR Call the stack to tell it that it owns the frame now my tfSendCompleteInterface myInterfaceHandle TM DEV SEND COMPLETE APP An example ISR handler for both of the methods would look something like this void deviceIsrHandler void int receivedPacketCount int sendCompletePacketCount unsigned long totalBytesSent Store number of packets ready to by received in receivedPacketCount y Store number of send complete packets in sendCompletePacketCount and store total number of bytes sent in totalBytesSent Notify the stack that data is waiting to be processed and that the driver has transmitted some complete frames Ey tfNotifyInterfaceIsr myInterfaceHandle receivedPacketCount sendCompletePacketCount totalBytesSent OUL 4 58 2004 Treck Incorporated Integrating into Your Environment Our experience tells us that it is usually best NOT to use a send complete task that is the highest priority The reason is that a send complete task will cause a context switch on every sent packet Let s look at a couple of metho
179. Manual tfRecvInterface and tfInterfaceSetOptions functions The Treck ffRecvInterface function will process incoming data If incoming data is a PING echo request this function will generate and send the reply in the context of the receive task If incoming data is for a user application socket then the ffRecvInterface function will process the incoming data and then will queue the buffer containing the user application data in the application socket receive queue The problem is that on a non serial device the device driver receive buffers will be tied up in the socket receive queue until the application actually recv the data Typically a device driver will have pre allocated maximum size Ethernet packet and if there is little data in each Ethernet frame this could end up consuming a lot of memory To fix this two techniques are used 1 Copy at the socket receive queue level If there is no data in the application socket receive queue the device driver buffer will be queued If there is a buffer already queued in the application socket receive queue by default the Treck stack will attempt to copy to a new buffer for UDP or to append to the previous buffer for TCP and free the device driver buffer By default the Treck stack will attempt to do so only if the ratio of the allocated block size to the buffer size is at or above 4 i e if the data uses less than or 25 of the allocated block However if the device driver recv fu
180. Meaning TM ENOERROR Success TM EINVAL Invalid Telnet Handle 6 121 Treck Real Time TCP IP User s Manual tfTeldUserExecute include lt trsocket h gt int tfTeldUserExecute void Function description The function executes the TELNET server non blocking mode only main loop This is to be used only if tf TeldUserStart had been called in non blocking mode Parameters None Returns Value Meaning TM ENOERROR Success TM EPERM Telnet server currently executing or had not been started or has been stopped 6 122 Application Reference tfTeldUserSend include lt trsocket h gt int tfTeldUserSend ttUserTeldHandle teldHandle char teldSendBufPtr int teldBytes int flag Function description This function is called to give data to the telnet server to send it to the telnet client Flag values Ifthe flag valueis TM TELD SEND EOL it indicates that end of command has been reached and means that the telnet server needs to append CR LF gt in ASCII mode or IAC EOR gt in binary mode to the user data If the flag value is TM TELD SEND COMMAND it indicates that the user is sending a TELNET IAC command and that the Treck Telnet server should treat the data as a command and not map the IAC character Flow control If the Treck server does not have enough room for the data it will not copy the data and return TM EWOULBLOCK The caller should try and re send the data at a later time Para
181. MinRtt pgiAvrRtt pgiSumRtt pgiSendErrorCode any pgiRecvErrorCode Returns Value 0 1 unsigned long unsigned long unsigned long int int Application Reference Minimum round trip time in milliseconds of the PING request reply packets Average round trip time in milliseconds of the PING request reply packets Sum of all round trip times in milli seconds of the PING request reply packets PING send request error code if PING recv error code if any including ICMP error from the network Meaning Success An error occurred If tfPingGetStatistics fails the associated error code can be retrieved using tfGetSocketError socketDescriptor TM EBADF TM EINVAL TM EINVAL socketDescriptor is not a valid descriptor pinginfoPtr is a NULL pointer socketDescriptor was not opened with tfPingOpenStart 6 7 Treck Real Time TCP IP User s Manual tfPingOpenStart include lt trsocket h gt int tfPingOpenStart char remoteHostNamePtr in pingInterval in U C c pingDataLength ttPingCBFuncPtr pingUserCBFuncPtr Function Description This function opens an ICMP socket and starts sending PING echo requests to a remote host as specified by the remoteHostName parameter PING echo requests are sent every pinginterval seconds The PING length not including IP and ICMP headers is given by the pingDataLength parameter If the pingUserCBFuncPtr parameter 1s non
182. NET server socket and start listening for incoming connections tfTeldUserStart can be either blocking or non blocking as specified by its last parameter Blocking Mode In blocking mode tfTeldUserStart should be called from a task tfTeldUserStart will not return unless an error occurs will block wait for incoming connections and execute the Telnet server code in the context of the calling task Choose the blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfTeldUserStart will return immediately after listening for incoming connections It is the user responsibility to then call tfTeldUserExecute periodically to execute the Telnet server code Choose the non blocking mode if you do not have an RTOS Kernel tfTeldUserExecute If the user calls TeldUserStart in non blocking mode then the user must call TeldUserExecute periodically If the user calls TeldUserStart in blocking mode then there is no need to call tfTeldUserExecute 6 114 Application Reference tfTeldUserStop The user calls tfTeldUserStop to close the telnet server socket and kill all existing Telnet connections tfTeldUserSend The user calls tfTeldUserSend to send data to a specified telnet client The telnet server will perform the NVT conversion before sending the data on the network tfTeldUserClose The user calls feldUserClose to force the server to close a specified telnet connection Telnet server to user interface
183. OR 2 3 want MS CHAP vl you must define TM USE PPP MSCHAP Since we already add TM PPP CHAP PROTOCOL in TM LCP AUTH PROTOCOL here we just need to add another algorithm for CHAP ifdef TM USE PPP MSCHAP chapAlgorithm TM CHAP MSV1 0x80 errorCode tfPppSetOption interfaceHandle int TM_PPP_CHAP_PROTOCOL TM_PPP_OPT_WANT TM CHAP ALG ADD char amp chapAlgorithm 1 assert errorCode TM ENOERROR fendif TM USE PPP MSCHAP 2 4 allows the peer to use this username for CHAP errorCode tfPppSetOption interfaceHandle int TM PPP CHAP PROTOCOL TM PPP OPT ALLOW TM CHAP USERNAME username strlen username assert errorCode TM ENOERROR 7 105 2004 Treck Incorporated Treck Real Time TCP IP User s Manual 2 5 set the priority order to be PAP CHAP MS CHAP errorCode tfPppSetAuthPriority IM PPP AUTHMETHOD PAP 1 assert errorCode TM ENOERROR errorCode tfPppSetAuthPriority IM PPP AUTHMETHOD CHAP 2 assert errorCode TM ENOERROR ifdef TM USE PPP MSCHAP errorCode tfPppSetAuthPriority IM PPP AUTHVETHCD MSCHAP VI 3 assert errorCode TM ENOERROR dendif TM USE PPP MSCHAP 3 Authenticator registers PAP CHAP MS CHAP authentication functions 3 1 Register PAP authenticate function errorCode tfPapRegisterAuthenticate interfaceHandle myPapAuthenticate assert errorCode TM ENOERROR
184. OR Success TM EINVAL Invalid FTP session pointer 6 43 Treck Real Time TCP IP User s Manual tfFtpGetReplyText include lt trsocket h gt int tfFtpGetReplyText ttUserFtpHandle ftpSessionPtr char replyStrPtr int replyStrLen i Function description This function retrieves the full text of the reply to the most recently executed FTP command Parameters Parameter Description fipSessionPtr FTP session handle replyStrPtr Pointer to string to place reply text replyStrLen Length of above string buffer Returns Value Meaning char Length of data copied into user string zero if invalid parameter or no reply string available 6 44 Application Reference tfFtpHelp include lt trsocket h gt int tfFtpHelp ttUserFtpHandle ftpSessionPtr char commandPtr ttFtpCBFuncPtr ftpDirCBFuncPtr i Function description This function retrieves help on the specified command from the remote FTP server When this data is retrieved a user supplied function is called The prototype for the callback function is int ftpCBFunc ttUserFtpHandle ftpSessionPtr char bufferPtr int bufferSize Parameters Parameter Description fipSessionPtr FTP session handle commandPtr Command to receive help on fipDirCBFuncPtr The function pointer of the user function to call when the directory listing is received See above for function prototype 6 45 Treck Real Time TCP IP User s Manual Returns
185. OTP request to a DHCP BOOTP server and will return with a TM EINPROGRESS errorCode Note that tfUseDhcp respectively tfUseBootp needs to have been called prior to calling tfConfigInterface otherwise the call will fail with error code TM EPERM An example of a configuration using the DHCP protocol would be errorCode tfConfigInterface myInterfaceHandle ttUserIpAddress 0 ttUserIpAddress 0 TM_DEV_IP_DHCP 1 unsigned char 0 Checking on completion of DHCP or BOOTP configuration Synchronous check The user can make multiple calls to tfConfigInterface to determine when the configuration has completed Additional calls to tfConfigInterface will return TM EALREADY as long as the BOOTP DHCP server has not replied tfConfigInterface will return TM ENOERROR if the BOOTP DHCP server has replied and the configuration has completed Asynchronous check To avoid this synchronous poll the user can provide a user call back function to tfUseDhcp respectively tfUseBootp that will be called upon completion of tfConfigInterface See tfUseDhcp respectively tfUseBootp for details Parameters Parameter Description interfaceld The device entry This is returned by tfAddInterface ipAddress The IP Address for this Interface netMask The net mask for this device Subnet or Supernet flag Special flags for this deviceOred together see below buffersPerFrameCount Number of scattered buffers allowed for each frame bei
186. P and IP software must be working Finally all routers along the return path must have correct routes On many systems the command users invoke to send ICMP echo requests is referred to as ping A sophisticated version of ping can send a series of ICMP echo requests capture responses and provide statistics about datagram loss It allows the user to specify the length of the data being sent and the interval between requests Less sophisticated versions merely send one ICMP echo request and await a reply Figure 1 33 shows the format of an echo request and reply messages 0 8 16 31 TYPE 8 or 0 CODE 0 CHECKSUM IDENTIFIER SEQUENCE NUMBER OPTIONAL DATA Fig 1 33 Format of an Echo Request and Reply The field OPTIONAL DATA is a variable length field that contains data to return to the sender An echo reply always returns the same data that was received in the request The sender to match replies to the requests uses fields SEQUENCE NUMBER and IDENTIFIER The value of the TYPE field specifies whether the message is a request 8 or a reply 0 1 48 2004 Treck Incorporated Introduction to TCP IP Summary Normal communication across an internet involves sending messages from an application on one host to an application on another host Routers may need to communicate directly with the network software on a particular host to report abnormal conditions or to send the host new routing information The Internet
187. PPP_CHAP_PROTOCOL TM_PPP_OPT_ALLOW TM_CHAP_ALG_ADD char amp chapAlgorithm 1 assert errorCode TM ENOERROR endif TM USE PPP MSCHAP 3 4 Peer wants to use this username errorCode tfPppSetOption interfaceHandle int TM PPP CHAP PROTOCOL TM PPP OPT WANT TM CHAP USERNAME username strlen username assert errorCode TM ENOERROR 3 5 Peer wants to use this password errorCode tfPppSetOption interfaceHandle int TM_PPP_CHAP_PROTOCOL TM_PPP_OPT_WANT TM_CHAP_SECRET password 8 Note You generally can t use strlen here for MS CHAP unicode password length count the octets in stead assert errorCode TM ENOERROR 3 6 Peer register new password function to get new password if the old one expires ifdef TM USE PPP MSCHAP errorCode tfMsChapRegisterNewPassword interfaceHandle myMsChapNewPassword assert errorCode TM ENOERROR fendif TM USE PPP MSCHAP Open the interface using 0 0 0 0 we will get one later from the authenticator 7 109 2004 Treck Incorporated Treck Real Time TCP IP User s Manual errorCode tfOpenInterface interfaceHandle zeroIPAddr F000 0 7 mask configFlags scatteredBufferCount ifdef TM_USE_PPP_MSCHAP char myMsChapNewPassword char username int lenPtr search peer s database to get the NEW password of this username calculate the UNICODE password length in oc tets and p
188. R t ER ERE EIE ERE HUE EE E tna 6 106 tfFSStructureMount sss eennn ener 6 107 tHE SS qn M ketene 6 108 ttESUSerAlloWwed oreste erat rae e eer eU 6 109 tHE S User 0 S00 pP 6 110 LEESUSerDOogOllt eio itor mb PU E ratito na teats 6 111 MEE S Write Hie eta rant ee creer ee tie cix 6 112 tfFSWriteFileRecord us 6 113 AANA BEN 1171 Me 6 114 User to Telnet server interface ccccccccscccssccessecsseceseecsseecsseseeeseseseeeeens 6 114 Telnet server to user interfaGe iu serrer reete eene n 6 115 tETeldClosed a eese etti Era A EEE t 6 116 pa ES Tro TL S sun Sects rkcso nieke ea keea e a elencesivasensiweeaas ante 6 117 ttTeldOpened u tenete rH e UU ERRES 6 118 ttIeldSendQueueBytes nina ina ere erg 6 119 tfTeldSendQueueSize sse eene nnne 6 120 tf TeldUserClose ic erret e OVE nies een ane eases 6 121 tfTeldUserExecute sess nnne nenne 6 122 ES EES eT c ee E etu NE T PAESE 6 123 HP Ve A Ser Staite o lee dt 6 126 tf Weld User Stop ssc cns ea aic oi rire ner Aurea 6 129 Treck Test Suite sscesicsessssesccsesensescesescevess esescevensvscveesensvevevessuuesveseievseueaseseesouees 6 130 Des fipti ti error remen ennemi een ener 6 130 Blocking Mode ueneno erratis irm E E EEE 6 132 Data validation e aee trece ERES er EE ERE RERO 6 133 Random testing mode 5 nd nen etui 6 133 Locking Test MN as 6 134 He POSE AEO AEEA tes ete ete dH S 6 134 tf Te StU
189. RABOR TM FTP LOCALERR TM FTP EXSPACE TM FTP NOSPACE TM FTP FILENAVAIL TM FTP FILENAME TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMDPARAM TM FTP SERVNAVAIL Application Reference Meaning The call is non blocking and did not complete Invalid ftpSessionPtr or bad filename Previous command has not finished Command requires user to be loggedin and user is not Command requires connection and user is not connected Command not supported by the user No error Success Data connection already open transfer started File status okay about to open data connection Can t open data connection Connection trouble closed transfer aborted Requested action aborted local error in processing Requested file action aborted exceed storage allocation Request action not taken insuffi cient storage space in system Requested file action not taken file unavailable Requested action not taken file name not allowed Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented for that parameter Service not available closing TELNET connection Treck Real Time TCP IP User s Manual TM_FTP_NOTLOGIN Not logged in 6 62 Application Reference tfFtpSyst include lt trsocket h gt int tfFtpSyst ttUserFtpHandle ftpSessionPtr char bufferPtr int bufferSize Function Description This function returns information about the sys
190. Re 7 61 TAS OST E nent 7 62 Public VS Pry ate pe 7 62 Reference Implementation seeds 7 62 NAtCOBEHS ean eter die te een I P 7 63 tiNatUnConiie cic ded nia adn Aida edi eit erre e eR eee aes 7 64 ti NatContis Na pt 2 poppe e RUE dite A 7 65 tiNatGonfig inner ICDServet o iere mesnnrnnteiettserennuts 7 66 ttNatContigInnerUdDSeEVeL s uu ur GO per Doer Deere DS 7 67 t NatConfigInnerFtpServet een petentem eese eo edec eiecit 7 68 ti Nat Ont S STAGES nm ur rette d USE a EE EAEE 7 70 t NatContigDynatiic 5 eno neetectiee teens lee eee 7 71 ttNatContig Max Enie Seisson enea assarrar sbacvapebizncbsnsespesteeiets 7 12 tENatDu mip corri ee atte oni ak on isin tense hee ces 7 73 PPP Interface e 7 74 Introduction to PPP intcr pe Petre eb o cR eene tees 7 74 2004 Treck Incorporated lag diable 7 74 PPP and Authenticatioh espress saves 50d PO detre Hs bar lents 7 76 tiChapRegisterA uth enti ate Lern ntes ete rene tees 7 78 tfMsChapRegisterAuthenticate seen 7 79 tfMsChapRegisterNewPasswotd eese 7 80 tfEapMd5RegisterAuthenticate eese 7 81 tfEapSetOptioh sis ocn ci ake rene tree e arae evans 7 82 itGietPppDrsIpAddtress 2 5 oot oe tre Re EAO ane ETRE GS 7 84 tfGetPppPeerlIpAddress essence tiet ei rote dete vest 7 85 tfPapRegisterAuthenticate isise erecto E REO Lus iUe Ss 7 86 tfPppSetOptlon sinon eret aiken ee
191. Real Time TCP IP User s Manual B 2 2004 Treck Incorporated RTOS Notes RTOS Application Note for uC OS uC OS is a simple preemptive kernel It does not have any way to perform dy namic memory allocation It does contain counting semaphores message queues and mail boxes as well a preemptive scheduling With your CD ROM you will have received various ports of uC OS for different processors If your processor is not included in the ports of uC OS that Treck provides then you might want to visit the uC OS web site at http www ucos ii com Predefined Settings in TRSYSTEM H There are processor specific settings for uC OS in trsystem h They will setup uC OS the same way that it was used in the Treck test facilities for various processors TM KERNEL UCOS X86 is used for the Intel 80x86 family in real mode TM KERNEL UCOS PPC is used for the PowerPC specifically the MPC860 for Motorola TM KERNEL UCOS CPU32 is used for the 32 Bit 68K family of processors from Motorola If you define one of the above in trsystem h the processor inline assembly task and memory allocation definitions will be made for you You can modify the uC OS processor specific area of trsystem h to suite your applications needs Initialization uC OS does not require any special initialization therefore the t KernelIniticalize should be a stub function Memory Allocation and Free Because uC OS does not contain any method for performing dynamic memory all
192. Real Time TCP IP User s Manual tfF SDeleteFile include lt trsocket h gt int tfFSDeleteFile void userDataPtr char pathNamePtr Function description Given the unique user data pointer as returned by tfFSUserLogin and a file name this function deletes the file Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFsUserLogin pathNamePtr Pointer to a null terminated string containing file name Returns Value Meaning 0 Success 1 Failure 6 94 Application Reference tfF SFlushFile include lt trsocket h gt int tfFSFlushFile void userDataPtr void fileDataPtr Function description Given a unique user data pointer as returned by tfFSUserLogin and a file data pointer as returned by tfFSOpenFile this function flushes the file Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin fileDataPtr Pointer to file data structure as returned by tfFSOpenFile Returns Value Meaning 0 Success 1 Failure 6 95 Treck Real Time TCP IP User s Manual tfF SGetNextDirEntry include lt trsocket h gt int tfFSGetNextDirEntry void userDataPtr void dirDataPtr char bufferPtr int bufferSize Function description Given the unique user data pointer as returned by tfFSUserLogin and a directory data pointer as returned by tfFSOpenDir this function retrieves the next entry in the directo
193. SErEXeCute 56a aos re tO nn Ne intense ens 6 136 INCESEAE ss 6 137 TritroductlOTis nire Ne tet en e eset 6 137 Public API tabissutissdibmettetettutiet ud n nei 6 138 CEN SL KC 6 138 2004 Treck Incorporated ttNtEntry CBFuncPtrt inasre pa deste reete ett eade beue euge 6 139 tENIOEERIGHeAaderStr c oet EL e HERO fuis 6 140 tENtGetArpEHeadetrStr moseri ec niet etes tette ec esee ette ped 6 141 tENtGetPopEleaderStt or dee err o D HR HEU UOTE RE 6 142 tENtGetUdpHeaderStr 5 sus 5 ioeeiec e eese Ee eons sve celi reds inet 6 143 CHING Rte Eth y TOS 1 TER 6 144 CENtATPENTYTOS Eee enr Ritter alc teer ended 6 145 tENUDCpEBUFy TOS o epi D Dg plor E PR See Hb b parce REOS 6 146 tENEtUdpEntry lOStr ice eoo te er eie tee See eee sues De dee Eee ep is eieh 6 147 bascule 6 148 NIRteENTY e R 6 148 HNAPEDIY e est 6 151 TUN CI se soris M 6 152 LAN LOG 6 Ei Cii dem E 6 156 Optional Protas Rr A AUTO IP Configuration ccsccssssssssssssssesescsssssssessscssesssscssesscsssssseseees 7 3 DESCHpioloco totes tetuer NEL ee eee rete ipie fas ef 7 3 Enabling AUTO IP 5 eren eerte eret db code ER vore ze ea 7 4 Ex mple zo ooo antenne T a e eels 7 4 tfAutoIPPiCkIpA ddress issue n e dessert fee ct etse evo riesenie ee 7 7 itCancelCollisionDeteCUOl oic etr E PR steels 7 8 tfContfigAutolp rater inner devant 7
194. SIZE 3000 char bufferArray TM BUF ARRAY SIZE retCode tfZeroCopyRecv ssd amp recvMessageHandle amp dataPtr sizeof bufferArray MSG SCATTERED if retCode gt 0 1 recvdLength retCode tm assert testzUdpToFrom retCode sendDataLength scatteredRecvCopyNCheck recvMessageHandle ttUser8BitPtr dataPtr ttPktLen retCode void tfFreeZeroCopyBuffer recvMessageHandle void scatteredRecvCopyNCheck ttUserMessage recvMessageHandle ttUser8BitPtr dataPtr ttPktLen msgLength ttUserPacketPtr recvPacketUPtr char bufferPtr int extraCount extraCount 1 recvPacketUPtr ttUserPacketPtr recvMessageHandle 5 101 2004 Treck Incorporated Treck Real Time TCP IP User s Manual bufferPtr amp bufferArray 0 tm_assert testzUdp msgLength recvPacketUPtr gt pktuChainDataLength tm_assert testzUdp msgLength lt sizeof bufferArray tm_assert testzUdp dataPtr recvPacketUPtr gt pktuLinkDataPtr do 1 tm assert testzUdp msgLength gt recvPacketUPtr gt pktuLinkDataLength tm_assert testzUdp recvPacketUPtr gt pktuLinkDataP tr ttUser8BitPtr O tm_bcopy recvPacketUPtr gt pktuLinkDataPtr bufferPtr recvPacketUPtr gt pktuLinkDataLength bufferPtr recvPacketUPtr gt pktuLinkDataLength msgLength recvPacketUPtr gt pktuLinkDataLength recvPacketUPtr recvPacketUPtr gt pktuLinkNextPtr extraCount j while msgLength ttPktLen 0 amp amp recvPacketUPtr
195. TM EINVAL One of the passed parameters is not valid 5 11 2004 Treck Incorporated Treck Real Time TCP IP User s Manual getsockname include lt trsocket h gt int getsockname int socketDescriptor struct sockaddr myAddressPtr int addressLengthPtr Jur Function Description This function returns to the caller the Local IP Address Port Number that we are using on a given socket Parameters Parameter Description socketDescriptor The socket descriptor that we wish to inquire about myAddressPtr The pointer to the address structure where the address information will be stored addressLengthPtr The length of the address structure Returns Value Meaning 0 Success l An error occurred getsockname can fail for any of the following reasons TM EBADF socketDescriptor is not a valid descriptor TM EINVAL One of the passed parameters is not valid 5 12 2004 Treck Incorporated Programmer s Reference getsockopt include lt trsocket h gt nt getsockopt E SocketDescriptor t protocolLevel t optionName ar optionValuePtr D s optionLengthPtr HQ bb BA H D D D D 2 Function Description getsockopt is used retrieve options associated with a socket Options may exist at multiple protocol levels they are always present at the uppermost socket level When manipulating socket options the level at which the option resides and the name of the option must be specified To manipulate
196. TM_DEV_OKAY 5 driverSend This routine is used to send the data out the network device Since Treck protocols support scatter send for devices there is a flag that gets passed into the device driver send routine There are two possible values for this flag TM USER BUFFER MORE TM USER BUFFER LAST The flag value TM USER BUFFER MORE means that there is more data to follow for this frame The flag value TM USER BUFFER LAST means that this is the last piece of this frame If your device does not support scatter send then the flag will always be set to TM USER BUFFER LAST with the exception of PPP or Slip serial devices 4 63 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Ethernet devices The Treck Ethernet or Treck Null link layer code will only send scattered data if the device supports scatter send If the device supports scatter send the only Ethernet scattered data frames sent by the Treck stack are TCP packets An Ethernet device driver does not need to copy the Treck data and can keep a pointer to it The data will not be freed until fSendCompleteInterface is called later on by the user when the user knows that the packet has been transmitted tfSendCompleteInterface Notes tfSendCompleteInterface may be called only once per complete frame which is denoted by the TM USER BUFFER LAST flag Please note that this function will operate on the frames in the order that they we
197. TP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP NAVAIL Description FTP session handle Pointer to buffer to receive Size of above result buffer Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Requested action not taken file Application Reference unavailable tfFtpQuit include lt trsocket h gt int tfFtpQuit ttUserFtpHandle ftpSessionPtr Function description This function quits the current FTP connection informs the remote server that we are closing all current connections Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK This FTP session is non blocking and the call did not complete TM EACCES Previous command did not com plete TM ENOTCONN The user is not currently connected to a FTP server TM BINVAL Invalid FTP session pointer TM FTP SYNTAXCMD Syntax error command unrecog nized Treck Real Time TCP IP User s Manual tfFtpRein include lt trsocket h gt int tfFtpRein ttUserFtpHandle ftpSessionPtr Function description R
198. TYPE BINARY blockingState is neither TM BLOCKING ON nor TM BLOCKING OFF blockingState is TM_BLOCKING ON and blocking mode is not enabled for the stack An error occurred with one or more of the socket calls within the function The TFTP server returned an Undefined error code message in the error packet 6 77 Treck Real Time TCP IP User s Manual TM_TFTP_NOTFOUND The TFTP server returned a File not found message in the error packet TM TFTP NOUSER The TFTP server returned a No such user message in the error packet TM TFTP BADOP The TFTP server returned an Illegal TFTP operation message in the error packet TM_TFTP_BADID The TFTP server returned an Unknown transfer ID message in the error packet TM TFTP ACCESS The TFTP server returned an Access violation message in the error packet TM TFTP NOSPACE The TFTP server returned a Disk full alloc exceeded message in the error packet TM TFTP FILEEXISTS The TFTP server returned a File already exists message in the error packet 6 78 Application Reference tfTftpSetTimeout include lt trsocket h gt void int int Function description tfTftpSetTimeout timeout retry This function allows the user to set the retry and timeout values for the TFTP client Parameters Parameter timeout retry Returns None Description The length of time 1n seconds a connection can remain silent before it ti
199. The DHCP client sends its domain name to the DHCP server during the exchange and the server acknowledges it if it supports this feature At the end of the DHCP transaction both the client and the server know the client s domain name Flags are used to negotiate which part of the DNS update will be performed by the DHCP server and which part by the DHCP client Treck DHCP client always fully delegates the DNS A and AAAA resource record updates to the DHCP server the DHCP server will update the PTR reverse lookup resource record To use FQDN define TM USE DHCP FQDN in trsystem h and rebuild the Treck stack Your application can then enable the use of FQDN with DHCP client by specifying the TM DHCPF FQDN ENABLE flag when calling the APIs tfDhcpConfSet tfDhcpUserSet and passing the desired domain name in the clientIdPtr and clientIdLength parameters If DHCP FQDN is enabled userBtEntry will also contain the FQDN option related parameters The FQDN domain name returned by the server in userBtEntryPtr gt btuServerFqdn its length in userBtEntryPtr gt btuServerFqdnLen DNS error codes RCodel and RCode2 returned by the DHCP server in userBtEntryPtr gt btuFqdnRCodel and userBtEntryPtr gt btuFqdnRCode2 a flags that indicates the FQDN update status in userBtEntryPtr gt btuFqdnStatus Possible valued for this flag are a combination of TM FQDNF PARTIAL if the received domain name was partial TM FQDNF MALFORMED if t
200. The record that immediately follows the record for astIpAddress lastPreference will be retrieved Parameters Parameter Description hostnameStr Hostname to resolve lastIpAddress IP address of the last retrieved mail host for this host lastPreference Preference of the last retrieved mail host for this host ipAddressPtr Set to the IP address of the host Returns Value Meaning TM_EINVAL Invalid host name string or IP address pointer TM_EWOULDBLOCK DNS lookup in progress The user should continue to call tfDnsGetHostName with the same parameters until it returns a value other than TM EWOULDBLOCK TM ENOERROR DNS lookup successful IP address stored in ipAddressPtr Treck Real Time TCP IP User s Manual tfDnsSetOption int tfDnsSetOption int optionType int optionValue Function Description This function sets various DNS options which are outlined below Option type Description TM DNS OPTION RETRIES Maximum number of times of retransmit a DNS request TM DNS OPTION CACHE SIZE Maximum number of entries in the DNS cache Must be greater than Zero TM DNS OPTION TIMEOUT Amount of time in seconds to wait before retransmitting a DNS request Parameters Parameter Description optionType See above optionValue Value for above option Returns Value Meaning TM EINVAL Invalid value for above option TM ENOPROTOOPT Option not supported not in above list TM ENOERROR Option set successfully Applicat
201. The socket number to check on the amount of bytes acked by the peer Returns Value Meaning gt 0 Number of bytes that have been sent to and acked by the TCP peer 1 An error has occurred tfGetSendCompltBytes can fail for the following reasons TM_ EBADF The socket descriptor is invalid TM_EOPNOTSUPP The socket is not a TCP socket 5 78 2004 Treck Incorporated Programmer s Reference tfGetSocketError include lt trsocket h gt int tfGetSocketError int socketDescriptor Function Description This function is used when any socket call fails TM SOCKET ERROR to get the error value back This call has been added to allow for the lack ofa per process errno value that is lacking in most embedded real time kernels Parameters Parameter Description socketDescriptor The socket descriptor to get the error on Returns The last errno value for a socket 5 79 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetWaitingBytes include lt trsocket h gt int tfGetWaitingBytes int socketDescriptor Function Description This function is used to get the number of bytes waiting to be read on a socket The tfloctl call with the FIONREAD request can be used instead Parameters Parameter Description socketDescriptor The socket number to check on the amount of waiting bytes Returns Value Meaning gt 0 Number of bytes waiting to be read 1 An error has occurred tfGetWaitingBytes ca
202. Time TCP IP User s Manual Critical Section Handling The functions ffKernelSetCritical and tfKernelReleaseCritical are used to set critical sections around code that is NOT reentrant The critical sections are used to prevent ANY other calls into the protocol stack These are used to prevent one task from updating a pointer while another task is accessing it Without critical sections there is the chance of corrupting pointers ifa pointer update is interrupted by another task or an ISR The Treck protocol stack is designed to keep these critical sections to a minimum usually about five assembly instructions Example for an Intel x86 void tfKernelSetCritical void asm cli void tfKernelReleaseCritical void asm sti 4 26 2004 Treck Incorporated Integrating into Your Environment TIP If you can guarantee that no preemption of Treck code will occur by another task or ISR calling a Treck function this includes the tfNotifyInterfacelsr function then the critical sections are not needed It is recommended that you continue to use the critical sections unless you are absolutely sure that no preemption of Treck code will occur You can also in line these functions by defining tm_kernel_set_critical and tm_kernel_release_critical to be the assembly for these functions to save the extra function call in the TRSYSTEM H file You can find examples in TRMACRO H This will enhance the data transfer speed Error Loggin
203. Transmission Control Protocol Now that we have discussed and understand the sliding window principle we can look at the reliable stream service provided by the TCP IP Internet protocol suite The service is defined by the Transmission Control Protocol or TCP This reliable stream service is so important that the entire protocol suite is referred to as TCP IP It is important to remember that TCP is not a piece of software it is acommunication protocol People seem to encounter TCP software much more than they do the communication protocol so it is natural that to think of a particular implementation as the standard TCP is both a connection oriented protocol and a byte stream oriented protocol What this means is that TCP transmits a set of bytes at a time These are called TCP segments Until now we have discussed only packet oriented delivery of information For example if we were to make a call to the stack with two 100 byte pieces of information using TCP it would send the information as a 200 byte piece Unlike other protocols it does not break the information into packets and then send it There is no packet delineation By using this method data transfer can be likened to a modem connection The method is essentially the same but the commands we use are different We use the connect function from the sender The receiver uses the isten function to receive incoming data TCP Header We say that TCP is very reliable The way TCP achiev
204. Treck An example of this function is as follows int tfKernelCreateCountSem ttUserGenericUnionPtr countingSemaphore int retCode Create and Initialize the semaphore to zero countingSemaphore gt genVoidParmPtr RTOSSemCreate 0 if countingSemaphore gt genVoidParmPtr void TM FAR 0 retCode 0 else retCode 1 return retCode 4 29 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The function tfKernelPendCountSem is used to pend or wait on a counting semaphore This function must wait indefinitely until the post occurs We pass back in the counting semaphore in the union that was used for the create An example of this is as follows int tfKernelPendCountSem ttUserGenericUnionPtr countingSemaphore int retCode if RTOSSemPend countingSemaphore gt genVoidParmPtr RTOS_NO_ERR retCode 0 else retCode 1 return retCode The function ffKernelPostCountSem is used to wake up another task or thread that has called zfKernelPendCountSem An example of this function is as follows int tfKernelPostCountSem ttUserGenericUnionPtr countingSemaphore int retCode if RTOSSemPost countingSemaphore genVoidParmPtr RTOS_NO_ERR retCode 0 else retCode 1 return retCode 4 30 2004 Treck Incorporated Integrating into Your Environment ISR Interface The ISR interface is used to provide an i
205. ULDBLOCK Non blocking datagram socket send if the socket does not have enough buffer space available to hold the message being sent no data is being sent and 1 is returned with socket error being set to TM EWOULDBLOCK The select call may be used to determine when it is possible to send more data 5 43 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Sending Out of Band Data For example if you have remote login application and you want to interrupt with a C keystroke at the socket level you want to be able to send the C flagged as special data also called out of band data You also want the TCP protocol to let the peer or remote TCP know as soon as possible that a special character is coming and you want the peer or remote TCP to notify the peer or remote application as soon as possible At the TCP level this mechanism is called TCP urgent data At the socket level the mechanism is called out of band data Out of band data generated by the socket layer is implemented at the TCP layer with the urgent data mechanism The user application can send one or several out of band data bytes With TCP you cannot send the out of band data ahead of the data that has already been buffered in the TCP send buffer but you can let the other side know with the urgent flag i e the term urgent data that out of band data is coming and you can let the peer TCP know the offset of the current data to the last byte of out of
206. UseAsyncPpp or tfUseAyncServerPpp functions you will get an error 4 44 2004 Treck Incorporated Integrating into Your Environment Step 9 Adding a New Device Driver This step is the most complicated because the device driver interface is so versatile The device driver interface is the same for all link layers including PPP You will find existing device drivers in the drivers directory If we have provided a device driver chances are that you will still need to modify it for your hardware platform Device drivers can almost never be moved between different hardware platform types without modification To allow you to hook up your driver in many different ways we provide these additional functions that you would call from your driver and task level to allow for a receive task transmit task and send complete task or to poll the device driver The use of these functions is optional depending on your environment e tfNotifyInterfacelsr e tfNotifyInterfaceTask may be used in addition to tfNotifyInterfacelsr e tfCheckReceivelnterface e tfinterfaceSetOptions e tfCheckXmitInterface e tfCheckSendiInterface e tfWaitReceiveInterface only if TM TASK RECV is defined e tfWaitXmitInterface only if TM TASK XMIT is defined e tfWaitSentInterface only if TM TASK SEND is defined tfRecvInterface is used to move received data into the stack and tfSendCompleteInterface is used to notify the stack that data has been sent The
207. User s Manual Parameters Parameter socketDescriptor bufferPtr bufferLength flags fromPtr fromLengthPtr Description The socket descriptor to receive data from The buffer to put the received data The length of the buffer area that bufferPtr points to See Below The socket from which the data is or to be received The length of the data area the fromPtr points to then upon return the actual length of the from data The flags parameter is formed by ORing one or more of the following MSG DONTWAIT MSG_PEEK Returns Value gt 0 5 38 2004 Treck Incorporated Do not wait for data but rather return immediately Peek at the data present on the socket the data is returned but not consumed so that a subsequent receive operation will see the same data Meaning Number of bytes actually received from the socket EOF An error occurred recvfrom will fail if TM EBADF TM BINVAL TM EMSGSIZE TM EPROTOTYPE TM ENOBUFS TM EWOULDBLOCK Programmer s Reference The socket descriptor is invalid One of the parameters is invalid The socket requires that message be received atomically and bufferLength was too small TCP protocol requires usage of recv not recvfrom There was insufficient user memory available to complete the operation The socket is marked as non blocking and no data is available to be read 5 39 2004 Treck Incorporated Treck Real Time TCP IP U
208. UserRelease include lt trsocket h gt int tfDhcpUserRelease ttUserInterface interfaceHandle int userIndex Function Description Cancel a DHCP request and or a DHCP lease that had been previously obtained using tfDhcpUserStart Parameters Parameter Description interfaceHandle Ethernet interface handle userIndex User Index between 0 and tvMaxUserDhcpEntries 1 Returns Value Meaning TM ENOERROR Success TM BINVAL Bad parameter 7 41 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDhcpUserSet include trsocket h int tfDhcpUserSet Cy ttUserInterface interfaceHandle int userlIndex int flags ttUserlpAddress requestedIpAddress unsigned char clientIdPtr int clientIdLength Function Description Allows the user to set the DHCP initial state INIT or INIT REBOOT prior to the user calling tfDhcpUserStart Called by the user when the user wants to specify his her own Client ID or suppress the Client ID option or if the user wants to start in INIT REBOOT state or if the user wants to specify an IP address in the DISCOVERY phase e Ifuser specifies INIT REBOOT state the Requested IP address needs to be specified as well e Ifuser specifies INIT state i e TM DHCPF INIT REBOOT not set optionally the user can specify the IP address and or the CLIENT ID option e If CLIENT ID is not specified and not suppressed the stack will pick a unique CLIENT ID that
209. UserStart returns TM ENOERROR the DHCP request has completed successfully ATM EINPROGRESS error return indicates that a DHCP configure or request has been sent this is alright A TM EALREADY error return indicates that a DHCP discover request has been previously sent as a result of a previous call to tfDhepUserStart If the function returns TM EINPROGRESS or TM EALREADY wait for the DHCP configuration to complete 1 e for dhepNotifyFunc to be called During the wait make sure tfTimerUpdate or tfTimerUpdatelsr and tfTimerExecute get called Ifthe function returns TM EINPROGRESS or TM EALREADY then when the DHCP request has completed or timed out the dhepNotifyFunc will be called as follows 7 44 2004 Treck Incorporated Optional Protocols dhcpNotifyFunc ethernetInterfaceHandle userIndex errorCode where the userIndex corresponds to the second parameter of tfDhcpUserStart and errorCode indicates whether the DHCP request has been successful errorCode 0 or timed out errorCode TM ETIMEDOUT Parameters Parameter InterfaceHandle UserIndex dhcpNotifyFuncPtr Pointer Returns Value TM ENOERROR TM EINPROGRESS TM EALREADY TM EINVAL TM ENOBUFS Other Description Ethernet interface handle User Index between 0 and tvMaxUserDhcpEntries 1 To a function that will be called when the DHCP request has completed or timed out Meaning Success The DHCP notify function wi
210. V Parameters Parameter socketDescriptor protocolLevel optionName optionValuePtr optionLength ProtocolLevel SOL SOCKET IP PROTOIP IP PROTOTCP Programmer s Reference Sets the minimum window probe timeout interval in milliseconds The network computed window probe timeout is bound by TM TCP PROBE MIN and TM TCP PROBE MAX Default 500 milliseconds Sets the maximum window probe timeout interval in milliseconds The network computed window probe timeout is bound by TM TCP PROBE MIN and TM TCP PROBE MAX Default 60 000 milliseconds Sets the interval between Keep Alive probes in seconds See TM TCP KEEPALIVE CNT This value cannot be changed after a connection is established and cannot be bigger than 120 seconds Default 75 seconds Description The socket descriptor to set the options on The protocol to set the option on See below The name of the option to set See below and above The pointer to a user variable from which the option value is set User variable is of data type described below The size of the user variable It is the size of the option data type described below Description Socket level protocol IP level protocol TCP level protocol 5 57 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ProtocolLevelOptionName Option data type Option value SOL_SOCKET SO_DONTROUTE int Oorl SO KEEPALIVE int 0 or 1 SO_LINGER struct linger SO_OOBINLINE i
211. _ERROR amp amp failed 0 Retrieve the socket error for failed bind call errorCode tfGetSocketError sd printf bind failed d n errorcode failed 1 if failed 0 Send some loop back data to our own socket addr sin_addr s_addr inet_addr 127 0 0 1 sentLength sendto sd bufferArray len 0 struct sockaddr TM FAR amp addr sizeof struct sockaddr in if sentLength TM SOCKET ERROR amp amp failed 0 Retrieve the socket error for failed sendto call errorCode tfGetSocketError sd printf sendto failed d n errorCode failed 1 if failed 0 printf Sd sent successfully n sentLength Receive some loop back data from our own socket recvdLength recvfrom sd bufferArray len 0 struct sockaddr TM FAR 0 0 4 42 2004 Treck Incorporated Integrating into Your Environment if recvdLength TM_SOCKET_ERROR amp amp failed 0 Retrieve the socket error for failed recvfrom call errorCode tfGetSocketError sd printf recvfrom failed d n errorCode failed 1 if failed 0 printf Sd received succesfully n recvdLength if sd TM_SOCKET_ERROR All done Close the socket void tfClose sd if failed 0 printf UDP LOOP BACK Test success n 4 43 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 8 Using E
212. a series of API s that you can use to hook Treck to any environment These API s include a kernel interface timer interface driver interface sockets interface and miscellaneous API s to allow you to configure Treck TCP IP to your environment Built inside of Treck is a locking system buffer system and timer system These different systems are described in this chapter so that you know how Treck uses the API s that are described in the next two chapters You will also need to know what the requirements are to integrate Treck Real Time TCP IP into your environment Locking System Treck Real Time TCP IP can be used in many different models You do not need an operating system in order to use Treck in your environment However if you have an operating system we will of course use that operating system to allow us to work best for you Operating systems seem to come in two different types The simplest operating system is a non preemptive operating system The most common variety of an operating system is a preemptive operating system The difference between the two types is crucial when you decide to integrate Treck Real Time TCP IP into your environment Preemption is when a task is interrupted by another task of higher priority or when a fixed time interval has occurred With a non preemptive operating system the user does not need to set up any critical sections A critical section is a section of code that is protected from preemption
213. a RST and discards all outstanding data Parameters Parameter Description socketDescriptor The socket descriptor to Reset Returns Value Meaning 0 Operation completed successfully l An error occurred tfResetConnection can fail for the following reasons TM EBADF The socket descriptor is invalid TM EOPNOTSUPP The socket is nota STREAM socket 5 90 2004 Treck Incorporated Programmer s Reference tfSendToFrom include lt trsocket h gt int tfSendToFrom int socketDescriptor char bufferPtr int bufferLength int flags const struct sockaddr toAddressPtr int addressLength const struct sockaddr fromAddressPtr Function Description tfSendToFrom behaves the same as sendto except for the use of the parameter fromAddressPointer This parameter specifies the address from where data is to be sent tfSendToFrom is used to transmit a message to another transport end point tfSendToFrom may be used at any time either in a connected or uncon nected state but not for a TCP socket socketDescriptor is a socket created with socket The address of the target is given by toAddressPtr with addressLength specifying its size If the message is too long to pass atomically through the underlying protocol then 1 is returned with the socket error being set to TM EMSGSIZE and the message is not transmitted A return value of 1 indicates locally detected errors only A positive return value does not impli
214. a default gateway needs to be added for that interface then the retrieved IP address should be used to add a default gateway through the corresponding interface If a static route needs to be added for that interface then the retrieved IP address should be used to add a static route through the corresponding interface Parameters Parameter Description interfaceHandle The interface Handle to get the Peer IP address from iflpAddress Ptr The pointer to the buffer where the Peer PPP IP address will be stored into Returns Value Meaning 0 Success TM_EINVAL One of the parameters is null or the device is a LAN device TM ENETDOWN Interface is not configured 7 85 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfPapRegisterAuthenticate include lt trsocket h gt int tfPapRegisterAuthenticate ttUserInterface interfaceHandle ttPapAuthenticateFunctPtr authFunctionPtr Function Description When acting as a PPP server a function must be called to validate an incoming authentication request This function is passed the username and password from the peer by the PPP layer The function must return 1 fora valid username password or 0 for an invalid username password The prototype for the authentication function 1s defined to be int myPapAuthenticate char username char password Parameters Parameter Description interfaceHandle The interface to use this authentica tion routine for authFunctionPtr Th
215. a random AUTO IP address ipAddress tfAutoIPPickIpAddress if ipAddress ttUserIpAddress 0 autoIpParam genIntParm mhomeIndex Register the call back function for that IP address with the stack y errorCode tfUseCollisionDetection ipAddress tfAutoIpFinish autoIpParam else errorCode TM_ENOENT while errorcode TM EADDRINUSE if errorCode TM_ENOERROR Selected AUTO IP address is not in the ARP cache Start sending ARP probes on the interface We use the default probe interval 2s and number of probes 4 mf 7 4 2004 Treck Incorporated Optional Protocols errorCode tfUserStartArpSend interfaceHandle ipAddress 0 0 0 return errorCode int tfAutoIpFinish ttUserInterface interfaceHandle ttUserIpAddress ipAddress int errorCode ttUserGenericUnion autoIpParam int mhomeIndex Cancel the collision detection check on that IP address void tfCancelCollisionDetection ipAddress mhomeIndex autoIpParam genIntParm if errorCode TM_ENOERROR No collision occurred Finish configuring the interface tlConfigured 1 if mhomeIndex 0 User used tfOpenInterface with TM DEV IP USER BOOT on mhome index 0 my errorCode tfFinishOpenInterface interfaceHandle ipAddress TM_IP_LOCAL_NETMASK if errorCode TM_ENOERROR printf tfFinishOpenInterface with 0x x n ipAddress else printf tfFini
216. a user tfFSWriteFile Write some bytes from a buffer to a file tfFSWriteFileRecord Write a record from a buffer to a file Entry points from the FTP client to the file system Note The Treck FTP client only uses a subset of the functions described above namely the eight functions in the list below tfFSCloseDir tfFSCloseFile tfFSOpenDir tfFSOpenFile tfFSReadFile tfFSUserLogin tfFSUserLogout tfFSWriteFile Entry points from the TFTP server to the file system Note The Treck TFTP server only uses a subset of the functions described above namely the six functions in the list below tfFSCloseDir tfFSCloseFile tfFSOpenDir tfFSOpenFile tfFSReadFile tfFSWriteFile Treck Real Time TCP IP User s Manual tfF SChangeDir include lt trsocket h gt int tfFSChangeDir void userDataPtr char pathNamePtr Function description Given the unique user data pointer as returned by tfFSUserLogin and a directory name this function changes the user s working directory to the new directory Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin pathNamePtr Pointer to a null terminated string containing directory path name Returns Value Meaning 0 Success 1 Failure 6 90 Application Reference tfFSChangeParentDir include lt trsocket h gt int tfFSChangeParentDir void userDataPtr Function description Given the unique user data pointer as retur
217. able However send and receive rings are generally the most complex part ofa driver s logic Check your ring logic very carefully by hand if necessary We also provide an API for use at the driver level that should alleviate this problem Please see the Programmers Reference Section of this manual 2004 Treck Incorporated 10 11 12 13 14 Debugging a Device Driver Use counters to compare the number of times the device driver send function is called with the TM USER BUFFER LAST flag set with the number of tfSendCompleteInterface is called tfSendCompleteInterface should be called once and only once for each time that the driver s send function is called with the TM USER BUFFER LAST flag set Calling tfSendCompleteInterface either too frequently or too infrequently can lead to memory loss and or corruption Use counters to compare the number of receive ISR events with the number of calls made to driver receive function For each packet the chip receives the stack should be notified Similarly for each packet the stack is notified of it should call the driver receive function once This test will verify that this is happening No printf or anything that takes too much CPU time inside the ISR Putting any extra code inside an ISR can be dangerous but printf statements and their relatives can be doubly so On various platforms printf involves acall to the operating system that may result in interrupts b
218. accepts full responsibility for the problems of reliability including message loss duplication delay and even out of order delivery However we can look at certain applications that do not need to utilize these strict options For example if a connection is made over the Internet that needs to transmit voice and video applications we can see that speed is more important than reliability Because packets are transmitted at such a high rate of speed we are willing to sacrifice the reliability for rate of transfer If we were using a reliable method for voice and video we would have to wait for two machines to exchange information to ensure that the information will not be lost sacrificing time However if we were to make the same connection using UDP there would be a steady steam of packets entering the application because there is no use of acknowledgements If two packets were to get discarded or sent out of order or even lost the result that we might see would be very minimal Again the important thing to decide is which is more important speed or reliability 1 49 2004 Treck Incorporated Treck Real Time TCP IP User s Manual UDP Message Format Each UDP message is referred to as a user datagram A user datagram consists of two parts a UDP header and a UDP data area As we can see in Figure 1 34 a UDP header is divided into four parts a 16 bit field that specifies the port from which it originated the port that it is going
219. ace can be configured that way In that case the following steps are needed after having called linkLayerHandle tfUseEthernet interfaceHandle tfAddInterface namePtr linkLayerHandle ee ee errorCode tfUseBootp interfaceHandle myNotifyFunction errorCode tfOpenInterface interfaceHandle OUL OUL TM_DEV_IP_BOOTP 1 Note that we have called tfOpenInterface with the TM DEV IP BOOTP flag set Note other flags such as TM DEV IP FORW ENB could be ORed to TM DEV IP BOOTP as needed Note The user must wait for the BOOTP configuration to complete During the wait ensure tfTimerUpdate or tf TimerUpdatelsr and tfTimerExecute are called ARP probes sent by the BOOTP client If the TM USE AUTO IP macro is defined in trsystem h and the AUTO IP option has been purchased then the BOOTP client will send several ARP Probes i e ARP request with a sender net address set to 0 to make sure that no other node has been configured with the same IP address If a node responds then the BOOTP would notify the user with a TM EADDRINUSE error code 7 16 2004 Treck Incorporated Optional Protocols Checking on completion of a BOOTP configuration Synchronous check The user can make multiple calls to tfOpenInterface to determine when the configuration has completed Additional calls to tfOpenInterface will return TM EALREADY as long as the BOOTP server has not replied tfOpenInterface will return TM ENOERROR i
220. ace interfaceHandle int mHome Index int flags ttUserlpAddress requestedIpAddress unsigned char clientIdPtr int clientIdLength e Function Description Allows the user to set the DHCP initial state INIT or INIT REBOOT prior to the user calling tfOpenInterface tf ConfigInterface Called by the user when the user wants to specify his her own Client ID or suppress the Client ID option or if the user wants to start in INIT REBOOT state or if the user wants to specify an IP address in the DISCOVERY phase e fuser specifies INIT REBOOT state the Requested IP address needs to be specified as well e If user specifies INIT state i e TM DHCPF INIT REBOOT not set optionally the user can specify the IP address and or the CLIENT ID option e f CLIENT ID is not specified and not suppressed the stack will pick a unique CLIENT ID that will be the same across reboots provided that the user uses the same type of configuration and same index If the user specifies TM DHCPF FQDN ENABLE in flags then clientIdPtr is used to indicate the DHCP FQDN option domain name If flags is set to TM DHCPF FQDN ENABLE and clientIdPtr is NULL the global FQDN configured by tfUserSetFqdn will be used instead Note that the TM DHCPF FQDN ENABLE option cannot be set at the same time as the other flags except TM DHCP FQDN PARTIAL Parameters Parameter Description interfaceHandle Ethernet interface handle mHomelndex multihome
221. ached TM NOTIFY SEND LOW WATER 2048 by default Note This function can only be used when there is a separate send complete task Parameters Parameter Description interfaceHandle The interface handle of the device to wait for a transmit complete to occur Returns Value Meaning 0 Success TM_ENOBUFS Insufficient memory to complete the operation 5 197 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfWaitXmitinterface include lt trsocket h gt int tfWaitXmitInterface ttUserInterface interfaceHandle Function Description This function is used to wait for data ready to be sent from the bottom ofthe Treck stack to the device driver data queued to the interface send queue If there is no data ready to be transmitted then it waits The caller should then call tfXmitInterface when this call completes successfully Note tfWaitXmitInterface can only be used when there is a separate transmit task Parameters Parameter Description interfaceHandle The interface handle for the device to which to send data Returns Value Meaning 0 Success TM ENOBUFS Insufficient memory to complete operation 5 198 2004 Treck Incorporated Programmer s Reference tfXmitinterface include lt trsocket h gt int tfXmitInterface ttUserInterface interfaceHandle Function Description tfXmitInterface is used to call the device driver send function with the next packet ready to be transmitted in
222. achine is unavailable to you this program makes it possible to run a similar test using a Windows platform Send pre initialized data Frequently errors with the driver can cause memory to be corrupted By sending pre initialized data at the application level it is easy to verify that the correct data are being sent Use Treck test suite to test the locks and the driver The Treck stack comes with a test suite that allows you to verify if the locking mechanism is working correctly Once that has been verified the suite is also capable of testing various other aspects of TCP and UDP communications Please see the Treck Test Suite section in this manual Make sure the user interface handle is valid when calling tfRecvInterface It has to be the interface handle as returned by tfAddInterface This is frequently interpreted as an error at the driver level but is actually C3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual C4 a bug in application code If the interface handle passed to tfRecvInterface is not valid it could cause the call to fail memory corruption or an application crash Temporarily disable TM DEV SCATTER SEND ENB in your call to tfOpenInterface The TM DEV SCATTER SEND ENB flag informs the stack that scatter send is available in the driver This means that the stack can deliver a packet to the driver in parts that is a packet may be comprised of more than one buffer This 1s des
223. acketUPtr After the interface is configured this new device driver send function will be called where the first parameter to the device driver send function is the interface handle as before and the second parameter is a pointer to the ttUserPacket structure as described above Note Once tfUseInterfaceOneScatSend has been called successfully on an interface the stack will always call the modified device driver send function passed as a second parameter to tfUseInterfaceOneScatSend for that interface 4 79 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Example Modified driverSend function to support per frame single call scattered send int devOneScatSendFunc ttUserInterface interfaceHandl ttUserPacketPtr packetUPtr User calls The user calls tfAddInterface specifying a null device driver send function to add the interface interfaceHandle tfAddInterface OUICC SCCI linkLayerHandle DevEtherOpen DevEtherClose tDevSendFuncPtr 0 DevEtherReceive tFreeRecvBufferFuncPtr 0 Devioctl DevGetPhyAddr rrorCode ct Fh Fh Hh ct reddit ct D Hh Hct Next the user calls the new tfUseInterfaceOneScatSend API to specify the modified device driver send function errorcode tfUseInterfaceOneScatSend ttUserInterfac interfaceHandle ttDevOneScatSendFunc devOneScatSendFunc If the call does not fail then the user can now call tfConfigInterface
224. actual socket before we try to close it if testSocket 1 Close the socket tfClose testSocket return returnVal 2 11 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TCP Client This code is very much like the UDP client Unlike UDP however it must call connect before actually transferring data as TCP requires a negotiated connection It then calls send the specified number of times An interesting observation is that the number of TCP data packets actually sent out on the wire will very probably not equal the number defined in this code TCP is stream based rather than datagram based so it will buffer data and attempt to send it in the most convenient size packets generally maximum sized packets include lt trsocket h gt define TM_BUF_SIZE 1400 define TM_PACKETS_TO_SEND 10 define TM_DEST_ADDR 10 129 36 52 define TM DEST PORT 9999 char testBuffer TM BUF SIZE char errorStr int tcpClient void int testSocket unsigned int counter struct sockaddr_in destAddr int errorCode int SockOption int returnVal returnVal 0 counter 0 Specify the address family destAddr sin_family AF_INET Specify the destination port destAddr sin port htons TM DEST PORT Specify the destination IP address destAddr sin addr s addr inet addr TM DEST ADDR Create a socket testSocket socket AF_INET SOCK STREAM IPPROTO TCP
225. ad of applying for 3 separate class C addresses we can manipulate our current class C address to accommodate our needs We know that we have 254 physical addresses available but because we do not want them all on the same physical network we need to find an alternative way to use our current address What we need to do is essentially break up our current address We do this by what is referred to as sub netting We know that in the structure of an IP address anything that is a in binary is referenced as the network and anything that is a 0 is referenced as the host We can restructure the netmask to move where the division is between the network portion and the host portion IP Address 208 229 201 0 Netmask 11111111 11111111 11111111 00000000 Hexadecimal FF 00 IP Address 208 229 201 0 Netmask 11111111 11111111 11111111 11000000 Hexadecimal FF CO Fig 1 27 Illustration of Sub Netting In the first chart of Figure 1 27 we see the default setup for a class C netmask We see the result of sub netting in the second chart of Figure 1 27 We have essentially changed the location of the bar between the third and fourth integers of our IP address We changed the location by changing the value of the netmask from FF FF FF 00 to FF FF FF CO Notice that we have changed the first two bits of the last byte to represent the network address In order to achieve super netting the same procedure is
226. adcast receivers update the IP to physical address binding information in their cache before processing an ARP packet ARP is a low level protocol that hides the underlying network physical addressing permitting one to assign an arbitrary IP address to every machine We think of ARP as a part of the physical network system and not as a part of the Internet protocols ARP Implementation Functionally ARP is divided into two parts The first part maps an IP address to a physical address when sending a packet The second part answers requests from other machines Address resolution for outgoing packets may seem to be pretty straightforward but some small details can complicate an implementation When given a destination IP address the software consults its ARP cache to see if it knows the mapping from IP address to physical address If it does the software extracts the physical address places the data in a frame using that address and transmits the frame If it does not know the mapping then the software must broadcast an ARP request and wait for a reply Many things can happen to complicate an address mapping The target machine can be down or just too busy to accept the request If so the sender may not receive a reply or the reply may be delayed Because an Ethernet is best effort delivery system the initial ARP broadcast can also be lost 1f this happens then the sender should retransmit at least once Meanwhile the sender must stor
227. after listening for incoming connections It is the user s responsibility to then call tfFtpdUserExecute periodically to execute the FTP server code Choose the non blocking mode if you do not have an RTOS Kernel 6 24 Parameters Parameter fileFlags maxConnections maxBackLog idleTimeout blockingState File system flags File system flags TM FS CWD FLAG TM FS SMNT FLAG TM FS RETR FLAG TM FS STOR FLAG TM FS STORU FLAG TM FS APPEND FLAG TM FS RENAME FLAG TM FS DELETE FLAG TM FS RMD FLAG TM FS MKD FLAG TM FS PWD FLAG TM FS LIST FLAG Application Reference Description Indicates which FTP file commands are supported by the file system It is the result of ORing together the flags described below corresponding to the FTP commands supported by the file system Maximum number of concurrent accepted incoming FTP connections allowed If zero then the FTP server will accept as many connections as there are available sockets Maximum number of concurrent pending before being accepted incoming FTP connections allowed Amount of time in seconds that a connection can sit idle before the server closes that connection The idle Timeout value cannot be less than 300 seconds 5 minutes TM BLOCKING ON for blocking mode TM BLOCKING OFF for non blocking mode Description Supports change working directory Supports structure mount Supports reading from a file Supports writing to a file Suppor
228. ag Indicates from where tfSendCompleteInterface is called See below It is very important to set the appropriate flag Flag Description TM DEV SEND COMPLETE DRIVER tfSendCompleteInterface is being called from the device driver TM DEV SEND COMPLETE APP tfSendCompleteInterface is being called either from a send task or from the main loop Returns Nothing 5 178 2004 Treck Incorporated Programmer s Reference tfSendCompletePacketinterface include lt trsocket h gt void tfSendCompletePacketInterfac ttUserInterface interfaceHandle ttUserPacketPtr packetPtr int devDriverLockFlag Jur Function Description This function is used to notify the stack that send has completed for a given frame so that the stack can remove it from the device send queue and free it If the device driver copies the packet before attempting the send it is permissible to call this routine from the context of the send otherwise it must only be alled after the device had actually sent the packet Use tfSendCompletePacketInterface instead of tfSendCompleteInterface when the device driver transmits the frames out of order tfSendCompletePacketInterface can only be used in conjunction with the single device driver send call per frame See tfUseInterfaceOneScatSend and TM USE DRV ONE SCAT SEND Parameters Parameter Description interfaceHandle The interface handle for the device to process the send complete packetPtr Indi
229. all back function in the context of the timer task with the TM ENOERROR error code e Once started the collision detection will stop only when the user calls tfCancelCollisionDetection e The user can call tfUseCollisionDetection at any time after tfStartTreck has been called Parameters Parameters Description ipAddress IP address to check userCbFunc Call back function Called by the Treck stack when either an ARP reply or ARP request has been received whose source IP address matches the above IP address Also called when a matching ARP probe is received while the interface has not been configured yet Also called when the tfUserStartArpSend timeout expires See userCbFunc section below userCbParam Parameter to be passed as is to the user call back function See below Returns Value Meaning TM EINVAL userCbFunc is NULL TM EADDRINUSE Another host on the network has been configured with the IP address We found the ARP mapping in the ARP cache TM EALREADY tfUseCollisionDetection has already been called for that IP address TM ENOBUFS Not enough memory to allocate a collision detection entry TM ENOERROR No error 7 11 2004 Treck Incorporated Treck Real Time TCP IP User s Manual userCbFunc call back function The call back function will be called as follows int userCbFunc ttUserInterface interfaceHandle ttUserlIpAddress ipAddress int errorCode ttUserGenericUnion userCbParam userCbFun
230. ameters is bad the bufferLength lt 0 or a flag not listed above is set 5 109 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfZeroCopySendTo include lt trsocket h gt nt tfZeroCopySendTo t SocketDescriptor UserMessage bufferHandle t bufferLength t flags onst struct sockaddr toAddressPtr nt toAddressLength p Q b ob oct HA H D D TT 3 7 Function Description This function is used to send a zero copy message It operates identically to sendto with the exception that it takes a zero copy buffer handle as a parameter Note Once tfZeroCopySendTo is called the caller does NOT own the buffer and it is freed by the TCP IP stack except when if fails with a TM EWOULDBLOCK error code in which case the user can either try and send the buffer at a later time or free the zero copy buffer using tfFreeZeroCopyBuffer Parameters Parameter Description socketDescriptor The socket descriptor to send data to buffer Handle The zero copy buffer obtained from tfGetZeroCopyBuffer bufferLength The length of the message to send flags Special flags for this device toAddressPtr The address to send the packet to toAddressLength The length of the address The flags parameter is formed by ORing one or more of the following MSG_DONTWAIT Don t wait for data send to complete but rather return immediately MSG_DONTROUTE The SO DONTROUTE option is turned on for the duration of
231. ampling period i e hysteresisSamples before we will notify the user that the link is bad Set to 0 if we aren t using any hysteresis otherwise this is the sampling period specified as the number of calls to the user s link quality monitoring function used to determine if the link is bad Meaning Success The interface handle is invalid or monitorFuncPtr was NULL You must call tfUsePppLqm first to initialize PPP LOM Optional Protocols tfLqmSendLinkQualityReport int tfLqmSendLinkQualityReport ttUserInterface interfaceHandle Function Description The PPP LOM specification RFC 1989 allows the Link Quality Report message to be sent more frequently than the negotiated reporting period and tfLqmSendLinkQualityReport gives you direct control over when Link Quality Report messages are sent You may want to use tfLqmSendLinkQualityReport if your link quality monitoring function is not being called frequently enough and you want to get feedback on what the current link quality is Parameters Parameter Description interfaceHandle The PPP interface to send the Link Quality Report message on Returns Value Meaning 0 Success TM_EINVAL The interface handle is invalid TM ENETDOWN The PPP interface is not open connected TM EOPNOTSUPP Could not send Link Quality Report message because LOM is disabled on the link 1 e the peer does not support LQM TM ENOBUFS Could not allocate a buffer for the
232. an application has created a socket and bound it to a port data destined to that port will be delivered to the application This is why the term socket is used it is the connection mechanism between the outside world the ports and the application A common misunderstanding is that sockets based systems can only communicate with other sockets based systems This is not true TCP IP or UDP IP communications are handled at the port level the underlying protocols do not care what mechanisms exist above the port Any Internet host can communicate with any other be it Berkeley Sockets WinSock or anything else Sockets is just an API that allows the programmer to access Internet functionality it does not modify the manner in which communications occur Let us use the example of an office building to illustrate how sockets and ports relate to each other The building itselfis analogous to an Internet host Each office represents a port the receptionist is a socket and the business itself is an application Suppose you are a visitor to this building looking for a particular business You wander in and get directed to the appropriate office You enter the office and speak with the receptionist who then relays your message to the business itself If there is nobody in the office you leave To rephrase the above in sockets terminology A packet is transmitted to a host It eventually gets to the correct port at which point the socket c
233. an be idle before it times out The number of consecutive retries a connection will make before it gives up Each time a connection times out it counts as one retry TM BLOCKING ON for blocking mode TM BLOCKING OFF for non blocking mode Meaning Success maxConnections is less than one blockingState is neither TM BLOCKING ON nor TM BLOCKING OFF blockingState is TM BLOCKING ON and blocking mode is not enabled for the stack The function was unable to create a socket This function uses various sockets calls Any other error codes returned will be from said sockets calls The error codes are defined in trsystem h Application Reference tfTftpdUserStop include lt trsocket h gt int tfTftpdUserStop void Function description This function stops execution ofthe TFTP server It closes the listening socket and killing all existing connections Parameters None Returns Value Meaning 0 Success TM EALREADY The TFTP server has already been stopped Treck Real Time TCP IP User s Manual File system interface Description The file system interface is used by the Treck FTP server Treck TFTP server and Treck FTP Client Entry points from the FTP server to the file system tfFSChangeDir Change current working directory tfF SChangeParentDir Change current working directory to parent directory tfF SCloseDir Close a directory that we had opened earlier tfFSCloseFile Close a file tfFSDelete
234. and mark zero otherwise See reve call for a description of out of band data See also tfGetOobData Offset 5 64 2004 Treck Incorporated Example Programmer s Reference Given a valid socketDescriptor the following code will turn on the socket s nonblocking I O flag int arg Value argValue 1 tfloctl socketDescriptor FIONBIO amp argValue Parameters Parameter socketDescriptor request argumentPtr Returns Value 0 l tfioctl can fail for the following reasons TM EBADF TM BINVAL Description The socket descriptor we want to perform the ioctl request on FIONBIO FIONREAD or SIOCATMARK A pointer to an int cell in which to store the request parameter or request result Meaning Success An error has occured The socket descriptor is invalid Request is not one of FIONBIO FIONREAD or SOIOCATMARK 5 65 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfRead include lt trsocket h gt int tfRead int socketDescriptor char bufferPtr int bufferLength Function Description tfRead is used to receive messages from another socket It is not called read to avoid confusion with an embedded kernel file system call It operates identically to recv except that it does not have any flag parameter and hence does not support out of band data or overwriting the blocking state ofthe socket for the duration of the call Parameters Parameter so
235. aning 0 Success TM EPERM TFTP server currently executing not started or stopped Application Reference tfTftpdUserStart include lt trsocket h gt int int int int int tfTftpdUserStart maxConnections sendTimeout timeoutTime blockingState Function Description This function opens a TFTP server socket and starts listening for incoming connections tfTftpdUserStart can be either blocking or non blocking as specified by the blockingState parameter Blocking Mode In blocking mode tfTftpdUserStart should be called from a task It will block and wait for incoming connections and will not return unless an error occurs The TFTP server code is executed in the context of the calling task Choose blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfTftpdUserStart will return immediately after checking for incoming connections It is the user s responsibility to then call tfTftpdUserExecute periodically to execute the TFTP server code Choose non blocking mode if you do not have an RTOS Kernel Treck Real Time TCP IP User s Manual Parameters Parameter maxConnections sendTimeout timeoutTime blockingState Returns Value 0 TM_EINVAL TM_EINVAL TM_EINVAL TM SOCKET ERROR All other error codes 6 86 Description Maximum number of concurrent incoming TFTP connections allowed Must be at least one The amount of time in seconds a connection c
236. arameter Description destIpA ddress Destination IP address destNetMask Destination IP Network Mask Returns Value Meaning 0 Success TM EHOSTUNREACH No route to destination 5 223 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfRegisterlpForwCB include lt trsocket h gt int tfRegisterIpForwCB ttUserIpForwCBFuncPtr ipForwCBFuncPtr Function Description Used to register a function for the Treck stack to call when a packet cannot be forwarded The function s parameters will indicate the source IP address and destination IP address of the packet in network byte order If the call back function returns an error code then the stack will send a host unreachable ICMP error message as before If the call back function returns TM ENOERROR then the stack will silently drop the packet The prototype for the callback function is int ipForwardCallback ttUserIpA ddress srcIpA ddress ttUserIpA ddress destIpA ddress Parameters Parameter Description ipForwCBFuncPtr A pointer to the forwarding callback function Returns Value Meaning 0 Success 5 224 2004 Treck Incorporated Programmer s Reference tfUseRip include lt trsocket h gt int tfUseRip void Function Description This function is called to start the RIPv2 Listener It will also turn on the TM OPTION RIP ENABLE mentioned in tfSetTreckOptions above Parameters None Returns Value Meaning 0 Success TM EMFILE Not en
237. aries with TCP will not work correctly if you use out of band data Default 0 TM TCP SEL ACK If this option value is zero then TCP selective Acknowledgment options are disabled Default 1 TM TCPWND SCALE If this option value is non zero then the TCP window scale option is enabled Default 1 TM TCP TS Ifthis option value is non zero then the TCP time stamp option is enabled 5 18 2004 Treck Incorporated TM TCP SLOW START TM TCPDELAY ACK TM TCPMAX REXMIT TM TCP KEEPALIVE CNT TM TCPFINWT2TIME TM TCP2MSLTIME TM TCP RTO DEF TM TCP RTO MIN TM TCPRTO MAX TM TCPPROBE MIN Programmer s Reference Default 1 If this option value is non zero then the TCP slow start algorithm is enabled Default 1 Get the TCP delay ack time in milliseconds Default 200 milliseconds Get the maximum number of retransmissions without any response from the remote before TCP gives up and aborts the connection See also TCP MAXRT above Default 12 Get the maximum number of keep alive probes without any response from the remote before TCP gives up and aborts the connection See also TCP KEEPALIVE above Default 8 Get the maximum amount of time TCP will wait for the remote side to close after it initiated a close Default 600 seconds Get the maximum amount of time TCP will wait in the TIME WAIT state once it has initiated a close of the connection Default 60 seconds Get the TCP default retransmi
238. arrive without coordinating with the original sender This system works well if all machines operate correctly all the time Aside from communication lines or processors failing there are a variety of conditions that will impede IP s ability to deliver datagrams when the destination machine is temporarily or permanently disconnected from the network when the time to live counter expires or when intermediate routers become so congested that they cannot process the incoming traffic The important difference between having a single network implemented with dedicated hardware and an internet implemented with software is that in the former the designer can add special hardware to inform attached hosts when problems arise In an internet which has no such hardware mechanism a sender cannot tell whether a delivery failure resulted from a local malfunction or aremote one This can make debugging difficult The IP protocol itself contains nothing to help the sender test connectivity or learn about such failures Designers added a special purpose message mechanism to the TCP IP protocols to allow routers in an internet to report errors or provide information about unexpected circumstances This mechanism known as the Internet Control Message Protocol ICMP is considered a required part of IP and must be included in every IP implementation Like all other traffic ICMP messages travel across the Internet in the data portion of IP datagrams The ultima
239. askVield tfKernel Warning Compiler Library Replacement Functions tfMemCpy tfMemSet tfQsort tfSPrintF tfSScanF tfStrCat tfStrChr tfStrCmp tfStrCpy tfStrCSpn tfStrError tfStrLen tfStrNCmp tStrRChr tfStrStr tfStrToL tfStrToUI tfVSPrintF tfVSScanF Programmer s Reference BSD 4 4 Socket API accept include lt trsocket h gt Int accept Int socketDescriptor struct sockaddr addressPtr int addressLengthPtr Function Description The argument socketDescriptor is a socket that has been created with socket bound to an address with bind and that is listening for connections after a call to listen accept extracts the first connection on the queue of pending connections creates a new socket with the properties of socketDescriptor and allocates a new socket descriptor for the socket If no pending connections are present on the queue and the socket is not marked as non blocking accept blocks the caller until a connection is present Ifthe socket is marked as non blocking and no pending connections are present on the queue accept returns an error as described below The accepted socket is used to send and recv data to and from the socket that it is connected to It is not used to accept more connections The original socket remains open for accepting further connections accept is used with connection based socket types currently with SOCK STREAM Using select prior to calling accept It is possible
240. at we had opened earlier Close a file Delete a file Get the next directory entry in the directory open with tfFSOpenDir either a long listing of the directory entry including volumes sub directories and file names or a short listing of the directory file name only depending on how the direc tory was open Given a file name return a unique file name in the current directory i e if the file name already exists make up a new name that is unique in the current directory Get user working directory Create specified directory Open specified directory or directory corresponding to a specified pattern to allow getting a long or short listing of the directory or of the directory entries matching the specified pattern Open a file creating it if it does not exist for read write or append specifying type ASCII or binary structure stream or record Read n bytes from a file into a buffer Read a record from a file up to n bytes Indicates whether EOR has been reached 6 21 Treck Real Time TCP IP User s Manual tfF SRemoveDir Remove specified directory tfFSRenameFile Rename a file tfFSStructureMount Mount the user to a new file system data structure tfFSSystem Return the system name tfFSUserAllowed Indicates whether a specified user is allowed on the system tfFSUserLogin Login a user if password is valid tfFSUserLogout Logout a user tfFSWriteFile Write some bytes from a buffer
241. atInterface is called In the ex amples directory the txscatlp c and txscatdr c modules contain sample code that uses this feature 4 8 2004 Treck Incorporated Integrating into Your Environment TM_DISABLE_TCP_ACK_PUSH This macro is uncommented by default When this macro is commented out Treck TCP will ACK every TCP segment that it receives that has the PUSH bit set Comment out this macro if you need the Treck stack to interoperate well with a peer that runs Windows 2000 because Internet Explorer waits for the ACK response to the PUSH bit being set before sending any new data TM_SINGLE_INTERFACE_HOME If this macro definition is added to trsystem h it will reduce code size by approximately 4 5 kilobytes by removing support for multiple interfaces and multi homing Note that when this macro is enabled you can only have a single interface and a single IP address configured on that interface Warning Defining this will prevent addition of the loop back device 1 Packets sent to the single interface IP address will be sent all the way to the driver instead of being loop back by the stack 2 Packets cannot be sent to the IP loop back address 127 0 0 1 TM_MULTIPLE_CONTEXT This macro is commented out by default Uncomment this macro if you want to run multiple instances of the Treck TCP IP stack Running multiple instances of the Treck stack is further described in appendix A of this manual TM_DIS
242. ate acks after duplicate ACK s One of the following TM NT TCPS CLOSED TM NT TCPS LISTEN TM NT TCPS SYN SENT TM NT TCPS SYN RECEIVED TM NT TCPS ESTABLISHED TM NT TCPS CLOSE WAIT TM NT TCPS FIN WAIT 1 TM NT TCPS CLOSING TM NT TCPS LAST ACK TM NT TCPS FIN WAIT 2 TM NT TCPS TIME WAIT TM NT TCPS INVALID 6 155 Treck Real Time TCP IP User s Manual ttNtUdpEntry Description Holds the information of a UDP entry for printing typedef struct tsNtUdpEntry ttUserl6Bit ntUdpSockDesc ttUser32Bit ntUdpBytesInRecvQ ttUser32Bit ntUdpBytesInSendQ ttUser32Bit ntUdpRecvQSize ttUser32Bit ntUdpSendQSize struct sockaddr_storage ntUdpLocalSockAddr ttUserl6Bit ntUdpOwnerCount ttNtUdpEntry typedef ttNtUdpEntry ttNtUdpEntryPtr Member ntUdpSockDesc ntUdpBytesInRecvQ ntUdpBytesInSendQ ntUdpRecvQSize ntUdpSendQSize ntUdpLocalSockAddr ntUdpOwnerCount 6 156 Description Socket descriptor integer Data in the receive queue in bytes Data in the send queue in bytes Size of the receive queue in bytes Size of the send queue in bytes Address port and protocol family information of the socket Owner count of the socket Optional Protocols 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Optional Protocols Function List AutoIP Configuration tfAutoIPPickIpAddress tfCancelCollisionDetection tfConfigAutolp tfUseColl
243. ated TM_OPTION_RIP_RECV_MODE TM_RIP_NONE TM RIP 1 TM RIP 2 TM RIP I TM RIP 2 Returns Value 0 TM EINVAL Programmer s Reference Meaning Ignore incoming RIP packets Accept RIP version 1 packets Accept RIP version 2 packets Accept both RIP version 1 and version 2 packets Meaning Success The option or its value is invalid 5 125 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSetTreckOptions include lt trsocket h gt int tfSetTreckOptions int optionName optionValue unsigned long Function Description This call is used to set various options that are used by the Treck TCP IP stack Note This function should be called only after having called tfStartTreck Parameters Parameter optionName optionValue Option Name TM OPTION ARP MAX RETRY TM OPTION ARP TIMEOUT TIME TM OPTION ARP QUIET TIME TM OPTION ARP TTL TM OPTION ARP MAX ENTRIES TM OPTION ARP SMART 5 126 2004 Treck Incorporated Description The option to change see below The new value to change it to Meaning The maximum number of ARP retries before going into the ARP quiet time state DEFAULT 6 The amount of time in seconds between ARP retries DEFAULT 1 The length of the ARP quiet time state in seconds DEFAULT 20 The length of time that an ARP entry should be kept in the ARP cache in seconds To disable ARP aging set to TM RT INF DEFAULT 600
244. ay is already in the routing table TM EHOSTUNREACH The gateway is not directly accessible TM EINVAL One of the parameters is bad the gatewaylIpA ddress is zero or interfaceld refers to the loopback interface 5 209 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfAddMcastRoute include lt trsocket h gt int ttUserInterface ttUserlpAddress ttUserlpAddress unsigned char Function Description tfAddMcastRoute interfaceld mcastAddress netmask mhome Index This function is used to add a multicast route associating a specific multicast destination address with a specific outgoing interface Normally the netmask parameter is set to all 1 s Parameters Parameter interfaceld mcastAddress netmask mhomelndex 5 210 Description The interface ID to use to add this routing entry Identifies the outgo ing interface to use for packets sent to the multicast destination address specified by mcastAddress The multicast destination address to add the route for The netmask for the route Nor mally this will be all 1 s i e inet_addr 255 255 255 255 which means that there must be an exact match of the packet destina tion address with mcastAddress for this route to be used to send the packet The multi home index to use to add this routing entry This is the multi home index of a valid IP address that is already configured on the interface identified by inter
245. believes there are no available buffers for it to write into Receive ring send ring miscoding can cause deadlock with the Ethernet chip There are various cases where bugs in the ring logic within a driver can cause the chip to stop responding Check your ring logic very carefully An interrupt was not cleared correctly Many chips will not interrupt again until you have cleared the last interrupt If your OS has a separate post for tasks and ISRs e g RTXC make sure that these are used correctly tfKernellsrPostEvent should use the ISR specific post function If your OS cannot post from an ISR at all you should call tfNotifyInterfacelIsr from the OS s post ISR function eg eCOS That is OS s that do not allow you to post to a semaphore or event flag inside an ISR will allow you to register a function that will be run after the ISR Put your tfNotifyInterfacelsr inside this function Other problems C 10 System locks up This is usually caused by memory corruption espe cially writing to memory address 0 See the Corrupted Memory section above Getting stuck inside an ISR will also cause this behavior Kernel Error tf cpSendPacket send queue corrupted This is symp tomatic of counting semaphores not working correctly or not initializing the counting semaphore value to zero 2004 Treck Incorporated
246. berBytesSent has reached TM NOTIFY SEND LOW WATER 2048 by default since the previous notification Parameters Parameter Description interfaceHandle the interface handle to notify Treck of numberRecvPackets The number of received packets to notify of numberSendCompletePackets The number of packets actually sent on this interface numberBytesSent The number bytes actually sent on this interface flag Unused Note The values for number RecvPackets numberSendCompletePackets and numberBytesSent may be 0 Returns None 5 163 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNotifyReceivelnterfacelsr Note tfNotifyReceivelnterfacelsr has been deprecated Please use tfNotifyInterfacelsr tfNotifyReceivelInterfacelsr will still function in your code tfNotifySentinterfacelsr Note tfNotifySentInterfacelsr has been deprecated Please use tfNotifyInterfacelIsr tfNotifySentInterfaceISr will still function in your code tfOpeninterface include lt trsocket h gt int tfOpenInterface ttUserInterface interfaceHandle ttUserlpAddress ipAddress ttUserlpAddress netMask int flag int buffersPerFrameCount Function Description This function is used to configure an interface with an IP address and net mask either supernet or subnet It must be called before the interface can be used An example would be errorCode tfOpenInterface myInterfaceHandle inet addr 208 229 201 65
247. blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfTftpdUserStart will return immediately after checking for incoming connections It is the user s responsibility to then call tfTftpdUserExecute periodically to execute the TFTP server code Choose non blocking mode if you do not have an RTOS Kernel 3 tfTftpdUserExecute If tfTftpdUserStart was called in non blocking mode tfTftpdUserExecute must be called periodically If tfTftpdUserStart was called in blocking mode there is no need to call tfTftpdUserExecute 4 tfTftpdUserStop 6 82 Application Reference The user calls tfTftpdUserStop to close the TFTP server socket and kill all existing TFTP connections File System Interface Note File system calls for TFTP can be found in the File System Section of this manual tfTftpdinit include lt trsocket h gt void tfTftpdInit void Function description This function initializes various data associated with the TFTP server It must be called before any other TFTP API call Parameters None Returns Nothing Treck Real Time TCP IP User s Manual tfTftpdUserExecute include lt trsocket h gt int tfTftpdUserExecute void Function description This function executes the TFTP server s main loop This call is valid only if tfTftpdUserStart has been called in non blocking mode and tfTftpdUserExecute is not currently executing Parameters None Returns Value Me
248. broadcast forwarding DEFAULT 0 A Boolean to enable IP fragmentation DEFAULT 1 The initial time to live for IP datagrams DEFAULT 64 5 123 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM OPTION IP TOS The default Type Of Service for IP datagrams DEFAULT 0 TM OPTION IP FRAG TTL Fragment re assembly timeout value in seconds DEFAULT 64 TM OPTION ICMP ADDR MASK AGENT A boolean to enable disable the ICMP address mask agent DEFAULT 0 TM OPTION UDP CHECKSUM A boolean to enable disable UDP checksums on outgoing packets DEFAULT 1 TM OPTION PMTU DECREASED TTL The length of time in seconds before a path MTU estimate increase is tried after having received an ICMP Datagram Too Big Message error DEFAULT 600 seconds TM OPTION PMTU LARGER TTL The length of time in seconds before another path MTU estimate increase is tried after a previous path MTU estimate increase has been successful DEFAULT 1200 seconds TM OPTION TIMER MAX EXECUTE The maximum number of timers to process in a single call to tfTimerExecute Default 0 which means that there is no maximum To minimize the latency of the tfTimerExecute call set to 1 TM OPTION RIP SEND MODE Meaning TM RIP NONE Ignore requests from the TCP IP stack to send RIP requests TM RIP 1 Send RIP version 1 packets TM RIP 2 Multicast RIP version 2 packets TM RIP 2 BROADCAST Broadcast RIP version 2 packets 5 124 2004 Treck Incorpor
249. c Parameters userCbFunc Parameters Description InterfaceHandle Interface as given to tfUserStartArpSend ipAddress IP address to check for collision errorCode Status of the ARP IP address collision detection See below userCbParam Parameter as passed by the user to tfUseCollisionDetection errorCode Parameter Value userCbFunc is called TM EADDRINUSE An ARP reply or ARP request or ARP probe interface not config ured yet has been received Collision detection will still continue until the user calls tfCancelCollisionDetection TM ENOERROR The timeout period for sending ARP requests Arp probes expired See tfUserStartArpSend Colli sion detection will still continue until the user calls tfCancelCollisionDetection 7 12 2004 Treck Incorporated Optional Protocols tfUserStartArpSend include lt trsocket h gt int tfUserStartArpSend ttUserInterface interfaceHandle ttUserlpAddress ipAddress int numberArpProbes ttUser32Bit arpProbeInterval ttUser32Bit timeout Function Description Start sending one or more ARP probes or ARP requests on a given interface If the interface is not configured yet with that IP address on any multi home then this command instructs the Treck stack to send one or more ARP probes An ARP probe is an ARP request with the sender net address set to zero If the interface has been configured with that IP address on one of its multi home then this command instructs
250. c portPublic On the private network the server will be implemented at ipPrivate portPrivate Call this function as many times as you like being sure not to assign conflicting public or private ip port protocol triads Parameters Parameter Description interfaceHandle Interface handle of the public NAT device to configure public a TCP port on ipPublic The server s public identity network byte order ipPrivate The server s private identity network byte order portPublic The server s pubic implementation host byte order portprivate The server s private implementa tion host byte order Returns Value Meaning TM ENOMEM Insufficient memory or too many triggers already TM ENOERROR Newly allocated trigger ip s and ports initialized TM EINVAL Erroneous use for details enable TM NAT TRACE 7 66 2004 Treck Incorporated Optional Protocols tfNatConfiglnnerUdpServer include lt trsocket h gt coc c oc c nop UserlInterface UserlpAddress UserlpAddress UserlpPort UserIpPort Function Description Configure a server on the private network for access via a specific UDP port on the public network The public world will know the server as ipPublic portPublic On the private network the server will be implemented at ipPrivate portPrivate tfNatConfigInnerUdpServer interfaceHandle ipPublic ipPrivate portPublic portPrivate Call this function as many times as you like being sure not to assign confli
251. call or tfTimerUpdate Parameters None Returns Nothing 5 228 2004 Treck Incorporated Programmer s Reference Kernel RTOS Interface tfKernelCreateCountSem include trsocket h int tfKernelCreateCountSem ttUserGenericUnionPtr countingSemaphorePtr Function Description RTOS SPECIFIC This function is used to create a counting semaphore that is used by Treck Parameters Parameter Description countingSemaphorePtr A RTOS Counting semaphore Returns Value Meaning 0 Success l An error occurred 5 229 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelCreateEvent include lt trsocket h gt void tfKernelCreateEvent ttUserGenericUnionPtr eventPtr Function Description RTOS SPECIFIC This function is used to create an event structure for pend post from an ISR Parameters Parameter Description eventPtr A pointer to an ISR event structure that is returned from an RTOS Returns Nothing 5 230 2004 Treck Incorporated Programmer s Reference tfKernelDeleteCountSem include lt trsocket h gt int tfKernelDeleteCountSem ttUserGenericUnionPtr countingSemaphorePtr Function Description RTOS SPECIFIC This function is used to remove a counting semaphore Parameters Parameter Description countingSemaphorePtr The counting semaphore to delete Returns Value Meaning 0 Operation completed successfully l An error occurred 5 231 2004 Treck Incor
252. called from an ISR Parameters Parameter Description interfaceHandle Interface handle as returned by tfAddInterface size Size of buffer to get from the pre allocated pool Returns A char to the beginning of the data area to store the received data into or a NULL pointer if there are no available receive pool buffers 5 174 2004 Treck Incorporated Programmer s Reference tfPoolReceive include lt trsocket h gt int ttUserInterface char TM FAR TM FAR int TM FAR ttUserBufferPtr Function Description tfPoolReceive interfaceHandle dataPtrPtr dataLengthPtr bufHandlePtr Remove first received buffer from the pool receive queue Store in dataPtrPtr dataLengthPtr bufHandlePtr the buffer data pointer data length and buffer handle respectively This function could be the drvRecvFuncPtr parameter to tfAddInterface Otherwise the user calls this function from the device driver receive function The parameters are identical to the device driver receive function Parameters Parameter interfaceHandle dataPtrPtr dataLengthPtr bufHandlePtr Returns Value TM DEV OKAY TM DEV ERROR Description Interface handle as returned by tfAddInterface Pointer to area where to store the buffer data pointer Pointer to area where to store the buffer data length Pointer to area where to store the buffer handle Meaning Success No buffer in the pool receive queue 5 175 2004 Treck Inc
253. cates which frame in the device send queue needs to be dequeued and freed flag Indicates from where tfSendCompletePacketInterface is called See below It is very important to set the appropriate flag Flag Description TM DEV SEND COMPLETE DRIVER tfSendCompletePacketInterface is being called from the device driver TM DEV SEND COMPLETE APP tfSendCompletePacketInterface is being called from either a send task or the main loop 5 179 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Nothing 5 180 2004 Treck Incorporated Programmer s Reference tfSetifMtu int tfSetIfMtu ttUserInterfac interfaceHandle int ifMtu Function Description This function is used to set the Maximum Transmission Unit MTU for a device For Ethernet and PPP this is typically set to 1500 bytes The link MTU is always the size of the largest IP packet which can be sent unfragmented over the link which is the maximum link layer frame size minus any link layer header and trailer overhead For PPP and Ethernet this value can be changed via Path MTU Discovery to allow larger frames and to prevent IP datagram fragmentation Parameters Parameter Description interfaceHandle The device driver entry that we wish to get the physical address on ifMtu The Maximum Transmission Unit for a device Returns Value Meaning 0 Success TM BINVAL One of the parameter is null or 0 By default the path MTU discovery
254. cattered recv function points to an array of user block data of type ttDruBlock uDevBLockCountPtr Upon return from the device driver scattered recv contains the number of such elements 4 82 2004 Treck Incorporated Integrating into Your Environment flagPtr Upon return from the device driver scattered recv indicates whether the stack owns the buffers TM DEV SCAT RECV STACK BUFFER or whether the device driver owns the buffers IM DEV SCAT RECV USER BUFFER uDevLockPtrPtr Upon retrun from the device driver scattered recv function uDevBlockPtrPtr points to an array of ttDruBlock There is one ttDruBlock per scattered buffer in the received frame Each ttDruBlock element contains a pointer to a user buffer a pointer to the beginning of the user data in the user buffer and the user data length in the user buffer ttDruBlock Fields Description druDataPtr points to beginning of data druDataLength indicates the data length druBufferPtr pointer to be passed to the device driver free function if user sets the flag to TM DEV SCAT RECV USER BUFFER in the driver recv call function See flagPtr below druStackBufferPtr pointer to stack pre allocated user buffer if user sets the flag to TM DEV SCAT RECV STACK BUFFER in the driver recv call function See flagPtr below If the device driver scattered recv function sets flagPtr to TM DEV SCAT RECV STACK BUFFER then druStackBufferPtr should point to a buf
255. ccess or failure message is sent to the system requesting access Unlike PAP CHAP has the ability to send periodic re authentication requests without renegotiating More information on CHAP can be found in RFC 1994 Microsoft Challenge Handshake Authentication Protocol MS CHAP This authentication method is not currently supported in the Treck stack This authentication method is very similar to regular CHAP except for a few details Standard CHAP uses 05 for the hashing algorithm while MS CHAP uses 08 It does not require the authenticator to store a clear text or reversibly encrypted password The authenticator has the ability to choose the number of retries as well as the ability to change passwords Unlike CHAP MS CHAP will give a reason for failure for example incorrect password More information on MS CHAP is available in RFC 2433 Internet Protocol Control Protocol IPCP The Internet Protocol Control Protocol enables disables and configures various IP modules on each end of the peer to peer link This protocol has its own list of options such as various types of compression MTU discovery specifying IP addresses and several more It is important to remember no IP packets can be sent before PPP is in the NCP phase In terms of the current Treck stack the NCP phase consists solely of IPCP This means a PPP link is first negotiated with LCP authentication takes place if it has been requested in LCP and then IPCP establishes comm
256. ce can be configured that way In that case the following steps are needed after having called linkLayerHandle tfUseEthernet interfaceHandle tfAddInterface namePtr linkLayerHandle e errorCode tfUseDhcp interfaceHandle myNotifyFunction errorCode tfOpenInterface interfaceHandle OUL OUL TM_DEV_IP_DHCP 1 Note that we have called tfOpenInterface with the TM DEV IP DHCP flag set Note other flags such as TM DEV IP FORW ENB could be ORed to TM DEV IP DHCP as needed Note The user needs to wait for the DHCP configuration to complete During the wait ensure tfTimerUpdate or t TimerUpdateIsr and tfTimerExecute get called User controlled configuration parameters A user API tfDhcpConfSet is provided to allow the user e to set the DHCP initial state to INIT REBOOT instead of the default INIT state with a user specified requested IP address and client ID e or to set a user specified requested IP address and or Client ID while DHCP is in the INIT state Or to allow the user to suppress the client ID option 7 24 2004 Treck Incorporated Optional Protocols ARP probes sent by the DHCP client If the TM USE AUTO IP macro is defined in trsystem h and the AUTO IP option has been purchased then the DHCP client will send several ARP Probes i e ARP request with a sender net address set to 0 to make sure that no other node has been configured with the same IP address If a node responds t
257. ce that way then a default outgoing interface will be used if after having configured the interface the user specified a system wide one using the new tfSetMulticastInterface API Otherwise the multicast sendto will fail IP TTL for Multicast Packets By default the IP layer will send a multicast packet with a TTL value of 1 unless the user changes the default multicast IP ttl value for the socket with setsockopt A TTL value of 1 will not allow the multicast IP datagram to be forwarded beyond the local subnet The option IPO MULTICAST TTL at the IPPROTO IP level has been added to setsockopt and getsockopt Mapping Multicast Addresses to Layer 2 Hardware Addresses To enable multicast mapping from the IP multicast address to an Ethernet multicast address the TM DEV MCAST ENB flag must be set in the tfOpenInterface flags parameter IGMP Protocol Receiving UDP Multicast Packets When a UDP datagram whose destination IP address is a multicast address arrives on an interface from the network we check that the host is amember of the multicast group on the interface it came in A host is a member of a group address for a given interface if it joined that multicast group Note In order to receive multicast packets the user must join a host group Joining a Host Group To join a host group a user socket application calls setsockopt with the IPO_ADD MEMBERSHIP option at the IPPROTO_IP level The option pointer points to a structure c
258. ceHandle ttUser32Bit virtualChannel int mhomeIndex Function Description tfInterfaceSetVirtualChannel allows the user to set an ATM virtual channel for a given multi home on an interface Parameters Parameter Description interfaceHandle The interface handle as returned by tfAddInterface virtualChannel ATM virtual channel set by the User mhomelndex Multi home index on the interface Returns Value Meaning TM ENOERROR Success TM EINVAL Invalid interface handle or multi home index Note also see tfInterfaceGetVirtualChannel 5 157 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfinterfaceSpinLock include lt trsocket h gt int tflnterfaceSpinLock ttUserInterface interfaceHandle Function Description tfInterfaceSpinLock is called from the device driver send routine to yield the CPU to allow spin lock while waiting for room to transmit the data This function will yield the CPU only ifthe user is using a transmit task to interface between the Treck stack and the device driver Parameters Parameter Description interfaceHandle The Interface Handle of the device we are waiting to be ready Returns Value Meaning 0 Success TM EPERM Function did not yield the CPU because the user is not using a transmit task i e did not call tfInterfaceSetOptions to turn on the transmit task option 5 158 2004 Treck Incorporated Programmer s Reference tfloctlInterface include lt t
259. ceIsr ttUserInterface interfaceHandle int numberRecvPackets int numberSendCompletePackets unsigned long numberBytesSent unsigned long flag Function Description This function notifies the stack with both the number of packets received in an ISR and the number of packets transmitted by the chip since the last ISR This function is to be called by the user inside an ISR with the appropriate number of received and sent packets This will in turn cause the stack to notify the user s application about what has occurred In the case of received packets tfCheckReceiveInterface will return 0 once for each received packets if the user is in polling mode In blocking mode tfWaitReceiveInterface will return once for each received packet For sent packets tfCheckSentInterface will return 0 once for each sent packet in polling mode or tfWaitSentInterface will return once for each sent packet in blocking mode These functions only notify the user of a sent packet in the case that the accumulated numberBytesSent has reached TM NOTIFY SEND LOW WATER 2048 by default since the previous notification Parameters Parameter Description interfaceHandle The interface handle to notify Treck of numberRecvPackets The number of received packets to notify of numberSendCompletePackets The number of packets actually sent on this interface numberBytesSent The number bytes actually sent on this interface flag Unused Note The values
260. cessor Processor RTOS Mfg Type Compiler Location source kernel ucos uC OS Motorola CPU32 SDS motorola cpu32 sds source kernel ucos uC OS Motorola CPU32 MRI motorola cpu32 mri source kernel ucos uC OS Motorola PowerPC Diab motorala pneldiab Borland source kernel ucos Bes intel 200 Real Com RG renlibarluad Microsoft source kernel ucos Heu d x30 Repl v6 0 intelx86 real msc60 AMX Motorola CPU32 SDS source kernel amx cj AMX Intel x86 Real Borland source kernel amx aj Green source kernel motorola ThreadX Motorola PowerPC Hills threadx ppc ghs The file name for the kernel interface is normally named as follows trXXX c Where XXX is the name of the kernel For example the uC OS interface is named trucos c In each of these files you will find the RTOS kernel interface functions You will find the TM FAR macro used in these interface functions This macro is defined to be far on the Intel processor running in real small model You will also notice that these files all include TRSOCKET H This single file contains all of the types that you will need to build the RTOS Kernel interface 4 22 2004 Treck Incorporated Integrating into Your Environment The kernel interface is broken down into the following elements Initialization Memory Allocation and Free Critical Section Handling Error Logging Warning Information Logging Task Suspend and Resume SR
261. ch to send the ARP probe s request s mhomelndex Multi home index of the IP address to be configured on the interface Returns Value Meaning TM ENOENT Could not pick a valid IP v4 IP address TM EALREADY tfUseCollisionDetection has already been called for that IP address TM ENOBUFS Not enough memory to allocate a collision detection entry or a timer TM EPERM Interface is not a LAN interface i e ARP not permitted on that interface TM ENXIO Interface has not been opened TM ENOERROR No error 7 9 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUseCollisionDetection include lt trsocket h gt int tfUseCollisionDetection ttUserlpAddress ipAddress ttArpChkCBFunc userCbFunc ttUserGenericUnion userCbParam Function Description Allow the Treck stack to check that no other host is using a given IP address This command instructs the Treck stack to store the given IP address so that it can later on check for ARP requests or replies coming from any interface not originated by this host and whose ARP sender addresses are the same as the given IP address The collision detection will only start after the user calls tfUserStartArpSend The collision detection will continue until the user calls tfCancelCollisionDetection If the interface given by tfUserStartArpSend is not configured yet the Treck stack will also check for ARP probes sent by other hosts The user gives a call back function
262. citly mean the message was delivered but rather that it was sent If the socket does not have enough buffer space available to hold the message being sent and is in blocking mode tfSendToFrom blocks If it is in non blocking mode or the MSG_DONTWAIT flag has been set in the flags param eter 1 is returned with the socket error being set to TM EWOULDBLOCK The select call may be used to determine when it is possible to send more data 5 91 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter socketDescriptor bufferPtr bufferLength flags toAddressPtr addressLength fromAddressPtr Returns Value gt 0 1 Description The socket descriptor to use to send data The buffer to send The length of the buffer to send MSG_DONTWAIT Don t wait for room in the socket send queue 0 wait for room in the socket send queue The address to send the data to The length of the area pointed to by toAddressPtr or fromAddressPtr The address to send the data from Meaning Number of bytes actually sent on the socket An error occurred error can be retrieved with tfGetSocketError tfSendToFrom can fail for the following reasons TM_EBADF TM_ENOBUFS TM EMSGSIZE TM EPROTOTYPE TM EWOULDBLOCK 5 92 2004 Treck Incorporated The socket descriptor is invalid There was insufficient user memory available to complete the operation The message was too long TCP protoc
263. cket errorStr tfStrError returnVal 2 14 2004 Treck Incorporated Introduction to BSD Sockets goto tcpServerEnd ja Bind the socket to the port and address at which we wish to receive data zy errorcode bind listenSocket amp destAddr sizeof destAddr Check for an error in bind if errorCode lt 0 returnVal tfGetSocketError listenSocket errorStr tfStrError returnVal goto tcpServerEnd Set up the socket as a listening socket errorCode listen listenSocket 10 Check for an error in listen if errorCode lt 0 returnVal tfGetSocketError listenSocket errorStr tfStrError returnVal goto tcpServerEnd Do this forever while 1 Get the size of the sockaddr_in structure addrLen sizeof sourceAddr Accept an incoming connection request The address port info for the connection s source is stored in sourceAddr The length of the data written to sourceAddr is stored in addrLen The initial value of addrLen is checked to make sure too many bytes are not written to sourceAddr Ey newSocket accept listenSocket amp sourceAddr amp addrLen Check for an error in accept if newSocket 0 returnVal tfGetSocketError listenSocket errorStr tfStrError returnVal goto tcpServerEnd Do this forever while 1 2 15 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Receive
264. cketDescriptor bufferPtr bufferLength Returns Value 20 5 66 2004 Treck Incorporated Description The socket descriptor to receive data from The buffer to put the received data into The length of the buffer area that bufferPtr points to Meaning Number of bytes actually received from the socket EOF An error occurred Programmer s Reference tfread will fail if TM EBADF The socket descriptor is invalid TM ENOBUFS There was insufficient user memory available to complete the operation TM EMSGSIZE The socket requires that message be received atomically and bufferLength was too small TM EWOULDBLOCK The socket is marked as non blocking and no data is available to be read TM ESHUTDOWN The remote socket has closed the connection and there is no more data to be read TCP socket only TM ENOTCONN Socket is not connected TM_EINVAL One of the parameter is invalid 5 67 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfWrite include lt trsocket h gt int tfWrite int socketDescriptor char bufferPtr int bufferLength Function Description tfWrite is used to transmit a message to another transport end point It is not called write to avoid confusion with an embedded kernel file system call It operates identically to send except that it does not have any flags parameter and hence does not support sending out of band data or overwriting the blocking state of
265. ckets calculate number of outbound LORs still in the pipeline outboundLarsInPipeline int ttUser32Bit Oxffffffff amp outLqrs countsPtr lastOutLqrs if outboundLgrsInPipeline gt 1 linkQuality outboundLqrsInPipeline 1 break case TM LOM MONITOR TIMEOUT linkQuality 1 break default this should not happen tfKernelWarning myLinkQualityMonitor unrecognized value for reasonCode break 7 115 2004 Treck Incorporated Treck Real Time TCP IP User s Manual require at least 2 sample periods to declare a link bad ay if linkQuality gt LOM HYSTERESIS MAX FAILURES linkQuality LOM HYSTERESIS MAX FAILURES return ttUser8Bit linkQuality Limitations We do not implement a default policy for judging the quality of the link and we do not attempt any recovery when the link quality is judged bad Instead the user must register a link quality monitoring function if they want to implement a link quality monitoring policy and we will give them a PPP callback after a user specified amount of hysteresis has been applied when the link quality is judged bad so that they can attempt recovery 7 116 2004 Treck Incorporated Optional Protocols Public API tfUsePppLqm int tfUsePppLqm ttUserInterface interfaceHandle ttUser32Bit lqrReTxPeriodMsec Function Description tfUsePppLqm is used to in
266. ckingMode not set to either TM BLOCKING ON or TM BLOCKING OFF TM EALREADY The DNS resolver has already been started TM ENOERROR Resolver started successfully Treck Real Time TCP IP User s Manual tfDnsGetHostAddr int tfDnsGetHostAddr ttUserIpAddress serverlpAddr char hostnameStr int hostnameStrLength Function Description This function retrieves the hostname associated with the given IP address a reverse DNS lookup Parameters Parameter Description serverlpAddr IP address to retrieve the hostname for hostnameStr Buffer to place the retrieved hostname in hostnameStrLength Size of the above buffer Returns Value Meaning TM_EINVAL Invalid host name string or IP address pointer TM EWOULDBLOCK DNS lookup in progress The user should continue to call tfDnsGetHostAddr with the same parameters until it returns a value other than TM EWOULDBLOCK Only returned when operating in non blocking mode TM ENOERROR DNS lookup successful hostname stored in hostnameStr length stored in hostnameStrLength Application Reference tfDnsGetHostByName int tfDnsGetHostName const char hostnameStr ttUserIpAddressPtr ipAddressPtr Function Description This function retrieves the IP address associated with the given hostname Parameters Parameter Description hostnameStr Hostname to resolve ipAddressPtr Set to the IP address of the host Returns Value Meaning TM_EINVAL Invalid host name string or
267. code is enabled If you do not need path MTU in your trsystem h define define TM DISABLE PMTU DISC This will prevent the compilation of the path MTU discovery code Turning off the path MTU discovery mechanism setsockopt If the path MTU discovery code has been compiled in and there is a need to disable path MTU discovery on a given connection the user can call the Berkeley socket API setsockopt on the connection or listening socket prior to the connection establishment with the P PROTOTCP protocol level and TCP MAXSEG option name If the option value is less than 64 bytes then the Treck stack will set the TCP MSS to the default value which is the outgoing device IP MTU minus 40 bytes 5 181 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Turning off the path MTU discovery mechanism tfDisablePathMtuDisc Another way of turning off the Path MTU discovery mechanism for a given destination IP address is to use the new API tfDisablePathMtuDisc This function will disable path MTU discovery for the route to the given destination IP address Path MTU estimates timeout values When Path MTU discovery is enabled for an indirect TCP destination IP address the Treck stack will try to increase the path MTU estimate up to the device IP MTU after the current path MTU estimate times out Two new options have been added to tfSetTreckOptions to allow the user to change the default timeout values for path MTU es
268. col Field iode ee teens e eds 1 26 The Information Field rrt rete ree 1 26 The Padding Field eese nont e erret 1 26 PPP Link Operation cree Mint eite eate ed tee ecu 1 27 Understanding IP Addresses Leere eere eene eene en nenne enne tn nana 1 28 IP Address Format 55 roter tet tI Rer ER eO E e Rd 1 28 Network and Broadcast Addresses ssssssssssseeeees 1 29 Limited Broadcast oie retenta sna 1 30 Drawbacks in Internet Addressing ssssssse 1 30 Dotted Decimal Notation intet estet eere tds 1 31 Loopback Address esee eui e EP RE 1 31 Special Address Conventions cccccccecseesceseeesecceeseceeeseceeeenecneeeeeeneeeas 1 32 Netmasks 25 85 endeoiiieteo o ener e o PRO UN ER 1 34 Reserved Addresses interitu etre beret te reine umes URS 1 35 Sub Netting amp Super Netting 4 1 36 The Internet Protocol IP eoe eret terere arn tpe erbe Pe Va ero etna s sosopo 1 37 Connectionless Packet Delivery Service 1 37 Purpose of the Internet Protocol 1 38 The Internet Datagram 1 5 ocean aiu td te CHEER Regi 1 38 Datagram BOFmat 5 acvesceesanceds casdadee P e ERR peter E CUR LER t i Fete rl 1 39 2004 Treck Incorporated Datagram Type of Service and Datagram Precedence 1 40 Datagram Encapsulation cs eie pen onere ED erepto ter REISEN HERE 1 40 Understanding Checksums ss 1 41 Introductions Rar term rede utin PEU 1 41 Explanation
269. cols in your system 2 Setting up the TRSYSTEM H file for various compile time switches 3 Creating the Build Command BAT files fora DOS Environment and Building the Library 4 Creating an RTOS Interface 5 Hooking in the Timer 6 Key things you need to do in order to start using Treck protocols 7 Testing the new library with a simple loop back test 8 Using Ethernet or PPP 9 Adding a new device driver 10 Testing your new device driver If we have some or all of these elements setup for you you will of course be able to skip some of these steps In our design we have made every effort to help the integration process be as simple as possible TIP Don t be overwhelmed by what looks like a lot of work for you to do Most of these steps can be performed in one or two days You will find that you will spend most of your time in the place where the hardware meets the software the device driver Just go through these steps and take them one at a time and you will have the integration completed before you know it 4 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 1 Determining How to Use the Protocols in Your System To help in making this decision you will need to ask yourself a few questions Am I using a Real Time Operating System RTOS Is my processor Big or Little Endian I do not have an RTOS Kernel to Interface to If you do not have an RTOS Kernel to which to interface you will stil
270. corporated Appendix C Debugging 2004 Treck Incorporated Treck Real Time TCP IP User s Manual C2 2004 Treck Incorporated Debugging a Device Driver Debugging a Device Driver How to debug a device driver 1 Use a network analyzer Network analyzers can be obtained from KLOS www klos com and Shomiti www shomiti com Network analyzers are invaluable when trying to debug a protocol stack They allow you to see all of the traffic on the network and thus inspect what was going on in the stack when problems were encountered For technical support to be effective in helping you with any problems you may encounter some form of packet capturing device is of the utmost importance Disable all Compiler Optimizations While debugging your device driver you should disable all compiler optimizations Certain compiler optimizations may cause problems with your network device driver and should not be enabled until the driver is completely debugged Use InetD95 for windows 95 98 included on distribution CD This tool emulates some of the standard services available on Unix machines Most interesting to us are the echo port and the discard port ports 7 and 9 respectively They allow you to send data from another source which they will either echo back to you or discard silently One of the easiest initial tests to do with the stack is to have it send data to another host which will then silently discard it If a Unix m
271. cting public or private ip port protocol triads Parameters Parameter interfaceHandle ipPublic ipPrivate portPublic portprivate Returns Value TM ENOMEM TM ENOERROR TM_EINVAL Description Interface handle of the public NAT device to cofigure public UDP port on The server s public identity host byte order The server s private identity host byte order The server s public implementa tion host byte order The server s private implementa tion host byte order Meaning Insufficient memory or too many triggers already Newly allocated trigger ip s and ports initialized Erroneous use for details enable TM NAT TRACE 7 67 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNatConfiginnerFtpServer include lt trsocket h gt int tfNatConfigInnerFtpServer ttUserInterface interfaceHandle ttUserIpAddress ipPublic ttUserIpAddress ipPrivate ttUserIpPort portPublicMin ttUserIpPort portPublicMax Function Description This function configures an FTP server on the private network for access as an FTP server via the public IP address The public world will know the FTP server as ipPublic 21 On the private network the server will be implemented at ipPrivate 21 Only one FTP server can be configured for a public NAT interface In case the FTP server ever gets a PASV command from the public client the inbound connection must be accommodated on a unique public port
272. ction Description Cancel a collision detection that had been registered with tfUseCollisionDetection The user will pass the IP address that is being checked for collision tfCancelCollisionDetection will search the list of collision detection entries and remove the matching entry and timer if any Collision detection for that IP address will stop Parameters Parameters Description ipAddress IP address that is currently being checked for collision Returns Value Meaning TM ENOENT No collision detection entry matching the IP address parameter has been found TM ENOERROR No error 7 8 2004 Treck Incorporated Optional Protocols tfConfigAutolp include lt trsocket h gt int tfConfigAutoIp ttUserInterface interfaceHandle int mhomeIndex Function Description This function is provided as an example tfConfigAutoIp picks an AUTO IP v4 address and calls tfUseCollisionDetection passing the selected IP address a call back function namely tfAutoIpFinish with a call back function parameter specifying the selected mhome index If tfUseCollisionDetection is successful that informa tion will be stored in the Treck stack Next it calls tfUserStartArpSend using the default values for the number of ARP probes 4 and ARP probe time interval 2 seconds so that the Treck stack can start sending ARP probes to check for collisions on the IP address Parameters Parameters Description interfaceHandle Interface on whi
273. cupies 6 contiguous bytes so it spans two lines in the diagram Field Hardware Type specifies a hardware interface type for which the sender seeks an answer it contains the value for Ethernet Similarly field Protocol Type specifies the type of high level protocol address the sender has supplied it contains 0800 for IP addresses Field Operation specifies an ARP request or ARP response Fields Hardware Address Length and Protocol Address Length allow ARP to be used with arbitrary networks because they specify the length of the hardware address and the length of the high level protocol address The sender supplies its hardware address and IP address if known in the fields Sender Hardware Address and Sender IP Address 1 21 2004 Treck Incorporated Treck Real Time TCP IP User s Manual When making a request the sender also supplies the target IP address or target hardware address using fields Target Hardware Address and Target IP Address Before the target machine responds it fills in the missing addresses swaps the target and sender pairs and changes the operation to a reply Therefore a reply carries the IP and hardware addresses of the original requester as well as the IP and hardware addresses of the machine for which a binding was sought Big Endian Little Endian To create an Internet that is independent of any particular vendor s machine architecture or network hardware the software must define a standard representation f
274. d TM LL LCP UP LCP negotiation has completed TM LL PAP UP PAP authentication has completed TM LL CHAP UP CHAP authentication has completed TM LL LQM UP LOM is enabled on the link TM LL LOM DISABLED LOM is disabled on the link TM LL LOM LINK BAD Link quality is bad user recovery should be attempted These events may be used to monitor the status of the PPP connection The PPP connection should not be used before a TM LL OPEN COMPLETE event is received and the device should not be restarted after a tfCloseInterface before a TM LL CLOSE COMPLETE event is received 7 99 2004 Treck Incorporated Treck Real Time TCP IP User s Manual From these events it is also possible to determine why PPP negotiation failed For instance if authentication fails a TM LL LCP UP event is first received indicating that the physical link has been negotiated However if authentication fails the next event will be TM LL CLOSE STARTED and then TM LL CLOSE COMPLETE since the link must be closed if negotiation fails If authentication is successful the events that are received are TM LL LCP UP TM LL PAP UP or TM LL CHAP UP and then TM LL OPEN COMPLETE Parameters Parameter Description linkNotifyFuncPtr The function to call to notify PPP events or TM LNK NOTIFY FUNC NULL PTR if notification is not needed The events are TM LL OPEN COMPLETE TM LL CLOSE STARTED TM LL CLOSE COMPLETE TM LL LCP UP TM LL PAP UP TM LL CHAP UP
275. d data when the SO OOBINLINE option is set see setsockopt 5 34 2004 Treck Incorporated Programmer s Reference TCP protocol only Ifthe SO OOBINLINE option is enabled the out of band data is left in the normal data stream and is read without specifying the MSG_OOB More than one out of band data bytes can be in the stream at any given time The out of band byte mark corresponds to the final byte of out of band data that was received In this case the MSG_OOB flag cannot be used with recv The out of band data will be read in line with the other data Again recv will not read past the position of the out of band mark in a single recv request Again tfloctl with the SOIOCATMARK or tfGetOobDataOffset can be used to determine where the last received out of band byte is in the stream Note that the user needs to either use select or tfRegisterSocketCB in order to know when out of band data has arrived or is arriving select may be used to determine when more data arrives or and when out of band data arrives tfRegisterSocketCB may be used to asynchronously determine when more data arrives or and when out of band data arrives Parameters Parameter Description socketDescriptor The socket descriptor from which to receive data bufferPtr The buffer into which the received data is put bufferLength The length of the buffer area that bufferPtr points to flags See below The flags parameter is formed by ORing one or mo
276. dString before failing Amount of times in seconds between time outs Only one flag is currently defined TM DIALER FAIL ON ERROR This flag causes the dialer to immediately return if the error string is received Normally the dialer would simply attempt to resend the previous string Meaning Expect send string added success fully Bad interface handle Timeout value is zero Bad send expect strings Insufficient memory to add expect send strings Optional Protocols tfUseDialer include lt trsocket h gt int tfUseDialer ttUserInterface interfaceHandle ttUserLnkNotifyFuncPtr notifyFuncPtr Function description Enables and initializes the dialer This does not start the dialer but simply initializes it the dialing will occur when tfOpenInterface is called This should only be enabled on a serial interface running PPP SLIP and should be called before any calls to tfDialerAddSendExpect or tfDialerAddExpectSend are made The notification function is used to monitor the status of the dialer The prototype of the notification function is myDialerNotify ttUserInterface interfaceHandle int flags The notification function will only be called when the dialer has finished either successfully or unsuccessfully There are two possible values for the flags parameter TM DIALER OPEN COMPLETE The dialer has completed the dialing session successfully TM DIALER OPEN FAILED The dialer encountered an err
277. data on the new socket created by accept errorCode recv newSocket testBuffer TM_BUF_SIZE 0 Make sure there wasn t an error if errorCode 0 tfClose newSocket returnVal tfGetSocketError newSocket errorStr tfStrError returnVal goto tcpServerEnd Receiving 0 bytes of data means the connection has been closed If this happens close the new socket and break out of this the inner loop Ry if errorcode 0 tfClose newSocket break tcpServerEnd Make sure there s a socket there before closing it if listenSocket 1 Close the listening socket tfClose listenSocket return returnVal 2 16 2004 Treck Incorporated Treck Systems 2004 Treck Incorporated Treck Real Time TCP IP User s Manual 2004 Treck Incorporated Treck Systems Treck Real Time TCP IP Systems Treck TCP IP is designed to be easy to integrate into your environment It is also designed to be scalable to your needs In other words it is designed to allow you to use as much or as little of Treck TCP IP as you need For example if you decide to make an int type 16 bits you can use up to 32000 sockets with very little penalty in performance When using the Treck TCP IP system we want you to think of it as a Black Box We believe that there should be no reason for you as an integrator to be intimately familiar with the internals of Treck TCP IP We have designed
278. details 5 165 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter interfaceld ipAddress netMask flag buffersPerFrameCount Flags Value TM DEV SCATTER SEND ENB TM DEV MCAST ENB TM DEV IP FORW ENB TM DEV IP FORW DBROAD ENB TM DEV IP FORW MCAST ENB TM DEV IP BOOTP TM DEV IP DHCP 5 166 2004 Treck Incorporated Description The device entry This is returned by tfAddInterface The IP Address for this Interface The net mask for this device Subnet or Supernet Special flags for this deviceOred together see below Number of scattered buffers allowed for each frame being sent out If scattered buffers are not allowed by the driver this number should be one otherwise it should be bigger than one Meaning This device supports sending data in multiple buffers per frame Ifthis flag is set then the buffersPerFrameCount should be bigger than 1 This flag should always be set for SLIP or PPP serial devices This device supports multicast addresses Allow IP Forwarding to and from this device Allow forwarding of IP directed broadcasts to and from this device Allow forwarding of IP multicast messages to and from this device Configure IP address using BOOTP client protocol tfUseBootp need to have been called first Configure IP address using DHCP client protocol tfUseDhep need to have been Programmer s Reference called
279. different keyword for interrupt then TM INTERRUPT here to be that keyword TM_GLOBAL_QLF Default qualifier for global variables If you would like to put all global vari ables into one memory type e g far huge near then define TM GLOBAL QLF here to be that qualifier and leave TM GLOBAL NEAR undefined TM_GLOBAL_NEAR Default qualifier for frequently used global variables If you would like to put the frequently used global variables into one memory type e g near and the rest of them into a different memory type e g far huge then the memory type for frequently used global variables here as TM GLOBAL NEAR and leave TM GLOBAL QLF undefined NOTE about TM GLOBAL _OLF and TM GLOBAL NEAR Only one of them can be redefined to have a value otherwise compiler errors will occur TM CONST QLF Default qulifier for constants If you would like to put all constants into one memory type e g far huge near the TM CONST QLF here to be that qualifier 4 15 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Data Alignment TM_ETHER_HW_ALIGN Various Ethernet chips exist with the ability to make use of DMA Many of these chips also come with the requirement that their buffers be aligned on a certain byte boundary 4 byte and 16 byte being most common TM ETHER HW ALIGN defines how many bytes each Ethernet buffer obtained with tfGetEthernetBuffer will be aligned to This macro defaults to 4 TM NEED ETHER
280. dle void myDeviceIsrHandler void int recvPacketCount int recvPacketLength int sendCompletePacketCount unsigned long totalBytesSent char TM FAR dataPtr recvPacketCount 0 sendCompletePacketCount 0 totalBytesSent 0 Check for receive interrupt if receivedData Retrieve the packet length into recvPacketLength Get a Treck buffer from the ISR dataPtr tfPoolIsrGetBuffer myInterfaceHandle recvPacketLength if dataPtr char TM FAR 0 Copy the data into the Treck buffer pointed to by dataPtr Accumulate number of packets ready to be received recvPacketCount 4 70 2004 Treck Incorporated Integrating into Your Environment else Copy the data into a scratch buffer Check for send complete interrupt if sendComplete Accumulate number of packets that have been transmitted sendCompletePacketCount Accumulate sent packet data sizes totalBytesSent packetDataSize Call this function only once tfNotifyInterfaceIsr myInterfaceHandle receivedPacketCount sendCompletePacketCount totalBytesSent OUL Dismiss the interrupt 4 71 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Further Device Driver Modifications to allow a device driver to be shared by several Ethernet Interfaces Modify your device driver as follows to allow a device driver to be shared by several Ethernet inter
281. dr char physAddrPtr int physAddrLength Function Description This function is used to delete an entry in the ARP cache by looking up the entry by the Physical Address This function will allow the user to manipulate the ARP cache beyond standard means Normally the TCP IP stack maintains the ARP cache Parameters Parameter Description physAddrPtr The Physical Address to delete in the ARP cache physAddrLength The length of the physical address Returns Value Meaning 0 Success TM_EINVAL Bad parameter 5 215 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDelDefaultGateway include lt trsocket h gt int tfDelDefaultGateway ttUserlpAddress gatewaylIpAddress Function Description This function is used to delete the system default gateway for all interfaces Parameters Parameter Description gatewaylpAddress The default gateway IP address in Network Byte Order Returns Value Meaning 0 Success TM EINVAL Parameter is 0 TM_ENOENT No default gateway was found 5 216 2004 Treck Incorporated Programmer s Reference tfDelProxyArpEntry include lt trsocket h gt int tfDelProxyArpEntry ttUserlpAddress arpIpAddress Function Descrpition This function deletes an entry from the Proxy ARP table for the given IP address arplpAddress is expected to be in network byte order Parameters Parameter Description arplpAddrss IP address on behalf of which the syst
282. dress gateway int hops Function Description This function is used to add a route for the interface It allows packets for a different network to be routed to the interface Parameters Parameter Description interfaceld The interface ID to use to add this routing entry destIpAddress The IP address to add the route for destNetMask The net mask for the route gateway IP address of the gateway for this route hops Number of routers between this host and the route Returns Value Meaning 0 Success TM ENOBUFS Not enough buffer to allocate a TM EALREADY TM EHOSTUNREACH TM _EINVAL routing entry The route is already in the routing table The gateway is not directly accessible One of the first 4 parameters is null or 0 5 213 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDelArpEntryBylpAddr include lt trsocket h gt int tfDelArpEntryByIpAddr ttUserlpAddress arpIpAddress Function Description This function is used delete an entry in the ARP cache This function will allow the user to manipulate the ARP cache beyond standard means Normally the TCP IP stack maintains the ARP cache Parameters Parameter Description arplpAddress The IP address to delete in the ARP cache Returns Value Meaning 0 Success TM _EINVAL Bad parameter 5 214 2004 Treck Incorporated Programmer s Reference tfDelArpEntryByPhysAddr include lt trsocket h gt int tfDelArpEntryByPhysAd
283. ds to avoid using the send complete task Methods to avoid using a send complete task When one of the two methods outlined here is used then tfNotifyInterfacelsr tfCheckSentInterface or tfWaitSentInterface need not be called Method 1 Copy the Data This method is less efficient than the extra context switch on large packets For drivers that use I O ports to communicate with the chip the data is already being copied to the data to the I O port inside the device driver send function anyways An example of this method is as follows int driverSend ttUserInterface interfaceHandle char TM FAR dataPtr int dataLength int flag while dataLength Send to I O Port outb dataPtr dataLength We are done with the data pointer if flag TM USER BUFFER LAST tfSendCompleteInterface interfaceHandle TM DEV SEND COMPLETE DRIVER return TM DEV OKAY Method 2 In line the Send Complete Call In this method in your device driver send function look for previous sent packets that have completed transmission and call send complete for those packets This method is a little trickier One must be careful when using this method to make sure to also look for sent packets periodically outside of the driver send call in the driver ioctl function Otherwise if the Treck stack creates packets faster than the chip can process them then a deadlock condition can occur where the send complete never gets called Th
284. e FTP client to interact with the operating system s file system to store and retrieve files for example User Interface There are two types of calls provided in the FTP Client User Interface The first of these is to create and end an FTP session A session can be composed of multiple consecutive connects to various servers These calls include tfFtpNewSession and tfFtpFreeSession A session can be called in either blocking mode or non blocking mode Blocking Mode In this mode each FTP command will return only once the operation has completed and will block until completed Choose this mode if you are using an RTOS Kernel Non Blocking Mode In this mode each FTP command returns immediately after beginning the op eration After each initial command is made it is necessary for the user to call tfFtpUserExecute until the command has completed which is indicated by tfFtpUserExecute returning a value other than TM EWOULDBLOCK The next type of call is to send various commands to the FTP server These commands perform various file operations such as send or receive delete and create directory These calls are composed of routines such as tfFtpConnect tfFtpStor and tfFtpDirList As an example of the FTP client user interface suppose we have an embedded device that wishes to upload a log file to a main server and also to retrieve the most recent configuration settings See the example code that would perform these functions on the f
285. e int errorCode short optionValue errorCode tfStartTreck treckStarted 1 Other main processing like adding an interface if errorCode TM_ENOERROR errorcode tfUseInterfaceXmitQueue interfaceHandle 1000 Other main processing like opening the interface Also every time ffTimerExecute is called then the tfToctlInterface function should be called as follows errorCode tfloctlInterface interfaceHandle TM DEV IOCTL EMPTY XMIT FLAG void TM FAR 0 0 4 55 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Advantages Disadvantages Transmit Calling the device driver send In blocking mode extra Task is done in the context of a context switch on every packet separate transmit task not in sent In polling mode extra the context of the user processing to check on packets application or the recv task or ready to be sent the timer task The transmit task can wait inside the device driver send function for the device to be ready to transmit and can call tfInterfaceSpinLock allowing other tasks to access the other device driver functions For example the recv task could access the driver recv function Tranmit The device driver send can Extra memory required One Queue return an error if it is not ready extra function call required in to transmit the current buffer the send path Cannot be used Hence the sending thread i e with a SLIP
286. e Counting semaphores are also used to allow us to wait for a resource to become available such as received data When we the call socket function reev and we are allowing blocking to occur if there is no data to receive we will pend on a counting semaphore until there is data for us to receive or the socket has been closed Blocking means that we will wait until some event has occurred that we want to happen A task that is blocked will allow other tasks to still run By default Sockets operate in blocking mode In order to achieve blocking when it needs to occur we rely on a counting semaphore By using counting semaphores for blocking we do not need to call the operating system ina critical section This is extremely important for embedded systems In fact some operating systems will not allow you to call them inside of a critical section If we did not use a counting semaphore then there could be a window of opportunity where a task never exits the blocking state should the event that we are waiting for occurred during that small window Most operating systems have the concept of a counting semaphore Not all operating systems offer a counting semaphore If your RTOS does not provide a counting semaphore but does have an event flag then use the counting semaphore implementation in kernel trcousem c A counting semaphore is a mechanism that allows you to wait for a resource indefinitely It also allows you to release the resource before
287. e non blocking separate transmit task in which case you do not need to define TM_TASK_XMIT TM_TASK_SEND This macro is used to notify the stack that a separate blocking send complete task will be used Notice that this is not a send task but a send complete task The user calls the send complete function in the context of the send complete task and this allows the user to adjust the priority of that task In most cases it is inefficient to use a separate send complete task The most efficient means of processing send completes is in the context of the task that is calling the actual driver send routine The reason that it is inefficient is because a separate send complete task requires a context switch on nearly every packet that was sent Note It is possible to use a polling i e non blocking separate send complete task in which case you do not need to define TM_TASK_SEND Timer Updates TM_TICK_LENGTH This macro is used to define the default value that will be used to specify the interval between timer updates for the protocol stack This is a default value and can be changed at run time The value specified is in milliseconds The accuracy of this time is not critical This value should be the average time in between updates to the Treck Timer System The typical values used for this macro are between 10 and 100 milliseconds 4 13 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Word Order You do need to know
288. e ACK 2 Lae Fig 1 37 Simple Positive Acknowledgement with Retransmission The final reliability problem arises when an underlying packet delivery system duplicates a packet Duplicates can also arise when networks experience high delays that cause premature retransmission Solving duplication problems requires careful consideration because both packets and acknowledgements can be duplicated Usually reliable protocols can detect duplicate packets by assigning each packet a sequence number and requiring the receiver to remember which sequence numbers it has received We will explore this further in an upcoming section To avoid confusion caused by delayed or duplicate acknowledgements positive acknowledgement protocols send sequence numbers back in acknowledgements Therefore the receiver can correctly associate acknowledgements with packets 1 53 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Events at Sender Site Network Messages Events at Receiver Site Packet Lost Send Packet 1 Start Timer A LS Packet Should Arrive _ ACK Should Be Sent ACK would normally L arrive at this time Retransmit Packet 1 Start Timer M m Receive Packet 2 1 Send ACK 1 Receive ACK 1 La Cancel Timer Fig 1 38 Packet Loss and Retransmission Sliding Windows As we continue in the explanation of the TCP protocol suite we need to examine the concept of a sliding window A sliding window enable
289. e Conf Nak includes the options that the receiver of the Conf Req found unacceptable and a suggestion for an appropriate value When a system receives a Conf Req that contains options it is unfamiliar with it responds with a Configure Reject Conf Rej It is similar to the Conf Nak in that it contains only those options that are unacceptable but it does not offer an alternative If a system receives a Conf Rej reply to its Conf Req it must send a new Conf Req without the unfamiliar options and exclude them from any future Conf Req messages Sample LCP Negotiation Here is a sample negotiation between two machines System X sends a Conf Req to System Y that asks for several options e would like you to send my PPP datagrams in blocks of 3000 bytes MRU option set to 3000 e can handle compressed protocol field compression enoble this option e would also like you to identify yourself let s use CHAP System Y looks at what System X asked for and formulates a response e don t know what protocol field compression is Because System Y doesn t understand protocol field compression it must send a Conf Rej containing that option After receiving the Conf Rej System X must now send another Conf Req but it may not ask for protocol field compression again e would like you to send my PPP datagrams in blocks of 3000 bytes MRU option set to 3000 e would like you to authenticate using CHAP 7 75 2004 Treck Incorporated Treck R
290. e The counting semaphore to wait on Returns Value Meaning 0 Operation completed successfully l An error occurred 5 238 2004 Treck Incorporated Programmer s Reference tfKernelPendEvent include lt trsocket h gt void tfKernelPendEvent eee ees eventPtr Function Description RTOS SPECIFIC This function is used to wait on an event from ISR Parameters Parameter Description eventPtr The event to wait on Returns Nothing 5 239 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelPostCountSem include lt trsocket h gt int tfKernelPostCountSem ttUserGenericUnionPtr countingSemaphore Function Description RTOS SPECIFIC This function is used for the signal processes waiting on a counting semaphore Parameters Parameter Description countingSemaphore The counting semaphore to post to Returns Value Meaning 0 Operation completed successfully l An error occurred 5 240 2004 Treck Incorporated tfKernelReleaseCritical include lt trsocket h gt void tfKerneReleaseCritical void Function Description RTOS SPECIFIC This function is used to end a critical section Parameters None Returns Nothing Programmer s Reference 5 241 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelSetCritical include lt trsocket h gt void tfKernelSetCritical void Function Description RTOS SPECIFIC This function is
291. e Timers In this model you will have a simple loop in a separate timer task In this loop you will update the timers and execute the timers that have expired You will then pause the task for some fixed interval This interval MUST match the tick count that you have setup for the system see trsystem h or tfInitTreckOptions This is the most popular method to use when you have a real time operating system An example of this method is as follows include trsocket h void timerTask void while 1 Update the Timers tfTimerUpdate Execute the Timers tfTimerExecute Call the RTOS to delay for 1 clock tick RTOSTimeDelay 1 4 36 2004 Treck Incorporated Integrating into Your Environment If your RTOS does not allow you to start a task at run time then you should use a simple flag or semaphore to prevent the calls to the timer prior to calling tfStartTreck An example of this is as follows include lt trsocket h gt static int treckStarted 0 void mainTask void int errCode errCode tfStartTreck if errCode TM_ENOERROR treckStarted 1 Other initialization code follows void timerTask void while 1 Check to make sure that Treck has started if treckStarted Update the Timers tfTimerUpdate Execute the Timers tfTimerExecute Call the RTOS to delay for 1 clock tick RTOSTimeDelay 1 Tip A good timer interva
292. e data The buffer to store the received data The length of the buffer to store the received data MSG_DONTWAIT Don t wait for data 0 wait for data to come in Where to store the address the data came from Length of the area pointed to by fromAddressPtr or toAddress Ptr Where to store the address the data was sent to Meaning Number of bytes actually sent on the socket An error occurred error can be retrieved with tfGetSocketError tfRecvFromTo can fail for the following reasons TM_EBADF TM_ENOBUFS TM EMSGSIZE TM EPROTOTYPE TM EWOULDBLOCK 5 88 2004 Treck Incorporated The socket descriptor is invalid There was insufficient user memory available to complete the operation The message was too long TCP protocol requires usage of recv not tfRecvFromTo The socket is marked as non blocking and the tfRecvFromTo operation would block Programmer s Reference tfRegisterlpForwCB include lt trsocket h gt int tfRegisterIpForwCB ttUserIpForwCBFuncPtr ipForwCBFuncPtr i Function Description Used to register a function for the Treck stack to call when a packet cannot be forwarded The call back function parameters will indicate the source IP address and destination IP address of the packet in network byte order This is useful to let the user know that a packet cannot be forwarded because a dial up interface is closed for example In that case the user call back function could trigger a dial up
293. e entry by the Physical Address This function will allow the user to manipulate the ARP cache beyond standard means Normally the TCP IP stack maintains the ARP cache Parameters Parameter Description physAddrPtr The Physical Address to lookup the entry in the ARP cache physAddrLen The length of the physical address arplpAddressPtr The location where to store the IP address of the matching physical entry Returns Value Meaning 0 Success TM_EINVAL Bad parameter TM ENOENT No ARP entry found with this physical address 5 221 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetDefaultGateway include lt trsocket h gt int tfGetDefaultGateway ttUserIpAddress TM FAR gwayIpAddPtr Function Description This function is called from the socket interface to get the default gateway IP address The default gateway IP address will be stored in network byte order Parameters Parameter Description gwaylpAddrPtr Pointer to store gateway IP address into Returns Value Meaning TM ENOERROR Success TM EINVAL Bad parameter TM ENOENT No default gateway 5 222 2004 Treck Incorporated Programmer s Reference tfRtDestExists include lt trsocket h gt int tfRtDestExists ttUserlpAddress destlpAddress ttUserlpAddress destNetMask Function Description Find out whether a route to a destination given by the pair destination IP address and destination IP network mask exists Parameters P
294. e ete stirred Pri edere er eee eun 7 87 1tSetPppPeerlpAddress yo cis uos itd rr REPRE HERE 7 98 tHUSCASYOCP pp ssc sisi secs 7 99 tfUseAsyncServerPpp sise 7 101 tiPppSetAwthPri rity iste dte estre besten dette bears 7 103 PPPEXAMDPLE irr od ort ert ee end 7 104 Authenticator Part 2 inn be ptis see beo sue t deos pec 7 104 i du M 7 107 PPP Link Quality Monitoring LQM sms 7 111 DeSCEHDODi nente te epa n rer een 7 111 Code Example ie esperner ere EGRE EUR SIEHE 7 112 HET 010 01s E 7 116 arii APP MD M 7 117 rro MEE 7 117 tfFreePppLaii e 7 118 ttLqmRiegisterMOnltok iiie cet ete deer reo RUE eR EXEC S te 7 119 tfLqmSendLinkQualityReport ss 7 123 ttPppSendEchoRequesb o oet HR UO ME ED RE HERR 7 124 t L qmSetLqr FimerPeriod 2 ecrire teen it ire 7 126 tfL qmGetLocalLqrTimerPeriod eeeeeeeenene 7 127 tfLqmGetPeerLqrTimerPeriod eeseeeeeeennr 7 128 Appendix A Configuration Notes ss Al Configuring IP Forwarding and IP Fragmentation A 3 Counting Semaphores in the Treck Stack sense A 4 DeSCEIDO Ja ottime Antist ie ire IR T DR eee A 4 Counting Semaphore Implementation with task priority order A 4 KernelGetCurrentTaskId ss A 5 tfKernelT skPendEvent 51 53 e intiasta A 6 tfKernelTuskPostEvehk uiu Leica etii eint tibeesen cepe beret 4 7 Counting Semaphore Implementatio
295. e ether It contains digital circuitry that allows it communicate with a digital computer The transceiver can sense if the ether is in use and can translate analog signals to and from digital form The cable that connects the transceiver and the host adapter is called the Attachment Unit Interface AUT This cable contains many wires These wires carry electrical current needed to operate the transceiver the signals that control the transceiver operation and the contents of the packet being sent or received See fig 1 4 ETHERNET TRANSCEIVER o N _ HOST INTERFACE AUI CABLE KR 7 ON ADAPTER BOARD BUS IN A COMPUTER Fig 1 4 Host to Ethernet Connection 1 8 2004 Treck Incorporated Introduction to TCP IP The AUI cable connects the host interface and the transceiver It carries power signals and transmitting or receiving packets Because of several obvious reasons like a big hard to bend bulky wire and the chance of electrical interference engineers developed a new method of Ethernet wiring It is called thin wire Ethernet or thinnet This cabling system proved to be more flexible thinner and less expensive However because of using such a thin wire the cable provided less protection against electrical interference It could not be placed near powerful electrical equipment like that found in a factory It also covers shorter distances and supports fewer computer connections per network than thick E
296. e function to call to authenticate the remote user Returns Value Meaning 0 Success TM EINVAL The interface handle is invalid 7 86 2004 Treck Incorporated Optional Protocols tfPppSetOption include lt trsocket h gt int tfPppSetOption ttUserInterface interfaceHandle int protocolLevel int remoteLocalFlag int optionName const char optionValuePtr int optionLength 7 Function Description This function is used to set the PPP options that we wish to negotiate as well as those options that we will allow This allows us to change the link away from the default parameters described in RFC1661 Parameters Parameter Description interfaceHandle The Interface handle to set these options for protocolLevel The protocol which this option should be applied Current supported protocols are TM PPP LCP PROTOCOL TM PPP IPCP PROTOCOL TM PPP PAP PROTOCOL TM PPP CHAP PROTOCOL remoteLocalFlag This flag describes whether the option is for what we want to use for our side of the link TM PPP OPT WANT or if it what we will allow the remote side to use TM PPP OPT ALLOW optionName The name of the option see below optionValuePtr The value of the option see below optionLength The length of the option see below 7 87 2004 Treck Incorporated Treck Real Time TCP IP User s Manual LCP TM_PPP_LCP_PROTOCOL Option Name TM_LCP_ADDRCONTROL_COMP TM LCP PROTOCOL COMP TM LCP MAGIC NU
297. e link testing features of PPP enable more detailed transfer of graphics binary files and World Wide Web pages to and from PC s and the public Internet or private Intranets 1 24 2004 Treck Incorporated Link Control Protocol When we use PPP the first thing we need to use is LCP or Link Control Protocol LCP sends a packet or a configuration request A configuration request establishes what specifics it needs for this request Both sides of a connection go through the same procedures Sometimes one side will wait for the other side sometimes both machines will transmit this information simultaneously The configuration request is simply a packet that specifies certain information about how it is going to utilize the link If we were to look at a sample frame format it would look similar to this Introduction to TCP IP Total Code Identifer Length Option Length Value 1 Byte 1 Byte 2 Bytes 1 Byte 1 Byte Var Fig 1 16 Sample Configuration Request Format This frame could be variable length depending on the number of options that are requested PPP Encapsulation PPP allows the peers on a given link to establish the encapsulation to be used for datagrams Frames transmitted via PPP have three fields as shown in Figure1 7 Protocol a Information Padding optional Fig 1 17 PPP Encapsulation The fields in a PPP frame are used as follows Protocol Field Info
298. e same port number to multiple sockets using different local IP addresses Note that to use this socket option you also need to uncomment TM USE REUSEADDR LIST in trsystem h Default 0 disable The low water mark for receiving The low water mark for sending The buffer size for input Default is 8192 bytes The buffer size for output Default is 8192 bytes TM_SO_RCVCOPY TM SO SNDAPPEND SO UNPACKEDDATA Programmer s Reference TCP socket fraction use of a receive buffer below which we try and append to a previous receive buffer in the socket receive queue UDP socket fraction use of a receive buffer below which we try and copy to a new receive buffer if there is already at least a buffer in the receive queue This is to avoid keeping large pre allocated receive buffers which the user has not received yet in the socket receive queue Default value is 4 25 TCP socket only Threshold in bytes of send buffer below which we try and append to previous send buffer in the TCP send queue Only used with send not with tfZeroCopySend This is to try to regroup lots of partially empty small buffers in the TCP send queue waiting to be ACKED by the peer otherwise we could run out of memory since the remote TCP will delay sending ACKs Note that care should be taken not to use tfZeroCopySend when sending small buffers since we do not try to regroup small buffers with tfZeroCopySend Default value is
299. e socket in a manner that allows the process to continue as quickly as possible The option SO BROADCAST requests permission to send broadcast datagrams on the socket With protocols that support out of band data the SO OOBINLINE option requests that out of band data be placed in the normal data input queue as received it will then be accessible with reev call without the MSG OOB flag SO SNDBUF and SO_RCVBUF are options that adjust the normal buffer sizes allocated for output and input buffers respectively The buffer size may be increased for high volume connections or may be decreased to limit the possible backlog of incoming data The Internet protocols place an absolute limit of 64 Kbytes on these values for UDP and TCP sockets in the default mode of operation The following options are recognized at the IP level IP_PROTOIP protocolLevel options Description IPO MULTICAST IF Get the configured IP address that uniquely identifies the outgoing interface for multicast datagrams sent on this socket A zero IP address parameter indicates that we want to reset a previously set outgoing interface for multicast packets sent on that socket IPO MULTICAST TTL Get the default IP TTL for outgoing multicast datagrams IPO SRCADDR Get the IP source address for the connection IPO_TOS IP type of service Default 0 IPO_TTL IP Time To Live in seconds Default 64 5 16 2004 Treck Incorporated Programmer s Reference The following
300. e stored into Returns Value Meaning 0 Success TM_EINVAL One of the parameters is null or the device is a LAN device TM ENETDOWN Interface is not configured Note Also see tfSetSlipPeerIpAddress 5 203 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSetSlipPeerlpAddress include lt trsocket h gt int tfSetSlipPeerIpAddress ttUserInterface interfaceHandle ttUserlpAddress ifIpAddress Function Description This function is used to set a default remote SLIP IPaddress This IP address will be used as the default remote point to point IP address in case no remote IP ad dress is negotiated with SLIP If no IP address is set with this function then the local IP address 1 will be used as the default IP address for the remote SLIP for routing purposes tfSetSlipPeerIpAddress can only be called between tfAddInterface or tfCloseInterface and tfOpenInterface Parameters Parameter interfaceHandle iflpAddress Returns Value 0 TM EINVAL TM EISCONN Note Also see tfGetSlipPeerIpAddress 5 204 2004 Treck Incorporated Description The interface handle to update the Peer IP address in The IP address to use for routing purposes for the remote SLIP system Meaning Success The interface handle is null or the device is a LAN device SLIP connection is already estab lished Programmer s Reference tfSlipSetOptions include lt trsocket h gt int tfSlipSetOptions
301. e the original outgoing packet so that it can be sent once the address has been resolved In fact the host must decide whether to allow other application programs to proceed while it processes an ARP request The second part ofthe ARP code handles ARP packets that arrive from the network When an ARP packet arrives the software first extracts the sender s IP address and hardware address pair and examines the local cache to see if it already has an entry for that sender Ifthe cache entry exists for the given IP address the handler updates that entry by overwriting the physical address with the physical address obtained from the packet The receiver then processes the rest of the ARP packet It is important to understand this for reference to the next section ARP Encapsulation and Identification Before we continue it is important to know just what encapsulation is Encapsulation Is treating a collection of structured information as a whole without affecting or 1 18 2004 Treck Incorporated Introduction to TCP IP taking notice of its internal structure This means that we can take any information and essentially put it in between pertinent information There are guidelines to follow that dictate the format of encapsulation Keeping that in mind when ARP messages travel from one machine to another they must be carried in physical frames ARP Message Frame Header Frame Data Area Fig 1 12 ARP Message Encapsulat
302. e translate packets based on IP address alone All permanent triggers are configured by API calls As the trigger list is a LIFO linked list triggers configured or spawned later detect packets earlier and so take precedence Public vs Private Each public NAT interface maintains a linked list of triggers ttDevice devNatTriggerHead A private interface is simply one that is not public No transformations are needed on private interfaces The task of the NAT software is to make a public NAT interface appear private to the rest of the TCP IP stack Internally NAT is associated only with the interface to the public network The business of each public NAT interface involves public and private addresses and ports The system on which the stack is running is known by the public information on that exernal public network and by the private information by the TCP IP stack and other internal private networks Reference Implementation TSTNAT C implements a NAT Router with a private Ethernet and a public dialup PPP connection to the public Internet NAT API Application Programming Interface Functions 7 62 2004 Treck Incorporated Optional Protocols tfNatConfig include lt trsocket h gt int tfNatConfig ttUserInterface interfaceHandle Function Description Identify a stack device as a public NAT interface Call exactly once per public NAT interface Call before any other NAT functions on this interface If the
303. e trquicc c driver contains this method 4 59 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Device Driver Functions that You May Need to Provide In this section we will describe and provide examples for the functions that you may need to provide In all of these functions you can be guaranteed of single threaded access to them provided that you do not call any of these functions directly We use the internal Treck locking system to provide this facility Because of this you should not need any critical sections in the device driver code except to protect data area that you set or access in the ISR Success in all of these calls is returned to the stack via the macro TM DEV OKAY while failure is indicated by TM DEV ERROR 1 deviceOpen The stack calls this optional routine to initialize the hardware and optionally install the ISR handler If your driver requires pre allocated buffers to be given to the chip you could pre allocate your buffers in this function If your hardware initializes correctly then you should return a success value TM DEV OKAY otherwise you should return TM DEV ERROR This routine is optional if you perform your hardware initialization elsewhere Example int myDeviceOpen ttUserInterface interfaceHandle Initialize the Hardware Install the ISR Handler Routine tfKernelInstallIsrHandler myHandlerFunctionPtr myHandlerIsrLocation return TM DEV OKAY In additi
304. eFile fFSDeleteFile fFSGetNextDirEntry fFSGetUniqueFileName fFSGetWorkingDir fFSMakeDir fFSOpenDir fFSOpenFile fFSReadFile fFSReadFileRecord fFSRemoveDir fFSRenameFile fFSStructureMount fFSSystem fFSUserAllowed fFSUserLogin fFSUserLogout fFSWriteFile fFSWriteFileRecord dde age ee ee ec tot eS Telnet Daemon fTeldClosed fTeldIncoming fTeldOpened fTeldUserClose fTeldUserExecute fTeldUserSend fTeldUserStart fTeldUserStop t t t t t t t t Treck Test Suite fTestTreck tfTestUserExecute 6 3 Treck Real Time TCP IP User s Manual PING Application Program Interface Description Three calls are provided in the PING Application Program Interface First the user calls tfPingOpenStart This opens an ICMP socket and sends periodic PING echo request packets tfPingOpenStart is passed a pointer to a character array containing a dotted decimal IP address representation of the remote host the inter val in seconds between PING echo requests the user data length of the PING echo requests and a pointer to a call back function to be called upon reception of a PING echo reply or a network ICMP error message If successful tfPingOpenStart returns a socket descriptor The system will keep sending PING echo requests from the timer until the user calls tfPingClose passing the socket descriptor as returned by tfPingOpenStart as the parameter Prior to calling tfPingClose the user can call tfPingGetStatistics
305. eal Time TCP IP User s Manual System Y looks at the new set of options from System X and formulates another reply e don t know how to use CHAP let s use PAP in stead This last reply was a Conf Nak As you can see this message does not necessarily instruct System X to discard these options It merely tells the peer that certain attributes are unacceptable and offers values or attributes that are more agreeable System X must send another Conf Req e would like my PPP datagrams in 3000 byte blocks e would like you to identify yourself using PAP Because System X accepted the hints offered by System Y and included them in this Conf Req System Y will send a Conf Ack that would look like this e am going to send you data in 3000 byte blocks e will use PAP to identify myself This is only one half of the LCP process Both systems will send Conf Reqs nearly simultaneously In terms of our example negotiation System Y would also send a Conf Req to describe how it would like to receive its data as well PPP and Authentication On some systems a secure login is desirable These systems could be an ISP a business network with some form of remote access or any system that must be mindful of what other systems should or should not have access LCP negotiates what authentication method if any will be used Authentication actually taking place is a different phase There are a variety of authentication methods and we will bri
306. eceived and the device should not be restarted after a tfCloseInterface before a TM LL CLOSE COMPLETE event is received From these events it is also possible to determine why PPP negotiation failed For instance if authentication fails a TM LL LCP UP event is first received indicating that the physical link has been negotiated However if authentication fails the next event will be TM LL CLOSE STARTED and then TM LL CLOSE COMPLETE since the link must be closed if negotiation fails If authentication is successful the events that are received are TM LL LCP UP TM LL PAP UP or TM LL CHAP UP and then TM LL OPEN COMPLETE 7 101 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter linkNotifyFuncPtr Returns Description The function to call to notify PPP events or TM LNK NOTIFY FUNC NULL PTR if notification is not needed The events are TM LL OPEN COMPLETE TM LL CLOSE STARTED TM LL CLOSE COMPLETE TM LL LCP UP TM LL PAP UP TM LL CHAP UP The PPP Server link layer handle or NULL if there is an error 7 102 2004 Treck Incorporated Optional Protocols tfPppSetAuthPriority int tfPppSetAuthPriority ttUser8Bit authMethod ttUser8Bit priorityValue Function Description User calls this routine to set priority value for PPP authentication methods The priority value can be any integar between 1 with highest priority and 15 lowest priority inclusive The auth
307. eck Incorporated Treck Real Time TCP IP User s Manual tfKernellsrPostEvent The function ffKernelIsrPostEvent is used to signal that an event has occurred and resume tasks that are waiting via ffKernelPendEvent This is called from tfNotifyInterfacelsr itself called from an interrupt handler Note Most RTOS have special calls or wrappers when a system call is called from an interrupt handler Please consult your RTOS manual for the proper way to post from an interrupt handler void tfKernellsrPostEvent ttUserGenericUnionPtr eventPtr int kernelError kernelError RTOSSemPost eventPtr genVoidParmPtr if kernelError RTOS_NO_ERR tfKernelError tfKernellsrPostEvent Unable to Post on Semaphore tfKernelTaskPostEvent The function ffKernelTaskPostEvent is used to signal that an event has occurred and resume the transmit task waiting via ffKernelPendEvent This call is only called from the Treck stack in the context of a task This call is needed if the user has defined TM TASK XMIT macro in rsytem h or if the user calls f VotifyInterfaceTask and has defined either TM TASK RECV or TM TASK SEND void tfKernelTaskPostEvent ttUserGenericUnionPtr eventPtr int kernelError kernelError RTOSSemPost eventPtr genVoidParmPtr if kernelError RTOS_NO_ERR tfKernelError tfKernelPostEvent Unable to Post on Semaphore 4 34 2004 Treck Incorporated Integrating into Your Envi
308. eck Simple Heap TM_USE_SHEAP If the user defines this macro the stack allocates its blocks of memory from the Treck simple heap static array using the simple heap allocation routine tfSheapMalloc instead of calling the RTOS fKernelMalloc Similarly the Treck stack will release an allocated block of memory of size bigger than 4096 bytes by calling the Treck simple heap free routine zfS heap Free instead of calling the RTOS ffKernelFree The user will define this macro if the user s RTOS does not provide heap management routines or if the user does not want the Treck stack to allocate its blocks of memory from the RTOS heap TM SHEAP SIZE If you do define TM USE SHEAP then you also have to define TM SHEAP SIZE to give the size in bytes ofthe Treck simple heap array TM SHEAP MIN BLOCK SIZE 4 Minimum block size in bytes when using the simple heap either when allocat ing a new block or when refragmenting a freed block If not defined here default value is 4 4 24 2004 Treck Incorporated Integrating into Your Environment TM_DYNAMIC_CREATE_SHEAP Normally the Treck simple heap is implemented as a static array However you can override this behavior by defining the macro TM DYNAMIC CREATE SHEAP in your trsystem h file in which case you decide how you want to implement it i e dynamic memory allocation specific to your RTOS by customizing the API tfKernelSheapCreate If TM DYNAMIC CREATE SHEAP is defined then zfKernelS
309. econds between ARP retries DEFAULT 1 TM OPTION ARP QUIET TIME The length ofthe ARP quiet time state in seconds DEFAULT 20 5 122 2004 Treck Incorporated TM_OPTION_ARP_TTL TM_OPTION_ARP MAX ENTRIES TM OPTION ARP SMART TM OPTION ROUTE MAX ENTRIES TM OPTION RIP ENABLE TM OPTION RIP SEND MODE TM OPTION RIP RECV MODE TM OPTION IP FORWARDING TM OPTION IP FRAGMENT TM OPTION IP TTL TM OPTION IP DBCAST FORWARD Programmer s Reference The length of time that an ARP entry should be kept in the ARP cache in seconds To disable ARP aging setto TM RT INF DEFAULT 600 Maximum number of ARP entries in the ARP cache Each entry consumes about 100 bytes Lower this value if your heap space is low DEFAULT 64 Boolean to indicate whether the ARP logic should store all ARP mappings broadcast on the local network even if we were not waiting for a reply or if the request was not for us Set this option value to 0 if your heap space is low DEFAULT 1 on Maximum number of dynamic route entries in the routing table DEFAULT 10 Boolean to enable disable the RIPv2 Listener once it has been started DEFAULT 0 To start RIP the user should call tfUseRip The mode used to send RIP packets See below Default TM RIP 2 BROADCAST The mode used to receive RIP packets see below DEFAULT TM RIP 1 TM RIP 2 A boolean to enable IP forwarding DEFAULT 0 A boolean to enable directed
310. ectory If successful copy the directory path name in bufferPtr up to bufferSize The directory path name could be either absolute or relative to the user working directory path but should be such that a subsequent tfFSChangeDir with that pathname as an argument should not fail Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin pathNamePtr Pointer to a null terminated string containing directory path bufferPtr Pointer to a buffer where to copy the pathname of the newly created directory bufferSize Size in bytes of the buffer Returns Value Meaning E Failure gt 0 Number of bytes copied into the buffer pointed to by bufferPtr 6 99 Treck Real Time TCP IP User s Manual tfF SOpenDir include lt trsocket h gt void tfFSOpenDir void userDataPtr char pathNamePtr int flag Function description Given the unique user data pointer as returned by tfFSUserLogin a pointer to a path name and a flag this function opens the directory corresponding to the path for reading either a long directory flag TM DIR LONG or short directory TM DIR SHORT Subsequent calls to tfFSGetNextDirEntry will fetch each entry in the directory matching the pattern as pointed to by pathNamePtr The tfFSOpenDir implementer should allocate a directory data structure to keep track of the path name matching pattern the reading position in the directory and the directory read flag
311. ed Treck Real Time TCP IP User s Manual tfConfGetBootEntry include lt trsocket h gt ttUserBtEntryPtr tfConfGetBootEntry ttUserInterfac interfaceHandle unsigned char multiHomeIndex Function Description Get a pointer to DHCP BOOTP Conf BOOT entry obtained while doing a tfOpenInterface with either TM DEV IP BOOTP or TM DEV IP DHCP If successfull the function will return a pointer to a ttUserBtEntry structure as defined in trsocket h In particular this structure will contain e The allocated IP address in the field btuYiaddr Default router entry in the field btuDefRouter e Primary Domain name server btuDns1ServerlpAddress e Secondary Domain name server btuDns2ServerlpAddress Parameters Parameter Description interfaceHandle Ethernet interface handle multiHomelndex Multi home index of the ethernet device Returns Value Meaning userBtEntryPtr Pointer to a user boot entry as defined in trsocket h ttUserBtEntryPtr 0 Failure No DHCP address bound 7 18 2004 Treck Incorporated Optional Protocols tfUseBootp include lt trsocket h gt int tfUseBootp ttUserInterface interfaceHandle ttDevNotifyFuncPtr devNotifyFuncPtr Function Description This function is used to initialize the BOOTP client interface and should be called between tfAddInterface and tfOpenInterface to allow configuration using the BOOTP client protocol If the second parameter is non null then upon complet
312. ed Treck Real Time TCP IP User s Manual tfDialerAddExpectSend include lt trsocket h gt int tfDialerAddExpectSend ttUserInterface interfaceHandle char sendString char expectString char errorString int numRetries int timeout unsigned char flags i Function description This function adds an expect send pair to the dialer client waits for the server to send a string and then sends a string in response When the dialer reaches this phase it waits for the remote host to send a string If this string matches expectString sendString is sent back in response and the dialer moves to the next state If the received string matches errorString this phase is aborted and if TM DIALER FAIL ON ERROR is set in flags the entire dialing session is ter minated with an error The dialer will wait for expectString or errorString for a time equal to timeout in seconds If the number of retries specified by numRetries has not been exhausted when this time elapses the dialer will begin waiting again When the retry limit has been reached the dialer will abort the session and return with an error 7 48 2004 Treck Incorporated Optional Protocols tfDialerAddSendExpect include lt trsocket h gt int tfDialerSendExpect ttUserInterface interfaceHandle char sendString char expectString char errorString int numRetries int timeout unsigned char flags Function description This fu
313. ed tfFtpClose include lt trsocket h gt int ttUserFtpHandle Function description Application Reference tfFtpClose ftpSessionPtr This function closes an FTP client socket without sending a QUIT command Normally an FTP connection should be closed with the tfFtpQuit call However if the connection or the call to tfFtpQuit fails this call may be used Parameters Parameter fipSessionPtr Returns Value TM ENOERROR TM_EINVAL Description FTP session handle Meaning Success Invalid FTP session pointer Treck Real Time TCP IP User s Manual tfFtpConnect include lt trsocket h gt int tfFtpConnect ttUserFtpHandle ftpSessionPtr char ipAddressPtr Function description This function attempts to connect to a remote FTP server Parameters Parameter Description fipSessionPtr FTP session handle ipAddressPtr String specifying the IP address of the remote FTP server Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK This FTP session is non blocking and the call did not complete TM EALREADY Command in progress previous call did not yet finish TM EACCES Trying to connect to a different FTP server with disconnecting from current server TM BINVAL Invalid FTP session pointer TM FTP SERVREADY Service ready in n minutes for exact time use tfFtpGetReplyText to retrieve full reply text TM FTP SERVNAVAIL Service not available closing TELNET connection Applica
314. ed in a Physical Network Frame To identify the frame as carrying an ARP message the sender assigns a special value to the type field in the frame header and places the ARP message in the frames data field When a frame arrives at a computer the network software uses the frame type to determine its contents In most technologies a single type value is used for all frames that carry an ARP message Network software in the receiver must then further examine the ARP message to distinguish between ARP requests and ARP replies 1 19 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ARP Protocol Format Unlike most protocols the data in ARP packets does not have a fixed format header Instead to make ARP useful for a variety of network technologies the length of fields that contain addresses depend on the type of network To make it possible to interpret an arbitrary ARP message the header includes the fixed fields near the beginning that specify the lengths of the addresses found in the succeeding fields In fact the ARP message format is general enough to allow it to be used with arbitrary physical addresses and arbitrary protocol addresses Fig 1 13 shows an ARP message with 4 bytes per line 1 0 8 16 24 3 Hardware Type Protocol Type Hardware Address Protocol Address parto Length Length Sender Hardware Address Bytes 0 3 Sender Hardware Address Bytes 4 5 Sender IP Address Bytes 0 1 Sender IP Address Byt
315. ed in this section now takes the frame handle as a parameter A new API tfSendCompletePacketInterface has been added to allow the user to specify which frame has been transmitted So even if the user device driver does not support scattered send a user might still want to use the modified device driver send API described in this section if the user needs to signal out of order frame send completion Note The modified driver send interface is not supported for point to point link layers such as PPP or SLIP and is not supported in conjunction with a transmit queue TM_USE_DRV_ONE_SCAT_SEND First in order to allow a single call to the driver send routine for a scattered frame TM USE DRV ONE SCAT SEND need to be defined in trsystem h Modified driverSend The user driverSend function API must be modified to support a single call to the driver send routine for a scattered frame The modified driverSend function now takes only two parameters The first parameter is still the interfaceHandle as before The second parameter is a pointer to a structure containing the information needed to access the scattered data in a frame int devOneScatSendFunc ttUserInterface interfaceHandle ttUserPacketPtr 4 77 2004 Treck Incorporated Treck Real Time TCP IP User s Manual packetUPtr where ttUserPacketPtr is a pointer to a ttUserPacket structure ttUserPacket and ttUserPacketPtr are defined as follows typedef struct tsUserPacket
316. ed in trsystem h it is the user s responsibility to ensure that the user free function is re entrant as it could potentially be called from different threads 5 96 2004 Treck Incorporated Parameters Parameter socketDescriptor UserBlockPtr userBlockCount userFreeFunction flags toAddressPtr toAddressLength tUserBlock data type typedef struct tsUserBlock char userBufferPtr routine char userDataPtr int userDataLength ttUserBlock Programmer s Reference Description As returned by a socket call Pointer to the first element of the user array that contains information about the user scattered data number of elements in the above array Pointer to the user free function that will be called for each user buffer when the data in the user buffer no longer need to be accessed This function is called by the Treck stack with the pointer to the user buffer as a parameter 0 or MSG_DONTWAIT If MSG DONTWAIT the call is non blocking for the duration of the call If flag is 0 then it is blocking if the socket is in blocking mode non blocking otherwise The address to send the data to If the user had called connect on the socket then toAddressPtr should be null The length of the address Pointer to buffer passed to the free Pointer to beginning of data Data length Function prototype for the user supplied user data free call back function int userFreeFunc char TM
317. eference driver open function tfDeviceClearPointer include lt trsocket h gt void tfDeviceClearPointer ttUserInterface interfaceHandl Function Description tfDeviceClearPointer will clear the association created by tfDeviceStorePointer between the interface handle and the device specific structure allocated in the device driver open function Call tfDeviceClearPointer from the driver close function and then if the pointer returned by tfDeviceClearPointer is non null free it Parameters Parameter Description interfaceHandle Interface Id as returned by tfAddInterface Returns Value Meaning Non zero pointer Success Pointer to the device driver pointer ttVoidPtr 0 No associated device driver pointer on this interface Note See also tfDeviceGetPointer tfDeviceStorePointer 5 143 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDeviceGetPointer include lt trsocket h gt void tfDeviceGetPointer ttUserInterface interfaceHandle Function Description Call tfDeviceGetPointer in any device driver function to retrieve the pointer to the device specific structure allocated and stored with the tfDeviceStorePointer API in the device driver open function tm device get pointer This macro has the same functionality as tfDeviceGetPointer It allows the user to avoid a function call in order to get the device driver pointer In that case the following header files need
318. efly examine the most common three Password Authentication Protocol PAP This is one of the earliest and simplest of the authentication methods available With this method both peers know a secret and one will send a user name and password when it is requested Of course if authentication is intended to be bi directional there should be two sets of secrets PAP s weakness is that the user name and password are sent across the wire in clear text and leaves the possibility that these secrets can be intercepted 7 76 2004 Treck Incorporated Optional Protocols Systems that use PAP typically do not use re authentication though it is not impossible If re authentication is necessary LCP must renegotiate and utilize PAP again For more information regarding PAP please refer to RFC 1334 Challenge Handshake Authentication Protocol CHAP This authentication method is more secure than PAP because it does not send a clear text user name and password Instead when a peer wishes to validate another it sends a name and a randomly generated number The peer attempting to gain access uses the name given by the authenticator to obtain a plain text secret it may prompt the user or look it up in a database The secret is then hashed with the random number and the result is sent to the authenticator The original sender then uses the same algorithm and compares the result with the value it received from its peer Based on the comparison a su
319. eing re enabled before the ISR has completed Also extra code inside the ISR can change the system in other ways For example printf calls are frequently mapped to a serial port Serial ports are generally slow enough that making use of one inside an ISR can change a system s timing significantly thus hiding potential timing bugs or even cause interrupts to be missed Make sure that any data that are either modified or checked during an ISR are protected by a critical section when accessed or changed anywhere else in the code Frequently hard to track bugs will occur when variables that are used inside an ISR are not protected elsewhere in the code For example one section of the driver increments a variable by one and then does an if statement based on that variable on the next line of code However the driver s ISR function also modifies that variable If an interrupt occurs between the variable being incremented and the variable being checked it could lead to unexpected results This is also true in the reverse If you are using a long integer on a 16 bit system it takes more than one processor instruction to modify that variable If this variable is checked in the ISR it must be protected elsewhere in the code to ensure that an interrupt does not occur while the variable is only partially modified Temporarily put a critical section around the send and receive functions in the driver to isolate the problem area If there is
320. em because the hardware provides no information to the sender about whether the packet was successfully delivered With that in mind ifa destination machine happens to be powered down the packets sent to that machine will be lost without notifying the sender of that fact Later we will see how the TCP IP protocols accommodate best effort delivery systems Ethernet has no central authority to grant access therefore we say that access control is distributed The Ethernet access scheme is called Carrier Sense Multiple Access with Collision Detect Itis CSMA because multiple machines can access the Ethernet simultaneously and each machine determines whether the ether is idle by sensing if there is a carrier wave present Before a host interface sends a packet it listens to the ether to see if a message is already being transmitted We call this carrier sensing If there is no transmission sensed then it begins transmitting Each transmission is limited in duration because there is a maximum packet size which we will discuss later Also the hardware must observe a minimum idle time between transmissions That means that no single pair of communicating machines can use the network without giving other machines an opportunity for access 1 11 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Collision Detect and Recovery When a transceiver begins transmission the signal does not reach all parts of the network at the same ti
321. em will stop replying to ARP requests Returns Value Meaning TM ENOERROR Success TM EINVAL Bad parameter 0 IP address parameter TM ENOENT Entry was not in PROXY ARP table 5 217 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDelStaticRoute include lt trsocket h gt int tfDelStaticRoute ttUserlpAddress destIpAddress ttUserlpAddress destNetMask Function Description This function is used to delete a route from the interface Parameters Parameter Description destlpAddress The IP Address to add the route for destNetMask The net mask for the route Returns Value Meaning 0 Success TM_EINVAL One of the parameter is 0 TM_ENOENT No routing enry for this route in the routing table TM_EPERM Cannot delete an ARP entry with tfDelStaticRoute 5 218 2004 Treck Incorporated Programmer s Reference tfDisablePathMtuDisc include lt trsocket h gt int tfDisablePathMtuDisc ttUserlpAddress destIpAddress unsigned short pathMtu E Function Description This function is used to disable path MTU discovery for a given route If pathMtu is zero or bigger than the outgoing device IP MTU then we will default the route IP MTU to the outgoing device IP MTU otherwise we will set the route IP MTU with the passed parameter value Parameters Parameter Description destlpAddress The IP address destination on which route we want to disable path MTU discovery pathMtu New fixed IP MTU If zero we
322. emory available to complete the operation TM EADDRINUSE The telnet server port is already in use TM ENOMEM Could not obtain a counting semaphore to be used for blocking the telnet server blocking mode only 6 128 Application Reference tfTeldUserStop include lt trsocket h gt int tfTeldUserStop void Function description This function stops execution of the telnet server by closing the listening socket and killing all existing connections Parameters None Returns Value Meaning TM ENOERROR Success TM EALREADY The telnet server has already been stopped 6 129 Treck Real Time TCP IP User s Manual Treck Test Suite Description The Treck stack includes a module that allows you to perform a variety of tests on your system These tests are outlined below UDP Tests TM TEST UDP SEND Sends UDP data to a remote server TM TEST UDP RECV Receives data from a remote client TM TEST UDP ECHO CLIENT Sends UDP data to a remote echo server and waits for the server to echo it back TM TEST UDP ECHO SERVER Receives UDP data from a remote client and echoes this data back to the client TCP Tests TM TEST TCP SEND Sends TCP data to a remote server TM TEST TCP RECV Receives TCP data from a remote client TM TEST TCP ECHO CLIENT Connects to a remote server and sends data to it waiting for the server to echo it back TM TEST TCP ECHO SERVER Accepts connections from remote peers Receives TCP data a
323. emory leak could also be caused by an error in the application For example failing to free zero copy receive buffers when the application calls t ZeroCopyRecv or tfZeroCopyRecvFrom will cause a loss of memory Another common problem occurs when the user calls tfZeroCopySend or tfZeroCopySendTo in non blocking mode If the error code is TM EWOULDBLOCK is returned the user still owns the buffer The buffer is freed in every other case Not having enough memory available for your system Frequently what appears to be a memory leak is simply a case of not giving the Treck stack enough memory to work with Try allocating more memory for the stack 1f available and see if allocations top out at a certain level C 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Corrupted Memory Calling tfSendCompleteInterface too soon or too frequently This could cause packets that have not been sent to be freed or packets to be freed more than once Endian mismatch between CPU and Ethernet chip For example an Ethernet chip with DMA capabilities write data to a buffer in main memory the address of which is written into one of its registers by the driver The driver writes the address in little endian mode but the chip interprets it as big endian and writes the data to the wrong part of memory Invalid physical memory address passed to the Ethernet chip For example passing a logical address data segment offset to a c
324. en it is possible to send more data Note If tfSendToInterface is used on an Ethernet interface with the interface configured temporarily with a zero IP address TM DEV IP USER BOOT flag then the only allowed destination IP addresses are either limited broadcast i e all F s or multicast addresses 5 93 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter Description socketDescriptor The socket descriptor to use to send data bufferPtr The buffer to send bufferLength The length of the buffer to send toPtr The address to send the data to toLength The length of the to area pointed to by toPtr flags See below InterfaceHandle Interface to send the data through mhomelndex Multihome index on the configured interface The flags parameter is formed by ORing one or more of the following MSG DONTWAIT Don t wait for data send to complete but rather return immediately MSG DONTROUTE The SO DONTROUTE option is turned on for the duration of the operation Only diagnostic or routing programs use it Returns Value Meaning gt 0 Number of bytes actually sent on the socket 1 An error occurred tfSendTolnterface will fail if TM_EBADF The socket descriptor is invalid TM_ENOBUFS There was insufficient user memory available to complete the operation TM EHOSTUNREACH No route to destination host TM EMSGSIZE The socket requires that message be sent atomically and the message
325. en the information will follow After the values have been calculated there may be an instance where the value is larger than a 16 bit word As we mentioned earlier the calculations are done in short word format If the result is larger than a 16 bit word the system performs a carry that allows the value to be shown as a 16 bit word This function is can be done a maximum of 2 times 1 43 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The Internet Control Message Protocol ICMP The previous section shows how the Internet Protocol software provides an unreliable connectionless datagram delivery service by arranging for each router to forward datagrams A datagram travels from router to router until it reaches one that can deliver the datagram directly to its final destination If a router cannot route or deliver a datagram or if the router detects an unusual condition that affects its ability to forward the datagram the router needs to inform the original source to take action to avoid or correct the problem In this section we will discuss a mechanism that Internet routers and hosts use to communicate control or error information We will see that routers use the mechanism to report problems and the hosts use it to test whether destinations are reachable The Internet Control Message Protocol In the connectionless system we have described so far each router operates autonomously routing or delivering datagrams that
326. enticator will try to negotiate authentica tion method with the highest priority If that authentication method is NAK ed by the peer it will choose the second one according to the priority value The less the priority value the higher priority to use The default priority value for the following authentication method is TM PPP AUTHMETHOD EAP 1 TM PPP AUTHMETHOD MSCHAP V2 2 not supported yet TM PPP AUTHMETHOD CHAP 3 TM PPP AUTHMETHOD PAP 4 TM PPP AUTHMETHOD MSCHAP VI 5 Note that whenever user calls tfPppSetAuthPriority the default priority value is gone User must call tfPppSetAuthPriority for all authentication methods if they want to change the default priority sequence EXAMPLE For example if user prefers the following priority sequence MSCHAPvI CHAP PAP then user may call tfPppSetAuthPriority TM PPP AUTHMETHOD MSCHAP VI 1 tfPppSetAuthPriority TM PPP AUTHMETHOD CHAP 2 tfPppSetAuthPriority TM PPP AUTHMETHOD PAP 3 RETURN TM ENOERROR successful return TM_EINVAL invalid parameter 7 103 2004 Treck Incorporated Treck Real Time TCP IP User s Manual PPP EXAMPLE Authenticator Policy Authenticator wants the peer to authenticate itself by using PAP CHAP or MS CHAPv1 with PAP to be the most preferred one and MS CHAPv1 the least preferred Peer Policy Supports MS CHAPv1 only needs Authenticator to set our IP address Expected behavior for authentication protocol 1 Authenticator sends L
327. equires that message be received atomically and bufferLength was too small TCP protocol requires usage of tfZeroCopyRecv not tfZeroCopyRecvFrom The socket is marked as non blocking and no data is available to be read 5 107 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfZeroCopySend include lt trsocket h gt int tfZeroCopySend int socketDescriptor ttUserMessage bufferHandle int bufferLength int flags Function Description This function 1s used to send a zero copy message It operates identically to send with the exception that it takes a zero copy buffer handle as a parameter and with the exception that it sends either the whole buffer or nothing Note Once tfZeroCopySend is called the caller does NOT own the buffer and it is freed by the TCP IP stack except when if fails with a TM EWOULDBLOCK error code in which case the user can either try and send the buffer at a later time or free the zero copy buffer using tf FreeZeroCopyBuffer Parameters Parameter socketDescriptor bufferHandle bufferLength flags Description The socket descriptor to send data to The zero copy buffer obtained from tfGetZeroCopyBuffer The length of the message to send See below The flags parameter is formed by ORing one or more of the following MSG DONTWAIT MSG_OOB MSG DONTROUTE 5 108 2004 Treck Incorporated Don t wait for data send to complete but rather r
328. er s Manual Interface configuration e tfUserStartArpSend can be called before the interface has been config ured with that IP address In that case the user has to have at least opened the interface with another IP address first or with a zero IP address and the TM DEV IP USER BOOT flag If the TM DEV IP USER BOOT flag has been used to open the interface then the user need to use tfFinishOpenInterface to finish the configuration with the selected IP address when it is determined that no other host uses that IP address e tfUserStartArpSend can be called after the interface has been config ured with the IP address parameter In that case ARP requests are being sent instead of ARP probes Parameters Parameters Description interfaceHandle Interface on which to send the ARP probe s request s ipAddress Target IP address of the ARP probe s request s Sender IP address of the ARP request s arpProbelnterval Interval in milliseconds between ARP probes requests If set to zero the default TM_PROBE_INTERVAL 2000 milliseconds is used for the probe interval numberArpProbes Maximum number of ARP probes requests to send Interval between ARP requests is arpProbelnterval in milliseconds If set to zero TM MAX PROBE 4 is used instead timeout Number of milliseconds to wait after sending the first ARP probe request and call the user call back function set by the user with tfUseCollisionDetection If set to z
329. er returned an Access violation message in the error packet The TFTP server returned a Disk full alloc exceeded message in the error packet The TFTP server returned a File already exists message in the error packet Treck Real Time TCP IP User s Manual TFTPD Application Program Interface Description The TFTPD Application Program Interface allows the user to run a TFTP server It consists of two parts User interface The user interface allows the user to start stop the TFTP server to allow stop remote TFTP clients to connect and exchange files with the host File system interface The file system interface allows the TFTP server to interact with the operating system s file system to do such things as store and retrieve files User Interface Four calls are provided in the TFTPD User Interface 1 tfTftpdInit This function must be called before any other TFTP API calls are made It ini tializes various data associated with the TFTP server 2 tfTftpdUserStart The user calls tfTftpdUserStart to open a TFTP server socket and to begin listening for incoming connections tfTftpdUserStart can be either blocking or non blocking as specified by its last parameter Blocking Mode In blocking mode tfTftpdUserStart should be called from a task It will block and wait for incoming connections and will not return unless an error occurs The TFTP server code is executed in the context of the calling task Choose
330. erPacket is defined as follows typedef struct tsUserPacket struct tsUserPacket pktuLinkNextPtr tt8BitPtr pktuLinkDataPtr ttPktLen pktuLinkDataLength ttPktLen pktuChainDataLength int pktuLinkExtraCount ttUserPacket ttUserPacket fields Description ptkuLinkNextPtr Points to the next ttUserPacket structure pktuLinkDataPtr Points to the data in the link pktuLinkDataLength Contains the length of that data pktuLinkChainDataLength pktuLinkExtraCount Contains the total length of the Scattered data Its value is ony valid in the first link Contains the number of extra links besides the first one Its value is only valid in the first link 5 105 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Example The following code extract shows how to navigate a scattered recv buffer and copies it into bufferArray define TM BUF ARRAY SIZE 3000 char bufferArray TM BUF ARRAY SIZE retCode tfZeroCopyRecvFrom ssd amp recvMessageHandle amp dataPtr sizeof bufferArray MSG SCATTERED tempSockAddrFrom sockPtr amp fromAddressLength if retCode gt 0 recvdLength retCode tm assert testzUdpToFrom retCode sendDataLength scatteredRecvCopyNCheck recvMessageHandle ttUser8BitPtr dataPtr ttPktLen retCode void tfFreeZeroCopyBuffer recvMessageHandle void scatteredRecvCopyNCheck tt UserMessage recvMessageHandle ttUser8BitPtr dataPtr ttPktLen msgLength
331. erSetFqdn const char fqdnPtr int fqdnLen int flags Function description This function is called by the user application to set the default system wide FQDN domain name If FQDN is not set using either tfDhcpConfSet or tfDhcpUserSet the value configured by this function will be used Parameters Parameter Description JSqdnLen the length of the domain name character string cannot be greater than 255 fadnPtr pointer to the domain name char string Flags Set it to TM DHCPF FQDN PARTIAL if the domain name is partial Returns Value Meaning 0 no error TM EINVAL Invalid FQDN domain name TM ENOBUFS Out of memory 7 34 2004 Treck Incorporated Optional Protocols DHCP User Controlled Configuration API Description With the user controlled configuration the user can query a DHCP server directly without automatically configuring an interface This is useful for example on a box that has an Ethernet interface serial lines and acts as a PPP server for the serial lines The user could get IP addresses from a DHCP server via the Ethernet interface and then assign those IP addresses to PPP clients on its serial lines Those IP addresses should also be added to the box proxy ARP table so that the box can respond to ARP requests on behalf of its PPP clients The following steps are needed tfInitTreckOptions must be called before tfStartTreck is called in order to reserve numberSerialLines DHCP user entries
332. erefore this option value should not be set to 0 for both ends of the link LQM TM_LCP_QUALITY_PROTOCOL Option Name Len Meaning TM LCP QUALITY PROTOCOL 4 Setting this option enables link quality monitoring The option value is specified in hundredths of a second and it configures the maximum time to delay i e LOR timer period between sending Link Quality Report mes sages refer to RFC 1989 Reporting Period field of the Quality Protocol Configura tion Option This option can be set for either the local or the remote end of the link however the direction in which it applies is the 7 90 2004 Treck Incorporated Optional Protocols opposite of what one would expect when remoteLocalFlag is set to TM PPP OPT WANT this specifies an option value that we want the remote end of the link to use and when remoteLocalFlag is set to TM PPP OPT ALLOW this specifies an option value that we will allow the remote end to configure us to use If a non zero option value is specified the LOR timer is started with the specified timeout period to pace the sending of Link Quality Report messages and this timer is restarted whenever a Link Quality Report mes sage 1s sent If the specified option value is 0 no LQR timer is used but instead a Link Quality Report mes sage is sent as a response every time one 1s received from the peer At least one side of the link must use the LQR timer to pace the sending of Link Quali
333. erface by calling setsockopt with the IPO DROP MEMBERSHIP option at the IPPROTO IP level The option pointer points to a structure containing the IP host group address and the interface defined by its IP address It will return TM EINVAL if the IP host group address is not a class D address or if there is no interface configured with the IP address stored in the structure It will return TM ENOENT if there is no such host group on the interface Otherwise the IP Host group address will be deleted from the interface and the Treck stack will call the interface driver specific ioctl to update the list of Ethernet multicast addresses corresponding to the IP host group addresses that have been added and not dropped The driver specific ioctl function is called with the TM DEV SET MCAST LIST flag value and with optionPtr pointing to the list of Ethernet multicast addresses corresponding to all the IP host group addresses added and not dropped and with optionLen indicating the number of those Ethernet multicast addresses We keep track of the list of Ethernet multicast addresses so that the driver does not have to Treck Stack Initialization of the IGMP Protocol When a new interface is configured the Treck stack will automatically join the 224 0 0 1 host group on that interface If RIP is enabled the Treck stack will also automatically join the 224 0 0 2 host group on that interface Limitations This implementation is for IP hosts only It does n
334. ernet Group Management Protocol is the protocol used by IP hosts to report their multicast group memberships to multicast routers Local host groups 224 0 0 0 through 224 0 0 255 memberships do not need to be reported since as indicated above they cannot be forwarded beyond the local subnet Without the IGMP protocol a host can send multicast IP datagrams but cannot receive any Description The following RFC s are implemented in the Treck IGMP implementation RFC 1112 Host Extensions for IP Multicasting RFC 2236 Internet Group Management Protocol RFC 2113 IP router alert option We will describe the design of the IP multicasting and the host IP IGMP protocol implementation in the Treck stack in detail Enabling the IGMP Code To compile in the IGMP code then the following macro should be added to trsystem h define TM_IGMP Sending Multicast Packets Send API Sending multicast packets does not require new API functions The user uses the send and sendto functions on a UDP socket with a multicast IP address destination 7 53 2004 Treck Incorporated Treck Real Time TCP IP User s Manual IP Outgoing Interface for Multicast Packets The user can choose a per socket default interface to send multicast packets by using a new setsockopt option IPO MULTICAST IF at the IPPROTO IP level with the IP address of the outgoing interface as the option value If the user does not specify a destination interfa
335. ero it will be set to the default value of numberArpProbes arpProbelnterval Returns 7 14 2004 Treck Incorporated Value TM_EINVAL TM ENOENT TM EALREADY TM ENOBUFS TM EPERM TM ENXIO TM ENOERROR Optional Protocols Meaning Invalid interface or NULL interface timeout is less than arpProbelnterval numberArpProbes The user is not checking the IP address for collision detection i e the user has not called tfUseCollisionDetection before calling tfUserStartArpSend tfUserStartArpSend has already been called for that IP address and has not timed out yet tfUserStartArpSend has already been called for that IP address for a different interface No memory to allocate a timer Interface is not a LAN interface i e ARP not permitted on that interface Interface has not been opened No error 7 15 2004 Treck Incorporated Treck Real Time TCP IP User s Manual BOOTP Automatic Configuration API Description The BOOTP user interface allows the user to query directly a BOOTP server for IP addresses that the user can use The Treck stack allows the user to retrieve the BOOTP addresses automatically When the user configures an interface multihome the Treck stack automatically queries a BOOTP server for an IP address and pa rameters and finishes configuring the interface multihome with the IP address and default router given by the BOOTP server Up to TM MAX IPS PER IF multihomes per interf
336. ers are meaningful for all tests For instance dataSize has no meaning when the test typeis TM TEST TCP CONNECT since no data is being sent and testType is not used when the TM TEST FLAG RANDOM option is chosen since the test type is selected at random Parameters Parameter Description testType The type of test to perform see above ipAddrStr String containing the IP address of the remote host eg 10 0 1 5 portNumber Port on the remote host to perform the test against dataSize Data buffer size for this test eg the size of the UDP datagram to send or the amount of data to receive testCount The number of times to execute this test 6 134 flags sessionHandlePtr testParam Returns Value TM_EINVAL TM_EINVAL TM ENOERROR TM EWOULDBLOCK TM EIO Application Reference Options to apply to this test see above Pointer to a test session handle Used in non blocking mode to return a session handle to be used with tfTestUserExecute Not used in blocking mode Not currently used Meaning Invalid test type specified No session handle pointer specified in non blocking mode Test completed successfully Returned when the test is run in non blocking mode The user should call tfTestUserExecute with the value specified in sessionHandlePtr to continue the test Incoming data failed validation 6 135 Treck Real Time TCP IP User s Manual tfTestUserExecute include lt trsocket h gt
337. ersions that differ from theirs preventing them from misinterpreting datagram contents according to an outdated format The header length field HLEN also 4 bits gives the datagram header length measured in 32 bit words As we will see all fields in the header have fixed length except for IP OPTIONS and corresponding PADDING fields The most common header which contains no options or padding measures 20 bytes and has a header length field equal to 5 The TOTAL LENGTH field gives the length of the IP datagram measured in bytes including bytes in the header and data The size of the data area can be computed by subtracting the length of the header HLEN from the TOTAL LENGTH Because the TOTAL LENGTH field is 16 bits long the maximum possible size of an IP datagram is 65 535 bytes It may become more important if future networks can carry data packets larger than 65 535 bytes 1 39 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Datagram Type of Service and Datagram Precedence Informally called Type of Service TOS the 8 bit SERVICE TYPE field specifies how the datagram should be handled and is broken down into five subfields Three PRECEDENCE bits specify datagram precedence with values ranging from 0 normal precedence through 7 network control allowing senders to indicate the importance of each datagram Although most host and router software ignores type of service it is an important concept because it p
338. es 2 3 Target Hardware Address Bytes 0 1 Target Hardware Address Bytes 2 5 Target IP Address Bytes 0 3 Fig 1 13 Example of ARP Format when Used for IP to Ethernet Address Resolution The length fields depend on the hardware and protocol address lengths which are 6 bytes for an Ethernet address and 4 bytes for an IP address 1 20 2004 Treck Incorporated Introduction to TCP IP Hardware Type Specifies a hardware interface type for which the sender seeks an answer Contains a value of for Ethernet Protocol Type Specifies the type of high level protocol address the sender has supplied It contains 0800 for IP addresses Operation Specifies an ARP Request ARP Response 2 Reverse ARP RARP Request 3 or RARP Response 4 Hardware Address Length Specifies the length of the hardware address Protocol Address Length Specifies the length of the high level protocol address Sender Hardware Address Specifies the sender s hardware address if known Sender IP Address Specifies the sender s Internet Protocol address if known Target Hardware Address When making a request specifies the sender s hardware address Target IP Address When making a request specifies the sender s IP address Unfortunately the variable length fields in ARP packets do not align neatly on 32 bit boundaries making Figure 1 13 difficult to read For example the sender s hardware address labeled Sender Hardware Address oc
339. es 5 73 HEFIUSHRECYO MTM 5 74 tfFreeDynamicMermioty eco eo eerte tenerent cre ede set roiun ierre ete ect 35 75 itEreeZeroC oOpyBU tlet oce enger temor tn E Dateien 5 76 tfGetOobDataOffset 3e as a been RE einai Gee 5 77 2004 Treck Incorporated tiGetSendComplt Bytes ses ants ubuntu 5 78 tfGetSocketError ssscsscscecssessssensesscssenceescsssnscsenecssssesscsessessnscessessseeoss 5 79 tiGetWaltINEBYtES ss esc runs wit ates stip ertet arin dece ee vs 5 80 tfGetZeroCopy Butter 2 52 54 vs iei pte eere pP neta o Fa pue dese ba 5 81 tnt TOA SCi e s ER ERES GREASE ee en eens 5 82 i TpScatteredSendos o ors es tete teria reri etri Pr tm 5 83 LIRAWSOCREL otii ie aem hide 5 85 t RGCVErOf IO terrre Er ERE EH FREE Fer EE TREET EE REPRE 5 87 tiRegisterlpROrw CB ettet sb este ree olea derby beue Den 5 89 tfResetConnection esse 5 90 Send TORLONI ore pda ete tte es 5 91 tfSendTolInterface eseessssseeseeeeeeeee nennen eene 5 93 tfSocketArrayWalk cessit entree robe teen steer e eari eseni ino insek 5 95 tfSocketScatteredSendTo sss eene 5 96 t ZeroCopyRecyv cnt eret meme ananas 5 99 MSG SCATIEBREDBD utro y PHRRCE eE KSEE OREERT OET iE 5 100 ERAT Aee Hse lon owen 5 101 tiZeroCopyRe8VEEFOID tbt ahs aavenesiteahasitebonstabiv E ERER NEsT EES 5 104 MSG SCATTERED 5 nire on reor e em ne et hes 5 105 Example 0 M eine testate Der ALI 5 106 t ZeroCopySend nessie Linc ce tbe
340. es reliability is in the format of the header As we mentioned earlier the unit of transfer between two machines using TCP software is called a segment Segments are exchanged to establish connections to transfer data to send acknowledgements to advertise window sizes and to close connections Let s look at the format of a TCP segment including the TCP header 0 16 31 Source Port Destination Port Sequence Numbers Acknowledgement Number HLEN Reserved Code Bits Window Checksum Urgent Pointer Options If Any Padding Data Fig 1 41 Format of a TCP Segment Including the TCP Header 1 57 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Each segment is divided into two parts a header followed by data The header also called the TCP header carries the expected identification and control information The Fields SOURCE PORT and DESTINATION PORT contain the TCP port numbers that identify application programs at the ends of the connection The SEQUENCE NUMBER field identifies the sender s byte stream of data in the segment The ACKNOWLEDGEMENT NUMBER specifies the number of bytes the source expects to receive next The sequence number refers to the stream flowing in the same direction as the segment while the acknowledgement field refers to the stream flowing in the opposite direction The following chart shows examples of currently assigned port numbers Decimal Keyword Description 7
341. esets current FTP connection to the state just following the initial connection This requires that the user be authenticated again using tfFtpLogin Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK This FTP session is non blocking and the call did not complete TM EACCES Previous command did not com plete TM ENOTCONN The user is not currently connected to a FTP server TM BINVAL Invalid FTP session pointer TM FTP SERVREADY Service ready in n minutes for exact time use tfFtpGetReplyText to retrieve full reply text TM FTP SERVNAVAIL Service not available closing TELNET connection TM FTP SYNTAXCMD Syntax error command unrecog nized TM FTP NOCMD Command not implemented Application Reference tfFtpRename include lt trsocket h gt int tfFtpRename ttUserFtpHandle ftpSessionPtr char fromNamePtr char toNamePtr Function description This function renames file on remote file system Parameters Parameter Description fipSessionPtr FTP session handle fromNamePtr Old filename toNamePtr New filename Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK This FTP session is non blocking and the call did not complete Previous command did not com plete TM EACCES TM ENOTCONN TM ENOTLOGIN TM EINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP NOCMDPARAM TM FTP SERVNAVAIL The user is
342. esh the receive pool and perform send completes Note that flag values bigger than or equal to 0x1000 are reserved by the Treck stack Example int myDeviceIloctl ttUserInterface interfaceHandle int flag void TM FAR optionPtr int optionLen int errorCode switch flag case REFILL RECEIVE myDriverReceiveRefill errorCode TM DEV OKAY break default errorCode TM DEV ERROR break return errorCode 4 62 2004 Treck Incorporated Integrating into Your Environment If you are using the Treck stack ISR pool functions i e if you had called tfPoolCreate in your deviceOpen function then you need to call the following function periodically errorCode tfloctlInterface interfaceHandle TM DEV IOCTL REFILL POOL FLAG void TM FAR 0 0 Note that in that case ffToctlInterface will not call your device driver ioctl function The pool refill will be done internally by the Treck stack 4 driverGetPhysicalAddress This routine is used to return the physical address of the device to the stack Currently it is only called for Ethernet devices The protocol stack needs the physical address to formulate an Ethernet frame Example int myDeviceGetPhyAddr ttUserInterface interfaceHandle char TM FAR physicalAddress Get the physical address from hardware or firmware Save it in Network Byte Order ay tfMemCpy physicalAddress deviceAddress TM_ETHERNET_PHY_ADDR_LEN return
343. essage Function pointer pointing to a user defined routine that handles a received LCP Echo Reply message Meaning Success The interface handle is invalid The PPP interface is not open connected The length of the Echo Request message exceeds the MRU used on the link Could not allocate a buffer for the Echo Request message 7 125 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfLqmSetLqrTimerPeriod int tfLqmSetLqrTimerPeriod ttUserInterface interfaceHandle ttUser32Bit lqrTimerPeriodMsec Function Description tfLqmSetLqrTimerPeriod can be called to increase the frequency of sending LQRs i e decrease the LQR timer period when using a LQR timer This function should be called by the user to send LQRs faster when the link is good outgoing but very bad incoming since in that case incom ing LQRs will be frequently lost The LQR timer period cannot be increased to be longer than the negotiated period Parameters Parameter Description interfaceHandle The PPP interface handle as returned by tfAddInterface IqrTimerPeriodMsec Configures how long in millisec onds we wait before sending a LQR This period cannot be longer than the negotiated period for the LQR timer and cannot be 0 Returns Value Meaning 0 Success TM EINVAL The interface handle is invalid or IqrTimerPeriod is invalid i e was 0 or was longer than the negotiated period TM EOPNOTSUPP No LQR timer is
344. est suite may be run in either blocking or non blocking mode In blocking mode the tfTestTreck function will return either when the test has successfully completed or when an error has occurred In non blocking mode tfTestTreck simply initiates the test This function returns immediately returns a session handle to the user and returns the result code TM EWOULDBLOCK After the test is started the user should call tfTestUserExecute in their main loop to execute an iteration of the test This function will return TM EWOULDBLOCK if the test is still in progress any other return code indicates that the test is complete and the user should no longer call tfTestUserExecute For instance a non blocking test s main loop may look something like ttUserTestHandle testHandle int testStarted testStarted 0 while 1 if testStarted 0 Attempt to send 25 UDP buffers of 500 bytes each to remote host 10 0 1 5 at port 9 This should be done in non blocking mode using the Treck Zero Copy socket extensions errorCode tfTestTreck TM TEST UDP SEND 10 0 1 5 htons 9 500 Er TM TEST FLAG NONBLOCKING TM TEST FLAG ZEROCOPY amp testHandle 0 testStarted 1 else errorCode tfTestUserExecute testHandle if errorCode TM EWOULDBLOCK TEST COMPLETE 6 132 Application Reference tfTimerExecute if tfCheckInterface interfaceHandle TM ENOERROR tfRec
345. eturn immediately Send out of band data on sockets that support this notion The underlying protocol must also support out of band data Only SOCK_STREAM sockets created in the AF_INET address family support out of band data The SO DONTROUTE option is turned on for the duration of the MSG SCATTERED Returns Value gt 0 1 tfZeroCopySend will fail if TM_EBADF TM_ENOBUFS TM EHOSTUNREACH TM EMSGSIZE TM EWOULDBLOCK TM ENOTCONN TM ESHUTDOWN TM EFAULT TM EINVAL Programmer s Reference operation Only diagnostic or routing programs use it Non TCP sockets Set this flag when sending a scattered zero copy recv buffer received with tfZeroCopyRecv See tfZeroCopyRecv Note that to send a user scattered buffer not obtained via a call to tfZeroCopyRecv then tfSocketScatteredSendTo can be used Meaning Number of bytes sent An error has occurred The socket descriptor is invalid There was insufficient user memory available to complete the operation Non TCP socket only No route to destination host The socket requires that message to be sent atomically and the message was too long The socket is marked as non blocking and the buffer length exceeds the available space left in the send queue Socket is not connected User has issued a write shutdown or a tfClose call TCP socket only bufferHandle does not correspond to a zero copy buffer One of the par
346. f strategy quickly spreads the attempts to retransmit over a reasonably long period of time therefore resulting in fewer collisions Because an Ethernet is a bus with the possibility of collisions one should not over utilize the Ethernet 80 utilization is about the maximum any Ethernet should be loaded with Ethernet Capacity The standard Ethernet is rated at 10 Mbps That means that data can be transmitted onto the cable at 10 million bits per second Although computers can generate data at Ethernet speed raw network speed should not be thought of as the rate at which two computers can exchange data Instead network speed should be thought of as a measure of the network s traffic capacity Think of a network as a water supply line in a house and think of packets as the water A large diameter pipe can carry a large quantity of water while a small diameter pipe can only carry a small amount of water So if you have a supply line to 20 sinks chances are that it will not work efficiently if all the sinks are turned on at the same time However if you have a3 supply line to those same 20 sinks it could easily handle supplying water if those sinks were all turned on at the same time This is the same way with an Ethernet For example a 10Mbps Ethernet can handle a few computers that generate heavy loads or many computers generating light loads 1 12 2004 Treck Incorporated Introduction to TCP IP Ethernet Hardware Addressing
347. f the BOOTP server has replied and the configuration has completed e Asynchronous check To avoid this synchronous poll the user can provide a user call back function to tfUseBootp as shown above This function will be called upon completion of tfOpenInterface The notifyFunc is called when the interface multi home index is configured or if the BOOTP request timed out as follows myNotifyFunction interfaceHandle errorCode where errorCode is 0 if the configuration was successful or TM ETIMEDOUT if the BOOTP request timed out BOOTP Configuration parameters When the BOOTP configuration has completed successfully as shown above the user can retrieve the BOOTP configuration parameters by calling userBtEntryPtr tfConfGetBootEntry ethernetInterfaceHandle multiHomeIndex If the BOOTP configuration has been successful this function will return a pointer to a boot structure null otherwise The userBtEntryPtr is a pointer to a structure defined in trsocket h In particular the userBtEntryPtr will contain The allocated IP address in the field userBtEntryPtr 7 btuYiaddr The subnet mask in the field userBtEntryPtr gt btuNetMask Default router entry in the field userBtEntryPtr gt btuDefRouter Configuring additional BOOTP IP addresses on the same interface To configure additional BOOTP IP addresses on the same interface multi hom ing use tfConfigInterface instead of tfOpenInterface 7 17 2004 Treck Incorporat
348. f the file system does not support records then the system end of line i e lt CR gt lt LF gt for DOS lt LF gt for Unix should be used instead of EOR Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin fileDataPtr Pointer to file data structure as returned by tfFSOpenFile bufferPtr Pointer to buffer data to copy into the file bytes Size in bytes of the data in the buffer eor End of record indicator 1 if end of record need to be written Returns Value Meaning 0 Success 1 Failure 6 113 Treck Real Time TCP IP User s Manual Telnet Daemon Description The TELNETD Application Program Interface allows the user to run a TELNET server It consist of 2 parts User to Telnet server interface The user to Telnet interface allows the user to start stop the Telnet server to allow stop remote telnet clients to connect and login on the server It also allows the user to send data to each connected telnet client Telnet server to user interface The Telnet server to user interface allows the telnet server to notify the user of incoming connections It also allows the telnet server to hand data received from each connected telnet client to the user after the NVT conversion has been performed by the telnet server User to Telnet server interface Five calls are provided in the user to telnet server interface tfTeldUserStart The user calls tfTeldUserStart to open a TEL
349. fOpenInterface tfPoolCreate tfPoolDelete tfPoollsrFreeBuffer tfPoolIsrGetBuffer tfPoolReceive tfRecvInterface tfRecvScatInterface tfSendCompleteInterface tfSendCompletePacketInterface tfSetIfMtu tfUnConfigInterface tfUseInterfaceOneScatSend tfUseInterfaceScatRecv 5 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUselnterfaceXmitQueue tfUselntfDriver tfUseScatIntfDriver tfWaitReceivelnterface tfWaitSentInterface tfWaitXmitInterface tfXmitInterface Null Link Layer API tfUseNullLinkLayer Ethernet API tfGetEthernetBuffer tfUseEthernet SLIP API tfGetSlipPeerlpAddress tfSetSlipPeerlpAddress tfSlipSetOptions tfUseSlip ARP Routing TableAPI tfAddArpEntry tfAddDefaultGateway tfAddMcastRoute tfAddProxyArpEntry tfAddStaticRoute tfDelArpEntryByIpAddr tfDelArpEntryByPhysA ddr tfDelDefaultGateway tfDelProxyArpEntry tfDelStaticRoute tfDisablePathMtuDisc tfGetArpEntryByIpAddr tfGetArpEntryByPhysA ddr tfGetDefaultGateway tfUseRip Timer Interface API tfTimerExecute tfTimerUpdate tfTimerUpdatelsr Kernel RTOS Interface tfKernelCreateCountSem tfKernelCreateEvent tfKernelDeleteCountSem tfKernelError tfKernelFree tfKernelInitialize tfKernelInstalIsrHandler tfKernelIsrPostEvent tfKernelMalloc tfKernelPendCountSem tfKernelPendEvent tfKernelPostCountSem tfKernelReleaseCritical 5 4 2004 Treck Incorporated tfKernelSetCritical tfKernelSheapCreate tfKernelTaskPostEvent tfKernelT
350. face 4 52 2004 Treck Incorporated Integrating into Your Environment void xmitTask void while 1 Wait for the post from the Treck stack tfWaitXmitInterface myInterfaceHandle Move the data from the stack to the device driver send function Ey tfXmitInterface myInterfaceHandle An example of using these calls to transmit the packets from a main line loop is as follows void main void ttUserInterface interfaceHandle int errorCode short optionValue errorCode tfStartTreck treckStarted 1 Other main processing like adding an interface if errorCode TM_ENOERROR optionValue 1 turn option on errorCode tfInterfaceSetOptions interfaceHandle TM_DEV_OPTIONS_XMIT_TASK amp optionValue sizeof short Other main processing like installing a timer ISR to make sure that tfTimerUpdatelsr is called periodically and opening the interface for Check if Treck timers have expired tfTimerExecute Check for received packets if tfCheckReceiveInterface myInterfaceHandle TM ENOERROR Call the stack to move the data from the driver and process it Ey tfRecvInterface myInterfaceHandle 4 53 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Check for packets to send if tfCheckXmitInterface myInterfaceHandle TM_ENOERROR Call the stack to move the data from the Treck stack
351. faceHandle ttEapMd5AuthFuncPtr authFuncPtr i Function Description When acting as a PPP server a function must be called to validate an incoming authentication request This function is passed the username and must return the associated secret The prototype for the authentication function is defined to be char myEapMdSAuthenticate char username int errorCode If the username is valid and a secret is being returned errorCode should be set to zero However if the specified username is invalid an unknown user for example errorCode should be set to a non zero value Parameters Parameter Description interfaceHandle The interface to use this authentica tion function on authFuncPtr Pointer to user s authentication routine Returns Value Meaning TM ENOERROR Success TM EINVAL interfaceHandle or authFuncPtr are NULL TM ENOPROTOOPT interfaceHandle refers to a device that does not support EAP 7 81 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfEapSetOption int tfEapSetOption ttUserInterface interfaceHandle int optionName const char optionValuePtr int optionLength Function Description Sets various EAP options Parameters Parameter Description interfaceHandle The interface handle to set the option on optionName Name of the option see below optionValuePtr Value of the option see below optionLength Length of the option see below Option Name Length Meaning
352. facelIsr TM EWOULDBLOCK There is no data waiting to be received from the device driver 5 135 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfCheckSentinterface include lt trsocket h gt int tfCheckSent Interface ttUserInterface interfaceHandle Function Description This function is used in conjunction with tfNotifyInterfacelsr and tfSendCompleteInterface to poll the device driver to see if the packet sent to the device driver has been sent This function will return 0 when the accumulated numberBytesSent notified by tfNotifyInterfacelsr has reached TM NOTIFY SEND LOW WATER 2048 by default When tfCheckSentInterface returns 0 the caller should then call tfSendCompleteInterface to allow the stack to free the zero copy buffers used by the protocol stack This callis used when the user does not have a separate send complete task or thread Parameters Parameter Description interfaceHandle The interface handle to check to see if data has been sent Returns Value Meaning 0 Send Complete has occurred the driver has called tfNotifyInterfaceIsr from the send complete interrupt service routine and the TM NOTIFY SEND LOW WATER mark has been reached TM EWOULDBLOCK No data has been sent yet or threshold has not been reached 5 136 2004 Treck Incorporated Programmer s Reference tfCheckXmitinterface include lt trsocket h gt int tfCheckXmitInterface ttUserInterface i
353. faceld This IP address is used as the default source IP address in packets sent to mcastAddress 2004 Treck Incorporated Returns Value TM ENOERROR TM EINVAL TM ENETDOWN TM EADDRNOTAVAIL TM EALREADY Programmer s Reference Meaning Successful interfaceld is an invalid interface ID The interface specified by interfaceld is not configured Either the interface specified by interfaceld was not configured with the multicast enabled flag i e TM DEV MCAST ENB or mcastAddress is not a valid multicast IP address This multicast route already exists 5 211 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfAddProxyArpEntry include lt trsocket h gt int tfAddProxyArpEntry ttUserlpAddress arplpAddress i Function Description Add an entry to the Proxy ARP table for the given IP address arpIpAddress is expected to be in network byte order Parameters Parameter Description arplpAddrss Ip address on behalf of which the system will reply to ARP requests Returns Value Meaning TM ENOERROR Success TM EINVAL Bad parameter 0 IP address parameter TM EALREADY Entry already in PROXY ARP table TM ENOBUFS Couldn t allocate proxy ARP entry 5 212 2004 Treck Incorporated Programmer s Reference tfAddStaticRoute include lt trsocket h gt int tfAddStaticRoute ttUserInterface interfaceld ttUserlpAddress destlpAddress ttUserlpAddress destNetMask ttUserIpAd
354. fer pointed to by first parameter of either tfGetEthernetBuffer tfGetDriverBuffer and the stack will be responsible for freeing that buffer when the stack is done processing that buffer If the device driver scattered recv function sets flagPtr to TM DEV SCAT RECV USER BUFFER then druBufferPtr points to a user allocated buffer When the stack 1s done processing that buffer the stack will call the device driver free function as set in tfAddInterface The user is responsible for managing the memory containing the array of ttDruBlock It is guaranteed that when the stack calls the modified driver recv function for an interface the array of ttDruBlock previously given to the stack 4 83 2004 Treck Incorporated Treck Real Time TCP IP User s Manual by a previous call to the driver recv function for the same interface will not be accessed anymore So it is safe for the user to re use the array itself then On the other hand it is only safe to re use a user allocated buffer after the device driver free function is called uDevBlockCountPtr Upon retrun from the device driver scattered recv function uDevBlockCountPtr should be set to the number of ttDruBlock in the arrary of ttDruBlock given to the stack flagPtr Upon retrun from the device driver scattered recv function flagPtr should be set to TM DEV SCAT RECV STACK BUFFER if the user used pre allocated stack buffers that the stack will be responsible fo
355. file has been reached Parameters Parameter Description socketDescriptor The socket descriptor from which to read data iov The list of buffers to put the received data iovent The number of buffers in the list 5 32 2004 Treck Incorporated Returns Value gt 0 0 1 ready will fail if TM_EBADF TM_EINVAL TM_ENOBUFS TM EWOULDBLOCK TM ESHUTDOWN TM ENOTCONN Programmer s Reference Meaning Number of bytes actually read from the socket EOF An error occurred The socket descriptor is invalid The iovent is 0 or less than 0 The sum of the iov len values overflowed an integer There was insufficient user memory available to complete the operation The socket is marked as non blocking and no data is available to be read The peer has closed the connection and there is no more data to read TCP socket only Socket is not connected 5 33 2004 Treck Incorporated Treck Real Time TCP IP User s Manual recv include lt trsocket h gt int recv int socketDescriptor char bufferPtr int bufferLength int flags Function Description recv is used to receive messages from another socket recv may be used only on a connected socket see connect accept socketDescriptor is a socket created with socket or accept The length of the message is returned If a message is too long to fit in the supplied buffer excess bytes may be discarded depending on the type of socket the mes
356. flag value For example if the user register for a recv event TM CB RECUY then the call back function will be called in the context of the receive task every time a packet is received from the network and queued in the socket receive queue Note that most ofthe call back calls will be made in the context ofthe receive task TM CB SOCKET ERROR TM CB RESET TM CB CLOSE COMPLETE events call backs could be made in the context of an application task or the receive task In all the other events call backs will be made in the context of the receive task Therefore processing should be kept at a minimum in the call back function In a multi tasking environment the user call back function should set a flag or increase a counter and signal the user application task Function prototype for the user supplied socket call back function void SocketCBFunc int SocketDescriptor int eventFlags E Example To register for incoming data incoming out of band data and remote close event notifications on socket descriptor sd retCode tfRegisterSocketCB sd socketCBFunc TM CB RECV TM CB RECV OOB TM CB REMOTE CLOSE 5 116 2004 Treck Incorporated Parameters Parameter socketDescriptor sockettCBFuncPtr eventFlags EventFlags TM CB CONNECT COMPLT TM CB ACCEPT TM CB RECV TM CB RECV OOB TM CB SEND COMPLT TM CB REMOTE CLOSE TM CB SOCKET ERROR TM CB RESET TM CB CLOSE COMPLT TM CB WRITE READY Programmer s Refe
357. followed with the exception that we move the bar between the third and fourth bytes to the left instead of to the right It allows us to group several class X addresses together to be one network address 1 36 2004 Treck Incorporated Introduction to TCP IP The Internet Protocol IP By concept a TCP IP Internet provides three sets of services as shown in Figure 1 28 by the way they are arranged in the figure we can see that there seems to be a dependency among them APPLICATION SERVICES RELIABLE TRANSPORT SERVICE CONNECTIONLESS PACKET DELIVERY SERVICE Fig 1 28 Three Conceptual Layers of Internet Services At the lowest level a connectionless delivery service provides a foundation on which everything rests At the next level a reliable transport service provides a higher level platform on which applications depend We will explore these services in more detail to see what each one provides and which protocols are associated with them Connectionless Packet Delivery Service The most fundamental Internet service consists of a packet delivery system Technically the service is defined as an unreliable best effort connectionless packet delivery system similar to the service provided by network hardware that operates on a best effort delivery pattern The service is called unreliable because delivery is not guaranteed The packet may be lost duplicated delayed or delivered out of order The service w
358. from on that socket Once you have retrieved your IP address and netmask from the net you can insert those values in the device and routing table using the tfFinishOpenInterface function errorCode tfFinishOpenInterface interfaceHandle IPAddr mask Note For more information on functions used in this section please refer to the Programmers Reference section of this manual 4 76 2004 Treck Incorporated Integrating into Your Environment Single Send Call Send per Frame Out of Order Send Description Single call to the driver send per scattered frame By default when the stack sends a frame scattered among different buffers and the device driver supports scattered send the stack will make multiple calls to the device driver send function one per scattered buffer This is inefficient This section describes additional APIs that have been added to the stack in order to support a single call to the device driver send API per frame even when sending scattered data Out of Order Frame Transmission Also because the user might want to order frames for transmission in a different order as transmitted by the stack the user might want to signal out of order frame send completion This is not allowed with the default device driver send interface because the frame handle is not given to the user as a parameter and therefore cannot be given as a parameter to tfSendCompleteInterface The modified device driver send API describ
359. g The function ffKernelError is used to report unrecoverable error messages and cause a restart of the system Errors that are reported include corrupt pointers and invalid memory The Treck protocol stack must not continue once this function has been called Example void tfKernelError char TM FAR functionName char TM FAR errorMessage printf Fatal Error in Function s s Wn functionName errorMessage while 1 LOOP Forever until the watchdog timer fires and reboots ny Warning Information Logging The function tfKernel Warning is used to convey to the user any abnormalities that occur during the normal operation of the Treck protocol stack These would include such items as bad checksums These are not fatal errors and the stack should continue to operate normally This function is provided to help the user diagnose network problems Example void tfKernelWarning char TM_FAR functionName char TM_FAR warningMessage printf Warning in Function s s Wn functionName warningMessage 4 27 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Task Suspend and Resume This set of functions is the most complex portion of the RTOS Kernel Interface For task suspend and remove we rely on a primitive that is available in most RTOS Kernels This primitive is a counting semaphore with an associated counter initialized to zero The features that we are looking for in the primitive
360. gth is bigger than the total data length in the user scattered buffers or IP header size is bigger than the maximum allowed by the RFC i e 60 or it less than the minimum 20 Data length of the IP datagram is bigger than the IP MTU and fragmentation is not allowed No route to host Destination IP address in the IP header is zero No interface could be found to send the packet out only if destination IP address is limited broadcast Outgoing interface is closed Interface transmit queue if full only if interface transmit queue is used Returned by device driver send function tfRawSocket include lt trsocket h gt int ttUserlpAddress int Function Description protocol Programmer s Reference tfRawSocket This function creates a raw socket A raw socket enables the user to either send data above the IP layer or to send data with the IP header In the latter case the user mustsetthe IPO HDRINCL option at the IP level in the setsockopt call When the user receives data on the raw socket the IP header is always included Given a transport layer protocol and IP address tfRawSocket returns a raw socket bound to TM RAW IP PORT and ipAddress Note that ipAddress can be a zero IP address if the user does not want to bind to a specific IP address The user can use this function only if TM USE RAW SOCKET has been defined in trsystem h An example of tfRawSocket usage is shown in the loop back test module txscat
361. hNamePtr Pointer to null terminated string containing new file name Returns Value Meaning 0 Success 1 Failure 6 106 Application Reference tfFSStructureMount include lt trsocket h gt int tfFSStructureMount void userDataPtr char pathNamePtr Function description Given the unique user data pointer as returned by tfFSUserLogin and a file sys tem this function mounts the user to the new file system Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFsUserLogin pathNamePtr Pointer to a null terminated string containing a file system name Returns Value Meaning 0 0 1 Failure 6 107 Treck Real Time TCP IP User s Manual tfFSSystem include lt trsocket h gt int tfFSSystem char bufferPtr int bufferSize Function description This function copies the official system name as assigned in the list of OPERATING SYSTEM NAMES in the Assigned Numbers RFC RFC 1700 into bufferPtr up to bufferSize bytes For example the DOS operating system has been assigned DOS as system name If the file system is a DOS file system then this function should copy DOS into bufferPtr If the system has not been assigned a system name in the RFC then this function should return 1 Parameters Parameter Description bufferPtr Pointer to a buffer where to copy the system name bufferSize Size in bytes of the buffer Returns Value Meaning Failure g
362. he tfUseInterfaceScatRecv call TM USE DRV SCAT RECV need to be defined in trsystem h Parameters Parameter Description interfaceHandle The interface handle of the device to recv data from devScatRecvFunc A function pointer to the device driver s recv function that handles scattered data within a frame in a single call Returns Value Meaning 0 Success TM EINVAL devScatRecvFunc is null TM EPERM The interface has already been opened 5 186 2004 Treck Incorporated Programmer s Reference devScatRecvFunc type is defined as follows int devScatRecvFunc ttUserInterface interfaceHandle ttDruBlockPtrPtr uDevBlockPtrPtr int uDevBlockCountPtr int flagPtr devScatRecvFunc Parameters devScatRecvFunc Parameter Description interfaceHandle The interface handle of the device to recv data from uDevBlockPtrPtr Address of an area where to store an array of user blocks describing the scattered data one block per scattered buffer uDevBlockCountPtr Address of an area where to store the number of scattered buffers within a frame flagPtr Address of an area where to store ownership of the scattered buffers that compose the received frame Upon return from the device driver scattered recv function uDevBlockPtrPtr points to an array of ttDruBlock There is one ttDruBlock per scattered buffer in the received frame Each ttDruBlock element contains a pointer to a user buffer a pointer to the beginning
363. he DHCP server returned a malformed domain name TM FQDNF NOT SUPPORTED if the DHCP server does not support the FQDN option 7 27 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM FQDNF NAMEREPLY if the DHCP server FQDN option reply contained a domain name 7 28 2004 Treck Incorporated Optional Protocols tfConfGetBootEntry include lt trsocket h gt ttUserBtEntryPtr tfConfGetBootEntry ttUserInterfac interfaceHandl unsigned char multiHomeIndex Function Description Get a pointer to DHCP BOOTP Conf BOOT entry obtained while doing a tfOpenInterface with either TM DEV IP BOOTP or TM DEV IP DHCP If successfull the function will return a pointer to a ttUserBtEntry structure as defined in trsocket h In particular this structure will contain The allocated IP address in the field btuYiaddr Default router entry in the field btuDefRouter Primary Domain name server btuDns1ServerlpAddress Secondary Domain name server btuDns2ServerlIpA ddress Parameters Parameter Description interfaceHandle Ethernet interface handle multiHomelndex Multi home index of the ethernet device Returns Value Meaning userBtEntryPtr Pointer to a user boot entry as defined in trsocket h ttUserBtEntryPtr 0 Failure No DHCP address bound 7 29 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDhcpConfSet include lt trsocket h gt int tfDhcpConfSet ttUserInterf
364. he IP protocol TM ENOBUFS There was insufficient user memory available to complete the operation TM EMSGSIZE pingDataLength exceeds socket send queue limit or pingDataLength exceeds the IP MTU and fragmentation is not allowed TM EHOSTUNREACH No route to remote host Example with a non null function pointer include lt trsocket h gt void tfPingUserCB int socketDescriptor socketDescriptor tfPingOpenStart 192 168 0 2 0 tfPingUserCB Example with a null function pointer include lt trsocket h gt socketDescriptor tfPingOpenStart 127 0 0 1 0 0 ttPingCBFuncPtr 0 6 9 Treck Real Time TCP IP User s Manual DNS Resolver Description The DNS Resolver allows a user to translate a hostname to an IP address an IP address to a hostname and to retrieve information about a host s mail exchang ers which is necessary to send SMTP e mail The user API consists of three functions that are called before a DNS operation is performed and then three functions to perform these operations Initialization functions tfDnsInit Initializes the DNS service and should be called before any other API call is made tfDnsSetServer Specifies the DNS server s to retrieve hostname information from tfDnsSetOption Sets various options regarding the operation of DNS timeout lengths number of retries etc User Interface tfDnsGetHostByName Translates the given hostname to its corresponding IP add
365. he Treck stack needs to be run in a given context If the user wants to run multiple instances of the Tubo Treck TCP IP stack any Treck TCP IP stack function should be called after a context has been set except for the context insensitive functions described below Context insensitive functions These Treck TCP IP stack functions can be called from any context or prior to setting any context Called from any or no context Comments tfInitTreckMultipleContext This function initializes the Treck global variables prior to any context creation tfTimer Update Called from a Timer task tfTimerUpdatelsr Called from Timer ISR A 11 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Initialization Sequence First initialization called before any other Treck TCP IP Stack call tflnitTreckMultipleContext void For each context contextHandle tfCreateTreckContext if contextHandl l ttUserContext 0 tfSetCurrentContext contextHandle errorCode tfStartTreck Summary of new context API s Context API Comments int tfInitTreckMultipleContext void Initializes multiple context global variables valid across all contexts ttUserContext tfCreateTreckContext void Create a Treck context i e allocate a structure contain ing all Treck variables for an instance of the Treck stack and returns a pointer to the newly allocated structure void tfSetCurrentContext ttUserC
366. he file transfer is completed or an error is returned The TFTP client code is executed in the context of the calling task Choose blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfTftpGet will return immediately It is then the user s responsibility to then call tfTftpUserExecute periodically to execute the TFTP client code Choose non blocking mode if you do not have an RTOS Kernel 6 72 Parameters Parameter filename remote_addr tfipbuf bufsize mode blocking Returns Value 0 TM_TFTP_EXECUT TM_TFTP_EINVAL TM_TFTP_EINVAL TM_TFTP_EINVAL TM_TFTP_ESOCK TM_TFTP_EBUF TM_TFTP_UNDEF TM_TFTP_NOUSER TM TFTP BADOP Application Reference Description Null terminated string containing the file name to retrieve from the server Structure representing the address of the server The type AF INET address and port for TFTP usually 69 must be filled in A pointer to a buffer to store the file into The size in bytes of the buffer TM TYPE ASCII for ASCII transfers TM TYPE BINARY for binary transfers TM BLOCKING ON for blocking mode TM BLOCKING OFF for non blocking mode Meaning Success A session is already in progress Only one session may be in progress at a time mode is neither TM TYPE ASCII nor TM TYPE BINARY blockingState is neither TM BLOCKING ON nor TM BLOCKING OFF blockingState is TM BLOCKING ON and blocking mode is not enabled
367. he interface ignores those packets that are addressed to other machines and passes to the host only those packets addressed to it The addressing mechanism and the hardware filter are needed to prevent the computer from becoming overwhelmed with incoming data Although the computer s CPU could perform the check doing so in the host interface keeps the traffic on the Ethernet from slowing down processing on all computers 1 13 2004 Treck Incorporated Treck Real Time TCP IP User s Manual A 48 bit Ethernet address can do more than specify a single destination computer An address can be one of three types e The physical address of one network interface a unicast address e The network broadcast address e A multicast address We typically write the Ethernet address in Hexadecimal For example 0x0ce134121978By convention the broadcast address all 1 s is reserved for sending to all stations simultaneously 11111111111111111111111111111111111111 or in hexadecimal FFFFFFFFFFFF Fig 1 8 Broadcast Address Multicast addresses provide a limited form of broadcast in which a subset of the computers on the network agree to listen to a given multicast address This set of computers is called a multicast group To join a multicast group the computer must instruct its host interface to accept the group s multicast address The advantage of multicasting lies in the ability to limit broadcasts Every computer in a mul
368. he stack by a previous call to the driver recv function on the same interface will not be accessed anymore So it is safe for the user to re use the array itself then On the other hand it is only safe to re use a user allocated buffer after the device driver free function has been called flagPtr parameter Description TM DEV SCAT RECV STACK BUFFER The scattered buffers used in the frame are pre allocated stack buffers The stack will be respon sible for freeing these buffers TM DEV SCAT RECV USER BUFFER The scattered buffers used in the frame belong to the user When the stack 1s done processing a buffer in a received frame the device driver free function as specified in tfAddInterface will be called for 5 188 2004 Treck Incorporated Programmer s Reference that buffer 5 189 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUselnterfaceXmitQueue include lt trsocket h gt int tfUselnterfaceXmitQueue ttUserInterface InterfaceHandle short numberXmitDescriptors Function Description Enable Disable the use of an interface transmit queue If specified depth numberXmitDescriptors parameter is zero this option is turned off Otherwise this function allocate an empty transmit ring of numberXmitDescriptors elements When an interface transmit queue is used if the device driver send function returns an error because the chip is not ready to transmit a pointer to the buffer
369. heapCreate will be called once per page By default there is one page of memory but that can be changed as shown in the TM SHEAP NUM PAGE section below TM SHEAP NUM PAGE 1 Number of memory pages Instead of a unique array the simple heap can be divided into several ones Uncomment TM SHEAP NUM PAGE and indicate the number of pages if you are using the simple heap with a system that has paged memory and that one page is too small to hold the whole simple heap memory static or preallocated by tfKernelSheap Create In this case the simple heap will be divided in several non contiguous pages If you do define TM SHEAP NUM PAGE to a number bigger than 1 then you will likely need to define TM DYNAMIC CREATE SHEAP also The default for TM SHEAP NUM PAGE is 1 Each page of memory must have the same size The default page sizeis TM SHEAP SIZE TM SHEAP NUM PAGE If the page size is lower or equal to 4Kb TM BUF Q6 SIZE you cannot use dynamic memory and must define TM DISABLE DYNAMIC MEMORY tfKernelSheapCreate This finction dynamically allocates the Treck simple heap tfKernelSheapCreate is only called when TM DYNAMIC CREATE SHEAP has been define d The size of the simple heap allocated must be TM SHEAP SIZE with the start of the simple heap 1 e the pointer returned being aligned on a 32 bit boundary Please see tfKernelSheapCreate in the programmer s reference section of this manual 4 25 2004 Treck Incorporated Treck Real
370. hen the DHCP client would decline the IP address and restart the discovery process in the INIT state after 10 seconds have elapsed Checking on completion of an automatic DHCP configuration Synchronous check The user can make multiple calls to tfOpenInterface to determine when the configuration has completed Additional calls to tfOpenInterface will return TM EALREADY as long as the DHCP server has not replied tfOpenInterface will return TM ENOERROR if the DHCP server has replied and the configuration has completed e Asynchronous check To avoid this synchronous poll the user can provide a user call back function to tfUseDhep as shown above This function will be called upon completion of tfOpenInterface The notifyFunc is called when the interface multi home index is con figured or if the DHCP request timed out as follows myNotifyFunction interfaceHandle errorCode where errorCode is 0 if the configuration was successful or TM ETIMEDOUT if the DHCP request timed out 7 25 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Automatic DHCP Configuration parameters When the DHCP configuration has completed successfully as shown above the user can retrieve the DHCP configuration parameters by calling userBtEntryPtr tfConfGetBootEntry ethernetInterfaceHandle multiHomeIndex If the DHCP configuration has been successful this function will return a pointer to a boot structure null otherwise The u
371. hese counts since they are used internally w counts Ptr gt lastOutLQRs may be compared with countsPtr gt peerInLQRs to determine how many outbound LQRs have been lost A countsPtr gt lastOutLQRs may be compared with outLORs to determine how many outbound LQRs are still in the pipeline En countDeltasPtr gt deltaPeerInPackets may be compared with countDeltasPtr gt deltaLastOutPackets to determine the number of lost 7 120 2004 Treck Incorporated Optional Protocols packets over the outgoing link 6 countDeltasPtr gt deltaPeerInOctets may be compared with countDeltasPtr gt deltaLastOutOctets to determine the number of lost octets over the outgoing link 7 countDeltasPtr gt deltaSavelnPackets may be compared with countDeltasPtr gt deltaPeerOutPackets to determine the number of lost packets over the incoming link 8 countDeltasPtr gt deltaSaveInOctets may be compared with countDeltasPtr gt deltaPeerOutOctets to determine the number of lost octets over the incoming link 9 countDeltas Ptr gt deltaPeerInDiscards and countDeltasPtr gt deltaPeerInErrors may be used to determine whether packet loss is due to congestion in the peer rather than physical link failure When reasonCode is set to TM LOM MONITOR_TIMEOUT countDeltasPtr and countsPtr are NULL If link quality is good your link quality monitoring function should return 0 otherwise it should return 1 unless you want to reduce the hysteresis and s
372. hip that is expecting a physical address could cause this problem Invalid alignment when receiving data Many Ethernet chips if they support DMA require that buffers they write into begin on a certain byte boundary These can be as small as two bytes that is buffers must begin on an even numbered memory address but are frequently as large as 16 bytes Not checking for failed memory allocation null pointer returned when allocating memory The ISR is changing or checking data that is changed or checked anywhere else in the driver If the data are not protected in the rest ofthe driver with critical sections an interrupt could occur at an inopportune time and lead to memory corruption or a host of other problems Locks are not working properly that is counting semaphores are not working properly This can be tested quickly with the tfTestTreck API call Make sure that counting semaphores you create have an initial value of Zero Receiving Corrupted Data Many chips do not tell you their pre allocated receive buffer alignment requirement A safe value to use if you do not know is 16 bytes Passing a receive buffer up the stack that has not been yet filled by the chip This is most frequently caused by an error in the receive ring logic Kernel Error Send Too Much Scattered Data C 8 This is a sign of corrupted memory See the Corrupted Memory section above 2004 Treck Incorporated Debugging a Device Drive
373. hird will be eight seconds etc Default 4 seconds Data Type unsigned char Total number of BOOTP DHCP requests to send without receiving a response from a BOOTP DHCP server Default 6 Data Type unsigned char 5 155 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Example on how to turn the usage of a transmit task on unsigned short optionValue optionValue 1 turn option on errorCode tfInterfaceSetOptions myInterfaceHandle TM_DEV_OPTIONS_XMIT_TASK amp optionValue sizeof unsigned short Parameters Parameter Description interfaceHandle Interface handle of the SLIP interface we want to set the option on optionName The option to set See above optionValuePtr The pointer to a user variable into which the option value is set User variable is of data type described above optionLength size of the user variable which is the size of the option data type Returns Value Meaning 0 Success TM_EINVAL Invalid optionName or invalid option length for option or invalid option value for option TM EPERM TM DEV OPTIONS RECV COPY Interface device is a point to point interface TM DEV OPTIONS XMIT TASK Interface device already configured opened or device interface transmit queue is used 5 156 2004 Treck Incorporated Programmer s Reference tfinterfaceSetVirtualChannel include lt trsocket h gt int tflnterfaceSetVirtualChannel ttUserInterface interfa
374. hort sin port struct in addr sin addr char sin zero 8 The structure in_addr that is used in sockaddr_in is defined as struct in_addr u_long s_addr These are the most important data structures used in sockets The second consists of an unsigned long integer that contains the IP address that will be associated with the socket The first has two other important fields sin family and sin port sin family tells sockets which protocol family to use For IPv4 the constant AF INET should always be passed in sin port tells what port number will be associated with the socket Sockaddr in is a modification of the standard sockaddr structure struct sockaddr u_char sa_len u_char sa_family char sa_data 14 Socket calls expect the standard sockaddr structure However for IPv4 communications it is proper to pass in a sockaddr in structure that has been cast to a sockaddr 2 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Common Sockets Calls This section lists the most commonly used socket calls and describes their uses This is purely introductory material For a more complete description of how the calls work please see the Programmer s Reference section of this manual socket Asocket in the simplest sense is a data structure used by the Sockets API When the user calls this function it creates a socket and returns reference a number for that socket That refere
375. hould be in passive mode and the second session should be in active mode The user needs to call tfFtpTurnPasv passing the fipUserHandleA parameter and the TM FTP PASSIVE MODE ON Parameters Parameter Description ftpUserHandleA The user handle of main FTP session will be operated on ftpUserHandleB The user handle of the 2nd FTP session for two FTP server model fromFileNamePtr Pointer to source file name string toFileNamePtr Pointer to destination file name string Returns Value TM EWOULDBLOCK TM EINVAL TM EACCES TM ENOTLOGIN TM ENOTCONN TM EOPNOTSUPP TM ENOERROR TM FTP NAVAIL TM FTP NOCMD TM FTP XFERSTART TM FTP FILEOKAY TM FTP DATAOPEN TM FTP XFERABOR TM FTP LOCALERR TM FTP EXSPACE TM FTP NOSPACE TM FTP FILENAVAIL TM FTP FILENAME TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMDPARAM TM FTP SERVNAVAIL TM FTP NOTLOGIN Application Reference Meaning The call is non blocking and did not complete Invalid ftpSessionPtr or bad filename Previous command has not finished Command requires user to be loggedin and user is not Command requires connection and user is not connected Command not supported by the user No error Success Requested action not taken file unavailable Command not implemented Data connection already open transfer started File status okay about to open data connection Can t open data connection Connection trouble closed transfer aborted
376. ignated by arguments provided by the user Code Voc d e Vof g Yi Yon 0 p s You Vox 1 5 252 2004 Treck Incorporated Description Read a character White space characters are not read unless c is used Read a decimal number Read a floating point number It can have a or sign It can also be a series of digits with a decimal point and an exponent e or E followed by a signed or unsigned integer Read a floating point number It can have a or sign It can also be a series of digits with a decimal point and an exponent e or E followed by a signed or unsigned integer Read a floating point number It can have a or sign It can also be a series of digits with a decimal point and an exponent e or E followed by a signed or unsigned integer Read a decimal integer Use an integer number to express the number of bytes successfully read Read an octal number Read a pointer platform specific Read a string Read an unsigned decimal integer Read a hexadecimal number Read a set of characters Programmer s Reference Parameters Parameter Description buffer The string to be parsed format The string containing the format specifiers dictating which type of data is to be read Returns The number of input fields that were both formatted and assigned a value If an error occurs tfSScanF will return End of File EOF 5 253 2004 Treck Incorporated Treck Real Time TCP IP
377. ile data structure as returned by tfFSOpenFile bufferPtr Pointer to buffer where to copy the data from the file bufferSize Size in bytes of the buffer eorPtr Pointer to end of record Returns Value Meaning gt 0 Number of copied bytes not including end of record 0 End of file has been reached 6 103 Treck Real Time TCP IP User s Manual 1 Failure 6 104 Application Reference tfFSRemoveDir include lt trsocket h gt int tfFSRemoveDir void userDataPtr char pathNamePtr Function description Given the unique user data pointer as returned by tfFSUserLogin and a directory name this function removes the directory Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin pathNamePtr Pointer to a null terminated string containing directory path name Returns Value Meaning 0 Success 1 Failure 6 105 Treck Real Time TCP IP User s Manual tfFSRenameFile include lt trsocket h gt int tfFSRenameFile void userDataPtr char fromPathNamePtr char toPathNamePtr Function description Given the unique user data pointer as returned by tfFSUserLogin a current file name and a new file name this function renames the file to the new file name Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFsUserLogin fromPathNamePtr Pointer to null terminated string containing current file name toPat
378. ill not detect such conditions nor will it inform the sender or receiver The service is called connectionless because each packet is treated independently from all others A sequence of packets sent from one computer to another may travel over different paths or some may be lost while others are delivered Finally the service is referred to as best effort delivery because the Internet software makes an earnest attempt to deliver packets That is the Internet does not discard packets arbitrarily Unreliability arises only when resources are exhausted or underlying networks fail 1 37 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Purpose of the Internet Protocol The protocol that defines the unreliable connectionless delivery mechanism is called the Internet Protocol and is usually referred to by its initials ZP IP provides three important definitions First the IP protocol defines the basic unit of data transfer used throughout a TCP IP Internet Thus it specifies the exact format of all data as it passes across a TCP IP Internet Second IP software performs the routing function choosing a path over which data will be sent Third in addition to the precise formal specification of data formats and routing IP includes a set of rules that embody the idea of unreliable packet delivery The rules characterize how hosts and routers should process packets how and when error messages should be generated and the conditions
379. in ffAddInterface or the driver receive function could call PoolReceive For example int myDeviceReceive ttUserInterface interfaceHandle char TM FAR TM FAR dataPtr int TM FAR dataLength ttUserBufferPtr bufHandlePtr return tfPoolReceive interfaceHandle dataPtr dataLength bufHandlePtr 4 68 2004 Treck Incorporated Integrating into Your Environment 7 driverFreeReceiveBuffer This function is used ONLY if you use your own buffer allocation for the received packets i e do not use fGetEthernetBuffer nor tfGetDriverBuffer nor the Treck stack recv ISR pool functions Since you pass a buffer to the stack the stack is zero copy you will need to know when the buffer is not in use anymore When this happens we call your driverFreeReceiveBuffer function to let you free or reuse the buffer Example int myDeviceFreeReceiveBuffer ttUserInterface interfaceHandle char TM_FAR dataPtr Free the Data here return TM_DEV_OKAY 8 driverIsrHandler The interrupt service routine only need to call the tfNotifyInterfacelIsr function if you use the Check or Wait functions described earlier Normally you need to dismiss the interrupt and notify the stack of the event that occurred The only call that you can make from a device interrupt handler into the protocol stack is one tfNotifyInterfacelIsr function Tip you should call fNotifyInterfacelsr only once per ISR because some RTOS on some CPU s will
380. in the setsockopt call when SO LINGER is requested If SO LINGER is disabled anda close on the socket is issued the system will process the close of the socket in a manner that allows the process to continue as quickly as possible 5 50 2004 Treck Incorporated Programmer s Reference The option SO BROADCAST requests permission to send broadcast datagrams on the socket With protocols that support out of band data the SO OOBINLINE option requests that out of band data be placed in the normal data input queue as received it will then be accessible with recv call without the MSG OOB flag SO SNDBUF and SO RCVBUF are options that adjust the normal buffer sizes allocated for output and input buffers respectively The buffer size may be increased for high volume connections or may be decreased to limit the possible backlog of incoming data The Internet protocols place an absolute limit of 64 Kbytes on these values for UDP and TCP sockets in the default mode of operation The following options are recognized at the IP level IP PROTOIP protocolLevel options IPO HDRINCL IPO TOS IPO TTL IPO SRCADDR IPO MULTICAST TTL IPO MULTICAST IF IPO ADD MEMBERSHIP IPO DROP MEMBERSHIP Description This is a toggle option used on Raw Sockets only If the value is non zero it instructs the Treck stack that the user is including the IP header when sending data Default 0 IP type of service Default 0 IP Time To Live in seconds
381. ing Normally the TCP code sends a non full sized segment only if it empties the TCP buffer Default 0 Set this option value to a zero value if the peer is a Berkeley system since Berkeley systems set the urgent data pointer to point to last byte of urgent data 1 Default 1 urgent pointer points to last byte of urgent data as specified in RFC1122 Set this option value to a non zero value to make TCP behavelike a message oriented protocol i e respect packet boundaries at the application level in both send and receive directions of data transfer Note that for the receive direction to respect packet boundaries the TCP peer which is sending must also implement similar functionality in its send direction This is useful as a reliable alternative to UDP Note that preserving packet boundaries with TCP will not work correctly if you use out of band data TM USE TCP PACKET must be defined in trsystem h to use the TM TCP PACKET option Default 0 Set this option value to a non zero value to enable sending the TCP selective Acknowlegment option Default 1 Set this option value to a non zero value to enable sending the TCP window scale option Default 1 5 55 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM TCP TS TM TCP SLOW START TM TCP DELAY ACK TM TCP MAX REXMIT TM TCP KEEPALIVE CNT TM TCP FINWT2TIME TM TCP 2MSLTIME TM TCP RTO DEF TM TCP RTO MIN TM TCP RTO MAX 5 56 2
382. ing at the same priority One task completes everything it needs to before another task is swapped in Another important item to consider when operating in embedded environments is that care must be taken with how we call a networking stack from an interrupt service routine If we were to receive a packet inside of an interrupt service routine and pass that packet to the networking stack it is possible that the packet may generate a response to the network This would increase the time that we stay inside of our interrupt service routine Most embedded systems have a requirement that the interrupt service routine time is kept to a minimum You will find with the Treck TCP IP a very small set of function calls are supported within an interrupt service routine These calls are limited in the amount of work that they do One of these would be to update the timer However this is not a recommended method for updating the timer system We would in fact prefer that the update and execute of the timer system be done in either a main line loop or a separate timer task Another call from an ISR that is supported is notification of a send complete or a received packet Note that we do not support passing a packet back to the stack from an ISR All we do is notify the stack that a packet has been received by the network hardware As we can see from what we have discussed thus far we only need the locking system when we are using Treck with a preemptive operati
383. ing between computers The original configuration of Ethernet technology involved setting up a connection between two computers using a coaxial cable This cable was generally 2 diameter and could be up to 500 meters long See figure 1 3 OUTER INSULATING JACEET gem BREAIDED METAL SHIELD POLYETHYLENE FILLER CENTER WIRE Fig 1 3 Cross Section of a Coaxial Cable Used in the Original Ethernet The cable itself was completely passive It carried no electrical current The only active electrical components that made the network function were associated with the computers attached to the network The connection between a computer and an Ethernet cable required a piece of hardware called a transceiver Looking at the physical cable there needed to be a hole in the outer layers for placement of the transceiver This was commonly referred to as a fap Usually small metal pins mounted to the transceiver would go through the hole in the cable to provide electrical contacts to the center wire and the braided shield Some manufactures made T s that required the cable to be cut and inserted Besides the transceiver there also needed to be a host interface or host adapter that would plug into the computer s bus This enabled the connection to be made from the computer to the network 1 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The transceiver is a small piece of hardware that was placed adjacent to th
384. int int int unsigned long unsigned long unsigned long unsigned long unsigned long int int int int Option data type Option value Oorl Oorl Oorl Oor1 Oorl Oor 1 Oorl Oorl Oorl Oor 1 Oor 1 0 or 1 0 or 1 Oor 1 Returns Value 0 1 getsockopt will fail if TM EBADF TM_EINVAL TM ENOPROTOOPT Programmer s Reference Meaning Successful set of option An error occurred The socket descriptor is invalid One of the parameters is invalid The option is unknown at the level indicated 5 23 2004 Treck Incorporated Treck Real Time TCP IP User s Manual htonl include lt trsocket h gt unsigned long htonl unsigned long longValue Function Description This function converts a long value from host byte order to network byte order Parameters Parameter Description long Value The value to convert Returns The converted value 5 24 2004 Treck Incorporated Programmer s Reference htons include lt trsocket h gt unsigned short htons unsigned short shortValue Function Description This function converts a short value from host byte order to network byte order Parameters Parameter Description shortValue The value to convert Returns The converted value 5 25 2004 Treck Incorporated Treck Real Time TCP IP User s Manual inet_addr include lt trsocket h gt unsigned long inet_addr char ipAddressDottedStringPtr Function
385. ion Given the unique user pointer as returned by tfFSUserLogin this function logs the user out and frees the structure pointed to by userDataPtr Parameters Parameter Description userDataPtr Pointer to the user data structure as returned by tfFSUserLogin Returns Nothing 6 111 Treck Real Time TCP IP User s Manual tfF SWriteFile include lt trsocket h gt int tfFSWriteFile void userDataPtr void fileDataPtr char bufferPtr int bytes Function description Given the unique user data pointer as returned by tfFSUserLogin and a file data pointer as returned by tfFSOpenFile this function writes bytes from the buffer pointed to by bufferPtr to the file Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin fileDataPtr Pointer to file data structure as returned by tfFSOpenFile bufferPtr Pointer to buffer data to copy into the file bytes Size in bytes of the data in the buffer Returns Value Meaning 0 Success 1 Failure 6 112 Application Reference tfFSWriteFileRecord include lt trsocket h gt int tfFSWriteFileRecord void userDataPtr void fileDataPtr char bufferPtr int bytes int eor Function description Given the unique user data pointer as returned by tfFSUserLogin and a file data pointer as returned by tfFSOpenFile this function writes up to bytes from the buffer in addition to an end of record 1f EOR is set to 1 I
386. ion specified by monitorFuncPtr must return 0 if link quality is good and a weighted non zero value if link quality is bad i e a value of 2 is twice as bad as a value of 1 etc When the accumulated value of bad counts returned by your link quality monitoring function exceeds hysteresisMaxFailures within the last hysteresisSamples times of calling your function you will be notified via the PPP callback flag TM LL LOM LINK BAD if you registered a link notifica tion function refer to tfUseAsyncPpp that the link is bad so that you can attempt recovery The link quality monitoring function will be called when one of the following events happens 1 A timeout occurs while waiting to receive a solicited Link Quality Report message from the peer The peer negotiated for us to use a non zero LOM reporting period which means that we are using the LQR timer to pace our sending of Link Quality Report messages This timer expired and we haven t yet received a Link Quality Report message from the peer for a Link Quality Report message we sent earlier i e reasonCode set to TM LOM MONITOR TIMEOUT 2 A Link Quality Report message is received from the peer 1 e reasonCode set to TM LOM MONITOR LQR 7 119 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The peer may not support LQM in which case the link quality monitoring function will never be called indicating that LQM is not being used on the link The function
387. ion Reference tfDnsSetServer int tfDnsSetServer ttUserIpAddress serverlpAddr int serverNumber Function Description This function sets the address of the primary and secondary DNS server To set the primary DNS server serverNumber should be set to TM DNS PRI SERVER for the secondary server it should be set to TM DNS SEC SERVER To remove a previously set entry set serverlpAddr to zero Parameters Parameter Description serverlpAddr IP address of the DNS server serverNumber Primary or secondary server Returns Value Meaning TM_EINVAL serverNumber is not TM DNS PRI SERVER or TM DNS SEC SERVER TM ENOERROR DNS server set successfully Treck Real Time TCP IP User s Manual FTPD Application Program Interface Description The FTPD Application Program Interface allows the user to run an FTP server It consists of two parts User interface The user interface allows the user to start stop the FTP server to allow stop remote FTP clients to connect and exchange files with the host File system interface The file system interface allows the FTP server to interact with the operating system s file system to store and retrieve files for example User Interface Three calls are provided in the FTPD User Interface 1 tfFtpdUserStart The user calls tfFtpdUserStart to open an FTP server socket and start listening for incoming connections tfFtpdUserStart can be either blocking or non blocking as specified by its last pa
388. ion of tfOpenInterface the function that it points to will be called Function prototype for the user supplied notify function void devNotifyFunc ttUserInterface interfaceHandle int errorCode This function will be called with the interfaceHandle passed to tfOpenInterface and with an error code value which is zero on success Example of a call with a non null second parameter Given interfaceHandle as returned by tfAddInterface and the user defined interface notify function devNotifyFunc void devNotifyFunc ttUserInterface interfaceHandle int Js errorcode tfUseBootp interfaceHandle devNotifyFunc Example of a call with a null second parameter If the user does not wish to be notified of tfOpenInterface completion then he can use the predefined NULL function pointer tfUseBootp interfaceHandle TM_DEV_NOTIFY_FUNC_NULL_PTR 7 19 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter interfaceHandle devNotifyFuncPtr Returns Value 0 TM_EINVAL TM EMFILE TM ADDRINUSE 7 20 2004 Treck Incorporated Description The interface handle as returned by tfAddInterface A pointer to a function that will be called upon completion of tfOpenInterface for a BOOTP configuration Meaning Success The interface handle parameter is invalid Not enough sockets to open the BOOTP client UDP socket Another socket is already bound to the BOOTP c
389. ion upon receiving any one of the socket events are described in the tfRegisterSocketCB section Returns Value Meaning 0 Success 1 An error has occurred tfRegisterSocketParamCB will fail if TM_EBADF The socket descriptor is invalid TM EINVAL socketCBFuncPtr is NULL and eventFlags is non zero 5 121 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Treck Initialization Functions tflnitTreckOptions include lt trsocket h gt int tfInitTreckOptions int optionName unsigned long optionValue Function Description This call is used to set various options that are used by the Treck TCP IP stack Note This function should be called only before calling tfStartTreck Parameters Parameter Description optionName The option to change see below optionValue The new value to change it to Note The option names marked with an asterisk can only be set using tfInitTreckOptions All the other options are common with tfSetTreckOptions Option Name Meaning TM OPTION TICK LENGTH The time in Milliseconds between calls to tfTimerUpdate or tfTimerUpdatelsr Cannot be set to 0 DEFAULT in TRSYSTEM H TM OPTION SOCKETS MAX The maximum number of sockets allowed on the system Allowed values are between 1 and Ox7FFF 1 DEFAULT 64 TM OPTION ARP MAX RETRY The maximum number of ARP retries before going into the ARP quiet time state DEFAULT 6 TM OPTION ARP TIMEOUT TIME The amount of time in s
390. ions alive Default 0 Linger on close if data is present Default is on with linger time of 60 seconds Enable disable reception of out of band data in band Default 0 Enable this socket option to bind the same port number to multiple sockets using different local IP addresses Note that to use this socket option you also need to uncomment TM USE REUSEADDR LIST in trsystem h Default 0 disable The low water mark for receiving data The low water mark for sending data Set buffer size for input Default 8192 bytes Set buffer size for output Default 8192 bytes TCP socket fraction use of a receive buffer below which we try and append to a previous receive buffer in the socket receive queue UDP socket fraction use of a receive buffer below which we try and copy to a new receive buffer if there is already at least a buffer in the receive queue This is to avoid keeping large pre allocated receive buffers which the user has not received yet in the socket receive queue Default value is 4 25 5 49 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM SO SNDAPPEND TCP socket only Threshold in bytes of send buffer below which we try and append to previous send buffer in the TCP send queue Only used with send not with tfZeroCopySend This is to try and regroup lots of partially empty small buffers in the TCP send queue waiting to be ACKED by the peer otherwise we
391. iption This function is similar to tfRegisterSocketCB and like tfRegisterSocketCB it is used to register a function call upon completion of one of more socket events It also allows the user to specify a user parameter that will be passed as a parameter to the call back function Function prototype for the user supplied socket call back function void socketCBParamFunc int socketDescriptor void socketUserPtr int eventFlags ke Parameters Parameter Description socketDescriptor The socket descriptor to register the call back for sockettCBFuncPtr The function pointers of the user function to be called when one or more of the registered events occur See below for function prototype socketUserPtr A user pointer that will be passes by the call back function eventFlags One or more of the flags as described in the tfRegisterSocketCB section and OR ed together 5 120 2004 Treck Incorporated Programmer s Reference When one or more of these events occur the Treck stack calls the user supplied call back function socketCBParamFunc socketDescriptor socketUserPtr eventF lags where socketDescriptor is the socket descriptor as given by the user in tfRegisterSocketCBParam socketUserPtr is the user pointer as given by the user in tfRegisterSocketCBParam and eventFlags contain one or more of the events specified by the user that have occurred The action s to be taken by the user in the user supplied call back funct
392. irable especially for TCP because it removes the necessity ofa copy and speeds up performance However supporting scatter send in the driver can be a little more complicated If the flag is being passed in to tfOpenInterface and you are seeing odd behavior try disabling it If you had a memory corruption problem before that now goes away it is a sign that tfSendComplete was being called too frequently It should be called once per packet as opposed to once per buffer Look for memory leaks Break point on memory allocation function after several minutes The Treck stack uses an optimized memory allocation scheme in which it maintains its own memory pool After the system becomes balanced which is usually within 5 minutes of startup the stack should not be requesting any more memory from the system If this is occurring it is a possible sign that memory is being lost within the driver Putting breakpoints on the system memory allocation functions tfKernelMalloc if you are using your operating system s memory allocation procedures tfSheapMalloc if you are using Treck s simple heap after the stack has been running for about five minutes will allow you to identify any suspicious memory allocations Look at send and receive buffer rings Most Ethernet drivers will require the user to set up send and or receive buffer rings Even if not required frequently the use of these buffer rings will speed up performance and is thus very desir
393. is already bound to the BOOTP client UDP port TM IP DEV BOOTP or TM IP DEV DHCP configurations only DHCP or BOOTP request timed out A PPP session is currently closing Call tfOpenInterface again after receving notification that the previous session has ended Error value as returned by the device driver open function 5 169 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfPoolCreate include lt trsocket h gt nt tfPoolCreate numberFullSizeBuffers numberSmallSizeBuffers fullBufferSize smallBufferSize alignment flag UserlInterface interfaceHandle n n n n n n pope ph p b b t ua B 1 Function Description Allocate a ring of pre allocated device driver receive buffers so that the device driver can get a pre allocated buffer from this recv pool during an ISR The user can specify a number of maximum size packets and a number of small size packets For Ethernet device driver the maxim size packet fullBufferSize parameter should be TM ETHER MAX PACKET CRC This function should be called from the device driver open function and the device driver should only get a buffer from this pool during an ISR Note The user must periodically replenish the Treck ISR recv pool as follows errorCode tfloctlInterface interfaceHandle TM DEV IOCTL REFILL POOL FLAG void 0 0 Parameters Parameter Description interfaceHandle Interface handle as given in the first para
394. is between 10ms and 100ms It is not necessary that the timer be VERY accurate between calls to fTimerUpdatelsr but it should be accurate on average over time 4 38 2004 Treck Incorporated Integrating into Your Environment Step 6 Key Things to Start Using Treck Now that you have a library and an idea of how to build your timer interface you are probably wondering how to start using the protocols on your platform You should at this point try to use the loopback support built into the protocol stack This will let you know if there is a problem with the RTOS or the Timer interface There is one call that you MUST make into the protocol stack before you can start using it That function is called StartTreck If you call this function which does not take any parameters it will initialize all the stack parameters to defaults if you do not call InitTreckOptions first If you have not set a tick length value in trsystem h or with tfInitTreckOptions you will get a kernel warning You will get a kernel error if you compile for the wrong byte order of your machine big endian versus little endian The only call that you can make into the protocol stack prior to calling zfStartTreck is tfTnitTreckOptions All of the functions mentioned here could be found in the Programmers Reference section of the manual As we mentioned above you can use the function ffInitTreckOptions to change any of the default parameters used for the stack It i
395. is enabled If zero it is disabled Meaning Success Not enough memory to allocate the empty transmit ring Device Interface already configured opened or User already uses a transmit task or device interface is a point to point interface 1 e PPP or SLIP 5 191 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUselntfDriver include lt trsocket h gt ttUserInterface tfUselntfDriver char namePtr ttUserLinkLayer linkLayerHandle int drvAddErrorPtr Function Description tfUseIntfDriver adds a loop back driver below the link layer and returns an interface handle An example would be as follows ethernetLinkLayerHandle tfUseEthernet mylInterfaceHandle tfUseIntfDriver TESTI etherLinkLayerHandle amp errorCode This function is very useful to debug a link layer When using the loop back driver some macro definitions configurations are necessary to insure that the loop back driver is used and not bypassed for a given destination IP address peer IP address Peer IP address Steps to ensure that the loop back driver is used configured in the stack Define TM LOOP TO DRIVER or Define TM SINGLE INTERFACE HOME not configured in the stack Define TM DEV IP NO CHECKIf the link layer is Ethernet then a proxy arp entry should be added for the peer IP address Parameters Parameter Description namePtr The callers name for the device each call to tfUseIntfDriver mus
396. is non zero then the sequence CR LF gt or CR NUL gt has been received in ASCII mode or lt IAC EOR gt in binary mode The user should copy all the data to their own buffers If there is not enough room the user should return TM EWOULDBLOCK and the telnet server will try to call this routine again later Parameters Parameter Description teldHandle Unique identifier for a telnet connection teldRecvBufPtr Pointer to buffer containing received data teldBytes Number of bytes in the receive buffer eolFlag End of line flag 1 to indicate EOL 0 otherwise Returns Value Meaning TM ENOERROR User had room for the data and copied it in its buffer TM EINVAL Invalid Telnet Handle TM EWOULDBLOCK User did not have enough room for all the data No data has been copied 6 117 Treck Real Time TCP IP User s Manual tfTeldOpened include lt trsocket h gt void tfTeldOpened ttUserTeldHandle teldHandle struct sockaddr_in sockAddrPtr Function description The user provides this function It is called from the telnet server to let the user know that a telnet client has established a new connection to the telnet server Parameters Parameter Description teldHandle Telnet handle Unique identifier for a telnet connection sockAddrPtr Pointer to a sockaddr in structure containing the IP address of the telnet client Returns Nothing 6 118 Application Reference tfTeldSendQueueBytes include lt trsocket h gt int
397. is removed from trsystem h the IP reassembly code is not compiled in If you expect to receive IP fragments you need to keep this macro in trsystem h Otherwise you can remove the TM IP REASSEMBLY macro from system h thereby reducing code size TM IP FRAGMENT NO COPY If you define TM IP FRAGMENT and your device driver supports scattered send then define TM IP FRAGMENT NO COPY to avoid an extra internal data copy when IP datagrams need to be fragmented TM DISABLE PMTU DISC By default the TCP Path MTU Discovery code is compiled in and turned on Adding this macro will prevent the compilation of the TCP Path MTU Discovery code thereby reducing code size TM DISABLE TCP SACK By default the TCP Selective Acknowledgement code is compiled in and turned on Adding this macro will prevent the compilation of the TCP Selective Acknowledgement code thereby reducing code size 4 6 2004 Treck Incorporated Integrating into Your Environment TM_TCP_FACK Define the TM_TCP_FACK macro to enable the Forward Acknowledgement algorithm It an only be enabled if TM DISABLE TCP SACK is not defined Enabling TM_TCP_FACK will allow the TCP Sack to retransmit more than one SACKed segment wireless TCP option only TM_USE_TCP_PACKET Enable this macro if you wish to enable code that modifies TCP behavior and forces TCP to send data on user send packet boundaries Note that this will only enable the code You must also set the TM TCP PACKET o
398. is returned but not consumed so that a subsequent receive operation will see the same data MSG_SCATTERED Non TCP sockets If the receive data is scattered it will be passed to the user as is and will not get copied into a new buffer to make the data contiguous Upon return bufferHandlePtr will point to a scattered buffer as explained below MSG_SCATTERED Description When the MSG SCATTERED bit is set in the flags parameters then upon successful return from tfZeroCopyRecv the bufferHandlePtr parameter should be cast to a pointer to a ttUserPacket structure where ttUserPacket is defined as follows typedef struct tsUserPacket 1 struct tsUserPacket pktuLinkNextPtr tt8BitPtr pktuLinkDataPtr ttPktLen pktuLinkDataLength ttPktLen pktuChainDataLength int pktuLinkExtraCount ttUserPacket ttUserPacket fields Description ptkuLinkNextPtr points to the next ttUserPacket structure pktuLinkDataPtr points to the data in the link pktuLinkDataLength contains the length of that data pktuLinkChainDataLength contains the total length of the scattered data Its value is ony valid in the first link pktuLinkExtraCount Contains the number of extra links besides the first one Its value is only valid in the first link 5 100 2004 Treck Incorporated Programmer s Reference Example The following code extract shows how to navigate a scattered recv buffer and copies it into bufferArray define TM BUF ARRAY
399. isionDetection tfUserStartArpSend BOOTP Automatic Configuration tfConfGetBootEntry tfUseBootp BOOTP relay agent tfStartBootRelayAgent tfStopBootRelayAgent DHCP Automatic Configuration tfConfGetBootEntry tfDhcpConfSet tfUseDhcp DHCP User configured tfDhcpUserGetBootEntry tfDhcpUserRelease tfDhcpUserSet tfDhcpUserStart Dialer tfDialerAddExpectSend tfDialerAddSendExpect tfUseDialer IGMP API drvlIoctlFunc tfSetMcastInterface NAT tfNatConfig tfNatUnConfig tfNatConfigNapt tfNatConfigInnerTcpServer tfNatConfigInnerUdpServer tfNatConfigInnerFtpServer tfNatConfigStatic tfNatConfigDynamic tfNatConfigMaxEntries tfNatDump 2004 Treck Incorporated PPP Interface tfChapRegisterAuthenticate tfGetPppDnsIpAddress tfGetPppPeerlpAddress tfPapRegisterAuthenticate tfPppSetOption tfSetPppPeerlpAddress tfUseAsyncPpp tfUseAsyncServerPpp tfUsePppLqm tfFreePppLqm tfLqmRegisterMonitor tfLqmSendLinkQualityReport tfPppSendEchoRequest tfLqmSetLqrTimerPeriod tfLqmGetLocalLqrTimerPeriod tfLqmGetPeerLqrTimerPeriod tfMsChapRegisterAuthenticate tfMsChapRegisterNewPassword tfEapMdSRegisterAuthenticate tfEapSetOption tfPppSetAuthPriority Optional Protocols AUTO IP Configuration Description The AUTO IP configuration APIs allow the user to configure the interface with an AUTO IP address without having to pick a specific IP address The IP address will automatically be selected in the AUTO IP v4 address range i e IP
400. itialize PPP Link Quality Monitoring LQM and must be called before tfOpenInterface for each distinct PPP interface that the user wants to monitor link quality on After calling tfUsePppLqm but before calling tfOpenInterface the user should call tfPppSetOption to set the TM LCP QUALITY PROTOCOL configuration option otherwise LOM won t be used on the link unless the peer negotiates it After this it is still possible that LOM is not being used on the link because the peer doesn t support it To determine if LOM is being used on the link install a PPP notification function refer to tfUseAsyncPpp When your PPP notifica tion function is called with the flag TM LL LQM UP this indicates that LOM has been enabled on the link When your PPP notification function is called with the flag TM LL LOM DISABLED this indicates that LOM has been disabled on the link Parameters Parameter Description interfaceHandle The PPP interface handle as returned by tfAddInterface IqrReTxPeriodMsec Configures how long in milliseconds we wait for the LQR response to a LQR we sent initiated LOR timer before timing out and retransmitting the LOR This should be chosen to be at least twice the smooth round trip time on the link Setting this parameter to 0 disables the use of a retransmission timer not recommended Returns Value Meaning 0 Success TM_EINVAL The interface handle is invalid TM EOPNOTSUPP Failed initializing PPP LQM 7 117
401. k to turn off Transmit and Receive It can also be used to remove the ISR Most people do not need a close for ethernet since the device typically stays connected It is very useful for PPP devices Example int myDeviceClose ttUserInterface interfaceHandle Turn off Ethernet reception Disable Ethernet transmission Uninstall the ISR handler S return TM DEV OKAY If you had called tfPoolCreate in your deviceOpen function then you will need to call tfPoolDelete in your deviceClose function Example int myDeviceClose ttUserInterface interfaceHandle int errorCode 4 61 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Turn off Ethernet reception Disable Ethernet transmission Uninstall the ISR handler Wy errorCode tfPoolDelete interfaceHandle return errorCode 3 driverloctl This optional routine is used as a pass through routine in the stack in most cases It is normally only called when the user calls ffToctlInterface The flags that are passed to tfloctlInterface are the same as those passed to driverloctl The only exception to this rule is when multicast support is needed In this case the Treck stack calls this function with Treck reserved flags TM DEV SET MCAST LIST to give the list of multicast addresses the Ethernet chip should receive or TM DEV SET ALL MCAST so that the Ethernet chip receives all multicast addresses Normally this routine is used to periodically refr
402. knowledgement protocol By increasing our window size it is possible to eliminate network idle time completely Simply put the sender can transmit packets as fast as the network can transfer them We need to remember that a finely tuned sliding window protocol keeps the network completely saturated with packets The timer is an important part of this protocol By design the sliding window protocol remembers which packets have been acknowledged and keeps a separate timer for each unacknowledged packet Ifa packet is lost the timer expires and the sender retransmits that packet When a sliding window slides it moves past all acknowledged packets On the receiving end the protocol software keeps its own window accepting and acknowledging packets as they arrive Thus the window breaks the packets up into three sets packets to the left of the window that have been successfully transmitted received and acknowledged packets to the right of the window that have not yet been sent and packets that lie in the window that are being transmitted Events at Sender Site Network Messages Events at Receiver Site Send Packet 1 7m Receive Packet 1 Send Packet 2 p Send ACK 1 Receive Packet 2 Send Packet 3 A Send ACK 2 Receive Packet 3 Receive ACK 1 A Send ACK 3 Receive ACK 2 Receive ACK 3 Fig 1 40 Three Packets Transmitted Using a Sliding Window Protocol 1 56 2004 Treck Incorporated Introduction to TCP IP
403. l If the fipUserHandleB parameter is non null then the two server model is used and the first session should be in passive mode and the second session should be in active mode The user needs to call tfFtpTurnPasv passing the fipUserHandleA parameter and the TM FTP PASSIVE MODE ON Parameters Parameter Description ftpUserHandleA The user handle of main FTP session will be operated on fipUserHandleB The user handle of the 2nd FTP session for two FTP server model fromFileNamePtr Pointer to source file name string toFileNamePtr Pointer to destination file name string Treck Real Time TCP IP User s Manual Returns Value TM EWOULDBLOCK TM_EINVAL TM_EACCES TM_ENOTLOGIN TM ENOTCONN TM EOPNOTSUPP TM ENOERROR TM FTP XFERSTART TM FTP FILEOKAY TM FTP DATAOPEN TM FTP XFERABOR TM FTP LOCALERR TM FTP FILENAVAIL TM FTP NAVAIL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP SERVNAVAIL TM FTP NOTLOGIN Meaning The call is non blocking and did not complete Invalid ftpSessionPtr or bad filename Previous command has not finished Command requires user to be loggedin and user is not Command requires connection and user is not connected Command not supported by the user No error Success Data connection already open transfer starting File status okay about to open data connection Can t open data connection Connection trouble closed transfer aborted Requested action abo
404. l is between 10ms and 100ms It is not necessary that the timer be VERY accurate between calls to tf TimerUpdate but it should be accurate on average over time It is usually best to set the timer task to the highest priority of tasks operating with the protocol stack but it is not necessary 4 37 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Method 2 A Timer ISR to Update Timers and Execute from Either a Main Line Loop or a Task In this method you simply update the timers from an ISR routine using the call tfTimerUpdatelsr Note that this is a different call than from the call made at task level tfTimerUpdate This call is designed to be able to be called from an interrupt handler It is not recommended to use this method if you have an RTOS You must NOT call the function ffTimerUpdatelsr before you call the function tfStartTreck In this regard it has the same rules as fTimerUpdate An example of using this method for a main line loop is as follows include trsocket h static int treckStarted 0 void timerIsrHandler void Check to make sure that Treck has started if treckStarted Update the Timers tfTimerUpdatelsr void main void int errCode errCode tfStartTreck treckStarted 1 Other initialization code follows if errCode TM ENOERROR while 1 tfTimerExecute Application code follows Tip A good timer interval
405. l need a minimum RTOS interface which we provide If you decide not to use an RTOS then remember that most of the calls into the Treck Protocol Stack will be done from a main line loop The biggest disadvantage in not using an RTOS is that you cannot make blocking calls i e make recv wait for data otherwise you will stop all processing in your system Another disadvantage is that you cannot prioritize events If you are thinking about this but are still undecided we suggest that you look at using uC OS as your RTOS This is included with the base Treck protocols If you are dead set against using an RTOS then we will help you understand the limitations in the Kernel configuration section of this chapter I have a RTOS Kernel to Interface to but it does not allow any blocking pending calls An example of this would be an event scheduler with all the calls made from a main loop This falls into the I do not have an RTOS Kernel to interface to category I have a RTOS Kernel to Interface to You will need to decide if your RTOS is preemptive or non preemptive If you do not know you can always assume preemptive which is the safest Preemptive RTOS Kernels need to have locking of shared resources TIP A Preemptive operating system is one where a timer tick or other event causes a context switch to a new task Tasks may have different priorities Higher priority tasks may interrupt lower priority tasks A non preemptive operati
406. lLevel OptionName data type TM_PPP_LCP_PROTOCOL TM_LCP_ADDRCONTROL_COMP unsigned char TM_LCP_PROTOCOL_COMP unsigned char TM LCP MAGIC NUMBER unsigned char TM LCP MAX RECV UNIT unsigned short TM LCP ACC unsigned long TM LCP AUTH PROTOCOL unsigned short I LCP TERM RETRY unsigned char TM LCP CONFIG RETRY unsigned char I LCP TIMEOUT unsigned char TM PPP IPCP PROTOCOL TM IPCP COMP PROTOCOL unsigned short TM IPCP VJ SLOTS unsigned char TM IPCP IP ADDRESS unsigned long TM IPCP RETRY unsigned char TM IPCP TIMEOUT unsigned char TM PPP PAP PROTOCOL TM PAP USERNAME char TM PAP PASSWORD char TM PAP RETRY unsigned char PAP TIMEOUT unsigned char TM PPP CHAP PROTOCOL TM CHAP USERNAME char TM CHAP SECRET char TM CHAP RETRY unsigned char TM CHAP TIMEOUT unsigned char TM PPP PROTOCOL PPPSEND BUFFER SIZE unsigned short 7 97 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSetPppPeerlpAddress include lt trsocket h gt int tfSetPppPeerIpAddress ttUserInterface interfaceHandle ttUserlpAddress ifIpAddress Function Description This function is used to set a default remote PPP SLIP IPaddress This IP address will be used as the default remote point to point IP address in case no remote IP address 1s negotiated with PPP see tfPppSetOption or for SLIP If no IP ad dress is set with this function and no IP address is negotiated with the remote PPP for PPP then the local IP address 1 will be u
407. lags This option when enabled is sent in the DHCPREQUEST and DHCPACK messages by both the client and the server The DHCP client sends its domain name to the DHCP server during the exchange and the server acknowledges it if it supports this feature At the end of the DHCP transaction both the client and the server know the client s domain name Flags are used to negotiate which part of the DNS update will be performed by the DHCP server and which part by the DHCP client Treck DHCP client always fully delegates the DNS A and AAAA resource record updates to the DHCP server the DHCP server will update the PTR reverse lookup resource record To use FQDN define TM USE DHCP FQDN in trsystem h and rebuild the Treck stack Your application can then enable the use of FQDN with DHCP client by specifying the TM DHCPF FQDN ENABLE flag when calling the APIs tfDhcpConfSet tfDhcpUserSet and passing the desired domain name in the clientIdPtr and clientIdLength parameters If DHCP FQDN is enabled userBtEntry will also contain the FQDN option related parameters 7 38 2004 Treck Incorporated Optional Protocols The FQDN domain name returned by the server in userBtEntryPtr gt btuServerFqdn its length in userBtEntryPtr gt btuServerFqdnLen DNS error codes RCodel and RCode2 returned by the DHCP server in userBtEntryPtr gt btuFqdnRCodel and userBtEntryPtr gt btuFqdnRCode2 a flags that indicates the FQDN update stat
408. ld still be a class C address However this would denote a different machine Note When an IP address ends in 0 it denotes the physical network or wire For Example 208 229 201 0 1 33 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Netmasks Netmasking allows the grouping together and breaking up of IP address space To illustrate this point lets look at the format of IP addressing in binary 11010000 11100101 11001001 01000010 Fig 1 22 Standard IP Address in Binary 110 10000 11100101 11001001 01000010 Fig 1 23 Class Identifying Digits for an IP Address i e Class A B or C If we were to set up a netmask we would essentially be creating an overlay for an IP address It would look similar to this in binary tt Ee Bs El 11111111 11111111 00000000 Network Host Fig 1 24 Sample Netmask 11010000 11001001 01000010 lillliil 11111111 11111111 00000000 Network Host Fig 1 25 Netmasking Example 1 34 2004 Treck Incorporated Introduction to TCP IP The all s side represents the network side The all 0 s side represents the host side If you were to take this netmask and overlay it on the IP address format like Fig 1 25 you can see that the default line between the network and the host falls between the third and fourth number Note Every machine on a network wire must agree on the value of the net
409. le between IPPORT RESERVEDSTART and the port number to reserve TM_EINVAL Bad parameter pointer is null or port number to reserve is less than IPPORT RESERVEDSTART 600 5 40 2004 Treck Incorporated Programmer s Reference select include lt trsocket h gt int select int numberSockets fd_set readSocketsPtr fd_set writeSocketsPtr fd_set exceptionSocketsPtr struct timeval timeOutPtr Function Description select examines the socket descriptor sets whose addresses are passed in readSocketsPtr writeSocketsPtr and exceptionSocketsPtr to see if any of their socket descriptors are ready for reading are ready for writing or have an exceptional condition pending respectively Out of band data is the only exceptional condition The numberSockets argument specifies the number of socket descriptors to be tested Its value is is the maximum socket descriptor to be tested plus one The socket descriptors from 0 to numberSockets 1 in the socket descriptor sets are examined On return select replaces the given socket descriptor sets with subsets consisting of those socket descriptors that are ready for the requested operation The return value from the call to select is the number of ready socket descriptors The socket descriptor sets are stored as bit fields in arrays of integers The following macros are provided for manipulating such file descriptor sets FD ZERO amp fdset Initializes a socket descript
410. led BUILD BAT and BUILDLIB BAT You do not need to modify this file unless you are removing protocols from the build This file can be called directly from the DOS command line like this C build bel86cc Note Your current directory MUST be the SOURCE directory in order to build the Treck objects Once the build completes and it should without warnings or errors if your paths are set correctly you are ready to create your library like this C gt buildlib bc86lib If you have done everything correctly to this point you should have a library If you get any compile errors please make sure that they are not due to any changes to the TRSYSTEM H file If you still have errors or warnings please contact technical support 4 20 2004 Treck Incorporated Integrating into Your Environment Tier 3 Setting up the Automated Build System There is one final batch file that you can add modify It is the automation that builds the C code into objects and inserts the objects into a library As you can imagine it is fairly simple It calls BUILD BAT to compile first then BUILDLIB BAT to put the objects into a library In our Tier 3 batch files we have them pass an extra define into the build so we don t have to modify TRSYSTEM H We also delete the library before we build to make sure that it is always a clean library Because we support more than one compiler the tier 3 batch files are a little more complex than y
411. lient UDP port Optional Protocols BOOTP relay agent tfStartBootRelayAgent include lt trsocket h gt int tfStartBootRelayAgent ttUserlIpAddress ipAddress ttUserInterface interfaceHandle unsigned char multiHomeIndex General description of a BOOTP relay agent BOOTP and DHCP clients send out limited broadcasts messages to UDP port 67 BOOTP server port in order to get boot configuration from a BOOTP DHCP server Ifthe server is not on the same subnet as the client the broadcast message will not reach the server since routers do not forward limited broadcasts To avoid having a BOOTP DHCP server on every subnet BOOTP relay agents have been designed so that they can receive the limited broadcast message from the BOOTP or DHCP client and send it with some modifications to a BOOTP DHCP server The BOOTP relay agent will also relay the replies from the BOOTP DHCP server back to the client Function Description This function is called to start the BOOTP relay agent to relay both BOOTP and DHCP requests to the specified remote server IP address from the specified interface handle multihome index Parameters Parameter Description ipAddress IP address of the remove server A limited broadcast address can also be specified OXFFFFFFFF interfaceHandle Interface through which to relay BOOTP and DHCP client requests multiHomelIndex Multi home index of the interface through which to relay BOOTP and DHCP client reques
412. lity determination policy and recovery algorithm also since the specific implementation will likely vary significantly depending on the application we have decided not to implement any default link quality determination policy or recovery algorithm but instead we provide a flexible API which enables the user to implement their own Description First before doing anything else if link quality monitoring is desired the user must define TM PPP LQM in trsystem h and then rebuild all of the Treck TCP IP code tfUsePppLqm is called to allocate the LQM state vector Before the link is opened the user calls tfPppSetOption to set the TM LCP QUALITY PROTOCOL configuration option and if the user wants to register a link quality monitoring function then they also negotiate a non zero value for the LQR timer After PPP opens the link PPP calls tfLqmEnable which starts the LOR timer Either before or after PPP opens the link but after the call to tfUsePppLqm the user calls tfLqmRegisterMonitor to register their link quality monitoring function Whenever a LQR is received the user s link quality monitoring function is called and is it passed incoming and outgo ing packet and byte counts derived from information contained in this LOR and also from the previously received LQR and the elapsed time since the this function was last called The user s link quality monitoring function then determines the link quality based on these counts and the delta ti
413. ll not be called DHCP request discover sent with no error DHCP request discover previously sent Bad parameter Not enough memory As returned by device driver send function 7 45 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Dialer Description Treck PPP or SLIP includes a module to facilitate dialing a remote host most likely an ISP Dialing occurs prior to the establishment of a PPP connection and is triggered by calling tfOpenInterface Prior to this call the user would first enable the dialer and then set up how the dialer will behave This is done with a series of send expect pairs where the local client sends a string to the remote host and waits for its response Expect send pairs behave in the opposite manner This is similar to the method used in many UNIX scripted dialers Each send expect or expect send pairs have an error string associated with them When this string is received it triggers an error inside the dialer The default behavior is simply to move to the next state 1 e the next send expect pair If TM DIALER FAIL ON ERROR is set and this error string is received the entire dialing session will be aborted with an error Every send expect pair has a time out value and a retry value associated with it This allows for instance a dialer to attempt to dial a phone number a finite number of times and if it still fails to abort the session
414. ll send data to port 9 of the remote host if an echo test is chosen it will echo data with port 7 The test will be executed the number of times specified in the parameter testCount A random data length is also chosen and is no larger than the data length specified in parameter dataSize Unless IP fragmentation is enabled the data length should be no larger than the MTU of the device less the space for the UDP amp IP headers 1472 for Ethernet as well as most other link layers in case a UDP test is chosen Random options flags are chosen appropriately for the selected test The exception to this is the TM TEST FLAG NONBLOCKING flag which remains set to the value passed in by the user 6 133 Treck Real Time TCP IP User s Manual Locking test This test operates differently than the rest of the test suite due to the way that locks work This test is only run once If locks are working correctly the user will receive a message via tfKernel Warning and if locks fail tfKernelError will be called For this test to operate the macro TM ERROR CHECKING must be defined in your trsystem h file tfTestTreck include lt trsocket h gt int tfTestTreck int testType char ipAddrStr int portNumber int dataSize unsigned long testCount unsigned long flags ttUserTestHandlePtr sessionHandlePtr void testParam Function description Performs a network test according to the specified parameters Not all param et
415. llow the user to loop back application data all the way to the device driver when sending to an interface configured IP address By default this macro is not defined in trsystem h and this causes the Treck TCP IP stack to loop back application data above the link layer when the user is sending to an interface configured IP address This is useful when debugging a device driver or link layer TM_USE_DRV_ONE_SCAT_SEND This macro is commented out by default Define the TM USE DRV ONE SCAT SEND macro if you wish to use a single call to the device driver passing the packet handle even when sending a frame with scattered buffers Note to enable this feature this macro must be added and tfUseInterfaceOneScatSend must be called on the interface that supports it TM_USE_DRV_SCAT_RECV This macro is commented out by default Define the TM USE DRV SCAT RECV macro if you want to allow the device driver recv function to pass back a frame to the stack in scattered buffers Gather Read Note that to enable this feature this macro needs to be added and tfUseInterfaceScatRecv needs to be called on the interface that supports it TM INDRV INLINE SEND RECV This macro is defined by default Undefine delete the TM INDRV INLINE SEND RECV macro to test loop back intra machine driver with a separate recv task In that case the intra machine received data will no longer be processed in the send path but will be processed when tfRecvInterface tfRecvSc
416. long or short listing of the directory or of the directory entries matching the specified pattern tfFSOpenFile Open a file creating it 1f it does not exist for read write or append specifying type ascii or binary structure stream or record tfFSReadFile Read n bytes from a file into a buffer tfFSUserLogin Login a user if password is valid tfFSUserLogout Logout a user tfFSWriteFile Write some bytes from a buffer to a file Note File system calls for the FTP client can be found in the File System Section of this manual FTP Client API Summary tfFtpNewSession tfFtpFreeSession tfFtpClose tfFtpConnect tfFtpLogin tfFtpCwd tfFtpCdup tfFtpQuit tfFtpRein tfFtpType tfFtpRetr tfFtpStor tfFtpAppe tfFtpRename tfFtpAbor tfFtpDele tfFtpRmd tfFtpMkd tfFtpPwd tfFtpDirList tfFtpSyst tfFtpHelp tfFtpMode tfFtpNoop tfFtpPort tfFtpGetReplyText tfFtpUserExecute Application Reference Creates a new FTP session Frees a FTP session Closes a FTP connection used if tfFtpQuit cannot close the connection properly Connects to a remote FTP server Log on and authenticate to a FTP server Changes current remote directory Changes to the current directory s parent directory Ends current FTP connection Resets current FTP connection Sets the current transfer type ASCII or binary Retrieves a file from the remote file system Stores a file on the remote file system Appends a file to a file on
417. lp c Parameters Parameter ipAddress Protocol Returns Value gt 0 TM_SOCKET ERROR Description User IP address to bind the raw socket with Protocol above IP for example IPPROTO_IGMP IPPROTO_ICMP IPPROTO_OSPF Meaning Success Call failed The user can retrieve the error code with the tfGetSocketError TM_SOCKET_ERROR API See below for table of possible error codes 5 85 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfRawSocket will fail if TM_EINVAL TM_EINVAL TM EADDRINUSE 5 86 2004 Treck Incorporated Invalid protocol for raw socket send receive The following protocols are disallowed IPPROTO UDP IPPROTO TCP There is no interface configured with the specified IP address only if ipAddress parameter is not zero A raw socket has already been opened for this protocol Programmer s Reference tfRecvFromTo include lt trsocket h gt int tfRecvFromTo int socketDescriptor Char bufferPtr int bufferLength int flags struct sockaddr fromAddressPtr int addressLengthPtr struct sockaddr toAddressPtr Function Description tfRecvFromTo behaves the same as recvfrom except for the use of the parameter toAddressPointer This parameter specifies the address to which data was sent tfRecvFromTo is used to receive messages from another socket tfRecvFromTo may be used to receive data on a socket whether it is in a connected s
418. mask The values must be identical for the netmask to operate correctly Reserved Addresses In a netmask there are guidelines that must be followed for correct setup with no errors The most important thing to remember is this If the host or network portion of the IP Address after applying the netmask is all 15 or 05 it cannot be assigned as a machine 5 IP address Any combination of numbers that translate into binary as being all s or 0 s also cannot be used Depending on where the netmask is setup the reserved numbers will change For example 192 0 X 128 0 X 127 X X 0 X X Fig 1 26 Reserved Addresses In these examples the network portion of the IP address is 0 except for 127 X X X which is reserved for loopback In the next section we will see how we can change the position of the bits in the network section of the netmask to manipulate our network for our personal needs 1 35 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Sub Netting amp Super Netting Let s look at an example to explain the use of sub netting and super netting Suppose that we have applied for an IP address and we received a class C address In our business we have 20 machines in the shipping department 20 machines in the engineering department and 50 machines in the clerical department We want all those machines to be able to access the network independently based on their departments Inste
419. me A transmission travels along the cable at approximately 80 the speed of light It is possible that two machines can sense that the ether is idle and begin transmitting at the same time When two electrical signals get crossed they become scrambled such that neither is meaningful These incidents are called collisions The Ethernet makes provisions for this happening Each transceiver is constantly monitoring the cable while it is transmitting to see if a foreign signal interferes with its transmission Technically this monitoring is called collision detect When a collision is detected the host interface aborts transmission and then waits for activity to subside and then tries to transmit again Care must be taken however or the network could wind up with all the transceivers busily trying to transmit resulting in collisions This is where the Ethernet excels it uses a binary exponential back off policy where a sender delays a random time after the first collision twice as long if a second collision occurs fours times as long if a third attempt results in a collision and so on The logic behind exponential back off is that in the unlikely event that many stations try to transmit simultaneously a severe traffic jam could occur In such a jam there is a very good chance that two stations will choose very similar back off times resulting in a high chance for another collision By doubling the random delay time the exponential back of
420. me and returns 0 if link quality is good and 1 if it is bad or greater than one to short circuit the hysteresis and cause link recovery to occur sooner These link quality counts are accumulated over multiple calls to the user s link quality monitoring function and if they surpass a specified max failure count within a specified 7 111 2004 Treck Incorporated Treck Real Time TCP IP User s Manual number of times that this function was called then the user is notified that the link is bad via a PPP callback flag after which they should attempt recovery of the link Code Example include lt trsocket h gt Parameters controlling determination of link quality define LOM HYSTERESIS MAX FAILURES 3 define LOM HYSTERESIS SAMPLES 4 Function prototype for link quality monitoring function rd ttUser8Bit myLinkQualityMonitor tUserInterface interfaceHandle nt reasonCode nsigned long timeElapsedMsec LgrCountDeltasPtr countDeltasPtr ConstLqrCountsPtr countsPtr User32Bit outLqrs User32Bit outPackets User32Bit ct ct ct ct tae c outOctets Function prototype for PPP link notification function void myPppLinkNotify ttUserInterface interfaceHandle int flag ttUserInterface interfaceHandle char errorMsgBuf 256 Status flags int lqmEnabledStatus int linkBadStatus int linkQualityMonitorRegisteredStatus int main void
421. ment re assembly timeout value in seconds DEFAULT 64 TM OPTION ICMP ADDR MASK AGENT A boolean to enable disable the TM OPTION UDP CHECKSUM ICMP address mask agent DEFAULT 0 A boolean to enable disable UDP checksums on outgoing packets DEFAULT 1 TM OPTION PMTU DECREASED TTL The length of time in seconds 5 127 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM OPTION PMTU LARGER TTL TM OPTION SEND TRAILER SIZE TM OPTION TIMER MAX EXECUTE TM OPTION RIP SEND MODE TM RIP NONE TM RIP 1 TM RIP 2 TM RIP 2 BROADCAST TM OPTION RIP RECV MODE TM RIP NONE TM RIP 1 TM RIP 2 TM RIP I TM RIP 2 Returns Value 0 TM EINVAL 5 128 2004 Treck Incorporated before a path MTU estimate increase is tried after having received an ICMP Datagram Too Big Message error DEFAULT 600 seconds The length of time in seconds before another path MTU estimate increase is tried after a previous path MTU estimate increase has been successful DEFAULT 1200 seconds Number of bytes of extra space to include at the end of outgoing packets This could be used for instance if the user needs space to copy their own trailer onto outgoing packets DEFAULT 0 The maximum number of timers to process in a single call to tfTimerExecute Default 0 which means that there is no maximum To minimize the latency of the tfTimerExecute call set to 1 Meaning Ignore requests from the TCP
422. mes out The number of consecutive times a connection can time out before it is closed 6 79 Treck Real Time TCP IP User s Manual tfTftpUserExecute include lt trsocket h gt ttUser32Bit tfTftpUserExecute void Function description This function executes the TFTP client s main loop This call is valid only if tfTftpGet or tfTftpPut has been called in non blocking mode and tfTftpUserExecute is not currently executing Parameters None Returns Value Meaning gt 0 tfTftpGet transfer was successful This value is the size of the file received TM_TFTP_SUCCESS TM_TFTP_EXECUT tfTftpPut transfer was successful This value is returned while the transfer is in progress TM TFTP TIMEOUT TM TFTP EBUF TM TFTP ESOCK TM TFTP ERROR TM TFTP UNDEF TM TFTP NOTFOUND TM TFTP NOUSER TM TFTP BADOP TM TFTP BADID A TFTP operation timed out Insufficient memory A socket error occurred General TFTP error The TFTP server returned an Undefined error code message in the error packet The TFTP server returned a File not found message in the error packet The TFTP server returned a No such user message in the error packet The TFTP server returned an Illegal TFTP operation message in the error packet The TFTP server returned an Unknown transfer ID message in the error packet TM_TFTP_ACCESS TM_TFTP_NOSPACE TM_TFTP_FILEEXISTS Application Reference The TFTP serv
423. meter of the driver open function or as returned by tfAddInterface numberFullSizeBuffers Number of full size buffers to pre allocate in the ring numberSmallSizeBuffers Number of small size buffers to pre allocate in the ring fullBufferSize Maximum buffer size TM_ETHER MAX PACKET CRC for Ethernet smallBufferSize Small buffer size for example 128 bytes alignment Specify data pointer alignment for pre allocated receive buffers 5 170 2004 Treck Incorporated flag Returns Value TM_EINVAL TM EPERM TM EALREADY TM ENOBUFS Programmer s Reference Indicates whether buffers should be re allocated in line when the tfPoolReceive function is called in the context of the recv task 0 means no in line reallocation TM POOL REFILL IN LINE means in line reallocation Meaning numberFullSizeBuffers parameter is less or equal to zero or fullBufferSize parameter is less or equal to zero or fullBufferSize is less than TM ETHER MAX PACKET CRC on Ethernet or numberSmallSizeBuffers is negative or smallBufferSize is negative or smallBufferSize is zero and numberSmallSizeBuffers is not Zero or alignment is negative or alignment is bigger than 64 or flag is neither 0 nor TM POOL REFILL IN LINE Function not called from driver device open Pool already created on that interface Not enough memory to allocate the recv pool 5 171 2004 Treck Incorporated Treck Real Time TCP IP User s Man
424. meters Parameter Description teldHandle Telnet handle Unique identifier for a telnet connection teldSendBufPtr Pointer to user send buffer containing the data 6 123 Treck Real Time TCP IP User s Manual teldBytes flag 6 124 Number of bytes in teldSendBuf to be sent Flag TM TELD SEND _ EOL to indicate that an EOL should be sent TM TELD SEND COMMAND to indicate that the user is sending a Telnet IAC command and not data Returns Value TM_ENOERROR TM_ENOBUFS TM EINVAL TM EWOULDBLOCK Application Reference Meaning Success Failed to allocate a buffer to copy the send data into Invalid Telnet Handle User did not have enough room for all the data 6 125 Treck Real Time TCP IP User s Manual tfTeldUserStart include lt trsocket h gt int tfTeldUserStart int telnetOptionsAllowed int maxConnections int maxBackLog int blockingState Function description This function opens a TELNET server socket and start listening for incoming connections tf TeldUserStart can be either blocking or non blocking as specified by its blockingState parameter Blocking Mode In blocking mode tfTeldUserStart is to be called from a task tfTeldUserStart will not return unless an error occurs It will block and wait for incoming connections and execute the telnet server code in the context of the calling task Choose the blocking mode if you are using an RTOS Kernel Non Blocking Mode In
425. minated string The output will never be longer than 16 bytes Returns Nothing 5 82 2004 Treck Incorporated Programmer s Reference tflpScatteredSend include lt trsocket h gt int tflpScatteredSend ttUserInterface interfaceHandle ttUserBlockPtr userBlockPtr int userBlockCount ttUserFreeFuncPtr userFreeFunctionPtr Function Description This function allows the user to send an IP datagram directly to the stack without using a socket interface without the Treck stack changing any IP header field except if IP fragmentation is needed and directly from user owned scattered data buffers Even the IP header itself could be scattered among several data buffers The user passes a pointer to an array of user block data of type ttUserBlock and the number of elements in the array Each ttUserBlock element contains a pointer to a user buffer a pointer to the beginning of the user data in the user buffer and the user data length in the user buffer Upon return from this routine the user can reuse the ttUserBlock array but the Treck stack owns the user buffers that were pointed to by the ttUserBlock elements The userFreeFunction will be called by the Treck stack for each user buffer when the data has been sent out on the network and the device driver no longer needs to access the data in the user buffer An example of tfIpScatteredSend usage is shown in the loop back test module txscatlp c If the user uses a preempti
426. mitInterface function from the Treck user transmit task to send the next packet in the device send queue to the device driver The device driver send is only called by fXmitInterface and thereby in the context of the Treck user transmit task The user will call tfInterfaceSpinLock from his device driver send in a loop while waiting for the device to be ready to transmit the buffer that the Treck stack wishes to send ffInterfaceSpinLock will release the Treck device driver lock and yield the CPU allowing other tasks to run and allowing for example the recv task to get the Treck device driver lock and therefore allowing the recy task to access the device driver recv routine Note that tfInterfaceSpinLock can only be called from the device driver send and only when a transmit task is used An example of using these calls to transmit packets from a separate task is as follows ttUserInterface myInterfaceHandle void main void int errorCode short optionValue errorCode tfStartTreck treckStarted 1 Other main processing like adding an interface if errorCode TM_ENOERROR optionValue 1 turn option on errorCode tfInterfaceSetOptions myInterfaceHandle TM_DEV_OPTIONS_XMIT_TASK amp optionValue sizeof short Start a timer task Start the receive task for my interface handle Start the transmit task for my interface handle Other main processing like opening the inter
427. mmer s Reference listen include lt trsocket h gt int listen int socketDescriptor int backLog Function Description To accept connections a socket is first created with socket a backlog for incoming connections is specified with listen and then the connections are accepted with accept The listen call applies only to sockets of type SOCK STREAM The backLog parameter defines the maximum length the queue of pending connections may grow to If a connection request arrives with the queue full and the underlying protocol supports retransmission the connection request may be ignored so that retries may succeed For AF INET sockets the TCP will retry the connection If the backlog is not cleared by the time the TCP times out connect will fail with TM ETIMEDOUT Parameters Parameter Description socketDescriptor The socket descriptor to listen on backlog The maximum number of outstanding connections allowed on the socket Returns Value Meaning 0 Success 1 An error occurred listen can fail for the following reason TM_EADDRINUSE The address is currently used by another socket TM EBADF The socket descriptor is invalid TM EOPNOTSUPP The socket is not of a type that supports the operation listen 5 29 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ntohl include lt trsocket h gt unsigned long ntohl unsigned long longValue Function Description This function converts a long
428. mply call ajsmcre This creates a counting semaphore Be sure to initialize to zero All counting semaphores that Treck uses must be initialized to zero To pend on a counting semaphore we simply call ajsmwat with a semaphore that was created B 6 2004 Treck Incorporated RTOS Notes To post on a counting semaphore we simply call ajsmsig with a semaphore that was created tfKernelTaskYield does not need to do anything with AMX 86 because AMX 86 is fully preemptive and every task has a unique priority This function should just be a stub function ISR Interface AMX 86 has a method to install ISRs in AMX 86 these are called Interrupt Ser vice Procedures ISP Since we normally use C code for the ISR code we need to setup our tfKernelInstallIsrHandler to call ajispm to create a wrapper ISP that will call our C function Then we call ajivtw to write the address of the wrapper that calls our C code to the interrupt vector table With AM X 86 it is okay to post on a counting semaphore from an ISR the func tions tfKernelCreateEvent tfKernelPendEvent and tfKernelPostEvent use uC OS counting semaphores You can use the same code as you used in tfKernelCreateCountSem tfKernelPendCountSem and tfKernelPostCountSem Hooking up the Timer The best way to hook a timer to Treck from AM X 86 is to create a separate timer task This task simply calls tfTimerUpdate tfTimerExecute then ajwatm The ajwatm takes as it parameter the
429. n myDeviceClose Send Function myDeviceSend Receive Function myDeviceReceive Free a Receive Buffer Function myDeviceFreeReceiveBuffer IOCTL Function myDeviceloctl Get Physical Address Function myDeviceGetPhysicalAddress INT to store error if one is returned amp errorCode Now open configure the device errorCode tfOpenInterface The handle from tfAddInterface myInterfaceHandle Our IP Address inet addr 192 1 1 2 Out Netmask Super or subnet inet addr 255 255 255 0 Special Flags Enable Scatter Send TM SCATTER SEND ENB Max buffers per frame 5 3 4 74 2004 Treck Incorporated Integrating into Your Environment tfAddInterface Notes For any functions that you did not implement for your device driver because they were not needed you can pass a NULL pointer into ffAddInterface instead of having a stub routine tfOpenInterface Notes Note tf ConfigInterface has been deprecated Please use tfOpenInterface tfConfigInterface will still function in your code and may be used to configure additional IP addresses on the same interface multi homing Scattered send Note that the flag TM SCATTER SEND ENB is used to inform the protocol stack that the device can support Scatter Send If we support scatter send we have to tell the stack what is the maximum number of pieces that the driver can handle in scatter send mode If you do not use Scatter Send
430. n This function executes the FTP client main loop Call valid only if tfFtpNewSession had been called in non blocking mode and tfFtpUserExecute is not currently executing Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM ENOERROR The current command has success fully completed TM EWOULDBLOCK The current command has not yet completed and tfFtpUserExecute should be called again TM_EINVAL Invalid FTP handle TM_EACCES Blocking is currently on This function should only be called when blocking is disabled 6 66 Application Reference FTP Passive Mode Description FTP passive mode is fully supported in the new release The user may use it in both one server and two server passive models Operation in two server passive model is illustrated here C User FTP onitro User PI C Control Server FTP Data Connection Server FTP mn Rp MAN P Port A Port B m User PI Server A User PI Server B C gt A Connect C gt B Connect C gt A PASV A gt C 227 Entering Passive Mode A1 A2 A3 A4 a1 a2 C gt B PORT A1 A2 A3 A4 a1 a2 B gt C 200 Okay C gt A STOR C gt B RETR B gt A Connect to HOST A PORT a Operation in one server mode is illustrated here Control User PI m 9 Server PI User FTP Server FTP C Le Data Connection gt A C gt A Connect C gt A PASV A gt
431. n Returns Return Meaning None 7 73 2004 Treck Incorporated Treck Real Time TCP IP User s Manual PPP Interface Introduction to PPP The Point to Point Protocol usually referred to as PPP is a low level protocol that performs two basic functions It establishes a link between two peers and it maintains that link This protocol communicates through the hardware layer to the PPP layer on a peer system Because communication takes place between two machines that have the same authority in the negotiation process neither system can be considered a client or a server Let s examine how PPP creates a link and communicates between two ma chines Communication is established in essentially three phases Link Control Protocol LCP Negotiates options and establishes the link between two systems Authentication This takes place after LCP option negotiation It is a request for a peer machine to identify itself with some form of password scheme We will discuss some of these methods later in this document While authentication is optional it is widely used with ISP s and other dial ins that require secure logins Network Control Protocol NCP Configures upper level protocols to operate over PPP For example our imple mentation of PPP uses IPCP Internet Protocol Control Protocol PPP Negotiation The first phase LCP is responsible for negotiating various options that will be enabled disabled or given specific values d
432. n OBI RIS OF re 5 181 tfUnConftipInterface eiie aee Eee eeece eret etep te tere PEE RE dese evel 5 183 tfUseInterfaceOneScatSend sssssssssssseseeeeeeeerennennnes 5 184 Use Interlace Scat ReCV 15e eerte er t D ce Y ones 5 186 tfUseInterfaceXmitQueue sis 5 190 Use MD IVETE su rentes ERE r EVE RU EE WERE mirent 5 192 tfUseScatIntfDriver sssssssesssessseeeeeeneennr enne enne enne 5 194 tt WaitRecelyelnterfaee a iu rii eie er E PTT P YET ER 5 196 tfWaitSentInterface ccc cccceescessecessecssesssceseecesascseeecseeeesaeseecesseseeeeeses 5 197 amp EWarLX mit Interface eee ra pet e Needs ERE TE RSHEEHAR 5 198 tfXmitInterface in 5 199 Ethernet Link Layer API 4 eese esent enne tn nennt nnt nsns 5 200 tfGetEthernetBuffer esssssssssessseseseeeee ener nnne 5 200 tb Se ETHeTNeL nee naine den RUNI 5 201 Null Link Layer APL cssccscicissssssssscesscovesconsssseassevscvsnsssacsseacoasvasencssaneseasesses 5 202 tfUseNullLikl Ayet vic mme ciate te ete een 5 202 SLIP Link Layer AR scvvsssieccssnscevsecssasiccvostssseecessestesvoresasteveuavenescevsantsa ses 5 203 tfGetShpPeerIpAcddress antenne 5 203 S LSLIDP CTIPAdAT SS RU ter o He PERLE es e PREIS 5 204 tfSlipSetOptiOnS iieri teret annee ee ener aie ees 5 205 APSO Specie esse eu eed tuU e ERREUR 5 207 ARP Ro ting Table APE en ese reet en retraso pee oes eee aene nhe eror Ee epa sus 5 208 2004 Treck Incorporated t
433. n fail for the following reason TM_ EBADF The socket descriptor is invalid 5 80 2004 Treck Incorporated Programmer s Reference tfGetZeroCopyBuffer include lt trsocket h gt ttUserMessage tfGetZeroCopyBuffer int size char ww dataPtrPtr Function Description This function 1s used to get a Zero Copy Buffer This buffer can then be used with tfZeroCopySend and tfZeroCopySendTo for zero copy send functions This is a TRUE zero copy if the device driver supports DMA sending Parameters Parameter Description size The size of the buffer to be used for the zero copy dataPtrPtr Pointer to a pointer that is the beginning of the user s data area This is where the user can store the data to be sent Returns The Zero Copy buffer or ttUserMessage 0 if not successful tfGetZeroCopyBuffer will fail for the following reason There was insufficient user memory availbale to complete the operation 5 81 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tflnetToAscii include lt trsocket h gt void tfInetToAscii unsigned long ipAddress char outputBuffer Function Description This function is used to convert an IP address to the dotted string notation Parameters Parameter Description ipAddress The IP address to convert outputBuffer A character buffer to store the result into It is the caller s responsibility to ensure that there is ample room in the buffer for the null ter
434. n that will free a receive buffer OPTIONAL A function pointer to an IOCTL routine This function is called by tfloctlInterface A function pointer to the device driver that will return the physical address for the device A pointer to an int that will contain an error if one occurred 5 131 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The following table is a list of the prototypes for the device driver functions int drvOpenFunc ttUserInterfac interfaceHandle int drvCloseFunc ttUserInterface interfaceHandle int drvSendFunc ttUserInterfac interfaceHandle char dataPtr int dataLength int flag int drvRecvFunc ttUserInterface interfaceHandle char TM FAR dataPtr int TM FAR dataLength ttUserBufferPtr userBufferHandlePtr int drvFreeRecvFunc ttUserInterface interfaceHandle char dataPtr int drvlIoctlFunc ttUserInterface interfaceHandle int flag void optionPtr int optionLen int drvGetPhysAddrFunc ttUserInterface interfaceHandle char physicalAddress Returns An Interface Handle or a NULL handle when an error occurs If an error occurs the error is stored in drvAddError Ptr ErrorCode Description TM BINVAL One of the parameters is invalid TM EALREADY Device has already been added TM ENOBUFS Not enough buffers to allocate a device entry 5 132 2004 Treck Incorporated Programmer s Reference tfAddinterfaceMhomeAdd
435. n tightly coupling the hardware interface with addressing the stack model identifies a separate interface through which these functions shall cooperate Figure 1 1 shows a sample of an OSI architecture model The lower levels of the stack consist of independent protocols that support specific hardware interfaces transport mechanisms and so forth while the higher layer protocols are interfaces into the user application code Application Presentation Session Transmission Network Data Link Physical PNW RAAN Fig 1 1 The OSI Architecture Model Figure 1 2 shows the TCP IP model We have mapped some of the protocols in use with TCP IP into the OSI reference model Note that BSD Sockets is at the session layer BSD Sockets is not a protocol It is a user API to allow access to the protocol stack beneath 7 Application Your Application and or Treck Applications 6 Presentation Host Network Byte Order Conversion 4 Transmission 3 Network 2 Data Link Ethernet 1 Physical Your Network Hardware Fig 1 2 The TCP IP Model 1 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The TCP IP stack layers perform the following functions Media Access Physical Protocols Specify the mechanisms for client and server nodes on a network to interface to the transmission media Data Link Protocols Specify the control characters and the lowest level mechanisms for transmitting packets of data in successive
436. n with FIFO order A 8 UfKernelTaskPend Event ss AG URernellaskPOstH vent sertie li rtilennsiai exci A 10 Running multiple instances of Treck ss A 11 Context insensitive functions accetti diese one rie icd A ll 2004 Treck Incorporated Initialization Sequence esie terree eoe beer cerek etes A 12 Summary of new context APIs A 12 Enabling the Multiple Instances code in Treck sssss A 13 Blocking mode non blocking mode ssssssssss A 13 No Kernel 55e A 13 Non preemptive kertiel tuse re rte er Or Pep rt dde A 14 Preemptive Kernel essentiel A 14 Device Driver Modif Cation sixes restreinte A 15 Device driver TSR iue aee oet petu Deiode pe be key Ree Fo HELP RRes pad A 15 tnit l reckMultipleCOntext eerie tr ert ert tees A 16 tiCreate TreckC htext i eire tecto terere nier A 17 tiSetCurrentCOntext c s d encens sienne A 18 pigri Oro ER A 19 Appendix B RTOS Notes c cccsccsessccosnseccessseseasezesseassttceeeosee Bul RTOS Application Note for uC OS cscsesssesssesseseesssecsscsesessesseesseeseers B 3 Predefined Settings in TRSYSTEM H eene B 3 ITA GV Ath ol n AE ee eine A A dede ere het B 3 Critical Section Handling eccentric eter teretes B 4 Error Logging and Warning Information Logging eeess B 4 Task Suspend and Resume conos pb d ESER PA Re B 4 BS RM AS
437. nable disable routing bypass for outgoing messages Default 0 5 13 2004 Treck Incorporated Treck Real Time TCP IP User s Manual SO ERROR SO KEEPALIVE SO OOBINLINE SO REUSEADDR SO RCVLOWAT SO SNDLOWAT SO RCVBUF SO SNDBUF 5 14 2004 Treck Incorporated When an error occurs on a socket the Treck stack internally sets the error code on the socket It is called the pending error for the socket If the user had called select for either readability or writability select returns with either or both condi tions set If the user had registered a call back function with the TM CB SOCKET ERROR flag the user would be notified In both cases the user can then retrieve the pending socket error by calling getsockopt with this option name at the SOL SOCKET level and the Treck stack will reset the internal socket error Alternatively if the user is waiting for incoming data read or other recv APIs can be called If there is no data queued to the socket the read recv call returns TM SOCKET ERROR the Treck stack resets the internal socket error and the pending socket error can be returned if the user calls tfGetSocketError equiva lent of errno Note that the SO ERROR option is useful when the user uses connect in non blocking mode and select Enable disable keep connections alive Default 0 disable Enable disable reception of out of band data in band Default is 0 Enable this socket option to bind th
438. name okay need password Need account for login Bad sequence of commands 6 47 Treck Real Time TCP IP User s Manual tfFtpMkd include lt trsocket h gt int tfFtpMkd ttUserFtpHandle ftpSessionPtr char directoryPathNamePtr char bufferPtr int bufferSize Function description This Function creates directory on remote file system Parameters Parameter fipSessionPtr directoryPathNamePtr bufferPtr bufferSize Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM ENOTLOGIN TM EINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP FILENAME TM FTP NOTLOGIN 6 48 Description FTP session handle Path of directory to create Pointer to buffer to receive result from MKD command Size of above result buffer Meaning Success This FTP session is non blocking and the call did not complete Previous command did not complete The user is not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecognized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Request action not taken file name not allowed Not logged in tfFtpNewSession include lt trsocket h gt ttUserFtpHandle int int char char Function description Application Reference tfFtpNewSession
439. nce number in turn must be used in future calls bind This call allows a user to associate a socket with a particular local port and IP address In the case of a server see listen and accept below it allows the user to specify which port and IP address incoming connections must be addressed to For outgoing connection requests see connect below it allows the user to specify which port the connection will come from when viewed by the other host Note bind is unnecessary for sockets that are not going to be set up to accept incoming connections In this case the stack will pick an appropriate IP address and a random port known as an ethereal port listen This function prepares the given socket to accept incoming TCP requests It must be called before accept accept This function detects incoming connection requests on the listening socket In blocking mode this call will cause a task to sleep until a connection request is received In non blocking mode this call will return TM EWOULDBLOCK indicating that no connection request is present and that accept must be called again If the user calls accept and a connection request is pending accept creates another socket based on the properties of the listening socket If the call is successful the socket descriptor of the newly created and connected socket is returned The new socket is created to allow communications with multiple clients from a single port on the server think of web se
440. nction adds a send expect pair to the dialer local peer sends a string and waits for the remote peer to respond When the dialer reaches this phase it will send sendString to the remote peer and waits for its response If this response matches expectString the dialer successfully moves to the next state However if the received string matches errorString the dialer will abort this phase and if TM DIALER FAIL ON ERROR is set in flags the entire dialing session will be aborted with an error After sending sendString the dialer will wait for a time equal to timeout in seconds If the number of retries specified by numRetries has not been ex hausted when this time elapses the dialer will resend sendString and repeat this process When the retry limit has been reached the dialer will abort the session and return with an error 7 49 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter interfaceHandle sendString expectString errorString numRetries timeout flags Returns Value TM ENOERROR TM BINVAL TM _EINVAL TM BINVAL TM ENOMEM 7 50 2004 Treck Incorporated Description Interface handle used in previous call to tfUseDialer this specifies the device to dial upon String to send when the expectString is received from the peer String to send to peer immediately String that 1f received from the peer indicates an error Number of times to retry sending sen
441. nction gives back a driver buffer which is not a Treck buffer then the Treck stack won t know the block allocation size In that case the Treck stack will assume that the block allocation size is the same as the data size and no copy will take place unless the user changes the default ratio to 1 The user can change this ratio using the per socket setsockopt function For example to change the ratio to 2 int optionValue optionValue 2 errorCode setsockopt socketDescriptor SOL SOCKET TM SO RCVCOPY amp optionValue sizeof int 4 50 2004 Treck Incorporated Integrating into Your Environment 2 Copy inside tfRecvInterface before processing the data disallowed for PPP or SLIP interfaces The user can set an interface option so that the device driver buffer can get copied into a new buffer if the device driver buffer data size is below a configurable threshold To set that option to 64 bytes for example short optionValue optionValue 64 Copy only if size is below or at 64 bytes errorCode tfInterfaceSetOptions myInterfaceHandle TM_DEV_OPTIONS_RECV_COPY amp optionValue sizeof short Note This option is not allowed on a PPP or SLIP interface since PPP or SLIP will copy the buffer into a new buffer while processing the incoming data So there is no need to copy the data an extra time tfInterfaceSetOptions tfCheckXmitInterface tfWaitXmitInterface tfXmitInterface and tfInterfaceSpinL
442. nd echoes it back to the client TM TEST TCP CONNECT Repeatedly connects and then discon nects from a TCP server Miscellaneous Tests TM TEST LOCK Verify that the Treck locking mechanism are set up and are functioning properly The behavior of these tests is modified by various flags TM TEST FLAG ZEROCOPY Send and receive data using the Treck Zero copy extensions rather than the standard sockets calls eg tfZeroCopySend rather than send TM TEST FLAG NONBLOCKING Causes the test suite to run in non blocking mode This should be used if no kernel is available on your system TM TEST FLAG UDP CONNECT Rather than using the standard UDP sendto recvfrom API call connect and use the TCP calls eg send recv 6 130 TM TEST FLAG UDP CS OFF TM TEST FLAG TCP NODELAY TM TEST FLAG FILL DATA TM TEST FLAG VALIDATE TM TEST FLAG RANDOM Application Reference Disable UDP checksums Checksums are enabled by default Sets the TCP NO DELAY option for this test This causes TCP to send data immediately rather than delaying until more data is sent This flag causes all outgoing data to be set to a repeating incremental pattern 0x00 0x01 etc before being sent Verify that all incoming data is as expected ie as TM TEST FLAG FILL DATA sets it see above Choose random values for various parameters 6 131 Treck Real Time TCP IP User s Manual Blocking Mode The Treck t
443. ndEvent Parameters Parameter Description eventPtr Pointer to the event flag upon which this function must pend Returns Nothing A 6 2004 Treck Incorporated Configuration Notes tfKernelTaskPostEvent void tfKernelTaskPostEvent ttUserGenericUnionPtr eventPtr Function Description The user must write this function to make use of their specific operating system This function resumes tasks that were waiting on the event pointed to by eventPtr This should be similar to tfKernellsrPostEvent with one major difference tfKernellsrPostEvent is called from within an ISR whereas tfKernelTaskPostEvent is called from a task Most operating systems have different calls when posting occurs from an ISR or from a task Parameters Parameter Description eventPtr Pointer to the event flag to which this function must post Returns Nothing A 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Counting Semaphore Implementation with FIFO order The user must call the following function The user must call tfTaskInit prior to calling tfStartTreck and prior to launching any task that utilizes the Treck task The user must define the following macro TM NUMEVT This is the number of events needed by the Treck stack This number should match the number of tasks making calls to the Treck stack Default 12 A 8 2004 Treck Incorporated Configuration Notes The user must define the following function
444. ndex is not configured Programmer s Reference tflnterfaceGetVirtualChannel int tflnterfaceGetVirtualChannel ttUserInterface interfaceHandle ttUser32Bit virtualChannelPtr Function Description tfInterfaceGetVirtualChannel is called by the user in the send path from the driver send routine to get the ATM virtual channel associated with the interface and multi home the data is sent from Note this function should only be called from the device driver send function Parameters Parameter Description interfaceHandle The interface handle as returned by tfAddInterface and passed to the device driver send function virtualChannelPtr Pointer to a 32 bit variable where the virtual channel will be stored if the call is successful Returns Value Meaning TM ENOERROR Success TM EINVAL Invalid interface handle or inter face handle does not match the interface handle of the packet currently being sent TM ENOENT Empty device send queue Note Also see tfInterfaceSetVirtual Channel 5 153 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfinterfaceSetOptions include lt trsocket h gt int tfinterfaceSetOptions ttUserInterface interfaceHandle int optionName void TM FAR optionValuePtr int optionLength Function Description Configure interface options optionValuePtr points to a variable oftype as described below OptionLenth contains the size of that variable Options
445. nect aei tere mines aee ere eeu dee hee 6 38 AE Rin 01 ON MEER 6 39 HP Gp DO M 6 40 2004 Treck Incorporated duro Brig E 6 41 L PIDET SESSIONS ends E eor tes EIE 6 43 tiPtpGetReply Text nere tin Nas un cere 6 44 thE CEG OM A 6 45 nigro Bora PI E M M 6 47 jai sonis EMEN 6 48 t FtpNewWSeSSIOL cai sits dessa ovens sre tet Deere db Mean ah cents 6 49 pigro 6 50 pig C 6 51 EIDPWd eco ge PE PE E M ELE 6 52 thE Cp Quit A iss nie aden nets sie ies en nea idem ede 6 53 EME RGU oi ve PE En UT 6 54 dsl SIM E 6 55 PDROIE segs en IM EE 6 57 pisano 6 59 pini EE 6 60 tHE CP SY e TH 6 63 CRD TOTP ASV oss Sac EE ERES 6 64 thE Opp Tey PC een E E terere erede treni ee ep eee sia eds e Bede ones eens 6 65 PED SELE XCCULS screen Here elo peri tpe eost s 6 66 FTP Passive Mode eee eee eese e eee eene eese en sistens tentia stessa sensn seinen 6 67 Ib rnnt ere ee er T EE ye ree 6 67 EXAMS ec een E rite tendent 6 68 TFTP Client Application Program Interface ss 6 71 User Interface sssnsnnnnniananimhmannusmaine 6 71 dio MEET 6 72 tETfCp itane cient eere Fen RED eerte aoa uie Werte e eee epe dud 6 75 CHU AUR UU EUER RN 6 76 dne TS ne ro E 6 79 te Mt WSELE Greiz REC ES 6 80 TFTPD Application Program Interface eerte enenne 6 82 Db vat 6 82 User Interfaces
446. nection requires an AUI connection When using a thin Ethernet setup the connection requires a BNC connector and when using a 0Base T connection an RJ 45 connector must be used The connectors resemble a modular telephone plug Many Ethernet manufacturers provide the option for the user to select which one of the three they want to use Although only one connector can be used at a time this allows the user to integrate easily between the three options 1 10 2004 Treck Incorporated Introduction to TCP IP Note that pair 1 and 2 and pairs 3 and 6 are twisted This is done for noise cancellation Pin 1 Outgoing Data 1 Pin 2 Outgoing Data 2 Pin 3 Incoming Data 1 Pin 4 No connection Pin 5 No connection Pin 6 Incoming Data 2 Pin 7 No connection Pin 8 No connection Fig 1 6 Pin Assignment of an RJ 45 Connector Properties of an Ethernet The Ethernet is a 10 Mbps broadcast bus technology with best effort delivery semantics and distributed access control It is a bus because all stations share a single communication channel However it is also a broadcast system because all transceivers receive every transmission It is important to know that all transceivers do not distinguish among transmissions A transceiver passes all packets from the cable to the host interface The host interface then chooses which packets the computer should receive and filters out all others It is called a best effort delivery syst
447. ned by tfFSUserLogin this function changes the user s working directory to its parent directory Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin Returns Value Meaning 0 Success 1 Failure 6 91 Treck Real Time TCP IP User s Manual tfF SCloseDir include lt trsocket h gt void tfFSCloseDir void userDataPtr void dirDataPtr Function description Given a unique user data pointer as returned by tfFSUserLogin and a directory data pointer as returned by tfFSOpenDir this function closes the directory and frees the directory data structure pointed to by dirDataPtr Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin dirDataPtr Pointer to newly allocated directory data structure Returns Nothing 6 92 Application Reference tfFSCloseFile include lt trsocket h gt int tfFSCloseFile void userDataPtr void fileDataPtr Function description Given a unique user data pointer as returned by tfFSUserLogin and a file data pointer as returned by tfFSOpenFile this function closes the file and frees the file data structure pointed to by fileDataPtr Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin fileDataPtr Pointer to file data structure as returned by tfFSOpenFile Returns Value Meaning 0 Success 1 Failure 6 93 Treck
448. nelWarning main errorMsgBuf if linkBadStatus 1 linkBadStatus 0 perform custom link recovery processing other stuff void myPppLinkNotify ttUserInterface interfaceHandle int flag switch flag case TM LL LOM LINK BAD linkBadStatus 1 break case TM LL LOM UP lqmEnabledStatus 1 break case TM_LL_LOM_DISABLED lqmEnabledStatus 0 break El other stuff ttUser8Bit myLinkQualityMonitor tUserInterface interfaceHandle nt reasonCode nsigned long timeElapsedMsec tLqrCountDeltasPtr countDeltasPtr E S rc ConstLqrCountsPtr countsPtr ser32Bit outLqgrs ser32Bit outPackets tUser32Bit outOctets U U ET ET CT er C 7 114 2004 Treck Incorporated Optional Protocols int linkQuality int outboundLqrsInPipeline linkQuality 0 switch reasonCode case TM LOM MONITOR LOR calculate link quality of the outgoing link if countDeltasPtr deltaLastOutPackets gt countDeltasPtr deltaPeerInPackets countDeltasPtr deltaPeerInDiscards linkQuality countDeltasPtr gt deltaLastOutPackets countDeltasPtr gt deltaPeerInPackets countDeltasPtr deltaPeerInDiscards calculate link quality of the incoming link if countDeltasPtr gt deltaPeerOutPackets gt countDeltasPtr deltaSaveInPackets linkQuality countDeltasPtr gt deltaPeerOutPackets countDeltasPtr deltaSaveInPa
449. ng for an IP address match on the incoming interface 5 141 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value Meaning 0 Success TM EADDRNOTAVAIL Attempt to configure the device with a broadcast address TM EINPROGRESS tfConfigInterface call has not completed This error will be returned for a DHCP or BOOTP configuration for example TM ENOBUFS Not enough memory to complete operation TM BINVAL Bad parameter or first configuration should be for multihome index 0 Note that a zero IP address is allowed for Ethernet if the BOOTP DHCP or USER BOOT flag is on or for PPP otherwise a TM EINVAL errorCode is returned TM EALREADY A previous call to tfConfigInterface has not yet completed TM EPERM User attempted to configure an IP address via DHCP respectively BOOTP without having called tfUseDhcp respectively tfUseBootp successfully first TM EMFILE Not enough sockets to open the BOOTP client UDP socket TM IPDEV BOOTP or TM IP DEV DHCP configurations only TM ADDRINUSE Another socket is already bound to the BOOTP client UDP port TM IP DEV BOOTP or TM IP DEV DHCP configurations only TM ETIMEDOUT DHCP or BOOTP request timed out TM EAGAIN A PPP session is currently closing Call tfConfigInterface again after receving notification that the previous session has ended other Error value as returned by the device 5 142 2004 Treck Incorporated Programmer s R
450. ng sent 5 140 2004 Treck Incorporated Programmer s Reference out If scattered buffers are not allowed by the driver this number should be one otherwise it should be bigger than one multiHomelndex The index for this IP address for multihoming Zero must be the first multi home index used Flags Value Meaning TM DEV SCATTER SEND ENB This device supports sending data in multiple buffers per frame If this flag is set then the buffersPerFrameCount should be bigger than 1 This flag should always be set for SLIP or PPP serial devices TM DEV MCAST ENB This device supports multicast addresses TM DEV IP FORW ENB Allow IP Forwarding to and from this device TM DEV IP FORW DBROAD ENB Allow forwarding of IP directed broadcasts to and from this device TM DEV IP FORW MCAST ENB Allow forwarding of IP multicast messages to and from this device TM DEV IP BOOTP Configure IP address using BOOTP client protocol tfUseBootp need to have been called first TM DEV IP DHCP Configure IP address using DHCP client protocol tfUseDhep need to have been called first TM DEV IP USER BOOT Allow the user to temporarily configure the interface with a zero IP address to allow the user to use a proprietary protocol to retrieve an IP address from the network TM DEV IP NO CHECK Allow the Treck stack to function in promiscuous mode where all packets received by this interface whill be handed to the application without checki
451. ng system and we are using Treck as a shared library in this environment What we have done with the locking system is to use the most atomic feature found in most embedded operating systems to achieve single threaded access to a data area We use a counting semaphore to guarantee that only one thread or task of a system can access certain shared data areas at one time By using a counting semaphore we allow the operating system to properly context switch to a higher priority task at the end of the locked section 3 4 2004 Treck Incorporated Treck Systems In our Treck TCP IP we use many different locks By operating in this fashion we avoid stopping other tasks that have no interest in our protected data area If there is no contention for the same data area tasks will still operate without blocking We do not call the operating system unless there is contention for a shared data area There is a large difference between a critical section and locking in Treck TCP IP A critical section is used to protect a shared data area in a very small amount of code This code is typically less than five assembly instructions in most instances On the other hand a lock is used to protect a shared data area or resource from reentrancy for longer periods This shared data area could be a socket entry routing entry or ARP entry Even with locks we attempt to keep the time as short as possible to avoid having contention for the shared data area or resourc
452. ng system is one where all tasks have the same priority run in a round robin fashion and explicitly give up the CPU through an RTOS call This is usually called a Round Robin Scheduler Next you will need to decide how you are going to use Treck Real Time TCP IP with your RTOS Do you want to have Treck run as its own task or in the context of other tasks as a 44 2004 Treck Incorporated Integrating into Your Environment shared library This choice depends on how you want your system to run Most embedded systems choose to use the protocol stack as a shared library because it gives you the most flexibility on how you want to prioritize the different processes in using a protocol stack If you decide to use Treck protocols as a single task then there is also the performance hit of having a thin layer between the application and the protocol stack Most people who want to have a separate task decide to do it to maintain modularity of the protocol stack In doing so they allow the protocol stack to be a plug in to an existing application Application Application Application Task Task Task 1 2 3 FTP Client Web Server Ping Treck RTOS Shared Library Device Driver Fig 4 1 Example of Using Treck Protocols as a Shared Library 4 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 2 Setting TRSYSTEM H for Various Compile Time Switches The TRSYSTEM H file is
453. non blocking mode tfTeldUserStart will return immediately after listening for incoming connections It is the user s responsibility to then call tfTeldUserExecute periodically to execute the telnet server code Choose the non blocking mode if you do not have an RTOS Kernel 6 126 Parameters Parameter telnetOptionsAllowed maxConnections maxBackLog blockingState Returns Value TM ENOERROR TM EINVAL TM EALREADY Application Reference Description Indicates which options we allow the client to negotiate The user can OR together TM TELD BINARY ON and TM TELD ECHO ON to allow binary transfer and echo by the server respectively Maximum number of concurrent accepted incoming telnet connections allowed If zero then the telnet server will accept as many connections as there are available sockets Maximum number of concurrent pending before being accepted incoming telnet connections allowed TM BLOCKING ON for blocking mode TM BLOCKING OFF for non blocking mode Meaning Success Incorrect telnet options flag maxConnections is either negative if non zero exceeds or equals the current number of available telnet connections or blockingState is neither TM BLOCKING ON nor TM BLOCKING OFF tfTeldUserStart has already been 6 127 Treck Real Time TCP IP User s Manual called TM EMFILE There are no more socket available to open the telnet server listening socket TM ENOBUFS Insufficient user m
454. ns ree osse eve eoe evens 4 15 TM GLOBAL NEAR uon x UU PEDEM Iter eRe Eese orrs tE 4 15 TM CONST QLP ecrire eee rte estate el as nee ves 4 15 Data Aligninelts a s Reed dede bre RR dta optet 4 16 TM ETHER HW ALIGN 5 5 tete needs 4 16 TM NEED ETHER 32BIT ALIGNMENT ene 4 16 Predefined Processor Macros sese 4 16 TM INTEL DES Ors ts enean PE ect ele tie 4 16 TM MOTOROLA CPU32 ss neret nere nettes dene ects 4 16 2004 Treck Incorporated TM MOTOROLA 68K inier ettet rte teer eee ve repose recs 4 16 PM MOTOROLA PPC 4 3 nente iren ee e Heber tient 4 16 TM TMS320 C3 iron doctors an epar hei CC re ee prever en 4 16 TM TMS320 C3 BIG ENDIAN ss 4 16 TM TMS320 C6 seine iier rase earne aue er E Det Dre Pec ae 4 16 Compiler Specifications 4 17 TM COMPILER SDS resta rettet eae eene aris ais eed ves 4 17 TM COMPILER DDI PPG 5 1 IO Ee EEEE PERETE 4 17 TM COMPILER MRI 68K secret 4 17 RIOS Kemel Environtnents 5 cette rere PR eats 4 17 TM KERNEL ELX 586 eicere eene pu dre vae veces 4 17 TM KERNEL UCOS X86 ete erreur OPE SEHR URS 4 17 TM KERNEL UCOS PC deese pace cene tete ie be Dyot ERE EE EO dae 4 17 TM KERNEL UGOS CPUS2 eio ren bt ee High 4 17 TM KERNEL UCOS MIPS neret rete entere e sexes 4 17 TM KERNEL UCOS XSOAXLE reete rt pereo tapete 4 17 TM KERNEL UCOS SH armee cedet teet ve ebore de tbe E die 4 17 TM KERNEL AMX CPUS32 oet pepe EE reci 4 17 TM K
455. nt 0 or 1 SO_RCVBUF unsigned long SO_RCVLOWAT unsigned long SO_REUSEADDR int Oor 1 SO_SNDBUF unsigned long SO_SNDLOWAT unsigned long TM SO RCVCOPY unsigned int TM SO SNDAPPEND unsigned int SO UNPACKEDDATA int Oorl IP_PROTOIP IPO TOS unsigned char IPO_TTL unsigned char IPO_SRCADDR ttUserIpAddress IPO MULTICAST TTL unsigned char IPO MULTICAST IF struct in_addr IPO ADD MEMBERSHIP struct ip mreq IPO DROP MEMBERSHIP structip mreq IP PROTOTCP TCP KEEPALIVE int TCP MAXRT int TCP MAXSEG int TCP NODELAY int Oorl TCP_NOPUSH int Oorl TCP_STDURG int Oorl TM_TCP_PACKET int Oorl TM_TCP_2MSLTIME int TM_TCP_DELAY ACK int TM_TCP_FINWT2TIME int TM_TCP_KEEPALIVE CNT int TM TCP KEEPALIVE INTV int TM TCP MAX REXMIT int TM TCP PROBE MAX unsigned long TM TCP PROBE MIN unsigned long TM TCP RTO DEF unsigned long TM TCP RTO MAX unsigned long TM TCP RTO MIN unsigned long TM TCP SEL ACK int Oorl TM TCP SLOW START int Oorl TM TCP TS int Oorl TM TCP WND SCALE int Oorl 5 58 2004 Treck Incorporated Returns Value 0 l setsockopt will fail if TM EBADF TM EINVAL TM ENOPROTOOPT TM EPERM TM EPERM TM ENETDOWN TM EADDRINUSE TM ENOBUF TM ENOENT Programmer s Reference Meaning Successful set of option An error occurred The socket descriptor is invalid One of the parameters is invalid The option is unknown at the level indicated Option cannot be set after the connection has been established IPO
456. nter to a user variable into which the option value is returned User variable is of data type described below Pointer to the size ofthe user variable which is the size of the option data type described below It is a value result parameter and the user should set the size prior to the call Description Socket level protocol IP level protocol TCP level protocol 5 21 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ProtocolLevel OptionName SOL SOCKET SO ACCEPTCON IP PROTOIP IP PROTOTCP 5 22 SO DONTROUTE SO ERROR SO KEEPALIVE SO LINGER SO OOBINLINE SO RCVBUF SO RCVLOWAT SO REUSEADDR SO SNDBUF SO SNDLOWAT TM SO RCVCOPY TM SO SNDAPPEND SO UNPACKEDDATA IPO MULTICAST IF IPO MULTICAST TTL IPO TOS IPO TTL IPO SRCADDR TCP KEEPALIVE TCP MAXRT TCP MAXSEG TCP NODELAY TCP NOPUSH TCP STDURG TM TCP 2MSLTIME TM TCP DELAY ACK TM TCP FINWT2TIME TM TCP MAX REXMIT TM TCP PACKET TM TCP PROBE MAX TM TCP PROBE MIN TM TCP RTO DEF TM TCP RTO MAX TM TCP RTO MIN TM TCP SEL ACK TM TCP SLOW START TM TCP TS TM TCP WND SCALE 2004 Treck Incorporated int int int int struct linger int unsigned long unsigned long int unsigned long unsigned long unsigned int unsigned int int struct in_addr unsigned char unsigned char unsigned char ttUserlpAddress int int int int int int int int int TM TCP KEEPALIVE CNT int TM TCP KEEPALIVE INTV
457. nterface for device drivers as device drivers are the only items that need an interrupt service routine In the ISR interface we need to be able to install an interrupt service routine and provide a mechanism to notify the protocol stack about ISR events The function KernelInstalllsrHandler is used to install an ISR handler Device drivers written by Treck Inc normally call this function It is not called directly by the Treck protocol stack If you do not use a Treck device driver then you will not need this function in your interface If you are using an Treck driver then this function is used to install the device drivers interrupt handler Our drivers do not do any packet processing within the ISR They simply notify task level routines that an event has occurred void tfKernelInstallIsrHandler ttUserIsrHandlerPtr funcPtr unsigned long offSet funcPtr is the Function To Be Called as the Handler of fSet is the offset into the Interrupt Vector Table Eri RTOSInstallISR void TM FAR funcPtr offSet 4 31 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Device Interface Routines The set of four functions tfKernelCreateEvent tfKernelPendEvent tfKernellsrPostEvent tfKernelTaskPostEvent are used internally by the Treck device interface routines They are only needed if the user wishes to use and to block in the receive task or the transmit task or the send complete task tfKernelTaskYield i
458. nterfaceHandle Function Description TfCheckXmitInterface is used to check if data is ready to be sent on a particular device interface data queued to the interface send queue This call can be used in environments where it is preferable to poll the device for data ready to be transmitted i e a main loop If you are using a separate task or thread to transmit data then you should use the tfWaitXmitInterface call Upon a successful return the user should call tfXmitInterface to send the data ready to be transmitted from the bottom of the Treck stack to the device driver Parameters Parameter Description interfaceHandle The interface handle to poll to see if data needs to be received from the device driver Returns Value Meaning 0 There is data waiting to be transmitted to the device driver TM EWOULDBLOCK There is no data waiting to be transmitted to the device driver 5 137 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfCloselnterface include lt trsocket h gt int tfCloseInterface ttUserInterface interfaceld Function Description This function is used to close the interface that is passed in It simply calls the link layer close routine the driver close routine removes the interface from the local routing table and returns the error code that the link layer or driver returns Parameters Parameter Description interfaceld The device driver entry that contains the close routine Re
459. null the function it points to is called for each received PING echo reply or ICMP error message with the socket descriptor returned by tfPingOpenStart passed as a parameter To get the PING connection results and statistics the user must call tfPingGetStatistics To stop the system from sending PING echo requests and to close the ICMP socket the user must call tfPingClose Parameters Parameter remoteHostNamePtr pinginterval pingDataLength pingUserCBFuncPtr 6 8 Description Pointer to character array contain ing a dotted decimal IP address Interval in seconds between PING echo requests If set to zero defaults to 1 second User Data length of the PING echo request If set to zero defaults to 56 bytes If set to a value between 1 and 3 defaults to 4 bytes Pointer to a user function to be called upon receiving a network PING echo reply or an ICMP error message with the socket descriptor as returned by tfPingOpenStart passed as a parameter Can be set to null function pointer if the user does not wish to be notified of incoming network traffic Application Reference Returns New ICMP Socket Descriptor or TM SOCKET ERROR 1 on error If tfPingOpenStart fails the errorCode can be retrieved with tfGetSocketError CM SOCKET ERROR TM BINVAL remoteHostNamePtr was a null pointer TM EINVAL pinginterval was negative TM_EINVAL pingDataLength was negative of bigger than 65595 maximum value allowed by t
460. nus any enabled TCP option for example 12 bytes for a TCP time stamp option 5 17 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Default is IP MTU minus 40 bytes TCP NODELAY If this option value is non zero the Nagle algorithm that buffers the sent data inside the TCP is disabled Useful to allow client s TCP to send small packets as soon as possible like mouse clicks Default 0 TCP_NOPUSH If this option value is non zero then TCP delays sending any TCP data until a full sized segment is buffered in the TCP buffers Useful for applications that send continuous big chunks of data and know that more data will be sent such as FTP Normally the TCP code sends a non full sized segment only if it empties the TCP buffer Default 0 TCP_STDURG If this option value is zero then the urgent data pointer points to the last bye of urgent data 1 like in Berkeley systems Default 1 urgent pointer points to last byte of urgent data as specified in RFC1122 TM TCP PACKET Ifthis option value is non zero then TCP behaves like a message oriented protocol i e respects packet bound aries at the application level in both send and receive directions of data transfer Note that for the receive direction to respect packet boundaries the TCP peer which is sending must also implement similar functionality in its send direction This is useful as a reliable alternative to UDP Note that preserving packet bound
461. o BSD Sockets 2004 Treck incorporatea Treck Real Time TCP IP User s Manual ZUU4 Treck Incorporated Introduction to BSD Sockets Intro to BSD Sockets The Berkeley Sockets 4 4 API Applications Programmer Interface is a set of standard function calls made available at the application level These functions allow programmers to include Internet communications capabilities in their products The Berkeley Sockets API also frequently referred to as simply sockets was originally released with 4 2BSD in 1983 Enhancements have continued through the 4 4BSD systems Berkeley based code can be found in many different operating systems both commercial and public domain such as BSD OS FreeBSD NetBSD OpenBSD and UnixWare 2 x Other popular operating systems such as Solaris and Linux employ the standard sockets interface though the code was written from scratch Other sockets APIs exist though Berkeley Sockets is generally regarded as the standard Two of the most common APIs are Winsock and TLI Winsock Windows Sockets was developed for the Microsoft Windows platform in 1993 and is based significantly on the BSD interface A large subset of the BSD API is provided with most of the exceptions being platform specific to BSD systems TLI Transport Layer Interface was developed by AT amp T and has the capability to access TCP IP and IPX SPX transport layers XTI X Open Transport Interface developed by X Open Company Ltd
462. o error reports ICMP does not fully specify the action to be taken for each possible error When a datagram causes an error ICMP can only report the error condition back to the original source of the datagram the source must relate the error to an individual application program or take other action to correct the problem Most errors stem from the original source but some do not Because ICMP reports problems to the original source it cannot be used to inform intermediate routers about problems Unfortunately the original source has no responsibility for the problem or control over a misbehaving router In fact the source may not be able to determine which router caused the problem You might ask Why restrict ICMP to communication with the original source Well to answer that question we know that a datagram only contains fields that specify the original source and the ultimate destination It does not contain a complete record of its trip through the Internet except for unusual cases where the record route option is used Furthermore because routers can establish and change their own routing tables there is no global knowledge of routes Thus when a datagram reaches a given router it is impossible to know the path it has taken to get there Ifthe router detects a problem it cannot know the set of intermediate machines that processed the datagram so it cannot inform them of the problem Instead of silently discarding the datagram
463. o the newly allocated structure tfCreateTreckContext should be called once for each instance of the Treck TCP IP stack It should be called after tfInitTreckMultipleContext and prior to any other Treck functions when using multiple instances of the Treck stack Parameters None Returns Value Meaning Non null pointer Pointer to newly created context ttUserContext 0 An error occurred A 17 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSetCurrentContext include lt trsocket h gt void tfSetCurrentContext ttUserContext contextHandle Function Description This function is used to set the current Treck stack context It is usually called after a context switch or after a kernel call Parameters Parameter Description contextHandle Treck stack context to be set Returns None A 18 2004 Treck Incorporated Configuration Notes tfGetCurrentContext include lt trsocket h gt ttUserContext tfGetCurrentContext void Function Description tfGetCurrentContext returns the current Treck stack context as known by the Treck stack It is usually called before a context switch or kernel call Parameters None Returns Value Meaning Non zero pointer Current context handle Null pointer Invalid context handle A 19 2004 Treck Incorporated Treck Real Time TCP IP User s Manual A 20 2004 Treck Incorporated Appendix B RTOS Notes 2004 Treck Incorporated Treck
464. o with Treck TCP IP is allow the system to dynamically allocate memory as needed This means the memory pool may grow over time After Treck TCP IP is used actively over a period of about one minute the maximum pool that Treck TCP IP will be using is already allocated from the operating system The pool that Treck is using will only grow as more performance demands are placed on the networking system By allocating buffers in this fashion Treck eliminates the guesswork that is involved in trying to setup a system We allow the protocol stack to only use the memory that is required for your performance demands You do not need to set aside an area of memory of a fixed size We have found that if you are forced to set aside a fixed size memory block that will be used by the TCP IP stack to dynamically allocate memory from you will be forced to set aside more memory than you will use in order to prevent out of memory errors from occurring We dynamically allocate almost all of our data structures This is done to keep the static memory area as small as possible Also by doing this we allow you to change the configuration of the protocol stack without recompiling By this time you must be asking yourself the question So how much RAM will I use We have found that a single TCP socket implementation with a small number of receive buffers will use less than 20k bytes of RAM when the highest performance demands are placed upon the protocol
465. ocation the Treck Simple Heap must be used In trsystem h be sure to define the following define TM_USE_SHEAP define TM_SHEAP SIZE size where size is the size in bytes of the simple heap area Most simple applications will need about 32K bytes of RAM To defining 32K you simply define TM SHEAP SIZE 32L 1024L Note that size is defined as a long constant Because the simple heap is used there is no need to create the functions tfKernelMalloc and t KernelF ree B 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Critical Section Handling uC OS does have critical section handling via two macros OS ENTER CRITICAL and OS EXIT CRITICAL For tfKernelSetCritical you simply call OS ENTER CRITICAL and for tfKernelReleaseCritical you simply call OS EXIT CRITICAL It 1s always best to use inline assembly for critical section handling by setting the macros fm kernel set critical and tm kernel release critical for your processor in trsystem h You will find preexisting critical section macros for specific processors and compiler combinations in trmacro h Error Logging and Warning Information Logging uC OS does not have any error reporting mechanism Since this is the case tfKernelError and tfKernel Warning should be written to write out to a display serial port or a predefined area of memory that can be examined via a debugger In the case of tfKernelError it should cause a CPU reset after displaying the error message
466. ock Functions This group of functions is used to allow synchronization between the user application sending threads and a separate Treck user transmit task They are not needed if the user does not wish to use a dedicated Treck user transmit task to send data to the device driver The tf CheckXmitInterface or tfWaitXmitInterface function is used to tell the user when to call tfXmitInterface The tf CheckXmitInterface function is used to poll for packets queued to the device send queue The ffWaitXmitInterface function is used to block the transmit task until one or more packets have been queued to the device send queue You must choose if you want a task to block until or to poll to see if a packet has been queued to the send queue The choice that you make defines which of the functions WaitXmitInterface or tf CheckXmitInterface that you will use 4 51 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Note After having initialized the stack the user need to call tfInterfaceSetOptions once with the TM DEV OPTIONS XMIT TASK option to let the Treck stack know that a separate transmit task is used whether the user chooses to use tf CheckXmitInterface polling method or tfWaitXmitInterface pending method If you do not have an RTOS you cannot use tfWaitXmitInterface If you do have an RTOS you can use tfWaitXmitInterface but only if you define the TM TASK XMIT macro in trsystem h The user will call the fX
467. ocketDescriptor is the socket descriptor as given by the user in tfRegisterSocketCB and eventFlags contain one or more of the events specified by the user that have occured Described below are the action s to be taken by the user in the user supplied call back function upon receiving any one of the socket events EventFlags TM CB CONNECT COMPLT TM CB ACCEPT TM CB RECV TM CB RECV OOB 5 118 2004 Treck Incorporated Description Non blocking connect issued earlier by the user has now completed and the connection is established with the peer on the socketDescriptor The user is now able to send and recv data on the connection given by the socketDescriptor A remote host has established a connection to the listening server socketDescriptor The user can now issue an accept call to retrieve the socket descriptor of the newly established connection Incoming data has arrived on the connection given by socketDescriptor The user can now issue any of the allowed recv calls for the protocol associated with the socket to retrieve the incoming data Incoming out of band data has arrived on the connection given by socketDescriptor The user can use the appropriate method to retrieve the out of band data as described in the recv section above TM_CB_SEND_COMPLT TM CB REMOTE CLOSE TM CB WRITE READY TM CB SOCKET ERROR TM CB RESET TM CB CLOSE COMPLT Returns Value 0 l tfRegisterSocketCB will fail if
468. of ChecksSuims ss es tethiminneuinnnnt 1 42 The Internet Control Message Protocol ICMP ss 1 44 The Internet Control Message Protocol see 1 44 Error Reporting vs Error Correction csccecesseseceeeeeeseeeeeeereeeeeeseneenenes 1 45 ICMP Message Delivery 2 etre tee evi tere Re eto ree cbe des 1 46 ICMP Message Format Je nU ORO ERREUR cs tonne 1 47 Testing Destination Reachability and Status Ping 1 48 SUMMAS 2p etium Uu nitet dam Dette 1 49 The User Datagram Protocol UDP eeeeeeeeeeee eene nennen 1 49 UDP Message Format uero ner rettet rette th Dern ore rto E Perro ERA 1 50 UDP Pseudo He der ist terminent 1 51 UDE Encdpsulati6n 2 d vtero Ce Hopes E rE EESEL EREE 1 51 The Transport Control Protocol TCP nes 1 52 Rehabl Stream Delivery ctetuer dtp nee CO DE PESSE ESTA 1 52 dipole D lasser inatres 1 53 Sliding Windows oni roto pee eet dut rte decreases 1 54 Transmission Control Protocol 1 57 TOP E ra E voor toties pa patte ts tiere 1 57 TCP IP and Client Server Relationships ss 1 59 vilia gb E 1 60 Introduction to BSD Sockets ses Del Intro to BSD Sockets 4 eese eee eee eene enne n nennen natns tuna tn sensns sun sinan 2 3 Overview of How Sockets Works sense 2 3 Byte Ordering Functions esee eese esent eene entes tn nennen stunt tna 2 4 Data Structures 2 5 Common Sockets Calls
469. off passive mode by using this function before setting up data connections Parameters Parameter Description fipUserHandle The user handle of FTP session will be operated on onFlag The FTP passive mode This parameter can be TM FTP PASSIVE MODE ON Or TM FTP PASSIVE MODE OFF Returns Name Description TM BINVAL Invalid argument TM ENOERROR No error 6 64 Application Reference tfFtpType include lt trsocket h gt int tfFtpType ttUserFtpHandle ftpSessionPtr int type i Function Description This function sets the transfer type to either binary or ASCII Parameters Parameter Description fipSessionPtr FTP session handle type Transfer type TM TYPE ASCII or TM TYPE BINARY Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK TM EACCES TM ENOTCONN TM BINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMDPARAM TM FTP SERVNAVAIL TM FTP NOTLOGIN This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented for that parameter Service not available closing TELNET connection Not logged in Treck Real Time TCP IP User s Manual tfFtpUserExecute include lt trsocket h gt int tfFtpUserExecute ttUserFtpHandle ftpSessionPtr Function Descriptio
470. ogrammer s Reference recvfrom include lt trsocket h gt nt recvfrom nt socketDescriptor har bufferPtr n bufferLength n flags truct sockaddr fromPtr nt fromLengthPtr BO BBQ BAB Ne Function Description recvfrom is used to receive messages from another socket recvfrom may be used to receive data on a socket whether it is in a connected state or not but not on a TCP socket socketDescriptor is a socket created with socket If fromPtr is not a NULL pointer the source address of the message is filled in fromLengthPtr is a value result parameter initialized to the size of the buffer associated with fromPtr and modified on return to indicate the actual size of the address stored there The length of the message is returned If a message is too long to fit in the supplied buffer excess bytes may be discarded depending on the type of socket the message is received from see socket Ifno messages are available at the socket the receive call waits for a message to arrive unless the socket is non blocking or the MSG DONTWAIT flag is set in the flags parameter in which case 1 is returned with socket error being set to EWOULDBLOCK select may be used to determine when more data arrives or and when out of band data arrives tfRegisterSocketCB may be used to asynchronously determine when more data arrives or and when out of band data arrives 5 37 2004 Treck Incorporated Treck Real Time TCP IP
471. ol requires usage of send not tfSendToFrom The socket is marked as non blocking and the send operation would blocktfSendTolnterface Programmer s Reference tfSendTolnterface include trsocket h int tfSendToInterface int SocketDescriptor char bufferPtr int bufferLength int flags const struct sockaddr toPtr int toLength ttUserInterface interfaceHandle unsigned char mhomeIndex Function Description tfSendToInterface is used to transmit a message to another transport end point tfSendToInterface may be used at any time either in a connected or unconnected state but not for a TCP socket socketDescriptor 1s a socket created with socket The address of the target is given by to with toLength specifying its size If the message is too long to pass atomically through the underlying protocol then is returned with the socket error being set to TM EMSGSIZE and the message is not transmitted A return value of 1 indicates locally detected errors only A positive return value does not implicitly mean the message was delivered but rather that it was sent If the socket does not have enough buffer space available to hold the message being sent and is in blocking mode tfSendToInterface blocks If it is in non blocking mode or the MSG DONTWAIT flag has been set in the flags parameter is returned with the socket error being set to TM EWOULDBLOCK The select call may be used to determine wh
472. ollowing page 6 28 Application Reference ttUserFtpHandle ftpHandle int errorCode Jk Create a new FTP client session which includes logging into the local filesystem y ftpHandle tfFtpNewSession 0 TM BLOCKING ON fsusername fspassword Connect to the FTP server errorcode tfFtpConnect ftpHandle 10 129 5 10 Login to the server errorCode tfFtpLogin ftpHandle ftpuser ftppass Sittpaecct Transmit daily log file to server errorCode tfFtpStor ftpHandle 0 home treck 100999 10g logfile Retrieve most recent configuration file from server 7 errorCode tfFtpRetr ftpHandle 0 home treck device cfg configfile Close FTP connection errorCode tfFtpQuit ftpHandle End FTP session errorCode tfFtpFreeSession ftpHandle 6 29 Treck Real Time TCP IP User s Manual File System Interface The user must provide this interface to the file system These functions outlined below allow the FTP client to access the local file system This interface is a subset of that required by the FTP server FTPD and the same routines may be used for both the FTP client and server Entry points from the FTP client to the file system tfFSCloseDir Close a directory that we had opened earlier tfFSCloseFile Close a file tfFSOpenDir Open specified directory or directory corresponding to a specified pattern to allow getting a
473. on some chips for example the Crystal LAN cs8900 won t dismiss a receive interrupt until the data is copied If this is the case you must get a buffer from within the ISR The Treck stack provides a set of tools that allow you to get a Treck buffer from within the ISR If you want to use these Treck tools you must to call tfPoolCreate in the deviceOpen function For example we pre allocate a pool of ten 128 bytes small buffers and we pre allocate a pool of five 1518 byte big buffers The TM POOL REFILL IN LINE flag indicates that we want the buffers to be re allocated in the receive task thread define TM ID RECV BIG BUFFERS 5 define TM_ID_RECV_SMALL_BUFFERS 10 define TM ID SMALL BUFFER SIZE 128 4 60 2004 Treck Incorporated Integrating into Your Environment int errorCode Initialize the Hardware Install the ISR Handler Routine tfKernelInstallIsrHandler myHandlerFunctionPtr myHandlerIsrLocation Example where we pre allocate a pool of 10 128 bytes small buffers and 5 maximum Ethernet size big buffers The TM_POOL_REFILL_IN_LINE flag indicates that we want the buffers to be re allocated in the receive task thread By errorCode tfPoolCreate interfaceHandle TM ID RECV BIG BUFFERS TM ID RECV SMALL BUFFERS TM ETHER MAX PACKET CRC TM ID SMALL BUFFER SIZE 0 TM POOL REFILL IN LINE return errorCode 2 deviceClose This optional routine is called by the stac
474. on userBuffer A user buffer handle as stored by tfGetEthernetBuffer or tfGetDriverBuffer Returns Value Meaning 0 Success TM DEV ERROR Null user buffer handle or user does not own the buffer 5 147 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetDriverBuffer include lt trsocket h gt char tfGetDriverBuffer ttUserBufferPtr userBufferPtr int length int alignment hr Function Description This function is used to get a buffer from the Treck buffer pool for the user to use for a device driver It is not required for a user to use the Treck buffer pool i e this function because some devices may not support it Parameters Parameter Description userBufferPtr A pointer to a ttUserBuffer variable that the user buffer handle is stored into length Number of bytes to be allocated by the system alignment The returned buffer pointer will be aligned on a multiple of this value Returns A char to the beginning of the data area to store the received data into or a NULL pointer if there is no memory to complete the operation 5 148 2004 Treck Incorporated Programmer s Reference tfGetBroadcastAddress int tfGetBroadcastAddress ttUserInterface interfaceHandle ttUserlIpAddress ifBroadcastAddressPtr unsigned char multiHomeIndex Function Description This function is used to retrieve the broadcast address for an interface The multi home index is used for interfaces that ha
475. on Description RTOS SPECIFIC This function is used to install an Interrupt Service Routine ISR handler Parameters Parameter Description handlerPtr The pointer to the function that the ISR should call offset Offset into the vector table where this handler should be installed Returns Nothing 5 235 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernellsrPostEvent include lt trsocket h gt void tfKernellsrPostEvent ttUserGenericUnionPtr eventPtr Function Description RTOS SPECIFIC This function is used to resume waiting tasks that were waiting on this event It is called from an ISR Parameters Parameter Description eventPtr The event to post on Returns Nothing 5 236 2004 Treck Incorporated Programmer s Reference tfKernelMalloc include lt trsocket h gt void tfKernelMalloc unsigned size Function Description RTOS SPECIFIC This function is used to allocate a block of memory Parameters Parameter Description size The amount of memory to allocate Returns A pointer to the beginning of the memory block 5 237 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelPendCountSem include lt trsocket h gt int tfKernelPendCountSem ttUserGenericUnionPtr countingSemaphore Function Description RTOS SPECIFIC This function is used to wait on a counting semaphore Parameters Parameter Description countingSemaphor
476. on description Finish opening an Interface that the user had started to open with the TM DEV IP USER BOOT flag That flag caused the Treck stack not to store the IP address netmask in the routing table leaving the interface in a half configured state tfFinishOpenInterface will attempt to insert the ipaddress netmask into the routing table Parameters Parameter Description interfaceld The device entry This is returned by tfAddInterface ipAddress The IP Address for this Interface at multihome index 0 netMask The net mask for this device Subnet or Supernet at multihome index 0 Returns Value Meaning 0 Success TM_EADDRNOTAVAIL Attempt to configure the device with a broadcast address TM_ENOBUFS Not enough memory to complete operation TM_EINVAL Bad parameter such as invalid interfaceld TM EALREADY ipAddress netMask already in the routing table TM EPERM User did not set the TM DEV IP USER BOOT flag when calling tfOpenInterface 5 146 2004 Treck Incorporated Programmer s Reference tfFreeDriverBuffer include lt trsocket h gt int tfFreeDriverBuffer ttUserBuffer userBuffer Function Description User frees a buffer that was allocated with either tfGetEthernetBuffer or tfGetDriverBuffer and that was not given to the Treck stack Note If the buffer has been given to the Treck stack the user no longer owns the buffer and should not call tfFreeDriverBuffer Parameters Parameter Descripti
477. on set successfully interfaceHandle is NULL interfaceHandle refers to a device that does not support EAP 7 83 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetPppDnsipAddress include lt trsocket h gt int ttUserInterface ttUserlpAddress int he Function description tfGetPppDnsIpAddress interfaceHandle dnsIpAddressPtr flag This function is used to return the DNS Addresses as negotiated by the remote PPP server This function can only be used with PPP devices If no DNS address is negotiated the IP address returned will be 0 0 0 0 Parameters Parameter interface handle dnsIpAddressPtr flag Returns Value 0 TM BINVAL TM ENETDOWN 7 84 Description The interface handle to get the DNS IP address from The pointer to the buffer where the DNS IP address will be stored One of the following TM DNS PRIMARY or TM DNS SECONDARY Meaning Success One of the parameters is null or the device is a LAN device Interface is not configured 2004 Treck Incorporated Optional Protocols tfGetPppPeerlpAddress include lt trsocket h gt int tfGetPppPeerIpAddress ttUserInterface interfaceHandle ttUserIpAddress ifIpAddress Function Description This function is used to get the PPP address that the remote PPP has used respectively SLIP address of the remote SLIP This function should be called after tfOpenInterface has completed successfully If
478. on the network Experience shows that because most network communication involves more than one packet transfer even a small cache is beneficial There are several important points to remember about ARP First notice that when one machine is about to use ARP because it needs to send information to another machine there is a high probability that the second machine will need to communicate with the first machine in the near future To anticipate the need ofthe second machine and to reduce network traffic the first machine sends its IP to physical address binding when sending a request to that machine That machine then extracts the first machine s binding from the request and saves that information in its ARP cache It then sends a reply to the first machine Because the first machine broadcasts its initial request all machines on the network receive it and can extract the IP to physical address and store it their cache This saves time in future transmissions When a computer has its host interface replaced e g 1 17 2004 Treck Incorporated Treck Real Time TCP IP User s Manual because the hardware has failed its physical address changes Other computers on the network that have stored a binding in their ARP cache must be notified of the change A system can notify others of a new address by sending an ARP broadcast when it boots To summarize remember The sender s IP to physical address binding is included in every ARP bro
479. on using tfInterfaceSetOptions That default threshold value can be changed at run time using the tfInterfaceSetOptions API with the TM DEV OPTIONS SCAT RECV LENGTH option Dealing with non contiguous network protocol headers in scattered recv buffers TM RECV SCAT MIN INCR BUF When the stack processes a received scattered buffer it checks that the network protocol header is contiguous at a given layer It if is not then it means that the header straddles between the first buffer and consecutive buffers in the frame If there is enough room at the end of the first of those consecutive buffers then the end of the header is copied there If there is not enough room then a new buffer is allocated and replaces the first buffer Data from the first buffer plus the end of the header is copied into the first buffer To prevent numerous re allocation of the first buffer while processing the network headers we allocate the maximum of TM RECV SCAT MIN INCR BUF and size of data that needs to be contiguous By default TM RECV SCAT MIN INCR BUF is set to 128 It can be defined to a different value in trsystem h define TM RECV SCAT MIN INCR BUF 128 4 85 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Example New User device driver recv function int tfDevEtherScatRecvFunc ttUserInterface interfaceHandle ttDruBlockPtrPtr uDevBlockPtrPtr int uDevBlockCountPtr int ELAGPEL JG User calls User
480. on will not be called The pool refill will be done internally by the Treck stack 5 159 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter Description interfaceHandle The interface handle of the driver s ioctl routine to call flag See below optionPtr Pointer to a tfloctlInterface specific parameter optionLen length of the option The flags parameter is formed by ORing one or more of the following 0x0 0x100 Device specific flag TM DEV IOCTL EMPTY XMIT FLAG Empty the device driver transmit queue TM DEV IOCTL REFILL POOL FLAG Refill the Treck recv pool TM DEV IOCTL OFFLOAD GET Query the device driver for offload capabilities TM DEV IOCTL OFFLOAD SET Set the device driver for offload Returns TM ENOERROR xmit All buffers have been transmitted refill All buffers are allocated TM EINPROGRESS xmit Some buffers but not all have been transmitted refill Some buffers but not all have been allocated TM EPERM xmit iftransmit queue not enabled 1 e user did not call tfUseInterfaceXmitQueue successfully refill if the user did not create a recv pool TM ENOBUFS refill No buffer could be allocated Other As returned from the device driver send routine Buffers are still in the interface transmit queue None was sent 5 160 2004 Treck Incorporated Programmer s Reference tfNotifyInterfacelsr include trsocket h void tfNotifyInterfa
481. onal institutions to connect to what was now being called the Internet although the term ARPANET was still being used Because the National Science Foundation funded NSFNET universities used it almost exclusively As commercial sites needed local area connectivity to share files within their company most of them turned to the IPX SPX protocols developed by Novell In fact at one time Novell was being used by more than 80 of commercial sites using local area networking As the need for Electronic Mail e mail and wide area networking grew in the commercial sector companies turned to the Internet and the TCP IP protocols that it used New companies were formed 1 3 2004 Treck Incorporated Treck Real Time TCP IP User s Manual to create new commercial backbone networks One of the first of these was UUNET Over the past few years the Internet has exploded onto the commercial scene because ofa new way of advertising called web pages Today it is difficult to watch television without being bombarded with web page addresses What is a Protocol The definition of a protocol is A set of formal rules describing how to transmit data especially across a network What are these rules Well these rules consist of how the packet is formatted how much data it carries if and how it can be sure that the remote computer has actually received the data as well as any additional information that the protocol needs to send to the remote side In
482. ontaining the IP host group address and the interface defined by its IP address It will return TM EINVAL if the IP host group address is not a class D address or if there is no interface configured with the IP address stored in the structure It will return TM EADDRINUSE if there was a previous successful IPO ADD MEMBERSHIP call for that host group on the same interface Otherwise this is the first call to IPO_ADD MEMBERSHIP for the pair The IP host group address will be added to the interface In order to enable reception of that multicast address the Treck stack will call the interface driver specific ioctl function The driver specific ioctl function is called with the TM DEV SET MCAST LIST flag value optionPtr pointing to the list of Ethernet multicast addresses corresponding to all the IP host group addresses added 7 54 2004 Treck Incorporated Optional Protocols so far and optionLen indicating the number of those Ethernet multicast addresses We keep track of the list of Ethernet multicast addresses so that the driver does not have to Note In order to receive multicast packets the user must implement a section in drvloctl to create a multicast address from a list of Ethernet addresses and store that multicast address in the Ethernet chip See drvloctl for details Leaving a Host Group To stop receiving multicast packets for a given host group destination on an interface the user need to leave that host group on that int
483. ontext contextHandle Set the current context handle to the one passed in i e set the Treck global variable tvCurrentContext to the passed parameter ttUserContext tfGetCurrentContext void Get the current context handle i e the context handle stored in tvCurrentContext A 12 2004 Treck Incorporated Configuration Notes Enabling the Multiple Instances code in Treck To enable the multiple instances code in the Treck stack uncomment the following macro in your trsystem h define TM MULTIPLE CONTEXT Blocking mode non blocking mode The following indicates the modifications needed for each type of embedded kernel No Kernel All applications have to run in non blocking mode All calls to the Treck stack are made from a main loop Example with 2 contexts and 2 interfaces per context errorCode tfInitTreckMultipleContext contextHandlel tfCreateTreckContext contextHandle2 tfCreateTreckContext tfSetCurrentContext contextHandlel errorCode tfStartTreck contextlInterfaceHandlel tfAddInterafce errorCode tfOpenInterface contextlInterfaceHandlel contextlInterfaceHandle2 tfAddInterface errorCode tfOpenInterface contextlInterfaceHandle2 tfSetCurrentContext contextHandle2 errorCode tfStartTreck context2InterfaceHandlel tfAddInterafce errorCode tfOpenInterface contextlInterfaceHandlel context2InterfaceHandle2 tfAddInterface errorCode
484. onveys the packet s data to the application If there is no socket at the destination port the packet is discarded Byte Ordering Functions Because TCP IP has to be a universal standard allowing communications between any platforms it is necessary to have a method of arranging information so that big endian and little endian machines can understand each other Thus there are functions that take the data you give them and return them in network byte order On platforms where data is already correctly ordered the functions do nothing and are frequently macro d into empty statements Byte ordering functions should always be used as they do not impact performance on systems that are already correctly ordered and they promote code portability The four byte ordering functions are htons htonl ntohs and ntohl These stand for host to network short host to network long network to host short and network to host long respectively htons translates a short integer from host byte order to network byte order htonl is similar translating a long integer The other two functions do the reverse translating from network byte order to host byte order 2 4 2004 Treck Incorporated Introduction to BSD Sockets Data Structures Before venturing into the realm of actual API functions one must understand a few structures The most important of these is sockaddr_in It is defined as follows struct sockaddr_in short sin_family u s
485. options are recognized at the TCP level IP_PROTOTCP protocolLevel options TCP_KEEPALIVE TCP MAXRT TCP MAXSEG Description Get the idle time in seconds for a TCP connection before it starts sending keep alive probes Note that keep alive probes will be sent only ifthe SO KEEPALIVE socket option is enabled Default 7 200 seconds Get the amount of time in seconds before the connection is broken once TCP starts retransmitting or probing a zero window when the peer does not respond A TCP MAXRT value of 0 means the system default and 1 means retransmit forever Note that unless the TCP MAXRT value is 1 wait forever the connection can also be broken if the number of maximum retransmission TM TCP MAX REXMIT has been reached See TM TCP MAX REXMIT below Default 0 which means use system default of TM TCP MAX REXMIT times network computed round trip time for an established connection For a non established connection since there is no computed round trip time yet the connection can be broken when either 75 seconds or when TM TCP MAX REXMIT times default network round trip time have elapsed whichever occurs first Get the maximum TCP segment size sent on the network Note that the TCP MAXSEG value is the maximum amount of data including TCP options but not the TCP header that can be sent per segment to the peer i e the amount of user data sent per segment is the value given by the TCP MAXSEG option mi
486. or and aborted the session 7 51 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter interfaceHandle notifyFuncPtr Returns Value TM ENOERROR TM_EINVAL TM EALREADY TM ENOMEM 7 52 2004 Treck Incorporated Description Interface to enable the dialer on User s function to be called to notify of status of dialer Meaning Dialer successfully initialized Bad interface handle Dialer already initialized Insufficient memory to initialize dialer Optional Protocols IGMP Protocol Introduction IP multicasting is the transmission of an IP datagram to a host group a set of zero or more hosts identified by a single IP destination address A host group IP address is a multicast IP address or class D IP address where the first 4 bits of the address are 1110 The range of host group IP addresses class D are from 224 0 0 1 to 239 255 255 255 Class D addresses starting with 224 0 0 x and 224 0 1 x have been reserved for various permanent assignments see RFC 1700 The range of addresses between 224 0 0 1 and 224 0 0 255 are local multicast addresses i e they cannot be forwarded beyond the local subnet and have been reserved for the use of routing protocols and other low level topology discovery or maintenance protocols such as gateway discovery and group membership recording The membership of a host group is dynamic hosts may join and leave groups at any time IGMP Int
487. or can be emulated with the Treck resolver by first calling tfDnsGetMailHost and then repeatedly calling tfDnsGetNextMailHost which will return TM_EANSWER when no more records are available With each call to tfDnsGetNextMailHost the IP address and preference value of the previous lookup must be included For instance the following code retrieves all three entries in the example above unsigned short mxPrefl mxPref2 mxPref3 ttUserIpAddress ipAddressl ipAddress2 ipAddress3 Get the first MX record maill treck com errorCode tfDnsGetMailHost treck com amp ipAddressl amp mxPrefl Get the second MX record mail2 treck com errorcode tfDnsGetNextMailHost treck com ipAddressl mxPrefl amp ipAddress2 amp mxPref2 P Get the third MX record mail3 treck com If tfDnsGetNextMailHost were called with ipAddress3 and mxPref33 it would return TM EANSWER a errorCode tfDnsGetNextMailHost treck com ipAddress2 mxPref3 amp ipAddress3 amp mxPref3 6 12 Application Reference tfDnslnit int tfDnsInit int blockingMode Function Description This function initializes the DNS resolver service This should be called once and only once when the system is started Parameters Parameter Description blockingMode Specifies whether the resolver should operate in blocking or non blocking mode TM BLOCKING ON or TM BLOCKING OFF Returns Value Meaning TM EINVAL blo
488. or data To illustrate that point consider what happens when software on one computer sends a 32 bit binary integer to another computer The physical transport hardware moves the sequence of bits from the first machine to the second without changing the order However not all machines store 32 and or 16 bit integers in the same way On some machines referred to as Little Endian the lowest memory address contains the low order byte of the integer On others referred to as Big Endian the lowest memory address holds the high order byte of the integer Thus direct copying of bytes from one machine to another may change the value of the number Standardizing byte order for integers is especially important in an Internet because Internet packets carry binary numbers that specify information like destination addresses and packet lengths Both the senders and receivers must understand such quantities The TCP IP protocols solve the byte order problem by defining a network standard byte order that all machines must use for binary fields in Internet packets Each host converts numeric items from the host specific order to network standard byte order before sending a packet and converts from network byte order to the host specific order when a packet arrives Naturally the user data field in a packet is exempt from this standard users are free to format their own data however they choose Of course most application programs use the Big Endian format as
489. or for outputting the routing entries ARP entries and socket entries The netstat tool is described in the Application Reference Section TM_USE_SNIFF if TM USE SNIFF is defined interface drivers will dump the packets to the file system in libpcap format to be opened by tcpdump windump ethereal or other libpcap file readers Models for Running Treck TM_TRECK_NO_KERNEL This macro is used to compile the stack so that it will not use an RTOS Kernel When you do not have a real time operating system you will not need to use the locking system that the Treck protocol stack provides Note that you will not be able to make any calls that will cause the system to block You must ensure that 4 11 2004 Treck Incorporated Treck Real Time TCP IP User s Manual any call into the Treck protocol stack will not block Critical sections for the driver interface are still enabled when you are using Treck without a kernel TM_TRECK_NONPREEMPTIVE_KERNEL This macro is used to compile the stack so that it will use a non preemptive kernel You must ensure that your kernel is not preemptive before you define this macro This macro disables the locking system which is not needed by a non preemptive kernel When you are using a non preemptive kernel you may still make calls to the Treck protocol stack that are either blocking or non blocking Critical sections for the driver interface are still enabled when you are using Treck with a non preemptive ke
490. or set fdset to the null set FD SET fd amp fdset Includes a particular socket descriptor fd in fdset FD CLR fd amp fdset Removes fd from fdset FD ISSET fd amp fdset Is non zero if fd is a member of fdset zero otherwise Note the term fd is used for BSD compatibility since select is used on both file systems and sockets under BSD Unix The timeout parameter specifies a length of time to wait for an event to occur before exiting this routine struct timeval contains the following members tv sec Number of seconds to wait tv usec Number of microseconds to wait 5 41 2004 Treck Incorporated Treck Real Time TCP IP User s Manual If the total time is less than one millisecond se ect will return immediately to the user The resolution of this timer is equal to the system tick length the amount of time between calls to t TimerUpdate tfTimerUpdatelsr Parameters Parameter Description numberSockets Biggest socket descriptor to be tested plus one readSocketsPtr The pointer to a mask of sockets to check for a read condition writeSocketsPtr The pointer to a mask of sockets to check for a write condition exceptionSockets Ptr The pointer to a mask of sockets to check for an exception condition Out of Band data timeOutPtr The pointer to a structure containing the length of time to wait for an event before exiting Returns Value Meaning 20 Number of sockets that are ready 0 Time limit exceeded l
491. orma tion on to the callback functions Returns Value Meaning TM ENOERROR Competed successfully TM ENOENT Call back function failed or told tfNetStat to stop TM EINVAL One of the passed in parameter is invalid 6 138 ttNtEntryCBFuncPtr int ttNtEntryUPtr ttUserGenericUnion ttUserGenericUnion Description Application Reference ttNtEntryCBFuncPtr NtEntryPtr genParaml genParam2 This is a callback interface definition it s passed as the second parameter to tfNetStat tfNetStat calls this function back for handling each of the entries found Parameters Parameter NtEntryPtr genParaml genParam2 Returns Value TM ENOERROR TM ENOENT Description Points to a union holding the information of an entry The function needs to access the appropriate union member to get the entry Generic parameter passed into tfNetStat Generic parameter passed into tfNetStat Meaning tell tfNetStat to continue tell tfNetStat to stop 6 139 Treck Real Time TCP IP User s Manual tfNtGetRteHeaderStr char tfNtGetRteHeaderStr char buffer int sizePtr Description Get a string of the routing table header with major fields Parameters Parameter Description Buffer buffer to hold the result string Its size should be TM NT ENTRY STR LEN bytes SizePtr In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Returns
492. orporated Introduction to TCP IP The Address Resolution Protocol ARP The Address Resolution Protocol ARP is a low level protocol used to bind addresses dynamically To better understand this concept look at Figure 1 11 This shows that the host H wants to know a machines IP address B To resolve this host H broadcasts a special packet that asks the host with a specific IP address to respond with its physical address All hosts receive the request but only B recognizes its IP address and sends a reply that contains its physical address When host H receives the reply from host B it uses its physical address to send the Internet packet directly to B E A B H C D Fig 1 11 ARP Transmission Sequence When a host makes a broadcast to all the machines on a network it makes every machine on the network process the broadcast data This can be very costly and time consuming To reduce communication costs and time machines that ARP maintains a cache of recently acquired IP to physical address bindings so they do not have to use ARP repeatedly Whenever a computer receives an ARP reply it saves the senders IP address and corresponding hardware address in its cache for successive lookups When transmitting a packet a computer always looks in its cache for a binding before sending an ARP request If a computer finds the desired binding in its ARP cache it need not send a broadcast
493. orporated Treck Real Time TCP IP User s Manual tfRecvinterface include lt trsocket h gt int tfRecvInterface ttUserInterface interfaceHandle Function Description This function is used to start processing of an incoming packet from the device driver It first calls the driver s receive routine and then begins processing of the packet The packet is processed in the context of the caller of this function Parameters Parameter Description interfaceHandle The Interface Handle of the device to receive data from Returns Value Meaning 0 Success TM ENOBUFS Insufficient memory to complete the operation 5 176 2004 Treck Incorporated Programmer s Reference tfRecvScatinterface include lt trsocket h gt int tfRecvScatInterface ttUserInterface interfaceHandl Function Description This function is used to start processing of an incoming packet from the device driver and can handle scattered data within a single frame Gather Read When the user has been notified that an incoming packet has arrived via either tfCheckReceiveInterface or tfWaitReceiveInterface it then calls tfRecvScatInterface so that the stack can call the driver scattered receive function and retrieve the data tfRecvScatInterface first calls the driver s scattered recv routine as specified in the tfUseInterfaceScatRecv API and then begins processing of the packet The packet 1s processed in the context of the caller of this f
494. ot include multicast routing A host group can only be joined once on a given interface This will prevent multiple sockets on the IP host from sharing the same multicast address i e only one process on the IP host could receive multicast packets for a given multicast destination IP address No loop back of multicast packet is allowed 7 55 2004 Treck Incorporated Treck Real Time TCP IP User s Manual drvloctiFunc include lt trsocket h gt void drvioctlFunc ttUserInterface interfaceHandle int flag void optionPtr int optionLen Function Description drvloctlFunc is a pointer to a function provided by the user and given to the Treck stack as the 8 parameter of the tfAddInterface function The Treck TCP IP stack will call the driver ioctl function with either TM DEVICE SET MCAST LIST or TM DEVICE SET ALL MCAST as de scribed below The driver does not have to maintain a list of currently enabled multicast addresses since the stack will do that and passes the complete list every time a new multicast address needs to be added or deleted Parameters Parameter Description interfaceHandle The interface handle of the driver s ioctl routine to call flag See below optionPtr Pointer to a flag specific param eter See below optionLen Length of the option 7 56 2004 Treck Incorporated Flag Parameter TM DEV SET MCAST LIST TM DEV SET ALL MCAST Returns Value 0 NONZERO Optional Protocols
495. ote to use or the Secondary DNS server that we want to use Se the section setting a PPP IP Address Default Don t Allow 7 93 2004 Treck Incorporated Treck Real Time TCP IP User s Manual PPP PPP_PROTOCOL Option Name Len Meaning TM PPP SEND BUFFER SIZE 2 Length of data buffered by the PPP link layer but not beyond the end of a packet before the device driver send function is called Default 1 byte TM IPCP RETRY 1 Sets the maximum number of IPCP config requests that will be sent without receiving a IPCP nak ack reject remoteLocalFlag has no effect Default 10 TM_IPCP_TIMEOUT 1 Sets the IPCP retransmission timeout value in seconds remoteLocalFlag has no effect Default 1 Second TM_PPP_PROTOCOL Option Name Len Meaning TM PPP SEND BUFFER SIZE 2 Length of data buffered by the PPP link layer but not beyond the end of a packet before the device driver send function is called Default 1 byte Setting a PPP IP address The following applies to all of the IP Address optionNames TM IPCP IP ADDRESS TM IPCP DNS PRI and TM IPCP DNS SEC e IftfPppSetOption is not used with the IP Address optionName default then the remote will not be allowed to request its IP and or DNS IP addresses e ftfPppSetOption is called with the IP Address optionNames remoteLocalFlag TM PPP OPT ALLOW and optionValuePtr points to an IP address whose value is 0 0 0 0 then the remote will be allowed to request that its IP DNS
496. ototype 6 41 Treck Real Time TCP IP User s Manual Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM ENOTLOGIN TM_EINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP FILENAVAIL TM FTP XFERSTART TM FTP FILEOKAY TM FTP DATAOPEN TM FTP XFERABOR TM FTP NOTLOGIN Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Requested file action not taken file unavailable Data connection already open transfer starting File status okay about to open data communications Can t open data connection Connection trouble closed transfer aborted TM FTP LOCALERR Requested action aborted local error in processing Not logged in Application Reference tfFtpFreeSession include lt trsocket h gt int tfFtpFreeSession ttUserFtpHandle ftpSessionPtr Function description This function frees resources associated with specified FTP session Should be called by a user when a session has completed Parameters Parameter Description fipSessionPtr FTP session handle Returns Value Meaning TM ENOERR
497. ou would design for your system An example of one of our build batch files is as follows File ucosx86l bat echo off if 1 goto usage del treck lib call build 1186cc TM KERNEL UCOS X86 call buildlib 1861ib goto end usage echo 0 builds Treck TCP IP for the Intel x86 Real Mode Processor echo running under uC OS v1 1 LARGE MODEL echo echo Usage echo 0 compiler echo echo Compilers supported echo Microsoft C 6 0 MC echo Borland C 5 0 BC echo echo Example 0 MC end Your build batch file does not need to be nearly this complex It can be as simple as echo off del TRECK LIB call call build bcl86cc buildlib bc861ib You then use this file to build the TCP IP library to link with your application kernel and device driver This way you do not need to call build and buildlib from the DOS command prompt 4 21 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 4 Creating an RTOS Kernel Interface This section describes how to setup the RTOS Kernel Interface Treck Real Time TCP IP is designed so that it can use nearly any Real Time Operating System If you do not have an RTOS then you will still need to read this section so that you can understand how the No RTOS version of the kernel interface is put together There are already pre configured RTOS kernel Interfaces These are located below the SOURCE directory in the following locations Pro
498. ough sockets to open the RIP socket TM ADDRINUSE Another socket is already bound to the RIP UDP port TM EALREADY tfUseRip has already been called successfully 5 225 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Timer Interface API tfTimerExecute include lt trsocket h gt void tfTimerExecute void Function Description This function is used to execute timers that have expired Parameters None Returns Nothing 5 226 2004 Treck Incorporated Programmer s Reference tfTimerUpdate include lt trsocket h gt void tfTimerUpdate void Function Description This function updates the internal Treck timers It tells them that one clock tick has passed This call cannot be made from an Interrupt Service Routine Note The integrator must decide if the Treck timers should be updated from an ISR main loop or a timer task and choose this call or tfTimerUpdatelsr Parameters None Returns Nothing 5 2277 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfTimerUpdatelsr include lt trsocket h gt void tfTimerUpdateIsr void Function Description This function updates the internal Treck timers It tells them that one clock tick has passed This call is designed to be called from an Interrupt Service Routine Note The integrator must decide if the Treck timers should be updated from an ISR main loop or a timer task and choose this
499. partially sent In that case the Treck stack will ensure that at least a minimum Ethernet size packet will be sent Re transmission of buffers that have been queued to the device transmit queue If a new buffer is being sent and the device transmit queue is not empty the Treck stack will first try and empty the device transmit queue If it fails to empty it completely then it will try to queue the current buffer to the device transmit queue storing the buffer pointer data length and flag in the next available slot at the end of the Treck device transmit queue Also when fSendCompletelnterface is called the Treck stack will try and empty the device transmit queue but only if t fSendCompleteInterface is not called from the device driver send function to avoid recursion Also the user should call 4 54 2004 Treck Incorporated Integrating into Your Environment tfloctlInterface periodically with the TM DEV IOCTL EMPTY XMIT FLAG flag to try and flush the Treck device transmit queue Note Using a Treck device transmit queue is not allowed for a SLIP or PPP serial device interface because the SLIP or PPP link layer functions send data to the device driver in a unique per interface buffer Since the same per interface buffer is being re used a pointer to it cannot be kept in the device transmit queue Example on using a device transmit queue of a 1000 entries for a given interface void main void ttUserInterface interfaceHandl
500. peed up the process of link failure in which case it should return a value greater than l NOTE Your link quality monitoring function is called with the device locked You cannot call any LOM public API functions from the monitoring function doing so will result in deadlock if you have define d the macro TM LOCK NEEDED to enable locking For example if your monitoring function determines that the link is good outgoing but very bad incoming and you want to send LORs at a faster rate in this case per RFC 1989 you cannot call LqmSendLinkQualityReport or tfLqmSetLqrTimerPeriod directly from your monitoring function since doing so will result in deadlock Instead have your monitoring function set a flag which you can then poll in another task or in your main polling loop that can then call the appropriate LOM public API functions Parameters Parameter Description interfaceHandle The PPP interface to use this link quality monitoring routine with monitorFuncPtr The function to call to monitor link quality hysteresisMaxFailures Set to 0 if we aren t using any hysteresis otherwise this is the 7 121 2004 Treck Incorporated Treck Real Time TCP IP User s Manual hysteresisSamples Returns Value 0 TM_EINVAL TM EOPNOTSUPP 7 122 2004 Treck Incorporated maximum number of bad link quality counts we are allowed to get back from calls to the user s link quality monitoring function within the specified s
501. pient The receiver takes the information contained in the IP header and places it into the pseudo header format for the purpose of computing the checksum SOURCE IP ADDRESS DESTINATION IP ADDRESS ZERO PROTOCOL UDP LENGTH Fig 1 35 Pseudo Header Format Used to Compute a Checksum UDP Encapsulation The UDP encapsulation format is one that works in the transport protocol layer UDP lies in the layer above the Internet Protocol Layer By concept application programs access UDP which use IP to send and receive datagrams We can see an illustration of this in Figure 1 36 Conceptual Layering Application User Datagram UDP Internet IP Network Interface Fig 1 36 Conceptual Layering of UDP Between Application Programs and IP By layering UDP above IP we can encapsulate a complete UDP message including the UDP header and data into an IP datagram As we learned earlier encapsulation means that the protocol UDP in this case basically inserts the information into a frame and then sends it across the network In the example of UDP it takes the information and attaches its own header to it and sends it to the network 1 51 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The Transport Control Protocol TCP The first thing we need to remember is that TCP is a connection oriented protocol This means that when the TCP protocol is used both sides need send each other some
502. pletelnterface interfaceHandle TM_DEV_SEND_COMPLETE_DRIVER return TM DEV OKAY 6 driverReceive In this routine a received packet is passed back into the protocol stack The stack calls this routine to retrieve a frame from the device driver You can use one of our buffers to store the data from the driver into or you can use your own buffer 4 65 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Special Ethernet Considerations for the driverReceive routine You MUST return an entire frame as the stack does not support Gather Read On RISC processors you should be careful that the IP header will be on a four byte boundary Since the Ethernet header is 14 bytes long this implies that the start of the Ethernet buffer should be on a 2 bytes boundary but not 4 byte boundary If you use our function ffGetEthernetBuffer you are guaranteed that this will be the case If you decide not to use tf GetEthernetBuffer with an Ethernet device you should for optimum performance make sure the Ethernet buffer is aligned on a two byte NOT FOUR BYTE boundary Ethernet Header Offsets When Long Word Aligned 0 6 12 14 Destination Addr Source Addr Type IP Header Notice that the IP Header does not start on a long word boundary This would not work on most RISC processors On other processors this may result in poor performance however processors such as the M68EN360 require that the received data appea
503. point link layers such as PPP or SLIP 4 81 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Device Driver Scattered recv Gather Read Description By default the stack expects all data within a frame given by the user device driver recv function to be contiguous Some device drivers support receiving data within a frame in scattered buffers because it is more efficient The interface to the device driver recv interface can be optionally modified to allow it TM_USE_DRV_SCAT_RECV First in order to allow a scattered device driver recv TM USE DRV SCAT RECV need to be defined in trsystem h Modified driver recv routine Description The user driverRecv function API need to be modified to support giving scattered data within a frame to the stack As in the case of the non scattered driver recv API the user can choose to either use pre allocated stack buffers or non stack buffers to store the data into The scattered driverRecv function takes four parameters as shown below int devScatRecvFunc ttUserInterfac interfaceHandle ttDruBlockPtrPtr uDevBlockPtrPtr int uDevBlockCountPtr int flagPtr devScatRecvFunc Parameters The modified user device driver recv function will be responsible for initializ ing uDevBlockPtrPtr uDevBlockCountPtr flagPtr Parameters Meaning interfaceHandle Initialized by the caller as before uDevBlockPtrPtr Upon return from the device driver s
504. porated Treck Real Time TCP IP User s Manual Counting Semaphores in the Treck Stack Description The Treck stack uses an operating system s existing counting semaphores If your operating system does not support counting semaphores Treck can use your OS s event flag mechanism to create its own Using an OS s existing counting semaphores is typically a more efficient method We have two separate counting semaphore versions The first method will grant counting semaphore requests by task priority and is implemented in the kernel trcousem c module The second method lighter version will grant counting semaphore requests in FIFO First In First Out order and is imple mented in the kernel trctsem2 c module Counting Semaphore Implementation with task priority order The user must call the following functions This may require some data type modifications 1 The user must call tfTaskInit prior to calling tfStartTreck and prior to launching any task that utilizes the Treck task 2 Before launching a task that utilizes the Treck stack the user must call tfTaskRegister for that task passing the taskIdPtr filled out by tfKernelGetCurrentTaskld and set the priority ofthe task The task index of the particular task will be returned An index bigger than or equal to TM NUMTSK indicates an overflow or a failure 3 The data type for the task ID may also need modification It is assumed that the task ID can be stored as an integer If
505. porated Treck Real Time TCP IP User s Manual tfKernelError include lt trsocket h gt void tfKernelError char functionName char errorMessage Function Description RTOS SPECIFIC This function is used to report an error and stop the system Debug Only Parameters Parameter Description functionName The Null terminated string contain ing the function name where the error occurred errorMessage The Null terminated string contain ing the error message Returns Nothing 5 232 2004 Treck Incorporated Programmer s Reference tfKernelFree include lt trsocket h gt int tfKernelFree void memoryBlockPtr Function Description RTOS SPECIFIC This function is used to free a block of memory back to the RTOS Parameters Parameter Description memoryBlockPtr The pointer to the area of memory to free Returns Value Meaning 0 Operation completed successfully l An error occurred 5 233 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernellnitialize include lt trsocket h gt void tfKernelInitialize void Function Description RTOS SPECIFIC This function is used to initialize the Kernel interface Parameters None Returns Nothing 5 234 2004 Treck Incorporated Programmer s Reference tfKernellnstallsrHandler include lt trsocket h gt void tfKernelInstalIsrHandler ttUserIsrHandlerPtr handlerPtr unsigned long offset Functi
506. previous request For retransmissions the Identifier MAY remain unchanged On reception the Identifier field of the Echo Request is copied into the Identifier field of the Echo Reply packet The user is responsible for incrementing echoRequestld as appropriate to ensure that the above RFC requirements on the use of the Identifier field are met Since poor link quality can result in no Echo Reply message being received after an Echo Request message was sent ttPppSendEchoRequest can be used to implement some level of link quality monitoring This is especially useful when PPP LOM is not supported by the peer on the link 7 124 2004 Treck Incorporated Optional Protocols The function prototype for the function called to process received LCP Echo Reply messages specified by echoReplyFuncPtr is defined as follows int myHandleEchoReply ttUserInterfac interfaceHandle ttUser8Bit echoRequestId const char dataPtr int dataLen Parameters Parameter interfaceHandle echoRequestld dataPtr echoReplyFuncPtr Returns Value 0 TM_EINVAL TM ENETDOWN TM EMSGSIZE TM ENOBUFS Description The PPP interface to send the Echo Request message on A unique ID for the Echo Request message This can be used to match Echo Request messages with their associated Echo Reply messages Pointer to the data to send in the Echo Request message dataLen Length of the data in bytes to send in the Echo Request m
507. ption at the IPPROTO TCP level as described in the setsockopt API page Warning Uncommenting this macro will make TCP less efficient and will disable Path MTU discovery and TCP Selective Acknowledgements TM DISABLE DYNAMIC MEMORY By default when the Treck stack allocates blocks of memory of size less than 4096 bytes it keeps them in its internal buffer management system when they are freed instead of releasing them to the heap Adding this macro will prevent the compilation ofthe Treck internal buffer management system code thereby reducing code size However this is not recommended as this will reduce performance since this will force the Treck stack to call the Operating system every time it needs to allocate or free a block of memory If the user has not disabled the Treck Dynamic Memory i e not defined this macro then the user can free all the unused dynamic memory held by the Treck stack at any time by calling the API tfFreeDynamicMemory TM ARP UPDATE ON RECV Enable this macro if you want the stack to update the ARP cache for every packet that is being received This will prevent the ARP cache entry from timing out and will prevent the stack from having to send an ARP request every 10 minutes but at the cost of code size and speed since every incoming packet needs to be checked and the ARP entry updated then TM OPTIMIZE SPEED This performance macro is used to optimize the code in favor of speed over size When using
508. ptional Protocols 7 129 2004 Treck Incorporated Appendix A Configuration Notes 2004 Treck Incorporated Treck Real Time TCP IP User s Manual A 2 2004 Treck Incorporated Configuration Notes Configuring IP Forwarding and IP Fragmentation IP Forwarding By default IP Forwarding is not enabled in the Treck stack To enable IP Forwarding the user must turn on the IP forwarding option after the tfStartTreck call errorCode tfSetTreckOptions TM OPTION IP FORWARDING 1UL In addition each device that the user wants to forward packets from and to should be configured with the TM DEV IP FORW ENB bit set in the tfOpenInterface flag parameter See the tfOpenInterface description for a list of the tfOpenInterface parameters Removing IP Fragmentation and IP Reassembly Code To save code space the user can optionally not compile the IP fragmentation and IP reassembly code in the Treck stack Warning in this case no IP fragmentation or IP reassembly will ever take place in the Treck stack To do that delete the following macro from trsystem h define TM IP FRAGMENT IP Fragmentation By default if the TM IP FRAGMENT macro is defined in rsystem h then IP Fragmentation is turned on in the Treck stack To disable IP Fragmentation the user must turn off the IP Fragmentation option after the tfStartTreck call as follows errorCode tfSetTreckOptions TM OPTION IP FRAGMENT OUL A 3 2004 Treck Incor
509. r Kernel Error Attempt to free more than alloc a buffer This can be a sign of corrupted memory See the Corrupted Memory section above This can also be an error in the application For example attempting to free a zero copy send buffer that has already been given to the stack will cause this error Ping and UDP work but TCP does not tfOpenInterface has enabled scattered send but the driver either does not support scatter send or device driver scatter send does not work properly Try disabling scatter send in tfOpenInterface and testing again If you have added an assembly checksum routine see the Tech Note included on the distribution CD it might not be working correctly Temporarily use the standard C version of the checksum routine to test this This will only be the case if checksums have been disabled for UDP Ping works but UDP and TCP do not This is frequently actually a routing problem If there was no call made in the application to add a default gateway or a static route for the final destination of the packet this problem will occur If you have added an assembly checksum routine see the Tech Note included on the distribution CD it might not be working correctly Temporarily use the standard C version of the checksum routine to test this Driver Will Not Send and or Receive Data The ISR is not installed correctly The interrupts are occurring correctly but the ISR is not being executed
510. r freeing Or TM DEV SCAT RECV USER BUFFER if the user used its own buffers tfUselnterfaceScatRecv The Treck stack need to be made aware that the modified driver recv function need to be used instead of the default driver recv function So after the call to tfAddInterface and before the call to tfOpenInterface the user need to call tfUseInterfaceScatRecv int tfUseInterfaceScatRecv ttUserInterface interfaceHandle ttDevScatRecvFunc devScatRecvFunc tfRecvScatinterface Instead of calling tfRecvInterface the user needs to call tfRecvScatInterface The modified device driver recv function is itself called from within tfRecvScatInterface 4 84 2004 Treck Incorporated Integrating into Your Environment Scattered recv contiguous length threshold used in tfRecvScatinterface Description tfRecvScatInterface will automatically copy up to a per device configurable recv contiguous header length if the data received in the first link of a device driver scattered recv is below this threshold In that case a new buffer is allocated by the stack and the threshold number of bytes but not more than the total length of the buffer is copied Compile time value TM DEV DEF RECV CONT HDR LENGTH Default threshold value is given by the TM DEV DEF RECV CONT HDR LENGTH macro and is by default defined to 68 for IPv4 and 88 for IPv6 It can be defined in trsystem h to overwrite the default value Run time modificati
511. r on a long word boundary This is the why we subtract 2 bytes from the pointer returned by GetEthernetBuffer in our quicc driver Ethernet Header Offsets When Short Word Aligned 2 8 14 16 Destination Addr Source Addr Type IP Header tfGetEthernetBuffer does this short word alignment for you If you do not use tfGetEthernetBuffer and allocate your own buffers then you should verify that they are short word aligned We will show examples of using your own buffer or using ffGetEthernetBuffer Special PPP Considerations For PPP you do not need to pass an entire frame back to the protocol stack You simply pass as much or as little as you wish as the PPP Link Layer will determine the framing automatically 4 66 2004 Treck Incorporated Integrating into Your Environment An Example of using tfGetEthernetBuffer to create a buffer to store the incoming data into int myDeviceReceive ttUserInterface interfaceHandle char TM FAR TM FAR dataPtr int TM FAR dataLength ttUserBufferPtr bufHandlePtr int errorCode Get a buffer to store the data into dataPtr tfGetEthernetBuffer bufHandlePtr if dataPtr char TM FAR 0 No memory so return an error errorCode TM_DEV_ERROR else Copy from the device driver into the buffer tfMemCpy dataPtr deviceRecvDataPtr deviceDataLength Save the length dataLength deviceDataLength Good return value errorCode TM DEV OKAY
512. r stops sending and or receiving data Other problems sisi sisi 2004 Treck Incorporated 2004 Treck Incorporated Introduction to TCP IP 2004 Treck litu pui awu Treck Real Time TCP IP User s Manual 2004 Treck Incorporated Introduction to TCP IP Short Background of the Internet The TCP IP protocol suite is also known as the Internet Protocol Suite since it is used to move data across the Internet The Internet is a worldwide network of computers located at many different companies institutions and government offices The Internet was started over three decades ago Realizing the need for a common method to share data and send messages in electronic form the US Department of Defense DOD started the Internet project within the Defense Advanced Research Projects Agency The first Internet was called ARPANET and started operation in 1968 As more and more researchers joined ARPANET people started to realize the need for a global network In 1979 a group called the Internet Control and Configuration Board ICCB was founded by ARPA and met to coordinate and structure the architecture of the now growing ARPANET In 1980 the ARPANET was extended to a global network when the computers that needed network connectivity were outfitted with the TCP IP protocol suite In 1983 the MILNET was created to allow military sites to have a separate network from the researchers Both of these networks ARPANET for researchers and M
513. r the Microtec Research Mentor Graphics 68K compiler RTOS Kernel Environments These macros are used for various predefined kernels With these macros you can use one of the real time operating systems listed below and most of the above settings will be set for you Feel free to use these as examples if you decide to add a different RTOS TM KERNEL ELX 86 This is used for the ELX 86 RTOS TM KERNEL UCOS X86 This is used for uC OS for the Intel Platform TM KERNEL UCOS PPC This is used for uC OS for the Motorola Power PC Platform TM KERNEL UCOS CPU32 This is used for uC OS for the Motorola CPU32 Core 683xx TM KERNEL UCOS MIPS This is used for uC OS for the MIPS processor TM KERNEL UCOS XSCALE This is used for uC OS for the XSCAL processor TM KERNEL UCOS SH2 This is used for uC OS for the SH2 platform TM KERNEL AMX CPU32 This is used for AMX for the Motorola CPU32 Core 683xx 4 17 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM KERNEL THREADX ARM7 This is used for ThreadX for the ARM7 platform TM KERNEL AMX X86 This is used for AMX for the Intel Platform TM KERNEL THREADX CPU32 This is used for ThreadX for the Motorola CPU32 Core 683xx TM KERNEL DOS X86 This is used for DOS for the Intel Platform TM KERNEL CMX C16X This is used for CMX RTOS for the Siemens C16X processors TM KERNEL NONE EZ80 This is used for Zilog EZ80 target board no OS TM KERNEL NONE H8S This is used for Hi
514. rHandle int errorCode i In order to use this no copy loop back driver Add the following macros to trsystem h define TM_LOOP_TO_DRIVER define TM_USE_DRV_SCAT_RECV define TM_USE_DRV_ONE_SCAT_SEND replace tfAddInterface with tfUseScatIntfDriver I e I In the examples directory txscatlp c and txscatdr c use the no copy loop back driver 4 87 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 10 Testing Your New Device Driver If you wrote your own device driver or modified ours you are now ready to begin testing on the network You will need some tools to do this correctly if you do not already have them Your most important tool when testing a device driver is a network analyzer There are many to choose from The cost ranges from a few hundred dollars to tens of thousands of dollars If you are in a hurry and are on a tight budget we suggest that you visit the following web site http www klos com At Klos Technologies they have both Ethernet and PPP analyzers that run on a PC under DOS for a few hundred dollars When testing your device driver your analyzer is your best friend next to the support engineer at Treck Inc Things to test for Y Make sure that you are sending packets If you are not then make sure that your driver s send routine is being called Set a break point with your debugger and step through your drivers send routine Y Make sure receive p
515. rameter Blocking Mode In blocking mode tfFtpdUserStart should be called from a task tfFtpdUserStart will not return unless an error occurs and will block and wait for incoming connections and execute the FTP server code in the con text of the calling task Choose the blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfFtpdUserStart will return immediately after listening for incoming connections It is the user s responsibility to then call tfFtpdUserExecute periodically to execute the FTP server code Choose the non blocking mode if you do not have an RTOS Kernel 2 tfF tpdUserExecute If the user had called tfFtpdUserStart in non blocking mode then the user needs to call tfFtpdUserExecute periodically If the user had called tfFtpdUserStart in blocking mode then there is no need to call tfFtpdUserExecute 3 tfFtpdUserStop The user calls tfFtpdUserStop to close the FTP server socket and kill all 6 20 existing FTP connections tfF SChangeDir tfF SChangeParentDir tfFSCloseDir tfFSCloseFile tfFSDeleteFile tfFSGetNextDirEntry tfFSGetUniqueFileName tfFSGetWorkingDir tfFSMakeDir tfFSOpenDir tfFSOpenFile tfFSReadFile tfFSReadFileRecord Application Reference File System Interface from the FTP server Entry points from the FTP server to the file system Change current working directory Change current working directory to parent Directory Close a directory th
516. rated Len Meaning Any Sets the username to use with CHAP Client Default NONE Any Sets the secret to use with CHAP Default NONE 1 Sets the maximum number of CHAP challenges that will be sent without receiving a CHAP response remoteLocalF lag has no effect Default 10 1 Sets the CHAP retransmission timeout value in seconds remoteLocalFlag has no effect Default 3 Seconds 1 Add a CHAP algorithm You don t need to add TM_CHAP_MDS5 because it is automatically added when TM PPP CHAP PROTOCOL is used You may add TM CHAP MSVI in order to support MS CHAP version 1 1 Delete a CHAP algo rithm You may delete TM CHAP MDS standard CHAP or TM CHAP MSVI MS CHAP version 1 Meaning Success protocolLevel or optionName 1s invalid The option value or length is invalid optionLength Optional Protocols optionLength should be the size of the data type option ValuePrtr is pointing to except for the TM PAP USERNAME TM PAP PASSWORD TM CHAP USERNAME and TM CHAP SECRET options where optionValuePtr points to the first byte of an array and where optionLength is the size of the array optionValuePtr 1s pointing to The data types are as follows Protoco
517. re delivered to your driver send routine If your device driver send function returns an error for a given buffer which has the TM USER BUFFER LAST flag set then you do not need to call tfSendCompleteInterface for that buffer In that case if a Treck device transmit queue is used the Treck stack will try and queue the buffer to the device transmit queue and try to send it later If it fails to queue the buffer to the device transmit queue or if there is no device transmit queue then the Treck stack will remove the corresponding packet from the send queue and free it PPP or SLIP serial devices The Treck PPP link layer code and Treck SLIP link layer code will send scattered data to SLIP or PPP serial devices This 1s because of the PPP asynchronous byte stuffing or because of SLIP escaping special characters The Treck PPP link layer code and Treck SLIP link layer code will copy the stuffed bytes or escaped bytes along with the packet bytes into a single intermediate buffer That single intermediate buffer will be repeatedly sent to the driver when it is full or when the end of the packet has been reached By default the intermediate buffer size is one byte Note that the Treck PPP link layer code or Treck SLIP link layer code will re use the same intermediate buffer so in a serial device driver send you need to copy the buffer data immediately If your serial device driver can handle more than one byte at a time you can change the si
518. re of the following MSG_DONTWAIT Do not wait for data but rather return immediately MSG OOB Read any out of band data present on the socket rather than the regular in band data MSG PEEK Peek at the data present on the socket the data is returned but not consumed so that a subsequent receive operation will see the same data 5 35 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value gt 0 0 1 recv will fail i TM_EBADF TM_ENOBUFS TM EMSGSIZE TM EWOULDBLOCK TM ESHUTDOWN TM_EINVAL TM ENOTCONN TM EHOSTUNREACH 5 36 2004 Treck Incorporated Meaning Number of bytes actually received from the socket EOF An error occurred The socket descriptor is invalid There was insufficient user memory available to complete the operation The socket requires that message be received atomically and bufferLength was too small The socket is marked as non blocking or the MSG DONTWAIT flag is used and no data is available to be read or the MSG OOB flag is set and the out of band data has not arrived yet from the peer The remote socket has closed the connection and there is no more data to be received TCP socket only One of the parameters is invalid or the MSG OOB flag is set and either the SO OOBINLINE option is set or there is no out of band data to read or coming from the peer Socket is not connected No route to the connected host Pr
519. reachable Source Quench Redirect change a route Echo Request Time Exceeded for a Datagram Parameter Problem on a Datagram Timestamp Request Information Request obsolete Information Reply obsolete Address Mask Request Address Mask Reply Fig 1 32 ICMP Message Types 1 47 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Testing Destination Reachability and Status Ping TCP IP protocols provide facilities to help network managers or users to identify network problems One of the most frequently used debugging tools invoke the ICMP echo request and echo reply messages A host or router sends an ICMP echo request message to a specified destination Any machine that receives an echo request formulates an echo reply and returns it to the original sender The request sends an optional data area the reply contains a copy of the data sent in the request The echo request and associated reply can be used to ensure that a destination is reachable and responding Because both the request and reply travel in IP datagrams successful receipt of a reply verifies that major pieces of the transport system work First IP software on the source computer must route the datagram Second intermediate routers between the source and destination must be operating and must route the datagram correctly Third the destination machine must be running it must at least respond to interrupts and both ICM
520. reated with socket The address ofthe target is given by to with toLength specifying its size Ifthe message is too long to pass atomically through the underlying protocol then is returned with the socket error being set to TM EMSGSIZE and the message is not transmitted A return value of 1 indicates locally detected errors only A positive return value does not implicitly mean the message was delivered but rather that it was sent If the socket does not have enough buffer space available to hold the message being sent and is in blocking mode sendto blocks If it is in non blocking mode or the MSG DONTWAIT flag has been set in the flags parameter 1 is returned with the socket error being set to TM EWOULDBLOCK The select call may be used to determine when it is possible to send more data 5 46 2004 Treck Incorporated Parameters Parameter socketDescriptor bufferPtr bufferLength toPtr toLength flags Programmer s Reference Description The socket descriptor to use to send data The buffer to send The length of the buffer to send The address to send the data to The length of the to area pointed to by toPtr See below The flags parameter is formed by ORing one or more of the following MSG DONTWAIT MSG DONTROUTE Returns Value gt 0 Si TM EHOSTDOWN sendto will fail if TM EBADF TM ENOBUFS TM BINVAL TM EHOSTUNREACH TM EMSGSIZE TM EPROTOTYPE TM EWOULDBLOCK Don t
521. rence Description The socket descriptor to register the call back for The function pointers of the user function to call when one or more of the registered events occur See below for function prototype One or more of the flags described below and OR ed together Description Register for a connection complete call back TCP socket only Register for a call back when a remote host has established a connection to our listening server TCP socket only Register for a call back when incoming data has arrived from our peer Register for a call back when out of band data has arrived from our peer TCP socket only Register for a call back when the data that we are sending has been acked by the peer host TCP socket only Register for a call back when our peer has shutdown the connection TCP socket only Register for a call back when an error occured on the connection Register for a call back when the peer has sent a reset on the connection TCP socket only Register for a call back when the user issued close has completed TCP socket only Indicates that there is more room on the send queue The user can now send more data on the connection given by the socketDescriptor 5 117 2004 Treck Incorporated Treck Real Time TCP IP User s Manual When one or more of these events occur the Treck stack calls the user supplied call back function socketCB Func socketDescriptor eventFlags where s
522. ress include lt trsocket h gt int tfAddInterfaceMhomeAddress ttUserInterface interfaceHandle ttUserlIpAddress ipAddress unsigned char multiHomeIndex y Function Description Add a multihome IP address to the interface without adding it to the routing table This allows the Treck stack for example to assume the IP address identity of another host on another network and therefore to allow a server application on the Treck stack to get the packets whose destination is for that other host and offload some of the work from that other host server If the interface uses the Ethernet link layer then the user should also add a proxy arp entry for the IP address it is assuming An example would be errorCode tfAddInterfaceMhomeAddress myInterfaceHandle inet addr 208 229 201 61 unsigned char 1 Parameters Parameter Description interfaceld The device entry This is returned by tfAddInterface ipAddress Extra multihome IP Address multiHomelndex The index for this IP address for multihoming Because we are adding an additional IP address without really configuring the interface the interface should already have been configured and this multihomelndex should be bigger than 0 5 133 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value 0 TM_EADDRNOTAVAIL TM ENOBUFS TM_EINVAL TM EALREADY 5 134 2004 Treck Incorporated Meaning Success Attempt to configure
523. ress e g treck com translates to 208 229 201 1 tfDnsGetHostByAddr Translates the given IP address to its corresponding hostname also called a reverse lookup tfDnsGetMailHost tfDnsGetNextMailHost Returns the first MX record in the list tfDnsGetMailHost and then retrieves any records that follow tfDnsGetNextMailHost Please see below for more information on using MX records Any of the user interface calls may return an error from theTreck stack or from the DNS server The errors from the Treck stack are the normal socket errors e g TM ENOMEM TM EHOSTUNREACH Errors returned from the DNS server are outlined below derived from RFC 1035 TM_DNS_EFORMAT TM_DNS_ESERVER TM DNS ENAME ERROR TM DNS ENOT IMPLEM TM DNS EREFUSED TM DNS EANSWER Non Blocking Mode Application Reference Format error The name server was unable to interpret the query Server Failure The name server was unable to process this query due to a problem with the name server Name Error Meaningful only for responses from an authoritative name server this code signifies that the domain name referenced in the query does not exist Not Implemented The name server does not support the requested kind of query Refused The name server refuses to perform the specified operation for policy reasons For example a name server may not wish to provide the information to the particular requester or a name ser
524. return immediately Send out of band data on sockets that support this notion The underlying protocol must also support out of band data Only SOCK STREAM sockets created in the AF INET address family support out of band data The SO DONTROUTE option is turned on for the duration of the operation Only diagnostic or routing programs use it Meaning Number of bytes actually sent on the socket An error occurred The socket descriptor is invalid One of the parameters is invalid the bufferPtr is NULL the bufferLength is 0 or an unsupported flag is set There was insufficient user memory available to complete the operation Non TCP socket only No route to destination host The socket requires that message to be sent atomically and the message was too long The socket is marked as non blocking and the send operation would block Socket is not connected User has issued a write shutdown or a tfClose call TCP socket only 5 45 2004 Treck Incorporated Treck Real Time TCP IP User s Manual sendto include lt trsocket h gt int sendto int socketDescriptor char bufferPtr int bufferLength int flags const struct sockaddr toPtr int toLength Function Description sendto is used to transmit a message to another transport end point sendto may be used at any time either in a connected or unconnected state but not for a TCP socket socketDescriptor is a socket c
525. returned by tfFsUserLogin pathNamePtr Pointer to a null terminated string containing file name flag Open flag TM FS READ TM FS WRITE TM FS APPEND type File type TM TYPE ASCII or TM TYPE BINARY structure File structure TM STRU RECORD or TM STRU STREAM Returns Value Meaning void 0 Failure fileDataPtr Pointer to newly allocated file data structure 6 101 Treck Real Time TCP IP User s Manual tfF SReadFile include lt trsocket h gt int tfFSReadFile void userDataPtr void fileDataPtr char bufferPtr int bufferSize Function description Given the unique user data pointer as returned by tfFSUserLogin and a file data pointer as returned by tfFSOpenFile this function reads up to bufferSize bytes into the buffer It returns the number of bytes actually read 0 if end of file has been reached 1 on error Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin fileDataPtr Pointer to file data structure as returned by tfFSOpenFile bufferPtr Pointer to buffer where to copy the data from the file bufferSize Size in bytes of the buffer Returns Value Meaning gt 0 Number of copied bytes 0 End of file Failure 6 102 Application Reference tfF SReadFileRecord include lt trsocket h gt int tfFSReadFileRecord void userDataPtr void fileDataPtr char bufferPtr int bufferSize int eorPtr Function description Given
526. rface The multi home index is used for interfaces that have more than one IP address Ifthe interface has only one IP address then the Multi home index should be set to zero Parameters Parameter interfaceHandle iflpAddressPtr mutiHomelndex Returns Value 0 TM_EINVAL TM ENETDOWN Description The device driver entry that we wish to get the physical address on A pointer to the location where to store the IP address for the interface An index for multiple IPs Meaning Success Bad parameter Interface multi home index is not configured 5 151 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetNetMask int ttUserInterface ttUserlpAddress unsigned char Function Description tfGetNetMask interfaceHandle netMaskPtr mutiHomeIndex This function is used to get the Net Mask from a given interface The multi home index is used for interfaces that have more than one IP address If the interface has only one IP address then the Multi home index should be set to zero Parameters Parameter interfaceHandle netMaskPtr mutiHomelndex Returns Value 0 TM_EINVAL TM ENETDOWN 5 152 2004 Treck Incorporated Description The device driver entry that we wish to get the net mask for A pointer to a location where to store the Net Mask upon function completion An index for multiple IP s per device Meaning Success Bad parameter Interface multi home i
527. ritev always reads one buffer completely before proceeding to the next On success writev return the number of bytes actually written this number may be less than the total of all ofthe iov len values if there is not enough space on the send queues Parameters Parameter Description socketDescriptor The socket descriptor to write data to iov The list of buffers to gather and send the data from iovent The number of buffers in the list Returns Value Meaning gt 0 Number of bytes actually written 1 An error occurred 5 69 2004 Treck Incorporated Treck Real Time TCP IP User s Manual writev will fail if TM EBADF TM EINVAL TM ENOBUFS TM EMSGSIZE TM EWOULDBLOCK TM ENOTCONN TM ESHUTDOWN 5 70 2004 Treck Incorporated The socket descriptor is invalid The iovent is 0 or less than 0 The sum of the iov len values overflowed an integer There was insufficient user memory available to complete the operation The socket requires that message to be sent atomically and the message was too long The socket is marked as non blocking and all the data could not be written The socket is not connected The user has issued a write shutdown call or a tfClose call TCP socket only Programmer s Reference Socket Extension Calls tfBindNoCheck include lt trsocket h gt int tfBindNoCheck int socketDescriptor const struct sockaddr addressPtr int addressLength Function Descrip
528. river senes e eene eet eti teinte 4 87 Step 10 Testing Your New Device Driver sense 4 88 Proerammner s Reler nt usines Del BSD 4 4 Socket API errant eene E 5 5 AC CEPU 220k 5 5 iun 5 COMMGCE IEEE 5 8 PCCP COTM AMIS C unes 5 11 CLS OCT AN Se nl lie 5 12 BEtSOCKOPE en red ore ent dc n t edt Erde ens 5 13 MAGGI ages educa cesta dde torii m ta aU 5 24 irj pp eres 5 25 Inct AME so costosa re te tte uS 5 26 VCE LR ee E epe eee el cede veste ape eer daar ates 5 27 MLE ESTO octets uer E ca t pM 5 28 tc eM P 5 29 TOI 0 T E A ERE EE 5 30 TORIS i eher te terme eden aes ed Nave p En een 5 31 TOAD tt de tt teen 5 32 PECI anes 5 34 SEA DUO 1 o PE EU D DLL DP 5 37 ITESVDOI sir ide 5 40 SLCC AR TR ue cote orev nn 5 41 SONG ee e e E E 5 43 TOT EPE E AE AAE AAA M A ATA 5 46 SELSOCKODE cac iere E er ee a 5 48 nime AT A E A T A TA 5 60 pnl 5 61 Digo EE 5 63 TO tn 5 64 RCA ote nnt 5 66 nui ER 5 68 D OUT cocotte tme PE USE DT NE 5 69 Socket Extension Calls cscccsssssssssssscssscssscssssssssssssssesssssessssssesssesesseees 5 71 i BindNoGheCck emmener tte 5 71 tiBlockineState s ss r ve
529. rmation Field Padding Establishes the network protocol that sent that datagram and with regard to which it should be interpreted The packet received from the network level protocol to be transmitted over the physical medium under the control of the PPP Establishes the network protocol that sent that datagram and with regard to which it should be interpreted 1 25 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The Protocol Field By default the protocol field is two bytes in length But it may optionally shorten to one byte if both peers agree It is transmitted in Big Endian most significant byte first Notice that in the protocol values in the following table the first byte is always even and the second byte is always odd The reason for this is field compression Protocol field values are defined in RFC 1700 Assigned Numbers The following values given in hexadecimal are of special interest when PPP is used along with TCP and IP 0021 Internet Protocol 002d Van Jacobson Compressed TCP IP 002f Van Jacobson Uncompressed TCP IP 8021 Internet Protocol Control Protocol c021 Link Control Protocol c023 Password Authentication Protocol c025 Link Quality Report C223 Challenge Handshake Authentication Protocol 0000 02ff Network Layer protocols 8000 bfff Network Control Protocols c000 fff Link Layer Control Protocols Fig 1 18 Protocol Field Values
530. rnel TM TRECK_ TASK This macro is used to compile the stack so that it can be used as an independent task When using Treck in this manner no ISR may call any Treck function In this model there are no critical sections and no blocking may occur This model is typically used when the application and the Treck code are in the same task and the device driver sends messages through the operating system to the task It is similar to using Treck without a kernel It may be used with either a preemptive or a non preemptive kernel TM_TRECK_PREEMPTIVE_KERNEL This macro is used to compile the stack so it can be used with a preemptive kernel In this model all critical sections are enabled You may also feel free to make blocking or non blocking calls in this environment This model is the most popular for systems integrating Treck into their environment TM_TASK_RECV This macro is used to notify the stack that a separate blocking receive task will be used It is not required to use a separate receive task However it is usually efficient to do so The receive task will be responsible for processing all received packets from a given interface If more than one interface is defined on the system more than one receive task may be used If you wish to make the decision to use a blocking receive task at run time then you should define this macro A separate blocking receive task can only be used if you are using a real time operating system and you are
531. ro when testing the Treck stack against Ixia s Automated Network Validation Library ANVL TM_USE_AUTO_IP This macro is commented out by default Uncomment this macro if you want to use Auto IP Configuration or want to add collision detection TM_USE_RAW_SOCKET Enable this macro if you want to use raw sockets tfRawSocket which allows you to send data above the IP layer or to send data with an IP header and to receive data with an IP header TM_RAW_SOCKET_INPUT_ICMP_REQUESTS Enable this macro if you want ICMP echo requests and ICMP address mask requests to be delivered to a raw ICMP socket TM_PING_REPLY_BROADCAST Enable this macro if you want the stack to reply to ping echo requests whose destination is a broadcast or a multicast address TM_PING_REPLY_MULTICAST Enable this macro if you want the stack to reply to ping echo requests whose destination is a multicast address implied if TM PING REPLY BROADCAST is enabled TM USE REUSEADDR LIST Enable this macro if you want to use the SO REUSEADDR socket level option with setsockopt which allows you to bind the same port number to multiple sockets using different local IP addresses TM USE PPP MSCHAP This macro is commented out by default Uncomment this macro if you want to use MS CHAP for PPP authentication 4 10 2004 Treck Incorporated Integrating into Your Environment TM_PPP_LQM Enable this macro if you want to use PPP Link Quality Monitoring TM_USE_E
532. rocessing is happening correctly by making sure that the incoming IP application data arrives at the socket Y Try UDP before trying TCP It is a simpler test and helps isolate problems If you are having problems Ensure the IP address and Netmask are set correctly Make sure your hardware is operating correctly Make sure your hardware address is correct and valid Make sure that tfTimerUpdate tf TimerUpdatelsr and tfTimerExecute are being called Make sure your loopback test still runs Make sure that you have interpreted the device user s manual correctly Trying sending packets by directly calling your driver s send routine Make sure that you are passing the correct parameters to the Treck functions Look for compiler warnings in your code Make sure that you actually check the return codes ofthe Treck functions that you call to ensure that an error did not occur Watch out for padding by the compiler Treck data structures are already padded and aligned on 32 bit boundaries SASS SS NSS s Please see Appendix C for detailed driver testing and debugging information 4 88 2004 Treck Incorporated Integrating into Your Environment 4 89 2004 Treck Incorporated Programmer s Reference 2004 Treck Incorporated Treck Real Time TCP IP User s Manual 5 2 2004 Treck Incorporated Programmer s Reference Function List BSD 4 4 Socket API accept bind connect getpeername getsockname getsockop
533. ronment tfKernelTaskYield The function KernelTask Yield is used to yield the CPU and let other tasks run This function is called only if the user uses a transmit task and calls the Treck function ffInterfaceSpinLock from within the device driver send function to let other tasks run and access the device driver routines while waiting for the device driver to be ready to transmit void tfKernelTaskYield void RTOSYield 0 This completes the RTOS interface After you have made these functions map onto your RTOS you are ready to move onto the next phase We suggest that you compile the code that you have written in this phase 4 35 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 5 Hooking in the Timer Now that you have compiled the library and created an RTOS interface you are ready to consider how you must hook in the timer Notice that the timer interface is not part of the RTOS interface This is because the timer interface can be hooked up in different ways These different methods do not depend on the RTOS interface There are two different methods to hook up the timer You must not call any timer functions prior to calling fStartTreck Method 1 Use a Timer Task to Update and Execute the Timers Method 2 Use a Timer ISR to Update the Timers and Execute from either a main line loop or a task These methods are described in more detail below Method 1 A Timer Task to Update and Execut
534. route 1s down target is a host if not set target is a network Use gate way 1f not set target 1s directly connected dynamically installed by daemon or redirect if not set the routing entry is created staticly output through this route Clonable entry Cloned entry Static entry configured by user ttNtArpEntry Description Application Reference Holds the information of an ARP entry for printing typedef struct tsNtArpEntry struct sockaddr_storage ntArpSockAddr ttUser8Bit ntArpHwAddress CCCTM MAX PHYS ADDR 3 4 4 int ntArpHwType int ntArpHwLength ttUser8Bit ntArpDeviceName TM MAX DEVICE NAME 3 4 4 ttNtArpEntry typedef ttNtArpEntry ttNtArpEntryPtr Member Description NtArpSockAddr Destination IP address for the ARP entry ntArpSockAddr ss family indicates the family of the address ntArpSockA ddr addr ipv6 or ntArpSockAddr addr ipv4 has the actual key IP Address NtArpHwAddress Array of unsigned char as the physical address NtArpHwLength Length of the physical address in bytes NtArpHwType Can be one of the below TM NT HWTYPE ETHERNET TM NT HWTYPE TOKENRING TM NT HWTYPE TOKENBUS NtArpDeviceName Name of the device associated with the ARP entry 6 151 Treck Real Time TCP IP User s Manual ttNtTcpEntry Holds the information of a TCP entry for printing typedef struct tsNtTcpEntry 1 ttUser16Bit ntTcpSockDesc ttUser32Bit ntTcpBytesInRecvQ
535. rovide the table header string and convert a netstat entry into a string tfNtGetRteHeaderStr tfNtGetArpHeaderStr tfNtGetTcpHeaderStr tfNtGetUdpHeaderStr tfNtRteEntryToStr tfNtArpEntryToStr tfNtTcpEntryToStr tfNtUdpEntryToStr These data structures are defined for netstat ttNtRteEntry ttNtArpEntry ttNtTcpEntry ttNtUdpEntry ttNtEntryU Note In order to use the netstat tool TM USE NETSTAT must be defined in trsystem h 6 137 Treck Real Time TCP IP User s Manual Public API tfNetStat int tfNetStat ttNtTableId tableld ttNtEntryCBFunctPtr ntEntryCBFuncPtr ttUserGenericUnion genParami ttUserGenericUnion genParam2 Function description This function walks through the Treck internal data For each entry found a ttNtEntryU structure is prepared and passed to the provided ntEntryCBFuncPtr together with the genParam and genParam2 The function walk continues until ntEntryCBFuncPtr returns a value other than TM ENOERROR or when there is no more entry Parameters Parameter Description tableld specifies the table that the user would like to walk output Valid values are TM NT TABLE RTE TM NT TABLE ARP TM NT TABLE UDP TM NT TABLE TCP ntEntryCBFuncPtr Call back function for handling each of the entry The user must implement this call back function genParam1 Generic parameter for passing informa tion on to the callback functions genParam2 Generic parameter for passing inf
536. rovides a mechanism that can allow control information to have precedence over data For example if all hosts and routers honor precedence it is possible to implement congestion control algorithms that are not affected by the by the congestion they are trying to control Bits D T and R specify the type of transport the datagram desires When set the D bit requests low delay the T bit requests high throughput and the R bit requests high reliability Of course it may not be possible for an Internet to guarantee the type of transport requested i e it could be that no path to the destination has the requested property Thus we think ofthe transport request as a hint to the routing algorithms not as a demand If a router knows more than one possible route to a given destination it can use the type of transport field to select one with characteristics closest to those desired For example suppose a router can select between a low capacity leased line and a high bandwidth but high delay satellite connection Datagrams carrying a keystroke from a user to a remote computer could have the D bit set requesting that they be delivered as quickly as possible while datagrams carrying a bulk file transfer could have the T bit set requesting that they travel across the high capacity satellite path Datagram Encapsulation Before we can understand the next fields in the datagram it is important to consider how datagrams relate to physical network frames
537. rporated Ertot Eog pin E semer eee ra eree a CESES EN EEEE FI ESE EAEE E 4 27 Warning Information Logging eee 4 27 Task Suspend and Resume en eere eet eccrine 4 28 ISR Intera ereere erren ea E eree ue co IUE 4 31 Device Interface Routimes eee sissivvicsnsnvenieninie esain 4 32 PHI ernelC Te ALS VST ce ous ood nd atta teer REEERE 4 33 tiKernelPendEYent suite th akandbded machin death ve ce ege ges 4 33 ttKernelISrPOSIBVEllb n rore D rene eee cn ser tud 4 34 t Kemel Task PostEvent erepto eere ne esse dete ceat des 4 34 tiKernelTasl Yield reee aaee e ee ne 4 35 Step 5 Hooking in the Timer ss eene eere ennt nnn nnns 4 36 Method 1 A Timer Task to Update and Execute Timers 4 36 Method 2 A Timer ISR to Update Timers and Execute from Either a Main lane LOOD OE A Taske eroe terea E Ue 4 38 Step 6 Key Things to Start Using Treck ceres 4 39 Step 7 Testing the New Library with a Loopback Test 4 40 Step 8 Using Ethernet or PPP eese eese enses tn ntn stn nnn 4 44 Step 9 Adding a New Device Driver msn 4 45 Device Driver Functions that You May Need to Provide 4 60 Further Device Driver Modifications to allow a device driver to be shared by several Ethernet Interfaces sisi hisser 4 72 Summary of Device Driver API s that are provided to allow a device driver to be shared by several Ethernet in
538. rror occurred If tfPingClose fails the associated error code can be retrieved using tfGetSocketError socketDescriptor TM_EBADF socketDescriptor is not a valid descriptor 6 5 Treck Real Time TCP IP User s Manual tfPingGetStatistics include lt trsocket h gt int tfPingGetStatistics int socketDescriptor ttPingInfoPtr pingInfoPtr Function Description This function gets Ping statistics in the ttPingInfo structure that pingInfoPtr points to socketDescriptor should match the socket descriptor returned by a call to tfPingOpenStart ping nfoPtr must point to a ttPingInfo structure allocated by the user Parameters Parameter Description socketDescriptor The socket descriptor as returned by a previous call to tfPingOpenStart pingInfoPtr The pointer to an empty structure where the results of the PING connection will be copied upon success of the call See below for details ttPingInfo Data structure Field data type Description pgilransmitted unsigned long Number of transmitted PING echo request packets so far pgiReceived unsigned long Number of received PING echo reply packets so far not including duplicates pgiDuplicated unsigned long Number of duplicated received PING echo reply packets so far pgiLastRtt unsigned long Round trip time in milliseconds of the last PING request reply pgiMaxRtt unsigned long Maximum round trip time in milliseconds of the PING request reply packets 6 6 Pgi
539. rror occurred tfClose can fail for the following reasons TM_EBADF The socket descriptor is invalid TM_EALREAY A previous tfClose call is already in progress TM_ETIMEDOUT The linger option was on with a non zero timeout value and the linger timeout expired before the TCP close handshake with the remote host could complete blocking TCP socket only 5 63 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfloctl include lt trsocket h gt int tfloctl int socketDescriptor unsigned long request int argumentPtr Function Description This function is used to set clear nonblocking I O to get the number of bytes to read or to check whether the specified socket s read pointer is currently at the out of band mark Itis not called ioctl to avoid confusion with an embedded kernel file system call Request Description FIONBIO Set clear nonbllocking I O if the int cell pointed to by argumentPtr contains a non zero value then the specified socket non blocking flag is turned on If it contains a zero value then the specified socket non blocking flag is turned off See also tfBlockingState FIONREAD Stores in the int cell pointed to by argumentPtr the number of bytes available to read from the socket descriptor See also tfGetWaitingBytes SIOCATMARK Stores in the int cell pointed to by argumentPtr a non zero value if the specified socket s read pointer is currently at the out of b
540. rsocket h gt void tfloctlInterface ttUserInterface interfaceHandle int flag void optionPtr int optionLen Function Description The function allows the user to call the driver special functions An example of a special function would be to perform driver maintenance or refill a receive pool This function is provided to allow the user to call the driver and be guaranteed that no other tasks are using the driver at the same time The flag parameter if below 0x100 is driver specific and has no meaning to the TCP IP stack Empty the transmit ring of buffers This function should also be called if the user uses the Treck device interface transmit queue In this case the user needs to periodically call tfloctlInterface to empty the device driver transmit queue as follows errorCode tfloctlInterface interfaceHandle TM DEV IOCTL EMPTY XMIT FLAG void 0 0 In this case the device driver ioctl function will not be called The Treck stack will internally attempt to empty the device Treck device interface transmit queue Refill the Treck ISR recv pool Ifthe user need to get a Treck buffer from the receive ISR and uses the Treck pre allocated recv pool of buffers then the user needs to periodically call tfloctlInterface to replenish the Treck ISR recv pool as follows errorCode tfloctlInterface interfaceHandle TM DEV IOCTL REFILL POOL FLAG void 0 0 In this case the device driver ioctl functi
541. rt is already in use TM ENOMEM Could not obtain a counting semaphore to be used for blocking the FTP server blocking mode only The number of available connections is computed by figuring out the number of unused sockets in the system subtracting one for the FTP listening socket one for a transient listening socket for a passive data connection one to send a 421 reply error message when we reach the maximum number of available connections and dividing by 2 to allow for 2 sockets one control socket and one data socket per connection numberUnusedSockets 3 2 6 26 Application Reference tfFtpdUserStop include lt trsocket h gt int tfFtpdUserStop void Function description This function stops execution of the FTP server by means of closing the listening socket and killing all existing connections Parameters None Returns Value Meaning 0 Success TM EALREADY The FTP server has already been stopped 6 27 Treck Real Time TCP IP User s Manual FTP Client Application Program Interface Description The FTP Client Application Program Interface allows the user to interact with a remote FTP server sending and receiving data and performing various file maintenance functions on the remote filesystem It consists primarily of two parts User interface The user interface allows the user to send commands to the remote FTP server File system interface The file system interface allows th
542. rted local error in processing Requested file action not taken file unavailable Requested action not taken file unavailable Syntax error command unrecog nized Syntax error in parameters or arguments Service not available closing TELNET connection Not logged in tfFtpRmd include lt trsocket h gt Application Reference int tfFtpRmd ttUserFtpHandle ftpSessionPtr char directoryPathNamePtr Function Description Removes directory on the remote file system Parameters Parameter fipSessionPtr directoryPathNamePtr Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM ENOTLOGIN TM _EINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP NAVAIL TM FTP NOTLOGIN Description FTP session handle Path of directory to remove Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server User is not currently logged in Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Requested action not taken file unavailable Not logged in Treck Real Time TCP IP User s Manual tfFtpStor include lt trsocket h gt int tfFtpRetr ttUserFtpHandle ftpUserHandleA ttUserFtpHandle f
543. rvers which listen on port 80 by default and are capable of communicating with thousands of hosts at the same time Each time the user calls accept and there is a connection requests pending it creates a new socket 2 6 2004 Treck Incorporated Introduction to BSD Sockets connect When a user issues a connect command the stack creates a connection with another host Before connect can instruct the stack to establish a connection the user must pass a socket and a sockaddr_in structure containing the destination IP address and port In TCP an actual connection is negotiated In UDP however no packets are exchanged send This call allows a user to send data over a connected socket Unlike sendto this socket must be connected Because the socket is already connected it is not necessary to specify the destination address the destination address was set in accept or connect send can be used for either UDP or TCP data sendto Unlike send sendto requires users to specify the destination port and address This is useful for UDP communications only as TCP requires a pre existing connection sendto may be used on either connected or unconnected UDP sockets In the case that a UDP socket is already connected the destination address provided to sendto will override the default established on the socket with connect recv This function allows the user to receive data on the connected socket recv can be used for either TCP or UDP
544. ry that matches the path given as an argument to tfFSOpenDir The next entry should be either a long listing of the next directory entry either volume name sub directory or file name with its attribute or a short listing of the direc tory entry file name only without any attribute and should be stored in the buffer pointed to by bufferPtr up to bufferSize bytes The FTP server will continue calling tfFSGetNextDirEntry until it gets a return value of 0 bytes indicating that all matching directory entries have been retrieved It is up to the developer of tfFSGetNextDirEntry to keep track of how many entries of the listing have been read so far whether the directory was open for long or short listing and the match ing pattern using dirDataPtr Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin dirDataPtr Pointer to newly allocated directory data structure bufferPtr Pointer to a buffer where to copy the next directory entry bufferSize Size in bytes of the buffer Returns Value Meaning sl Failure 20 Number of bytes copied into the buffer pointed to by bufferPtr 0 End of directory 6 96 Application Reference tfF SGetUniqueFileName include lt trsocket h gt int tfFSGetUniqueFileName void userDataPtr char bufferPtr int bufferSize Function description Given the unique user data pointer as returned by tfFSUserLogin this function finds and copies a uniq
545. ryPtr btuYiaddr 4 The user can then configure that PPP interface calling tfOpenInterface with this pppinterfaceld parameter using a static IP address for its interface In the link layer call back function set in tfUseAsyncServerPpp if the flag is TM LL OPEN COMPLETE then the user can add the PROXY ARP entry tfAddProxyArpEntry userBtEntryPtr gt btuYiaddr In the link layer call back function if the flag is TM LL CLOSE STARTED then the user can delete the PROXY ARP entry tfDelProxyArpEntry userBtEntryPtr gt btu Yiaddr 7 37 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The user can request for additional DHCP IP addresses for additional PPP serial lines repeating this process starting at tfDhcpUserStart above with different userIndex and pppInterfaceld values If the user were to close the Ethernet interface then all the DHCP addresses that were allocated with the tfDhcpUserStart calls should be released prior to closing the Ethernet interface by calling tfDhcpUserRelease thernetInterfaceHandle userIndex This must be done for each userIndex that was used in a successful tfDhcp UserStart DHCP FQDN Option FQDN is DHCP option 81 The FQDN option enables DHCP clients and DHCP servers to exchange the DHCP client domain name information for the purpose of dynamically updating this information in the DNS Domain Name System The FQDN option consists of a domain name and a set of f
546. s tfKernelTaskPendEvent void tfKernelTaskPendEvent ttUserGenericUnionPtr eventPtr Function Description The user must write this function to make use of their specific operating system This function pends on an event pointed to by eventPtr which is posted from another task This should be similar if not identical to tfKernelPendEvent Parameters Parameter Description eventPtr Pointer to the event flag upon which this function must pend Returns Nothing Ad 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelTaskPostEvent void tfKernelTaskPostEvent ttUserGenericUnionPtr eventPtr Function Description The user must write this function to make use of their specific operating system This function resumes tasks that were waiting on the event pointed to by eventPtr This should be similar to tfKernellsrPostEvent with one major difference tfKernellsrPostEvent is called from within an ISR whereas tfKernelTaskPostEvent is called from a task Most operating systems have different calls when posting occurs from an ISR or from a task Parameters Parameter Description eventPtr Pointer to the event flag to which this function must post Returns Nothing A 10 2004 Treck Incorporated Configuration Notes Running multiple instances of Treck A set of new APIs described in this section have been added to allow users to run multiple instances of the Treck TCP IP stack Each instance of t
547. s not recommend that you change any parameters at this point as the stack should work fine with the defaults that are set up The following is an example of how easy it is to start using the protocol stack include trsocket h void main void Define the variables that I need to Startup int errorCode int sd Start the protocol stack errorCode tfStartTreck if errorCode TM ENOERROR Now do my loopback code sd socket PF INET SOCK DGRAM 0 4 39 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Step 7 Testing the New Library with a Loopback Test Now you are ready to start using Treck protocols in loopback mode The loopback address is defined as 127 0 0 1 You should setup a simple client server to make sure that packets traverse all the way down the stack and back up The loopback driver sits below TCP IP so it is a good test to see if you have things working thus far f you are not familiar with sockets programming then you should review the section titled Introduction to BSD Sockets Other good reference material on this subject would include Introduction to TCP IP Volume 3 BSD Edition by Douglas E Comer and UNIX Network Programming Volume 1 by W Richard Stevens After you have completed the loopback test you are ready to move onto the next section The reason that we suggest that you complete the loopback test first is to reduce the amount of i
548. s only used if the user uses a trasnmit task and wishes to call the Treck function tfInterfaceSpinLock inside the device driver send function to let the other tasks run while waiting for the device driver to be ready to transmit No RTOS or event scheduler with main loop If you do not have any RTOS or if you have an event scheduler with a main loop implementation then you have neither defined TM TRECK PREEMPTIVE KERNEL nor TM TRECK NONPREMTIVE KERNEL in your frsystem h In that case then the first four functions are not needed because they will not be called since in that case the user is not allowed to block Preemptive or non preemptive kernel If you are using a preemptive kernel or a non preemptive kernel then you have defined either TM TRECK PREEMPTIVE KERNEL or TM TRECK NON PREEMPTIVE KERNEL in your system h In that case you will need some or all of these first 4 functions as shown in the following table depending on which of the following additional macros you have defined in your frsystem h TM TASK RECV TM TASK XMIT TM TASK SEND tfKernelCreateEvent tfKernelCreateEvent tfKernelCreateEvent tfKernelPendEvent tfKernelPendEvent tfKernelPendEvent tfKernellsrPostEvent tfKernellsrPostEvent tfKernelTaskPostEvent Note that if you have not defined any of these macros you do not need to provide any of these 4 functions since they will not be called 4 32 2004 Treck Incorporated In
549. s stream transmission to be efficient To understand this concept we need to keep in mind Figure 1 37 It shows how a sender transmits a packet and waits for an acknowledgement from the receiver before transmitting another Also we can gather from this illustration that data only flows from one machine to another in one direction at any given time even if the network is capable of simultaneous communications in both directions The network will be completely idle during times the machines delay responses for example when computing a checksum When dealing with a network with high transmission delays we must remember that a simple positive acknowledgement protocol wastes a substantial amount of network bandwidth This is because it must wait to send another packet until it receives an acknowledgement for the original packet that was sent The solution to this problem is the Sliding Window Concept 1 54 2004 Treck Incorporated Introduction to TCP IP Sliding window protocols use network bandwidth more efficiently because they allow the user to transmit multiple packets before waiting to receive an acknowledgement To illustrate this point look at Figure 1 39 If we think of a sequence of packets to be transmitted the protocol places a small fixed size window on the sequence and transmits all packets that lie inside of that window Intial Window Window Slides gt
550. sage is received from see socket The length of the message returned could also be smaller than bufferLength this is not an error If no messages are available at the socket the receive call waits for a message to arrive unless the socket is non blocking or the MSG_DONTWAIT flag is set in the flags parameter in which case 1 is returned with socket error being set to TM EWOULDBLOCK Out of band data not in the stream urgent data when the SO OOBINLINE option is not set default TCP protocol only A single out of band data byte is provided with the TCP protocol when the SO OOBINLINE option is not set If an out of band data byte is present recv with the MSG OOB flag not set will not read past the position of the out of band data byte in a single recv request That is if there are 10 bytes from the current read position until the out of band byte and if we execute a recv specifying a bufferLength of 20 bytes and a flag value of 0 recv will only return 10 bytes This forced stopping is to allow us to execute the SOIOCATMARK tfloctl to determine when we are at the out of band byte mark Alternatively tfGetOobDataOffset can be used instead of tfloctl to determine the offset of the out of band data byte When we are at the mark recv with the MSG OOB flag set can read the out of band data byte Note that the user needs to either use select or tfRegisterSocketCB in order to know when out of band data has arrived or is arriving Out of ban
551. scription Permanently associate a public IP with a private IP Useful to support the maximum Configure as many static associations as you like on a public NAT interface being sure to avoid conflicts of course different public IP s with other static IP configurations Inner server configurations on the same public IP should come later or the static configuration would hide them dynamic IP configurations should never use the same IP address Parameters Parameter Description interface handle Interface handle of the public NAT device on which to create a static association ipPublic Public IP address network byte order ipPrivate Private IP address network byte order Return Value Meaning TM ENOMEM Insufficient memory or too many triggers already TM ENOERROR Newly allocated trigger ip s and ports initialized TM EINVAL Erroneous use for details enable TM NAT TRACE 7 70 2004 Treck Incorporated Optional Protocols tfNatConfigDynamic include lt trsocket h gt int tfNatConfigDynamic ttUserInterface interfaceHandle ttUserIpAddress ipPublic Function Description Allow automatic temporary association of public with private IP addresses associations will expire after TM NTRTTL DYNAMIC seconds of no traffic may be called multiple times on a public NAT interface with different public IP addresses Later calls will specify the most used public IP addresses Should be called after tfNatConfigStatic if called Otherwise the
552. scription buffer buffer to hold the result string Its size should be TM NT ENTRY STR LEN sizePtr In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Returns Value Description Valid pointer Pointer to the result string NULL One of the parameters is bad 6 143 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNtRteEntryToStr char tfNtRteEntryToStr ttNtRteEntryPtr ntRteEntryPtr char Buffer int SizePtr Description Converts a routing entry into a string that has the major fields in Parameters Parameter Description ntRteEntryPtr Routing entry to be converted buffer buffer to hold the result string Its size should be TM NT ENTRY STR LEN sizePtr In pointer to the size of the buffer TM NT ENTRY STR LEN Out pointer to the actual size of the result string Returns Value Meaning Valid pointer Pointer to the result string NULL One of the parameters is bad 6 144 tfNtArpEntryToStr char ttNtArpEntryPtr char int Description Application Reference tfNtArpEntryToStr NtArpEntryPtr Buffer SizePtr Converts a ARP entry into a string that has the major fields in Parameters Parameter ntArpEntryPtr buffer sizePtr Returns Value Valid pointer NULL Description ARP entry to be converted buffer to hold the result string Its size should be TM NT ENTRY STR
553. sed as the default IP address for the remote PPP or SLIP for routing purposes see tfGetPppPeerIpAddress tfSetPppPeerIpAddress can only be called between tfAddInterface or tfCloseInterface and tfOpenInterface Parameters Parameter Description interfaceHandle The interface handle to update the Peer IP address in ifIpAddress The IP address to use for routing purposes for the remote PPP system Returns Value Meaning 0 Success TM_EINVAL The interface handle is null or the device is a LAN device TM EISCONN PPP connection is already estab lished 7 98 2004 Treck Incorporated Optional Protocols tfUseAsyncPpp include lt trsocket h gt ttUserLinkLayer tfUseAsyncPpp ttUserLnkNotifyFuncPtr linkNotifyFuncPtr Function Description This function is used to initialize the asynchronous PPP client link layer When link up or link down events occur the stack will call the function passed in If you do not need notification of events then the parameter should be set to TM LNK NOTIFY FUNC NULL PTR Your prototype for your notification function should look like this void myPppNotifyFunction ttUserInterface interfaceHandle int flags This function is called with the interface handle and a flag The flag is set to one of the following TM LL OPEN COMPLETE PPP Device is ready to accept data from the user TM LL CLOSE STARTED PPP Device has started to close this link TM LL CLOSE COMPLETE PPP Device has close
554. ser s Manual rresvport include lt trsocket h gt int rresvport int portToReservePtr Function Description rresvport is used to create a TCP socket and bind a reserved port to the socket starting with the port to reserve given by the user The portToReservePtr parameter is a value result parameter The integer pointed to by portToReservePtr is the first port number that the function attempts to bind to The caller typically initializes the starting port number to IPPORT RESERVED 1 IPPORT RESERVED is defined as 1024 If the bind fails because that port is already used then rresvport decrements the port number and tries again If it finally reaches IPPORT RESERVEDSTART defined as 600 and finds it already in use it returns and set the socket error to TM EAGAIN Ifthis function successfully binds to a reserved port number it returns the socket descriptor to the user and stores the reserved port that the socket is bound to in the integer cell pointed to by portToReservePtr Parameters Parameter Description portToReservePtr Pointer to the port number to reserve and to the port number reserved on success Returns Value Meaning gt 0 Valid socket descpriptor 1 An error occurred If an error occured the socket error can be retrieved by calling tfGetSocketError and using TM SOCKET ERROR as the socket descriptor parameter rresvport will fail if TM AGAIN The TCP IP stack could not find any port number availab
555. serBtEntryPtr is a pointer to a structure defined in trsocket h In particular the userBtEntryPtr will contain The allocated IP address in the field userBtEntryPtr 7 btuYiaddr The subnet mask in the field userBtEntryPtr gt btuNetMask Default router entry in the field userBtEntryPtr gt btuDefRouter Primary Domain name server userBtEntryPtr gt btuDns IServerIpAddress Secondary Domain name server userBtEntryPtr 7 btuDns2ServerIpAddress An array of TM DHCP NBNS NUM SERVER NetBios name servers IPv4 addresses returned in the NBNS option userBtEntryPtr gt btuNetBiosNumNameServers By default TM DHCP NBNS NUM SERVER is equal to 2 allowing the storage of 2 name servers The number of NetBios name servers userBtEntryPtr gt btuNetBiosNumNameServers Configuring additional automatic DHCP IP addresses on the same interface To configure additional automatic DHCP IP addresses on the same interface multi homing use tfConfigInterface instead of tfOpenInterface 7 26 2004 Treck Incorporated Optional Protocols DHCP FQDN Option FQDN is DHCP option 81 The FQDN option enables DHCP clients and DHCP servers to exchange the DHCP client domain name information for the purpose of dynamically updating this information in the DNS Domain Name System The FQDN option consists of a domain name and a set of flags This option when enabled is sent in the DHCPREQUEST and DHCPACK messages by both the client and the server
556. shOpenInterface with 0x x failed s Nn ipAddress tfStrError errorCode else User had already opened the interface on another mhome errorCode tfConfigInterface interfaceHandle ipAddress TM_IP_LOCAL_NETMASK 0 not used 1 has to be one unsigned char mhomeIndex if errorCode TM ENOERROR printf tfConfigInterface with 0x x n ipAddress 7 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual else printf tfConfigInterface with Ox x failed s n ipAddress tfStrError errorCode else A collision occurred on the IP address try another IP address Kg tfConfigAutoIp interfaceHandle mhomeIndex return 0 7 6 2004 Treck Incorporated Optional Protocols tfAutoIPPicklpAddress include lt trsocket h gt ttUserIpAddress tfAutoIPPickIpAddress void Description Pick a valid AUTO IP v4 address in the AUTO IP IPv4 address pool i e pick and IP address between 169 254 1 0 and 169 254 254 255 that has not been picked in the previous attempt to pick an IP address Parameters None Returns Value Meaning Non zero IP address Valid AUTO IP v4 address 0 No valid AUTO IP v4 address was found 7 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfCancelCollisionDetection include lt trsocket h gt int tfCancelCollisionDetection ttUserlpAddress ipAddress Fun
557. small segments called frames between nodes Network Protocols Means by which packets of data are routed through the network from sender to receiver This level is more concerned with the path the packets take not the content of those packets Transport Protocols Assume responsibility for the delivering of a potentially large message from the sending application on one network to the receiving destination Session Protocols Responsible for negotiating parameters for the link i e which layer 3 protocol to use Presentation Protocols Responsible for making sure that data is viewed the same on both ends of the communication Can also be used for encryption and compression Application Protocols Forms the working toolset for network users and the applications that are written to support them In the original TCP IP stack the network layer consisted of the Internet Protocol IP and the transport layer consisted of the Transport Control Protocol TCP for reliable delivery of application messages and User Datagram Protocol for UDP for efficient exchange of small packets primarily for control and administrative purposes The Ethernet Protocol From its inception in 1978 by the Xerox Corporation Intel Corporation and Digital Equipment Corporation Ethernet has become a very popular LAN technology It 1 6 2004 Treck Incorporated Introduction to TCP IP has grown to be one of the most widely used methods of packet switch
558. ss 4 10 TM PING REPLY MULTICAST ss 4 10 TM USE REUSEADDR LIST sens 4 10 TM USE PPP MSCHAPD 5 ete cerere rettet in kein sien 4 10 TIVE PPP ROME a A TEILS 4 11 TM USE EAD 2er tote doen eee rite rice dear ee ee Ebr dee Bea veces 4 11 ATIVE SUSE IPC nt Minna ileseestagvelentevsens 4 11 TM USER PACKET DATA ALLOC ss 4 11 TIE USE VOLDDANN S enero retro ce tete pit ree hae rites 4 11 TM OPTIMIZE MANY MHOMES eene 4 11 TM USE NETSDAI ioni Rio ar ER 4 11 TM USE SNIEE iride rete tee poc entente Yes reb recep etn 4 11 TM TRECK NO KERNEL 0 0r HEP reb En EEG 4 11 TM TRECK NONPREEMPTIVE KERNEL 4 12 TM TRECK PREEMPTIVE KERNEL eee 4 12 TM TASK RECV T 4 12 AVL TASK AMI ed ie men 4 12 TM TASK SEND eie citet eee ese epar eee ae Fe vede pen 4 13 Timer Updates sos ett ee Hetero ee pU enr UR eines 4 13 TM TICK LENCGHIH erii nee reeieeoe petes ennemies eee 4 13 Doro ns c ERE 4 14 TM LITTLE ENDLAN etri eerte ter ie ree eta 4 14 TM BIG ENDIAN needs 4 14 Memory Allocation usines riens 4 14 TINEAUSECSSEBAD s dense icit HR REIP ueteri Ibo pud 4 14 TM SHEAP SIZE eoe frt reperto ete o rasero Erdesa S vE n 4 14 TM DYNAMIC CREATE SHEAP eerte 4 14 Complier Qualifications iere ite a Itpeete eese teu Se eee ekses ebi 4 15 TIVE EAR RE SEN 4 15 TM CODE FAR ioter teret eoe terere ee aeree vee 4 15 TM INTERRUPT intett pt 5 rrt nere aet bieten 4 15 TM GLOBAL QLP erste sieme
559. ssion timeout value in milliseconds Used when no network round trip time has been computed yet Default 3 000 milliseconds Get the minimum retransmission timeout in milliseconds The network computed retransmission timeout is bound by TM TCP RTO MIN and TM TCP RTO MAX Default 100 milliseconds Get the maximum retransmission timeout in milliseconds The network computed retransmission timeout is bound by TM TCPRTO MIN and TM RTO MAX Default 64 000 milliseconds Get the minimum window probe timeout 5 19 2004 Treck Incorporated Treck Real Time TCP IP User s Manual interval in milliseconds The network computed window probe timeout is bound by TM TCP PROBE MIN and TM TCP PROBE MAX Default 500 milliseconds TM TCP PROBE MAX Get the maximum window probe timeout interval in milliseconds The network computed window probe timeout is bound by TM TCP PROBE MIN and TM TCP PROBE MAX Default 60 000 milliseconds TM TCP KEEPALIVE INTV Get the interval between Keep Alive probes in seconds See TM TCP KEEPALIVE CNT Default 75 seconds 5 20 2004 Treck Incorporated Parameters Parameter socketDescriptor protocolLevel optionName option ValuePtr optionLengthPtr ProtocolLevel SOL SOCKET IP PROTOIP IP PROTOTCP Programmer s Reference Description The socket descriptor to get the option from The protocol to get the option from See below The option to get See above and below The poi
560. stack The amount of RAM used in your system will depend on many different factors These factors include the size of your sockets send queue and receive queue as well as the number of pre allocated receive buffers for the device Most of the RAM is used for your data The internal data structures are very small For example a single UDP socket entry requires less than 200 bytes for the internal data structures If we are using TCP on a socket then the internal data structure grows to less than 400 bytes A socket entry is only allocated between the socket call and the close call This means that the socket data structures are not in use when the socket is not active This allows you to have a high number of sockets defined on a system and use a small amount of RAM while they are not in use Maximum RAM usage is also dependent on the maximum number of concurrent sockets that you have open at any given time The interface to your operating system or C compiler from the buffer system is a simple malloc and free call 3 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Timer System The timer system is the most simple of the systems to understand We need a fixed time interval notification into the protocol stack This is very similar to the crystal that is attached to your microprocessor We use this fixed time notification to let us know how much time has elapsed This is very important for a protocol stack We must know ho
561. stack ever shuts down orderly call tfNatUnConfig for each interface where tfNatConfig returned TM ENOERROR Parameters Parameter Description interfaceHandle interface handle of the public NAT device Return Value Meaning TM ENOERROR success TM EINVAL not a valid interface handle 7 63 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNatUnConfig include lt trsocket h gt int tfNatUnConfig ttUserInterface interfaceHandle Function Description Dismantle a stack device s functioning as a public NAT interface Call exactly once per public NAT interface that 1s for each interface for which tfNatConfig returned TM ENOERROR Call after all other NAT functions on this interface Parameters Parameter Description interfaceHandle interface handle of the NAT device to tfNatUnConfig Return Value Meaning TM ENOERROR success TM EINVAL not a valid interface handle or not an interface that was fNatConfig d 7 64 2004 Treck Incorporated Optional Protocols tfNatConfigNapt include lt trsocket h gt int tfNatConfigNapt ttUserInterface interfaceHandle ttUserIpAddress ipPublic ttUserIpPort portPublicMin ttUserIpPort portPublicMax Function Description This function defines a range of port numbers that are used to route traffic from multiple private machines through the NAT router to the public network Call tfConfigNatp only once on a public NAT interface Do not use the ipP
562. statically assigned private system may commandeer a dynamic IP address This is not harmful just unlikely to be useful Parameters Parameter Description interface handle Interface handle of the public NAT device on which to create a dynamic association ipPublic Public IP address network byte order Return Value Meaning TM ENOMEM Insufficient memory or too many triggers already TM ENOERROR Newly allocated trigger ip s and ports initialized TM EINVAL Erroneous use for details enable TM NAT TRACE 7 71 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNatConfigMaxEntries include lt trsocket h gt void tfNatConfigMaxEntries int maxentries Function Description Set the maximum number of triggers for NAT to track on a public interface This maximum will apply to all public interfaces until changed again The default is 64 TM DEF NAT MAX ENTRIES in trmacro h Parameters Parameter Description maxentries Maximum simultaneous triggers Returns Return Meaning None 1 12 2004 Treck Incorporated Optional Protocols tfNatDump include lt trsocket h gt void tfNatDump ttUserInterface interfaceHandle Function Description Displays details of the current set of NAT triggers to stderr define TM NAT DUMP in trsystem h to enable or comment out to save code Parameters Parameter Description interfaceHandle Interface handle of the NAT device from which to retrieve informatio
563. string NULL One of the parameters is bad 6 147 Treck Real Time TCP IP User s Manual Data structures These data structures holds a mapped copy of the internal stack data they are only for the output purpose modifying these data has no effect on the internal data ttNtRteEntry To hold the information of a routing entry typedef struct tsNtRteEntry struct sockaddr_storage ntRteDestSockAddr ttUser8Bit ntRtePrefixLength ttUser32Bit ntRteOwnerCount ttUser32Bit ntRteMhomeIndex char ntRteDeviceName C IM MAX DEVICE NAME 3 4 4 struct sockaddr storage ntRteGwSockAddr ttUser8Bit ntRteHwAddress TM_MAX_PHYS_ADDR 3 4 4 int ntRteHwLength ttUser8Bit ntRteClonePrefixLength ttUser32Bit ntRteMtu ttUser32Bit ntRteHops ttUser32Bit ntRteTtl ttUser16Bit ntRteFlags ttNtRteEntry typedef ttNtRteEntry ttNtRteEntryPtr Member Description ntRteDestSockAddr ntRteDestSockAddr ss_family indicates the family of the address ntRteDestSockAddr addr ipv6 or ntRteDestSockAddr addr ipv4 has the actual key IP Address ntRtePrefixLength Matching prefix length associated with the routing entry 1 128 for IPV6 and 1 32 for IPV4 entries ntRteOwnerCount Owner count for the routing entry ntRteMhomelndex Multihome index in device entry ntRteDeviceName Name of the device associated with the routing entry gtRteGwSockAddr For gateway route this
564. t tfTftpInit tfTftpPut tfTftpSetTimeout tfTftpUserExecute Blocking Mode Called by the user to get a file from a TFTP server This function must be called before any other TFTP API calls are made It initializes various data associated with the TFTP client Called by the user to store a file to a TFTP server Called by the user to set timeout and retry values If the stack is running in non blocking mode this function must be called periodically in order to get the client to execute In blocking mode this function should not be called In blocking mode tfTftpGet and tf TftpPut will both block until the transfer is completed or an error is returned The TFTP client code is executed in the context of the calling task Choose blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode calls to tfTftpGet and tf TftpPut will return immediately tfTftpUserExecute must be called periodically to cause them to execute Choose non blocking mode if you are not using an RTOS Kernel Treck Real Time TCP IP User s Manual tfTftpGet include lt trsocket h gt int tfTftpGet char filename struct sockaddr remote_addr char tftpbuf unsigned long int bufsize unsigned short int mode int blocking Function Description This function retrieves a file from a TFTP server Blocking Mode In blocking mode tfTftpGet should be called from within a task It will block until t
565. t htonl htons inet_addr inet_aton inet_ntoa listen ntohl ntohs readv recv recvfrom rresvport select send sendto setsockopt shutdown socket tfClose tfloctl tfRead tfWrite writev Socket Extension Calls tfBindNoCheck tfBlockingState tfFlushRecvQ tfFreeDynamicMemory tfFreeZeroCopyBuffer tfGetOobDataOffset tfGetSendCompltBytes tfGetSocketError tfGetWaitingBytes tfGetZeroCopyBuffer tfInetToAscii tflpScatteredSend tfRawSocket tfRecvFromto tfRegisterIPForwCB tfResetConnection tfSendToFrom tfSendToInterface tfSocketArray Walk tfSocketScatteredSendTo Programmer s Reference tfZeroCopyRecv tfZeroCopyRecvFrom tfZeroCopySend tfZeroCopySendTo tfZeroCopyUserBufferSend tfZeroCopyUserBufferSendto Call Back Function Registration tfRegisterSocketCB tfRegisterSocketCBParam Treck Initialization tflnitTreckOptions tfSetTreckOptions tfStartTreck Device Interface API tfAddInterface tfAddInterfaceMhomeAddress tfCheckReceivelnterface tfCheckSentInterface tfCheckXmitInterface tfCloseInterface tfConfigInterface tfDeviceClearPointer tfDeviceGetPointer tfDeviceStorePointer tfFinishOpenInterface tfFreeDriverBuffer tfGetDriverBuffer tfGetBroadcastAddress tfGetIfMtu tfGetIpAddress tfGetNetMask tfInterfaceGetVirtualChannel tfInterfaceSetOptions tfInterfaceSetVirtualChannel tfInterfaceSpinLock tfloctlInterface tfNotifyInterfacelsr tfNotifyInterfaceTask tfNotifyReceivelnterfacelsr tfNotifySentInterfacelsr t
566. t use a unique name The name length cannot exceed TM MAX DEVICE NAME 1 13 bytes 5 192 2004 Treck Incorporated linkLayerHandle drvAddErrorPtr Returns Programmer s Reference The link layer layer 2 protocol handle that this interface will use This is returned by tfUseEthernet tfUseAsyncPpp or tfUseSlip A pointer to an int that will contain an error if one occurred An Interface Handle or a NULL handle when an error occurs If an error occurs the error is stored in drvAddError Ptr ErrorCode TM EINVAL TM EALREADY TM ENOBUFS Description One of the parameters is invalid Device with same name has already been added Not enough buffers to allocate a device entry 5 193 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUseScatintfDriver include lt trsocket h gt ttUserInterface tfUseScatIntfDriver char namePtr ttUserLinkLayer linkLayerHandle int errorCode Ju Function Description tfUseScatIntfDriver adds a loop back driver below link layer using one scattered device driver send call and scattered device driver recv tfUseIntfDriver and tfUseScatIntfDriver are very useful to debug a link layer tfUseScatIntfDriver avoids copying the data in the loop back driver Example ethernetLinkLayerHandle tfUseEthernet myInterfaceHandle tfUseScatIntfDriver TESTSCAT ethernet LinkLayerHandle amp errorCode Note Both TM USE
567. t 0 Number of bytes copied 6 108 Application Reference tfFSUserAllowed include lt trsocket h gt int tfFSUserAllowed char userNamePtr Function description This function verifies whether a user is allowed on the system Parameters Parameter Description userNamePtr Pointer to a null terminated string containing the user name Returns Value Meaning 0 Success 1 User is not allowed on the system 6 109 Treck Real Time TCP IP User s Manual tfF SUserLogin include lt trsocket h gt void tfFSUserLogin char userNamePtr char passwordPtr Function description When given a User name string and Password string this function returns a unique user data pointer 1f password is correct it returns a Null pointer otherwise The just allocated user data pointer points to a data structure containing information unique to the just logged in current user such as its current working directory Parameters Parameter Description userNamePtr Pointer to a null terminated string containing the user name passwordPtr Pointer to a null terminated string containing the password Returns Value Meaning void 0 Failure userDataPtr Pointer to a unique user data structure containing information about the given user such as its working directory 6 110 Application Reference tfF SUserLogout include lt trsocket h gt void tfFSUserLogout void userDataPtr Function Descript
568. t blocking Function Description This function sends a file to a TFTP server Blocking Mode In blocking mode tfTftpPut should be called from within a task It will block until the file transfer is completed or an error is returned The TFTP client code is executed in the context of the calling task Choose blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfTftpPut will return immediately It is then the user s responsibility to then call tf TftpUserExecute periodically to execute the TFTP client code Choose non blocking mode if you do not have an RTOS Kernel 6 76 Parameters Parameter filename remote_addr iftpbuf bufsize mode blocking Returns Value 0 TM_TFTP_EXECUT TM_TFTP_EINVAL TM_TFTP_EINVAL TM_TFTP_EINVAL TM_TFTP_ESOCK TM_TFTP_UNDEF Application Reference Description Null terminated string containing the file name to send to the server Structure representing the address of the server The type AF INET address and port for TFTP usually 69 must be filled in A pointer to a buffer to store the file into The number of bytes to send from the buffer TM TYPE ASCII for ASCII transfers TM TYPE BINARY for binary transfers TM BLOCKING ON for blocking mode TM BLOCKING OFF for non blocking mode Meaning Success A session is already in progress Only one session may be in progress at a time mode is neither TM TYPE ASCII nor TM
569. t for the DHCP configuration to complete i e for dhepNotifyFunc to be called During the wait ensure tfTimerUpdate or tfTimerUpdatelsr and tfTimerExecute are called When the DHCP request has completed or timed out the dhepNotifyFunc will be called as follows dhcpNotifyFunc ethernetInterfaceHandle userIndex errorCode The userIndex corresponds to the second parameter of tfDhcpUserStart and errorCode indicates whether the DHCP request has been successful 1 e errorCode 0 or timed out errorCode TM ETIMEDOUT User controlled configuration parameters A user API DhcpUserSet is provided to allow the user e to set the DHCP initial state to INIT REBOOT instead of the default INIT state with a user specified requested IP address and client ID e or to set a user specified requested IP address and or Client ID while DHCP is in the INIT state e Or to allow the user to suppress the client ID option ARP probes sent by the DHCP client If the TM USE AUTO IP macro is defined in trsystem h and the AUTO IP option has been purchased then the DHCP client will send several ARP Probes i e ARP request with a sender net address set to 0 to make sure that no other node has been configured with the same IP address If a node responds then the DHCP client would decline the IP address and restart the discovery process in the INIT state after 10 seconds have elapsed 7 36 2004 Treck Incorporated Optional Protocols When the D
570. t is allowed In this case if the connection has not been established and not failed connect will return TM SOCKET ERROR and tfGetSocketError will return TM EINPROGRESS error code indicating that the connection is pending connect should never be called more than once Additional calls to connect will fail with TM EALREADY error code returned by tfGetSocketError Non blocking connect and select After issuing one non blocking connect the user can call select with the write mask set for that socket descriptor to check for connection completion When select returns with the write mask set for that socket the user can call getsockopt with the SO ERROR option name If the retrieved pending socket error is TM_ENOERROR then the connection has been established otherwise an error occurred on the connection as indicated by the retrieved pending socket error Non blocking connect and tfRegisterSocketCB Alternatively the user could have issued a tfRegisterSocketCB call with TM CB CONNECT COMPLTITM CB SOCKET ERROR event flags prior to issuing a non blocking connect to get an asynchronous notification of the completion of the connect call If the TM CB SOCKET ERROR flag is set 5 8 2004 Treck Incorporated Programmer s Reference when the call back function is called the user can retrieve the pending socket error by calling getsockopt with the SO ERROR option name Non blocking connect and polling Alternatively after the user issues
571. t it takes a zero copy buffer handle as a parameter and puts the beginning of the data into a passed pointer Note The user must call tf reeZeroCopyBuffer in order to free the buffer after the user has finished with it Parameters Parameter Description socketDescriptor The socket descriptor to send data to bufferHandlePtr The zero copy buffer that contains the message dataPtrPtr A pointer to a char pointer where the start of the data is stored maxBufferLength The maximum length of the message flags See below fromAddressPtr The address to packet came from fromAddressLength The length of the address 5 104 2004 Treck Incorporated Programmer s Reference The flags parameter is formed by ORing one or more of the following MSG DONTWAIT MSG_PEEK MSG SCATTERED MSG_SCATTERED Description Do not wait for data but rather return immediately Peek at the data present on the socket the data is returned but not consumed so that a subsequent receive operation will see the same data If the receive data is scattered it will be passed to the user as is and will not get copied into a new buffer to make the data contiguous Upon return bufferHandlePtr will point to a scattered buffer as explained below When the MSG SCATTERED bit is set in the flags parameters then upon successful return from tfZeroCopyRecvFrom the bufferHandlePtr parameter should be cast to a pointer to a ttUserPacket structure where ttUs
572. t not the TCP header that can be sent per segment to the peer i e the amount of user data sent per segment is the value given by the TCP MAXSEG option minus any enabled TCP option for example 12 bytes for a TCP time stamp option The TCP MAXSEG value can be decreased or increased prior to a connection establishment but it is not recommended to set it to a value higher than the IP MTU minus 40 bytes for example 1460 bytes on Ethernet since this would cause fragmentation of TCP segments Note setting the TCP_MAXSEG option will inhibit the automactic computation of that value by the system based on the IP MTU which avoids fragmentation and will also inhibit Path Mtu Discovery After the connection has started this value cannot be changed Note also that the TCP_MAXSEG value cannot be set below 64 bytes Default value is IP MTU minus TCP NODELAY TCP_NOPUSH TCP_STDURG TM TCP PACKET TM TCP SEL ACK TM TCP WND SCALE Programmer s Reference 40 bytes Set this option value to a non zero value to disable the Nagle algorithm that buffers the sent data inside the TCP Useful to allow client s TCP to send small packets as soon as possible like mouse clicks Default 0 Set this option value to a non zero value to force TCP to delay sending any TCP data until a full sized segment is buffered in the TCP buffers Useful for applications that send continuous big chunks of data like FTP and know that more data is com
573. tTcpRcvAdv ntTcpCwnd 6 154 Description Socket descriptor integer Data in the receive queue in bytes Data in the send queue in bytes Size of the receive queue in bytes Size of the send queue in bytes Local address port and protocol family information of the socket Owner count of the socket Peer s address port and protocol family information of the socket TCP flags Retransmission timeout number of retransmitted segments Send Sequence Variables SND UNA send unacknowledged Send Sequence Variables ISS initial send sequence number Send Sequence Variables SND NXT send next Highest sequence number sent used because of retransmit Receive Sequence Variables IRS initial receive sequence number Send Sequence Variables SND WLI segment sequence number used for last window update SND Send Sequence Variables SND WL2 segment acknowledg ment number used for last window update Maximum send window seen so far Receive Sequence VariablesRCV NXT receive next Receive Sequence Variables RCV WND receive window Sequence number of right edge of advertized window Could be smaller than Rev Nxt Rev Wnd to avoid silly window syndrome Also used to prevent shrinkage of our receive window Send congestion window ntTcpSsthresh ntTcpBackLog ntTcpDupAck ntTcpAcksAfterRexmit ntTcpState Application Reference Send slow start threshold size Back logs Duplicate ACKs number of non duplic
574. tachi H8S platform no OS TM KERNEL RZK EZ80 This is used for RZK RTOS for Zilog EZ80 target board TM KERNEL REALOS FR This is used for REALOS RTOS for the Fujitsu MBxxxxx platform TM KERNEL TI DSP BIOS This is used for DSO BIOS RTOS for the TI DSPs TM KERNEL WIN32 X86 This is used for Win32 TM KERNEL VISUAL X86 This is used for testing under VC environment single threaded for auto mated testing TM KERNEL LINUX APP This is used for Linux 4 18 2004 Treck Incorporated Integrating into Your Environment Step 3 Creating the Build Command BAT Files for a DOS Environment and Building the Library Instead of using make files to build the Treck TCP IP library We have put together simple batch files for a DOS build environment These are designed to be easy to understand and design for compilers that we do not support yet The other feature of using batch files for DOS is that they can be easily converted to shell scripts for the UNIX environment It is best to think of the batch files as a three tiered system for building your project TIP Before running any batch files to build the system you should run the batch file SETUP BAT located in the TRECKBIN directory to setup the proper path to the Treck directories Tier 1 Compiler Primitives and Library Utility Primitives Tier 2 Compile Library all the Treck code Tier 3 Automated Build System Let s look at each of these tiers individually Tier 1 Se
575. tains the value 1 It is important to keep in mind that even though ICMP messages are encapsulated and sent using IP datagrams it is not considered a higher level protocol it is a required part of IP The reason for using IP to deliver ICMP messages is that they may need to travel across several physical networks to reach their final destination Thus they cannot be delivered by the physical transport alone 1 46 2004 Treck Incorporated Introduction to TCP IP ICMP Message Format Although each ICMP message has its own format they all begin with the same three fields These are an 8 bit integer message TYPE field that identifies the message an 8 bit CODE field that provides further information about the message type and a 16 bit CHECKSUM field ICMP uses the same additive checksum algorithm as IP but the ICMP checksum only covers the ICMP message In addition ICMP messages that report errors always include the header and the first 64 data bits of the datagram causing the problem The reason for returning more than the datagram header alone is to allow the receiver to determine which protocol s and which application program were responsible for the datagram Higher level protocols in the TCP IP suite are designed so that crucial information is encoded in the first 64 bits The 7YPE field defines the meaning of the message as well as its format The types include Type Field ICMP Message Type Echo Reply Destination Un
576. tate or not but not on a TCP socket socketDescriptor is a socket created with socket If fromAddressPtr is not a NULL pointer the source address of the message is filled in If toAddressPtr is nota NULL pointer the destination address of the message is filled in addressLengthPtr is a value result parameter initialized to the size of the buffer associated with fromAddressPtr and with toAddressPtr and modified on return to indicate the actual size of the address stored there The length of the message is returned If a message is too long to fit in the supplied buffer excess bytes may be discarded depending on the type of socket the message is received from see socket If no messages are available at the socket the receive call waits for a message to arrive unless the socket is non blocking or the MSG DONTWAIT flag is set in the flags parameter in which case 1 is returned with socket error being set to EWOULDBLOCK select may be used to determine when more data arrives or and when out of band data arrives tfRegisterSocketCB may be used to asynchronously determine when more data arrives or and when out of band data arrives tfRegisterlpForwCB 5 87 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter socketDescriptor bufferPtr bufferLength flags fromAddressPtr addressLengthPtr toAddressPtr Returns Value gt 0 1 Description The socket descriptor to use to receiv
577. te destination of an ICMP message is not an application program or user on the destination machine but the Internet Protocol software on that machine That is when an ICMP error message arrives the ICMP software modules handle it Of course if ICMP determines that a particular higher level protocol or application program has caused a problem it will inform the appropriate module 1 44 2004 Treck Incorporated Introduction to TCP IP So in other words The Internet Control Message Protocol allows routers to send error or control messages to other routers or hosts ICMP provides communication between the Internet Protocol software on one machine to the Internet Protocol software on another Initially designed to allow routers to report the cause of delivery errors to hosts ICMP is not restricted to routers Although guidelines restrict the use of some ICMP messages an arbitrary machine can send an ICMP message to any other machine Thus a host can use ICMP to correspond with a router or another host The chief advantage of allowing hosts to use ICMP is that it provides a single mechanism used for all control and information messages Error Reporting vs Error Correction Technically ICMP is an error reporting mechanism It provides a way for routers that encounter an error to report the error to the original source Although the protocol specification outlines intended uses of ICMP and suggests possible actions to take in response t
578. technology is called twisted pair Ethernet This technology allows the user to connect to the Ethernet using a pair of conventional unshielded copper wires similar to the wires used to connect telephones One obvious advantage to this method is reduced cost but it also protects other computers on the network from a user who disconnects a single computer Sometimes it is even possible to use existing telephone wiring for the Ethernet Known technically as 0Base T a twisted pair wiring scheme connects each computer on a network using Ethernet hubs An Ethernet hub is an electronic device that simulates the signals on an Ethernet cable The physical unit is a small box or hub that usually reside in the wiring closet or telephone room RJ 45 Plug x Cat 3 4 or 5 UTP Cable 100 meters max EXPANDED VIEW OF x AN RJ 45 PHONE JACK NL OUTGOING DATA 1 OUTGOING DATA 2 INCOMING DATA 1 INCOMING DATA 2 ERESIA Fig 1 5 Exploded View of Twisted Pair Cable Using this method only allows for a connection to be made between a computer and a hub within 100 meters A hub requires power and can be set up for authorized personnel to monitor and control its operation over the network An Ethernet hub provides the same communication capability as a thin or thick Ethernet They merely allow for alternative wiring schemes As we have discussed when using a thick Ethernet setup the con
579. tegrating into Your Environment tfKernelCreateEvent The function ffKernelCreateEvent is used to create a counting semaphore or binary semaphore of event flag It is only called from task level One event will be created per interface and per TM TASK XXXX macro defined For example if you have configured 2 interfaces and have defined TM TASK RECV TM TASK XMIT and TM TASK SEND then you will need 6 events At most one task will be waiting on that kernel primitive void tfKernelCreateEvent ttUserGenericUnionPtr eventPtr void semaphorePtr Initialize the semaphore to zero semaphorePtr RTOSSemCreate 0 if semaphorePtr void 0 eventPtr gt genVoidParmPtr void semaphorePtr else tfKernelError tfKernelCreateEvent Unable to Create Semaphore tm_thread_stop tfKernelPendEvent The function KernelPendEvent is used to pend on an event that will be posted to The task calling this function must wait indefinitely while waiting for the post event call It is only called from task level either from tfWaitReceiveInterface or from tfWaitXmitInterface or from tfWaitSentInterface Wait on an Event my void tfKernelPendEvent ttUserGenericUnionPtr eventPtr int kernelError RTOSSemPend eventPtr genVoidParmPtr 0 amp kernelError if kernelError RTOS NO ERR tfKernelError tfKernelPendEvent Unable to Pend on Semaphore tm thread stop 4 33 2004 Tr
580. tem hosting the remote file system Parameters Parameter fipSessionPtr bufferPtr bufferSize Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM _EINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL Description FTP session handle Pointer to buffer to receive result from SYST command Size of above result buffer Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Treck Real Time TCP IP User s Manual tfFtpTurnPasv int tfFtpTurnPasv ttUserFtpHandle ftpUserHandle int onFlag Function Description This function is used to set the mode of the FTP data connection on the peer FTP server Note that this API will not send the PASV command to the server It will merely set the mode on the FTP client session e Ifthe TM FTP PASSIVE MODE OFF flag is set then the peer FTP server will initiate the data connection i e connect on the data connec tion default setting e Ifthe TM FTP PASSIVE MODE ON flag is set then the peer FTP server will not initiate the connection on the data connection but rather wait for a data connection e The User can turn on
581. tems that you are attempting to debug It is VERY difficult to debug your RTOS interface Timer interface Device Driver and Application all at the same time From our experience we have found that most people have trouble with the device driver because it is where the software meets the hardware If you test first with loopback you can isolate your debugging to the RTOS Timer and Loopback application code first and debug the device driver last One interesting item about Treck protocols is that you do not need to recompile the protocol stack in order to add your device driver later so performing this task should not be too much of a burden If you are not familiar with sockets programming the loopback interface is a great place to learn Tip You should not attempt to add your device driver until you are confident that the stack is working correctly in loopback mode We have included an example of using the loopback interface It is not intended to be an example of using the protocol stack for high performance It is written to be easy to understand and follow Please feel free to use this code as a guide in writing your loopback test program 4 40 2004 Treck Incorporated Integrating into Your Environment Example Loop Back Application include lt trsocket h gt include lt stdio h gt for printf define TM_PORT_LOOPBACK_TEST htons 10 char bufferArray 1024 Example of a UDP socket loop back send and receive
582. teredSendTo include lt trsocket h gt int tfSocketScatteredSendTo int socketDescriptor ttUserBlockPtr userBlockPtr int userBlockCount ttUserFreeFuncPtr userFreeFunction int flags const struct sockaddr TM FAR toAddressPtr int toAddressLength e Function Description This function allows the user to send data on a non TCP socket directly from user owned scattered data buffers The user passes a pointer to an array of user block data of type ttUserBlock and the number of elements in the array Each ttUserBlock element contains a pointer to a user buffer a pointer to the beginning of the user data in the user buffer and the user data length in the user buffer Upon return from this routine the user can reuse the array of ttUserBlock but the Treck stack owns the user buffers that were pointed to by the ttUserBlock elements The only excep tion is when TM SOCKET ERROR is returned and the errorCode retrieved with tfGetSocketError is TM EWOULDBLOCK In that case the user still owns the buffers and should try to resend the same buffers later on The userFreeFunction will be called by the Treck stack for each user buffer when the data has been sent out on the network and the device driver no longer needs to access the data in the user buffer An example of tfSocketScatteredSendTo usage is shown in the loop back test module txscatlp c If the user uses a preemptive kernel i e TM TRECK PREEMPTIVE KERNEL is defin
583. terfaces sse 4 72 Device driver open function ssssssssesseeeeeeeenns 4 72 Device driver close function 4 72 Amy device driver FUNCHON sospese tere eR P eurer eer sinn 4 72 Device driver ISR Ha dler olestie reet emet 4 73 Adding and Configuring your New Device Driver 4 74 Single Send Call Send per Frame Out of Order Send 4 77 DD SCHDIOR eave ere te eee pe eer ere rac ere eee nn eer er 4 77 Single call to the driver send per scattered frame 477 Out of Order Frame Transmission 477 TM USE DRV ONE SCAT SEND si ses 4 77 Modified driverSend ccceecccsseceseecessceseecesecsseeeeeeceeseseeseeeseaeeeeesens 4 77 tiUselntertaceOneScatS end xvas ied inden acc 4 79 Ic eer 4 80 tfSendCompletePacketInterface ssssseeeeenees 4 81 Limitations NR m 4 81 Device Driver Scattered recv Gather Read 4 82 Description siue ot eiiam ge ire etats 4 82 TM USE DRV SCAT RECV noorem a pa 4 82 Modified driver recv routine esssssssssseeeeeeneneennen 4 82 tiUselnterfaceS catR ECY Re tien 4 84 tfRecvScatInterface sesssssseseseeeeeeeeene nnne enne ener ennt 4 84 Scattered recv contiguous length threshold used in tfRecvScatInterface 2004 Treck Incorporated 4 85 Dealing with non contiguous network protocol headers in scattered recv buffers TM RECV SCAT MIN INCR BUF 4 85 I cni RE 4 86 No copy loop back d
584. tfSPrintF myBuffer This is example number d 1 result This is example number 1 call tfSPrintf myBuffer This is s number d example 2 output This is example number 2 Code Description c Print a character d Print a signed decimal integer e Scientific notation prints a lower case e E Scientific notation prints an upper case E f Decimal floating point g Choose between e or f depending on which is shorter G Choose between E or F depending on which is shorter Yi Print a signed decimal integer on The value to which n corresponds is a pointer to a variable representing the number of characters successfully output 0 Print an unsigned octal p Show a pointer s Print a string up to the first null character encountered You Print an unsigned decimal integer Vox Print an unsigned hex integer lowercase SX Print an unsigned hex integer uppercase 5 Print a percent sign 5 250 2004 Treck Incorporated Programmer s Reference Parameters Parameter Description buffer The string to be written format The string containing the format specifiers Returns A number representing the number of characters put into an array 5 251 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSScanF int const char const char Function Description tfSScanF buffer format This function is used to parse a string it reads data from buffer into locations des
585. th same name has already been added Not enough buffers to allocate a device entry 5 195 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfWaitReceivelnterface include lt trsocket h gt int tfWaitReceiveInterface ttUserInterface interfaceHandle Function Description This function is used to wait for the tfNotifyInterfacelsr routine to be called from the device driver s receive interrupt service routine If there is no call to tfNotifyInterfacelsr then it waits It returns each time that there is ONE new packet to be received which is signaled by tfNotifylnterfacelsr The caller should then call tfRecvInterface when this call completes successfully Note tfWaitReceiveInterface can only be used when there is a separate receive task Parameters Parameter Description interfaceHandle The interface handle for the device we wish to wait for data for Returns Value Meaning 0 Success TM ENOBUFS Insufficient memory to complete operation 5 196 2004 Treck Incorporated Programmer s Reference tfWaitSentinterface include lt trsocket h gt int tfWaitSentInterface ttUserInterface interfaceHandle Function Description This function is used to wait for a tfNotifyInterfacelsr function to be called from the transmit complete interrupt service routine if there is none then it waits This function will wait until the accumulated numberBytesSent notified by tfNotifyInterfacelsr has re
586. that could not be transmitted along with its length and flag is stored in an empty slot in the Treck device transmit queue The device transmit queue should be big enough to hold pointers to all the buffers that will be sent by the application The size of the data sent by an application is limited by the socket send queue size So an interface transmit queue should be big enough to hold pointers to buffers sent from all the application sockets through that particular interface The space allocation overhead for a x entries device transmit queue is 12 x 8 bytes So for a device transmit queue containing 1000 slots the overhead is 8012 bytes Note This function can only be called when the device is not configured Cannot be called for a point to point interface Cannot be called if a transmit task is used If the interface transmit queue is enabled the user should call errorCode tfloctlInterface interfaceHandle TM DEV IOCTL EMPTY XMIT FLAG void 0 0 periodically to try and empty the device transmit queue which contains all the buffers that the device driver could not send right away 5 190 2004 Treck Incorporated Parameters Parameter interfaceHandle numberXmitDescriptors Returns Value 0 TM_ENOBUFS TM EPERM Programmer s Reference Description The Interface Handle of the device we are waiting to be ready Length of the transmit queue If positive the interface transmit queue
587. the operation Only diagnostic or routing programs use it 5 110 2004 Treck Incorporated MSG SCATTERED Returns Value gt 0 1 tfZeroCopySendTo will fail if TM_EBADF TM_EHOSTUNREACH TM_ EMSGSIZE TM_EPROTOTYPE TM_EWOULDBLOCK TM_EFAULT TM_EINVAL Programmer s Reference Set this flag when sending a scattered zero copy recv buffer received with fZeroCopyRecvFrom See tfZeroCopyRecvFrom Note that to send a user scattered buffer not obtained via a call to tfZeroCopyRecvFrom then tfSocketScatteredSendTo can be used Meaning Number of bytes sent An error has occurred The socket descriptor is invalid No route to destination host The socket requires that message be sent atomically and the message was too long TCP protocol requires usage of tfZeroCopySend not tfZeroCopySendTo The socket is marked as non blocking and the send operation would block bufferHandle does not correspond to a zero copy buffer One of the parameters is bad the bufferLength lt 0 ora flag not listed above is set or toAddressPtr is null or toAddressLength does not equal the sizeof struct sockaddr_in 5 111 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfZeroCopyUserBufferSend include lt trsocket h gt int tfZeroCopyUserBufferSend int socketDescriptor char userBufferPtr char userDataPtr int userDataLength ttUserFreeFuncPtr userFreeFunction int flags
588. the design of PPP addresses has three areas of functionality Encapsulation How PPP nests within the stack of protocols that make up the entire communications environment in a network Link Control Protocol How PPP establishes configures and monitors the data link connection Network Control Protocols How PPP interacts with a variety of network layer protocols including IP PPP requires that both sides negotiate a link for what they both will accept and how the link will operate Characteristics such as the maximum size of the datagram that a given peer will accept the authentication protocol if any that should be applied to datagrams originating from that sender and compression schemes are all open to negotiations between the two systems being linked via PPP This negotiation takes the form of a series of packet exchanges until both systems have agreed to the parameters under which the link will operate PPP is intended for use in simple links that transport datagrams between two peers PPP supports full duplex lines with simultaneous bi directional traffic Unlike some link level protocols PPP assumes that datagrams arrive in the order they were sent Within this limitation PPP offers an easy connection protocol between hosts bridges routers and client computers Previously SLIP was the preferred protocol for dial up links Now however PPP is almost exclusively used for dial up links because of its flexibility In particular th
589. the device with a broadcast address Not enough memory to complete operation Bad parameter i e bad interface handle or multi home index out of boundaries not between 0 and TM MAX IPS PER IF The interface has already been configured at this mult home index Programmer s Reference tfCheckReceivelnterface include lt trsocket h gt int tfCheckReceiveInterface ttUserInterface interfaceHandle Function Description This function is used to check if the data is waiting to be received on a particular device interface This call can be used in environments where it is preferable to poll the device for received data i e a main loop If you are using a separate task or thread to receive data then you should use the tfWaitReceiveInterface call The call is used is used in conjunction with tfNotifyInterfacelsr and tfRecvInterface to poll the device driver for received data Upon a successful return the user should call tfRecvInterface to send the data from the device driver to the protocol stack Note There must be a one to one correspondence from the number of received packets parameter in tfNotifyInterfacelsr to the number of tfRecvInterface calls Parameters Parameter Description interfaceHandle The interface handle to poll to see if data needs to be received from the device driver Returns Value Meaning 0 There is data waiting in the device driver to be received the driver has called tfNotifyInter
590. thernet On a thin wire Ethernet network the costly bulky transceivers were replaced with digital high speed circuits That enabled direct connection from a computer to the Ethernet Now instead the computer contains both the circuitry and the host interface This is beneficial to manufacturers of small computers and workstations because they can integrate Ethernet hardware into single board computers and mount connectors directly to the back of the computer This method is also beneficial if many computers occupy a single room The thinnet cable runs from one computer workstation directly to another Another computer can be added by simply connecting that computer to another on the thinnet chain The disadvantage to this is that it enables users to manipulate the ether If it is disconnected all the computers in the chain are unable to communicate However in most cases the advantages outweigh the disadvantages This method uses BNC connectors to connect to the Ethernet This is much simpler that coaxial cable A BNC connector can be installed easily without the use of any tools Therefore a user can connect to the Ethernet without the aid of a technician 1 9 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Twisted Pair Ethernet In the last few years technology has made advancements that have made it possible to construct an Ethernet that no longer needs electrical shielding of a coaxial cable This type of Ethernet
591. thernet or PPP Now that you are comfortable that the stack and interfaces to it are working correctly you are ready to include the link layer that you wish to use For this operation you will need to define a handle to store the desired link layer into We call this a link layer handle and it is defined as a UserLinkLayer type Adding or using a link layer is a simple process You simply call link layer USE function to pull in the appropriate link layer from the library These functions are called UseEthernet tfUseAsyncPpp tfUseAsyncServerPpp and fUseNullLinkLayer The null link layer is used to pass raw IP datagrams directly to from the device driver interface This way you can use the device driver interface to hookup a new link layer In the base TCP IP package you will receive both the Ethernet and Null link layers Examples of this follow ttUserLinkLayer ethernetHandle ttUserLinkLayer pppServerHandle ttUserLinkLayer pppClientHandle ttUserLinkLayer nullLinkHandle Select the Ethernet DIX protocol ethernetHandle tfUseEthernet Select the PPP server Link Layer Protocol pppServerHandle tfUseAsyncServerPpp notifyServerFuncPtr Select the PPP Client Link Layer Protocol pppClientHandle tfUseAsyncPpp notifyClientFuncPtr Select the NULL Link Layer nullLinkHandle t fUseNullLinkLayer Note PPP is an optional protocol and if you did not purchase PPP and attempt to call tf
592. this 1s not the case Replace taskIdPtr genInParm and tskIdUnion genIntParm located in tfKernelGetCurrentTaskId and tfTaskIdToIndex with the appropriate data type as defined in ttUserGenericUnion The user must modify the following macros TM NUMTSK This is the number of tasks making calls to the Treck stack Default 12 tm task lower same This macro is defined as taskAPri lt taskBPri If priorities are arranged so that lower values have higher priority modify the macro to taskAPri gt taskBPri AA 2004 Treck Incorporated Configuration Notes The user must define the following functions tfKernelGetCurrentTaskld int tfKernelGetCurrentTaskId ttUserGenericUnionPtr taskIdPtr Function Description The user must write this function to make use of their specific operating system This function stores the task ID of the currently running task in taskIdPtr Parameters Parameter Description taskIdPtr Pointer to a ttUserGenericUnionPtr into which the task ID is stored Returns TM_KERN OK A 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfKernelTaskPendEvent void tfKernelTaskPendEvent ttUserGenericUnionPtr eventPtr Function Description The user must write this function to make use of their specific operating system This function pends on an event pointed to by eventPtr which is posted from another task This should be similar if not identical to tfKernelPe
593. this macro you will notice that the code is much larger than without it However you will see a noticeable increase in speed Typically this macro is used to in line functions that are used repeatedly TM OPTIMIZE SIZE This macro is used to optimize the code in favor of size over speed When using this macro you will get the smallest code size available You will notice that the performance of the system is degraded when you use this macro This macro is to be used when the performance of the system does not matter but code size does 4 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual TM_ERROR_CHECKING This macro is used to turn on error checking for the protocol stack It is used for debugging purposes it is not intended for use in your released product The error checking will send messages to the functions ffKernelError and tfKernel Warning for you to log There is a performance and size impact when using this macro TM_THREAD_STOP Thread stop is used to stop a thread which has had an unrecoverable error By default it is defined as a forever loop You can define this macro to supersede the default definition TM_PROTO_EXTERN By default the prototypes declared in the Treck header files are not declared extern If your linker dictates that they should be declared extern then add the following macro define TM_PROTO_EXTERN extern TM_LOOP_TO_DRIVER If this macro definition is added to trsystem h it will a
594. ticast group can be reached with a single packet transmission Computers that choose not to participate in a particular multicast group do not receive packets sent to the group To accommodate broadcast and multicast addressing Ethernet interface hardware must recognize more than its physical address A host interface usually accepts at least two kinds of packets those addressed to the interface s physical address and those addressed to the network broadcast address Some interfaces can be programmed to recognize multicast addresses or even alternate physical addresses When the operating system starts it initializes the Ethernet interface giving it a set of addresses to recognize The interface then examines the destination address field in each packet passing on to the host only those transmissions designated for one of the specified addresses 1 14 2004 Treck Incorporated Introduction to TCP IP Special Bits of an Ethernet Address Under universally administrated addressing a unique address is embedded in ROM on each network interface The first three bytes of the 48 bit address identify the manufacturer of the adapter the remaining bits identify the adapter card number Under locally administrated addressing the user is responsible for configuring the source address of each workstation 0 8 16 24 31 Hardware Type Protocol Type Hardware Address Protocol Address Length Length Sender Hardware Address Bytes 0 3
595. timates 5 182 2004 Treck Incorporated Programmer s Reference tfUnConfigInterface include trsocket h int tfUnConfigInterface ttUserInterface interfaceld unsigned char mult iHomeIndex Function Description This function is used to remove an IP address from an interface for a particular multi home index By un configuring an interface we can then re configure it with a new IP address and netmask Parameters Parameter Description interfaceld The device entry multiHomelndex The Index for this IP address Returns Value Meaning 0 Success TM_EINVAL One of the parameters is invalid TM ENOENT Interface was not configured 5 183 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUselnterfaceOneScatSend include lt trsocket h gt int tfUseInterfaceOneScatSend ttUserInterface interfaceHandle ttDevOneScatSendFunc devOneScatSendFunc Function Description Specify a driver driver scattered send function that is called once per frame even when the data is scattered on a given interface tfUseInterfaceOneScatSend must be called prior to calling tfConfigInterface and after having called tfAddInterface to replace the device driver send function specified in tfAddInterface Once tfUseInterfaceOneScatSend has been called the device send logic in the Treck stack will call the specified single call device driver scattered send function instead of the one provided in tfAddInterface
596. tion tfBindNoCheck assigns an address to an unnamed socket When a socket is created with socket it exists in an address family space but has no address assigned tfBindNoCheck requests that the address pointed to by addressPtr be assigned to the socket Clients do not normally require that an address be assigned to a socket However servers usually require that the socket be bound to a well known address The port number must be less than 32768 TM_SOC_NO_INDEX or could be OxFFFF TM WILD PORT Binding to the TM WILD PORT port number allows a server to listen for incoming connection requests on all the ports This function is similar to bind except that bind checks that the address that the user wants to bind to is a valid configured address on an interface tfBindNoCheck does not check for that and allows the user to bind to any IP address Parameters Parameter Description socketDescriptor The socket descriptor to assign an IP address and port number to addressPtr The pointer to the structure containing the address to assign addressLength The length of the address structure 5 71 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value Meaning 0 Success 1 An error occurred tfBindNoCheck can fail for any of the following reasons TM_EADDRINUSE The specified address is already in use TM_EBADF socketDescriptor is not a valid descriptor TM_EINVAL One of the passed parameters is invalid
597. tion socketDescriptor The socket descriptor to flush the socket receive buffer for Returns Value Meaning TM ENOERROR This function always returns TM ENOERROR 5 74 2004 Treck Incorporated Programmer s Reference tfFreeDynamicMemory include lt trsocket h gt int tfFreeDynamicMemory void Function Description This function frees all memory allocated dynamically by the Treck internal memory management system Called by the user when the user does not want to use the Treck stack anymore and wants all currently unused memory to be returned to the user s system Note The user cannot free the Treck Dynamic memory if the user uses the Treck simple heap Returns Value Meaning 0 Success TM ENOENT The user cannot free the dynamic memory either because the user had disabled the dynamic memory by defining the following macro TM DISABLE DYNAMIC MEMORY in trsystem h or because the user uses the Treck simple heap 5 75 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfFreeZeroCopyBuffer include lt trsocket h gt int tfFreeZeroCopyBuffer ttUserMessage bufferHandle Function Description This function is used to free a zero copy buffer that was allocated via tfGetZeroCopyBuffer tfZeroCopyRecv or tfZeroCopyRecvFrom Parameters Parameter Description buffer Handle The buffer handle of the buffer to free Returns Value Meaning 0 Success l Error The buffer did not belong
598. tion Reference tfFtpCwd include lt trsocket h gt int tfFtpCwd ttUserFtpHandle ftpSessionPtr char pathNamePtr Function description Changes directory on the remote file system Parameters Parameter fipSessionPtr pathNamePtr Returns Value TM ENOERROR TM WOULDBLOCK TM EACCES TM ENOTCONN TM_EINVAL TM FTP SYNTAXCMD TM FTP SYNTAXARG TM FTP NOCMD TM FTP SERVNAVAIL TM FTP NOTLOGIN TM FTP NAVAIL TM FTP NOCMD Description FTP session handle New directory name Meaning Success This FTP session is non blocking and the call did not complete Previous command did not com plete The user is not currently connected to a FTP server Invalid FTP session pointer Syntax error command unrecog nized Syntax error in parameters or arguments Command not implemented Service not available closing TELNET connection Not logged in Requested action not taken file unavailable Command not implemented Treck Real Time TCP IP User s Manual tfFtpDele include lt trsocket h gt int tfFtpDele ttUserFtpHandle ftpSessionPtr char pathNamePtr Function description This function deletes file on remote file system Parameters Parameter Description fipSessionPtr FTP session handle pathNamePtr Filename to delete Returns Value Meaning TM ENOERROR Success TM WOULDBLOCK TM EACCES TM ENOTCONN TM ENOTLOGIN TM BINVAL TM FTP SYNTAXCMD TM FTP SYNTAX
599. tion request and sent to the underlying protocol layers Sockets of type SOCK STREAM are full duplex byte streams A stream socket must be in a connected state before any data may be sent or received on it A connection to another socket is created with connect on the client side On the server side the server must call listen and then accept Once connected data may be transferred using recv and send calls or some variant of 5 61 2004 Treck Incorporated Treck Real Time TCP IP User s Manual the send and recv calls When a session has been completed a close of the socket should be performed The communications protocols used to implement a SOCK_STREAM ensure that data is not lost or duplicated If a piece of data for which the peer protocol has buffer space cannot be success fully transmitted within a reasonable length of time then the connection is consid ered broken and calls will indicate an error with 1 return value and with TM_ETIMEDOUT as the specific socket error The TCP protocols optionally keep sockets warm by forcing transmissions roughly every two hours in the ab sence of other activity An error is then indicated if no response can be elicited on an otherwise idle connection for an extended period for instance 5 minutes SOCK DGRAM or SOCK RAW sockets allow datagrams to be sent to corre spondents named in sendto calls Datagrams are generally received with recvfrom which returns the next datagram with its ret
600. to the size of the message or message length and the UDP checksum 0 16 31 UDP SOURCE PORT UDP DESTINATION PORT UDP MESSAGE LENGTH UDP CHECKSUM DATA Fig 1 34 Format of Fields in a UDP Datagram The SOURCE PORT and DESTINATION PORT fields contain 16 bit UDP protocol numbers which are used as application identifiers among the processes waiting to receive them The SOURCE PORT is optional However when it is used it specifies the port to which replies should be sent If the field is not used it should be set to Zero The LENGTH field contains a count of bytes in the UDP datagram including the header and the user data The minimum number that can be in this field is eight the length of the header by itself As we mentioned earlier the CHECKSUM field is optional A value of zero in the checksum field indicates that the checksum has not been computed 1 50 2004 Treck Incorporated Introduction to TCP IP UDP Pseudo Header To compute a checksum UDP attaches a pseudo header to the UDP datagram and pads the datagram with one byte of zeros and then computes the checksum over the entire object It is important to remember that the padding of zeros and the pseudo header are not transmitted with the UDP datagram nor are they included in the length The purpose of using a pseudo header is to verify that the UDP datagram has reached the appropriate destination The pseudo header is not transmitted to the reci
601. to a file tfFSWriteFileRecord Write a record from a buffer to a file Note File system calls for the FTP server can be found in the File System Section of this manual 6 22 Application Reference tfFtpdUserExecute include lt trsocket h gt int tfFtpdUserExecute void Function description This function executes the Ftp server main loop This call is valid only if tfFtpdUserStart has been called in non blocking mode and tfFtpdUserExecute is not currently executing Parameters None Returns Value Meaning 0 Success TM EPERM Ftp server currently executing or has not been started or has been stopped 6 23 Treck Real Time TCP IP User s Manual tfFtpdUserStart include lt trsocket h gt int tfFtpdUserStart int fileFlags int maxConnections int maxBackLog int idleTimeout int blockingState Function Description This function opens an FTP server socket and starts listening for incoming connections tfFtpdUserStart can be either blocking or non blocking as specified by its blockingState parameter Blocking Mode In blocking mode tfFtpdUserStart should be called from a task tfFtpdUserStart will not return unless an error occurs It will block and wait for incoming connections and execute the FTP server code in the context of the calling task Choose the blocking mode if you are using an RTOS Kernel Non Blocking Mode In non blocking mode tfFtpdUserStart will return immediately
602. to be included include lt trsocket h gt include lt trmacro h gt include lt trtype h gt include lt trproto h gt include lt trglobal h gt Parameters Parameter Description interfaceHandle Interface Id as returned by tfAddInterface Returns Value Meaning Non zero pointer Success void 0 No pointer was stored on the interface Note See also t DeviceClearPointer fDeviceStorePointer 5 144 2004 Treck Incorporated Programmer s Reference tfDeviceStorePointer include lt trsocket h gt int tfDeviceStorePointer ttUserInterface interfaceHandle void deviceDriverPtr Function Description In the device driver open function after having allocated a device driver specific structure call tfDeviceStorePointer to store a pointer to that structure on the interface Parameters Parameter Description interfaceHandle Interface Id as returned by tfAddInterface deviceDriverPtr Device Driver Pointer to be stored on the interface Returns Value Meaning TM ENOERROR Success TM EALREADY A device driver pointer was already stored on that interface TM EINVAL Invalid interface handle Note See also tfDeviceClearPointer fDeviceGetPointer 5 145 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfFinishOpeninterface nclude lt trsocket h gt p nt tfFinishOpenInterface tUserInterface interfaceHandle tUserlpAddress ipAddress tUserlpAddress netMask dde Functi
603. to retrieve results and statistics of the PING connection such as number of packets transmitted number of packets received round trip time of the last PING echo request error code as given by a received network ICMP error message etc The user passes the socket descriptor returned by tfPingOpenStart as the first param eter to tfPingGetStatistics and a pointer to a ttPingInfo structure as the second parameter where the system will copy the results and statistics of the PING con nection if the tfPingGetStatistics returns with no error The user can be notified of incoming PING echo replies or incoming ICMP error messages if he specifies a non null call back function pointer as the last parameter to tfPingOpenStart In that case the call back function is called every time a PING echo reply or an ICMP error message is received The call back function takes one parameter the socket descriptor as returned by the tfPingOpenStart The user can then retrieve the PING connection information by calling tfPingGetStatistics 6 4 Application Reference tfPingClose include lt trsocket h gt int tfPingClose int socketDescriptor Function Description This function stops the sending of any PING echo requests and closes the ICMP socket that had been opened via tfPingOpenStart Parameters Parameter Description socketDescriptor An ICMP PING socket descriptor as returned by tfPingOpenStart Returns Value Meaning 0 Success 1 An e
604. to rie rre ra a SURE EXT eR dans 4 6 TM IP REASSEMBLY iato eG D YER ERES TEESE EE 4 6 TM IP FRAGMENT NO COPY seen 4 6 TM DISABLE PMTU DISC iicet re Re nr a ex edes 4 6 TM DISABLE TCP SACK ss 4 6 TM TOP BACK iiie o FG EOREEEU ROT EI EEUU HER EI ETE ERES 4 7 TM USE TCP PACKET 55r rom rne FER de HP Eaton 4 7 TM DISABLE DYNAMIC MEMORY ss 4 7 TM ARP UPDATE ON RECV eee 4 7 TM OPTIMIZE SPEED dore OU er o EEES 4 7 TM OPTIMIZE SIZE tiitrhre nei pe e Hat 4 7 TM ERROR CHECKING cees eoi e er neon rd heats 4 8 TM THREAD STOP trit nr ebrei eR 4 8 TM PROTO EXTERN 55 IHR RU HEISE NER uen nel 4 8 TM LOOP TO DRIVER iiiter err err ra pre eer 4 8 TM USE DRV ONE SCAT SEND esee 4 8 TM USE DRY SCAT RECV us 4 8 TM INDRV INLINE SEND RECV UN 4 8 TM DISABLE TCP ACK PUSH 4 eere 4 9 TM SINGLE INTERFACE HOME sn 4 9 TM MULTIPLE CONTEXT nter th teer ther erre rei orb a 4 9 TM DISABLE ANSI LINE FILE ns 4 9 TM DISABLE TCP RFC2414 us 4 9 TM DISABEE TCP REC2581 5i onec echter me reris 4 9 TM DISABLE TCP RFC3042 ss 4 9 TM DEV SEND OFFLOAD 3er rm ep er S PX concerns 4 9 TM DEV RECV OFFLOAD sisi 4 10 TM USER OCS es seen nn ener eee De re rtt ete e tea 4 10 2004 Treck Incorporated TM PC LINT ep 4 10 API SG ANNE dtt nite etude Mei SLE ELT 4 10 TM USE AUTO IP ior eicere teer ee ee eerte teu 4 10 TM USE RAW SOCKET hU ner ees 4 10 TM RAW SOCKET INPUT ICMP REQUESTS 4 10 TM PING REPLY BROADCAST
605. to select a listening socket for the purpose of an accept by selecting it for a read However this will only indicate when a connect indication is pending it is still necessary to call accept Using tfRegisterSocketCB prior to calling accept Alternatively the user could issue a tfregisterSocketCB call on the listening socket with a TM CB ACCEPT event flag to get an asynchronous notification of an incoming connection request Again this will only indicate that a connection request is pending it is still necessary to call accept after having received the asynchronous notification 5 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Parameters Parameter Description socketDescriptor The socket descriptor that was created with socket and bound to with bind and is listening for connections with listen addressPtr The structure to write the incoming address into addressLengthPtr Initially it contains the amount of space pointed to by addressPtr On return it contains the length in bytes of the address returned Returns New Socket Descriptor or 1 on error If accept fails the errorCode can be retrieved with tfGetSocketError socketDescriptor which will return one of the following error codes TM EBADF The socket descriptor is invalid TM_EINVAL addressPtr was a null pointer TM_EINVAL addressLengthPtr was a null pointer TM_EINVAL The value of addressLengthPtr was too small TM ENOBUFS There was ins
606. tpUserHandleB char TM FAR fromFileNamePtr char TM FAR toFileNamePtr Function Description This function is used to transmit a file to remote FTP server corresponding to fipUserHandleA This function is implemented for both passive mode and normal mode and also works with both one FTP server model and two FTP servers model e One server model If the fipUserHandleB parameter is NULL then the one server model is used and the operation could be either in server active mode or server passive mode By default the server is in active mode The user needs to call tfFtpTurnPasv with the TM FTP PASSIVE MODE ON flag to turn the server in passive mode e Two server model If the fipUserHandleB parameter is non null then the two server model is used and the first session should be in passive mode and the second session should be in active mode The user needs to call tfFtpTurnPasv passing the fipUserHandleA parameter and the TM FTP PASSIVE MODE ON Parameters Parameter Description fipUserHandleA The user handle of main FTP session will be operated on fipUserHandleB The user handle of the 2nd FTP session for two FTP server model fromFileNamePtr Pointer to source file name string toFileNamePtr Pointer to destination file name string 6 60 Returns Value TM EWOULDBLOCK TM_EINVAL TM_EACCES TM_ENOTLOGIN TM ENOTCONN TM EOPNOTSUPP TM ENOERROR TM FTP XFERSTART TM FTP FILEOKAY TM FTP DATAOPEN TM FTP XFE
607. tr1 is equal to stringPtr2 Greater than Zero stringPtrl is greater than stringPtr2 5 256 2004 Treck Incorporated Programmer s Reference tfStrCpy int tfStrCpy char destinationPtr const char sourcePtr Function Description This function copies the contents of one array pointed to by sourceptr and places it in the array pointed to by destinationPtr The array pointed to by destinationptr must be large enough to hold the contents of the array pointed to by sourcePtr If the two arrays overlap the behavior is undefined Parameters Parameter Description destinationPtr The array to which data 1s copied sourcePtr The array from which data is copied Returns destinationPtr 5 257 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfStrCSpn int tfStrCSpn char destinationPtr const char sourcePtr Function Description This function searches for any characters in sourcePtr that also appear in the destinationPtr and returns the offset ofthe first matched character in destinationPtr Parameters Parameter Description destinationPtr The string to be searched sourcePtr A list of the characters to be searched for in destinationPtr Returns Offset of the first matched character in destinationPtr 5 258 2004 Treck Incorporated Programmer s Reference tfStrError int tfStrError int errorcode hr Function Description This function returns the error message correlated
608. transmit queue is used Returned by device driver send function Programmer s Reference tfZeroCopyRecv include lt trsocket h gt nt tfZeroCopyRecv t SocketDescriptor UserMessage bufferHandlePtr ar dataPtrPtr t maxBufferLength t flags p bp Ot HA H Bo ARA EF 42 RT Function Description This function is used to recv a zero copy message It operates identically to recv with the exception that it takes a zero copy buffer handle as a parameter and puts the beginning of the data into a passed pointer However it does not support the MSG OOB flag since there is only one byte of out of band data and it would be inefficient to use the tfZeroCopyRecv in that case To recv out of band data the recv call should be used instead Note The user must call tfFreeZeroCopyBuffer in order to free the buffer after the user has finished with it Parameters Parameter Description socketDescriptor The socket descriptor to send data to bufferHandlePtr The zero copy buffer that contains the message dataPtrPtr A pointer to a char pointer where the start of the data 1s stored maxBufferLength The length of the message flags See below 5 99 2004 Treck Incorporated Treck Real Time TCP IP User s Manual The flags parameter is formed by ORing one or more of the following MSG_DONTWAIT Don t wait for data but rather return immediately MSG PEEK Peek at the data present on the socket the data
609. ts 7 21 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Returns Value 0 TM_EINVAL TM_EMFILE TM ADDRINUSE TM EALREADY 7 22 2004 Treck Incorporated Meaning Success Invalid interface handle or multi home index or invalid IP address Not enough sockets to open the BOOTP relay agent UDP socket Another socket is already bound to the BOOTP relay agent UDP port tfStartBootRelayAgent has already been called successfully Optional Protocols tfStopBootRelayAgent include lt trsocket h gt int tfStopBootRelayAgent void Function Description This function is called to stop the BOOTP relay agent This will close the UDP BOOTP relay agent UDP socket Parameters None Returns Value Meaning 0 Success TM EALREADY tfStopBootRelayAgent has already been called successfully 7 23 2004 Treck Incorporated Treck Real Time TCP IP User s Manual DHCP Automatic Configuration API Description The DHCP user interface allows the user to query directly a DHCP server for IP addresses that the user can use The Treck stack allows the user to retrieve the DHCP addresses automatically When the user configures an interface multihome the Treck stack automatically queries a DHCP server for an IP address and parameters and finishes configuring the interface multihome with the IP address and default router given by the DHCP server UptoTM MAX IPS PER IF multihomes per interfa
610. ts writing to a file making up a new name if the file name already exists Supports append to a file Supports renaming of file name Supports deletion of file Supports removing directory Supports making directory Supports retrieving the current working directory Supports long listing of directory file 6 25 Treck Real Time TCP IP User s Manual names volume and directories TM FS NLST FLAG Supports short listing of directory file names only TM FS CR LF FLAG The file system end of line is CR LF TM FS RECORD FLAG The file system supports record structures If this flag is set the FTP server will interpret the FTP record bytes if the FTP client transfers data with record structure TM FS ALLCMND MASK ORing of all above command flags Returns Value Meaning 0 Success TM EINVAL Incorrect file flag specified TM EINVAL maxConnections is either negative or if non zero exceeds or equals the current number of available FTP connections TM EINVAL maxBackLog is either negative or null or exceeds or equals the current number of available FTP connections TM EINVAL The idle timeout is less than 300 seconds TM EINVAL blockingState is neither TM BLOCKING ON nor TM BLOCKING OFF TM EALREADY tfFtpdUserStart has already been called TM EMFILE No more socket available to open the FTPD listening socket TM ENOBUFS Insufficient user memory available to complete the operation TM EADDRINUSE The FTP server po
611. ttUserPacketPtr 0 tm_assert testzUdp msgLength 0 recvPacketUPtr ttUserPacketPtr recvMessageHandle tm_assert testzUdp extraCount recvPacketUPtr gt pktuLinkExtraCount Note See also fZeroCopySend Returns Value Meaning 0 EOF gt 0 Number of bytes received 1 An error has occurred tfZeroCopyRecv will fail if TM EBADF The socket descriptor is invalid TM ENOBUFS There was insufficient user memory available to complete the operation 5 102 2004 Treck Incorporated TM EMSGSIZE TM EWOULDBLOCK TM ESHUTDOWN TM_EINVAL TM ENOTCONN Programmer s Reference The socket requires that message be received atomically and bufferLength was too small The socket is marked as non blocking or the MSG DONTWAIT flag is used and no data is available to be read The remote socket has closed the connection and there is no more data to be received TCP socket only One of the parameter is invalid Socket is not connected 5 103 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfZeroCopyRecvFrom include lt trsocket h gt nt tfZeroCopyRecvFrom t socketDescriptor UserMessage bufferHandlePtr ar dataPtrPtr maxBufferLength flags uct sockaddr fromAddressPtr d fromAddressLength n n n n n PAU HE Q tb H TK cf Cc e Function Description This function is used to recv a zero copy message It operates identically to recvfrom with the exception tha
612. tting up the compiler and library utility primitives Here you simply create a batch file BAT that contains the compiler command line The first parameter 1 is the file to compile without the C extension The second parameter is optional but is typically used for a define that is passed to the compiler when building the Treck code An example of this is as follows File bcl86cc bat echo off if 2 goto noopt bcc v ml 1 c w9999 I trhome include D 2 1 c gt l err goto end noopt bcc v ml 1 c w9999 I trhome include 1 c gt l err end This file could have been as simple as this bcc v ml 1 c w9999 I trhome include 1 c gt l err 4 19 2004 Treck Incorporated Treck Real Time TCP IP User s Manual That is all there is to the compile batch file but we still need a library batch file We do the same thing for the library utility Notice that the library utility does not use the second parameter 2 and the first parameter is the same as in the compile command line An example of this is as follows File bc86lib bat echo off tlib treck 1 ob j An important thing to note is that our command line only adds a single object to the library You should place both of these files into the TRECKBIN directory Now that you have completed these two tasks you can build the Treck Library Tier 2 Compile Library all the Treck code The batch files that are used for this tier are cal
613. turns Value Meaning 0 Success TM_EINVAL Parameter is invalid TM EALREADY The device is already closed TM EINPROGRESS If the connection is in the process of closing the connection as in PPP The user doesn t need to do anything and will be notified by the PPP link layer when the interface is actually closed 5 138 2004 Treck Incorporated tfConfiginterface Programmer s Reference include lt trsocket h gt UserlInterface UserlpAddress UserlpAddress D D CT CT crt nsigned char amp p op ct oct oc o b F Function Description tfConfigInterface interfaceHandle ipAddress netMask flag buffersPerFrameCount multiHomeIndex This function is used to configure an interface with an IP address and net mask either supernet or subnet Can be used for Multiple IP Addresses on an Interface Multihoming It must be called before the interface can be used An example would be errorcode tfConfigInterface myInterfaceHandle inet addr 208 229 201 65 inet addr 255 255 255 0 0 1 unsigned char 0 Note tf ConfigInterface is deprecated for the first multihome Please use tfOpenInterface for the first multihome configuration instead of tfConfig Interface 5 139 2004 Treck Incorporated Treck Real Time TCP IP User s Manual DHCP or BOOTP configuration tfConfigInterface with a TM DEV IP DHCP respectively TM DEV IP BOOTP flag will send a DHCP respectively BO
614. ty Report messages when link quality monitoring is enabled therefore this option value should not be set to 0 for both ends of the link 7 91 2004 Treck Incorporated Treck Real Time TCP IP User s Manual IPCP TM_PPP_IPCP_PROTOCOL Option Name TM_IPCP_COMP_PROTOCOL TM_IPCP_MAX FAILURES TM IPCP VJ SLOTS TM IPCP IP ADDRESS TM IPCP DNS PRI TM IPCP DNS SEC 7 92 2004 Treck Incorporated Len Meaning Specifies the type of compression to use over the link Currently only VJ TCP IP header compression is available which is defined as TM PPP COMP TCP PROTOCOL Default No Compression Sets the maximum number of IPCP configuration failures This determines the maximum number of configuration NAKsthat will be sent before we reject an option Default 5 The number of slots used to store state information for each side of a VJ compressed link This value is determined by the maximum number of concurrent TCP sessions that you will have Default 1 slot Specifies 1f we want to allow the remote to set their IP address Please see setting a peer PPP IP address below for explanations Default Don t Allow Specifies the IP addresses of the Primary DNS Server we will allow the remote to use or the Primary DNS server that we ant to us Se the section setting a PPP IP Address Default Don t Allow Specifies the IP Address of the Secondary DNS server Optional Protocols we will allow the rem
615. ty information for network number 27 it is not a network address 1 31 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Special Address Conventions In practice IP uses only a few combinations of 0 s or s All 0 s This Host All 0 s Host on this net 2 All s Limited Broadcast local net Net All 1 s Direct Broadcast for net 4 127 anything often 1 Loopback 5 Fig 1 21 Special Forms of IP Addresses As the notes in Figure 1 21 show using all 0 s for the network is only allowed during the bootstrap procedure It allows a machine to communicate temporarily Once the machine learns its correct network and IP address it must not use network 0 Allowed only at system startup and is never a valid destination address Never a valid source address Never a valid source address Never a valid source address 5 Should never appear on a network 1 32 2004 Treck Incorporated Introduction to TCP IP IP Addressing Format Let s look at the physical setup of an IP address If we have an IP address number of 208 229 201 66 or 11010000 11100101 11001001 01000010 This number represents the address of a particular machine on a network This is that machines personal identification number Each machine on that network will have the same first three numbers For example a machine with the address 208 229 201 68 would still be on the same network and wou
616. type of recognition that they have established a connection This is different from the earlier mentioned section describing such protocols as UDP which is a connectionless oriented protocol where information is sent out without the need for acknowledgement Commonly TCP is known to be a very reliable protocol because of this fact Reliable Stream Delivery Why do we need reliable stream delivery To answer this question at the lowest level computer communication networks provide unreliable packet delivery As we have mentioned in previous sections packets can be lost or destroyed when transmission errors interfere with data when network hardware fails or when networks become too heavily loaded Networks that deliver packets dynamically such as UDP can deliver them out of order deliver them after a substantial delay or even deliver duplicates Also underlying network technologies may dictate optimal packet size or invoke other constraints needed to achieve efficient transfer rates At the highest level application programs may need to send large volumes of data from one computer to another Using a connectionless delivery system for large volume transfers can be tedious and also requires programmers to incorporate error detection and recovery into each application program All these problems and inconveniences have caused a necessity to find a general purpose solution to providing reliable stream delivery This will make it possible for e
617. ual tfPoolDelete include lt trsocket h gt int tfPoolDelete ttUserInterface interfaceHandle Function Description Free the pool of pre allocated recv buffers which was allocated in fPoolCreate Should be called by the user from the device driver close function Parameters Parameter Description interfaceHandle Interface handle as given in the first parameter of the driver close function or as returned by tfAddInterface Returns Value Meaning TM EALREADY Pool already deleted or not created on that interface 5 172 2004 Treck Incorporated Programmer s Reference tfPoollsrFreeBuffer include lt trsocket h gt void tfPool isrFreeBuffer ttUserInterface interfaceHandle int dataSize Function description Called from recv ISR if last packet returned by tfPoollsrGetBuffer queued to be processed by the tfRecvInterface needs to be freed i e removed from the pool recv queue and put back in the ring of free buffers to be used by the chip Parameters Parameter Description ttUserInterface Interface handle size size of buffer just allocated Returns None 5 173 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfPoollsrGetBuffer include lt trsocket h gt char TM_FAR tfPoollsrGetBuffer ttUserInterface interfaceHandle int size Function Description Get a pre allocated buffer from the recv pool and queue that buffer in the pool receive queue Can only be
618. ublic value in any other NAT configuration function but the one call to tfNatConfigNapt except the tfNatConfigInner Server functions tfNatConfigNapt should be called before any tfNatConfigStatic or tfNatConfigDynamic calls on the same interface In that case NAPT would only be used for non statically assigned machines after all dynamic associations were already in use Though UDP ports never conflict with TCP ports there is only one next port maintained so ports are allocated as if they did conflict Parameters Parameter Description interfaceHandle Interface handle of the public NAT device on which to configure routing ipPublic Public IP address network byte order portPublicMin Inclusive range of port numbers host byte order portPublicMax Inclusive range of port numbers host byte order Return Value Meaning TM ENOMEM Insufficient memory or too many TM ENOERROR triggers already Newly allocated trigger ip s and ports initialized 7 65 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfNatConfiginnerTcpServer include lt trsocket h gt int tfNatConfigInnerTcpServer ttUserInterface interfaceHandle ttUserIpAddress ipPublic ttUserIpAddress ipPrivate ttUserlpPort portPublic ttUserlpPort portPrivate Function Description Configure a server on the private network for access via a specific TCP port on the public network The public world will know the server as ipPubli
619. ue Meaning 0 Success 1 An error occurred bind can fail for any of the following reasons TM_EADDRINUSE The specified address is already in use TM_EBADF socketDescriptor is not a valid descriptor TM_EINVAL One of the passed parameters is invalid or socket is already bound 5 7 2004 Treck Incorporated Treck Real Time TCP IP User s Manual connect include lt trsocket h gt int connect int socketDescriptor const struct sockaddr addressPtr int addressLength by Function Description The parameter socketDescriptor is a socket If it is of type SOCK DGRAM connect specifies the peer with which the socket is to be associated this address is the address to which datagrams are to be sent if a receiver is not explicitly designated it is the only address from which datagrams are to be received If the socket socketDescriptor is of type SOCK STREAM connect attempts to make a connection to another socket either local or remote The other socket is specified by addressPtr addressPtr is a pointer to the IP address and port number of the remote or local socket IfsocketDescriptor is not bound then it will be bound to an address selected by the underlying transport provider Generally stream sockets may successfully connect only once datagram sockets may use connect multiple times to change their association Datagram sockets may dissolve the association by connecting to a null address Note that a non blocking connec
620. ue file name that does not conflict with any existing file names in the user s working directory in the buffer pointed to by bufferPtr up to bufferSize bytes Parameters Parameter Description userDataPtr Pointer to user data structure as re turned by tfFsUserLogin bufferPtr Pointer to buffer where to store the unique file name bufferSize Size in bytes of the buffer Returns Value Meaning ST Failure gt 0 Number of copied bytes 6 97 Treck Real Time TCP IP User s Manual tfF SGetWorkingDir include lt trsocket h gt int tfFSGetWorkingDir void userDataPtr char bufferPtr int bufferSize Function description Given the unique user data pointer as returned by tfFSUserLogin copy the user s working directory in the buffer pointed to by bufferPtr up to bufferSize Parameters Parameter Description userDataPtr Pointer to user data structure as returned by tfFSUserLogin bufferPtr Pointer to a buffer where to copy the pathname of the user working directory bufferSize Size in bytes of the buffer Returns Value Meaning zl Failure 20 Number of bytes copied into the buffer pointed to by bufferPtr 6 98 Application Reference tfFSMakeDir include lt trsocket h gt int tfFSMakeDir void userDataPtr char pathNamePtr char bufferPtr int bufferSize Function description Given the unique user data pointer as returned by tfFSUserLogin and a directory name this function creates the dir
621. ufficient user memory available to complete the operation TM EPERM Cannot call accept without calling listen first TM EOPNOTSUPP The referenced socket is not of type SOCK STREAM TM EWOULDBLOCK The socket is marked as non blocking and no connections are present to be accepted 5 6 2004 Treck Incorporated Programmer s Reference bind include lt trsocket h gt int bind int socketDescriptor const struct sockaddr addressPtr int addressLength yu Function Description bind assigns an address to an unnamed socket When a socket is created with socket it exists in an address family space but has no address assigned bind requests that the address pointed to by addressPtr be assigned to the socket Clients do not normally require that an address be assigned to a socket However servers usually require that the socket be bound to a well known address The port number must be less than 32768 TM SOC NO INDEX or could be OxFFFF TM WILD PORT Binding to the TM WILD PORT port number allows a server to listen for incoming connection requests on all the ports Multiple sockets cannot bind to the same port with different IP addresses as might be allowed in UNIX Parameters Parameter Description socketDescriptor The socket descriptor to assign an IP address and port number to addressPtr The pointer to the structure containing the address to assign addressLength The length of the address structure Returns Val
622. unction The user should use tfRecvScatInterface instead of tfRecvInterface when the user wishes to support scattered data within a received frame Gather Read in the device driver recv processing The user needs to define TM USE SCAT DRV RECV and needs to have called tfUselnterfaceScatRecy successfully on that interface If the user has not called tfUseInterfaceScatRecv on that interface then tfRecvInterface should be called instead Parameters Parameter Description interfaceHandle The interface Handle of the device to receive the scattered data from Returns Value Meaning 0 Success TM ENOBUFS Insufficient memory to complete the operation TM EINVAL One of the parameters returned by the scattered device driver recv function is invalid 5 177 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfSendCompletelnterface include lt trsocket h gt void tfSendCompleteInterface ttUserInterface interfaceHandle int flag Function Description This function is used to notify the stack that send has been completed and allow the stack to free the outgoing buffers If the device driver copies the packet before attempting the send it is permissible to call this routine from the context of the send otherwise it must only be called after the device had actually sent the packet Parameters Parameter Description interfaceHandle The interface handle for the device to process the send complete fl
623. unication with the IP layer on the peer machine For detailed information about the options within IPCP please refer to RFC 1332 IPCP in the Treck stack also includes options to obtain the addresses of Domain Name Servers DNS servers Domain name servers are remote servers that match domain names such as treck com to an appropriate IP address Detailed information on the DNS options within IPCP and implementation can be found in RFC 1877 TA 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfChapRegisterAuthenticate include lt trsocket h gt int tfChapRegisterAuthenticate ttUserInterface interfaceHandle ttChapAuthenticateFunctPtr authFunctionPtr Function Description When acting as a PPP server a function must be called to validate an incoming authentication request This function is passed the username and will return the secret password for this particular username Chap module will further compute the challenge using this secret and compare with the challenge given by the peer If both challenge match the peer 1s positively authenticated otherwise the peer is denied The prototype for the authentication function 1s defined to be char myChapAuthenticate char username which returns the secret corresponding to this user If the user name passed to myChapAuthenticate is invalid this function should return TM CHAP INVALID USER Should the password for this user be empty this function
624. upported Unix sendport turned off FTP transfers involving server port numbers other than the standard ports 21 and 20 are not supported e g by entering the client command open host lt port gt Private IP Addressing The following IP addresses should be used for private networks when connected by a NAT router to the public Internet They have been reserved specifically for this purpose by RFC 1918 Address Allocation for Private Internets 10 0 0 0 10 255 255 255 16 million class A addresses 172 16 0 0 172 31 255 255 1 million class B addresses 192 168 0 0 192 168 255 255 64 thousand class C addresses Using other addresses may result in conflicts the NAT router can t resolve 7 61 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Triggers The basis of this implementation of NAT is the trigger object Each ttNatTrigger instance represents some possibility of interception of an incoming or outgoing packet Every packet that comes in or out of a public NAT interface is scrutinized by all current triggers There are several types of triggers see TM NTRTYPE in trmacro h each looking at different aspects of packets Also triggers are either permanent or temporary the duration depending on type traffic and timing Some triggers recognize new TCP connections and spawn other triggers that live for the duration of those connections Those session triggers look at addresses and ports Som
625. uring communication LCP negotiation makes PPP more effective than SLIP Kermit Z Modem and many of the other early peer to peer protocols Unlike PPP these early protocols did not have robust schemes for negotiating options and they were not extensible Newer versions of PPP may contain more options than previous versions but can still effectively communicate with them Each system knows how it would like to receive data the most efficient way or options required by a system administrator and tells its peer by sending a Configure Request Conf Req A Conf Req specifies options such as authentication control field compression address field compression Maximum Receive Unit MRU Magic Number and many others If a system receives a Conf Req and all of the requested options are acceptable it replies with a Configure Acknowledge Conf Ack 7 74 2004 Treck Incorporated Optional Protocols The Configure Acknowledge tells the sender of the Conf Req that all the requested options are acceptable have been enabled and it is ready to start communicating Because some systems may have certain options disabled or have version of PPP that does not support all the options they may not be able to comply with a set of options a peer might request For example if a machine requests the MRU option set to 3000 bytes and the peer system could not send data in blocks that large it would return a Configure Negative Acknowledge Conf Nak Th
626. urn address The operation of sockets is controlled by socket level options These options are defined in the file lt trsocket h gt setsockopt and getsockopt are used to set and get options respectively Parameters Parameter Description family The protocol family to use for this socket currently only PF_INET is used type The type of socket protocol The layer 4 protocol to use for this socket Family Type Protocol Actual protocol PF INET SOCK DGRAM IPPROTO UDP UDP PF INET SOCK STREAM IPPROTO TCP TCP PF INET SOCK RAW IPPROTO_ICMP ICMP PF INET SOCK RAW IPRPTOTO_IGMP IGMP Returns New Socket Descriptor or 1 on error If an error occured the socket error can be retrieved by calling tfGetSocketError and using TM SOCKET ERROR as the socket descriptor parameter socket will fail i TM EMFILE No more sockets are available TM ENOBUFS There was insufficient user memory available to complete the operation TM EPROTONOSUPPORT The protocol type or the specified protocol is not supported within this family 5 62 2004 Treck Incorporated Programmer s Reference tfClose include trsocket h int tfClose int socketDescriptor Function Description This function is used to close a socket It is not called close to avoid confusion with an embedded kernel file system call Parameters Parameter Description socketDescriptor The socket descriptor to close Returns Value Meaning 0 Operation completed successfully 1 An e
627. us in userBtEntryPtr gt btuFqdnStatus Possible valued for this flag are a combination of TM FQDNF PARTIAL if the received domain name was partial TM FQDNF MALFORMED if the DHCP server returned a malformed domain name TM FQDNF NOT SUPPORTED if the DHCP server does not support the FQDN option TM FQDNF NAMEREPLY if the DHCP server FQDN option reply contained a domain name 7 39 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfDhcpUserGetBootEntry include lt trsocket h gt ttUserBtEntryPtr tfDhcpUserGetBootEntry ttUserInterface interfaceHandle int index Function Description Get a pointer to a DHCP user BOOT entry This function can only be used after a successful call to tfDhcpUserStart If successful the function will return a pointer to a ttUserBtEntry structure as defined in trsocket h In particular this structure will contain The allocated IP address in the field btuYiaddr Default router entry in the field btuDefRouter Primary Domain name server btuDns1ServerlpAddress Secondary Domain name server btuDns2ServerIpAddress Parameters Parameter Description interfaceHandle Ethernet interface handle userIndex User Index between 0 and tvMaxUserDhcpEntries 1 Returns Value Meaning userBtEntryPtr Pointer to a user boot entry as defined in trsocket h ttUserBtEntryPtr 0 Failure No DHCP address bound 7 40 2004 Treck Incorporated Optional Protocols tfDhcp
628. using the Treck protocols as a shared library Note It is possible to use a polling i e non blocking separate receive task in which case you do not need to define TM_TASK_RECV TM_TASK_XMIT This macro is used to notify the stack that a separate blocking transmit task will be used to send packets to the device driver A separate blocking transmit task can only be used if you are using a real time operating system and you are using the Treck protocols as a shared library If more than one interface is defined on the system more than one transmit task may be used It is not required to use a separate blocking transmit task If no transmit task is used then the packets are queued to the device driver send queue and are sent to the driver in the context of the sending thread The sending thread could be a user application task sending data or the 4 12 2004 Treck Incorporated Integrating into Your Environment receive task sending a TCP acknowledgment or a PING echo reply or the timer task re transmitting data Ifa separate transmit task is used then packets are queued to the device send queue in the context of the sending thread Then when a context switch occurs the packets are sent to the driver in the context of the transmit task In most cases it is inefficient to use a separate blocking transmit task because it requires a context switch on nearly every packet sent by the sending thread Note It is possible to use a polling i
629. ut the value in lenPtr return the password pointer endif TM USE PPP MSCHAP T 7 110 2004 Treck Incorporated Optional Protocols PPP Link Quality Monitoring LQM PPP LQM enables the application to determine when PPP link quality has degraded to the point where recovery is necessary PPP LQM does this via the exchange of Link Quality Report protocol messages at a negotiated interval referred to as the Reporting Period of the LQR timer A Link Quality Report message contains the sender s state information w regards to how many packets and bytes have been successfully sent and received on the link When the peer receives the Link Quality Report message it can compare these counts against it s own similar state information to determine link quality and then if it judges link quality bad can recover the link i e by bringing the link down and then up again or some other application specific recovery algorithm The link can have a transient failure in which case some amount of hysteresis is needed to average link quality over some multiple of the Reporting Period so that transient link failures do not cause the link to go up and down too frequently PPP LOM does not specify the specific policy to be used to judge link quality nor does it specify how to recover the link when link quality is judged bad Since we believe that any user planning to use PPP LOM is sophisticated enough to implement their own link qua
630. ve kernel i e TM TRECK PREEMPTIVE KERNEL is defined in trsystem h it is the user s responsibility to ensure that the user free function is re entrant as it could potentially be called from different threads Parameters Parameter Description interfacehandle If the user knows the interface the packet is to be sent out to then this field is non null userBlockPtr Pointer to the first element data type ttUserBlock of the user array that contains information about the user scattered data UserBlockCount Number of elements in the above array 5 83 2004 Treck Incorporated Treck Real Time TCP IP User s Manual ttUserBlock data type typedef struct tsUserBlock char userBufferPtr Pointer to buffer passed to the free routine char userDataPtr Pointer to beginning of data int userDataLength Data length ttUserBlock Function prototype for the user supplied user data free call back function int userFreeFunc char TM FAR bufferPtr TM EMSGSIZE TM EHOSTUNREACH TM EDESTADDRREQ TM ENOENT TM ENXIO TM EIO Other error code 2004 Treck Incorporated Returns Value Meaning TM ENOERROR Success TM EINVAL One of the parameters is bad i e userBlockPtr is null or userBlockCount is less or equal to 0 or userFreeFunction is null or interface handle is invalid TM ENOBUFS Could not allocate Treck headers to send the data or could not allocate an ARP entry TM EFAULT Bad packet The IP header len
631. ve more than one IP address If the interface has only one IP address then the Multi home index should be set to zero The broadcast address is automatically calculated from the IP address and Netmask combination Parameters Parameter Description interfaceHandle The device driver entry that we wish to get the broadcast address on ifBroadcastAddressPtr The pointer to the area that the function will store the broadcast address into multiHomelndex An index for multiple IPs Returns Value Meaning 0 Success TM_EINVAL Bad parameter TM ENETDOWN Interface multi home index is not configured 5 149 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfGetlfMtu int tfGetIfMtu ttUserInterfac interfaceHandle int ifMtuPtr Function Description This function is used to retrieve the Maximum Transmission Unit MTU for a device Parameters Parameter Description interfaceHandle The device driver entry that we wish to get the physical address on ifMtuPtr Pointer to the integer that will contain the Maximum Transmission Unit for a device Returns Value Meaning 0 Success TM EINVAL One of the parameters is null or 0 5 150 2004 Treck Incorporated tfGetlpAddress int ttUserInterface ttUserlpAddress unsigned char Function Description Programmer s Reference tfGetIpAddress interfaceHandle iflpAddressPtr mutiHomeIndex This function is used to get the IP address of an inte
632. ver may not wish to perform a particular operation e g zone transfer for particular data No answer received from name server 1 e response packet received but it did not contain the answer to our query The call to perform a DNS function will simply block until the operation is complete or an error is received However with non blocking mode it is necessary to poll the DNS Resolver to determine if the operation has completed If an operation is still in progress the call will return TM_EWOULDBLOCK Ifan error code other than TM_EWOULDBLOCK is received the operation has completed Mail Exchanger MX Records Each hostname contains a list of machines that are willing to accept mail destined for that hostname This is necessary should one of the machines be 6 11 Treck Real Time TCP IP User s Manual unable to receive mail Each one of the hosts in this list contains a preference value that indicates the order that these hosts should be used An e mail program should first attempt delivery to the hostname with the lowest prefer ence value and if unable to connect to attempt delivery to the hostname with the next highest preference For instance treck com may have the following MX entries maill treck com 10 208 229 201 1 mail2 treck com 20 208 229 201 2 mail3 treck com 30 208 229 201 3 Mail should first be sent to maill treck com If that fails it should be sent tomail2 treck com andsoon This behavi
633. vinterface interfaceHandle Data validation There are two flags that can be used to validate that incoming and outgoing data is correct TM TEST FLAG FILL DATA will fill any outgoing data with any incrementing byte pattern of 0x00 0x01 OxFF The remote host receiving data can then validate that the incoming data matches this pattern The flag TM TEST FLAG VALIDATE performs the inverse operation it verifies that any received data matches this 0x00 0x01 OxFF pattern If any validation fails the test will return with a TM_EIO error code These two flags can be used in a variety of ways to validate data For instance if an echo test is being performed setting both of these flags will verify that both incoming and outgoing data is correct Another example application of these flags is when the Treck test suite is being run between two devices one device could run the TM TEST TCP SEND test with the TM TEST FLAG FILL DATA option set and the other device could run the TM TEST TCP RECY test with the TM TEST FLAG VALIDATE option set and vice versa Random testing mode When the TM TEST FLAG RANDOM option is set tf TestTreck will execute a random client test with random parameters The test type is chosen from the set of send send tests TM TEST UDP SEND TM TEST TCP SEND echo tests TM UDP ECHO CLIENT TM TCP ECHO CLIENT and the TCP connect test TM TEST TCP CONNECT Ifa send or TCP connect test is chosen it wi
634. w long a TCP packet takes to get to a remote system We must also know how much time an ARP entry has been in the ARP queue In addition the timer system also measures routing entries and is used for Treck PPP You don t deal with all of the individual timers that Treck TCP IP manages Since we only use a single notification to let us know how much time is elapsed the timer system will manage all of the different timers used by the Treck TCP IP system Treck TCP IP is flexible in the way that you provide this notification You have the option of using an ISR or a task to do the timer notification The notification is done in a single function call You can then decide when you wish to execute the timers The execution of the timers is done with a single function 3 8 2004 Treck Incorporated Integrating Treck Real Time Protocols Into Your Environment 2004 Treck Incorporated Treck Real Time TCP IP User s Manual 2004 Treck Incorporated Integrating into Your Environment Integrating Treck Real Time Protocols Into Your Environment Now that you have a basic understanding of TCP IP and the Treck Systems you are probably wondering how to integrate Treck protocols into your system You have looked at the product and discovered there are many files and API s that you may have to deal with To aid you in your integration effort we will break this task down into several key elements 1 Deciding how you will use the proto
635. xperts to build a single instance of stream protocol software that all application programs use The advantage of this is to help isolate application programs from the details of networking and it also makes it possible to define a uniform interface for stream transfer service 1 52 2004 Treck Incorporated Introduction to TCP IP Reliability Reliable stream delivery service guarantees to deliver a stream of data from one machine to another without duplication or loss This statement brings up an interesting question How can protocol software provide reliable transfer if the underlying communication system offers only unreliable packet delivery Most reliable protocols use a single fundamental technique known as positive acknowledgement with retransmission This technique requires a recipient to com municate with the source by sending an acknowledgement ACK message as it receives data The sender keeps the report of each packet it sends and then waits for an acknowledgement before sending the next packet The sender also starts a timer when it sends a packet and retransmits a packet if the timer expires before a packet arrives The following diagram shows how the simplest positive acknowledgement protocol transfers data Events at Sender Site Network Messages Events at Receiver Site Send Packet 1 Receive Packet 1 Send ACK 1 TIME Receive ACK 1 gt ae Send Packet 2 Receive Packet 2 Send ACK 2 Receiv
636. y the stack MSG DONTWAIT MSG DONTROUTE MSG WAITALL or 0 Meaning Number of bytes transmitted queued Treck will free the user buffers An error occurred The user can retrieve the error code with the tfGetSocketError socketDescriptor API Meaning Not enough room to queue the data in the socket send queue User still owns his buffer and is responsible for re sending later on One of the parameters is bad userBufferPtr or userDataPtr or userDataLength or user free function is 0 or userDataLength is 1 or flags has a bit set that is not allowed Not enough memory to allocate the Treck headers The socket descriptor is invalid The data length was bigger than the send queue No route to host 5 115 2004 Treck Incorporated Treck Real Time TCP IP User s Manual API Call Back Function Registration tfRegisterSocketCB include lt trsocket h gt int tfRegisterSocketCB int socketDescriptor ttUserSocketCBFuncPtr socketCBFuncPtr int eventFlags Function Description This function is used to register a function call upon completion of one of more socket events This allows the user to issue non blocking calls and get a call back upon completion of one or more socket events as described in the table below The call back function will be called repeatedly each time one or more of the events registered for occur until the user cancel the event s with another call to tfRegisterSocketCB with a new event
637. y valid in the first link pktuLinkExtraCount Contains the number of extra links besides the first one Its value is only valid in the first link The single call per frame user device driver send function will loop through all the links of the scattered frame in order to send a complete frame 5 185 2004 Treck Incorporated Treck Real Time TCP IP User s Manual tfUselnterfaceScatRecv include lt trsocket h gt int tfUseInterfaceScatRecv ttUserInterface interfaceHandle ttDevScatRecvFunc devScatRecvFunc Function Description By default the stack expects all data within a frame given by the user device driver recv function to be contiguous Some device drivers support receiving data within a frame in scattered buffers Gather Read because it is more efficient tfUseInterfaceScatRecv replaces the default device driver recv function added in tfAddInterface with a driver driver scattered recv function that is called once per frame even when the device driver received data is scattered on a given interface Gather Read tfUseInterfaceScatRecv must be called prior to calling tfConfigInterface and after having called tfAddInterface to replace the device driver recv function specified in tfAddInterface If tfUseInterfaceScatRecv has been called successfully the user needs to call tfRecvScatInterface instead of tfRecvInterface tfRecvScatInterface will call the modified device driver recv function specified in t
638. you actually wait If the event occurs before you wait your task will not wait for the resource This mechanism is very important to the operation of Treck TCP IP Protocol stacks need this mechanism in order to work in an asynchronous mode properly Now there is another question that you must be asking yourself Do I actually need a counting semaphore The answer is simple If you are not using a preemptive operating system and you do not make any blocking calls then you do not need a counting semaphore We only use the counting semaphore for blocking and locking 3 5 2004 Treck Incorporated Treck Real Time TCP IP User s Manual Treck TCP IP calls Create Semaphore tfKernelCreateSemaphore Breen Task 1 Calls a function that attempts to lock a resource that is already locked RTOS Kernel Treck TCP IP calls tfKernelPend Task 2 Task 1 Finishes with the locked Continues to run resource getting the lock RTOS Kernel Treck calls i tfKernelPost lt Semaphore Support Post on Semaphore 777777 Figure 3 1 RTOS allows Task 1 to Continue 3 6 2004 Treck Incorporated Treck Systems Buffer System In Treck TCP IP we have an internal buffer management system for performance reasons We have found that if we need to call the operating system every time that we need a buffer and again have to call the operating system in order to free that buffer there is a severe penalty on performance What we d
639. ytes Fig 1 10 Ethernet Frame Format In addition to identifying the source and destination each frame transmitted across the Ethernet contains a preamble type field data field and Cyclic Redundancy Check CRC The preamble consists of 64 bits of alternating 0 s and s to help receiving nodes synchronize The 32 bit CRC helps the interface detect the transmission errors The sender computes the CRC as a function of the data in the frame and the receiver recomputes the CRC to verify that the packet has been received intact The frame type field contains a 16 bit integer that identifies the type of data being carried in the frame From the Internet point of view the frame type field is essential because it means that Ethernet frames are se f identifying When a frame arrives at a given machine the operating system uses the frame type to determine which protocol software module should process the frame The chief advantage of self identifying frames is that they allow multiple protocols to be intermixed on the same physical network without interference For example one frame could have an application program using Internet protocols while another is used for local experimental protocol The operating system uses the type field of an arriving frame to decide how to process the contents We will see that TCP IP uses self identifying Ethernet frames to distinguish among several protocols 1 16 2004 Treck Inc
640. ze of the intermediate buffer being sent with ffPppSetOption for a PPP link layer or ffSlipSetOptions for a SLIP link layer You can change the size of the SLIP intermediate buffer at any time and the change will take effect immediately But you need to change the size of the PPP intermediate buffer before opening the interface For example to change the intermediate SLIP send buffer size to 1500 you can call unsigned short optionValue optionValue 1500 errorCode tfSlipSetOptions interfaceHandle TM SLIP OPT SEND BUF SIZE void TM FAR amp optionValue sizeof unsigned short To change the intermediate PPP send buffer size to 1500 for example you need to call before calling ffOpenInterface 4 64 2004 Treck Incorporated Integrating into Your Environment unsigned short optionValue optionValue 1500 errorCode tfPppSetOption interfaceHandle TM_PPP_PROTOCOL 0 TM_PPP_SEND_BUFFER_SIZE const char TM FAR amp 0ptionValue sizeof unsigned short Note You must only call send completes for the piece of data that has the TM USER BUFFER LAST flag set to guarantee that only ONE send complete per frame is issued Example int myDeviceSend ttUserInterface interfaceHandle char TM FAR dataPtr int dataLength int flag while dataLength Send to I O Port outb MY DEVICE PORT dataPtr dataLength We are done with the frame if flag TM USER BUFFER LAST tfSendCom

Treck TCP/IP User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents