1 /* This Source Code Form is subject to the terms of the Mozilla Public
2  * License, v. 2.0. If a copy of the MPL was not distributed with this
3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4 
5 /*
6 ** nssilock.h - Instrumented locking functions for NSS
7 **
8 ** Description:
9 **    nssilock provides instrumentation for locks and monitors in
10 **    the NSS libraries. The instrumentation, when enabled, causes
11 **    each call to the instrumented function to record data about
12 **    the call to an external file. The external file
13 **    subsequently used to extract performance data and other
14 **    statistical information about the operation of locks used in
15 **    the nss library.
16 **
17 **    To enable compilation with instrumentation, build NSS with
18 **    the compile time switch NEED_NSS_ILOCK defined.
19 **
20 **    say:  "gmake OS_CFLAGS+=-DNEED_NSS_ILOCK" at make time.
21 **
22 **    At runtime, to enable recording from nssilock, one or more
23 **    environment variables must be set. For each nssILockType to
24 **    be recorded, an environment variable of the form NSS_ILOCK_x
25 **    must be set to 1. For example:
26 **
27 **       set NSS_ILOCK_Cert=1
28 **
29 **    nssilock uses PRLOG is used to record to trace data. The
30 **    PRLogModule name associated with nssilock data is: "nssilock".
31 **    To enable recording of nssilock data you will need to set the
32 **    environment variable NSPR_LOG_MODULES to enable
33 **    recording for the nssilock log module. Similarly, you will
34 **    need to set the environment variable NSPR_LOG_FILE to specify
35 **    the filename to receive the recorded data. See prlog.h for usage.
36 **    Example:
37 **
38 **        export NSPR_LOG_MODULES=nssilock:6
39 **        export NSPR_LOG_FILE=xxxLogfile
40 **
41 ** Operation:
42 **    nssilock wraps calls to NSPR's PZLock and PZMonitor functions
43 **    with similarly named functions: PZ_NewLock(), etc. When NSS is
44 **    built with lock instrumentation enabled, the PZ* functions are
45 **    compiled into NSS; when lock instrumentation is disabled,
46 **    calls to PZ* functions are directly mapped to PR* functions
47 **    and the instrumentation arguments to the PZ* functions are
48 **    compiled away.
49 **
50 **
51 ** File Format:
52 **    The format of the external file is implementation
53 **    dependent. Where NSPR's PR_LOG() function is used, the file
54 **    contains data defined for PR_LOG() plus the data written by
55 **    the wrapped function. On some platforms and under some
56 **    circumstances, platform dependent logging or
57 **    instrumentation probes may be used. In any case, the
58 **    relevant data provided by the lock instrumentation is:
59 **
60 **      lockType, func, address, duration, line, file [heldTime]
61 **
62 **    where:
63 **
64 **       lockType: a character representation of nssILockType for the
65 **       call. e.g. ... "cert"
66 **
67 **       func: the function doing the tracing. e.g. "NewLock"
68 **
69 **       address: address of the instrumented lock or monitor
70 **
71 **       duration: is how long was spent in the instrumented function,
72 **       in PRIntervalTime "ticks".
73 **
74 **       line: the line number within the calling function
75 **
76 **       file: the file from which the call was made
77 **
78 **       heldTime: how long the lock/monitor was held. field
79 **       present only for PZ_Unlock() and PZ_ExitMonitor().
80 **
81 ** Design Notes:
82 **    The design for lock instrumentation was influenced by the
83 **    need to gather performance data on NSS 3.x. It is intended
84 **    that the effort to modify NSS to use lock instrumentation
85 **    be minimized. Existing calls to locking functions need only
86 **    have their names changed to the instrumentation function
87 **    names.
88 **
89 ** Private NSS Interface:
90 **    nssilock.h defines a private interface for use by NSS.
91 **    nssilock.h is experimental in nature and is subject to
92 **    change or revocation without notice. ... Don't mess with
93 **    it.
94 **
95 */
96 
97 /*
98  * $Id:
99  */
100 
101 #ifndef _NSSILCKT_H_
102 #define _NSSILCKT_H_
103 
104 #include "utilrename.h"
105 #include "prtypes.h"
106 #include "prmon.h"
107 #include "prlock.h"
108 #include "prcvar.h"
109 
110 typedef enum {
111     nssILockArena = 0,
112     nssILockSession = 1,
113     nssILockObject = 2,
114     nssILockRefLock = 3,
115     nssILockCert = 4,
116     nssILockCertDB = 5,
117     nssILockDBM = 6,
118     nssILockCache = 7,
119     nssILockSSL = 8,
120     nssILockList = 9,
121     nssILockSlot = 10,
122     nssILockFreelist = 11,
123     nssILockOID = 12,
124     nssILockAttribute = 13,
125     nssILockPK11cxt = 14, /* pk11context */
126     nssILockRWLock = 15,
127     nssILockOther = 16,
128     nssILockSelfServ = 17,
129     nssILockKeyDB = 18,
130     nssILockLast /* don't use this one! */
131 } nssILockType;
132 
133 /*
134 ** conditionally compile in nssilock features
135 */
136 #if defined(NEED_NSS_ILOCK)
137 
138 /*
139 ** Declare operation type enumerator
140 ** enumerations identify the function being performed
141 */
142 typedef enum {
143     FlushTT = 0,
144     NewLock = 1,
145     Lock = 2,
146     Unlock = 3,
147     DestroyLock = 4,
148     NewCondVar = 5,
149     WaitCondVar = 6,
150     NotifyCondVar = 7,
151     NotifyAllCondVar = 8,
152     DestroyCondVar = 9,
153     NewMonitor = 10,
154     EnterMonitor = 11,
155     ExitMonitor = 12,
156     Notify = 13,
157     NotifyAll = 14,
158     Wait = 15,
159     DestroyMonitor = 16
160 } nssILockOp;
161 
162 /*
163 ** Declare the trace record
164 */
165 struct pzTrace_s {
166     pthread_t threadID;      /* PR_GetThreadID() */
167     nssILockOp op;           /* operation being performed */
168     nssILockType ltype;      /* lock type identifier */
169     PRIntervalTime callTime; /* time spent in function */
170     PRIntervalTime heldTime; /* lock held time, or -1 */
171     void *lock;              /* address of lock structure */
172     PRIntn line;             /* line number */
173     char file[24];           /* filename */
174 };
175 
176 /*
177 ** declare opaque types. See: nssilock.c
178 */
179 typedef struct pzlock_s PZLock;
180 typedef struct pzcondvar_s PZCondVar;
181 typedef struct pzmonitor_s PZMonitor;
182 
183 #else /* NEED_NSS_ILOCK */
184 
185 #define PZLock PRLock
186 #define PZCondVar PRCondVar
187 #define PZMonitor PRMonitor
188 
189 #endif /* NEED_NSS_ILOCK */
190 
191 #endif /* _NSSILCKT_H_ */
192