SEMAPHORE DIRECTIVES FOR RSX-11M-PLUS EXECUTIVE Version 02.3P July 12,1982 Last modification July 20,1983 Harry Atherton University of Cincinnati Medical Center Department of Pediatrics, ML 541 231 Bethesda Ave. Cincinnati, Ohio 45267 Phone (513) 872-5341 The files in this UIC implement binary semaphore operations in the RSX-11M-PLUS executive. This software has been in use at our installation since RSX-11M V3.0, and it is believed to be bug free. If you have any problems, comments, or suggestions I would like to hear them. No responsibility is assumed for the use or reliability of this software. SEMAPHORE DIRECTIVES FOR RSX-11M-PLUS EXECUTIVE PAGE 2 The following files implement the binary semaphore P-operation and V-operation executive directives: DRTBL.MOD -- Adds the directives to the dispatch table. DREIF.MOD -- Adds call to cleanup routine on task exit. SYSCM.MOD -- Adds semaphore queues to executive data base. DRSEM.MAC -- Directive processing and exit cleanup routines. SEMDIR.MAC -- Macros that can be added to RSXMAC.SML to provide directive calls SEMP$S AND SEMV$S. SEMCAL.MAC -- FORTRAN callable subroutines provide directive calls SEMP and SEMV. Object module should be added to your FORTRAN object library. SEMTEST.FTN -- Small FORTRAN program to test and demonstrate use of semaphores. The object module of SEMCAL.MAC must be available to the task builder. SEMTEST2.FTN-- Small FORTRAN program to test for error return when SEMP is called twice. The object module of SEMCAL.MAC must be available to the task builder. The following files are only relevant to a system using executive directive commons. RSX11M.ADD and DIRCOM.ADD and DR2COM.ADD -- Commands to be added to the corresponding TKB executive build files. RSX11M.DIF and DIRCOM.DIF and DR2COM.DIF and DR211M.DIF -- Listings of CMP output, showing the changes that are made to the various build files to include the semaphores in a system with executive directive commons. To add the semaphore directives a system generation must be done. To prepare for the SYSGEN copy files DRTBL.MOD, DREIF.MOD, and SYSCM.MOD to [11,40] on the executive source disk. Also copy DRSEM.MAC to [11,10] on the executive source disk. After applying any DEC supplied patches these SEMAPHORE DIRECTIVES FOR RSX-11M-PLUS EXECUTIVE PAGE 3 modifications are made. The SLP correction files DRTBL.MOD, DREIF.MOD, and SYSCM.MOD use ASCII string locators to insert the additions to the program logic. These files must be applied AFTER any DEC patches. Note that these files are called .MOD instead of .COR to avoid confusing them with the DEC files. Also watch out for file version numbers on the source files if multiple SYSGENS are done on the same disk. The DEC correction files specify version 1 for input and version 2 for output. If you are working with a virgin disk everything will work right since the .MOD files do not specify version numbers. To have the module DRSEM assembled with the other executive modules answer Y to the question: "AE030 Do you wish to pause to edit any files before assemblying ?" Then edit the file [11,24]RSXASM.CMD. Locate the line containing DRSED. It should look like: [11,24]DRSED,listing=[1,1]EXEMC/ML,[11,10]RSXMC/PA:1,DRSED Add a line exactly like it, except replace DRSED with DRSEM (it occurrs three times in the line). The module DRSEM will be included in the executive object module library automatically by SYSGEN. The executive TKB files must also be modified. Answer Y to the question: "BE030 Do you want to pause to edit any files before task-building ?" Different files are affected depending on whether or not executive directive commons are used. If you are building the executive without executive directive commons the directive modules are referenced in file DIR.CMD. Edit this file and locate the line containing DREXP. Add the following line after it: [1,24]RSX11M/LB:DRSEM If you are building the executive with directive commons the module DRSEM should be placed in the second executive directive common, DR211M. Four taskbuild files must be modified to do this without error messages. DIRCOM.CMD insert file DIRCOM.ADD before the / at end of file. DR2COM.CMD insert file DR2COM.ADD before the / at end of file. Also add the line [1,24]RSX11M/LB:DRSEM before the line [1,54]DSP11M.STB/SS. DR211M.CMD add the line [1,24]RSX11M/LB:DRSEM before the line [1,54]RSX11M.STB/SS. SEMAPHORE DIRECTIVES FOR RSX-11M-PLUS EXECUTIVE PAGE 4 RSX11M.CMD insert file RSX11M.ADD before the / at end of file. Print the four .DIF files in this directory to see how the changes appear in the .CMD files. After completing the editing the SYSGEN can proceed normally from this point. When the SYSGEN is finished you can add the file SEMDIR.MAC to [1,1]RSXMAC.SML so the macros SEMP$S and SEMV$S will be available. Also the file SEMCAL.MAC should be assembled and the object module placed in [1,1]SYSLIB.OLB, [1,1]ANSLIB.OLB, [1,1]F4POTS.OLB, and/or [1,1]FOROTS.OLB so the FORTRAN subroutines SEMP and SEMV are available. To demonstrate the functioning of the semaphores, compile and build the programs SEMTEST.FTN and SEMTEST2.FTN. By running multiple copies of SEMTEST from several terminals you can see how the semaphore functions allow only one program at a time to execute the "critical region" between the P-operation and the V-operation. The program SEMTEST2 works in a similar manner, but it calls SEMP twice and prints the directive status from each directive call. List these programs to see what they do. The following pages describe the executive directives in the format of the Executive Reference Manual. Additional information about semaphores is given in the paper "Implementation and Application of Semaphores in RSX-11M" presented at the Fall 1979 DECUS. This appears in the Proceedings of the Digital Equipment Computer Users Society USA 1979 Fall. Reprints are available from the author. SEMP$S (only $S form supplied) Semaphore P-operation The Semaphore P-operation instructs the executive to place the issuing task on the specified semaphore list. If there is already a task on the list the issuing task is suspended. If no other task is on the list the issuing task continues execution. FORTRAN call: CALL SEMP(number[,ids]) number = Semaphore number ids = Directive status Macro call: SEMP$S number[,error] number = Semaphore number error = Error routine address DSW Return Codes: IS.SPD -- Successful Completion (task was suspended) IS.SUC -- Successful completion (task was not suspended) IE.UPN -- Insufficient dynamic memory IE.ILU -- Semaphore number outside allowable range (range is 1-20; upper limit is alterable at system generation time; see module DRSEM.MAC) IE.ITS -- Program is already on the specified semaphore queue IE.ADP -- Part of DPB is out of the issuing task's address space IE.SDP -- DIC or DPB size is invalid Notes: 1. If the task is suspended the suspend status bit is set; see description of directive SPND$ for additional notes. SEMP$S (cont.) 2. Since the suspend bit is used the task may be resumed by the MCR command or the executive directive. If this is done proper operation of the semaphore will be impossible. 3. There are two successful completion codes, IS.SPD = +2 and IS.SUC = +1. If you are interested in knowing whether or not a program is actually suspended when it calls SEMP$S, the status returned will tell you. SEMV$S (only $S form supplied) Semaphore V-operation The Semaphore V-operation instructs the executive to remove the issuing task from the head of the specified semaphore list. If any other tasks are on the list the one at the head is resumed. If the issuing task is not at the head of the specified list no action is taken and status code IE.ULN is returned. FORTRAN call: CALL SEMV(number[,ids]) number = Semaphore number ids = Directive status Macro call: SEMV$S number[,error] number = Semaphore number error = Error routine address DSW Return Codes: IS.SUC -- Successful completion IE.ULN -- Task was not at head of the specified list (Note 1) IE.ACT -- Next task on list was not active (Note 2) IE.ITS -- Next task on list was not suspended (Note 2) IE.ADP -- Part of DPB is out of issuing task's address space IE.SDP -- DIC or DPB size is invalid Notes: 1. This will result if the task calls SEMV$S without having previously called SEMP$S with the same semaphore number. 2. This may be caused if a program using the semaphores is resumed by the MCR command or executive directive. 3. When a task exits the executive cleans up the semaphore lists. If the exiting task has failed to do any required SEMV$S directives, they are simulated by the executive.