/* * Copyright (c) 2015-2016, The Linux Foundation. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following * disclaimer in the documentation and/or other materials provided * with the distribution. * * Neither the name of The Linux Foundation nor the names of its * contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /** @page dcc Decentralized Congestion Control Decentralized congestion control (DCC) is a mandatory component of ITS-G5 stations operating in ITS-G5A and ITS-G5B frequency bands to maintain network stability, throughput efficiency, and fair resource allocation to ITS-G5 stations. DCC reduces congestion on busy channels. Each station monitors the state of the channel to determine the percentage of time that the channel is busy. This measurement is called the channel load. The DCC parameters are stored in the network design limits (NDL) database. The NDL is split into a number of states where each state corresponds to a range of channel loads. Each state contains the limits for the transmit parameters that can be used while in that state. When the channel becomes more congested according to the channel load, the station will help to reduce the congestion by moving into a more restrictive state associated with the higher channel load. The least restrictive state is referred to as the "Relaxed state," and the most restrictive state is referred to as the "Restrictive state." The states inbetween are referred to as "active states". Moving to more restrictive states as the channel load increases reduces the congestion by modifying various transmit parameters, such as by transmitting with a higher MCS, by reducing the transmit power, and by limiting the transmit rate. The DCC algorithm is described in detail in "ETSI TS 102 687". To enable DCC, include the -d parameter when executing dsrc_config. For example, to configure DSRC on channel 5860 with DCC enabled, execute the following command: dsrc_config -c set_config -o channel_freq0=5860 -d If the -d parameter is not present, DCC is disabled. The configurable parameters for DCC referred to as the network design limits (NDL) are read by the dsrc_config sample app from the file dcc.dat in the same folder as dsrc_config and sent to the host driver. If dsrc_config is executed with the -d option but the file dcc.dat does not exist, dsrc_config will fail. The NDL parameters in dcc.dat are as follows: DCC_Channels Currently, DCC is supported on a maximum of two channels. We can specify the channels using the center frequency. For single channel: DCC_Channels=5860 For two channels: DCC_Channels=5860,5890 DCC_ControlLoopEnable This parameter is used to enable the DCC control loop state machine for each channel. To enable the state machine on two channels, the string is set this way: DCC_ControlLoopEnable=1,1 It is possible for the end user to disable the state machine per channel and only have the DCC statistics reporting enabled to understand the channel properties, or to have both the DCC state machine and DCC statistics reporting disabled as well. DCC_StatsEnable This parameters helps to enable DCC statistic reporting on each channel. If this is enabled, these are the statistics that are sent to the user. 1. Average TX power of frames of each access category 2. Average data rate of frames of each access category 3. Channel load value DCC_StatsInterval This configures the interval of DCC statistics reporting. This value is in multiples of 10 ms. To configure the interval to 5 seconds for 2 channels, set DCC_StatsInterval=500,500 DCC_MinDccSampling This gives the information to the firmware about how often the channel load value needs to be checked. Every minimum DCC sampling interval, the firmware finds the channel load value for the last minimum DCC sampling time and records that. This value is specified in multiples of 10 ms. For example, DCC_MinDccSampling=100 to set the value to 1 second. DCC_MeasurementInterval This interval determines how often the firmware consolidates the statistics that are sent every stats interval to the user. Preferably, this value is less than or equal to the stats interval value, and the stats interval value can be an integer multiple of the measurement interval. This value is specified in multiples of 10 ms. NDL_minTxPower This number specifies the maximum transmit power allowed in the Restrictive state. This number is specified as physicalValue = referenceValue + number * stepSize where the reference value is -20 dBm and the stepSize is 0.5 dBm. For example, to specify 10 dBm (physicalValue) as the NDL_minTxPower, set the value to number = (physicalValue - referenceValue) / stepSize = (10 - -20)/0.5 = 30/0.5 = 60 NDL_minTxPower=60 When in the Restrictive state, any packets sent with a value higher than NDL_minTxPower from the application will go out with NDL_minTxPower. Any packets sent with a value less than NDL_minTxPower from the application will go out with same power as specified by the application. NDL_maxTxPower This number specifies the maximum transmit power allowed in the Relaxed state. This number is specified the same way as NDL_minTxPower. When in the Relaxed state, any packets sent with a value higher than NDL_maxTxPower from the application will go out with NDL_maxTxPower. Any packets sent with a value less than NDL_maxTxPower from the application will go out with the same power as specified by the application. NDL_defTxPower-AC_BK, NDL_defTxPower-AC_BE, NDL_defTxPower-AC_VO, NDL_defTxPower-AC_VI NDL_defTxPower parameters are not used in the current implementation. NDL_maxPacketDuration-AC_BK This provides the maximum packet duration or air time allowed for packets sent with the access category background (BK). This value is specified in multiples of 8 microseconds. For example, to allow a maximum packet air time of 10 ms, set NDL_maxPacketDuration-AC_BK=1250 Any packets of background priority sent with a length that takes air time higher than NDL_maxPacketDuration-AC_BK will be dropped by the hardware. NDL_maxPacketDuration-AC_BE This provides the maximum packet duration or air time allowed for packets sent with the access category best-effort (BE). This value is specified in multiples of 8 microseconds. For example, to allow a maximum packet air time of 10 ms set NDL_maxPacketDuration-AC_BK=1250 Any packets of best-effort priority sent with a length that takes air time higher than NDL_maxPacketDuration-AC_BE will be dropped by the hardware. NDL_maxPacketDuration-AC_VO This provides the maximum packet duration or air time allowed for packets sent with the access category voice (VO). This value is specified in multiples of 8 microseconds. For example, to allow a maximum packet air time of 10 ms set NDL_maxPacketDuration-AC_BE=1250 Any packets of voice priority sent with a length that takes air time higher than NDL_maxPacketDuration-AC_VO will be dropped by the hardware. NDL_maxPacketDuration-AC_VI This provides the maximum packet duration or air time allowed for packets sent with the access category video (VI). This value is specified in multiples of 8 microseconds. For example, to allow a maximum packet air time of 10 ms set NDL_maxPacketDuration-AC_VI=1250 Any packets of video priority sent with a length that takes air time higher than NDL_maxPacketDuration-AC_VI will be dropped by the hardware. NDL_minPacketInterval This value is the minimum interval between two subsequent packets when the DCC access control loop state is in the Relaxed state. This value is specified in multiples of 10 ms. The next packets will not be sent until the NDL_minPacketInterval time expires after sending the previous packet. NDL_maxPacketInterval This value is the minimum interval between subsequent packets when the DCC access control loop state is in the Restrictive state. This value is specified in multiples of 10 ms. The next packets will not be sent until the NDL_maxPacketInterval time expires after sending the previous packet. NDL_defPacketInterval-AC_BK, NDL_defPacketInterval-AC_BE, NDL_defPacketInterval-AC_VO, NDL_defPacketInterval-AC_VI These parameters are not used in the current implementation NDL_minDatarate This is the minimum data rate allowed in the Relaxed state. This value is specified in MCS index 0 to 7, where MCS 0 corresponds to the lowest data rate (BPSK+1/2R) and MCS7 corresponds to the highest data rate (64QAM+3/4R). For example, for MCS2: NDL_minDatarate=2 Any packets that are sent with an MCS index lower than NDL_minDatarate will go out with a NDL_minDatarate data rate. Any packets that are sent with an MCS index higher than NDL_minDatarate by the application will be sent with the same data rate as determined by the application. NDL_maxDatarate This is the minimum data rate allowed in the Restrictive state. This value is specified in MCS index 0 to 7, where MCS 0 corresponds to the lowest data rate (BPSK+1/2R) and MCS7 corresponds to the highest data rate (64QAM+3/4R). For example, for MCS6: NDL_maxDatarate=6 Any packets that are sent with an MCS index lower than NDL_maxDatarate will go out with NDL_maxDatarate data rate. Any packets that are sent with an MCS index higher than NDL_maxDatarate by the application will be sent with the same data rate as determined by the application. NDL_defDatarate-AC_BK, NDL_defDatarate-AC_BE, NDL_defDatarate-AC_VO, NDL_defDatarate-AC_VI These parameters are not used in the current implementation NDL_minCarrierSense, NDL_maxCarrierSense, NDL_defCarrierSense, NDL_defDccSensitivity These parameters are not used in the current implementation and the hardware is set to a default receive sensitivity for the entire duration of DCC operation. NDL_maxCsRange, NDL_refPathLoss, NDL_minSNR These parameters are not supported in the current implementation NDL_snrBackoff-MCS0, NDL_snrBackoff-MCS1, NDL_snrBackoff-MCS2, NDL_snrBackoff-MCS3, NDL_snrBackoff-MCS4, NDL_snrBackoff-MCS5, NDL_snrBackoff-MCS6, NDL_snrBackoff-MCS7 These values are returned as is in the DCC statistics event sent to the user. NDL_tmPacketArrivalRate-AC_BK, NDL_tmPacketArrivalRate-AC_BE, NDL_tmPacketArrivalRate-AC_VO, NDL_tmPacketArrivalRate-AC_VI, NDL_tmPacketAvgDuration-AC_BK, NDL_tmPacketAvgDuration-AC_BE, NDL_tmPacketAvgDuration-AC_VO, NDL_tmPacketAvgDuration-AC_VI, NDL_tmSignalAvgPower-AC_BK, NDL_tmSignalAvgPower-AC_BE, NDL_tmSignalAvgPower-AC_VO, NDL_tmSignalAvgPower-AC_VI, NDL_maxChannelUse, NDL_tmChannelUse-AC_BK, NDL_tmChannelUse-AC_BE, NDL_tmChannelUse-AC_VO, NDL_tmChannelUse-AC_VI All these parameters are not supported in the current implementation. NDL_minChannelLoad This is the channel load threshold for the Relaxed state. If the channel load is lower than this, the DCC access control loop will stay in the Relaxed state. If the channel load is equal or above this, the access control loop will go to one of the other active states or the Restrictive state, depending on the magnitude of the channel load. NDL_maxChannelLoad This is the channel load threshold for the Restrictive state. If the channel load is equal or above this, the DCC control loop state will transition to the Restrictive state. NDL_refQueueStatus-AC_BK This value specifies whether the transmit queue of access category Background is in the Open or Closed state. If the value is 1, the queue is open, and if the value is 0, the queue is closed. Any packets sent by the application with access category Background will be dropped by the hardware if the queue for that access category is in the Closed state. NDL_refQueueStatus-AC_BE This value specifies whether the transmit queue of access category BE is in the Open or Closed state. If the value is 1, the queue is open, and if the value is 0, the queue is closed. Any packets sent by the application with access category BE will be dropped by the hardware if the queue for that access category is in the Closed state. NDL_refQueueStatus-AC_VI This value specifies whether the transmit queue of access category Video is in the Open or Closed state. If the value is 1, the queue is open, and if the value is 0, the queue is closed. Any packets sent by the application with access category Video will be dropped by the hardware if the queue for that access category is in the Closed state. NDL_refQueueStatus-AC_VO This value specifies whether the transmit queue of access category Voice is in the Open or Closed state. If the value is 1, the queue is open, and if the value is 0, the queue is closed. Any packets sent by the application with access category Voice will be dropped by the hardware if the queue for that access category is in the Closed state. NDL_queueLen-AC_BK, NDL_queueLen-AC_BE, NDL_queueLen-AC_VO, NDL_queueLen-AC_VI These values are not supported in the current implementation NDL_timeUp This value, usually an integer multiple of the minimum DCC sampling interval, specifies how long the state machine has to wait before going to higher, more restrictive states. DCC_minDCCSampling <= NDL_timeUp <= NDL_timeDown NDL_timeDown This value specifies how long the state machine must wait before going to lower, more relaxed states. This value is usually an integer multiple of the minimum DCC sampling and is equal to or higher than NDL_timeUp. NDL_numActiveStates This value specifies the number of active states supported by the DCC access control loop state machine. The current implementation supports a maximum of four active states. NDL_asChanLoad-ActiveState_1, NDL_asChanLoad-ActiveState_2, NDL_asChanLoad-ActiveState_3, NDL_asChanLoad-ActiveState_4 This value specifies the channel load threshold for Active State 1. The last number in the parameter string indicates the state number. NDL_asDcc-AC_BK-ActiveState_1, NDL_asDcc-AC_BE-ActiveState_1, NDL_asDcc-AC_VO-ActiveState_1, NDL_asDcc-AC_VI-ActiveState_1, NDL_asDcc-AC_BK-ActiveState_2, NDL_asDcc-AC_BE-ActiveState_2, NDL_asDcc-AC_VO-ActiveState_2, NDL_asDcc-AC_VI-ActiveState_2, NDL_asDcc-AC_BK-ActiveState_3, NDL_asDcc-AC_BE-ActiveState_3, NDL_asDcc-AC_VO-ActiveState_3, NDL_asDcc-AC_VI-ActiveState_3, NDL_asDcc-AC_BK-ActiveState_4, NDL_asDcc-AC_BE-ActiveState_4, NDL_asDcc-AC_VO-ActiveState_4, NDL_asDcc-AC_VI-ActiveState_4 NDL_asDcc is a bitmap that is specified for each access category and state. This bitmap selects the DCC mechanisms that will get a new threshold in the given state. This is the meaning of each bit in the bitmap: | Value | DCC Mechanism | |:------|---------------| | 1 | TPC | | 2 | TRC | | 4 | TDC | | 8 | DSC | | 16 | TAC | | 32 | reserved | | 0 | None | | 63 | All | For example: NDL_asDcc-AC_VI-ActiveState_1=7 means TPC, TRC, and TDC will get new thresholds in Active State 1. NDL_asTxPower-AC_BK-ActiveState_1, NDL_asTxPower-AC_BE-ActiveState_1, NDL_asTxPower-AC_VO-ActiveState_1, NDL_asTxPower-AC_VI-ActiveState_1, NDL_asTxPower-AC_BK-ActiveState_2, NDL_asTxPower-AC_BE-ActiveState_2, NDL_asTxPower-AC_VO-ActiveState_2, NDL_asTxPower-AC_VI-ActiveState_2, NDL_asTxPower-AC_BK-ActiveState_3, NDL_asTxPower-AC_BE-ActiveState_3, NDL_asTxPower-AC_VO-ActiveState_3, NDL_asTxPower-AC_VI-ActiveState_3, NDL_asTxPower-AC_BK-ActiveState_4, NDL_asTxPower-AC_BE-ActiveState_4, NDL_asTxPower-AC_VO-ActiveState_4, NDL_asTxPower-AC_VI-ActiveState_4 This parameter specifies a new maximum power threshold for the given state and access category. The number specified for this follows the same formula as NDL_minTxPower, specified in section 5.7. If the value is set to 'ref', it will use the thresholds from the previous state. For example: NDL_asTxPower-AC_VI-ActiveState_1=60,ref means, in Active State 1, the new maximum transmit power for the first channel is 10 dBm and the new maximum transmit power for the second channel is the same as the maximum transmit power for the second channel in the previous state for any packets with the video access category. NDL_asPacketInterval-AC_BK-ActiveState_1, NDL_asPacketInterval-AC_BE-ActiveState_1, NDL_asPacketInterval-AC_VO-ActiveState_1, NDL_asPacketInterval-AC_VI-ActiveState_1, NDL_asPacketInterval-AC_BK-ActiveState_2, NDL_asPacketInterval-AC_BE-ActiveState_2, NDL_asPacketInterval-AC_VO-ActiveState_2, NDL_asPacketInterval-AC_VI-ActiveState_2, NDL_asPacketInterval-AC_BK-ActiveState_3, NDL_asPacketInterval-AC_BE-ActiveState_3, NDL_asPacketInterval-AC_VO-ActiveState_3, NDL_asPacketInterval-AC_VI-ActiveState_3, NDL_asPacketInterval-AC_BK-ActiveState_4, NDL_asPacketInterval-AC_BE-ActiveState_4, NDL_asPacketInterval-AC_VO-ActiveState_4, NDL_asPacketInterval-AC_VI-ActiveState_4 This parameter specifies the new minimum packet interval threshold for the given state and access category. This value is specified in multiples of 10 ms. If the value is set to 'ref', it will use the thresholds from the previous state. For example: NDL_asPacketInterval-AC_VO-ActiveState_3=100,ref means, in Active State 3, the new minimum packet interval threshold for the first channel is 1 second and the new minimum packet interval for the second channel is the same as in the previous state for any packets with the voice access category. NDL_asDatarate-AC_BK-ActiveState_1, NDL_asDatarate-AC_BE-ActiveState_1, NDL_asDatarate-AC_VO-ActiveState_1, NDL_asDatarate-AC_VI-ActiveState_1, NDL_asDatarate-AC_BK-ActiveState_2, NDL_asDatarate-AC_BE-ActiveState_2, NDL_asDatarate-AC_VO-ActiveState_2, NDL_asDatarate-AC_VI-ActiveState_2, NDL_asDatarate-AC_BK-ActiveState_3, NDL_asDatarate-AC_BE-ActiveState_3, NDL_asDatarate-AC_VO-ActiveState_3, NDL_asDatarate-AC_VI-ActiveState_3, NDL_asDatarate-AC_BK-ActiveState_4, NDL_asDatarate-AC_BE-ActiveState_4, NDL_asDatarate-AC_VO-ActiveState_4, NDL_asDatarate-AC_VI-ActiveState_4 This parameter specifies the minimum data rate for the given state and access category. This value is specified as MCS index 0 to 7. If the value is set to 'ref', it will use the thresholds from the previous state. For example: NDL_asDatarate-AC_VO-ActiveState_2=ref, 6 means, in Active State 2, the minimum data rate for the first channel is the same as in the previous state, and the minimum data rate for the second channel is MCS6. NDL_asCarrierSense-AC_BK-ActiveState_1, NDL_asCarrierSense-AC_BE-ActiveState_1, NDL_asCarrierSense-AC_VO-ActiveState_1, NDL_asCarrierSense-AC_VI-ActiveState_1, NDL_asCarrierSense-AC_BK-ActiveState_2, NDL_asCarrierSense-AC_BE-ActiveState_2, NDL_asCarrierSense-AC_VO-ActiveState_2, NDL_asCarrierSense-AC_VI-ActiveState_2, NDL_asCarrierSense-AC_BK-ActiveState_3, NDL_asCarrierSense-AC_BE-ActiveState_3, NDL_asCarrierSense-AC_VO-ActiveState_3, NDL_asCarrierSense-AC_VI-ActiveState_3, NDL_asCarrierSense-AC_BK-ActiveState_4, NDL_asCarrierSense-AC_BE-ActiveState_4, NDL_asCarrierSense-AC_VO-ActiveState_4, NDL_asCarrierSense-AC_VI-ActiveState_4 These parameters are not used in the current implementation. */