From owner-svn-src-head@freebsd.org Sun Oct 8 17:56:44 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 9D587E3BDD2 for ; Sun, 8 Oct 2017 17:56:44 +0000 (UTC) (envelope-from ian@freebsd.org) Received: from outbound1a.eu.mailhop.org (outbound1a.eu.mailhop.org [52.58.109.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id E45A52DA6 for ; Sun, 8 Oct 2017 17:56:43 +0000 (UTC) (envelope-from ian@freebsd.org) X-MHO-User: 0518bb5d-ac52-11e7-a893-25625093991c X-Report-Abuse-To: https://support.duocircle.com/support/solutions/articles/5000540958-duocircle-standard-smtp-abuse-information X-Originating-IP: 73.78.92.27 X-Mail-Handler: DuoCircle Outbound SMTP Received: from ilsoft.org (unknown [73.78.92.27]) by outbound1.eu.mailhop.org (Halon) with ESMTPSA id 0518bb5d-ac52-11e7-a893-25625093991c; Sun, 08 Oct 2017 17:56:34 +0000 (UTC) Received: from rev (rev [172.22.42.240]) by ilsoft.org (8.15.2/8.15.2) with ESMTP id v98HuUXN001560; Sun, 8 Oct 2017 11:56:30 -0600 (MDT) (envelope-from ian@freebsd.org) Message-ID: <1507485390.86205.323.camel@freebsd.org> Subject: Re: svn commit: r324415 - in head/sys: kern sys From: Ian Lepore To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Date: Sun, 08 Oct 2017 11:56:30 -0600 In-Reply-To: <201710081733.v98HXnu1094645@repo.freebsd.org> References: <201710081733.v98HXnu1094645@repo.freebsd.org> Content-Type: text/plain; charset="ISO-8859-1" X-Mailer: Evolution 3.18.5.1 FreeBSD GNOME Team Port Mime-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 08 Oct 2017 17:56:44 -0000 On Sun, 2017-10-08 at 17:33 +0000, Ian Lepore wrote: > Author: ian > Date: Sun Oct  8 17:33:49 2017 > New Revision: 324415 > URL: https://svnweb.freebsd.org/changeset/base/324415 > > Log: >   Add eventhandler notifications for newbus device attach/detach. >    > [...] >    >   A couple salient comments from the review, they amount to some helpful >   documentation about these events, but there's currently no good place for >   such documentation... About this last point... sys/eventhandler.h is now an ever-growing list of EVENTHANDLER_DECLARE() statements for events that are unrelated to each other.  I think we are at the point where it's no longer a few well-known "standard system event queues", it's turning into a mess. My first thought was to add these to bus.h because they're bus events.  But you have to include eventhandler.h to use EVENTHANDLER_DECLARE, and I didn't want to pull it (and its dependencies) into bus.h. Now I'm thinking maybe we need a handful of separate header files, like bus_events.h, proc_events.h, thread_events.h, etc.  Maybe we could have a kern_events.h as a catch-all for a few misc ones like low-memory, root-mounted, etc.  Having a few subsystem-focused header files would provide a good place to put some comment blocks describing quirks and other nice-to-know information about using/handling the events. Or we could go with full-on manpages for describing each event, or each group of related events.  In that case we'd need some sort of naming convention that makes it easy to find the page for the events you care about.  My gut tells me comment blocks at the point of the DECLARE statements are more likely to get written than manpages. Thoughts? -- Ian