linux-kernel - Re: kgdb: core

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-Id: <20080422181942.80f96975.randy.dunlap@oracle.com>
Date:	Tue, 22 Apr 2008 18:19:42 -0700
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	Jason Wessel <jason.wessel@...driver.com>
Cc:	Randy Dunlap <RANDY.DUNLAP@...cle.com>,
	Andrew Morton <akpm@...ux-foundation.org>, mingo@...e.hu,
	linux-kernel@...r.kernel.org
Subject: Re: kgdb: core

On Tue, 22 Apr 2008 16:19:55 -0500 Jason Wessel wrote:

> Randy Dunlap wrote:
> > --- Original Message --- (akpm wrote:)
> >>> On Tue, 22 Apr 2008 08:25:19 -0700 Randy Dunlap
> <randy.dunlap@...cle.com> wrote:
> >>>
> >>> kernel-doc output doesn't depend on build $ARCH.
> >> Ah, interesting.  I made an ass of u and me.
> >>
> >> In that case documentng them in x86 .c and leaving all other definitions
> >> and declarations uncommented sounds the way to go?  
> >
> > Yes, that would be fine and traditional (historical).
> >
> > ~Randy
> >
> 
> So is the summary here that we cannot just document the actual
> interface API in the incude/linux/kgdb.h?

The summary is that we prefer for kernel-doc to be placed at (function
etc.) definition/implementation sites, not at declaration sites.
However, I'm sure that there are exceptions to this.

> The problem I had here was pretty simple in that not all of the
> functions in the API are used by all the archs.  It seemed pretty
> reasonable at the time to just document everything in the .h file
> because it was more for the folks who wanted to add kgdb support to an
> arch and of little to no use to end users of kgdb.

I see.  That could pose a problem.

And there is not any one $arch that does use the complete API?
If so, all of the kernel-doc could be in that $arch.

> The mainline only has a small chunk of the docs right now because not
> all of kgdb is merged.  I was just hoping it was real easy to generate
> some reasonable looking docs.  The docs for all the kgdb code that
> exists (in mainline and not in mainline) can be viewed here as an
> example.
> 
> http://kernel.org/pub/linux/kernel/people/jwessel/kgdb/

If it poses an extreme hardship on you to conform to the
norms/expectations, so be it.  It won't kill anything AFAIK.
(i.e., I won't object.)

---
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/