drivers/xilinx_common/xversion.c

   1 /* $Id: xversion.c,v 1.1 2006/12/13 14:23:34 imanuilov Exp $ */
   2 /******************************************************************************
   3 *
   4 *       XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
   5 *       AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
   6 *       SOLUTIONS FOR XILINX DEVICES.  BY PROVIDING THIS DESIGN, CODE,
   7 *       OR INFORMATION AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE,
   8 *       APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION
   9 *       THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
  10 *       AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE
  11 *       FOR YOUR IMPLEMENTATION.  XILINX EXPRESSLY DISCLAIMS ANY
  12 *       WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE
  13 *       IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR
  14 *       REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
  15 *       INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  16 *       FOR A PARTICULAR PURPOSE.
  17 *
  18 *       (c) Copyright 2002 Xilinx Inc.
  19 *       All rights reserved.
  20 *
  21 ******************************************************************************/
  22 /*****************************************************************************/
  23 /**
  24 *
  25 * @file xversion.c
  26 *
  27 * This file contains the implementation of the XVersion component. This
  28 * component represents a version ID.  It is encapsulated within a component
  29 * so that it's type and implementation can change without affecting users of
  30 * it.
  31 *
  32 * The version is formatted as X.YYZ where X = 0 - 9, Y = 00 - 99, Z = a - z
  33 * X is the major revision, YY is the minor revision, and Z is the
  34 * compatability revision.
  35 *
  36 * Packed versions are also utilized for the configuration ROM such that
  37 * memory is minimized. A packed version consumes only 16 bits and is
  38 * formatted as follows.
  39 *
  40 * <pre>
  41 * Revision                  Range       Bit Positions
  42 *
  43 * Major Revision            0 - 9       Bits 15 - 12
  44 * Minor Revision            0 - 99      Bits 11 - 5
  45 * Compatability Revision    a - z       Bits 4 - 0
  46 *
  47 * MODIFICATION HISTORY:
  48 *
  49 * Ver   Who    Date   Changes
  50 * ----- ---- -------- -------------------------------------------------------
  51 * 1.00a xd   11/03/04 Improved support for doxygen.
  52 </pre>
  53 *
  54 ******************************************************************************/
  55
  56
  57 /***************************** Include Files *********************************/
  58
  59 #include "xbasic_types.h"
  60 #include "xversion.h"
  61
  62 /************************** Constant Definitions *****************************/
  63
  64 /* the following constants define the masks and shift values to allow the
  65  * revisions to be packed and unpacked, a packed version is packed into a 16
  66  * bit value in the following format, XXXXYYYYYYYZZZZZ, where XXXX is the
  67  * major revision, YYYYYYY is the minor revision, and ZZZZZ is the compatability
  68  * revision
  69  */
  70 #define XVE_MAJOR_SHIFT_VALUE       12
  71 #define XVE_MINOR_ONLY_MASK         0x0FE0
  72 #define XVE_MINOR_SHIFT_VALUE       5
  73 #define XVE_COMP_ONLY_MASK          0x001F
  74
  75 /* the following constants define the specific characters of a version string
  76  * for each character of the revision, a version string is in the following
  77  * format, "X.YYZ" where X is the major revision (0 - 9), YY is the minor
  78  * revision (00 - 99), and Z is the compatability revision (a - z)
  79  */
  80 #define XVE_MAJOR_CHAR      0   /* major revision 0 - 9 */
  81 #define XVE_MINOR_TENS_CHAR 2   /* minor revision tens 0 - 9 */
  82 #define XVE_MINOR_ONES_CHAR 3   /* minor revision ones 0 - 9 */
  83 #define XVE_COMP_CHAR       4   /* compatability revision a - z */
  84 #define XVE_END_STRING_CHAR 5
  85
  86 /**************************** Type Definitions *******************************/
  87
  88
  89 /***************** Macros (Inline Functions) Definitions *********************/
  90
  91
  92 /************************** Function Prototypes ******************************/
  93
  94 static u32 IsVersionStringValid(s8 *StringPtr);
  95
  96 /*****************************************************************************/
  97 /**
  98 *
  99 * Unpacks a packed version into the specified version. Versions are packed
 100 * into the configuration ROM to reduce the amount storage. A packed version
 101 * is a binary format as oppossed to a non-packed version which is implemented
 102 * as a string.
 103 *
 104 * @param    InstancePtr points to the version to unpack the packed version into.
 105 * @param    PackedVersion contains the packed version to unpack.
 106 *
 107 * @return   None.
 108 *
 109 * @note     None.
 110 *
 111 ******************************************************************************/
 112 void XVersion_UnPack(XVersion * InstancePtr, u16 PackedVersion)
 113 {
 114         /* not implemented yet since CROM related */
 115 }
 116
 117 /*****************************************************************************/
 118 /**
 119 *
 120 * Packs a version into the specified packed version. Versions are packed into
 121 * the configuration ROM to reduce the amount storage.
 122 *
 123 * @param    InstancePtr points to the version to pack.
 124 * @param    PackedVersionPtr points to the packed version which will receive
 125 *           the new packed version.
 126 *
 127 * @return
 128 *
 129 * A status, XST_SUCCESS, indicating the packing was accomplished
 130 * successfully, or an error, XST_INVALID_VERSION, indicating the specified
 131 * input version was not valid such that the pack did not occur
 132 * <br><br>
 133 * The packed version pointed to by PackedVersionPtr is modified with the new
 134 * packed version if the status indicates success.
 135 *
 136 * @note
 137 *
 138 * None.
 139 *
 140 ******************************************************************************/
 141 int XVersion_Pack(XVersion * InstancePtr, u16 *PackedVersionPtr)
 142 {
 143         /* not implemented yet since CROM related */
 144
 145         return XST_SUCCESS;
 146 }
 147
 148 /*****************************************************************************/
 149 /**
 150 *
 151 * Determines if two versions are equal.
 152 *
 153 * @param    InstancePtr points to the first version to be compared.
 154 * @param    VersionPtr points to a second version to be compared.
 155 *
 156 * @return
 157 *
 158 * TRUE if the versions are equal, FALSE otherwise.
 159 *
 160 * @note
 161 *
 162 * None.
 163 *
 164 ******************************************************************************/
 165 u32 XVersion_IsEqual(XVersion * InstancePtr, XVersion * VersionPtr)
 166 {
 167         u8 *Version1 = (u8 *) InstancePtr;
 168         u8 *Version2 = (u8 *) VersionPtr;
 169         int Index;
 170
 171         /* assert to verify input arguments */
 172
 173         XASSERT_NONVOID(InstancePtr != NULL);
 174         XASSERT_NONVOID(VersionPtr != NULL);
 175
 176         /* check each byte of the versions to see if they are the same,
 177          * return at any point a byte differs between them
 178          */
 179         for (Index = 0; Index < sizeof(XVersion); Index++) {
 180                 if (Version1[Index] != Version2[Index]) {
 181                         return FALSE;
 182                 }
 183         }
 184
 185         /* No byte was found to be different between the versions, so indicate
 186          * the versions are equal
 187          */
 188         return TRUE;
 189 }
 190
 191 /*****************************************************************************/
 192 /**
 193 *
 194 * Converts a version to a null terminated string.
 195 *
 196 * @param    InstancePtr points to the version to convert.
 197 * @param    StringPtr points to the string which will be the result of the
 198 *           conversion. This does not need to point to a null terminated
 199 *           string as an input, but must point to storage which is an adequate
 200 *           amount to hold the result string.
 201 *
 202 * @return
 203 *
 204 * The null terminated string is inserted at the location pointed to by
 205 * StringPtr if the status indicates success.
 206 *
 207 * @note
 208 *
 209 * It is necessary for the caller to have already allocated the storage to
 210 * contain the string.  The amount of memory necessary for the string is
 211 * specified in the version header file.
 212 *
 213 ******************************************************************************/
 214 void XVersion_ToString(XVersion * InstancePtr, s8 *StringPtr)
 215 {
 216         /* assert to verify input arguments */
 217
 218         XASSERT_VOID(InstancePtr != NULL);
 219         XASSERT_VOID(StringPtr != NULL);
 220
 221         /* since version is implemented as a string, just copy the specified
 222          * input into the specified output
 223          */
 224         XVersion_Copy(InstancePtr, (XVersion *) StringPtr);
 225 }
 226
 227 /*****************************************************************************/
 228 /**
 229 *
 230 * Initializes a version from a null terminated string. Since the string may not
 231 * be a format which is compatible with the version, an error could occur.
 232 *
 233 * @param    InstancePtr points to the version which is to be initialized.
 234 * @param    StringPtr points to a null terminated string which will be
 235 *           converted to a version.  The format of the string must match the
 236 *           version string format which is X.YYX where X = 0 - 9, YY = 00 - 99,
 237 *           Z = a - z.
 238 *
 239 * @return
 240 *
 241 * A status, XST_SUCCESS, indicating the conversion was accomplished
 242 * successfully, or XST_INVALID_VERSION indicating the version string format
 243 * was not valid.
 244 *
 245 * @note
 246 *
 247 * None.
 248 *
 249 ******************************************************************************/
 250 int XVersion_FromString(XVersion * InstancePtr, s8 *StringPtr)
 251 {
 252         /* assert to verify input arguments */
 253
 254         XASSERT_NONVOID(InstancePtr != NULL);
 255         XASSERT_NONVOID(StringPtr != NULL);
 256
 257         /* if the version string specified is not valid, return an error */
 258
 259         if (!IsVersionStringValid(StringPtr)) {
 260                 return XST_INVALID_VERSION;
 261         }
 262
 263         /* copy the specified string into the specified version and indicate the
 264          * conversion was successful
 265          */
 266         XVersion_Copy((XVersion *) StringPtr, InstancePtr);
 267
 268         return XST_SUCCESS;
 269 }
 270
 271 /*****************************************************************************/
 272 /**
 273 *
 274 * Copies the contents of a version to another version.
 275 *
 276 * @param    InstancePtr points to the version which is the source of data for
 277 *           the copy operation.
 278 * @param    VersionPtr points to another version which is the destination of
 279 *           the copy operation.
 280 *
 281 * @return
 282 *
 283 * None.
 284 *
 285 * @note
 286 *
 287 * None.
 288 *
 289 ******************************************************************************/
 290 void XVersion_Copy(XVersion * InstancePtr, XVersion * VersionPtr)
 291 {
 292         u8 *Source = (u8 *) InstancePtr;
 293         u8 *Destination = (u8 *) VersionPtr;
 294         int Index;
 295
 296         /* assert to verify input arguments */
 297
 298         XASSERT_VOID(InstancePtr != NULL);
 299         XASSERT_VOID(VersionPtr != NULL);
 300
 301         /* copy each byte of the source version to the destination version */
 302
 303         for (Index = 0; Index < sizeof(XVersion); Index++) {
 304                 Destination[Index] = Source[Index];
 305         }
 306 }
 307
 308 /*****************************************************************************/
 309 /**
 310 *
 311 * Determines if the specified version is valid.
 312 *
 313 * @param    StringPtr points to the string to be validated.
 314 *
 315 * @return
 316 *
 317 * TRUE if the version string is a valid format, FALSE otherwise.
 318 *
 319 * @note
 320 *
 321 * None.
 322 *
 323 ******************************************************************************/
 324 static u32 IsVersionStringValid(s8 *StringPtr)
 325 {
 326         /* if the input string is not a valid format, "X.YYZ" where X = 0 - 9,
 327          * YY = 00 - 99, and Z = a - z, then indicate it's not valid
 328          */
 329         if ((StringPtr[XVE_MAJOR_CHAR] < '0') ||
 330             (StringPtr[XVE_MAJOR_CHAR] > '9') ||
 331             (StringPtr[XVE_MINOR_TENS_CHAR] < '0') ||
 332             (StringPtr[XVE_MINOR_TENS_CHAR] > '9') ||
 333             (StringPtr[XVE_MINOR_ONES_CHAR] < '0') ||
 334             (StringPtr[XVE_MINOR_ONES_CHAR] > '9') ||
 335             (StringPtr[XVE_COMP_CHAR] < 'a') ||
 336             (StringPtr[XVE_COMP_CHAR] > 'z')) {
 337                 return FALSE;
 338         }
 339
 340         return TRUE;
 341 }