Contents Previous Next

8. EPICS CVS Repository

8.1. Overview

All development of EPICS core software makes use of a central CVS repository at APS. Remote access to this is possible but is controlled by the requirements of the APS firewall and DoE policies on computer security. The remainder of this chapter assumes that the user has some experience in using CVS.

Licensing and Distribution

Until the question of future EPICS licensing is fully resolved the source code for the core software can only be made available to collaboration members, thus anonymous CVS read access to the whole repository cannot be provided. Anonymous access to the epics/modules directory containing unbundled hardware support packages is possible though, and experiments are being made in providing this facility from the APS web-site. A link to this facility will appear on the APS EPICS home page if the experiments prove successful.

CVSROOT

The EPICS CVS repository is at /net/phoebus/epicsmgr/cvsroot on any of the machines in the APS controls group network. Users must be a member of the Unix group epicsmgr to be able to access the repository using CVS.

8.2. Base

EPICS base is found at epics/base relative to the CVSROOT. Note that base is also defined as the CVS module name for this subdirectory.

Files are tagged with each release, and distributed versions also have a branch created to allow bug fixes to be applied and retrieved without also getting changes that are intended for the next major release. For example the branch with tag epics_R3_13_1_branch is used for all bug fixes to version 3.13.1 but not include modifications being developed for version 3.14 (which should appear only on the main branch until released).

Marty Kraimer <mrk@aps.anl.gov> should usually be consulted before checking in changes to base. Janet B. Anderson <jba@aps.anl.gov> is in charge of the release process.

8.3. Modules

Hardware support code (device and driver support and some specialized record types) is being unbundled from base, and the intention is for 3.14 to not have any hardware-specific code in it. The existing support routines will be packaged up as <supporttop> applications and these will be placed into the epics/modules area of the repository. Responsibility for future maintenance of these modules is being divested from APS where other volunteers can be found, and after unbundling any remaining modules will be left fallow. Sites interested in taking on a such a module are asked to contact Andrew Johnson <anj@aps.anl.gov> about this. The list of modules and Module Owners will be merged into Steve Lewis' List of EPICS Supported Hardware pages in due course.

Module Classifications

The repository structure within epics/modules will reflect the classification of the module concerned. The basic philosophy behind the repository structure is that the location of a particular module is determined by its functionality, not by the connection method needed to control it. Cross-references will obviously be needed from the particular bus involved, but these should be given in the documentation and web-site for the bus, not the repository. Some devices may have more than one method of connection, and in these cases the name of the <supporttop> directory should include the bus used (for example epics/modules/bus/gpib/mpfGpib is the module that supports GPIB communications over MPF). The module categories are as follows:

