drivers/usb/host/dwc_common_port/dwc_cc.h

   1 /* =========================================================================
   2  * $File: //dwh/usb_iip/dev/software/dwc_common_port_2/dwc_cc.h $
   3  * $Revision: #4 $
   4  * $Date: 2010/09/28 $
   5  * $Change: 1596182 $
   6  *
   7  * Synopsys Portability Library Software and documentation
   8  * (hereinafter, "Software") is an Unsupported proprietary work of
   9  * Synopsys, Inc. unless otherwise expressly agreed to in writing
  10  * between Synopsys and you.
  11  *
  12  * The Software IS NOT an item of Licensed Software or Licensed Product
  13  * under any End User Software License Agreement or Agreement for
  14  * Licensed Product with Synopsys or any supplement thereto. You are
  15  * permitted to use and redistribute this Software in source and binary
  16  * forms, with or without modification, provided that redistributions
  17  * of source code must retain this notice. You may not view, use,
  18  * disclose, copy or distribute this file or any information contained
  19  * herein except pursuant to this license grant from Synopsys. If you
  20  * do not agree with this notice, including the disclaimer below, then
  21  * you are not authorized to use the Software.
  22  *
  23  * THIS SOFTWARE IS BEING DISTRIBUTED BY SYNOPSYS SOLELY ON AN "AS IS"
  24  * BASIS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  26  * FOR A PARTICULAR PURPOSE ARE HEREBY DISCLAIMED. IN NO EVENT SHALL
  27  * SYNOPSYS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  28  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  29  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  30  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  31  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  33  * USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  34  * DAMAGE.
  35  * ========================================================================= */
  36 #ifndef _DWC_CC_H_
  37 #define _DWC_CC_H_
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /** @file
  44  *
  45  * This file defines the Context Context library.
  46  *
  47  * The main data structure is dwc_cc_if_t which is returned by either the
  48  * dwc_cc_if_alloc function or returned by the module to the user via a provided
  49  * function. The data structure is opaque and should only be manipulated via the
  50  * functions provied in this API.
  51  *
  52  * It manages a list of connection contexts and operations can be performed to
  53  * add, remove, query, search, and change, those contexts.  Additionally,
  54  * a dwc_notifier_t object can be requested from the manager so that
  55  * the user can be notified whenever the context list has changed.
  56  */
  57
  58 #include "dwc_os.h"
  59 #include "dwc_list.h"
  60 #include "dwc_notifier.h"
  61
  62
  63 /* Notifications */
  64 #define DWC_CC_LIST_CHANGED_NOTIFICATION "DWC_CC_LIST_CHANGED_NOTIFICATION"
  65
  66 struct dwc_cc_if;
  67 typedef struct dwc_cc_if dwc_cc_if_t;
  68
  69
  70 /** @name Connection Context Operations */
  71 /** @{ */
  72
  73 /** This function allocates memory for a dwc_cc_if_t structure, initializes
  74  * fields to default values, and returns a pointer to the structure or NULL on
  75  * error. */
  76 extern dwc_cc_if_t *dwc_cc_if_alloc(void *mem_ctx, void *mtx_ctx,
  77                                     dwc_notifier_t *notifier, unsigned is_host);
  78
  79 /** Frees the memory for the specified CC structure allocated from
  80  * dwc_cc_if_alloc(). */
  81 extern void dwc_cc_if_free(void *mem_ctx, void *mtx_ctx, dwc_cc_if_t *cc_if);
  82
  83 /** Removes all contexts from the connection context list */
  84 extern void dwc_cc_clear(void *mem_ctx, dwc_cc_if_t *cc_if);
  85
  86 /** Adds a connection context (CHID, CK, CDID, Name) to the connection context list.
  87  * If a CHID already exists, the CK and name are overwritten.  Statistics are
  88  * not overwritten.
  89  *
  90  * @param cc_if The cc_if structure.
  91  * @param chid A pointer to the 16-byte CHID.  This value will be copied.
  92  * @param ck A pointer to the 16-byte CK.  This value will be copied.
  93  * @param cdid A pointer to the 16-byte CDID.  This value will be copied.
  94  * @param name An optional host friendly name as defined in the association model
  95  * spec.  Must be a UTF16-LE unicode string.  Can be NULL to indicated no name.
  96  * @param length The length othe unicode string.
  97  * @return A unique identifier used to refer to this context that is valid for
  98  * as long as this context is still in the list. */
  99 extern int32_t dwc_cc_add(void *mem_ctx, dwc_cc_if_t *cc_if, uint8_t *chid,
 100                           uint8_t *cdid, uint8_t *ck, uint8_t *name,
 101                           uint8_t length);
 102
 103 /** Changes the CHID, CK, CDID, or Name values of a connection context in the
 104  * list, preserving any accumulated statistics.  This would typically be called
 105  * if the host decideds to change the context with a SET_CONNECTION request.
 106  *
 107  * @param cc_if The cc_if structure.
 108  * @param id The identifier of the connection context.
 109  * @param chid A pointer to the 16-byte CHID.  This value will be copied.  NULL
 110  * indicates no change.
 111  * @param cdid A pointer to the 16-byte CDID.  This value will be copied.  NULL
 112  * indicates no change.
 113  * @param ck A pointer to the 16-byte CK.  This value will be copied.  NULL
 114  * indicates no change.
 115  * @param name Host friendly name UTF16-LE.  NULL indicates no change.
 116  * @param length Length of name. */
 117 extern void dwc_cc_change(void *mem_ctx, dwc_cc_if_t *cc_if, int32_t id,
 118                           uint8_t *chid, uint8_t *cdid, uint8_t *ck,
 119                           uint8_t *name, uint8_t length);
 120
 121 /** Remove the specified connection context.
 122  * @param cc_if The cc_if structure.
 123  * @param id The identifier of the connection context to remove. */
 124 extern void dwc_cc_remove(void *mem_ctx, dwc_cc_if_t *cc_if, int32_t id);
 125
 126 /** Get a binary block of data for the connection context list and attributes.
 127  * This data can be used by the OS specific driver to save the connection
 128  * context list into non-volatile memory.
 129  *
 130  * @param cc_if The cc_if structure.
 131  * @param length Return the length of the data buffer.
 132  * @return A pointer to the data buffer.  The memory for this buffer should be
 133  * freed with DWC_FREE() after use. */
 134 extern uint8_t *dwc_cc_data_for_save(void *mem_ctx, dwc_cc_if_t *cc_if,
 135                                      unsigned int *length);
 136
 137 /** Restore the connection context list from the binary data that was previously
 138  * returned from a call to dwc_cc_data_for_save.  This can be used by the OS specific
 139  * driver to load a connection context list from non-volatile memory.
 140  *
 141  * @param cc_if The cc_if structure.
 142  * @param data The data bytes as returned from dwc_cc_data_for_save.
 143  * @param length The length of the data. */
 144 extern void dwc_cc_restore_from_data(void *mem_ctx, dwc_cc_if_t *cc_if,
 145                                      uint8_t *data, unsigned int length);
 146
 147 /** Find the connection context from the specified CHID.
 148  *
 149  * @param cc_if The cc_if structure.
 150  * @param chid A pointer to the CHID data.
 151  * @return A non-zero identifier of the connection context if the CHID matches.
 152  * Otherwise returns 0. */
 153 extern uint32_t dwc_cc_match_chid(dwc_cc_if_t *cc_if, uint8_t *chid);
 154
 155 /** Find the connection context from the specified CDID.
 156  *
 157  * @param cc_if The cc_if structure.
 158  * @param cdid A pointer to the CDID data.
 159  * @return A non-zero identifier of the connection context if the CHID matches.
 160  * Otherwise returns 0. */
 161 extern uint32_t dwc_cc_match_cdid(dwc_cc_if_t *cc_if, uint8_t *cdid);
 162
 163 /** Retrieve the CK from the specified connection context.
 164  *
 165  * @param cc_if The cc_if structure.
 166  * @param id The identifier of the connection context.
 167  * @return A pointer to the CK data.  The memory does not need to be freed. */
 168 extern uint8_t *dwc_cc_ck(dwc_cc_if_t *cc_if, int32_t id);
 169
 170 /** Retrieve the CHID from the specified connection context.
 171  *
 172  * @param cc_if The cc_if structure.
 173  * @param id The identifier of the connection context.
 174  * @return A pointer to the CHID data.  The memory does not need to be freed. */
 175 extern uint8_t *dwc_cc_chid(dwc_cc_if_t *cc_if, int32_t id);
 176
 177 /** Retrieve the CDID from the specified connection context.
 178  *
 179  * @param cc_if The cc_if structure.
 180  * @param id The identifier of the connection context.
 181  * @return A pointer to the CDID data.  The memory does not need to be freed. */
 182 extern uint8_t *dwc_cc_cdid(dwc_cc_if_t *cc_if, int32_t id);
 183
 184 extern uint8_t *dwc_cc_name(dwc_cc_if_t *cc_if, int32_t id, uint8_t *length);
 185
 186 /** Checks a buffer for non-zero.
 187  * @param id A pointer to a 16 byte buffer.
 188  * @return true if the 16 byte value is non-zero. */
 189 static inline unsigned dwc_assoc_is_not_zero_id(uint8_t *id) {
 190         int i;
 191         for (i=0; i<16; i++) {
 192                 if (id[i]) return 1;
 193         }
 194         return 0;
 195 }
 196
 197 /** Checks a buffer for zero.
 198  * @param id A pointer to a 16 byte buffer.
 199  * @return true if the 16 byte value is zero. */
 200 static inline unsigned dwc_assoc_is_zero_id(uint8_t *id) {
 201         return !dwc_assoc_is_not_zero_id(id);
 202 }
 203
 204 /** Prints an ASCII representation for the 16-byte chid, cdid, or ck, into
 205  * buffer. */
 206 static inline int dwc_print_id_string(char *buffer, uint8_t *id) {
 207         char *ptr = buffer;
 208         int i;
 209         for (i=0; i<16; i++) {
 210                 ptr += DWC_SPRINTF(ptr, "%02x", id[i]);
 211                 if (i < 15) {
 212                         ptr += DWC_SPRINTF(ptr, " ");
 213                 }
 214         }
 215         return ptr - buffer;
 216 }
 217
 218 /** @} */
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* _DWC_CC_H_ */