Fix sentence structure to follow a better logic (zero is disable and
one is enable).
Correct return values in myopen() and myclose() in Example code.

Bug: docs/79318
Thanks to: Derek Tattersall
MFC after: 7 days
Start to address the race issue between restoring a file's contents
and restoring the metadata.  In particular, the metadata-restore
functions now all accept a file descriptor and a pathname.  If the
file descriptor is set and the platform supports the appropriate
syscall, restore the metadata through the file descriptor.  Otherwise,
restore it through the pathname.  This is complicated by varying
syscall support (FreeBSD has an fchmod(2) but no fchflags(2), for
example) and because non-file entries don't have an fd to use in
restoring attributes (for example, mknod(2) doesn't return a file
handle).

MFC after: 14 days
For sparc64 conditionalize the compilation of the gfb_cursor() variant
which doesn't assume a hardware cursor on __sparc64__ rather than on
DEV_CREATOR. If we want to include more than one framebuffer driver in
e.g. the GENERIC kernel all drivers have to work the same way. Now that
DEV_CREATOR is no longer used remove it from options.sparc64.
- Make sure that the OFW address properties that are going to be decode
  consist of the expected number of address and size cells (we can't use
  dynamic arrays here because at the point in the boot process when this
  code is used malloc() doesn't work, yet). This fixes a Fast Data Access
  MMU Miss when uart(4) (erroneously) calls OF_decode_addr() to decode
  the address of PS/2 keyboards. PS/2 keyboards use a different and also
  undocumented scheme at the first parent node than mapping at 'ranges'
  properties. It's however not worth implementing that other scheme and
  actually also fits atkbdc(4) better to just start at the first parent
  node of PS/2 keyboards which is the 8042 controller (I have atkbdc(4)
  working that way).
- Use FBSDID.

MFC after:	1 month
- MFpowerpc: sys/powerpc/powerpc/nexus.c rev. 1.7 (partial)
  Use bus_generic_probe() and add a bus_add_child() interface method to
  allow device drivers to use the identify method to add themselves if
  need be (e.g. syscons(4)).
- Use FBSDID.
- Sprinkle some KBD_IS_* and KBD_*_DONE macros in sunkbd_configure() as
  a band-aid allowing to call this function savely multiple times, e.g.
  during sckbdprobe() and sc_probe_unit(). Otherwise calling it a second
  time results in a non-working keyboard. This needs a lot of more work
  to actually do the right thing and work like expected.
- Let sunkbd_configure() return the number of the found keyboards, i.e.
  1 in case probing succeeds, as it's expected. The return values of the
  keyboard configure functions however currently aren't checked so this
  doesn't make a difference at the moment.
- Use FBSDID.
Remove superfluous braces and add #ifndef __sparc64__ around the
VTB_FRAMEBUFFER specific code. On sparc64 we don't use a buffer of
type VTB_FRAMEBUFFER (see syscons.c) and excluding the respective
code here allows to compile syscons(4) without isa(4).

Requested by:	joerg, marcel, yongari
On sparc64 use 'syscons' rather than 'sc' for SC_DRIVER_NAME so
syscons(4) and its pseudo-devices don't get confused (including by
other device drivers) with the system controller devices which are
also termed 'sc' in the OFW tree (and which we probably want to
interface with hwpmc(4) one day).
- Not every architecture defaults to a black background (e.g. sparc64
  uses white) so base the color of the border on SC_NORM_ATTR rather
  than hardcoding BG_BLACK.
- Use SC_DRIVER_NAME rather than hardcoding 'sc' in message strings
  (see also sys/dev/syscons/syscons.h rev. 1.82).
