From owner-freebsd-doc@FreeBSD.ORG Sat Oct 4 03:00:31 2003 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 0061B16A4BF for ; Sat, 4 Oct 2003 03:00:31 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 47AD743FF7 for ; Sat, 4 Oct 2003 03:00:29 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.9/8.12.9) with ESMTP id h94A0TFY028310 for ; Sat, 4 Oct 2003 03:00:29 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.9/8.12.9/Submit) id h94A0Tlb028309; Sat, 4 Oct 2003 03:00:29 -0700 (PDT) (envelope-from gnats) Resent-Date: Sat, 4 Oct 2003 03:00:29 -0700 (PDT) Resent-Message-Id: <200310041000.h94A0Tlb028309@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Dan Strick Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 8DAA816A4B3 for ; Sat, 4 Oct 2003 02:53:36 -0700 (PDT) Received: from smtp.covadmail.net (mx05.covadmail.net [63.65.120.65]) by mx1.FreeBSD.org (Postfix) with SMTP id E409643FE1 for ; Sat, 4 Oct 2003 02:53:34 -0700 (PDT) (envelope-from strick@covad.net) Received: (covad.net 23980 invoked from network); 4 Oct 2003 09:53:29 -0000 Received: from unknown (HELO ice.nodomain) (68.164.194.240) by sun-qmail13 with SMTP; 4 Oct 2003 09:53:29 -0000 Received: from ice.nodomain (localhost [127.0.0.1]) by ice.nodomain (8.12.8p1/8.12.8) with ESMTP id h949rWNo000720 for ; Sat, 4 Oct 2003 02:53:32 -0700 (PDT) (envelope-from dan@ice.nodomain) Received: (from dan@localhost) by ice.nodomain (8.12.8p1/8.12.8/Submit) id h949rWDm000719; Sat, 4 Oct 2003 02:53:32 -0700 (PDT) Message-Id: <200310040953.h949rWDm000719@ice.nodomain> Date: Sat, 4 Oct 2003 02:53:32 -0700 (PDT) From: Dan Strick To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Subject: docs/57568: errors in FreeBSD Architecture Handbook X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list Reply-To: Dan Strick List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 04 Oct 2003 10:00:31 -0000 >Number: 57568 >Category: docs >Synopsis: errors in FreeBSD Architecture Handbook >Confidential: no >Severity: serious >Priority: medium >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sat Oct 04 03:00:28 PDT 2003 >Closed-Date: >Last-Modified: >Originator: Dan Strick >Release: FreeBSD 4.8-RELEASE i386 >Organization: >Environment: System: FreeBSD ice 4.8-RELEASE FreeBSD 4.8-RELEASE #0: Sun Apr 6 21:47:39 PDT 2003 root@ice:/usr/src/sys/compile/ICE i386 >Description: This is not a report of a bug in a FreeBSD release but a report of errors in http://www.freebsd.org/doc/en_US.ISO8859-1/books/arch-handbook/index.html. All of the examples given in sections 5.3.2 and 5.3.3 on the "Using Sysinit" page are wrong. All of the usages of the SYSINIT macro are missing the "uniquifier" argument and have the "func" argument in its place and the "ident" argument is supposed to be a pointer to something (or NULL). Perhaps the examples are actually for the previous implementation of the Sysinit facility and were not changed after it was last reimplemented. (wild guess) Suggestion (not related to the bug described above): since linker sets are used for things besides the SYSINIT macro, perhaps most of the information in the first paragraph of section 5.2 (Sysinit Operation) should be moved to the explanation of Linker Set in section 5.1 (Terminology) and be made more explicit. It might be nice to explain to the reader that the facility depends on the Gnu C __asm__ feature, the Gnu Assembler .section/.previous directives, the Gnu linker support for those features and on the gensetdefs(8) program. The linker set facility is *very* hard to understand unless you are familiar with all those features and examine a kernel Makefile and the kernel.h/linker_set.h files in the system sources to discover the glue that binds those features together. >How-To-Repeat: >Fix: >Release-Note: >Audit-Trail: >Unformatted: