lib/libpmc/pmclog.3

   1 .\" Copyright (c) 2005-2006 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .Dd March 26, 2006
  25 .Dt PMCLOG 3
  26 .Os
  27 .Sh NAME
  28 .Nm pmclog_open ,
  29 .Nm pmclog_close ,
  30 .Nm pmclog_read ,
  31 .Nm pmclog_feed
  32 .Nd parse event log data generated by
  33 .Xr hwpmc 4
  34 .Sh LIBRARY
  35 .Lb libpmc
  36 .Sh SYNOPSIS
  37 .In pmclog.h
  38 .Ft "void *"
  39 .Fn pmclog_open "int fd"
  40 .Ft void
  41 .Fn pmclog_close "void *cookie"
  42 .Ft int
  43 .Fn pmclog_read "void *cookie" "struct pmclog_ev *ev"
  44 .Ft int
  45 .Fn pmclog_feed "void *cookie" "char *data" "int len"
  46 .Sh DESCRIPTION
  47 These functions provide a way for application programs to extract
  48 events from an event stream generated by
  49 .Xr hwpmc 4 .
  50 .Pp
  51 A new event log parser is allocated using
  52 .Fn pmclog_open .
  53 Argument
  54 .Fa fd
  55 may be a file descriptor opened for reading if the event stream is
  56 present in a file, or the constant
  57 .Dv PMCLOG_FD_NONE
  58 for an event stream present in memory.
  59 This function returns a cookie that is passed into the other functions
  60 in this API set.
  61 .Pp
  62 Function
  63 .Fn pmclog_read
  64 returns the next available event in the event stream associated with
  65 argument
  66 .Fa cookie .
  67 Argument
  68 .Fa ev
  69 points to an event descriptor that which will contain the result of a
  70 successfully parsed event.
  71 .Pp
  72 An event descriptor returned by
  73 .Fn pmclog_read
  74 has the following structure:
  75 .Bd -literal
  76 struct pmclog_ev {
  77        enum pmclog_state pl_state;      /* parser state after 'get_event()' */
  78        off_t             pl_offset;     /* byte offset in stream */
  79        size_t            pl_count;      /* count of records so far */
  80        struct timespec   pl_ts;         /* log entry timestamp */
  81        enum pmclog_type  pl_type;       /* log entry kind */
  82        union {                          /* log entry data */
  83                 struct pmclog_ev_callchain   pl_cc;
  84                 struct pmclog_ev_closelog    pl_cl;
  85                 struct pmclog_ev_dropnotify  pl_d;
  86                 struct pmclog_ev_initialize  pl_i;
  87                 struct pmclog_ev_map_in      pl_mi;
  88                 struct pmclog_ev_map_out     pl_mo;
  89                 struct pmclog_ev_pmcallocate pl_a;
  90                 struct pmclog_ev_pmcallocatedyn pl_ad;
  91                 struct pmclog_ev_pmcattach   pl_t;
  92                 struct pmclog_ev_pmcdetach   pl_d;
  93                 struct pmclog_ev_proccsw     pl_c;
  94                 struct pmclog_ev_procexec    pl_x;
  95                 struct pmclog_ev_procexit    pl_e;
  96                 struct pmclog_ev_procfork    pl_f;
  97                 struct pmclog_ev_sysexit     pl_e;
  98                 struct pmclog_ev_userdata    pl_u;
  99        } pl_u;
 100 };
 101 .Ed
 102 .Pp
 103 The current state of the parser is recorded in
 104 .Va pl_state .
 105 This field can take on the following values:
 106 .Bl -tag -width ".Dv PMCLOG_REQUIRE_DATA"
 107 .It Dv PMCLOG_EOF
 108 (For file based parsers only)
 109 An end-of-file condition was encountered on the configured file
 110 descriptor.
 111 .It Dv PMCLOG_ERROR
 112 An error occurred during parsing.
 113 .It Dv PMCLOG_OK
 114 A complete event record was read into
 115 .Fa *ev .
 116 .It Dv PMCLOG_REQUIRE_DATA
 117 There was insufficient data in the event stream to assemble a complete
 118 event record.
 119 For memory based parsers, more data can be fed to the
 120 parser using function
 121 .Fn pmclog_feed .
 122 For file based parsers, function
 123 .Fn pmclog_read
 124 may be retried when data is available on the configured file
 125 descriptor.
 126 .El
 127 .Pp
 128 The rest of the event structure is valid only if field
 129 .Va pl_state
 130 contains
 131 .Dv PMCLOG_OK .
 132 Field
 133 .Va pl_offset
 134 contains the offset of the current record in the byte stream.
 135 Field
 136 .Va pl_count
 137 contains the serial number of this event.
 138 Field
 139 .Va pl_ts
 140 contains a timestamp with the system time when the event occurred.
 141 Field
 142 .Va pl_type
 143 denotes the kind of the event returned in argument
 144 .Fa *ev
 145 and is one of the following:
 146 .Bl -tag -width ".Dv PMCLOG_TYPE_PMCALLOCATE"
 147 .It Dv PMCLOG_TYPE_CLOSELOG
 148 A marker indicating a successful close of a log file.
 149 This record will be the last record of a log file.
 150 .It Dv PMCLOG_TYPE_DROPNOTIFY
 151 A marker indicating that
 152 .Xr hwpmc 4
 153 had to drop data due to a resource constraint.
 154 .It Dv PMCLOG_TYPE_INITIALIZE
 155 An initialization record.
 156 This is the first record in a log file.
 157 .It Dv PMCLOG_TYPE_MAP_IN
 158 A record describing the introduction of a mapping to an executable
 159 object by a
 160 .Xr kldload 2
 161 or
 162 .Xr mmap 2
 163 system call.
 164 .It Dv PMCLOG_TYPE_MAP_OUT
 165 A record describing the removal of a mapping to an executable
 166 object by a
 167 .Xr kldunload 2
 168 or
 169 .Xr munmap 2
 170 system call.
 171 .It Dv PMCLOG_TYPE_PCSAMPLE
 172 A record containing an instruction pointer sample.
 173 .It Dv PMCLOG_TYPE_PMCALLOCATE
 174 A record describing a PMC allocation operation.
 175 .It Dv PMCLOG_TYPE_PMCATTACH
 176 A record describing a PMC attach operation.
 177 .It Dv PMCLOG_TYPE_PMCDETACH
 178 A record describing a PMC detach operation.
 179 .It Dv PMCLOG_TYPE_PROCCSW
 180 A record describing a PMC reading at the time of a process context switch.
 181 .It Dv PMCLOG_TYPE_PROCEXEC
 182 A record describing an
 183 .Xr execve 2
 184 by a target process.
 185 .It Dv PMCLOG_TYPE_PROCEXIT
 186 A record describing the accumulated PMC reading for a process at the
 187 time of
 188 .Xr _exit 2 .
 189 .It Dv PMCLOG_TYPE_PROCFORK
 190 A record describing a
 191 .Xr fork 2
 192 by a target process.
 193 .It Dv PMCLOG_TYPE_SYSEXIT
 194 A record describing a process exit, sent to processes
 195 owning system-wide sampling PMCs.
 196 .It Dv PMCLOG_TYPE_USERDATA
 197 A record containing user data.
 198 .El
 199 .Pp
 200 Function
 201 .Fn pmclog_feed
 202 is used with parsers configured to parse memory based event streams.
 203 It is intended to be called when function
 204 .Fn pmclog_read
 205 indicates the need for more data by a returning
 206 .Dv PMCLOG_REQUIRE_DATA
 207 in field
 208 .Va pl_state
 209 of its event structure argument.
 210 Argument
 211 .Fa data
 212 points to the start of a memory buffer containing fresh event data.
 213 Argument
 214 .Fa len
 215 indicates the number of data bytes available.
 216 The memory range
 217 .Bq Fa data , Fa data No + Fa len
 218 must remain valid till the next time
 219 .Fn pmclog_read
 220 returns an error.
 221 It is an error to use
 222 .Fn pmclog_feed
 223 on a parser configured to parse file data.
 224 .Pp
 225 Function
 226 .Fn pmclog_close
 227 releases the internal state allocated by a prior call
 228 to
 229 .Fn pmclog_open .
 230 .Sh RETURN VALUES
 231 Function
 232 .Fn pmclog_open
 233 will return a
 234 .No non- Ns Dv NULL
 235 value if successful or
 236 .Dv NULL
 237 otherwise.
 238 .Pp
 239 Function
 240 .Fn pmclog_read
 241 will return 0 in case a complete event record was successfully read,
 242 or will return \-1 and will set the
 243 .Va pl_state
 244 field of the event record to the appropriate code in case of an error.
 245 .Pp
 246 Function
 247 .Fn pmclog_feed
 248 will return 0 on success or \-1 in case of failure.
 249 .Sh EXAMPLES
 250 A template for using the log file parsing API is shown below in pseudocode:
 251 .Bd -literal
 252 void *parser;                   /* cookie */
 253 struct pmclog_ev ev;            /* parsed event */
 254 int fd;                         /* file descriptor */
 255
 256 fd = open(filename, O_RDONLY);  /* open log file */
 257 parser = pmclog_open(fd);       /* initialize parser */
 258 if (parser == NULL)
 259         --handle an out of memory error--;
 260
 261 /* read and parse data */
 262 while (pmclog_read(parser, &ev) == 0) {
 263         assert(ev.pl_state == PMCLOG_OK);
 264         /* process the event */
 265         switch (ev.pl_type) {
 266         case PMCLOG_TYPE_ALLOCATE:
 267                 --process a pmc allocation record--
 268                 break;
 269         case PMCLOG_TYPE_PROCCSW:
 270                 --process a thread context switch record--
 271                 break;
 272         case PMCLOG_TYPE_CALLCHAIN:
 273                 --process a callchain sample--
 274                 break;
 275         --and so on--
 276         }
 277 }
 278
 279 /* examine parser state */
 280 switch (ev.pl_state) {
 281 case PMCLOG_EOF:
 282         --normal termination--
 283         break;
 284 case PMCLOG_ERROR:
 285         --look at errno here--
 286         break;
 287 case PMCLOG_REQUIRE_DATA:
 288         --arrange for more data to be available for parsing--
 289         break;
 290 default:
 291         assert(0);
 292         /*NOTREACHED*/
 293 }
 294
 295 pmclog_close(parser);           /* cleanup */
 296 .Ed
 297 .Sh ERRORS
 298 A call to
 299 .Fn pmclog_init_parser
 300 may fail with any of the errors returned by
 301 .Xr malloc 3 .
 302 .Pp
 303 A call to
 304 .Fn pmclog_read
 305 for a file based parser may fail with any of the errors returned by
 306 .Xr read 2 .
 307 .Sh SEE ALSO
 308 .Xr read 2 ,
 309 .Xr malloc 3 ,
 310 .Xr pmc 3 ,
 311 .Xr hwpmc 4 ,
 312 .Xr pmcstat 8
 313 .Sh HISTORY
 314 The
 315 .Nm pmclog
 316 API first appeared in
 317 .Fx 6.0 .