sys/dev/ofw/ofw_if.m

   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
  38 INTERFACE 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  */
  46 METHOD 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  */
  56 METHOD 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  */
  66 METHOD 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  */
  76 METHOD 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  */
  86 METHOD 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  */
  97 METHOD 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  */
 111 METHOD 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  */
 127 METHOD 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  */
 143 METHOD 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  */
 158 METHOD 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  */
 170 METHOD 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  */
 182 METHOD 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  */
 196 METHOD 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  */
 210 METHOD 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
 225 METHOD 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
 243 METHOD 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  */
 257 METHOD 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  */
 267 METHOD 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  */
 279 METHOD 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  */
 293 METHOD 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  */
 306 METHOD 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  */
 321 METHOD 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  */
 334 METHOD 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  */
 345 METHOD void enter {
 346         ofw_t           _ofw;
 347 };
 348
 349 /**
 350  * @brief Halt and return control to firmware.
 351  */
 352 METHOD void exit {
 353         ofw_t           _ofw;
 354 };