code_notes.lyx

CNC 的开放码,EMC2 V2.2.8版

\layout LyX-Code

        timer.wait();    /* Wait till the next 5 second interval */
\layout LyX-Code

    }
\layout LyX-Code

    delete timer;
\layout LyX-Code

}
\layout Section

Semaphore
\layout Standard

The Semaphore class provides a method of mutual exclusions for accessing
 a shared resource.
 The function to get a semaphore can either block until access is available,
 return after a timeout, or return immediately with or without gaining the
 semaphore.
 The constructor will create a semaphore or attach to an existing one if
 the ID is already in use.
\layout Standard

The Semaphore::destroy() must be called by the last process only.
\layout Section

CMS
\layout Standard

At the heart of libnml is the CMS class, it contains most of the functions
 used by libnml and ultimately NML.
 Many of the internal functions are overloaded to allow for specific hardware
 dependant methods of data passing.
 Ultimately, everything revolves around a central block of memory (referred
 to as the 
\begin_inset Quotes eld
\end_inset 

message buffer
\begin_inset Quotes erd
\end_inset 

 or just 
\begin_inset Quotes eld
\end_inset 

buffer
\begin_inset Quotes erd
\end_inset 

).
 This buffer may exist as a shared memory block accessed by other CMS/NML
 processes, or a local and private buffer for data being transfered by network
 or serial interfaces.
\layout Standard

The buffer is dynamically allocated at run time to allow for greater flexibility
 of the CMS/NML sub-system.
 The buffer size must be large enough to accommodate the largest message,
 a small amount for internal use and allow for the message to be encoded
 if this option is chosen (encoded data will be covered later).
 Figure 
\begin_inset LatexCommand \ref{fig:CMS buffer}

\end_inset 

 is an internal view of the buffer space.
\layout Standard


\begin_inset Float figure
wide false
collapsed false

\layout Standard
\align center 

\begin_inset Graphics
	filename CMS_buffer.eps
	width 3in
	height 4in
	keepAspectRatio

\end_inset 


\layout Caption


\begin_inset LatexCommand \label{fig:CMS buffer}

\end_inset 

CMS buffer
\end_inset 


\layout Standard

The CMS base class is primarily responsible for creating the communications
 pathways and interfacing to the O.S.
\layout Chapter

NML Notes /* FIX ME */
\layout Standard


\shape italic 
A collection of random notes and thought whilst studying the libnml and
 rcslib code.
\layout Standard


\shape italic 
Much of this needs to be edited and re-written in a coherent manner before
 publication.
\layout Section

Configuration file format
\layout Standard

NML configuration consists of two types of line formats.
 One for Buffers, and a second for Processes that connect to the buffers.
\layout Subsection

Buffer line
\layout Standard

The original NIST format of the buffer line is:
\layout Standard

B name type host size neut RPC# buffer# max_procs key [type specific configs]
\layout Itemize

B identifies this line as a Buffer configuration.
\layout Itemize

name is the identifier of the buffer.
\layout Itemize

type describes the buffer type - SHMEM, LOCMEM, FILEMEM, PHANTOM, or GLOBMEM.
\layout Itemize

host is either an IP address or host name for the NML server
\layout Itemize

size is the size of the buffer
\layout Itemize

neut a boolean to indicate if the data in the buffer is encoded in a machine
 independent format, or raw.
\layout Itemize

RPC# Obsolete - Place holder retained for backward compatibility only.
\layout Itemize

buffer# A unique ID number used if a server controls multiple buffers.
\layout Itemize

max_procs is the maximum processes allowed to connect to this buffer.
\layout Itemize

key is a numerical identifier for a shared memory buffer
\layout Subsection

Type specific configs
\layout Standard

The buffer type implies additional configuration options whilst the host
 operating system precludes certain combinations.
 In an attempt to distill published documentation in to a coherent format,
 only the SHMEM buffer type will be covered.
\layout Itemize

mutex=os_sem - default mode for providing semaphore locking of the buffer
 memory.
