1. 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
BE-BI-TB

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

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

4. 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
BE-BI-TB

5. 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
BE-BI-TB

6. 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
BE-BI-TB

7. 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
BE-BI-TB

8. 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
BE-BI-TB

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

10. 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
BE-BI-TB

11. 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.
BE-BI-TB

12. 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?
BE-BI-TB

13. 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
BE-BI-TB

14. 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
BE-BI-TB

15. 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.
BE-BI-TB

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

17. 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.
BE-BI-TB

18. 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
BE-BI-TB

19. 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.
BE-BI-TB

20. 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
BE-BI-TB

21. 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
BE-BI-TB

22. Thank you for your attention!
Links:
BE-BI-TB