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