NetBSD Problem Report #44759

From riz@netbsd-i386.localdomain  Tue Mar 22 23:21:36 2011
Return-Path: <riz@netbsd-i386.localdomain>
Received: from mail.netbsd.org (mail.netbsd.org [204.152.190.11])
	by www.NetBSD.org (Postfix) with ESMTP id 5402A63B9B8
	for <gnats-bugs@gnats.NetBSD.org>; Tue, 22 Mar 2011 23:21:36 +0000 (UTC)
Message-Id: <20110322220455.5DA8FE015F@netbsd-i386.localdomain>
Date: Tue, 22 Mar 2011 15:04:55 -0700 (PDT)
From: riz@NetBSD.org
Reply-To: riz@NetBSD.org
To: gnats-bugs@gnats.NetBSD.org
Subject: many CFATTACH_DECL* macros, little documentation
X-Send-Pr-Version: 3.95

>Number:         44759
>Category:       kern
>Synopsis:       CFATTACH_DECL* macros should be better documented
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Mar 22 23:25:01 +0000 2011
>Originator:     riz@NetBSD.org
>Release:        NetBSD 5.99.48
>Organization:

>Environment:


System: NetBSD netbsd-i386 5.99.48 NetBSD 5.99.48 (TUTORIAL) #1: Tue Mar 22 11:56:44 PDT 2011 riz@netbsd-i386:/usr/src/sys/arch/i386/compile/TUTORIAL i386
Architecture: i386
Machine: i386
>Description:
	I'm currently working with the kernel development tutorials,
trying to update them where appropriate for NetBSD (while also using them
to polish my skills).  I wanted to add (for example) the ability to detach
to the pseudo-device tutorial, and it seems like I need to add a CFATTACH_DECL()
(which I gleaned by looking at other pseudo-device code).  However, I could
not find any documentation to help me decide _which_ of the variants
to use.  In device.h, I see:

CFATTACH_DECL
CFATTACH_DECL_NEW
CFATTACH_DECL2_NEW
CFATTACH_DECL3_NEW.

After looking around (apropos was no help), I found some documentation of
CFATTACH_DECL in driver(9), but no mention of alternatives.

>How-To-Repeat:

>Fix:
	I humbly suggest:

	- xref CFATTACH_DECL to driver(9) somehow, so it's findable from
	apropos.

	- add some discussion of the variants, either to driver(9) or
	comments in driver. I don't have any suggested wording, because
	I'm still pretty fuzzy on the concept myself.

>Unformatted:

Home	PR Database Search