1#- 2# Copyright (c) 2008 Nathan Whitehorn 3# All rights reserved. 4# 5# Redistribution and use in source and binary forms, with or without 6# modification, are permitted provided that the following conditions 7# are met: 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. 13# 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 24# SUCH DAMAGE. 25# 26# $FreeBSD$ 27# 28 29#include <dev/ofw/openfirm.h> 30#include <dev/ofw/ofwvar.h> 31 32/** 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. 35 *@{ 36 */ 37 38INTERFACE ofw; 39 40/** 41 * @brief Initialize OFW client interface 42 * 43 * @param _cookie A handle to the client interface, generally the OF 44 * callback routine. 45 */ 46METHOD void init { 47 ofw_t _ofw; 48 void *_cookie; 49}; 50 51/** 52 * @brief Return next sibling of node 53 * 54 * @param _node Selected node 55 */ 56METHOD phandle_t peer { 57 ofw_t _ofw; 58 phandle_t _node; 59}; 60 61/** 62 * @brief Return parent of node 63 * 64 * @param _node Selected node 65 */ 66METHOD phandle_t parent { 67 ofw_t _ofw; 68 phandle_t _node; 69}; 70 71/** 72 * @brief Return first child of node 73 * 74 * @param _node Selected node 75 */ 76METHOD phandle_t child { 77 ofw_t _ofw; 78 phandle_t _node; 79}; 80 81/** 82 * @brief Return package corresponding to instance 83 * 84 * @param _handle Selected instance 85 */ 86METHOD phandle_t instance_to_package { 87 ofw_t _ofw; 88 ihandle_t _handle; 89}; 90 91/** 92 * @brief Return length of node property 93 * 94 * @param _node Selected node 95 * @param _prop Property name 96 */ 97METHOD ssize_t getproplen { 98 ofw_t _ofw; 99 phandle_t _node; 100 const char *_prop; 101}; 102 103/** 104 * @brief Read node property 105 * 106 * @param _node Selected node 107 * @param _prop Property name 108 * @param _buf Pointer to buffer 109 * @param _size Size of buffer 110 */ 111METHOD ssize_t getprop { 112 ofw_t _ofw; 113 phandle_t _node; 114 const char *_prop; 115 void *_buf; 116 size_t _size; 117}; 118 119/** 120 * @brief Get next property name 121 * 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 126 */ 127METHOD int nextprop { 128 ofw_t _ofw; 129 phandle_t _node; 130 const char *_prop; 131 char *_buf; 132 size_t _size; 133}; 134 135/** 136 * @brief Set property 137 * 138 * @param _node Selected node 139 * @param _prop Property name 140 * @param _buf Value to set 141 * @param _size Size of buffer 142 */ 143METHOD int setprop { 144 ofw_t _ofw; 145 phandle_t _node; 146 const char *_prop; 147 const void *_buf; 148 size_t _size; 149}; 150 151/** 152 * @brief Canonicalize path 153 * 154 * @param _path Path to canonicalize 155 * @param _buf Buffer for canonicalized path 156 * @param _size Size of buffer 157 */ 158METHOD ssize_t canon { 159 ofw_t _ofw; 160 const char *_path; 161 char *_buf; 162 size_t _size; 163}; 164 165/** 166 * @brief Return phandle for named device 167 * 168 * @param _path Device path 169 */ 170METHOD phandle_t finddevice { 171 ofw_t _ofw; 172 const char *_path; 173}; 174 175/** 176 * @brief Return path for node instance 177 * 178 * @param _handle Instance handle 179 * @param _path Buffer for path 180 * @param _size Size of buffer 181 */ 182METHOD ssize_t instance_to_path { 183 ofw_t _ofw; 184 ihandle_t _handle; 185 char *_path; 186 size_t _size; 187}; 188 189/** 190 * @brief Return path for node 191 * 192 * @param _node Package node 193 * @param _path Buffer for path 194 * @param _size Size of buffer 195 */ 196METHOD ssize_t package_to_path { 197 ofw_t _ofw; 198 phandle_t _node; 199 char *_path; 200 size_t _size; 201}; 202 203 204# Methods for OF method calls (optional) 205 206/** 207 * @brief Test to see if a service exists. 208 * 209 * @param _name name of the service 210 */ 211METHOD int test { 212 ofw_t _ofw; 213 const char *_name; 214}; 215 216/** 217 * @brief Call method belonging to an instance handle 218 * 219 * @param _instance Instance handle 220 * @param _method Method name 221 * @param _nargs Number of arguments 222 * @param _nreturns Number of return values 223 * @param _args_and_returns Values for arguments, followed by returns 224 */ 225 226METHOD int call_method { 227 ofw_t _ofw; 228 ihandle_t _instance; 229 const char *_method; 230 int _nargs; 231 int _nreturns; 232 233 unsigned long *_args_and_returns; 234}; 235 236/** 237 * @brief Interpret a forth command 238 * 239 * @param _cmd Command 240 * @param _nreturns Number of return values 241 * @param _returns Values for returns 242 */ 243 244METHOD int interpret { 245 ofw_t _ofw; 246 const char *_cmd; 247 int _nreturns; 248 unsigned long *_returns; 249}; 250 251# Device I/O Functions (optional) 252 253/** 254 * @brief Open node, returning instance handle 255 * 256 * @param _path Path to node 257 */ 258METHOD ihandle_t open { 259 ofw_t _ofw; 260 const char *_path; 261} 262 263/** 264 * @brief Close node instance 265 * 266 * @param _instance Instance to close 267 */ 268METHOD void close { 269 ofw_t _ofw; 270 ihandle_t _instance; 271} 272 273/** 274 * @brief Read from device 275 * 276 * @param _instance Device instance 277 * @param _buf Buffer to read to 278 * @param _size Size of buffer 279 */ 280METHOD ssize_t read { 281 ofw_t _ofw; 282 ihandle_t _instance; 283 void *_buf; 284 size_t size; 285} 286 287/** 288 * @brief Write to device 289 * 290 * @param _instance Device instance 291 * @param _buf Buffer to write from 292 * @param _size Size of buffer 293 */ 294METHOD ssize_t write { 295 ofw_t _ofw; 296 ihandle_t _instance; 297 const void *_buf; 298 size_t size; 299} 300 301/** 302 * @brief Seek device 303 * 304 * @param _instance Device instance 305 * @param _off Offset to which to seek 306 */ 307METHOD int seek { 308 ofw_t _ofw; 309 ihandle_t _instance; 310 uint64_t _off; 311} 312 313# Open Firmware memory management 314 315/** 316 * @brief Claim virtual memory 317 * 318 * @param _addr Requested memory location (NULL for first available) 319 * @param _size Requested size in bytes 320 * @param _align Requested alignment 321 */ 322METHOD caddr_t claim { 323 ofw_t _ofw; 324 void *_addr; 325 size_t _size; 326 u_int _align; 327} 328 329/** 330 * @brief Release virtual memory 331 * 332 * @param _addr Memory location 333 * @param _size Size in bytes 334 */ 335METHOD void release { 336 ofw_t _ofw; 337 void *_addr; 338 size_t _size; 339}; 340 341# Commands for returning control to the firmware 342 343/** 344 * @brief Temporarily return control to firmware 345 */ 346METHOD void enter { 347 ofw_t _ofw; 348}; 349 350/** 351 * @brief Halt and return control to firmware 352 */ 353METHOD void exit { 354 ofw_t _ofw; 355}; 356 357 358