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/dspdeh.h>
27 #include <dspbridge/nodedefs.h>
28 #include <dspbridge/disp.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_create2 ========
100 * After successful loading of the image from api_init_complete2
101 * (PROC Auto_Start) or proc_load this fxn is called. This creates
102 * the Node Manager and updates the DEV Object.
104 * hdev_obj: Handle to device object created with dev_create_device().
106 * 0: Successful Creation of Node Manager
107 * -EPERM: Some Error Occurred.
112 * 0 and hdev_obj->node_mgr != NULL
113 * else hdev_obj->node_mgr == NULL
115 extern int dev_create2(struct dev_object *hdev_obj);
118 * ======== dev_destroy2 ========
120 * Destroys the Node manager for this device.
122 * hdev_obj: Handle to device object created with dev_create_device().
124 * 0: Successful Creation of Node Manager
125 * -EPERM: Some Error Occurred.
130 * 0 and hdev_obj->node_mgr == NULL
133 extern int dev_destroy2(struct dev_object *hdev_obj);
136 * ======== dev_destroy_device ========
138 * Destroys the channel manager for this device, if any, calls
139 * bridge_dev_destroy(), and then attempts to unload the Bridge module.
141 * hdev_obj: Handle to device object created with
142 * dev_create_device().
145 * -EFAULT: Invalid hdev_obj.
146 * -EPERM: The Bridge driver failed it's bridge_dev_destroy() function.
151 extern int dev_destroy_device(struct dev_object
155 * ======== dev_get_chnl_mgr ========
157 * Retrieve the handle to the channel manager created for this device.
159 * hdev_obj: Handle to device object created with
160 * dev_create_device().
161 * *mgr: Ptr to location to store handle.
164 * -EFAULT: Invalid hdev_obj.
169 * 0: *mgr contains a handle to a channel manager object,
171 * else: *mgr is NULL.
173 extern int dev_get_chnl_mgr(struct dev_object *hdev_obj,
174 struct chnl_mgr **mgr);
177 * ======== dev_get_cmm_mgr ========
179 * Retrieve the handle to the shared memory manager created for this
182 * hdev_obj: Handle to device object created with
183 * dev_create_device().
184 * *mgr: Ptr to location to store handle.
187 * -EFAULT: Invalid hdev_obj.
192 * 0: *mgr contains a handle to a channel manager object,
194 * else: *mgr is NULL.
196 extern int dev_get_cmm_mgr(struct dev_object *hdev_obj,
197 struct cmm_object **mgr);
200 * ======== dev_get_dmm_mgr ========
202 * Retrieve the handle to the dynamic memory manager created for this
205 * hdev_obj: Handle to device object created with
206 * dev_create_device().
207 * *mgr: Ptr to location to store handle.
210 * -EFAULT: Invalid hdev_obj.
215 * 0: *mgr contains a handle to a channel manager object,
217 * else: *mgr is NULL.
219 extern int dev_get_dmm_mgr(struct dev_object *hdev_obj,
220 struct dmm_object **mgr);
223 * ======== dev_get_cod_mgr ========
225 * Retrieve the COD manager create for this device.
227 * hdev_obj: Handle to device object created with
228 * dev_create_device().
229 * *cod_mgr: Ptr to location to store handle.
232 * -EFAULT: Invalid hdev_obj.
237 * 0: *cod_mgr contains a handle to a COD manager object.
238 * else: *cod_mgr is NULL.
240 extern int dev_get_cod_mgr(struct dev_object *hdev_obj,
241 struct cod_manager **cod_mgr);
244 * ======== dev_get_deh_mgr ========
246 * Retrieve the DEH manager created for this device.
248 * hdev_obj: Handle to device object created with dev_create_device().
249 * *deh_manager: Ptr to location to store handle.
252 * -EFAULT: Invalid hdev_obj.
254 * deh_manager != NULL.
257 * 0: *deh_manager contains a handle to a DEH manager object.
258 * else: *deh_manager is NULL.
260 extern int dev_get_deh_mgr(struct dev_object *hdev_obj,
261 struct deh_mgr **deh_manager);
264 * ======== dev_get_dev_node ========
266 * Retrieve the platform specific device ID for this device.
268 * hdev_obj: Handle to device object created with
269 * dev_create_device().
270 * dev_nde: Ptr to location to get the device node handle.
272 * 0: Returns a DEVNODE in *dev_node_obj.
273 * -EFAULT: Invalid hdev_obj.
278 * 0: *dev_nde contains a platform specific device ID;
279 * else: *dev_nde is NULL.
281 extern int dev_get_dev_node(struct dev_object *hdev_obj,
282 struct cfg_devnode **dev_nde);
285 * ======== dev_get_dev_type ========
287 * Retrieve the platform specific device ID for this device.
289 * hdev_obj: Handle to device object created with
290 * dev_create_device().
291 * dev_nde: Ptr to location to get the device node handle.
294 * -EFAULT: Invalid hdev_obj.
299 * 0: *dev_nde contains a platform specific device ID;
300 * else: *dev_nde is NULL.
302 extern int dev_get_dev_type(struct dev_object *device_obj,
306 * ======== dev_get_first ========
308 * Retrieve the first Device Object handle from an internal linked list of
309 * of DEV_OBJECTs maintained by DEV.
312 * NULL if there are no device objects stored; else
313 * a valid DEV_HOBJECT.
315 * No calls to dev_create_device or dev_destroy_device (which my modify the
316 * internal device object list) may occur between calls to dev_get_first
319 * The DEV_HOBJECT returned is valid.
320 * A subsequent call to dev_get_next will return the next device object in
323 extern struct dev_object *dev_get_first(void);
326 * ======== dev_get_intf_fxns ========
328 * Retrieve the Bridge driver interface function structure for the
329 * loaded Bridge driver.
331 * hdev_obj: Handle to device object created with
332 * dev_create_device().
333 * *if_fxns: Ptr to location to store fxn interface.
336 * -EFAULT: Invalid hdev_obj.
341 * 0: *if_fxns contains a pointer to the Bridge
343 * else: *if_fxns is NULL.
345 extern int dev_get_intf_fxns(struct dev_object *hdev_obj,
346 struct bridge_drv_interface **if_fxns);
349 * ======== dev_get_io_mgr ========
351 * Retrieve the handle to the IO manager created for this device.
353 * hdev_obj: Handle to device object created with
354 * dev_create_device().
355 * *mgr: Ptr to location to store handle.
358 * -EFAULT: Invalid hdev_obj.
363 * 0: *mgr contains a handle to an IO manager object.
364 * else: *mgr is NULL.
366 extern int dev_get_io_mgr(struct dev_object *hdev_obj,
367 struct io_mgr **mgr);
370 * ======== dev_get_next ========
372 * Retrieve the next Device Object handle from an internal linked list of
373 * of DEV_OBJECTs maintained by DEV, after having previously called
374 * dev_get_first() and zero or more dev_get_next
376 * hdev_obj: Handle to the device object returned from a previous
377 * call to dev_get_first() or dev_get_next().
379 * NULL if there are no further device objects on the list or hdev_obj
381 * else the next valid DEV_HOBJECT in the list.
383 * No calls to dev_create_device or dev_destroy_device (which my modify the
384 * internal device object list) may occur between calls to dev_get_first
387 * The DEV_HOBJECT returned is valid.
388 * A subsequent call to dev_get_next will return the next device object in
391 extern struct dev_object *dev_get_next(struct dev_object
395 * ========= dev_get_msg_mgr ========
397 * Retrieve the msg_ctrl Manager Handle from the DevObject.
399 * hdev_obj: Handle to the Dev Object
400 * msg_man: Location where msg_ctrl Manager handle will be returned.
408 extern void dev_get_msg_mgr(struct dev_object *hdev_obj,
409 struct msg_mgr **msg_man);
412 * ========= dev_get_node_manager ========
414 * Retrieve the Node Manager Handle from the DevObject. It is an
417 * hdev_obj: Handle to the Dev Object
418 * node_man: Location where Handle to the Node Manager will be
422 * -EFAULT: Invalid Dev Object handle.
425 * node_man is not null
427 * 0: *node_man contains a handle to a Node manager object.
428 * else: *node_man is NULL.
430 extern int dev_get_node_manager(struct dev_object
432 struct node_mgr **node_man);
435 * ======== dev_get_symbol ========
437 * Get the value of a symbol in the currently loaded program.
439 * hdev_obj: Handle to device object created with
440 * dev_create_device().
441 * str_sym: Name of symbol to look up.
442 * pul_value: Ptr to symbol value.
445 * -EFAULT: Invalid hdev_obj.
446 * -ESPIPE: Symbols couldn not be found or have not been loaded onto
453 * 0: *pul_value contains the symbol value;
455 extern int dev_get_symbol(struct dev_object *hdev_obj,
456 const char *str_sym, u32 * pul_value);
459 * ======== dev_get_bridge_context ========
461 * Retrieve the Bridge Context handle, as returned by the
462 * bridge_dev_create fxn.
464 * hdev_obj: Handle to device object created with dev_create_device()
465 * *phbridge_context: Ptr to location to store context handle.
468 * -EFAULT: Invalid hdev_obj.
470 * phbridge_context != NULL.
473 * 0: *phbridge_context contains context handle;
474 * else: *phbridge_context is NULL;
476 extern int dev_get_bridge_context(struct dev_object *hdev_obj,
477 struct bridge_dev_context
481 * ======== dev_exit ========
483 * Decrement reference count, and free resources when reference count is
488 * DEV is initialized.
490 * When reference count == 0, DEV's private resources are freed.
492 extern void dev_exit(void);
495 * ======== dev_init ========
497 * Initialize DEV's private state, keeping a reference count on each call.
500 * TRUE if initialized; FALSE if error occured.
503 * TRUE: A requirement for the other public DEV functions.
505 extern bool dev_init(void);
508 * ======== dev_insert_proc_object ========
510 * Inserts the Processor Object into the List of PROC Objects
511 * kept in the DEV Object
513 * proc_obj: Handle to the Proc Object
514 * hdev_obj Handle to the Dev Object
515 * bAttachedNew Specifies if there are already processors attached
517 * 0: Successfully inserted into the list
519 * proc_obj is not NULL
520 * hdev_obj is a valid handle to the DEV.
522 * List(of Proc object in Dev) Exists.
524 * 0 & the PROC Object is inserted and the list is not empty
526 * If the List of Proc Object is empty bAttachedNew is TRUE, it indicated
527 * this is the first Processor attaching.
528 * If it is False, there are already processors attached.
530 extern int dev_insert_proc_object(struct dev_object
533 bool *already_attached);
536 * ======== dev_remove_proc_object ========
538 * Search for and remove a Proc object from the given list maintained
541 * p_proc_object: Ptr to ProcObject to insert.
542 * dev_obj: Ptr to Dev Object where the list is.
543 * already_attached: Ptr to return the bool
546 * -EPERM Failure to Remove the PROC Object from the list
550 * dev_obj->proc_list != NULL
551 * !LST_IS_EMPTY(dev_obj->proc_list)
552 * already_attached !=NULL
555 * List will be deleted when the DEV is destroyed.
558 extern int dev_remove_proc_object(struct dev_object
559 *hdev_obj, u32 proc_obj);
562 * ======== dev_notify_clients ========
564 * Notify all clients of this device of a change in device status.
565 * Clients may include multiple users of BRD, as well as CHNL.
566 * This function is asychronous, and may be called by a timer event
567 * set up by a watchdog timer.
569 * hdev_obj: Handle to device object created with dev_create_device().
570 * ret: A status word, most likely a BRD_STATUS.
572 * 0: All registered clients were asynchronously notified.
573 * -EINVAL: Invalid hdev_obj.
577 * 0: Notifications are queued by the operating system to be
578 * delivered to clients. This function does not ensure that
579 * the notifications will ever be delivered.
581 extern int dev_notify_clients(struct dev_object *hdev_obj, u32 ret);
584 * ======== dev_remove_device ========
586 * Destroys the Device Object created by dev_start_device.
588 * dev_node_obj: Device node as it is know to OS.
591 * <error code> Otherwise.
595 extern int dev_remove_device(struct cfg_devnode *dev_node_obj);
598 * ======== dev_set_chnl_mgr ========
600 * Set the channel manager for this device.
602 * hdev_obj: Handle to device object created with
603 * dev_create_device().
604 * hmgr: Handle to a channel manager, or NULL.
607 * -EFAULT: Invalid hdev_obj.
612 extern int dev_set_chnl_mgr(struct dev_object *hdev_obj,
613 struct chnl_mgr *hmgr);
616 * ======== dev_set_msg_mgr ========
618 * Set the Message manager for this device.
620 * hdev_obj: Handle to device object created with dev_create_device().
621 * hmgr: Handle to a message manager, or NULL.
627 extern void dev_set_msg_mgr(struct dev_object *hdev_obj, struct msg_mgr *hmgr);
630 * ======== dev_start_device ========
632 * Initializes the new device with bridge environment. This involves
633 * querying CM for allocated resources, querying the registry for
634 * necessary dsp resources (requested in the INF file), and using this
635 * information to create a bridge device object.
637 * dev_node_obj: Device node as it is know to OS.
640 * <error code> Otherwise.
645 extern int dev_start_device(struct cfg_devnode *dev_node_obj);