NetBSD Problem Report #32430
From imago@13thmonkey.org Sun Jan 1 23:43:53 2006
Return-Path: <imago@13thmonkey.org>
Received: from rangerover.13thmonkey.org (internetplanet.demon.nl [82.161.161.224])
by narn.netbsd.org (Postfix) with ESMTP id 01C2D63B942
for <gnats-bugs@gnats.NetBSD.org>; Sun, 1 Jan 2006 23:43:52 +0000 (UTC)
Message-Id: <20060101234348.995E755F0@rangerover.13thmonkey.org>
Date: Mon, 2 Jan 2006 00:43:48 +0100 (CET)
From: reinoud@NetBSD.org
Reply-To: reinoud@NetBSD.org
To: gnats-bugs@netbsd.org
Subject: genfs lacking documentation
X-Send-Pr-Version: 3.95
>Number: 32430
>Category: kern
>Synopsis: There is no documentation on genfs nor its gop's
>Confidential: no
>Severity: serious
>Priority: medium
>Responsible: kern-bug-people
>State: open
>Class: doc-bug
>Submitter-Id: net
>Arrival-Date: Mon Jan 02 07:16:02 +0000 2006
>Last-Modified: Sat Jun 11 11:40:02 +0000 2011
>Originator: Reinoud Zandijk
>Release: NetBSD 2.99.16
>Organization:
NetBSD
>Environment:
System: NetBSD rangerover 2.99.16 NetBSD 2.99.16 (GENERIC) #1: Tue Feb 22 20:57:13 CET 2005 imago@heethoofdje.kasbah:/usr/sources/cvs.netbsd.org/src/sys/arch/sparc/compile/obj/GENERIC sparc
Architecture: sparc
Machine: sparc
>Description:
There is no documentation on src/sys/miscfs/genfs. There is no description
of how to interact with it nor what the gop calls do.
>How-To-Repeat:
-
>Fix:
Write manpage.
>Audit-Trail:
From: Julian Fagir <gnrp@komkon2.de>
To: gnats-bugs@netbsd.org
Cc:
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 11:12:45 +0200
Hi,
recently we had a discussion in the IRCNet #netbsd about that topic.
After having a short look, we created a stub for genfs, layerfs, fifofs and
specfs by copying their description from the NetBSD internals guide and
adding some references.
It is intended to be used as genfs(9), and also linked to layerfs(9),
fifofs(9), specfs(9).
I uploaded it to http://komkon2.de/genfs.9
Regards, Julian
From: Reinoud Zandijk <reinoud@NetBSD.org>
To: gnats-bugs@NetBSD.org
Cc: kern-bug-people@netbsd.org, gnats-admin@netbsd.org,
netbsd-bugs@netbsd.org
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 12:27:33 +0200
On Sat, Jun 11, 2011 at 09:15:06AM +0000, Julian Fagir wrote:
> recently we had a discussion in the IRCNet #netbsd about that topic.
> After having a short look, we created a stub for genfs, layerfs, fifofs and
> specfs by copying their description from the NetBSD internals guide and
> adding some references.
>
> It is intended to be used as genfs(9), and also linked to layerfs(9),
> fifofs(9), specfs(9).
Thanks for the start. What i was targeting in the PR however was a description
of the various generic FS functions genfs provides and more important its
callbacks.
I think the stub should be more seen as a genfs(0), layerfs(0), specfs(0),
fifofs(0). Still a nice thing to add :) Even if its just marked as a stub.
People seeing references to them at least have a way of knowing what it is all
about.
The genfs(9) could then deal with the semantics of the genfs and its callbacks
and their semantics i.e. when are they called and why. The specfs(9) could
then deal with the special issues around special files etc.
With regards,
Reinoud
From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc: reinoud@NetBSD.org
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 13:48:36 +0300
On Sat, Jun 11, 2011 at 10:30:07AM +0000, Reinoud Zandijk wrote:
> I think the stub should be more seen as a genfs(0), layerfs(0), specfs(0),
> fifofs(0). Still a nice thing to add :) Even if its just marked as a stub.
> People seeing references to them at least have a way of knowing what it is all
> about.
There is no "section zero". Since the page contains the CODE REFERENCES
section, and references to various section 9 pages, section 9 seems right.
Otherwise, section 7 could be appropriate.
But.
Clearly this is unfinished. I don't see much value with stubs like this.
"The genfs subsystem implements generic filesystem operations to be
shared across different filesystems".
This comes close to "null-documentation". Note that the issue has been
discussed previously [1].
- Jukka.
[1] http://mail-index.netbsd.org/current-users/2010/05/13/msg013353.html
From: Julian Fagir <gnrp@komkon2.de>
To: gnats-bugs@NetBSD.org
Cc:
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 13:21:57 +0200
Hi,
> Clearly this is unfinished. I don't see much value with stubs like this.
>
> "The genfs subsystem implements generic filesystem operations to be
> shared across different filesystems".
>
> This comes close to "null-documentation". Note that the issue has been
> discussed previously [1].
Ah, I didn't know that, ok.
Yes, it is unfinished. The thought about making a stub came up when I wanted
to know what genfs is for, but found nothing in the online documentation.
Only analysing the code a bit and eventually having it seen in the NetBSD
Internals Guide turned out what it really is. Having a manpage for faster
lookup would be nice.
There is actually no more documentation about these issues anywhere than
this manpage/in the NetBSD Internals.
I agree this does not have a great value, but at least you find documentation
somewhere in the online documentation of what it is about.
The question seems to be rather if you want only good documentation or at
least whole, but incomplete documentation.
The ticket should remain open, no matter if this stub is commited or not.
Regards, Julian
From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc: reinoud@NetBSD.org, Julian Fagir <gnrp@komkon2.de>
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 14:37:00 +0300
On Sat, Jun 11, 2011 at 11:25:03AM +0000, Julian Fagir wrote:
> The ticket should remain open, no matter if this stub is commited or not.
Sure. The conclusion from the previous discussion round was:
1. Write section 4 pages for each file system (or fs component);
i.e. e.g. tmpfs(4), mfs(4), genfs(4), and so on.
2. When appropriate, append the section 4 pages with the layout and
used structures; i.e. e.g. tmpfs(5), mfs(5), ffs(5), and so on.
3. Write section 9 pages for the actual KPI.
4. Once the above are done, consider a summary page.
The case (1) is doable without too dense file system hacking background, and
I happy to commit each well-written page. This can include, for instance,
general description and notes, pros & cons, history, authors, pointers to
further documentation, and so on. The case (3) obviously requires some
background in actual file system programming.
- Jukka.
>Unformatted:
(Contact us)
$NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2007
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.