LCLS
SLC-Aware IOC
Magnet Facililty Design


Contact:  Kristi Luchini
Last Updated:  September 22, 2005

Table of Contents

1 Introduction
2 Magnet Handler Thread
3 Magnet Initialization
4 Magnet Message Processing
5 Magnet Diagnostics
6 Magnet Databases
7 Magnet Displays
8 References
8.1 Magnet Functional Specification
8.2 Message Service Design
8.3 Database Service Design
8.4 EPICS Database Naming Conventions
8.5 EPICS Database Standards
8.6 magLib




1  Introduction
The magnet service of the SLC-Aware IOC provides magnet  power supply control and monitoring by acting as a message pass-through service from the SLC Control System to the EPICS Control System and visa-versa.

The magnet service is comprised of two SLC-aware threads (SLC Aware Magnet Facility) and a set of EPICS database records (EPICS Magnet Facility).  The EPICS database records are comprised of both hardware and software records such that the hardware records interface to EPICS device and driver support. This driver and device suport  communicates to  hardware that controls and monitor the magnet power supply.  The SLC-aware threads act as a message pass-through to allow the SLC Control System to request beam synchronous measurements. The data can be returned to the SLC control system via the SLC-aware threads, and is also available through EPICS Channel Access to any EPICS client.

The types of magnets that will be controlled and monitored are correctors, quadrupoles, dipoles, solenoids and pulsed supplies.

The SLC-Aware magnet service communicates with the SLC Control System the Message Service interface. Request messages are received from the Message Service in the mgntHdlr message queue and reply messages are sent to the Message Service to be forwarded to the SLC Control System. 
The magnet service uses the Database Service to access information stored in the SLC Database concerning the acquisition devices. In addition EPICS database access services are used to retrieve data from EPICS PV so that the SLC and EPICS database will be synced.




2  Magnet Handler
The magnet handler thread, mgntHdlrThread() is the main magnet task that  is started at  IOC boot by the SLC Executive Thread, slcExecThread(), at IOC initialization. The purpose of the magnet thread is to process incoming magnet messages that are generated locally or are sent from a standalone process on the Alpha, such as the SCP or Paranoia for example.

Source File:  mgntHdlr.c
Protype File: mgntHdlr.h

mgntHdlrThread   - Processes incoming messages from the SLC Control System
mgntHdlrCleanup - The function is called to clean up any allocated memory before exiting the magnet handler thread.

void mgntHdlrThread(void);
int    mgntHdlrCleanup(void);

3  Magnet Initialization

Souce File: mgntInit.c
Prototype Header File:  mgntInit.h

mgntInit  - Magnet initialization
vmsstat_t mgntInit( const * mgntInfo_ts *mgnt_ps );

mgntInitExit - Free dblists and message queues
vmsstat_t  mgntInitExit(void );

mgntInitDbGetUnit - Get  magnet database unit information for the specified primary
static vmsstat_t mgntInitDbGetUnits(const char             * const prim_a,
                                                       const char              *          unit_a,
                                                       const unsigned long *         nunits_p );

mgntInitMsgQ - Create message queues for each magnet function
static vmsstat_t mgntInitMsgQ(void);

mgntInitEpicsPv - Create mapping between SLC database prim,micro, unit and corresponding list of EPICS PV's.
static vmsstat_t  mgntInitEpicsPv( const char     * const prim_a,
                                                    const char     * const unit_a,
                                                    const char    *  const    secn_list,
                                                    unsigned long                nsecn,
                                                    const   * ...                   pvAddr_p);

4  Magnet Message Processing

Souce File: msgQUtil.c
Prototype Header File:  msgQUtil.h

msgQMsgProcess - the purpose of this function is to process a function based on the function code provided.  All functions have the same calling arguments. The reply message is issued for those functions that  expect one.
vmsstat_t msgQMsgProcess(scpThread_te                       thread_e,
                                                 unsigned long                        nr_func,
                                                 const slcScpFunc_ts * const scp_func_as,
                                                 const void                  *          rMsg_p,
                                                 const void                  *          sMsg_p );      
Souce File: mgntCal.c,mgntCheck.c,mgntDaoc.c,mgntIactToBact.c,mgntPtrb.c,mgntStdz.c,mgntTouchup.c,mgntTrim.c,mgntZero.c
Prototype Header File:  mgntFunc.hc
   
mgntCal - Magnet calibration function

vmsstat_t mgntCal( const int           *nbytes_p,
                              const void const *rMsg_p,
                              const  void          *smsg_p );

mgntCheck - Read all magnet adc's
vmsstat_t mgntCheck( const int           *nbytes_p,
                              const void const *rMsg_p,
                              const  void          *smsg_p );
mgntDaoc - Dumb analog out control
vmsstat_t mgntDaoc( const int           *nbytes_p,
                              const void const *rMsg_p,
                              const  void          *smsg_p );

mgntIactToBact - Set the acutal current to the actual B-field.
vmsstat_t mgntIactToBact( const int    *nbytes_p,
                                        const void const *rMsg_p,
                                        const  void          *smsg_p );

mgntPtrb - Set a magnet and don't bother to check the readback to be within tolarance.
vmsstat_t mgntPtrb( const int           *nbytes_p,
                              const void const *rMsg_p,
                              const  void          *smsg_p );

mgntStdz - Magnet standardization
vmsstat_t mgntStdz( const int           *nbytes_p,
                              const void const *rMsg_p,
                              const  void          *smsg_p );
mgnt - Read all magnet adc's
vmsstat_t mgntCheck( const int           *nbytes_p,
                              const void const *rMsg_p,
                              const  void          *smsg_p );
mgntTouchUp - Touch up dac if adc is not within tolerance
vmsstat_t mgntTouchup( const int           *nbytes_p,
                                      const void const *rMsg_p,
                                      const  void          *smsg_p );

mgntTrim - Trim magnet to desired b-field
vmsstat_t mgntTrim( const int           *nbytes_p,
                               const void const *rMsg_p,
                               const  void          *smsg_p );

mgntZero- Zero magnet
vmsstat_t mgntTrim( const int           *nbytes_p,
                               const void const *rMsg_p,
                               const  void          *smsg_p );
                 
5 Magnet Diagnostics

6 Magnet Database

7 Magnet Displays