[TEG.LCLSDOC]TIMEX.STUFF 29 Mar 2004 rev. 06 May 2004 This is just a sketchy description of how timing information is sent from VMS to iRMXmicro. Read this at your own risk. A task (TIMING_download_task in REF_RMX_TIME:TIMING_DOWNLOAD.C86) in the iRMXmicro is dedicated to receiving download of timing data from process TIMEX running in (prod or dev) Alpha. At bootup time the iRMXmicro sends an unsolicited message to TIMEX requesting the download. For any micro, this download consists of at most three major blocks: TMATRIX & TNOMINAL; DUPCD conditional expressions; TMVA's. TIMEX does not handle timing value updates ("ENTER TDES" on a timing panel of a SCP, or turns of a timing knob); the SCP transmits those via the "SLC message service". (Note: TIMEX's unique 4-char id as defined in includefile REF_C_INC:PROCESS_PARM.H is "V074".) TIMEX redownloads a micro's DUPCD conditional expressions whenever requested to do so by a SCP with which an operator has edited DUPCD conditional expressions for that micro. TIMEX enqueues download requests whether those requests come from a SCP or from micros being booted, and for any micro TIMEX strictly serializes any such requests. Downloading or redownloading a micro's DUPCD conditional expressions necessarily entails reloading internal memory of all that micro's PDU's, halting that micro's timing outputs for a few seconds. Message from micro initially requesting download from TIMEX consists of structure fwd_hdr_ts (defined in REF_C_INC:MSGHEAD.HC) followed by structure timex_ip_hdr_ts followed by structure timex_micrreqmsg_ts (both defined in REF_C_INC:RGBM_TSTRUCTS.HC). If transmission is via SLCnet as opposed to IP/TCP then fwd_hdr_ts and timex_ip_hdr_ts are omitted. Longword flags in structure timex_micrreqmsg_ts can have any or all or none of bits TIMEX_REQFLAG_TMATRIX, TIMEX_REQFLAG_TEXPR, and TIMEX_REQFLAG_TMVA (defined in REF_C_INC:RGBM_DEFINES.HC) set, requesting all or any subset or none of the three kinds. In this request message, longword type in timex_micrreqmsg_ts should contain value TIMEX_REQTYPE_DOWNLOAD. In any download from TIMEX, the first message is a timex_dwnld_hdrmsg_ts (headed by structures fwd_hdr_ts and timex_ip_hdr_ts unless SLCnet). Most elements of timex_dwnld_hdrmsg_ts are documented in RGBM_TSTRUCTS.HC. Longword flags (echo if request originated in micro) tells which major blocks should be processed. The timex_dwnld_hdrmsg_ts contains size and checksum for each of the three major blocks; zero size means major block is absent; if indicated size of major block is zero but that major block's flags bit is set then the micro's existing copy if any of that major block should be deleted; if that major block's flags bit is not set then the micro's existing copy if any of that major block should remain as is. Order of three major blocks is: TMATRIX & TNOMINAL if present; timing value sum expressions & beamcode translation structures if present; TMVA's if any used in this micro. After micro has processed all major blocks sent, micro must send timex_micrfinmsgh_ts acknowledgement to TIMEX in which longword status contains final VMS-style status code (see error message definition file REF_SLCMSG:TIMEDEF.MSG); again, fwd_hdr_ts and timex_ip_hdr_ts are absent if SLCnet. TMATRIX consists of a two-dimensional array of longwords, where the (inner) row length is 32 = max possible "base beamcode" + 1 = N_BEAMS (defined in REF_C_INC:SLCPARM.HC), and the grosser subscript indexes through just those devices represented in the TMATRIX for that micro. In this major block, the micro's TNOMINAL immediately follows TMATRIX, and consists simply of one more row of N_BEAMS longwords indexed by base beamcode - 1, though in fact the micro never refers to this copy of TNOMINAL. Longwords in any row in TMATRIX are indexed by base beamcode - 1, and the last longword is wasted (beamcode 0 is reserved for no-op and is not considered a base beamcode). See includefiles REF_C_INC:TMATRIX.H,TMATNODES.H. To see how structures defined in those two includefiles get created and filled to start with, see source file REF_TMATRIX:TGEN_SUB.FOR. For definitions of flag bits in any longword in TMATRIX, see REF_C_INC:TMATPARM.HC. DUPCD timing value sum expression major block consists of numerous small variable-length structures concatenated one after another. Do read comments carefully in REF_C_INC:RGBM_TSTRUCTS.HC,RGBM_DEFINES.HC; comments in RGBM_VAX_TYPES.H may also be helpful, though micro code never sees contents of that includefile. Representations of DUPCD conditional expressions themselves are unneeded in the micro; TIMEX sends to the micro timing value sum expressions by which the micro can update timing values for substitute beamcodes, and beamcode translation structures by which the micro, on any one 360th of a second, can extract from the PNET broadcast message the base beamcode and a subset of modifier bits (compacting the latter down to an integer of at most 11 = MODF_BITS_PBCOD_MAX bits) to find the actual "substitute" beamcode to broadcast to timing devices via camac F19A8,F19A9,F19A10. The basic limitation is the 8-bit value sent via F19, and since in some micros the usage of beamcode modifier bits turned out to proliferate far enough to overrun the PDU's 8-bit decoding space, the micro is further subdivided into at most four crate groups, for each of which the DUPCD conditional expression translation is done separately (expression translation by the Alpha, and PNET translation by the micro). By the way, any camac crate can contain at most one PDU or PPDU (for hardware reasons). Micro's 360-Hz interrupt-driven routine, given a PNET message, does the following for each crate group: extract base beamcode from PNET message, and use instance (if any for that base beamcode and this crate group) of structure rg_pptrans_head_ts to extract & compact the relevant beamcode modifier bits and look up corresponding substitute beamcode for broadcast on F19 to crates in this crate group (and if that rg_pptrans_head_ts instance is missing then base beamcode is used). Micro's task-level procedure TIMING_output_tmatrix_val in module REF_RMX_TIME:TIMING_UPWRITE.C86, which processes any timing value update (received from SCP via "SLC message service") for a given timing channel and base beamcode, must go through all timing value sum expressions for that timing channel and base beamcode to compute (and write into PDU's memory) timing values for associated substitute beamcodes. Similarly, procedure TIMING_update_tmva_val, which processes any TMVA value update, must go through all timing value sum expressions and reevaluate & output all those which involve the given TMVA. In the DUPCD timing value sum expression major block sent by TIMEX, the timing value sum expressions (tmvsum_micx_beg_ts's) come first, followed by the rg_pptrans_head_ts's, but note again that each instance of each structure is variably more than what the named structure definition shows. TMVA's are timing variables which can span micros, and overlap the function of timing knobs, and possibly may be left unimplemented in LCLS IOC. Note in case you have occasion to look at the iRMXmicro code: For replacing a block of information that will be seen by interrupt-driven code, task-level code accomplishes the installation or replacement by using a single uninterruptible instruction. Since there is no single instruction for storing a far pointer (48-bit pointer consisting of offset and selector), the thing stored must be either a selector or a near pointer as opposed to a far pointer. For sharing a counter or a word containing flag bits between interrupt-driven code and task-driven code, each instance of such code depends on usage of a single uninterruptible instruction to update (read & write) memory. Structures of messages by which SCP sends (via "SLC message service", not via TIMEX) timing value updates (SCP touchpanel ENTER TDES or ACTIVATE or DEACTIVATE or REACTIVATE button pushes, or turns of a timing multi-knob) are defined in includefile REF_C_INC:TIME_REQREPLY_STRUC.HC. Function codes identifying these messages are defined in includefile REF_C_INC:TIMEFUNC.HC. Surely only a subset need ever be implemented in IOC code. VDU update messages carry a longword integer value in ticks of the right kind, and relative to that a floating-point value in nanoseconds, in hopes of avoiding straddling an "edge" caused by rounding from floating-point (unfortunately that trick doesnt suffice). By the way, surely no TGAS will exist in any LCLS IOC (dont ask). Note on include filename extension convention: almost all of our own .H files are never seen by iRMXmicro code; .HC files are seen commonly by both VMS code and iRMXmicro code; .HM files are seen only ever by iRMXmicro code. Future .HF files will be for the benefit of the FECC, which deals only in longwords.