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 +.\" 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 +.\" 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 .