- Remove duplicate FBSDID.
- Start copyright comments with /*- where missing.
o creator(4):
  - Use register macros instead of magic values in the code. [1]
  - Check the return values of OF_getprop() and other stuff that actually
    can fail.
  - Let the unimplemented video driver methods return ENODEV rather
    than 0 so other code isn't tricked into thinking a certain operation
    was successfull. In case of e.g. the video driver creator_ioctl()
    this caused vidcontrol(1) to return random garbage information.
    Remove the TODO macros in the unimplemented video driver methods
    which did a printf("%s: unimplemented\n", __func__). Under certain
    circumstances these managed to invoke a printf() when a low-level
    console device wasn't attached, yet, causing a Fast Data Access MMU
    Miss. These macros were only really usefull for development anyway.
  - Set the struct video_adapter and struct video_info va_flags and
    vi_flags etc. as appropriate.
  - In creator_configure() don't rely on hitting the node which is the
    chosen console device first when searching the OFW tree for adapters
    compatible with this driver. Instead just check whether the chosen
    console device is a viable target for this driver. Targets that are
    not the console (including additional cards in multi-head configs)
    will be attached through creator_upa_attach(). I think this how the
    code in creator_configure() was actually meant to work.
    Honour the VIO_PROBE_ONLY flag and don't initialise and register the
    console device twice when creator_configure() is called a second time
    during sc_probe_unit().
    Let creator_configure() return the number of the found adapters,
    i.e. 1 in case probing succeeds, as it's expected. The return values
    of video adapter configure functions however currently aren't checked
    so this doesn't make a difference at the moment.
  - In creator_upa_attach() don't rely on probing and attaching the
    adapter which is the console first, in case there are multiple
    adpaters and one of them is the console this could lead into using
    the video adapter unit 0 twice.
  - Make the check for DACs with inverted cursor control a bit more
    precise and actually honour that information when turning the cursor
    on or off. Add a helper function creator_cursor_enable() for this
    in order to keep code duplication low. [1]
  - Don't bother with faking a hardware cursor in case a device is the
    console. Apparently this was meant to start kernel output right after
    where the firmware left. In general this isn't worth the fuzz and
    also had no real effect as creator_set_mode() did clear the screen
    in any case, not just in case a device was not the console.
  - Implement creator_fill_rect() and use it to actually blank the
    display in creator_blank_display() when the mode is V_DISPLAY_BLANK,
    moving blanking the display out of creator_set_mode(). Use it also
    to implement creator_set_border() so the border can be re-drawn
    when switching to a VTY from X, exiting X, etc. (which leaves us
    with a black border most of the time).
  - Implement the video driver creator_ioctl(), moving the implementation
    of the IOCTL interface from the fbN CDEV version of creator_ioctl()
    into the video driver version and use the latter to implement the
    former. Use fb_commonioctl() to handle most of the FBIO IOCTLs.
    This gives programs like vidcontrol(1) which use the video driver
    creator_ioctl() a chance of working.
    Implement turning off the cursor via the FBIOSCURSOR IOCTL, which
    Xorg uses to in order to inform the OS that it's taking over the
    cursor. In creator_putm() check whether the cursor is enabled and
    (re-)install it if necessary, moving installing the cursor out of
    creator_init() and into a helper function creator_cursor_install().
    This fixes the missing mouse pointer when switching to a VTY from X,
    exiting X, etc.
  - Some clean-up (remove unused/useless code, etc.).

o sparc64/creator/creator_upa.c / sparc64/sparc64/sc_machdep.c:
  - Attach syscons(4) as an own pseudo-device on the nexus rather than
    directly in creator_upa_attach(), similiar to attaching syscons(4)
    as a pseudo-device on isa(4) on other archs. This makes it a whole
    lot easier to do the right thing in multi-head configs, especially
    with different types of graphics adapters. [2]
  - Set SC_AUTODETECT_KBD by default so USB keyboards work out of the
    box. [2]

Based on/obtained from:	Xorg 'ffb' driver [1]
Based on/obtained from:	FreeBSD/powerpc [2]
Grab FBTYPE_NOTSUN3 and use it for FBTYPE_PCIMISC. The value matches
the one used in NetBSD for FBTYPE_PCIMISC.
Add machfb(4), a driver for ATI Mach64 graphics chips intended for
use with syscons(4) on sparc64. It's based on the respective NetBSD
driver with some additional info (initialisation/hardware cursor)
obtained from the Xorg 'ati' driver and some ideas taken from
creator(4). ATI Mach64 chips ("ATI Rage") are quite common as low-
end graphics chips in PCI-based sun4u machines and are used on-board
in e.g. Blade 100 and a couple of OEM products. Most if not all of
the Sun PGX add-on cards family (descriptions of the PGX32 are
conflicting but most say it's a Rage Pro) are also based on these
chips. Depending on the version of the OBP Mach64 cards destined for
use in i386 machines also work in sun4u machines.
The driver uses pixel mode with hardware acceleration as far as
syscons(4) currently permits on sparc64 so text mode is already
quite fast. The hardware cursor is used for the mouse pointer;
for one because this is a "restriction" induced in syscons(4) on
sparc64 by creator(4) and also because of issues with mapping
the aperture when used as a low-level early during boot. Due to
insufficiencies in the available documentation I didn't manage to
get mode switch work properly (sync problems), yet. So for now
this driver relies on the OBP having initialised a mode (as does
creator(4)). On all of the tested machines is even true when using
a serial console (and also not only when the OBP switched to a
serial console because no keyboard is present). In general however
the states the Mach64 chips are left in by the OBP vary a lot
depending on the version of the OBP. This e.g. includes the aperture
not being mapped in even when used as the console and the OBP just
barfing when asked to map it. The latter is also the reason for the
existence of this native driver in FreeBSD rather than taking an
OFW frambuffer approach.
Xorg is also happy to talk to these chips by mmap'ing them through
this driver. For some hardware configs like on the Blade 100 a fix
for the Xorg sparc64 MD bus code is however needed (added in version
6.8.2_2 of the xorg-server port).
The video driver font loading and saving methods are not implemented,
yet, as syscons(4) needs more work in that area to work viable on
sparc64.
With minor modifications machfb(4) would most likely also work on
powerpc, when #ifdef'ing the OFW and possibly implementing mode
setting probably also on the other archs. The latter is however
not very practible at the moment as it would conflict with vga(4).

Tested/developed with:	Rage II+ add-on card on AX1105 and AXi board,
			AXe board (on-board Rage Pro)
Additional testing by:	marcel (Ultra 5 w/ on-board Rage Pro),
			scottl (Naturetech GENIALstation 777S w/ on-board
			Rage Mobility M1),
			Michiel Boland and Ilmar S. Habibulin (Blade 100
			w/ on-board Rage XL)
- Hook up machfb(4) to the sparc64 build, not enabled in GENERIC
  by default, yet.
- Replace "graphics cards" with "framebuffers" in the description
  of creator(4) in order to make it uniform with the description of
  machfb(4) and the latter occur both on-board and as add-on cards.
Remove GIANT_REQUIRED from swapout_procs().
Add PCI ID for BCM5789.

Submitted by:	S. Aeschbacher
BCM5789 support.

MFC after:	3 days
- Add a HARDWARE section based on the previous 'Supported Cards'
  subsection and the hardware notes.
- Xref all snd_* drivers

MFC after:	1 week
soundcard -> sound card

MFC after:	3 days