Application Programmer’s Guide to the Plasma Control System (preliminary draft) John Ferron, Mike Walker, Ben Penaflor, Bob Johnson General Atomics February 28, 2011 Contents 1 Introduction 1 2 Background information for application code authors 3 2.1 PCS overview ................................... 3 2.2 Model for the control system operation ..................... 4 2.3 Feedback control overview ............................ 5 2.4 Organization of applications ........................... 6 2.5 Data structures in the real time process ..................... 7 2.5.1 The target and pointer target vectors .................. 11 2.5.2 The function vector ............................ 12 2.5.3 Parameter data .............................. 13 2.5.4 Scratch memory introduction ...................... 13 2.5.5 Global and static variables on the real time processor ......... 14 2.5.6 Allocation of space in the real time data structures .......... 15 2.6 Pre-shot setup and post-shot cleanup ...................... 16 2.7 Archival of the PCS response .......................... 19 2.8 PCS timing .................................... 21 2.9 Using multiple real time processors in parallel ................. 22 2.9.1 Task and data distribution ........................ 23 2.9.2 Communication between real time processors .............. 24 2.9.3 The interprocessor communication functions .............. 26 2.9.4 Real time message facility ........................ 27 2.9.5 Resource contention ........................... 29 2.10 Data processing and storage in the waveform server .............. 30 2.10.1 Raw operator data ............................ 31 2.10.1.1 Waveforms ........................... 31 2.10.1.2 Static data items ........................ 32 2.10.2 Processed data .............................. 35 2.10.3 Generating vector indices ......................... 36 2.10.4 Generating data entry numbers ..................... 38 2.10.5 The alg vectors routine .......................... 39 i DRAFT DRAFT DRAFT DRAFT ii 2.10.6 External data items ............................ 42 2.10.7 Storage of processed data in the waveform server ........... 43 2.10.7.1 Parameter data storage .................... 43 2.10.7.2 Vector element time evolution storage ............ 44 2.10.8 Producing target vector data from waveform vertices ......... 45 2.10.9 The alg vertices routine ......................... 49 2.10.10 Global and static variables in the waveform server ........... 49 2.11 Parameter data .................................. 50 2.11.1 Uses for parameter data ......................... 50 2.11.2 Raw and processed parameter data ................... 51 2.11.3 Quick start outlines for parameter data ................. 51 2.11.3.1 Outline for parameter data block usage 1 ........... 51 2.11.3.2 Outline for parameter data block usage 2 ........... 53 2.11.3.3 Outline for parameter data block usages 3 and 4 ...... 53 2.11.4 Parameter data in the waveform server ................. 53 2.11.4.1 Initializing parameter data ................... 54 2.11.4.2 Creating parameter data blocks ................ 55 2.11.4.3 The parameter data block name ................ 57 2.11.4.4 Parameter data block options ................. 57 2.11.4.5 The parameter data block descriptor ............. 59 2.11.4.6 Specifying the alignment of a parameter data block ..... 68 2.11.4.7 Parameter block storage order ................. 69 2.11.4.8 Sharing a parameter data block ................ 69 2.11.4.9 Retrieving parameter block data ............... 71 2.11.4.10 Replacing parameter block data ................ 72 2.11.5 Parameter data copy routines ...................... 73 2.11.5.1 Data to be archived ...................... 74 2.11.5.2 Restoring data ......................... 74 2.11.5.3 Maintaining backward compatibility ............. 75 2.11.5.4 For the real time CPU ..................... 77 2.11.5.5 For the user interface ...................... 77 2.11.5.6 From the user interface ..................... 78 2.11.5.7 Parameter data size routine .................. 78 2.11.6 Data computation routine ........................ 78 2.11.7 Accessing parameter data in real time .................. 79 2.11.7.1 Parameter block pointer array ................. 79 2.11.7.2 Parameter data pointers in the pointer target vector .... 83 2.11.8 The parameter data editor in the user interface ............ 85 2.11.8.1 Calling format ......................... 85 2.11.8.2 Using the standard display library procedures ........ 86 2.11.8.3 staticdata editor init procedure ................ 88 DRAFT DRAFT DRAFT DRAFT iii 2.11.8.4 staticdata editor load defaults procedure ........... 88 2.11.8.5 staticdata editor load procedure ................ 89 2.11.8.6 staticdata editor update procedure .............. 89 2.11.8.7 staticdata editor example ................... 89 2.11.8.8 display init procedure ..................... 93 2.11.8.9 Obtaining the parameter data ................. 94 2.11.8.10 Editor interface standards ................... 95 2.11.8.11 Returning the updated parameter data ............ 97 2.11.8.12 Adding the editor code to the user interface ......... 97 2.11.8.13 generic editor .......................... 98 2.11.8.14 matrix editor .......................... 99 2.11.9 Parameter data examples ......................... 99 2.11.10 Scratch parameter blocks ......................... 99 2.12 Standard static data types ............................ 100 2.12.1 Automatic restoration of standard static data types .......... 101 2.13 Changing default attributes of waveforms - special cases ........... 102 2.14 Communicating with the user .......................... 104 2.14.1 Raw data problem list .......................... 104 2.14.2 Log messages ............................... 107 2.14.3 Debug printouts .............................. 108 2.15 Using phase sequences .............................. 108 2.15.1 Forcing a phase sequence change .................... 109 2.16 Useful index macros ............................... 111 2.16.1 Category indices ............................. 111 2.16.2 Phase sequence indices .......................... 112 2.16.3 Processor indices ............................. 112 2.16.4 Algorithm indices ............................. 112 2.17 Regulating the PCS setup ............................ 113 2.17.1 Establishing default setup data ..................... 114 2.17.2 The access control mask ......................... 115 2.17.3 Inhibiting restore of data ......................... 115 2.17.3.1 The setup restore procedure .................. 116 2.17.3.2 Initializing data during a setup restore ............ 118 2.17.4 Parameter data block external files ................... 119 2.18 PCS directories .................................. 121 3 Algorithm Specification and Documentation 124 4 The control algorithm code 126 4.1 Introduction .................................... 126 4.2 Configuration definitions ............................. 127 DRAFT DRAFT DRAFT DRAFT iv 4.3 Symbol definitions ................................ 127 4.4 Fast data save code definitions .......................... 128 4.5 Waveform server global variables ........................ 128 4.6 The algorithm descriptors ............................ 131 4.6.1 The waveform server structure ...................... 132 4.6.2 The host process structure ........................ 137 4.6.3 The real time code structure ....................... 140 4.7 Data item descriptors ............................... 143 4.8 External data item descriptors .......................... 148 4.9 Name changes ................................... 150 4.10 Waveform server function prototypes ...................... 152 4.11 Functions for the waveform server ........................ 152 4.12 Function prototypes for host cpu process code ................. 153 4.13 Functions for the real time host process ..................... 153 4.14 Function prototypes for the real time code ................... 154 4.15 The real time code ................................ 155 4.16 How master files are combined .......................... 156 4.16.1 categories.h ................................ 157 4.16.2 controldefs.h ................................ 158 4.16.3 The partial array of structures ...................... 159 4.16.4 control.h .................................. 161 4.16.5 wavemain.c ................................ 163 4.16.6 hostmain.c ................................. 164 4.16.7 realmain.c ................................. 168 5 Support for PID calculations 172 5.0.1 Example of pidv4 code segments .................... 173 5.0.2 Using pidv3 code segments ....................... 177 5.0.3 Using old pid lookup tables ....................... 178 6 Periodic actions and raw data actions 181 6.1 Periodic actions .................................. 181 6.2 Raw data actions ................................. 183 7 The user interface 185 7.1 The view log .................................... 185 7.2 The ”next shot” option .............................. 186 7.3 The ”future shot” option ............................. 186 7.4 The ”shared shot” option ............................. 187 7.5 The waveform editor ............................... 187 7.5.1 Menu options ............................... 187 DRAFT DRAFT DRAFT DRAFT v 7.5.1.1 File menu ............................ 187 7.5.1.2 Show menu ........................... 188 7.5.1.3 Category menu ......................... 188 7.5.1.4 Phase menu ........................... 188 7.5.1.5 Defaults menu ......................... 189 7.5.1.6 Edit menu ...........................