docs/57568: errors in FreeBSD Architecture Handbook

[Dan Strick]

>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 at 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: