Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PMCLOG(3)	       FreeBSD Library Functions Manual		     PMCLOG(3)

NAME
     pmclog_open, pmclog_close,	pmclog_read, pmclog_feed -- parse event	log
     data generated by hwpmc(4)

LIBRARY
     Performance Monitoring Counters Interface Library (libpmc,	-lpmc)

SYNOPSIS
     #include <pmclog.h>

     void *
     pmclog_open(int fd);

     void
     pmclog_close(void *cookie);

     int
     pmclog_read(void *cookie, struct pmclog_ev	*ev);

     int
     pmclog_feed(void *cookie, char *data, int len);

DESCRIPTION
     These functions provide a way for application programs to extract events
     from an event stream generated by hwpmc(4).

     A new event log parser is allocated using pmclog_open().  Argument	fd may
     be	a file descriptor opened for reading if	the event stream is present in
     a file, or	the constant PMCLOG_FD_NONE for	an event stream	present	in
     memory.  This function returns a cookie that is passed into the other
     functions in this API set.

     Function pmclog_read() returns the	next available event in	the event
     stream associated with argument cookie.  Argument ev points to an event
     descriptor	that which will	contain	the result of a	successfully parsed
     event.

     An	event descriptor returned by pmclog_read() has the following struc-
     ture:

     struct pmclog_ev {
	    enum pmclog_state pl_state;	     /*	parser state after 'get_event()' */
	    off_t	      pl_offset;     /*	byte offset in stream */
	    size_t	      pl_count;	     /*	count of records so far	*/
	    struct timespec   pl_ts;	     /*	log entry timestamp */
	    enum pmclog_type  pl_type;	     /*	log entry kind */
	    union {			     /*	log entry data */
		     struct pmclog_ev_closelog	  pl_cl;
		     struct pmclog_ev_dropnotify  pl_d;
		     struct pmclog_ev_initialize  pl_i;
		     struct pmclog_ev_map_in	  pl_mi;
		     struct pmclog_ev_map_out	  pl_mo;
		     struct pmclog_ev_pcsample	  pl_s;
		     struct pmclog_ev_pmcallocate pl_a;
		     struct pmclog_ev_pmcattach	  pl_t;
		     struct pmclog_ev_pmcdetach	  pl_d;
		     struct pmclog_ev_proccsw	  pl_c;
		     struct pmclog_ev_procexec	  pl_x;
		     struct pmclog_ev_procexit	  pl_e;
		     struct pmclog_ev_procfork	  pl_f;
		     struct pmclog_ev_sysexit	  pl_e;
		     struct pmclog_ev_userdata	  pl_u;
	    } pl_u;
     };

     The current state of the parser is	recorded in pl_state.  This field can
     take on the following values:

     PMCLOG_EOF		  (For file based parsers only)	An end-of-file condi-
			  tion was encountered on the configured file descrip-
			  tor.

     PMCLOG_ERROR	  An error occurred during parsing.

     PMCLOG_OK		  A complete event record was read into	*ev.

     PMCLOG_REQUIRE_DATA  There	was insufficient data in the event stream to
			  assemble a complete event record.  For memory	based
			  parsers, more	data can be fed	to the parser using
			  function pmclog_feed().  For file based parsers,
			  function pmclog_read() may be	retried	when data is
			  available on the configured file descriptor.

     The rest of the event structure is	valid only if field pl_state contains
     PMCLOG_OK.	 Field pl_offset contains the offset of	the current record in
     the byte stream.  Field pl_count contains the serial number of this
     event.  Field pl_ts contains a timestamp with the system time when	the
     event occurred.  Field pl_type denotes the	kind of	the event returned in
     argument *ev and is one of	the following:

     PMCLOG_TYPE_CLOSELOG     A	marker indicating a successful close of	a log
			      file.  This record will be the last record of a
			      log file.

     PMCLOG_TYPE_DROPNOTIFY   A	marker indicating that hwpmc(4)	had to drop
			      data due to a resource constraint.

     PMCLOG_TYPE_INITIALIZE   An initialization	record.	 This is the first
			      record in	a log file.

     PMCLOG_TYPE_MAP_IN	      A	record describing the introduction of a	map-
			      ping to an executable object by a	kldload(2) or
			      mmap(2) system call.

     PMCLOG_TYPE_MAP_OUT      A	record describing the removal of a mapping to
			      an executable object by a	kldunload(2) or
			      munmap(2)	system call.

     PMCLOG_TYPE_PCSAMPLE     A	record containing an instruction pointer sam-
			      ple.

     PMCLOG_TYPE_PMCALLOCATE  A	record describing a PMC	allocation operation.

     PMCLOG_TYPE_PMCATTACH    A	record describing a PMC	attach operation.

     PMCLOG_TYPE_PMCDETACH    A	record describing a PMC	detach operation.

     PMCLOG_TYPE_PROCCSW      A	record describing a PMC	reading	at the time of
			      a	process	context	switch.

     PMCLOG_TYPE_PROCEXEC     A	record describing an execve(2) by a target
			      process.

     PMCLOG_TYPE_PROCEXIT     A	record describing the accumulated PMC reading
			      for a process at the time	of _exit(2).

     PMCLOG_TYPE_PROCFORK     A	record describing a fork(2) by a target
			      process.

     PMCLOG_TYPE_SYSEXIT      A	record describing a process exit, sent to pro-
			      cesses owning system-wide	sampling PMCs.

     PMCLOG_TYPE_USERDATA     A	record containing user data.

     Function pmclog_feed() is used with parsers configured to parse memory
     based event streams.  It is intended to be	called when function
     pmclog_read() indicates the need for more data by a returning
     PMCLOG_REQUIRE_DATA in field pl_state of its event	structure argument.
     Argument data points to the start of a memory buffer containing fresh
     event data.  Argument len indicates the number of data bytes available.
     The memory	range [data, data + len] must remain valid till	the next time
     pmclog_read() returns an error.  It is an error to	use pmclog_feed() on a
     parser configured to parse	file data.

     Function pmclog_close() releases the internal state allocated by a	prior
     call to pmclog_open().

