Defines | Enumerations | Functions

/home/sindre/dev_uclinux/suzaku_shared/hwos_sw/libhwos/hmsg.h File Reference

[Hardware OS Message Interface] Functionality for messages and message queues. More...

#include "hstructures.h"

Go to the source code of this file.

Defines

#define HMSG_DATA_SIZE   128
 Size of data for messages sent to HWOS.

Enumerations

enum  hmsg_type { HMT_ALL, HMT_CTRL, HMT_CTRLMEM, HMT_REGPROC }
 

Definition of message types.


enum  hmsg_command {
  HMC_ALLOC, HMC_EXEC, HMC_FREE, HMC_LDDEV,
  HMC_READ, HMC_RMDEV, HMC_RMQUE, HMC_UMQUE,
  HMC_WRITE, HMC_SET_BITFILE, HMC_REGPROC
}
 

Definition of commands that can be sent through messages from a client application.

More...
enum  hmsg_return { HMR_OK = 0, HMR_ERROR = -1, HMR_NOPID = -2 }
 

Definition of return values that can be sent back to a client application.


Functions

char * hmsg_get_bitfilename (void *msg)
 Filename for FPGA bitstream.
int hmsg_set_bitfilename (void *msg, char *bitfilename)
 Set filename for FPGA bitstream.
int hmsg_get_nice (void *msg)
 Get nice value (user defined priority).
int hmsg_set_nice (void *msg, int nice)
 Set nice value (user defined priority).
int hmsg_get_sender (void *msg)
 Get sender ID for the message.
int hmsg_set_sender (void *msg, int id)
 Set sender ID for the message.
int hmsg_get_type (void *msg)
 Get type of the message.
int hmsg_get_size (void *msg)
 Get size of the data field.
int hmsg_set_size (void *msg, int size)
 Set size of the data field.
int hmsg_set_return (void *msg, enum hmsg_return retval)
 Set return value for the specified message.
enum hmsg_return hmsg_get_return (void *msg)
 Get return value for the specified message.
char * hmsg_get_data (void *msg)
 Get data (string of characters) for message.
int hmsg_set_data (void *msg, char *data)
 Set data (string of characters) for message.
int hmsg_set_address (void *msg, int address)
 Set address field for a message.
int hmsg_get_address (void *msg)
 Get address field for a message.
enum hmsg_command hmsg_get_command (void *msg)
 Get command for message.
int hmsg_set_command (void *msg, enum hmsg_command command)
 Set command for message.
void * hmsg_create (int type)
 Create and allocate memory for a message.
int hmsg_remove (void *msg)
 Destroy message.
int hmsg_send (void *msg, struct hmqueue *msq)
 Send a message.
void * hmsg_receive (struct hmqueue *msq)
 Blocking wait for an incoming message.

Detailed Description

[Hardware OS Message Interface] Functionality for messages and message queues.

Defines an interface for message passing between the HWOS and a client application. The message system is implemented using System V Message Queues.

Based on (2010): Vegard Endresen

Author (2011): Sindre Hansen

Definition in file hmsg.h.


Enumeration Type Documentation

Definition of commands that can be sent through messages from a client application.

Enumerator:
HMC_ALLOC 

Allocate BRAM memory.

HMC_EXEC 

Write program to instruction segment of BRAM.

HMC_FREE 

Free BRAM memory.

HMC_LDDEV 

Load device driver.

HMC_READ 

Read data from backend.

HMC_RMDEV 

Remove device driver.

HMC_RMQUE 

Register receive message queue to HWOS.

HMC_UMQUE 

Unregister receive message queue to HWOS.

HMC_WRITE 

Write data to backend.

HMC_SET_BITFILE 

Set filename for bitstream file (deprecated?).

HMC_REGPROC 

Register a process.

Definition at line 31 of file hmsg.h.


Function Documentation

void* hmsg_create ( int  type  ) 

Create and allocate memory for a message.

Parameters:
type The type of the new message.
Returns:
Pointer to the memory of the new message on success. NULL on failure.

Definition at line 334 of file hmsg.c.

