diff options
Diffstat (limited to 'drivers/staging/tidspbridge/include/dspbridge/dspdefs.h')
| -rw-r--r-- | drivers/staging/tidspbridge/include/dspbridge/dspdefs.h | 1048 |
1 files changed, 0 insertions, 1048 deletions
diff --git a/drivers/staging/tidspbridge/include/dspbridge/dspdefs.h b/drivers/staging/tidspbridge/include/dspbridge/dspdefs.h deleted file mode 100644 index ed32bf383132..000000000000 --- a/drivers/staging/tidspbridge/include/dspbridge/dspdefs.h +++ /dev/null @@ -1,1048 +0,0 @@ -/* - * dspdefs.h - * - * DSP-BIOS Bridge driver support functions for TI OMAP processors. - * - * Bridge driver entry point and interface function declarations. - * - * Notes: - * The DSP API obtains it's function interface to - * the Bridge driver via a call to bridge_drv_entry(). - * - * Bridge services exported to Bridge drivers are initialized by the - * DSP API on behalf of the Bridge driver. - * - * Bridge function DBC Requires and Ensures are also made by the DSP API on - * behalf of the Bridge driver, to simplify the Bridge driver code. - * - * 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 DSPDEFS_ -#define DSPDEFS_ - -#include <dspbridge/brddefs.h> -#include <dspbridge/cfgdefs.h> -#include <dspbridge/chnlpriv.h> -#include <dspbridge/dspdeh.h> -#include <dspbridge/devdefs.h> -#include <dspbridge/io.h> -#include <dspbridge/msgdefs.h> - -/* Handle to Bridge driver's private device context. */ -struct bridge_dev_context; - -/*--------------------------------------------------------------------------- */ -/* BRIDGE DRIVER FUNCTION TYPES */ -/*--------------------------------------------------------------------------- */ - -/* - * ======== bridge_brd_monitor ======== - * Purpose: - * Bring the board to the BRD_IDLE (monitor) state. - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device context. - * Returns: - * 0: Success. - * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL - * Ensures: - * 0: Board is in BRD_IDLE state; - * else: Board state is indeterminate. - */ -typedef int(*fxn_brd_monitor) (struct bridge_dev_context *dev_ctxt); - -/* - * ======== fxn_brd_setstate ======== - * Purpose: - * Sets the Bridge driver state - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device info. - * brd_state: Board state - * Returns: - * 0: Success. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL; - * brd_state <= BRD_LASTSTATE. - * Ensures: - * brd_state <= BRD_LASTSTATE. - * Update the Board state to the specified state. - */ -typedef int(*fxn_brd_setstate) (struct bridge_dev_context - * dev_ctxt, u32 brd_state); - -/* - * ======== bridge_brd_start ======== - * Purpose: - * Bring board to the BRD_RUNNING (start) state. - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device context. - * dsp_addr: DSP address at which to start execution. - * Returns: - * 0: Success. - * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL - * Board is in monitor (BRD_IDLE) state. - * Ensures: - * 0: Board is in BRD_RUNNING state. - * Interrupts to the PC are enabled. - * else: Board state is indeterminate. - */ -typedef int(*fxn_brd_start) (struct bridge_dev_context - * dev_ctxt, u32 dsp_addr); - -/* - * ======== bridge_brd_mem_copy ======== - * Purpose: - * Copy memory from one DSP address to another - * Parameters: - * dev_context: Pointer to context handle - * dsp_dest_addr: DSP address to copy to - * dsp_src_addr: DSP address to copy from - * ul_num_bytes: Number of bytes to copy - * mem_type: What section of memory to copy to - * Returns: - * 0: Success. - * -EPERM: Other, unspecified error. - * Requires: - * dev_context != NULL - * Ensures: - * 0: Board is in BRD_RUNNING state. - * Interrupts to the PC are enabled. - * else: Board state is indeterminate. - */ -typedef int(*fxn_brd_memcopy) (struct bridge_dev_context - * dev_ctxt, - u32 dsp_dest_addr, - u32 dsp_src_addr, - u32 ul_num_bytes, u32 mem_type); -/* - * ======== bridge_brd_mem_write ======== - * Purpose: - * Write a block of host memory into a DSP address, into a given memory - * space. Unlike bridge_brd_write, this API does reset the DSP - * Parameters: - * 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: - * 0: Success. - * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL; - * host_buf != NULL. - * Ensures: - */ -typedef int(*fxn_brd_memwrite) (struct bridge_dev_context - * dev_ctxt, - u8 *host_buf, - u32 dsp_addr, u32 ul_num_bytes, - u32 mem_type); - -/* - * ======== bridge_brd_mem_map ======== - * Purpose: - * Map a MPU memory region to a DSP/IVA memory space - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device info. - * ul_mpu_addr: MPU memory region start address. - * virt_addr: DSP/IVA memory region u8 address. - * ul_num_bytes: Number of bytes to map. - * map_attrs: Mapping attributes (e.g. endianness). - * Returns: - * 0: Success. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL; - * Ensures: - */ -typedef int(*fxn_brd_memmap) (struct bridge_dev_context - * dev_ctxt, u32 ul_mpu_addr, - u32 virt_addr, u32 ul_num_bytes, - u32 map_attr, - struct page **mapped_pages); - -/* - * ======== bridge_brd_mem_un_map ======== - * Purpose: - * UnMap an MPU memory region from DSP/IVA memory space - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device info. - * virt_addr: DSP/IVA memory region u8 address. - * ul_num_bytes: Number of bytes to unmap. - * Returns: - * 0: Success. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL; - * Ensures: - */ -typedef int(*fxn_brd_memunmap) (struct bridge_dev_context - * dev_ctxt, - u32 virt_addr, u32 ul_num_bytes); - -/* - * ======== bridge_brd_stop ======== - * Purpose: - * Bring board to the BRD_STOPPED state. - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device context. - * Returns: - * 0: Success. - * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL - * Ensures: - * 0: Board is in BRD_STOPPED (stop) state; - * Interrupts to the PC are disabled. - * else: Board state is indeterminate. - */ -typedef int(*fxn_brd_stop) (struct bridge_dev_context *dev_ctxt); - -/* - * ======== bridge_brd_status ======== - * Purpose: - * Report the current state of the board. - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device context. - * board_state: Ptr to BRD status variable. - * Returns: - * 0: - * Requires: - * board_state != NULL; - * dev_ctxt != NULL - * Ensures: - * *board_state is one of - * {BRD_STOPPED, BRD_IDLE, BRD_RUNNING, BRD_UNKNOWN}; - */ -typedef int(*fxn_brd_status) (struct bridge_dev_context *dev_ctxt, - int *board_state); - -/* - * ======== bridge_brd_read ======== - * Purpose: - * Read a block of DSP memory, from a given memory space, into a host - * buffer. - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device info. - * host_buf: Pointer to host buffer (Destination). - * dsp_addr: Address on DSP board (Source). - * ul_num_bytes: Number of bytes to transfer. - * mem_type: Memory space on DSP from which to transfer. - * Returns: - * 0: Success. - * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL; - * host_buf != NULL. - * Ensures: - * Will not write more than ul_num_bytes bytes into host_buf. - */ -typedef int(*fxn_brd_read) (struct bridge_dev_context *dev_ctxt, - u8 *host_buf, - u32 dsp_addr, - u32 ul_num_bytes, u32 mem_type); - -/* - * ======== bridge_brd_write ======== - * Purpose: - * Write a block of host memory into a DSP address, into a given memory - * space. - * Parameters: - * 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: - * 0: Success. - * -ETIMEDOUT: Timeout occurred waiting for a response from hardware. - * -EPERM: Other, unspecified error. - * Requires: - * dev_ctxt != NULL; - * host_buf != NULL. - * Ensures: - */ -typedef int(*fxn_brd_write) (struct bridge_dev_context *dev_ctxt, - u8 *host_buf, - u32 dsp_addr, - u32 ul_num_bytes, u32 mem_type); - -/* - * ======== bridge_chnl_create ======== - * Purpose: - * Create a channel manager object, responsible for opening new channels - * and closing old ones for a given 'Bridge board. - * Parameters: - * channel_mgr: Location to store a channel manager object on output. - * hdev_obj: Handle to a device object. - * mgr_attrts: Channel manager attributes. - * mgr_attrts->max_channels: Max channels - * mgr_attrts->birq: Channel's I/O IRQ number. - * mgr_attrts->irq_shared: TRUE if the IRQ is shareable. - * mgr_attrts->word_size: DSP Word size in equivalent PC bytes.. - * mgr_attrts->shm_base: Base physical address of shared memory, if any. - * mgr_attrts->sm_length: Bytes of shared memory block. - * Returns: - * 0: Success; - * -ENOMEM: Insufficient memory for requested resources. - * -EIO: Unable to plug ISR for given IRQ. - * -EFAULT: Couldn't map physical address to a virtual one. - * Requires: - * channel_mgr != NULL. - * mgr_attrts != NULL - * mgr_attrts field are all valid: - * 0 < max_channels <= CHNL_MAXCHANNELS. - * birq <= 15. - * word_size > 0. - * hdev_obj != NULL - * No channel manager exists for this board. - * Ensures: - */ -typedef int(*fxn_chnl_create) (struct chnl_mgr - **channel_mgr, - struct dev_object - * hdev_obj, - const struct - chnl_mgrattrs * mgr_attrts); - -/* - * ======== bridge_chnl_destroy ======== - * Purpose: - * Close all open channels, and destroy the channel manager. - * Parameters: - * hchnl_mgr: Channel manager object. - * Returns: - * 0: Success. - * -EFAULT: hchnl_mgr was invalid. - * Requires: - * Ensures: - * 0: Cancels I/O on each open channel. Closes each open channel. - * chnl_create may subsequently be called for the same device. - */ -typedef int(*fxn_chnl_destroy) (struct chnl_mgr *hchnl_mgr); -/* - * ======== bridge_deh_notify ======== - * Purpose: - * When notified of DSP error, take appropriate action. - * Parameters: - * hdeh_mgr: Handle to DEH manager object. - * evnt_mask: Indicate the type of exception - * error_info: Error information - * Returns: - * - * Requires: - * hdeh_mgr != NULL; - * evnt_mask with a valid exception - * Ensures: - */ -typedef void (*fxn_deh_notify) (struct deh_mgr *hdeh_mgr, - u32 evnt_mask, u32 error_info); - -/* - * ======== bridge_chnl_open ======== - * Purpose: - * Open a new half-duplex channel to the DSP board. - * Parameters: - * chnl: Location to store a channel object handle. - * hchnl_mgr: Handle to channel manager, as returned by - * CHNL_GetMgr(). - * chnl_mode: One of {CHNL_MODETODSP, CHNL_MODEFROMDSP} specifies - * direction of data transfer. - * ch_id: If CHNL_PICKFREE is specified, the channel manager will - * select a free channel id (default); - * otherwise this field specifies the id of the channel. - * pattrs: Channel attributes. Attribute fields are as follows: - * pattrs->uio_reqs: Specifies the maximum number of I/O requests which can - * be pending at any given time. All request packets are - * preallocated when the channel is opened. - * pattrs->event_obj: This field allows the user to supply an auto reset - * event object for channel I/O completion notifications. - * It is the responsibility of the user to destroy this - * object AFTER closing the channel. - * This channel event object can be retrieved using - * CHNL_GetEventHandle(). - * pattrs->hReserved: The kernel mode handle of this event object. - * - * Returns: - * 0: Success. - * -EFAULT: hchnl_mgr is invalid. - * -ENOMEM: Insufficient memory for requested resources. - * -EINVAL: Invalid number of IOReqs. - * -ENOSR: No free channels available. - * -ECHRNG: Channel ID is out of range. - * -EALREADY: Channel is in use. - * -EIO: No free IO request packets available for - * queuing. - * Requires: - * chnl != NULL. - * pattrs != NULL. - * pattrs->event_obj is a valid event handle. - * pattrs->hReserved is the kernel mode handle for pattrs->event_obj. - * Ensures: - * 0: *chnl is a valid channel. - * else: *chnl is set to NULL if (chnl != NULL); - */ -typedef int(*fxn_chnl_open) (struct chnl_object - **chnl, - struct chnl_mgr *hchnl_mgr, - s8 chnl_mode, - u32 ch_id, - const struct - chnl_attr * pattrs); - -/* - * ======== bridge_chnl_close ======== - * Purpose: - * Ensures all pending I/O on this channel is cancelled, discards all - * queued I/O completion notifications, then frees the resources allocated - * for this channel, and makes the corresponding logical channel id - * available for subsequent use. - * Parameters: - * chnl_obj: Handle to a channel object. - * Returns: - * 0: Success; - * -EFAULT: Invalid chnl_obj. - * Requires: - * No thread must be blocked on this channel's I/O completion event. - * Ensures: - * 0: chnl_obj is no longer valid. - */ -typedef int(*fxn_chnl_close) (struct chnl_object *chnl_obj); - -/* - * ======== bridge_chnl_add_io_req ======== - * Purpose: - * Enqueue an I/O request for data transfer on a channel to the DSP. - * The direction (mode) is specified in the channel object. Note the DSP - * address is specified for channels opened in direct I/O mode. - * Parameters: - * chnl_obj: Channel object handle. - * host_buf: Host buffer address source. - * byte_size: Number of PC bytes to transfer. A zero value indicates - * that this buffer is the last in the output channel. - * A zero value is invalid for an input channel. - *! buf_size: Actual buffer size in host bytes. - * dw_dsp_addr: DSP address for transfer. (Currently ignored). - * dw_arg: A user argument that travels with the buffer. - * Returns: - * 0: Success; - * -EFAULT: Invalid chnl_obj or host_buf. - * -EPERM: User cannot mark EOS on an input channel. - * -ECANCELED: I/O has been cancelled on this channel. No further - * I/O is allowed. - * -EPIPE: End of stream was already marked on a previous - * IORequest on this channel. No further I/O is expected. - * -EINVAL: Buffer submitted to this output channel is larger than - * the size of the physical shared memory output window. - * Requires: - * Ensures: - * 0: The buffer will be transferred if the channel is ready; - * otherwise, will be queued for transfer when the channel becomes - * ready. In any case, notifications of I/O completion are - * asynchronous. - * If byte_size is 0 for an output channel, subsequent CHNL_AddIOReq's - * on this channel will fail with error code -EPIPE. The - * corresponding IOC for this I/O request will have its status flag - * set to CHNL_IOCSTATEOS. - */ -typedef int(*fxn_chnl_addioreq) (struct chnl_object - * chnl_obj, - void *host_buf, - u32 byte_size, - u32 buf_size, - u32 dw_dsp_addr, u32 dw_arg); - -/* - * ======== bridge_chnl_get_ioc ======== - * Purpose: - * Dequeue an I/O completion record, which contains information about the - * completed I/O request. - * Parameters: - * chnl_obj: Channel object handle. - * timeout: A value of CHNL_IOCNOWAIT will simply dequeue the - * first available IOC. - * chan_ioc: On output, contains host buffer address, bytes - * transferred, and status of I/O completion. - * chan_ioc->status: See chnldefs.h. - * Returns: - * 0: Success. - * -EFAULT: Invalid chnl_obj or chan_ioc. - * -EREMOTEIO: CHNL_IOCNOWAIT was specified as the timeout parameter - * yet no I/O completions were queued. - * Requires: - * timeout == CHNL_IOCNOWAIT. - * Ensures: - * 0: if there are any remaining IOC's queued before this call - * returns, the channel event object will be left in a signalled - * state. - */ -typedef int(*fxn_chnl_getioc) (struct chnl_object *chnl_obj, - u32 timeout, - struct chnl_ioc *chan_ioc); - -/* - * ======== bridge_chnl_cancel_io ======== - * Purpose: - * Return all I/O requests to the client which have not yet been - * transferred. The channel's I/O completion object is - * signalled, and all the I/O requests are queued as IOC's, with the - * status field set to CHNL_IOCSTATCANCEL. - * This call is typically used in abort situations, and is a prelude to - * chnl_close(); - * Parameters: - * chnl_obj: Channel object handle. - * Returns: - * 0: Success; - * -EFAULT: Invalid chnl_obj. - * Requires: - * Ensures: - * Subsequent I/O requests to this channel will not be accepted. - */ -typedef int(*fxn_chnl_cancelio) (struct chnl_object *chnl_obj); - -/* - * ======== bridge_chnl_flush_io ======== - * Purpose: - * For an output stream (to the DSP), indicates if any IO requests are in - * the output request queue. For input streams (from the DSP), will - * cancel all pending IO requests. - * Parameters: - * chnl_obj: Channel object handle. - * timeout: Timeout value for flush operation. - * Returns: - * 0: Success; - * S_CHNLIOREQUEST: Returned if any IORequests are in the output queue. - * -EFAULT: Invalid chnl_obj. - * Requires: - * Ensures: - * 0: No I/O requests will be pending on this channel. - */ -typedef int(*fxn_chnl_flushio) (struct chnl_object *chnl_obj, - u32 timeout); - -/* - * ======== bridge_chnl_get_info ======== - * Purpose: - * Retrieve information related to a channel. - * Parameters: - * chnl_obj: Handle to a valid channel object, or NULL. - * channel_info: Location to store channel info. - * Returns: - * 0: Success; - * -EFAULT: Invalid chnl_obj or channel_info. - * Requires: - * Ensures: - * 0: channel_info points to a filled in chnl_info struct, - * if (channel_info != NULL). - */ -typedef int(*fxn_chnl_getinfo) (struct chnl_object *chnl_obj, - struct chnl_info *channel_info); - -/* - * ======== bridge_chnl_get_mgr_info ======== - * Purpose: - * Retrieve information related to the channel manager. - * Parameters: - * hchnl_mgr: Handle to a valid channel manager, or NULL. - * ch_id: Channel ID. - * mgr_info: Location to store channel manager info. - * Returns: - * 0: Success; - * -EFAULT: Invalid hchnl_mgr or mgr_info. - * -ECHRNG: Invalid channel ID. - * Requires: - * Ensures: - * 0: mgr_info points to a filled in chnl_mgrinfo - * struct, if (mgr_info != NULL). - */ -typedef int(*fxn_chnl_getmgrinfo) (struct chnl_mgr - * hchnl_mgr, - u32 ch_id, - struct chnl_mgrinfo *mgr_info); - -/* - * ======== bridge_chnl_idle ======== - * Purpose: - * Idle a channel. If this is an input channel, or if this is an output - * channel and flush_data is TRUE, all currently enqueued buffers will be - * dequeued (data discarded for output channel). - * If this is an output channel and flush_data is FALSE, this function - * will block until all currently buffered data is output, or the timeout - * specified has been reached. - * - * Parameters: - * chnl_obj: Channel object handle. - * timeout: If output channel and flush_data is FALSE, timeout value - * to wait for buffers to be output. (Not used for - * input channel). - * flush_data: If output channel and flush_data is TRUE, discard any - * currently buffered data. If FALSE, wait for currently - * buffered data to be output, or timeout, whichever - * occurs first. flush_data is ignored for input channel. - * Returns: - * 0: Success; - * -EFAULT: Invalid chnl_obj. - * -ETIMEDOUT: Timeout occurred before channel could be idled. - * Requires: - * Ensures: - */ -typedef int(*fxn_chnl_idle) (struct chnl_object *chnl_obj, - u32 timeout, bool flush_data); - -/* - * ======== bridge_chnl_register_notify ======== - * Purpose: - * Register for notification of events on a channel. - * Parameters: - * chnl_obj: Channel object handle. - * event_mask: Type of events to be notified about: IO completion - * (DSP_STREAMIOCOMPLETION) or end of stream - * (DSP_STREAMDONE). - * notify_type: DSP_SIGNALEVENT. - * hnotification: Handle of a dsp_notification object. - * Returns: - * 0: Success. - * -ENOMEM: Insufficient memory. - * -EINVAL: event_mask is 0 and hnotification was not - * previously registered. - * -EFAULT: NULL hnotification, hnotification event name - * too long, or hnotification event name NULL. - * Requires: - * Valid chnl_obj. - * hnotification != NULL. - * (event_mask & ~(DSP_STREAMIOCOMPLETION | DSP_STREAMDONE)) == 0. - * notify_type == DSP_SIGNALEVENT. - * Ensures: - */ -typedef int(*fxn_chnl_registernotify) - (struct chnl_object *chnl_obj, - u32 event_mask, u32 notify_type, struct dsp_notification *hnotification); - -/* - * ======== bridge_dev_create ======== - * Purpose: - * Complete creation of the device object for this board. - * Parameters: - * device_ctx: Ptr to location to store a Bridge device context. - * hdev_obj: Handle to a Device Object, created and managed by DSP API. - * config_param: Ptr to configuration parameters provided by the - * Configuration Manager during device loading. - * pDspConfig: DSP resources, as specified in the registry key for this - * device. - * Returns: - * 0: Success. - * -ENOMEM: Unable to allocate memory for device context. - * Requires: - * device_ctx != NULL; - * hdev_obj != NULL; - * config_param != NULL; - * pDspConfig != NULL; - * Fields in config_param and pDspConfig contain valid values. - * Ensures: - * 0: All Bridge driver specific DSP resource and other - * board context has been allocated. - * -ENOMEM: Bridge failed to allocate resources. - * Any acquired resources have been freed. The DSP API - * will not call bridge_dev_destroy() if - * bridge_dev_create() fails. - * Details: - * Called during the CONFIGMG's Device_Init phase. Based on host and - * DSP configuration information, create a board context, a handle to - * which is passed into other Bridge BRD and CHNL functions. The - * board context contains state information for the device. Since the - * addresses of all pointer parameters may be invalid when this - * function returns, they must not be stored into the device context - * structure. - */ -typedef int(*fxn_dev_create) (struct bridge_dev_context - **device_ctx, - struct dev_object - * hdev_obj, - struct cfg_hostres - * config_param); - -/* - * ======== bridge_dev_ctrl ======== - * Purpose: - * Bridge driver specific interface. - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device info. - * dw_cmd: Bridge driver defined command code. - * pargs: Pointer to an arbitrary argument structure. - * Returns: - * 0 or -EPERM. Actual command error codes should be passed back in - * the pargs structure, and are defined by the Bridge driver implementor. - * Requires: - * All calls are currently assumed to be synchronous. There are no - * IOCTL completion routines provided. - * Ensures: - */ -typedef int(*fxn_dev_ctrl) (struct bridge_dev_context *dev_ctxt, - u32 dw_cmd, void *pargs); - -/* - * ======== bridge_dev_destroy ======== - * Purpose: - * Deallocate Bridge device extension structures and all other resources - * acquired by the Bridge driver. - * No calls to other Bridge driver functions may subsequently - * occur, except for bridge_dev_create(). - * Parameters: - * dev_ctxt: Handle to Bridge driver defined device information. - * Returns: - * 0: Success. - * -EPERM: Failed to release a resource previously acquired. - * Requires: - * dev_ctxt != NULL; - * Ensures: - * 0: Device context is freed. - */ -typedef int(*fxn_dev_destroy) (struct bridge_dev_context *dev_ctxt); - -/* - * ======== bridge_io_create ======== - * Purpose: - * Create an object that manages I/O between CHNL and msg_ctrl. - * Parameters: - * io_man: Location to store IO manager on output. - * hchnl_mgr: Handle to channel manager. - * hmsg_mgr: Handle to message manager. - * Returns: - * 0: Success. - * -ENOMEM: Memory allocation failure. - * -EPERM: Creation failed. - * Requires: - * hdev_obj != NULL; - * Channel manager already created; - * Message manager already created; - * mgr_attrts != NULL; - * io_man != NULL; - * Ensures: - */ -typedef int(*fxn_io_create) (struct io_mgr **io_man, - struct dev_object *hdev_obj, - const struct io_attrs *mgr_attrts); - -/* - * ======== bridge_io_destroy ======== - * Purpose: - * Destroy object created in bridge_io_create. - * Parameters: - * hio_mgr: IO Manager. - * Returns: - * 0: Success. - * -ENOMEM: Memory allocation failure. - * -EPERM: Creation failed. - * Requires: - * Valid hio_mgr; - * Ensures: - */ -typedef int(*fxn_io_destroy) (struct io_mgr *hio_mgr); - -/* - * ======== bridge_io_on_loaded ======== - * Purpose: - * Called whenever a program is loaded to update internal data. For - * example, if shared memory is used, this function would update the - * shared memory location and address. - * Parameters: - * hio_mgr: IO Manager. - * Returns: - * 0: Success. - * -EPERM: Internal failure occurred. - * Requires: - * Valid hio_mgr; - * Ensures: - */ -typedef int(*fxn_io_onloaded) (struct io_mgr *hio_mgr); - -/* - * ======== fxn_io_getprocload ======== - * Purpose: - * Called to get the Processor's current and predicted load - * Parameters: - * hio_mgr: IO Manager. - * proc_load_stat Processor Load statistics - * Returns: - * 0: Success. - * -EPERM: Internal failure occurred. - * Requires: - * Valid hio_mgr; - * Ensures: - */ -typedef int(*fxn_io_getprocload) (struct io_mgr *hio_mgr, - struct dsp_procloadstat * - proc_load_stat); - -/* - * ======== bridge_msg_create ======== - * Purpose: - * Create an object to manage message queues. Only one of these objects - * can exist per device object. - * Parameters: - * msg_man: Location to store msg_ctrl manager on output. - * hdev_obj: Handle to a device object. - * msg_callback: Called whenever an RMS_EXIT message is received. - * Returns: - * 0: Success. - * -ENOMEM: Insufficient memory. - * Requires: - * msg_man != NULL. - * msg_callback != NULL. - * hdev_obj != NULL. - * Ensures: - */ -typedef int(*fxn_msg_create) - (struct msg_mgr **msg_man, - struct dev_object *hdev_obj, msg_onexit msg_callback); - -/* - * ======== bridge_msg_create_queue ======== - * Purpose: - * Create a msg_ctrl queue for sending or receiving messages from a Message - * node on the DSP. - * Parameters: - * hmsg_mgr: msg_ctrl queue manager handle returned from - * bridge_msg_create. - * msgq: Location to store msg_ctrl queue on output. - * msgq_id: Identifier for messages (node environment pointer). - * max_msgs: Max number of simultaneous messages for the node. - * h: Handle passed to hmsg_mgr->msg_callback(). - * Returns: - * 0: Success. - * -ENOMEM: Insufficient memory. - * Requires: - * msgq != NULL. - * h != NULL. - * max_msgs > 0. - * Ensures: - * msgq !=NULL <==> 0. - */ -typedef int(*fxn_msg_createqueue) - (struct msg_mgr *hmsg_mgr, - struct msg_queue **msgq, u32 msgq_id, u32 max_msgs, void *h); - -/* - * ======== bridge_msg_delete ======== - * Purpose: - * Delete a msg_ctrl manager allocated in bridge_msg_create(). - * Parameters: - * hmsg_mgr: Handle returned from bridge_msg_create(). - * Returns: - * Requires: - * Valid hmsg_mgr. - * Ensures: - */ -typedef void (*fxn_msg_delete) (struct msg_mgr *hmsg_mgr); - -/* - * ======== bridge_msg_delete_queue ======== - * Purpose: - * Delete a msg_ctrl queue allocated in bridge_msg_create_queue. - * Parameters: - * msg_queue_obj: Handle to msg_ctrl queue returned from - * bridge_msg_create_queue. - * Returns: - * Requires: - * Valid msg_queue_obj. - * Ensures: - */ -typedef void (*fxn_msg_deletequeue) (struct msg_queue *msg_queue_obj); - -/* - * ======== bridge_msg_get ======== - * Purpose: - * Get a message from a msg_ctrl queue. - * Parameters: - * msg_queue_obj: Handle to msg_ctrl queue returned from - * bridge_msg_create_queue. - * pmsg: Location to copy message into. - * utimeout: Timeout to wait for a message. - * Returns: - * 0: Success. - * -ETIME: Timeout occurred. - * -EPERM: No frames available for message (max_msgs too - * small). - * Requires: - * Valid msg_queue_obj. - * pmsg != NULL. - * Ensures: - */ -typedef int(*fxn_msg_get) (struct msg_queue *msg_queue_obj, - struct dsp_msg *pmsg, u32 utimeout); - -/* - * ======== bridge_msg_put ======== - * Purpose: - * Put a message onto a msg_ctrl queue. - * Parameters: - * msg_queue_obj: Handle to msg_ctrl queue returned from - * bridge_msg_create_queue. - * pmsg: Pointer to message. - * utimeout: Timeout to wait for a message. - * Returns: - * 0: Success. - * -ETIME: Timeout occurred. - * -EPERM: No frames available for message (max_msgs too - * small). - * Requires: - * Valid msg_queue_obj. - * pmsg != NULL. - * Ensures: - */ -typedef int(*fxn_msg_put) (struct msg_queue *msg_queue_obj, - const struct dsp_msg *pmsg, u32 utimeout); - -/* - * ======== bridge_msg_register_notify ======== - * Purpose: - * Register notification for when a message is ready. - * Parameters: - * msg_queue_obj: Handle to msg_ctrl queue returned from - * bridge_msg_create_queue. - * event_mask: Type of events to be notified about: Must be - * DSP_NODEMESSAGEREADY, or 0 to unregister. - * notify_type: DSP_SIGNALEVENT. - * hnotification: Handle of notification object. - * Returns: - * 0: Success. - * -ENOMEM: Insufficient memory. - * Requires: - * Valid msg_queue_obj. - * hnotification != NULL. - * notify_type == DSP_SIGNALEVENT. - * event_mask == DSP_NODEMESSAGEREADY || event_mask == 0. - * Ensures: - */ -typedef int(*fxn_msg_registernotify) - (struct msg_queue *msg_queue_obj, - u32 event_mask, u32 notify_type, struct dsp_notification *hnotification); - -/* - * ======== bridge_msg_set_queue_id ======== - * Purpose: - * Set message queue id to node environment. Allows bridge_msg_create_queue - * to be called in node_allocate, before the node environment is known. - * Parameters: - * msg_queue_obj: Handle to msg_ctrl queue returned from - * bridge_msg_create_queue. - * msgq_id: Node environment pointer. - * Returns: - * Requires: - * Valid msg_queue_obj. - * msgq_id != 0. - * Ensures: - */ -typedef void (*fxn_msg_setqueueid) (struct msg_queue *msg_queue_obj, - u32 msgq_id); - -/* - * Bridge Driver interface function table. - * - * The information in this table is filled in by the specific Bridge driver, - * and copied into the DSP API's own space. If any interface - * function field is set to a value of NULL, then the DSP API will - * consider that function not implemented, and return the error code - * -ENOSYS when a Bridge driver client attempts to call that function. - * - * This function table contains DSP API version numbers, which are used by the - * Bridge driver loader to help ensure backwards compatility between older - * Bridge drivers and newer DSP API. These must be set to - * BRD_API_MAJOR_VERSION and BRD_API_MINOR_VERSION, respectively. - * - * A Bridge driver need not export a CHNL interface. In this case, *all* of - * the bridge_chnl_* entries must be set to NULL. - */ -struct bridge_drv_interface { - u32 brd_api_major_version; /* Set to BRD_API_MAJOR_VERSION. */ - u32 brd_api_minor_version; /* Set to BRD_API_MINOR_VERSION. */ - fxn_dev_create dev_create; /* Create device context */ - fxn_dev_destroy dev_destroy; /* Destroy device context */ - fxn_dev_ctrl dev_cntrl; /* Optional vendor interface */ - fxn_brd_monitor brd_monitor; /* Load and/or start monitor */ - fxn_brd_start brd_start; /* Start DSP program. */ - fxn_brd_stop brd_stop; /* Stop/reset board. */ - fxn_brd_status brd_status; /* Get current board status. */ - fxn_brd_read brd_read; /* Read board memory */ - fxn_brd_write brd_write; /* Write board memory. */ - fxn_brd_setstate brd_set_state; /* Sets the Board State */ - fxn_brd_memcopy brd_mem_copy; /* Copies DSP Memory */ - fxn_brd_memwrite brd_mem_write; /* Write DSP Memory w/o halt */ - fxn_brd_memmap brd_mem_map; /* Maps MPU mem to DSP mem */ - fxn_brd_memunmap brd_mem_un_map; /* Unmaps MPU mem to DSP mem */ - fxn_chnl_create chnl_create; /* Create channel manager. */ - fxn_chnl_destroy chnl_destroy; /* Destroy channel manager. */ - fxn_chnl_open chnl_open; /* Create a new channel. */ - fxn_chnl_close chnl_close; /* Close a channel. */ - fxn_chnl_addioreq chnl_add_io_req; /* Req I/O on a channel. */ - fxn_chnl_getioc chnl_get_ioc; /* Wait for I/O completion. */ - fxn_chnl_cancelio chnl_cancel_io; /* Cancl I/O on a channel. */ - fxn_chnl_flushio chnl_flush_io; /* Flush I/O. */ - fxn_chnl_getinfo chnl_get_info; /* Get channel specific info */ - /* Get channel manager info. */ - fxn_chnl_getmgrinfo chnl_get_mgr_info; - fxn_chnl_idle chnl_idle; /* Idle the channel */ - /* Register for notif. */ - fxn_chnl_registernotify chnl_register_notify; - fxn_io_create io_create; /* Create IO manager */ - fxn_io_destroy io_destroy; /* Destroy IO manager */ - fxn_io_onloaded io_on_loaded; /* Notify of program loaded */ - /* Get Processor's current and predicted load */ - fxn_io_getprocload io_get_proc_load; - fxn_msg_create msg_create; /* Create message manager */ - /* Create message queue */ - fxn_msg_createqueue msg_create_queue; - fxn_msg_delete msg_delete; /* Delete message manager */ - /* Delete message queue */ - fxn_msg_deletequeue msg_delete_queue; - fxn_msg_get msg_get; /* Get a message */ - fxn_msg_put msg_put; /* Send a message */ - /* Register for notif. */ - fxn_msg_registernotify msg_register_notify; - /* Set message queue id */ - fxn_msg_setqueueid msg_set_queue_id; -}; - -/* - * ======== bridge_drv_entry ======== - * Purpose: - * Registers Bridge driver functions with the DSP API. Called only once - * by the DSP API. The caller will first check DSP API version - * compatibility, and then copy the interface functions into its own - * memory space. - * Parameters: - * drv_intf Pointer to a location to receive a pointer to the - * Bridge driver interface. - * Returns: - * Requires: - * The code segment this function resides in must expect to be discarded - * after completion. - * Ensures: - * drv_intf pointer initialized to Bridge driver's function - * interface. No system resources are acquired by this function. - * Details: - * Called during the Device_Init phase. - */ -void bridge_drv_entry(struct bridge_drv_interface **drv_intf, - const char *driver_file_name); - -#endif /* DSPDEFS_ */ |