Re: Should Representation Clauses be complete for each bit?

Re: Should Representation Clauses be complete for each bit?

[Stephen Leake]

Lowe Anthony A wrote:
> 
> Some of our new Ada folks have written Rep Clauses which do not
> explicitly map every bit in the range of data to a member of the
> record.  (i.e.
>    type x is record
>      one : boolean;
>      two : boolean;
>      three : boolean;
>    end record;
>    for x use record
>      one   at 0 range 0..0;
>      two   at 0 range 3..3;
>      three at 0 range 15..15;
>    end record;
> 
> In the past I have always used a package Rep_Clause_Types which
> defines spare bits types for anywhere from 1 to 31 bits of spare and
> subprograms to set each of the choices to all zeros or ones.  I have
> not found any information in the LRM or Q&S to guide which way is more
> appropriate.
>     On one hand, it is helpful to explicitly state that these bits are
> spare and will not be used for any specific purpose.  If you fill in
> the spare bits with elements, they can be explicitly set to a value
> (ones or zeros).   This is nice for cleanliness, but costs some
> execution time for initialization.  I also am a bit concerned about
> people using the 'spare bit' types instead of creating new types when
> the spare bits mean something.
>     On the other hand, if the compilers do not require you to fill it
> in and the Q&S is quiet on the subject, it must not be that bad to
> do.   It is definitely easier and less crowded to not fill them in.
>     If my description is not too biased I think you can see that I am
> leaning towards requiring each rep clause to be complete.   I am
> interested on other takes on this issue for screaming benifits/costs
> of either approach.

I've had problems leaving bits undefined and then passing them to
Windows API functions. The Windows API has many "flag" arguments that
are easily defined by Ada records. However, the C definition is via
constants with 1 in the appropriate bits. Apparently, the actual API
functions do not always mask out the unused bits.

I've also had problems with comparing test outputs. If you leave bits
undefined, then you get whatever was left in the register from the
previous operation. If you then print this value as hex (for debugging
stream output, say), you may see different values from run to run. I
usually only see different values when changing compilers (GNAT to
ObjectAda), but it could happen when you change optimization levels. The
problem is not that the behavior is undefined, just that the test output
changes, which makes comparing the test results more difficult.

So I've adopted the general policy that all bits must be defined.
-- 
- Stephe

Re: Should Representation Clauses be complete for each bit?

[Marin David Condic, 561.796.8997, M/S 731-96]

Stephen Leake <Stephen.Leake@GSFC.NASA.GOV> writes:
>Lowe Anthony A wrote:
>>
<snip>
>>     If my description is not too biased I think you can see that I am
>> leaning towards requiring each rep clause to be complete.   I am
>> interested on other takes on this issue for screaming benifits/costs
>> of either approach.
>
<snip>
>
>So I've adopted the general policy that all bits must be defined.
>
    I used to be of the mind that all bits should be defined as
    "Spare_xx" or something similar to make it clear which bits were
    undefined by hardware, etc. It had the advantage of making a
    change rather direct & simple if one of the spare bits suddenly
    comes into use.

    However, I've shifted my thinking on this. It is certainly less
    "cluttered" to avoid declaring unused bits. Also, it is less
    misleading. I have encountered code where the programmer declared
    all unused bits as "Spare" (or similar) only to discover later
    that there really were definitions for the bits in question - just
    that they were unused by this particular piece of code. One might
    have been tempted to appropriate the bits for something else. So
    if they are left completely undefined, someone else comming along
    later is not likely to make assumptions about the bits other than
    that they are not used by this application.

    One thing I do favor is this: Where you are using the rep clause
    to model something coming out of hardware or some external source,
    I find it a good idea to define all of the fields that are
    documented and do so with names as close to what appears in the
    document as is possible. This way it is explicit what bits the
    hardware is supposed to be setting/using, what bits the hardware
    does not care about (if its labeled "reserved" you probably want
    to declare it to make clear that the hardware *might* use those
    bits) and there is a clear mapping between what someone reads in
    the document and what they read in the code. The code may not use
    all the bits that are defined - and that's O.K. - but it is clear
    when reading the definition, why those bits exist.

    It would be nice to have a convention on this one way or the
    other.

    MDC

Marin David Condic, Senior Computer Engineer     Voice:     561.796.8997
Pratt & Whitney GESP, M/S 731-95, P.O.B. 109600  Fax:       561.796.4669
West Palm Beach, FL, 33410-9600                  Internet:  CONDICMA@PWFL.COM
=============================================================================
    "Because that's where they keep the money."
        --  Willie Sutton when asked why he robbed banks.
=============================================================================

Should representation clauses be complete for each bit?

[okellogg]

Picking up an age old thread,
http://groups.google.com/group/comp.lang.ada/browse_thread/thread/9ab165cd2cc73cb

IMHO it would be a real gain if we could explicitly mention the unused
bits in the rep spec.
Reusing the example from the OP,

>    type x is record
>      one : boolean;
>      two : boolean;
>      three : boolean;
>    end record;
>    for x use record
>      one   at 0 range 0..0;
>      two   at 0 range 3..3;
>      three at 0 range 15..15;
>    end record;

What I imagine is something like,

for x use record
   one   at 0 range 0 .. 0;
   null   at 0 range 1 .. 2;    // note reserved word "null"
   two   at 0 range 3 .. 3;
   null   at 0 range 4 .. 14;
   three at 0 range 15 .. 15;
end record;
for x'Size use 16;

The components with "null" would instruct the compiler to fill the
bits with 0.

-- Oliver

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

okellogg <okellogg@users.sourceforge.net> writes:

> Picking up an age old thread,
> http://groups.google.com/group/comp.lang.ada/browse_thread/thread/9ab165cd2cc73cb

Wow.   1998.

> IMHO it would be a real gain if we could explicitly mention the unused
> bits in the rep spec.

I think the unused bits should be explicitly declared.

> Reusing the example from the OP,
>
>>    type x is record
>>      one : boolean;
>>      two : boolean;
>>      three : boolean;
>>    end record;
>>    for x use record
>>      one   at 0 range 0..0;
>>      two   at 0 range 3..3;
>>      three at 0 range 15..15;
>>    end record;
>
> What I imagine is something like,
>
> for x use record
>    one   at 0 range 0 .. 0;
>    null   at 0 range 1 .. 2;    // note reserved word "null"
>    two   at 0 range 3 .. 3;
>    null   at 0 range 4 .. 14;
>    three at 0 range 15 .. 15;
> end record;
> for x'Size use 16;
>
> The components with "null" would instruct the compiler to fill the
> bits with 0.

How about the following?

package P is
   type Bits2 is mod 2**2;
   pragma Assert (Bits2'Size = 2);
   type Bits11 is mod 2**11;
   pragma Assert (Bits11'Size = 11);

   type T is
      record
         One : Boolean;
         Gap1 : Bits2; -- must be zero
         Tooth : Boolean;
         Gap2 : Bits11; -- must be zero
         Ree : Boolean;
      end record
        with Predicate => T.Gap1 = 0 and T.Gap2 = 0;

   for T use
      record
         pragma Complete_Representation;
         One at 0 range 0..0;
         Gap1 at 0 range 1..2;
         Tooth at 0 range 3..3;
         Gap2 at 0 range 4..14;
         Ree at 0 range 15..15;
      end record;
end P;

with Ada.Assertions; use Ada.Assertions;
procedure P.Main is
   X : T := (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0); -- OK
begin
   begin
      X := T'(One | Tooth | Ree => True, Gap1 => 1, Gap2 => 2); -- Wrong.
   exception
      when Assertion_Error => null; -- OK
   end;
   pragma Assert (X = (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0));
end P.Main;

By the way, I find Ada's representation clauses to be at the wrong
level of abstraction.  Why can't I just write a single line of code
that means "put all the components in declaration order with no gaps
in between"?

- Bob

Re: Should representation clauses be complete for each bit?

[Georg Bauhaus]

On 20.07.11 16:51, Robert A Duff wrote:

> By the way, I find Ada's representation clauses to be at the wrong
> level of abstraction.  Why can't I just write a single line of code
> that means "put all the components in declaration order with no gaps
> in between"?

Is this a frequent use case?

Re: Should representation clauses be complete for each bit?

[okellogg]

On 20 Jul., 16:51, Robert A Duff <bobd...@shell01.TheWorld.com> wrote:
> [...]
> > IMHO it would be a real gain if we could explicitly mention the unused
> > bits in the rep spec.
>
> I think the unused bits should be explicitly declared.

My use case originates from a bit packed communication protocol where
the standard requires spare bits interspersed among the useful data.
However the API of the driver shall not expose these spare fields.
This leads to the complexity that I have two sets of type definitions,
one for on-the-wire usage and the other, almost identical (modulo the
spare fields) for the driver API - which entails the need for hand
coded conversion between these types.

Oliver

Re: Should representation clauses be complete for each bit?

[Dmitry A. Kazakov]

On Wed, 20 Jul 2011 08:29:18 -0700 (PDT), okellogg wrote:

> My use case originates from a bit packed communication protocol where
> the standard requires spare bits interspersed among the useful data.

My advise would be not to use representation clauses. They cannot deal with
protocols anyway. Think about protocol error handling, special patterns of
bits, checksums etc. It also makes no sense in letting the wire-specific
types to spoil the rest of your code with unchecked unions, nonnative
scalars, misaligned data, nul-terminated rubbish etc. Any performance gain
compared to explicit parsing would be negligible and may turn to a loss
later when the data are used.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Should representation clauses be complete for each bit?

[okellogg]

On Jul 20, 6:24 pm, "Dmitry A. Kazakov" <mail...@dmitry-kazakov.de>
wrote:
> On Wed, 20 Jul 2011 08:29:18 -0700 (PDT), okellogg wrote:
> > My use case originates from a bit packed communication protocol where
> > the standard requires spare bits interspersed among the useful data.
>
> My advise would be not to use representation clauses. They cannot deal with
> protocols anyway.

Wow. I thought this is what rep clauses are there for.

> Think about protocol error handling, special patterns of
> bits, checksums etc. It also makes no sense in letting the wire-specific
> types to spoil the rest of your code with unchecked unions, nonnative
> scalars, misaligned data, nul-terminated rubbish etc. Any performance gain
> compared to explicit parsing would be negligible and may turn to a loss
> later when the data are used.

Mind you, I am talking in hindsight, this is not something I invented.
I.e. I've implemented the mentioned protocol already.
I share your concerns wrt a high level interface but I'm talking about
a driver API here.
OTOH, I guess I could go along with "if it's a low level interface,
why not make the spare bits visibile too."
At this level, the user must know precisely what he's doing anyway,
and that filling data into spare fields isn't going to buy anything.
It's just extra baggage that nobody really needs.

Oliver

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

okellogg <okellogg@users.sourceforge.net> writes:

> On 20 Jul., 16:51, Robert A Duff <bobd...@shell01.TheWorld.com> wrote:
>> [...]
>> > IMHO it would be a real gain if we could explicitly mention the unused
>> > bits in the rep spec.
>>
>> I think the unused bits should be explicitly declared.
>
> My use case originates from a bit packed communication protocol where
> the standard requires spare bits interspersed among the useful data.
> However the API of the driver shall not expose these spare fields.

I see.

But that could happen with any component -- it doesn't have to be
"spare" and set to zero.  What if the protocol requires "set this
3-bit gap to all 1's"?  Or what if there's a checksum component,
which is set by the driver just before shipping the thing over
the wire -- in that case, you wouldn't want to expose the checksum
to clients.

Perhaps this is what you really want (note that this is illegal
for all sorts of reasons):

   type T1 is
      record
         One : Boolean;
         Tooth : Boolean;
         Ree : Boolean;
      end record;

   type T2 is new T1 with private; -- not Ada!
private
   type T2 is new T1 with
      record
         Gap1 : Bits2; -- must be zero
         Gap2 : Bits11; -- must be zero
      end record
        with Predicate => T.Gap1 = 0 and T.Gap2 = 0;

   for T1 use
      record
         pragma Complete_Representation;
         One at 0 range 0..0;
         Tooth at 0 range 3..3;
         Ree at 0 range 15..15;
      end record;

   for T2 use
      record
         pragma Complete_Representation;
         Gap1 at 0 range 1..2;
         Gap2 at 0 range 4..14;
      end record;

- Bob

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

Georg Bauhaus <rm.dash-bauhaus@futureapps.de> writes:

> On 20.07.11 16:51, Robert A Duff wrote:
>
>> By the way, I find Ada's representation clauses to be at the wrong
>> level of abstraction.  Why can't I just write a single line of code
>> that means "put all the components in declaration order with no gaps
>> in between"?
>
> Is this a frequent use case?

Yes, I think so.

- Bob

Re: Should representation clauses be complete for each bit?

[okellogg]

On Jul 20, 7:27 pm, Robert A Duff <bobd...@shell01.TheWorld.com>
wrote:
> [...]
> But that could happen with any component -- it doesn't have to be
> "spare" and set to zero.  What if the protocol requires "set this
> 3-bit gap to all 1's"?  Or what if there's a checksum component,
> which is set by the driver just before shipping the thing over
> the wire -- in that case, you wouldn't want to expose the checksum
> to clients.

Yes, I guess you're right.
The syntax you propose is much more general and flexible.

> Perhaps this is what you really want (note that this is illegal
> for all sorts of reasons):
>
>    type T1 is
>       record
>          One : Boolean;
>          Tooth : Boolean;
>          Ree : Boolean;
>       end record;
>
>    type T2 is new T1 with private; -- not Ada!
> private
>    type T2 is new T1 with
>       record
>          Gap1 : Bits2; -- must be zero
>          Gap2 : Bits11; -- must be zero
>       end record
>         with Predicate => T.Gap1 = 0 and T.Gap2 = 0;

I'd imagine that a default assignment at Gap1 and Gap2 would suffice?
         Gap1 : Bits2 := 0;

>    for T1 use
>       record
>          pragma Complete_Representation;
>          One at 0 range 0..0;
>          Tooth at 0 range 3..3;
>          Ree at 0 range 15..15;
>       end record;
>
>    for T2 use
>       record
>          pragma Complete_Representation;
>          Gap1 at 0 range 1..2;
>          Gap2 at 0 range 4..14;
>       end record;
>

I believe the compiler would warn about incomplete representation at
T1?

Also I guess an upcast from T2 to T1 should do for converting the
types but I'm not so sure about the downcast from T1 to T2?

-- Oliver

Re: Should representation clauses be complete for each bit?

[Dmitry A. Kazakov]

On Wed, 20 Jul 2011 09:58:14 -0700 (PDT), okellogg wrote:

> On Jul 20, 6:24�pm, "Dmitry A. Kazakov" <mail...@dmitry-kazakov.de>
> wrote:
>> On Wed, 20 Jul 2011 08:29:18 -0700 (PDT), okellogg wrote:
>>> My use case originates from a bit packed communication protocol where
>>> the standard requires spare bits interspersed among the useful data.
>>
>> My advise would be not to use representation clauses. They cannot deal with
>> protocols anyway.
> 
> Wow. I thought this is what rep clauses are there for.

I doubt it. Theoretically one could invent some data representation
language capable to match and parse a protocol into a set of typed objects.
Ada's representation clauses is not such a language being too limited and
too primitive. I think Ada designers didn't considered this as a goal,
because they didn't bother to provide representation clauses for
floating-point types, variant records, unconstrained arrays, linked lists
etc, the types you really need to map any, more or less, elaborated
protocol. Even if they did, that would be still useless, without the notion
of state influencing the representation etc.

>> Think about protocol error handling, special patterns of
>> bits, checksums etc. It also makes no sense in letting the wire-specific
>> types to spoil the rest of your code with unchecked unions, nonnative
>> scalars, misaligned data, nul-terminated rubbish etc. Any performance gain
>> compared to explicit parsing would be negligible and may turn to a loss
>> later when the data are used.
> 
> Mind you, I am talking in hindsight, this is not something I invented.
> I.e. I've implemented the mentioned protocol already.

OK, you were lucky, or maybe not, because it may have hit you later.

> I share your concerns wrt a high level interface but I'm talking about
> a driver API here.

What is the difference?

> At this level, the user must know precisely what he's doing anyway,
> and that filling data into spare fields isn't going to buy anything.
> It's just extra baggage that nobody really needs.

Poorly designed protocols are more common than others.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Should representation clauses be complete for each bit?

[J-P. Rosen]

Le 20/07/2011 21:14, okellogg a �crit :
> I believe the compiler would warn about incomplete representation at
> T1?
> 
<PLUG>
Two useful AdaControl rules:
check representation_clauses (incomplete_layout);
-- some components are missing

check representation_clauses (non_contiguous_layout);
-- there are gaps in the record
</PLUG>
-- 
---------------------------------------------------------
           J-P. Rosen (rosen@adalog.fr)
Adalog a d�m�nag� / Adalog has moved:
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

okellogg <okellogg@users.sourceforge.net> writes:

>> � � � � with Predicate => T.Gap1 = 0 and T.Gap2 = 0;
>
> I'd imagine that a default assignment at Gap1 and Gap2 would suffice?
>          Gap1 : Bits2 := 0;

Yeah, maybe.

>> � �for T1 use
>> � � � record
>> � � � � �pragma Complete_Representation;
>> � � � � �One at 0 range 0..0;
>> � � � � �Tooth at 0 range 3..3;
>> � � � � �Ree at 0 range 15..15;
>> � � � end record;
>>
>> � �for T2 use
>> � � � record
>> � � � � �pragma Complete_Representation;
>> � � � � �Gap1 at 0 range 1..2;
>> � � � � �Gap2 at 0 range 4..14;
>> � � � end record;
>>
>
> I believe the compiler would warn about incomplete representation at
> T1?

I think "pragma Complete_Representation" means "require every component
to be mentioned", not "require every bit from 0 to 'Size-1 to be used up.
Not sure.

> Also I guess an upcast from T2 to T1 should do for converting the
> types but I'm not so sure about the downcast from T1 to T2?

I'm assuming the package would export functions to create T2 objects
and operate on them.  Or maybe it would be more convenient to derive
the other way round (put the gaps in the parent type), so clients
could say (Parent_Type with One | Tooth => True, Ree => False),
assuming Parent_Type defaults the gaps to 0, as you suggested.

- Bob

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

"J-P. Rosen" <rosen@adalog.fr> writes:

> Le 20/07/2011 21:14, okellogg a �crit :
>> I believe the compiler would warn about incomplete representation at
>> T1?
>> 
> <PLUG>
> Two useful AdaControl rules:
> check representation_clauses (incomplete_layout);
> -- some components are missing
>
> check representation_clauses (non_contiguous_layout);
> -- there are gaps in the record
> </PLUG>

Cool.  I think the GNAT pragma matches incomplete_layout,
but the other one seems even more useful, to me.

- Bob

Re: Should representation clauses be complete for each bit?

[Martin]

On Jul 20, 3:51 pm, Robert A Duff <bobd...@shell01.TheWorld.com>
wrote:
> okellogg <okell...@users.sourceforge.net> writes:
> > Picking up an age old thread,
> >http://groups.google.com/group/comp.lang.ada/browse_thread/thread/9ab...
>
> Wow.   1998.
>
> > IMHO it would be a real gain if we could explicitly mention the unused
> > bits in the rep spec.
>
> I think the unused bits should be explicitly declared.
>
>
>
>
>
>
>
>
>
> > Reusing the example from the OP,
>
> >>    type x is record
> >>      one : boolean;
> >>      two : boolean;
> >>      three : boolean;
> >>    end record;
> >>    for x use record
> >>      one   at 0 range 0..0;
> >>      two   at 0 range 3..3;
> >>      three at 0 range 15..15;
> >>    end record;
>
> > What I imagine is something like,
>
> > for x use record
> >    one   at 0 range 0 .. 0;
> >    null   at 0 range 1 .. 2;    // note reserved word "null"
> >    two   at 0 range 3 .. 3;
> >    null   at 0 range 4 .. 14;
> >    three at 0 range 15 .. 15;
> > end record;
> > for x'Size use 16;
>
> > The components with "null" would instruct the compiler to fill the
> > bits with 0.
>
> How about the following?
>
> package P is
>    type Bits2 is mod 2**2;
>    pragma Assert (Bits2'Size = 2);
>    type Bits11 is mod 2**11;
>    pragma Assert (Bits11'Size = 11);
>
>    type T is
>       record
>          One : Boolean;
>          Gap1 : Bits2; -- must be zero
>          Tooth : Boolean;
>          Gap2 : Bits11; -- must be zero
>          Ree : Boolean;
>       end record
>         with Predicate => T.Gap1 = 0 and T.Gap2 = 0;
>
>    for T use
>       record
>          pragma Complete_Representation;
>          One at 0 range 0..0;
>          Gap1 at 0 range 1..2;
>          Tooth at 0 range 3..3;
>          Gap2 at 0 range 4..14;
>          Ree at 0 range 15..15;
>       end record;
> end P;
>
> with Ada.Assertions; use Ada.Assertions;
> procedure P.Main is
>    X : T := (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0); -- OK
> begin
>    begin
>       X := T'(One | Tooth | Ree => True, Gap1 => 1, Gap2 => 2); -- Wrong.
>    exception
>       when Assertion_Error => null; -- OK
>    end;
>    pragma Assert (X = (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0));
> end P.Main;
>
> By the way, I find Ada's representation clauses to be at the wrong
> level of abstraction.  Why can't I just write a single line of code
> that means "put all the components in declaration order with no gaps
> in between"?
>
> - Bob

A bit like Telegen2's "pragma Preserve_Layout" (if my memory hasn't
rusted too much)?...

-- Martin

Re: Should representation clauses be complete for each bit?

[Martin]

On Jul 20, 6:28 pm, Robert A Duff <bobd...@shell01.TheWorld.com>
wrote:
> Georg Bauhaus <rm.dash-bauh...@futureapps.de> writes:
> > On 20.07.11 16:51, Robert A Duff wrote:
>
> >> By the way, I find Ada's representation clauses to be at the wrong
> >> level of abstraction.  Why can't I just write a single line of code
> >> that means "put all the components in declaration order with no gaps
> >> in between"?
>
> > Is this a frequent use case?
>
> Yes, I think so.
>
> - Bob

I think you're right, Bob. In fact, I'd go so far as to say it's very,
very common.
-- Martin

Re: Should representation clauses be complete for each bit?

[Stephen Leake]

Georg Bauhaus <rm.dash-bauhaus@futureapps.de> writes:

> On 20.07.11 16:51, Robert A Duff wrote:
>
>> By the way, I find Ada's representation clauses to be at the wrong
>> level of abstraction.  Why can't I just write a single line of code
>> that means "put all the components in declaration order with no gaps
>> in between"?
>
> Is this a frequent use case?

Yes, extremely.

The case with explicit gaps is also extremely common; I like the 'null
at ...' idea.

-- 
-- Stephe

Re: Should representation clauses be complete for each bit?

[Stephen Leake]

okellogg <okellogg@users.sourceforge.net> writes:

> On 20 Jul., 16:51, Robert A Duff <bobd...@shell01.TheWorld.com> wrote:
>> [...]
>> > IMHO it would be a real gain if we could explicitly mention the unused
>> > bits in the rep spec.
>>
>> I think the unused bits should be explicitly declared.
>
> My use case originates from a bit packed communication protocol where
> the standard requires spare bits interspersed among the useful data.
> However the API of the driver shall not expose these spare fields.
> This leads to the complexity that I have two sets of type definitions,
> one for on-the-wire usage and the other, almost identical (modulo the
> spare fields) for the driver API - which entails the need for hand
> coded conversion between these types.

+2

-- 
-- Stephe

Re: Should representation clauses be complete for each bit?

[Stephen Leake]

okellogg <okellogg@users.sourceforge.net> writes:

> On Jul 20, 7:27 pm, Robert A Duff <bobd...@shell01.TheWorld.com>
> wrote:
>> [...]
>> But that could happen with any component -- it doesn't have to be
>> "spare" and set to zero.  What if the protocol requires "set this
>> 3-bit gap to all 1's"?  Or what if there's a checksum component,
>> which is set by the driver just before shipping the thing over
>> the wire -- in that case, you wouldn't want to expose the checksum
>> to clients.
>
> Yes, I guess you're right.
> The syntax you propose is much more general and flexible.

+2

-- 
-- Stephe

Re: Should representation clauses be complete for each bit?

[Simon Wright]

Martin <martin@thedowies.com> writes:

> On Jul 20, 6:28 pm, Robert A Duff <bobd...@shell01.TheWorld.com>
> wrote:
>> Georg Bauhaus <rm.dash-bauh...@futureapps.de> writes:
>> > On 20.07.11 16:51, Robert A Duff wrote:
>>
>> >> By the way, I find Ada's representation clauses to be at the wrong
>> >> level of abstraction.  Why can't I just write a single line of code
>> >> that means "put all the components in declaration order with no gaps
>> >> in between"?
>>
>> > Is this a frequent use case?
>>
>> Yes, I think so.
>>
>> - Bob
>
> I think you're right, Bob. In fact, I'd go so far as to say it's very,
> very common.
> -- Martin

Presumably if something took only three bits you'd have to say that much
at least.

And would it be 'Size or 'Object_Size? (remembering that Natural'Size
{used to be,is} Integer'Size - 1).

Wouldn't pragma Pack do this?

It may be that *if you need to specify a representation* this is a
common use case (I don't remember it being so), but needing to specify a
representation is pretty rare anyway. And so it should be, after all it
should only happen at the edges, well hidden from the bulk of the
application.

Re: Should representation clauses be complete for each bit?

[Georg Bauhaus]

On 21.07.11 09:37, Martin wrote:
> On Jul 20, 6:28 pm, Robert A Duff <bobd...@shell01.TheWorld.com>
> wrote:
>> Georg Bauhaus <rm.dash-bauh...@futureapps.de> writes:
>>> On 20.07.11 16:51, Robert A Duff wrote:
>>
>>>> By the way, I find Ada's representation clauses to be at the wrong
>>>> level of abstraction.  Why can't I just write a single line of code
>>>> that means "put all the components in declaration order with no gaps
>>>> in between"?
>>
>>> Is this a frequent use case?
>>
>> Yes, I think so.
>>
>> - Bob
> 
> I think you're right, Bob. In fact, I'd go so far as to say it's very,
> very common.
> -- Martin

More specifically, if the original example of "not all bits used and some
gaps between them" is unusual, is it so

- when mapping to a set of hardware pins, say?

- or when "interfacing" to C structs?

For C structs, declaration order seems very convenient, as C keeps
declaration order.  But C may well introduce gaps between structure
components whenever its alignment rules requires.  Then I will want
gaps in Ada, too.  Is a convention pragma sufficient, then?

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

Simon Wright <simon@pushface.org> writes:

> Presumably if something took only three bits you'd have to say that much
> at least.

Part of my complaint is that you have to say it twice:

    type Bits2 is mod 2**2;
    pragma Assert (Bits2'Size = 2);

OK, now we have a 2-bit type.  But we have to specify 2 bits again
in the rep clause:

         Gap1 at 0 range 1..2;

> And would it be 'Size or 'Object_Size? (remembering that Natural'Size
> {used to be,is} Integer'Size - 1).

"is"

'Size is what you want, I think, although you might want a feature
that says "warn me if I do something weird" (like making an array
of Natural whose 'Component_Size is 31.

If you have a record with a 32-bit Natural component, and you read it in
from some outside source, you have to worry about that extra bit.
You really need to have a 31-bit Natural, with a must-be-zero gap
(which I claim should normally be explicit).  Or else you want a
32-bit Integer, so you can write validation code ("if X.Y < 0 then
panic; end if;").

> Wouldn't pragma Pack do this?

No, Pack doesn't guarantee any particular representation.  For example,
it allows the compiler to reorder the components, which is a good
idea for efficiency.  Pack is all about efficiency, not about
interfacing to some outside hardware or network protocol.

> It may be that *if you need to specify a representation* this is a
> common use case

Yes, that's what I meant.

>... (I don't remember it being so), but needing to specify a
> representation is pretty rare anyway. And so it should be, after all it
> should only happen at the edges, well hidden from the bulk of the
> application.

I agree.

- Bob

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

Georg Bauhaus <rm.dash-bauhaus@futureapps.de> writes:

> More specifically, if the original example of "not all bits used and some
> gaps between them" is unusual, is it so
>
> - when mapping to a set of hardware pins, say?

Whenever I see documentation for such things, they have rectangular pictures
showing what every bit means.  They don't have implicit gaps.  If there
are any gaps, they are shown explicitly, as "must be zero" or "reserved
for future hardware extensions" or whatever.

My claim is that the Ada code interfacing to such a thing should be
similarly explicit about the gaps.

Otherwise, you end up with nasty bugs: one compiler just happens to
set the gaps to zero, and you write to a file, and binary comparisons
of those files work.  Then you port to a different compiler, and it
puts arbitrary junk in the gaps.

> - or when "interfacing" to C structs?
>
> For C structs, declaration order seems very convenient, as C keeps
> declaration order.  But C may well introduce gaps between structure
> components whenever its alignment rules requires.  Then I will want
> gaps in Ada, too.  Is a convention pragma sufficient, then?

Right, pragma Convention(C) will properly interface to a C struct,
so long as the Ada record matches the C struct component-for-component,
and you're using a C compiler supported (for interfacing) by the Ada
compiler -- it's the Ada compiler's job to make the layout match
what that particular C compiler does.  And Convention(C) will prevent
reordering of components.

- Bob

Re: Should representation clauses be complete for each bit?

[Brian Drummond]

On Thu, 21 Jul 2011 11:43:22 +0200, Georg Bauhaus wrote:

> On 21.07.11 09:37, Martin wrote:
>> On Jul 20, 6:28 pm, Robert A Duff <bobd...@shell01.TheWorld.com> wrote:
>>> Georg Bauhaus <rm.dash-bauh...@futureapps.de> writes:
>>>> On 20.07.11 16:51, Robert A Duff wrote:
>>>
>>>>> By the way, I find Ada's representation clauses to be at the wrong
>>>>> level of abstraction.  Why can't I just write a single line of code
>>>>> that means "put all the components in declaration order with no gaps
>>>>> in between"?
>>>
>>>> Is this a frequent use case?
>>>
>>> Yes, I think so.
>>>
>>> - Bob
>> 
>> I think you're right, Bob. In fact, I'd go so far as to say it's very,
>> very common.
>> -- Martin
> 
> More specifically, if the original example of "not all bits used and
> some gaps between them" is unusual, is it so
> 
> - when mapping to a set of hardware pins, say?

Not common. But one common case is a hardware register in a peripheral, 
or even something as basic as a mode register in DDR memory ... "these 
fields are reserved, so undefined (probably bad) things will happen if 
you do anything other than set them to 0"

- Brian

Re: Should representation clauses be complete for each bit?

[Randy Brukardt]

"Robert A Duff" <bobduff@shell01.TheWorld.com> wrote in message 
news:wcczkk9ngxy.fsf@shell01.TheWorld.com...
...
> I think the unused bits should be explicitly declared.

I agree.

...
> How about the following?
>
> package P is
>   type Bits2 is mod 2**2;
>   pragma Assert (Bits2'Size = 2);
>   type Bits11 is mod 2**11;
>   pragma Assert (Bits11'Size = 11);
>
>   type T is
>      record
>         One : Boolean;
>         Gap1 : Bits2; -- must be zero
>         Tooth : Boolean;
>         Gap2 : Bits11; -- must be zero
>         Ree : Boolean;
>      end record
>        with Predicate => T.Gap1 = 0 and T.Gap2 = 0;

I would do this slightly differently (in fact we did, in Claw where we had 
this exact problem):

   type T is
      record
         One : Boolean;
         Gap1 : Bits2 := 0; -- must be zero
         Tooth : Boolean;
         Gap2 : Bits11 := 0; -- must be zero
         Ree : Boolean;
      end record
       with Predicate => T.Gap1 = 0 and T.Gap2 = 0;

with the same record rep clause.
Then the (correct) aggregates don't need to mention the gaps explicitly:

with Ada.Assertions; use Ada.Assertions;
procedure P.Main is
--   X : T := (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0); -- OK
    X : T := (One | Tooth | Ree => True, others =>  <>); -- OK

                             Randy.

Re: Should representation clauses be complete for each bit?

[Randy Brukardt]

"Robert A Duff" <bobduff@shell01.TheWorld.com> wrote in message 
news:wcczkk9ngxy.fsf@shell01.TheWorld.com...
...
> By the way, I find Ada's representation clauses to be at the wrong
> level of abstraction.  Why can't I just write a single line of code
> that means "put all the components in declaration order with no gaps
> in between"?

Isn't that what pragma Pack (sorry, aspect Pack) does? Even though it is 
horrible idea (see below)?

And that's (almost) always what any record declaration means (at least in 
Janus/Ada). We (almost) never have gaps between (discrete) components; they 
always fill all of the space (typically 8 or 16 bits). You could get a gap 
by compiling with time optimization on and then having alternating 8 and 16 
(or 32) bit components, but that's the only way. (The gap is caused by 
alignment concerns).

If you mean bit packing, I would object strenously. Bit packing *should* be 
hard to get, since it saps so much performance from your code. A record 
representation clause might be a bit wordy, but it is hard enough to write 
that it is clear that the programmer really wants that representation. Which 
is fine, then we'll go through the effort of giving it to him -- but 
otherwise forget it.

I don't think pragma Pack should *ever* do bit packing (with the possible 
exception of packed arrays of Boolean). It should provide the smallest 
*efficient* space, not some overly packed extremely expensive in code size 
and runtime version. I realize that is water under the dam (or is it over 
the bridge ;-), but I would be very against making a bad situation worse.

                                       Randy.

Re: Should representation clauses be complete for each bit?

[Randy Brukardt]

"Robert A Duff" <bobduff@shell01.TheWorld.com> wrote in message 
news:wcchb6fbs04.fsf@shell01.TheWorld.com...
...
> Part of my complaint is that you have to say it twice:
>
>    type Bits2 is mod 2**2;
>    pragma Assert (Bits2'Size = 2);

There is a reason that Ada has constants. ;-) And I have no idea why you are 
using an Assert here rather than specifying the Size oughtright (I always do 
that in such cases):

   Gap1_Size : constant := 2;
   type Gap1_Bits is mod 2**Gap1_Size with Size => Gap1_Size;

This gives a compile-time failure if there is something wrong with the Size, 
not a runtime one (as Assert does). And it also has the benefit of working 
(at least if we use the old syntax) on Ada 83 compilers and Ada 95 compilers 
that never implemented the goofy Ada 95 'Size rules [i.e. Janus/Ada 95].

> OK, now we have a 2-bit type.  But we have to specify 2 bits again
> in the rep clause:
>
>         Gap1 at 0 range 1..2;

            Gap1 at 0 range 1 .. Gap1_Size;

or to be even more general:

           Gap1 at 0 range Gap1_Start .. Gap1_Size - Gap1_Start + 1;

(We have a number of lines like this in Claw and other programs here.)

 I understand the complaint here, but I still think that explictly 
specifying the bit packing in this way is best. The syntax that requires 
mentioning both the low and high bits is overkill, but that has nothing to 
do with this particular issue -- it is overkill for *any* record. We really 
need an alternative shorter syntax for these lines in a record 
representation clause:

            Gap1 at 0 bit 1;

or something like that. No one ever wants to give the high bound in these 
clauses -- it's almost pointless and a real pain if it might change (note 
the most general form given above).

                       Randy.

Re: Should representation clauses be complete for each bit?

[tmoran]

>  type T is
>     record
>        ...
>        Gap1 : Bits2 := 0; -- must be zero

In Claw.Bitmaps there's a record with

    type Windows_Info is record
        ...
        Planes   : Claw.Word range 1 .. 1 := 1;

IIRC we noticed that we definitely needed the representation

        Planes      at 12 range 0 .. 15;

otherwise ObjectAda didn't leave any space, since it knew that Planes
was a constant always equal to 1.

Re: Should representation clauses be complete for each bit?

[Robert A Duff]

"Randy Brukardt" <randy@rrsoftware.com> writes:

> I would do this slightly differently (in fact we did, in Claw where we had 
> this exact problem):
>
>    type T is
>       record
>          One : Boolean;
>          Gap1 : Bits2 := 0; -- must be zero
>          Tooth : Boolean;
>          Gap2 : Bits11 := 0; -- must be zero
>          Ree : Boolean;
>       end record
>        with Predicate => T.Gap1 = 0 and T.Gap2 = 0;
>
> with the same record rep clause.
> Then the (correct) aggregates don't need to mention the gaps explicitly:
>
> with Ada.Assertions; use Ada.Assertions;
> procedure P.Main is
> --   X : T := (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0); -- OK
>     X : T := (One | Tooth | Ree => True, others =>  <>); -- OK

Hmm.  That seems reasonable, although it makes me nervous that
you might accidentally say:

    X : T := (One | Tooth => True, others =>  <>);

which evilly leaves junk in Ree.  That sort of bug is likely if you add
new components to a record.

- Bob

Re: Should representation clauses be complete for each bit?

[Randy Brukardt]

"Robert A Duff" <bobduff@shell01.TheWorld.com> wrote in message 
news:wcc62mtav52.fsf@shell01.TheWorld.com...
> "Randy Brukardt" <randy@rrsoftware.com> writes:
>
>> I would do this slightly differently (in fact we did, in Claw where we 
>> had
>> this exact problem):
>>
>>    type T is
>>       record
>>          One : Boolean;
>>          Gap1 : Bits2 := 0; -- must be zero
>>          Tooth : Boolean;
>>          Gap2 : Bits11 := 0; -- must be zero
>>          Ree : Boolean;
>>       end record
>>        with Predicate => T.Gap1 = 0 and T.Gap2 = 0;
>>
>> with the same record rep clause.
>> Then the (correct) aggregates don't need to mention the gaps explicitly:
>>
>> with Ada.Assertions; use Ada.Assertions;
>> procedure P.Main is
>> --   X : T := (One | Tooth | Ree => True, Gap1 => 0, Gap2 => 0); -- OK
>>     X : T := (One | Tooth | Ree => True, others =>  <>); -- OK
>
> Hmm.  That seems reasonable, although it makes me nervous that
> you might accidentally say:
>
>    X : T := (One | Tooth => True, others =>  <>);
>
> which evilly leaves junk in Ree.  That sort of bug is likely if you add
> new components to a record.

Ugh. There really should be a restriction or something to prevent using <> 
for uninitialized things. We have such a rule for discriminants, it would 
seem easy enough to have it for all types (admittedly, it would be 
complicated by the recursive nature for record types). It can't be very 
common that the program actually wants to write aggregates that fill the 
aggregate with junk.

                                     Randy.

Re: Should representation clauses be complete for each bit?

[okellogg]

On 23 Jul., 02:13, "Randy Brukardt" <ra...@rrsoftware.com> wrote:
> [...]
>  I understand the complaint here, but I still think that explictly
> specifying the bit packing in this way is best. The syntax that requires
> mentioning both the low and high bits is overkill, but that has nothing to
> do with this particular issue -- it is overkill for *any* record. We really
> need an alternative shorter syntax for these lines in a record
> representation clause:
>
>             Gap1 at 0 bit 1;
>
> or something like that. No one ever wants to give the high bound in these
> clauses -- it's almost pointless and a real pain if it might change (note
> the most general form given above).

So the number given after "bit" is the starting bit? I like that idea.
(Well, after all we still need to be aware of sizes, be it just to
figure out the next available starting bit.)

Oliver

Re: Should representation clauses be complete for each bit?

[Randy Brukardt]

"okellogg" <okellogg@users.sourceforge.net> wrote in message 
news:4606c5b0-7da1-43d0-a490-ba842f7621f7@hd10g2000vbb.googlegroups.com...
>On 23 Jul., 02:13, "Randy Brukardt" <ra...@rrsoftware.com> wrote:
>> [...]
>> I understand the complaint here, but I still think that explictly
>> specifying the bit packing in this way is best. The syntax that requires
>> mentioning both the low and high bits is overkill, but that has nothing 
>> to
>> do with this particular issue -- it is overkill for *any* record. We 
>> really
>> need an alternative shorter syntax for these lines in a record
>> representation clause:
>>
>> Gap1 at 0 bit 1;
>>
>> or something like that. No one ever wants to give the high bound in these
>> clauses -- it's almost pointless and a real pain if it might change (note
>> the most general form given above).
>
>So the number given after "bit" is the starting bit? I like that idea.

Right.  The big problem with this is finding the right keyword to use (I 
don't think any of the existing ones work, I looked over the list before 
posting the above).

>(Well, after all we still need to be aware of sizes, be it just to
>figure out the next available starting bit.)

True enough. If we really wanted the size indicated, we ought to do that 
directly:

 Gap1 at 0 bit 1 size 2;

because calculating it is a pain, especially when the size is a named 
constant and not a literal.

One of the largest mistakes I made in designing the intermediate code for 
Janus/Ada was copying the record representation clause too closely; the 
design should have been the same as the above, not the first and last bits 
of the record rep. clause. That's because the first and last bit design 
doesn't work for packed array indexing (everything is variable and thus you 
don't know what size code to generate), while the size of the component is 
probably a constant.

That seems true for the design of the record rep. clause as well.

But I suspect it won't get changed, because it is "insufficiently broken". 
Someone would have to make a pretty good case that there is a problem, and 
I'm not sure that can be done.

                                  Randy.

Re: Should representation clauses be complete for each bit?

[BrianG]

On 07/21/2011 11:06 AM, Robert A Duff wrote:
> Georg Bauhaus<rm.dash-bauhaus@futureapps.de>  writes:
>
>> More specifically, if the original example of "not all bits used and some
>> gaps between them" is unusual, is it so
>>
>> - when mapping to a set of hardware pins, say?
>
> Whenever I see documentation for such things, they have rectangular pictures
> showing what every bit means.  They don't have implicit gaps.  If there
> are any gaps, they are shown explicitly, as "must be zero" or "reserved
> for future hardware extensions" or whatever.
>
> My claim is that the Ada code interfacing to such a thing should be
> similarly explicit about the gaps.
>
> Otherwise, you end up with nasty bugs: one compiler just happens to
> set the gaps to zero, and you write to a file, and binary comparisons
> of those files work.  Then you port to a different compiler, and it
> puts arbitrary junk in the gaps.


It doesn't have to be a different compiler, or even a different version 
- this can happen with host/target. For instance, Windows and VxWorks 
always seem to be exact opposites on these kind of things.  Makes coding 
standards and such rather important.

BrianG
000
@gmail.com

[test email, trying to re-set-up account]