![]() |
![]() |
![]() |
![]() |
![]() |
Connection of Host and Target
General
The following sections will detail the technical requirements and the technical implementation of the connection between host and target. The following items will be outlined:
- Structure of Communications Link Software
- Default Implementation of Communications Link Software as delivered.
- How to implement user host executables, which are able to communicate with the SDL Target Tester's target library. This is described in the subsection Open Interface.
Structure of Communications Link Software
This is the structure for the communications link software, which is - in principle - applicable for host, as well as for target site:
The following subsections describe the current implementation and how to implement a new communications link software.
Default Implementation of Communications Link Software
Message Transfer and Presentation of Messages
State Machine and Handshake
For all the commands and messages, there is a small state machine to handle the correct transfer of information. All messages, which have the suffix _REQ (request) in their name (message tag) are to be confirmed from the target with one of the _CNF (confirmation) messages. (See the file tmcod.h, where all message tags are defined).
For messages which take parameters, there is always (no exception) a special _CNF message which carries the response parameters back to the requestor. The requestor is usually the host.
For the messages, which do not carry parameters, a positive confirmation is done via the message CMD_OKAY_CNF.
If a message cannot be recognized or processed within the target, a negative confirmation CMD_ERROR_CNF is used in all cases.
Each _REQ message must be confirmed before the next one can be sent.
Messages with an _IND (indication) suffix are mostly sent from target to host in order to indicate a specific situation. For these messages, the sender is always the originator.
Message Formats
The following subsections give a complete list of messages which can be sent to and received from the target.
Each typedef shown below is packed into a data link frame in its target representation.
That means a memcpy (destbuffer,struct,sizeof(struct)) is performed to copy a structure to/from the data link frame.
On host site, it is therefore necessary to perform message encoding and message decoding.
Formats Concerning the Cmicro Tracer
All messages belonging to the Cmicro Tracer are part of the message class XMK_MICRO_TRACER (F1h).
- Message tag: CMD_TTASK
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL TaskSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TTASKConditional compile:XMK_ADD_TTASK- Message tag: CMD_TSET
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL SetSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TSETConditional compile:XMK_ADD_TSET- Message tag: CMD_TRESET
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL ResetSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TRESETConditional compile:XMK_ADD_TRESET- Message tag: CMD_TSTOP
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL StopSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TSTOPConditional compile:XMK_ADD_TSTOP- Message tag: CMD_TSTATE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL StateSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TSTATEConditional compile:XMK_ADD_TSTATE- Message tag: CMD_TSTATIC_CREATE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL Static createSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TSTATIC_CREATEConditional compile:XMK_ADD_TSTATICCREATE- Message tag: CMD_TCREATE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL CreateSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TCREATEConditional compile:XMK_ADD_TCREATE- Message tag: CMD_TDYNAMIC_CREATE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL Dynamic createSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TDYNAMIC_CREATEConditional compile:XMK_ADD_TDYNAMICCREATE- Message tag: CMD_TDECISION
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL DecisionSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TDECISIONConditional compile:XMK_ADD_TDecisionValue- Message tag: CMD_TSAVE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL SaveSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TSAVEConditional compile:XMK_ADD_TSAVE- Message tag: CMD_TTIMER
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL TimerSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TTIMERConditional compile:XMK_ADD_TTIMER- Message tag: CMD_TINPUT
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL InputSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TINPUTConditional compile:XMK_ADD_TINPUT- Message tag: CMD_TPROCEDURE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL ProcedureSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TPROCEDUREConditional compile:XMK_ADD_TNAME- Message tag: CMD_TOUTPUT
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL OutputSent when :Execution of that SDL symbolDirection :T->HTypedefinition :xmk_T_CMD_TOUTPUTConditional compile:XMK_ADD_TOUTPUT- Message tag: CMD_TDISCARD
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL DiscardSent when :Execution of that SDL symbolDirection :T->HTypdefinition :xmk_T_CMD_TDISCARDConditional compile:XMK_ADD_TDISCARD- Message tag: CMD_PRINT_STRING
Messageclass :XMK_MICRO_TRACERMeaning :User command Print stringSent when :Execution of fct.xmk_PrintString()Direction :T->HTypedefinition :xmk_T_CMD_PRINT_STRINGConditional compile:XMK_ADD_CPRINT_STRING- Message tag: CMD_TIMPLICIT_CONSUMPTION
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL Implicit consumptionSent when :Implicit consumption occursDirection :T->HTypdefinition :xmk_T_CMD_TIMPLICIT_CONSUMTIONConditional compile:XMK_ADD_TIMPLICIT_CONSUMPTION- Message tag: CMD_TACTUAL_RESET
Messageclass :XMK_MICRO_TRACERMeaning :Trace of SDL Actual resetSent when :SDL timer is actually resetDirection :T->HTypedefinition :xmk_T_CMD_TACTUAL_RESETConditional compile:XMK_ADD_TACTUAL_RESET- Message tag: CMD_TSYS_ERROR
Messageclass :XMK_MICRO_TRACERMeaning :Trace of system errorSent when :Any kind of systemerror was detectedDirection :T->HTypedefinition :xmk_T_CMD_TSYS_ERRORConditional compile:XMK_ADD_TERROR- Message tag: CMD_TSYS_SCHEDULE
Messageclass :XMK_MICRO_TRACERMeaning :Trace of system schedule eventSent when :When scheduling is performedDirection :T->HTypedefinition :xmk_T_CMD_TSYS_SCHEDULEConditional compile:XMK_ADD_TSCHEDULE- Message tag: CMD_TSYS_SHOWPRIO
Messageclass :XMK_MICRO_TRACERMeaning :Trace of system event : change priority levelSent when :When changing to another prioritylevelDirection :T->HTypedefinition :xmk_T_CMD_TSYS_SHOWPRIOConditional compile:XMK_ADD_TSHOWPRIO- Message tag: CMD_TBETWEEN_SYMBOL
Messageclass :XMK_MICRO_TRACERMeaning :Another symbol than input is executedSent when :Another symbol than input is executedDirection :T->HTypedefinition :xmk_T_CMD_TBETWEEN_SYMBOLConditional compile:XMK_ADD_SDLE_TRACE- Message tag: CMD_TAT_FIRST_SYMBOL
Messageclass :XMK_MICRO_TRACERMeaning :An Input symbol has bee executedSent when :An Input symbol is executedDirection :T->HTypedefinition :xmk_T_CMD_TAT_FIRST_SYMBOLConditional compile:XMK_ADD_SDLE_TRACEFormats Concerning the Cmicro Recorder
All messages belonging to the Cmicro Recorder are part of the message class XMK_MICRO_RECORDER (F2h).
- Message tag: CMD_RECORD_COUNT_IND
Messageclass :XMK_MICRO_RECORDERMeaning :Show recorded event counter to hostSent when :When ENV->SDL stimuli detectedDirection :T->HTypedefinition :xmk_CMD_RECORD_COUNT_INDConditional compile:XMK_ADD_MICRO_RECORDER- Message tag: CMD_RECORD_OUTPUT_ENV2SDL
Messageclass :XMK_MICRO_RECORDERMeaning :Indicate stimuli ENV->SDL to hostSent when :When ENV->SDL stimuli detectedDirection :T->HTypedefinition :xmk_T_CMD_RECORD_OUTPUT_ENV2SDLConditional compile:XMK_ADD_MICRO_RECORDER- Message tag: CMD_RECORD_OUTPUT_SDL2ENV
Messageclass :XMK_MICRO_RECORDERMeaning :unusedSent when :-Direction :T->HTypedefinition :-Conditional compile:XMK_ADD_MICRO_RECORDER- Message tag: CMD_PLAY_SECTION_REQ
Messageclass :XMK_MICRO_RECORDERMeaning :Request next sections from hostSent when :When current cnt reaches debit cntDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_MICRO_RECORDER- Message tag: CMD_PLAY_COUNT
Messageclass :XMK_MICRO_RECORDERMeaning :Transfer Debitcounter to targetSent when :When target requests next sectionsDirection :H->TTypedefinition :xmk_T_CMD_PLAY_COUNTConditional compile:XMK_ADD_MICRO_RECORDER
- Message description: The message is sent when the Cmicro Recorder is active and is in play mode. It is sent if the target requests the next stimuli (an environment signal). It is also sent in the initialization phase of the play mode. Outside the initialization phase, it is always sent together with, but after CMD_PLAY_OUTPUT_ENV2SDL.
- Message tag: CMD_PLAY_OUTPUT_ENV2SDL
Messageclass :XMK_MICRO_RECORDERMeaning :Transfer stimuli ENV->SDL to targetSent when :When target requests next sectionsDirection :H->TTypedefinition :xmk_T_CMD_PLAY_OUTPUT_ENV2SDLConditional compile:XMK_ADD_MICRO_RECORDER- Message tag: CMD_PLAY_OUTPUT_SDL2ENV
Messageclass :XMK_MICRO_RECORDERMeaning :unusedSent when :-Direction :H->TTypedefinition :-Conditional compile:XMK_ADD_MICRO_RECORDER- Message tag: CMD_RECORDER_OFF
Messageclass :XMK_MICRO_RECORDERMeaning :Switch off recorderSent when :When at end of replay session detectedDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_MICRO_RECORDERFormats Concerning the Command and Debug Interface
All messages belonging to the Cmicro Commands are part of the message class XMK_MICRO_COMMAND (F0h).
- Message tag: CMD_SUSPEND_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Suspend Cmicro KernelSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CSUSPEND- Message tag: CMD_RESUME_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Resume Cmicro KernelSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CRESUME- Message tag: CMD_SYSTEM_REINIT_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Reinitialize SDL systemSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CREINIT- Message tag: CMD_SYSTEM_SHUTDOWN_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Shutdown SDL systemSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CSHUTDOWN- Message tag: CMD_SINGLE_STEP_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Go into single stepSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CSINGLE_STEP- Message tag: CMD_DISABLE_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Disable processing of timersSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CDISABLE_TIMER- Message tag: CMD_ENABLE_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Enable processing of timersSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CENABLE_TIMER- Message tag: CMD_NEXT_STEP_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Execute next stepSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CNEXT_STEP- Message tag: CMD_SYSTEM_CONTINUE_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Continue system, if haltedSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CCONTINUE- Message tag: CMD_SET_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Set breakpointSent when :User typed in commandDirection :H->TTypedefinition :xmk_T__CMD_SET_BREAKPOINT_REQConditional compile:XMK_ADD_CBREAK_LOGIC- Message tag: CMD_BREAK_INPUT_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Set breakpoint on SDL inputSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_BREAK_INPUT_REQConditional compile:XMK_ADD_CBREAK_LOGIC- Message tag: CMD_BREAK_STATE_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Set breakpoint on nextstateSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_BREAK_STATE_REQConditional compile:XMK_ADD_CBREAK_STATE- Message tag: CMD_CLEAR_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Clear specified breakpoint from listSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_CLEAR_BREAKPOINT_REQConditional compile:XMK_ADD_CBREAK_LOGIC- Message tag: CMD_CLEAR_ALL_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Clear all breakpointsSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CBREAK_LOGIC- Message tag: CMD_QUERY_BREAKPOINT_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query the breakpoint listSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CBREAK_LOGIC- Message tag: CMD_QUERY_ERROR_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query last error occured in systemSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CQUERY_ERROR- Message tag: CMD_NEXT_STATE_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Modify processstate to valueSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_NEXT_STATE_REQConditional compile:XMK_ADD_CNEXTSTATE- Message tag: CMD_CREATE_PROCESS_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Create SDL processSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_CREATE_PROCESS_REQConditional compile:XMK_ADD_CCREATE_PROCESS- Message tag: CMD_TBUF_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query TracebufferSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CTBUF- Message tag: CMD_KILL_PROCESS_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Kill processSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_KILL_PROCESS_REQConditional compile:XMK_USE_CMD_KILL&XMK_ADD_CKILL_PROCESS- Message tag: CMD_PCO_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Define PCOSent when :unusedDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_QUERY_PROCESS_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query process stateSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_QUERY_PROCESS_REQConditional compile:XMK_ADD_CQUERY_PROCESS- Message tag: CMD_QUERY_QUEUE_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query all queuesSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CQUERY_QUEUE- Message tag: CMD_RMQUEUE_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Flush all queuesSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CRM_QUEUE- Message tag: CMD_SET_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Set SDL timerSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_SET_TIMER_REQConditional compile:XMK_ADD_CSET_TIMER- Message tag: CMD_RESET_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Reset SDL timerSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_RESET_TIMER_REQConditional compile:XMK_ADD_CRESET_TIMER- Message tag: CMD_QUERY_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query timertablesSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:XMK_ADD_CQUERY_TIMER- Message tag: CMD_ACTIVE_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Query, if timer activeSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_ACTIVE_TIMER_REQConditional compile:XMK_ADD_CACTIVE_TIMER- Message tag: CMD_FLUSH_SIGNAL_BY_SID_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Flush signals with given IDSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_FLUSH_SIGNAL_BY_SID_REQConditional compile:XMK_ADD_CFLUSH_SIGNAL_BY_SID- Message tag: CMD_FLUSH_SIGNALS_BY_PID_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Flush signals of processSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_FLUSH_SIGNALS_BY_PID_REQConditional compile:XMK_ADD_CFLUSH_SIGNALS_BY_PID- Message tag: CMD_RESET_ALL_TIMERS_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Reset all timersSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_RESET_ALL_TIMERS_REQConditional compile:XMK_ADD_CRESET_ALL_TIMERS- Message tag: CMD_SCALE_TIMER_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Scale timersSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_SCALE_TIMER_REQConditional compile:XMK_ADD_CSCALE_TIMER- Message tag: CMD_START_SDL_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Starts the SDL systemSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_START_SDL_REQConditional compile:-- Message tag: CMD_OUTPUT_TO_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Sends a signal from the environmentSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_OUTPUT_TO_REQConditional compile:-- Message tag: CMD_OUTPUT_INTERNAL_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Sends an internal signalSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_GET_CONFIG_REQ
Messageclass :XMK_MICRO_COMMANDMeaning :Gets the target's configurationSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_REC_OFF
Messageclass :XMK_MICRO_COMMANDMeaning :Switch recorder offSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_REC_PLAY
Messageclass :XMK_MICRO_COMMANDMeaning :Switch recorder to play modeSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_REC_RECORD
Messageclass :XMK_MICRO_COMMANDMeaning :Switch recorder to record modeSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_TRACE_ON
Messageclass :XMK_MICRO_COMMANDMeaning :Switch trace on in generalSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_TRACE_OFF
Messageclass :XMK_MICRO_COMMANDMeaning :Switch trace off in generalSent when :User typed in commandDirection :H->TTypedefinition :-Conditional compile:-- Message tag: CMD_TRACE_PROCESS
Messageclass :XMK_MICRO_COMMANDMeaning :Modify traceoptions for processSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_TRACE_PROCESSConditional compile:-- Message tag: CMD_TRACE_SIGNAL
Messageclass :XMK_MICRO_COMMANDMeaning :Modify traceoptions for signalSent when :User typed in commandDirection :H->TTypedefinition :xmk_T_CMD_TRACE_SIGNALConditional compile:-- Message tag: CMD_BREAK_HIT_IND
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate breakpoint hit to hostSent when :Breakpoint hit in targetDirection :T->HTypedefinition :xmk_T_CMD_BREAK_HIT_INDConditional compile:XMK_ADD_CBREAK_LOGIC- Message tag: CMD_ERROR_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Negative acknowledge on commandSent when :A command couldn't be executedDirection :T->HTypedefinition :-Conditional compile:-- Message tag: CMD_TBUF_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate TracebuffercontentsSent when :Response to user commandDirection :T->HTypedefinition :-Conditional compile:-- Message tag: CMD_OKAY_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Command acknowledgeSent when :Command correctly executedDirection :T->HTypedefinition :-Conditional compile:unconditional- Message tag: CMD_QUERY_PROCESS_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate process stateSent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_QUERY_PROCESS_CNFConditional compile:XMK_ADD_CQUERY_PROCESS- Message tag: CMD_QUERY_QUEUE_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate queue statesSent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_QUERY_QUEUE_CNFConditional compile:XMK_ADD_CQUERY_QUEUE- Message tag: CMD_QUERY_TIMER_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate timer tableSent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_QUERY_TIMER_CNFConditional compile:XMK_ADD_CQUERY_TIMER- Message tag: CMD_ACTIVE_TIMER_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate, if timer is activeSent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_ACTIVE_TIMER_CNFConditional compile:XMK_ADD_CACTIVE_TIMER- Message tag: CMD_QUERY_BREAKPOINT_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate breaklist to hostSent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_QUERY_BREAKPOINT_CNFConditional compile:-- Message tag: CMD_QUERY_ERROR_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate last error occuredSent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_QUERY_ERROR_CNFConditional compile:-- Message tag: CMD_START_SDL_IND
Messageclass :XMK_MICRO_COMMANDMeaning :Indicate ready for configurationSent when :Response to user commandDirection :T->HTypedefinition :-Conditional compile:-- Message tag: CMD_START_SDL_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Confirm SDL system startSent when :Response to user commandDirection :T->HTypedefinition :-Conditional compile:-- Message tag: CMD_GET_CONFIG_IND
Messageclass :XMK_MICRO_COMMANDMeaning :Send target's configurationSent when :Automatic at startupDirection :T->HTypedefinition :xmk_GET_CONFIG_INDConditional compile:-- Message tag: CMD_GET_DATA_CONFIG_IND
Messageclass :XMK_MICRO_COMMANDMeaning :see description belowSent when :Automatic at startupDirection :T->HTypedefinition :xmk_GET_DATA_CONFIG_INDConditional compile:XMK_USE_AUTO_MCOD- Message tag: CMD_GET_CONFIG_CNF
Messageclass :XMK_MICRO_COMMANDMeaning :Sent when :Response to user commandDirection :T->HTypedefinition :xmk_T_CMD_GET_CONFIG_CNFConditional compile:-Used Default Protocol
The data link part of the communications link is represented by the data link module and the coder module. The coder module ensures that each data link frame is encoded / decoded according to definitions of the default protocol.
- The protocol delivered with the Cmicro Package is easy to modify.
- It allows transfer of all the data necessary for each part of the SDL Target Tester
- It allows the transfer of user defined data to be integrated.
- No handshake procedure or retransmission request is implemented
Each frame of the Cmicro Protocol is seen from the physical layer as binary data.
Each frame consists of the following items:
- Message Class
Used to classify the information (is it SDL Target Tester or User defined data?). The codes F3h to FFh are free to use by the user, the other ones are reserved for the SDL Target Tester.- Message Tag
Used to differentiate the different information either of the SDL Target Tester or the user defined data. For user defined data, the message tag is free to use. If more than 255 bytes are to be transferred, the most significant bit of the message tag is set, otherwise it is cleared. This means there are up to 128 free values for the message tag.- SYNC
Fixed marker 0xaa is used to check if the receiver is synchronized with the sender. This is to detect problems in the start-up phase of host and target. This field of the message header is used in combination with the message class (>= F0h) to re-synchronize the data stream in the host's data link layer (sdtgate).- Message Length
Used to store the information about how many bytes are to follow after the length information, excluding the CRC information. The message length is normally encoded in one octet, which means the following data has a maximum length of 255 octets. If there is more data the most significant bit of the message tag is used to indicate that the message length exceeds 255 octets. In that case the message length is encoded in 2 octets which makes it possible to transfer 65536 octets of data.- Data
Free formatted data (user data or data for the SDL Target Tester).- Checksum
Used to check if the frame is OK on the receiving site. The checksum is built beginning from tag1 to the last data byte by a modulo-8 operation. The sync byte is included in the CRC.The following is an example of a coded Cmicro Protocol frame for a MS DOS PC, where the message tag is coded as CMD_TSTATIC_CREATE. Note this is only an example and the real coding may be different.
Example 624 : Coding for MS-DOS PC
The functions described in The API on Target can be used to encode / decode these frames.
The Communications Link's Target Site
The Data Link Layer
General
The data link of the communications link usually handles the separately message transfer of information from host and to host.
The data link uses the services and functions of the physical layer in order to transmit and receive information.
The data link offers functionality that makes it possible to send and to receive messages via the physical layer assigned to the data link. This functionality can be used by all programs (if implemented so). Mainly it is the SDL Target Tester which uses the data link layer services in order to send and to receive messages. But the users may want to send and receive messages, too. This is possible by using the data link layer functions and by regarding the defined protocol used for each message.
The data link layer offers the following functionality:
- Receive a message from any part of the system like kernel SDL processes or user defined C functions.
- Store messages in a buffer.
- If the physical layer is ready with the transfer of the last message, send the next message to the physical layer.
- If the physical layer indicates a complete message, store it into the receiving buffer.
- Deliver the messages, which have been stored within the receiving buffer to the requesting program parts.
- Poll the physical layer.
- Handle both directions in parallel.
- CRC procedures (if necessary).
The data link layer is represented by the following functions, which are exported by the data link (mg_dl) module.
Data Link Functions Used by SDL Target Tester
The SDL Target Tester's target library uses the following C functions of the link and buffering file mg_dl.c. The body of each C function may be rewritten according to the users needs.
xmk_DLInit xmk_DLQuery xmk_DLRead xmk_DLWrite xmk_DLDeinitThese functions are fixed into the SDL Target Tester's data link layer and they handle the mapping and the access to the physical layer.
The Physical Layer
General
Any type of physical communications link can be used to connect host and target, e.g. it could be a V.24, a TCP/IP or a IEEE 488 interface or it could be any other serial or parallel interface.
The physical layer of the communications link normally handles the byte-wise transfer of messages from host to target and the other way around.
It uses the services of the underlaying hardware like interrupts, CPU registers or memory mapped I/O.
The physical layer offers functionality to the data link layer in order to make it possible to transfer any kind of information, including SDL Target Tester data and / or user data.
The physical layer offers the following functionality:
- Receive a buffer which is to be transferred from the data link layer.
- Send this buffer byte-wise via special hardware (or OS - system call) to the receiving system (either host or target).
- If all characters of this buffer have been transmitted, request next buffer.
- Receive characters from the sending system via special hardware (or OS - system call).
- Collect characters until a message is complete; characters are stored within a temporary buffer.
- If message is complete in temporary buffer, transfer it to the data link layer.
- Handle both directions simultaneously.
- CRC procedures (if necessary).
Physical Layer Functions Used by the Data Link Layer (Default)
As described above the data link layer of the SDL Target Tester's target library is shown in the files mt_cod.c and mg_dl.c. Please note that mg_dl.c is only a template with a default implementation for the connection between data link and physical layer.
Distributed with the SDL Target Tester's target library, there are several template files for the physical layer (TCP/IP and V.24 interfaces) contained in the cmicro/template/commlink directory in the installation directory. These template files are tested only for the specific hardware in the Cmicro Package test environments. An error free compilation or execution cannot be guaranteed for the user's target hardware.
There are physical layer templates for the following target hardware:
- Intel 8051 derivatives -> 8051_v24.[ch]
Franklin/Keil C51 and IAR C51 compilers- Siemens 80C166 -> 80166v24.[ch]
BSO/Tasking 80C166 compiler- MS Windows NT/95 -> win32v24.[ch]
Microsoft VC++ 6.00- MS Windows NT/95 -> win_sock.[ch]
Microsoft VC++ 6.00- SunOS 5.x -> ux_sock.[ch]
GNU gcc, Sun WorkShop compilers CC and ccFor use in the target executable, one of the modules listed above is automatically included in mg_dl.c. Which physical layer module is included depends on the compiler selected and the flags set in ml_mcf.h (e.g. XMK_USE_V24 or XMK_USE_SOCKETS).
The template module mg_dl.c works as follows:
The function xmk_DLInit initializes the buffers used for the data link and calls the initialization of the physical layer (by default this is xmk_V24Init).
xmk_DLDeinit is the counterpart of xmk_DLInit and frees the interface device. This function is normally empty in microcontroller applications but has to be used on PCs, under Microsoft Windows or UNIX.
xmk_DLWrite is called when a complete frame should be sent to the host. There are two ways the connection to the physical layer can be handled.
- Blocked
- Unblocked
- If the frame should be sent, it is handed over to a ring buffer. Although the previous frame has not been sent completely, SDL can execute because the data link does not have to wait.
- One exception must be mentioned: If the transmitter's ring buffer (used for V.24 communication) is full (macro XMK_MAX_SEND_ENTRIES) the data link will still have to wait here. Also the size allowed for the ring buffer's entries must be great enough (to verify this see the macro XMK_MAX_SEND_ONE_ENTRY.
xmk_DLRead will be polled with each cycle of the SDL loop xmk_RunSDL (see module mk_main.c). If the transmitter and the receiver of the physical layer are not implemented as interrupt service routines (which is strongly recommended) the transmit and receive functions have to be called here (xmk_V24Receive and xmk_V24Send for the distributed V.24 templates). In addition for the V.24 interface the XON handshake has to be called here doing xmk_V24Handshake.
As in xmk_DLWrite there are two ways the receiver buffers can be handled in xmk_DLRead. It is also possible to use a ring buffer for the receiver's side. Similar as in xmk_DLWrite it is necessary to fill the macros XMK_MAX_RECEIVE_ONE_ENTRY and XMK_MAX_RECEIVE_ENTRIES with useful values.
Steps to Implement a Communications Link
Extension to the Template Makefile
In the distribution of the Cmicro Package there are several template makefiles.
On UNIX the existing makefile templates are called makeoptions.no_tester and makeoptions.with_tester.
In Windows the existing makefile templates are called makeno_t.opt and makew_t.opt.
The intention is to give one template makefile where the SDL Target Tester is not included (which means that there is no compilation of any SDL Target Tester C code), and to give one template makefile including the SDL Target Tester.
In the template makefiles that include the SDL Target Tester, it is necessary to define the communications link software by adding the name of the C module(s) that contain(s) this. This can be achieved by changing the list of the object files given in sctLINKTARGET_WITH_TESTER (e.g. 8051_v24.suffix). In addition, the compilation rules for this/these additional module(s) must be specified as well in the makefile.
Finally, the makefile name must be changed into makeoptions on UNIX, and into make.opt in Windows.
The makeoptions and make.opt files below the predefined kernel directories in <sdtdir>/SCMA* are not intended to be used for target or target debug applications.
Adapting the Data Link Layer
The data link layer for the SDL Target Tester on target site is represented by the module dl.c with the functions
Several ways to fill these functions are already given in mg_dl.c.
The data link layer can be build using a ring buffer for all the trace message or writing each message directly to the physical layer.
Furthermore the data link layer must be build to work together with the physical layers (E.g. ISR driven or not).
It is recommended to have a look into the distributed template mg_ dl.c which shows different ways.
- For using the ring buffer, please follow the flag TCC80166.
- For using no ring buffer, please follow the flags IARC51 or KEIL_C51.
- For using an ISR driven physical layer, please follow the flags IARC51 and KEIL_C51.
- For using a not ISR driven physical layer, please follow the flag TCC80166.
Adapting the Physical Layer
There are given tested physical layers for the micro controllers 8051 and 80166.
The structure of these physical layers should be taken and filled with the functions for the needed communications link. E.g. the function to write to a serial interface must be replaced by a function to write to an Ethernet interface.
The Communications Link's Host Site
The sdtgate is one executable of the SDL Target Tester's tool chain on host site. It is built to simplify the communication between the host and the target.
In this release of the SDL Target Tester, the sdtgate is built using a V.24 interface and the sockgate is build using a TCP/IP interface. But as you can see in this subsection, it will be very simple to implement any other communication interface as a new executable.
Communication between the SDL Target Tester Executables
The SDL Target Tester executables sdtmtui, sdtmt and sdtgate communicate with the help of the Cmicro Postmaster. The Cmicro Postmaster handles all the communication between the SDL Target Tester tool chain and is started automatically when the SDL Target Tester is invoked.
The Default V.24 Connection: Sdtgate
Fork Parameters for the Sdtgate
There are two groups of fork parameters handed over to the sdtgate.
The Sdtgate Device Specifications
Inside the SDL Target Tester configuration file sdtmt.opt there are 7 entries for the gateway executable.
USE_GATE <pathname>/sdtgateGATE_CHAR_PARAM_1 /dev/ttyaGATE_CHAR_PARAM_2 0GATE_CHAR_PARAM_3 0GATE_INT_PARAM_1 9600GATE_INT_PARAM_2 0GATE_INT_PARAM_3 0On UNIX, it muse be ensured that the device (/dev/ttya above) is accessible. Ask the system administrator if there are problems to open this device.
USE_GATE <pathname>/sdtgate.exeGATE_CHAR_PARAM_1 COM2GATE_CHAR_PARAM_2 0GATE_CHAR_PARAM_3 0GATE_INT_PARAM_1 9600GATE_INT_PARAM_2 0GATE_INT_PARAM_3 0USE_GATE gives the name of the used gate only.
Inside the delivered sdtgate for V.24 interface only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. For future developments there are 2 further string parameters and two further integer parameters which are handed over when forking the gate.
The delivered version of the sdtgate uses fixed values for parity, start bits, stop bits...
These are: databits = 8, startbits = 1, stopbits = 1, parity = none
Coding Rules
There are two coding rule pieces of information the gate needs to work.
These are the length of a character on the target in octets (normally 1) and the position of the character. This value is necessary for special micro controller memory layouts e.g. the MSP58C80 gets the character length of 2 octets but the used character is the lower octet only. In this case the character position is 1. Normally if the character size is 1 the character position is 0.
The TCP/IP Connection: Sockgate
The Sockgate Device Specifications
Like the sdtgate, the sockgate is using only 3 of the 7 entries for the gateway executable inside the SDL Target Tester configuration file sdtmt.opt.
USE_GATE <pathname>/sockgateGATE_CHAR_PARAM_1 207.46.138.0GATE_CHAR_PARAM_2 0GATE_CHAR_PARAM_3 0GATE_INT_PARAM_1 9000GATE_INT_PARAM_2 0GATE_INT_PARAM_3 0USE_GATE gives the name of the used gate only.
It must be ensured that the IP-address (207.46.138.0 above) is accessible.
Inside the delivered sockgate only the GATE_CHAR_PARAM_1 (a string) and the GATE_INT_PARAM_1 (an integer) are used. The delivered version of the sockgate uses an address string (a valid IP-address) and a port number (valid between 1 and 65535).
Building an Custom Made Communications Link
All the C files and libraries necessary to re-build the default gateway sdtgate are delivered with the SDL Target Tester. The files for a custom built gateway are named usergate to distinguish between the custom and the delivered sdt- and sockgate.
The Modules Building a Usergate
The following files are part of the usergate:
cmicro+ sdtmpm| + sunos5| | + sdtmlib.a (SunOS 5 version)| + wini386| + sdtmpmcl.lib (Microsoft C++ 6.0 version)| + sdtmpmcl5.lib (Microsoft C++ 5.0 version)+ mcod| + mcodfnc.[ch]pp| + mcodlib.[ch]pp| + mcod.h+ sdtgate| + mg_ctrl.[ch]| + usergate.rc (Windows only)| + sunos5| | + usergate.[ch] (SunOS 5 version)| + wini386| + usergate.[ch] (Windows version)+ template+ mg_dl.[ch]+ commlink+ <interface>.[ch]Files with suffix .h and .hpp are not listed but are still being used.
<interface> stands for the selected interface type.
On UNIX the module ux_v24.c is used (ux_sock.c for sockets).
In Windows the module win32v24.c is used (win_sock.c for sockets).
The purpose of each module is as follows:
- mcodfnc.cpp
- This module delivers all functions to decode and encode the messages sent between the different executables of the SDL Target Tester tool chain. All functions are contained within a C++ class called ClassHostMessage.
- As these functions have to be suitable for the executables sdtmt and sdtmtui, no changes need be made by the user.
- mcodlib.cpp
- mcod.h
- mg_ctrl.c
- usergate.rc (Windows only)
- usergate.c
- This file handles all the initialization and communication of the sdtgate with the Cmicro Postmaster.
- This file is platform specific and needs to be modified in some cases, e.g. when using the V.24 or socket interface on MS Windows a Windows Message is generated when a character is received or completely sent. The reaction on the WM_COMMNOTIFY message can be removed here if another interface is used.
- sdtmlib.a/sdtmpmbc.lib/sdtmpmcl.lib
- <Interface>.c
- The last of the listed files needs some modifications if the communication interface is to be changed.
- There are eight functions inside this module
- xmk_V24Init() and xmk_SocketInit()
These functions are called only once after the sdtgate has been forked. All initialization of the communication device have to be done here.
Errors should be given as plain text and will be sent to the user interface.- xmk_V24Deinit() and xmk_SocketDeinit()
These functions may not need to be filled for the wanted communication interface. If it has to, all deinitialization can be done here. This function is called directly before exiting the gate.- xmk_V24Handshake()
The V.24 RS-232 protocol describes the use of the XON - XOFF communication. In the SDL Target Tester's host - target communication XON characters sent only every second. If using another communication protocol (like RS-422/RS-485) this function must be left empty.- xmk_V24Receive() and xmk_SocketReceive()
This function does several things.
At first the communication interface is polled and all available characters are taken from the interface. Then the gate checks the received character stream for the correct sync field position, the length field is read and the amount of characters used to build one complete target message is sent to sdtmt, unless there are no complete messages left.
The re-synchronization of the data stream is also done in this function if the sync field is not in the correct position.- xmk_V24Send() and xmk_SocketSend()
If the gate gets a message from sdtmt which is to be transmitted to the target, this function is called.
There are several ways to transmit the whole message. For instance, on Windows NT it is possible to hand over a character buffer to the serial interface. The rest of the transmission is being done by the interface itself.- xmk_ExtractControl() / xmk_MaskControl()
These two functions are for use with an XON-XOFF protocol. If a message contains an XON or XOFF character, in front of this XON or XOFF an ESC is inserted in xmk_MaskControl() to differ this (XON/XOFF-) character from the control XON/XOFF.
On the other hand if a message containing XON/XOFF characters is received, the function xmk_ExtractControl() removes all ESC from the data stream.
These functions are called from xmk_V24Send() and xmk_V24Receive() only and the function calls should be removed if the new communication interface does not support the XON-XOFF protocol.Compiler Settings
- On UNIX:
- In Windows:
Current Restrictions for Communications Link Software
SDL Restrictions
It is impossible to transfer pointer values via the communications link. An example may be the SDL predefined sort charstring which is by default implemented as a pointer in C.
To avoid problems, users must not use SDL sorts that are implemented as pointers (like charstring), whenever it is required to send / receive them via the communications link (e.g. Cmicro Tracer or Cmicro Recorder functionality). This means, that this kind of sorts should only be used in signals inside the SDL system but not at it's environment.
Message Length
The maximum length of the message length is restricted.
Each message is transferred as:
Header + Data + CRCThe length field contained in the header may represent the values from 0 to 255. If the MSB in the message tag is set to "1", then the length field is expected to be a 2 octet values, which makes it possible to represent the value from 256 to 65535.
However, the length field consisting of 2 octets is currently not implemented.
In fact, no message may be greater than 4 + 255 + 1 = 260 characters in total (1 character normally is equal to 1 Byte, which consists of 8 Bits).
Connection of a Newly Implemented Communications Link
The SDL Target Tester uses only a few C function calls in order to send and receive information via the communications link. From the C syntax point of view, users only have to implement the body of these functions and to link them together with the SDL Target Tester's target library into one executable program.
However, when considering timing constraints, critical paths, interrupts and similar things, users have to note the following.
Critical Paths
Critical paths occur in any type of software which uses interrupts. Especially the transfer of information between ordinary C code and interrupt service routines must be considered, e.g. for the communication from the physical layer (which may be implemented as an ISR) to the data link layer (which may be implemented as ordinary C functions).
Critical paths may occur at any place in the software which accesses global C variables.
The beginning of each critical path must be blocked with something like "disable interrupts" (see XMK_BEGIN_CRITICAL_PATH in the compiler section of ml_typ.h). The end of a critical path must be released with something like "enable interrupts" (see XMK_END_CRITICAL_PATH).
Timing Constraints
Often there are timing constraints to be considered within the target system. Timing problems must be prevented. Each ISR must be implemented with a few statements only, in order to make the execution time as short as possible.
Interrupts
C functions which should be compiled as ISRs by the C compiler in use are mostly
marked by a preprocessor directive or by a special C compiler keyword. The C compilers reference manual must be consulted in order to implement ISRs.
Open Interface
The open interface can be used to implement user host executables which are able to communicate with the SDL Target Tester at the target site. The SDL Target Tester at the target site is represented by the target library.
Using the Open Interface
In order to use the open interface in this way, the following are of interest:
- Which messages can be sent to the target. This is described within the earlier subsection Message Formats.
- Which messages are to be expected from the target. This is also described within Message Formats.
- The format of these messages. Also described within the earlier subsection Message Formats.
- The situations in which the messages may be sent. Please refer to the subsection State Machine and Handshake.
- The situations in which a particular message may be received. Again, please refer to State Machine and Handshake.
It is not of great interest what the format of the data link frames is because it is possible either to use the existing protocol or to re-implement the protocol (e.g. it may be necessary in order to integrate the SDL Target Tester into an existing communication link's software).
The host site must send each message in target representation.
For instance, if the target system uses integers as 2 octet values with the ordering higher octet first, then the host must send an integer value with higher octet and then lower octet, irrespective of its own layout.
For the other direction (reception of messages at host site), the host must also map the information according to the relation between the target memory layout and its own internal representation.
Accessing the Data Link by User
The user can send information via the communication link by calling the C function xmk_DLWrite with appropriate parameters. The following example shows one possibility.
#define HelloWorldTag <AnyValueAllowed>char buffer [20];char helloworld [15];int length = 0;int write_result ;strcpy (helloworld, 'Hello World');buffer [0] = 0x11;length ++;/* any value for Messageclass, except *//* reserved values for SDL Target Teste *//* reserved values begin from 250 to 255 */buffer [1] = HelloWorldTag;length ++;/* any value for Messagetag *//* Messagetag is made unique together *//* with Messageclass, so that no *//* conflict occurs. */buffer [2] = strlen (helloworld);length ++;/* length of data for this message *//* length is given without calculating *//* the CRC field */memcpy (buffer [3], helloworld, strlen (helloworld);length += strlen (helloworld);/* It is assumed, that no stringterminator *//* is included in the message (the length *//* can be calculated from Messagelength) */buffer [length] = xmk_EvalChkSum (buffer, length);/* Evaluate the checksum of current buffer */write_result = xmk_DLWrite (buffer, 5 + strlen (helloworld));/* transmit buffer via communications link */The user can receive information from the communication link by calling the C function xmk_DLRead with appropriate parameters.
The following section is partially implemented within the module mk_main.c
p_data = xmk_DLRead () ;if (p_data != (char *) NULL){/* if anything received, decode it *//* according to Cmicro Protocol */result = xmk_Cod_Decode (p_data,&MessageClass,&Messagetag,&MessageLength,buffer,sizeof (buffer));if (MessageClass == XMK_MICRO_COMMAND){result = xmk_HandleCmd ( Messagetag, (xmk_U_CMDS*) buffer );return;}/*** Received user message*/if (MessageClass != 0xF8){ErrorHandler (-7777);return ;}if (HelloWorldTag == Messagetag){/* HelloWorldTag is used in this example to *//* identify the hello world message *//* The user can choose any value for the *//* Message tag */char helloworld [15];memset (helloworld, 0, sizeof (helloworld));memcpy (helloworld, buffer, MessageLength);printf ('%s', helloworld);}The above examples assume that the Cmicro protocol (which is described in Used Default Protocol) is used.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |