TSP: The Transport Sample Protocol



The BB Core Library
[BlackBoard (BB)]

Collaboration diagram for The BB Core Library:The BlackBoard library API. More...


Modules

 The BB Alias System
 The BB alias system is a part of the BlackBoard library which enable a special publish interface called bb_alias_publish.

Data Structures

struct  bb_operations
 Implementation agnostic operations, for now these functions abstract the following operating modes:
  • SysV shmem + IPCs
  • /dev/bb mmap from user space
  • in-kernel bb_create, bb_publish.
More...
struct  kernel_private
 In-kernel black board specific data, part of the S_BB_T structure. More...
struct  S_BB
 BlackBoard description structure. More...
struct  S_BB_DATADESC
 BlackBoard data descriptor. More...
struct  S_BB_MSG
 BlackBoard message definition. More...
struct  sysv_private
 SysV specific data, part of the S_BB_T structure. More...

Defines

#define BB_EXT_SIZE_V0x0004000   4096
 Size of the S_BB_PRIV_T in version 0x0004000.

Typedefs

typedef S_BB_DATADESC S_BB_DATADESC_T
 BlackBoard data descriptor.
typedef S_BB_MSG S_BB_MSG_T
 BlackBoard message definition.
typedef S_BB S_BB_T
 BlackBoard description structure.

Enumerations

enum  BB_STATUS_T {
  BB_STATUS_UNKNOWN = 0, BB_STATUS_GENUINE, BB_STATUS_DIRTY, BB_STATUS_DESTROYED,
  BB_STATUS_SHADOW
}
 BlackBoard status. More...
enum  bb_type
 The black board type, this is tightly coupled to the struct bb_operations *ops[] defined in bb_core.c it's used as a selector of the right set of operations. More...
enum  E_BB_TYPE_T {
  E_BB_DISCOVER = 0, E_BB_DOUBLE = 1, E_BB_FLOAT, E_BB_INT8,
  E_BB_INT16, E_BB_INT32, E_BB_INT64, E_BB_UINT8,
  E_BB_UINT16, E_BB_UINT32, E_BB_UINT64, E_BB_CHAR,
  E_BB_UCHAR, E_BB_USER
}
 BlackBoard publishable data type. More...

Functions

int32_t bb_attach (S_BB_T **bb, const char *bb_name)
 Attach to an existing blackboard.
int32_t bb_check_version (volatile S_BB_T *bb)
 Check if the accessed blackboard is of the same version as the one used by this code.
int32_t bb_create (S_BB_T **bb, const char *pc_bb_name, int32_t n_data, int32_t data_size)
 Create a blackboard.
int32_t bb_ctl (S_BB_T *bb, unsigned int request,...)
 General purpose bb control function.
void * bb_data (volatile S_BB_T *bb)
 Return a pointer to the beginning of the data array of the specified BB.
S_BB_DATADESC_Tbb_data_desc (volatile S_BB_T *bb)
 Return a pointer to the beginning of the data descriptor array of the specified BB.
int32_t bb_data_initialise (volatile S_BB_T *bb, S_BB_DATADESC_T *data_desc, void *default_value)
 Initialise a freshly created structure to a default value.
int32_t bb_data_memset (S_BB_T *bb, const char c)
 Memset the data area of a BB.
int32_t bb_data_print (volatile S_BB_T *bb, S_BB_DATADESC_T data_desc, FILE *pf, int32_t *idxstack, int32_t idxstack_len)
 Print the content of a data descriptor.
int32_t bb_destroy (S_BB_T **bb)
 Destroy a blackboard.
int32_t bb_detach (S_BB_T **bb)
 Detach from blackboard.
double bb_double_of (void *value, E_BB_TYPE_T bbtype)
 Return a double value from the pointer value considered as the bbtype.
int32_t bb_dump (volatile S_BB_T *bb, FILE *filedesc)
 Dump a blackboard to a file stream.
int32_t bb_find (volatile S_BB_T *bb, const char *var_name)
 Search a variable within a BlackBoard.
