Subject: Element Properties

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 4 May 2005 13:58:18 -0400

I sent the message below to the list more than a month ago.
There are a series of specific questions that I would really like feedback on.
Yours,
Joel

--------------------------------------------------------

As suggested on the list before the meeting, and discussed at the meeting, 
I think it may make sense to provide explicit mechanisms in the model and 
protocol for referencing the properties of any element of any LFB.

The basic approach would be to include in the core library a data 
definition for the scalar for access (none, read-only, write-only, and 
read-write is what I would start with.)
Then, we would define a structure to be returned for a properties reference 
to any element in the model.  A property reference would be indicated by 
setting a bit in the path flags that reference the element.

At the moment, I can see two structure definitions.  One for most elements 
which only contains the access permissions, and one for arrays which 
contains other array properties.  I have included the XML declarations for 
all of this at the end of this message.

There are a number of open questions:

1) What should we use for the properties of a structure?  We could just 
return the permissions, which would relate to the structure as a whole.  We 
could try to return a complex structure with the permissions for the struct 
and the permissions for every element within the structure.  I am inclined 
to keep this simple, but the result is that if one needs the element 
properties one has to GET a number of pieces of information.

2) What should we use for the properties of an LFB?  (This would be 
reference by a path with the properties flag set and 0 identifiers in the 
path ids.)  Should it reference just the LFB?  Should it try to return the 
properties for every top level element in the LFB?

3) What about Aliases?  All the other properties are read only.  It is very 
tempting to put the Alias target information into the alias properties 
structure (much as the array information is in the array properties 
structure.)  The one aspect that gives me pause in doing that is that we 
would have to allow SET operations against Alias properties to make this 
work.  Is that a good idea?

4) As a minor aspect, if we have nested path-data TLVs how should the 
property flag be set and interpreted?  My inclination is to say that the 
flag only applies to paths which do not have nested path-data.

For completeness, the XML:

<dataTypeDefs>
   <dataTypeDef>
     <name> elementAccessScalar </name>
     <synopsis> scalar of access permission values </synopsis>
     <atomic>
       <baseType> uchar </baseType>
       <specialValues>
         <specialValue value="0">
           <name> no-access </name>
           <synopsis> no access is permitted </synopsis>
         </specialValue>
         <specialValue value="2">
           <name> read-only </name>
           <synopsis> read access is permitted </synopsis>
         </specialValue>
         <specialValue value="2">
           <name> write-only </name>
           <synopsis> write access is permitted </synopsis>
         </specialValue>
         <specialValue value="3">
           <name> read-write </name>
           <synopsis> read and write access is permitted </synopsis>
         </specialValue>
       </specialValues>
     </atomic>
   </dataTypeDef>

   <dataTypeDef>
     <name> BasicElementProperties </name>
     <synopsis> the structure for most element properties </name>
     <struct>
       <element>
         <elementID> 1 </elementID>
         <name> access-permissions </name>
         <synopsis> what access is permitted to the referenced element 
</synopsis>
         <typeRef> elementAccessScalar </typeRef>
       </element>
     </struct>
   </dataTypeDef>

   <dataTypeDef>
     <name> ArrayElementProperties </name>
     <synopsis> the additional properties for an array element </name>
     <struct>
       <derived-from> BasicElementProperties </dervice-from>
       <element>
         <elementID> 2 </elementID>
         <name> first-used-index </name>
         <synopsis> index of the first used array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
       <element>
         <elementID> 3 </elementID>
         <name> first-unused-index </name>
         <synopsis> index of the first available array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
       <element>
         <elementID> 4 </elementID>
         <name> last-used-index </name>
         <synopsis> index of the last used array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
        <element>
         <elementID> 5 </elementID>
         <name> used-entry-count </name>
         <synopsis> number of entries used in the array element </synposis>
         <typeRef> uint32 </typeRef>
       </element>
    </struct>
   </dataTypeDef>

Yours,
Joel M. Halpern

PS: I have moved derived-from and element-ID to nested elements instead of 
attributes because that seems the most consistent with the advice I could 
get from the application folks.  I still should talk to Scott Hollenbeck to 
really understand this.

---

From: Jamal Hadi Salim <[email-masked]>
Date: Wed, 4 May 2005 18:04:05 -0400

Hi Joel,

> There are a series of specific questions that I would really like feedback on.

Apologies, I meant to respond (after reading it of course ;->).

Sounds sensible.

> all of this at the end of this message.

Access controls for elements and the array properties are the only
associated metadata i can think of at the moment; it doesnt seem that
you object to any other properties being added in the future, right?

> properties one has to GET a number of pieces of information.

The more fine grained the better, but its a lot of detail. 
I think that hierachies (example a struct X access control vs a
X.element1 access control with the former defining the default for the
struct  and the later overriding the default. Too complex)

> properties for every top level element in the LFB?

So example properties of an LFB would be its ID, where its derived from
etc? 
It sounds to me like what you describe is sufficient for the path at
least.
I think anything under LFBClassDefs is target-able via a path - so is it
would be simpler to access those properties just by pointing at them
appropriately, no?

> work.  Is that a good idea?

Shouldnt all properties be SETable anyways? In otherwise, shouldnt i
(CE) be able to change an attribute from read-only to read-write at
runtime? It depends on the attribute of course - some dont make sense to
do so. 

> flag only applies to paths which do not have nested path-data.

Why this restriction? I would think that if i can formulate a GET to
some target with the properties bit set, theres a clear meaning as to
what i am trying to GET, no?

>          <elementID> 1 </elementID>

Did you just go back to the old format of defining IDs?

Otherwise, the xml looks clear enough to me.

> get from the application folks.  I still should talk to Scott Hollenbeck to 

Duh, ok - this answers my question then. Are you going to change the
general grammar to match this?

cheers,
jamal

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 4 May 2005 20:02:02 -0400

I did not edit the message to reflect what I learned since about attributes 
and elements.
I have been going back and forth on what things should be attributes, and 
what should be nested elements.

If I have understood the XML experts properly, the best answer is that IDs 
should be attributes, but "derived-from" should be an element.

Thanks for looking at all of this.
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 4 May 2005 20:03:33 -0400

I had assumed that if an FE said that an element was read-only, that was 
because the FE was not prepared to let the CE write to that element.  If 
the FE is prepared to let the CE write the element, then it would be 
read-write.
So I could not come up with a case where the CE would write the properties, 
except for the alias situation.

Thanks,
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 4 May 2005 20:11:22 -0400

Let me be more explicit about the case I thought was confusing:

Path-Data:
    Flag(a) = properties, path = 1.2
       nested-path-data-1
            Flag(b) = 0, path = 3
       nested-path-data-2
            Flag(c) =properties, path=4

(nested-path-1 and nested-path-2 are both nested in the main path-data, and 
are siblings to each other.)

Clearly, something about 1.2.3 and 1.2.4 is to be returned.
If we ignore flag a, then we return the data from 1.2.3, and the properties 
about 1.2.4.
If flag-a matters, then the only conclusion I can reach is that we are to 
return the properties information about 1.2.3 and 1.2.4, and the flags b 
and c don't matter.

My suggestion is that flag-a should be ignored.

Yours,
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Wed, 4 May 2005 20:12:24 -0400

That's what I thought too.
If we come up with more, we add it (this rev or a future rev).
Joel

---

From: Jamal Hadi Salim <[email-masked]>
Date: Thu, 5 May 2005 17:43:30 -0400

> except for the alias situation.

Hopefully this will address Ellen's comment as well and lets pick access
control as an example.

Who is it that decides that an elememt is read-only?

1) Clearly one scheme is to make that call at LFB definition time.
And everybody knows. 

