1.1 --- a/src/devices/csma/csma-net-device.h	Tue Aug 05 10:06:40 2008 -0700
     1.2 +++ b/src/devices/csma/csma-net-device.h	Tue Aug 05 10:34:26 2008 -0700
     1.3 @@ -201,34 +201,36 @@
     1.4    /**
     1.5     * Set The max PHY-level payload length of packets sent over this device.
     1.6     *
     1.7 -   * Okay, that was easy to say, but the details are a bit thorny.  We have a MAC-level that is the payload that higher 
     1.8 +   * Okay, that was easy to say, but the details are a bit thorny.  We have a MAC-level MTU that is the payload that higher 
     1.9     * level protocols see.  We have a PHY-level MTU which is the maximum number of bytes we can send over the link 
    1.10     * (cf. 1500 bytes for Ethernet).  The value that determines the relationship between these two values is the link
    1.11 -   * encapsulation mode.  The link encapsulation defines the number of bytes of overhead that are required for the particular
    1.12 -   * MAC protocol used.  For example, if the LLC/SNAP encapsulation is used, eight bytes of LLC/SNAP header are consumed and
    1.13 -   * therefore the MAC-level MTU must be set and reported as eight bytes less than the PHY-level MTU (which we call the
    1.14 -   * payload length to try and avoid confusion).
    1.15 +   * encapsulation mode.  The link encapsulation method dictates the number of bytes of overhead that are required for the 
    1.16 +   * particular MAC protocol used.  For example, if the LLC/SNAP encapsulation is used, eight bytes of LLC/SNAP header are 
    1.17 +   * consumed and therefore the MAC-level MTU must be set and reported as eight bytes less than the PHY-level MTU (which we 
    1.18 +   * call the payload length to try and avoid confusion).
    1.19     *
    1.20 -   * So, what do we do since there must be three values which must always be consistent in the driver?  Which values to we
    1.21 -   * allow to be changed and how do we ensure the other two are consistent?  We want to actually enable a user to change 
    1.22 -   * these two payload lengths in flexible ways, but we want the results (even at intermediate stages) to be consistent.  
    1.23 -   * We certainly don't want to require that users must understand the various requirements of an enapsulation mode in order 
    1.24 -   * to set these variables.
    1.25 +   * So, what do we do since there are be three values which must always be consistent in the driver?  Which values to we
    1.26 +   * allow to be changed and how do we ensure the other two are consistent?  We want to actually allowe a user to change 
    1.27 +   * these three variables in flexible ways, but we want the results (even at intermediate stages of her ultimate change) to 
    1.28 +   * be consistent.  We certainly don't want to require that users must understand the various requirements of an enapsulation
    1.29 +   * mode in order to set these variables.
    1.30     *
    1.31     * Consider the following situation:  A user wants to set the physical layer MTU to 1400 bytes instead of 1500.  This
    1.32     * user shouldn't have to concern herself that the current encapuslation mode is LLC and this will consume eight bytes.
    1.33     * She should not have to also set the MAC MTU to 1392 bytes, and she should certainly not have to do this before setting
    1.34 -   * the PHY MTU.  
    1.35 +   * the PHY MTU to make the eventual result consistent.  
    1.36     *
    1.37 -   * A user who is interested in setting the MAC-level MTU to 1400 bytes should not be forced to understand that in certain
    1.38 -   * cases the PHY-level MTU must be set to eight bytes more than what he wants in certain cases and zero bytes in others.
    1.39 +   * Similarly, a user who is interested in setting the MAC-level MTU to 1400 bytes should not be forced to understand that 
    1.40 +   * (based on encapsulation mode) the PHY-level MTU may need to be set to eight bytes more than what he wants in certain 
    1.41 +   * cases and zero bytes in others.
    1.42     *
    1.43     * Now, consider a user who is only interested in changing the encapsulation mode from LLC/SNAP to ETHERNET_V1.  This 
    1.44     * is going to change the relationship between the MAC MTU and the PHY MTU.  We've may have to come up with a new value 
    1.45 -   * for at least one of the MTUs?  Which one?
    1.46 +   * for at least one of the MTUs?  Which one?  There are too many free variables.
    1.47     *
    1.48 -   * We could play games trying to figure out what the user wants to do, but that is typically a bad plan.  So we're going
    1.49 -   * to just define a flexible behavior.  Here it is:
    1.50 +   * We could play games trying to figure out what the user wants to do, but that is typically a bad plan and programmers
    1.51 +   * have a long and distinguished history of guessing wrong.  We'll avoid all of that and just define a flexible behavior
    1.52 +   * that can be worked to get what you want.  Here it is:
    1.53     *
    1.54     * - If the user is changing the encapsulation mode, the PHY MTU will remain fixed and the MAC MTU will change, if required,
    1.55     * to make the three values consistent;
    1.56 @@ -237,12 +239,14 @@
    1.57     * will be changed to make the three values consistent;
    1.58     *
    1.59     * - If the user is changing the PHY MTU, he is interested in getting that part of the system set, so the MAC MTU
    1.60 -   * will be changed to make the three values consistent.
    1.61 +   * will be changed to make the three values consistent;
    1.62 +   *
    1.63 +   * - You cannot define the MAC MTU and PHY MTU separately -- they are always tied together by the emulation mode.
    1.64     * 
    1.65     * So, if a user calls SetMaxPayloadLength, we assume that the PHY-level MTU is the interesting thing for that user and
    1.66 -   * we just adjust the MAC-level MTU to "the correct value" based on the current encapsulation mode.  If a user calls 
    1.67 +   * we just adjust the MAC-level MTU to a new "correct value" based on the current encapsulation mode.  If a user calls 
    1.68     * SetMacMtu, we assume that the MAC-level MTU is the interesting property for that user, and we adjust the PHY-level MTU 
    1.69 -   * to "the correct value" for the current encapsulation mode.  If a user calls SetEncapsulationMode, then we take the
    1.70 +   * to a new "correct value" for the current encapsulation mode.  If a user calls SetEncapsulationMode, then we take the
    1.71     * MAC-level MTU as the free variable and set its value to match the current PHY-level MTU.
    1.72     *
    1.73     * \param mayPayloadLength The max PHY-level payload length of packets sent over this device.