| /* |
| * proc.h |
| * |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * |
| * This is the DSP API RM module interface. |
| * |
| * 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 PROC_ |
| #define PROC_ |
| |
| #include <dspbridge/cfgdefs.h> |
| #include <dspbridge/devdefs.h> |
| #include <dspbridge/drv.h> |
| |
| /* |
| * ======== proc_attach ======== |
| * Purpose: |
| * Prepare for communication with a particular DSP processor, and return |
| * a handle to the processor object. The PROC Object gets created |
| * Parameters: |
| * processor_id : The processor index (zero-based). |
| * hmgr_obj : Handle to the Manager Object |
| * attr_in : Ptr to the dsp_processorattrin structure. |
| * A NULL value means use default values. |
| * ph_processor : Ptr to location to store processor handle. |
| * Returns: |
| * 0 : Success. |
| * -EPERM : General failure. |
| * -EFAULT : Invalid processor handle. |
| * 0: Success; Processor already attached. |
| * Requires: |
| * ph_processor != NULL. |
| * PROC Initialized. |
| * Ensures: |
| * -EPERM, and *ph_processor == NULL, OR |
| * Success and *ph_processor is a Valid Processor handle OR |
| * 0 and *ph_processor is a Valid Processor. |
| * Details: |
| * When attr_in is NULL, the default timeout value is 10 seconds. |
| */ |
| extern int proc_attach(u32 processor_id, |
| const struct dsp_processorattrin |
| *attr_in, void **ph_processor, |
| struct process_context *pr_ctxt); |
| |
| /* |
| * ======== proc_auto_start ========= |
| * Purpose: |
| * A Particular device gets loaded with the default image |
| * if the AutoStart flag is set. |
| * Parameters: |
| * hdev_obj : Handle to the Device |
| * Returns: |
| * 0 : On Successful Loading |
| * -ENOENT : No DSP exec file found. |
| * -EPERM : General Failure |
| * Requires: |
| * hdev_obj != NULL. |
| * dev_node_obj != NULL. |
| * PROC Initialized. |
| * Ensures: |
| */ |
| extern int proc_auto_start(struct cfg_devnode *dev_node_obj, |
| struct dev_object *hdev_obj); |
| |
| /* |
| * ======== proc_ctrl ======== |
| * Purpose: |
| * Pass control information to the GPP device driver managing the DSP |
| * processor. This will be an OEM-only function, and not part of the |
| * 'Bridge application developer's API. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * dw_cmd : Private driver IOCTL cmd ID. |
| * pargs : Ptr to an driver defined argument structure. |
| * Returns: |
| * 0 : SUCCESS |
| * -EFAULT : Invalid processor handle. |
| * -ETIME: A Timeout Occurred before the Control information |
| * could be sent. |
| * -EPERM : General Failure. |
| * Requires: |
| * PROC Initialized. |
| * Ensures |
| * Details: |
| * This function Calls bridge_dev_ctrl. |
| */ |
| extern int proc_ctrl(void *hprocessor, |
| u32 dw_cmd, struct dsp_cbdata *arg); |
| |
| /* |
| * ======== proc_detach ======== |
| * Purpose: |
| * Close a DSP processor and de-allocate all (GPP) resources reserved |
| * for it. The Processor Object is deleted. |
| * Parameters: |
| * pr_ctxt : The processor handle. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : InValid Handle. |
| * -EPERM : General failure. |
| * Requires: |
| * PROC Initialized. |
| * Ensures: |
| * PROC Object is destroyed. |
| */ |
| extern int proc_detach(struct process_context *pr_ctxt); |
| |
| /* |
| * ======== proc_enum_nodes ======== |
| * Purpose: |
| * Enumerate the nodes currently allocated on a processor. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * node_tab : The first Location of an array allocated for node |
| * handles. |
| * node_tab_size: The number of (DSP_HNODE) handles that can be held |
| * to the memory the client has allocated for node_tab |
| * pu_num_nodes : Location where DSPProcessor_EnumNodes will return |
| * the number of valid handles written to node_tab |
| * pu_allocated : Location where DSPProcessor_EnumNodes will return |
| * the number of nodes that are allocated on the DSP. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EINVAL : The amount of memory allocated for node_tab is |
| * insufficent. That is the number of nodes actually |
| * allocated on the DSP is greater than the value |
| * specified for node_tab_size. |
| * -EPERM : Unable to get Resource Information. |
| * Details: |
| * Requires |
| * pu_num_nodes is not NULL. |
| * pu_allocated is not NULL. |
| * node_tab is not NULL. |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_enum_nodes(void *hprocessor, |
| void **node_tab, |
| u32 node_tab_size, |
| u32 *pu_num_nodes, |
| u32 *pu_allocated); |
| |
| /* |
| * ======== proc_get_resource_info ======== |
| * Purpose: |
| * Enumerate the resources currently available on a processor. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * resource_type: Type of resource . |
| * resource_info: Ptr to the dsp_resourceinfo structure. |
| * resource_info_size: Size of the structure. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EBADR: The processor is not in the PROC_RUNNING state. |
| * -ETIME: A timeout occurred before the DSP responded to the |
| * querry. |
| * -EPERM : Unable to get Resource Information |
| * Requires: |
| * resource_info is not NULL. |
| * Parameter resource_type is Valid.[TBD] |
| * resource_info_size is >= sizeof dsp_resourceinfo struct. |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| * This function currently returns |
| * -ENOSYS, and does not write any data to the resource_info struct. |
| */ |
| extern int proc_get_resource_info(void *hprocessor, |
| u32 resource_type, |
| struct dsp_resourceinfo |
| *resource_info, |
| u32 resource_info_size); |
| |
| /* |
| * ======== proc_get_dev_object ========= |
| * Purpose: |
| * Returns the DEV Hanlde for a given Processor handle |
| * Parameters: |
| * hprocessor : Processor Handle |
| * device_obj : Location to store the DEV Handle. |
| * Returns: |
| * 0 : Success; *device_obj has Dev handle |
| * -EPERM : Failure; *device_obj is zero. |
| * Requires: |
| * device_obj is not NULL |
| * PROC Initialized. |
| * Ensures: |
| * 0 : *device_obj is not NULL |
| * -EPERM : *device_obj is NULL. |
| */ |
| extern int proc_get_dev_object(void *hprocessor, |
| struct dev_object **device_obj); |
| |
| /* |
| * ======== proc_get_state ======== |
| * Purpose: |
| * Report the state of the specified DSP processor. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * proc_state_obj : Ptr to location to store the dsp_processorstate |
| * structure. |
| * state_info_size: Size of dsp_processorstate. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure while querying processor state. |
| * Requires: |
| * proc_state_obj is not NULL |
| * state_info_size is >= than the size of dsp_processorstate structure. |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_get_state(void *hprocessor, struct dsp_processorstate |
| *proc_state_obj, u32 state_info_size); |
| |
| /* |
| * ======== PROC_GetProcessorID ======== |
| * Purpose: |
| * Report the state of the specified DSP processor. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * proc_id : Processor ID |
| * |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure while querying processor state. |
| * Requires: |
| * proc_state_obj is not NULL |
| * state_info_size is >= than the size of dsp_processorstate structure. |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_get_processor_id(void *proc, u32 * proc_id); |
| |
| /* |
| * ======== proc_get_trace ======== |
| * Purpose: |
| * Retrieve the trace buffer from the specified DSP processor. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * pbuf : Ptr to buffer to hold trace output. |
| * max_size : Maximum size of the output buffer. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure while retrieving processor trace |
| * Buffer. |
| * Requires: |
| * pbuf is not NULL |
| * max_size is > 0. |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_get_trace(void *hprocessor, u8 * pbuf, u32 max_size); |
| |
| /* |
| * ======== proc_load ======== |
| * Purpose: |
| * Reset a processor and load a new base program image. |
| * This will be an OEM-only function. |
| * Parameters: |
| * hprocessor: The processor handle. |
| * argc_index: The number of Arguments(strings)in the aArgV[] |
| * user_args: An Array of Arguments(Unicode Strings) |
| * user_envp: An Array of Environment settings(Unicode Strings) |
| * Returns: |
| * 0: Success. |
| * -ENOENT: The DSP Executable was not found. |
| * -EFAULT: Invalid processor handle. |
| * -EPERM : Unable to Load the Processor |
| * Requires: |
| * user_args is not NULL |
| * argc_index is > 0 |
| * PROC Initialized. |
| * Ensures: |
| * Success and ProcState == PROC_LOADED |
| * or DSP_FAILED status. |
| * Details: |
| * Does not implement access rights to control which GPP application |
| * can load the processor. |
| */ |
| extern int proc_load(void *hprocessor, |
| const s32 argc_index, const char **user_args, |
| const char **user_envp); |
| |
| /* |
| * ======== proc_register_notify ======== |
| * Purpose: |
| * Register to be notified of specific processor events |
| * Parameters: |
| * hprocessor : The processor handle. |
| * event_mask : Mask of types of events to be notified about. |
| * notify_type : Type of notification to be sent. |
| * hnotification: Handle to be used for notification. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle or hnotification. |
| * -EINVAL : Parameter event_mask is Invalid |
| * DSP_ENOTIMP : The notification type specified in uNotifyMask |
| * is not supported. |
| * -EPERM : Unable to register for notification. |
| * Requires: |
| * hnotification is not NULL |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_register_notify(void *hprocessor, |
| u32 event_mask, u32 notify_type, |
| struct dsp_notification |
| *hnotification); |
| |
| /* |
| * ======== proc_notify_clients ======== |
| * Purpose: |
| * Notify the Processor Clients |
| * Parameters: |
| * proc : The processor handle. |
| * events : Event to be notified about. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : Failure to Set or Reset the Event |
| * Requires: |
| * events is Supported or Valid type of Event |
| * proc is a valid handle |
| * PROC Initialized. |
| * Ensures: |
| */ |
| extern int proc_notify_clients(void *proc, u32 events); |
| |
| /* |
| * ======== proc_notify_all_clients ======== |
| * Purpose: |
| * Notify the Processor Clients |
| * Parameters: |
| * proc : The processor handle. |
| * events : Event to be notified about. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : Failure to Set or Reset the Event |
| * Requires: |
| * events is Supported or Valid type of Event |
| * proc is a valid handle |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| * NODE And STRM would use this function to notify their clients |
| * about the state changes in NODE or STRM. |
| */ |
| extern int proc_notify_all_clients(void *proc, u32 events); |
| |
| /* |
| * ======== proc_start ======== |
| * Purpose: |
| * Start a processor running. |
| * Processor must be in PROC_LOADED state. |
| * This will be an OEM-only function, and not part of the 'Bridge |
| * application developer's API. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EBADR: Processor is not in PROC_LOADED state. |
| * -EPERM : Unable to start the processor. |
| * Requires: |
| * PROC Initialized. |
| * Ensures: |
| * Success and ProcState == PROC_RUNNING or DSP_FAILED status. |
| * Details: |
| */ |
| extern int proc_start(void *hprocessor); |
| |
| /* |
| * ======== proc_stop ======== |
| * Purpose: |
| * Start a processor running. |
| * Processor must be in PROC_LOADED state. |
| * This will be an OEM-only function, and not part of the 'Bridge |
| * application developer's API. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EBADR: Processor is not in PROC_LOADED state. |
| * -EPERM : Unable to start the processor. |
| * Requires: |
| * PROC Initialized. |
| * Ensures: |
| * Success and ProcState == PROC_RUNNING or DSP_FAILED status. |
| * Details: |
| */ |
| extern int proc_stop(void *hprocessor); |
| |
| /* |
| * ======== proc_end_dma ======== |
| * Purpose: |
| * Begin a DMA transfer |
| * Parameters: |
| * hprocessor : The processor handle. |
| * pmpu_addr : Buffer start address |
| * ul_size : Buffer size |
| * dir : The direction of the transfer |
| * Requires: |
| * Memory was previously mapped. |
| */ |
| extern int proc_end_dma(void *hprocessor, void *pmpu_addr, u32 ul_size, |
| enum dma_data_direction dir); |
| /* |
| * ======== proc_begin_dma ======== |
| * Purpose: |
| * Begin a DMA transfer |
| * Parameters: |
| * hprocessor : The processor handle. |
| * pmpu_addr : Buffer start address |
| * ul_size : Buffer size |
| * dir : The direction of the transfer |
| * Requires: |
| * Memory was previously mapped. |
| */ |
| extern int proc_begin_dma(void *hprocessor, void *pmpu_addr, u32 ul_size, |
| enum dma_data_direction dir); |
| |
| /* |
| * ======== proc_flush_memory ======== |
| * Purpose: |
| * Flushes a buffer from the MPU data cache. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * pmpu_addr : Buffer start address |
| * ul_size : Buffer size |
| * ul_flags : Reserved. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure. |
| * Requires: |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| * All the arguments are currently ignored. |
| */ |
| extern int proc_flush_memory(void *hprocessor, |
| void *pmpu_addr, u32 ul_size, u32 ul_flags); |
| |
| /* |
| * ======== proc_invalidate_memory ======== |
| * Purpose: |
| * Invalidates a buffer from the MPU data cache. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * pmpu_addr : Buffer start address |
| * ul_size : Buffer size |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure. |
| * Requires: |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| * All the arguments are currently ignored. |
| */ |
| extern int proc_invalidate_memory(void *hprocessor, |
| void *pmpu_addr, u32 ul_size); |
| |
| /* |
| * ======== proc_map ======== |
| * Purpose: |
| * Maps a MPU buffer to DSP address space. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * pmpu_addr : Starting address of the memory region to map. |
| * ul_size : Size of the memory region to map. |
| * req_addr : Requested DSP start address. Offset-adjusted actual |
| * mapped address is in the last argument. |
| * pp_map_addr : Ptr to DSP side mapped u8 address. |
| * ul_map_attr : Optional endianness attributes, virt to phys flag. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure. |
| * -ENOMEM : MPU side memory allocation error. |
| * -ENOENT : Cannot find a reserved region starting with this |
| * : address. |
| * Requires: |
| * pmpu_addr is not NULL |
| * ul_size is not zero |
| * pp_map_addr is not NULL |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_map(void *hprocessor, |
| void *pmpu_addr, |
| u32 ul_size, |
| void *req_addr, |
| void **pp_map_addr, u32 ul_map_attr, |
| struct process_context *pr_ctxt); |
| |
| /* |
| * ======== proc_reserve_memory ======== |
| * Purpose: |
| * Reserve a virtually contiguous region of DSP address space. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * ul_size : Size of the address space to reserve. |
| * pp_rsv_addr : Ptr to DSP side reserved u8 address. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure. |
| * -ENOMEM : Cannot reserve chunk of this size. |
| * Requires: |
| * pp_rsv_addr is not NULL |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_reserve_memory(void *hprocessor, |
| u32 ul_size, void **pp_rsv_addr, |
| struct process_context *pr_ctxt); |
| |
| /* |
| * ======== proc_un_map ======== |
| * Purpose: |
| * Removes a MPU buffer mapping from the DSP address space. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * map_addr : Starting address of the mapped memory region. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure. |
| * -ENOENT : Cannot find a mapped region starting with this |
| * : address. |
| * Requires: |
| * map_addr is not NULL |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_un_map(void *hprocessor, void *map_addr, |
| struct process_context *pr_ctxt); |
| |
| /* |
| * ======== proc_un_reserve_memory ======== |
| * Purpose: |
| * Frees a previously reserved region of DSP address space. |
| * Parameters: |
| * hprocessor : The processor handle. |
| * prsv_addr : Ptr to DSP side reservedBYTE address. |
| * Returns: |
| * 0 : Success. |
| * -EFAULT : Invalid processor handle. |
| * -EPERM : General failure. |
| * -ENOENT : Cannot find a reserved region starting with this |
| * : address. |
| * Requires: |
| * prsv_addr is not NULL |
| * PROC Initialized. |
| * Ensures: |
| * Details: |
| */ |
| extern int proc_un_reserve_memory(void *hprocessor, |
| void *prsv_addr, |
| struct process_context *pr_ctxt); |
| |
| #endif /* PROC_ */ |