2) The FE makes that call. It does make sense; there are cases where
somethings (as an example something residing in ROM such as a serial
number) are read only.
However if we know #1, #2 is a noop.

3) The CE makes the call. This is the scenario i was referring to. 
Ok, granted it doesnt make sense for the CE to overwrite something
that is truly read-only at the FE, but assume the CE is smart enough to
know the difference.

Actually let me backtrack a little .. the model i had in mind for access
control was to infact to allow for for true ACLs and
different entities to access an FE's LFB. Some of them may have
read-only permission while some may have read-write ability. This will
fall under #3 where the CE sets these permissions - I realize i am
pushing the envelope a little here but do we wanna disallow that?

cheers,
jamal

---

From: Jamal Hadi Salim <[email-masked]>
Date: Thu, 5 May 2005 17:46:38 -0400

Joel,

Yes, I can see the ambiguity in this case.
Can you please capture the text in your description in the draft as well
(maybe some appendix section)?. I am leaving the thread in its entirety
below so people understand whats being said.

cheers,
jamal

---

From: Jamal Hadi Salim <[email-masked]>
Date: Thu, 5 May 2005 17:50:25 -0400

Actualluy one way to resolve this ambiguity is not to use flags but
rather a new command like GET-PROPERTIES

cheers,
jamal

---

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 5 May 2005 17:53:55 -0400

This seems to be about multiple entities having access to some FE attribute:

Clearly, the CE can not tell the FE not to write something it needs to write.
The access permissions information is about CE access.
SO, we must be talking about multiple CE.

1) That is something way out of scope, with lots of complications.
2) Having one CE say "no CE may write this" seems odd, since equivalently, 
some other CE can say "This is writeable", so I can not see why having a CE 
change the permissions, if it were possible, would be helpful.

It seems like life is much simpler if the permissions are about what the FE 
will permit the CE to do.

If we want later to enhance the properties structure with some other 
information for interlock control or something, that would come later.  I 
would hate to mask the basic "this is what the FE will permit the CE to do" 
property.

Yours,
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 5 May 2005 17:54:58 -0400

I will be happy to capture the ambiguity in the text.
But we need to pick the behavior.  Is ignoring the outer flags acceptable?

Does anyone other than Jamal and me understand this?

Thanks,
Joel

---

From: "Joel M. Halpern" <[email-masked]>
Date: Thu, 5 May 2005 17:56:12 -0400

That is particularly attractive if we do not want writeable properties.

Yours,
Joel

---

From: Jamal Hadi Salim <[email-masked]>
Date: Thu, 5 May 2005 18:12:06 -0400

> SO, we must be talking about multiple CE.

I am not sure whether i would go as far as calling them "CEs"
but they are say processes in the CE. A process may "own" one LFB 
(qoS) while another may " own"  configuration of another(forwarding). 
We seem to have allowed a description of this in some of the earlier
drafts. 

> 1) That is something way out of scope, with lots of complications.

I wouldnt disagree. 

> change the permissions, if it were possible, would be helpful.

Not if you think of them as processes in the CE. We did allow such
descriptions (cant remember what draft) - and this has already caused
questions in regards to the xID a while back from people like Robert.

> will permit the CE to do.

Agree. 

> would hate to mask the basic "this is what the FE will permit the CE to do" 

Well as in any ACL you will maintain some list of possible entities and
their permissions.

Note, I am not disagreeing on the complexity of this and i am not sure i
want it even ;-> I just brought AC as a way to show a different
perspective. My intent was to show that element properties other than
aliases may need to be writeable - maybe not the ones we have identified
right now. 
I dont want to be totaly future-proof but if the cost of adding it is
low today, i would have no issues.

cheers,
jamal

---

From: Jamal Hadi Salim <[email-masked]>
Date: Thu, 5 May 2005 18:24:58 -0400

> >rather a new command like GET-PROPERTIES

Or you could have a SET-PROPERTIES in addition if writable proved
useful.

cheers,
jamal