diff options
Diffstat (limited to 'static/freebsd/man4/openfirm.4 3.html')
| -rw-r--r-- | static/freebsd/man4/openfirm.4 3.html | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/static/freebsd/man4/openfirm.4 3.html b/static/freebsd/man4/openfirm.4 3.html new file mode 100644 index 00000000..b868db43 --- /dev/null +++ b/static/freebsd/man4/openfirm.4 3.html @@ -0,0 +1,178 @@ +<table class="head"> + <tr> + <td class="head-ltitle">OPENFIRM(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">OPENFIRM(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">openfirm</code> — <span class="Nd">Open + Firmware interface</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/ioctl.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">dev/ofw/openfirmio.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <span class="Pa">/dev/openfirm</span> device is an interface + to the Open Firmware device tree. This interface is highly stylized. It uses + <a class="Xr">ioctl(2)</a> calls for all operations. These calls refer to + the nodes in the 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.</p> +<p class="Pp">The calls that only take and/or return the package handle of a + node use a pointer to a <var class="Vt">phandle_t</var> for this purpose. + The others use a pointer to a <var class="Vt">struct ofiocdesc</var> + descriptor, which has the following definition:</p> +<div class="Bd Pp Li"> +<pre>struct ofiocdesc { + phandle_t of_nodeid; + int of_namelen; + const char *of_name; + int of_buflen; + char *of_buf; +};</pre> +</div> +<p class="Pp">The <var class="Va">of_nodeid</var> member is the package handle + of the node that is passed in or returned. Strings are passed in via the + <var class="Va">of_name</var> member of <var class="Va">of_namelen</var> + length. The maximum accepted length of <var class="Va">of_name</var> is + <code class="Dv">OFIOCMAXNAME</code>. The <var class="Va">of_buf</var> + member is used to return strings except for the + <code class="Dv">OFIOCSET</code> call where it is also used to pass in a + string. In the latter case the maximum accepted length of + <var class="Va">of_buf</var> is <code class="Dv">OFIOCMAXVALUE</code>. + Generally, <var class="Va">of_buf</var> works in a value-result fashion. At + entry to the <a class="Xr">ioctl(2)</a> call, + <var class="Va">of_buflen</var> is expected to reflect the buffer size. On + return, <var class="Va">of_buflen</var> is updated to reflect the buffer + contents.</p> +<p class="Pp">The following <a class="Xr">ioctl(2)</a> calls are supported:</p> +<dl class="Bl-tag"> + <dt id="OFIOCGETOPTNODE"><a class="permalink" href="#OFIOCGETOPTNODE"><code class="Dv">OFIOCGETOPTNODE</code></a></dt> + <dd>Uses a <var class="Vt">phandle_t</var>. Takes nothing and returns the + package handle of the <span class="Pa">/options</span> node.</dd> + <dt id="OFIOCGETNEXT"><a class="permalink" href="#OFIOCGETNEXT"><code class="Dv">OFIOCGETNEXT</code></a></dt> + <dd>Uses a <var class="Vt">phandle_t</var>. Takes the package handle of a node + and returns the package handle of the next node in the 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.</dd> + <dt id="OFIOCGETCHILD"><a class="permalink" href="#OFIOCGETCHILD"><code class="Dv">OFIOCGETCHILD</code></a></dt> + <dd>Uses a <var class="Vt">phandle_t</var>. 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 + <code class="Dv">OFIOCGETNEXT</code>. If the node does not have a child, a + package handle of 0 is returned.</dd> + <dt id="OFIOCGET"><a class="permalink" href="#OFIOCGET"><code class="Dv">OFIOCGET</code></a></dt> + <dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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.</dd> + <dt id="OFIOCGETPROPLEN"><a class="permalink" href="#OFIOCGETPROPLEN"><code class="Dv">OFIOCGETPROPLEN</code></a></dt> + <dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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 <code class="Dv">OFIOCGET</code> 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.</dd> + <dt id="OFIOCSET"><a class="permalink" href="#OFIOCSET"><code class="Dv">OFIOCSET</code></a></dt> + <dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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 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 Open Firmware may also + completely refuse to write the given value to the property. In this case + <code class="Er">EINVAL</code> is returned.</dd> + <dt id="OFIOCNEXTPROP"><a class="permalink" href="#OFIOCNEXTPROP"><code class="Dv">OFIOCNEXTPROP</code></a></dt> + <dd>Uses a <var class="Vt">struct ofiocdesc</var>. 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, <code class="Er">ENOENT</code> is + returned.</dd> + <dt id="OFIOCFINDDEVICE"><a class="permalink" href="#OFIOCFINDDEVICE"><code class="Dv">OFIOCFINDDEVICE</code></a></dt> + <dd>Uses a <var class="Vt">struct ofiocdesc</var>. Takes the name or alias + name of a device node. Returns package handle of the node. If no matching + node is found, <code class="Er">ENOENT</code> is returned.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<dl class="Bl-tag"> + <dt><span class="Pa">/dev/openfirm</span></dt> + <dd>Open Firmware interface node</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">The following may result in rejection of an operation:</p> +<dl class="Bl-tag"> + <dt>[<code class="Er">EBADF</code>]</dt> + <dd>The requested operation requires permissions not specified at the call to + <code class="Fn">open</code>().</dd> + <dt>[<code class="Er">EINVAL</code>]</dt> + <dd>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.</dd> + <dt>[<code class="Er">ENAMETOOLONG</code>]</dt> + <dd>The given name or value exceeds the maximum allowed length of + <code class="Dv">OFIOCMAXNAME</code> and + <code class="Dv">OFIOCMAXVALUE</code> bytes respectively.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">ioctl(2)</a>, <a class="Xr">ofwdump(8)</a></p> +<p class="Pp"><cite class="Rs"><i class="RsB">IEEE Std 1275-1994:</i>, + <i class="RsB">IEEE Standard for Boot Firmware (Initialization + Configuration) Firmware:</i>, <i class="RsB">Core Requirements and + Practices"</i>, <span class="RsQ">IEEE Standards Organization</span>, + <span class="RsO">ISBN 1-55937-426-8</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">openfirm</code> interface first appeared in + <span class="Ux">NetBSD 1.6</span>. The first + <span class="Ux">FreeBSD</span> version to include it was + <span class="Ux">FreeBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">openfirm</code> interface was ported to + <span class="Ux">FreeBSD</span> by <span class="An">Thomas Moestl</span> + <<a class="Mt" href="mailto:tmm@FreeBSD.org">tmm@FreeBSD.org</a>>. + This manual page was written by <span class="An">Marius Strobl</span> + <<a class="Mt" href="mailto:marius@FreeBSD.org">marius@FreeBSD.org</a>> + based on the <span class="Ux">OpenBSD</span> manual page for + <a class="Xr">openprom(4)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">Due to limitations within Open Firmware itself, these functions + run at elevated priority and may adversely affect system performance.</p> +<p class="Pp">For at least the <span class="Pa">/options</span> node the + property value passed in to the <code class="Dv">OFIOCSET</code> call has to + be null-terminated and the value length passed in has to include the + terminating ‘<code class="Li">\0</code>’. However, as with the + <code class="Dv">OFIOCGET</code> call, the returned value length does not + include the terminating ‘<code class="Li">\0</code>’.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 16, 2021</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |