Marty's Issues and Notes of EPICS V4 Development

Documentation Standards

What is the difference between documentation of a software component of EPICS V4, and its specification. Will there be a difference?

What are the documentation standards?

There already are several separate mercurial projects. Will each keep it's own set of documentation?

We have a combination of Java, C++, and Python. Java and Pythgon each have documentation standards. As far as I know C++ does not.

For java pvDataJava, etc use the eclipse javadoc generator to produce html documentation. I think channelFinder and pvManager both use maven to produce the documentation. What will be the standard? What are the standards for project and package overviews?

What about documentation guidelines for C++?

Licensing

What is the status?

Source files carry license, or refer to a license? This goes with documentation stndards above.

GW: Suggest all source carries a standard header but that it is functional - it describes the file, authorship and modifications their authors and dates. It only should refer to a license page elsewhere.

Release Naming and Project Dependences

There are already quite a few separate projects. If each service is a separate project there will be even more. This compatiblity problems must be addressed.

There seems to be agreement on the following

  1. Releases will be named x.y.z. First release of pvDayta, etc will be named 1.0.0
  2. x will be incremented when and only when the network protocol changes
  3. When x changes all projects that communicate with each other must have a new release.

MK: But what about y and z? There are at least two issues.

introspection changes
If two services communicate and the introspection interface for data passed between them changes they may require new releases
multiple projects within a single process
If the projects both use a common jar (Java) or shared library (C++) then the projects must share the same release of the jar or shared library

GW: Suggest major, minor, dot. MAJOR is not forward compatible, minor is not backward compatible. Don't make it depedent on network protocol specifically, nor introspection specifically. There will be anumber of things in each class.

PVAccess protocol

MK: Is it ready to be declared normative document?

GW: Is it ready to be published as a FPWD - we voted yes. Is it normative? - The way I use "Normative" indicates intention more than readiness. A standard is normative if you intend it to be. Normative means basically a formal spec. If we say a pvData "is" normative - we are making a statement about the documentation, openness, and formality of its specification.

Use Cases

To help motivate the next sections lets consider some use cases. Others (GW, GS, BD) should suggest some. E.g.

For each use case discuss:

what client gets
What is presented on a OPI screen or what is given to an archive service.
data sources
What is real time data from IOCS. What comes from database. What control messages have to be passed to IOCs
services
What are the actual services.

Aida architecture

Topics include:

What is a service
Is it a process or a thread or a combination of both?
How many services?
Just rough estimate. Is the number still growing?
Where are services located
Is each service network addressable? If yes it it via corba or WEB services or both or others?
How is data transfered between services
If corba is it via IDLs or "corba any" or a combination? If within a process then how? If " corba any" how does service introspect?

pvServices architecture

Uses cases for services

Need to make everyone clear on the use cases of services, which motivates then the architecture.

To make this managable first consider services based on magnets and bpms.

Some topics are:

sources of data
What does an IOC provide? What does a database provide? What do other services provide?
what is being serviced?
An entire machine like a storage ring is one example. A local bump is another
magnet related services
What is a complete set?
bpm related services
What is a complete set?
What is generic and what is site specific
Some things must have knowledge of specific machine. But what?

Other services to discuss?

How is data made network available. We already have a combination of WEB services, caV3 and pvAccess. Is this it?

Source code organization in pvService

Presently both the core "support for" services, ie org.epics.pvService.rpc, and essentially prototype frameworks for services, and services themeselves, are all 3 in org.epics.pvService! Need to spearate core, from frameworks, from services.

Data Types and pvManager

A suggestion was made that standard types be provided as pvManager types.

What does this mean?

Take VDouble for example.

Is this what defines VDouble?

    public interface VDouble extends Scalar<Double>, Alarm, Time, Display {}
    ...
    public interface Scalar<T> {
        T getValue();
    }
    public interface Alarm {
        AlarmSeverity getAlarmSeverity();
        AlarmStatus getAlarmStatus()
    }
    ....

Or is VDouble defined via metadata syntax?

    structure VDouble
        double value
        alarm alarm
        timeStamp timeStamp
        display display

GW: Alarm and timestamp are controls ideas, they have no place in defining any kind of double used at a high level, any more than theweb service your bank offers encodes timestamp and alarm when it sends you the amounts of transactions.

And why would standard types be defined in terms of pvManager anyway? Surely it's pvManager's job to understand the normative aggregate types and normative functional types, not the other way around.

Five basic data types which come from the epicsV3 DBR types are enum, timeStamp, alarm, display, and control. Both pvManager and pvData (called properties) provide alternate ways to package what is in the DBR types defined in EPICS V3. But they do it in different ways.

What other standard data types will the charter define?

It looks like are least statistics, table, and image.

What about others?

GW: I think we need to define a taxonomy: type (Field, PVField), display "V", aggregate type (table, multi-channel array, possibly image data too). Those would be nomative. On top of the normative types we might also suggest non-normative functional types: archive data retrival record, bpm orbit data, Twiss Parameters, Transfer Matrix, etc