From owner-svn-src-projects@FreeBSD.ORG Thu Jan 10 18:04:43 2013 Return-Path: Delivered-To: svn-src-projects@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 107B520E; Thu, 10 Jan 2013 18:04:43 +0000 (UTC) (envelope-from alfred@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id E8DA1D97; Thu, 10 Jan 2013 18:04:42 +0000 (UTC) Received: from svn.freebsd.org (svn.FreeBSD.org [8.8.178.70]) by svn.freebsd.org (8.14.5/8.14.5) with ESMTP id r0AI4gBj081711; Thu, 10 Jan 2013 18:04:42 GMT (envelope-from alfred@svn.freebsd.org) Received: (from alfred@localhost) by svn.freebsd.org (8.14.5/8.14.5/Submit) id r0AI4gvf081710; Thu, 10 Jan 2013 18:04:42 GMT (envelope-from alfred@svn.freebsd.org) Message-Id: <201301101804.r0AI4gvf081710@svn.freebsd.org> From: Alfred Perlstein Date: Thu, 10 Jan 2013 18:04:42 +0000 (UTC) To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r245261 - projects/utrace2/lib/libc/sys X-SVN-Group: projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-projects@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the src " projects" tree" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 10 Jan 2013 18:04:43 -0000 Author: alfred Date: Thu Jan 10 18:04:42 2013 New Revision: 245261 URL: http://svnweb.freebsd.org/changeset/base/245261 Log: Document the new syscall and conventions used. Modified: projects/utrace2/lib/libc/sys/utrace.2 Modified: projects/utrace2/lib/libc/sys/utrace.2 ============================================================================== --- projects/utrace2/lib/libc/sys/utrace.2 Thu Jan 10 18:01:46 2013 (r245260) +++ projects/utrace2/lib/libc/sys/utrace.2 Thu Jan 10 18:04:42 2013 (r245261) @@ -44,6 +44,16 @@ .In sys/ktrace.h .Ft int .Fn utrace "const void *addr" "size_t len" +.Bd -literal +struct utrace2_data { + int ud_type; /* type of utrace record, + must be >= UTRACE_APPLICATIONMIN */ + int ud_version; /* version of 'type' */ + char application_data[SIZE]; /* your data */ +}; +.Ed +.Ft int +.Fn utrace2 "const void *addr" "size_t len" .Sh DESCRIPTION Adds a record to the process trace with information supplied by user. The record contains @@ -51,6 +61,81 @@ The record contains bytes from memory pointed to by .Fa addr . This call only has an effect if the calling process is being traced. +.Pp +The old +.Fn utrace +system call uses unstructured data and should be avoided. +.Pp +The new +.Fn utrace2 +function is for structured data and should be used with an overlay structure +that matches the +.Vt struct utrace2_data +above. +.Pp The format of the overlay must begin with two integer (int) fields. +The first is the utrace record type, for applications it must be +greater than or equal to UTRACE_APPLICATIONMIN (defined in +.In sys/ktrace.h ) +The second should be the version of the record. +.Pp +.Sh EXAMPLES FOR USER CODE +An example for +.Em non-system +code: +.Bd -literal + #define MY_UTRACE (UTRACE_APPLICATIONMIN + 1) + #define D_SIZE 20 + struct my_utrace2_data { + int ud_type; /* type of utrace record, + must be >= UTRACE_APPLICATIONMIN */ + int ud_version; /* version of 'type' */ + char hello[D_SIZE]; /* your data */ + } ud; + + ud.ud_type = MY_UTRACE; + ud.ud_version = 1; + strcpy(ud.hello, "world"); + utrace2(&ud, sizeof(ud)); + +.Ed +.Sh EXAMPLES FOR FREEBSD SYSTEM CODE +An example for a +.Em system library +(ONLY FOR BASE FREEBSD): +.Pp +First add an entry to +.In sys/ktrace.h +near +.Dv UTRACE_MALLOC . +Then start writing records using code like this: +.Bd -literal + #define UTRACE_THREAD_NEW 1 + #define UTRACE_THREAD_DEL 2 + struct utrace2_thread_data { + int ud_type; /* type of utrace record, + must be >= UTRACE_APPLICATIONMIN */ + int ud_version; /* version of 'type' */ + int ud_thread_op; /* UTRACE_THREAD_NEW/UTRACE_THREAD_DEL */ + int ud_thread_id; /* id of thread */ + }; + + int + thread_create(void) + { + int tid; + struct utrace2_thread_data ud; + + tid = get_new_tid(); + ud.ud_type = UTRACE_THREAD; + ud.ud_version = 1; + ud.ud_thread_op = UTRACE_THREAD_NEW; + ud.ud_thread_id = tid; + return tid; + } +.Ed +.Pp +Then you should add your new data type to +.Xr kdump 1 . .Sh RETURN VALUES .Rv -std .Sh ERRORS