Home | History | Annotate | Download | only in Common 
      1 /** @file
      2     Utility functions for performing basic math operations constrained within a
      3     modulus.
      4 
      5     These functions are intended to simplify small changes to a value which much
      6     remain within a specified modulus.
      7 
      8   NOTE: Changes must be less than or equal to the modulus specified by MaxVal.
      9 
     10     Copyright (c) 2012, Intel Corporation. All rights reserved.<BR>
     11     This program and the accompanying materials are licensed and made available
     12     under the terms and conditions of the BSD License which accompanies this
     13     distribution.  The full text of the license may be found at
     14     http://opensource.org/licenses/bsd-license.php.
     15 
     16     THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
     17     WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
     18 **/
     19 #include  <Uefi.h>
     20 #include  <LibConfig.h>
     21 #include  <assert.h>
     22 
     23 /** Counter = (Counter + 1) % MaxVal;
     24 
     25     Counter is always expected to be LESS THAN MaxVal.
     26         0 <= Counter < MaxVal
     27 
     28     @param[in]    Counter   The value to be incremented.
     29     @param[in]    MaxVal    Modulus of the operation.
     30 
     31     @return   Returns the result of incrementing Counter, modulus MaxVal.
     32               If Counter >= MaxVal, returns -1.
     33 **/
     34 INT32
     35 EFIAPI
     36 ModuloIncrement(
     37   UINT32  Counter,
     38   UINT32  MaxVal
     39   )
     40 {
     41   INT32  Temp;
     42 
     43   if(Counter < MaxVal) {
     44     Temp = (INT32)(Counter + 1);
     45     if(Temp >= (INT32)MaxVal) {
     46       Temp = 0;
     47     }
     48   }
     49   else {
     50     Temp = -1;
     51   }
     52   return Temp;
     53 }
     54 
     55 /** Counter = (Counter - 1) % MaxVal;
     56 
     57     Counter is always expected to be LESS THAN MaxVal.
     58         0 <= Counter < MaxVal
     59 
     60     @param[in]    Counter   The value to be decremented.
     61     @param[in]    MaxVal    Modulus of the operation.
     62 
     63     @return   Returns the result of decrementing Counter, modulus MaxVal.
     64               If Counter >= MaxVal, returns -1.
     65 **/
     66 INT32
     67 EFIAPI
     68 ModuloDecrement(
     69   UINT32  Counter,
     70   UINT32  MaxVal
     71   )
     72 {
     73   INT32  Temp;
     74 
     75   if(Counter < MaxVal) {
     76     Temp = (INT32)Counter - 1;
     77     // If Counter is zero, Temp will become -1.
     78     if(Temp < 0) {
     79       Temp = (INT32)MaxVal - 1;
     80     }
     81   }
     82   else {
     83     Temp = -1;
     84   }
     85 
     86   return Temp;
     87 }
     88 
     89 /** Decrement Counter but don't decrement past zero.
     90 
     91     @param[in]    Counter   The value to be decremented.
     92 
     93     @return   Returns the result of decrementing Counter.
     94 **/
     95 UINT32
     96 EFIAPI
     97 BoundDecrement(
     98   UINT32  Counter
     99   )
    100 {
    101   return ((Counter > 0) ? (Counter - 1) : 0);
    102 }
    103 
    104 /** Increment Counter but don't increment past MaxVal.
    105     Counter should be maintained in the range (0 <= Counter < MaxVal).
    106 
    107     @param[in]    Counter   The value to be decremented.
    108     @param[in]    MaxVal    The upper bound for Counter.
    109 
    110     @return   Returns the result of incrementing Counter.
    111 **/
    112 UINT32
    113 EFIAPI
    114 BoundIncrement(
    115   UINT32  Counter,
    116   UINT32  MaxVal
    117   )
    118 {
    119   return ((Counter < (MaxVal - 1)) ? (Counter + 1) : (MaxVal - 1));
    120 }
    121 
    122 /** Counter = (Counter + Increment) % MaxVal;
    123 
    124     @param[in]    Counter   The value to be incremented.
    125     @param[in]    Increment The value to add to Counter.
    126     @param[in]    MaxVal    Modulus of the operation.
    127 
    128     @return   Returns the result of adding Increment to Counter, modulus MaxVal,
    129               or -1 if Increment is larger than MaxVal.
    130 **/
    131 INT32
    132 EFIAPI
    133 ModuloAdd (
    134   UINT32  Counter,
    135   UINT32  Increment,
    136   UINT32  MaxVal
    137   )
    138 {
    139   UINT32   Temp;
    140 
    141   if(Increment > MaxVal) {
    142     return -1;
    143   }
    144   Temp = (Counter + Increment);
    145   while(Temp >= MaxVal) {
    146     Temp -= MaxVal;
    147   }
    148   return Temp;
    149 }
    150