xref: /5.5.2/phosphor/docs/Architecture.md (revision bcc011a6)
1# Phosphor Architecture
2
3## Frontend
4
5The frontend consists of two main interfaces:
6
7- Instrumentation Macros
8- TraceLog / TraceLogConfig / TraceConfig
9
10### Instrumentation Macros
11
12The instrumentation macros are basically wrappers around the TraceLog::logEvent
13member functions. There are also some additional utilities, such as the scoped
14macros.
15
16### TraceLog
17
18The TraceLog is the primary interface used for interacting with Phosphor
19externally. It is used by the instrumentation macros for actually logging events
20and also used directly by end users for configuration etc.
21
22The TraceLog encapsulates most of the logic for actually managing tracing
23tracing events and tying all the parts of the system together.
24
25#### TraceLogConfig
26
27The TraceLogConfig class is used to perform one-time configuration of a
28TraceLog and consists of configuration that can only performed once.
29
30#### TraceConfig
31
32The TraceConfig class is used to perform per-trace configuration of a TraceLog
33and is passed directly to the TraceLog::start member function.
34
35## Backend
36
37### TraceEvent
38
39The TraceEvent class represents a singular event which contains a name,
40category, timestamp (Which is accurate/meaningful relative to other events) and
41optional arguments along with the type for those arguments.
42
43### TraceChunk
44
45A TraceChunk is conceptually a collection of TraceEvents and contains 1 or more
46pages worth of TraceEvents.
47
48### TraceBuffer
49
50The TraceBuffer is a collection of TraceChunks. It loans TraceChunks out to
51ChunkTenants.
52
53### ChunkTenant
54
55A ChunkTenant is conceptually an object which borrows a TraceChunk from a
56TraceBuffer. A ChunkTenant can either be allocated per-thread (In the event that
57threads have been registered appropriately) or can be shared using a pool of
58ChunkTenants distributed by thread id. A ChunkTenant has two main parts
59
60 - A pointer to the currently borrowed chunk (Or nullptr if not currently
61   borrowing one).
62 - A ChunkLock
63
64#### ChunkLock
65
66The ChunkLock is used to guard access to a Chunk. It is conceptually similar to
67a reader/writer lock that only allows a single reader. It has three states:
68
69 * Unlocked
70 * SlaveLocked, locked by the TraceLog::logEvent frontend
71 * MasterLocked, locked by the TraceLog::evictThreads backend
72
73There are two distinct lock states as front-end consumers via logEvent will not
74be blocked by the `MasterLocked` state (it uses try_lock). The reason for this
75is that if the ChunkLock has been locked via the `evictThreads` route then
76tracing will be shut down and front-end consumers don't need to acquire the
77lock.
78