1 /*
2  * dspdefs.h
3  *
4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5  *
6  * Bridge driver entry point and interface function declarations.
7  *
8  * Notes:
9  *   The DSP API obtains it's function interface to
10  *   the Bridge driver via a call to bridge_drv_entry().
11  *
12  *   Bridge services exported to Bridge drivers are initialized by the
13  *   DSP API on behalf of the Bridge driver.
14  *
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.
17  *
18  * Copyright (C) 2005-2006 Texas Instruments, Inc.
19  *
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.
23  *
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.
27  */
28 
29 #ifndef DSPDEFS_
30 #define DSPDEFS_
31 
32 #include <dspbridge/brddefs.h>
33 #include <dspbridge/cfgdefs.h>
34 #include <dspbridge/chnlpriv.h>
35 #include <dspbridge/dspdeh.h>
36 #include <dspbridge/devdefs.h>
37 #include <dspbridge/io.h>
38 #include <dspbridge/msgdefs.h>
39 
40 /* Handle to Bridge driver's private device context. */
41 struct bridge_dev_context;
42 
43 /*--------------------------------------------------------------------------- */
44 /* BRIDGE DRIVER FUNCTION TYPES */
45 /*--------------------------------------------------------------------------- */
46 
47 /*
48  *  ======== bridge_brd_monitor ========
49  *  Purpose:
50  *      Bring the board to the BRD_IDLE (monitor) state.
51  *  Parameters:
52  *      dev_ctxt:    Handle to Bridge driver defined device context.
53  *  Returns:
54  *      0:        Success.
55  *      -ETIMEDOUT:  Timeout occurred waiting for a response from hardware.
56  *      -EPERM:      Other, unspecified error.
57  *  Requires:
58  *      dev_ctxt != NULL
59  *  Ensures:
60  *      0:        Board is in BRD_IDLE state;
61  *      else:           Board state is indeterminate.
62  */
63 typedef int(*fxn_brd_monitor) (struct bridge_dev_context *dev_ctxt);
64 
65 /*
66  *  ======== fxn_brd_setstate ========
67  *  Purpose:
68  *      Sets the Bridge driver state
69  *  Parameters:
70  *      dev_ctxt:    Handle to Bridge driver defined device info.
71  *      brd_state:      Board state
72  *  Returns:
73  *      0:        Success.
74  *      -EPERM:      Other, unspecified error.
75  *  Requires:
76  *      dev_ctxt != NULL;
77  *      brd_state  <= BRD_LASTSTATE.
78  *  Ensures:
79  *      brd_state  <= BRD_LASTSTATE.
80  *  Update the Board state to the specified state.
81  */
82 typedef int(*fxn_brd_setstate) (struct bridge_dev_context
83 				       * dev_ctxt, u32 brd_state);
84 
85 /*
86  *  ======== bridge_brd_start ========
87  *  Purpose:
88  *      Bring board to the BRD_RUNNING (start) state.
89  *  Parameters:
90  *      dev_ctxt:    Handle to Bridge driver defined device context.
91  *      dsp_addr:       DSP address at which to start execution.
92  *  Returns:
93  *      0:        Success.
94  *      -ETIMEDOUT:  Timeout occurred waiting for a response from hardware.
95  *      -EPERM:      Other, unspecified error.
96  *  Requires:
97  *      dev_ctxt != NULL
98  *      Board is in monitor (BRD_IDLE) state.
99  *  Ensures:
100  *      0:        Board is in BRD_RUNNING state.
101  *                      Interrupts to the PC are enabled.
102  *      else:           Board state is indeterminate.
103  */
104 typedef int(*fxn_brd_start) (struct bridge_dev_context
105 				    * dev_ctxt, u32 dsp_addr);
106 
107 /*
108  *  ======== bridge_brd_mem_copy ========
109  *  Purpose:
110  *  Copy memory from one DSP address to another
111  *  Parameters:
112  *      dev_context:    Pointer to context handle
113  *  dsp_dest_addr:  DSP address to copy to
114  *  dsp_src_addr:   DSP address to copy from
115  *  ul_num_bytes: Number of bytes to copy
116  *  mem_type:   What section of memory to copy to
117  *  Returns:
118  *      0:        Success.
119  *      -EPERM:      Other, unspecified error.
120  *  Requires:
121  *      dev_context != NULL
122  *  Ensures:
123  *      0:        Board is in BRD_RUNNING state.
124  *                      Interrupts to the PC are enabled.
125  *      else:           Board state is indeterminate.
126  */
127 typedef int(*fxn_brd_memcopy) (struct bridge_dev_context
128 				      * dev_ctxt,
129 				      u32 dsp_dest_addr,
130 				      u32 dsp_src_addr,
131 				      u32 ul_num_bytes, u32 mem_type);
132 /*
133  *  ======== bridge_brd_mem_write ========
134  *  Purpose:
135  *      Write a block of host memory into a DSP address, into a given memory
136  *      space.  Unlike bridge_brd_write, this API does reset the DSP
137  *  Parameters:
138  *      dev_ctxt:    Handle to Bridge driver defined device info.
139  *      dsp_addr:       Address on DSP board (Destination).
140  *      host_buf:       Pointer to host buffer (Source).
141  *      ul_num_bytes:     Number of bytes to transfer.
142  *      mem_type:       Memory space on DSP to which to transfer.
143  *  Returns:
144  *      0:        Success.
145  *      -ETIMEDOUT:  Timeout occurred waiting for a response from hardware.
146  *      -EPERM:      Other, unspecified error.
147  *  Requires:
148  *      dev_ctxt != NULL;
149  *      host_buf != NULL.
150  *  Ensures:
151  */
152 typedef int(*fxn_brd_memwrite) (struct bridge_dev_context
153 				       * dev_ctxt,
154 				       u8 *host_buf,
155 				       u32 dsp_addr, u32 ul_num_bytes,
156 				       u32 mem_type);
157 
158 /*
159  *  ======== bridge_brd_mem_map ========
160  *  Purpose:
161  *      Map a MPU memory region to a DSP/IVA memory space
162  *  Parameters:
163  *      dev_ctxt:    Handle to Bridge driver defined device info.
164  *      ul_mpu_addr:      MPU memory region start address.
165  *      virt_addr:      DSP/IVA memory region u8 address.
166  *      ul_num_bytes:     Number of bytes to map.
167  *      map_attrs:       Mapping attributes (e.g. endianness).
168  *  Returns:
169  *      0:        Success.
170  *      -EPERM:      Other, unspecified error.
171  *  Requires:
172  *      dev_ctxt != NULL;
173  *  Ensures:
174  */
175 typedef int(*fxn_brd_memmap) (struct bridge_dev_context
176 				     * dev_ctxt, u32 ul_mpu_addr,
177 				     u32 virt_addr, u32 ul_num_bytes,
178 				     u32 map_attr,
179 				     struct page **mapped_pages);
180 
181 /*
182  *  ======== bridge_brd_mem_un_map ========
183  *  Purpose:
184  *      UnMap an MPU memory region from DSP/IVA memory space
185  *  Parameters:
186  *      dev_ctxt:    Handle to Bridge driver defined device info.
187  *      virt_addr:      DSP/IVA memory region u8 address.
188  *      ul_num_bytes:     Number of bytes to unmap.
189  *  Returns:
190  *      0:        Success.
191  *      -EPERM:      Other, unspecified error.
192  *  Requires:
193  *      dev_ctxt != NULL;
194  *  Ensures:
195  */
196 typedef int(*fxn_brd_memunmap) (struct bridge_dev_context
197 				       * dev_ctxt,
198 				       u32 virt_addr, u32 ul_num_bytes);
199 
200 /*
201  *  ======== bridge_brd_stop ========
202  *  Purpose:
203  *      Bring board to the BRD_STOPPED state.
204  *  Parameters:
205  *      dev_ctxt:    Handle to Bridge driver defined device context.
206  *  Returns:
207  *      0:        Success.
208  *      -ETIMEDOUT:  Timeout occurred waiting for a response from hardware.
209  *      -EPERM:      Other, unspecified error.
210  *  Requires:
211  *      dev_ctxt != NULL
212  *  Ensures:
213  *      0:        Board is in BRD_STOPPED (stop) state;
214  *                      Interrupts to the PC are disabled.
215  *      else:           Board state is indeterminate.
216  */
217 typedef int(*fxn_brd_stop) (struct bridge_dev_context *dev_ctxt);
218 
219 /*
220  *  ======== bridge_brd_status ========
221  *  Purpose:
222  *      Report the current state of the board.
223  *  Parameters:
224  *      dev_ctxt:    Handle to Bridge driver defined device context.
225  *      board_state:    Ptr to BRD status variable.
226  *  Returns:
227  *      0:
228  *  Requires:
229  *      board_state != NULL;
230  *      dev_ctxt != NULL
231  *  Ensures:
232  *      *board_state is one of
233  *       {BRD_STOPPED, BRD_IDLE, BRD_RUNNING, BRD_UNKNOWN};
234  */
235 typedef int(*fxn_brd_status) (struct bridge_dev_context *dev_ctxt,
236 				     int *board_state);
237 
238 /*
239  *  ======== bridge_brd_read ========
240  *  Purpose:
241  *      Read a block of DSP memory, from a given memory space, into a host
242  *      buffer.
243  *  Parameters:
244  *      dev_ctxt:    Handle to Bridge driver defined device info.
245  *      host_buf:       Pointer to host buffer (Destination).
246  *      dsp_addr:       Address on DSP board (Source).
247  *      ul_num_bytes:     Number of bytes to transfer.
248  *      mem_type:       Memory space on DSP from which to transfer.
249  *  Returns:
250  *      0:        Success.
251  *      -ETIMEDOUT:  Timeout occurred waiting for a response from hardware.
252  *      -EPERM:      Other, unspecified error.
253  *  Requires:
254  *      dev_ctxt != NULL;
255  *      host_buf != NULL.
256  *  Ensures:
257  *  Will not write more than ul_num_bytes bytes into host_buf.
258  */
259 typedef int(*fxn_brd_read) (struct bridge_dev_context *dev_ctxt,
260 				   u8 *host_buf,
261 				   u32 dsp_addr,
262 				   u32 ul_num_bytes, u32 mem_type);
263 
264 /*
265  *  ======== bridge_brd_write ========
266  *  Purpose:
267  *      Write a block of host memory into a DSP address, into a given memory
268  *      space.
269  *  Parameters:
270  *      dev_ctxt:    Handle to Bridge driver defined device info.
271  *      dsp_addr:       Address on DSP board (Destination).
272  *      host_buf:       Pointer to host buffer (Source).
273  *      ul_num_bytes:     Number of bytes to transfer.
274  *      mem_type:       Memory space on DSP to which to transfer.
275  *  Returns:
276  *      0:        Success.
277  *      -ETIMEDOUT:  Timeout occurred waiting for a response from hardware.
278  *      -EPERM:      Other, unspecified error.
279  *  Requires:
280  *      dev_ctxt != NULL;
281  *      host_buf != NULL.
282  *  Ensures:
283  */
284 typedef int(*fxn_brd_write) (struct bridge_dev_context *dev_ctxt,
285 				    u8 *host_buf,
286 				    u32 dsp_addr,
287 				    u32 ul_num_bytes, u32 mem_type);
288 
289 /*
290  *  ======== bridge_chnl_create ========
291  *  Purpose:
292  *      Create a channel manager object, responsible for opening new channels
293  *      and closing old ones for a given 'Bridge board.
294  *  Parameters:
295  *      channel_mgr:    Location to store a channel manager object on output.
296  *      hdev_obj:     Handle to a device object.
297  *      mgr_attrts:      Channel manager attributes.
298  *      mgr_attrts->max_channels: Max channels
299  *      mgr_attrts->birq:      Channel's I/O IRQ number.
300  *      mgr_attrts->irq_shared:   TRUE if the IRQ is shareable.
301  *      mgr_attrts->word_size: DSP Word size in equivalent PC bytes..
302  *      mgr_attrts->shm_base:  Base physical address of shared memory, if any.
303  *      mgr_attrts->sm_length: Bytes of shared memory block.
304  *  Returns:
305  *      0:            Success;
306  *      -ENOMEM:        Insufficient memory for requested resources.
307  *      -EIO:         Unable to plug ISR for given IRQ.
308  *      -EFAULT:    Couldn't map physical address to a virtual one.
309  *  Requires:
310  *      channel_mgr != NULL.
311  *      mgr_attrts != NULL
312  *      mgr_attrts field are all valid:
313  *          0 < max_channels <= CHNL_MAXCHANNELS.
314  *          birq <= 15.
315  *          word_size > 0.
316  *      hdev_obj != NULL
317  *      No channel manager exists for this board.
318  *  Ensures:
319  */
320 typedef int(*fxn_chnl_create) (struct chnl_mgr
321 				      **channel_mgr,
322 				      struct dev_object
323 				      * hdev_obj,
324 				      const struct
325 				      chnl_mgrattrs * mgr_attrts);
326 
327 /*
328  *  ======== bridge_chnl_destroy ========
329  *  Purpose:
330  *      Close all open channels, and destroy the channel manager.
331  *  Parameters:
332  *      hchnl_mgr:       Channel manager object.
333  *  Returns:
334  *      0:        Success.
335  *      -EFAULT:    hchnl_mgr was invalid.
336  *  Requires:
337  *  Ensures:
338  *      0: Cancels I/O on each open channel. Closes each open channel.
339  *          chnl_create may subsequently be called for the same device.
340  */
341 typedef int(*fxn_chnl_destroy) (struct chnl_mgr *hchnl_mgr);
342 /*
343  *  ======== bridge_deh_notify ========
344  *  Purpose:
345  *      When notified of DSP error, take appropriate action.
346  *  Parameters:
347  *      hdeh_mgr:        Handle to DEH manager object.
348  *      evnt_mask:    Indicate the type of exception
349  *      error_info:    Error information
350  *  Returns:
351  *
352  *  Requires:
353  *      hdeh_mgr != NULL;
354  *     evnt_mask with a valid exception
355  *  Ensures:
356  */
357 typedef void (*fxn_deh_notify) (struct deh_mgr *hdeh_mgr,
358 				u32 evnt_mask, u32 error_info);
359 
360 /*
361  *  ======== bridge_chnl_open ========
362  *  Purpose:
363  *      Open a new half-duplex channel to the DSP board.
364  *  Parameters:
365  *      chnl:           Location to store a channel object handle.
366  *      hchnl_mgr:	Handle to channel manager, as returned by
367  *      		CHNL_GetMgr().
368  *      chnl_mode:          One of {CHNL_MODETODSP, CHNL_MODEFROMDSP} specifies
369  *                      direction of data transfer.
370  *      ch_id:        If CHNL_PICKFREE is specified, the channel manager will
371  *                      select a free channel id (default);
372  *                      otherwise this field specifies the id of the channel.
373  *      pattrs:         Channel attributes.  Attribute fields are as follows:
374  *      pattrs->uio_reqs: Specifies the maximum number of I/O requests which can
375  *                      be pending at any given time. All request packets are
376  *                      preallocated when the channel is opened.
377  *      pattrs->event_obj: This field allows the user to supply an auto reset
378  *                      event object for channel I/O completion notifications.
379  *                      It is the responsibility of the user to destroy this
380  *                      object AFTER closing the channel.
381  *                      This channel event object can be retrieved using
382  *                      CHNL_GetEventHandle().
383  *      pattrs->hReserved: The kernel mode handle of this event object.
384  *
385  *  Returns:
386  *      0:                Success.
387  *      -EFAULT:            hchnl_mgr is invalid.
388  *      -ENOMEM:            Insufficient memory for requested resources.
389  *      -EINVAL:        Invalid number of IOReqs.
390  *      -ENOSR:    No free channels available.
391  *      -ECHRNG:       Channel ID is out of range.
392  *      -EALREADY:        Channel is in use.
393  *      -EIO:         No free IO request packets available for
394  *                              queuing.
395  *  Requires:
396  *      chnl != NULL.
397  *      pattrs != NULL.
398  *      pattrs->event_obj is a valid event handle.
399  *      pattrs->hReserved is the kernel mode handle for pattrs->event_obj.
400  *  Ensures:
401  *      0:                *chnl is a valid channel.
402  *      else:                   *chnl is set to NULL if (chnl != NULL);
403  */
404 typedef int(*fxn_chnl_open) (struct chnl_object
405 				    **chnl,
406 				    struct chnl_mgr *hchnl_mgr,
407 				    s8 chnl_mode,
408 				    u32 ch_id,
409 				    const struct
410 				    chnl_attr * pattrs);
411 
412 /*
413  *  ======== bridge_chnl_close ========
414  *  Purpose:
415  *      Ensures all pending I/O on this channel is cancelled, discards all
416  *      queued I/O completion notifications, then frees the resources allocated
417  *      for this channel, and makes the corresponding logical channel id
418  *      available for subsequent use.
419  *  Parameters:
420  *      chnl_obj:          Handle to a channel object.
421  *  Returns:
422  *      0:        Success;
423  *      -EFAULT:    Invalid chnl_obj.
424  *  Requires:
425  *      No thread must be blocked on this channel's I/O completion event.
426  *  Ensures:
427  *      0:        chnl_obj is no longer valid.
428  */
429 typedef int(*fxn_chnl_close) (struct chnl_object *chnl_obj);
430 
431 /*
432  *  ======== bridge_chnl_add_io_req ========
433  *  Purpose:
434  *      Enqueue an I/O request for data transfer on a channel to the DSP.
435  *      The direction (mode) is specified in the channel object. Note the DSP
436  *      address is specified for channels opened in direct I/O mode.
437  *  Parameters:
438  *      chnl_obj:          Channel object handle.
439  *      host_buf:       Host buffer address source.
440  *      byte_size:	Number of PC bytes to transfer. A zero value indicates
441  *                      that this buffer is the last in the output channel.
442  *                      A zero value is invalid for an input channel.
443  *!     buf_size:       Actual buffer size in host bytes.
444  *      dw_dsp_addr:      DSP address for transfer.  (Currently ignored).
445  *      dw_arg:          A user argument that travels with the buffer.
446  *  Returns:
447  *      0:        Success;
448  *      -EFAULT: Invalid chnl_obj or host_buf.
449  *      -EPERM:   User cannot mark EOS on an input channel.
450  *      -ECANCELED: I/O has been cancelled on this channel.  No further
451  *                      I/O is allowed.
452  *      -EPIPE:     End of stream was already marked on a previous
453  *                      IORequest on this channel.  No further I/O is expected.
454  *      -EINVAL: Buffer submitted to this output channel is larger than
455  *                      the size of the physical shared memory output window.
456  *  Requires:
457  *  Ensures:
458  *      0: The buffer will be transferred if the channel is ready;
459  *          otherwise, will be queued for transfer when the channel becomes
460  *          ready.  In any case, notifications of I/O completion are
461  *          asynchronous.
462  *          If byte_size is 0 for an output channel, subsequent CHNL_AddIOReq's
463  *          on this channel will fail with error code -EPIPE.  The
464  *          corresponding IOC for this I/O request will have its status flag
465  *          set to CHNL_IOCSTATEOS.
466  */
467 typedef int(*fxn_chnl_addioreq) (struct chnl_object
468 					* chnl_obj,
469 					void *host_buf,
470 					u32 byte_size,
471 					u32 buf_size,
472 					u32 dw_dsp_addr, u32 dw_arg);
473 
474 /*
475  *  ======== bridge_chnl_get_ioc ========
476  *  Purpose:
477  *      Dequeue an I/O completion record, which contains information about the
478  *      completed I/O request.
479  *  Parameters:
480  *      chnl_obj:          Channel object handle.
481  *      timeout:        A value of CHNL_IOCNOWAIT will simply dequeue the
482  *                      first available IOC.
483  *      chan_ioc:       On output, contains host buffer address, bytes
484  *                      transferred, and status of I/O completion.
485  *      chan_ioc->status:   See chnldefs.h.
486  *  Returns:
487  *      0:        Success.
488  *      -EFAULT: Invalid chnl_obj or chan_ioc.
489  *      -EREMOTEIO:   CHNL_IOCNOWAIT was specified as the timeout parameter
490  *                      yet no I/O completions were queued.
491  *  Requires:
492  *      timeout == CHNL_IOCNOWAIT.
493  *  Ensures:
494  *      0: if there are any remaining IOC's queued before this call
495  *          returns, the channel event object will be left in a signalled
496  *          state.
497  */
498 typedef int(*fxn_chnl_getioc) (struct chnl_object *chnl_obj,
499 				      u32 timeout,
500 				      struct chnl_ioc *chan_ioc);
501 
502 /*
503  *  ======== bridge_chnl_cancel_io ========
504  *  Purpose:
505  *      Return all I/O requests to the client which have not yet been
506  *      transferred.  The channel's I/O completion object is
507  *      signalled, and all the I/O requests are queued as IOC's, with the
508  *      status field set to CHNL_IOCSTATCANCEL.
509  *      This call is typically used in abort situations, and is a prelude to
510  *      chnl_close();
511  *  Parameters:
512  *      chnl_obj:          Channel object handle.
513  *  Returns:
514  *      0:        Success;
515  *      -EFAULT:    Invalid chnl_obj.
516  *  Requires:
517  *  Ensures:
518  *      Subsequent I/O requests to this channel will not be accepted.
519  */
520 typedef int(*fxn_chnl_cancelio) (struct chnl_object *chnl_obj);
521 
522 /*
523  *  ======== bridge_chnl_flush_io ========
524  *  Purpose:
525  *      For an output stream (to the DSP), indicates if any IO requests are in
526  *      the output request queue.  For input streams (from the DSP), will
527  *      cancel all pending IO requests.
528  *  Parameters:
529  *      chnl_obj:              Channel object handle.
530  *      timeout:            Timeout value for flush operation.
531  *  Returns:
532  *      0:            Success;
533  *      S_CHNLIOREQUEST:    Returned if any IORequests are in the output queue.
534  *      -EFAULT:        Invalid chnl_obj.
535  *  Requires:
536  *  Ensures:
537  *      0:            No I/O requests will be pending on this channel.
538  */
539 typedef int(*fxn_chnl_flushio) (struct chnl_object *chnl_obj,
540 				       u32 timeout);
541 
542 /*
543  *  ======== bridge_chnl_get_info ========
544  *  Purpose:
545  *      Retrieve information related to a channel.
546  *  Parameters:
547  *      chnl_obj:          Handle to a valid channel object, or NULL.
548  *      channel_info:   Location to store channel info.
549  *  Returns:
550  *      0:        Success;
551  *      -EFAULT: Invalid chnl_obj or channel_info.
552  *  Requires:
553  *  Ensures:
554  *      0:        channel_info points to a filled in chnl_info struct,
555  *                      if (channel_info != NULL).
556  */
557 typedef int(*fxn_chnl_getinfo) (struct chnl_object *chnl_obj,
558 				       struct chnl_info *channel_info);
559 
560 /*
561  *  ======== bridge_chnl_get_mgr_info ========
562  *  Purpose:
563  *      Retrieve information related to the channel manager.
564  *  Parameters:
565  *      hchnl_mgr:           Handle to a valid channel manager, or NULL.
566  *      ch_id:            Channel ID.
567  *      mgr_info:           Location to store channel manager info.
568  *  Returns:
569  *      0:            Success;
570  *      -EFAULT: Invalid hchnl_mgr or mgr_info.
571  *      -ECHRNG:   Invalid channel ID.
572  *  Requires:
573  *  Ensures:
574  *      0:            mgr_info points to a filled in chnl_mgrinfo
575  *                          struct, if (mgr_info != NULL).
576  */
577 typedef int(*fxn_chnl_getmgrinfo) (struct chnl_mgr
578 					  * hchnl_mgr,
579 					  u32 ch_id,
580 					  struct chnl_mgrinfo *mgr_info);
581 
582 /*
583  *  ======== bridge_chnl_idle ========
584  *  Purpose:
585  *      Idle a channel. If this is an input channel, or if this is an output
586  *      channel and flush_data is TRUE, all currently enqueued buffers will be
587  *      dequeued (data discarded for output channel).
588  *      If this is an output channel and flush_data is FALSE, this function
589  *      will block until all currently buffered data is output, or the timeout
590  *      specified has been reached.
591  *
592  *  Parameters:
593  *      chnl_obj:          Channel object handle.
594  *      timeout:        If output channel and flush_data is FALSE, timeout value
595  *                      to wait for buffers to be output. (Not used for
596  *                      input channel).
597  *      flush_data:     If output channel and flush_data is TRUE, discard any
598  *                      currently buffered data. If FALSE, wait for currently
599  *                      buffered data to be output, or timeout, whichever
600  *                      occurs first. flush_data is ignored for input channel.
601  *  Returns:
602  *      0:            Success;
603  *      -EFAULT:        Invalid chnl_obj.
604  *      -ETIMEDOUT: Timeout occurred before channel could be idled.
605  *  Requires:
606  *  Ensures:
607  */
608 typedef int(*fxn_chnl_idle) (struct chnl_object *chnl_obj,
609 				    u32 timeout, bool flush_data);
610 
611 /*
612  *  ======== bridge_chnl_register_notify ========
613  *  Purpose:
614  *      Register for notification of events on a channel.
615  *  Parameters:
616  *      chnl_obj:          Channel object handle.
617  *      event_mask:     Type of events to be notified about: IO completion
618  *                      (DSP_STREAMIOCOMPLETION) or end of stream
619  *                      (DSP_STREAMDONE).
620  *      notify_type:    DSP_SIGNALEVENT.
621  *      hnotification:  Handle of a dsp_notification object.
622  *  Returns:
623  *      0:        Success.
624  *      -ENOMEM:    Insufficient memory.
625  *      -EINVAL:     event_mask is 0 and hnotification was not
626  *                      previously registered.
627  *      -EFAULT:    NULL hnotification, hnotification event name
628  *                      too long, or hnotification event name NULL.
629  *  Requires:
630  *      Valid chnl_obj.
631  *      hnotification != NULL.
632  *      (event_mask & ~(DSP_STREAMIOCOMPLETION | DSP_STREAMDONE)) == 0.
633  *      notify_type == DSP_SIGNALEVENT.
634  *  Ensures:
635  */
636 typedef int(*fxn_chnl_registernotify)
637  (struct chnl_object *chnl_obj,
638   u32 event_mask, u32 notify_type, struct dsp_notification *hnotification);
639 
640 /*
641  *  ======== bridge_dev_create ========
642  *  Purpose:
643  *      Complete creation of the device object for this board.
644  *  Parameters:
645  *      device_ctx:     Ptr to location to store a Bridge device context.
646  *      hdev_obj:     Handle to a Device Object, created and managed by DSP API.
647  *      config_param:        Ptr to configuration parameters provided by the
648  *                      Configuration Manager during device loading.
649  *      pDspConfig:     DSP resources, as specified in the registry key for this
650  *                      device.
651  *  Returns:
652  *      0:            Success.
653  *      -ENOMEM:        Unable to allocate memory for device context.
654  *  Requires:
655  *      device_ctx != NULL;
656  *      hdev_obj != NULL;
657  *      config_param != NULL;
658  *      pDspConfig != NULL;
659  *      Fields in config_param and pDspConfig contain valid values.
660  *  Ensures:
661  *      0:        All Bridge driver specific DSP resource and other
662  *                      board context has been allocated.
663  *      -ENOMEM:    Bridge failed to allocate resources.
664  *                      Any acquired resources have been freed.  The DSP API
665  *                      will not call bridge_dev_destroy() if
666  *                      bridge_dev_create() fails.
667  *  Details:
668  *      Called during the CONFIGMG's Device_Init phase. Based on host and
669  *      DSP configuration information, create a board context, a handle to
670  *      which is passed into other Bridge BRD and CHNL functions.  The
671  *      board context contains state information for the device. Since the
672  *      addresses of all pointer parameters may be invalid when this
673  *      function returns, they must not be stored into the device context
674  *      structure.
675  */
676 typedef int(*fxn_dev_create) (struct bridge_dev_context
677 				     **device_ctx,
678 				     struct dev_object
679 				     * hdev_obj,
680 				     struct cfg_hostres
681 				     * config_param);
682 
683 /*
684  *  ======== bridge_dev_ctrl ========
685  *  Purpose:
686  *      Bridge driver specific interface.
687  *  Parameters:
688  *      dev_ctxt:    Handle to Bridge driver defined device info.
689  *      dw_cmd:          Bridge driver defined command code.
690  *      pargs:          Pointer to an arbitrary argument structure.
691  *  Returns:
692  *      0 or -EPERM. Actual command error codes should be passed back in
693  *      the pargs structure, and are defined by the Bridge driver implementor.
694  *  Requires:
695  *      All calls are currently assumed to be synchronous.  There are no
696  *      IOCTL completion routines provided.
697  *  Ensures:
698  */
699 typedef int(*fxn_dev_ctrl) (struct bridge_dev_context *dev_ctxt,
700 				   u32 dw_cmd, void *pargs);
701 
702 /*
703  *  ======== bridge_dev_destroy ========
704  *  Purpose:
705  *      Deallocate Bridge device extension structures and all other resources
706  *      acquired by the Bridge driver.
707  *      No calls to other Bridge driver functions may subsequently
708  *      occur, except for bridge_dev_create().
709  *  Parameters:
710  *      dev_ctxt:    Handle to Bridge driver defined device information.
711  *  Returns:
712  *      0:        Success.
713  *      -EPERM:      Failed to release a resource previously acquired.
714  *  Requires:
715  *      dev_ctxt != NULL;
716  *  Ensures:
717  *      0: Device context is freed.
718  */
719 typedef int(*fxn_dev_destroy) (struct bridge_dev_context *dev_ctxt);
720 
721 /*
722  *  ======== bridge_io_create ========
723  *  Purpose:
724  *      Create an object that manages I/O between CHNL and msg_ctrl.
725  *  Parameters:
726  *      io_man:         Location to store IO manager on output.
727  *      hchnl_mgr:       Handle to channel manager.
728  *      hmsg_mgr:        Handle to message manager.
729  *  Returns:
730  *      0:        Success.
731  *      -ENOMEM:    Memory allocation failure.
732  *      -EPERM:      Creation failed.
733  *  Requires:
734  *      hdev_obj != NULL;
735  *      Channel manager already created;
736  *      Message manager already created;
737  *      mgr_attrts != NULL;
738  *      io_man != NULL;
739  *  Ensures:
740  */
741 typedef int(*fxn_io_create) (struct io_mgr **io_man,
742 				    struct dev_object *hdev_obj,
743 				    const struct io_attrs *mgr_attrts);
744 
745 /*
746  *  ======== bridge_io_destroy ========
747  *  Purpose:
748  *      Destroy object created in bridge_io_create.
749  *  Parameters:
750  *      hio_mgr:         IO Manager.
751  *  Returns:
752  *      0:        Success.
753  *      -ENOMEM:    Memory allocation failure.
754  *      -EPERM:      Creation failed.
755  *  Requires:
756  *      Valid hio_mgr;
757  *  Ensures:
758  */
759 typedef int(*fxn_io_destroy) (struct io_mgr *hio_mgr);
760 
761 /*
762  *  ======== bridge_io_on_loaded ========
763  *  Purpose:
764  *      Called whenever a program is loaded to update internal data. For
765  *      example, if shared memory is used, this function would update the
766  *      shared memory location and address.
767  *  Parameters:
768  *      hio_mgr:     IO Manager.
769  *  Returns:
770  *      0:    Success.
771  *      -EPERM:  Internal failure occurred.
772  *  Requires:
773  *      Valid hio_mgr;
774  *  Ensures:
775  */
776 typedef int(*fxn_io_onloaded) (struct io_mgr *hio_mgr);
777 
778 /*
779  *  ======== fxn_io_getprocload ========
780  *  Purpose:
781  *      Called to get the Processor's current and predicted load
782  *  Parameters:
783  *      hio_mgr:     IO Manager.
784  *      proc_load_stat   Processor Load statistics
785  *  Returns:
786  *      0:    Success.
787  *      -EPERM:  Internal failure occurred.
788  *  Requires:
789  *      Valid hio_mgr;
790  *  Ensures:
791  */
792 typedef int(*fxn_io_getprocload) (struct io_mgr *hio_mgr,
793 					 struct dsp_procloadstat *
794 					 proc_load_stat);
795 
796 /*
797  *  ======== bridge_msg_create ========
798  *  Purpose:
799  *      Create an object to manage message queues. Only one of these objects
800  *      can exist per device object.
801  *  Parameters:
802  *      msg_man:            Location to store msg_ctrl manager on output.
803  *      hdev_obj:         Handle to a device object.
804  *      msg_callback:        Called whenever an RMS_EXIT message is received.
805  *  Returns:
806  *      0:            Success.
807  *      -ENOMEM:        Insufficient memory.
808  *  Requires:
809  *      msg_man != NULL.
810  *      msg_callback != NULL.
811  *      hdev_obj != NULL.
812  *  Ensures:
813  */
814 typedef int(*fxn_msg_create)
815  (struct msg_mgr **msg_man,
816   struct dev_object *hdev_obj, msg_onexit msg_callback);
817 
818 /*
819  *  ======== bridge_msg_create_queue ========
820  *  Purpose:
821  *      Create a msg_ctrl queue for sending or receiving messages from a Message
822  *      node on the DSP.
823  *  Parameters:
824  *      hmsg_mgr:            msg_ctrl queue manager handle returned from
825  *                          bridge_msg_create.
826  *      msgq:               Location to store msg_ctrl queue on output.
827  *      msgq_id:	    Identifier for messages (node environment pointer).
828  *      max_msgs:           Max number of simultaneous messages for the node.
829  *      h:                  Handle passed to hmsg_mgr->msg_callback().
830  *  Returns:
831  *      0:            Success.
832  *      -ENOMEM:        Insufficient memory.
833  *  Requires:
834  *      msgq != NULL.
835  *      h != NULL.
836  *      max_msgs > 0.
837  *  Ensures:
838  *      msgq !=NULL <==> 0.
839  */
840 typedef int(*fxn_msg_createqueue)
841  (struct msg_mgr *hmsg_mgr,
842   struct msg_queue **msgq, u32 msgq_id, u32 max_msgs, void *h);
843 
844 /*
845  *  ======== bridge_msg_delete ========
846  *  Purpose:
847  *      Delete a msg_ctrl manager allocated in bridge_msg_create().
848  *  Parameters:
849  *      hmsg_mgr:    Handle returned from bridge_msg_create().
850  *  Returns:
851  *  Requires:
852  *      Valid hmsg_mgr.
853  *  Ensures:
854  */
855 typedef void (*fxn_msg_delete) (struct msg_mgr *hmsg_mgr);
856 
857 /*
858  *  ======== bridge_msg_delete_queue ========
859  *  Purpose:
860  *      Delete a msg_ctrl queue allocated in bridge_msg_create_queue.
861  *  Parameters:
862  *      msg_queue_obj:  Handle to msg_ctrl queue returned from
863  *                  bridge_msg_create_queue.
864  *  Returns:
865  *  Requires:
866  *      Valid msg_queue_obj.
867  *  Ensures:
868  */
869 typedef void (*fxn_msg_deletequeue) (struct msg_queue *msg_queue_obj);
870 
871 /*
872  *  ======== bridge_msg_get ========
873  *  Purpose:
874  *      Get a message from a msg_ctrl queue.
875  *  Parameters:
876  *      msg_queue_obj:     Handle to msg_ctrl queue returned from
877  *                     bridge_msg_create_queue.
878  *      pmsg:          Location to copy message into.
879  *      utimeout:      Timeout to wait for a message.
880  *  Returns:
881  *      0:       Success.
882  *      -ETIME:  Timeout occurred.
883  *      -EPERM:     No frames available for message (max_msgs too
884  *                     small).
885  *  Requires:
886  *      Valid msg_queue_obj.
887  *      pmsg != NULL.
888  *  Ensures:
889  */
890 typedef int(*fxn_msg_get) (struct msg_queue *msg_queue_obj,
891 				  struct dsp_msg *pmsg, u32 utimeout);
892 
893 /*
894  *  ======== bridge_msg_put ========
895  *  Purpose:
896  *      Put a message onto a msg_ctrl queue.
897  *  Parameters:
898  *      msg_queue_obj:      Handle to msg_ctrl queue returned from
899  *                      bridge_msg_create_queue.
900  *      pmsg:           Pointer to message.
901  *      utimeout:       Timeout to wait for a message.
902  *  Returns:
903  *      0:        Success.
904  *      -ETIME:   Timeout occurred.
905  *      -EPERM:      No frames available for message (max_msgs too
906  *                      small).
907  *  Requires:
908  *      Valid msg_queue_obj.
909  *      pmsg != NULL.
910  *  Ensures:
911  */
912 typedef int(*fxn_msg_put) (struct msg_queue *msg_queue_obj,
913 				  const struct dsp_msg *pmsg, u32 utimeout);
914 
915 /*
916  *  ======== bridge_msg_register_notify ========
917  *  Purpose:
918  *      Register notification for when a message is ready.
919  *  Parameters:
920  *      msg_queue_obj:      Handle to msg_ctrl queue returned from
921  *                      bridge_msg_create_queue.
922  *      event_mask:     Type of events to be notified about: Must be
923  *                      DSP_NODEMESSAGEREADY, or 0 to unregister.
924  *      notify_type:    DSP_SIGNALEVENT.
925  *      hnotification:  Handle of notification object.
926  *  Returns:
927  *      0:        Success.
928  *      -ENOMEM:    Insufficient memory.
929  *  Requires:
930  *      Valid msg_queue_obj.
931  *      hnotification != NULL.
932  *      notify_type == DSP_SIGNALEVENT.
933  *      event_mask == DSP_NODEMESSAGEREADY || event_mask == 0.
934  *  Ensures:
935  */
936 typedef int(*fxn_msg_registernotify)
937  (struct msg_queue *msg_queue_obj,
938   u32 event_mask, u32 notify_type, struct dsp_notification *hnotification);
939 
940 /*
941  *  ======== bridge_msg_set_queue_id ========
942  *  Purpose:
943  *      Set message queue id to node environment. Allows bridge_msg_create_queue
944  *      to be called in node_allocate, before the node environment is known.
945  *  Parameters:
946  *      msg_queue_obj:  Handle to msg_ctrl queue returned from
947  *                  bridge_msg_create_queue.
948  *      msgq_id:       Node environment pointer.
949  *  Returns:
950  *  Requires:
951  *      Valid msg_queue_obj.
952  *      msgq_id != 0.
953  *  Ensures:
954  */
955 typedef void (*fxn_msg_setqueueid) (struct msg_queue *msg_queue_obj,
956 				    u32 msgq_id);
957 
958 /*
959  *  Bridge Driver interface function table.
960  *
961  *  The information in this table is filled in by the specific Bridge driver,
962  *  and copied into the DSP API's own space.  If any interface
963  *  function field is set to a value of NULL, then the DSP API will
964  *  consider that function not implemented, and return the error code
965  *  -ENOSYS when a Bridge driver client attempts to call that function.
966  *
967  *  This function table contains DSP API version numbers, which are used by the
968  *  Bridge driver loader to help ensure backwards compatility between older
969  *  Bridge drivers and newer DSP API.  These must be set to
970  *  BRD_API_MAJOR_VERSION and BRD_API_MINOR_VERSION, respectively.
971  *
972  *  A Bridge driver need not export a CHNL interface.  In this case, *all* of
973  *  the bridge_chnl_* entries must be set to NULL.
974  */
975 struct bridge_drv_interface {
976 	u32 brd_api_major_version;	/* Set to BRD_API_MAJOR_VERSION. */
977 	u32 brd_api_minor_version;	/* Set to BRD_API_MINOR_VERSION. */
978 	fxn_dev_create dev_create;	/* Create device context */
979 	fxn_dev_destroy dev_destroy;	/* Destroy device context */
980 	fxn_dev_ctrl dev_cntrl;	/* Optional vendor interface */
981 	fxn_brd_monitor brd_monitor;	/* Load and/or start monitor */
982 	fxn_brd_start brd_start;	/* Start DSP program. */
983 	fxn_brd_stop brd_stop;	/* Stop/reset board. */
984 	fxn_brd_status brd_status;	/* Get current board status. */
985 	fxn_brd_read brd_read;	/* Read board memory */
986 	fxn_brd_write brd_write;	/* Write board memory. */
987 	fxn_brd_setstate brd_set_state;	/* Sets the Board State */
988 	fxn_brd_memcopy brd_mem_copy;	/* Copies DSP Memory */
989 	fxn_brd_memwrite brd_mem_write;	/* Write DSP Memory w/o halt */
990 	fxn_brd_memmap brd_mem_map;	/* Maps MPU mem to DSP mem */
991 	fxn_brd_memunmap brd_mem_un_map;	/* Unmaps MPU mem to DSP mem */
992 	fxn_chnl_create chnl_create;	/* Create channel manager. */
993 	fxn_chnl_destroy chnl_destroy;	/* Destroy channel manager. */
994 	fxn_chnl_open chnl_open;	/* Create a new channel. */
995 	fxn_chnl_close chnl_close;	/* Close a channel. */
996 	fxn_chnl_addioreq chnl_add_io_req;	/* Req I/O on a channel. */
997 	fxn_chnl_getioc chnl_get_ioc;	/* Wait for I/O completion. */
998 	fxn_chnl_cancelio chnl_cancel_io;	/* Cancl I/O on a channel. */
999 	fxn_chnl_flushio chnl_flush_io;	/* Flush I/O. */
1000 	fxn_chnl_getinfo chnl_get_info;	/* Get channel specific info */
1001 	/* Get channel manager info. */
1002 	fxn_chnl_getmgrinfo chnl_get_mgr_info;
1003 	fxn_chnl_idle chnl_idle;	/* Idle the channel */
1004 	/* Register for notif. */
1005 	fxn_chnl_registernotify chnl_register_notify;
1006 	fxn_io_create io_create;	/* Create IO manager */
1007 	fxn_io_destroy io_destroy;	/* Destroy IO manager */
1008 	fxn_io_onloaded io_on_loaded;	/* Notify of program loaded */
1009 	/* Get Processor's current and predicted load */
1010 	fxn_io_getprocload io_get_proc_load;
1011 	fxn_msg_create msg_create;	/* Create message manager */
1012 	/* Create message queue */
1013 	fxn_msg_createqueue msg_create_queue;
1014 	fxn_msg_delete msg_delete;	/* Delete message manager */
1015 	/* Delete message queue */
1016 	fxn_msg_deletequeue msg_delete_queue;
1017 	fxn_msg_get msg_get;	/* Get a message */
1018 	fxn_msg_put msg_put;	/* Send a message */
1019 	/* Register for notif. */
1020 	fxn_msg_registernotify msg_register_notify;
1021 	/* Set message queue id */
1022 	fxn_msg_setqueueid msg_set_queue_id;
1023 };
1024 
1025 /*
1026  *  ======== bridge_drv_entry ========
1027  *  Purpose:
1028  *      Registers Bridge driver functions with the DSP API. Called only once
1029  *      by the DSP API.  The caller will first check DSP API version
1030  *      compatibility, and then copy the interface functions into its own
1031  *      memory space.
1032  *  Parameters:
1033  *      drv_intf  Pointer to a location to receive a pointer to the
1034  *                      Bridge driver interface.
1035  *  Returns:
1036  *  Requires:
1037  *      The code segment this function resides in must expect to be discarded
1038  *      after completion.
1039  *  Ensures:
1040  *      drv_intf pointer initialized to Bridge driver's function
1041  *      interface. No system resources are acquired by this function.
1042  *  Details:
1043  *      Called during the Device_Init phase.
1044  */
1045 void bridge_drv_entry(struct bridge_drv_interface **drv_intf,
1046 		   const char *driver_file_name);
1047 
1048 #endif /* DSPDEFS_ */
1049