Channel Access < kazuro.furukawa @ kek.jp > Introduction to Channel Access Kazuro Furukawa <kazuro.furukawa@kek.jp> for EPICS Seminar at J-PARC March 14, 2012 Based on presentations by Kenneth Evans, Jr., 2004 Kazuro Furukawa, 2006 Kay Kasemir, 2007 Kazuro Furukawa, 2010 <http://www-linac.kek.jp/cont/epics/> EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 1 Channel Access 概要 Controls Channel Access Concepts Channel Access API Simple CA Client Simple CA Client with Callbacks (EPICS Build System) EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 2 Channel Access 加速器の制御 なぜ制御が必要か、制御で何をするのか 粒子の軌道を変えるための電磁石の制御の例から 考えてみよう EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 3 Channel Access 電磁石を使って粒子の軌道を制御しよう (1) まずお試し用の電磁石で練習しようか 電流変更するためのつまみと電流メータを使おう 去年測った電流と磁場の関係のグラフを探さなきゃ… 見つけたけど、いちいち読み取るのは面倒だなあ… メータの針では精度がないからデジタル表示にしよう PC で軌道計算をしてから設定しなくちゃ あれ、電源がオフになった なんだコイルの熱を冷やすのに水を流すのか… 水の表示器を置いておこう 間違って電流値を大き掛け過ぎたら、またオフになった 電源を壊さないように過電流の制限に引っかかったんだ さっきと同じ電流値にしても正しい磁場にならないぞ 鉄芯のヒステリシスで電流と磁場の関係が変わっちゃった 電流を上げたり下げたりして初期化しよう EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 4 Channel Access 電磁石を使って粒子の軌道を制御しよう (2) 本物の粒子の軌道を曲げてみよう あれ、本物の電磁石は 1km も離れているのか しょうがない配線しよう あれ、電磁石って何百台もあるの、ひえっー とても全部配線できないよ しょうがない、切り替え器を使って一個のつまみと一個のメータでたくさんの 電磁石を扱えるようにしよう あったまいいー 入射器からリングに粒子を入射してと あれ、うまく周回してくれないよ ビームモニタの情報を PC に送って、軌道計算して、電磁石の磁場を調整し なくちゃ ええっ、何百台もの電磁石の、制限値に注意して、磁場特性の変換をして、一度に、設定 しなくてはいけないの そんなことひとりでできないよ… EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 5 Channel Access 粒子を制御しよう というわけで、 制御インターフェース群:加速器装置の情報解釈など ネットワーク:情報伝送、タイミング伝送 計算機群:軌道計算、情報管理 (表示、操作、記録) など を使うことになった 制御システムを使用すれば ビームモニタからの情報を参照して、 シミュレーション計算結果と比較して、 マイクロ波装置や偏向、収束、補正電磁石などを操作して、 粒子ビームを自在に操り、 粒子加速器の性能を最大限に発揮して みんなに有効な実験結果を導くことが可能、かも... EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 6 Channel Access KEKB Operation Improvement (base of SuperKEKB) Belle/KEK May.2000 Apr.2003 Dual Bunch e+ Feb.2005 Continuous Injections Dec.2008 Crab Cavities and Simultaneous Injection EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 7 Channel Access 大型物理実験装置 数十人から数千人規模の研究者が関わる物理実験装置 素粒子物理学実験、光学・電波天文台、プラズマ核融合、など ほとんどが国際協力で予算獲得、建設、運用 例えば、素粒子のジュネーブ CERN/LHC、核融合のカダラッシュ ITER、天文のチリ ALMA などアジア、ヨーロッパ、アメリカの国際協力 で実現しているものは多い 関連した国際会議が開かれている、来年 10 月は米国 (サンフランシスコ) LHC/CERN EPICS Seminar at J-PARC ITER/JAEA Kazuro Furukawa, KEK, Mar.2012. 8 Channel Access 制御システムの目標 (の例) 信頼性が高くかつ柔軟な制御処理機構を道具として 提供する 性能を高めるための (実時間) 自動処理 モデリング・シミュレーション 新しい問題に対する迅速な対処 情報の交換・管理 データ解析 安全機構 EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 9 Channel Access EPICS たくさんの制御システムが同じ問題を抱えていたのに、違う ハードウェア/ソフトウェアを使い違った方法で解決しようとして いた そこで EPICS が開発された ほとんどの制御についての要求が満たされる Closed Loop / Open Loop Logical Value Conversion Synchronous / Asynchronous Programless / Performance Display / Archive / Analysis EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 10 Channel Access KEKB and Controls 制御用ソフトウェア EPICS 以前はほとんどが内製ソフトウェアの組み合わせ RPC, CORBA, … 徐々に共通ソフトウェアに移行してきた KEK では 1994 年から “EPICS” と呼ばれる国際共同開発のソフトウェアへ BSD-like な Open-source、多数の研究所が採用 SCADA や Labview などとほぼ同等またはそれ以上の機能 他に CORBA を基本としたものなどもある 当初は中間層と全体制御の間で EPICS を利用していた 現在は小型コントローラにも内蔵するようになってきている 最近 ITER (プラズマ核融合) も採用を決める 上位ソフトウェアはスクリプト言語で書かれるものも多い 粒子加速器の物理の記述が行えて Mathematica 文法に近い “SADscript” とい うソフトウェアが多用される 他に Python や Perl、Tcl なども 下位ソフトウェアは C++ や C が多い EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 11 Channel Access EPICS EPICS を使用すると これまで各研究所で作られていた制御のためのプログラムを個別に書 いたり、保守したりする必要がなくなる よりよく考慮された設計になっている可能性が高い 当初は考えていなかった制御が必要になることは多い 多様な制御方式に対応できる 多様なアプリケーションプログラムを使用できる 他のグループからの支援を得られる可能性がある 国際的に貢献できる可能性がある x 最新のソフトウェア技術の利用が制限される オブジェクト指向プログラミング、CORBA、とか 部分的に使用することは可能 EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 12 Channel Access チャネルアクセスの参考書 以降の Slide は Channel Access (CA) の概略説明 より深く調べるときには EPICS の web page を覗いてみる http://www.aps.anl.gov/epics/index.php Look under Documents Also under Base, then a specific version of Base EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 15 Channel Access EPICS システムの構成 MEDM MEDM Client Client Client MEDM Channel Access Server EPICS Seminar at J-PARC IOC IOC IOC Meter Power Supply Camera Kazuro Furukawa, KEK, Mar.2012. 16 Channel Access Search and Connect の手続き MEDM MEDM Client Client Client MEDM 3. TCP Connection Let’s talk ! 2. UDP Reply 1. UDP Broadcast Sequence Who has it ? I have it ! Server Check EPICS Seminar at J-PARC IOC Check IOC Check IOC IOC Check Meter Power Supply Camera Kazuro Furukawa, KEK, Mar.2012. 17 Channel Access Channel Access の動作 “connection request” or “search request” Channel Access Client Who has a PV named “S1A:H1:CurrentAO”? “get” or “caget” What is its value? “put” or “caput” “set a monitor” Change its value to 30.5 Notify me when the value changes CA Client CA Server Channel Access Server I do. 25.5 AMPS Process Variables: OK, it is now 30.5 It is now 20.5 AMPS It is now 10.5 AMPS It is now 0.0023 AMPS “put complete” S1A:H1:CurrentAO S1:P1:x or S1:P1:y S1:G1:vacuum EPICS Seminar at J-PARC or 30.5 is too high. It is now set to the maximum value of 27.5. “post an event” or “post a monitor” You are not authorized to change this value Kazuro Furukawa, KEK, Mar.2012. 18 Channel Access Search 要求 Client からの Search 要求は UDP の Packet から成る Only goes to EPICS_CA_ADDR_LIST Starts with a small interval (30 ms), that doubles each time Until it gets larger than 5 s, then it stays at 5 s Stops after 100 packets or when it gets a response Never tries again until it sees a beacon anomaly or creates a new PV Total time is about 8 minutes to do all 100 全ての Server は指定 PV が存在するかどうか調べる 普通は最初 (または少数の) の要求 Packet で接続が確立できる 存在しない PV を要求すると、多量の Traffic を生じる Try to eliminate them EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 20 Channel Access Beacon Beacon は Server から送られる UDP broadcast packet 正常時には, 個々の Server は一定時間間隔で UDP Beacon を broadcast する (like a heartbeat) EPICS_CA_BEACON_PERIOD, 15 s by default Server の起動時には, Server は連続した UDP beacon を broadcast する Starts with a small interval (25 ms, 75 ms for VxWorks) Interval doubles each time Until it gets larger than 15 s, then it stays at 15 s Takes about 10 beacons and 40 s to get to steady state Client はその beacon を監視し続ける Determine connection status, whether to reissue searches EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 21 Channel Access Virtual Circuit の切断 3.14 5 and later Hang-up message from server TCP connection is closed MEDM screens go white Clients reissue search requests EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 22 Channel Access Virtual Circuit の無応答 3.14.5 and later No response from server for 30 sec. Client then sends “Are you there” query If no response for 5 sec, TCP connection is not closed For several hours, at least MEDM screens go white Clients do not reissue search requests Helps with network storms Clients that do not call ca_poll frequently get a virtual circuit disconnect even though the server may be OK Clients written for 3.13 but using 3.14 may have a problem May be changed in future versions EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 23 Channel Access 重要な環境変数 (Environment Variable) EPICS_CA_ADDR_LIST Determines where to search Is a list (separated by spaces) “123.45.1.255 123.45.2.14 123.45.2.108” Default is broadcast addresses of all interfaces on the host Works when servers are on same subnet as Clients Broadcast address Goes to all servers on a subnet Example: 123.45.1.255 Use ifconfig –a on UNIX to find it (or ask an administrator) EPICS_CA_AUTO_ADDR_LIST YES: Include default addresses above in searches NO: Do not search on default addresses If you set EPICS_CA_ADDR_LIST, usually set this to NO EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 24 Channel Access EPICS_CA_ADDR_LIST MEDM MEDM Client Client Client Broadcast Specific 123.45.1.255 123.45.2.108 Subnet 1 Server EPICS Seminar at J-PARC MEDM Subnet 2 IOC Not Included IOC IOC Meter Power Supply Camera Kazuro Furukawa, KEK, Mar.2012. 25 Channel Access その他の環境変数 CA Client CA Server EPICS_CA_ADDR_LIST EPICS_CA_AUTO_ADDR_LIST EPICS_CA_CONN_TMO EPICS_CA_BEACON_PERIOD EPICS_CA_REPEATER_PORT EPICS_CA_SERVER_PORT EPICS_CA_MAX_ARRAY_BYTES EPICS_TS_MIN_WEST EPICS_CAS_SERVER_PORT EPICS_CAS_AUTO_BEACON_ADDR_LIS T EPICS_CAS_BEACON_ADDR_LIST EPICS_CAS_BEACON_PERIOD EPICS_CAS_BEACON_PORT EPICS_CAS_INTF_ADDR_LIST EPICS_CAS_IGNORE_ADDR_LIST さらに詳しくは Channel Access Reference Manual を参照 EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 26 Channel Access Release 3.13 の 3.14 の似ている部分 EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 27 Channel Access Release 3.13 と 3.14 の違い 3.14 is threaded Your program does not have to be threaded 3.14 has different names for some functions ca_context_create for ca_task_initialize ca_context_destroy for ca_task_exit ca_create_channel for ca_search_and_connect ca_create_subscription for ca_add_event ca_clear_subscription for ca_clear_event The new functions may have more capabilities, usually related to threading We will use the new names 3.14 has a different mechanism for lost connections Virtual circuit unresponsive (Not available in 3.13) Virtual circuit disconnected EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 28 Channel Access EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 29 Channel Access EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 30 Channel Access EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 31 Channel Access CA (Channel Access) の API (Application Program Interface) The main CA client interface is the "C" library that comes with EPICS base Internally uses C++, but API is pure C. Almost all other CA client interfaces use that C library Exception: New pure Java JAC EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 32 Channel Access 基本的な Channel Access Client の手続き Initialize Channel Access ca_task_initialize or ca_context_create Search ca_search_and_connect or ca_create_channel Do get or put ca_get or ca_put Monitor ca_add_event or ca_create_subscription Give Channel Access a chance to work ca_poll, ca_pend_io, ca_pend_event Clear a channel ca_clear_channel Close Channel Access ca_task_exit or ca_context_destroy EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 33 Channel Access cadef.h All C or C++ programs must include cadef.h #include <cadef.h> You can look at this file to get more insight into Channel Access This presentation will use C examples We will try to emphasize concepts, not the language Even if you do not use C, it is important to understand what is going on behind what you do use EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 34 Channel Access ca_context_create enum ca_preemptive_callback_select { ca_disable_preemptive_callback, ca_enable_preemptive_callback }; int ca_context_create ( enum ca_preemptive_callback_select SELECT ); Should be called once prior to any other calls Sets up Channel Access Use SELECT=ca_disable_preemptive_callback Unless you intend to do threads Can also use ca_task_initialize() for 3.13 compatibility EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 35 Channel Access ca_context_destroy void ca_context_destroy (); Should be called before exiting your program Shuts down Channel Access Can also use ca_task_exit() for 3.13 compatibility EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 36 Channel Access ca_create_channel typedef void caCh (struct connection_handler_args ARGS); int ca_create_channel ( const char *PVNAME, caCh *CALLBACK, void *PUSER, capri PRIORITY, chid *PCHID ); Sets up a channel and starts the search process PVNAME is the name of the process variable CALLBACK is the name of your connection callback (or NULL) The callback will be called whenever the connection state changes, including when first connected Information about the channel is contained in ARGS Use NULL if you don’t need a callback EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 37 Channel Access ca_create_channel, cont’d typedef void caCh (struct connection_handler_args ARGS); int ca_create_channel ( const char *PVNAME, caCh *CALLBACK, void *PUSER, capri PRIORITY, chid *PCHID ); PUSER is a way to pass additional information Whatever you have stored at this address It is stored in the chid In C++ it is often the this pointer for a class Use NULL if you don’t need it Use PRIORITY=CA_PRIORITY_DEFAULT EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 38 Channel Access ca_create_channel, cont’d typedef void caCh (struct connection_handler_args ARGS); int ca_create_channel ( const char *PVNAME, caCh *CALLBACK, void *PUSER, capri PRIORITY, chid *PCHID ); A chid is a pointer to (address of) an opaque struct used by Channel Access to store much of the channel information chanId is the same as chid (typedef chid chanId;) PCHID is the address of the chid pointer (Use &CHID) You need to allocate space for the chid before making the call Channel Access will allocate space for the struct and return the address EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 39 Channel Access ca_create_channel, cont’d typedef void caCh (struct connection_handler_args ARGS); int ca_create_channel ( const char *PVNAME, caCh *CALLBACK, void *PUSER, capri PRIORITY, chid *PCHID ); Use macros to access the information in the chid ca_name(CHID) gives the process variable name ca_state(CHID) gives the connection state ca_puser(CHID) gives the PUSER you specified Etc. The ARGS struct in the connection callback includes the chid Can also use ca_search_and connect() for 3.13 compatibility EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 40 Channel Access ca_clear_channel int ca_clear_channel (chid CHID); Shuts down a channel and reclaims resources Should be called before exiting the program CHID is the same chid used in ca_create_channel EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 41 Channel Access ca_array_get int ca_array_get ( chtype TYPE, unsigned long COUNT, chid CHID, void *PVALUE ); Requests a scalar or array value from a process variable Typically followed by ca_pend_io TYPE is the external type of your variable Use one of the DBR_xxx types in db_access.h E.g. DBR_DOUBLE or DBR_STRING COUNT is the number of array elements to read CHID is the channel identifier from ca_create_channel PVALUE is where you want the value(s) to go There must be enough space to hold the values EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 42 Channel Access ca_array_get_callback typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_array_get_callback ( chtype TYPE, unsigned long COUNT, chid CHID, pCallBack USERFUNC, void *USERARG ); Requests a scalar or array value from a process variable, using a callback TYPE is the external type of your variable Use one of the DBR_xxx types in db_access.h E.g. DBR_DOUBLE or DBR_STRING COUNT is the number of array elements to read EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 43 Channel Access ca_array_get_callback, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_array_get_callback ( chtype TYPE, unsigned long COUNT, chid CHID, pCallBack USERFUNC, void *USERARG ); CHID is the channel identifier from ca_create_channel USERFUNC is the name of your callback to be run when the operation completes USERARG is a way to pass additional information to the callback struct event_handler_args has a void *usr member EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 44 Channel Access ca_array_put int ca_array_put ( chtype TYPE, unsigned long COUNT, chid CHID, const void *PVALUE); Requests writing a scalar or array value to a process variable Typically followed by ca_pend_io TYPE is the external type of your supplied variable Use one of the DBR_xxx types in db_access.h E.g. DBR_DOUBLE or DBR_STRING COUNT is the number of array elements to write CHID is the channel identifier from ca_create_channel PVALUE is where the value(s) to be written are found EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 45 Channel Access ca_array_put_callback typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_array_put_callback ( chtype TYPE, unsigned long COUNT, chid CHID, const void *PVALUE, pCallBack USERFUNC, void *USERARG ); Requests writing a scalar or array value to a process variable, using a callback TYPE is the external type of your variable Use one of the DBR_xxx types in db_access.h E.g. DBR_DOUBLE or DBR_STRING EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 46 Channel Access ca_array_put_callback, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_array_put_callback ( chtype TYPE, unsigned long COUNT, chid CHID, const void *PVALUE, pCallBack USERFUNC, void *USERARG ); COUNT is the number of array elements to write CHID is the channel identifier from ca_create_channel PVALUE is where the value(s) to be written are found EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 47 Channel Access ca_array_put_callback, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_array_put_callback ( chtype TYPE, unsigned long COUNT, chid CHID, const void *PVALUE, pCallBack USERFUNC, void *USERARG ); USERFUNC is the name of your callback to be run when the operation completes USERARG is a way to pass additional information to the callback struct event_handler_args has a void *usr member EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 48 Channel Access ca_create_subscription typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_create_subscription ( chtype TYPE, unsigned long COUNT, chid CHID, unsigned long MASK, pCallBack USERFUNC, void *USERARG, evid *PEVID ); Specify a callback function to be invoked whenever the process variable undergoes significant state changes Value, Alarm status, Alarm severity This is the way to monitor a process variable EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 49 Channel Access ca_create_subscription, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_create_subscription ( chtype TYPE, unsigned long COUNT, chid CHID, unsigned long MASK, pCallBack USERFUNC, void *USERARG, evid *PEVID ); TYPE is the external type you want returned Use one of the DBR_xxx types in db_access.h E.g. DBR_DOUBLE or DBR_STRING COUNT is the number of array elements to monitor EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 50 Channel Access ca_create_subscription, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_create_subscription ( chtype TYPE, unsigned long COUNT, chid CHID, unsigned long MASK, pCallBack USERFUNC, void *USERARG, evid *PEVID ); CHID is the channel identifier from ca_create_channel MASK has bits set for each of the event trigger types requested DBE_VALUE DBE_LOG DBE_ALARM EPICS Seminar at J-PARC Value changes Exceeds archival deadband Alarm state changes Kazuro Furukawa, KEK, Mar.2012. 51 Channel Access ca_create_subscription, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_create_subscription ( chtype TYPE, unsigned long COUNT, chid CHID, unsigned long MASK, pCallBack USERFUNC, void *USERARG, evid *PEVID ); USERFUNC is the name of your callback to be run when the state change occurs USERARG is a way to pass additional information to the callback struct event_handler_args has a void *usr member EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 52 Channel Access ca_create_subscription, cont’d typedef void ( *pCallBack ) (struct event_handler_args ARGS); int ca_create_subscription ( chtype TYPE, unsigned long COUNT, chid CHID, unsigned long MASK, pCallBack USERFUNC, void *USERARG, evid *PEVID ); PEVID is the address of an evid (event id) You need to allocate space for the evid before making the call Similar to a chid Only used to clear the subscription (Can be NULL if not needed) EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 53 Channel Access ca_clear_subscription int ca_clear_subscription ( evid EVID ); Used to remove a monitor callback EVID is the evid from ca_create_subscription EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 54 Channel Access ca_add_exception_event typedef void (*pCallback) (struct exception_handler_args ARGS ); int ca_add_exception_event ( pCallback USERFUNC, void *USERARG ); Used to replace the default exception handler USERFUNC is the name of your callback to be run when an exception occurs Use NULL to remove the callback USERARG is a way to pass additional information to the callback struct exception_handler_args has a void *usr member EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 55 Channel Access Request Handling The preceding routines are requests They only queue the operation They hardly ever fail The return values are almost always ECA_NORMAL (But they should be checked) These requests are only processed when one of the following is called ca_pend_io ca_pend_event ca_poll Blocks until requests are processed Blocks a specified time Processes current work only If these routines are not called, the requests are not processed and background tasks are also not processed The rule is that one of these should be called every 100 ms To allow processing of background tasks (beacons, etc.) EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 56 Channel Access ca_pend_io int ca_pend_io (double TIMEOUT); Flushes the send buffer Blocks for up to TIMEOUT seconds until Outstanding gets complete Searches with no callback have connected Returns ECA_NORMAL when gets and searches are complete Returns ECA_TIMEOUT otherwise Means something went wrong Get requests can be reissued Search requests can be reissued after ca_clear_channel Channel Access background tasks are performed Unless there were no outstanding I/O requests Use with searches, gets, and puts that don’t use callbacks EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 57 Channel Access ca_pend_event int ca_pend_event (double TIMEOUT); Flushes the send buffer Process background tasks for TIMEOUT seconds Does not return until TIMEOUT seconds have elapsed Use this when your application doesn’t have to do anything else Use ca_pend_event instead of sleep EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 58 Channel Access ca_poll int ca_poll (); Flushes the send buffer Process outstanding tasks only Exits when there are no more outstanding tasks Otherwise similar to ca_pend_event Use this when your application has other things to do E.g. most GUI programs Be sure it is called at least every 100 ms EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 59 Channel Access CHID Macros chtype ca_field_type ( CHID ); unsigned ca_element_count ( CHID ); char *ca_name ( CHID ); void *ca_puser ( CHID ); void ca_set_puser ( chid CHID, void *PUSER ); enum channel_state ca_state ( CHID ); enum channel_state { cs_never_conn, Valid chid, server not found or unavailable cs_prev_conn, Valid chid, previously connected to server cs_conn, Valid chid, connected to server cs_closed }; Channel deleted by user char *ca_host_name ( CHID ); int ca_read_access ( CHID ); int ca_write_access ( CHID ); EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 60 Channel Access ca_connection_handler_args struct ca_connection_handler_args { chanId chid; Channel id long op; CA_OP_CONN_UP or CA_OP_CONN_DOWN }; Used in connection callback Note chanId is used rather than chid Some compilers don’t like chid chid; EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 61 Channel Access event_handler_args typedef struct event_handler_args { void *usr; User argument supplied with request chanId chid; Channel ID long type; The type of the item returned long count; The element count of the item returned const void *dbr; A pointer to the item returned int status; ECA_xxx status of the requested op } evargs; Used in get, put, and monitor callbacks Do not use the value in dbr if status is not ECA_NORMAL EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 62 Channel Access Channel Access API 関数の一覧 ca_add_exception_event ca_attach_context ca_clear_channel ca_clear_subscription ca_client_status ca_context_create ca_context_destroy ca_context_status ca_create_channel ca_create_subscription ca_current_context ca_dump_dbr() ca_element_count ca_field_type ca_flush_io ca_get ca_host_name ca_message ca_name ca_read_access ca_replace_access_rights_event ca_replace_printf_handler ca_pend_event ca_pend_io ca_poll ca_puser ca_put ca_set_puser ca_signal ca_sg_block ca_sg_create ca_sg_delete ca_sg_get ca_sg_put ca_sg_reset ca_sg_test ca_state ca_test_event ca_test_io ca_write_access channel_state dbr_size[] dbr_size_n dbr_value_size[] dbr_type_to_text SEVCHK ca_search ca_search_and_connect ca_task_exit ca_task_initialize Deprecated ca_add_event ca_clear_event EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 63 Channel Access Ubuntu で試してみよう Warning Bellow should be tried without real network Normally, you should follow the institute rules Running “excas” all the time is bad Boot Ubuntu Linux from USB memory Applications -> Accessories -> Terminal sudo ifconfig eth0 192.168.1.2 ping 192.168.1.2 excas –p z: & caget z:fred z:freddy z:jane z:janet After you finish killall excas EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 64 Channel Access makeBaseApp.pl を使えば簡単 Includes a template for basic CA client in C: Start with this: echo $PATH $EPICS_HOST_ARCH $EPICS_CA_ADDR_LIST cd ; mkdir cac ; cd cac makeBaseApp.pl -t caClient cacApp make 2>&1 | tee make.log Result: bin/linux-x86/caExample <some PV> bin/linux-x86/caMonitor <file with PV list> cd bin/linux-x86 ./caExample z:fred echo z:fred > alist echo z:freddy >> alist ./caMonitor alist Then read the sources, compare with the reference manual, and edit/extend to suit your needs. EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 65 Channel Access makeBaseApp の caExample.c Minimal CA client program. Fixed timeout, waits until data arrives. Requests everything as 'DBR_DOUBLE'. … which results in values of C-type 'double'. See db_access.h header file for all the DBR_… constants and the resulting C types or structures. In addition to the basic DBR_<type> requests, it is possible to request packaged attributes like DBR_CTRL_<type> to get { value, units, limits, …} in one request. EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 66 Channel Access makeBaseApp の caMonitor.c Better CA client program. Registers callbacks to get notified when connected ot disconnected Subscribes to value updates instead of waiting. … but still uses the same data type (DBR_STRING) for everything. EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 67 Channel Access 理想的な CA client? Use callbacks for everything no idle 'wait', no fixed time outs. Upon connection, check the channel's native type (int, double, string, …) to limit the type conversion burden on the IOC. … request the matching DBR_CTRL_<type> once to get the full channel detail (units, limits, …). … and then subscribe to DBR_TIME_<type> to get updates of only time/status/value so now we always stay informed, yet limit the network traffic. Only subscribe once, not with each connection, because CA client library will automatically re-activate subscriptions! This is what EDM, archiver, … do. Quirk: They don't learn about online changes of channel limits, units, …. Doing that via a subscription means more network traffic, and CA doesn't send designated events for 'meta information changed'. EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 68 Channel Access Simple CA Client Defines and includes /* Simple CA client */ #define #define #define #define #include #include #include #include TIMEOUT 1.0 SCA_OK 1 SCA_ERR 0 MAX_STRING 40 <stdio.h> <stdlib.h> <string.h> <cadef.h> EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 69 Channel Access Simple CA Client Function prototypes and global variables /* Function prototypes */ int main(int argc, char **argv); static int parseCommand(int argc, char **argv); static void usage(void); /* Global variables */ int pvSpecified=0; char name[MAX_STRING]; char value[MAX_STRING]; double timeout=TIMEOUT; EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 70 Channel Access Simple CA Client Parse the command line int main(int argc, char **argv) { int stat; chid pCh; /* Parse the command line */ if(parseCommand(argc,argv) != SCA_OK) exit(1); if(!pvSpecified) { printf("No PV specified\n"); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 71 Channel Access Simple CA Client Initialize Channel Access /* Initialize */ stat=ca_context_create(ca_disable_preemptive_callback); if(stat != ECA_NORMAL) { printf("ca_context_createfailed:\n%s\n", ca_message(stat)); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 72 Channel Access Simple CA Client Request the search /* Search */ stat=ca_create_channel(name,NULL,NULL, CA_PRIORITY_DEFAULT,&pCh); if(stat != ECA_NORMAL) { printf("ca_create_channel failed:\n%s\n", ca_message(stat)); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 73 Channel Access Simple CA Client Call ca-pend_io to process the search /* Process search */ stat=ca_pend_io(timeout); if(stat != ECA_NORMAL) { printf(“search timed out after %g sec\n", timeout); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 74 Channel Access Simple CA Client Request the get /* Get the value */ stat=ca_array_get(DBR_STRING,1,pCh,&value); if(stat != ECA_NORMAL) { printf("ca_array_get:\n%s\n", ca_message(stat)); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 75 Channel Access Simple CA Client Call ca_pend_io to process the get /* Process get */ stat=ca_pend_io(timeout); if(stat != ECA_NORMAL) { printf(“get timed out after %g sec\n", timeout); exit(1); } printf("The value of %s is %s\n",name,value) EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 76 Channel Access Simple CA Client Clean up /* Clear the channel */ stat=ca_clear_channel(pCh); if(stat != ECA_NORMAL) { printf("ca_clear_channel failed:\n%s\n", ca_message(stat)); } /* Exit */ ca_context_destroy(); return(0); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 77 Channel Access SEVCHK For simple error handling in test programs SEVCHK ( <function call>, “message” ) Macro that checks return codes If error, displays message and aborts Used in example programs DON’T use for robust clients EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 78 Channel Access Simple CA Client Output simplecaget evans:calc The value of evans:calc is 6 EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 79 Channel Access Simple CA Client with Callbacks Defines and includes /* Simple CA client with Callbacks */ #define #define #define #define TIMEOUT 1.0 SCA_OK 1 SCA_ERR 0 MAX_STRING 40 #include #include #include #include #include <stdio.h> <stdlib.h> <time.h> <string.h> <cadef.h> EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 80 Channel Access Simple CA Client with Callbacks Function prototypes /* Function prototypes */ int main(int argc, char **argv); static void connectionChangedCB(struct connection_handler_args args); static void valueChangedCB(struct event_handler_args args); static char *timeStamp(void); static int parseCommand(int argc, char **argv); static void usage(void); EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 81 Channel Access Simple CA Client with Callbacks Global variables /* Global variables */ int pvSpecified=0; char name[MAX_STRING]; time_t curTime, startTime; double timeout=TIMEOUT; EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 82 Channel Access Simple CA Client with Callbacks Parse the command line int main(int argc, char **argv) { int stat; chid pCh; /* Parse the command line */ if(parseCommand(argc,argv) != SCA_OK) exit(1); if(!pvSpecified) { printf("No PV specified\n"); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 83 Channel Access Simple CA Client with Callbacks Initialize Channel Access /* Initialize */ stat=ca_context_create(ca_disable_preemptive_callback); if(stat != ECA_NORMAL) { printf("ca_context_createfailed:\n%s\n", ca_message(stat)); exit(1); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 84 Channel Access Simple CA Client with Callbacks Search /* Search */ stat=ca_create_channel(name,connectionChangedCB,NULL, CA_PRIORITY_DEFAULT,&pCh); if(stat != ECA_NORMAL) { printf("ca_create_channel failed:\n%s\n", ca_message(stat)); exit(1); } printf("%s Search started for %s\n",timeStamp(),name); EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 85 Channel Access Simple CA Client with Callbacks Wait in ca_pend_event for the callbacks to occur /* Wait */ startTime=curTime; ca_pend_event(timeout); printf("%s ca_pend_event timed out after %g sec\n", timeStamp(),timeout); EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 86 Channel Access Simple CA Client with Callbacks Clean up /* Clear the channel */ stat=ca_clear_channel(pCh); if(stat != ECA_NORMAL) { printf("ca_clear_channel failed:\n%s\n", ca_message(stat)); } /* Exit */ ca_context_destroy(); return(0); } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 87 Channel Access Simple CA Client with Callbacks Connection callback implementation static void connectionChangedCB(struct connection_handler_args args) { chid pCh=args.chid; int stat; /* Branch depending on the state */ switch(ca_state(pCh)) { EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 88 Channel Access Simple CA Client with Callbacks Connection callback implementation case cs_conn: printf("%s Connection successful\n",timeStamp()); stat=ca_array_get_callback(DBR_STRING,1,pCh, valueChangedCB,NULL); if(stat != ECA_NORMAL) { printf("ca_array_get_callback:\n%s\n", ca_message(stat)); exit(1); } break; EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 89 Channel Access Simple CA Client with Callbacks Connection callback implementation case cs_never_conn: printf("%s Cannot connect\n",timeStamp()); break; case cs_prev_conn: printf("%s Lost connection\n",timeStamp()); break; case cs_closed: printf("%s Connection closed\n",timeStamp()); break; } } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 90 Channel Access Simple CA Client with Callbacks Value changed callback implementation static void valueChangedCB(struct event_handler_args args) { /* Print the value */ if(args.status == ECA_NORMAL && args.dbr) { printf("%s Value is: %s\n",timeStamp(), (char *)args.dbr); printf("Elapsed time: %ld sec\n", curTime-startTime); } } EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 91 Channel Access Simple CA Client with Callbacks Output simplecagetcb evans:calc Sep 14 18:31:55 Search started for evans:calc Sep 14 18:31:55 Connection successful Sep 14 18:31:55 Value is: 5 Elapsed time: 0 sec Sep 14 18:31:56 ca_pend_event timed out after 1 sec Time for this operation is typically a few ms EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 92 Channel Access Simple Get Clients のソースファイルの例 Some of the code that is not related to Channel Access has not been shown All the files necessary to build a project as an EPICS Extension should be available with the presentation Makefile Makefile.Host simplecaget.c simplecagetcb.c LICENSE Stored as simpleCA.tar.gz EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 93 Channel Access EPICS の Build システム Supports both native and GNU compilers Builds multiple types of components libraries, executables, headers, scripts, java classes, … Supports multiple host and target operating systems Builds for all hosts and targets in a single <top> tree epics/base epics/extensions Allows sharing of components across <top> trees Has different rules and syntax for 3.13 and 3.14 EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 94 Channel Access System Requirements 必要な software Perl version 5 or greater GNU make, version 3.78.1/3.81 or greater C++ compiler and linker (GNU or host vendor's compiler) 場合によって必要な software Tornado II and board support packages RTEMS development tools and libraries Motif, X11, JAVA, Tcl/Tk, Python… EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 95 Channel Access User Requirements Set an environment variable to specify the architecture EPICS_HOST_ARCH for 3.14 solaris-sparc, linux-x86_64, win32-x86, darwin-x86, etc. Set the PATH so the required components can be found Perl, GNU make, C and C++ compilers System commands (e.q. cp, rm, mkdir) EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 96 Channel Access Internet 上の参考文書 Example files http://www.aps.anl.gov/epics/ Documents - Training - Developing Client Tools - Introduction to Chnnael Access Clients - Example Files Build examples of EPICS-Base, etc on several Platforms http://www-linac.kek.jp/cont/epics/win32/ http://www-linac.kek.jp/cont/epics/linux/ http://www-linac.kek.jp/cont/epics/darwin/ EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 97 Channel Access Channel-Access の簡単な例 Of course, this Presentation makeBaseApp.pl -t caClient {app-name} caExample.c caMonitor.c makeBaseEx.pl -t example {ext-name} caExample.c EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 98 Channel Access Typical Extensions Build Tree epics/base epics/extensions config configure bin solaris solaris-sparc lib solaris solaris-sparc src simpleCA O.solaris O.solaris-sparc EPICS Seminar at J-PARC <top> for base <top> for extensions 3.13 configuration 3.14 configuration Binaries by architecture Libraries by architecture Sources by application Application source files Binaries for this application Kazuro Furukawa, KEK, Mar.2012. 99 Channel Access Getting Started with an Extension Make a directory structure for base http://www.aps.anl.gov/epics/extensions/index.php E.g. epics/base Obtain base and build it Set COMPAT_TOOLS_313 first if necessary (see later) Make a directory structure for extensions E.g. epics/extensions Get extensions/config and configure from the EPICS pages Set EPICS_BASE to your desired version of base In extensions/configure/RELEASE for 3.14 Type gnumake (or make) in extensions Get an extension and put it under extensions/src Type gnumake (or make) in your application directory EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 100 Channel Access Using the 3.13 Build Rules for Extensions EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 101 Channel Access Using the 3.14 Build Rules for Extensions Go to the the EPICS page for your version of base http://www.aps.anl.gov/epics/base/index.php Read the README It is very extensive Should tell you everything you need to know There is a only a Makefile and it uses 3.14 syntax Set EPICS_HOST_ARCH for your platform solaris-sparc, linux-x86, win32-x86, darwin-ppc, etc. Configuration is in extensions/configure RELEASE (Specifies what base) os/CONFIG_SITE_xxx (Specifies local changes for xxx arch) EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 102 Channel Access Makefile for Simple Get Clients TOP = ../.. include $(TOP)/config/CONFIG_EXTENSIONS include $(TOP)/config/RULES_ARCHS EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 103 Channel Access Makefile.Host for Simple Get Clients TOP = ../../.. include $(TOP)/config/CONFIG_EXTENSIONS HOST_OPT = NO CMPLR = STRICT PROD = simplecaget simplecagetcb PROD_LIBS = ca Com ca_DIR = $(EPICS_BASE_LIB) Com_DIR = $(EPICS_BASE_LIB) simplecaget_SRCS += simplecaget.c simplecagetcb_SRCS += simplecagetcb.c include $(TOP)/config/RULES.Host EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 104 Channel Access 試してみる 自分の PC でもできるぞ Virtual Linac http://www.aps.anl.gov/epics/download/examples/index.php http://www.aps.anl.gov/epics/download/examples/vlinac_multi.tgz CSS http://www-linac.kek.jp/cont/css/ http://www-linac.kek.jp/cont/css/apps/css_kek_3.1.0-linux.gtk.x86_64_20120226_010803.zip http://www-linac.kek.jp/cont/css/apps/css_kek_3.1.0-linux.gtk.x86_20120226_010803.zip もっと詳しくは http://www.aps.anl.gov/epics/ EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 105 Channel Access 試してみる 自分の PC でもできるぞ Macintosh, Windows, Linux 例えば http://www-linac.kek.jp/cont/epics/darwin/ http://www-linac.kek.jp/jisshu/ http://www-linac.kek.jp/cont/epics/ もっと詳しくは http://www.aps.anl.gov/epics/ Application Developer’s Guide Record Reference Manual Channel Access Reference Manual EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 106 Channel Access Acknowledgements Jeff Hill [LANL] is responsible for EPICS Channel Access and has developed almost all of it himself Janet Anderson [ANL] is responsible for and has developed most of the EPICS Build System EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 107 Channel Access Thank You EPICS Seminar at J-PARC Kazuro Furukawa, KEK, Mar.2012. 108