int32_t bb_get_array_name (char *array_name, int array_name_size_max, S_BB_DATADESC_T *aliasstack, int32_t aliasstack_size, int32_t *indexstack, int32_t indexstack_len)
 Build in array_name the name of the array defined by the provided alias stack and index stack.
int32_t bb_get_mem_size (volatile S_BB_T *bb)
 Return the memory occupation (in byte) of a blackboard.
int32_t bb_get_nb_item (volatile S_BB_T *bb)
 Return the number of data that are currently published in blackboard.
int32_t bb_get_nb_max_item (volatile S_BB_T *bb)
 Return the maximum number of data that could be published in blackboard.
S_BB_PRIV_T * bb_get_priv (volatile S_BB_T *bb)
 Get a pointer to the private structure of the BB.
int32_t bb_lock (volatile S_BB_T *bb)
 Lock blackboard.
int32_t bb_logMsg (const BB_LOG_LEVEL_T level, const char *modname, char *fmt,...)
 Log message for BB Error.
int32_t bb_msg_id (volatile S_BB_T *bb)
 Return the BB message queue identifier.
int32_t bb_msgq_isalive (S_BB_T *bb)
 Allow the caller to verify if the message queue is still working.
void * bb_publish (volatile S_BB_T *bb, S_BB_DATADESC_T *data_desc)
 Publish a data in a blackboard.
int32_t bb_rcv_msg (volatile S_BB_T *bb, S_BB_MSG_T *msg)
 Receive a message on the BB message queue.
int32_t bb_shadow_get (S_BB_T *bb_shadow, volatile S_BB_T *bb_src)
 Ask for a shadow blackboard creation.
int32_t bb_shadow_update_data (S_BB_T *bb_shadow, volatile S_BB_T *bb_src)
 Update the data zone of a shadow blackboard.
int32_t bb_size (const int32_t n_data, const int32_t data_size)
 Return the size of a blackboard with n_data publishable elements with a data zone of size data_size byte.
int32_t bb_snd_msg (volatile S_BB_T *bb, S_BB_MSG_T *msg)
 Send message through BB msg queue.
int32_t bb_string_value_print (volatile S_BB_T *bb, S_BB_DATADESC_T data_desc, FILE *pf, int32_t *idxstack, int32_t idxstack_len)
 Print the value off a BB published data on a STDIO file stream.
void * bb_subscribe (volatile S_BB_T *bb, S_BB_DATADESC_T *data_desc)
 Subscribe to blackboard data.
E_BB_TYPE_T bb_type_string2bb_type (const char *bb_type_string)
 Convert a string representing a E_BB_TYPE_T to a BlackBoard data type.
int32_t bb_unlock (volatile S_BB_T *bb)
 Unlock blackboard.
int32_t bb_value_print (volatile S_BB_T *bb, S_BB_DATADESC_T data_desc, FILE *pf, int32_t *idxstack, int32_t idxstack_len)
 Print the value off a BB published data on a STDIO file stream.
int32_t bb_value_write (volatile S_BB_T *bb, S_BB_DATADESC_T data_desc, const char *value, int32_t *idxstack, int32_t idxstack_len)
 Write value represented by string to BB published data.
size_t sizeof_bb_type (E_BB_TYPE_T bb_type)
 The size (in byte) of a BlackBoard data type.

Variables

bb_get_varname_fn bb_get_varname
 Get the name of a variable described by .
bb_set_varname_fn bb_set_varname
 Get the name of a variable described by .
bb_varname_max_len_fn bb_varname_max_len
 Get the max len of a name of a variable described by .


Detailed Description

The BlackBoard library API.

The BlackBoard library has two-level of usage a full-fledge more complicated API which is the API you are currently looking at or a more simple with less functionnality API called The BB Simple Library.


Define Documentation

#define BB_EXT_SIZE_V0x0004000   4096

Size of the S_BB_PRIV_T in version 0x0004000.


Typedef Documentation

typedef struct S_BB_DATADESC S_BB_DATADESC_T

BlackBoard data descriptor.

Each data published in a blackboard is described using one such structure.

typedef struct S_BB_MSG S_BB_MSG_T

