Debugging EPICS Applications For Beginners
- EPICS Documentation on WWW at APS
http://epics.aps.anl.gov/asd/controls
- Applications Developer's Guide
Particularly -- Chapter 2. -- IOC Test Facilities
-
Record Reference Manual
- VxWorks Programmer's Manual
Particularly:
- Chapter 2 -- Getting Started
- Chapter 12 -- Debugging
- Chapter 11 -- The Shell
- Your new application:
"It's never worked and it's never going to work!"
- Your existing application:
"It worked yesterday and I didn't change a thing!"
- Someone else's application:
"It's not my application! How should I know why it doesn't work?"
- Use working applications as templates.
- Make small changes and try them out.
- Try out subroutines from the vxWorks shell.
Subroutine Records and sequences should call
subroutines that can be called easily from the
vxWorks shell.
- If it works save it!
- Save whole application directories with
tar
.
cd <application directory>
tar -cvf <filename> .
(. means you will also include invisible files from your current directory)
- Example:
cd ~training/et1
tar -cvf /local_temp/et1.tar .
tar
saves symbolic links unless special flags are used.
- Don't use
cp
to copy application directories
or you will copy most of EPICS.
- Log onto the IOC or tip hardwire to it.
- Type:
bootChange
and enough carriage returns to get all the boot parameters on the screen.
- Copy the text to a file on the Sun. You can do this from a
cmdtool
on the Sun by:
- Clicking with the left mouse button on the first letter of the text.
- Clicking with the middle button on the last.
- Hit the copy key (3rd from bottom on left key pad).
- Open a text file and hit the paste key.
'.mv167> bootChange
'.' = clear field; '-' = go to previous field; ^D = quit
boot device : ei
processor number : 0
host name : leia
file name : ~wright/vx/v51.epics/config/mv167/vxWorks
inet on ethernet (e) : 189.165.32.83:ffffff00
inet on backplane (b):
host inet (h) : 189.165.32.26
gateway inet (g) :
user (u) : vx
ftp password (pw) (blank = use rsh): xxxxxxx
flags (f) : 0x29
target name (tn) : vxmv156733a
startup script (s) : ~wright/camac_demo/camac/startup.mv167
other (o) :
- The injector arcs and the boot parameters disappear.
- Someone else is sharing your IOC and the parameters get changed.
- You change the parameters yourself and put in some strange characters.
- You can cut and paste from a saved file into the boot parameters.
- You don't have a serial connection and you've forgotten the network address.
i
-- lists processes running
spy
-- statistics about task execution (spyStop
- to stop)
checkStack
-- statistics on stack usage for every task
memShow
-- memory usage on the system
tt <task name or id>
-- task trace -- works with suspended tasks
td <task name or id>
-- task delete
lkup "<string>"
-- prints all symbol table elements containing <string>
help
-- lists useful commands with examples
dbgHelp
-- help with debugging. break points etc.
lkup "Help"
-- will list all help routines.
sp <routine name>, <parameter>,...,<parameter>
-- spawns a task with default stack and priority. You must use this if your routine calls channel access or you want to use the break point facilities.
<script name>
-- runs the vxWorks script (located
in the UNIX working directory) on the IOC.
<vxWorks command> <UNIX file name>
-- Puts output from vxWorks Command into the UNIX file.
copy "<UNIX file name>"
-- prints UNIX file contents to standard output on the IOC.
Examples
i
(with EPICS running)
NAME ENTRY TID PRI STATUS PC SP ERRNO DELAY
---------- ------------ -------- --- ---------- -------- -------- ------- -----
tExcTask _excTask 3dc2f4 0 PEND 5a83c 3dc25c 3006b 0
tLogTask _logTask 3d99f4 0 PEND 5a83c 3d9958 0 0
tShell _shell 3a85f4 1 READY 46f08 3a82d0 3d0001 0
tRlogind _rlogind 3b72dc 2 PEND a2a0 3b70e0 0 0
tTelnetd _telnetd 3b5438 2 PEND a2a0 3b5368 0 0
tRdbTask _rdbTask 3b2a08 20 PEND a2a0 3b28e8 d0003 0
timeStamp _gts_select 2b9570 32 PEND a2a0 2b9414 0 0
callback _callbackTas 2bd2cc 40 PEND a2a0 2bd284 0 0
scanEvent 30da20 299184 41 PEND a2a0 29913c 0 0
gpibLink 2c99b2 2bb5e4 47 PEND a2a0 2bb590 0 0
tNetTask _netTask 3d5668 50 PEND a2a0 3d5610 0 0
scanPeriod 30d676 29ba44 53 DELAY 46772 29b9f8 0 4
CA client _camsgtask 2ad814 180 PEND a2a0 2ad71c 0 0
CA repeater_ca_repeater 38439c 181 PEND a2a0 384250 0 0
CA TCP _req_server 2b5a28 181 PEND a2a0 2b598c 0 0
CA event _event_task 27f7c0 181 PEND a2a0 27f778 0 0
CA event _event_task 33ce64 181 PEND a2a0 33ce1c 0 0
CA UDP _cast_server 2b44b0 182 PEND a2a0 2b4384 0 0
CA online _rsrv_online 2b2f24 183 DELAY 46772 2b2e88 0 283
taskwd 31a368 2c4500 200 DELAY 46772 2c444c 0 241
value = 0 = 0x0
i
(Without EPICS running)
NAME ENTRY TID PRI STATUS PC SP ERRNO DELAY
---------- ------------ -------- --- ---------- -------- -------- ------- -----
tExcTask _excTask 3dc2f4 0 PEND 5a83c 3dc25c 0 0
tLogTask _logTask 3d99f4 0 PEND 5a83c 3d9958 0 0
tShell _shell 3a8834 1 READY 46f08 3a8510 0 0
tRlogind _rlogind 3b72dc 2 PEND a2a0 3b70e0 0 0
tTelnetd _telnetd 3b5438 2 PEND a2a0 3b5368 0 0
tRdbTask _rdbTask 3b2a08 20 PEND a2a0 3b28e8 d0003 0
tNetTask _netTask 3d5668 50 PEND a2a0 3d5610 0 0
tFtpdTask _ftpdTask 3b0550 55 PEND a2a0 3b0494 0 0
tPortmapd _portmapd 3b3f20 100 PEND a2a0 3b3dec 16 0
value = 0 = 0x0
- The startup file doesn't exist.
- The startup file has an error in it.
- You need to watch the IOC boot!
"When I telnet on to the IOC, EPICS is not running?"
- telnet onto a Sun that has a serial link to the IOC tip hardwire
- OR: if you don't have a serial link to the IOC
- Create an empty startup file
- On the SUN:
cd <your application directory>
cp startup.mv167 startup.full
edit startup.mv167
and delete all lines after pwd
.
- Telnet onto the IOC and type:
reboot
- Telnet on again and type:
< startup.full
- Watch for errors in
dbLoad
dbLoad "~wright/appl/camac/db/camac.database"
0xfa9f10 (tShell): dbLoad: check sdrSum Error: Database out of date
value = -1 = 0xffffffff = _asLock + 0xff055b1b
- Or
iocInit
0xfa9f10 (tShell): Missing record support entry table record support entry
table not found for _gsubRSET
0xfa9f10 (tShell): iocInit: Record Support Failed during Initialization
cau
-- Used on both the Sun and the IOC.
(cau
must be loaded separately on the IOC
and is in the extensions for UNIX tools in 3.12.)
dbl, dbpr, dbpf, dbtr
-- see Chapter 2
of the IOC Application Developer's Guide
- Tracing by setting the
TPRO
field -- see Chapter 2
of the IOC Record Reference Manual
- Time stamps must be working -- this is what you might see on the IOC:
Could not contact a master timing IOC
0xfa9f10 (tShell): iocInit: All initialization complete
- You need an environmental resource file to tell the IOC what the
Network address of the time server is. This is what you need
for EPICS 3.11. EPICS 3.12 shouldn't need EPICS_IOCMCLK_INET.
Example:
houston% cat ~wright/appl/camac/resource.def
EPICS_SYSCLK_INET DBF_STRING 128.165.32.95
EPICS_IOCMCLK_INET DBF_STRING 128.165.32.214
grep
-- searches files for strings or regular expressions.
For example:
- Use it to: find the definition of an EPICS define used in a program:
grep ERROR /home/epics/r3.11/share/epicsH/*.h
which
-- tells you which version of a program you are using.
For example:
which dct
.epicsUnix/sun4/bin/dct
ls -l
-- tells you where links point and what permissions are.
For example:
ls -l .epicsUnix
lrwxrwxrwx 1 wright 32 Jan 13 12:17 .epicsUnix -> /home/epics/release/R3.11.4/Unix/
printenv
-- prints your UNIX environmental variables
For example:
printenv| grep EPICS
EPICS_DISPLAY_PATH=.:./dl
- Prove that you made no changes:
- If there really were no changes.
- It's the hardware!
- It's a memory problem!
- It's a network problem!
- It's a subtle problem!
- Sign onto the IOC and look at the boot parameters
- The startup file will tell you what directory the application is in.
- Go into their directory and look at the startup file. This should tell you
exactly what was loaded and executed on the IOC.
- Look at the
Makefile
in their src
directory.
Hopefully they used the standard directory structure.
This should tell what files were made and
what compilers were used.
- If there are
Capfast
or Gdct
files you
have a good chance of understanding the database.
- To get a list of all the channels used in the displays
(assuming they are using
edd
and dm
).
First report the display to a .adl
file.
If you are lucky, they have some names in common
from the standard naming convention. For example:
grep R03 mydisplay.adl > display.list
- To get a list of all database channels used in sequences.
grep assign *.st > st.dblist
- To get a list of channels used in the database from a short report.
grep PV myreport.short > PV.list
or go into dct
and ask it to Print One-Line Summaries.