components/common/inc/stream_private.h

   1 /******************************************************************************
   2  @file stream_private.h
   3
   4  @brief TIMAC 2.0 API Internal "stream" implimentation details
   5
   6  Group: WCS LPC
   7  $Target Devices: Linux: AM335x, Embedded Devices: CC1310, CC1350$
   8
   9  ******************************************************************************
  10  $License: BSD3 2016 $
  11
  12    Copyright (c) 2015, Texas Instruments Incorporated
  13    All rights reserved.
  14
  15    Redistribution and use in source and binary forms, with or without
  16    modification, are permitted provided that the following conditions
  17    are met:
  18
  19    *  Redistributions of source code must retain the above copyright
  20       notice, this list of conditions and the following disclaimer.
  21
  22    *  Redistributions in binary form must reproduce the above copyright
  23       notice, this list of conditions and the following disclaimer in the
  24       documentation and/or other materials provided with the distribution.
  25
  26    *  Neither the name of Texas Instruments Incorporated nor the names of
  27       its contributors may be used to endorse or promote products derived
  28       from this software without specific prior written permission.
  29
  30    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  31    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  32    THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  33    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  34    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  35    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  36    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  37    OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  38    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  39    OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  40    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41  ******************************************************************************
  42  $Release Name: TI-15.4Stack Linux x64 SDK$
  43  $Release Date: July 14, 2016 (2.00.00.30)$
  44  *****************************************************************************/
  45
  46 /*
  47  * OVERVIEW
  48  * ========
  49  *
  50  * The STREAM implimentations share a number of "common" features
  51  * This header file describes the common items shared across all
  52  * streams, it is not intended for use by general code
  53  * it should only be used by code that is implimenting a stream.
  54  */
  55
  56 #if !defined(STREAM_PRIVATE_H)
  57 #define STREAM_PRIVATE_H
  58
  59
  60 #if !defined(_STREAM_IMPLIMENTOR_)
  61 #error This file should only be included by stream implimentation code.
  62 #endif
  63
  64 /* forward decloration */
  65 struct io_stream_funcs;
  66
  67 /*!
  68  * @struct io_stream - represents byte stream, emulates the stdio FILE
  69  *
  70  * To create a stream, call one of the STREAM_CREATE_foobar() functions
  71  * where foobar is the type of interface you wish to access.
  72  */
  73 struct io_stream {
  74     /*! check value, used to verify this is an io-stream */
  75     const int *check_ptr;
  76
  77     /*! stream specific funcs (method functions, specific to stream type)*/
  78     const struct io_stream_funcs *pFuncs;
  79
  80     /*! for use internal by stream specific funcs */
  81     intptr_t opaque_ptr;
  82
  83     /*! for use internal by the io stream to handle unget operations */
  84     int      unget_buf;
  85
  86     /* set to true when an error occurs. */
  87     bool     is_error;
  88
  89     /*! for use by the rd callback */
  90     intptr_t rd_rdy_cookie;
  91
  92     /*!  this callback is called when data is put into the rx fifo */
  93     void (*rd_rdy_cb)(struct io_stream *pIO, int nAvail);
  94 };
  95
  96 /*!
  97  * @struct io_stream_funcs
  98  *
  99  * @brief Functions (methods) that backend various streams
 100  */
 101 struct io_stream_funcs {
 102     /*! Name for debug purposes */
 103     const char *name;
 104
 105     /*! close the stream, does not always release resources */
 106     void (*close_fn)(struct io_stream *pIO);
 107
 108     /*!
 109      * @brief write bytes to the stream
 110      * @param pIO stream - the io stream to use
 111      * @param pData - data buffer holding the data
 112      * @param nbytes - number of bytes to write
 113      * @param timeout_mSecs - timeout in milliseconds (see timeout mSec rule)
 114      *
 115      * @return -1 on error, 0..actual number of bytes written
 116      */
 117     int  (*wr_fn)(struct io_stream *pIO, const void *pData, size_t n, int timeout_mSecs);
 118
 119     /*!
 120      * @brief read bytes from the stream
 121      * @param pIO stream - the io stream to use
 122      * @param pData - data buffer to put data into
 123      * @param nbytes - number of bytes to read
 124      * @param timeout_mSecs - timeout in milliseconds (see timeout mSec rule)
 125      *
 126      * @return -1 on error, 0..actual number of bytes read
 127      */
 128     int  (*rd_fn)(struct io_stream *pIO, void *pData, size_t n, int timeout_mSecs);
 129
 130     /*!
 131      * @brief Determine if the io stream is readable
 132      *
 133      * @param pIO - the io stream
 134      * @param timeout_mSec - the timeout for the poll operation
 135      * @return true if it is, false if not
 136      */
 137     bool  (*poll_fn)(struct io_stream *pIO, int timeout_mSec);
 138
 139     /*!
 140      * @brief Flush all buffered IO to the device
 141      *
 142      * @param pIO - the io stream
 143      *
 144      * @return negative error, 0 success
 145      */
 146     int  (*flush_fn)(struct io_stream *pIO);
 147
 148     /*!
 149      * @brief clear underlying errors.
 150      *
 151      * @param pIO - the io stream
 152      */
 153     void (*clear_fn)(struct io_stream *pIO);
 154 };
 155
 156 /*!
 157  * @brief Create & Initialize a io_stream properly
 158  * @param pFuncs - set of method functions for this stream.
 159  * @param opaque - the opaque parameter for the method functions
 160  *
 161  * @returns NULL on error, or an initialized io stream
 162  *
 163  * To return the "handle" to the caller, cast the "io_stream" pointer
 164  * to an intptr_t.
 165  */
 166 struct io_stream *STREAM_createPrivate(const struct io_stream_funcs *pFuncs, intptr_t opaque);
 167
 168 /*!
 169  * @brief Release resources (memory) in the io_stream structure
 170  * @param pIO - io stream from STREAM_CreatePrivate()
 171  */
 172 void STREAM_destroyPrivate(struct io_stream *pIO);
 173
 174 /*!
 175  * @brief convert an handle into an io_stream structure pointer.
 176  * @param h - public version (handle) of an IO stream
 177  * @returns NULL if h is invalid, or a proper structure pointer.
 178  */
 179 struct io_stream *STREAM_hToStruct(intptr_t h);
 180
 181 /*
 182  * @brief convert an io_stream structure pointer into a public handle
 183  * @param pIO - the io stream to convert.
 184  * @returns proper value for the IO stream
 185  */
 186 intptr_t STREAM_structToH(struct io_stream *pIO);
 187
 188 #endif
 189
 190 /*
 191  *  ========================================
 192  *  Texas Instruments Micro Controller Style
 193  *  ========================================
 194  *  Local Variables:
 195  *  mode: c
 196  *  c-file-style: "bsd"
 197  *  tab-width: 4
 198  *  c-basic-offset: 4
 199  *  indent-tabs-mode: nil
 200  *  End:
 201  *  vim:set  filetype=c tabstop=4 shiftwidth=4 expandtab=true
 202  */
 203