drivers/staging/tidspbridge/include/dspbridge/node.h

   1 /*
   2  * node.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * DSP/BIOS Bridge Node Manager.
   7  *
   8  * Copyright (C) 2005-2006 Texas Instruments, Inc.
   9  *
  10  * This package is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License version 2 as
  12  * published by the Free Software Foundation.
  13  *
  14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17  */
  18
  19 #ifndef NODE_
  20 #define NODE_
  21
  22 #include <dspbridge/procpriv.h>
  23
  24 #include <dspbridge/nodedefs.h>
  25 #include <dspbridge/dispdefs.h>
  26 #include <dspbridge/nldrdefs.h>
  27 #include <dspbridge/drv.h>
  28
  29 /*
  30  *  ======== node_allocate ========
  31  *  Purpose:
  32  *      Allocate GPP resources to manage a node on the DSP.
  33  *  Parameters:
  34  *      hprocessor:         Handle of processor that is allocating the node.
  35  *      pNodeId:            Pointer to a dsp_uuid for the node.
  36  *      pargs:              Optional arguments to be passed to the node.
  37  *      attr_in:            Optional pointer to node attributes (priority,
  38  *                          timeout...)
  39  *      ph_node:             Location to store node handle on output.
  40  *  Returns:
  41  *      0:            Success.
  42  *      -ENOMEM:        Insufficient memory on GPP.
  43  *      -ENOKEY:          Node UUID has not been registered.
  44  *      -ESPIPE:        iAlg functions not found for a DAIS node.
  45  *      -EDOM:         attr_in != NULL and attr_in->prio out of
  46  *                          range.
  47  *      -EPERM:          A failure occured, unable to allocate node.
  48  *      -EBADR:    Proccessor is not in the running state.
  49  *  Requires:
  50  *      node_init(void) called.
  51  *      hprocessor != NULL.
  52  *      pNodeId != NULL.
  53  *      ph_node != NULL.
  54  *  Ensures:
  55  *      0:            IsValidNode(*ph_node).
  56  *      error:              *ph_node == NULL.
  57  */
  58 extern int node_allocate(struct proc_object *hprocessor,
  59                                 IN CONST struct dsp_uuid *pNodeId,
  60                                 OPTIONAL IN CONST struct dsp_cbdata
  61                                 *pargs, OPTIONAL IN CONST struct dsp_nodeattrin
  62                                 *attr_in,
  63                                 OUT struct node_object **ph_node,
  64                                 struct process_context *pr_ctxt);
  65
  66 /*
  67  *  ======== node_alloc_msg_buf ========
  68  *  Purpose:
  69  *      Allocate and Prepare a buffer whose descriptor will be passed to a
  70  *      Node within a (dsp_msg)message
  71  *  Parameters:
  72  *      hnode:          The node handle.
  73  *      usize:          The size of the buffer to be allocated.
  74  *      pattr:          Pointer to a dsp_bufferattr structure.
  75  *      pbuffer:        Location to store the address of the allocated
  76  *                      buffer on output.
  77  *  Returns:
  78  *      0:        Success.
  79  *      -EFAULT:    Invalid node handle.
  80  *      -ENOMEM:    Insufficent memory.
  81  *      -EPERM:      General Failure.
  82  *      -EINVAL:      Invalid Size.
  83  *  Requires:
  84  *      node_init(void) called.
  85  *      pbuffer != NULL.
  86  *  Ensures:
  87  */
  88 extern int node_alloc_msg_buf(struct node_object *hnode,
  89                                      u32 usize, OPTIONAL struct dsp_bufferattr
  90                                      *pattr, OUT u8 **pbuffer);
  91
  92 /*
  93  *  ======== node_change_priority ========
  94  *  Purpose:
  95  *      Change the priority of an allocated node.
  96  *  Parameters:
  97  *      hnode:              Node handle returned from node_allocate.
  98  *      prio:          New priority level to set node's priority to.
  99  *  Returns:
 100  *      0:            Success.
 101  *      -EFAULT:        Invalid hnode.
 102  *      -EDOM:         prio is out of range.
 103  *      -EPERM: The specified node is not a task node.
 104  *              Unable to change node's runtime priority level.
 105  *      -EBADR:    Node is not in the NODE_ALLOCATED, NODE_PAUSED,
 106  *                          or NODE_RUNNING state.
 107  *      -ETIME:       A timeout occurred before the DSP responded.
 108  *  Requires:
 109  *      node_init(void) called.
 110  *  Ensures:
 111  *      0 && (Node's current priority == prio)
 112  */
 113 extern int node_change_priority(struct node_object *hnode, s32 prio);
 114
 115 /*
 116  *  ======== node_close_orphans ========
 117  *  Purpose:
 118  *      Delete all nodes whose owning processor is being destroyed.
 119  *  Parameters:
 120  *      hnode_mgr:       Node manager object.
 121  *      proc:          Handle to processor object being destroyed.
 122  *  Returns:
 123  *      0:        Success.
 124  *      -EPERM:      Unable to delete all nodes belonging to proc.
 125  *  Requires:
 126  *      Valid hnode_mgr.
 127  *      proc != NULL.
 128  *  Ensures:
 129  */
 130 extern int node_close_orphans(struct node_mgr *hnode_mgr,
 131                                      struct proc_object *proc);
 132
 133 /*
 134  *  ======== node_connect ========
 135  *  Purpose:
 136  *      Connect two nodes on the DSP, or a node on the DSP to the GPP. In the
 137  *      case that the connnection is being made between a node on the DSP and
 138  *      the GPP, one of the node handles (either node1 or node2) must be
 139  *      the constant NODE_HGPPNODE.
 140  *  Parameters:
 141  *      node1:         Handle of first node to connect to second node. If
 142  *                      this is a connection from the GPP to node2, node1
 143  *                      must be the constant NODE_HGPPNODE. Otherwise, node1
 144  *                      must be a node handle returned from a successful call
 145  *                      to Node_Allocate().
 146  *      node2:         Handle of second node. Must be either NODE_HGPPNODE
 147  *                      if this is a connection from DSP node to GPP, or a
 148  *                      node handle returned from a successful call to
 149  *                      node_allocate().
 150  *      uStream1:       Output stream index on first node, to be connected
 151  *                      to second node's input stream. Value must range from
 152  *                      0 <= uStream1 < number of output streams.
 153  *      uStream2:       Input stream index on second node. Value must range
 154  *                      from 0 <= uStream2 < number of input streams.
 155  *      pattrs:         Stream attributes (NULL ==> use defaults).
 156  *      conn_param:     A pointer to a dsp_cbdata structure that defines
 157  *                      connection parameter for device nodes to pass to DSP
 158  *                      side.
 159  *                      If the value of this parameter is NULL, then this API
 160  *                      behaves like DSPNode_Connect. This parameter will have
 161  *                      length of the string and the null terminated string in
 162  *                      dsp_cbdata struct. This can be extended in future tp
 163  *                      pass binary data.
 164  *  Returns:
 165  *      0:                Success.
 166  *      -EFAULT:            Invalid node1 or node2.
 167  *      -ENOMEM:            Insufficient host memory.
 168  *      -EINVAL:             A stream index parameter is invalid.
 169  *      -EISCONN:  A connection already exists for one of the
 170  *                              indices uStream1 or uStream2.
 171  *      -EBADR:        Either node1 or node2 is not in the
 172  *                              NODE_ALLOCATED state.
 173  *      -ECONNREFUSED: No more connections available.
 174  *      -EPERM:              Attempt to make an illegal connection (eg,
 175  *                              Device node to device node, or device node to
 176  *                              GPP), the two nodes are on different DSPs.
 177  *  Requires:
 178  *      node_init(void) called.
 179  *  Ensures:
 180  */
 181 extern int node_connect(struct node_object *node1,
 182                                u32 uStream1,
 183                                struct node_object *node2,
 184                                u32 uStream2,
 185                                OPTIONAL IN struct dsp_strmattr *pattrs,
 186                                OPTIONAL IN struct dsp_cbdata
 187                                *conn_param);
 188
 189 /*
 190  *  ======== node_create ========
 191  *  Purpose:
 192  *      Create a node on the DSP by remotely calling the node's create
 193  *      function. If necessary, load code that contains the node's create
 194  *      function.
 195  *  Parameters:
 196  *      hnode:              Node handle returned from node_allocate().
 197  *  Returns:
 198  *      0:            Success.
 199  *      -EFAULT:        Invalid hnode.
 200  *      -ESPIPE:        Create function not found in the COFF file.
 201  *      -EBADR:    Node is not in the NODE_ALLOCATED state.
 202  *      -ENOMEM:        Memory allocation failure on the DSP.
 203  *      -ETIME:       A timeout occurred before the DSP responded.
 204  *      -EPERM:          A failure occurred, unable to create node.
 205  *  Requires:
 206  *      node_init(void) called.
 207  *  Ensures:
 208  */
 209 extern int node_create(struct node_object *hnode);
 210
 211 /*
 212  *  ======== node_create_mgr ========
 213  *  Purpose:
 214  *      Create a NODE Manager object. This object handles the creation,
 215  *      deletion, and execution of nodes on the DSP target. The NODE Manager
 216  *      also maintains a pipe map of used and available node connections.
 217  *      Each DEV object should have exactly one NODE Manager object.
 218  *
 219  *  Parameters:
 220  *      phNodeMgr:      Location to store node manager handle on output.
 221  *      hdev_obj:     Device for this processor.
 222  *  Returns:
 223  *      0:        Success;
 224  *      -ENOMEM:    Insufficient memory for requested resources.
 225  *      -EPERM:      General failure.
 226  *  Requires:
 227  *      node_init(void) called.
 228  *      phNodeMgr != NULL.
 229  *      hdev_obj != NULL.
 230  *  Ensures:
 231  *      0:        Valide *phNodeMgr.
 232  *      error:          *phNodeMgr == NULL.
 233  */
 234 extern int node_create_mgr(OUT struct node_mgr **phNodeMgr,
 235                                   struct dev_object *hdev_obj);
 236
 237 /*
 238  *  ======== node_delete ========
 239  *  Purpose:
 240  *      Delete resources allocated in node_allocate(). If the node was
 241  *      created, delete the node on the DSP by remotely calling the node's
 242  *      delete function. Loads the node's delete function if necessary.
 243  *      GPP side resources are freed after node's delete function returns.
 244  *  Parameters:
 245  *      hnode:              Node handle returned from node_allocate().
 246  *  Returns:
 247  *      0:            Success.
 248  *      -EFAULT:        Invalid hnode.
 249  *      -ETIME:       A timeout occurred before the DSP responded.
 250  *      -EPERM:          A failure occurred in deleting the node.
 251  *      -ESPIPE:        Delete function not found in the COFF file.
 252  *  Requires:
 253  *      node_init(void) called.
 254  *  Ensures:
 255  *      0:            hnode is invalid.
 256  */
 257 extern int node_delete(struct node_object *hnode,
 258                               struct process_context *pr_ctxt);
 259
 260 /*
 261  *  ======== node_delete_mgr ========
 262  *  Purpose:
 263  *      Delete the NODE Manager.
 264  *  Parameters:
 265  *      hnode_mgr:       Node manager object.
 266  *  Returns:
 267  *      0:        Success.
 268  *  Requires:
 269  *      node_init(void) called.
 270  *      Valid hnode_mgr.
 271  *  Ensures:
 272  */
 273 extern int node_delete_mgr(struct node_mgr *hnode_mgr);
 274
 275 /*
 276  *  ======== node_enum_nodes ========
 277  *  Purpose:
 278  *      Enumerate the nodes currently allocated for the DSP.
 279  *  Parameters:
 280  *      hnode_mgr:       Node manager returned from node_create_mgr().
 281  *      node_tab:       Array to copy node handles into.
 282  *      node_tab_size:   Number of handles that can be written to node_tab.
 283  *      pu_num_nodes:     Location where number of node handles written to
 284  *                      node_tab will be written.
 285  *      pu_allocated:    Location to write total number of allocated nodes.
 286  *  Returns:
 287  *      0:        Success.
 288  *      -EINVAL:      node_tab is too small to hold all node handles.
 289  *  Requires:
 290  *      Valid hnode_mgr.
 291  *      node_tab != NULL || node_tab_size == 0.
 292  *      pu_num_nodes != NULL.
 293  *      pu_allocated != NULL.
 294  *  Ensures:
 295  *      - (-EINVAL && *pu_num_nodes == 0)
 296  *      - || (0 && *pu_num_nodes <= node_tab_size)  &&
 297  *        (*pu_allocated == *pu_num_nodes)
 298  */
 299 extern int node_enum_nodes(struct node_mgr *hnode_mgr,
 300                                   void **node_tab,
 301                                   u32 node_tab_size,
 302                                   OUT u32 *pu_num_nodes,
 303                                   OUT u32 *pu_allocated);
 304
 305 /*
 306  *  ======== node_exit ========
 307  *  Purpose:
 308  *      Discontinue usage of NODE module.
 309  *  Parameters:
 310  *  Returns:
 311  *  Requires:
 312  *      node_init(void) successfully called before.
 313  *  Ensures:
 314  *      Any resources acquired in node_init(void) will be freed when last NODE
 315  *      client calls node_exit(void).
 316  */
 317 extern void node_exit(void);
 318
 319 /*
 320  *  ======== node_free_msg_buf ========
 321  *  Purpose:
 322  *      Free a message buffer previously allocated with node_alloc_msg_buf.
 323  *  Parameters:
 324  *      hnode:          The node handle.
 325  *      pbuffer:        (Address) Buffer allocated by node_alloc_msg_buf.
 326  *      pattr:          Same buffer attributes passed to node_alloc_msg_buf.
 327  *  Returns:
 328  *      0:        Success.
 329  *      -EFAULT:    Invalid node handle.
 330  *      -EPERM:      Failure to free the buffer.
 331  *  Requires:
 332  *      node_init(void) called.
 333  *      pbuffer != NULL.
 334  *  Ensures:
 335  */
 336 extern int node_free_msg_buf(struct node_object *hnode,
 337                                     IN u8 *pbuffer,
 338                                     OPTIONAL struct dsp_bufferattr
 339                                     *pattr);
 340
 341 /*
 342  *  ======== node_get_attr ========
 343  *  Purpose:
 344  *      Copy the current attributes of the specified node into a dsp_nodeattr
 345  *      structure.
 346  *  Parameters:
 347  *      hnode:          Node object allocated from node_allocate().
 348  *      pattr:          Pointer to dsp_nodeattr structure to copy node's
 349  *                      attributes.
 350  *      attr_size:      Size of pattr.
 351  *  Returns:
 352  *      0:        Success.
 353  *      -EFAULT:    Invalid hnode.
 354  *  Requires:
 355  *      node_init(void) called.
 356  *      pattr != NULL.
 357  *  Ensures:
 358  *      0:        *pattrs contains the node's current attributes.
 359  */
 360 extern int node_get_attr(struct node_object *hnode,
 361                                 OUT struct dsp_nodeattr *pattr, u32 attr_size);
 362
 363 /*
 364  *  ======== node_get_message ========
 365  *  Purpose:
 366  *      Retrieve a message from a node on the DSP. The node must be either a
 367  *      message node, task node, or XDAIS socket node.
 368  *      If a message is not available, this function will block until a
 369  *      message is available, or the node's timeout value is reached.
 370  *  Parameters:
 371  *      hnode:          Node handle returned from node_allocate().
 372  *      message:       Pointer to dsp_msg structure to copy the
 373  *                      message into.
 374  *      utimeout:       Timeout in milliseconds to wait for message.
 375  *  Returns:
 376  *      0:        Success.
 377  *      -EFAULT:    Invalid hnode.
 378  *      -EPERM: Cannot retrieve messages from this type of node.
 379  *              Error occurred while trying to retrieve a message.
 380  *      -ETIME:   Timeout occurred and no message is available.
 381  *  Requires:
 382  *      node_init(void) called.
 383  *      message != NULL.
 384  *  Ensures:
 385  */
 386 extern int node_get_message(struct node_object *hnode,
 387                                    OUT struct dsp_msg *message, u32 utimeout);
 388
 389 /*
 390  *  ======== node_get_nldr_obj ========
 391  *  Purpose:
 392  *      Retrieve the Nldr manager
 393  *  Parameters:
 394  *      hnode_mgr:       Node Manager
 395  *      phNldrObj:      Pointer to a Nldr manager handle
 396  *  Returns:
 397  *      0:        Success.
 398  *      -EFAULT:    Invalid hnode.
 399  *  Ensures:
 400  */
 401 extern int node_get_nldr_obj(struct node_mgr *hnode_mgr,
 402                                     OUT struct nldr_object **phNldrObj);
 403
 404 /*
 405  *  ======== node_init ========
 406  *  Purpose:
 407  *      Initialize the NODE module.
 408  *  Parameters:
 409  *  Returns:
 410  *      TRUE if initialization succeeded, FALSE otherwise.
 411  *  Ensures:
 412  */
 413 extern bool node_init(void);
 414
 415 /*
 416  *  ======== node_on_exit ========
 417  *  Purpose:
 418  *      Gets called when RMS_EXIT is received for a node. PROC needs to pass
 419  *      this function as a parameter to msg_create(). This function then gets
 420  *      called by the Bridge driver when an exit message for a node is received.
 421  *  Parameters:
 422  *      hnode:      Handle of the node that the exit message is for.
 423  *      nStatus:    Return status of the node's execute phase.
 424  *  Returns:
 425  *  Ensures:
 426  */
 427 void node_on_exit(struct node_object *hnode, s32 nStatus);
 428
 429 /*
 430  *  ======== node_pause ========
 431  *  Purpose:
 432  *      Suspend execution of a node currently running on the DSP.
 433  *  Parameters:
 434  *      hnode:              Node object representing a node currently
 435  *                          running on the DSP.
 436  *  Returns:
 437  *      0:            Success.
 438  *      -EFAULT:        Invalid hnode.
 439  *      -EPERM: Node is not a task or socket node.
 440  *              Failed to pause node.
 441  *      -ETIME:       A timeout occurred before the DSP responded.
 442  *      DSP_EWRONGSTSATE:   Node is not in NODE_RUNNING state.
 443  *  Requires:
 444  *      node_init(void) called.
 445  *  Ensures:
 446  */
 447 extern int node_pause(struct node_object *hnode);
 448
 449 /*
 450  *  ======== node_put_message ========
 451  *  Purpose:
 452  *      Send a message to a message node, task node, or XDAIS socket node.
 453  *      This function will block until the message stream can accommodate
 454  *      the message, or a timeout occurs. The message will be copied, so Msg
 455  *      can be re-used immediately after return.
 456  *  Parameters:
 457  *      hnode:              Node handle returned by node_allocate().
 458  *      pmsg:               Location of message to be sent to the node.
 459  *      utimeout:           Timeout in msecs to wait.
 460  *  Returns:
 461  *      0:            Success.
 462  *      -EFAULT:        Invalid hnode.
 463  *      -EPERM: Messages can't be sent to this type of node.
 464  *              Unable to send message.
 465  *      -ETIME:       Timeout occurred before message could be set.
 466  *      -EBADR:    Node is in invalid state for sending messages.
 467  *  Requires:
 468  *      node_init(void) called.
 469  *      pmsg != NULL.
 470  *  Ensures:
 471  */
 472 extern int node_put_message(struct node_object *hnode,
 473                                    IN CONST struct dsp_msg *pmsg, u32 utimeout);
 474
 475 /*
 476  *  ======== node_register_notify ========
 477  *  Purpose:
 478  *      Register to be notified on specific events for this node.
 479  *  Parameters:
 480  *      hnode:          Node handle returned by node_allocate().
 481  *      event_mask:     Mask of types of events to be notified about.
 482  *      notify_type:    Type of notification to be sent.
 483  *      hnotification:  Handle to be used for notification.
 484  *  Returns:
 485  *      0:        Success.
 486  *      -EFAULT:    Invalid hnode.
 487  *      -ENOMEM:    Insufficient memory on GPP.
 488  *      -EINVAL:     event_mask is invalid.
 489  *      -ENOSYS:   Notification type specified by notify_type is not
 490  *                      supported.
 491  *  Requires:
 492  *      node_init(void) called.
 493  *      hnotification != NULL.
 494  *  Ensures:
 495  */
 496 extern int node_register_notify(struct node_object *hnode,
 497                                        u32 event_mask, u32 notify_type,
 498                                        struct dsp_notification
 499                                        *hnotification);
 500
 501 /*
 502  *  ======== node_run ========
 503  *  Purpose:
 504  *      Start execution of a node's execute phase, or resume execution of
 505  *      a node that has been suspended (via node_pause()) on the DSP. Load
 506  *      the node's execute function if necessary.
 507  *  Parameters:
 508  *      hnode:              Node object representing a node currently
 509  *                          running on the DSP.
 510  *  Returns:
 511  *      0:            Success.
 512  *      -EFAULT:        Invalid hnode.
 513  *      -EPERM: hnode doesn't represent a message, task or dais socket node.
 514  *              Unable to start or resume execution.
 515  *      -ETIME:       A timeout occurred before the DSP responded.
 516  *      DSP_EWRONGSTSATE:   Node is not in NODE_PAUSED or NODE_CREATED state.
 517  *      -ESPIPE:        Execute function not found in the COFF file.
 518  *  Requires:
 519  *      node_init(void) called.
 520  *  Ensures:
 521  */
 522 extern int node_run(struct node_object *hnode);
 523
 524 /*
 525  *  ======== node_terminate ========
 526  *  Purpose:
 527  *      Signal a node running on the DSP that it should exit its execute
 528  *      phase function.
 529  *  Parameters:
 530  *      hnode:              Node object representing a node currently
 531  *                          running on the DSP.
 532  *      pstatus:            Location to store execute-phase function return
 533  *                          value.
 534  *  Returns:
 535  *      0:            Success.
 536  *      -EFAULT:        Invalid hnode.
 537  *      -ETIME:       A timeout occurred before the DSP responded.
 538  *      -EPERM: Type of node specified cannot be terminated.
 539  *              Unable to terminate the node.
 540  *      -EBADR:    Operation not valid for the current node state.
 541  *  Requires:
 542  *      node_init(void) called.
 543  *      pstatus != NULL.
 544  *  Ensures:
 545  */
 546 extern int node_terminate(struct node_object *hnode,
 547                                  OUT int *pstatus);
 548
 549 /*
 550  *  ======== node_get_uuid_props ========
 551  *  Purpose:
 552  *      Fetch Node properties given the UUID
 553  *  Parameters:
 554  *
 555  */
 556 extern int node_get_uuid_props(void *hprocessor,
 557                                       IN CONST struct dsp_uuid *pNodeId,
 558                                       OUT struct dsp_ndbprops
 559                                       *node_props);
 560
 561 #ifdef CONFIG_TIDSPBRIDGE_BACKTRACE
 562 /**
 563  * node_find_addr() - Find the closest symbol to the given address.
 564  *
 565  * @node_mgr:           Node manager handle
 566  * @sym_addr:           Given address to find the closest symbol
 567  * @offset_range:               offset range to look fo the closest symbol
 568  * @sym_addr_output:    Symbol Output address
 569  * @sym_name:           String with the symbol name of the closest symbol
 570  *
 571  *      This function finds the closest symbol to the address where a MMU
 572  *      Fault occurred on the DSP side.
 573  */
 574 int node_find_addr(struct node_mgr *node_mgr, u32 sym_addr,
 575                                 u32 offset_range, void *sym_addr_output,
 576                                 char *sym_name);
 577
 578 enum node_state node_get_state(void *hnode);
 579 #endif
 580
 581 #endif /* NODE_ */