\layout Itemize

mutex=none - Not used
\layout Itemize

mutex=no_interrupts - not applicable on a Linux system
\layout Itemize

mutex=no_switching - not applicable on a Linux system
\layout Itemize

mutex=mao split - Splits the buffer in to half (or more) and allows one
 process to access part of the buffer whilst a second process is writing
 to another part.
\layout Itemize

TCP=(port number) - Specifies which network port to use.
\layout Itemize

UDP=(port number) - ditto
\layout Itemize

STCP=(port number) - ditto
\layout Itemize

serialPortDevName=(serial port) - Undocumented.
\layout Itemize

passwd=file_name.pwd - Adds a layer of security to the buffer by requiring
 each process to provide a password.
\layout Itemize

bsem - NIST documentation implies a key for a blocking semaphore, and if
 bsem=-1, blocking reads are prevented.
\layout Itemize

queue - Enables queued message passing.
\layout Itemize

ascii - Encode messages in a plain text format
\layout Itemize

disp - Encode messages in a format suitable for display (???)
\layout Itemize

xdr - Encode messages in External Data Representation.
 (see rpc/xdr.h for details).
\layout Itemize

diag - Enables diagnostics stored in the buffer (timings and byte counts
 ?)
\layout Subsection

Process line 
\layout Standard

The original NIST format of the process line is:
\layout Standard

P name buffer type host ops server timeout master c_num [type specific configs]
\layout Itemize

P identifies this line as a Process configuration.
\layout Itemize

name is the identifier of the process.
\layout Itemize

buffer is one of the buffers defined elsewhere in the config file.
\layout Itemize

type defines whether this process is local or remote relative to the buffer.
\layout Itemize

host specifies where on the network this process is running.
\layout Itemize

ops gives the process read only, write only, or read/write access to the
 buffer.
\layout Itemize

server specifies if this process will running a server for this buffer.
\layout Itemize

timeout sets the timeout characteristics for accesses to the buffer.
\layout Itemize

master indicates if this process is responsible for creating and destroying
 the buffer.
\layout Itemize

c_num an integer between zero and (max_procs -1)
\layout Subsection

Configuration Comments
\layout Standard

Some of the configuration combinations are invalid, whilst others imply
 certain constraints.
 On a Linux system, GLOBMEM is obsolete, whilst PHANTOM is only really useful
 in the testing stage of an application, likewise for FILEMEM.
 LOCMEM is of little use for a multi-process application, and only offers
 limited performance advantages over SHMEM.
 This leaves SHMEM as the only buffer type to use with emc2.
\layout Standard

The neut option is only of use in a multi-processor system where different
 (and incompatible) architectures are sharing a block of memory.
 The likelihood of seeing a system of this type outside of a museum or research
 establishment is remote and is only relevant to GLOBMEM buffers.
\layout Standard

The RPC number is documented as being obsolete and is retained only for
 compatibility reasons.
\layout Standard

With a unique buffer name, having a numerical identity seems to be pointless.
 Need to review the code to identify the logic.
 Likewise, the key field at first appears to be redundant, and it could
 be derived from the buffer name.
\layout Standard

The purpose of limiting the number of processes allowed to connect to any
 one buffer is unclear from existing documentation and from the original
 source code.
 Allowing unspecified multiple processes to connect to a buffer is no more
 difficult to implement.
\layout Standard

The mutex types boil down to one of two, the default 
\begin_inset Quotes eld
\end_inset 

os_sem
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

mao split
\begin_inset Quotes erd
\end_inset 

.
 Most of the NML messages are relatively short and can be copied to or from
 the buffer with minimal delays, so split reads are not essential.
\layout Standard

Data encoding is only relevant when transmitted to a remote process - Using
 TCP or UDP implies XDR encoding.
 Whilst ascii encoding may have some use in diagnostics or for passing data
 to an embedded system that does not implement NML.
\layout Standard

UDP protocols have fewer checks on data and allows a percentage of packets
 to be dropped.
 TCP is more reliable, but is marginally slower.