BlackBoard message definition.

This type must conform to the constraint of a SysV message queue message used by msgsnd(2).

typedef struct S_BB S_BB_T

BlackBoard description structure.

This structure describes the BlackBoard itself (not data published in BlackBoard which are described by the S_BB_DATADESC_T structure).


Enumeration Type Documentation

enum BB_STATUS_T

BlackBoard status.

Enumerator:
BB_STATUS_UNKNOWN  Unknown status
BB_STATUS_GENUINE  Genuine as opposed to a shadow one
BB_STATUS_DIRTY  Unused for now
BB_STATUS_DESTROYED  The BlackBoard has been destroyed by one of the process that were attached to, other should detach as fast as possible
BB_STATUS_SHADOW  A Shadow BlackBoard created by bb_shadow_get

enum bb_type

The black board type, this is tightly coupled to the struct bb_operations *ops[] defined in bb_core.c it's used as a selector of the right set of operations.

enum E_BB_TYPE_T

BlackBoard publishable data type.

Any data published with bb_publish, bb_alias_publish or bb_simple_publish should be specified with its type.

Enumerator:
E_BB_DISCOVER  Discover is used by bb_subscribe when discovering data type
E_BB_DOUBLE  An IEEE double precision floating point
E_BB_FLOAT  An IEEE simple precision floating point
E_BB_INT8  An 8bit signed integer
E_BB_INT16  A 16bit signed integer
E_BB_INT32  A 32bit signed integer
E_BB_INT64  A 64bit signed integer
E_BB_UINT8  An 8bit unsigned integer
E_BB_UINT16  A 16bit unsigned integer
E_BB_UINT32  A 32bit unsigned integer
E_BB_UINT64  A 64bit unsigned integer
E_BB_CHAR  An 8bit signed character
E_BB_UCHAR  An 8bit unsigned character
E_BB_USER  A user type of any size (should be supplied) in bb_publish


Function Documentation

int32_t bb_attach ( S_BB_T **  bb,
const char *  bb_name 
)

Attach to an existing blackboard.

=

Parameters:
[out] bb Pointer to BB pointer (should not be NULL). the pointed value is updated is BB attach succeed.
[in] bb_name blackboard name
Returns:
E_OK if blackboard exists and attach succeed E_NOK otherwise.

int32_t bb_check_version ( volatile S_BB_T bb  ) 

Check if the accessed blackboard is of the same version as the one used by this code.

Parameters:
[in] bb the BlackBoard to be checked
Returns:
0 if version is the same, < 0 if current version is older than the accessed blackboard, > 0 for the converse.

int32_t bb_create ( S_BB_T **  bb,
const char *  pc_bb_name,
int32_t  n_data,
int32_t  data_size 
)

Create a blackboard.

Create a shared memory segment of the specified size then mmap it for the current process and initialize the zone to contains a fresh new blackboard structure. Only one process should create a blackboard others should attach through

See also:
bb_attach(S_BB_T**, const char*).
Parameters:
[in,out] bb Pointer to a BB pointer. IN, non NULL pointer. OUT, the pointed element is the new created BB or NULL is creation failed.
[in] pc_bb_name the blackboard name
[in] n_data maximum data to be stored in blackboard. I.e. the number of different published element in BB (each element has an associated key)
[in] data_size the maximum data zone size (in byte) of the blackboard. This is the sum of all data published in the blackboard.
Returns:
E_OK if creation succeed E_NOK if failed.

int32_t bb_ctl ( S_BB_T bb,
unsigned int  request,
  ... 
)

General purpose bb control function.

Parameters:
[in] bb a BlackBoard pointer
[in] request the kind of request (see BB_CTL defines)
Returns:
BB_OK is the operation succeeded, BB_NOK otherwise.

void* bb_data ( volatile S_BB_T bb  ) 

Return a pointer to the beginning of the data array of the specified BB.

Parameters:
[in] bb BlackBoard pointer
Returns:
start address of the data array in bb

S_BB_DATADESC_T* bb_data_desc ( volatile S_BB_T bb  ) 

