drivers/staging/tidspbridge/include/dspbridge/io.h

   1 /*
   2  * io.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * The io module manages IO between CHNL and msg_ctrl.
   7  *
   8  * Copyright (C) 2005-2006 Texas Instruments, Inc.
   9  *
  10  * This package is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License version 2 as
  12  * published by the Free Software Foundation.
  13  *
  14  * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  15  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  16  * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17  */
  18
  19 #ifndef IO_
  20 #define IO_
  21
  22 #include <dspbridge/cfgdefs.h>
  23 #include <dspbridge/devdefs.h>
  24
  25 #include <dspbridge/iodefs.h>
  26
  27 /*
  28  *  ======== io_create ========
  29  *  Purpose:
  30  *      Create an IO manager object, responsible for managing IO between
  31  *      CHNL and msg_ctrl.
  32  *  Parameters:
  33  *      channel_mgr:            Location to store a channel manager object on
  34  *                              output.
  35  *      hdev_obj:             Handle to a device object.
  36  *      mgr_attrts:              IO manager attributes.
  37  *      mgr_attrts->birq:        I/O IRQ number.
  38  *      mgr_attrts->irq_shared:     TRUE if the IRQ is shareable.
  39  *      mgr_attrts->word_size:   DSP Word size in equivalent PC bytes..
  40  *  Returns:
  41  *      0:                Success;
  42  *      -ENOMEM:            Insufficient memory for requested resources.
  43  *      -EIO:             Unable to plug channel ISR for configured IRQ.
  44  *      -EINVAL: Invalid DSP word size (must be > 0).
  45  *               Invalid base address for DSP communications.
  46  *  Requires:
  47  *      io_init(void) called.
  48  *      io_man != NULL.
  49  *      mgr_attrts != NULL.
  50  *  Ensures:
  51  */
  52 extern int io_create(struct io_mgr **io_man,
  53                             struct dev_object *hdev_obj,
  54                             const struct io_attrs *mgr_attrts);
  55
  56 /*
  57  *  ======== io_destroy ========
  58  *  Purpose:
  59  *      Destroy the IO manager.
  60  *  Parameters:
  61  *      hio_mgr:         IOmanager object.
  62  *  Returns:
  63  *      0:        Success.
  64  *      -EFAULT:    hio_mgr was invalid.
  65  *  Requires:
  66  *      io_init(void) called.
  67  *  Ensures:
  68  */
  69 extern int io_destroy(struct io_mgr *hio_mgr);
  70
  71 /*
  72  *  ======== io_exit ========
  73  *  Purpose:
  74  *      Discontinue usage of the IO module.
  75  *  Parameters:
  76  *  Returns:
  77  *  Requires:
  78  *      io_init(void) previously called.
  79  *  Ensures:
  80  *      Resources, if any acquired in io_init(void), are freed when the last
  81  *      client of IO calls io_exit(void).
  82  */
  83 extern void io_exit(void);
  84
  85 /*
  86  *  ======== io_init ========
  87  *  Purpose:
  88  *      Initialize the IO module's private state.
  89  *  Parameters:
  90  *  Returns:
  91  *      TRUE if initialized; FALSE if error occurred.
  92  *  Requires:
  93  *  Ensures:
  94  *      A requirement for each of the other public CHNL functions.
  95  */
  96 extern bool io_init(void);
  97
  98 /*
  99  *  ======== io_on_loaded ========
 100  *  Purpose:
 101  *      Called when a program is loaded so IO manager can update its
 102  *      internal state.
 103  *  Parameters:
 104  *      hio_mgr:         IOmanager object.
 105  *  Returns:
 106  *      0:        Success.
 107  *      -EFAULT:    hio_mgr was invalid.
 108  *  Requires:
 109  *      io_init(void) called.
 110  *  Ensures:
 111  */
 112 extern int io_on_loaded(struct io_mgr *hio_mgr);
 113
 114 #endif /* CHNL_ */