An initial proposal for review

[Joel Sherrill]

Madhusudan C.S wrote:
>
>     On a general note, I'm not sure that the object-oriented terminology
>     (class, abstract class, methods) is strictly correct in the context of
>     RTEMS development. Sure OO ideas are prevalent in RTEMS, but there
>     is no
>     innate support for those concepts from the development tools.
>
>
> Exactly while I was going through the code, I felt the same too. I 
> completely agree that the use of these terminologies is not very apt 
> in RTEMS context, but the terms class and methods are used in the 
> project ideas page in the wiki too. But definitely the use of the term 
> abstract class wont fit in RTEMS development context. Can you please 
> suggest me what are the better terms that can replace these terms.
See separate post.
>
>     Looks good, though... well done !
>
>
> Thanks again. But one request. You have done a thorough review. But 
> you have not commented on any of the technical parts as such. Is my 
> proposal clear technically. Is this what you(RTEMS) are expecting from 
> a student who works on this project. Since many parts are taken from 
> the wiki description, what is your take on this? Does this proposal 
> project that I have done enough work on RTEMS and code structure. As I 
> was away for a while due to some problems, I was not able to do lot of 
> discussion with you people which I had planned, before coming up with 
> the proposal. So please comment on the technical feasibilities too.
>
I am overwhelmed this morning.  Technical comments:

+ "The second variant converts the POSIX standard timespec structure 
into a single field 64-bit unsigned integer making the math operations 
on the timestamps more fast and reliable." isn't technically the goal -- 
it is close.  How about this wording:

The second variant uses a 64-bit unsigned integer representing 
nanoseconds since the POSIX epoch.  This will make the timestamp math 
faster on many target architecture

Also this is something that I do not believe can be selected at application
configuration time.  I think it is an RTEMS compile time option so
you can save space by not mentioning confdefs.h at all.  You are using
a "configure time option to direct conditional compilation"

It is even possible that you might do something like have a score timestamp
that includes cpuopts.h and then conditionally includes implementation A or
implementation B.  Or the Makefile.am could pick which implementation to
compile and appropriate headers to install.   Correcting and going light on
this descrtption will help you technically and on character counts.
> Also my friends who did a non-technical review for me said that I have 
> used too many "I"s. They asked me to keep this proposal neutral as 
> much as possible. Can you please give your suggestion on this?
>
Oh are they an English teacher? :-D

But the friends are right in that it is bad form in technical 
proposals.  You can use
phrases like "this project" to be neutral though. 

- This project consists of...
- At the conclusion of this project, we ...
- Phase 3 of the project concludes...

Also saying things like "design phase", "implementation phase"... 
documentation phase
and test phase can help avoid I.

> Most important thing is that the proposal is now nearly 11,000 
> characters, but Google has imposed a restriction of 7500 Characters. 
> So I am struggling a lot to cut down the proposal by 3,500 characters. 
> Can you please tell me which part of the proposal needs heavy tailoring??
>
One trick is to use abbreviations.  I don't know how many times "Score 
Timestamp"
is used but making it "ST" after the first reference will help.

Also shorter simpler words sometimes helps.

nanoseconds -> nsecs...

But mostly you need to get away from lengthy prepositional phrases.  My
dissertation was bad about saying XXX of the YYY where I could have
said YYY XXX ... if that makes sense... of the.. is often a junk type 
phrase.

Consider this sentence from the Project Details:

"When nanosecond granularity was added to RTEMS timestamps in version 
4.8.0 and above, an immediate option was to use POSIX specified struct 
timespec containing two fields of 32-bits data types as a data 
structure. But performing math operations on struct timespec has been 
proved to be very slow on many of the target platforms supported by 
RTEMS. So the idea of this project is to provide a 64-bits timestamp 
support conditionally."

When nanosecond granularity was added to RTEMS timestamps in version 
4.8.0 and above, an immediate option was to use POSIX specified struct 
timespec containing two fields of 32-bits data types as a data 
structure. But performing math operations on struct timespec has been 
proved to be very slow on many of the target platforms supported by 
RTEMS. So the idea of this project is to provide a 64-bits timestamp 
support conditionally.

Rough cut at a shorter version since your audience knows some background:

Nanosecond timestamps currently use POSIX struct timespec.
Math operations on struct timespec is computationally expensive.
This project will implement a 64-bit timestamp which is more
efficient on many targets. Individual targets will be able to select the
implementation that is more efficient for them.

A bit shorter... another example:

"Since ScoreTimestamp is an abstract class, the core part of this 
project comes into picture now as a second implementation of this class."

ST is an abstract class with two target selectable implementations.

Another wordy place is.. "I would again perform verification of all the test
cases in the same manner considered earlier."

How about: "Verification testing must be repeated."

This same paragraph is long because it repeats the details of the
phase.  Just say something like "upon completion of the implementation
phase, "

This is last but not least... I think your benefits section is good.
Try to make sure you don't repeat details from the description
unnecessarily.

I don't think example code will be needed since it is used completely
in RTEMS itself and you will do 100% testing of it both functional
and performance using the RTEMS test suites.

Phases could all start with resume like phrases which start with a verb.

"Work with.." "Analyze ..."

That eliminates garbage phrases like "In this phase I will" which
helps on the character count.

I am not being too picky.. overall it is very good.. just needs
tightening to loose 3500 characters. :-D
>
>
> -- 
> Thanks and regards,
> Madhusudan.C.S
>


-- 
Joel Sherrill, Ph.D.             Director of Research & Development
joel.sherrill at OARcorp.com        On-Line Applications Research
Ask me about RTEMS: a free RTOS  Huntsville AL 35805
   Support Available             (256) 722-9985