Return a pointer to the beginning of the data descriptor array of the specified BB.

Parameters:
[in] bb BlackBoard pointer
Returns:
start address of the data descriptor array in bb

int32_t bb_data_initialise ( volatile S_BB_T bb,
S_BB_DATADESC_T data_desc,
void *  default_value 
)

Initialise a freshly created structure to a default value.

If default value pointer is NULL then all type are initialized to 0 but the E_BB_USER for which the data zone is set to binary 0.

Parameters:
[in] bb pointer to the blackboard whose the data belongs.
[in,out] data_desc pointer to the data descriptor structure (should NOT be NULL).
[in,out] default_value default pointer to the default value used for init. If NULL then initialize to 0.
Returns:
E_OK if init OK E_NOK otherwise.

int32_t bb_data_memset ( S_BB_T bb,
const char  c 
)

Memset the data area of a BB.

Parameters:
[in,out] bb BB pointer, should not be NULL.
[in] c the character used to memset each byte of the BlackBoard data area.

int32_t bb_data_print ( volatile S_BB_T bb,
S_BB_DATADESC_T  data_desc,
FILE *  pf,
int32_t *  idxstack,
int32_t  idxstack_len 
)

Print the content of a data descriptor.

Parameters:
[in] bb pointer to BB where the data reside
[in,out] data_desc pointer to data descriptor.
[in,out] pf stream file pointer to be used for printing.
[in] idxstack the index stack
[in] idxstack_len the size of the index stack
Returns:
always return E_OK unless pf is NULL.

int32_t bb_destroy ( S_BB_T **  bb  ) 

Destroy a blackboard.

Destroy the BB structure. Destroy the shared memory segment and detach from it. Note that effective shared memory segment destruction will occur when the last process attached is detached (through

See also:
bb_detach for example).
Parameters:
[in,out] bb Pointer to BB pointer. Should not be NULL.
Returns:
E_OK on success E_NOK otherwise.

int32_t bb_detach ( S_BB_T **  bb  ) 

Detach from blackboard.

Parameters:
[in,out] bb Pointer to BB pointer (should not be NULL)
Returns:
E_OK if blackboard exists and detach succeed E_NOK otherwise.

double bb_double_of ( void *  value,
E_BB_TYPE_T  bbtype 
)

Return a double value from the pointer value considered as the bbtype.

Parameters:
[in] value pointer to the value
[in] bbtype the type of the pointer
Returns:
double value of the pointed value

int32_t bb_dump ( volatile S_BB_T bb,
FILE *  filedesc 
)

Dump a blackboard to a file stream.

Blackboard description and all data content is dumped.

Parameters:
[in,out] bb pointer to BB.
[in,out] filedesc file stream descriptor.
Returns:
E_OK if dump succeed E_NOK otherwise.

int32_t bb_find ( volatile S_BB_T bb,
const char *  var_name 
)

Search a variable within a BlackBoard.

Parameters:
[in] bb BlackBoard pointer
[in] var_name the name of the searched variable
Returns:
index of the variable in the BB descriptor array

int32_t bb_get_array_name ( char *  array_name,
int  array_name_size_max,
S_BB_DATADESC_T aliasstack,
int32_t  aliasstack_size,
int32_t *  indexstack,
int32_t  indexstack_len 
)

Build in array_name the name of the array defined by the provided alias stack and index stack.

Parameters:
[out] array_name the string to be used to build array name
[in] array_name_size_max the maximum (usable) size for array_name
[in] aliasstack the alias stack
[in] aliasstack_size the size of the alias stack
[in] indexstack the index stack
[in] indexstack_len the lenth of the index stack
Returns:
E_OK on success, E_NOK otherwise

int32_t bb_get_mem_size ( volatile S_BB_T bb  ) 

Return the memory occupation (in byte) of a blackboard.

Parameters:
[in] bb pointer to BB.
Returns:
memory occupied by the specified BB in bytes

int32_t bb_get_nb_item ( volatile S_BB_T bb  ) 

Return the number of data that are currently published in blackboard.

Parameters:
[in] bb pointer to blackboard.
Returns:
the number of data currently published in blackboard.

