/* SPDX-License-Identifier: BSD-2-Clause */ /** * @file * * @ingroup ofw * * RTEMS FDT implementation of OpenFirmWare Interface. * * RTEMS OFW is a FDT only implementation of the OpenFirmWare interface. * This API is created to be compatible with FreeBSD OpenFirmWare interface. * The main intention is to make porting of FreeBSD drivers to RTEMS easier. */ /* * Copyright (C) 2020 Niteesh Babu G S * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _OFW_H #define _OFW_H #ifdef __cplusplus extern "C" { #endif #include #include #include /** * Represents a node in the device tree. The offset from fdtp to node is used * instead of fdt offset to make sure this is compatible with OF interface in * FreeBSD. */ typedef uint32_t phandle_t; /** * Represents the effective phandle of the node. */ typedef uint32_t ihandle_t; /** * Represents the data type of the buffer. */ typedef uint32_t pcell_t; /** * @struct rtems_ofw_memory_area * * This is used to represent elements(FDT properties) that define * region of memory address. */ typedef struct { /** The start address of the memory region. */ uint32_t start; /** The size of the memory region. */ uint32_t size; } rtems_ofw_memory_area; /** * @struct rtems_ofw_ranges * * This is used to represent the ranges property in the device tree. */ typedef struct { /** The physical address within the child bus address space */ uint32_t child_bus; /** The physical address within the parent bus address space */ uint32_t parent_bus; /** The size of the range in the child’s address space */ uint32_t size; } rtems_ofw_ranges; /** * @brief Gets the node that is next to @a node. * * @param[in] node Node offset * * @retval Peer node offset Successful operation. * @retval 0 No peer node or invalid node handle */ phandle_t rtems_ofw_peer( phandle_t node ); /** * @brief Gets the node that is the child of @a node. * * @param[in] node Node offset * * @retval child node offset Successful operation. * @retval 0 No child node or invalid node handle */ phandle_t rtems_ofw_child( phandle_t node ); /** * @brief Gets the node that is the parent of @a node. * * @param[in] node Node offset * * @retval child node offset Successful operation. * @retval 0 No child node or invalid node handle */ phandle_t rtems_ofw_parent( phandle_t node ); /** * @brief Gets the length of the property mentioned in @a propname. * * @param[in] node Node offset * @param[in] prop Property name * * @retval -1 Invalid node or property * @retval Length of property on successful operation */ ssize_t rtems_ofw_get_prop_len( phandle_t node, const char *propname ); /** * @brief Gets the value of property mentioned in @a propname. * * @param[in] node Node offset * @param[in] prop Property name * @param[out] buf The property value gets stored in this buffer (Pre-allocated) * @param[in] len Length of the buffer * @retval -1 Invalid node or property * @retval Length of property on successful operation */ ssize_t rtems_ofw_get_prop( phandle_t node, const char *propname, void *buf, size_t len ); /** * @brief Gets the value of property mentioned in @a prop. * * Gets the value of property of @a node and converts the value into the host's * endianness. * * @param[in] node Node offset * @param[in] prop Property name * @param[out] buf The property value gets stored in this buffer(Pre-allocated) * after converted to the host's endianness * @param[in] len Length of the buffer * * @retval -1 Invalid node or property * @retval Length of property on successful operation */ ssize_t rtems_ofw_get_enc_prop( phandle_t node, const char *prop, pcell_t *buf, size_t len ); /** * @brief Checks if the property @a propname is present in @a node. * * @param[in] node Node offset * @param[in] propname Property name * * @retval 0 Property not present. * @retval 1 Property is present. */ int rtems_ofw_has_prop( phandle_t node, const char *propname ); /** * @brief Searches for property @a propname in @a node. * * Searches the node and its parent recursively for the property and fills the * buffer with the first found value. * * @param[in] node Node offset * @param[in] propname Property name * @param[out] buf The property value gets stored in this buffer (Pre-allocated) * @param[in] len Length of the buffer * * @retval Length of the property if property is found. * @retval -1 Property is not found. */ ssize_t rtems_ofw_search_prop( phandle_t node, const char *propname, void *buf, size_t len ); /** * @brief Searches for property @a propname in @a node. * * Searches the node and its parent recursively for the property and fills the * buffer with the first value found after converting it to the endianness of * the host. * * @param[in] node Node offset * @param[in] propname Property name * @param[out] buf The property value gets stored in this buffer(Pre-allocated) * after converted to the host's endianness * @param[in] len Length of the buffer * * @retval Length of the property if property is found. * @retval -1 Property is not found. */ ssize_t rtems_ofw_search_enc_prop( phandle_t node, const char *propname, pcell_t *buf, size_t len ); /** * @brief Gets the value of property mentioned in @a propname. * * Same as rtems_ofw_getprop, but the @a buf is allocated in this routine and * the user is responsible for freeing it. * * @param[in] node Node offset * @param[in] propname Property name * @param[out] buf The buffer is allocated in this routine and user is * responsible for freeing. * * @retval -1 Property is not found. * @retval Length of the property if property is found. */ ssize_t rtems_ofw_get_prop_alloc( phandle_t node, const char *propname, void **buf ); /** * @brief Gets multiple values of the property @a propname. * * Same as rtems_ofw_getprop_alloc but it can read properties with multiple * values. * For eg: reg = <0x1000 0x10 0x2000 0x20> * * @param[in] node Node offset * @param[in] propname Property name * @param[in] elsz Size of the single value * @param[out] buf The buffer is allocated in this routine and user is * responsible for freeing. * * @retval -1 Property is not found. * @retval Number of values read. */ ssize_t rtems_ofw_get_prop_alloc_multi( phandle_t node, const char *propname, int elsz, void **buf ); /** * @brief Gets the value of property mentioned in @a propname. * * Same as rtems_ofw_getprop_alloc but the value stored in the buffer is * converted into the host's endianness. * * @param[in] node Node offset * @param[in] propname Property name * @param[out] buf The buffer is allocated in this routine and user is * responsible for freeing. * * @retval -1 Property is not found. * @retval Length of the property if property is found. */ ssize_t rtems_ofw_get_enc_prop_alloc( phandle_t node, const char *propname, void **buf ); /** * @brief Gets multiple values of the property @a propname. * * Same as rtems_ofw_getprop_alloc_multi but the values stored in the buffer * are converted to the host's endianness. * * @param[in] node Node offset * @param[in] propname Property name * @param[in] elsz Size of the single value * @param[out] buf The buffer is allocated in this routine and user is * responsible for freeing. * * @retval -1 Property is not found. * @retval Number of values read. */ ssize_t rtems_ofw_get_enc_prop_alloc_multi( phandle_t node, const char *propname, int elsz, void **buf ); /** * @brief Free's the buffers allocated by the rtems_ofw_*_alloc functions. * * @param[in] buf Buffer to be freed */ void rtems_ofw_free( void *buf ); /** * @brief Finds the next property of @a node. * * Finds the next property of the node and when @a propname is NULL it returns * the value in the first property. * * @param[in] node Node offset * @param[in] previous Previous property name * @param[out] buf The value of the next property gets stored in this buffer * (Pre-allocated) * @param[in] len Length of the buffer * * @retval -1 node or previous property does not exist * @retval 0 no more properties * @retval 1 success */ int rtems_ofw_next_prop( phandle_t node, const char *previous, char *buf, size_t len ); /** * @brief Sets the property @name of @a node to @a buf. * * @param[in] node Node offset * @param[in] name Property name * @param[in] buf Buffer contains the value to be set. * @param[in] len Length of the buffer * * @retval -1 node does not exist * @retval 0 on success * @retval libFDT error codes on unsuccessful setting operation */ int rtems_ofw_set_prop( phandle_t node, const char *name, const void *buf, size_t len ); /** * @brief Converts a device specifier to a fully qualified path name. * * @param[in] dev device specifier * @param[out] buf The path is filled into the buffer(Pre-allocated) * @param[in] length of the buffer * * @retval -1 always. Unimplemented. */ ssize_t rtems_ofw_canon( const char *dev, char *buf, size_t len ); /** * @brief Finds the node at the given path * * @param[in] path to the node from root * * @retval -1 node does not exist * @retval node handle on success */ phandle_t rtems_ofw_find_device( const char *path ); /** * @brief This routine converts effective phandle @a xref to node offset. * * @param[in] xref Node phandle * * @retval Node offset on success * @retval Node phandle on failure */ phandle_t rtems_ofw_node_from_xref( phandle_t xref ); /** * @brief This routine converts node offset to effective phandle of @a node. * * @retval Node phandle on success * @retval Node offset on failure */ phandle_t rtems_ofw_xref_from_node( phandle_t node ); /* * instance handles(ihandle_t) as same as phandles in the FDT implementation * of OF interface. */ /** * @brief Converts @a instance handle to phandle. * * instance are same as node offsets in FDT. * * @param[in] instance Node offset * * @retval phandle of node on success. * @retval instance of node on failure. */ phandle_t rtems_ofw_instance_to_package( ihandle_t instance ); /** * @brief Find the node's path from phandle. * * @param[in] node Node offset * @param[out] buf Path is filled into this buffer(Pre-allocated). * @param[in] len Length of the buffer. * * @retval -1 always. Unimplemented. */ ssize_t rtems_ofw_package_to_path( phandle_t node, char *buf, size_t len ); /** * @brief Find the node's path from ihandle. * * @param[in] instance Node offset * @param[out] buf Path is filled into this buffer(Pre-allocated). * @param[in] len Length of the buffer. * * @retval -1 always. Unimplemented. */ ssize_t rtems_ofw_instance_to_path( ihandle_t instance, char *buf, size_t len ); /** * @brief Queries the node's reg value. * * This routine fills the buffer @a buf with the values in reg property of node * @a node. It reads all the values of the property and fills the buffer to max * size. * This routine is local to RTEMS OFW and does not have an corresponding * FreeBSD OFW pair. * * @param[in] node Node offset * @param[out] buf Register values are stored in this buffer(Pre-allocated). * @param[in] size Length of the buffer. * * @retval -1 If reg property is missing. * @retval Length of the reg property in bytes. */ int rtems_ofw_get_reg( phandle_t node, rtems_ofw_memory_area *buf, size_t size ); /** * @brief Queries the node's interrupt value. * * This routine fills the buffer @a buf with the interrupt number. In case of * multiple numbers it fills the buffer to its full extent. * This routine is local to RTEMS OFW and does not have an corresponding * FreeBSD OFW pair. * * @param[in] node Node offset * @param[out] buf Interrupt values are stored in this buffer(Pre-allocated). * @param[in] size Length of the buffer. * * @retval -1 If interrupts property is missing. * @retval The number of interrupt numbers read. */ int rtems_ofw_get_interrupts( phandle_t node, rtems_vector_number *buf, size_t size ); /** * @brief Queries the node's status. * * This routine is local to RTEMS OFW and does not have an corresponding * FreeBSD OFW pair. * * @param[in] node Node offset * * @retval true Status is OK or empty. * @retval false Status is not OK or missing. */ bool rtems_ofw_node_status( phandle_t node ); /** * @brief Gets node phandle from compatible property. * * This routine is local to RTEMS OFW and does not have an corresponding * FreeBSD OFW pair. * * @param[in] compat Compatible string * * @retval 0 Node with @a compat as compatible string not found * @retval Node phandle on success. */ phandle_t rtems_ofw_find_device_by_compat( const char *compat ); /** * @brief check a nodes compatible property. * * This routine is local to RTEMS OFW and does not have an corresponding * FreeBSD OFW pair. * * Return true if @a compat equals @a node compatible property * * @param[in] node phandle of node * @param[in] compat Compatible string * * @retval 1 If node contains the @a compat as a element in compatible * property. * @retval 0 Otherwise. */ bool rtems_ofw_is_node_compatible( phandle_t node, const char *compat ); #ifdef __cplusplus } #endif #endif /* _OFW_H */