4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
6 * This is the DSP API RM module interface.
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 #include <dspbridge/cfgdefs.h>
23 #include <dspbridge/devdefs.h>
24 #include <dspbridge/drv.h>
29 * ======== proc_attach ========
31 * Prepare for communication with a particular DSP processor, and return
32 * a handle to the processor object. The PROC Object gets created
34 * processor_id : The processor index (zero-based).
35 * hmgr_obj : Handle to the Manager Object
36 * attr_in : Ptr to the dsp_processorattrin structure.
37 * A NULL value means use default values.
38 * ph_processor : Ptr to location to store processor handle.
41 * -EPERM : General failure.
42 * -EFAULT : Invalid processor handle.
43 * 0: Success; Processor already attached.
45 * ph_processor != NULL.
48 * -EPERM, and *ph_processor == NULL, OR
49 * Success and *ph_processor is a Valid Processor handle OR
50 * 0 and *ph_processor is a Valid Processor.
52 * When attr_in is NULL, the default timeout value is 10 seconds.
54 extern int proc_attach(u32 processor_id,
55 const struct dsp_processorattrin
56 *attr_in, void **ph_processor,
57 struct process_context *pr_ctxt);
60 * ======== proc_auto_start =========
62 * A Particular device gets loaded with the default image
63 * if the AutoStart flag is set.
65 * hdev_obj : Handle to the Device
67 * 0 : On Successful Loading
68 * -ENOENT : No DSP exec file found.
69 * -EPERM : General Failure
72 * dev_node_obj != NULL.
76 extern int proc_auto_start(struct cfg_devnode *dev_node_obj,
77 struct dev_object *hdev_obj);
80 * ======== proc_ctrl ========
82 * Pass control information to the GPP device driver managing the DSP
83 * processor. This will be an OEM-only function, and not part of the
84 * 'Bridge application developer's API.
86 * hprocessor : The processor handle.
87 * dw_cmd : Private driver IOCTL cmd ID.
88 * pargs : Ptr to an driver defined argument structure.
91 * -EFAULT : Invalid processor handle.
92 * -ETIME: A Timeout Occurred before the Control information
94 * -EPERM : General Failure.
99 * This function Calls bridge_dev_ctrl.
101 extern int proc_ctrl(void *hprocessor,
102 u32 dw_cmd, struct dsp_cbdata *arg);
105 * ======== proc_detach ========
107 * Close a DSP processor and de-allocate all (GPP) resources reserved
108 * for it. The Processor Object is deleted.
110 * pr_ctxt : The processor handle.
113 * -EFAULT : InValid Handle.
114 * -EPERM : General failure.
118 * PROC Object is destroyed.
120 extern int proc_detach(struct process_context *pr_ctxt);
123 * ======== proc_enum_nodes ========
125 * Enumerate the nodes currently allocated on a processor.
127 * hprocessor : The processor handle.
128 * node_tab : The first Location of an array allocated for node
130 * node_tab_size: The number of (DSP_HNODE) handles that can be held
131 * to the memory the client has allocated for node_tab
132 * pu_num_nodes : Location where DSPProcessor_EnumNodes will return
133 * the number of valid handles written to node_tab
134 * pu_allocated : Location where DSPProcessor_EnumNodes will return
135 * the number of nodes that are allocated on the DSP.
138 * -EFAULT : Invalid processor handle.
139 * -EINVAL : The amount of memory allocated for node_tab is
140 * insufficent. That is the number of nodes actually
141 * allocated on the DSP is greater than the value
142 * specified for node_tab_size.
143 * -EPERM : Unable to get Resource Information.
146 * pu_num_nodes is not NULL.
147 * pu_allocated is not NULL.
148 * node_tab is not NULL.
153 extern int proc_enum_nodes(void *hprocessor,
160 * ======== proc_get_resource_info ========
162 * Enumerate the resources currently available on a processor.
164 * hprocessor : The processor handle.
165 * resource_type: Type of resource .
166 * resource_info: Ptr to the dsp_resourceinfo structure.
167 * resource_info_size: Size of the structure.
170 * -EFAULT : Invalid processor handle.
171 * -EBADR: The processor is not in the PROC_RUNNING state.
172 * -ETIME: A timeout occurred before the DSP responded to the
174 * -EPERM : Unable to get Resource Information
176 * resource_info is not NULL.
177 * Parameter resource_type is Valid.[TBD]
178 * resource_info_size is >= sizeof dsp_resourceinfo struct.
182 * This function currently returns
183 * -ENOSYS, and does not write any data to the resource_info struct.
185 extern int proc_get_resource_info(void *hprocessor,
187 struct dsp_resourceinfo
189 u32 resource_info_size);
192 * ======== proc_exit ========
194 * Decrement reference count, and free resources when reference count is
199 * PROC is initialized.
201 * When reference count == 0, PROC's private resources are freed.
203 extern void proc_exit(void);
206 * ======== proc_get_dev_object =========
208 * Returns the DEV Hanlde for a given Processor handle
210 * hprocessor : Processor Handle
211 * device_obj : Location to store the DEV Handle.
213 * 0 : Success; *device_obj has Dev handle
214 * -EPERM : Failure; *device_obj is zero.
216 * device_obj is not NULL
219 * 0 : *device_obj is not NULL
220 * -EPERM : *device_obj is NULL.
222 extern int proc_get_dev_object(void *hprocessor,
223 struct dev_object **device_obj);
226 * ======== proc_init ========
228 * Initialize PROC's private state, keeping a reference count on each
232 * TRUE if initialized; FALSE if error occurred.
235 * TRUE: A requirement for the other public PROC functions.
237 extern bool proc_init(void);
240 * ======== proc_get_state ========
242 * Report the state of the specified DSP processor.
244 * hprocessor : The processor handle.
245 * proc_state_obj : Ptr to location to store the dsp_processorstate
247 * state_info_size: Size of dsp_processorstate.
250 * -EFAULT : Invalid processor handle.
251 * -EPERM : General failure while querying processor state.
253 * proc_state_obj is not NULL
254 * state_info_size is >= than the size of dsp_processorstate structure.
259 extern int proc_get_state(void *hprocessor, struct dsp_processorstate
260 *proc_state_obj, u32 state_info_size);
263 * ======== PROC_GetProcessorID ========
265 * Report the state of the specified DSP processor.
267 * hprocessor : The processor handle.
268 * proc_id : Processor ID
272 * -EFAULT : Invalid processor handle.
273 * -EPERM : General failure while querying processor state.
275 * proc_state_obj is not NULL
276 * state_info_size is >= than the size of dsp_processorstate structure.
281 extern int proc_get_processor_id(void *proc, u32 * proc_id);
284 * ======== proc_get_trace ========
286 * Retrieve the trace buffer from the specified DSP processor.
288 * hprocessor : The processor handle.
289 * pbuf : Ptr to buffer to hold trace output.
290 * max_size : Maximum size of the output buffer.
293 * -EFAULT : Invalid processor handle.
294 * -EPERM : General failure while retireving processor trace
303 extern int proc_get_trace(void *hprocessor, u8 * pbuf, u32 max_size);
306 * ======== proc_load ========
308 * Reset a processor and load a new base program image.
309 * This will be an OEM-only function.
311 * hprocessor: The processor handle.
312 * argc_index: The number of Arguments(strings)in the aArgV[]
313 * user_args: An Array of Arguments(Unicode Strings)
314 * user_envp: An Array of Environment settings(Unicode Strings)
317 * -ENOENT: The DSP Execuetable was not found.
318 * -EFAULT: Invalid processor handle.
319 * -EPERM : Unable to Load the Processor
321 * user_args is not NULL
325 * Success and ProcState == PROC_LOADED
326 * or DSP_FAILED status.
328 * Does not implement access rights to control which GPP application
329 * can load the processor.
331 extern int proc_load(void *hprocessor,
332 const s32 argc_index, const char **user_args,
333 const char **user_envp);
336 * ======== proc_register_notify ========
338 * Register to be notified of specific processor events
340 * hprocessor : The processor handle.
341 * event_mask : Mask of types of events to be notified about.
342 * notify_type : Type of notification to be sent.
343 * hnotification: Handle to be used for notification.
346 * -EFAULT : Invalid processor handle or hnotification.
347 * -EINVAL : Parameter event_mask is Invalid
348 * DSP_ENOTIMP : The notification type specified in uNotifyMask
350 * -EPERM : Unable to register for notification.
352 * hnotification is not NULL
357 extern int proc_register_notify(void *hprocessor,
358 u32 event_mask, u32 notify_type,
359 struct dsp_notification
363 * ======== proc_notify_clients ========
365 * Notify the Processor Clients
367 * proc : The processor handle.
368 * events : Event to be notified about.
371 * -EFAULT : Invalid processor handle.
372 * -EPERM : Failure to Set or Reset the Event
374 * events is Supported or Valid type of Event
375 * proc is a valid handle
379 extern int proc_notify_clients(void *proc, u32 events);
382 * ======== proc_notify_all_clients ========
384 * Notify the Processor Clients
386 * proc : The processor handle.
387 * events : Event to be notified about.
390 * -EFAULT : Invalid processor handle.
391 * -EPERM : Failure to Set or Reset the Event
393 * events is Supported or Valid type of Event
394 * proc is a valid handle
398 * NODE And STRM would use this function to notify their clients
399 * about the state changes in NODE or STRM.
401 extern int proc_notify_all_clients(void *proc, u32 events);
404 * ======== proc_start ========
406 * Start a processor running.
407 * Processor must be in PROC_LOADED state.
408 * This will be an OEM-only function, and not part of the 'Bridge
409 * application developer's API.
411 * hprocessor : The processor handle.
414 * -EFAULT : Invalid processor handle.
415 * -EBADR: Processor is not in PROC_LOADED state.
416 * -EPERM : Unable to start the processor.
420 * Success and ProcState == PROC_RUNNING or DSP_FAILED status.
423 extern int proc_start(void *hprocessor);
426 * ======== proc_stop ========
428 * Start a processor running.
429 * Processor must be in PROC_LOADED state.
430 * This will be an OEM-only function, and not part of the 'Bridge
431 * application developer's API.
433 * hprocessor : The processor handle.
436 * -EFAULT : Invalid processor handle.
437 * -EBADR: Processor is not in PROC_LOADED state.
438 * -EPERM : Unable to start the processor.
442 * Success and ProcState == PROC_RUNNING or DSP_FAILED status.
445 extern int proc_stop(void *hprocessor);
448 * ======== proc_end_dma ========
450 * Begin a DMA transfer
452 * hprocessor : The processor handle.
453 * pmpu_addr : Buffer start address
454 * ul_size : Buffer size
455 * dir : The direction of the transfer
457 * Memory was previously mapped.
459 extern int proc_end_dma(void *hprocessor, void *pmpu_addr, u32 ul_size,
460 enum dma_data_direction dir);
462 * ======== proc_begin_dma ========
464 * Begin a DMA transfer
466 * hprocessor : The processor handle.
467 * pmpu_addr : Buffer start address
468 * ul_size : Buffer size
469 * dir : The direction of the transfer
471 * Memory was previously mapped.
473 extern int proc_begin_dma(void *hprocessor, void *pmpu_addr, u32 ul_size,
474 enum dma_data_direction dir);
477 * ======== proc_flush_memory ========
479 * Flushes a buffer from the MPU data cache.
481 * hprocessor : The processor handle.
482 * pmpu_addr : Buffer start address
483 * ul_size : Buffer size
484 * ul_flags : Reserved.
487 * -EFAULT : Invalid processor handle.
488 * -EPERM : General failure.
493 * All the arguments are currently ignored.
495 extern int proc_flush_memory(void *hprocessor,
496 void *pmpu_addr, u32 ul_size, u32 ul_flags);
499 * ======== proc_invalidate_memory ========
501 * Invalidates a buffer from the MPU data cache.
503 * hprocessor : The processor handle.
504 * pmpu_addr : Buffer start address
505 * ul_size : Buffer size
508 * -EFAULT : Invalid processor handle.
509 * -EPERM : General failure.
514 * All the arguments are currently ignored.
516 extern int proc_invalidate_memory(void *hprocessor,
517 void *pmpu_addr, u32 ul_size);
520 * ======== proc_map ========
522 * Maps a MPU buffer to DSP address space.
524 * hprocessor : The processor handle.
525 * pmpu_addr : Starting address of the memory region to map.
526 * ul_size : Size of the memory region to map.
527 * req_addr : Requested DSP start address. Offset-adjusted actual
528 * mapped address is in the last argument.
529 * pp_map_addr : Ptr to DSP side mapped u8 address.
530 * ul_map_attr : Optional endianness attributes, virt to phys flag.
533 * -EFAULT : Invalid processor handle.
534 * -EPERM : General failure.
535 * -ENOMEM : MPU side memory allocation error.
536 * -ENOENT : Cannot find a reserved region starting with this
539 * pmpu_addr is not NULL
540 * ul_size is not zero
541 * pp_map_addr is not NULL
546 extern int proc_map(void *hprocessor,
550 void **pp_map_addr, u32 ul_map_attr,
551 struct process_context *pr_ctxt);
554 * ======== proc_reserve_memory ========
556 * Reserve a virtually contiguous region of DSP address space.
558 * hprocessor : The processor handle.
559 * ul_size : Size of the address space to reserve.
560 * pp_rsv_addr : Ptr to DSP side reserved u8 address.
563 * -EFAULT : Invalid processor handle.
564 * -EPERM : General failure.
565 * -ENOMEM : Cannot reserve chunk of this size.
567 * pp_rsv_addr is not NULL
572 extern int proc_reserve_memory(void *hprocessor,
573 u32 ul_size, void **pp_rsv_addr,
574 struct process_context *pr_ctxt);
577 * ======== proc_un_map ========
579 * Removes a MPU buffer mapping from the DSP address space.
581 * hprocessor : The processor handle.
582 * map_addr : Starting address of the mapped memory region.
585 * -EFAULT : Invalid processor handle.
586 * -EPERM : General failure.
587 * -ENOENT : Cannot find a mapped region starting with this
590 * map_addr is not NULL
595 extern int proc_un_map(void *hprocessor, void *map_addr,
596 struct process_context *pr_ctxt);
599 * ======== proc_un_reserve_memory ========
601 * Frees a previously reserved region of DSP address space.
603 * hprocessor : The processor handle.
604 * prsv_addr : Ptr to DSP side reservedBYTE address.
607 * -EFAULT : Invalid processor handle.
608 * -EPERM : General failure.
609 * -ENOENT : Cannot find a reserved region starting with this
612 * prsv_addr is not NULL
617 extern int proc_un_reserve_memory(void *hprocessor,
619 struct process_context *pr_ctxt);