{
        // Allocate memory based on message type.
        // Point msg object to the newly allocated memory afterwards.
        if (type == HMT_CTRL) {
                struct hmsg_ctrl* ctrl_msg;
                ctrl_msg = (struct hmsg_ctrl*)calloc(1, sizeof(struct hmsg_ctrl));
                if (set_type_(ctrl_msg, HMT_CTRL) < 0) {
                        free(ctrl_msg);
                        return NULL;
                }
                hmsg_set_command(ctrl_msg, -1);
                hmsg_set_size(ctrl_msg, -1);
                hmsg_set_return(ctrl_msg, -1);
                return ctrl_msg;
        } else if (type == HMT_CTRLMEM) {
                struct hmsg_ctrlmem* ctrlmem_msg;
                ctrlmem_msg = (struct hmsg_ctrlmem*)calloc(1, sizeof(struct hmsg_ctrlmem));
                if (set_type_(ctrlmem_msg, HMT_CTRLMEM) < 0) {
                        free(ctrlmem_msg);
                        return NULL;
                }
                hmsg_set_command(ctrlmem_msg, -1);
                hmsg_set_address(ctrlmem_msg, -1);
                hmsg_set_return(ctrlmem_msg, -1);
                hmsg_set_size(ctrlmem_msg, -1);
                hmsg_set_data(ctrlmem_msg, "");
                return ctrlmem_msg;
        } else if (type == HMT_REGPROC) {
                struct hmsg_regproc* regproc_msg;
                regproc_msg = (struct hmsg_regproc*)calloc(1, sizeof(struct hmsg_regproc));
                if (set_type_(regproc_msg, HMT_REGPROC) < 0) {
                        free(regproc_msg);
                        return NULL;
                }
                hmsg_set_nice(regproc_msg, -1);
                // Set command by default.
                hmsg_set_command(regproc_msg, HMC_REGPROC);
                hmsg_set_bitfilename(regproc_msg, "");
                return regproc_msg;
        } else {
                hlog_write(HLOG_ERROR, "hmsg_create: Failed to create message. Unknown type.\n");
                return NULL;
        }
}

int hmsg_get_address ( void *  msg  ) 

Get address field for a message.

Parameters:
msg Message of type HMT_CTRLMEM.
Returns:
Positive address on success. Negative on failure.

Definition at line 268 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_CTRLMEM)
                return ((struct hmsg_ctrlmem*)msg)->mtext.address;
        else {
                hlog_write(HLOG_ERROR, "hmsg_set_address: Failed to set address. Unknown message type.\n");
                return -1;
        }
}

char* hmsg_get_bitfilename ( void *  msg  ) 

Filename for FPGA bitstream.

Parameters:
msg Message of type HMT_REGPROC.
Returns:
The filename.

Definition at line 124 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_REGPROC)
                return (char*)(((struct hmsg_regproc*)msg)->mtext.bitfilename);
        else {
                hlog_write(HLOG_ERROR, "hmsg_get_bitfilename: Failed to return data. Unknown message type.\n");
                return NULL;
        }   
}

enum hmsg_command hmsg_get_command ( void *  msg  ) 

Get command for message.

Parameters:
msg Message of any type.
Returns:
The command entry (positive integer) for the message. Negative on failure.

Definition at line 299 of file hmsg.c.

{
        switch( hmsg_get_type(msg) ) {
                case HMT_CTRL:
                        return ((struct hmsg_ctrl*)msg)->mtext.command;
                case HMT_CTRLMEM:
                        return ((struct hmsg_ctrlmem*)msg)->mtext.command;
                case HMT_REGPROC:
                        return ((struct hmsg_regproc*)msg)->mtext.command;
                default:
                        return -1;
        }
}

char* hmsg_get_data ( void *  msg  ) 

Get data (string of characters) for message.

Parameters:
msg Message of type HMT_CTRLMEM.
Returns:
Pointer to data on success. NULL on failure.

Definition at line 232 of file hmsg.c.

{
        switch (hmsg_get_type(msg)) {
                case HMT_CTRLMEM:
                        return (char*)(((struct hmsg_ctrlmem*)msg)->mtext.data);
                default:
                        hlog_write(HLOG_ERROR, "hmsg_get_data: Failed to return data. Unknown message (type=");
                        hlog_write_integer(hmsg_get_type(msg));
                        hlog_write_text(").\n");
                        return NULL;
        }
}

