board/xilinx/common/xversion.c

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