Allowed queue depth values to be declared as capability

[niloda]

Some hardware can configure the depth of an egress queue to a value choose within a defined list of permitted values. This means that the depth cannot be freely set to a value in the range 0..max-queue-depth. The current model does not allow a user to be aware about the permitted values.

Proposed solution A list of integer values can be added to ethernet-container-capability to be filled with the permitted values of queue depth. In case the hardware supports any value between 0 and max-queue-depth, this list can be filled with a subset of permitted values. In case the queue depth cannot be configured, the list should contain only the value -1. The attribute max-queue-depth can be removed from ethernet-container-capability.

[demx8as6]

Info: All api providers and consumers (hardware and software vendors) are ask to check if the proposed solution works and can be implemented. If so, it would be the preferred solution.

Just for documentation: how the issues could be solved too, but would need tooling enhancements, therefore it is not the preferred solution.

ethernet-container-2-0@2020-04-21.yang.txt ethernet-container-2-0@2020-04-21.yang.tree.txt

[michbin]

It should be feasible to implement the proposal. However, we should keep in mind that the list of supported values can become quite large. I know of one example with at least 120 values.

The most general solution would be a union (simplified Yang syntax):

  choice available-queue-depth
    case range
      leaf min-value   
      leaf max-value     What is the unit? kByte vs --6-4-k-B-y-t-e-? Decision: Byte 
      leaf step-width    128Bytes
    case set
      leaf-list supported-value-list -> step width could be dynamic (doubling)

I am not sure whether we would like to spend the necessary effort.

added by Martin 2020-04-29: Status: Brainstroming: - new proposal in the next comment.

Alternative

• in capabilities the choice could be explained - similar to radio-signal-id
• capability only for documentation purpose but no SW is forced to check configuration. -- not a leafref in configuration

Statement

• supported-value-list is sufficient - effort for UML to YANG enhancements is too much
• importance is low

Proposal

• supported-value-list in cap - no restriction on the length of this list and unit bytes -- supported-value-list in cap could be a subset or is the complete set of the allowed range for configuration -- all values in the list must be allowed for configuration -- if a value is configured, which is not in the supported value list, it is a decision by the device-software or mediator-software how to handle the situation.
• capability only for documentation purpose but no SW (device, app) is forced to check configuration.

add recommendation for SDN-App development.

if device does not support config for queue-depth - then the supported-value-list should contain the default value -1 -> min-element should be 1.

multiplicity for supported-value-list in UML is: 1..*

-- not a leafref in configuration -- rule: max(supported-value-list) == max-value of the supported range -- rule: min(supported-value-list) == min-value of the supported range

[demx8as6]

Solution:

Note: the following description and wording uses terms and notations from ethernet-container-2-0.yang. The mapping to UML is made by UML modelers. Results after UML to YANG translations will look as described below.

The attribute (or leaf) "max-queue-depth" is replaced by a leaf-list "supported-queue-depth-list" in ethernet-container-capabilities, respectively the AvailableQueueType datatype in the UML.

The min-elements statement gets the value 1 (UML multiplicity: 1..*), to force the interface implementation to express the default-value -1 in case configuring the buffer size would not be supported by the hardware. As a consequence the attribute (or leaf) "queue-depth-configuration-is-avail" will be removed. The description in ethernet-configuration for lead "queue-depth" must be adopted.

The description of the leaf-list "supported-queue-depth-list" must explain the following information for implementation on device, mediator and SDN-app level.

• The "supported-queue-depth-list" must exclusively contain values, which are actually configurable at the hardware (except of the default value -1, in case buffer size cannot be configured at all).

• The values listed in "supported-queue-depth-list" might be all or a subset of values actually configurable at the hardware. To allow configuring the device according to its full capabilities, the values entered into the "queue-depth" attribute (or leaf) in the ethernet-configuration are not limited to the ones stated in "supported-queue-depth-list" (YANG must not contain a MUST statement referencing the values of the "supported-queue-depth-list " capability attribute.)

• If a value, which is supported by the hardware, but not listed in the "supported-queue-depth-list", would be tried to be configured, the device-software or mediator-software shall successfully validate (and operate) it.

• If a value, which is not supported by the hardware, would be tried to be configured, the device-software or mediator-software might implementation specifically react . It could either respond with operation failed and ...Configuration value out of range of hardware capabilities... or it could map the sent configuration value on the closest value, which is actually supported by the hardware. Vendors are free to chose according to the existing capabilities of their devices.

• Configuration attempts with values lower than the minimum value or higher than the maximum value of the "supported-queue-depth-list" must be answered with the operation failed and ...Configuration value out of range of hardware capabilities...

[openBackhaul]

Decision on the 5G-xhaul-call on 19th of May 2021: (same as described as solution above) Note: the following description and wording uses terms and notations from ethernet-container-2-0.yang. The mapping to UML is made by UML modelers. Results after UML to YANG translations will look as described below.

The attribute (or leaf) "max-queue-depth" is replaced by a leaf-list "supported-queue-depth-list" in ethernet-container-capabilities, respectively the AvailableQueueType datatype in the UML.

The min-elements statement gets the value 1 (UML multiplicity: 1..*), to force the interface implementation to express the default-value -1 in case configuring the buffer size would not be supported by the hardware. As a consequence the attribute (or leaf) "queue-depth-configuration-is-avail" will be removed. The description in ethernet-configuration for lead "queue-depth" must be adopted.

The description of the leaf-list "supported-queue-depth-list" must explain the following information for implementation on device, mediator and SDN-app level.

• The "supported-queue-depth-list" must exclusively contain values, which are actually configurable at the hardware (except of the default value -1, in case buffer size cannot be configured at all).

  • The values listed in "supported-queue-depth-list" might be all or a subset of values actually configurable at the hardware. To allow configuring the device according to its full capabilities, the values entered into the "queue-depth" attribute (or leaf) in the ethernet-configuration are not limited to the ones stated in "supported-queue-depth-list" (YANG must not contain a MUST statement referencing the values of the "supported-queue-depth-list " capability attribute.)

• If a value, which is supported by the hardware, but not listed in the "supported-queue-depth-list", would be tried to be configured, the device-software or mediator-software shall successfully validate (and operate) it.

• If a value, which is not supported by the hardware, would be tried to be configured, the device-software or mediator-software might implementation specifically react . It could either respond with operation failed and ...Configuration value out of range of hardware capabilities... or it could map the sent configuration value on the closest value, which is actually supported by the hardware. Vendors are free to chose according to the existing capabilities of their devices.

• Configuration attempts with values lower than the minimum value or higher than the maximum value of the "supported-queue-depth-list" must be answered with the operation failed and ...Configuration value out of range of hardware capabilities...

[openBackhaul]

Fixed with EthernetContainer_2.0.0-tsp.220405.1755.