2 # Copyright (c) 2008 Nathan Whitehorn
5 # Redistribution and use in source and binary forms, with or without
6 # modification, are permitted provided that the following conditions
8 # 1. Redistributions of source code must retain the above copyright
9 # notice, this list of conditions and the following disclaimer.
10 # 2. Redistributions in binary form must reproduce the above copyright
11 # notice, this list of conditions and the following disclaimer in the
12 # documentation and/or other materials provided with the distribution.
14 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 #include <dev/ofw/openfirm.h>
30 #include <dev/ofw/ofwvar.h>
33 * @defgroup OFW ofw - KObj methods for Open Firmware RTAS implementations
34 * @brief A set of methods to implement the Open Firmware client side interface.
41 * @brief Initialize OFW client interface
43 * @param _cookie A handle to the client interface, generally the OF
52 * @brief Return next sibling of node.
54 * @param _node Selected node
56 METHOD phandle_t peer {
62 * @brief Return parent of node.
64 * @param _node Selected node
66 METHOD phandle_t parent {
72 * @brief Return first child of node.
74 * @param _node Selected node
76 METHOD phandle_t child {
82 * @brief Return package corresponding to instance.
84 * @param _handle Selected instance
86 METHOD phandle_t instance_to_package {
92 * @brief Return length of node property.
94 * @param _node Selected node
95 * @param _prop Property name
97 METHOD ssize_t getproplen {
104 * @brief Read node property.
106 * @param _node Selected node
107 * @param _prop Property name
108 * @param _buf Pointer to buffer
109 * @param _size Size of buffer
111 METHOD ssize_t getprop {
120 * @brief Get next property name.
122 * @param _node Selected node
123 * @param _prop Current property name
124 * @param _buf Buffer for next property name
125 * @param _size Size of buffer
127 METHOD int nextprop {
136 * @brief Set property.
138 * @param _node Selected node
139 * @param _prop Property name
140 * @param _buf Value to set
141 * @param _size Size of buffer
152 * @brief Canonicalize path.
154 * @param _path Path to canonicalize
155 * @param _buf Buffer for canonicalized path
156 * @param _size Size of buffer
158 METHOD ssize_t canon {
166 * @brief Return phandle for named device.
168 * @param _path Device path
170 METHOD phandle_t finddevice {
176 * @brief Return path for node instance.
178 * @param _handle Instance handle
179 * @param _path Buffer for path
180 * @param _size Size of buffer
182 METHOD ssize_t instance_to_path {
190 * @brief Return path for node.
192 * @param _node Package node
193 * @param _path Buffer for path
194 * @param _size Size of buffer
196 METHOD ssize_t package_to_path {
203 # Methods for OF method calls (optional)
206 * @brief Test to see if a service exists.
208 * @param _name name of the service
216 * @brief Call method belonging to an instance handle.
218 * @param _instance Instance handle
219 * @param _method Method name
220 * @param _nargs Number of arguments
221 * @param _nreturns Number of return values
222 * @param _args_and_returns Values for arguments, followed by returns
225 METHOD int call_method {
232 cell_t *_args_and_returns;
236 * @brief Interpret a forth command.
238 * @param _cmd Command
239 * @param _nreturns Number of return values
240 * @param _returns Values for returns
243 METHOD int interpret {
250 # Device I/O Functions (optional)
253 * @brief Open node, returning instance handle.
255 * @param _path Path to node
257 METHOD ihandle_t open {
263 * @brief Close node instance.
265 * @param _instance Instance to close
273 * @brief Read from device.
275 * @param _instance Device instance
276 * @param _buf Buffer to read to
277 * @param _size Size of buffer
279 METHOD ssize_t read {
287 * @brief Write to device.
289 * @param _instance Device instance
290 * @param _buf Buffer to write from
291 * @param _size Size of buffer
293 METHOD ssize_t write {
301 * @brief Seek device.
303 * @param _instance Device instance
304 * @param _off Offset to which to seek
312 # Open Firmware memory management
315 * @brief Claim virtual memory.
317 * @param _addr Requested memory location (NULL for first available)
318 * @param _size Requested size in bytes
319 * @param _align Requested alignment
321 METHOD caddr_t claim {
329 * @brief Release virtual memory.
331 * @param _addr Memory location
332 * @param _size Size in bytes
334 METHOD void release {
340 # Commands for returning control to the firmware
343 * @brief Temporarily return control to firmware.
350 * @brief Halt and return control to firmware.