git: 0cdfc338053b - main - man4: bring back ofw_console.4 and openfirm.4
Marius Strobl
marius at FreeBSD.org
Sat Jan 16 22:53:49 UTC 2021
The branch main has been updated by marius:
URL: https://cgit.FreeBSD.org/src/commit/?id=0cdfc338053bc323b3c89f82b287f0fd52da8343
commit 0cdfc338053bc323b3c89f82b287f0fd52da8343
Author: Marius Strobl <marius at FreeBSD.org>
AuthorDate: 2021-01-16 15:58:38 +0000
Commit: Marius Strobl <marius at FreeBSD.org>
CommitDate: 2021-01-16 22:53:13 +0000
man4: bring back ofw_console.4 and openfirm.4
Back when I wrote openfirm.4, sparc64 was the only architecture to
include the corresponding device. However, nowadays all supported
architectures will provied this Open Firmware interface, even x86
when built with FDT support.
As for ofw_console(4), powerpc actually was the first architecture
to ship it but we'll probably not see another consumer in future.
This partially reverts 702547720ca01437081fb1b6f9eb281c9541021b and
r357794 respectively, adjusting paths and content as appropriate.
---
share/man/man4/Makefile | 2 +
share/man/man4/man4.powerpc/Makefile | 1 +
share/man/man4/man4.powerpc/ofw_console.4 | 111 +++++++++++
share/man/man4/openfirm.4 | 296 ++++++++++++++++++++++++++++++
4 files changed, 410 insertions(+)
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 at 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 at 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 at 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 at FreeBSD.org .
+This manual page was written by
+.An Marius Strobl Aq Mt marius at 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 .
More information about the dev-commits-src-main
mailing list