diff --git a/applications/common-database-patterns.rst b/applications/common-database-patterns.rst deleted file mode 100644 index 8d79711..0000000 --- a/applications/common-database-patterns.rst +++ /dev/null @@ -1,56 +0,0 @@ -Common Database patterns -======================== - -Pull Alarm Status w/o Data --------------------------- -This is useful to bring alarm status in without affecting the value stored in a record. -In the following example the alarm status of **$(P):set** is fetched by **$(P):rbv** when it is processed, but the value is read from a different record. - -:: - - record(bo, "$(P):set") { - field(OSEV, "MAJOR") - field(FLNK, "$(P):rbv") - } - -:: - - record(bi, "$(P):rbv") { - field(SDIS, "$(P):set NPP MS") - field(DISV, "-1") - field(INP , "$(P):some:other:record") - } - -Combined Setting and Readback ------------------------------ -Use when a single PV is desired. Could be used to show the results of rounding in a float to fixed precision conversion. - -In the following example the value read from a ‘bi’ is inverted so that the associated ‘bo’ acts as a toggle. - -:: - - record(bi, "$(P):rbv") { - field(DTYP, "...") - field(INP , "...") - field(PINI, "YES") - field(FLNK, "$(P):inv") - } - -:: - - record(calcout, "$(P):inv") - field(CALC, "!A") - field(INPA, "$(P):rbv") - field(OUT , "$(P) NPP") - } - -:: - - record(bo, "$(P)") { - field(DTYP, "...") - field(OUT , "...") - field(FLNK, "$(P):rbv") - } - -The important point is the NPP modifier on output link of the ‘calcout’ record. -This updates the VAL field of the ‘bo’ record (and posts monitors) without processing it. \ No newline at end of file diff --git a/building-epics/configuring-vxworks-6_x.md b/building-epics/configuring-vxworks-6_x.md deleted file mode 100644 index f684100..0000000 --- a/building-epics/configuring-vxworks-6_x.md +++ /dev/null @@ -1,97 +0,0 @@ -# Configuring vxWorks 6.x - -## vxWorks 6.x Information - -This page provides a advice on configuring and using the Wind River’s Workbench environment and the vxWorks 6.x RTOS with EPICS. If you discover any other information that ought to be published here, please [let me know](mailto:anj@anl.dot.gov). - -Note that there is a [separate page](vxworks6_tornado) provided for users of vxWorks 5.x and Wind River’s Tornado. - -[Tornado 2.2 and Linux](https://epics-controls.org/resources-and-support/documents/howto-documents/vxworks6/t2-2-linux/) - -[PowerPC](https://epics-controls.org/resources-and-support/documents/howto-documents/vxworks6/powerpc/) - -[Configuring WRS Tornado 2.x for EPICS](https://epics-controls.org/resources-and-support/documents/howto-documents/vxworks6/t20xconfig/) - -### Configuring a vxWorks 6.x image - -Using the Wind River Workbench to create a vxWorks image suitable for running EPICS IOCs, the following components are **required** in addition to the standard components included with a new vxWorks 6.x Image Project (System Image) with a PROFILE\_DEVELOPMENT Configuration Profile: - -* C++ components - * standard library - * C++ Iostreams and other … — INCLUDE\_CPLUS\_IOSTREAMS -* Network Components (default) - * Network Applications (default) - * SNTP Components - * SNTP Client (daemon) — INCLUDE\_IPSNTPC - _Set the NTP server addresses under here. The primary server IPv4 address can be set to sysBootParams.had for the IOC to always use its boot host as an NTP server._ - * Network Core Components (default) - * Backwards compatibility wrapper routines - * libc wrappers - * sntpcTimeGet wrapper — INCLUDE\_IPWRAP\_SNTPCTIMEGET - * network init — INCLUDE\_NET\_INIT -* operating system components (default) - * IO system components (default) - * IO Subsystem Components - * Basic IO System - * max # open files in the system — NUM\_FILES - _Configure this to more than the maximum number of CA sessions you expect need to connect into and out of this IOC at the same time. The CA protocol uses one file handle per client, and every additional network socket, serial port and other vxWorks device will use at least one._ - * kernel components (default) - * unix compatable environment variables (default) - * install environment variable task create/delete hooks — ENV\_VAR\_USE\_HOOKS - _This variable must be set to FALSE._ - -The following components are **optional** but will often be wanted: - -* Network Components (default) - * Network Applications (default) - * SNTP Components - * INCLUDE\_IPSNTP\_CMD - * DNS Client — INCLUDE\_IPDNSC - _Set the DNS domain name and at least the DNS primary name server under here. The server can be set to sysBootParams.had for the IOC to always use its boot host as a DNS server_ - * Network Core Components (default) - * Backwards compatibility wrapper routines - * libc wrappers - * arp utility wrapper — INCLUDE\_IPWRAP\_ARP - * utilslib wrappers - * ifShow wrapper — INCLUDE\_IPWRAP\_IFSHOW - * ifconfig wrapper — INCLUDE\_IPWRAP\_IFCONFIG - * netstat wrapper — INCLUDE\_IPWRAP\_NETSTAT - * ping wrapper — INCLUDE\_IPWRAP\_PING - * routec wrapper — INCLUDE\_IPWRAP\_ROUTECMD -* development tool components (default) - * spy — INCLUDE\_SPY -* operating system components (default) - * IO system components (default) - * NFS Components - * NFS client All — INCLUDE\_NFS\_CLIENT\_ALL - -These components are included in the PROFILE\_DEVELOPMENT configuration by default but **not required** by EPICS so may safely be excluded: - -* Network Components (default) - * Network Core Components (default) - * Backwards compatibility wrapper routines - * libc wrappers - * getservbyname wrapper — INCLUDE\_IPWRAP\_GETSERVBYNAME - * getservbyport wrapper — INCLUDE\_IPWRAP\_GETSERVBYPORT -* application components (default) - * application initialization — INCLUDE\_USER\_APPL -* development tool components (default) - * Compiler support routines - * Diab compiler support routines — INCLUDE\_DIAB\_INTRINSICS -* operating system components (default) - * ANSI C components (libc) (default) - * ANSI locale — INCLUDE\_ANSI\_LOCALE - * ANSI stdio extensions — INCLUDE\_ANSI\_STDIO\_EXTRA - * POSIX components - * POSIX timers (default) — INCLUDE\_POSIX\_TIMERS - * sigevent notification library — INCLUDE\_SIGEVENT - * Real Time Process components — FOLDER\_RTP - * SYSCTL Component — FOLDER\_SYSCTL - -### vxWorks 6.6 GNU Header stdexcept - -There is a bug in the GNU C++ header file stdexcept as delivered with vxWorks 6.6 which results in some undefined symbols when you try to load the IOC code. The header has been fixed in later vxWorks releases, and there may have been an official Wind River patch issued to fix this, but Erik Bjorklund has provided [this patch](https://epics.anl.gov/base/vxWorks6.6-gnu-stdexcept.patch) to address the problem. - -### Adding a CR/CSR Master Window to the mv6100 BSP - -Eric Bjorklund [gave a talk](https://epics.anl.gov/meetings/2006-06/RecDevDrv_Support/Support_for_CR-CSR_Addressing.pdf) at a EPICS collaboration meeting in June 2006 describing how he added support for accessing the VME CR/CSR address space to the mv6100 BSP. diff --git a/building-epics/cross-compile-epics-and-a-ioc-to-an-old-x86-linux.md b/building-epics/cross-compile-epics-and-a-ioc-to-an-old-x86-linux.md deleted file mode 100644 index 4ba5be4..0000000 --- a/building-epics/cross-compile-epics-and-a-ioc-to-an-old-x86-linux.md +++ /dev/null @@ -1,378 +0,0 @@ -# How To cross compile EPICS and a IOC to an old x86 Linux system - -## Introduction - -I was given the task of developing a IOC which should run in a x86 PC with an old Linux distribution. -My development machine was a x86_64 PC running Ubuntu 12.04. -EPICS does a great job cross compiling from a 64-bits host to a 32-bits target if both have compatible versions of glibc, -binutils, -kernel, -etc. -In my case, -however, -my target had much older versions. I considered two different solutions: - -1. Create a Virtual Machine and install the target's Linux distribution. From the Virtual Machine, -compile EPICS and my IOC, -and then run the IOC in the target -2. Build a toolchain configured for my target and use that toolchain to compile both EPICS and the IOC. - -The first approach is the easiest, -but compiling from inside a VM can be slow and the distribution was not very user friendly. -So I took the second path, -which I'll describe in this document. - -## Overview - -I'm assuming you, like me, are running Ubuntu 64 bits. I'm also assuming you already have EPICS base downloaded and compiled. We will go through the steps of downloading, configuring and compiling [Crosstool-NG](http://crosstool-ng.org/), which will be used to generate our toolchain. Then we will download and compile a couple of libraries needed by EPICS (namely [readline](https://www.gnu.org/software/readline/) and [ncurses](https://www.gnu.org/software/ncurses/)). Finally, we will compile EPICS base and an example IOC to our target using the newly built toolchain. - -## Crosstool-NG - -### Downloading and extracting - -First we get the tarball containing the source code and extract it. - -``` bash -wget http://crosstool-ng.org/download/crosstool-ng/crosstool-ng-1.9.3.tar.bz2 -tar -xvf crosstool-ng-1.9.3.tar.bz2 -``` - -Crosstool-NG has a lot of dependencies, you might want to get them before compiling: - -``` bash -sudo apt-get install gawk bison flex texinfo automake libtool cvs libcurses5-dev build-essential -``` - -### Compiling - -In order to compile: - -``` bash -cd crosstool-ng-1.9.3 -./configure --local -make -``` - -### Configuring - -Before configuring Crosstool-NG, I gathered information about my target system: - -Kernel Version: - -``` console -$ uname -r -2.6.27.27 -``` - -GCC Version: - -``` console -$ gcc --version -gcc (GCC) 4.2.4 -``` - -glibc version: - -``` console -$ /lib/libc.so.6 -GNU C Library stable release version 2.7, by Roland McGrath et al. -``` - -binutils version: - -``` console -$ ld --version -GNU ld (Linux/GNU Binutils) 2.18.50.0.9.20080822 -``` - -Based on this information, and on a lot of trial and error, I configured Crosstool-NG as follows (everything else set as default): - -``` console -$ ./ct-ng menuconfig - -PATHS AND MISC OPTIONS - [*] Use obsolete features - -TARGET OPTIONS - Target architecture (x86) - Bitness: (32-bit) - (i686) Architecture Level - -OPERATING SYSTEM - Target OS (linux) - Linux kernel version (2.6.27.55) - -BINARY UTILITIES - Binutils version (2.17) - -C-COMPILER - GCC version (4.2.4) - [*] C++ - -C-LIBRARY - glibc version (2.6.1) - -``` - -I tried other configurations, but they crashed the compilation process. - -### Compiling the toolchain - -Now we can compile the toolchain: - -``` bash -./ct-ng build -``` - -This will take a while. Go get some coffee or watch a cat video on Youtube. - -Once built, the toolchain will be in `$HOME/x-tools/i686-unknown-linux-gnu/` - -It's a good idea (I think) to put the cross-compiler binaries on your path. Add this to the end of your ~/.bashrc: - -``` bash -PATH=$PATH:$HOME/x-tools/i686-unknown-linux-gnu/bin -``` - -Then source your .bashrc, so the changes take effect. - -``` bash -. ~/.bashrc -``` - -## EPICS dependencies - -In order to properly build epics-base to our target system, we have to take care of EPICS dependencies first. Namely, the libraries 'readline' and 'ncurses'. - -They will be installed in our toolchain directory. We have to make it writable: - -``` bash -chmod -R +w $HOME/x-tools/i686-unknown-linux-gnu/i686-unknown-linux-gnu/sys-root/usr -``` - -Now we can download, configure, compile and install the libraries. - -### readline - -``` bash -wget ftp://ftp.cwru.edu/pub/bash/readline-6.2.tar.gz -tar -xvf readline-6.2.tar.gz -cd readline-6.2 -./configure --prefix=$HOME/x-tools/i686-unknown-linux-gnu/i686-unknown-linux-gnu/sys-root/usr --host=i686-unknown-linux-gnu -make -make install -``` - -### ncurses - -``` bash -wget ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses-5.9.tar.gz -tar -xvf ncurses-5.9.tar.gz -cd ncurses-5.9 -./configure --prefix=$HOME/x-tools/i686-unknown-linux-gnu/i686-unknown-linux-gnu/sys-root/usr --host=i686-unknown-linux-gnu -make -make install -``` - -## Configure cross-compilation in EPICS - -We're almost done. Back to the epics-base directory, open the file: `$EPICS_BASE/configure/CONFIG_SITE` - -Change the line: - -``` makefile -CROSS_COMPILER_TARGET_ARCHS= -``` - -To: - -``` makefile -CROSS_COMPILER_TARGET_ARCHS=linux-686 -``` - -This tells EPICS base to be compiled both for the host system and for the linux-686 target. - -Save and close. Now we will create our own target configuration file, based on a existing file. - -``` bash -cd $EPICS_BASE/configure/os -cp CONFIG_SITE.Common.linux-x86 CONFIG_SITE.Common.linux-686 -``` - -Open `CONFIG_SITE.Common.linux-686` and edit it. Comment out the line: - -``` makefile -#COMMANDLINE_LIBRARY = READLINE -``` - -And uncomment: - -``` makefile -COMMANDLINE_LIBRARY = READLINE_NCURSES -``` - -At the end of the file, add the lines: - -``` makefile -GNU_DIR=$HOME/x-tools/i686-unknown-linux-gnu -GNU_TARGET=i686-unknown-linux-gnu -``` - -This tells EPICS to search for both readline and ncurses libraries during compilation. The last two lines indicate the location of the toolchain and its prefix. Save and close. Last file to edit: CONFIG.Common.linux-686 - -Change the line that says - -``` makefile -VALID_BUILDS = Ioc -``` - -To - -``` makefile -VALID_BUILDS = Host Ioc -``` - -This is needed in order to get caRepeater compiled, according to [this source](https://epics.anl.gov/tech-talk/2012/msg01102.php). - -### Recompile EPICS base - -Now, we recompile EPICS base: - -``` bash -make clean uninstall -make -``` - -Hopefully, we have everything in place to start developing our IOC's. - -## Example IOC - -Let's create a working directory for our programs. I decided to call it 'apps': - -``` bash -mkdir ~/apps -``` - -### Creating - -To create an example IOC, we use a Perl script provided by EPICS: - -``` bash -cd ~/apps -mkdir myexample -cd myexample -makeBaseApp.pl -t example myexample -``` - -The last command tells the script to create an application named 'myexample' using the template (option -t) 'example'. Now we make our IOC bootable - -``` bash -makeBaseApp.pl -i -t example myexample -``` - -It will ask you what the target is. We went to all this trouble to be able to select: - -``` bash -linux-686 -``` - -For the Application Name, just hit enter. - -### Configuring - -Add this line to the file `~/apps/myexample/configure/CONFIG_SITE` - -``` makefile -STATIC_BUILD=YES -``` - -This will statically link EPICS libraries into our executable. - -Now, let's consider that you will put your IOC in the folder /home of your target system. Edit the file ~/apps/myexample/iocBoot/iocmyexample/envPaths, so it will be: - -``` csh -epicsEnvSet("ARCH","linux-686") -epicsEnvSet("IOC","iocskel") -epicsEnvSet("TOP","/home/myexample") -epicsEnvSet("EPICS_BASE","/home/myexample") -``` - -Note that we set EPICS base to coincide with the folder of our IOC. I did it because the IOC depends on the caRepeater program, which would be present in an EPICS base if we had one in our target. Because we don't, I'll simply copy the caRepeater generated by the host to the the /bin folder of our IOC folder: - -``` bash -cp $EPICS_BASE/bin/linux-686/caRepeater ~/apps/myexample/bin/linux-686/ -``` - -### Compiling - -Compile the IOC and prepare it for execution. - -``` bash -make -chmod +x iocBoot/iocmyexample/st.cmd -``` - -Note that you won't be able to run the IOC in your host system, given that it was compiled to our target system. You won't be able to run it in your target system neither, as your target lacks three libraries: two needed by caRepeater and one needed by the IOC. - -First, take care of the libraries needed by caRepeater: - -``` bash -mkdir ~/apps/myexample/lib -mkdir ~/apps/myexample/lib/linux-686/ -cp $EPICS_BASE/lib/linux-686/libca.so.3.14 ~/apps/myexample/lib/linux-686 -cp $EPICS_BASE/lib/linux-686/libCom.so.3.14 ~/apps/myexample/lib/linux-686 -``` - -Then copy libreadline from your host's folder: - -``` bash -~/x-tools/i686-unknown-linux-gnu/i686-unknown-linux-gnu/sys-root/usr/lib/libreadline.so.6.2 -``` - -To your target's folder: - -``` bash -/lib/libreadline.so.6 -``` - -Please note the change in the filename. - -### Executing - -After copying your myexample folder to your target's /home folder, you can run your IOC: - -``` bash -cd /home/myexample/iocBoot/iocmyexample -./st.cmd -``` - -If everything goes as expected, you will have an epics prompt: - -``` console -epics> -``` - -Try listing the records: - -``` console -epics> dbl -bruno:ai1 -bruno:ai2 -bruno:ai3 -bruno:aiExample -bruno:aiExample1 -bruno:aiExample2 -bruno:aiExample3 -bruno:aSubExample -bruno:calc1 -bruno:calc2 -bruno:calc3 -bruno:calcExample -bruno:calcExample1 -bruno:calcExample2 -bruno:calcExample3 -bruno:compressExample -bruno:subExample -bruno:xxxExample -``` - diff --git a/building-epics/how-to-port-epics-to-a-new-os-architecture.rst b/building-epics/how-to-port-epics-to-a-new-os-architecture.rst deleted file mode 100644 index a67d847..0000000 --- a/building-epics/how-to-port-epics-to-a-new-os-architecture.rst +++ /dev/null @@ -1,27 +0,0 @@ -How To Port EPICS to a new OS/Architecture -========================================== - -This isn’t a detailed list of tasks, but is intended to show the main stages needed to add a new build architecture to EPICS. -If you make use of this and find there are hints you’d like to suggest, or steps missing please add them. - -* Download a tarfile for the latest release of EPICS Base, or the snapshot from the R3.14 branch (not the trunk), and unpack it. -* If you’re not already familiar with EPICS, at least skim chapter 4 of the IOC Application Developers Guide (hereafter known as the AppDevGuide; our build system is different to the usual “./configure && make” approach. -* Build your on a linux-x86 or solaris-sparc system so you know what a fully built system actually looks and acts like. You can build multiple architectures simultaneously in the same tree, which makes for easier comparisons. On linux the build instructions should be as simple as - -:: - - export EPICS_HOST_ARCH=linux-x86 - cd - make - -* On the new system system, setenv EPICS_HOST_ARCH to the name for your new architecture, which usually takes the form -, for example solaris-sparc, linux-x86, windows-x86 -* In the /configure/os directory, create these files by copying and editing the files from an existing architecture: - -:: - - CONFIG.Common. - CONFIG..Common - CONFIG_SITE..Common - -* I would suggest looking at the darwin-ppc or linux-x86 versions to start with; for a Unix-like OS you should be able to make use of the UnixCommon and/or GnuCommon files to provide most of the definitions and rules. -* If you have to cross-compile then there’s more work you have to do and these instructions are probably not sufficient to get you there. \ No newline at end of file diff --git a/building-epics/vxworks6_tornado.md b/building-epics/vxworks6_tornado.md deleted file mode 100644 index a657136..0000000 --- a/building-epics/vxworks6_tornado.md +++ /dev/null @@ -1,27 +0,0 @@ -# Configuring Tornado/vxWorks 5.5.x - -## Tornado/vxWorks 5.5.x Information - -This page provides a repository for information about using the WRS Tornado environment and the vxWorks 5.5.x RTOS with EPICS that doesn’t really belong anywhere else on this site. - -Note that there is a [separate page](configuring-vxworks-6_x) provided for users of vxWorks 6.x and Wind River Workbench. - -There is also a reasonably good Tornado 2.0 FAQ available [on the web](http://www.xs4all.nl/~borkhuis/vxworks/vxworks.html), mostly comprising answers to questions posted to the comp.os.vxworks news group. - -## Tornado 2.2 (vxWorks 5.5.x) - -### Installation - -According to the Tornado 2.2 release notes, you cannot install multiple host and/or target architectures in the same directory. - -### Linux Hosting - -See [this page](https://epics.anl.gov/base/tornado-linux.php) for information building vxWorks target code on Linux. - -### EPICS Support - -VxWorks 5.5 is only supported on EPICS 3.14.x and 3.15.x releases. From Base-3.16 and later you must use VxWorks 6.6 or later. - -## PowerPC Issues - -There is a [separate page](https://epics.anl.gov/base/ppc.php) discussing the specific problems associated with using PowerPC CPUs under vxWorks/Tornado. diff --git a/collaboration/how-to-run-an-epics-collaboration-meeting.rst b/collaboration/how-to-run-an-epics-collaboration-meeting.rst deleted file mode 100644 index 5c70014..0000000 --- a/collaboration/how-to-run-an-epics-collaboration-meeting.rst +++ /dev/null @@ -1,12 +0,0 @@ -How to run an EPICS Collaboration Meeting -========================================= - -This page is intended for “lessons learned” by sites who have run collaboration meetings, as hints to help future meetings run smoothly. - -.. toctree:: - :maxdepth: 1 - - run-collaboration-meeting/organization - run-collaboration-meeting/communications - run-collaboration-meeting/facilities - run-collaboration-meeting/agenda \ No newline at end of file diff --git a/collaboration/run-collaboration-meeting/agenda.rst b/collaboration/run-collaboration-meeting/agenda.rst deleted file mode 100644 index a90a57c..0000000 --- a/collaboration/run-collaboration-meeting/agenda.rst +++ /dev/null @@ -1,13 +0,0 @@ -Agenda -====== - -Setting an initial program structure gives presenters an idea of what topics the hosting institution may be particularly interested in, but isn’t necessary. - -In recent years the hosting site has been responsible for soliciting and collecting speakers names and talk titles; -an Indico website can perform much of the clerical work involved automatically, but the talks will still have to be manual scheduled into the Agenda. -Individual talks are usually allotted 15 minutes plus 5 minutes for questions, but some topics may be given additional time. -Recent meetings have also introduced “Lightning talks” which are 5 minutes long with no question time, and these have proven popular and a good way to cover many topics in a short time. - -The community will usually submit a number of submissions of presentations, but the hosts should expect to have to do some additional solicitation to fill out the program. -This can (should) be informed by topics the host institute is interested in. -Communications to the whole community about submitting talks should be sent to tech-talk. \ No newline at end of file diff --git a/collaboration/run-collaboration-meeting/communications.rst b/collaboration/run-collaboration-meeting/communications.rst deleted file mode 100644 index 9dac161..0000000 --- a/collaboration/run-collaboration-meeting/communications.rst +++ /dev/null @@ -1,11 +0,0 @@ -Communications -============== - -If possible, start creating a website for the meeting before it is first announced to on tech-talk; -some people will want to be able to find out more about the location when they first hear about it, so the announcement should have a link to that website. - -Attendees from some countries such as China may have to navigate a quite long approvals process (internal, government and visa) to be able to attend, and may need a letter of invitation from you to get those approvals. -Provide enough information so they know who to ask well in advance (3-4 months or more is advisable). - -Eventually you’ll most probably need online registration of attendees and possibly speakers, as well as to provide information about local hotels, transportation to/from nearby airports, and local tourist agencies for attendees’ partners. -Arranging a “partner programme” is usually unnecessary. \ No newline at end of file diff --git a/collaboration/run-collaboration-meeting/facilities.rst b/collaboration/run-collaboration-meeting/facilities.rst deleted file mode 100644 index ad37cfe..0000000 --- a/collaboration/run-collaboration-meeting/facilities.rst +++ /dev/null @@ -1,19 +0,0 @@ -Facilities -========== -For the main meeting, a hall with LCD projector(s) for computer connection and a PC to display the presentation files. -Most people will bring talks in MS PowerPoint, Adobe PDF and/or LibreOffice Impress formats (installing LibreOffice on this machine is advised, but not essential if you give people notice). -It saves time and confusion at these international meetings if the PC can be configured with English language settings (Windows menus etc.). -Providing a remote control for the presentation program and a laser pointer is helpful. - -Some presenters may want to use their own laptops for live demonstrations, or if they’re using a less common presentation program (e.g. Apple’s Keynote). - -In a large hall speakers should use a microphone if a PA is available; a radio-microphone is preferred. - -The main hall (and ideally the other meeting rooms too) should have reliable, high-bandwidth WiFi internet access since most people will bring a laptop or notebook PC and want to connect up during the meeting. - -Laptop batteries don’t last more than a few hours, so there will be demand for power sockets in the hall too. -If these are not available at every seat, providing extension leads spread about the room is generally a good idea and is much appreciated by attendees. - -Refreshments should be available at the breaks mid-morning and mid-afternoon. -If your institution can’t afford to fund these itself it is acceptable to charge attendees a fee at registration to pay for them (exhibitors funds are also helpful here). -People will expect to pay for their own lunches, and also to pay to attend the conference dinner which is usually held on the evening before the last day. \ No newline at end of file diff --git a/collaboration/run-collaboration-meeting/organization.rst b/collaboration/run-collaboration-meeting/organization.rst deleted file mode 100644 index 20eb95c..0000000 --- a/collaboration/run-collaboration-meeting/organization.rst +++ /dev/null @@ -1,24 +0,0 @@ -Organization -============ - -The EPICS Council now decides where meetings will be held, so there are usually 2 meetings a year, circulating between the Americas, Europe and the Asia/Pacific region. -Future meeting locations that have already been fixed are usually listed here. - -Collaboration meetings are usually 3 days long from Tuesday to Thursday or Wednesday to Friday, allowing for training and smaller working groups on the other days of the week. -You’ll need a big room for the full meeting, and some smaller meeting rooms for any workshops and training sessions you host. - -Also somewhere near the refreshment location a room for any exhibitions; past meetings have succeeded in attracting companies who will a small sum to put up a display table at these meetings. -Providing large-screen TVs or projectors in the exhibition space allows EPICS-related projects to demonstrate their software. - -Recent attendance has been between 80-130 people, but this depends on the number of users from the hosting site and nearby. -It can be difficult for government-funded workers (especially from US Department of Energy labs) to get approval for travel to exotic locations though, so expect attendance to vary. -Workshops can be around 30 people, but may vary depending on the topic. -If someone wants to run a workshop you can ask them for estimates on numbers. - -To include some hands-on training you may may provide PCs capable of running a virtual machine for students to use, or ask them to bring their own laptops (which some will do anyway). -Training is still possible without these, but would consist of basic lectures and demo’s only. -You would need to decide what kind of training you want, and organize some people in the community to give it. - -Topics for workshops should generally be aligned with interests of the hosts. -It will take support on the host side to make sure there is sufficient interest and attendance. -Subgroups of developers such as the EPICS Core, CS-Studio and AreaDetector groups may ask to hold a private developers meeting adjacent to the main meeting, which will usually require providing a 10-15 seat meeting room with WiFi for each group for the period of their meeting. \ No newline at end of file diff --git a/conf.py b/conf.py index cbc0632..236f177 100644 --- a/conf.py +++ b/conf.py @@ -4,6 +4,7 @@ # list see the documentation: # http://www.sphinx-doc.org/en/master/config + # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, @@ -34,7 +35,8 @@ "sphinx.ext.graphviz", "sphinx_copybutton", "sphinx.ext.intersphinx", - "myst_parser" + "myst_parser", + "sphinx_reredirects", ] myst_enable_extensions =[ @@ -50,7 +52,6 @@ "tasklist", ] - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -83,3 +84,72 @@ 'logo_only': True, } html_logo = "images/EPICS_white_logo_v02.png" + + +# -- Redirections specifications --------------------------------------------- + +# Specify redirections to https://docs.epics-controls.org/ +# instead of having a whole dedicated sub-website, i.e. readthedocs How-Tos +# "project": https://docs.epics-controls.org/projects/how-tos/en/latest/ +# See https://documatt.gitlab.io/sphinx-reredirects/usage.html +redirects = { + #"index": + # "", # not redirected + + "getting-started/installation": + "https://docs.epics-controls.org/en/latest/getting-started/installation.html", + + "getting-started/linux-packages": + "https://docs.epics-controls.org/en/latest/getting-started/linux-packages.html", + + "getting-started/creating-ioc": + "https://docs.epics-controls.org/en/latest/getting-started/creating-ioc.html", + + "getting-started/installation-windows": + "https://docs.epics-controls.org/en/latest/getting-started/installation-windows.html", + + "getting-started/installation-windows-msys2": + "https://docs.epics-controls.org/en/latest/getting-started/installation-windows-msys2.html", + + "getting-started/installation-windows-plain": + "https://docs.epics-controls.org/en/latest/getting-started/installation-windows-plain.html", + + "getting-started/installation-windows-env": + "https://docs.epics-controls.org/en/latest/getting-started/installation-windows-env.html", + + "building-epics/how-to-port-epics-to-a-new-os-architecture": + "https://docs.epics-controls.org/en/latest/build-system/how-to-port-epics-to-a-new-os-architecture.html", + + "building-epics/configuring-vxworks-6_x": + "https://docs.epics-controls.org/en/latest/build-system/configuring-vxworks-6_x.html", + + "building-epics/vxworks6_tornado": + "https://docs.epics-controls.org/en/latest/build-system/vxworks6_tornado.html", + + "building-epics/cross-compile-epics-and-a-ioc-to-an-old-x86-linux": + "https://docs.epics-controls.org/en/latest/build-system/cross-compile-epics-and-a-ioc-to-an-old-x86-linux.html", + + "applications/common-database-patterns": + "https://docs.epics-controls.org/en/latest/process-database/common-database-patterns.html", + + "collaboration/how-to-run-an-epics-collaboration-meeting": + "https://docs.epics-controls.org/en/latest/community/how-to-run-an-epics-collaboration-meeting.html", + + "collaboration/run-collaboration-meeting/organization": + "https://docs.epics-controls.org/en/latest/community/run-collaboration-meeting/organization.html", + + "collaboration/run-collaboration-meeting/communications": + "https://docs.epics-controls.org/en/latest/community/run-collaboration-meeting/communications.html", + + "collaboration/run-collaboration-meeting/facilities": + "https://docs.epics-controls.org/en/latest/community/run-collaboration-meeting/facilities.html", + + "collaboration/run-collaboration-meeting/agenda": + "https://docs.epics-controls.org/en/latest/community/run-collaboration-meeting/agenda.html", + + "writing-drivers/how-to-avoid-copying-arrays-with-waveformrecord": + "https://docs.epics-controls.org/en/latest/process-database/how-to-avoid-copying-arrays-with-waveformrecord.html", + + "infrastructure-and-other/how-to-find-which-ioc-provides-a-pv": + "https://docs.epics-controls.org/en/latest/process-database/how-to-find-which-ioc-provides-a-pv.html", +} diff --git a/getting-started/creating-ioc.rst b/getting-started/creating-ioc.rst deleted file mode 100644 index 591ede4..0000000 --- a/getting-started/creating-ioc.rst +++ /dev/null @@ -1,212 +0,0 @@ -Creation of an Input/Output Controller (IOC) -============================================ - -An IOC allows to talk to devices e.g. via ethernet. Create a directory for -the IOCs. For example ``$HOME/EPICS/IOCs`` - -:: - - cd $HOME/EPICS - mkdir IOCs - cd IOCs - -Create a top for an IOC called ``sampleIOC`` - -:: - - mkdir sampleIOC; cd sampleIOC - makeBaseApp.pl -t example sampleIOC - makeBaseApp.pl -i -t example sampleIOC - Using target architecture darwin-x86 (only one available) - The following applications are available: - sampleIOC - What application should the IOC(s) boot? - The default uses the IOC's name, even if not listed above. - Application name? (just return) - -Now, by running ``make``, a sample IOC like the demo/test IOC is -built. Next, we want to add asyn and StreamDevice to the IOC. For this, we add -the stream and asyn libraries to the Makefile. Edit -``sampleIOCApp/src/Makefile`` and add the block - -:: - - #add asyn and streamDevice to this IOC production libs - sampleIOC_LIBS += stream - sampleIOC_LIBS += asyn - -The application must also load ``asyn.dbd`` and -``stream.dbd`` to use StreamDevice. This can be put into a generated -dbd, e.g into ``xxxSupport.dbd`` which already gets included by the -Makefile. So the ``xxxSupport.dbd`` now reads: - -:: - - cat sampleIOCApp/src/xxxSupport.dbd - include "xxxRecord.dbd" - device(xxx,CONSTANT,devXxxSoft,"SoftChannel") - # - include "stream.dbd" - include "asyn.dbd" - registrar(drvAsynIPPortRegisterCommands) - registrar(drvAsynSerialPortRegisterCommands) - registrar(vxi11RegisterCommands) - -To find the dbd files, you have to add the paths to these files in -``configure/RELEASE``: - -:: - - ... - # Build variables that are NOT used in paths should be set in - # the CONFIG_SITE file. - # Variables and paths to dependent modules: - SUPPORT = ${HOME}/EPICS/support - ASYN=$(SUPPORT)/asyn - STREAM=$(SUPPORT)/stream - # If using the sequencer, point SNCSEQ at its top directory: - #SNCSEQ = $(MODULES)/seq-ver - ... - -If ``make`` was done before, ``make distclean`` is -probably required. Anyway, then ``make``. The newly created IOC can be -run with: - -:: - - cd iocBoot/iocsampleIOC/ - chmod u+x st.cmd - ./st.cmd - -Not very interesting yet, because there is no database file nor a protocol -file. - -:: - - ls -la sampleIOCApp/Db/ - total 56 - drwxr-xr-x 11 maradona staff 374 Jun 1 16:47 . - drwxr-xr-x 5 maradona staff 170 Jun 1 12:46 .. - -rw-r--r-- 1 maradona staff 523 Jun 1 12:46 Makefile - drwxr-xr-x 2 maradona staff 68 Jun 1 16:47 O.Common - drwxr-xr-x 3 maradona staff 102 Jun 1 16:47 O.darwin-x86 - -rw-r--r-- 1 maradona staff 1761 Jun 1 12:46 circle.db - -rw-r--r-- 1 maradona staff 1274 Jun 1 12:46 dbExample1.db - -rw-r--r-- 1 maradona staff 921 Jun 1 12:46 dbExample2.db - -rw-r--r-- 1 maradona staff 286 Jun 1 12:46 dbSubExample.db - -rw-r--r-- 1 maradona staff 170 Jun 1 12:46 sampleIOCVersion.db - -rw-r--r-- 1 maradona staff 307 Jun 1 12:46 user.substitutions - -Note that this is a ``Db`` directory and not the ``db`` -directory that is in ``./sampleIOC``. For MDOxxxx scopes by Tektronix, the -database (``.db``) and protocol (``.proto``) file can look -something like - -:: - - cat MDO.db - record(stringin, $(P)$(R)idn){ - field(DESC, "Asks for info blabla") - field(DTYP, "stream") - field(INP, "@MDO.proto getStr(*IDN,99) $(PORT) $(A)") - field(PINI, "YES") - } - - cat MDO.proto - Terminator = LF; - getStr{ - out "$1?"; - in "%s"; - @replytimeout {out "$1?"; in "%s";} - } - -Now, we add to ``sampleIOCApp/Db/Makefile`` the information that -these files must be included in the compilation. So - -:: - - cat sampleIOCApp/Db/Makefile - TOP=../.. - include $(TOP)/configure/CONFIG - #---------------------------------------- - # ADD MACRO DEFINITIONS BELOW HERE - # Install databases, templates & substitutions like this - DB += circle.db - DB += dbExample1.db - DB += dbExample2.db - DB += sampleIOCVersion.db - DB += dbSubExample.db - DB += user.substitutions - DB += MDO.db - DB += MDO.proto - # If .db template is not named *.template add - # _TEMPLATE = - include $(TOP)/configure/RULES - #---------------------------------------- - # ADD EXTRA GNUMAKE RULES BELOW HERE - -Again, ``make`` in directory sampleIOC. Finally, we add IP port -configuration, setting the Stream path and loading the database to the -``st.cmd`` file. The ``st.cmd`` should read: - -:: - - cat st.cmd - - #!../../bin/darwin-x86/sampleIOC - - #- You may have to change sampleIOC to something else - #- everywhere it appears in this file - - < envPaths - - epicsEnvSet ("STREAM_PROTOCOL_PATH","$(TOP)/db") - - cd "${TOP}" - - ## Register all support components - dbLoadDatabase "dbd/sampleIOC.dbd" - sampleIOC_registerRecordDeviceDriver pdbbase - - ## Load record instances - dbLoadTemplate "db/user.substitutions" - dbLoadRecords "db/sampleIOCVersion.db", "user=UUUUUU" - dbLoadRecords "db/dbSubExample.db", "user=UUUUUU" - - #IF if the user also defines EPICS_CAS_INTF_ADDR_LIST then beacon address - #list automatic configuration is constrained to the network interfaces specified - #therein, and therefore only the broadcast addresses of the specified LAN interfaces, - #and the destination addresses of all specified point-to-point links, will be automatically configured. - #epicsEnvSet ("EPICS_CAS_INTF_ADDR_LIST","aaa.aaa.aaa.aaa") - - # connect to the device ... IP-Address ! Port 2025 used by textronix, see manual - drvAsynIPPortConfigure("L0","bbb.bbb.bbb.bbb:pppp",0,0,0) - - ## Load record instances - dbLoadRecords("db/MDO.db", "P=UUUUUU:,PORT=L0,R=MDO:,L=0,A=0") - - #- Set this to see messages from mySub - #var mySubDebug 1 - - #- Run this to trace the stages of iocInit - #traceIocInit - - cd "${TOP}/iocBoot/${IOC}" - iocInit - - ## Start any sequence programs - #seq sncExample, "user=UUUUUU" - -In here, you have to replace *UUUUUU* with the user name that runs -the EPICS IOC (you?). *bbb.bbb.bbb.bbb* is the IP of the device (e.g. -the scope) and *pppp* the port on which it listens. -*EPICS_CAS_INTF_ADDR_LIST* can be used if there are two network -interfaces (e.g. wlan and eth0). - -The following commands might be necessary with multiple network -interfaces: - -:: - - export EPICS_CA_ADDR_LIST=ccc.ccc.ccc.ccc << Broadcast address of the network - export EPICS_CA_AUTO_ADDR_LIST=NO \ No newline at end of file diff --git a/getting-started/installation-windows-env.rst b/getting-started/installation-windows-env.rst deleted file mode 100644 index be15c9b..0000000 --- a/getting-started/installation-windows-env.rst +++ /dev/null @@ -1,54 +0,0 @@ -Setting the system environment ------------------------------- -In order to run all EPICS commands anywhere by using their simple name and to build more EPICS modules using the same setup, you can set three environment variables for the current shell or user on the Windows system: - -* EPICS_BASE -* EPICS_HOST_ARCH -* Path - -Note that *running* IOCs only needs the Path to be set correctly (when using dynamic DLL builds). -*Building* IOC applications needs EPICS_HOST_ARCH and benefits from EPICS_BASE being set. - -Required settings for Path -^^^^^^^^^^^^^^^^^^^^^^^^^^ -The way you are building your binaries determines which paths have to be added to the Path variable. - -* Static builds - - 1. Add the EPICS Base binary directory for your target to be able to call the EPICS command line tools without specifying their fully qualified path. - - This setting is for convenience only and not mandatory. Your IOCs run without it. - -* Dynamic (DLL) builds - - 1. Add the EPICS Base binary directory for your target so that the EPICS DLLs are found and you can use the CLI tools without specifying the path. - 2. If you built your binaries using MinGW and want to use them under the Command Prompt or through a shortcut icon, add the MinGW binary directory ("C:\\msys64\\mingw64\\bin") so that the MinGW runtime system DLLs are found. Inside the MSYS2 Bash shell, this location is included by default. - - Both settings are mandatory; the former for all builds, the latter under the stated condition. - -Set environment using a batch or script from EPICS Base -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -EPICS Base provides script and batch files to help setting the environment for running EPICS commands and doing EPICS builds. - -The ``windows.bat`` batch file in the folder called ``startup`` sets the environment if you use the Windows command prompt and compiled your EPICS Base using Visual Studio compilers with the help of Strawberry Perl. -You probably will have to edit ``windows.bat`` to adapt it to your needs and ``call`` it from any Windows command prompt before doing EPICS commands or builds. - -If you use the MSYS2 bash shell, you similarly need to adapt and run the ``unix.sh`` shell script from any bash shell prompt before doing EPICS commands or builds. - -Set environment using the Windows settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This method requires less effort and does not need something special to be executed or called from the command prompt. - -Go to Start Menu, Type "environment" and select "Edit environment variables for your account". -If you have Administrator rights and want to do it globally, you can also select ``Edit the system environment variables``. - -1. Select ``Advance`` tab, navigate to ``Environment Variables`` button. That should open editable tables of settings for Windows Environment. -2. Select ``User Variable for 'user'`` option, press NEW -3. Add EPICS BASE path here. In ``Variable Name``, put "EPICS_BASE". For ``Variable Value``, enter the location of your EPICS Base installation, e.g., "C:\\msys64\\home\\'user'\\base-R7.0.4.1" -4. Set the host architecture. In ``Variable Name``, put "EPICS_HOST_ARCH". For ``Variable Value``, put "windows-x64-mingw" or "windows-x64" (depending on your selection of compilers). -5. Navigate to the variable called ``Path``. Press Edit. -6. If you are using the MinGW compilers and dynamic (DLL) linking, add the path for the MinGW64 DLLs. Press NEW and enter "C:\\msys64\\mingw64\\bin". Press ok. -7. Add the path for the EPICS commands and DLLs. Press NEW and enter ``%EPICS_BASE%\bin\%EPICS_HOST_ARCH%``. Press ok twice and you are done. -8. Restart the Machine and check if EPICS commands like ``caget`` and ``camonitor`` are being recognised as valid commands in any location and work. - -Note that by default the MSYS2 shell does not inherit the parent environment. To change that behavior, you need to start the shell with the argument ``-use-full-path``. diff --git a/getting-started/installation-windows-msys2.rst b/getting-started/installation-windows-msys2.rst deleted file mode 100644 index 262d01f..0000000 --- a/getting-started/installation-windows-msys2.rst +++ /dev/null @@ -1,305 +0,0 @@ -Installation using MSYS2 and the MinGW Compilers -================================================ -MSYS2 has all the required tools available through an easy-to-use package manager, and its bash shell looks and feels like working on Linux. Most Bash commands are similar to their Linux versions. MSYS2 is available for Windows 7 and up only. The following procedure is verified on Windows 8.1 (64 bit) and Windows 10 (64 bit). - -Install tools -------------- -MSYS2 provides a Bash shell, Autotools, revision control systems and other tools for building native Windows applications using MinGW-w64 toolchains. It can be installed from its official `website `_. Download and run the installer - "x86_64" for 64-bit, "i686" for 32-bit Windows. The installation procedure is well explained on the website. These instructions assume you are running on 64-bit Windows. - -The default location of the MSYS2 installation is ``C:\msys64``. If you don't have Administrator rights, you can install MSYS2 in any location you have access to, e.g. ``C:\Users\'user'\msys64`` (with 'user' being your Windows user directory name). We will assume the default location in this document. - -Once installation is complete, you have three options available for starting a shell. The difference between these options is the preset of the environment variables that select the compiler toolchain to use. -Launch the "MSYS MinGW 64-bit" option to use the MinGW 64bit toolchain, producing 64bit binaries that run on 64bit Windows systems. The "MSYS MinGW 32-bit" option will use the MinGW 32bit toolchain, producing 32bit binaries that will run on 32bit and 64bit Windows systems. - -Again: you have a single installation of MSYS2, these different shells are just setups to use different compilers. Installation and update of your MSYS2 system only has to be done once - you can use any of the shell options for that. - -Update MSYS2 with following command:: - - $ pacman -Syu - -After this finishes (let it close the bash shell), open bash again and run the same command again to finish the updates. The same procedure is used for regular updates of the MSYS2 installation. An up-to-date system shows:: - - $ pacman -Syu - :: Synchronizing package databases... - mingw32 is up to date - mingw64 is up to date - msys is up to date - :: Starting core system upgrade... - there is nothing to do - :: Starting full system upgrade... - there is nothing to do - -Install the necessary tools (perl is already part of the base system):: - - $ pacman -S tar make - -Packages with such "simple" names are part of the MSYS2 environment and work for all compilers/toolchains that you may install on top on MSYS2. - -Install compiler toolchains ---------------------------- -Packages that are part of a MinGW toolchain start with the prefix "mingw-w64-x86_64-" for the 64bit toolchain or "mingw-w64-i686-" for the 32bit toolchain. -(The "w64" part identifies the host system will be different when using a 32bit MSYS2 environment, e.g. on a 32bit Windows host.) - -Install the MinGW 32bit and/or MinGW 64bit toolchains:: - - $ pacman -S mingw-w64-x86_64-toolchain - $ pacman -S mingw-w64-i686-toolchain - -Each complete toolchain needs about 900MB of disk space. -If you want to cut down the needed disk space (to about 50%), instead of hitting return when asked which packages of the group to install, you can select the minimal set of packages required for compiling EPICS Base: ``binutils``, ``gcc`` and ``gcc-libs``. - -If you are not sure, check your set of tools is complete and everything is installed properly:: - - $ pacman -Q - ... - make 4.3-1 - perl 5.32.0-2 - mingw-w64-x86_64-... - mingw-w64-i686-... - ... - -Update your installation regularly ----------------------------------- -As mentioned above, you can update your complete installation (including all tools and compiler toolchains) at any time using:: - - $ pacman -Syu - -You should do this in regular intervals. - -Download and build EPICS Base ------------------------------ -Start the "MSYS MinGW 64-bit" shell and do:: - - $ cd $HOME - $ wget https://epics-controls.org/download/base/base-7.0.4.1.tar.gz - $ tar -xvf base-7.0.4.1.tar.gz - $ cd base-R7.0.4.1 - $ export EPICS_HOST_ARCH=windows-x64-mingw - $ make - -When using the MinGW 32bit toolchain, the "MSYS MinGW 32-bit" shell must be used and EPICS_HOST ARCH must be set to "win32-x86-mingw". - -Note: If you are connecting to your MSYS2 system through ssh, you need to set and allow an environment variable to use the environment presets for the MinGW compilers. In the MSYS2 configuration of the ssh daemon (``/etc/ssh/sshd_config``), add the line - -:: - - AcceptEnv MSYSTEM - -and on your (local) client configuration (``~/.ssh/config``) add the line - -:: - - SetEnv MSYSTEM=MINGW64 - -to use the MinGW 64-bit compiler chain (``MINGW32`` to use a 32-bit installation). - -During the compilation, there will probably be warnings, but there should be no error. You can choose any EPICS Base version to build, the procedure remains the same. - -Please refer to the chapter "Build Time" in :doc:`installation-windows` for ways to shorten your build. - -Quick test from MSYS2 Bash --------------------------- -As long as you haven't added the location of your programs to the ``PATH`` environment variable (see below), you will have to provide the whole path to run commands or `cd` into the directory they are located in and prefix the command with ``./``. - -Replace 'user' with the actual Windows user folder name existing in your Windows installation - MSYS2 creates your home directory using that name. In the examples, we assume the default location for MSYS2 (``C:\msys64``). - -Run ``softIoc`` and, if everything is ok, you should see an EPICS prompt:: - - $ cd /home/'user'/base-R7.0.4.1/bin/windows-x64-mingw - $ ./softIoc -x test - Starting iocInit - iocRun: All initialization complete - dbLoadDatabase("C:\msys64\home\'user'\base-R7.0.4.1\bin\windows-x64-mingw\..\..\dbd\softIoc.dbd") - softIoc_registerRecordDeviceDriver(pdbbase) - iocInit() - ############################################################################ - ## EPICS R7.0.4.1 - ## Rev. 2020-10-21T11:57+0200 - ############################################################################ - epics> - -You can exit with ctrl-c or by typing exit. - -As long as you are in the location of the EPICS Base binaries, you can run them by prefixing with ``./``. Try commands like ``./caput``, ``./caget``, ``./camonitor``, ... - -Quick test from Windows command prompt --------------------------------------- -Open the Windows command prompt. Again, 'user' is the Windows user folder name. -The MSYS2 home folders are inside the MSYS2 installation. - -If you built EPICS Base with dynamic (DLL) linking, you need to add the location of the C++ libraries to the `PATH` variable for them to be found. (Again, assuming a 64bit MSYS2 installation with default paths and the MinGW 64bit toolchain.) - -:: - - >set "PATH=%PATH%C:\msys64\mingw64\bin;" - >cd C:\msys64\home\'user'\base-R7.0.4.1\bin\windows-x64-mingw - >softIoc -x test - Starting iocInit - ############################################################################ - ## EPICS R7.0.4.1 - ## Rev. 2020-10-21T11:57+0200 - ############################################################################ - iocRun: All initialization complete - epics> - -You can exit with ctrl-c or by typing exit. - -As long as you are in the location of the EPICS Base binaries, they will all work using their simple names. Try commands like ``caput``, ``caget``, ``camonitor``, ... - -Create a demo/test IOC ----------------------- -Although the ``softIoc`` binary can be used with multiple instances with different db files, you will need to create your own IOC at some point. We will create a test ioc from the existing application template in Base using the ``makeBaseApp.pl`` script. - -Let's create one IOC, which takes the values of 2 process variables (PVs), adds them and stores the result in 3rd PV. - -We will use ``MSYS2`` for building the IOC. Open the ``MSYS2 Mingw 64-bit`` shell. Make sure the environment is set up correctly (see :doc:`installation-windows-env`). - -Create a new directory ``testioc``:: - - $ mkdir testioc - $ cd testioc - -From that ``testioc`` folder run the following:: - - $ makeBaseApp.pl -t ioc test - $ makeBaseApp.pl -i -t ioc test - Using target architecture windows-x64-mingw (only one available) - The following applications are available: - test - What application should the IOC(s) boot? - The default uses the IOC's name, even if not listed above. - Application name? - -Accept the default name and press enter. That should generate a skeleton for your ``testioc``. - -You can find the full details of the application structure in the "Application Developer's Guide", chapter `Example IOC Application `_. - -:: - - $ ls - configure iocBoot Makefile testApp - -Now create a ``db`` file which describes PVs for your ``IOC``. Go to ``testApp/Db`` and create ``test.db`` file with following record details:: - - record(ai, "test:pv1") - { - field(VAL, 49) - } - record(ai, "test:pv2") - { - field(VAL, 51) - } - record(calc,"test:add") - { - field(SCAN,"1 second") - field(INPA, "test:pv1") - field(INPB, "test:pv2") - field("CALC", "A + B") - } - -Open ``Makefile`` and navigate to - -:: - - #DB += xxx.db - -Remove # and change this to ``test.db``:: - - DB += test.db - -Go to back to root folder for IOC ``testioc``. Go to ``iocBoot/ioctest``. Modify the ``st.cmd`` startup command file. - -Change:: - - #dbLoadRecords("db/xxx.db","user=XXX") - -to:: - - dbLoadRecords("db/test.db","user=XXX") - -Save all the files and go back to the MSYS2 Bash terminal. Make sure the architecture is set correctly:: - - $ echo $EPICS_HOST_ARCH - windows-x64-mingw - -Change into the testioc folder and run ``make``:: - - $ cd ~/testioc - $ make - -This should create all the files for the test IOC. - -:: - - $ ls - bin configure db dbd iocBoot lib Makefile testApp - -Go to ``iocBoot/ioctest`` . Open the ``envPaths`` file and change the MSYS2 relative paths to full Windows paths:: - - epicsEnvSet("IOC","ioctest") - epicsEnvSet("TOP","C:/msys64/home/'user'/testioc") - epicsEnvSet("EPICS_BASE","C:/msys64/home/'user'/base-7.0.4.1") - -**Note:** You can use Linux style forward slash characters in path specifications inside this file or double backslashes (``\\``). - -At this point, you can run the IOC from either an MSYS2 Bash shell or from a Windows command prompt, by changing into the IOC directory and running the test.exe binary with your startup command script as parameter. - -In the Windows command prompt:: - - >cd C:\msys64\home\'user'\testioc\iocBoot\ioctest - >..\..\bin\windows-x64-mingw\test st.cmd - -In the MSYS2 shell:: - - $ cd ~/testioc/iocBoot/ioctest - $ ../../bin/windows-x64-mingw/test st.cmd - - -In both cases, the IOC should start like this:: - - Starting iocInit - iocRun: All initialization complete - #!../../bin/windows-x64-mingw/test - < envPaths - epicsEnvSet("IOC","ioctest") - epicsEnvSet("TOP","C:/msys64/home/'user'/testioc") - epicsEnvSet("EPICS_BASE","C:/msys64/home/'user'/base-R7.0.4.1") - cd "C:/msys64/home/'user'/testioc" - ## Register all support components - dbLoadDatabase "dbd/test.dbd" - test_registerRecordDeviceDriver pdbbase - Warning: IOC is booting with TOP = "C:/msys64/home/'user'/testioc" - but was built with TOP = "/home/'user'/testioc" - ## Load record instances - dbLoadRecords("db/test.db","user='user'") - cd "C:/msys64/home/'user'/testioc/iocBoot/ioctest" - iocInit - ############################################################################ - ## EPICS R7.0.4.1 - ## Rev. 2020-10-21T11:57+0200 - ############################################################################ - ## Start any sequence programs - #seq sncxxx,"user='user'" - epics> - -Check if the database ``test.db`` you created is loaded correctly:: - - epics> dbl - test:pv1 - test:pv2 - test:add - -As you can see 3 process variable is loaded and available. Keep this terminal open and running. Test this process variable using another terminals. - -Open another shell for monitoring ``test:add``:: - - $ camonitor test:add - test:add 2020-10-23 13:39:14.795006 100 - -That terminal will monitor the PV ``test:add`` continuously. If any value change is detected, it will be updated in this terminal. Keep it open to observe the behaviour. - -Open a third shell. Using caput, modify the values of ``test:pv1`` and ``test:pv2`` as we have done in the temperature example above. You will see changes of their sum in the second terminal accordingly. - -At this point, you have one IOC ``testioc`` running, which loaded the database ``test.db`` with 3 records. From other processes, you can connect to these records using Channel Access. If you add more process variable in ``test.db``, you will have to ``make`` the `testioc` application again and restart the IOC to load the new version of the database. - -You can also create and run IOCs like this in parallel with their own databases and process variables. Just keep in mind that each record instance has to have a unique name for Channel Access to work properly. diff --git a/getting-started/installation-windows-plain.rst b/getting-started/installation-windows-plain.rst deleted file mode 100644 index 911b16d..0000000 --- a/getting-started/installation-windows-plain.rst +++ /dev/null @@ -1,280 +0,0 @@ -Installation using plain Windows and the Visual Studio compilers -================================================================ - -Install tools -------------- -There are two reasonable options. - -Using Chocolatey -^^^^^^^^^^^^^^^^ -Go to the `Chocolatey website `_ and follow their instructions to download and install the package manager. - -Using Chocolatey, install Strawberry Perl and Gnu Make. - -Manually -^^^^^^^^ -Install Strawberry Perl or ActivePerl using the Windows installers available on their download pages. - -Strawberry Perl contains a suitable version of GNU Make. Otherwise, you can download a Windows executable that Andrew provides at https://epics.anl.gov/download/tools/make-4.2.1-win64.zip. Unzip it into a location (path must not contain spaces or parentheses) and add it to the system environment. - -Put tools in the Path -^^^^^^^^^^^^^^^^^^^^^ -Make sure the tools' locations are added to the system environment variable Path. Inside a shell (command prompt) they must be callable using their simple name, e.g.:: - - >perl --version - - This is perl 5, version 26, subversion 1 (v5.26.1) built for MSWin32-x64-multi-thread - (with 1 registered patch, see perl -V for more detail) - - Copyright 1987-2017, Larry Wall - - Binary build 2601 [404865] provided by ActiveState http://www.ActiveState.com - Built Dec 11 2017 12:23:25 - ... - - >make --version - GNU Make 4.2.1 - Built for x86_64-w64-mingw32 - Copyright (C) 1988-2016 Free Software Foundation, Inc. - License GPLv3+: GNU GPL version 3 or later - This is free software: you are free to change and redistribute it. - There is NO WARRANTY, to the extent permitted by law. - -Install the compiler --------------------- -Download the Visual Studio Installer and install (the community edition is free). Make sure you enable the Programming Languages / C++ Development options. - -In VS 2019, you also have the option to additionally install the Visual C++ 2017 compilers, if that is interesting for you. - -Download and build EPICS Base ------------------------------ - -1. Download the distribution from e.g. https://epics-controls.org/download/base/base-7.0.4.1.tar.gz. -2. Unpack it into a work directory. -3. Open a Windows command prompt and change into the directory you unpacked EPICS Base into. - - **Note:** The complete path of the current directory mustn't contain any spaces or parentheses. If your working directory path does, you can do another cd into the same directory, replacing every path component containing spaces or parentheses with its Windows short path (that can be displayed with ``dir /x``). -4. Set the EPICS host architecture EPICS_HOST_ARCH (windows-x64 for 64bit builds, win32-x86 for 32bit builds). -5. Run the ``vcvarsall.bat`` script of your installation (the exact path depends on the type and language of installation) to set the environment for your build. -6. Run ``make`` (or ``gmake`` if using the version from Strawberry Perl). - -:: - - >cd base-R7.0.4.1 - >set EPICS_HOST_ARCH=windows-x64 - >"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64 - ********************************************************************** - ** Visual Studio 2019 Developer Command Prompt v16.6.2 - ** Copyright (c) 2020 Microsoft Corporation - ********************************************************************** - [vcvarsall.bat] Environment initialized for: 'x64' - - >make - -There will probably be warnings, but there should be no error. You can choose any EPICS base to install, the procedure remains the same. - -Please refer to the chapter "Build Time" in :doc:`installation-windows` for ways to shorten your build. - -Quick test from Windows command prompt --------------------------------------- -As long as you haven't added the location of your programs to the ``PATH`` environment variable (see :doc:`installation-windows-env`), you will have to provide the whole path to run commands or `cd` into the directory they are located in. - -Open the Windows command prompt. Again, replace 'user' with the actual Windows user folder name existing in your Windows installation. - -Run ``softIoc`` and, if everything is ok, you should see an EPICS prompt:: - - >cd C:\Users\'user'\base-R7.0.4.1\bin\windows-x64-mingw - >softIoc -x test - Starting iocInit - iocRun: All initialization complete - dbLoadDatabase("C:\Users\'user'\base-R7.0.4.1\bin\windows-x64\..\..\dbd\softIoc.dbd") - softIoc_registerRecordDeviceDriver(pdbbase) - iocInit() - ############################################################################ - ## EPICS R7.0.4.1 - ## Rev. 2020-10-21T11:57+0200 - ############################################################################ - epics> - -You can exit with ctrl-c or by typing exit. - -As long as you are in the location of the EPICS Base binaries, they will all work using their simple names. Try commands like ``caput``, ``caget``, ``camonitor``, ... - -Quick test from MSYS2 Bash --------------------------- -Obviously, if you have an installation of MSYS2, you can run the same verification from the MSYS2 Bash shell:: - - $ cd /c/Users/'user'/base-R7.0.4.1/bin/windows-x64 - $ ./softIoc -x test - Starting iocInit - iocRun: All initialization complete - dbLoadDatabase("C:\Users\'user'\base-R7.0.4.1\bin\windows-x64\..\..\dbd\softIoc.dbd") - softIoc_registerRecordDeviceDriver(pdbbase) - iocInit() - ############################################################################ - ## EPICS R7.0.4.1 - ## Rev. 2020-10-21T11:57+0200 - ############################################################################ - epics> - -You can exit with ctrl-c or by typing exit. - -As long as you are in the location of the EPICS Base binaries, you can run them by prefixing ``./``. Try commands like ``./caput``, ``./caget``, ``./camonitor``, ... - - -Create a demo/test IOC ----------------------- -Although the ``softIoc`` binary can be used with multiple instances with different db files, you will need to create your own IOC at some point. We will create a test ioc from the existing application template in Base using the ``makeBaseApp.pl`` script. - -Let's create one IOC, which takes the values of 2 process variables (PVs), adds them and stores the result in 3rd PV. - -We will use the Windows command prompt for building the IOC. Open the command prompt. Create a new directory ``testioc``:: - - >mkdir testioc - >cd testioc - -From that ``testioc`` folder run the following:: - - >makeBaseApp.pl -t ioc test - >makeBaseApp.pl -i -t ioc test - Using target architecture windows-x64 (only one available) - The following applications are available: - test - What application should the IOC(s) boot? - The default uses the IOC's name, even if not listed above. - Application name? - -Accept the default name and press enter. That should generate a skeleton for your ``testioc``. - -You can find the full details of the application structure in the "Application Developer's Guide", chapter `Example IOC Application `_. - -:: - - >dir /b - configure - iocBoot - Makefile - testApp - -Now create a ``db`` file which describes PVs for your ``IOC``. Go to ``testApp\Db`` and create ``test.db`` file with following record details:: - - record(ai, "test:pv1") - { - field(VAL, 49) - } - record(ai, "test:pv2") - { - field(VAL, 51) - } - record(calc,"test:add") - { - field(SCAN,"1 second") - field(INPA, "test:pv1") - field(INPB, "test:pv2") - field("CALC", "A + B") - } - -Open ``Makefile`` and navigate to - -:: - - #DB += xxx.db - -Remove # and change this to ``test.db``:: - - DB += test.db - -Go to back to root folder for IOC ``testioc``. Go to ``iocBoot\ioctest``. Modify the ``st.cmd`` startup command file. - -Change:: - - #dbLoadRecords("db/xxx.db","user=XXX") - -to:: - - dbLoadRecords("db/test.db","user=XXX") - -Save all the files and go back to the MSYS2 Bash terminal. Make sure the environment is set up correctly (see :doc:`installation-windows-env`).:: - - >echo $EPICS_HOST_ARCH - windows-x64 - >cl - Microsoft (R) C/C++ Optimizing Compiler Version 19.27.29112 for x64 - Copyright (C) Microsoft Corporation. All rights reserved. - -Change into the testioc folder and run ``make`` (or ``gmake`` when using the make from Strawberry Perl):: - - >cd %HOMEPATH%\testioc - >make - -This should build the executable and create all files for the test IOC:: - - >dir /b - bin - configure - db - dbd - iocBoot - lib - Makefile - testApp - -At this point, you can run the IOC from either an MSYS2 Bash shell or from a Windows command prompt, by changing into the IOC directory and running the test.exe binary with your startup command script as parameter. - -In the Windows command prompt:: - - >cd %HOMEPATH%\testioc\iocBoot\ioctest - >..\..\bin\windows-x64\test st.cmd - -Or - if you have an installation - in the MSYS2 shell:: - - $ cd ~/testioc/iocBoot/ioctest - $ ../../bin/windows-x64/test st.cmd - - -In both cases, the IOC should start like this:: - - Starting iocInit - #!../../bin/windows-x64/test - < envPaths - epicsEnvSet("IOC","ioctest") - epicsEnvSet("TOP","C:/Users/'user'/testioc") - epicsEnvSet("EPICS_BASE","C:/Users/'user'/base-R7.0.4.1") - cd "C:/Users/'user'/testioc" - ## Register all support components - dbLoadDatabase "dbd/test.dbd" - test_registerRecordDeviceDriver pdbbase - ## Load record instances - dbLoadRecords("db/test.db","user='user'") - cd "C:/Users/'user'/testioc/iocBoot/ioctest" - iocInit - ############################################################################ - ## EPICS R7.0.4.1 - ## Rev. 2020-10-21T11:57+0200 - ############################################################################ - iocRun: All initialization complete - ## Start any sequence programs - #seq sncxxx,"user='user'" - epics> - -Check if the database ``test.db`` you created is loaded correctly:: - - epics> dbl - test:pv1 - test:pv2 - test:add - -As you can see 3 process variable is loaded and available. Keep this terminal open and running. Test this process variable using another terminals. - -Open another shell for monitoring ``test:add``:: - - >camonitor test:add - test:add 2020-10-23 13:39:14.795006 100 - -That terminal will monitor the PV ``test:add`` continuously. If any value change is detected, it will be updated in this terminal. Keep it open to observe the behaviour. - -Open a third shell. Using caput, modify the values of ``test:pv1`` and ``test:pv2`` as we have done in the temperature example above. You will see changes of their sum in the second terminal accordingly. - -At this point, you have one IOC ``testioc`` running, which loaded the database ``test.db`` with 3 records. From other processes, you can connect to these records using Channel Access. If you add more process variable in ``test.db``, you will have to ``make`` the `testioc` application again and restart the IOC to load the new version of the database. - -You can also create and run IOCs like this in parallel with their own databases and process variables. Just keep in mind that each record instance has to have a unique name for Channel Access to work properly. diff --git a/getting-started/installation-windows.rst b/getting-started/installation-windows.rst deleted file mode 100644 index 133e523..0000000 --- a/getting-started/installation-windows.rst +++ /dev/null @@ -1,126 +0,0 @@ -======================= -Installation on Windows -======================= - -Introduction ------------- - -EPICS -^^^^^ -EPICS is a toolkit for building control systems. You can get the basic ideas from the EPICS web site at https://epics-controls.org/about-epics/. - -Traditionally, an EPICS installation starts with compiling the core parts ("EPICS Base") from source. -This process is covered by these instructions, starting from scratch on a Windows system and getting you to the point where you have a working IOC and can connect to it from a command line shell. -Other How-Tos will guide you further. - -EPICS on Windows -^^^^^^^^^^^^^^^^ -While it is not its primary or most widely used target platform, the EPICS low-level libraries have good and -well-tested implementations on Windows. EPICS runs fine on Windows targets, fast and robust. - -There are, however, a few choices about how to compile and run EPICS on Windows that you will have to take beforehand. -Understanding these choices and their implications before making decisions will help you to avoid mistakes and spend time fixing them. - -Cygwin -^^^^^^ -As mentioned before, EPICS Base has its own native Windows implementation of all necessary low level services. There is no need to go through the Posix emulation layer that Cygwin provides. The native Windows implementation is more portable and performs better. Unless you need to use Cygwin, e.g., if you are using a binary vendor-provided library for Cygwin, you should prefer a native Windows build. - -Also, Cygwin is deprecated as a target platform for EPICS. - -Build Time -^^^^^^^^^^ -The time needed to build EPICS Base depends on a few factors, including the speed of the processor and file system, the compiler used, the build mode (DLL or static), possibly debugging options and others. -On a medium sized two-core machine, a complete build of EPICS 7 often takes between 15 and 30 minutes, the 3.15 branch can be built in 6 to 10 minutes. - -Use ``make -j`` to make use of multiple CPU cores. - -Required Tools --------------- -* C++ compiler: either MinGW (GCC) or Microsoft's Visual Studio compiler (VS) -* archive unpacker (7zip or similar) -* GNU Make (4.x) -* Perl - -Choice 1: Compiler ------------------- -You will need a C++ compiler with its supporting C++ standard libraries. -Two major compilers are supported by EPICS and its build system: - -Microsoft's Visual Studio compiler (VS) - Probably the most widely used compiler for EPICS on the Windows platform. - The "Community Edition" is free to download and use. (You need to have Administrator rights to install it.) - Any Visual Studio installation will need the "C++ development" parts for the compiler toolchain to be installed. - - EPICS is using the Make build system. You can use the Visual Studio IDE, but EPICS does not provide any project files or configurations for Visual Studio's own build system. - -MinGW (GCC) - Minimalist GNU for Windows - A compiler toolchain based on the widely-used GNU compilers that - like the VS compiler - generates native Windows executables. - -Both compiler toolchains can create shared libraries (DLLs) and static libraries. On a 64bit system, both can create 64bit output (runs on 64bit systems) and 32bit output (runs on both 32bit and 64bit systems). - -When using C++, libraries are not compatible between those two compilers toolchains. When generating a binary (e.g., an IOC), all C++ code that is being linked must have been generated uniformly by either VS or MinGW. (The reason is different name mangling for symbol names: a symbol needed for linking an executable will not be found in a library generated with the other compiler, because its name is different there.) - -If you need to link against vendor-provided binary C++ libraries, this will most likely determine which compiler you need to use. - -Choice 2: Build Environment and Tool Installation -------------------------------------------------- - -MSYS2 -^^^^^ -`MSYS2 `_ (available for Windows 7 and up) is a pretty complete "feels like Linux" environment. It includes a Linux style package manager (`pacman`), which makes it very easy to install the MinGW toolchains (32 and 64 bit) and all other necessary tools. It also offers a bash shell. If you are used to working in a Linux environment, you will like working on MSYS2. - -MSYS2 can be installed, used and updated (including tools and compilers) without Administrator rights. - -As up-to-date MinGW/GCC compilers are an integral part of the package, MSYS2 is strongly recommended for using the MinGW compiler toolchains. - -The Visual Studio compilers can also be used from the MSYS2 bash. This needs a one-time setup of an intermediate batch script to get the Visual Studio environment settings correctly inherited. The resulting shell can compile using Visual Studio compilers as well as using MinGW, selected by the EPICS_HOST_ARCH environment variable setting. - -Chocolatey -^^^^^^^^^^ -`Chocolatey `_ is a package manager for Windows with a comfortable GUI, making it easy to install and update software packages (including the tools needed for building EPICS). In many cases, Chocolatey packages wrap around the native Windows installers of software. - -Using Chocolatey needs Administrator rights. - -Windows Installers -^^^^^^^^^^^^^^^^^^ -You can also install the required tools independently, directly using their native Windows installers. - -For Perl, both Strawberry Perl and ActivePerl are known to work. Strawberry Perl is more popular; it includes GNU Make (as `gmake.exe`) and the MinGW/GCC compiler necessary to build the Channel Access Perl module that is part of EPICS Base. - -For GNU Make, the easiest way is to use the one included in Strawberry Perl. Otherwise, there is a Windows binary provided on the EPICS web site. - -Native Windows installers often need Administrator rights. - -Choice 3: Static or DLL Build / Deployment ------------------------------------------- -If you configure the EPICS build system to build your IOCs dynamically (i.e., using DLLs), they need the DLLs they have been linked against to be present on the target system, either in the same directory as the IOC binary or in a directory that is mentioned in the ``%PATH%`` environment variable. - -Depending on how you plan to deploy your IOCs into the production system, it might be easier to use static builds when generating IOCs. The resulting binaries will be considerably larger, but they will run on any Windows system without providing additional EPICS DLLs. - -When running many EPICS IOCs on a single target machine, the `shared` aspect of a DLL build will lead to smaller memory usage. The DLL is in memory once and used concurrently by all IOC binaries, while the statically linked binaries each have their own copy of the library in memory. - -*Note:* When using the Visual Studio compilers, compilation uses different flags for building DLLs and building static libraries. You can't generate static and shared libraries in the same build. You can provide both options in your EPICS installation by running both builds in sequence (with ``make clean`` inbetween), so that your applications can decide between static or DLL build. Or you can just provide one option globally for your installation, which all installations will have to use. - -Windows Path Names ------------------- -Make based builds do not work properly when there are space characters or parentheses in the paths that are part of the build (including the path where the `make` application resides and the path of the workspace). - -If you cannot avoid paths with such characters, use the Windows short path (can be displayed with ``dir /x``) for all path components with those characters in any path settings and/or your workspace directory. - -Put Tools in the PATH ---------------------- -No matter which shell and environment you use, the tools (perl, make) should end up being in the ``%PATH%``, so that they are found when called just by their name. - -Install and Build ------------------ -Depending on your set of choices, the instructions for building EPICS Base, building IOC applications and running them are different. -The following detailed instructions focus on two common sets of choices: using MSYS2 with the MinGW Gnu compilers and using the plain Windows command prompt with the Visual Studio compilers. - -Setting the environment for building and running applications has to be done for either set of choices. - -.. toctree:: - :maxdepth: 1 - - installation-windows-msys2 - installation-windows-plain - installation-windows-env diff --git a/getting-started/installation.rst b/getting-started/installation.rst deleted file mode 100644 index 8e76681..0000000 --- a/getting-started/installation.rst +++ /dev/null @@ -1,296 +0,0 @@ -Installation on Linux/UNIX/DARWIN (Mac) -======================================= - -What is EPICS about? ------------------------------------ -We assume that you know more or less what EPICS is. Here we want to start -from scratch and get to the point where we have a working server, offering some -PVs for reading (caget or pvget) and writing -(caput or pvput), and we read and write on them from -another terminal, either on the same machine or on another one in the same -network. If you are going to use two different machines, you will have to -repeat the steps for installing EPICS for both of them. - -Prepare your system -------------------- - -You need ``make``, ``c++`` and ``libreadline`` to compile from source. On macOS these -dependencies can be installed by using e.g. ``homebrew``. On Linux you -can use ``apt-get install``. The :doc:`linux-packages` document lists all -of the packages required to build EPICS base, the sequencer, synApps modules, and areaDetector. - -Install EPICS -------------- - -:: - - mkdir $HOME/EPICS - cd $HOME/EPICS - git clone --recursive https://github.com/epics-base/epics-base.git - cd epics-base - make - -After compiling you should put the path into ``$HOME/.profile`` or into ``$HOME/.bashrc`` -by adding the following to either one of those files: - -:: - - export EPICS_BASE=${HOME}/EPICS/epics-base - export EPICS_HOST_ARCH=$(${EPICS_BASE}/startup/EpicsHostArch) - export PATH=${EPICS_BASE}/bin/${EPICS_HOST_ARCH}:${PATH} - -EpicsHostArch is a program provided by EPICS that returns the architecture -of your system. -Thus the code above should be fine for every architecture. - -Test EPICS ----------- -Now log out and log in again, so that your new path is set correctly. -Alternatively, you can execute the three lines above beginning with export -directly from the terminal. - -Run ``softIoc`` and, if everything is ok, you should see an EPICS prompt. - -:: - - softIoc - epics> - -You can exit with ctrl-c or by typing exit. - -Voilà. - -Ok, that is not very impressive, but at least you know that EPICS is -installed correctly. So now let us try something more complex, which will -hopefully suggest how EPICS works. - -In whatever directory you like, prepare a file test.db that -reads like - -:: - - record(ai, "temperature:water") - { - field(DESC, "Water temperature in the fish tank") - } - -This file defines a record instance called temperature:water, which -is an analog input (ai) record. As you can imagine DESC stays for -Description. Now we start softIoc again, but this time using this -record database. - -:: - - softIoc -d test.db - -Now, from your EPICS prompt, you can list the available records with the -dbl command and you will see something like - -:: - - epics> dbl - temperature:water - epics> - -Open a new terminal (we call it nr. 2) and try the command line tools -caget and caput. You will see something like -:: - - your prompt> caget temperature:water - temperature:water 0 - your prompt> caget temperature:water.DESC - temperature:water.DESC Water temperature in the fish tank - your prompt> caput temperature:water 21 - Old : temperature:water 0 - New : temperature:water 21 - your prompt> caput temperature:water 24 - Old : temperature:water 21 - New : temperature:water 24 - your prompt> caget temperature:water - temperature:water 24 - ... etc. - -Now open yet another terminal (nr. 3) and try ``camonitor`` as - -:: - - camonitor temperature:water - -First, have a look at what happens when you change the temperature:water -value from terminal nr. 2 using caput. Then, try to change the -value by some tiny amounts, like 15.500001, 15.500002, 15.500003… You will -see that camonitor reacts but the readings do not change. If you -wanted to see more digits, you could run - -:: - - camonitor -g8 temperature:water - -For further details on the Channel Access protocol, including documentation -on the ``caput``, ``caget``, ``camonitor``... command line tools, please refer to the -`Channel Access Reference Manual `_. - -In real life, however, it is unlikely that the 8 digits returned by your -thermometer (in this example) are all significant. We should thus limit the -traffic to changes of the order of, say, a hundredth of a degree. To do this, -we add one line to the file ``test.db``, so that it reads - -:: - - record(ai, "temperature:water") - { - field(DESC, "Water temperature in Lab 10") - field(MDEL, ".01") - } - -MDEL stands for Monitor Deadband. If you now run - -:: - - softIoc -d test.db - -with the new ``test.db`` file, you will see that -``camonitor`` reacts only to changes that are larger than 0.01. - -This was just a simple example. Please refer to a recent -`Record Reference Manual `_ -for further information. - -Create a demo/test ioc to test ca and pva ------------------------------------------ - -:: - - mkdir -p $HOME/EPICS/TEST/testIoc - cd $HOME/EPICS/TEST/testIoc - makeBaseApp.pl -t example testIoc - makeBaseApp.pl -i -t example testIoc - make - cd iocBoot/ioctestIoc - chmod u+x st.cmd - ioctestIoc> ./st.cmd - #!../../bin/darwin-x86/testIoc - < envPaths - epicsEnvSet("IOC","ioctestIoc") - epicsEnvSet("TOP","/Users/maradona/EPICS/TEST/testIoc") - epicsEnvSet("EPICS_BASE","/Users/maradona/EPICS/epics-base") - cd "/Users/maradona/EPICS/TEST/testIoc" - ## Register all support components - dbLoadDatabase "dbd/testIoc.dbd" - testIoc_registerRecordDeviceDriver pdbbase - ## Load record instances dbLoadTemplate "db/user.substitutions" - dbLoadRecords "db/testIocVersion.db", "user=junkes" - dbLoadRecords "db/dbSubExample.db", "user=junkes" - #var mySubDebug 1 - #traceIocInit - cd "/Users/maradona/EPICS/TEST/testIoc/iocBoot/ioctestIoc" - iocInit - Starting iocInit - ############################################################################ - ## EPICS R7.0.1.2-DEV - ## EPICS Base built Mar 8 2018 - ############################################################################ - iocRun: All initialization complete - 2018-03-09T13:07:02.475 Using dynamically assigned TCP port 52908. - ## Start any sequence programs - #seq sncExample, "user=maradona" - epics> dbl - maradona:circle:tick - maradona:compressExample - maradona:line:b - maradona:aiExample - maradona:aiExample1 - maradona:ai1 - maradona:aiExample2 - ... etc. ... - epics> - -Now in another terminal, one can try command line tools like - -:: - - caget, caput, camonitor, cainfo (Channel Access) - pvget, pvput, pvlist, eget, ... (PVAccess) - -Add the asyn package --------------------- -:: - - cd $HOME/EPICS - mkdir support - cd support - git clone https://github.com/epics-modules/asyn.git - cd asyn - -Edit ``$HOME/EPICS/support/asyn/configure/RELEASE`` and set -``EPICS_BASE`` like - -:: - - EPICS_BASE=${HOME}/EPICS/epics-base - -Comment ``IPAC=...`` and ``SNCSEQ=...``, as they are not -needed for the moment. The whole file should read: - -:: - - #RELEASE Location of external products - HOME=/Users/maradona - SUPPORT=$(HOME)/EPICS/support - -include $(TOP)/../configure/SUPPORT.$(EPICS_HOST_ARCH) - # IPAC is only necessary if support for Greensprings IP488 is required - # IPAC release V2-7 or later is required. - #IPAC=$(SUPPORT)/ipac-2-14 - # SEQ is required for testIPServer - #SNCSEQ=$(SUPPORT)/seq-2-2-5 - # EPICS_BASE 3.14.6 or later is required - EPICS_BASE=$(HOME)/EPICS/epics-base - -include $(TOP)/../configure/EPICS_BASE.$(EPICS_HOST_ARCH) - -Now, run -:: - - make - -Install StreamDevice (by Dirk Zimoch, PSI) ------------------------------------------- -:: - - cd $HOME/EPICS/support - git clone https://github.com/paulscherrerinstitute/StreamDevice.git - cd StreamDevice/ - rm GNUmakefile - -Edit ``$HOME/EPICS/support/StreamDevice/configure/RELEASE`` to specify the install location of EPICS base and of additional software modules, for example: -:: - - EPICS_BASE=${HOME}/EPICS/epics-base - SUPPORT=${HOME}/EPICS/support - ASYN=$(SUPPORT)/asyn - -Remember that ``$(NAME)`` works if it is defined within the same -file, but ``${NAME}`` with curly brackets must be used if a shell -variable is meant. It is possible that the compiler does not like some of the -substitutions. In that case, replace the ``${NAME}`` variables with -full paths, like ``/Users/maradona/EPICS...``. - -The sCalcout record is part of synApps. If streamDevice should be built with support for this record, you have to install at least the calc module from SynApps first. For now let's just comment out that line with ``#`` for it to be ignored. - -:: - #CALC=${HOME}/EPICS/support/synApps/calc - -If you want to enable regular expression matching, you need the PCRE package. For most Linux systems, it is already installed. In that case tell StreamDevice the locations of the PCRE header file and library. However, the pre-installed package can only by used for the host architecture. Thus, add them not to RELEASE but to RELEASE.Common.linux-x86 (if linux-x86 is your EPICS_HOST_ARCH). Be aware that different Linux distributions may locate the files in different directories. -:: - - PCRE_INCLUDE=/usr/include/pcre - PCRE_LIB=/usr/lib - -For 64 bit installations, the path to the library may be different: -:: - - PCRE_INCLUDE=/usr/include/pcre - PCRE_LIB=/usr/lib64 - -Again, if you're not interested in support for reular expression matching at this time then you can comment out any lines referring to PCRE in the ``configure/RELEASE`` file using a ``#``. It can always be added later. - -Finally run ``make`` (we are in the directory ``...EPICS/support/StreamDevice``) diff --git a/getting-started/linux-packages.rst b/getting-started/linux-packages.rst deleted file mode 100644 index 9f886de..0000000 --- a/getting-started/linux-packages.rst +++ /dev/null @@ -1,110 +0,0 @@ -Packages required for EPICS on Centos 8 -======================================= - -.. contents:: Contents - - -Overview --------- -This document describes the packages that must be installed in order to build EPICS base, -synApps, and areaDetector on a new Centos 8 system. -For other versions of Linux the package manager and package names may be different, -but the requirements are likely to be the same. - -Add the Extra Packages for Enterprise Linux (EPEL) site for the dnf package manager. -This site has additional packages that are needed:: - - sudo dnf install epel-release - -Enable the powertools repository by running:: - - sudo dnf config-manager --set-enabled powertools - -Or on CentOS 9 Stream by running:: - - sudo dnf config-manager --set-enabled crb - - -Packages required to build EPICS base -------------------------------------- - -:: - - sudo dnf install gcc gcc-c++ gcc-toolset-9-make readline-devel perl-ExtUtils-Install make - - -Packages required by the sequencer ----------------------------------- - -:: - - sudo dnf install re2c - -Packages required by epics-modules/asyn ---------------------------------------- - -:: - - sudo dnf install rpcgen libtirpc-devel - -Packages required by the Canberra and Amptek support in epics-modules/mca -------------------------------------------------------------------------- - -:: - - sudo dnf install libnet-devel libpcap-devel libusb-devel - -Packages required by the Linux drivers in epics-modules/measComp ----------------------------------------------------------------- - -:: - - sudo dnf install libnet-devel libpcap-devel libusb-devel - -Packages required by areaDetector/ADSupport/GraphicsMagick ----------------------------------------------------------- - -:: - - sudo dnf install xorg-x11-proto-devel libX11-devel libXext-devel - - -Packages required by areaDetector/ADEiger ------------------------------------------ - -:: - - sudo dnf install zeromq-devel - - -Packages required to build aravis 7.0.2 for areaDetector/ADAravis ------------------------------------------------------------------ - -:: - - sudo dnf install ninja-build meson glib2-devel libxml2-devel gtk3-devel gstreamer1 gstreamer1-devel gstreamer1-plugins-base-devel libnotify-devel gtk-doc gobject-introspection-devel - - -Packages required to build areaDetector/ADVimba ------------------------------------------------ - -:: - - sudo dnf install glibmm24-devel - - -Packages required to build EDM ------------------------------- - -:: - - sudo dnf install giflib giflib-devel zlib-devel libpng-devel motif-devel libXtst-devel - -Packages required to build MEDM ------------------------------- - -:: - - sudo dnf install libXt-devel motif-devel - - diff --git a/index.rst b/index.rst index b1a0bfd..f799b8a 100644 --- a/index.rst +++ b/index.rst @@ -3,59 +3,59 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +********************************** Welcome to the EPICS How-To Pages! -=================================== +********************************** -.. toctree:: - :hidden: +⚠️ https://docs.epics-controls.org/projects/how-tos/en/latest/ is now deprecated/archived in favor +of https://docs.epics-controls.org/en/latest/. - EPICS Website - EPICS Documents +ℹ️ All pages of https://docs.epics-controls.org/projects/how-tos/en/latest/ have been migrated to +https://docs.epics-controls.org/en/latest/. +ℹ️ All the existing links of https://docs.epics-controls.org/projects/how-tos/en/latest/ (listed +below) will now redirect you to the rigth pages in https://docs.epics-controls.org/en/latest/. -.. toctree:: - :maxdepth: 1 - :caption: Getting started +Getting started +*************** - getting-started/installation - getting-started/linux-packages.rst - getting-started/creating-ioc - getting-started/installation-windows +* `Installation on Linux/UNIX/DARWIN (Mac) `_ +* `Packages required for EPICS on Centos 8 `_ +* `Creation of an Input/Output Controller (IOC) `_ +* `Installation on Windows `_ +Building EPICS +************** -.. toctree:: - :maxdepth: 1 - :caption: Building EPICS +* `How To Port EPICS to a new OS/Architecture `_ +* `Getting Started with EPICS on RTEMS 4 `_ +* `Configuring vxWorks 6.x `_ +* `Configuring Tornado/vxWorks 5.5.x `_ +* `How To cross compile EPICS and a IOC to an old x86 Linux system `_ - building-epics/how-to-port-epics-to-a-new-os-architecture - Getting Started with EPICS on RTEMS 4 - building-epics/configuring-vxworks-6_x - building-epics/vxworks6_tornado - building-epics/cross-compile-epics-and-a-ioc-to-an-old-x86-linux +Applications +************ +* `Common Database patterns `_ -.. toctree:: - :maxdepth: 1 - :caption: Applications +Collaboration +************* - applications/common-database-patterns +* `How to run an EPICS Collaboration Meeting `_ +Writing Drivers and Device Support +********************************** -.. toctree:: - :maxdepth: 1 - :caption: Collaboration - - collaboration/how-to-run-an-epics-collaboration-meeting +* `How to Avoid Copying Arrays with waveformRecord `_ -.. toctree:: - :maxdepth: 1 - :caption: Writing Drivers and Device Support +Infrastructure and Other +************************ - writing-drivers/how-to-avoid-copying-arrays-with-waveformrecord +* `How to find which IOC provides a PV `_ .. toctree:: - :maxdepth: 1 - :caption: Infrastructure and Other + :hidden: - infrastructure-and-other/how-to-find-which-ioc-provides-a-pv + EPICS Website + EPICS Documents diff --git a/infrastructure-and-other/how-to-find-which-ioc-provides-a-pv.rst b/infrastructure-and-other/how-to-find-which-ioc-provides-a-pv.rst deleted file mode 100644 index 767bca2..0000000 --- a/infrastructure-and-other/how-to-find-which-ioc-provides-a-pv.rst +++ /dev/null @@ -1,101 +0,0 @@ -How to find which IOC provides a PV -=================================== - -This process is for IOCs running on Linux servers. - -Find Host and TCP port ----------------------- - -The ``cainfo`` command will tell you which host is serving a particular PV, and which TCP port number on that host is used. - -:: - - $ cainfo LN-TS{EVR:1A-SFP}Pwr:RX-I - LN-TS{EVR:1A-SFP}Pwr:RX-I - State: connected - Host: 10.0.152.111:5064 - Access: read, write - Native data type: DBF_DOUBLE - Request type: DBR_DOUBLE - Element count: 1 - -Here we see that the PV “LN-TS{EVR:1A-SFP}Pwr:RX-I” is served from port number 5064 of 10.0.152.111. - -:: - - $ cainfo LN-RF{AMP:1}Amp-Sts - LN-RF{AMP:1}Amp-Sts - State: connected - Host: linacioc01.cs.nsls2.local:36349 - Access: read, write - Native data type: DBF_ENUM - Request type: DBR_ENUM - Element count: 1 - - -Here is another example where the hostname is shown instead of an IP address. -Also this server has more than one IOC, and the one in question is using port 36349. - -Find which process is using a TCP port (Linux only) ---------------------------------------------------- -Super-user (root) permission is required to find which Linux process is bound to a particular TCP port. - -To continue the example from above. On the server linacioc01.cs.nsls2.local we run: - -:: - - $ sudo netstat -tlpn | grep 36349 - tcp 0 0 0.0.0.0:36349 0.0.0.0:* LISTEN 4627/s7ioc - -This tells us that TCP port 36349 is bound by process ID (PID) 4627, which has the process name of ‘s7ioc’. - -Find information about a process (Linux only) ---------------------------------------------- -The ``ps`` command can give some information, including the command used to start the process. -This often contains enough information to identify where the IOC’s files can be found. - -:: - - $ ps aux|grep 4627 - softioc 4627 1.5 0.0 93748 6616 pts/23 Ssl+ Jan07 744:18 ../../bin/linux-x86/s7ioc /epics/iocs/RF-CONTROL/iocBoot/iocrf-control/st.cmd - -There are several pieces of information available under ``/proc`` which are useful. -The entry ``/proc//cwd`` is a symbolic link to the current working directory of the process. -There is also ``/proc//exe`` which links to the executable. - -:: - - $ sudo ls -l /proc/4627/cwd - lrwxrwxrwx 1 softioc softioc 0 Feb 10 11:49 /proc/4627/cwd -> /epics/iocs/RF-CONTROL - $ sudo ls -l /proc/4627/exe - lrwxrwxrwx 1 softioc softioc 0 Jan 7 09:58 /proc/4627/exe -> /epics/iocs/RF-CONTROL/bin/linux-x86/s7ioc - -Additional: Finding the procServ/screen running an IOC (Linux only) -------------------------------------------------------------------- -The ``ps`` command can also tell us the PID of the parent of the IOC process. -The techniques of step 3 can also be applied to the parent. - -:: - - $ ps -eo pid,ppid,user,cmd|grep 4627 - 4627 4566 softioc ../../bin/linux-x86/s7ioc /epics/iocs/RF-CONTROL/iocBoot/iocrf-control/st.cmd - -The parent PID in the second column is 4566. - -:: - - $ ps aux|grep 4566 - softioc 4566 0.0 0.0 3452 592 ? Ss Jan07 2:18 /usr/bin/procServ -q -c /epics/iocs/RF-CONTROL/iocBoot/iocrf-control -i ^D^C^] -p /var/run/softioc-RF-CONTROL.pid -n RF-CONTROL --restrict --logfile=/var/log/softioc-RF-CONTROL.log 4057 /epics/iocs/RF-CONTROL/iocBoot/iocrf-control/st.cmd - -And to complete the circle, and get access to the IOC console, we find which TCP port this procServ instance is bound to. - -:: - - $ sudo netstat -tlpn|grep 4566 - tcp 0 0 127.0.0.1:4057 0.0.0.0:* LISTEN 4566/procServ - $ telnet localhost 4057 - epics> dbpr LN-RF{AMP:1}Amp-Sts - ASG: DESC: Ampl.500 MHz E-Source DISA: 0 - DISP: 0 DISV: 1 NAME: LN-RF{AMP:1}Amp-Sts - RVAL: 16 SEVR: NO_ALARM STAT: NO_ALARM SVAL: 0 - TPRO: 0 VAL: 1 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 59cc4f0..c6a2a70 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ sphinx_copybutton sphinx-hoverxref myst_parser +sphinx-reredirects diff --git a/writing-drivers/how-to-avoid-copying-arrays-with-waveformrecord.rst b/writing-drivers/how-to-avoid-copying-arrays-with-waveformrecord.rst deleted file mode 100644 index 5f35420..0000000 --- a/writing-drivers/how-to-avoid-copying-arrays-with-waveformrecord.rst +++ /dev/null @@ -1,234 +0,0 @@ -How to Avoid Copying Arrays with waveformRecord -=============================================== - -This page describes how to use the array field memory management feature that was introduced in EPICS 3.15.1. -This allows array data to be moved into and out of the value (aka BPTR) field of the waveform, aai, and aao types. - -Making use of this feature involves replacing the pointer stored in the BPTR field with another (user allocated) pointer. -The basic rules are: - -#. BPTR, and the memory it is currently pointing to, can only be accessed while the record is locked. -#. NELM may not be changed. -#. BPTR must always point to a piece of memory large enough to accommodate the maximum number of elements (as given by the NELM field). - -Rule #1 means that it is only safe to read, write, or de-reference the BPTR field from a device support function, or after manually calling dbScanLock(). -Rule #3 means that BPTR can never be set to NULL, and when replacing BPTR, the replacement must be allocated large enough for the worst case. -An external client may put an array of up to NELM elements to the field at almost any time. - -Example -####### - -:: - - /* Demonstration of using custom allocation for waveformRecord buffers. - * - * Requires EPICS Base 3.15.1 or newer - * - * This example makes inefficient use of malloc() and - * free(). This is done to make clear where new memory appears. - * In reality a free list should be used. - * - * Also be aware that this example will use 100% of the time of one CPU core. - * However, this will be spread across available cores. - * - * To use this example include the following in a DBD file: - * - * device(waveform,CONSTANT,devWfZeroCopy,"Zero Copy Demo") - * - * Also include a record instance - * - * record(waveform, "$(NAME)") { - * field(DTYP, "Zero Copy Demo") - * field(FTVL, "SHORT") - * field(NELM, "100") - * field(SCAN, "I/O Intr") - * } - */ - - #include - #include - #include - #include - #include - #include - #include - #include - #include - #include - #include - #include - #include - - #include - - static ELLLIST allPvt = ELLLIST_INIT; - - struct devicePvt { - ELLNODE node; - - /* synchronize access to this structure */ - epicsMutexId lock; - /* wakeup the worker when another update is needed */ - epicsEventId wakeup; - /* notify the scanner thread when another update is available */ - IOSCANPVT scan; - - /* the next update */ - void *nextBuffer; - epicsUInt32 maxbytes, numbytes; - }; - - static void startWorkers(initHookState); - - static long init(int phase) - { - if(phase!=0) - return 0; - initHookRegister(&startWorkers); - return 0; - } - - static long init_record(waveformRecord *prec) - { - struct devicePvt *priv; - if(prec->ftvl!=menuFtypeSHORT) { - errlogPrintf("%s.FTVL must be set to SHORT for this example\n", prec->name); - return 0; - } - - /* cleanup array allocated by record support. - * Not necessary since we use calloc()/free(), - * but needed when allocating in other ways. - */ - free(prec->bptr); - prec->bptr = callocMustSucceed(prec->nelm, dbValueSize(prec->ftvl), "first buf"); - - priv = callocMustSucceed(1, sizeof(*priv), "init_record devWfZeroCopy"); - priv->lock = epicsMutexMustCreate(); - priv->wakeup = epicsEventMustCreate(epicsEventFull); - scanIoInit(&priv->scan); - priv->maxbytes = prec->nelm*dbValueSize(prec->ftvl); - - ellAdd(&allPvt, &priv->node); - - prec->dpvt = priv; - return 0; - } - - static void worker(void*); - - static void startWorkers(initHookState state) - { - ELLNODE *cur; - /* Don't start worker threads until - * it is safe to call scanIoRequest() - */ - if(state!=initHookAfterInterruptAccept) - return; - for(cur=ellFirst(&allPvt); cur; cur=ellNext(cur)) - { - struct devicePvt *priv = CONTAINER(cur, struct devicePvt, node); - epicsThreadMustCreate("wfworker", - epicsThreadPriorityHigh, - epicsThreadGetStackSize(epicsThreadStackSmall), - &worker, priv); - } - } - - static void worker(void* raw) - { - struct devicePvt *priv=raw; - void *buf = NULL; - epicsUInt32 nbytes = priv->maxbytes; - - while(1) { - - if(!buf) { - /* allocate and initialize a new buffer for later (local) use */ - size_t i; - epicsInt16 *ibuf; - buf = callocMustSucceed(1, nbytes, "buffer"); - ibuf = (epicsInt16*)buf; - for(i=0; iwakeup, 1.0)==epicsEventError) { - cantProceed("worker encountered an error waiting for wakeup\n"); - } - - epicsMutexMustLock(priv->lock); - - if(!priv->nextBuffer) { - /* make the local buffer available to the read_wf function */ - priv->nextBuffer = buf; - buf = NULL; - priv->numbytes = priv->maxbytes; - scanIoRequest(priv->scan); - } - - epicsMutexUnlock(priv->lock); - } - } - - static long get_iointr_info(int dir, dbCommon *prec, IOSCANPVT *scan) - { - struct devicePvt *priv=prec->dpvt; - if(!priv) - return 0; - *scan = priv->scan; - /* wakeup the worker when this thread is placed in the I/O scan list */ - if(dir==0) - epicsEventSignal(priv->wakeup); - return 0; - } - - static long read_wf(waveformRecord *prec) - { - struct devicePvt *priv=prec->dpvt; - if(!priv) - return 0; - - epicsMutexMustLock(priv->lock); - - if(priv->nextBuffer) { - /* an update is available, so claim it. */ - - if(prec->bptr) - free(prec->bptr); - - prec->bptr = priv->nextBuffer; /* no memcpy! */ - priv->nextBuffer = NULL; - prec->nord = priv->numbytes / dbValueSize(prec->ftvl); - - epicsEventSignal(priv->wakeup); - } - - epicsMutexUnlock(priv->lock); - - assert(prec->bptr); - - return 0; - } - - static - struct dset5 { - dset com; - DEVSUPFUN read; - } devWfZeroCopy = { - {5, NULL, - &init, - &init_record, - &get_iointr_info - }, - &read_wf - }; - - #include - - epicsExportAddress(dset, devWfZeroCopy);