{"id":55,"date":"2013-01-21T08:08:02","date_gmt":"2013-01-21T14:08:02","guid":{"rendered":"http:\/\/tommysprinkle.com\/mvssp\/?p=55"},"modified":"2013-05-22T08:34:37","modified_gmt":"2013-05-22T13:34:37","slug":"svc-routines-introduction","status":"publish","type":"post","link":"https:\/\/tommysprinkle.com\/mvssp\/2013\/01\/21\/svc-routines-introduction\/","title":{"rendered":"SVC Routines – Introduction"},"content":{"rendered":"

We can now explore how to add system level functionality using SVC (Supervisor Call) routines.\u00a0 SVC routines are invoked through the use of the SVC machine instruction.\u00a0 A SVC instruction causes a SVC Interruption to occur.\u00a0 It effectively allows for a special type of call instruction that can switch between problem mode execution and supervisor mode.\u00a0 SVC routines are defined at SYSGEN time.\u00a0 SVC routines are categorized into six types.\u00a0 Type 1, 2, and 6 SVC routines are linked as part of the resident control program.\u00a0 Type 3 and 4 SVC routines reside in the Link Pack Area (LPA) and may be either fixed or pageable.\u00a0 All SVC routines must be reentrant.\u00a0 I will focus on type 3\/4 SVC routines since they reside in LPA as individual modules and are less restrictive – and they provide all the functionality I am looking for.<\/p>\n

SVC modules must have a specific name in the format:<\/p>\n\n\n\n\n\n
Type 1, 2,\u00a0 6<\/td>\nIGCnnn<\/td>\nnnn = Signed Decimal Number<\/td>\n<\/tr>\n
Type 3<\/td>\nIGC00nnn<\/td>\n<\/td>\n<\/tr>\n
Type 4<\/td>\nIGCssnnn<\/td>\nss = load module number -1<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

There are a maximum of 256 SVC routines that can be defined (0-255).\u00a0 The nnn part of the name indicates the SVC number.\u00a0 It is a signed decimal number so the last digit contains the sign in the high order four bits (x’C0′)\u00a0 make the last digit a letter (A-I) for the numbers zero through nine.\u00a0 If the last digit is zero then the last character is X’C0′ or ‘{‘.\u00a0 For example a Type 3 SVC with the number 123 would be named “IGC0012C”.\u00a0 If it was SVC 130 it would be named “IGC0013{“.\u00a0 Once you understand the way the names are generated it is easy to deal with.\u00a0 The difference between Type 3 and 4 SVC routines is that Type 3 routines consist of a singe module and type 4 routines are made up multiple modules.\u00a0 For our purposes Type 3 and 4 SVC routines are the same.\u00a0 A Type 5 SVC is a placeholder and indicates the SVC will be added after the SYSGEN in complete.<\/p>\n

Since the SVC call is routed through the SVC interrupt handler the SVC routine does not have to save the callers registers (they are saved by the system in the Request Block).\u00a0 Registers 0, 1, 13, and 15 are passed from the caller to the SVC routine.\u00a0 On return the system restores registers 2 through 12.\u00a0 The SVC routine may pass information back to the caller in registers 0, 1, and 15.\u00a0 Register 13 usually points to a save area established by the calling routine.\u00a0 It may be necessary for the SVC routine to establish a save area if standard call linkage will be used to call other routines.\u00a0 Registers 3 through 7 contain parameters passed by the SVC interrupt handler.\u00a0 Here is a summary of register contents on entry to a SVC routine:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\u00a00<\/td>\n\u00a0Same as when SVC was issued<\/td>\n<\/tr>\n
\u00a01<\/td>\n\u00a0Same as when SVC was issued<\/td>\n<\/tr>\n
\u00a02<\/td>\n\u00a0Unpredictable<\/td>\n<\/tr>\n
\u00a03<\/td>\n\u00a0A(CVT)<\/td>\n<\/tr>\n
\u00a04<\/td>\n\u00a0A(TCB)<\/td>\n<\/tr>\n
\u00a05<\/td>\n\u00a0A(SVRB) Type 2,3,4<\/td>\n<\/tr>\n
\u00a06<\/td>\n\u00a0Entry Point of SVC Routine<\/td>\n<\/tr>\n
\u00a07<\/td>\n\u00a0A(ASCB)<\/td>\n<\/tr>\n
\u00a08<\/td>\n\u00a0Unpredictable<\/td>\n<\/tr>\n
\u00a09<\/td>\n\u00a0Unpredictable<\/td>\n<\/tr>\n
10<\/td>\n\u00a0Unpredictable<\/td>\n<\/tr>\n
11<\/td>\n\u00a0Unpredictable<\/td>\n<\/tr>\n
12<\/td>\n\u00a0Unpredictable<\/td>\n<\/tr>\n
13<\/td>\n\u00a0Same as when SVC was issued<\/td>\n<\/tr>\n
14<\/td>\n\u00a0Return Address<\/td>\n<\/tr>\n
15<\/td>\n\u00a0Same as when SVC was issued<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

A Simple SVC Routine<\/h2>\n

Now we can write a simple SVC routine.\u00a0 We will accept two input parameters in registers 0 and 1.\u00a0 The SVC routine will add the contents of these two registers and return the result in register 15.\u00a0 This is really a very silly SVC routine but it will prove that we understand the basics of writing our own SVC.<\/p>\n

On my system I happen to know that SVC number 230 is a Type 3 SVC and it is currently not in use.\u00a0 I will use it for my test SVC routine but you may have to use another SVC number depending how SVC routines are defined and used on your system.<\/p>\n

SVC01    CSECT ,        \r\n         USING SVC01,R6 \r\n*                       \r\n         LR    R15,R0   \r\n         AR    R15,R1   \r\n*                       \r\n         BR    R14<\/pre>\n
Here is our whole SVC routine (minus the equates for the registers).\u00a0 Our load module must be named to reflect the SVC number (“IGC0023A” for SVC 231) but the internal CSECT name can be anything we want.\u00a0 We establish addressability using register 6 as our base register since it already contains the entry point address.\u00a0 We copy the value of register 0 into register 15 and then add teh value of register 1.\u00a0 All that is left is to return using the address in register 14.\u00a0 The contents of registers 0, 1, and 15 will be returned to the caller.<\/p>\n
Now we can assemble and link into SYS1.LPALIB.<\/p>\n
Next we need a test program to invoke our new SVC.\u00a0 Here is the main part of the test program:<\/p>\n
         LA    R0,111                     \r\n         LA    R1,222                     \r\n         SVC   231                        \r\n*                                         \r\n         CVD   R15,DOUBLE                 \r\n         MVC   RESULT,=X'4020202020202120'\r\n         ED    RESULT,DOUBLE+4            \r\n*                                         \r\n         MVC   WTO+8(8),RESULT            \r\nWTO      WTO   '++++++++',ROUTCDE=(1,11)<\/pre>\n
I left out the program linkage but once our program is up and running we load up our two input parameter registers and issue the SVC instruction to call our SVC routine.\u00a0 On return from the SVC we convert the return value in register 15 to decimal and use the edit instruction to make it printable.\u00a0 The result is moved into the WTO parameter list and a message is sent to the console.<\/p>\n
JOB 6815  $HASP373 SVC01T   STARTED - INIT 12 - CLASS A - SYS TCS3 \r\nJOB 6815  IEF450I SVC01T MVSSP - ABEND SFE7 U0000 - TIME=07.06.47  \r\nJOB 6815   7.06.48   0.00.00   0.00.00  SFE7   SVC01T    MVSSP     \r\nJOB 6815   7.06.48   0.00.00   0.00.00  SFE7   SVC01T    ########  \r\nJOB 6815  $HASP395 SVC01T   ENDED<\/pre>\n
When we try running our test program we get a System ABEND FE7.\u00a0 Notice that X’E7′ is 231 decimal which is our SVC number.\u00a0 This ABEND indicates the SVC has not been installed.\u00a0 To actually get our SVC routine installed we need to IPL and CLPA (Create Link Pack Area) or we could use MLPA (Modify Link Pack Area) to do a temporary install of our routine.\u00a0 A normal IPL does not change the LPA.\u00a0 It is only rebuilt when CLPA is specified.<\/p>\n
Now after a quick IPL with a CLPA we run our test again:<\/p>\n
JOB 6825  $HASP373 SVC01T   STARTED - INIT 12 - CLASS A - SYS TCS3 \r\nJOB 6825  +     333                                                \r\nJOB 6825   7.31.17   0.00.00   0.00.00  0000   SVC01T    MVSSP     \r\nJOB 6825   7.31.17   0.00.00   0.00.00  0000   SVC01T    ########  \r\nJOB 6825  $HASP395 SVC01T   ENDED<\/pre>\n
And we get the expected result (111+222=333) which proves we have successfully written, installed, and invoked a SVC routine.<\/p>\n","protected":false},"excerpt":{"rendered":"
We can now explore how to add system level functionality using SVC (Supervisor Call) routines.\u00a0 SVC routines are invoked through the use of the SVC machine instruction.\u00a0 A SVC instruction causes a SVC Interruption to occur.\u00a0 It effectively allows for a special type of call instruction that can switch between problem mode execution and supervisor …<\/p>\n
Continue reading ‘SVC Routines – Introduction’ »<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[9],"tags":[],"class_list":["post-55","post","type-post","status-publish","format-standard","hentry","category-introduction"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_shortlink":"https:\/\/wp.me\/p3x7AW-T","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/posts\/55","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/comments?post=55"}],"version-history":[{"count":9,"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/posts\/55\/revisions"}],"predecessor-version":[{"id":64,"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/posts\/55\/revisions\/64"}],"wp:attachment":[{"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/media?parent=55"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/categories?post=55"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tommysprinkle.com\/mvssp\/wp-json\/wp\/v2\/tags?post=55"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}