int hmsg_get_nice ( void *  msg  ) 

Get nice value (user defined priority).

Parameters:
msg Message of type HMT_REGPROC.
Returns:
Positive nice value on success. Negative on failure.

Definition at line 147 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_REGPROC)
                return ((struct hmsg_regproc*)msg)->mtext.nice;
        else
                return -1;
}

enum hmsg_return hmsg_get_return ( void *  msg  ) 

Get return value for the specified message.

Parameters:
msg Message of type HMT_CTRL or HMT_CTRLMEM.
Returns:
The return value (constrained by enum hmsg_return).

Definition at line 205 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_CTRL || hmsg_get_type(msg) == HMT_CTRLMEM)
                return ((struct hmsg_ctrl*)msg)->mtext.retval;
        else
                return -1;
}

int hmsg_get_sender ( void *  msg  ) 

Get sender ID for the message.

In this version of the HWOS, this is always the message queue ID of the queue owned by the sender.

Parameters:
msg Message of any type.
Returns:
Positive message queue ID on success. Negative on failure.

Definition at line 177 of file hmsg.c.

{
        if (msg == NULL)
                return -1;

        return ((struct hmsg_base*)msg)->mtext.sender_id;
}

int hmsg_get_size ( void *  msg  ) 

Get size of the data field.

Parameters:
msg Message of type HMT_CTRLMEM.
Returns:
The size (positive integer) on success. Negative on failure.

Definition at line 214 of file hmsg.c.

{
        if (hmsg_get_type(msg) != HMT_CTRLMEM)
                return -1;

        return ((struct hmsg_ctrlmem*)msg)->mtext.size;
}

int hmsg_get_type ( void *  msg  ) 

Get type of the message.

Parameters:
msg Message of any type.
Returns:
The type (positive integer) on success. Negative on failure.

Definition at line 186 of file hmsg.c.

{
        if (msg == NULL)
                return -1;

        return ((struct hmsg_base*)msg)->type;
}

void* hmsg_receive ( struct hmqueue msq  ) 

Blocking wait for an incoming message.

Parameters:
msq The message queue where the message arrives.
Returns:
Pointer to the received message on success. NULL on failure.

Definition at line 392 of file hmsg.c.

{
        void* msg = NULL;
        int msqid = hmqueue_get_id(msq);

        // Allocate a memory block large enough to store any kind of message.
        msg = calloc(1, get_mtext_max_size_() + sizeof(long));
        msgrcv(msqid, msg, get_mtext_max_size_(), 0, 0);
        // Reallocate a smaller memory block.
        msg = realloc(msg, get_struct_size_( hmsg_get_type(msg) ));

        return msg;
}

int hmsg_remove ( void *  msg  ) 

Destroy message.

Actually just runs free(msg) if msg != NULL.

Parameters:
type Message of any type.
Returns:
0 on success. NULL on failure.

Definition at line 381 of file hmsg.c.

{
        if (msg == NULL)
                return -1;
        
        free(msg);

        return 0;
}

int hmsg_send ( void *  msg,
struct hmqueue msq 
)

Send a message.

Puts a message in a message queue.

Parameters:
msg Message of any type.
msq Message queue. Message is put in this queue.
Returns:
0 on success. Negative value on failure.

Definition at line 278 of file hmsg.c.

{
        int msqid = hmqueue_get_id(msq);
        hlog_write(HLOG_DEBUG, "hmsg_send: Adding message to message queue. msqid=");
        hlog_write_integer(msqid);
        hlog_write_text(".\n");

        switch( hmsg_get_type(msg) ) {
                case HMT_CTRL:
                        return msgsnd(msqid, (struct hmsg_ctrl*)msg, get_mtext_size_(HMT_CTRL), 0);
                case HMT_CTRLMEM:
                        return msgsnd(msqid, (struct hmsg_ctrlmem*)msg, get_mtext_size_(HMT_CTRLMEM), 0);
                case HMT_REGPROC:
                        return msgsnd(msqid, (struct hmsg_regproc*)msg, get_mtext_size_(HMT_REGPROC), 0);
                default:
                        hlog_write(HLOG_ERROR, "hmsg_send: Failed to send message. Unknown type.\n");
                        return -2;
        }
}