\layout Standard

If emc2 is to be connected to a network, one would hope that it is local
 and behind a firewall.
 About the only reason to allow access to emc2 via the Internet would be
 for remote diagnostics - This can be achieved far more securely using other
 means, perhaps by a web interface.
\layout Standard

The exact behaviour when timeout is set to zero or a negative value is unclear
 from the NIST documents.
 Only INF and positive values are mentioned.
 However, buried in the source code of rcslib, it is apparent that the following
 applies:
\layout Standard

timeout > 0 Blocking access until the timeout interval is reached or access
 to the buffer is available.
\layout Standard

timeout = 0 Access to the buffer is only possible if no other process is
 reading or writing at the time.
\layout Standard

timeout < 0 or INF Access is blocked until the buffer is available.
\layout Section

NML base class /* FIX ME */
\layout Standard


\shape italic 
Expand on the lists and the relationship between NML, NMLmsg, and the lower
 level cms classes.
\layout Standard

Not to be confused with NMLmsg, RCS_STAT_MSG, or RCS_CMD_MSG.
\layout Standard

NML is responsible for parsing the config file, configuring the cms buffers
 and is the mechanism for routing messages to the correct buffer(s).
 To do this, NML creates several lists for:
\layout Itemize

cms buffers created or connected to.
\layout Itemize

processes and the buffers they connect to
\layout Itemize

a long list of format functions for each message type
\layout Standard

This last item is probably the nub of much of the malignment of libnml/rcslib
 and NML in general.
 Each message that is passed via NML requires a certain amount of information
 to be attached in addition to the actual data.
 To do this, several formatting functions are called in sequence to assemble
 fragments of the overall message.
 The format functions will include NML_TYPE, MSG_TYPE, in addition to the
 data declared in derived NMLmsg classes.
 Changes to the order in which the formatting functions are called and also
 the variables passed will break compatability with rcslib if messed with
 - 
\shape italic 
There are reasons for maintaining rcslib compatability, and good reasons
 for messing with the code.
 The question is, which set of reasons are overriding ?
\layout Subsection

NML internals
\layout Subsubsection

NML constructor
\layout Standard

NML::NML() parses the config file and stores it in a linked list to be passed
 to cms constructors in single lines.
 It is the function of the NML constructor to call the relevant cms constructor
 for each buffer and maintain a list of the cms objects and the processes
 associated with each buffer.
\layout Standard

It is from the pointers stored in the lists that NML can interact with cms
 and why Doxygen fails to show the real relationships involved.
\layout Standard

(side note) The config is stored in memory before passing a pointer to a
 specific line to the cms constructor.
 The cms constructor then parses the line again to extract a couple of variables...
 It would make more sense to do ALL the parsing and save the variables in
 a struct that is passed to the cms constructor - This would eliminate string
 handling and reduce duplicate code in cms....
\layout Subsubsection

NML read/write
\layout Standard

Calls to NML::read and NML::write both perform similar tasks in so much
 as processing the message - The only real variation is in the direction
 of data flow.
\layout Standard

A call to the read function first gets data from the buffer, then calls
 format_output(), whilst a write function would call format_input() before
 passing the data to the buffer.
 It is in format_xxx() that the work of constructing or deconstructing the
 message takes place.
 A list of assorted functions are called in turn to place various parts
 of the NML header (not to be confused with the cms header) in the right
 order - The last function called is emcFormat() in emc.cc.
\layout Subsubsection

NMLmsg and NML relationships
\layout Standard

NMLmsg is the base class from which all message classes are derived.
 Each message class must have a unique ID defined (and passed to the constructor
) and also an update(*cms) function.
 The update() will be called by the NML read/write functions when the NML
 formatter is called - The pointer to the formatter will have been declared
 in the NML constructor at some point.
 By virtue of the linked lists NML creates, it is able to select cms pointer
 that is passed to the formatter and therefor which buffer is to be used.
\the_end