include/ofw/ofw.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup ofw
0007  *
0008  * RTEMS FDT implementation of OpenFirmWare Interface.
0009  *
0010  * RTEMS OFW is a FDT only implementation of the OpenFirmWare interface.
0011  * This API is created to be compatible with FreeBSD OpenFirmWare interface.
0012  * The main intention is to make porting of FreeBSD drivers to RTEMS easier.
0013  */
0014
0015 /*
0016  * Copyright (C) 2020 Niteesh Babu G S <niteesh.gs@gmail.com>
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #ifndef _OFW_H
0041 #define _OFW_H
0042
0043 #ifdef __cplusplus
0044 extern "C" {
0045 #endif
0046
0047 #include <rtems.h>
0048 #include <stdint.h>
0049 #include <sys/types.h>
0050
0051 /**
0052  * Represents a node in the device tree. The offset from fdtp to node is used
0053  * instead of fdt offset to make sure this is compatible with OF interface in
0054  * FreeBSD.
0055  */
0056 typedef uint32_t  phandle_t;
0057 /**
0058  * Represents the effective phandle of the node.
0059  */
0060 typedef uint32_t  ihandle_t;
0061 /**
0062  * Represents the data type of the buffer.
0063  */
0064 typedef uint32_t  pcell_t;
0065
0066 /**
0067  * @struct rtems_ofw_memory_area
0068  *
0069  * This is used to represent elements(FDT properties) that define
0070  * region of memory address.
0071  */
0072 typedef struct {
0073   /** The start address of the memory region. */
0074   uint32_t start;
0075   /** The size of the memory region. */
0076   uint32_t size;
0077 } rtems_ofw_memory_area;
0078
0079 /**
0080  * @struct rtems_ofw_ranges
0081  *
0082  * This is used to represent the ranges property in the device tree.
0083  */
0084 typedef struct {
0085   /** The physical address within the child bus address space */
0086   uint32_t child_bus;
0087   /** The physical address within the parent bus address space */
0088   uint32_t parent_bus;
0089   /** The size of the range in the child’s address space */
0090   uint32_t size;
0091 } rtems_ofw_ranges;
0092
0093 /**
0094  * @brief Gets the node that is next to @a node.
0095  *
0096  * @param[in] node Node offset
0097  *
0098  * @retval Peer node offset Successful operation.
0099  * @retval 0 No peer node or invalid node handle
0100  */
0101 phandle_t rtems_ofw_peer(
0102   phandle_t   node
0103 );
0104
0105 /**
0106  * @brief Gets the node that is the child of @a node.
0107  *
0108  * @param[in] node Node offset
0109  *
0110  * @retval child node offset Successful operation.
0111  * @retval 0 No child node or invalid node handle
0112  */
0113 phandle_t rtems_ofw_child(
0114   phandle_t   node
0115 );
0116
0117 /**
0118  * @brief Gets the node that is the parent of @a node.
0119  *
0120  * @param[in] node Node offset
0121  *
0122  * @retval child node offset Successful operation.
0123  * @retval 0 No child node or invalid node handle
0124  */
0125 phandle_t rtems_ofw_parent(
0126   phandle_t   node
0127 );
0128
0129 /**
0130  * @brief Gets the length of the property mentioned in @a propname.
0131  *
0132  * @param[in] node Node offset
0133  * @param[in] prop Property name
0134  *
0135  * @retval -1 Invalid node or property
0136  * @retval  Length of property on successful operation
0137  */
0138 ssize_t rtems_ofw_get_prop_len(
0139   phandle_t   node,
0140   const char *propname
0141 );
0142
0143 /**
0144  * @brief Gets the value of property mentioned in @a propname.
0145  *
0146  * @param[in] node Node offset
0147  * @param[in] prop Property name
0148  * @param[out] buf The property value gets stored in this buffer (Pre-allocated)
0149  * @param[in] len Length of the buffer
0150
0151  * @retval -1 Invalid node or property
0152  * @retval  Length of property on successful operation
0153  */
0154 ssize_t rtems_ofw_get_prop(
0155   phandle_t    node,
0156   const char  *propname,
0157   void        *buf,
0158   size_t       len
0159 );
0160
0161 /**
0162  * @brief Gets the value of property mentioned in @a prop.
0163  *
0164  * Gets the value of property of @a node and converts the value into the host's
0165  * endianness.
0166  *
0167  * @param[in] node Node offset
0168  * @param[in] prop Property name
0169  * @param[out] buf The property value gets stored in this buffer(Pre-allocated)
0170  * after converted to the host's endianness
0171  * @param[in] len Length of the buffer
0172  *
0173  * @retval -1 Invalid node or property
0174  * @retval  Length of property on successful operation
0175  */
0176 ssize_t rtems_ofw_get_enc_prop(
0177   phandle_t    node,
0178   const char  *prop,
0179   pcell_t     *buf,
0180   size_t       len
0181 );
0182
0183 /**
0184  * @brief Checks if the property @a propname is present in @a node.
0185  *
0186  * @param[in] node Node offset
0187  * @param[in] propname Property name
0188  *
0189  *  @retval  0 Property not present.
0190  *  @retval  1 Property is present.
0191  */
0192 int rtems_ofw_has_prop(
0193   phandle_t    node,
0194   const char  *propname
0195 );
0196
0197 /**
0198  * @brief Searches for property @a propname in @a node.
0199  *
0200  * Searches the node and its parent recursively for the property and fills the
0201  * buffer with the first found value.
0202  *
0203  * @param[in] node Node offset
0204  * @param[in] propname Property name
0205  * @param[out] buf The property value gets stored in this buffer (Pre-allocated)
0206  * @param[in] len Length of the buffer
0207  *
0208  * @retval  Length of the property if property is found.
0209  * @retval  -1 Property is not found.
0210  */
0211 ssize_t rtems_ofw_search_prop(
0212   phandle_t    node,
0213   const char  *propname,
0214   void        *buf,
0215   size_t       len
0216 );
0217
0218 /**
0219  * @brief Searches for property @a propname in @a node.
0220  *
0221  * Searches the node and its parent recursively for the property and fills the
0222  * buffer with the first value found after converting it to the endianness of
0223  * the host.
0224  *
0225  * @param[in] node Node offset
0226  * @param[in] propname Property name
0227  * @param[out] buf The property value gets stored in this buffer(Pre-allocated)
0228  * after converted to the host's endianness
0229  * @param[in] len Length of the buffer
0230  *
0231  * @retval  Length of the property if property is found.
0232  * @retval  -1 Property is not found.
0233  */
0234 ssize_t rtems_ofw_search_enc_prop(
0235   phandle_t    node,
0236   const char  *propname,
0237   pcell_t     *buf,
0238   size_t       len
0239 );
0240
0241 /**
0242  * @brief Gets the value of property mentioned in @a propname.
0243  *
0244  * Same as rtems_ofw_getprop, but the @a buf is allocated in this routine and
0245  * the user is responsible for freeing it.
0246  *
0247  * @param[in] node Node offset
0248  * @param[in] propname Property name
0249  * @param[out] buf The buffer is allocated in this routine and user is
0250  * responsible for freeing.
0251  *
0252  * @retval  -1 Property is not found.
0253  * @retval  Length of the property if property is found.
0254  */
0255 ssize_t rtems_ofw_get_prop_alloc(
0256   phandle_t    node,
0257   const char  *propname,
0258   void       **buf
0259 );
0260
0261 /**
0262  * @brief Gets multiple values of the property @a propname.
0263  *
0264  * Same as rtems_ofw_getprop_alloc but it can read properties with multiple
0265  * values.
0266  * For eg: reg = <0x1000 0x10 0x2000 0x20>
0267  *
0268  * @param[in] node Node offset
0269  * @param[in] propname Property name
0270  * @param[in] elsz Size of the single value
0271  * @param[out] buf The buffer is allocated in this routine and user is
0272  * responsible for freeing.
0273  *
0274  * @retval  -1 Property is not found.
0275  * @retval   Number of values read.
0276  */
0277 ssize_t rtems_ofw_get_prop_alloc_multi(
0278   phandle_t    node,
0279   const char  *propname,
0280   int          elsz,
0281   void       **buf
0282 );
0283
0284 /**
0285  * @brief Gets the value of property mentioned in @a propname.
0286  *
0287  * Same as rtems_ofw_getprop_alloc but the value stored in the buffer is
0288  * converted into the host's endianness.
0289  *
0290  * @param[in] node Node offset
0291  * @param[in] propname Property name
0292  * @param[out] buf The buffer is allocated in this routine and user is
0293  * responsible for freeing.
0294  *
0295  * @retval  -1 Property is not found.
0296  * @retval  Length of the property if property is found.
0297  */
0298 ssize_t rtems_ofw_get_enc_prop_alloc(
0299   phandle_t    node,
0300   const char  *propname,
0301   void       **buf
0302 );
0303
0304 /**
0305  * @brief Gets multiple values of the property @a propname.
0306  *
0307  * Same as rtems_ofw_getprop_alloc_multi but the values stored in the buffer
0308  * are converted to the host's endianness.
0309  *
0310  * @param[in] node Node offset
0311  * @param[in] propname Property name
0312  * @param[in] elsz Size of the single value
0313  * @param[out] buf The buffer is allocated in this routine and user is
0314  * responsible for freeing.
0315  *
0316  * @retval  -1 Property is not found.
0317  * @retval   Number of values read.
0318  */
0319 ssize_t rtems_ofw_get_enc_prop_alloc_multi(
0320   phandle_t     node,
0321   const char   *propname,
0322   int           elsz,
0323   void        **buf
0324 );
0325
0326 /**
0327  * @brief Free's the buffers allocated by the rtems_ofw_*_alloc functions.
0328  *
0329  * @param[in] buf Buffer to be freed
0330  */
0331 void rtems_ofw_free(
0332   void   *buf
0333 );
0334
0335 /**
0336  * @brief Finds the next property of @a node.
0337  *
0338  * Finds the next property of the node and when @a propname is NULL it returns
0339  * the value in the first property.
0340  *
0341  * @param[in] node Node offset
0342  * @param[in] previous Previous property name
0343  * @param[out] buf The value of the next property gets stored in this buffer
0344  * (Pre-allocated)
0345  * @param[in] len Length of the buffer
0346  *
0347  * @retval  -1 node or previous property does not exist
0348  * @retval   0 no more properties
0349  * @retval   1 success
0350  */
0351 int rtems_ofw_next_prop(
0352   phandle_t    node,
0353   const char  *previous,
0354   char        *buf,
0355   size_t       len
0356 );
0357
0358 /**
0359  * @brief Sets the property @name of @a node to @a buf.
0360  *
0361  * @param[in] node Node offset
0362  * @param[in] name Property name
0363  * @param[in] buf Buffer contains the value to be set.
0364  * @param[in] len Length of the buffer
0365  *
0366  * @retval  -1 node does not exist
0367  * @retval   0 on success
0368  * @retval   libFDT error codes on unsuccessful setting operation
0369  */
0370 int rtems_ofw_set_prop(
0371   phandle_t    node,
0372   const char  *name,
0373   const void  *buf,
0374   size_t       len
0375 );
0376
0377 /**
0378  * @brief Converts a device specifier to a fully qualified path name.
0379  *
0380  * @param[in] dev device specifier
0381  * @param[out] buf The path is filled into the buffer(Pre-allocated)
0382  * @param[in] length of the buffer
0383  *
0384  * @retval  -1 always. Unimplemented.
0385  */
0386 ssize_t rtems_ofw_canon(
0387   const char  *dev,
0388   char        *buf,
0389   size_t       len
0390 );
0391
0392 /**
0393  * @brief Finds the node at the given path
0394  *
0395  * @param[in] path to the node from root
0396  *
0397  * @retval  -1 node does not exist
0398  * @retval   node handle on success
0399  */
0400 phandle_t rtems_ofw_find_device(
0401   const char  *path
0402 );
0403
0404 /**
0405  * @brief This routine converts effective phandle @a xref to node offset.
0406  *
0407  * @param[in] xref Node phandle
0408  *
0409  * @retval Node offset on success
0410  * @retval Node phandle on failure
0411  */
0412 phandle_t rtems_ofw_node_from_xref(
0413   phandle_t   xref
0414 );
0415
0416 /**
0417  * @brief This routine converts node offset to effective phandle of @a node.
0418  *
0419  * @retval Node phandle on success
0420  * @retval Node offset on failure
0421  */
0422 phandle_t rtems_ofw_xref_from_node(
0423   phandle_t   node
0424 );
0425
0426 /*
0427  * instance handles(ihandle_t) as same as phandles in the FDT implementation
0428  * of OF interface.
0429  */
0430
0431 /**
0432  * @brief Converts @a instance handle to phandle.
0433  *
0434  * instance are same as node offsets in FDT.
0435  *
0436  * @param[in] instance Node offset
0437  *
0438  * @retval phandle of node on success.
0439  * @retval instance of node on failure.
0440  */
0441 phandle_t rtems_ofw_instance_to_package(
0442   ihandle_t   instance
0443 );
0444
0445 /**
0446  * @brief Find the node's path from phandle.
0447  *
0448  * @param[in] node Node offset
0449  * @param[out] buf Path is filled into this buffer(Pre-allocated).
0450  * @param[in] len Length of the buffer.
0451  *
0452  * @retval -1 always. Unimplemented.
0453  */
0454 ssize_t rtems_ofw_package_to_path(
0455   phandle_t   node,
0456   char       *buf,
0457   size_t      len
0458 );
0459
0460 /**
0461  * @brief Find the node's path from ihandle.
0462  *
0463  * @param[in] instance Node offset
0464  * @param[out] buf Path is filled into this buffer(Pre-allocated).
0465  * @param[in] len Length of the buffer.
0466  *
0467  * @retval -1 always. Unimplemented.
0468  */
0469 ssize_t rtems_ofw_instance_to_path(
0470   ihandle_t  instance,
0471   char      *buf,
0472   size_t     len
0473 );
0474
0475 /**
0476  * @brief Queries the node's reg value.
0477  *
0478  * This routine fills the buffer @a buf with the values in reg property of node
0479  * @a node. It reads all the values of the property and fills the buffer to max
0480  * size.
0481  * This routine is local to RTEMS OFW and does not have an corresponding
0482  * FreeBSD OFW pair.
0483  *
0484  * @param[in] node Node offset
0485  * @param[out] buf Register values are stored in this buffer(Pre-allocated).
0486  * @param[in] size Length of the buffer.
0487  *
0488  * @retval -1 If reg property is missing.
0489  * @retval  Length of the reg property in bytes.
0490  */
0491 int rtems_ofw_get_reg(
0492   phandle_t              node,
0493   rtems_ofw_memory_area *buf,
0494   size_t                 size
0495 );
0496
0497 /**
0498  * @brief Queries the node's interrupt value.
0499  *
0500  * This routine fills the buffer @a buf with the interrupt number. In case of
0501  * multiple numbers it fills the buffer to its full extent.
0502  * This routine is local to RTEMS OFW and does not have an corresponding
0503  * FreeBSD OFW pair.
0504  *
0505  * @param[in] node Node offset
0506  * @param[out] buf Interrupt values are stored in this buffer(Pre-allocated).
0507  * @param[in] size Length of the buffer.
0508  *
0509  * @retval -1 If interrupts property is missing.
0510  * @retval  The number of interrupt numbers read.
0511  */
0512 int rtems_ofw_get_interrupts(
0513   phandle_t            node,
0514   rtems_vector_number *buf,
0515   size_t               size
0516 );
0517
0518 /**
0519  * @brief Queries the node's status.
0520  *
0521  * This routine is local to RTEMS OFW and does not have an corresponding
0522  * FreeBSD OFW pair.
0523  *
0524  * @param[in] node Node offset
0525  *
0526  * @retval true  Status is OK or empty.
0527  * @retval false Status is not OK or missing.
0528  */
0529 bool rtems_ofw_node_status( phandle_t node );
0530
0531 /**
0532  * @brief Gets node phandle from compatible property.
0533  *
0534  * This routine is local to RTEMS OFW and does not have an corresponding
0535  * FreeBSD OFW pair.
0536  *
0537  * @param[in] compat Compatible string
0538  *
0539  * @retval 0 Node with @a compat as compatible string not found
0540  * @retval Node phandle on success.
0541  */
0542 phandle_t rtems_ofw_find_device_by_compat( const char *compat );
0543
0544 /**
0545  * @brief check a nodes compatible property.
0546  *
0547  * This routine is local to RTEMS OFW and does not have an corresponding
0548  * FreeBSD OFW pair.
0549  *
0550  * Return true if @a compat equals @a node compatible property
0551  *
0552  * @param[in] node phandle of node
0553  * @param[in] compat Compatible string
0554  *
0555  * @retval 1 If node contains the @a compat as a element in compatible
0556  * property.
0557  * @retval 0 Otherwise.
0558  */
0559 bool rtems_ofw_is_node_compatible( phandle_t node, const char *compat );
0560
0561 #ifdef __cplusplus
0562 }
0563 #endif
0564
0565 #endif /* _OFW_H */