Re: [Accellera:itc] IM324: Support one-time callbacks and multiple callbacks

Per,

Thanks for the writeup of this.

A few comments embedded (prefixed w/ johnS:) ...

Per Bojsen wrote:
> Hi,
>
> Here's my attempt at capturing what we talked about at the last few
> meetings. I took Amy's latest proposal from 3/3/2010 and modified it
> to include notify pipe handles and multiple callbacks:
>
> The following is a function declaration for notification callback
> functions that
> are used to notify the C side that an operation is possible on an input
> or output
> transaction pipe.
>
> typedef void (*scemi_pipe_notify_callback)(
> void *context ); // input: C model context
>
> The following is a type declaration of the notify callback handles.
>
> typedef <implementation defined type> scemi_pipe_notify_handle;

johnS:
Why is the handle not simply a 'void *' ? The implementation defined
type can be simply concealed in the implementation. An
opaque void * pointer should be sufficient at the application
level.

Also, void * is what we now use for pipe handles which have
similar semantics so it would be more consistent to
use this for callback handles as well.

>
> The notify callback handle type is opaque and the underlying type is
> implementation defined.

johnS:
Yes, on this we agree.

>
> All notification callbacks must be registered using the following call:
>
> scemi_pipe_notify_handle scemi_pipe_set_notify_callback(
> void *pipe_handle, // input: pipe handle
> scemi_pipe_notify_callback notify_callback,
> // input: notify callback function
> void *notify_context, // input: notify context
> int when = 0 // input: notify condition
> );
>
> Note the following properties:
>
> * pipe_handle - the handle identifying the specific pipe as
> derived from the unique combination of the HDL scope and the pipe ID
> (see section 0)
>
> * notify_callback - the name of the user callback function being
> registered.
>
> * notify_context - the user defined context object to be passed
> to the function whenever it is called
>
> * when - the user defined notify condition.
>
> When conditions:
>
> * 0: Static and persistent call back; callback condition
> determined by infrastructure based on the mode of operation.
>
> * N > 0: Dynamic and one-time callback; callback condition
> specified by the application per callback registration.
> . For input pipe: call back when scemi_pipe_c_can_send() >= N.
> . For output pipe: call back when
> sceni_pipe_c_can_receive() >= N.

johnS:
This 'N' argument is still a little goofy to me.

We're overloading persistence vs. non-persistence with
a callback threshold.

I suggest that we just have 0 be persistent and 1 be non-persistent
for now. If we need more complex usage down the road we can
expand this.

>
> The return value of scemi_pipe_set_notify_callback is a notify callback
> handle
> that uniquely identifies the callback. Any number of callbacks can be
> registered for each pipe. On notify events, if more than one callback is
> eligible to be called (as determined by the when argument), they eligible
> callbacks will be called in the order of registration.
>
> If a callback modifies the pipe state in any way, e.g., by removing
> elements
> from the pipe, any downstream callbacks will see the effect of this
> operation.

johnS:
Yes, very well stated.

>
> This handle can be used to remove a
> callback at any time using the following function:
>
> bool scemi_pipe_clear_notify_callback(
> scemi_notify_handle notify_handle // input: notify callback handle
> );
>
> [Note: I don't think bool is a valid C type except in very recent C
> versions but we can adjust that.]
>
> The scemi_pipe_clear_notify_callback() returns true if the notify callback
> identified by the notify_handle argument was successfully removed. It
> returns
> false, otherwise. Those conditions include:
>
> * The notify_handle value is not a value returned by a previous
> scemi_pipe_set_notify_callback() call.
>
> * The callback was already removed by a prior call of
> scemi_pipe_clear_notify_callback().
>
> * The callback was registered with a when value greater than 0 and the
> callback has expired and been removed by the infrastructure.

johnS:
I suggest we do not do error handling with a return argument
for this call alone.

This is inconsistent with what we do for all the other calls
which is to rely on the SCE-MI error handling facility.

I think we can make the return type 'void' in this case and
defer errors to the error handling facility.

>
> The following call can be used to retrieve a notify context object for a
> given
> notify callback:
>
> void *scemi_pipe_get_notify_context( // return: notify context object
> pointer
> scemi_pipe_notify_handle notify_handle ); // input: notify handle
>

johnS:
This looks good.

> *******
>
> The following example shows how dynamic callback can be used to
> implement the blocking send function on top of the non-blocking send
> function:
>
> static void notify_ok_to_send_or_receive(
> void *context ){ // input: notify context
> sc_event *me = (sc_event *)context;
> me->notify();
> }
>
> void scemi_pipe_c_send(
> void *pipe_handle, // input: pipe handle
> int num_elements, // input: #elements to be written
> const svBitVecVal *data, // input: data
> svBit eom ) // input: end-of-message marker flag
> {
> int byte_offset = 0;
> int elements_sent;
> int pipe_depth = scemi_pipe_get_depth(pipe_handle);
> while( num_elements ){
> elements_sent = scemi_pipe_c_try_send(pipe_handle, byte_offset,
> num_elements, data, eom );
> byte_offset += elements_sent * scemi_pipe_get_bytes_per_element(
> pipe_handle );
> num_elements -= elements_sent;
> if(num_elements > 0){
> int N = (num_elements > pipe_depth)?pipe_depth:num_elements;
> if( ok_to_send == NULL ) ok_to_send = new sc_event;
> scemi_pipe_set_notify_callback(pipe_handle,
> notify_ok_to_send_or_receive, ok_to_send, N);
> wait( *ok_to_send );
> }
> }
> }

johnS:
Very good Per. I will update IM 319 accordingly once we
fully agree on this proposal.

-- johnS
<eom>

>
> Thanks,
> Per
>
>

-- 
This email may contain material that is confidential, privileged
and/or attorney work product for the sole use of the intended
recipient.  Any review, reliance or distribution by others or
forwarding without express permission        /\
is strictly prohibited. If you are     /\   |  \
not the intended recipient please     |  \ /   |
contact the sender and delete        /    \     \
all copies.                      /\_/  K2  \_    \_
______________________________/\/            \     \
John Stickley                   \             \     \
Mgr., Acceleration Methodologies \             \________________
Mentor Graphics - MED             \_
                                    \   john_stickley@mentor.com
                                     \     Phone: (201) 467-4385
________________________________________________________________
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.