4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
6 * Bridge Bridge driver device operations.
8 * Copyright (C) 2005-2006 Texas Instruments, Inc.
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.
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.
22 /* ----------------------------------- Module Dependent Headers */
23 #include <dspbridge/chnldefs.h>
24 #include <dspbridge/cmm.h>
25 #include <dspbridge/cod.h>
26 #include <dspbridge/dehdefs.h>
27 #include <dspbridge/nodedefs.h>
28 #include <dspbridge/dispdefs.h>
29 #include <dspbridge/dspdefs.h>
30 #include <dspbridge/dmm.h>
31 #include <dspbridge/host_os.h>
33 /* ----------------------------------- This */
34 #include <dspbridge/devdefs.h>
37 * ======== dev_brd_write_fxn ========
39 * Exported function to be used as the COD write function. This function
40 * is passed a handle to a DEV_hObject by ZL in arb, then calls the
41 * device's bridge_brd_write() function.
43 * arb: Handle to a Device Object.
44 * dev_ctxt: Handle to Bridge driver defined device info.
45 * dsp_addr: Address on DSP board (Destination).
46 * host_buf: Pointer to host buffer (Source).
47 * ul_num_bytes: Number of bytes to transfer.
48 * mem_type: Memory space on DSP to which to transfer.
50 * Number of bytes written. Returns 0 if the DEV_hObject passed in via
57 extern u32 dev_brd_write_fxn(void *arb,
59 void *host_buf, u32 ul_num_bytes, u32 mem_space);
62 * ======== dev_create_device ========
64 * Called by the operating system to load the Bridge Driver for a
67 * device_obj: Ptr to location to receive the device object handle.
68 * driver_file_name: Name of Bridge driver PE DLL file to load. If the
69 * absolute path is not provided, the file is loaded
70 * through 'Bridge's module search path.
71 * host_config: Host configuration information, to be passed down
72 * to the Bridge driver when bridge_dev_create() is called.
73 * pDspConfig: DSP resources, to be passed down to the Bridge driver
74 * when bridge_dev_create() is called.
75 * dev_node_obj: Platform specific device node.
77 * 0: Module is loaded, device object has been created
78 * -ENOMEM: Insufficient memory to create needed resources.
79 * -EPERM: Unable to find Bridge driver entry point function.
80 * -ESPIPE: Unable to load ZL DLL.
84 * driver_file_name != NULL.
85 * host_config != NULL.
88 * 0: *device_obj will contain handle to the new device object.
89 * Otherwise, does not create the device object, ensures the Bridge driver
90 * module is unloaded, and sets *device_obj to NULL.
92 extern int dev_create_device(struct dev_object
94 const char *driver_file_name,
95 struct cfg_devnode *dev_node_obj);
98 * ======== dev_create_iva_device ========
100 * Called by the operating system to load the Bridge Driver for IVA.
102 * device_obj: Ptr to location to receive the device object handle.
103 * driver_file_name: Name of Bridge driver PE DLL file to load. If the
104 * absolute path is not provided, the file is loaded
105 * through 'Bridge's module search path.
106 * host_config: Host configuration information, to be passed down
107 * to the Bridge driver when bridge_dev_create() is called.
108 * pDspConfig: DSP resources, to be passed down to the Bridge driver
109 * when bridge_dev_create() is called.
110 * dev_node_obj: Platform specific device node.
112 * 0: Module is loaded, device object has been created
113 * -ENOMEM: Insufficient memory to create needed resources.
114 * -EPERM: Unable to find Bridge driver entry point function.
115 * -ESPIPE: Unable to load ZL DLL.
118 * device_obj != NULL.
119 * driver_file_name != NULL.
120 * host_config != NULL.
121 * pDspConfig != NULL.
123 * 0: *device_obj will contain handle to the new device object.
124 * Otherwise, does not create the device object, ensures the Bridge driver
125 * module is unloaded, and sets *device_obj to NULL.
127 extern int dev_create_iva_device(struct dev_object
129 const char *driver_file_name,
130 const struct cfg_hostres
132 struct cfg_devnode *dev_node_obj);
135 * ======== dev_create2 ========
137 * After successful loading of the image from api_init_complete2
138 * (PROC Auto_Start) or proc_load this fxn is called. This creates
139 * the Node Manager and updates the DEV Object.
141 * hdev_obj: Handle to device object created with dev_create_device().
143 * 0: Successful Creation of Node Manager
144 * -EPERM: Some Error Occurred.
149 * 0 and hdev_obj->hnode_mgr != NULL
150 * else hdev_obj->hnode_mgr == NULL
152 extern int dev_create2(struct dev_object *hdev_obj);
155 * ======== dev_destroy2 ========
157 * Destroys the Node manager for this device.
159 * hdev_obj: Handle to device object created with dev_create_device().
161 * 0: Successful Creation of Node Manager
162 * -EPERM: Some Error Occurred.
167 * 0 and hdev_obj->hnode_mgr == NULL
170 extern int dev_destroy2(struct dev_object *hdev_obj);
173 * ======== dev_destroy_device ========
175 * Destroys the channel manager for this device, if any, calls
176 * bridge_dev_destroy(), and then attempts to unload the Bridge module.
178 * hdev_obj: Handle to device object created with
179 * dev_create_device().
182 * -EFAULT: Invalid hdev_obj.
183 * -EPERM: The Bridge driver failed it's bridge_dev_destroy() function.
188 extern int dev_destroy_device(struct dev_object
192 * ======== dev_get_chnl_mgr ========
194 * Retrieve the handle to the channel manager created for this device.
196 * hdev_obj: Handle to device object created with
197 * dev_create_device().
198 * *mgr: Ptr to location to store handle.
201 * -EFAULT: Invalid hdev_obj.
206 * 0: *mgr contains a handle to a channel manager object,
208 * else: *mgr is NULL.
210 extern int dev_get_chnl_mgr(struct dev_object *hdev_obj,
211 struct chnl_mgr **mgr);
214 * ======== dev_get_cmm_mgr ========
216 * Retrieve the handle to the shared memory manager created for this
219 * hdev_obj: Handle to device object created with
220 * dev_create_device().
221 * *mgr: Ptr to location to store handle.
224 * -EFAULT: Invalid hdev_obj.
229 * 0: *mgr contains a handle to a channel manager object,
231 * else: *mgr is NULL.
233 extern int dev_get_cmm_mgr(struct dev_object *hdev_obj,
234 struct cmm_object **mgr);
237 * ======== dev_get_dmm_mgr ========
239 * Retrieve the handle to the dynamic memory manager created for this
242 * hdev_obj: Handle to device object created with
243 * dev_create_device().
244 * *mgr: Ptr to location to store handle.
247 * -EFAULT: Invalid hdev_obj.
252 * 0: *mgr contains a handle to a channel manager object,
254 * else: *mgr is NULL.
256 extern int dev_get_dmm_mgr(struct dev_object *hdev_obj,
257 struct dmm_object **mgr);
260 * ======== dev_get_cod_mgr ========
262 * Retrieve the COD manager create for this device.
264 * hdev_obj: Handle to device object created with
265 * dev_create_device().
266 * *cod_mgr: Ptr to location to store handle.
269 * -EFAULT: Invalid hdev_obj.
274 * 0: *cod_mgr contains a handle to a COD manager object.
275 * else: *cod_mgr is NULL.
277 extern int dev_get_cod_mgr(struct dev_object *hdev_obj,
278 struct cod_manager **cod_mgr);
281 * ======== dev_get_deh_mgr ========
283 * Retrieve the DEH manager created for this device.
285 * hdev_obj: Handle to device object created with dev_create_device().
286 * *deh_manager: Ptr to location to store handle.
289 * -EFAULT: Invalid hdev_obj.
291 * deh_manager != NULL.
294 * 0: *deh_manager contains a handle to a DEH manager object.
295 * else: *deh_manager is NULL.
297 extern int dev_get_deh_mgr(struct dev_object *hdev_obj,
298 struct deh_mgr **deh_manager);
301 * ======== dev_get_dev_node ========
303 * Retrieve the platform specific device ID for this device.
305 * hdev_obj: Handle to device object created with
306 * dev_create_device().
307 * dev_nde: Ptr to location to get the device node handle.
309 * 0: Returns a DEVNODE in *dev_node_obj.
310 * -EFAULT: Invalid hdev_obj.
315 * 0: *dev_nde contains a platform specific device ID;
316 * else: *dev_nde is NULL.
318 extern int dev_get_dev_node(struct dev_object *hdev_obj,
319 struct cfg_devnode **dev_nde);
322 * ======== dev_get_dev_type ========
324 * Retrieve the platform specific device ID for this device.
326 * hdev_obj: Handle to device object created with
327 * dev_create_device().
328 * dev_nde: Ptr to location to get the device node handle.
331 * -EFAULT: Invalid hdev_obj.
336 * 0: *dev_nde contains a platform specific device ID;
337 * else: *dev_nde is NULL.
339 extern int dev_get_dev_type(struct dev_object *device_obj,
343 * ======== dev_get_first ========
345 * Retrieve the first Device Object handle from an internal linked list of
346 * of DEV_OBJECTs maintained by DEV.
349 * NULL if there are no device objects stored; else
350 * a valid DEV_HOBJECT.
352 * No calls to dev_create_device or dev_destroy_device (which my modify the
353 * internal device object list) may occur between calls to dev_get_first
356 * The DEV_HOBJECT returned is valid.
357 * A subsequent call to dev_get_next will return the next device object in
360 extern struct dev_object *dev_get_first(void);
363 * ======== dev_get_intf_fxns ========
365 * Retrieve the Bridge driver interface function structure for the
366 * loaded Bridge driver.
368 * hdev_obj: Handle to device object created with
369 * dev_create_device().
370 * *if_fxns: Ptr to location to store fxn interface.
373 * -EFAULT: Invalid hdev_obj.
378 * 0: *if_fxns contains a pointer to the Bridge
380 * else: *if_fxns is NULL.
382 extern int dev_get_intf_fxns(struct dev_object *hdev_obj,
383 struct bridge_drv_interface **if_fxns);
386 * ======== dev_get_io_mgr ========
388 * Retrieve the handle to the IO manager created for this device.
390 * hdev_obj: Handle to device object created with
391 * dev_create_device().
392 * *mgr: Ptr to location to store handle.
395 * -EFAULT: Invalid hdev_obj.
400 * 0: *mgr contains a handle to an IO manager object.
401 * else: *mgr is NULL.
403 extern int dev_get_io_mgr(struct dev_object *hdev_obj,
404 struct io_mgr **mgr);
407 * ======== dev_get_next ========
409 * Retrieve the next Device Object handle from an internal linked list of
410 * of DEV_OBJECTs maintained by DEV, after having previously called
411 * dev_get_first() and zero or more dev_get_next
413 * hdev_obj: Handle to the device object returned from a previous
414 * call to dev_get_first() or dev_get_next().
416 * NULL if there are no further device objects on the list or hdev_obj
418 * else the next valid DEV_HOBJECT in the list.
420 * No calls to dev_create_device or dev_destroy_device (which my modify the
421 * internal device object list) may occur between calls to dev_get_first
424 * The DEV_HOBJECT returned is valid.
425 * A subsequent call to dev_get_next will return the next device object in
428 extern struct dev_object *dev_get_next(struct dev_object
432 * ========= dev_get_msg_mgr ========
434 * Retrieve the msg_ctrl Manager Handle from the DevObject.
436 * hdev_obj: Handle to the Dev Object
437 * msg_man: Location where msg_ctrl Manager handle will be returned.
445 extern void dev_get_msg_mgr(struct dev_object *hdev_obj,
446 struct msg_mgr **msg_man);
449 * ========= dev_get_node_manager ========
451 * Retrieve the Node Manager Handle from the DevObject. It is an
454 * hdev_obj: Handle to the Dev Object
455 * node_man: Location where Handle to the Node Manager will be
459 * -EFAULT: Invalid Dev Object handle.
462 * node_man is not null
464 * 0: *node_man contains a handle to a Node manager object.
465 * else: *node_man is NULL.
467 extern int dev_get_node_manager(struct dev_object
469 struct node_mgr **node_man);
472 * ======== dev_get_symbol ========
474 * Get the value of a symbol in the currently loaded program.
476 * hdev_obj: Handle to device object created with
477 * dev_create_device().
478 * str_sym: Name of symbol to look up.
479 * pul_value: Ptr to symbol value.
482 * -EFAULT: Invalid hdev_obj.
483 * -ESPIPE: Symbols couldn not be found or have not been loaded onto
490 * 0: *pul_value contains the symbol value;
492 extern int dev_get_symbol(struct dev_object *hdev_obj,
493 const char *str_sym, u32 * pul_value);
496 * ======== dev_get_bridge_context ========
498 * Retrieve the Bridge Context handle, as returned by the
499 * bridge_dev_create fxn.
501 * hdev_obj: Handle to device object created with dev_create_device()
502 * *phbridge_context: Ptr to location to store context handle.
505 * -EFAULT: Invalid hdev_obj.
507 * phbridge_context != NULL.
510 * 0: *phbridge_context contains context handle;
511 * else: *phbridge_context is NULL;
513 extern int dev_get_bridge_context(struct dev_object *hdev_obj,
514 struct bridge_dev_context
518 * ======== dev_exit ========
520 * Decrement reference count, and free resources when reference count is
525 * DEV is initialized.
527 * When reference count == 0, DEV's private resources are freed.
529 extern void dev_exit(void);
532 * ======== dev_init ========
534 * Initialize DEV's private state, keeping a reference count on each call.
537 * TRUE if initialized; FALSE if error occured.
540 * TRUE: A requirement for the other public DEV functions.
542 extern bool dev_init(void);
545 * ======== dev_is_locked ========
547 * Predicate function to determine if the device has been
548 * locked by a client for exclusive access.
550 * hdev_obj: Handle to device object created with
551 * dev_create_device().
553 * 0: TRUE: device has been locked.
554 * 0: FALSE: device not locked.
555 * -EFAULT: hdev_obj was invalid.
560 extern int dev_is_locked(struct dev_object *hdev_obj);
563 * ======== dev_insert_proc_object ========
565 * Inserts the Processor Object into the List of PROC Objects
566 * kept in the DEV Object
568 * proc_obj: Handle to the Proc Object
569 * hdev_obj Handle to the Dev Object
570 * bAttachedNew Specifies if there are already processors attached
572 * 0: Successfully inserted into the list
574 * proc_obj is not NULL
575 * hdev_obj is a valid handle to the DEV.
577 * List(of Proc object in Dev) Exists.
579 * 0 & the PROC Object is inserted and the list is not empty
581 * If the List of Proc Object is empty bAttachedNew is TRUE, it indicated
582 * this is the first Processor attaching.
583 * If it is False, there are already processors attached.
585 extern int dev_insert_proc_object(struct dev_object
588 bool *already_attached);
591 * ======== dev_remove_proc_object ========
593 * Search for and remove a Proc object from the given list maintained
596 * p_proc_object: Ptr to ProcObject to insert.
597 * dev_obj: Ptr to Dev Object where the list is.
598 * already_attached: Ptr to return the bool
601 * -EPERM Failure to Remove the PROC Object from the list
605 * dev_obj->proc_list != NULL
606 * !LST_IS_EMPTY(dev_obj->proc_list)
607 * already_attached !=NULL
610 * List will be deleted when the DEV is destroyed.
613 extern int dev_remove_proc_object(struct dev_object
614 *hdev_obj, u32 proc_obj);
617 * ======== dev_notify_clients ========
619 * Notify all clients of this device of a change in device status.
620 * Clients may include multiple users of BRD, as well as CHNL.
621 * This function is asychronous, and may be called by a timer event
622 * set up by a watchdog timer.
624 * hdev_obj: Handle to device object created with dev_create_device().
625 * ret: A status word, most likely a BRD_STATUS.
627 * 0: All registered clients were asynchronously notified.
628 * -EINVAL: Invalid hdev_obj.
632 * 0: Notifications are queued by the operating system to be
633 * delivered to clients. This function does not ensure that
634 * the notifications will ever be delivered.
636 extern int dev_notify_clients(struct dev_object *hdev_obj, u32 ret);
639 * ======== dev_remove_device ========
641 * Destroys the Device Object created by dev_start_device.
643 * dev_node_obj: Device node as it is know to OS.
646 * <error code> Otherwise.
650 extern int dev_remove_device(struct cfg_devnode *dev_node_obj);
653 * ======== dev_set_chnl_mgr ========
655 * Set the channel manager for this device.
657 * hdev_obj: Handle to device object created with
658 * dev_create_device().
659 * hmgr: Handle to a channel manager, or NULL.
662 * -EFAULT: Invalid hdev_obj.
667 extern int dev_set_chnl_mgr(struct dev_object *hdev_obj,
668 struct chnl_mgr *hmgr);
671 * ======== dev_set_msg_mgr ========
673 * Set the Message manager for this device.
675 * hdev_obj: Handle to device object created with dev_create_device().
676 * hmgr: Handle to a message manager, or NULL.
682 extern void dev_set_msg_mgr(struct dev_object *hdev_obj, struct msg_mgr *hmgr);
685 * ======== dev_start_device ========
687 * Initializes the new device with bridge environment. This involves
688 * querying CM for allocated resources, querying the registry for
689 * necessary dsp resources (requested in the INF file), and using this
690 * information to create a bridge device object.
692 * dev_node_obj: Device node as it is know to OS.
695 * <error code> Otherwise.
700 extern int dev_start_device(struct cfg_devnode *dev_node_obj);