4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
6 * Bridge driver entry point and interface function declarations.
9 * The DSP API obtains it's function interface to
10 * the Bridge driver via a call to bridge_drv_entry().
12 * Bridge services exported to Bridge drivers are initialized by the
13 * DSP API on behalf of the Bridge driver.
15 * Bridge function DBC Requires and Ensures are also made by the DSP API on
16 * behalf of the Bridge driver, to simplify the Bridge driver code.
18 * Copyright (C) 2005-2006 Texas Instruments, Inc.
20 * This package is free software; you can redistribute it and/or modify
21 * it under the terms of the GNU General Public License version 2 as
22 * published by the Free Software Foundation.
24 * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
25 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
26 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
32 #include <dspbridge/brddefs.h>
33 #include <dspbridge/cfgdefs.h>
34 #include <dspbridge/chnlpriv.h>
35 #include <dspbridge/dehdefs.h>
36 #include <dspbridge/devdefs.h>
37 #include <dspbridge/iodefs.h>
38 #include <dspbridge/msgdefs.h>
41 * Any IOCTLS at or above this value are reserved for standard Bridge driver
44 #define BRD_RESERVEDIOCTLBASE 0x8000
46 /* Handle to Bridge driver's private device context. */
47 struct bridge_dev_context;
49 /*--------------------------------------------------------------------------- */
50 /* BRIDGE DRIVER FUNCTION TYPES */
51 /*--------------------------------------------------------------------------- */
54 * ======== bridge_brd_monitor ========
56 * Bring the board to the BRD_IDLE (monitor) state.
58 * dev_ctxt: Handle to Bridge driver defined device context.
61 * -ETIMEDOUT: Timeout occured waiting for a response from hardware.
62 * -EPERM: Other, unspecified error.
66 * 0: Board is in BRD_IDLE state;
67 * else: Board state is indeterminate.
69 typedef int(*fxn_brd_monitor) (struct bridge_dev_context *dev_ctxt);
72 * ======== fxn_brd_setstate ========
74 * Sets the Bridge driver state
76 * dev_ctxt: Handle to Bridge driver defined device info.
77 * brd_state: Board state
80 * -EPERM: Other, unspecified error.
83 * brd_state <= BRD_LASTSTATE.
85 * brd_state <= BRD_LASTSTATE.
86 * Update the Board state to the specified state.
88 typedef int(*fxn_brd_setstate) (struct bridge_dev_context
89 * dev_ctxt, u32 brd_state);
92 * ======== bridge_brd_start ========
94 * Bring board to the BRD_RUNNING (start) state.
96 * dev_ctxt: Handle to Bridge driver defined device context.
97 * dsp_addr: DSP address at which to start execution.
100 * -ETIMEDOUT: Timeout occured waiting for a response from hardware.
101 * -EPERM: Other, unspecified error.
104 * Board is in monitor (BRD_IDLE) state.
106 * 0: Board is in BRD_RUNNING state.
107 * Interrupts to the PC are enabled.
108 * else: Board state is indeterminate.
110 typedef int(*fxn_brd_start) (struct bridge_dev_context
111 * dev_ctxt, u32 dsp_addr);
114 * ======== bridge_brd_mem_copy ========
116 * Copy memory from one DSP address to another
118 * dev_context: Pointer to context handle
119 * dsp_dest_addr: DSP address to copy to
120 * dsp_src_addr: DSP address to copy from
121 * ul_num_bytes: Number of bytes to copy
122 * mem_type: What section of memory to copy to
125 * -EPERM: Other, unspecified error.
127 * dev_context != NULL
129 * 0: Board is in BRD_RUNNING state.
130 * Interrupts to the PC are enabled.
131 * else: Board state is indeterminate.
133 typedef int(*fxn_brd_memcopy) (struct bridge_dev_context
137 u32 ul_num_bytes, u32 mem_type);
139 * ======== bridge_brd_mem_write ========
141 * Write a block of host memory into a DSP address, into a given memory
142 * space. Unlike bridge_brd_write, this API does reset the DSP
144 * dev_ctxt: Handle to Bridge driver defined device info.
145 * dsp_addr: Address on DSP board (Destination).
146 * host_buf: Pointer to host buffer (Source).
147 * ul_num_bytes: Number of bytes to transfer.
148 * mem_type: Memory space on DSP to which to transfer.
151 * -ETIMEDOUT: Timeout occured waiting for a response from hardware.
152 * -EPERM: Other, unspecified error.
158 typedef int(*fxn_brd_memwrite) (struct bridge_dev_context
161 u32 dsp_addr, u32 ul_num_bytes,
165 * ======== bridge_brd_mem_map ========
167 * Map a MPU memory region to a DSP/IVA memory space
169 * dev_ctxt: Handle to Bridge driver defined device info.
170 * ul_mpu_addr: MPU memory region start address.
171 * virt_addr: DSP/IVA memory region u8 address.
172 * ul_num_bytes: Number of bytes to map.
173 * map_attrs: Mapping attributes (e.g. endianness).
176 * -EPERM: Other, unspecified error.
181 typedef int(*fxn_brd_memmap) (struct bridge_dev_context
182 * dev_ctxt, u32 ul_mpu_addr,
183 u32 virt_addr, u32 ul_num_bytes,
185 struct page **mapped_pages);
188 * ======== bridge_brd_mem_un_map ========
190 * UnMap an MPU memory region from DSP/IVA memory space
192 * dev_ctxt: Handle to Bridge driver defined device info.
193 * virt_addr: DSP/IVA memory region u8 address.
194 * ul_num_bytes: Number of bytes to unmap.
197 * -EPERM: Other, unspecified error.
202 typedef int(*fxn_brd_memunmap) (struct bridge_dev_context
204 u32 virt_addr, u32 ul_num_bytes);
207 * ======== bridge_brd_stop ========
209 * Bring board to the BRD_STOPPED state.
211 * dev_ctxt: Handle to Bridge driver defined device context.
214 * -ETIMEDOUT: Timeout occured waiting for a response from hardware.
215 * -EPERM: Other, unspecified error.
219 * 0: Board is in BRD_STOPPED (stop) state;
220 * Interrupts to the PC are disabled.
221 * else: Board state is indeterminate.
223 typedef int(*fxn_brd_stop) (struct bridge_dev_context *dev_ctxt);
226 * ======== bridge_brd_status ========
228 * Report the current state of the board.
230 * dev_ctxt: Handle to Bridge driver defined device context.
231 * board_state: Ptr to BRD status variable.
235 * board_state != NULL;
238 * *board_state is one of
239 * {BRD_STOPPED, BRD_IDLE, BRD_RUNNING, BRD_UNKNOWN};
241 typedef int(*fxn_brd_status) (struct bridge_dev_context *dev_ctxt,
245 * ======== bridge_brd_read ========
247 * Read a block of DSP memory, from a given memory space, into a host
250 * dev_ctxt: Handle to Bridge driver defined device info.
251 * host_buf: Pointer to host buffer (Destination).
252 * dsp_addr: Address on DSP board (Source).
253 * ul_num_bytes: Number of bytes to transfer.
254 * mem_type: Memory space on DSP from which to transfer.
257 * -ETIMEDOUT: Timeout occured waiting for a response from hardware.
258 * -EPERM: Other, unspecified error.
263 * Will not write more than ul_num_bytes bytes into host_buf.
265 typedef int(*fxn_brd_read) (struct bridge_dev_context *dev_ctxt,
268 u32 ul_num_bytes, u32 mem_type);
271 * ======== bridge_brd_write ========
273 * Write a block of host memory into a DSP address, into a given memory
276 * dev_ctxt: Handle to Bridge driver defined device info.
277 * dsp_addr: Address on DSP board (Destination).
278 * host_buf: Pointer to host buffer (Source).
279 * ul_num_bytes: Number of bytes to transfer.
280 * mem_type: Memory space on DSP to which to transfer.
283 * -ETIMEDOUT: Timeout occured waiting for a response from hardware.
284 * -EPERM: Other, unspecified error.
290 typedef int(*fxn_brd_write) (struct bridge_dev_context *dev_ctxt,
293 u32 ul_num_bytes, u32 mem_type);
296 * ======== bridge_chnl_create ========
298 * Create a channel manager object, responsible for opening new channels
299 * and closing old ones for a given 'Bridge board.
301 * channel_mgr: Location to store a channel manager object on output.
302 * hdev_obj: Handle to a device object.
303 * mgr_attrts: Channel manager attributes.
304 * mgr_attrts->max_channels: Max channels
305 * mgr_attrts->birq: Channel's I/O IRQ number.
306 * mgr_attrts->irq_shared: TRUE if the IRQ is shareable.
307 * mgr_attrts->word_size: DSP Word size in equivalent PC bytes..
308 * mgr_attrts->shm_base: Base physical address of shared memory, if any.
309 * mgr_attrts->usm_length: Bytes of shared memory block.
312 * -ENOMEM: Insufficient memory for requested resources.
313 * -EIO: Unable to plug ISR for given IRQ.
314 * -EFAULT: Couldn't map physical address to a virtual one.
316 * channel_mgr != NULL.
318 * mgr_attrts field are all valid:
319 * 0 < max_channels <= CHNL_MAXCHANNELS.
323 * No channel manager exists for this board.
326 typedef int(*fxn_chnl_create) (struct chnl_mgr
331 chnl_mgrattrs * mgr_attrts);
334 * ======== bridge_chnl_destroy ========
336 * Close all open channels, and destroy the channel manager.
338 * hchnl_mgr: Channel manager object.
341 * -EFAULT: hchnl_mgr was invalid.
344 * 0: Cancels I/O on each open channel. Closes each open channel.
345 * chnl_create may subsequently be called for the same device.
347 typedef int(*fxn_chnl_destroy) (struct chnl_mgr *hchnl_mgr);
349 * ======== bridge_deh_notify ========
351 * When notified of DSP error, take appropriate action.
353 * hdeh_mgr: Handle to DEH manager object.
354 * evnt_mask: Indicate the type of exception
355 * error_info: Error information
360 * evnt_mask with a valid exception
363 typedef void (*fxn_deh_notify) (struct deh_mgr *hdeh_mgr,
364 u32 evnt_mask, u32 error_info);
367 * ======== bridge_chnl_open ========
369 * Open a new half-duplex channel to the DSP board.
371 * chnl: Location to store a channel object handle.
372 * hchnl_mgr: Handle to channel manager, as returned by
374 * chnl_mode: One of {CHNL_MODETODSP, CHNL_MODEFROMDSP} specifies
375 * direction of data transfer.
376 * ch_id: If CHNL_PICKFREE is specified, the channel manager will
377 * select a free channel id (default);
378 * otherwise this field specifies the id of the channel.
379 * pattrs: Channel attributes. Attribute fields are as follows:
380 * pattrs->uio_reqs: Specifies the maximum number of I/O requests which can
381 * be pending at any given time. All request packets are
382 * preallocated when the channel is opened.
383 * pattrs->event_obj: This field allows the user to supply an auto reset
384 * event object for channel I/O completion notifications.
385 * It is the responsibility of the user to destroy this
386 * object AFTER closing the channel.
387 * This channel event object can be retrieved using
388 * CHNL_GetEventHandle().
389 * pattrs->hReserved: The kernel mode handle of this event object.
393 * -EFAULT: hchnl_mgr is invalid.
394 * -ENOMEM: Insufficient memory for requested resources.
395 * -EINVAL: Invalid number of IOReqs.
396 * -ENOSR: No free channels available.
397 * -ECHRNG: Channel ID is out of range.
398 * -EALREADY: Channel is in use.
399 * -EIO: No free IO request packets available for
404 * pattrs->event_obj is a valid event handle.
405 * pattrs->hReserved is the kernel mode handle for pattrs->event_obj.
407 * 0: *chnl is a valid channel.
408 * else: *chnl is set to NULL if (chnl != NULL);
410 typedef int(*fxn_chnl_open) (struct chnl_object
412 struct chnl_mgr *hchnl_mgr,
419 * ======== bridge_chnl_close ========
421 * Ensures all pending I/O on this channel is cancelled, discards all
422 * queued I/O completion notifications, then frees the resources allocated
423 * for this channel, and makes the corresponding logical channel id
424 * available for subsequent use.
426 * chnl_obj: Handle to a channel object.
429 * -EFAULT: Invalid chnl_obj.
431 * No thread must be blocked on this channel's I/O completion event.
433 * 0: chnl_obj is no longer valid.
435 typedef int(*fxn_chnl_close) (struct chnl_object *chnl_obj);
438 * ======== bridge_chnl_add_io_req ========
440 * Enqueue an I/O request for data transfer on a channel to the DSP.
441 * The direction (mode) is specified in the channel object. Note the DSP
442 * address is specified for channels opened in direct I/O mode.
444 * chnl_obj: Channel object handle.
445 * host_buf: Host buffer address source.
446 * byte_size: Number of PC bytes to transfer. A zero value indicates
447 * that this buffer is the last in the output channel.
448 * A zero value is invalid for an input channel.
449 *! buf_size: Actual buffer size in host bytes.
450 * dw_dsp_addr: DSP address for transfer. (Currently ignored).
451 * dw_arg: A user argument that travels with the buffer.
454 * -EFAULT: Invalid chnl_obj or host_buf.
455 * -EPERM: User cannot mark EOS on an input channel.
456 * -ECANCELED: I/O has been cancelled on this channel. No further
458 * -EPIPE: End of stream was already marked on a previous
459 * IORequest on this channel. No further I/O is expected.
460 * -EINVAL: Buffer submitted to this output channel is larger than
461 * the size of the physical shared memory output window.
464 * 0: The buffer will be transferred if the channel is ready;
465 * otherwise, will be queued for transfer when the channel becomes
466 * ready. In any case, notifications of I/O completion are
468 * If byte_size is 0 for an output channel, subsequent CHNL_AddIOReq's
469 * on this channel will fail with error code -EPIPE. The
470 * corresponding IOC for this I/O request will have its status flag
471 * set to CHNL_IOCSTATEOS.
473 typedef int(*fxn_chnl_addioreq) (struct chnl_object
478 u32 dw_dsp_addr, u32 dw_arg);
481 * ======== bridge_chnl_get_ioc ========
483 * Dequeue an I/O completion record, which contains information about the
484 * completed I/O request.
486 * chnl_obj: Channel object handle.
487 * timeout: A value of CHNL_IOCNOWAIT will simply dequeue the
488 * first available IOC.
489 * chan_ioc: On output, contains host buffer address, bytes
490 * transferred, and status of I/O completion.
491 * chan_ioc->status: See chnldefs.h.
494 * -EFAULT: Invalid chnl_obj or chan_ioc.
495 * -EREMOTEIO: CHNL_IOCNOWAIT was specified as the timeout parameter
496 * yet no I/O completions were queued.
498 * timeout == CHNL_IOCNOWAIT.
500 * 0: if there are any remaining IOC's queued before this call
501 * returns, the channel event object will be left in a signalled
504 typedef int(*fxn_chnl_getioc) (struct chnl_object *chnl_obj,
506 struct chnl_ioc *chan_ioc);
509 * ======== bridge_chnl_cancel_io ========
511 * Return all I/O requests to the client which have not yet been
512 * transferred. The channel's I/O completion object is
513 * signalled, and all the I/O requests are queued as IOC's, with the
514 * status field set to CHNL_IOCSTATCANCEL.
515 * This call is typically used in abort situations, and is a prelude to
518 * chnl_obj: Channel object handle.
521 * -EFAULT: Invalid chnl_obj.
524 * Subsequent I/O requests to this channel will not be accepted.
526 typedef int(*fxn_chnl_cancelio) (struct chnl_object *chnl_obj);
529 * ======== bridge_chnl_flush_io ========
531 * For an output stream (to the DSP), indicates if any IO requests are in
532 * the output request queue. For input streams (from the DSP), will
533 * cancel all pending IO requests.
535 * chnl_obj: Channel object handle.
536 * timeout: Timeout value for flush operation.
539 * S_CHNLIOREQUEST: Returned if any IORequests are in the output queue.
540 * -EFAULT: Invalid chnl_obj.
543 * 0: No I/O requests will be pending on this channel.
545 typedef int(*fxn_chnl_flushio) (struct chnl_object *chnl_obj,
549 * ======== bridge_chnl_get_info ========
551 * Retrieve information related to a channel.
553 * chnl_obj: Handle to a valid channel object, or NULL.
554 * channel_info: Location to store channel info.
557 * -EFAULT: Invalid chnl_obj or channel_info.
560 * 0: channel_info points to a filled in chnl_info struct,
561 * if (channel_info != NULL).
563 typedef int(*fxn_chnl_getinfo) (struct chnl_object *chnl_obj,
564 struct chnl_info *channel_info);
567 * ======== bridge_chnl_get_mgr_info ========
569 * Retrieve information related to the channel manager.
571 * hchnl_mgr: Handle to a valid channel manager, or NULL.
573 * mgr_info: Location to store channel manager info.
576 * -EFAULT: Invalid hchnl_mgr or mgr_info.
577 * -ECHRNG: Invalid channel ID.
580 * 0: mgr_info points to a filled in chnl_mgrinfo
581 * struct, if (mgr_info != NULL).
583 typedef int(*fxn_chnl_getmgrinfo) (struct chnl_mgr
586 struct chnl_mgrinfo *mgr_info);
589 * ======== bridge_chnl_idle ========
591 * Idle a channel. If this is an input channel, or if this is an output
592 * channel and flush_data is TRUE, all currently enqueued buffers will be
593 * dequeued (data discarded for output channel).
594 * If this is an output channel and flush_data is FALSE, this function
595 * will block until all currently buffered data is output, or the timeout
596 * specified has been reached.
599 * chnl_obj: Channel object handle.
600 * timeout: If output channel and flush_data is FALSE, timeout value
601 * to wait for buffers to be output. (Not used for
603 * flush_data: If output channel and flush_data is TRUE, discard any
604 * currently buffered data. If FALSE, wait for currently
605 * buffered data to be output, or timeout, whichever
606 * occurs first. flush_data is ignored for input channel.
609 * -EFAULT: Invalid chnl_obj.
610 * -ETIMEDOUT: Timeout occured before channel could be idled.
614 typedef int(*fxn_chnl_idle) (struct chnl_object *chnl_obj,
615 u32 timeout, bool flush_data);
618 * ======== bridge_chnl_register_notify ========
620 * Register for notification of events on a channel.
622 * chnl_obj: Channel object handle.
623 * event_mask: Type of events to be notified about: IO completion
624 * (DSP_STREAMIOCOMPLETION) or end of stream
626 * notify_type: DSP_SIGNALEVENT.
627 * hnotification: Handle of a dsp_notification object.
630 * -ENOMEM: Insufficient memory.
631 * -EINVAL: event_mask is 0 and hnotification was not
632 * previously registered.
633 * -EFAULT: NULL hnotification, hnotification event name
634 * too long, or hnotification event name NULL.
637 * hnotification != NULL.
638 * (event_mask & ~(DSP_STREAMIOCOMPLETION | DSP_STREAMDONE)) == 0.
639 * notify_type == DSP_SIGNALEVENT.
642 typedef int(*fxn_chnl_registernotify)
643 (struct chnl_object *chnl_obj,
644 u32 event_mask, u32 notify_type, struct dsp_notification *hnotification);
647 * ======== bridge_dev_create ========
649 * Complete creation of the device object for this board.
651 * device_ctx: Ptr to location to store a Bridge device context.
652 * hdev_obj: Handle to a Device Object, created and managed by DSP API.
653 * config_param: Ptr to configuration parameters provided by the
654 * Configuration Manager during device loading.
655 * pDspConfig: DSP resources, as specified in the registry key for this
659 * -ENOMEM: Unable to allocate memory for device context.
661 * device_ctx != NULL;
663 * config_param != NULL;
664 * pDspConfig != NULL;
665 * Fields in config_param and pDspConfig contain valid values.
667 * 0: All Bridge driver specific DSP resource and other
668 * board context has been allocated.
669 * -ENOMEM: Bridge failed to allocate resources.
670 * Any acquired resources have been freed. The DSP API
671 * will not call bridge_dev_destroy() if
672 * bridge_dev_create() fails.
674 * Called during the CONFIGMG's Device_Init phase. Based on host and
675 * DSP configuration information, create a board context, a handle to
676 * which is passed into other Bridge BRD and CHNL functions. The
677 * board context contains state information for the device. Since the
678 * addresses of all pointer parameters may be invalid when this
679 * function returns, they must not be stored into the device context
682 typedef int(*fxn_dev_create) (struct bridge_dev_context
690 * ======== bridge_dev_ctrl ========
692 * Bridge driver specific interface.
694 * dev_ctxt: Handle to Bridge driver defined device info.
695 * dw_cmd: Bridge driver defined command code.
696 * pargs: Pointer to an arbitrary argument structure.
698 * 0 or -EPERM. Actual command error codes should be passed back in
699 * the pargs structure, and are defined by the Bridge driver implementor.
701 * All calls are currently assumed to be synchronous. There are no
702 * IOCTL completion routines provided.
705 typedef int(*fxn_dev_ctrl) (struct bridge_dev_context *dev_ctxt,
706 u32 dw_cmd, void *pargs);
709 * ======== bridge_dev_destroy ========
711 * Deallocate Bridge device extension structures and all other resources
712 * acquired by the Bridge driver.
713 * No calls to other Bridge driver functions may subsequently
714 * occur, except for bridge_dev_create().
716 * dev_ctxt: Handle to Bridge driver defined device information.
719 * -EPERM: Failed to release a resource previously acquired.
723 * 0: Device context is freed.
725 typedef int(*fxn_dev_destroy) (struct bridge_dev_context *dev_ctxt);
728 * ======== bridge_io_create ========
730 * Create an object that manages I/O between CHNL and msg_ctrl.
732 * io_man: Location to store IO manager on output.
733 * hchnl_mgr: Handle to channel manager.
734 * hmsg_mgr: Handle to message manager.
737 * -ENOMEM: Memory allocation failure.
738 * -EPERM: Creation failed.
741 * Channel manager already created;
742 * Message manager already created;
743 * mgr_attrts != NULL;
747 typedef int(*fxn_io_create) (struct io_mgr **io_man,
748 struct dev_object *hdev_obj,
749 const struct io_attrs *mgr_attrts);
752 * ======== bridge_io_destroy ========
754 * Destroy object created in bridge_io_create.
756 * hio_mgr: IO Manager.
759 * -ENOMEM: Memory allocation failure.
760 * -EPERM: Creation failed.
765 typedef int(*fxn_io_destroy) (struct io_mgr *hio_mgr);
768 * ======== bridge_io_on_loaded ========
770 * Called whenever a program is loaded to update internal data. For
771 * example, if shared memory is used, this function would update the
772 * shared memory location and address.
774 * hio_mgr: IO Manager.
777 * -EPERM: Internal failure occurred.
782 typedef int(*fxn_io_onloaded) (struct io_mgr *hio_mgr);
785 * ======== fxn_io_getprocload ========
787 * Called to get the Processor's current and predicted load
789 * hio_mgr: IO Manager.
790 * proc_load_stat Processor Load statistics
793 * -EPERM: Internal failure occurred.
798 typedef int(*fxn_io_getprocload) (struct io_mgr *hio_mgr,
799 struct dsp_procloadstat *
803 * ======== bridge_msg_create ========
805 * Create an object to manage message queues. Only one of these objects
806 * can exist per device object.
808 * msg_man: Location to store msg_ctrl manager on output.
809 * hdev_obj: Handle to a device object.
810 * msg_callback: Called whenever an RMS_EXIT message is received.
813 * -ENOMEM: Insufficient memory.
816 * msg_callback != NULL.
820 typedef int(*fxn_msg_create)
821 (struct msg_mgr **msg_man,
822 struct dev_object *hdev_obj, msg_onexit msg_callback);
825 * ======== bridge_msg_create_queue ========
827 * Create a msg_ctrl queue for sending or receiving messages from a Message
830 * hmsg_mgr: msg_ctrl queue manager handle returned from
832 * msgq: Location to store msg_ctrl queue on output.
833 * msgq_id: Identifier for messages (node environment pointer).
834 * max_msgs: Max number of simultaneous messages for the node.
835 * h: Handle passed to hmsg_mgr->msg_callback().
838 * -ENOMEM: Insufficient memory.
844 * msgq !=NULL <==> 0.
846 typedef int(*fxn_msg_createqueue)
847 (struct msg_mgr *hmsg_mgr,
848 struct msg_queue **msgq, u32 msgq_id, u32 max_msgs, void *h);
851 * ======== bridge_msg_delete ========
853 * Delete a msg_ctrl manager allocated in bridge_msg_create().
855 * hmsg_mgr: Handle returned from bridge_msg_create().
861 typedef void (*fxn_msg_delete) (struct msg_mgr *hmsg_mgr);
864 * ======== bridge_msg_delete_queue ========
866 * Delete a msg_ctrl queue allocated in bridge_msg_create_queue.
868 * msg_queue_obj: Handle to msg_ctrl queue returned from
869 * bridge_msg_create_queue.
872 * Valid msg_queue_obj.
875 typedef void (*fxn_msg_deletequeue) (struct msg_queue *msg_queue_obj);
878 * ======== bridge_msg_get ========
880 * Get a message from a msg_ctrl queue.
882 * msg_queue_obj: Handle to msg_ctrl queue returned from
883 * bridge_msg_create_queue.
884 * pmsg: Location to copy message into.
885 * utimeout: Timeout to wait for a message.
888 * -ETIME: Timeout occurred.
889 * -EPERM: No frames available for message (max_msgs too
892 * Valid msg_queue_obj.
896 typedef int(*fxn_msg_get) (struct msg_queue *msg_queue_obj,
897 struct dsp_msg *pmsg, u32 utimeout);
900 * ======== bridge_msg_put ========
902 * Put a message onto a msg_ctrl queue.
904 * msg_queue_obj: Handle to msg_ctrl queue returned from
905 * bridge_msg_create_queue.
906 * pmsg: Pointer to message.
907 * utimeout: Timeout to wait for a message.
910 * -ETIME: Timeout occurred.
911 * -EPERM: No frames available for message (max_msgs too
914 * Valid msg_queue_obj.
918 typedef int(*fxn_msg_put) (struct msg_queue *msg_queue_obj,
919 const struct dsp_msg *pmsg, u32 utimeout);
922 * ======== bridge_msg_register_notify ========
924 * Register notification for when a message is ready.
926 * msg_queue_obj: Handle to msg_ctrl queue returned from
927 * bridge_msg_create_queue.
928 * event_mask: Type of events to be notified about: Must be
929 * DSP_NODEMESSAGEREADY, or 0 to unregister.
930 * notify_type: DSP_SIGNALEVENT.
931 * hnotification: Handle of notification object.
934 * -ENOMEM: Insufficient memory.
936 * Valid msg_queue_obj.
937 * hnotification != NULL.
938 * notify_type == DSP_SIGNALEVENT.
939 * event_mask == DSP_NODEMESSAGEREADY || event_mask == 0.
942 typedef int(*fxn_msg_registernotify)
943 (struct msg_queue *msg_queue_obj,
944 u32 event_mask, u32 notify_type, struct dsp_notification *hnotification);
947 * ======== bridge_msg_set_queue_id ========
949 * Set message queue id to node environment. Allows bridge_msg_create_queue
950 * to be called in node_allocate, before the node environment is known.
952 * msg_queue_obj: Handle to msg_ctrl queue returned from
953 * bridge_msg_create_queue.
954 * msgq_id: Node environment pointer.
957 * Valid msg_queue_obj.
961 typedef void (*fxn_msg_setqueueid) (struct msg_queue *msg_queue_obj,
965 * Bridge Driver interface function table.
967 * The information in this table is filled in by the specific Bridge driver,
968 * and copied into the DSP API's own space. If any interface
969 * function field is set to a value of NULL, then the DSP API will
970 * consider that function not implemented, and return the error code
971 * -ENOSYS when a Bridge driver client attempts to call that function.
973 * This function table contains DSP API version numbers, which are used by the
974 * Bridge driver loader to help ensure backwards compatility between older
975 * Bridge drivers and newer DSP API. These must be set to
976 * BRD_API_MAJOR_VERSION and BRD_API_MINOR_VERSION, respectively.
978 * A Bridge driver need not export a CHNL interface. In this case, *all* of
979 * the bridge_chnl_* entries must be set to NULL.
981 struct bridge_drv_interface {
982 u32 brd_api_major_version; /* Set to BRD_API_MAJOR_VERSION. */
983 u32 brd_api_minor_version; /* Set to BRD_API_MINOR_VERSION. */
984 fxn_dev_create pfn_dev_create; /* Create device context */
985 fxn_dev_destroy pfn_dev_destroy; /* Destroy device context */
986 fxn_dev_ctrl pfn_dev_cntrl; /* Optional vendor interface */
987 fxn_brd_monitor pfn_brd_monitor; /* Load and/or start monitor */
988 fxn_brd_start pfn_brd_start; /* Start DSP program. */
989 fxn_brd_stop pfn_brd_stop; /* Stop/reset board. */
990 fxn_brd_status pfn_brd_status; /* Get current board status. */
991 fxn_brd_read pfn_brd_read; /* Read board memory */
992 fxn_brd_write pfn_brd_write; /* Write board memory. */
993 fxn_brd_setstate pfn_brd_set_state; /* Sets the Board State */
994 fxn_brd_memcopy pfn_brd_mem_copy; /* Copies DSP Memory */
995 fxn_brd_memwrite pfn_brd_mem_write; /* Write DSP Memory w/o halt */
996 fxn_brd_memmap pfn_brd_mem_map; /* Maps MPU mem to DSP mem */
997 fxn_brd_memunmap pfn_brd_mem_un_map; /* Unmaps MPU mem to DSP mem */
998 fxn_chnl_create pfn_chnl_create; /* Create channel manager. */
999 fxn_chnl_destroy pfn_chnl_destroy; /* Destroy channel manager. */
1000 fxn_chnl_open pfn_chnl_open; /* Create a new channel. */
1001 fxn_chnl_close pfn_chnl_close; /* Close a channel. */
1002 fxn_chnl_addioreq pfn_chnl_add_io_req; /* Req I/O on a channel. */
1003 fxn_chnl_getioc pfn_chnl_get_ioc; /* Wait for I/O completion. */
1004 fxn_chnl_cancelio pfn_chnl_cancel_io; /* Cancl I/O on a channel. */
1005 fxn_chnl_flushio pfn_chnl_flush_io; /* Flush I/O. */
1006 fxn_chnl_getinfo pfn_chnl_get_info; /* Get channel specific info */
1007 /* Get channel manager info. */
1008 fxn_chnl_getmgrinfo pfn_chnl_get_mgr_info;
1009 fxn_chnl_idle pfn_chnl_idle; /* Idle the channel */
1010 /* Register for notif. */
1011 fxn_chnl_registernotify pfn_chnl_register_notify;
1012 fxn_io_create pfn_io_create; /* Create IO manager */
1013 fxn_io_destroy pfn_io_destroy; /* Destroy IO manager */
1014 fxn_io_onloaded pfn_io_on_loaded; /* Notify of program loaded */
1015 /* Get Processor's current and predicted load */
1016 fxn_io_getprocload pfn_io_get_proc_load;
1017 fxn_msg_create pfn_msg_create; /* Create message manager */
1018 /* Create message queue */
1019 fxn_msg_createqueue pfn_msg_create_queue;
1020 fxn_msg_delete pfn_msg_delete; /* Delete message manager */
1021 /* Delete message queue */
1022 fxn_msg_deletequeue pfn_msg_delete_queue;
1023 fxn_msg_get pfn_msg_get; /* Get a message */
1024 fxn_msg_put pfn_msg_put; /* Send a message */
1025 /* Register for notif. */
1026 fxn_msg_registernotify pfn_msg_register_notify;
1027 /* Set message queue id */
1028 fxn_msg_setqueueid pfn_msg_set_queue_id;
1032 * ======== bridge_drv_entry ========
1034 * Registers Bridge driver functions with the DSP API. Called only once
1035 * by the DSP API. The caller will first check DSP API version
1036 * compatibility, and then copy the interface functions into its own
1039 * drv_intf Pointer to a location to receive a pointer to the
1040 * Bridge driver interface.
1043 * The code segment this function resides in must expect to be discarded
1046 * drv_intf pointer initialized to Bridge driver's function
1047 * interface. No system resources are acquired by this function.
1049 * Called during the Device_Init phase.
1051 void bridge_drv_entry(struct bridge_drv_interface **drv_intf,
1052 const char *driver_file_name);
1054 #endif /* DSPDEFS_ */