Cheburashka and Gena Tools for memory map management and HDL, driver and FESA class generation Bartosz Bielawski BE-RF-CS Anthony Rey, Tom Levens Andrey Pashnin, Bruno Kremel, Michael Jaussi, John Molendijk, Miguel Ojeda Sandonis, Greg Hagmann, Bartosz Bielawski, Andy Butterworth, Przemysław Plutecki, Frederic Dubouchet and many others from BE-RF-FB and BE-RF-CS 02.11.2017 BE-BI-TB

Outline Original motivation: (in)consistency between firmware & FE software Memory map definition (Cheburashka) HDL generation (Gena) Upgrade plans Intergroup collaboration 02.11.2017 BE-BI-TB

Seen by the LLRF designer: VME bus VHDL register declarations Memory map 02.11.2017 BE-BI-TB

Seen by the software developer: LSA/InCA, MATLAB… LabVIEW, Python… CMW Java client API CMW C++ client API Controls MiddleWare (CMW) Device/property interface Linux Front End Computer (FEC) CMW server API Server task FESA class (generated + device-specific user code) Data store Real-time task Real-time task accesses the HW via the device driver, synchronized to the accelerator timing system. It accesses the data store which is MULTIPLEXED in order to handle multi-cycling machines where you may have a different setting for each cycle. The server task allows clients to access the data store and/or the hardware. Driver (generated by Encore tool) Device access library Device driver VME bus VME board VME board 02.11.2017 BE-BI-TB

Device drivers (pre-2013) Excel file Hardware Database Entered by hand Encore Driver generation tool Device driver is installed on the front end computer and the user code (FESA class) is compiled against the library and header. So far so good, with an obvious caveat. Must match driver and HW Compilation of FESA class libmydevice.a Device access library libmydevice.h Device driver 02.11.2017 BE-BI-TB

Mismatches possible Mismatch between compiled user code and driver: Error in deploying driver Installed new driver, FESA class not correctly redelivered FESA class Device access library Mismatch between firmware and driver: Error in Excel file or while manually entering memory map in database Flashed new firmware, forgot to redeliver driver and rebuild software Device driver VME bus VME board Both cases result in access to wrong registers and unpredictable behaviour 02.11.2017 BE-BI-TB

Solution Master memory map description in XML file mydevice.xml Master memory map description in XML file Generate driver configuration file and VHDL from same master file driver configuration VHDL memory map Encore libmydevice.a libmydevice.h FPGA firmware Keep driver, software and firmware in sync 02.11.2017 BE-BI-TB

Memory map editor A. Rey Enter attributes: name, size, width, read/write… Edit register and memory map Memory map tree browser. Typical functionalities of tree browser: Can add/delete/clone/expand/move up/down etc. nodes in the tree. Attributes: in this case of the whole memory map. Nodes: register or memory nodes, table shows for each node in the tree the data width and calculated address. Once the memory map is entered it is saved as an XML file. There are buttons to validate it and generate VHDL and driver configuration. Validate Generate VHDL Generate driver Automatic address calculation and alignment 02.11.2017 BE-BI-TB

Documentation Web pages Web documentation generated from XML via XSLT 02.11.2017 BE-BI-TB

Register block reuse Certain register blocks occur in many designs acquisition memories, function generators… Can be saved as sub-maps in separate XML files and included in memory map C++ libraries written for complex functionalities e.g. acquisition memory buffers 02.11.2017 BE-BI-TB

Sub-maps Submap Functionalities/register blocks which are used in many different modules can be reused by defining them as submaps which can be included in other memory maps. Can use all the same features as top-level memory maps. 02.11.2017 BE-BI-TB

FESA class generation HW designers: Lots of tedious coding in FESA C++ want access to every functionality of the board (whole register map) want it yesterday reserve the right to change the register map whenever they want Lots of tedious coding in FESA C++ We have the memory map description; why not generate the FESA code as well? 02.11.2017 BE-BI-TB

FESA class generation my_device.xml driver configuration FESA class design file & C++ source libmy_device.a libmy_device.h HW designers like to have access to every single register. This means a lot of tedious coding. Since we already have the memory map description, why not generate a FESA class as well? Lots of additional information needed for this: semantic information about each register. FESA class for testing Generate design file and C++ source for FESA class Meant for testing: exposes registers as FESA device properties 02.11.2017 BE-BI-TB

FESA class generation Simple access to registers is not enough Need to know the semantics of the register numeric type or bit field composed of sub-registers? conversion factors/algorithms 02.11.2017 BE-BI-TB

Register semantics Sub-registers Bit-field A register can be divided into sub-registers with their own bit ranges: here 15 downto 8, 7 downto 0. 02.11.2017 BE-BI-TB

Register semantics Code-field (enum) Register or sub-register can be defined as a code-field or enumeration with attributed values. 02.11.2017 BE-BI-TB

Other FESA class functionality Additional features added to support FESA class functionality: Virtual registers: only exist in FESA class Alarm generation for fault bits Multiplexed data store and RT code for PPM classes … Allows to have a fully working FESA class generated automatically (for commissioning purposes). Represents a substantial time saving for SW developers. 02.11.2017 BE-BI-TB

Further HDL generation The main tool (Cheburashka) generates only the VHDL register declarations A companion tool Gena has been developed which can generate a complete register block. It can be launched directly form the Cheburashka application. The companion tool Gena can be launched to generate the full VHDL register block 02.11.2017 BE-BI-TB

Gena Generates large amount of HDL previously done by hand. T. Levens Python script which reads master XML memory map file Produces VHDL code for the entire register control block Supports all standard register types (R/W/RW/RMW). Registers are auto-split into bits/sub-registers if these are defined. Supports multiple memories, each with own data and strobe inputs. Supports multiple “areas” of registers, each gets its own multiplexer set. Memory maps are also used in the firmware to connect to DSP AMI bus, I2C etc. Generates large amount of HDL previously done by hand. Represents a substantial time saving for firmware developers. 02.11.2017 BE-BI-TB

Upgrade plans P. Plutecki Since September 2017 BE-RF-CS has a Fellow dedicated to development of Cheburashka. Creation of supporting code and configuration of infrastructure: Moving code to Gitlab, Continuous Integration if possible, Extra code to allow plugin based architecture, Upgrade of PyCheb: Merging all the versions, Making it work with Python3, Generation of Python direct access package for testing on FECs C++ Code generation: Moving code generation to an external plugin and making use of Jinja2 templating engine, Template creation based on hand-written code, Has to follow the evolution of the FESA framework, Better encapsulation: structure using libraries rather than FESA actions. GUI: Evolution of current Java application 02.11.2017 BE-BI-TB

Intergroup collaboration Informal discussions between RF, BI and CO suggest there is an interest in looking for a common solution: GUI for memory map editing Agree on standard for memory map format Backends for HDL, drivers, FESA classes… This is a good moment to look at our requirements and the feasibility of a common approach 02.11.2017 BE-BI-TB

Thank you for your attention! Links: https://wikis.cern.ch/display/BERF/Cheburashka+Documentation http://accelconf.web.cern.ch/AccelConf/ICALEPCS2013/papers/tuppc116.pdf 02.11.2017 BE-BI-TB