1 #ifndef CYGONCE_KERNEL_MQUEUE_INL
2 #define CYGONCE_KERNEL_MQUEUE_INL
3 /*========================================================================
7 // Message queues implementation
9 //========================================================================
10 //####ECOSGPLCOPYRIGHTBEGIN####
11 // -------------------------------------------
12 // This file is part of eCos, the Embedded Configurable Operating System.
13 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
15 // eCos is free software; you can redistribute it and/or modify it under
16 // the terms of the GNU General Public License as published by the Free
17 // Software Foundation; either version 2 or (at your option) any later version.
19 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
20 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
21 // FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
24 // You should have received a copy of the GNU General Public License along
25 // with eCos; if not, write to the Free Software Foundation, Inc.,
26 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
28 // As a special exception, if other files instantiate templates or use macros
29 // or inline functions from this file, or you compile this file and link it
30 // with other works to produce a work based on this file, this file does not
31 // by itself cause the resulting work to be covered by the GNU General Public
32 // License. However the source code for this file must still be made available
33 // in accordance with section (3) of the GNU General Public License.
35 // This exception does not invalidate any other reasons why a work based on
36 // this file might be covered by the GNU General Public License.
38 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
39 // at http://sources.redhat.com/ecos/ecos-license/
40 // -------------------------------------------
41 //####ECOSGPLCOPYRIGHTEND####
42 //========================================================================
43 //#####DESCRIPTIONBEGIN####
45 // Author(s): jlarmour
48 // Purpose: This file provides the implementation for eCos message
50 // Description: This differs from the message boxes also supported
51 // by eCos primarily because the requirements of message
52 // queues are driven by POSIX semantics. POSIX semantics are
53 // more dynamic and therefore heavyweight than Mboxes,
54 // including prioritization, and variable sized queues and
56 // Usage: Do not include this file directly - instead
57 // #include <cyg/kernel/mqueue.hxx>
59 //####DESCRIPTIONEND####
61 //======================================================================
66 #include <pkgconf/system.h>
67 #include <pkgconf/kernel.h> // Configuration header
71 #include <stddef.h> // size_t, NULL
72 #include <cyg/infra/cyg_type.h> // Types
73 #include <cyg/kernel/mqueue.hxx> // Header for this file, just in case
74 #include <cyg/infra/cyg_ass.h> // Assertion support
75 #include <cyg/infra/cyg_trac.h> // Tracing support
76 #include <cyg/kernel/sched.hxx> // scheduler
77 #include <cyg/kernel/sched.inl> // scheduler inlines
78 #include <cyg/kernel/sema.hxx> // Cyg_Counting_Semaphore
80 #ifdef CYGPKG_ISOINFRA
81 # include <string.h> // memcpy
83 externC void * memcpy( void *, const void *, size_t );
87 // An alternative implementation based on mutexes and condition variables
88 // rather than semaphores/scheduler locking was considered. But it was
89 // not thought quite as good because it isn't driver safe. You would
90 // also have to manage explicitly what counting semaphores do for you
91 // intrinsically. Also with the mutex approach, the message queue would
92 // be locked the whole time a new entry was being filled in, or copied out
94 // It also makes the non-blocking case properly non-blocking rather than
95 // still being able to block while waiting for a mutex protecting
96 // the message queue internal structures
98 /* INLINE FUNCTIONS */
100 #ifndef CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE
101 # define CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE inline
104 //------------------------------------------------------------------------
106 CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE cyg_bool
107 Cyg_Mqueue::check_this( cyg_assert_class_zeal zeal ) const
109 if (zeal != cyg_none) {
110 CYG_CHECK_DATA_PTRC(this); // extreme paranoia
112 #ifdef CYGDBG_USE_ASSERTS
113 if ( qlen <= 0 || msgsize <= 0 )
117 if ( queuespacesize < sizeof(struct qentry)+1 )
120 CYG_CHECK_DATA_PTRC(queuespace);
121 CYG_CHECK_FUNC_PTRC(free_fn);
123 // prevent pre-emption through this. Not so bad since
124 // this is only a diagnostic function
125 Cyg_Scheduler::lock();
128 CYG_CHECK_DATA_PTRC(q);
129 if (NULL != freelist)
130 CYG_CHECK_DATA_PTRC(freelist);
131 if (NULL != callback)
132 CYG_CHECK_FUNC_PTRC(callback);
134 // check each queue entry
135 long msgs=0, busymsgs=0;
136 unsigned int oldprio=0;
140 oldprio = q->priority;
141 for ( qtmp=q; NULL != qtmp; qtmp=qtmp->next ) {
142 if ( NULL != qtmp->next )
143 CYG_CHECK_DATA_PTRC( qtmp->next );
145 // queue should be priority ordered
146 if ( qtmp->priority > oldprio )
148 oldprio = qtmp->priority;
150 #ifdef CYGDBG_USE_ASSERTS
153 if ( qtmp->buflen > msgsize )
164 // check that number of used and unused messages == q length
165 for ( qtmp=freelist; NULL != qtmp; qtmp=qtmp->next ) {
166 if ( NULL != qtmp->next )
167 CYG_CHECK_DATA_PTRC( qtmp->next );
174 #ifdef CYGDBG_USE_ASSERTS
175 // and sum of all messages should be the total q length
176 if ( qlen != (msgs+freemsgs+busymsgs) )
180 Cyg_Scheduler::unlock();
183 return true; // object OK
185 Cyg_Scheduler::unlock();
186 return false; // object fubar'd
189 //------------------------------------------------------------------------
191 CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE
192 Cyg_Mqueue::Cyg_Mqueue( long maxmsgs, long maxmsgsize,
193 qalloc_fn_t qalloc, qfree_fn_t qfree, qerr_t *err )
194 : putsem(maxmsgs), getsem(0)
196 CYG_REPORT_FUNCTION();
197 CYG_REPORT_FUNCARG5( "maxmsgs=%ld, maxmsgsize=%ld, qalloc=%08x, "
198 "qfree=%08x, &err=%08x", maxmsgs, maxmsgsize,
200 CYG_PRECONDITIONC( (maxmsgs > 0) && (maxmsgsize > 0) );
201 CYG_CHECK_DATA_PTRC( err );
202 CYG_CHECK_FUNC_PTRC( qalloc );
203 CYG_CHECK_FUNC_PTRC( qfree );
205 // mem to allocate for entire queue size. Also wants to be rounded
206 // up so that the structs are aligned.
207 const long addralign = sizeof(void *) - 1;
208 long entrysize = (sizeof(struct qentry) + maxmsgsize + addralign)
211 queuespacesize = entrysize * maxmsgs;
212 queuespace = qalloc( queuespacesize );
214 if (NULL == queuespace) {
223 for ( i=0, qtmp=(struct qentry *)queuespace;
225 i++, qtmp=qtmp->next ) {
227 qtmp->next = (struct qentry *)((char *)qtmp + entrysize);
230 freelist = (struct qentry *)queuespace;
232 // set the last entry in the chain to the start to make the list circular
238 #ifdef CYGDBG_USE_ASSERTS
240 msgsize = maxmsgsize;
245 // object should be valid now
251 //------------------------------------------------------------------------
253 CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE
254 Cyg_Mqueue::~Cyg_Mqueue()
256 CYG_REPORT_FUNCTION();
258 if ( NULL != queuespace ) {
259 // object should be valid if queuespace was successfully allocated
261 free_fn( queuespace, queuespacesize );
264 #ifdef CYGDBG_USE_ASSERTS
265 qlen = msgsize = 0; // deliberately make it fail check_this() if used
271 //------------------------------------------------------------------------
273 // put() copies len bytes of *buf into the queue at priority prio
274 CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE Cyg_Mqueue::qerr_t
275 Cyg_Mqueue::put( const char *buf, size_t len, unsigned int prio, bool block
276 #ifdef CYGFUN_KERNEL_THREADS_TIMER
277 , cyg_tick_count timeout
281 CYG_REPORT_FUNCTYPE( "err=%d");
282 CYG_REPORT_FUNCARG4( "buf=%08x, len=%ld, prio=%ud, block=%d",
283 buf, len, prio, block==true );
284 CYG_CHECK_DATA_PTRC( buf );
286 CYG_PRECONDITIONC( len <= (size_t)msgsize );
289 struct qentry *qtmp, *qent;
291 // wait till a freelist entry is available
292 if ( true == block ) {
293 #ifdef CYGFUN_KERNEL_THREADS_TIMER
295 if ( false == putsem.wait(timeout) ) {
302 if ( false == putsem.wait() ) {
307 if ( false == putsem.trywait() ) {
313 // prevent preemption when fiddling with important members
314 Cyg_Scheduler::lock();
318 // get a queue entry from the freelist
319 // don't need to check the freelist - the semaphore tells us there's
320 // definitely a usable non-busy one there. It's just a question of
323 if (!freelist->busy) { // fast-track common case
325 freelist = freelist->next;
327 for ( qtmp=freelist; qtmp->next->busy; qtmp=qtmp->next )
328 CYG_EMPTY_STATEMENT; // skip through
330 qtmp->next = qent->next;
333 // now put it in place in q
339 struct qentry **qentp;
341 // insert into queue according to prio
342 for ( qentp=&q; NULL != *qentp; qentp = &((*qentp)->next) ) {
343 if ((*qentp)->priority < prio)
351 qent->priority = prio; // have to set this now so when the sched is
352 // unlocked, other qent's can be added in the
354 qent->busy = true; // let things know this entry should be ignored until
355 // it's finished having its data copied
357 // unlock the scheduler, and potentially switch threads, but
358 // that's okay now. We don't want it locked for the expensive memcpy
359 Cyg_Scheduler::unlock();
362 memcpy( qent->buf(), buf, len );
364 // make available now - setting non-atomically is alright if you think
365 // about it - the only thing that matters is that it's completed before
369 // if we have to notify someone, we only do it if no-one's already
370 // sitting waiting for a message to appear, AND if it's a transition
371 // from empty to non-empty
373 if ( callback != NULL && !getsem.waiting() && (0 == getsem.peek()) ) {
375 callback( *this, callback_data );
383 CYG_REPORT_RETVAL(err);
385 } // Cyg_Mqueue::put()
387 //------------------------------------------------------------------------
390 // get() returns the oldest highest priority message in the queue in *buf
391 // and sets *prio to the priority (if prio is non-NULL) and *len to the
392 // actual message size
394 CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE Cyg_Mqueue::qerr_t
395 Cyg_Mqueue::get( char *buf, size_t *len, unsigned int *prio, bool block
396 #ifdef CYGFUN_KERNEL_THREADS_TIMER
397 , cyg_tick_count timeout
401 CYG_REPORT_FUNCTYPE( "err=%d");
402 CYG_REPORT_FUNCARG4( "buf=%08x, len=%08x, prio=%08x, block=%d",
403 buf, len, prio, block==true );
404 CYG_CHECK_DATA_PTRC( buf );
405 CYG_CHECK_DATA_PTRC( len );
407 CYG_CHECK_DATA_PTRC( prio );
413 // wait till a q entry is available
414 if ( true == block ) {
415 #ifdef CYGFUN_KERNEL_THREADS_TIMER
417 if ( false == getsem.wait(timeout) ) {
424 if ( false == getsem.wait() ) {
429 if ( false == getsem.trywait() ) {
435 // prevent preemption when fiddling with important members
437 Cyg_Scheduler::lock();
439 // don't need to check the q - the semaphore tells us there's
440 // definitely a usable non-busy one there. It's just a question of
443 if ( !q->busy ) { // fast-track the common case
449 for ( qtmp=q; qtmp->next->busy; qtmp=qtmp->next )
450 CYG_EMPTY_STATEMENT; // skip through
453 qtmp->next = qent->next;
456 // now stick at front of freelist, but marked busy
457 qent->next = freelist;
460 qent->busy = true; // don't let it truly be part of the freelist just yet
461 // till the data is copied out
463 // unlock the scheduler, and potentially switch threads, but
464 // that's okay now. We don't want it locked for the expensive memcpy
465 Cyg_Scheduler::unlock();
469 *prio = qent->priority;
470 memcpy( buf, qent->buf(), *len );
472 // make available now - setting non-atomically is alright if you think
473 // about it - the only thing that matters is that it's completed before
483 CYG_REPORT_RETVAL(err);
486 } // Cyg_Mqueue::get()
488 //------------------------------------------------------------------------
490 // count() returns the number of messages in the queue
494 CYG_REPORT_FUNCTYPE("curmsgs=%d");
496 long curmsgs = (long)getsem.peek();
498 CYG_REPORT_RETVAL(curmsgs);
500 } // Cyg_Mqueue::count()
502 //------------------------------------------------------------------------
505 // Supply a callback function to call (with the supplied data argument)
506 // when the queue goes from empty to non-empty (unless someone's already
507 // doing a get()). This returns the old callback_fn, and if olddata is
508 // non-NULL sets it to the old data (yes, really!)
509 CYGPRI_KERNEL_SYNCH_MQUEUE_INLINE Cyg_Mqueue::callback_fn_t
510 Cyg_Mqueue::setnotify( callback_fn_t callback_fn, CYG_ADDRWORD data,
511 CYG_ADDRWORD *olddata)
513 CYG_REPORT_FUNCTYPE("old callback=%08x");
514 CYG_REPORT_FUNCARG3XV( callback_fn, data, olddata );
515 if ( NULL != callback_fn )
516 CYG_CHECK_FUNC_PTRC( callback_fn );
518 CYG_CHECK_DATA_PTRC( olddata );
522 // Need to prevent preemption for accessing common structures
523 // Just locking the scheduler has the least overhead
524 Cyg_Scheduler::lock();
528 *olddata = callback_data;
530 callback_data = data;
531 callback = callback_fn;
533 Cyg_Scheduler::unlock();
535 CYG_REPORT_RETVAL(oldfn);
539 //------------------------------------------------------------------------
541 #endif /* CYGONCE_KERNEL_MQUEUE_INL multiple inclusion protection */