From owner-freebsd-geom@FreeBSD.ORG Sun Mar 7 07:43:57 2004 Return-Path: Delivered-To: freebsd-geom@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 825DB16A4CE for ; Sun, 7 Mar 2004 07:43:57 -0800 (PST) Received: from mailbox.univie.ac.at (mail.univie.ac.at [131.130.1.27]) by mx1.FreeBSD.org (Postfix) with ESMTP id C7CAC43D2D for ; Sun, 7 Mar 2004 07:43:56 -0800 (PST) (envelope-from le@FreeBSD.org) Received: from wireless (adslle.cc.univie.ac.at [131.130.102.11]) i27FhoUJ1100610 for ; Sun, 7 Mar 2004 16:43:51 +0100 Date: Sun, 7 Mar 2004 16:43:50 +0100 (CET) From: Lukas Ertl To: geom@FreeBSD.org Message-ID: <20040307164215.H624@korben.in.tern> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-DCC-ZID-Univie-Metrics: imap 4243; Body=0 Fuz1=0 Fuz2=0 Subject: gctl_* API (libgeom) X-BeenThere: freebsd-geom@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: GEOM-specific discussions and implementations List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 07 Mar 2004 15:43:57 -0000 Hi, I've put together some docs for the gctl_* API in libgeom that I'd like to commit anytime soon. Please review it. ---8<--- Index: lib/libgeom/Makefile =================================================================== RCS file: /home/ncvs/src/lib/libgeom/Makefile,v retrieving revision 1.9 diff -u -r1.9 Makefile --- lib/libgeom/Makefile 18 Aug 2003 15:25:38 -0000 1.9 +++ lib/libgeom/Makefile 7 Mar 2004 15:41:18 -0000 @@ -25,6 +25,12 @@ libgeom.3 geom_stats_snapshot_free.3 \ libgeom.3 geom_stats_snapshot_timestamp.3 \ libgeom.3 geom_stats_snapshot_reset.3 \ - libgeom.3 geom_stats_snapshot_next.3 + libgeom.3 geom_stats_snapshot_next.3 \ + libgeom.3 gctl_get_handle.3 \ + libgeom.3 gctl_ro_param.3 \ + libgeom.3 gctl_rw_param.3 \ + libgeom.3 gctl_issue.3 \ + libgeom.3 gctl_free.3 \ + libgeom.3 gctl_dump.3 .include Index: lib/libgeom/libgeom.3 =================================================================== RCS file: /home/ncvs/src/lib/libgeom/libgeom.3,v retrieving revision 1.4 diff -u -r1.4 libgeom.3 --- lib/libgeom/libgeom.3 18 Jun 2003 19:43:17 -0000 1.4 +++ lib/libgeom/libgeom.3 7 Mar 2004 15:41:18 -0000 @@ -38,7 +38,13 @@ .Nm geom_stats_snapshot_free , .Nm geom_stats_snapshot_timestamp , .Nm geom_stats_snapshot_reset , -.Nm geom_stats_snapshot_next +.Nm geom_stats_snapshot_next , +.Nm gctl_get_handle , +.Nm gctl_ro_param , +.Nm gctl_rw_param , +.Nm gctl_issue , +.Nm gctl_free , +.Nm gctl_dump .Nd userland API library for kernel GEOM subsystem .Sh LIBRARY .Lb libgeom @@ -61,6 +67,19 @@ .Fn geom_stats_snapshot_reset "void *arg" .Ft "struct g_stat *" .Fn geom_stats_snapshot_next "void *arg" +.Ss "Control Functions" +.Ft "struct gctl_req *" +.Fn gctl_get_handle "void" +.Ft void +.Fn gctl_ro_param "struct gctl_req *req" "const char *name" "int len" "const void *value" +.Ft void +.Fn gctl_rw_param "struct gctl_req *req" "const char *name" "int len" "void *value" +.Ft "const char *" +.Fn gctl_issue "struct gctl_req *req" +.Ft void +.Fn gctl_free "struct gctl_req *req" +.Ft void +.Fn gctl_dump "struct gctl_req *req" "FILE *f" .Sh DESCRIPTION The .Nm geom @@ -129,8 +148,86 @@ returns the next item, and .Dv NULL if there are no more items in the snapshot. +.Ss "Control Functions" +The +.Fn gctl_* +functions are used to send requests to GEOM classes. In order for a GEOM +class to actually be able to receive these requests, it must have defined a +"ctlreq" function. +.Pp +A +.Ar struct gctl_req * , +obtained with +.Fn gctl_get_handle , +can hold any number of parameters, which must be set with +.Fn gctl_ro_param +(for read-only parameters) or +.Fn gctl_rw_param +(for read/write parameters). +.Pp +Both +.Fn gctl_ro_param +and +.Fn gctl_rw_param +take a string +.Ar name , +which is used to identify the parameter, and a +.Ar value , +which contains - in the read-only case - the data to be passed to the +GEOM class, or - in the read/write case - a pointer to preallocated memory +that the GEOM class should fill with the desired data. If +.Ar len +is negative, it is assumed that +.Ar value +is an ASCII string and the actual length is taken from the string length of +.Ar value ; +otherwise it must hold the size of +.Ar value . +.Pp +A parameter with a +.Ar name +containing the string "class" is mandatory for each request, and the +corresponding +.Ar value +must hold the name of the GEOM class where the request should be sent to. +.Pp +Also mandatory for each request is a parameter with a +.Ar name +called "verb", and the corresponding +.Ar value +needs to hold the command string that the GEOM class should react upon. +.Pp +Once all desired parameters are filled in, the request must be sent to +the GEOM subsystem with +.Fn gctl_issue , +which returns NULL on success, or a string containing the error message +on failure. +.Pp +After the request is finished, the allocated memory should be released with +.Fn gctl_free . +.Pp +.Fn gctl_dump +can be used to write the contents of +.Ar req +to the open file handle pointed to by +.Ar f . +.Sh EXAMPLES +Create a request that is to be sent to the CCD class and tell +it to destroy a specific geom: +.Bd -literal -offset indent +H = gctl_get_handle(); +gctl_ro_param(H, "verb", -1, "destroy geom"); +gctl_ro_param(H, "class", -1, "CCD"); +sprintf(buf, "ccd%d", ccd); +gctl_ro_param(H, "geom", -1, buf); +errstr = gctl_issue(H); +if (errstr != NULL) + err(1, "Could not destroy ccd: %s", errstr); +gctl_free(H); +.Ed .Sh AUTHORS .An Poul-Henning Kamp Aq phk@FreeBSD.org +.An Lukas Ertl Aq le@FreeBSD.org .Sh HISTORY The .Nm geom ---8<--- regards, le -- Lukas Ertl http://mailbox.univie.ac.at/~le/ le@FreeBSD.org http://people.freebsd.org/~le/ From owner-freebsd-geom@FreeBSD.ORG Sun Mar 7 08:08:43 2004 Return-Path: Delivered-To: freebsd-geom@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id AB70616A4CE; Sun, 7 Mar 2004 08:08:43 -0800 (PST) Received: from critter.freebsd.dk (critter.freebsd.dk [212.242.86.163]) by mx1.FreeBSD.org (Postfix) with ESMTP id D197943D1F; Sun, 7 Mar 2004 08:08:42 -0800 (PST) (envelope-from phk@phk.freebsd.dk) Received: from critter.freebsd.dk (localhost [127.0.0.1]) by critter.freebsd.dk (8.12.11/8.12.11) with ESMTP id i27G8e7D003935; Sun, 7 Mar 2004 17:08:41 +0100 (CET) (envelope-from phk@phk.freebsd.dk) To: Lukas Ertl From: "Poul-Henning Kamp" In-Reply-To: Your message of "Sun, 07 Mar 2004 16:43:50 +0100." <20040307164215.H624@korben.in.tern> Date: Sun, 07 Mar 2004 17:08:40 +0100 Message-ID: <3934.1078675720@critter.freebsd.dk> cc: geom@freebsd.org Subject: Re: gctl_* API (libgeom) X-BeenThere: freebsd-geom@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: GEOM-specific discussions and implementations List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 07 Mar 2004 16:08:43 -0000 In message <20040307164215.H624@korben.in.tern>, Lukas Ertl writes: >Hi, > >I've put together some docs for the gctl_* API in libgeom that I'd like to >commit anytime soon. Please review it. I tweaked a few details, added a paragraph about the error handling and commmitted it. Thanks a BUNDLE! -- Poul-Henning Kamp | UNIX since Zilog Zeus 3.20 phk@FreeBSD.ORG | TCP/IP since RFC 956 FreeBSD committer | BSD since 4.3-tahoe Never attribute to malice what can adequately be explained by incompetence. From owner-freebsd-geom@FreeBSD.ORG Mon Mar 8 04:36:37 2004 Return-Path: Delivered-To: freebsd-geom@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id F0EA016A4CE for ; Mon, 8 Mar 2004 04:36:37 -0800 (PST) Received: from pasmtp.tele.dk (pasmtp.tele.dk [193.162.159.95]) by mx1.FreeBSD.org (Postfix) with ESMTP id 5B8C743D1D for ; Mon, 8 Mar 2004 04:36:37 -0800 (PST) (envelope-from xride@x12.dk) Received: from x12.dk (xforce.dk [80.164.11.218]) by pasmtp.tele.dk (Postfix) with ESMTP id 1747B1EC361 for ; Mon, 8 Mar 2004 13:36:35 +0100 (CET) Received: by x12.dk (Postfix, from userid 666) id 4D3244D; Mon, 8 Mar 2004 13:36:35 +0100 (CET) Received: from localhost (localhost [127.0.0.1]) by x12.dk (Postfix) with ESMTP id 38CC626 for ; Mon, 8 Mar 2004 13:36:35 +0100 (CET) Date: Mon, 8 Mar 2004 13:36:35 +0100 (CET) From: Soeren Straarup To: geom@FreeBSD.org Message-ID: <20040308131859.O36699-100000@x12.dk> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Subject: Are there a new snapshot of geom_vinum? X-BeenThere: freebsd-geom@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: GEOM-specific discussions and implementations List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 08 Mar 2004 12:36:38 -0000 has the url that was mailled to list been updated lately? When will it appear in the current tree? cause i've patched my current with it about a week ago, it crashed my test box, but it is headless without a console cable, so debug info will come at a later point. best regards Soeren Soeren Straarup | aka OZ2DAK aka Xride FreeBSD wannabe | FreeBSD since 2.2.6-R If you see the light at the end of the tunnel, then make sure it is not a train.. From owner-freebsd-geom@FreeBSD.ORG Mon Mar 8 05:00:57 2004 Return-Path: Delivered-To: freebsd-geom@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id DC69E16A4CE for ; Mon, 8 Mar 2004 05:00:57 -0800 (PST) Received: from mailbox.univie.ac.at (mailbox.univie.ac.at [131.130.1.27]) by mx1.FreeBSD.org (Postfix) with ESMTP id 56FE543D2F for ; Mon, 8 Mar 2004 05:00:57 -0800 (PST) (envelope-from le@FreeBSD.org) Received: from pcle2.cc.univie.ac.at (pcle2.cc.univie.ac.at [131.130.2.177]) i28D0p1p1173518; Mon, 8 Mar 2004 14:00:53 +0100 Date: Mon, 8 Mar 2004 14:00:51 +0100 (CET) From: Lukas Ertl To: Soeren Straarup In-Reply-To: <20040308131859.O36699-100000@x12.dk> Message-ID: <20040308135944.M51503@pcle2.cc.univie.ac.at> References: <20040308131859.O36699-100000@x12.dk> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-DCC-ZID-Univie-Metrics: imap 4243; Body=0 Fuz1=0 Fuz2=0 cc: geom@FreeBSD.org Subject: Re: Are there a new snapshot of geom_vinum? X-BeenThere: freebsd-geom@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: GEOM-specific discussions and implementations List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 08 Mar 2004 13:00:58 -0000 On Mon, 8 Mar 2004, Soeren Straarup wrote: > has the url that was mailled to list been updated lately? I've uploaded a new tarball about ten days ago, please see . > When will it appear in the current tree? I don't know yet when I'll commit it, it's not finished yet. regards, le -- Lukas Ertl http://mailbox.univie.ac.at/~le/ le@FreeBSD.org http://people.freebsd.org/~le/