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 int 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# Methods for OF method calls (optional) 204 205/** 206 * @brief Test to see if a service exists. 207 * 208 * @param _name name of the service 209 */ 210METHOD int test { 211 ofw_t _ofw; 212 const char *_name; 213}; 214 215/** 216 * @brief Call method belonging to an instance handle. 217 * 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 223 */ 224 225METHOD int call_method { 226 ofw_t _ofw; 227 ihandle_t _instance; 228 const char *_method; 229 int _nargs; 230 int _nreturns; 231 232 cell_t *_args_and_returns; 233}; 234 235/** 236 * @brief Interpret a forth command. 237 * 238 * @param _cmd Command 239 * @param _nreturns Number of return values 240 * @param _returns Values for returns 241 */ 242 243METHOD int interpret { 244 ofw_t _ofw; 245 const char *_cmd; 246 int _nreturns; 247 cell_t *_returns; 248}; 249 250# Device I/O Functions (optional) 251 252/** 253 * @brief Open node, returning instance handle. 254 * 255 * @param _path Path to node 256 */ 257METHOD ihandle_t open { 258 ofw_t _ofw; 259 const char *_path; 260} 261 262/** 263 * @brief Close node instance. 264 * 265 * @param _instance Instance to close 266 */ 267METHOD void close { 268 ofw_t _ofw; 269 ihandle_t _instance; 270} 271 272/** 273 * @brief Read from device. 274 * 275 * @param _instance Device instance 276 * @param _buf Buffer to read to 277 * @param _size Size of buffer 278 */ 279METHOD ssize_t read { 280 ofw_t _ofw; 281 ihandle_t _instance; 282 void *_buf; 283 size_t size; 284} 285 286/** 287 * @brief Write to device. 288 * 289 * @param _instance Device instance 290 * @param _buf Buffer to write from 291 * @param _size Size of buffer 292 */ 293METHOD ssize_t write { 294 ofw_t _ofw; 295 ihandle_t _instance; 296 const void *_buf; 297 size_t size; 298} 299 300/** 301 * @brief Seek device. 302 * 303 * @param _instance Device instance 304 * @param _off Offset to which to seek 305 */ 306METHOD int seek { 307 ofw_t _ofw; 308 ihandle_t _instance; 309 uint64_t _off; 310} 311 312# Open Firmware memory management 313 314/** 315 * @brief Claim virtual memory. 316 * 317 * @param _addr Requested memory location (NULL for first available) 318 * @param _size Requested size in bytes 319 * @param _align Requested alignment 320 */ 321METHOD caddr_t claim { 322 ofw_t _ofw; 323 void *_addr; 324 size_t _size; 325 u_int _align; 326} 327 328/** 329 * @brief Release virtual memory. 330 * 331 * @param _addr Memory location 332 * @param _size Size in bytes 333 */ 334METHOD void release { 335 ofw_t _ofw; 336 void *_addr; 337 size_t _size; 338}; 339 340# Commands for returning control to the firmware 341 342/** 343 * @brief Temporarily return control to firmware. 344 */ 345METHOD void enter { 346 ofw_t _ofw; 347}; 348 349/** 350 * @brief Halt and return control to firmware. 351 */ 352METHOD void exit { 353 ofw_t _ofw; 354}; 355