XC documentation problems

[carveone]

As an introduction to the xmos processors I decided to start with the XMOS "Programming in XC" pdf file available from the xmos website.

As a somewhat pedantic QA type person I think there are a number of issues with the documentation that I thought I'd raise here in case I'm either misunderstanding the docs or there are actually errors.

Here's a few of the several I picked up on a first reading:

Page 3:

1.2.1 Constants

In C, 'x' is not a char, it's an int.


Page 25.

Suddenly "in port" and "out port" are now "port". It isn't adequately explained how "in port" can be referred to as "port" and what happens. Is a "port" in or out?


Page 25:

putbyte(rxByte >> 24)

Sure. Except that rxByte is signed. This is a no-no in C and always has been. Right shifting signed quantities can result in highly unexpected results.


Page 45:

At various points in the docs it is explained that a portcounter is an unsigned 16 bit quantity. However this page and several others store it in a signed 32 bit int and increment it. In my humble opinion this cannot possibly work.

When the timers were explained it was clear that the 32 bit unsigned quantity stored would perform as expected when stored in a 32 bit unsigned int even when incrementing that int would cause an overflow.


Page 48:

for (int cols =0; cols <320; cols ++) {
time +=30;
c :> x;
DTMG @ time <: 1; // strobe high
DATA @ time <: x; // pixel 0


The docs say that the DTMG write will block until the next rising edge, ie: at time+1/2. So how will the DATA write occur on time?

That'll do for now :-)

[segher]

putbyte(rxByte >> 24)

Sure. Except that rxByte is signed. This is a no-no in C and always has been. Right shifting signed quantities can result in highly unexpected results.

See C99, 6.5.7/5.

Right shifting positive values is perfectly well-defined in C. Right shifting negative numbers
is implementation-defined; so doing that is not fully portable, but in practice every compiler
nowadays uses sign extension for it (all the world is two's complement).

[jason]

Thanks for the feedback carveone, I shall pass on your comments to the documentation team.

[carveone]

Thanks Jason. I tried to post directly to the XMOS site but wasn't allowed. I thought posting to an open forum would get my concerns out there. Plus I haven't any previous experience with the XMOS processors.

Segher. I'd agree with you up to a point. I'm not really saying the result is undefined, I'm just saying it's bad practice to set yourself up with such an unnecessary pitfall. "The Practice of Programming" book (cowritten by Kernigan) advised strenuously against it and that's mainly where I was coming from.

putbyte(rxByte >> 24)

In the example I'd cited, the upper 24 bits are now unpredictably all 1s or all 0s. I'd much prefer:

putbyte((rxByte >> 24) & 0xFF)

which kinda says to the next poor guy reading your code: "Look, I'm only interested in the 8 bits here, and now you can safely do a comparison against another value".

[segher]

I would argue this is at exactly the same level as your program depending on a certain
(minimum) size for ints (which it _also_ does, btw :-) ). And almost every realistic program
does that.

Instead of the explicit and with 0xff (there is an implicit one already), it probably is
better to make the variable unsigned. In general, anything that is treated as a bitpattern
instead of as a number should be unsigned.

So yeah, I agree with you on the dangers of signed numbers; just not that this is particularly
bad case.


Segher

[jason]

Which part of the XMOS site were you trying to post to?

[aleonard]

One thing I'd like to see in the documentation is an explanation of the runtime exception codes produced by the dev tools. (such as ET_ILLEGAL_RESOURCE). It would be nice for new users (such as myself) to be able to look up the codes and see what they mean / what types of scenarios trigger them. This would help in understanding what's going on and locating the problem.

Just something to add to the wish-list. I haven't been able to find this in the documentation if it already exists.

[segher]

The exception codes are explained in "The XMOS XS1 Architecture",
in the very last section.

[aleonard]

Ah, great. Thanks for the info!