int32_t bb_get_nb_max_item ( volatile S_BB_T bb  ) 

Return the maximum number of data that could be published in blackboard.

Parameters:
[in] bb pointer to blackboard.
Returns:
the maximum number of data that could be published in blackboard

S_BB_PRIV_T* bb_get_priv ( volatile S_BB_T bb  ) 

Get a pointer to the private structure of the BB.

Returns:
a pointer to the private structure of the BB

int32_t bb_lock ( volatile S_BB_T bb  ) 

Lock blackboard.

A BlackBoard should be locked befaore any structural change or to protect different process against each other from concurrent modifications. This is a blocking call (using sys V semaphore).

See also:
bb_publish/

bb_subscribe automatically lock the blackboard.

Parameters:
[in,out] bb BB pointer, should not be NULL.
Returns:
E_OK if lock succeed, E_NOK otherwise.

int32_t bb_logMsg ( const BB_LOG_LEVEL_T  level,
const char *  modname,
char *  fmt,
  ... 
)

Log message for BB Error.

This function may be replaced by a project specific function which want to use BB with a unified log system. The default implementation use TSP STRACE facility.

Parameters:
[in] level the log level.
[in] modname the module who sent the message.
[in] fmt format as in printf.
Returns:
0 on success, -1 on error.

int32_t bb_msg_id ( volatile S_BB_T bb  ) 

Return the BB message queue identifier.

Parameters:
[in,out] bb pointer to BB.
Returns:
message queue id

int32_t bb_msgq_isalive ( S_BB_T bb  ) 

Allow the caller to verify if the message queue is still working.

Parameters:
[in,out] bb pointer to BB.
Returns:
E_OK on success, E_NOK otherwise

void* bb_publish ( volatile S_BB_T bb,
S_BB_DATADESC_T data_desc 
)

Publish a data in a blackboard.

This request allocate space for the specified data in blackboard and return the address of the newly allocated space. This function has the same semantic as malloc(3).

Parameters:
[in,out] bb BB pointer (should not be NULL).
[in,out] data_desc Data descriptor of the data to be published. OUT, if data has been properly allocated the S_BB_DATADESC_T.data_offset is updated.
Returns:
address of the allocated data, NULL if allocation failed.

int32_t bb_rcv_msg ( volatile S_BB_T bb,
S_BB_MSG_T msg 
)

Receive a message on the BB message queue.

This is a blocking call.

Parameters:
[in,out] bb pointer to BB.
[in,out] msg the message to be read. The type of the message to be received should be be specified on entry in the message structure msg->mtype.
Returns:
E_OK on success, E_NOK otherwise

int32_t bb_shadow_get ( S_BB_T bb_shadow,
volatile S_BB_T bb_src 
)

Ask for a shadow blackboard creation.

A shadow blackboard is a blackboard which does not reside in shared memory is meant to be in local memory. This BB is not meant to be shared between several process or thread. The only valid operation on a shadow BB are:

int32_t bb_shadow_update_data ( S_BB_T bb_shadow,
volatile S_BB_T bb_src 
)

Update the data zone of a shadow blackboard.

This is essentially a memcpy of the blackboard data zone.

Parameters:
[in,out] bb_shadow pointer to shadow BB
[in] bb_src pointer to source BB (the same BB initially used for making shadow)
Returns:
E_OK on success.

int32_t bb_size ( const int32_t  n_data,
const int32_t  data_size 
)

Return the size of a blackboard with n_data publishable elements with a data zone of size data_size byte.

This is the exact size of the SHM segment required to create a BB.

Parameters:
[in] n_data the number of publishable data in blackboard
[in] data_size the size (in byte) of the blackboard data zone.
Returns:
the size (in byte) of this kind of blackboard.

int32_t bb_snd_msg ( volatile S_BB_T bb,
S_BB_MSG_T msg 
)

Send message through BB msg queue.

This is a non blocking call, if there is no more room in the message queue, the message is not sent and lost.

Parameters:
[in,out] bb pointer to BB
[in,out] msg pointer to message to be sent
Returns:
E_OK on success E_NOK otherwise.

