Date: Sun, 25 Jan 2004 21:51:15 +0100 From: Poul-Henning Kamp <phk@phk.freebsd.dk> To: geom@freebsd.org Subject: manual page comments... Message-ID: <57579.1075063875@critter.freebsd.dk>
next in thread | raw e-mail | index | archive | help
I sat down with a printout of the manual pages and a pencil, here are my comments. Overall: great stuff, thanks a lot! I'd like to suggest that symmetric operations gets merged, for instance g_new_consumer() and g_destroy_consumer etc. We should probably also tie all these into a revised version of geom(4). About examples: I wonder if a geom_example page with a heavily commented "null" class might be a better idea than a lot of skeleton examples in the various pages. DECLARE_GEOM_CLASS Mention that it works both for compiled in and KLD'ed classes. Mention that on activation all preexisting providers are offered for tasting. We to document the member functions as well, and I wonder if they should be described on this page, on a "g_class" page or on one dedicated page for each. ->destroy_geom is also called at other times, in particular as a result of the user asking for it to happen. In the g_class initialization, please mention that people MUST use C99 initialization (like the example) so we can change the struct later on (this is important!). g_attach merge with g_detach page ? "From now on a geom ... of another class" is not really correct and rather unclear. Mention that access counts are necessary before actual I/O can happen. g_bio remove mention of bio_bcount, bio_resid, they are, and should not be used in GEOM. bio_driver[12] s/$/(ie: the provider)/ bio_caller[12] s/$/(ie: the consumer)/ bio_completed Number of bytes completed, but they may not be completed from the front of the request. bio_from, bio_to, bio_children, bio_inbed, bio_parent: mention that they are normally read-only for a class. example: Technically it could be done without a softc, and that might be worth a comment, but please keep the softc in the example since it shows how to derive it from the bio. /* * Could be: * g_io_request(cbp, LIST_FIRST(&bp->bio_to->geom->consumers)); */ g_io_requst(cbp, sc->ex_consumer); g_destroy_consumer: merge with g_new_consumer ? s/Typically t/T/ g_destroy_geom: merge with g_new_geomf ? g_destroy_provider merge with g_new_providerf ? s/A topology lock/The topology lock/ (May apply other files as well) g_error_provider maybe merge with g_new_providerf s/sectorsize, the function/sectorsize and other initialization, the function/ g_new_geomf We need to document the member functions, either here, in a "g_geom" page or one each their own pages. s/geom you need to/geom you must/ (twice) g_new_providerf s/an undefined situation/programmer error/ g_post_event merge with g_cancel_event ? needs better example. mention that events are good for avoiding running out of stack and for lock-barrier transitions. g_provider_by_name you must hold topology. The reason this is not enforced with KASSERT is the clone routine in geom_dev which cannot (this is a problem I need to fix). g_read_data, g_write_data merge s/more than or equal to 512/a multiple of the sectorsize for the provider/ g_waitfor_event /can not be called recusively/can not be called from an event/ (we should enforce this with KASSERT if we can) better example. g_wither_geom explain that this is an automatic "garbage collect" to avoid duplicated code in all classes. Mention that the softc should be disposed off and NULL'ed before calling this functions. Mention that withering a geom is not enough to ensure you can unload a class. -- 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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?57579.1075063875>