/* WDB.pcl - WDB Protocol Requests *//* Copyright 1984-1998 Wind River Systems, Inc. *//*modification history--------------------01j,15jan99,dbt  updated WDB_EVENTPOINT_ADD documentation.01i,22jun98,dbt  doc: updated to WDB 2.001h,27may98,rhp  doc: Changed first heading to standard DESCRIPTION.01g,09apr98,dbt  doc : added WDB_CONTEXT_STATUS_GET documentation.		       fixed an error in WDB_MODE_GET manual. 01f,31dec96,dgp  doc: more spelling corrections01e,06dec96,dgp  doc: correct spelling01d,21nov96,dgp  doc: change Target-Server to Target Server01c,18nov96,dgp  doc: correct italic and bold formatting01b,06nov96,dgp  doc: check into Clearcase01a,23jul96,dgp  written.*//*DESCRIPTIONThis document describes the Wind River Debug (WDB) version 2.0 protocol.It is the protocol used by the Tornado target server back endsthat communicate with the target agent (WDB RPC, WDB Serial, WDB NetROMand WDB Pipe).The diagram below gives an overview of the Tornado environment..CS        +---------+             +---------+    +---------+    +---------+        |         |             |         |    |         |    |         |        |  Shell  |             | Debugger|    | Browser |    |  Other  |        |         |             |         |    |         |    |  Tools  |        +----+----+             +----+----+    +----+----+    +----+----+             |                       |              |              |             +--------------------+  |  +-----------+              |                                  |  |  |  +-----------------------+                        WTX       |  |  |  |                      Protocol    |  |  |  |                              +--+--+--+--+---+                             |               |                             | Target Server |                             |               |                             +-+--+--+--+--+-+			       |  |  |	|  |                               |  |  |  |  +--------------------------+                               |  |  |  +-----------------+	      |                          +----+  |  +--------+           |           |                          |       |           |           |           |   Target Server   +---+---+  +---+----+  +---+----+  +---+----+  +---+----+    Back Ends      |  WDB  |  |  WDB   |  |  WDB   |  |  WDB   |  |Non-WDB |                   |  RPC  |  | Netrom |  | Serial |  | Pipe   |  |Back End|                   +---+---+  +---+----+  +----+---+  +---+----+  +---+----+                       |          |            |          |           |        Host           |          |            |          |           | - - - - - - - -- - - -|- - - - - |- - - - - - |- - - - - |- - - - - -|- -  Target (or simulator)|          |            |          |           |                       |          |            |          |           |                   +---+---+  +---+----+  +----+---+  +---+----+      |                   |Network|  | Netrom |  | Serial |  |  Pipe  |      | WDB Target Agent  |Comm if|  |Comm if |  |Comm if |  |Comm if |      |  Communication    +---+---+  +---+----+  +----+---+  +---+----+      |   Interfaces          |          |            |          |           |                       +--------+ | +----------+          |           |                                | | | +-------------------+           |				| | | |                               |                             +--+-+-+-+--+                       +----+----+                             |WDB Target |                       | Non-WDB |     Agents                  |   Agent   |                       |  Agent  |                             +-----+-----+                       +----+----+                                   |                                  |                              +----+----+                             |                              |         |                             |                              | vxWorks +-----------------------------+                              |         |                              +---------+.CENOTE: If you want to create a new back end for Tornado, knowledge ofthe WDB protocol is not needed. Creating a back end that communicateswith the WDB agent requires installing a new communication pathbetween the host and target. Once the communication path is established,the target agent performs all the services needed.Creating a back end that communicates with a non-WDB agent (for example, anICE) requires implementing all the target services required.For details, refer to the .I API Programmer's Guide: Target Server Back End.The next few sections describe the format of messages sent betweenthe host and target. The rest of this chapter describes the actualset of services provided by the agent.PROTOCOL OVERVIEWThe WDB protocol is an RPC-based protocol which uses UDP. The WDB agent acts as a server for requests sent by the target server. For more information, seeone of the many generally available references on UDP and Sun RPC.Some key definitions can be found in share/src/agents/wdb/wdb.h:.iP The UDP port that the agent accepts request from, WDBPORT, is 0x4321..iPThe agent's RPC program number, WDBPROG, is 0x55555555..iPThe agent's RPC version number, WDBVERS, is 1..LPREQUESTS SENT TO THE AGENTA WDB request packet sent to the agent contains, in order:.iP A 20-byte IP header..iPAn 8-byte UDP header. It consists of four 16-bit words. WDBPORT is word 2..iPA 40-byte RPC request header. It consists of ten 32-bit words. WDBPROG isword 3. WDBVERS is word 4. The RPC procedure number is word 5..iPAn XDR stream. The first 12 bytes of this stream is WDB-parameter-wrapper information. (See `${WIND_BASE}/share/src/agents/wdb' for moreinformation on the WDB_XDR functions.).LPThe diagram below shows the layout of the WDB request packet.  The main WDB information is contained in the XDR stream.  This is where the input parametersfor the WDB functions are transferred to the target agent..CS                             +-----+ IP HEADER                   |     | 20 bytes                    |     |               		     |     | 			     |     | 			     |     | 			     +-----+ UDP HEADER                  |     | WDBPORT 8 bytes                     |     |			     +-----+ RPC REQUEST HEADER          |     | 40 bytes                    |     | WDBPROG (10 32-bit words)           |     | WDBVERS			     |     | RPC procedure #			     |     |			     |     |			     |     |			     |     | XDR Stream		     +-----+ WDB PARAMETER WRAPPER       |     | Checksum 12 bytes                    |     | Packet Size			     |     | Sequence #			     | - - | XDR encoded PARAMETERS      |     | (function input parameters) |     |			     |     |			     |     |.CEThe WDB parameter wrapper contains three 4-byte words. The first wordis a checksum over the whole RPC packet (RPC header + XDR stream).The second word is the packet size. These two words enable the agentto determine if a corrupted packet has arrived. The third word isa sequence number. The low order two bytes of the sequence numberare used to allow the agent to ignore old or duplicated requests (whichcan occur with UDP transport). The high order two bytes are the`host ID'. When a host issues a WDB_TARGET_CONNECT request,the host ID portion of the sequence number is recorded. If a requestarrives from a non-connected host, the RPC fails with the RPCerror status PROG_UNAVAIL or SYSTEM_ERR, depending on whether theagent is already connected to another target server or not.The WDB_TARGET_CONNECT request always establishes a new connection,if necessary by dropping the old one. If the host wants to test whether ornot the agent is already connected before trying to establish a connection,it should first issue a WDB_TARGET_PING request and see if the RPC failswith error status PROG_UNAVAIL. If so the connection is busy.The routine `xdr_WDB_PARAM_WRAPPER' is used to encode or decode the entire XDRstream (the procedure parameters plus the 12-byte parameter wrapper). The following example is a code stub from the host routine rpcCoreClntCall():.CS    seqNumber++ ;    ...    wdbParamWrapper.xdr = inProc;         /@ xdr func for proc params @/    wdbParamWrapper.pParams = in;         /@ pointer to proc params @/    wdbParamWrapper.seqNum = processId | seqNumber;     /@ seq nb @/    ...    clntStatus = clnt_call (pWdbClnt, procNum, xdr_WDB_PARAM_WRAPPER,                            &wdbParamWrapper,                            ...);.CEREPLIES SENT BY THE AGENTA WDB reply packet sent by the agent contains, in order:.iP A 20-byte IP header..iPAn 8-byte UDP header..iPA 24-byte RPC reply header..iPAn XDR stream. The first 12 bytes of this stream is WDB replywrapper info (see below). The rest of the stream is the XDR-encoded reply from the procedure..LPThe diagram below shows the layout of the WDB reply packet.  As with the WDBrequest packet, the main WDB information is contained in the XDR stream.  Theresult of the WDB function is returned to the host in this stream..CS                             +-----+ IP HEADER                   |     | 20 bytes                    |     |                             |     |                             |     |                             |     |                             +-----+ UDP HEADER                  |     | 8 bytes                     |     |                             +-----+ RPC REPLY HEADER            |     | 24 BYTES                    |     | WDBPROG (6 32-bit words)            |     | WDBVERS                             |     | RPC procedure #                             |     |                             |     |                             |     |                             |     | XDR Stream                  +-----+ WDB REPLY WRAPPER           |     | Checksum 12 bytes                    |     | Packet Size                             |     | WDB Error Status                             | - - | XDR encoded REPLY           |     | (function output)           |     |                             |     |                             |     |.CELike the WDB parameter wrapper, the WDB reply wrapper contains three 4-byte words. The first word is a checksum over the whole RPC packet (RPC header plus XDR stream). The second word is the packet size. These two words enable the host to determine if a corrupted reply was returned (and, if so, to reissue the request). The third word is the WDB error status. The high order bit is set if there are events pending on the target, in which case thehost can issue a WDB_EVENT_GET request to upload the event. The rest of the word is the actual error status.牋.LPREPLY ERRORSAfter a remote procedure is called, the program should perform error checking.Error status can be communicated in one of two ways: in the RPC header or inthe reply wrapper. If the failure is reported in the RPC header, then the host's`clnt_call' will return an RPC error status. These have conventional meanings according to the RPC specification. In addition, the WDB agent uses thefollowing special codes:.iP RPC_PROCUNAVAIL 5The RPC procedure requested is not configured into the agent. The agent is scalable, so this usually means the agent was built without that service..iP RPC_PROGUNAVAILThe agent refused to execute the procedure because it is connected to another host..iP RPC_SYSTEMERRORThe agent refused to execute the procedure because it is not connected to any host. If you were previously connected, the target has rebooted..LPEven if the RPC call succeeds (meaning that the agent tries to execute your command), the command may still fail. The `errCode' field in the reply wrappercan be checked; if the lower 30 bits are zero, the command succeeded. (Rememberthat the high-order bit is set if there are events pending on the target.) If the value is non-zero, then the procedure failed and the word contains the error code. Error codes have the format WDB_ERR_XXX and are defined in ${WIND_BASE}/share/src/agents/wdb/wdb.h.The routine `xdr_WDB_REPLY_WRAPPER' is used to encode or decode the entire XDR stream (the reply data plus the 12-byte reply wrapper). The followingpseudo code shows how it works:.CS    wdbReplyWrapper.xdr = outProc;              /@ reply xdr function @/    wdbReplyWrapper.pReply = out;               /@ where to decode reply @/    wdbReplyWrapper.errCode = OK;               /@ just to clear this field @/    ...    clntStatus = clnt_call (pWdbClnt, procNum, xdr_WDB_PARAM_WRAPPER,                            &wdbParamWrapper, xdr_WDB_REPLY_WRAPPER,                             &wdbReplyWrapper, timeout);    check (clntStatus)        {        if (RPC_TIMEDOUT or RPC_CANTDECODERES or RPC_CANTDECODEARGS)           try again        if (RPC_SYSTEMERROR)           if we were previously connected, then target must have rebooted           so resync and reconnect.        if (RPC_PROCUNAVAIL)           procedure not configured into agent. Try to rebuild the agent           with that facility included (e.g., virtual I/O is an optional           agent facility).        if (RPC_SUCCESS)           agent tried to execute the routine.           check high order bit of wdbReplyWrapper.errCode to see if events           are pending on the target. If so, execute a WDB_EVENT_GET request           after finishing processing this reply.           mask off the high order bit of wdbReplyWrapper.errCode.           if (wdbReplyWrapper.errCode == 0)              success! In this case wdbReplyWrapper.xdr decoded the              reply and put it in wdbReplyWrapper.pReply.           else              wdbReplyWrapper.errCode contains the reason for procedure              failure. The error coded are defined in wdb.h.        }.CEAs the above pseudo code indicates, if you do not receive an RPC error orRPC_SUCCESS, `wdbReplyWrapper.errCode' contains the reason for the procedurefailure.  The possible error codes are as follows:.CSWDB_OK                          OK      /@ success @/WDB_ERR_INVALID_PARAMS          0x501   /@ params invalid @/WDB_ERR_MEM_ACCES               0x502   /@ memory fault @/WDB_ERR_AGENT_MODE              0x503   /@ wrong agent mode @/WDB_ERR_RT_ERROR                0x504   /@ run-time callout failed @/WDB_ERR_INVALID_CONTEXT         0x505   /@ bad task ID @/WDB_ERR_INVALID_VIO_CHANNEL     0x506   /@ bad virtual I/O channel @/WDB_ERR_INVALID_EVENT           0x507   /@ no such event type @/WDB_ERR_INVALID_EVENTPOINT      0x508   /@ no such eventpoint @/WDB_ERR_GOPHER_FAULT            0x509   /@ gopher fault @/WDB_ERR_GOPHER_TRUNCATED        0x50a   /@ gopher tape too large @/WDB_ERR_EVENTPOINT_TABLE_FULL   0x50b   /@ out of room @/WDB_ERR_NO_AGENT_PROC           0x50c   /@ agent proc not installed @/WDB_ERR_NO_RT_PROC              0x50d   /@ run-time callout unavail @/WDB_ERR_GOPHER_SYNTAX           0x50e   /@ gopher syntax error @/WDB_ERR_NOT_FOUND               0x50f   /@ object not found @/WDB_ERR_HW_REGS_EXHAUSTED       0x510   /@ hardware breakpoint registers full @/WDB_ERR_INVALID_HW_BP           0x511   /@ invalid hardware breakpoint @/WDB_ERR_PROC_FAILED             0x5ff   /@ generic proc failure @/WDB_ERR_NO_CONNECTION           0x600   /@ not connected @/WDB_ERR_CONNECTION_BUSY         0x601   /@ someone else connected @/WDB_ERR_COMMUNICATION           0x6ff   /@ generic comm error @/.CEASYNCHRONOUS NOTIFICATION BY THE AGENTAsynchronous events can be generated on the target. These includeexceptions, breakpoints, and task exiting. These events are queued on thetarget until the host uploads them with the WDB_EVENT_GET service. Inorder to prevent the host from polling for events, the agent has two waysto notify the host that events are pending. One way is setting the highorder bit in the `errCode' status of the reply wrapper. The other way is bysending a "notify packet".Normally the agent only sends data to the host in response to RPCrequests. The convention is that if the host receives data when it is notwaiting for a reply, it means that an event is pending on the target. Thetarget server waits for events from other host tools as well as from thetarget.  When the target sends an event, the host issues a WDB_EVENT_GETrequest to upload the event (and keeps uploading events until the highorder bit in the `errCode' field is clear). The actual notify packet sent bythe agent is a packet that can not be confused with an RPC reply (in caseit sends the notify packet just as the host issues an RPC request). Infact, it sends a bogus RPC request.PROCEDURESWDB transactions occur as described above. We now describe the setof WDB procedures. For each procedure, we list the input and outputstructures (if any), and some possible error codes. The error codes listedare in addition to the ones described in the previous sections.The actual values for the RPC procedure number, error status,and data types can be found in `${WIND_BASE}/share/src/agents/wdb/wdb.h'.