Common ATCA driver introduction

The common ATCA driver is responsible for the following:

• Connect to CPSW driver and establish communication with the registers of the firmware common structure and are
  • DaqMux 0 and 1 configurations
  • JESD Top (AMC) 0 and 1
  • Waveform engine
  • Build information
  • Temperature information
  • timing cross bar
• Provide API class, once instantiated using static function, the user is permitted to control the registers and create and read streams

Driver file structure

The files in the driver are as follows

• atcaCommon.h: Contains definition of a base class IATCACommonFw class. 
• atcaCommon.cc: Contains the implementation of new class CATCACommonFwAdapt that implements class IATCACommonFw. This class uses CPSW to establish communication with the DaqMuxes, waveform engines, ADC interfaces (JESD), and firmware information, and provides API functions to write/read to/from the registers.
• crossbarControlYaml.hh: Defines class CrossbarControlYaml. This class uses CPSW to establish communication with the crossbar in hardware. It provides API functions to read and write to crossbar configurations.
• crossbarControlYaml.cc: implements CrossbarControlYaml class

Operation

The common ATCA driver uses the common platform software driver (establishes connections with hardware based on protocols and addresses described in YAML files). The API assumes that the CPSW YAML files were already read and parsed successfully. The API requires a path the denote where all the registers will reside. 

The YAMLs necessary for the correct operation of the common ATCA API are shown as follows

• AppTop.yaml
• AxiSysMonUltraScale.yaml
• AppCore.yaml
• AmcCarrierBsi.yaml
• DaqMuxV2.yaml
• AppTopJesd.yaml
• AmcCarrierCore.yaml
• AxiVersion.yaml
• JesdRx.yaml
• AmcCarrierBsa.yaml
• BsaWaveformEngine.yaml
• AxiStreamDmaRingWrite.yaml

Some of these YAMLs call one another, so the YAMLs that actually contain the registers are just some of them. The paths that are required for the registers are as follows

• AmcCarrierCore/AxiVersion

• AmcCarrierCore/AxiSysMonUltraScale

• AmcCarrierCore/AmcCarrierBsi

• AppTop/AppTopJesd(0/[0])

• AppTop/AppTopJesd(1/[1])

• AppTop/DaqMuxV2[0]

• AppTop/DaqMuxV2[1]

• AmcCarrierCore/AmcCarrierBsa/BsaWaveformEngine[0]/WaveformEngineBuffers

• AmcCarrierCore/AmcCarrierBsa/BsaWaveformEngine[1]/WaveformEngineBuffers

All the registers that will be accessed are in the previously mentioned paths. A summary of the used registers are as follows:

atca Common API class (atcaCommon.cc/hh)

This class is responsible for DaqMux 0 and 1 configurations, JESD Top (AMC) 0 and 1, Waveform engine, Build information, and temperature information. 

API Instantiation

The static function if the parent class ATCACommonFw allows the instantiation of API class. It seems to return an instantiation of the child class as follows:

ATCACommonFw IATCACommonFw::create(Path p)
{
    return IEntryAdapt::check_interface<ATCACommonFwAdapt, DevImpl>(p);
}

The code to instantiate the API is as follows

atcaCommon = IATCACommonFw::create(p_atcaCommon);

Stream instantiation

The stream can be created using the createStream method in the API. Streams can be instantiated separately by calling the CPSW stream creation function directly as follows

    try {
        _stream[0] = IStream::create(p_root->findByName(stream0));
    } 
    catch (InvalidArgError &e) {
        // Don't print error if the stream name is empty, as the user didn't
        // want to create this channel anyway.
    }
    catch (CPSWError &e) {
        fprintf(stderr, "CPSW Error: %s, file: %s, line: %d\n", e.getInfo().c_str(), __FILE__, __LINE__);
    }

YAML string mapping

CrossbarControlYaml API class (crossbarControlYaml.ccc/hh)

This class is responsible for configuring the timing cross bar. The timing cross bar is nothing more than four multiplexers configuring four outputs. The four outputs and the four inputs are as follows:

• 0: NC TPG timing
• 1: Mini TPG
• 2: Back plane
• 3: SC TPG timing

The UML diagram is shown as follows.

The functions available are simply to instantiate a crossbar, and to configure and read current configuration. 

Exception handling

The driver does not throw any exceptions. Nonetheless, CPSW throws CPSWError errors and the driver propagates these exceptions. In these contexts the driver prints to stderr. Upper layers should catch exceptions of type CPSWError.