include/fvid2_graph.h

   1 /*
   2  *  Copyright (c) Texas Instruments Incorporated 2018
   3  *
   4  *  Redistribution and use in source and binary forms, with or without
   5  *  modification, are permitted provided that the following conditions
   6  *  are met:
   7  *
   8  *    Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  *
  11  *    Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the
  14  *    distribution.
  15  *
  16  *    Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 /**
  34  *  \file fvid2_graph.h
  35  *
  36  *  \brief FVID2 Graph interface file.
  37  */
  38
  39 #ifndef FVID2_GRAPH_H_
  40 #define FVID2_GRAPH_H_
  41
  42 /* ========================================================================== */
  43 /*                             Include Files                                  */
  44 /* ========================================================================== */
  45
  46 #include <ti/drv/fvid2/fvid2.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /* ========================================================================== */
  53 /*                           Macros & Typedefs                                */
  54 /* ========================================================================== */
  55
  56 /**
  57  *  \brief Graph Alignment
  58  */
  59 #define FVID2_GRAPH_DEF_ALIGN        ((uint32_t) 16U)
  60
  61 /**
  62  *  \brief Invalid Node Id
  63  */
  64 #define FVID2_GRAPH_INVALID_NODE_ID  ((uint32_t) 0x0U)
  65
  66 /**
  67  *  \brief Maximum number of nodes
  68  */
  69 #define FVID2_GRAPH_MAX_NODES        ((uint32_t) 25U)
  70
  71 /**
  72  *  \brief Maximum number of paths
  73  */
  74 #define FVID2_GRAPH_MAX_NUM_PATHS    ((uint32_t) 40U)
  75
  76 /**
  77  *  \anchor Fvid2_GraphNodeMode
  78  *  \name   Mode of the node
  79  *
  80  *  @{
  81  */
  82 /** \brief  Disable mode */
  83 #define FVID2_GRAPH_NODE_MODE_DISABLE            ((uint32_t) 0x0U)
  84 /** \brief Enable mode */
  85 #define FVID2_GRAPH_NODE_MODE_ENABLE             ((uint32_t) 0x1U)
  86 /** \brief Check Mode */
  87 #define FVID2_GRAPH_NODE_MODE_CHECK              ((uint32_t) 0x2U)
  88 /* @} */
  89
  90 /**
  91  *  \anchor Fvid2_GraphNodeType
  92  *  \name   Node Type
  93  *
  94  *  @{
  95  */
  96 /** \brief Node type is dummy */
  97 #define FVID2_GRAPH_NODE_TYPE_DUMMY            ((uint32_t) 0x0U)
  98 /** \brief Node type is DSS Pipe */
  99 #define FVID2_GRAPH_NODE_TYPE_DSS_PIPE         ((uint32_t) 0x1U)
 100 /** \brief Node type is DSS Overlay */
 101 #define FVID2_GRAPH_NODE_TYPE_DSS_OVERLAY      ((uint32_t) 0x2U)
 102 /** \brief Node type is DSS Video Port */
 103 #define FVID2_GRAPH_NODE_TYPE_DSS_VP           ((uint32_t) 0x3U)
 104 /** \brief Node type is DSS Output */
 105 #define FVID2_GRAPH_NODE_TYPE_DSS_OUT          ((uint32_t) 0x4U)
 106 /** \brief Maximum Node types */
 107 #define FVID2_GRAPH_NODE_TYPE_MAX              ((uint32_t) 0x5U)
 108 /* @} */
 109
 110 /**
 111  *  \anchor Fvid2_GraphNodeInputNum
 112  *  \name   Number of inputs to a particular node
 113  *
 114  *  @{
 115  */
 116 /** \brief No Input */
 117 #define FVID2_GRAPH_NODE_IN_NONE               ((uint32_t) 0x0U)
 118 /** \brief Single Input */
 119 #define FVID2_GRAPH_NODE_IN_SINGLE             ((uint32_t) 0x1U)
 120 /** \brief Multiple Inputs */
 121 #define FVID2_GRAPH_NODE_IN_MULTI              ((uint32_t) 0x2U)
 122 /* @} */
 123
 124 /**
 125  *  \anchor Fvid2_GraphNodeOutputNum
 126  *  \name   Number of outputs from a particular node
 127  *
 128  *  @{
 129  */
 130 /** \brief No Output */
 131 #define FVID2_GRAPH_NODE_OUT_NONE              ((uint32_t) 0x0U)
 132 /** \brief Single Output */
 133 #define FVID2_GRAPH_NODE_OUT_SINGLE            ((uint32_t) 0x1U)
 134 /** \brief Multiple Outputs */
 135 #define FVID2_GRAPH_NODE_OUT_MULTI             ((uint32_t) 0x2U)
 136 /* @} */
 137
 138 /* ========================================================================== */
 139 /*                         Structure Declarations                             */
 140 /* ========================================================================== */
 141
 142 /** \brief Forward declaration for Node Information. */
 143 typedef struct Fvid2_GraphNodeInfo_t Fvid2_GraphNodeInfo;
 144
 145 /**
 146  *  \brief Structure containing Node Set Configuration.
 147  */
 148 typedef struct
 149 {
 150     uint32_t numNodes;
 151     /**< Number of input/output nodes */
 152     Fvid2_GraphNodeInfo *node[FVID2_GRAPH_MAX_NUM_PATHS];
 153     /**< Pointer to the input/output node */
 154     uint32_t isEnabled[FVID2_GRAPH_MAX_NUM_PATHS];
 155     /**< Flag to indicate whether input/output is enabled or not. */
 156 } Fvid2_GraphNodeSet;
 157
 158 /**
 159  *  \brief Structure containing Node Information.
 160  */
 161 struct Fvid2_GraphNodeInfo_t
 162 {
 163     uint32_t nodeId;
 164     /**< Node Id */
 165     uint32_t nodeInNum;
 166     /**< Number of inputs to this particular node. Refer \ref
 167      *   Fvid2_GraphNodeInputNum for values */
 168     uint32_t nodeOutNum;
 169     /**< Number of outputs from this particular node. Refer \ref
 170      *   Fvid2_GraphNodeOutputNum for values */
 171     uint32_t nodeType;
 172     /**< Node type for the particular node. Refer \ref Fvid2_GraphNodeType
 173      *   for values */
 174     uint32_t isDummy;
 175     /**< Variable defining whether node type is dummy */
 176     uint32_t inUse;
 177     /**< Variable defining whether node is used in the present context */
 178     Fvid2_GraphNodeSet inputNodeSet;
 179     /**< Input Node Set */
 180     Fvid2_GraphNodeSet outputNodeSet;
 181     /**< Output Node Set */
 182 };
 183
 184 /**
 185  *  \brief Structure containing Node List
 186  */
 187 typedef struct
 188 {
 189     uint32_t numNodes;
 190     /**< Number of nodes */
 191     Fvid2_GraphNodeInfo *list;
 192     /**< Pointer to node list */
 193 } Fvid2_GraphNodeList;
 194
 195 /**
 196  * \brief Structure containing edge information. Edge is a connection
 197  *  between two nodes i.e. two modules. Video Hardware can be represented
 198  *  by a graph, where each module is node and edge is present between two
 199  *  nodes if they are connected.
 200  */
 201 typedef struct
 202 {
 203     uint32_t startNode;
 204     /**< Starting node of the edge */
 205     uint32_t endNode;
 206     /**< End node of the edge */
 207 } Fvid2_GraphEdgeInfo;
 208
 209 /**
 210  *  \brief Structure containing Edge List.
 211  */
 212 typedef struct
 213 {
 214     uint32_t numEdges;
 215     /**< Number of the edge */
 216     Fvid2_GraphEdgeInfo *list;
 217     /**< Edge list */
 218 } Fvid2_GraphEdgeList;
 219
 220 /**
 221  *  \brief Structure containing Graph information.
 222  */
 223 typedef struct
 224 {
 225     Fvid2_GraphNodeList *nodeList;
 226     /**< Node list of the graph */
 227     Fvid2_GraphEdgeList *edgeList;
 228     /**< Edge list of the graph */
 229 } Fvid2_GraphInfo;
 230
 231 /* ========================================================================== */
 232 /*                          Function Declarations                             */
 233 /* ========================================================================== */
 234
 235 /**
 236  *  \brief Initialize the fvid2 graph.
 237  *
 238  *  \param inNodeList   Pointer to list of nodes.
 239  *                      Refer #Fvid2_GraphNodeList for details
 240  *  \param inEdgeList   Pointer to list of edges.
 241  *                      Refer #Fvid2_GraphEdgeList for details
 242  *  \param graphHandle  Graph handle.
 243  *
 244  *  \return Graph Handle
 245  */
 246 Fvid2_GraphInfo *Fvid2_graphInit(const Fvid2_GraphNodeList *inNodeList,
 247                                  const Fvid2_GraphEdgeList *inEdgeList,
 248                                  Fvid2_GraphInfo *graphHandle);
 249
 250 /**
 251  *  \brief Un-initialize the fvid2 graph.
 252  *
 253  *  \param graphHandle  Graph handle.
 254  *
 255  *  \return status
 256  */
 257 int32_t Fvid2_graphDeInit(Fvid2_GraphInfo *graphHandle);
 258
 259 /**
 260  *  \brief Function to get the pointer to node for the given index.
 261  *
 262  *  \param nodeList     Pointer to list of nodes.
 263  *                      Refer #Fvid2_GraphNodeList for details
 264  *  \param nodeIndex    Node index.
 265  *
 266  *  \return Node information.
 267  */
 268 Fvid2_GraphNodeInfo *Fvid2_graphGetNodeInfo(const Fvid2_GraphNodeList *nodeList,
 269                                             uint32_t nodeIndex);
 270
 271 /**
 272  *  \brief Function to check if the particular input node is available.
 273  *
 274  *  \param nodeList     Pointer to list of nodes.
 275  *                      Refer #Fvid2_GraphNodeList for details
 276  *  \param nodeId       Node Id
 277  *
 278  *  \return TRUE if available else FALSE.
 279  */
 280 uint32_t Fvid2_graphIsNodeInputAvailable(const Fvid2_GraphNodeList *nodeList,
 281                                          uint32_t nodeId);
 282
 283 /**
 284  *  \brief Function to check if the particular output node is available.
 285  *
 286  *  \param nodeList     Pointer to list of nodes.
 287  *                      Refer #Fvid2_GraphNodeList for details
 288  *  \param nodeId       Node Id
 289  *
 290  *  \return TRUE if available else FALSE.
 291  */
 292 uint32_t Fvid2_graphIsNodeOutputAvailable(const Fvid2_GraphNodeList *nodeList,
 293                                           uint32_t nodeId);
 294
 295 /**
 296  *  \brief This function allocates nodes within the graph by enabling specified
 297  *         edges. To enable an edge, it enables output of source node and
 298  *         enables input of the target node.
 299  *
 300  *  \param nodeList       Pointer to list of nodes.
 301  *                        Refer #Fvid2_GraphNodeList for details
 302  *  \param edgeList       Pointer to list of edges.
 303  *                        Refer #Fvid2_GraphEdgeList for details
 304  *  \param graphNodeMode  Node mode. Refer \ref Fvid2_GraphNodeMode for values.
 305  *
 306  *  \return Returns error if a node is already active.
 307  */
 308 int32_t Fvid2_graphAllocNodes(const Fvid2_GraphNodeList *nodeList,
 309                               const Fvid2_GraphEdgeList *edgeList,
 310                               uint32_t graphNodeMode);
 311
 312 /**
 313  *  \brief This function gets a list of valid nodes in an edge list and
 314  *         also enables the input in each entry.
 315  *
 316  *  \param inNodeList     Pointer to list of nodes that are input to this API.
 317  *                        Refer #Fvid2_GraphNodeList for details
 318  *  \param inEdgeList     Pointer to list of edges that are input to this API.
 319  *                        Refer #Fvid2_GraphEdgeList for details
 320  *  \param outNodeList    Pointer to list of nodes that are output from this API
 321  *                        Refer #Fvid2_GraphNodeList for details
 322  *  \param outEdgeList    Pointer to list of edges that are output from this API
 323  *                        Refer #Fvid2_GraphEdgeList for details
 324  *  \param maxOutNodeCnt  Output node count
 325  *  \param maxOutEdgeCnt  Output edge count
 326  *
 327  *  \return status
 328  */
 329 int32_t Fvid2_graphGetPath(const Fvid2_GraphNodeList *inNodeList,
 330                            const Fvid2_GraphEdgeList *inEdgeList,
 331                            Fvid2_GraphNodeList *outNodeList,
 332                            Fvid2_GraphEdgeList *outEdgeList,
 333                            uint32_t maxOutNodeCnt,
 334                            uint32_t maxOutEdgeCnt);
 335
 336 /**
 337  *  \brief This function sets graph nodes and edges to free.
 338  *
 339  *  \param nodeList   Pointer to list of nodes.
 340  *                    Refer #Fvid2_GraphNodeList for details
 341  *  \param edgeList   Pointer to list of edges.
 342  *                    Refer #Fvid2_GraphEdgeList for details
 343  *
 344  *  \return status
 345  */
 346 int32_t Fvid2_graphFreePath(Fvid2_GraphNodeList *nodeList,
 347                             Fvid2_GraphEdgeList *edgeList);
 348
 349 /**
 350  *  \brief This function finds the enabled node within the array.
 351  *
 352  *  \param array  Pointer to list of nodes.
 353  *  \param size   Size of array.
 354  *
 355  *  \return Index of enabled node.
 356  */
 357 int32_t Fvid2_graphGetEnabledIndex(const uint32_t *array, uint32_t size);
 358
 359 /**
 360  *  \brief This function adds an edge between two nodes.
 361  *
 362  *  \param edge        Pointer to edge. Refer #Fvid2_GraphEdgeInfo for details
 363  *  \param startNode   Start Node
 364  *  \param endNode     End Node
 365  *
 366  *  \return None
 367  */
 368 void Fvid2_graphAddEdge(Fvid2_GraphEdgeInfo *edge,
 369                         uint32_t startNode,
 370                         uint32_t endNode);
 371
 372 #ifdef __cplusplus /* If this is a C++ compiler, end C linkage */
 373 }
 374 #endif
 375
 376 #endif /* FVID2_GRAPH_H_ */