RETURN VALUES
     Function pmclog_open() will return	a non-NULL value if successful or NULL
     otherwise.

     Function pmclog_read() will return	0 in case a complete event record was
     successfully read,	or will	return -1 and will set the pl_state field of
     the event record to the appropriate code in case of an error.

     Function pmclog_feed() will return	0 on success or	-1 in case of failure.

EXAMPLES
     A template	for using the log file parsing API is shown below in pseu-
     docode:

     void *parser;		     /*	cookie */
     struct pmclog_ev ev;	     /*	parsed event */
     int fd;			     /*	file descriptor	*/

     fd	= open(filename, O_RDONLY);  /*	open log file */
     parser = pmclog_open(fd);	     /*	initialize parser */
     if	(parser	== NULL)
	     --handle an out of	memory error--;

     /*	read and parse data */
     while (pmclog_read(parser,	&ev) ==	0) {
	     assert(ev.pl_state	== PMCLOG_OK);
	     /*	process	the event */
	     switch (ev.pl_type) {
	     case PMCLOG_TYPE_ALLOCATE:
		     --process a pmc allocation	record--
		     break;
	     case PMCLOG_TYPE_PROCCSW:
		     --process a thread	context	switch record--
		     break;
	     case PMCLOG_TYPE_PCSAMPLE:
		     --process a PC sample--
		     break;
	     --and so on--
	     }
     }

     /*	examine	parser state */
     switch (ev.pl_state) {
     case PMCLOG_EOF:
	     --normal termination--
	     break;
     case PMCLOG_ERROR:
	     --look at errno here--
	     break;
     case PMCLOG_REQUIRE_DATA:
	     --arrange for more	data to	be available for parsing--
	     break;
     default:
	     assert(0);
	     /*NOTREACHED*/
     }

     pmclog_close(parser);	     /*	cleanup	*/

ERRORS
     A call to pmclog_init_parser() may	fail with any of the errors returned
     by	malloc(3).

     A call to pmclog_read() for a file	based parser may fail with any of the
     errors returned by	read(2).

SEE ALSO
     read(2), malloc(3), pmc(3), hwpmc(4), pmcstat(8)

HISTORY
     The pmclog	API currently under development.  It first appeared in
     FreeBSD 6.0.

FreeBSD	10.1			March 26, 2006			  FreeBSD 10.1

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pmclog&sektion=3&manpath=FreeBSD+7.4-RELEASE>

home | help