Bus interface (epics/modules/bus)
This classification is for bus interface and device support software such as GPIB, CAMAC, Bitbus, IPAC and MPF etc. These modules provide the bus interface and generic device support, but not software specific to a particular remote I/O modules which connects to that bus; that software lives in one of the other areas below (unless it's an adapter to a different bus type). It is up to the module owner to decide whether to have a monolithic <supporttop> which might have to contain several drivers for different interfaces to the same bus type, or to split these into a common bus-related module and separate support applications for each interface driver.
PLC interface (epics/modules/plc)
Interfaces that communicate with a PLC using some software protocol are collected here. The precise distinction between plc and bus interface depends whether the device being communicated with is usually end-user programmable or not, thus the Allen-Bradley scanner support appears in the Bus interfaces, but if the the Allen-Bradley PLC-5 interface using the DF-1 serial protocol is ever managed centrally it should be installed here.
Serial interfacing (epics/modules/serial)
Serial is really another example of a bus type, but being pragmatic about it there are so many different interfaces to serial devices it was felt necessary to give them a top-level structure. Distinction between a PLC interface and a Serial one should use the 'is it programmable?' test.
Soft support (epics/modules/soft)
Support applications which don't have associated hardware. The unbundled SNL sequencer will be distributed as a <supporttop> application here, as will the pal record, and the vxWorks statistics and symbol device supports.
Analog I/O (epics/modules/analog)
This classification is for analog and waveform I/O device and driver support. Initially there will be a <supporttop> for each manufacturer, although the module owner may further subdivide this into more <supporttop> applications if desired. These <supporttop>s may have dependencies on one of the Bus interfaces above.
Digital I/O (epics/modules/digital)
Digital I/O device support appears here, including long integers. The same substructure applies as described for Analog I/O.
Motor control (epics/modules/motor)
The stepperMotor record is here, also intended for DC motor controllers etc. A single <supporttop> is provided for each manufacturer containing the device and driver support interface software, to encourage the development of a single driver interface for use by both the stepperMotor and motor record types.
Timing I/O (epics/modules/timing)
Pulse generators, counters, timing and event interfaces belong here. The event distribution system record types are in the common application, and the APS-developed hardware support for these is in aps. The pulseCounter, pulseDelay and pulseTrain records that are specific to the Mizar MZ8310 are with the associated device and driver support in the mizar application.
Instrument I/O (epics/modules/instrument)
Anything that supports a number of related I/O variables or has a complex record type which doesn't obviously fit into one of the other categories may be placed here. Each instrument manufacturer should have their own subdirectory, and the support applications for the individual instruments will exist below that.
Site-specific (epics/modules/site)
Sites that share custom hardware with one or more other labs can place support modules here if they don't fit any of the other categories particularly well. Any substructure should be decided by the lab concerned.

Additional categories or sub-divisions can be added if they prove necessary. For example some of the client extension programs could be converted to using the makeBaseApp structure, and it would be appropriate to give them in a suitable classification in this area rather than the existing monolithic epics/extensions area.

The above path names may seem to result in a very broad tree, putting only a very small number of devices/drivers in each <supporttop> application. This is deliberate, as at most sites an individual <ioctop> application will usually only need a reasonably small number of device types. Experience at APS has shown that bundling too much support code into a single application produces a software maintenance nightmare further down the line, and this is one reason why we are unbundling the hardware support. A broad tree should not add significantly to the tasks an application developer needs to perform, and EPICS site managers can help by including the necessary additional lines (commented out as desired) in the config/RELEASE file of the local makeBaseApp templates.

When installing packages for use by applications, we recommend that the same relative path name be used as given above, but the particular version of the module will need to be given a name which reflects the particular module version. At APS the release number (such as 2-1) is used as the last component of the path name to the module, so that for example the Allen Bradley Scanner <supporttop> might be installed at /usr/local/iocapps/R3.14.0/bus/allenBradley/2-1. This makes it possible to install a new version of a <supporttop> application at any time but still ensure that only the application engineer in charge of a particular IOC can decide when to switch to using the new version. The APS Procedures section of this document describes this approach, although it does not use the classification structure described here as it was developed for earlier releases of EPICS.

The preferred method of distributing modules is to provide a tar file for each release, accessed through the module's web-site or ftp server. Module owners are also encouraged to read the Linux Software Release Practice HOWTO document which gives good advice on release procedures.

Any hardware record, device or driver support which was provided with release 3.13.1 of EPICS base but which is missing from the above list will be deleted. Should you need any such software you should check on Steve Lewis' Supported Hardware web page and approach the current maintainer directly, or ask on tech-talk. As a last resort you can always obtain the source code from release 3.13.1 and create your own support application for it.

8.4. Module Owner Responsibilities

A significant part of the work of a Module Owner (MO) is to maintain the code, fixing reported bugs or merging bug fixes from other users. However equally important or even more vital are the tasks associated with creating and maintaining documentation so the module can be used, and with packaging up releases and making the software easily available to other EPICS sites. It may be appropriate for some modules to divide the work between several people, some of whom might not be software developers (web-site maintenance for example).

Documentation

One of the first jobs should be to develop a web-site for the module. Eventually this should contain:

Ideally copies of the documentation should be distributed with the software, but at the very least there should be a README file present which gives the URL for the module's web-site and the name of the Module Owner.

A template module web-page has been developed (using Netscape Composer, although any HTML editor can be used) which MOs may start from if they so wish. This will obviously need to be modified to suit particular circumstances by changing or removing parts as necessary (search for underscore characters in the HTML file to find all the parts that will need replacing). If you develop your own site, please try to ensure that all the above information can be accessed by the users somehow, although it does not have to be all on one page.

If you do not have access to a web-server or would prefer to maintain the web-site at a central location, APS will make an area of its web-site available to nominated MOs for module use. Requests for web-space and an account on the APS server should be made to Bill McDowell.

Distribution

The recommended method is to provide a tar file for each documented release of the <supporttop>, accessible via the module's web-site or an ftp server. This is pretty much an industry-standard approach for obtaining software, and as long as there are no copyright problems in making the software available on a public server it should be the preferred method.

Unless there are particular reasons not to do so, try and keep older versions of the software available. This particularly applies where a particular version of EPICS base is required. MOs may be called upon to incorporate bug fixes into old module versions and generate new releases of these after an upgrade of EPICS base has required a significant change to the software. The release version number should indicate the relevant parentage.

We are looking at the possibility of providing a mirrored copy of the CVS repository outside the APS firewall, providing anonymous read-only access. This should make it easier for sites to obtain and install upgrades without compromising security for the code-base. Until the legal copyright issue has been resolved this would only serve the $CVSROOT/epics/modules area.

Development

As changes occur to EPICS base, modifications may be needed to the <supporttop> applications to remain compatible with the new versions. The changes needed and any tools to help with this will be published by the base developers as soon as these have been confirmed, and any modifications thought to require significant effort should have been discussed on tech-talk or other forum beforehand. The MO will be responsible for ensuring that the required changes are applied and tested, and a new release created.

Delegation

There may be several developers in the EPICS consortium with an interest in a particular module, and the MO is at liberty to distribute the workload associated with maintaining the module as she/he sees fit. Overall responsibility for the software and final authority for what should or should not be included in it will remain with the MO however.


Contents Previous Next