##*************************************
##
## E.S.O. - VLT project
##
## "@(#) $Id: README,v 1.2 1999/04/22 14:52:44 vltsccm Exp $"
##
## README"
## 
## who      when     what
##-------- -------- ------------------
##
README


This directory contains the "lcumod" template module, used as starting point to
create a lcc command interpreter based application. The purpose of this
template is twofold, first to provide to lcu's developpers an application
skeleton, composed mainly by lcc standard functions and commands, with 
conventions on naming and files organisation, then to present some tools
developped during the ntt sw upgrade.


Components
==========

Currently the "lcumod" module is composed by:

1.Inlude files

lcumod.h provided to applications to access lcumod by direct procedure calls.
It will be also used for unit test programs.
	
lcumodInternal.h for lcumod internal use.

lcumodErrors.h for lcumod errors definition. The most common error are based on  
predefined errors in "tooErrors.h". The new module has to define specific ones
and to update the ERRORS/lcumod_ERRORS file.

lcumodDatabase.h 
	
lcumodSignals.h 
	
2. Source files
	
lcumodDbConfig.c to get direct addresses of all database parameters defined in
lcumodDatabase.h.

lcumodIoConfig.c to get direct addresses of all signals defined in lcumodSignals.h.

lcumodStd<function>.c where function stands for lcc standard functions such as 
lcumodStdInit, lcumodStdOnline...
The standard functions are templates. Please add in these templates
the actions required for your system.
	
Additional standard functions such as lcumodStdGetVersion, lcumodStdGetState,
lcumodStdGetSimulation.c.
	
Additional internal functions such as lcumodStdCheckOnline, 
lcumodStdSetSimulation.

lcumodStdInterface for these lcc standard interface functions
	
lcumodInitAll.c for general initialisation. It will start the application as a
Command Server.
	
lcumodExample.c to provide two examples of database access functions:
lcumodSetDbValue and lcumodGetDbValue. The first function can only be executed
if the module is in lcc "Online" state, and the valid value to set is defined
from -1000 to +1000 range in the CDT file.
	
lcumodInterface.c for these two example interface functions

Templates for Break and Kill signal handlers (lcumodHandleBreak.c,
lcumodHandleKill.c). Add in these templates the actions required for your 
system.
	
3. CDT/CIT

Defining all lcc standard commands and the two example commands: SETDB and 
GETDB.

Command naming convention:

- The command shall describe the action (a verb). The object shall be
  the destination of the comamnd. If the destination controls several
  objects, the second part can contain the name of the object.
- One of the command synonyms should be the function name itself.

Examples:

        READ / WRITE
        GET / SET
        ADD / DELETE
        MODIFY / CHANGE / CLEAR
        START / STOP
        ENABLE / DISABLE
        MOVE
        REQUEST
        CONFIG
        ENTER / EXIT
        OPEN / CLOSE
        LOAD / UNLOAD

In case you need the object in the command name, use the three firt
characters of the verb:
		
	REA / WRI			read, write
	GET / SET			get, set
	ADD / DEL  			add, delete 
	MOD / CHA / CLE 		modify, change, clear
	STA / STO			start, stop
	ENA / DIS			enable, disable
	MOV				move
	REQ				request
	CON				configure
	ENT / EXI			enter, exit
	OPE / CLO			open, close
	LOA / UNL			load, unload

	Ex: Move Shutter A Up to position x
	
	Assuming that the final function to execute this action is named
	lcumodMoveShutter, having 3 parameters corresponding to Side (A or B),
	Direction (Up or Down) and a position value, we could create 4 
	commands invoking this same function:
	
	- Main command : 	MOVSH A, Up, x
	- Synonymes: 		MOVSHU A, Up, x
				lcumodMoveShutter A, Up, x 
		

4. Database

The following naming convention is adopted, where xxx stands for the attribute 
name:

	dbSYMADDRESS lcumodDbxxx  for parameter name
	dbDIRADDRESS lcumodDbAxxx for parameter direct address
	
For performance purpose, the access to database shall be done using direct
addressing, unless incompatibility with requirements. 

