4 files changed, 410 insertions, 0 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index b8e63315cb95..abdc1b0f4c4b 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -410,6 +410,7 @@ MAN=	aac.4 \
 	oce.4 \
 	ocs_fc.4\
 	ohci.4 \
+	openfirm.4 \
 	orm.4 \
 	${_ossl.4} \
 	ow.4 \
@@ -718,6 +719,7 @@ MLINKS+=netintro.4 net.4 \
 	netintro.4 networking.4
 MLINKS+=${_nfe.4} ${_if_nfe.4}
 MLINKS+=nge.4 if_nge.4
+MLINKS+=openfirm.4 openfirmware.4
 MLINKS+=ow.4 onewire.4
 MLINKS+=pccbb.4 cbb.4
 MLINKS+=pcm.4 snd.4 \
diff --git a/share/man/man4/man4.powerpc/Makefile b/share/man/man4/man4.powerpc/Makefile
index 6cc248c8fcf3..05c5d4012fe8 100644
--- a/share/man/man4/man4.powerpc/Makefile
+++ b/share/man/man4/man4.powerpc/Makefile
@@ -7,6 +7,7 @@ MAN=	adb.4 \
 	cuda.4 \
 	dtsec.4 \
 	llan.4 \
+	ofw_console.4 \
 	pmu.4 \
 	powermac_nvram.4 \
 	smu.4 \
