diff gsm-fw/g23m-aci/gdd_dio/gdd.h @ 775:eedbf248bac0

gsm-fw/g23m-aci subtree: initial import from LoCosto source
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Sun, 12 Oct 2014 01:45:14 +0000
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gsm-fw/g23m-aci/gdd_dio/gdd.h	Sun Oct 12 01:45:14 2014 +0000
@@ -0,0 +1,440 @@
+/*  
++-----------------------------------------------------------------------------
+|  Project :  GSM-F&D (8411)
+|  Modul   :  BAT library
++-----------------------------------------------------------------------------
+|  Copyright 2002 Texas Instruments Berlin, AG
+|                 All rights reserved.
+|
+|                 This file is confidential and a trade secret of Texas
+|                 Instruments Berlin, AG
+|                 The receipt of or possession of this file does not convey
+|                 any rights to reproduce or disclose its contents or to
+|                 manufacture, use, or sell anything it may describe, in
+|                 whole, or in part, without the specific written consent of
+|                 Texas Instruments Berlin, AG.
++-----------------------------------------------------------------------------
+|  Purpose :  API of the Generic Data aDapter (GDD) which connects the
+|             application domain with the protocol stack.
++-----------------------------------------------------------------------------
+*/
+
+#ifndef GDD_H 
+#define GDD_H
+
+/*==== INCLUDES =============================================================*/
+
+/*==== DEFINITIONS ==========================================================*/
+
+/** Return and error values of GDD functions */
+enum GDD_RESULT_CODES
+{
+  GDD_OK                    = 0,   /* OK, no error occured */
+  GDD_BUSY                  = 1,   /* Currently busy */
+  GDD_DIO_NOT_READY         = 2,   /* Dio not initialized or ready */
+  GDD_NO_CONNECTION_SLOT    = 3,   /* Max number of connections already open */
+  GDD_NO_BUF_AVAILABLE      = 4,   /* No buffer available (for sending) */
+  GDD_INVALID_PARAMS        = 5,   /* Invalid input parameter */
+  GDD_REQ_BUF_TOO_LARGE     = 6,   /* Requested buffer too large */
+  GDD_INVALID_BUFFER        = 7,   /* Invalid buffer */
+  GDD_ALREADY_INITIALIZED   = 97,  /* Instance already initialized */
+  GDD_NO_MEMORY             = 98,  /* Memory allocation during initialization failed */
+  GDD_INTERNAL_ERROR        = 99   /* General error code for all other errors */
+};
+
+
+/*==== CONSTS ===============================================================*/
+
+/** This size that's required for maintenance of one single connection.
+    Only needed if the application must allocated memory to be passed into
+    gdd_init(). */
+#define GDD_DIO_SIZEOF_CONDATA 64
+
+/** Size of first buffer segment (used for internal purposes) */
+#define GDD_DIO_PID_SEG_SIZE   2
+
+
+/*==== TYPES =================================================================*/
+
+/** Connection handle */
+typedef U32 T_GDD_CON_HANDLE;
+
+
+/** Identifier for the adapter instances - each instance corresponds to a
+    DIO driver type */
+typedef enum 
+{
+  GDD_INST_NONE = -1,
+  GDD_INST_BAT     = 0,   /* The BAT library                */
+  GDD_INST_APP,           /* Application                    */
+  GDD_INST_TCP,           /* TCPIP entity                   */
+  GDD_INST_SOCK,          /* Socket library                 */
+  GDD_INST_SOCKCFG,       /* Socket library configuration   */
+  
+  /* Add new instances here and increase GDD_NUM_INSTS accordingly */     
+  GDD_NUM_INSTS,
+  /* Maximum number of instances is defined by GDD_MAX_INST_ID */
+  GDD_MAX_INST_ID     = 255
+} T_GDD_INST_ID;
+
+
+/*
+ *  GDD data format - identicial to DIOv4 data format.
+ */
+typedef struct
+{
+  U8             _align0;      /*<  0:  1> alignment */
+  U8             _align1;      /*<  1:  1> alignment */
+  U16            c_data;       /*<  2:  2> counter   */
+  U8             *ptr_data;    /*<  4:  4> pointer to  pointer to the first
+                                           byte of the data buffer segment */
+} T_GDD_SEGMENT;
+
+typedef struct
+{
+  U16            length;           /*<  0:  2> len of dio_ctrl */
+  U8             _align0;          /*<  2:  1> alignment */
+  U8             c_segment;        /*<  3:  1> counter of segments */
+  T_GDD_SEGMENT  *ptr_gdd_segment; /*<  4:  4> pointer to Structured Element */
+} T_GDD_BUF;
+
+
+
+/** Capabilities of DIO BAT adapter, to be set by the client */
+typedef struct
+{
+  U32               mtu_size;
+} T_GDD_DIO_CAP;
+
+
+/** Capabilities of the BAT adapter, to be set by the client */
+typedef union
+{
+  T_GDD_DIO_CAP     dio_cap;
+  /* Capabilities for future adapter implementations to be added here */
+} T_GDD_CAP;
+
+
+/** GDD result type */
+typedef U16 GDD_RESULT;
+
+
+/** Signal types */
+typedef enum
+{
+  GDD_SIGTYPE_CONNECTION_OPENED  = 1, /* Connection is established and usable */
+  GDD_SIGTYPE_CONNECTION_FAILED  = 2, /* Connection failed or closed down unexpectedly */
+  GDD_SIGTYPE_SEND_BUF_AVAILABLE = 3, /* A new send buffer becomes available after an
+                                         unsuccessfull call to gdd_get_send_buffer */
+  GDD_SIGTYPE_BUF_SENT           = 4  /* Indicates that the last sent buffer has been
+                                         successfully sent */ 
+} T_GDD_SIGTYPE;
+
+
+
+/** Data associated with a GDD signal */
+typedef struct
+{
+  T_GDD_SIGTYPE     sig;
+} T_GDD_SIGNAL;
+
+
+
+/***************************************************************************
+ * Call-back function definitions (to be implemented by the client)
+ ***************************************************************************/
+   
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_signal_cb
++------------------------------------------------------------------------------
+| Description : The adapter calls this call-back function to send received data
+|               to the client. The client must copy the data contained in the
+|               buffer, since the buffer will be invalidated upon returning
+|               from this function.
+|               Alternatively, the client can indicate that he is currently
+|               busy. In this case, he has to call gdd_signal_ready_rcv() at a
+|               later time to invoke this call-back function again.
+|
+| Parameters  : sig            - Signal
++------------------------------------------------------------------------------
+*/
+typedef void (* T_GDD_SIGNAL_CB)
+( T_GDD_CON_HANDLE    con,
+  T_GDD_SIGNAL        sig );
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_received_data_cb
++------------------------------------------------------------------------------
+| Description : The adapter calls this callback function to signal events to
+|               the client.
+|
+| Parameters  : sig            - Signal
+|
+| Return      : GDD_OK         - Data was copied by client
+|               GDD_BUSY       - Client was busy and could not receive data.
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_RECEIVE_DATA_CB)
+( T_GDD_CON_HANDLE    con,
+  T_GDD_BUF *         buf );
+
+
+/***************************************************************************
+ * Function definitions
+ ***************************************************************************/
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_init
++------------------------------------------------------------------------------
+| Description : This optional function can be used to provide the house-keeping
+|               memory required for the given adapter instance. On platforms
+|               where memory allocation is available, the function might be
+|               called with the parameter mem set to 0. In this case, it is
+|               just use to limit the number of connections via the parameter
+|               num_con.
+|
+| Parameters  : inst           - Instance identifier of the adapter
+|               mem            - Memory allocated by client for maintenance
+|                                of the connections (Input parameter).
+|                                If set to 0, the adapter will allocate
+|                                the memory itself.
+|               num_con        - Maximum number of connections
+|
+| Return      : GDD_OK         - Initialization successful
+|               >GDD_OK        - Error (see manual for error codes)
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_INIT)
+( T_GDD_INST_ID     inst,
+  void *            mem,
+  U16               num_con);
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_deinit
++------------------------------------------------------------------------------
+| Description : This function de-initializes an adapter instance.
+|               Any memory that the adapter has allocated internally is freed.
+|
+| Parameters  : inst           - Instance identifier of the adapter
+|
+| Return      : GDD_OK         - Initialization successful
+|               >GDD_OK        - Error (see manual for error codes)
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_DEINIT)
+( T_GDD_INST_ID     inst);
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_connect
++------------------------------------------------------------------------------
+| Description : This function prepares a new connection for data transmission.
+|               If the function succeeds, it will return a connection handle
+|               in the parameter 'con_handle' to the caller. Each connection is
+|               uniquely identified by its connection handle.
+| 
+| Note        : The connection cannot be used straight away. Instead, the
+|               client receives a signal GDD_SIGTYPE_CONNECTION_OPENED when the
+|               connection setup has been finished.
+|
+|               Each open connection should be closed using the function
+|               gdd_close() when it is not used any longer.
+|
+| Parameters  : inst       - Instance identifier of the adapter
+|               con_handle - New handle to the adapter passed back to the
+|                            caller (output parameter).
+|               cap        - capabilities of the adapter
+|               rcv_cb     - Call-back for receiving data (provided by client)
+|               sig_cb     - Call-back for signals (provided by client)
+|
+| Return      : GDD_OK     - Connecting is setup and being created. The client
+|                            has to wait for signal GDD_SIGTYPE_CONNECTION_OPENED
+|                            before the connection is usable.
+|               >GDD_OK    - Error (see manual for error codes)
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_CONNECT)
+( T_GDD_INST_ID     inst,
+  T_GDD_CON_HANDLE * con_handle,
+  const T_GDD_CAP * cap,
+  T_GDD_RECEIVE_DATA_CB rcv_cb,
+  T_GDD_SIGNAL_CB   sig_cb );
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_disconnect
++------------------------------------------------------------------------------
+| Description : This function closes and deletes a connection.
+|               The connection handle will not be valid any longer.
+|
+| Parameters  : con_handle     - Handle to the connection to be closed
+|
+| Return      : GDD_OK         - Initialization successful
+|               >GDD_OK        - Error (see manual for error codes)
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_DISCONNECT)
+( T_GDD_CON_HANDLE  con_handle );
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_get_send_buffer
++------------------------------------------------------------------------------
+| Description : This function request a send buffer of a minimum size data_size
+|               for sending on the connection specified with con. The buffer is
+|               passed back in the parameter 'buf'.
+|               After a successful call to this function, it is the
+|               responsibility of the caller to subsequently fill the buffer
+|               and call gdd_send_data(), before another call to
+|               gdd_get_send_buffer() is done. In other words, the client must
+|               make sure that calls to these two functions are synchronized.
+|
+| Parameters  : con_handle  - Connection handle
+|               buf         - Pointer to pointer to send buffer (out parameter)
+|               data_size   - Minimum size of requested buffer
+|
+| Return      : GDD_OK                - Initialization successful
+|               >GDD_OK               - Error (see manual for error codes)
+|               GDD_NO_BUF_AVAILABLE  - No buffer available. The client
+|                                       will be notified with a signal
+|                                       GDD_SIGTYPE_SEND_BUF_AVAILABLE when a
+|                                       buffer is ready and can be requested.
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_GET_SEND_BUFFER)
+( T_GDD_CON_HANDLE  con_handle,
+  T_GDD_BUF **      buf,
+  U16               data_size );
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_send_data
++------------------------------------------------------------------------------
+| Description : This functions sends a buffer over the specified connection.
+|               Please see also description of gdd_get_send_buffer().
+|
+|
+| Parameters  : con_handle  - Connection handle
+|               buf         - Buffer to be sent
+|
+| Return      : GDD_OK             - Initialization successful
+|               >GDD_OK            - Error (see manual for error codes)
+|               GDD_INVALID_BUFFER - The buffer pointed to is incorrect, i.e.
+|                                    not the one that was previously requested
++------------------------------------------------------------------------------
+*/
+typedef GDD_RESULT (* T_GDD_SEND_DATA)
+( T_GDD_CON_HANDLE  con,
+  T_GDD_BUF *       buf);
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_signal_ready_rcv
++------------------------------------------------------------------------------
+| Description : This function is called from the client to indicate that he
+|               is ready to receive. Typically, it is called from the client
+|               when he becomes ready after a preceding result callback
+|               (result_cb) was returned with GDD_BUSY.
+|
+| Parameters  : con_handle  - Connection handle
++------------------------------------------------------------------------------
+*/
+typedef void (* T_GDD_SIGNAL_READY_RCV)
+( T_GDD_CON_HANDLE  con );
+
+
+/** GDD Function pointer table */
+typedef struct
+{
+  T_GDD_INIT             gdd_init;
+  T_GDD_DEINIT           gdd_deinit;
+  T_GDD_CONNECT          gdd_connect;
+  T_GDD_DISCONNECT       gdd_disconnect;
+  T_GDD_GET_SEND_BUFFER  gdd_get_send_buffer;
+  T_GDD_SEND_DATA        gdd_send_data;
+  T_GDD_SIGNAL_READY_RCV gdd_signal_ready_rcv;
+} T_GDD_FUNC;
+
+
+/** Needed for initialization of client of BAT adapter (BAT library) */
+extern T_GDD_FUNC gdd_func_dio;
+
+
+/***************************************************************************
+ * Helper function definitions
+ ***************************************************************************/
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_write_buf
++------------------------------------------------------------------------------
+| Description : Write data from a client buffer into into a GDD buffer
+|               The datagram protocol ID for the following link layer (PPP) is
+|               set internally to 0x21 (IPv4). If you need to set the protocol
+|               ID to something else, please use the function 
+|               gdd_write_buf_with_pid()..
+|
+| Parameters  : src_buf    - Source buffer (client owned)
+|               src_size   - Size of source buffer
+|               dest_buf   - Destination buffer
+|
+| Return      : 0 if all bytes have been written to the destination buffer.
+|               If not all bytes could be written, the return value is larger
+|               than 0 and denotes the number of remaining (unwritten) bytes.
+|               A negative return value indicates an error.
++------------------------------------------------------------------------------
+*/
+S32 gdd_write_buf(const U8 * src_buf, U16 src_size, T_GDD_BUF * dest_buf);
+
+/*
++------------------------------------------------------------------------------
+| Description : Write user data and a datagram protocol ID used by the link 
+|               layer (PPP) into a GDD buffer.
+|
+| Parameters  : src_buf     - Source buffer (client owned)
+|               src_size    - Size of source buffer
+|               dest_buf    - Destination buffer
+|               protocol_id - datagram protocol identifier
+|
+| Return      : 0 if all bytes have been written to the destination buffer.
+|               If not all bytes could be written, the return value is larger
+|               than 0 and denotes the number of remaining (unwritten) bytes.
+|               A negative return value indicates an error.
++------------------------------------------------------------------------------
+*/
+S32 gdd_write_buf_with_pid(const U8 * src_buf,  U16 src_size,
+                           T_GDD_BUF * dest_buf,U8 protocol_id);
+
+
+/*
++------------------------------------------------------------------------------
+| Function    : gdd_read_buf
++------------------------------------------------------------------------------
+| Description : Read data from a GDD buffer into a client buffer.
+|
+| Parameters  : src_buf    - Source buffer received from GDD
+|               dest_buf   - Destination buffer (client owned)
+|               dest_size  - Size of destination buffer
+|
+| Return      : 0 if all bytes have been copied into the destination buffer.
+|               If not all bytes could be copied into the destination buffer,
+|               the return value is larger than 0 and denotes the number of
+|               remaining (unread) bytes. A negative return value indicase an
+|               error.
++------------------------------------------------------------------------------
+*/
+S32 gdd_read_buf(const T_GDD_BUF * src_buf, U8 * dest_buf, U16 dest_size);
+
+
+#endif /* GDD_H */