base/include/rtai_scb.h File Reference

---

Detailed Description

SCB stand for Shared (memory) Circular Buffer.

It is a non blocking implementation for just a single writer (producer) and reader (consumer) and, under such a constraint, it can be a specific substitute for RTAI mailboxes. There are other constraints that must be satisfied so it cannot be a general substitute for the more flexible RTAI mailboxes. In fact it provides just functions corresponding to RTAI mailboxes non blocking atomic send/receive of messages, i.e. the equivalents of rt_mbx_send_if and rt_mbx_receive_if. Moreover the circular buffer size must be >= to the largest message to be sent/received. Thus sending/receiving a message either succeeds of fails. However thanks to the use of shared memory it should be more efficient than mailboxes in atomic exchanges of messages from kernel to user space. So it is a good candidate for supporting drivers development.

Author:

Paolo Mantegazza

Note:

Copyright © 2004 Paolo Mantegazza <mantegazza@aero.polimi.it>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Definition in file rtai_scb.h.#include <rtai_shm.h>
#include <asm/rtai_atomic.h>

Include dependency graph for rtai_scb.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines
#define	SCB   ((void *)(scb))
#define	SIZE   ((volatile int *)scb)[-3]
#define	FBYTE   ((volatile int *)scb)[-2]
#define	LBYTE   ((volatile int *)scb)[-1]
#define	HDRSIZ   (3*sizeof(int))
Functions
void *	rt_scb_init (unsigned long name, int size, unsigned long suprt)
	Allocate and initialize a shared memory circular buffer.
int	rt_scb_delete (unsigned long name)
	Free a shared memory circular buffer.
int	rt_scb_bytes (void *scb)
	Get the number of bytes avaiable in a shared memory circular buffer.
int	rt_scb_get (void *scb, void *msg, int msg_size)
	Gets (receives) a message, only if the whole message can be passed all at once.
int	rt_scb_evdrp (void *scb, void *msg, int msg_size)
	eavedrops a message.
int	rt_scb_put (void *scb, void *msg, int msg_size)
	Puts (sends) a message, only if the whole message can be passed all at once.

---

Define Documentation

#define FBYTE   ((volatile int *)scb)[-2]

Definition at line 47 of file rtai_scb.h. Referenced by rt_scb_bytes(), rt_scb_evdrp(), rt_scb_get(), and rt_scb_put().

#define HDRSIZ   (3*sizeof(int))

Definition at line 49 of file rtai_scb.h. Referenced by rt_scb_init().

#define LBYTE   ((volatile int *)scb)[-1]

Definition at line 48 of file rtai_scb.h. Referenced by rt_scb_bytes(), rt_scb_evdrp(), rt_scb_get(), and rt_scb_put().

#define SCB   ((void *)(scb))

Definition at line 45 of file rtai_scb.h. Referenced by rt_scb_evdrp(), rt_scb_get(), and rt_scb_put().

#define SIZE   ((volatile int *)scb)[-3]

Definition at line 46 of file rtai_scb.h. Referenced by rt_scb_bytes(), rt_scb_evdrp(), rt_scb_get(), and rt_scb_put().

---

Function Documentation

int rt_scb_bytes (  void *  scb  )  [inline]

Get the number of bytes avaiable in a shared memory circular buffer. For internal use only. rt_scb_bytes is used to get the number of bytes avaiable in a shared memory circular buffer. Parameters: scb  is the pointer handle returned when the buffer was initted. Returns: the available number of bytes. Definition at line 145 of file rtai_scb.h. References FBYTE, LBYTE, and SIZE.

int rt_scb_delete (  unsigned long  name  )  [inline]

Free a shared memory circular buffer. For internal use only. rt_scb_delete is used to release a previously allocated shared memory circular buffer. Parameters: name  is the unsigned long identifier used when the buffer was allocated; Analogously to what done by all the named allocation functions the freeing calls have just the effect of decrementing a usage count, unmapping any user space shared memory being freed, till the last is done, as that is the one the really frees any allocated memory. Returns: the size of the succesfully freed buffer, 0 on failure. Do not call this function if you provided your own memory to the circular buffer. Definition at line 126 of file rtai_scb.h. References rt_shm_free(). Here is the call graph for this function:

int rt_scb_evdrp (  void *  scb, void *  msg, int  msg_size )  [inline]

eavedrops a message. rt_scb_evdrp atomically spies the message msg of msg_size bytes from the shared memory circular buffer scb. It returns immediately and the caller is never blocked. It is like rt_scb_get but leaves the message in the shared memory circular buffer. Returns: On success, i.e. message got, it returns 0, msg_size on failure. Definition at line 195 of file rtai_scb.h. References FBYTE, LBYTE, SCB, and SIZE.

int rt_scb_get (  void *  scb, void *  msg, int  msg_size )  [inline]

Gets (receives) a message, only if the whole message can be passed all at once. rt_scb_get tries to atomically receive the message msg of msg_size bytes from the shared memory circular buffer scb. It returns immediately and the caller is never blocked. Returns: On success, i.e. message got, it returns 0, msg_size on failure. Definition at line 163 of file rtai_scb.h. References FBYTE, LBYTE, SCB, and SIZE.

void* rt_scb_init (  unsigned long  name, int  size, unsigned long  suprt )  [inline]

Allocate and initialize a shared memory circular buffer. For internal use only. rt_scb_init is used to allocate and initialize a shared memory circular buffer. Parameters: name  is an unsigned long identifier; size  is the size of the circular buffer. suprt  is the kernel allocation method to be used, it can be: USE_VMALLOC, use vmalloc; USE_GFP_KERNEL, use kmalloc with GFP_KERNEL; USE_GFP_ATOMIC, use kmalloc with GFP_ATOMIC; USE_GFP_DMA, use kmalloc with GFP_DMA. for use in kernel only applications the user can use "suprt" to pass the address of any memory area (s)he has allocated on her/his own. Since name can be a clumsy identifier, services are provided to convert 6 characters identifiers to unsigned long, and vice versa. See also: nam2num() and num2nam(). It must be remarked that only the very first call does a real allocation, any following call to allocate with the same name from anywhere will just increase the usage count and maps the circular buffer to the user space, or return the related pointer to the already allocated buffer in kernel space. In any case the functions return a pointer to the circular buffer, appropriately mapped to the memory space in use. So if one is really sure that the named circular buffer has been initted already parameters size and suprt are not used and can be assigned any value. Returns: a valid address on succes, 0 on failure. Definition at line 90 of file rtai_scb.h. References atomic_cmpxchg, HDRSIZ, and rt_shm_alloc.

int rt_scb_put (  void *  scb, void *  msg, int  msg_size )  [inline]

Puts (sends) a message, only if the whole message can be passed all at once. rt_scb_put tries to atomically send the message msg of msg_size bytes to the shared memory circular buffer scb. It returns immediately and the caller is never blocked. Returns: On success, i.e. message put, it returns 0, msg_size on failure. Definition at line 225 of file rtai_scb.h. References FBYTE, LBYTE, SCB, and SIZE.

---