int32_t bb_string_value_print ( volatile S_BB_T bb,
S_BB_DATADESC_T  data_desc,
FILE *  pf,
int32_t *  idxstack,
int32_t  idxstack_len 
)

Print the value off a BB published data on a STDIO file stream.

Parameters:
[in] bb the BlackBoard where data is published
[in] data_desc the BB data descriptor. Be sure to provide a properly initialised data_desc since the function does not verify this.
[in] pf the STDIO file stream pointer, should be open for writing.
[in] idxstack the indexstack (in the alias case) The BB Alias System. it is not read if idxstack_len is 0.
[in] idxstack_len the indexstack length should be >= 0, if 0 idxstack is ignored

void* bb_subscribe ( volatile S_BB_T bb,
S_BB_DATADESC_T data_desc 
)

Subscribe to blackboard data.

The function search the data in BB and return its address if found.

Parameters:
[in] bb pointer to BB.
[in,out] data_desc data descriptor for the searched data on entry updated data desc if found.
Returns:
data address if found NULL if not found.

E_BB_TYPE_T bb_type_string2bb_type ( const char *  bb_type_string  ) 

Convert a string representing a E_BB_TYPE_T to a BlackBoard data type.

Parameters:
[in] bb_type_string a string representing a BlackBoard data type
Returns:
the BlackBoard data type or -1 if conversion failed.

int32_t bb_unlock ( volatile S_BB_T bb  ) 

Unlock blackboard.

Parameters:
[in,out] bb BB pointer, should not be NULL.
Returns:
E_OK if unlock succeed, E_NOK otherwise.

int32_t bb_value_print ( volatile S_BB_T bb,
S_BB_DATADESC_T  data_desc,
FILE *  pf,
int32_t *  idxstack,
int32_t  idxstack_len 
)

Print the value off a BB published data on a STDIO file stream.

Parameters:
[in] bb the BlackBoard where data is published
[in] data_desc the BB data descriptor. Be sure to provide a properly initialised data_desc since the function does not verify this.
[in] pf the STDIO file stream pointer, should be open for writing.
[in] idxstack the indexstack (in the alias case) The BB Alias System. it is not read if idxstack_len is 0.
[in] idxstack_len the indexstack length should be >= 0, if 0 idxstack is ignored

int32_t bb_value_write ( volatile S_BB_T bb,
S_BB_DATADESC_T  data_desc,
const char *  value,
int32_t *  idxstack,
int32_t  idxstack_len 
)

Write value represented by string to BB published data.

This is a mid-level BlackBoard write API which avoid the search complexity used when bb_subscribing to get the data pointer. Nevertheless the function take care of the string to value conversion with proper hexvalue.

Parameters:
[in] bb the BlackBoard where data is published
[in] data_desc the BB data descriptor. Be sure to provide a properly initialised data_desc since the function does not verify this.
[in] value the string representing the value to be written to BB data
[in] idxstack the indexstack (in the alias case) The BB Alias System. it is not read if idxstack_len is 0.
[in] idxstack_len the indexstack length should be >= 0, if 0 idxstack is ignored
Returns:
BB_OK on success BB_NOK otherwise.

size_t sizeof_bb_type ( E_BB_TYPE_T  bb_type  ) 

The size (in byte) of a BlackBoard data type.

Parameters:
[in] bb_type a BlackBoard data type
Returns:
The size (in byte) of a BlackBoard data type or -1 if bb_type equals E_BB_USER or is unknown.


Variable Documentation

bb_get_varname_fn bb_get_varname

Get the name of a variable described by .

Parameters:
[in] dd the descriptor of the variable
Returns:
the variable name, must be freed by caller

bb_set_varname_fn bb_set_varname

Get the name of a variable described by .

Parameters:
[in] dd the descriptor of the variable
Returns:
the variable name, must be freed by caller

bb_varname_max_len_fn bb_varname_max_len

Get the max len of a name of a variable described by .

Returns:
the max lenght of a variable name

Framework Home Page.


Beware !! TSP wave is coming...