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