diff options
Diffstat (limited to 'drivers/staging/tidspbridge/include/dspbridge/node.h')
| -rw-r--r-- | drivers/staging/tidspbridge/include/dspbridge/node.h | 583 |
1 files changed, 583 insertions, 0 deletions
diff --git a/drivers/staging/tidspbridge/include/dspbridge/node.h b/drivers/staging/tidspbridge/include/dspbridge/node.h new file mode 100644 index 000000000000..49ed5c1128e5 --- /dev/null +++ b/drivers/staging/tidspbridge/include/dspbridge/node.h @@ -0,0 +1,583 @@ +/* + * node.h + * + * DSP-BIOS Bridge driver support functions for TI OMAP processors. + * + * DSP/BIOS Bridge Node Manager. + * + * Copyright (C) 2005-2006 Texas Instruments, Inc. + * + * This package is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation. + * + * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. + */ + +#ifndef NODE_ +#define NODE_ + +#include <dspbridge/procpriv.h> + +#include <dspbridge/nodedefs.h> +#include <dspbridge/dispdefs.h> +#include <dspbridge/nldrdefs.h> +#include <dspbridge/drv.h> + +/* + * ======== node_allocate ======== + * Purpose: + * Allocate GPP resources to manage a node on the DSP. + * Parameters: + * hprocessor: Handle of processor that is allocating the node. + * node_uuid: Pointer to a dsp_uuid for the node. + * pargs: Optional arguments to be passed to the node. + * attr_in: Optional pointer to node attributes (priority, + * timeout...) + * noderes: Location to store node resource info. + * Returns: + * 0: Success. + * -ENOMEM: Insufficient memory on GPP. + * -ENOKEY: Node UUID has not been registered. + * -ESPIPE: iAlg functions not found for a DAIS node. + * -EDOM: attr_in != NULL and attr_in->prio out of + * range. + * -EPERM: A failure occured, unable to allocate node. + * -EBADR: Proccessor is not in the running state. + * Requires: + * node_init(void) called. + * hprocessor != NULL. + * node_uuid != NULL. + * noderes != NULL. + * Ensures: + * 0: IsValidNode(*ph_node). + * error: *noderes == NULL. + */ +extern int node_allocate(struct proc_object *hprocessor, + const struct dsp_uuid *node_uuid, + const struct dsp_cbdata + *pargs, const struct dsp_nodeattrin + *attr_in, + struct node_res_object **noderes, + struct process_context *pr_ctxt); + +/* + * ======== node_alloc_msg_buf ======== + * Purpose: + * Allocate and Prepare a buffer whose descriptor will be passed to a + * Node within a (dsp_msg)message + * Parameters: + * hnode: The node handle. + * usize: The size of the buffer to be allocated. + * pattr: Pointer to a dsp_bufferattr structure. + * pbuffer: Location to store the address of the allocated + * buffer on output. + * Returns: + * 0: Success. + * -EFAULT: Invalid node handle. + * -ENOMEM: Insufficent memory. + * -EPERM: General Failure. + * -EINVAL: Invalid Size. + * Requires: + * node_init(void) called. + * pbuffer != NULL. + * Ensures: + */ +extern int node_alloc_msg_buf(struct node_object *hnode, + u32 usize, struct dsp_bufferattr + *pattr, u8 **pbuffer); + +/* + * ======== node_change_priority ======== + * Purpose: + * Change the priority of an allocated node. + * Parameters: + * hnode: Node handle returned from node_allocate. + * prio: New priority level to set node's priority to. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -EDOM: prio is out of range. + * -EPERM: The specified node is not a task node. + * Unable to change node's runtime priority level. + * -EBADR: Node is not in the NODE_ALLOCATED, NODE_PAUSED, + * or NODE_RUNNING state. + * -ETIME: A timeout occurred before the DSP responded. + * Requires: + * node_init(void) called. + * Ensures: + * 0 && (Node's current priority == prio) + */ +extern int node_change_priority(struct node_object *hnode, s32 prio); + +/* + * ======== node_close_orphans ======== + * Purpose: + * Delete all nodes whose owning processor is being destroyed. + * Parameters: + * hnode_mgr: Node manager object. + * proc: Handle to processor object being destroyed. + * Returns: + * 0: Success. + * -EPERM: Unable to delete all nodes belonging to proc. + * Requires: + * Valid hnode_mgr. + * proc != NULL. + * Ensures: + */ +extern int node_close_orphans(struct node_mgr *hnode_mgr, + struct proc_object *proc); + +/* + * ======== node_connect ======== + * Purpose: + * Connect two nodes on the DSP, or a node on the DSP to the GPP. In the + * case that the connnection is being made between a node on the DSP and + * the GPP, one of the node handles (either node1 or node2) must be + * the constant NODE_HGPPNODE. + * Parameters: + * node1: Handle of first node to connect to second node. If + * this is a connection from the GPP to node2, node1 + * must be the constant NODE_HGPPNODE. Otherwise, node1 + * must be a node handle returned from a successful call + * to Node_Allocate(). + * node2: Handle of second node. Must be either NODE_HGPPNODE + * if this is a connection from DSP node to GPP, or a + * node handle returned from a successful call to + * node_allocate(). + * stream1: Output stream index on first node, to be connected + * to second node's input stream. Value must range from + * 0 <= stream1 < number of output streams. + * stream2: Input stream index on second node. Value must range + * from 0 <= stream2 < number of input streams. + * pattrs: Stream attributes (NULL ==> use defaults). + * conn_param: A pointer to a dsp_cbdata structure that defines + * connection parameter for device nodes to pass to DSP + * side. + * If the value of this parameter is NULL, then this API + * behaves like DSPNode_Connect. This parameter will have + * length of the string and the null terminated string in + * dsp_cbdata struct. This can be extended in future tp + * pass binary data. + * Returns: + * 0: Success. + * -EFAULT: Invalid node1 or node2. + * -ENOMEM: Insufficient host memory. + * -EINVAL: A stream index parameter is invalid. + * -EISCONN: A connection already exists for one of the + * indices stream1 or stream2. + * -EBADR: Either node1 or node2 is not in the + * NODE_ALLOCATED state. + * -ECONNREFUSED: No more connections available. + * -EPERM: Attempt to make an illegal connection (eg, + * Device node to device node, or device node to + * GPP), the two nodes are on different DSPs. + * Requires: + * node_init(void) called. + * Ensures: + */ +extern int node_connect(struct node_object *node1, + u32 stream1, + struct node_object *node2, + u32 stream2, + struct dsp_strmattr *pattrs, + struct dsp_cbdata + *conn_param); + +/* + * ======== node_create ======== + * Purpose: + * Create a node on the DSP by remotely calling the node's create + * function. If necessary, load code that contains the node's create + * function. + * Parameters: + * hnode: Node handle returned from node_allocate(). + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -ESPIPE: Create function not found in the COFF file. + * -EBADR: Node is not in the NODE_ALLOCATED state. + * -ENOMEM: Memory allocation failure on the DSP. + * -ETIME: A timeout occurred before the DSP responded. + * -EPERM: A failure occurred, unable to create node. + * Requires: + * node_init(void) called. + * Ensures: + */ +extern int node_create(struct node_object *hnode); + +/* + * ======== node_create_mgr ======== + * Purpose: + * Create a NODE Manager object. This object handles the creation, + * deletion, and execution of nodes on the DSP target. The NODE Manager + * also maintains a pipe map of used and available node connections. + * Each DEV object should have exactly one NODE Manager object. + * + * Parameters: + * node_man: Location to store node manager handle on output. + * hdev_obj: Device for this processor. + * Returns: + * 0: Success; + * -ENOMEM: Insufficient memory for requested resources. + * -EPERM: General failure. + * Requires: + * node_init(void) called. + * node_man != NULL. + * hdev_obj != NULL. + * Ensures: + * 0: Valide *node_man. + * error: *node_man == NULL. + */ +extern int node_create_mgr(struct node_mgr **node_man, + struct dev_object *hdev_obj); + +/* + * ======== node_delete ======== + * Purpose: + * Delete resources allocated in node_allocate(). If the node was + * created, delete the node on the DSP by remotely calling the node's + * delete function. Loads the node's delete function if necessary. + * GPP side resources are freed after node's delete function returns. + * Parameters: + * noderes: Node resource info handle returned from + * node_allocate(). + * pr_ctxt: Poninter to process context data. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -ETIME: A timeout occurred before the DSP responded. + * -EPERM: A failure occurred in deleting the node. + * -ESPIPE: Delete function not found in the COFF file. + * Requires: + * node_init(void) called. + * Ensures: + * 0: hnode is invalid. + */ +extern int node_delete(struct node_res_object *noderes, + struct process_context *pr_ctxt); + +/* + * ======== node_delete_mgr ======== + * Purpose: + * Delete the NODE Manager. + * Parameters: + * hnode_mgr: Node manager object. + * Returns: + * 0: Success. + * Requires: + * node_init(void) called. + * Valid hnode_mgr. + * Ensures: + */ +extern int node_delete_mgr(struct node_mgr *hnode_mgr); + +/* + * ======== node_enum_nodes ======== + * Purpose: + * Enumerate the nodes currently allocated for the DSP. + * Parameters: + * hnode_mgr: Node manager returned from node_create_mgr(). + * node_tab: Array to copy node handles into. + * node_tab_size: Number of handles that can be written to node_tab. + * pu_num_nodes: Location where number of node handles written to + * node_tab will be written. + * pu_allocated: Location to write total number of allocated nodes. + * Returns: + * 0: Success. + * -EINVAL: node_tab is too small to hold all node handles. + * Requires: + * Valid hnode_mgr. + * node_tab != NULL || node_tab_size == 0. + * pu_num_nodes != NULL. + * pu_allocated != NULL. + * Ensures: + * - (-EINVAL && *pu_num_nodes == 0) + * - || (0 && *pu_num_nodes <= node_tab_size) && + * (*pu_allocated == *pu_num_nodes) + */ +extern int node_enum_nodes(struct node_mgr *hnode_mgr, + void **node_tab, + u32 node_tab_size, + u32 *pu_num_nodes, + u32 *pu_allocated); + +/* + * ======== node_exit ======== + * Purpose: + * Discontinue usage of NODE module. + * Parameters: + * Returns: + * Requires: + * node_init(void) successfully called before. + * Ensures: + * Any resources acquired in node_init(void) will be freed when last NODE + * client calls node_exit(void). + */ +extern void node_exit(void); + +/* + * ======== node_free_msg_buf ======== + * Purpose: + * Free a message buffer previously allocated with node_alloc_msg_buf. + * Parameters: + * hnode: The node handle. + * pbuffer: (Address) Buffer allocated by node_alloc_msg_buf. + * pattr: Same buffer attributes passed to node_alloc_msg_buf. + * Returns: + * 0: Success. + * -EFAULT: Invalid node handle. + * -EPERM: Failure to free the buffer. + * Requires: + * node_init(void) called. + * pbuffer != NULL. + * Ensures: + */ +extern int node_free_msg_buf(struct node_object *hnode, + u8 *pbuffer, + struct dsp_bufferattr + *pattr); + +/* + * ======== node_get_attr ======== + * Purpose: + * Copy the current attributes of the specified node into a dsp_nodeattr + * structure. + * Parameters: + * hnode: Node object allocated from node_allocate(). + * pattr: Pointer to dsp_nodeattr structure to copy node's + * attributes. + * attr_size: Size of pattr. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * Requires: + * node_init(void) called. + * pattr != NULL. + * Ensures: + * 0: *pattrs contains the node's current attributes. + */ +extern int node_get_attr(struct node_object *hnode, + struct dsp_nodeattr *pattr, u32 attr_size); + +/* + * ======== node_get_message ======== + * Purpose: + * Retrieve a message from a node on the DSP. The node must be either a + * message node, task node, or XDAIS socket node. + * If a message is not available, this function will block until a + * message is available, or the node's timeout value is reached. + * Parameters: + * hnode: Node handle returned from node_allocate(). + * message: Pointer to dsp_msg structure to copy the + * message into. + * utimeout: Timeout in milliseconds to wait for message. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -EPERM: Cannot retrieve messages from this type of node. + * Error occurred while trying to retrieve a message. + * -ETIME: Timeout occurred and no message is available. + * Requires: + * node_init(void) called. + * message != NULL. + * Ensures: + */ +extern int node_get_message(struct node_object *hnode, + struct dsp_msg *message, u32 utimeout); + +/* + * ======== node_get_nldr_obj ======== + * Purpose: + * Retrieve the Nldr manager + * Parameters: + * hnode_mgr: Node Manager + * nldr_ovlyobj: Pointer to a Nldr manager handle + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * Ensures: + */ +extern int node_get_nldr_obj(struct node_mgr *hnode_mgr, + struct nldr_object **nldr_ovlyobj); + +/* + * ======== node_init ======== + * Purpose: + * Initialize the NODE module. + * Parameters: + * Returns: + * TRUE if initialization succeeded, FALSE otherwise. + * Ensures: + */ +extern bool node_init(void); + +/* + * ======== node_on_exit ======== + * Purpose: + * Gets called when RMS_EXIT is received for a node. PROC needs to pass + * this function as a parameter to msg_create(). This function then gets + * called by the Bridge driver when an exit message for a node is received. + * Parameters: + * hnode: Handle of the node that the exit message is for. + * node_status: Return status of the node's execute phase. + * Returns: + * Ensures: + */ +void node_on_exit(struct node_object *hnode, s32 node_status); + +/* + * ======== node_pause ======== + * Purpose: + * Suspend execution of a node currently running on the DSP. + * Parameters: + * hnode: Node object representing a node currently + * running on the DSP. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -EPERM: Node is not a task or socket node. + * Failed to pause node. + * -ETIME: A timeout occurred before the DSP responded. + * DSP_EWRONGSTSATE: Node is not in NODE_RUNNING state. + * Requires: + * node_init(void) called. + * Ensures: + */ +extern int node_pause(struct node_object *hnode); + +/* + * ======== node_put_message ======== + * Purpose: + * Send a message to a message node, task node, or XDAIS socket node. + * This function will block until the message stream can accommodate + * the message, or a timeout occurs. The message will be copied, so Msg + * can be re-used immediately after return. + * Parameters: + * hnode: Node handle returned by node_allocate(). + * pmsg: Location of message to be sent to the node. + * utimeout: Timeout in msecs to wait. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -EPERM: Messages can't be sent to this type of node. + * Unable to send message. + * -ETIME: Timeout occurred before message could be set. + * -EBADR: Node is in invalid state for sending messages. + * Requires: + * node_init(void) called. + * pmsg != NULL. + * Ensures: + */ +extern int node_put_message(struct node_object *hnode, + const struct dsp_msg *pmsg, u32 utimeout); + +/* + * ======== node_register_notify ======== + * Purpose: + * Register to be notified on specific events for this node. + * Parameters: + * hnode: Node handle returned by node_allocate(). + * event_mask: Mask of types of events to be notified about. + * notify_type: Type of notification to be sent. + * hnotification: Handle to be used for notification. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -ENOMEM: Insufficient memory on GPP. + * -EINVAL: event_mask is invalid. + * -ENOSYS: Notification type specified by notify_type is not + * supported. + * Requires: + * node_init(void) called. + * hnotification != NULL. + * Ensures: + */ +extern int node_register_notify(struct node_object *hnode, + u32 event_mask, u32 notify_type, + struct dsp_notification + *hnotification); + +/* + * ======== node_run ======== + * Purpose: + * Start execution of a node's execute phase, or resume execution of + * a node that has been suspended (via node_pause()) on the DSP. Load + * the node's execute function if necessary. + * Parameters: + * hnode: Node object representing a node currently + * running on the DSP. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -EPERM: hnode doesn't represent a message, task or dais socket node. + * Unable to start or resume execution. + * -ETIME: A timeout occurred before the DSP responded. + * DSP_EWRONGSTSATE: Node is not in NODE_PAUSED or NODE_CREATED state. + * -ESPIPE: Execute function not found in the COFF file. + * Requires: + * node_init(void) called. + * Ensures: + */ +extern int node_run(struct node_object *hnode); + +/* + * ======== node_terminate ======== + * Purpose: + * Signal a node running on the DSP that it should exit its execute + * phase function. + * Parameters: + * hnode: Node object representing a node currently + * running on the DSP. + * pstatus: Location to store execute-phase function return + * value. + * Returns: + * 0: Success. + * -EFAULT: Invalid hnode. + * -ETIME: A timeout occurred before the DSP responded. + * -EPERM: Type of node specified cannot be terminated. + * Unable to terminate the node. + * -EBADR: Operation not valid for the current node state. + * Requires: + * node_init(void) called. + * pstatus != NULL. + * Ensures: + */ +extern int node_terminate(struct node_object *hnode, + int *pstatus); + +/* + * ======== node_get_uuid_props ======== + * Purpose: + * Fetch Node properties given the UUID + * Parameters: + * + */ +extern int node_get_uuid_props(void *hprocessor, + const struct dsp_uuid *node_uuid, + struct dsp_ndbprops + *node_props); + +#ifdef CONFIG_TIDSPBRIDGE_BACKTRACE +/** + * node_find_addr() - Find the closest symbol to the given address. + * + * @node_mgr: Node manager handle + * @sym_addr: Given address to find the closest symbol + * @offset_range: offset range to look fo the closest symbol + * @sym_addr_output: Symbol Output address + * @sym_name: String with the symbol name of the closest symbol + * + * This function finds the closest symbol to the address where a MMU + * Fault occurred on the DSP side. + */ +int node_find_addr(struct node_mgr *node_mgr, u32 sym_addr, + u32 offset_range, void *sym_addr_output, + char *sym_name); + +enum node_state node_get_state(void *hnode); +#endif + +#endif /* NODE_ */ |