| /* |
| * dev.h |
| * |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * |
| * Bridge Bridge driver device operations. |
| * |
| * 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 DEV_ |
| #define DEV_ |
| |
| /* ----------------------------------- Module Dependent Headers */ |
| #include <dspbridge/chnldefs.h> |
| #include <dspbridge/cmm.h> |
| #include <dspbridge/cod.h> |
| #include <dspbridge/dspdeh.h> |
| #include <dspbridge/nodedefs.h> |
| #include <dspbridge/disp.h> |
| #include <dspbridge/dspdefs.h> |
| #include <dspbridge/dmm.h> |
| #include <dspbridge/host_os.h> |
| |
| /* ----------------------------------- This */ |
| #include <dspbridge/devdefs.h> |
| |
| /* |
| * ======== dev_brd_write_fxn ======== |
| * Purpose: |
| * Exported function to be used as the COD write function. This function |
| * is passed a handle to a DEV_hObject by ZL in arb, then calls the |
| * device's bridge_brd_write() function. |
| * Parameters: |
| * arb: Handle to a Device Object. |
| * dev_ctxt: Handle to Bridge driver defined device info. |
| * dsp_addr: Address on DSP board (Destination). |
| * host_buf: Pointer to host buffer (Source). |
| * ul_num_bytes: Number of bytes to transfer. |
| * mem_type: Memory space on DSP to which to transfer. |
| * Returns: |
| * Number of bytes written. Returns 0 if the DEV_hObject passed in via |
| * arb is invalid. |
| * Requires: |
| * DEV Initialized. |
| * host_buf != NULL |
| * Ensures: |
| */ |
| extern u32 dev_brd_write_fxn(void *arb, |
| u32 dsp_add, |
| void *host_buf, u32 ul_num_bytes, u32 mem_space); |
| |
| /* |
| * ======== dev_create_device ======== |
| * Purpose: |
| * Called by the operating system to load the Bridge Driver for a |
| * 'Bridge device. |
| * Parameters: |
| * device_obj: Ptr to location to receive the device object handle. |
| * driver_file_name: Name of Bridge driver PE DLL file to load. If the |
| * absolute path is not provided, the file is loaded |
| * through 'Bridge's module search path. |
| * host_config: Host configuration information, to be passed down |
| * to the Bridge driver when bridge_dev_create() is called. |
| * pDspConfig: DSP resources, to be passed down to the Bridge driver |
| * when bridge_dev_create() is called. |
| * dev_node_obj: Platform specific device node. |
| * Returns: |
| * 0: Module is loaded, device object has been created |
| * -ENOMEM: Insufficient memory to create needed resources. |
| * -EPERM: Unable to find Bridge driver entry point function. |
| * -ESPIPE: Unable to load ZL DLL. |
| * Requires: |
| * DEV Initialized. |
| * device_obj != NULL. |
| * driver_file_name != NULL. |
| * host_config != NULL. |
| * pDspConfig != NULL. |
| * Ensures: |
| * 0: *device_obj will contain handle to the new device object. |
| * Otherwise, does not create the device object, ensures the Bridge driver |
| * module is unloaded, and sets *device_obj to NULL. |
| */ |
| extern int dev_create_device(struct dev_object |
| **device_obj, |
| const char *driver_file_name, |
| struct cfg_devnode *dev_node_obj); |
| |
| /* |
| * ======== dev_create2 ======== |
| * Purpose: |
| * After successful loading of the image from api_init_complete2 |
| * (PROC Auto_Start) or proc_load this fxn is called. This creates |
| * the Node Manager and updates the DEV Object. |
| * Parameters: |
| * hdev_obj: Handle to device object created with dev_create_device(). |
| * Returns: |
| * 0: Successful Creation of Node Manager |
| * -EPERM: Some Error Occurred. |
| * Requires: |
| * DEV Initialized |
| * Valid hdev_obj |
| * Ensures: |
| * 0 and hdev_obj->node_mgr != NULL |
| * else hdev_obj->node_mgr == NULL |
| */ |
| extern int dev_create2(struct dev_object *hdev_obj); |
| |
| /* |
| * ======== dev_destroy2 ======== |
| * Purpose: |
| * Destroys the Node manager for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with dev_create_device(). |
| * Returns: |
| * 0: Successful Creation of Node Manager |
| * -EPERM: Some Error Occurred. |
| * Requires: |
| * DEV Initialized |
| * Valid hdev_obj |
| * Ensures: |
| * 0 and hdev_obj->node_mgr == NULL |
| * else -EPERM. |
| */ |
| extern int dev_destroy2(struct dev_object *hdev_obj); |
| |
| /* |
| * ======== dev_destroy_device ======== |
| * Purpose: |
| * Destroys the channel manager for this device, if any, calls |
| * bridge_dev_destroy(), and then attempts to unload the Bridge module. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * -EPERM: The Bridge driver failed it's bridge_dev_destroy() function. |
| * Requires: |
| * DEV Initialized. |
| * Ensures: |
| */ |
| extern int dev_destroy_device(struct dev_object |
| *hdev_obj); |
| |
| /* |
| * ======== dev_get_chnl_mgr ======== |
| * Purpose: |
| * Retrieve the handle to the channel manager created for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * *mgr: Ptr to location to store handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * mgr != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *mgr contains a handle to a channel manager object, |
| * or NULL. |
| * else: *mgr is NULL. |
| */ |
| extern int dev_get_chnl_mgr(struct dev_object *hdev_obj, |
| struct chnl_mgr **mgr); |
| |
| /* |
| * ======== dev_get_cmm_mgr ======== |
| * Purpose: |
| * Retrieve the handle to the shared memory manager created for this |
| * device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * *mgr: Ptr to location to store handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * mgr != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *mgr contains a handle to a channel manager object, |
| * or NULL. |
| * else: *mgr is NULL. |
| */ |
| extern int dev_get_cmm_mgr(struct dev_object *hdev_obj, |
| struct cmm_object **mgr); |
| |
| /* |
| * ======== dev_get_dmm_mgr ======== |
| * Purpose: |
| * Retrieve the handle to the dynamic memory manager created for this |
| * device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * *mgr: Ptr to location to store handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * mgr != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *mgr contains a handle to a channel manager object, |
| * or NULL. |
| * else: *mgr is NULL. |
| */ |
| extern int dev_get_dmm_mgr(struct dev_object *hdev_obj, |
| struct dmm_object **mgr); |
| |
| /* |
| * ======== dev_get_cod_mgr ======== |
| * Purpose: |
| * Retrieve the COD manager create for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * *cod_mgr: Ptr to location to store handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * cod_mgr != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *cod_mgr contains a handle to a COD manager object. |
| * else: *cod_mgr is NULL. |
| */ |
| extern int dev_get_cod_mgr(struct dev_object *hdev_obj, |
| struct cod_manager **cod_mgr); |
| |
| /* |
| * ======== dev_get_deh_mgr ======== |
| * Purpose: |
| * Retrieve the DEH manager created for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with dev_create_device(). |
| * *deh_manager: Ptr to location to store handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * deh_manager != NULL. |
| * DEH Initialized. |
| * Ensures: |
| * 0: *deh_manager contains a handle to a DEH manager object. |
| * else: *deh_manager is NULL. |
| */ |
| extern int dev_get_deh_mgr(struct dev_object *hdev_obj, |
| struct deh_mgr **deh_manager); |
| |
| /* |
| * ======== dev_get_dev_node ======== |
| * Purpose: |
| * Retrieve the platform specific device ID for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * dev_nde: Ptr to location to get the device node handle. |
| * Returns: |
| * 0: Returns a DEVNODE in *dev_node_obj. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * dev_nde != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *dev_nde contains a platform specific device ID; |
| * else: *dev_nde is NULL. |
| */ |
| extern int dev_get_dev_node(struct dev_object *hdev_obj, |
| struct cfg_devnode **dev_nde); |
| |
| /* |
| * ======== dev_get_dev_type ======== |
| * Purpose: |
| * Retrieve the platform specific device ID for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * dev_nde: Ptr to location to get the device node handle. |
| * Returns: |
| * 0: Success |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * dev_nde != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *dev_nde contains a platform specific device ID; |
| * else: *dev_nde is NULL. |
| */ |
| extern int dev_get_dev_type(struct dev_object *device_obj, |
| u8 *dev_type); |
| |
| /* |
| * ======== dev_get_first ======== |
| * Purpose: |
| * Retrieve the first Device Object handle from an internal linked list of |
| * of DEV_OBJECTs maintained by DEV. |
| * Parameters: |
| * Returns: |
| * NULL if there are no device objects stored; else |
| * a valid DEV_HOBJECT. |
| * Requires: |
| * No calls to dev_create_device or dev_destroy_device (which my modify the |
| * internal device object list) may occur between calls to dev_get_first |
| * and dev_get_next. |
| * Ensures: |
| * The DEV_HOBJECT returned is valid. |
| * A subsequent call to dev_get_next will return the next device object in |
| * the list. |
| */ |
| extern struct dev_object *dev_get_first(void); |
| |
| /* |
| * ======== dev_get_intf_fxns ======== |
| * Purpose: |
| * Retrieve the Bridge driver interface function structure for the |
| * loaded Bridge driver. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * *if_fxns: Ptr to location to store fxn interface. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * if_fxns != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *if_fxns contains a pointer to the Bridge |
| * driver interface; |
| * else: *if_fxns is NULL. |
| */ |
| extern int dev_get_intf_fxns(struct dev_object *hdev_obj, |
| struct bridge_drv_interface **if_fxns); |
| |
| /* |
| * ======== dev_get_io_mgr ======== |
| * Purpose: |
| * Retrieve the handle to the IO manager created for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * *mgr: Ptr to location to store handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * mgr != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *mgr contains a handle to an IO manager object. |
| * else: *mgr is NULL. |
| */ |
| extern int dev_get_io_mgr(struct dev_object *hdev_obj, |
| struct io_mgr **mgr); |
| |
| /* |
| * ======== dev_get_next ======== |
| * Purpose: |
| * Retrieve the next Device Object handle from an internal linked list of |
| * of DEV_OBJECTs maintained by DEV, after having previously called |
| * dev_get_first() and zero or more dev_get_next |
| * Parameters: |
| * hdev_obj: Handle to the device object returned from a previous |
| * call to dev_get_first() or dev_get_next(). |
| * Returns: |
| * NULL if there are no further device objects on the list or hdev_obj |
| * was invalid; |
| * else the next valid DEV_HOBJECT in the list. |
| * Requires: |
| * No calls to dev_create_device or dev_destroy_device (which my modify the |
| * internal device object list) may occur between calls to dev_get_first |
| * and dev_get_next. |
| * Ensures: |
| * The DEV_HOBJECT returned is valid. |
| * A subsequent call to dev_get_next will return the next device object in |
| * the list. |
| */ |
| extern struct dev_object *dev_get_next(struct dev_object |
| *hdev_obj); |
| |
| /* |
| * ========= dev_get_msg_mgr ======== |
| * Purpose: |
| * Retrieve the msg_ctrl Manager Handle from the DevObject. |
| * Parameters: |
| * hdev_obj: Handle to the Dev Object |
| * msg_man: Location where msg_ctrl Manager handle will be returned. |
| * Returns: |
| * Requires: |
| * DEV Initialized. |
| * Valid hdev_obj. |
| * node_man != NULL. |
| * Ensures: |
| */ |
| extern void dev_get_msg_mgr(struct dev_object *hdev_obj, |
| struct msg_mgr **msg_man); |
| |
| /* |
| * ========= dev_get_node_manager ======== |
| * Purpose: |
| * Retrieve the Node Manager Handle from the DevObject. It is an |
| * accessor function |
| * Parameters: |
| * hdev_obj: Handle to the Dev Object |
| * node_man: Location where Handle to the Node Manager will be |
| * returned.. |
| * Returns: |
| * 0: Success |
| * -EFAULT: Invalid Dev Object handle. |
| * Requires: |
| * DEV Initialized. |
| * node_man is not null |
| * Ensures: |
| * 0: *node_man contains a handle to a Node manager object. |
| * else: *node_man is NULL. |
| */ |
| extern int dev_get_node_manager(struct dev_object |
| *hdev_obj, |
| struct node_mgr **node_man); |
| |
| /* |
| * ======== dev_get_symbol ======== |
| * Purpose: |
| * Get the value of a symbol in the currently loaded program. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * str_sym: Name of symbol to look up. |
| * pul_value: Ptr to symbol value. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * -ESPIPE: Symbols couldn not be found or have not been loaded onto |
| * the board. |
| * Requires: |
| * str_sym != NULL. |
| * pul_value != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *pul_value contains the symbol value; |
| */ |
| extern int dev_get_symbol(struct dev_object *hdev_obj, |
| const char *str_sym, u32 * pul_value); |
| |
| /* |
| * ======== dev_get_bridge_context ======== |
| * Purpose: |
| * Retrieve the Bridge Context handle, as returned by the |
| * bridge_dev_create fxn. |
| * Parameters: |
| * hdev_obj: Handle to device object created with dev_create_device() |
| * *phbridge_context: Ptr to location to store context handle. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * phbridge_context != NULL. |
| * DEV Initialized. |
| * Ensures: |
| * 0: *phbridge_context contains context handle; |
| * else: *phbridge_context is NULL; |
| */ |
| extern int dev_get_bridge_context(struct dev_object *hdev_obj, |
| struct bridge_dev_context |
| **phbridge_context); |
| |
| /* |
| * ======== dev_insert_proc_object ======== |
| * Purpose: |
| * Inserts the Processor Object into the List of PROC Objects |
| * kept in the DEV Object |
| * Parameters: |
| * proc_obj: Handle to the Proc Object |
| * hdev_obj Handle to the Dev Object |
| * bAttachedNew Specifies if there are already processors attached |
| * Returns: |
| * 0: Successfully inserted into the list |
| * Requires: |
| * proc_obj is not NULL |
| * hdev_obj is a valid handle to the DEV. |
| * DEV Initialized. |
| * List(of Proc object in Dev) Exists. |
| * Ensures: |
| * 0 & the PROC Object is inserted and the list is not empty |
| * Details: |
| * If the List of Proc Object is empty bAttachedNew is TRUE, it indicated |
| * this is the first Processor attaching. |
| * If it is False, there are already processors attached. |
| */ |
| extern int dev_insert_proc_object(struct dev_object |
| *hdev_obj, |
| u32 proc_obj, |
| bool *already_attached); |
| |
| /* |
| * ======== dev_remove_proc_object ======== |
| * Purpose: |
| * Search for and remove a Proc object from the given list maintained |
| * by the DEV |
| * Parameters: |
| * p_proc_object: Ptr to ProcObject to insert. |
| * dev_obj: Ptr to Dev Object where the list is. |
| * already_attached: Ptr to return the bool |
| * Returns: |
| * 0: If successful. |
| * -EPERM Failure to Remove the PROC Object from the list |
| * Requires: |
| * DevObject is Valid |
| * proc_obj != 0 |
| * dev_obj->proc_list != NULL |
| * !LST_IS_EMPTY(dev_obj->proc_list) |
| * already_attached !=NULL |
| * Ensures: |
| * Details: |
| * List will be deleted when the DEV is destroyed. |
| * |
| */ |
| extern int dev_remove_proc_object(struct dev_object |
| *hdev_obj, u32 proc_obj); |
| |
| /* |
| * ======== dev_notify_clients ======== |
| * Purpose: |
| * Notify all clients of this device of a change in device status. |
| * Clients may include multiple users of BRD, as well as CHNL. |
| * This function is asychronous, and may be called by a timer event |
| * set up by a watchdog timer. |
| * Parameters: |
| * hdev_obj: Handle to device object created with dev_create_device(). |
| * ret: A status word, most likely a BRD_STATUS. |
| * Returns: |
| * 0: All registered clients were asynchronously notified. |
| * -EINVAL: Invalid hdev_obj. |
| * Requires: |
| * DEV Initialized. |
| * Ensures: |
| * 0: Notifications are queued by the operating system to be |
| * delivered to clients. This function does not ensure that |
| * the notifications will ever be delivered. |
| */ |
| extern int dev_notify_clients(struct dev_object *hdev_obj, u32 ret); |
| |
| /* |
| * ======== dev_remove_device ======== |
| * Purpose: |
| * Destroys the Device Object created by dev_start_device. |
| * Parameters: |
| * dev_node_obj: Device node as it is know to OS. |
| * Returns: |
| * 0: If success; |
| * <error code> Otherwise. |
| * Requires: |
| * Ensures: |
| */ |
| extern int dev_remove_device(struct cfg_devnode *dev_node_obj); |
| |
| /* |
| * ======== dev_set_chnl_mgr ======== |
| * Purpose: |
| * Set the channel manager for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with |
| * dev_create_device(). |
| * hmgr: Handle to a channel manager, or NULL. |
| * Returns: |
| * 0: Success. |
| * -EFAULT: Invalid hdev_obj. |
| * Requires: |
| * DEV Initialized. |
| * Ensures: |
| */ |
| extern int dev_set_chnl_mgr(struct dev_object *hdev_obj, |
| struct chnl_mgr *hmgr); |
| |
| /* |
| * ======== dev_set_msg_mgr ======== |
| * Purpose: |
| * Set the Message manager for this device. |
| * Parameters: |
| * hdev_obj: Handle to device object created with dev_create_device(). |
| * hmgr: Handle to a message manager, or NULL. |
| * Returns: |
| * Requires: |
| * DEV Initialized. |
| * Ensures: |
| */ |
| extern void dev_set_msg_mgr(struct dev_object *hdev_obj, struct msg_mgr *hmgr); |
| |
| /* |
| * ======== dev_start_device ======== |
| * Purpose: |
| * Initializes the new device with bridge environment. This involves |
| * querying CM for allocated resources, querying the registry for |
| * necessary dsp resources (requested in the INF file), and using this |
| * information to create a bridge device object. |
| * Parameters: |
| * dev_node_obj: Device node as it is know to OS. |
| * Returns: |
| * 0: If success; |
| * <error code> Otherwise. |
| * Requires: |
| * DEV initialized. |
| * Ensures: |
| */ |
| extern int dev_start_device(struct cfg_devnode *dev_node_obj); |
| |
| #endif /* DEV_ */ |