5. Signals

The following naming convention is adopted, where xxx stands for the signal  
name. It is important to stress that the  hardware names shall be kept 
unchanged if they already existed.

Signals would have suffix i or o related to input/output
	
	dbSYMADDRESS lcumodSxxx  for signal name (better lcumodSixxx)
	ioDIRADDRESS lcumodSAxxx for signal direct address (better lcumodSiAxxx)

For performance purpose, the access to signals shall be done using direct
addressing, unless incompatibility with requirements.

5. Boot files
- bootScript and userScript
- devicesFile in order to receive standard lcc commands

6. Environments
The following files have to be created/updated according to the CCS 
installation manual:

- $VLTROOT/ENVIRONMENTS or $INTROOT/ENVIRONMENTS to define node and servers
- $VLTROOT/config/qsemu.config in order to communicate via qsemu
- $RTAPROOT/etc/RtapEnvList in order to communicate via Rtap
- /etc/services... 


Module "too"
============

Contain tracing and verbose functions, simplified database access functions,
useful macros... and used in a large extent by the template. It shall be 
loaded before loading of "lcumod".


Tools
=====

1. The include files lcumodDatabase.h, lcumodSignals.h, their corresponding
   database structures and the files lcumodDbConfig.c, m2IoConfig.c
   can be generated automatically from respective awk files, according 
   to the updated make file.
   
   Syntax: make awk
   
   See lcumod/src/lcumodDatabase.awk and lcumod/src/lcumodSignals.awk
		
   NOT SUPPORTED.

2. The function tooSetLCUTime() can be added to the boot script to 
   set the LCU time in case xntp is not used.
   
3. The shell script "tooReplace" to replace any pattern by another one from
   a set of source files. It changes the file contents.
   
   Ex: tooReplace lcumod myMod lcumod/include/*.h
       tooReplace lcumod myMod lcumod/CDT/lcumodServer.cdt
   
4. The shell script "tooMvReplace" to replace any pattern by another one from
   a set of source files names. It renames the files.
   
   Ex: tooMvReplace lcumod myMod lcumod/src/*.c

5. Alternatively use the script "cmd" (from lcumod/src). 
   lcumod/src/cmd -rf lcumod "<path>/tooReplace lcumod <mod>" "*"
   lcumod/src/cmd -rf lcumod "<path>/tooReplace LCUMOD <MOD>" "*"	
   lcumod/src/cmd -rf lcumod "<path>/tooMvReplace lcumod <mod>" "*"
   lcumod/src/cmd -rf lcumod "<path>/tooMvReplace LCUMOD <MOD>" "*"

Guide lines
===========
Before changing the template, try to install it as it is.

1. Install the module in your integration area (INTROOT)
2. Set up and configure your boot directory (BOOTROOT/vw/BOOT/<lcuenv>) with
   the utility vccConfigLcu. 
   Observe that the name of your environment can be only 7 characters maximum.
3. Install the template files with the utility lcumodCreateEnv. The
   utility searches first the environment in INTROOT and if not found in
   VLTROOT.
4. Reboot your LCU and try to send commands to lcumodServer

Now remane the tepmplate to your module name and verify the correctness of
the renamed template. It can be done simply by use of "tooReplace" and 
"tooMvReplace" scripts or using the "cmd" script:

1. Copy "lcumod" to new module directory
2. Replace "lcumod" by new module name for all include files/source files and 
   CDT/CIT/ERRORS.
3. Update $VLTROOT or $INTROOT/ENVIRONMENTS, qsemu.config and RtapEnvList
4. Update boot files
5. Boot lcu to verify the load and the readiness of the new Command Server
   (e.g. enter i under VxWorks shell)
6. Verify the communication with other environments
   (e.g. use command "version" from lccei, or SETDB, GETDB...)
...

To extend the template with new functions/commands:

1. Create specific functions
2. Update <module>Interface.c
3. Update CDT/CIT files with new commands
4. Update <module>Errosr.h and <module>_ERRORS
5. Update <module>.c
