############# .s10 .TAB STOPS +8,+8,+8,+8,+8,+8,+8,+8,+8,+8,+8 .c ;Building and Using .c ;Resident Libraries .s6 .c ;Reid Madsen .c ;Director of Systems .c ;Weidner Communications Corporation .c ;Provo, Utah .s6 .LM +10.RM -10.NAP.NHY What is a resident library? How do I build one? Who needs them? Why use them? What problems will I have using them? The Task Builder provides you with many ways of using resident libraries for tailoring tasks to meet specific requirements and to allow more efficient use of available memory. In addition to the above questions, this session will cover the building of resident libraries, cluster libraries and supervisor mode libraries; linking resident libraries together; linking tasks to resident libraries; problems, speed considerations, and hidden quirks. .LM -10.RM +10.NAP.NHY .page The RSX-11M/M-PLUS Task Builder provides you with the ability to use three different types of shared regions to increase the logical address space of your tasks. The three types of shared regions are: .list "o" .le;Common Shared Region - on unmapped systems, a shared region defined either at run time or during the sysgen process; for example, a global common area. .le;Library Shared Region - a shared region containing common code or routines shared by multiple tasks, and in this way saving virtual address space in the tasks. This type of region is more commonly known as a Library. .le;Dynamic Region - a region created dynamically at run time using the $CRRG memory management directive. .els The purpose of this session is to provide you with information concerning the design, building and use of libraries. Discussion will be based only on the RSX-11M/M-PLUS features of the Task Builder with the hope that users of IAS may gain some ideas as well. I hope that this information plus the session proceedings will help you in your library efforts. .s1 Those attending this session should have a general knowledge of the Task Builder, MACRO-11 and the Overlay Description Language (ODL). The information presented here and in the session can be found in the MACRO-11 and Task Builder Manuals of the RSX-11M/M-PLUS documentation set. My hope in giving this presentation was to consolidate the information concerning libraries into an easily understandable form. If you are interested in reading more on the subject, I suggest that you read the following areas from the manuals. .s1 .test page 11 .nf Task Builder Manual - Chapter 2 - Task Builder Functions Especially 2.4 - 2.6 Chapter 3 - Overlay Capability Chapter 4 - Overlay Loading Methods Chapter 5 - Shared Region Concepts Especially 5.1 and 5.2 Chapter 6 - Supervisor-Mode Libraries Macro-11 Manual - Chapter 6 - General Assembler Directives System Management - Chapter 10- Virtual Monitor Console Routine .fill .s1 If you already have a general understanding of the Task Builder, MACRO-11 and ODL files, this session will help expand your understanding. .s2 .c 80;What is a Library? .s1 A library is a collection of commonly used re-entrant subroutines that reside in memory. The use of a library allows any number of tasks to share a single copy of the routines which are contained in the library. This ability to share common code reduces the total physical memory requirements of the tasks linked to the library. .s1 .TEST PAGE 3 The Task builder creates a library in much the same way that it creates a regular user task. The library, however, does not have a stack or task header and therefore cannot be run by itself. .s1 In RSX-11M/M-PLUS systems, libraries are generally installed in their own partitions before tasks which have linked to them can run. On RSX-11M-PLUS systems, however, libraries can also be installed in the GEN partition. If not fixed in memory, library will be loaded into memory, if not currently there, when a task that is linked to the library becomes active. When installed in the GEN partition, libraries may also be swapped out of memory when not in use and the memory used for the library is freed. .s1 In this session we will discuss three type of libraries. .list "o" .le;Resident Library - a library which requires a portion of your tasks virtual address space. Each library of this type requires it's own address window. .le;Cluster Library - a set of libraries which share a portion of your tasks virtual address space. A set of cluster libraries are all mapped through the same address window. .le;Supervisor-Mode Library - (RSX-11M-PLUS only) - a library which is mapped using the processors supervisor-mode I-space registers, while mapping the task with supervisor-mode D-space registers. The use of supervisor-mode libraries allows user tasks access to 64KW virtual address space. .els With the exception of supervisor-mode libraries, a resident library or a set of cluster libraries will require at least one APR (for a 4K or smaller library) of the task that links to the library. Libraries which are overlaid also require additional overhead in the task root for autoload vectors, segment descriptors, window descriptors, and region descriptors. Any space which is given up to a library cannot be used for other purposes. .s2 .c 80;Why Use a Library? .s1 In simple terms, you use a library to reduce the total physical memory requirements for tasks which run on your system. By building tasks with libraries, you can then get more tasks and/or data into physical memory for execution and/or use. This in turn increases system throughput by decreasing disk swapping. .s1 This concept can be illustrated by showing three tasks and their physical memory requirements when not linked with a library vs. when linked with a library. .s1 .TEST PAGE 40 .nf +-----------------------+ +-----------------------+ | | |///////////////////////| | | |///////////////////////| | Free | |/////// Library ///////| | | |///////////////////////| | | +-----------------------+ +-----------------------+ | | |///////////////////////| | | |///////////////////////| | | |///////////////////////| | | |///////////////////////| | Free | | | | | | | | | | Task C | | | | 20 K | | | | | +-----------------------+ | | | | +-----------------------+ | | |///////////////////////| | Task C | |///////////////////////| | 12K + 8K | | | | 20K | | Task B | | | | 12 K | +-----------------------+ | | | | +-----------------------+ | Task B | |///////////////////////| | 8K + 8K | |///////////////////////| | 16K | |///////////////////////| +-----------------------+ | | | | | Task A | | Task A | | 16 K | | 10K + 8K | | | | 18K | | | | | +-----------------------+ +-----------------------+ | | | | | Executive | | Executive | | | | | +-----------------------+ +-----------------------+ Figure 1A Figure 1B .fill .s1 In Figure 1A, the physical memory requirements of Tasks A, B and C are shown. It is not possible in this case to bring in any more copies of Task A, B or C without first displacing the original copy of either Task A, B or C. In each task there are routines which could be placed in a library. The shaded areas (/) of each task represent these routines. It should be noted that Task C contains all of the routines that could be put into the library and that tasks A and B contain a subset of those routines. .s1 Figure 1B illustrates the physical memory requirements of Tasks A, B and C after they have been linked to a library. The library is the shaded area (/) at the top and contains the common routines from Figure 1A. The total physical memory requirements have been reduced, allowing more copies of Tasks A, B and C to occupy memory before swapping occurs. .s1 It should be noted that even though the amount of physical memory required has decreased, the virtual address space used by each task has not decreased. In fact, the virtual address space of Tasks A and B has increased. .s1 Basically, the use of shared libraries can help you in the following five areas. .list "o" .le; Reduce physical memory requirements of tasks. .le; Reduce disk swapping. .le; Increase system throughput. .le; Save $$$ by possibly not having to purchase more memory. .le; Reduce physical size of tasks residing on disk, thus freeing disk blocks for other uses. .els .s1 .c 80;How Many Libraries Should I Use? .s1 Everyone should be able to benefit from using the FCS library. The source file for FCSRES is distributed as a part of your distribution media. If you so desire, you can link a number of your privileged and non-privileged tasks to FCSRES during the SYSGEN process. The use of this library can significantly reduce the memory required by common tasks such as PIP, TKB, MAC and many others. .s1 Some of the layered product's such as FORTRAN, BASIC-PLUS-2 and RMS provide you with the capability of building libraries composed of the modules from the products OTS. If you are using any one of the layered products which provide this feature, you may want to create a library for that product. Some of these products provide you with libraries that have already been created. FORTRAN, however, allows you to include into your library only those routines which you feel are needed for your particular application. In addition to these types of libraries you may want to include a library which consists of common subroutines which have been written at your site as a part of your software application. .s1 In selecting routines for use in your library, only include those which are used frequently by user tasks. Libraries which contain infrequently used routines, waste valuable memory space and are not very efficient since very few tasks use the routines contained in them. .s1 In deciding whether or not another library will be of use to your system, you might consider the following questions. .list "o" .le;Will the library contain routines used by many of the tasks running on your system? .le;Can the physical memory lost by making the library resident be recovered from the physical memory saved by the tasks linking to the library? .le;Will the decrease in speed caused by using Cluster Libraries be acceptable? .els If you can answer in the affirmative to these questions, then the resident library will most likely be of help to you. Keep in mind that these are only general guidelines, and that they may not apply to all systems. The number of libraries you should use might be determined only by testing your system with the library installed. .s2 .c 80;Library Sources .s1 The modules that go into a resident library come from either object libraries (OLB's) or numerous object files (OBJ's). At our site all of the modules that go into any of our libraries can be found in SYSLIB.OLB. .s1 If you are including into a library some of your own site specific routines, it is suggested that you make sure the routines are free of bugs before you build a library containing them. If nothing else, you will be able to sleep well at night without having to worry about the users getting you! .s1 In order for the library to be shared among many users, all modules which are to be included must be written so as to be re-entrant. In addition, libraries which contain modules which are both re-entrant and position independant provide the greatest flexibility for the user since the library can be placed at any available APR in the task image. .s2 .c 80;Defining Library Contents .s1 The contents of any library can be defined by using either a MACRO-11 source file, by creating an Overlay Descriptor Language file (ODL) which defines the library overlay structure or by specifying a list of input files to the Task Builder. In all cases the modules to be included in the library may be contained in multiple OLB or OBJ files. .s1 A MACRO-11 source file is used to define a library by specifying the global entry points desired in the library. .s1 The ODL form of a library definition is used to define a library by specifying the names of the object modules desired in the library. .s1 Libraries defined by specifying a list of input files will be discussed in the section concerning task building the library. .s1 Two good examples of how a library may be defined using a MACRO-11 source file are found in the definition files for the FCS and FORTRAN resident libraries. The FORTRAN source is found in [11,40]F4PRES.MAC on the FORTRAN distribution kit. The FCS definition is found in [200,200]FCSRES.MAC on the RSX-11M/M-PLUS distribution kits. Since both files are quite long, we will not show them here, but will instead give examples which illustrate the ideas. .s1 The following is a MACRO-11 source file that defines a library containing at least the five entry points defined by using the MACRO-11 .GLOBL directive. .s1 .TEST PAGE 16 .nf ; ; RESLIB.MAC ; RESLIB - MACRO-11 definition file ; .TITLE RESLIB - Name of your library .IDENT /V1.0/ ; ; Global Entry points to include in library ; .GLOBL ENTRY1 ; A list of entry points .GLOBL ENTRY2 ; that you want included .GLOBL ENTRY3 ; in the library. .GLOBL ENTRY4 ; .GLOBL ENTRY5 ; .blank .END .fill .s1 After you have defined a library in this manner you assemble the definition file and task build it. The details of the task building will be discussed later. The library that is built using the above definition file will include the modules that contain the entry points specified. In addition, other modules will be included as necessary to resolve any undefined global entry points not included in the definition file. .s1 The FCS resident library which is built by SYSGEN is defined using an Overlay Descriptor Language file. After SYSGEN the file is found in [1,24] FCSRS1BLD.ODL. The ODL file defines the overlay structure of the library, the name of each module desired in the library and it's position in the library. The following is an example of how you can define a library using an ODL file. This version defines a library which is non-overlaid and contains the modules MOD1, MOD2, MOD3, MOD4, MOD5, MOD6. .s1 .TEST PAGE 13 .nf ; ; RESLIB.ODL ; RESLIB Overlay Description file ; .NAME RESLIB .ROOT RESLIB-LIB ; ; Names of modules to put in the library ; LIB: .FCTR LB:[1,1]SYSLIB/LB:MOD1:MOD2:MOD3-LIB1 LIB1: .FCTR LB:[1,1]SYSLIB/LB:MOD4:MOD5:MOD6 .blank .END .fill .s1 This ODL assumes that the modules named are in the system library on the current LB: device. The library is then linked by TKB. The library built from the above definition file will include the modules specified plus any other modules necessary to resolve all undefined global entry points not contained in the above modules. .s1 It is sometimes necessary or desireable to create libraries that use memory-resident overlays. By doing this, you can reduce the virtual address space requirements of both the library and the tasks that are linked to it. The FCS ODL file previously mentioned defines a 4K memory-resident overlaid library. You may define a memory overlaid library for all types of libraries except supervisor-mode libraries, which currently do not support that feature. The following ODL file is used to define a resident library or cluster library composed of the same set of modules used above in two memory-resident overlays. .s1 .TEST PAGE 16 .nf ; ; RESOVR.ODL ; Overlay Descriptor File for LIBOVR ; .NAME LIBOVR .ROOT LIBOVR-*!(OVR1,OVR2) ; ; Names of modules to put in the library ; .NAME SEG1 OVR1: .FCTR SEG1-LB:[1,1]SYSLIB/LB:MOD1:MOD2:MOD3 .blank .NAME SEG2 OVR2: .FCTR SEG2-LB:[1,1]SYSLIB/LB:MOD4:MOD5:MOD6 .blank .END .fill .s1 When defining overlaid libraries, care should be taken to be sure that modules from one segment do not reference modules in another segment. In the above example, none of the modules from SEG1 can access entry points in SEG2. .s2 .test page 4 .c 80;Building the Library .s1 After you have defined the library, you are ready to create the library using TKB. In the examples which follow, the commands necessary to build the library are assumed to be included in indirect command files which are submitted to TKB in the form: .s1 .nf TKB @filename .fill .s1 I prefer this mode of command input and will not give any examples using the multi-line input capability of the Task Builder. .s1 The Task Builder takes as input one of the library definitions described above. It produces the library task image, library symbol definition table (STB) and optionally a map of the library task image. .s1 The symbol definition file created by the Task Builder contains the linkage information concerning the shared region as well as global symbol definitions for all accessable entry points and their addresses. This file has the same format as a .OBJ file and is used as input to the Task Builder when linking to the library. The Task Builder uses the information from the .STB file in resolving calls from within the user task to locations within the library. .s1 If desired the Task Builder will generate a map of the library task image which will give you detailed information concerning task size, program sections, modules composing the library and the entry points into the library. Though not used by the Task Builder to link the library to user tasks, the map can be very useful in debugging, evaluating and changing the library contents. .s1 The commands necessary to build the library depend on the type of library you are building and the type of library definition file used. In the examples that follow I have shown the commands necessary to build a basic resident library. The additional commands necessary to build overlaid libraries, cluster libraries and supervisor libraries will be discussed in the sections that follow. .s1 The following file demonstrates how to build libraries defined with a MACRO-11 library definition. .s1 .TEST PAGE 12 .nf RESLIB/-HD/LI[/PI][,RESLIB/-SP/MA],RESLIB=RESLIB LB:[1,1]SYSLIB/LB / STACK=0 PAR=RESLIB:160000:20000 ; 4K Library in APR 7 TASK=RESLIB .blank : ; additional Task Builder : ; options necessary to build : ; cluster libraries and : ; supervisor-mode libraries // .fill .s1 In the next example, are shown the commands necessary when building a library that is defined using an ODL library definition file. .s1 .TEST PAGE 12 .nf RESLIB/-HD/LI[/PI][,RESLIB/-SP/MA],RESLIB=RESLIB/MP STACK=0 PAR=RESLIB:160000:20000 ; 4K Library in APR 7 TASK=RESLIB .blank : ; additional Task Builder : ; options necessary to build : ; memory overlaid libraries, : ; : ; cluster libraries and : ; supervisor-mode libraries // .fill .s1 To build a library by specifying a list of input modules you use a command file containing the following commands. Note that the following will build a 4K position independant library. .s1 .TEST PAGE 14 .nf RESLIB/-HD/LI/PI[,RESLIB/-SP/MA],RESLIB= LB:[1,1]SYSLIB/LB:MOD1:MOD2:MOD3 LB:[1,1]SYSLIB/LB:MOD4:MOD5:MOD6 LB:[1,1]SYSLIB/LB / STACK=0 PAR=RESLIB:0:20000 ; 4K position independant TASK=RESLIB .blank : ; additional Task Builder : ; options necessary to build : ; cluster libraries and : ; supervisor-mode libraries // .fill .s1 A number of switches are used in the above examples to control Task Builder functions. .list "o" .le; /-HD instructs the Task Builder to exclude the task header from the library task image. Since the library task is not an executable image, the header is not included. .le; /LI makes the Task Builder build a shared library. .le; /PI informs the Task Builder that the library contains only position independant code which can be loaded at any virtual address. Non-PIC libraries are always bound to the address specified using the PAR option. A library which has been built PIC but which contains some non-PIC code, will not function correctly. .le; /MA forces the Task Builder to include in the map file the names of routines it has added to your task from SYSLIB. .le; /MP informs TKB that the library definition file is an Overlay Description Language file. When specified, TKB receives all the input file specifications from this file and the ODL file can be the only input file specified. .le; /LB is used to tell TKB that one of the input files is an object module library. It is used either to extract a module out of the specified or to tell TKB that the OLB file is to be searched first for all unresolved global references. .els In addition to the switches, a few Task Builder options are used to give TKB information about the characteristics of your task. .list "o" .le;STACK=0 - this option is used to suppress the stack area in the library task image. It is not needed since the library task is not executable. .le;PAR=partition-name[:base:length] - this option identifies the partition name for which your task is built, the base address of the partition and the length of the partition in bytes. When building a shared library, the name of the partition name, .TSK name and .STB name must all be the same! .s1 If the library contains only PIC code, and the library is built with the /PI switch, the base address specified should be zero. This forces the addresses of all entry points within the library to be offsets from zero or zero based offsets. This allows the Task Builder to place the library at any free APR in the user task image. It then adds that base address to all entry point offsets in order to find the real addresses of all entry points in the library for use in resolving symbols in user tasks. .s1 If the library does not contain PIC code, the base address specified must be the base address of the APR where you are going to place the library. The library will always be placed at that address in user tasks. .els .s1 .c 80;Building Libraries with Memory-Resident Overlays .s1 When TKB builds a library with memory-resident overlays, it includes in the symbol definition file the overlay data base and the global references for the overlay run-time modules to be extracted from the system library. The symbol definition file also contains global definitions only for those symbols or entry points that are defined or referenced in the root segment of the library. If the symbol is not referenced in the root of the library you must force inclusion of the symbol into the root segment using the GBLREF option. This will cause TKB to generate a 4 word autoload vector for the symbol or entry point and include it in the symbol definition file. In libraries with null roots any symbol or entry point must be defined in this manner if access to the symbol or entry point is desired by user tasks. .s1 When the library is linked by TKB to a user task image, it includes the overlay run-time modules, overlay data base and all autoload vectors in the root of the task. This may have an adverse effect, especially if there are a large number of entry points and symbols within the library image. .s1 Care should be taken to make sure that all necessary entry points not referenced in the root are defined using the GBLREF option. If one is omitted, TKB will attempt to resolve the symbol by searching the system library. This may cause "MULTIPLY DEFINED SYMBOL" errors when linking the library to a user task. .s1 The following example illustrates how you would build the library previously defined in RESOVR.ODL. The entry points defined in the GBLREF statements are the entry points into MOD1, MOD2, ... MOD6. .s1 .TEST PAGE 9 .nf RESOVR/-HD/LI[/PI][,RESOVR/-SP/MA],RESOVR=RESOVR/MP STACK=0 PAR=RESOVR:160000:20000 ; 4K Library in APR 7 TASK=RESOVR .blank GBLREF=ENTRY1,ENTRY2,ENTRY3 ; Global references for GBLREF=ENTRY4,ENTRY5,ENTRY6 ; entry points not in ; root segment. // .fill .s2 .c 80;Building Cluster Libraries .s1 There are several rules which you must follow in designing and building cluster libraries. They are summarized here. You may find out more details concerning them in the TKB manual, section 5.2. .list "o" .le;All libraries with exception of the first must be memory-resident overlaid. The cluster library mechanism is an extension to the existing Task Builder overlay structures. The overlay run time system sees the library cluster as a null-rooted PLAS-overlaid co-tree, with each library of the cluster as a sub-tree. Each of these sub-trees, with exception of the first, must have a null root. This allows TKB to use its normal tree processing to build the task structure. The first library may also have a null root if desired. .s1 If the first library does not have a null root, it becomes the default library in the cluster. If all libraries have null roots, the first library accessed by the user task becomes the default library of the cluster. When any routine is referenced which is not in the default library, its mapping context is pushed onto the stack and the library containing the routine being referenced is mapped. Upon exit from the routine, the mapping context of the default library is restored. .le;User task vectors indirectly resolve all interlibrary references. In the example below, a call to the FCS .CLOSE routine appears in the library LIBRES. The .CLOSE routine is in the FCSRES library of the same cluster. LIBRES, however, cannot directly reference the FCSRES routine because it is not currently mapped by the user task. In Figure 2 the details of how the call to .CLOSE is revectored to the appropriate library are shown. .le;Revectored entry point symbols must not appear in the "Upstream" symbol definition file. A GBLXCL option must appear for each symbol being revectored to a "Downstream" library. .le;A called Library routine must not require parameters on the stack. Since the mapping context of the default library is saved on the stack whenever it is displaced, any routines not in the default library must not reference parameters on the stack using the stack pointer. They may, however, reference parameters on the stack if those parameters are referenced through some argument pointer (R5). This rule only applies to control transfers into cluster libraries. In addition, only JSR PC and RTS PC call and return conventions are allowed for routines in the library. .le;All libraries must be built PIC or built for the same address. This does not mean that all libraries in the cluster use the same number of APRs or the same number of address windows. It does require that they all be mapped to the same task virtual address. To enable this the libraries of the cluster must either be PIC or built for the same virtual address. .le;Trap or Asynchronous entry into a library is not allowed. This is not permitted since it is unknown which library or library segment will be mapped when the trap or fault occurs. .els .PAGE .nf ---------------------------- ------------------------- | | | | *1* | 164324: JSR PC,.CLOSE | | | *7* | : | | .CLOSE:: ; | *6* | : | | 162240: ; FCS .CLOSE | | : ; Module FCSVEC | | : ; routine | | : | | : ; | *2* | .CLOSE::MOV _#10,-(SP) | | : | | : JMP DISPAT | | : RTS PC | *7* | : | | | | : | | | *3* | DISPAT: MOV R0,-(SP) | | | | : MOV @_#.FSRPT,R0 | | | | : ADD A.JUMP(R0),2(SP) | | | : MOV (SP)+,R0 | | | | : MOV @(SP)+,-(SP) | | | *4* | : RTS PC | | | | | | | ---------------------------- ------------------------- LIBRES FCSRES .blank 2 ------------------------------------- | | | .FSRPT:: ; FCS impure area | | 1000: | | : | | : | | 1000+A.JUMP: .FCSJT | | : | | : | | : | | .FCSJT:: ; FCS jump table | | 2000: | | : | | : | | 2010: .CLOSE | | : | | : ; In psect $$ALVC | | : ; Autoload vectors | *4* | .CLOSE:: | | 3000: JSR PC,$AUTO | | : Segment desc. addr. | | : 162240 | | : | *5* | $AUTO:: : | | : : ; Load segment | | : : | *6* | : JMP 162240 | | | ------------------------------------- User Task .blank 2 FIGURE 2 .fill .page The clustering mechanism shown in the above example is composed of the following steps. .list .le;A call to the .CLOSE routine is initiated in the library LIBRES. .le;The .CLOSE routine is defined as a global entry point in the module FCSVEC which has been included in LIBRES. Control is transferred to that location where a table offset into the FCSJMP table is pushed onto the stack. .le;The address of the FCS impure data area in user task is then obtained by using the pointer .FSRPT. At the offset A.JUMP in the FCS data area is the address of the FCS jump table. In this example the table contains the addresses of the autoload vectors for each FCS entry point. This addresss is then added to the table offset previously pushed on the stack and is then used to replace itself with the address of the .CLOSE autoload vector. After restoring R0, this address is at the top of the stack. .le;A return is then executed by the dispatch code transferring control to the autoload vector for .CLOSE. .le; The current mapping context is pushed on the stack and the segment containing the called symbol is mapped by the overlay run-time system. .le;A JMP is then executed to transfer control to the .CLOSE routine in the FCSRES library. .le;Upon return (RTS) from the .CLOSE routine. The mapping context saved on the stack is restored and control is transferred back to LIBRES. .els Because FCSVEC is included, all the FCS global entry points will appear in the symbol table of library LIBRES, and will be visible to the user task in both LIBRES and FCSRES. In order to eliminate multiply defined symbols, you must use the GBLXCL option for each global symbol that is revectored from the calling library to the FCSRES library. The GBLXCL option causes references to the symbol named to be excluded from the symbol table and thus eliminates multiply defined symbols. .s1 Using the above rules and principles the cluster library is built using the following commands to TKB. .s1 .TEST PAGE 21 .nf CLSLIB/-HD/LI[/PI][,CLSLIB/-SP/MA],CLSLIB=CLSLIB LB:[1,1]SYSLIB/LB:FCSVEC ; FCS vector routine LB:[1,1]SYSLIB/LB / STACK=0 PAR=CLSLIB:160000:20000 ; 4K Library in APR 7 TASK=CLSLIB ; ; Force the FCS jump table to be included in ; the root of the user task. ; GBLINC=.FCSJT ; ; Eliminate any references to FCS-11 entry points ; from the library symbol table. ; GBLXCL=.CLOSE,.CSI1,.CSI2,.DLFNB,.FINIT GBLXCL=.GET,.GETSQ,.GTDID,.MRKDL,.OPFNB GBLXCL=.PARSE,.POINT,.POSRC,.PRINT,.PUT GBLXCL=.PUTSQ,.SAVR1,.READ,.WAIT // .fill .S1 Since TKB searches the system library to resolve any undefined global references in the library, it is possible to have a global entry point defined in more than one library. Should this condition occur, you must eliminate the symbol from all but one of the libraries using the GBLXCL option. If this is not done, TKB will return multiply defined errors for each symbol duplicated. .s1 Cluster libraries built with this mechanism can also be used as non-clustered libraries. In the above example CLSLIB is linked to FCSRES via the cluster library linkage mechanism. The two libraries can be used in any of the following forms: .list "o" .le; Either library can be used by itself using the LIBR= option of the Task Builder. .le; Both libraries can be used jointly using the LIBR= option. It is assumed that no address conflict exists between the two libraries. .le; Under RSX-11M/PLUS, CLSLIB can be linked to using the LIBR= option and the supervisor-mode library FCSFSL can be linked to using the SUPLIB= option. .le; Finally, both libraries can be accessed using the CLSTR= option. .els This mechanism gives you a great deal of flexibility, which is a very important item when designing libraries. .s2 .c 80;Building Supervisor-Mode Libraries .s1 Building a supervisor mode library is not much different from building any other kind of library. The following example shows a sample build file necessary to build a supervisor-mode library. The CMPRT option informs the Task Builder that you are building a supervisor mode library. .s1 .TEST PAGE 19 .nf SUPRES/-HD/LI/PI[,SUPRES/-SP/MA],SUPRES=SUPRES LB:[1,1]SYSLIB/LB / STACK=0 PAR=SUPRES:0:100000 ; 16 K library TASK=SUPRES ; ; Specify the return to user mode completion routine ; CMPRT=$CMPCS ; ; Eliminate any modules which may be included in the ; user task as well as in the supervisor-mode library ; from the symbol table. ; GBLXCL=module-name : : // .fill .S1 There are certain restrictions in using supervisor-mode libraries that you should know before designing and building one. .list "o" .le;You should only include routines that use the JSR PC, X and RTS PC call and return sequence in the library. .le;If an entry point exists in the library and in the user task, it must be eliminated from the library symbol table using the GBLXCL option. .le;Generally, the library may not contain data of any kind. Supervisor-mode libraries that contain data require very complicated mapping which can result in the user task being overwritten. I will refer you to the Task Builder manual for further information on how to access data with supervisor-mode libraries. .le;The library may not contain routines that receive parameters passed on the stack. .els .s1 Unfortunately, I have not had much experience with supervisor-mode libraries and will have to refer you to the manuals for more details. .s2 .c 80;Installing the Library in Your System .s1 The Task Builder by default looks for all library symbol definition files in LB:[1,1]. It is therefore recommended that you put both the library task image and symbol table there for safe keeping. .s1 After defining and linking your library, you are ready to install it in your system. At WCC we do this by creating a new bootable system image using VMR. This is not an uncommon occurance, since we are always trying to get a little more juice from the machine. .s1 Each library is installed in a partition of the same name as the task. This partition must be at least as big as the task. It may be larger, but this is not recommended since the whole idea in using libraries is to save memory. The size of the task is determined by examining the map created by the Task Builder. The following is an example of what to look for. .s1 .test page 9 .nf WCIRES.TSK Memory allocation map TKB M40.02 Partition name : WCIRES Identification : 01 Task UIC : [300,70] Task attributes: -HD Total address windows: 1. ** Task image size : 4096. words ** Task address limits: 160000 177777 R-W disk blk limits: 000003 000022 000020 00016. .fill .s1 The key figure in determining task size is the 'Task image size' as specified in the map above. The task size is always rounded up to the next 32 word boundary. When specifying the partition size it is expressed as the number of 32 word blocks necessary to hold the task. .noperiod In this case it is 4096. divided by 32. or .period 128. After creating the partition, the task is installed in the partition and if you are running under RSX-11M-PLUS you may also fix that task in memory. .s1 The VMR commands necessary to create the partition and to install and fix the library are shown here. .s1 .test page 3 .nf SET /PAR=WCIRES:*:128. ; Create partition INS LB:[1,1]WCIRES[/PAR=WCIRES] ; Install library FIX WCIRES/REG ; Fix library image .fill .s1 For the purposes of building, testing and debugging the library, you may want to temporarily install the library in a partition which is larger than the library. This is done to allow the library to increase in size without having to enlarge the partition it resides in. When work is completed on the library, you can then permanently install it in a partition of the correct size. .s1 One thing I have noticed is that the SYSGEN procedure often supplies you with the wrong partition sizes for partitions generated by SYSGEN. If you are in a pinch for memory you can recover this space by creating a new system image with smaller partitions. You can use the MCR PAR command to find out if the partitions in the system are of the correct size. .s2 .TEST PAGE 4 .c 80;Using Resident Libraries .s1 All of the work we have done above is nothing if the users of your system do not take advantage of what you have done. Speaking from experience, I strongly suggest that you educate your users in the hows and whys of using resident libraries. .s1 Here are three basic rules that I believe can be helpful in teaching your users how to use libraries. .list .le;If a Library is available which contains routines you are using, link it to your task. One of the reasons you chose to use a library was to conserve memory by reducing task size, this cannot be done if the libraries are not used. Use as many libraries as possible which contain routines that you use. .le;Do not use clustered libraries unless absolutely necessary. The cluster library overlay mechanism is very costly in terms of time. If you have free APRs in your task and can link to the libraries without using a library cluster, do it. Clustered libraries should only be used when a task needs to use many libraries but does not have sufficient space to link to them in a non-clustered environment. Libraries built to be used in a cluster may also be used in a non clustered environment. .le;If you are running under RSX-11M/PLUS use the FCS supervisor mode library (FCSFSL) rather than the FCS Plas overlaid library (FCSRES). The reason is simple. The FCS supervisor mode library does not take any space away from your task since it is mapped using the supervisors I-space APRs. This may allow you to link to another library without using a cluster library structure or it may allow you to simplify your task's overlay structure. .els The commands given to the Task Builder to link a library to a user task depend on the type of library or library structure you task requires. The following TKB options are used to specify the type of library configuration you need. .list "o" .le; For non-clustered and non-supervisor-mode libraries one of the following two TKB options is used. .s1 .test page 2 .nf LIBR=name:access-code[:apr] RESLIB=file-spec/access-code[:apr] .fill .le; Clustered libraries use the following TKB option. .nf CLSTR=name1,name2[,...[,name6]]:access-code[:apr] .fill .le; Supervisor-mode libraries are specified by using one of the following TKB options. .s1 .test page 2 .nf SUPLIB=name:[-]SV[:apr] RESSUP=file-spec/[-]SV[:apr] .fill .els .s1 The elements of the keywords are defined as follows: .list "o" .le;NAME - the name of a "system controlled" library. By "system controlled", we mean the library task image and symbol table reside in LB:[1,1]. .le;FILE-SPEC - the file specification of a "user owned" library. A "user owned" library task image and symbol table may reside in any UIC. .le;ACCESS-CODE - either read-write (RW) or read-only (RO). .le;APR - If the library is built as a PIC library, you may place the library in any of the free APRs not used by the task. .le;[-]SV - Informs TKB whether you will use mode switching vectors as provided by TKB (SV) or whether you will be providing your own (-SV). .els .s1 For the purposes of example, suppose we have the following 3 libraries available to us. .list "o" .le; CLSLIB - a 4KW cluster library linked to FCSRES using the cluster library linkage mechanism. The library is non-PIC and is built at address 160000. .le; RESLIB - a 4KW null-rooted library which is built PIC. .le; FCSRES - the 4KW standard FCS library distributed by DEC. .els .s1 We have two tasks of different sizes which we want to link to the libraries which are available on the system. The tasks are described as follows: .s1 .test page 20 .nf 32 +-----------------------+ +-----------------------+ | | | | 28 | | |///////////////////////| | | |///////////////////////| 24 | | |///////////////////////| | | |///////////////////////| 20 | | |///////////////////////| | | |///////////////////////| 16 | | |///////////////////////| |///////////////////////| |///////////////////////| 12 |///////////////////////| |///////////////////////| |///////////////////////| |///////////////////////| 8 |///////////////////////| |///////////////////////| |///////////////////////| |///////////////////////| 4 |///////////////////////| |///////////////////////| |///////////////////////| |///////////////////////| 0 +-----------------------+ +-----------------------+ .blank TASKA TASKB .fill .s1 TASKA is a 14KW task which allows us to use almost any library configuration we want. The best configuration however is one in which all 3 libraries are linked using the LIBR= option. This gives us the best access to routines in the libraries without any speed delays. .s1 TASKB is a 28K task which limits us somewhat in the way we map the libraries. Let us assume that we are not able to recover sufficient address space in the task by using libraries to link all 3 libraries with the LIBR= option of the Task Builder. Let us also assume that we are able to recover enough address space so we have 2 free APRs. Given these parameters, one of the library configurations which we could use would be the following. .s1 .nf LIBR=FCSRES:RO CLSTR=CLSLIB,RESLIB:RO .fill .s1 If it was determined that TASKB did not use any of the routines in one of the libraries then the two remaining libraries could be linked using the LIBR= option. .s1 The library configuration above is best if TASKB is I/O intensive. If TASKB uses routines in RESLIB extensively and does very little I/O then the following configuration is better: .s1 .nf LIBR=RESLIB:RO CLSTR=CLSLIB,FCSRES:RO .fill .s1 If you have questions as to which configuration of your libraries is best for a given task, try it with each possibility and check the time results. .S2 .C 80;Linking One Library to Another .s1 .s1 In addition to linking user tasks to libraries, it is possible to link one shared library to another. It can be advantageous to have the code in one library linked to the code in another library. The disadvantage is that in order to use the first library, there must also be enough virtual address space in the user task to contain the second library. .s1 There are two exceptions that must be adhered to when linking libraries together. .list "o" .le;Cluster libraries cannot link to libraries within the same cluster unless they use the cluster library linkage mechanism described previously. .le;Supervisor-mode libraries cannot link to other supervisor-mode libraries or to user-mode libraries. .els .s1 .TEST PAGE 4 .c 80;Library Speed Considerations .s1 There is some time overhead in using the library features of clustering and memory resident overlays. To demonstrate this, I wrote the following little program as a speed test. .s1 .TEST PAGE 24 .nf PROGRAM TIME IMPLICIT INTEGER (A-Z) BYTE BUFF(100) INTEGER START(8), END(8) INTEGER*4 MAX, I 1 FORMAT (' ',8I3) .blank MAX=10000 5 CALL GETIM(START) .blank DO 10 I=1,MAX X = IMOD(100,2) CALL BYTSET(100,0,BUFF) 10 CONTINUE .blank CALL GETIM(END) WRITE (5,1) END WRITE (5,1) START IF (MAX .EQ. 100000) CALL EXIT MAX = 100000 GOTO 5 END .FILL .S1 The previous module was compiled and then task built in one of 3 different ways. .list "o" .le;TEST1 - With no libraries. .le;TEST2 - With a library using the TKB option .s1 .nf LIBR=WCCOVR:RO .fill .s1 where WCCOVR is a null-rooted overlaid library contained the F77 modules (IMOD) in one segment and our software specific modules (BYTSET) in the other segment. .le;TEST3 - With a library cluster built with the following TKB option. .s1 .nf CLSTR=F77RES,WCIRES:RO .fill .s1 F77RES in this example was a non-overlaid library containing the F77 OTS modules (IMOD) and WCIRES a null-rooted library containing our software specific modules (BYTSET). .els .s1 The purpose of the test was to force the overlay run-time system to switch back and forth between memory overlays or clustered libraries. This is by no means an exhaustive test and you may want to do more testing on your own. The results are presented for your study. .s1 .test page 6 .nf MAX | TIME TEST1 | TIME TEST2 | TIME TEST3 ----------+---------------+---------------+--------------- 10000 | 2:28 | 2:35 | 19:51 | | | 100000 | 24:34 | 25:35 | 3:18:21 | | | .FILL .S1 No real appreciable difference is found between TEST1 and TEST2. TEST3, however, displays the real cost of having a frequently used library as the non-default member of a library cluster. .s2 .c 80;General Library Considerations .s1 At our site, we develop software that is generally run on the systems distributed by us. Currently we have in the field numerous 11/23's, 11/34's, 11/44's and 11/70's. The big issue for us was to choose a library configuration that could be used on all of the systems we distribute. For that reason, we could not use supervisor-mode libraries or libraries that were too large to be used effectively on 11/34's and 11/23's. If you are in the same position, transportability may be something you want to consider as well. .s1 As previously mentioned, the code that goes into a library should be well tested and free of bugs. It should also be in a static state of change. It can be frustrating to find that the module in SYSLIB.OLB has been changed so that it works differently than the one in the library. .s1 I would like to request that DEC supply, along with the OTS manuals for layered products, a list of the OTS modules that receive parameters passed through the stack pointer. This would be of great help in designing and building libraries. .s2 .c 80;Summary .s1 The Task Builder has provided us with the capability of doing some very nice things with shared libraries. Whether or not you will be able to use any of these features depends a lot on your particular application and on your willingness to do a little experimenting with the concepts presented. You won't know if libraries can be of use to your system or application until you try it. Go home and try them out. They really do work! .s2 .c;Good Luck! I hope this has been worthwhile.