Re: [Simulavr-devel] Re: Some questions and my offer to help you

[reinhard . jessich]

On Tue, 01 Jan 2002, Theodore A. Roth wrote:

<snip>

> :)You are right this is no stopper, but I think in the loop in gdb_continue,
> :)the commands sent from gdb must be checked and executed. This is no big 
> issue.
> :)The only complicated thing could be to handle the commands correctly, while 
> we
> :)are in a running phase. I mean we must ignore the continue command $c#63 
> while
> :)we are already in gdb_continue, else we would get an endless loop and a 
> stack
> :)overflow.
> 
> I got a patch from Tor Ringstad yesterday that kinda fixes this up a 
> little. It still needs some work to do what you want though.
> 
> :)I think the decoding part in gdb_main_loop must be a separated function, 
> which
> :)can be called from gdb_continue and from gdb_main_loop.
> :)Then gdb_parse_packet must know, if gdb_continue is already executed or not.
> :)This needs an enum in AvrCore, where we store the current executed command. 
> I
> :)don't like mixing flags over different structures. AvrCore is the data
> :)structure for simulation, but it could be used to store this state. An 
> other,
> :)more separated possibility, would be to store it in a structure, which is 
> known
> :)only by gdbserver and which is the first parameter of any gdb function. This
> :)is the more object oriented solution.
> 
> So you're basically saying that the decoder part needs to be re-entrant? 
> That makes some sense. I think it's doable.
Yes, and I don't think it is complicated here.

> Threads here might make things easier, although I must admit I have an 
> aversion to threading the simulator. I might be more inclined to do it if 
> the threaded parts are not pushed down in the actual simulator part of the 
> code. For example, keeping all threading in the gdbserver.c part might be 
> easier to handle. If it can be done without threads for now, I'd like that 
> better. I do agree we need to work on this.
I don't think that we need threads. For the current problem a state is enough.
Threads make things more compliate. I know this from my daily work.

<snip>

> :)I don't think it is a good idea to extend the simulator to much. The main 
> task
> :)of the simulator is to simulate the CPU. But this as much exact as possible.
> :)It is not task of the simulater to provide complicated stimuli. The 
> simulator
> :)must be able to write its outputs and to read them. There must be a well
> :)defined interface to the simulator, so that other applications can be 
> connected.
> 
> I agree. I think this still needs to be designed. Also, there's still work 
> to be done to achieve complete simulation. The rest of the simulation 
> though, might be tightly coupled with the interface to stimuli. I've been 
> putting this off since it looks like it will be complicated. Alas, it's 
> getting to the point where it needs to be thought about. I'm open to 
> discussion here.
I will think about it and provide a description.

> :)I know, that there is a simulator for the power-pc. I don't know its 
> external
> :)interface definiton. Do you know it? Shall I have a look to it?
> 
> I've looked at some of the sims included with the gdb source. There's some 
> really complicated stuff going on there and I couldn't get a good grasp of 
> what was going on from the little time I spent looking at it. I've wish to 
> try digging through it, that's fine. If you find something interesting, 
> point me at it and I'll try to grok it.
I had a short look to the gdb sim. It looks really complicated. I think it is
not so complicate to add a new cpu. mcore looks simple, only one file.
m68hc11 is more similar to the AVR and looks also not so complicate. But
there is no documentation about it and how to add a new cpu. My feeling is,
that it is well designed (like gcc) and it can do a lot of things, but without
documentation? I think it is completely different than you approach and if we
jump now to this simulation environment, we need to start from scratch. Maybe
we can reuse the command engine. Maybe someone else can explain us the
sim and then we can dicide it again. For the moment we should keep simulavr as
it is, I think. But if you have time to investigate gdb sim?

> :)> It is possible with the extended remote protocol. It should be an easy 
> :)> hack to get simulavr to stay up.
> :)So you will investigate it?
> 
> Yeah, I try to make some time to look into it. My plate seems to be 
> filling up rather quickly right now though. ;)
If more people working on a project, more ideas come up.

> :)I like documented SW. I have seen some comments in the code of simulavr, 
> but I
> :)missed a module header. This describes in a short form, what the module 
> does.
> 
> Can you give me an example of what you missed or wanted?
At the begin of a file, the functionality of that module shall be described.
I see only a file display.h/.c. But I don't know what a display is. There
should be a brief description with a purpose and maybe some over all
description of the concepts behind. This can be done in doxygen syntax to have
it in the generated documentation. But for the first it is enough to have it
written in a normal comment. I think for the display you have documented it
somewere else, but then it sould be a not where it can be found.

In a header file for a specific source file, the interface and the purpose
of each public function shall be described. Here an example:

/**
 * This function must be called, if an UI message from any E1 link is received.
 * The message is stored in the receive buffer. The real transfer is
 * executed by LnkCntrWork. If the last message is not already transmittet, it
 * is dicarded and the new message is stored. This is possible, because UI
 * messages are unreliable.
 *
 * @param theLink number of the link from which the UI message was received
 * @param pMsg pointer to the received UI message
 * @param length length of the received UI message
 * @param offsetData offset where the data starts
 **/
EXTERN void LnkCntrUnitDataIndic( word theLink, byte * pMsg, word length
                                                         , word offsetData );

This can be parsed by doxygen and I think it is also readable for humans.

Normaly I write my C code in an object oriented manner. With such a design it
makes sense to document the interface of this "class".
It must be documented in the header, because this is what I read, if I would
like to use a "class". It shouldn't be necessary to look to the implementation.
It is better to have a short command than no command, at least the parameters
of a function must be documented.

> I do agree with having the code documented.
I comment each member of a structure, if it's name is not enough, but this
is very seldom the case.

Example:
/*
 * message header for the link controller; This sent before each message, so 
that
 * the link controller can determine what to do with a new message received from
 * a link.
 */
typedef struct iscc_msg_header_lnkcntr_s
{
   word MsgNum PACKED_DATA;             /* message number, to recognice doubled
                                         * messages
                                         */
   iscc_node_address_t Sender PACKED_DATA; /* sender node of this message
                                         */
   iscc_msg_cntrl_info_t MsgCntrlInfo PACKED_DATA;  /* to know to which receive
                                         * buffer the message must be copied;
                                         * a version information is also stored
                                         */
} iscc_msg_header_lnkcntr_t;



I comment never, what you can see in the code, but I comment what you can't see

Example:
   {
      word currentLink;
      for( currentLink = 0; currentLink < ISCC_NUM_OF_LINKS; currentLink ++ )
      {
         /* this will establish the links, if they are not established and the
          * dead timout is expired
          */
         LinkEstablish( currentLink );

         /* try to send older received messages */
         LinkRcvMsgBufferCheck( currentLink );

         /* try to send received UI messages */
         LinkRcvUiMsgBufferCheck( currentLink );
      }
   }

> Ken Restivo has shown me some output of doxygen on simulavr already. I
> thought it was a bit much to document every function in simulavr. It
> didn't seem to add anything that I couldn't do with etags/ctags and the
Sorry, I don't know etags/ctags.

> comments in the code. It just seemed to duplicate it. _But_, for
> documenting an external interface API, I think it would be great. I 
> haven't completely written doxygen off yet.
I write documents in LaTex, but if the interface is small, sometimes a well
documented header file is enough.

Regards,
   Reinhard

-- 
 Ing. Reinhard Jessich              mailto: address@hidden
 A-1190 Vienna, Goergengasse 2/2/1  phone: +43/1/3692600
 http://members.telering.at/jessich mobile: +43/664/1735439