int hmsg_set_address ( void *  msg,
int  address 
)

Set address field for a message.

Parameters:
msg Message of type HMT_CTRLMEM.
Returns:
Positive on success. Negative on failure.

Definition at line 255 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_CTRLMEM)
                ((struct hmsg_ctrlmem*)msg)->mtext.address = address;
        else {
                hlog_write(HLOG_ERROR, "hmsg_set_address: Failed to set address. Unknown message type.\n");
                return -1;
        }

        return 0;
}

int hmsg_set_bitfilename ( void *  msg,
char *  bitfilename 
)

Set filename for FPGA bitstream.

Parameters:
msg Message of type HMT_REGPROC.
bitfilename The filename.
Returns:
0 on success. Negative on failure.

Definition at line 135 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_REGPROC) {
                strncpy(hmsg_get_bitfilename(msg), bitfilename, HPROCESS_MAX_FILENAME_SIZE);
                return 0;
        } else {
                hlog_write(HLOG_ERROR, "hmsg_set_bitfilename: Failed to set data. Unknown message type.\n");
                return -1;
        }
}

int hmsg_set_command ( void *  msg,
enum hmsg_command  command 
)

Set command for message.

Parameters:
msg Message of any type.
The command entry (positive integer) for the message.
Returns:
0 on success. Negative on failure.

Definition at line 314 of file hmsg.c.

{
        switch( hmsg_get_type(msg) ) {
                case HMT_CTRL:
                        ((struct hmsg_ctrl*)msg)->mtext.command = command;
                        break;
                case HMT_CTRLMEM:
                        ((struct hmsg_ctrlmem*)msg)->mtext.command = command;
                        break;
                case HMT_REGPROC:
                        ((struct hmsg_regproc*)msg)->mtext.command = command;
                        break;
                default:
                        return -1;
        }

        return 0;
}

int hmsg_set_data ( void *  msg,
char *  data 
)

Set data (string of characters) for message.

Parameters:
msg Message of type HMT_CTRLMEM.
data Pointer to the data. Size not larger than HMSG_DATA_SIZE.
Returns:
0 on success. Negative on failure.

Definition at line 246 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_CTRLMEM) {
                strncpy(hmsg_get_data(msg), data, HMSG_DATA_SIZE);
                return 0;
        } else
                return -1;
}

int hmsg_set_nice ( void *  msg,
int  nice 
)

Set nice value (user defined priority).

Parameters:
msg Message of type HMT_REGPROC.
nice The positive value.
Returns:
0 on success. Negative on failure.

Definition at line 156 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_REGPROC) {
                ((struct hmsg_regproc*)msg)->mtext.nice = nice;
                return 0;
        } else
                return -1;
}

int hmsg_set_return ( void *  msg,
enum hmsg_return  retval 
)

Set return value for the specified message.

Parameters:
msg Pointer to a response message.
retval Return value.
Returns:
Positive on success. Negative on failure.

Definition at line 195 of file hmsg.c.

{
        if (hmsg_get_type(msg) == HMT_CTRL || hmsg_get_type(msg) == HMT_CTRLMEM) {
                ((struct hmsg_ctrl*)msg)->mtext.retval = retval;
                return 0;
        } else
                return -1;
}

int hmsg_set_sender ( void *  msg,
int  id 
)

Set sender ID for the message.

In this version of the HWOS, this is always the message queue ID of the queue owned by the sender.

Parameters:
msg Message of any type.
id The message queue ID.
Returns:
0 on success. Negative on failure.

Definition at line 166 of file hmsg.c.

{
        if (msg == NULL)
                return -1;

        ((struct hmsg_base*)msg)->mtext.sender_id = id;

        return 0;
}

int hmsg_set_size ( void *  msg,
int  size 
)

Set size of the data field.

Parameters:
msg Message of type HMT_CTRLMEM.
size The size of the data field.
Returns:
0 on success. Negative on failure.

Definition at line 222 of file hmsg.c.

{
        if (hmsg_get_type(msg) != HMT_CTRLMEM)
                return -1;

        ((struct hmsg_ctrlmem*)msg)->mtext.size = size;

        return 0;
}

 All Data Structures Files Functions Variables Enumerations Enumerator Defines