diff --git a/share/man/man4/man4.powerpc/ofw_console.4 b/share/man/man4/man4.powerpc/ofw_console.4
new file mode 100644
index 000000000000..eb73235c4970
--- /dev/null
+++ b/share/man/man4/man4.powerpc/ofw_console.4
@@ -0,0 +1,111 @@
+.\"-
+.\" Copyright (c) 2001 Miodrag Vallat.
+.\" Copyright (c) 2005 Marius Strobl <marius@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistribution of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"	from: OpenBSD: pcons.4,v 1.4 2003/06/02 16:16:26 miod Exp
+.\" $FreeBSD$
+.\"
+.Dd January 16, 2021
+.Dt OFW_CONSOLE 4 powerpc
+.Os
+.Sh NAME
+.Nm ofw_console
+.Nd "Open Firmware console"
+.Sh SYNOPSIS
+.Cd "cpu AIM"
+.Cd "options OFWCONS_POLL_HZ=N"
+.Pp
+.Cd "options KDB"
+.Cd "options DDB"
+.Cd "options ALT_BREAK_TO_DEBUGGER"
+.Sh DESCRIPTION
+The
+.Nm
+driver provides a simple text console,
+using the Open Firmware services for input and output.
+It will use the Open Firmware console devices set via the
+.Va input-device
+and
+.Va output-device
+variables.
+.Pp
+This driver is deprecated and only provided as a fallback console mechanism
+if the real console hardware can not be driven by
+.Fx .
+.Pp
+In case the
+.Nm
+console appears to work too slowly, its responsiveness probably can be improved
+by including
+.Cd "options OFWCONS_POLL_HZ=N" .
+When omitted,
+.Dv OFWCONS_POLL_HZ
+defaults to 4.
+For example, on
+.Tn Sun Ultra 2
+a value of 20 or higher works best.
+Too high values, on the other hand, can cause
+.Nm
+to unnecessarily consume CPU.
+.Sh FILES
+.Bl -tag -width ".Pa /dev/keyboard" -compact
+.It Pa /dev/console
+.It Pa /dev/keyboard
+terminal input device in case the console input device is the keyboard
+.It Pa /dev/screen
+terminal output device in case the console output device is the screen
+.It Pa /dev/tty[a-z]
+terminal device in case both the console input and output device is tty[a-z]
+.El
+.Sh SEE ALSO
+.Xr akbd 4 ,
+.Xr powermac_nvram 4 ,
+.Xr vt 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 5.0 .
+.Sh AUTHORS
+The
+.Nm
+driver was written by
+.An Benno Rice Aq Mt benno@FreeBSD.org .
+.Sh CAVEATS
+Since the Open Firmware will handle BREAK
+(or Stop-A)
+sequences before
+.Nm ,
+the preferred way to enter
+.Xr ddb 4
+when using
+.Nm
+is to include
+.Cd "options ALT_BREAK_TO_DEBUGGER"
+in a ddb-enabled kernel, and enter the alternate BREAK sequence
+(RETURN TILDE CTRL-b).
+.Sh BUGS
+The
+.Nm
+driver also not attach to the hardware resources it actually talks to.
diff --git a/share/man/man4/openfirm.4 b/share/man/man4/openfirm.4
new file mode 100644
index 000000000000..ef9755d0c49d
--- /dev/null
+++ b/share/man/man4/openfirm.4
@@ -0,0 +1,296 @@
+.\"-
+.\" Copyright (c) 1992, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" This software was developed by the Computer Systems Engineering group
+.\" at Lawrence Berkeley Laboratory under DARPA contract BG 91-66 and
+.\" contributed to Berkeley.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	from: @(#)openprom.4	8.1 (Berkeley) 6/5/93
+.\"	from: OpenBSD: openprom.4,v 1.9 2004/03/22 22:07:21 miod Exp
+.\"
+.\"-
+.\" Copyright (c) 2005 Marius Strobl <marius@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 16, 2021
+.Dt OPENFIRM 4
+.Os
+.Sh NAME
+.Nm openfirm
+.Nd "Open Firmware interface"
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/ioctl.h
+.In dev/ofw/openfirmio.h
+.Sh DESCRIPTION
+The
+.Pa /dev/openfirm
+device is an interface to the
+.Tn Open Firmware
+device tree.
+This interface is highly stylized.
+It uses
+.Xr ioctl 2
+calls for all operations.
+These calls refer to the nodes in the
+.Tn Open Firmware
+device tree.
+The nodes are represented by package handles,
+which are simply integer values describing data areas.
+Occasionally a package handle of 0 may be used or returned instead,
+as described below.
+.Pp
+The calls that only take and/or return the package handle of a node
+use a pointer to a
+.Vt phandle_t
+for this purpose.
+The others use a pointer to a
+.Vt "struct ofiocdesc"
+descriptor,
+which has the following definition:
+.Bd -literal
+struct ofiocdesc {
+	phandle_t	of_nodeid;
+	int		of_namelen;
+	const char	*of_name;
+	int		of_buflen;
+	char		*of_buf;
+};
+.Ed
+.Pp
+The
+.Va of_nodeid
+member is the package handle of the node that is passed in or returned.
+Strings are passed in via the
+.Va of_name
+member of
+.Va of_namelen
+length.
+The maximum accepted length of
+.Va of_name
+is
+.Dv OFIOCMAXNAME .
+The
+.Va of_buf
+member is used to return strings except for the
+.Dv OFIOCSET
+call where it is also used to pass in a string.
+In the latter case the maximum accepted length of
+.Va of_buf
+is
+.Dv OFIOCMAXVALUE .
+Generally,
+.Va of_buf
+works in a value-result fashion.
+At entry to the
+.Xr ioctl 2
+call,
+.Va of_buflen
+is expected to reflect the buffer size.
+On return,
+.Va of_buflen
+is updated to reflect the buffer contents.
+.Pp
+The following
+.Xr ioctl 2
+calls are supported:
+.Bl -tag -width ".Dv OFIOCGETOPTNODE"
+.It Dv OFIOCGETOPTNODE
+Uses a
+.Vt phandle_t .
+Takes nothing and returns the package handle of the
+.Pa /options
+node.
+.It Dv OFIOCGETNEXT
+Uses a
+.Vt phandle_t .
+Takes the package handle of a node and returns the package handle of the next
+node in the
+.Tn Open Firmware
+device tree.
+The node following the last node has a package handle of 0.
+The node following the node with the package handle of 0 is the first node.
+.It Dv OFIOCGETCHILD
+Uses a
+.Vt phandle_t .
+Takes the package handle of a node and returns the package handle of the first
+child of that node.
+This child may have siblings.
+These can be determined by using
+.Dv OFIOCGETNEXT .
+If the node does not have a child,
+a package handle of 0 is returned.
+.It Dv OFIOCGET
+Uses a
+.Vt "struct ofiocdesc" .
+Takes the package handle of a node and the name of a property.
+Returns the property value and its length.
+If no such property is associated with that node,
+the length of the value is set to \-1.
+If the named property exists but has no value,
+the length of the value is set to 0.
+.It Dv OFIOCGETPROPLEN
+Uses a
+.Vt "struct ofiocdesc" .
+Takes the package handle of a node and the name of a property.
+Returns the length of the property value.
+This call is the same as
+.Dv OFIOCGET
+except that only the length of the property value is returned.
+It can be used to determine whether a node has a particular property or whether
+a property has a value without the need to provide memory for storing the value.
+.It Dv OFIOCSET
+Uses a
+.Vt "struct ofiocdesc" .
+Takes the package handle of a node,
+the name of a property and a property value.
+Returns the property value and the length that actually have been written.
+The
+.Tn Open Firmware
+may choose to truncate the value if it is too long or write a valid value
+instead if the given value is invalid for the particular property.
+Therefore the returned value should be checked.
+The
+.Tn Open Firmware
+may also completely refuse to write the given value to the property.
+In this case
+.Er EINVAL
+is returned.
+.It Dv OFIOCNEXTPROP
+Uses a
+.Vt "struct ofiocdesc" .
+Takes the package handle of a node and the name of a property.
+Returns the name and the length of the next property of the node.
+If the property referenced by the given name is the last property of the node,
+.Er ENOENT
+is returned.
+.It Dv OFIOCFINDDEVICE
+Uses a
+.Vt "struct ofiocdesc" .
+Takes the name or alias name of a device node.
+Returns package handle of the node.
+If no matching node is found,
+.Er ENOENT
+is returned.
+.El
+.Sh FILES
+.Bl -tag -width ".Pa /dev/openfirm"
+.It Pa /dev/openfirm
+Open Firmware interface node
+.El
+.Sh DIAGNOSTICS
+The following may result in rejection of an operation:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The requested operation requires permissions not specified at the call to
+.Fn open .
+.It Bq Er EINVAL
+The given package handle is not 0 and does not correspond to any valid node,
+or the given package handle is 0 where 0 is not allowed.
+.It Bq Er ENAMETOOLONG
+The given name or value exceeds the maximum allowed length of
+.Dv OFIOCMAXNAME
+and
+.Dv OFIOCMAXVALUE
+bytes respectively.
+.El
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr ofwdump 8
+.Rs
+.%Q "IEEE Standards Organization"
+.%B "IEEE Std 1275-1994:"
+.%B "IEEE Standard for Boot Firmware (Initialization Configuration) Firmware:"
+.%B Core Requirements and Practices"
+.%O ISBN 1-55937-426-8
+.Re
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 1.6 .
+The first
+.Fx
+version to include it was
+.Fx 5.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+interface was ported to
+.Fx
+by
+.An Thomas Moestl Aq Mt tmm@FreeBSD.org .
+This manual page was written by
+.An Marius Strobl Aq Mt marius@FreeBSD.org
+based on the
+.Ox
+manual page for
+.Xr openprom 4 .
+.Sh CAVEATS
+Due to limitations within
+.Tn Open Firmware
+itself,
+these functions run at elevated priority and may adversely affect system
+performance.
+.Pp
+For at least the
+.Pa /options
+node the property value passed in to the
+.Dv OFIOCSET
+call has to be null-terminated and the value length passed in has to include
+the terminating
+.Ql \e0 .
+However, as with the
+.Dv OFIOCGET
+call,
+the returned value length does not include the terminating
+.Ql \e0 .