SEMAPHORE DIRECTIVES FOR RSX-11M EXECUTIVE Version 01.2 May 18,1977 Last modification April 16,1980 Harry Atherton University of Cincinnati Medical Center Department of Pediatrics, Room 6253 231 Bethesda Ave. Cincinnati, Ohio 45267 Phone (513) 872-5341 The files in this UIC implement binary semaphore opera- tions in the RSX-11M executive. This software has been in use at our installation for over two years, and it is be- lieved 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 EXECUTIVE PAGE 2 The following files implement the binary semaphore P-operation and V-operation executive directives: DRDSP.MOD -- Adds the directives to the dispatch table. DREIF.MOD -- Adds call to cleanup routine on task exit. The above are for RSX-11M V3.2 (BL26). DRSEM.MAC -- Directive processing and exit cleanup rou- tines. 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 direc- tive calls SEMP and SEMV. Object module should be added to SYSLIB.OLB or FOROTS.OLB. SEMTEST.FTN -- Small FORTRAN program to test and demonstrate use of semaphores. The object module of SEM- CAL.MAC must be available to the task build- er. DRDSP.OLD -- DREIF.OLD -- If you are generating RSX-11M V3.1 (BL22) use these files in place of the first two files. To add the semaphore directives a system generation must be done. To prepare for the SYSGEN copy files DRDSP.MOD and DREIF.MOD to [11,40] on the executive source disk. These two files are for RSX-11M V3.2(BL26). If you are generating RSX-11M V3.1 (BL22) use the files DRDSP.OLD and DREIF.OLD instead. Also copy DRSEM.MAC to [11,10] on the executive source disk. After applying any DEC supplied patches, these modifi- cations are made. The SLP correction files DRDSP.MOD and DREIF.MOD use ASCII string locators to insert the additions to the program logic. (The comments are still handled by absolute line numbers since their location is not critical to proper program operation). These files must be applied AFTER the DEC patches. (There is a correction to DRDSP.MAC on the Autopatch kit). 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 DRDSP.MAC if multiple SYSGENS are done on the same disk. The DEC correc- tion files specify version 1 for input and version 2 for output. If you are working with a virgin disk everything will work right since DRDSP.MOD does not specify version numbers. If you have gone through all of this before there will be a DRDSP.MAC;3 left over. In that case DRDSP.MOD will use it for input and create a version 4 which would have the modifications applied twice. Make sure that there is not already a DRDSP.MAC;3 on the disk before you start. DRDSP.OLD and DREIF.OLD still use absolute line numbers SEMAPHORE DIRECTIVES FOR RSX-11M EXECUTIVE PAGE 3 for insertion. I am not aware of any DEC changes to these files in V3.1. It is essential that these modifications only be applied to the original version of the .MAC files. To have the module DRSEM assembled with the other exe- cutive modules answer Y to the question: "Do you wish to edit any of the Executive files ?" 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,LB: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 automati- cally by SYSGEN. This is also a good time to edit the exe- cutive build command file. It is file [11,10]RSXBLD.CMD on the baseline disk. Locate the line containing DRSED. Add the following line after it: [1,24]RSX11M/LB:DRSEM 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 or [1,1]FOROTS.OLB so the FORTRAN subroutines SEMP and SEMV are available. To demonstrate the functioning of the semaphores, com- pile and build the program SEMTEST.FTN. By running multiple copies 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 following pages describe the executive directives in the format of the Executive Reference Manual. Additional information about semaphores is given in the paper "Imple- mentation and Application of Semaphores in RSX-11M" present- ed at the Fall 1979 DECUS. This should appear 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 sus- pended. 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 suspend- ed) 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.ADP -- Part of DPB is out of the issuing task's ad- dress 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 addi- tional notes. 2. Since the suspend bit is used the task may be re- sumed by the MCR command or the executive direc- tive. If this is done proper operation of the sem- aphore will be impossible. 3. There are two successful completion codes, IS.SPD = +2 and IS.SUC = +1. If you are interested in know- ing 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 sema- phore 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 sema- phore number. 2. This may be caused if a program using the sema- phores is resumed by the MCR command or executive directive. 3. When a task exits the executive cleans up the sema- phore lists. If the exiting task has failed to do any required SEMV$S directives, they are simulated by the executive.