Re: [Qemu-devel] [PATCH v5 03/10] rocker: add register programming guide

[Scott Feldman]

On Tue, Feb 3, 2015 at 8:40 AM, Eric Blake <address@hidden> wrote:
> On 01/22/2015 01:03 AM, address@hidden wrote:
>> From: Scott Feldman <address@hidden>
>>
>> This is the register programming guide for the Rocker device.  It's intended
>> for driver writers and device writers.  It covers the device's PCI space,
>> the register set, DMA interface, and interrupts.
>>
>
> In addition to typos already pointed out by Stefan,
>
>> +
>> +Writing BASE_ADDR or SIZE will reset HEAD and TAIL to zero.  HEAD cannot be
>> +written passed TAIL.  To do so would wrap the ring.  An empty ring is when 
>> HEAD
>
> s/passed/past/

Got all the corrections, thanks guys.

>
>> +
>> +To support forward- and backward-compatibility, descriptor and completion
>> +payloads are specified in TLV format.  Fields are packed with Type=field 
>> name,
>> +Length=field length, and Value=field value.  Software will ignore unknown 
>> fields
>> +filled in by the switch.  Likewise, the switch will ignore unknown fields
>> +filled in by software.
>
> Is ignoring unknown fields always the wisest action?  If the unknown
> fields are supposed to have an impact according the to writer, but get
> ignored by the reader, then the two can get out of sync with what they
> assume the other end is doing.

This is the beauty of using TLVs for the cmd structures.  The driver
and device can be version mismatched and still function at
lowest-common set.  Care must be taken when adding new options to a
TLV enum list by adding new items to the end.  And if an existing
structure can't be extended, then a new one is created, but the old
one must remain for backward-compatibility. If it's important for one
side to know the level of support of the other side, then option A can
be tried, and if that fails, try option B, and so on.