Subject:
|
NQC API for the new Swan firmware
|
Newsgroups:
|
lugnet.robotics.rcx.nqc
|
Date:
|
Tue, 11 Jan 2005 16:59:14 GMT
|
Viewed:
|
5713 times
|
| |
|
|
I am working feverishly on updates to NQC which will include extensions to the
built-in API in support of Dick Swan's new firmware. My intent is to be
consistent with the existing NQC API. However, there are some issues I am
debating and I would like to get a lot of input from NQC users.
1. NQC historically defines constants using all caps and underscores.
SERIAL_PACKET_DEFAULT, SENSOR_MODE_RAW, etc...
There are a number of new constants for the Swan firmware. I'm inclined to
follow the existing naming pattern. So what Dick has written as
kSystemOpcodesPerTimeslice
I might instead use
SYS_OPCODES_PER_TIMESLICE
or something like that. I'd prefer to not use a mixture of naming conventions.
What do NQC users think?
2. NQC has typically defined for sources a Value function which reads the value
of a source and a Set procedure (void function) which does not return a value
but is used to set the value of the source. For instance, the UART API defines
#define SerialPacket() @(0x210010)
#define SerialComm() @(0x210011)
__nolist void SetSerialPacket(const int &v) { ... }
__nolist void SetSerialComm(const int &v) { ... }
In some cases this is necessary since the source is read only and a separate
opcode is used to write to the source such as with the Global Output Status
source. Sources which can be written directly, such as the UART source, can be
accessed using NQC like this:
SerialPacket() = SERIAL_PACKET_DEFAULT;
SetSerialPacket(SERIAL_PACKET_DEFAULT);
The code generated here is:
011 set SerSetting(16), 0 05 21 10 02 00 00
017 set SerSetting(16), 0 05 21 10 02 00 00
As you can see the two lines result in identical code.
So my issue is whether or not to continue the general pattern in NQC of defining
a set/get pair for each source. I slavishly followed this pattern when I
developed the Spybot API so there are a lot of pairs such as
#define PingInterval() PingControl(1)
__nolist void SetPingInterval(const int &i) { ... }
even though it is perfectly fine to just write
x = PingInterval();
PingInterval() = 0;
And in cases like this where the source is combined with a specific index (like
some UART source/index combinations and like all of the new Swan System source
and index combinations) it would be possible to define the value function as if
it were simply a variable which could be either set or read using syntax like
x = PingInterval;
PingInterval = 0;
And for the new Swan System source I could define the API like I did for the
Spybot with a pair of get/set functions
#define MotorTransitionDelay() System(SYS_MOTOR_TRANSITION)
__nolist void SetMotorTransitionDelay(const int &v) { ... }
or I could define the API as variables
#define MotorTransitionDelay System(SYS_MOTOR_TRANSITION)
Would you rather write code like this?
PingInterval = 0;
MotorTransitionDelay = 50;
Or would you rather write code like this?
SetPingInterval(0);
SetMotorTransitionDelay(50);
What would all you NQC users think if I moved all the SetXXX API functions in
those cases where the source is directly writable into a new #ifdef section of
the API which would break existing code that used those SetXXX API functions and
removed empty parenthesis pairs as well? Something like:
#ifdef __OLD_FUNCTION_SYNTAX
#define SerialPacket() @(0x210010)
#define SerialComm() @(0x210011)
__nolist void SetSerialPacket(const int &v) { ... }
__nolist void SetSerialComm(const int &v) { ... }
#else
#define SerialPacket @(0x210010)
#define SerialComm @(0x210011)
#endif
Then for the new Swan API I would not define SetXXX functions or use "()"
syntax.
To compile existing code users would need to either change their code to use the
modified syntax or add a
#define __OLD_FUNCTION_SYNTAX
to each of their programs. Or if they wanted to always use the deprecated
syntax they could add a
-D__OLD_FUNCTION_SYNTAX
to the NQC Compiler command line options in the Preferences dialog. If I took
this approach I would also modifiy BricxCC so that it would no longer syntax
highlight or code complete or have context sensitive help for the deprecated
items.
The alternative is to leave things the way they are (perhaps the best idea) and
follow the existing pattern even though it results in a pair of functions where
one variable would do fine. I'm having a very hard time deciding on which
course to take.
Thanks for your input
John Hansen
|
|
Message has 1 Reply:
 | | Re: NQC API for the new Swan firmware
|
| (...) I would in this case prefer the second - I actually use a "kMyNamedConstant" convention in my code, and find it very nice to have the API constants very easily seperable from my constants. (...) Again, personally I would prefer that, as it (...) (20 years ago, 11-Jan-05, to lugnet.robotics.rcx.nqc)
|
2 Messages in This Thread:
 
- Entire Thread on One Page:
- Nested:
All | Brief | Compact | Dots
Linear:
All | Brief | Compact
|
|
|
|
