← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-ti-omap4/precise

« back to all changes in this revision

Viewing changes to arch/arm/plat-omap/include/syslink/messageq.h

  • Committer: Bazaar Package Importer
  • Author(s): Paolo Pisati
  • Date: 2011-06-29 15:23:51 UTC
  • mfrom: (26.1.1 natty-proposed)
  • Revision ID: james.westby@ubuntu.com-20110629152351-xs96tm303d95rpbk
Tags: 3.0.0-1200.2
* Rebased against 3.0.0-6.7
* BSP from TI based on 3.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
arch/arm/plat-omap/include/syslink/messageq.h
1
 
/*
2
 
 *  messageq.h
3
 
 *
4
 
 *  The MessageQ module supports the structured sending and receiving of
5
 
 *  variable length messages. This module can be used for homogeneous or
6
 
 *  heterogeneous multi-processor messaging.
7
 
 *
8
 
 *  Copyright (C) 2009 Texas Instruments, Inc.
9
 
 *
10
 
 *  This package is free software; you can redistribute it and/or modify
11
 
 *  it under the terms of the GNU General Public License version 2 as
12
 
 *  published by the Free Software Foundation.
13
 
 *
14
 
 *  THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
15
 
 *  IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
16
 
 *  WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
17
 
 *  PURPOSE.
18
 
 */
19
 
 
20
 
#ifndef _MESSAGEQ_H_
21
 
#define _MESSAGEQ_H_
22
 
 
23
 
/* Standard headers */
24
 
#include <linux/types.h>
25
 
 
26
 
/* Utilities headers */
27
 
#include <linux/list.h>
28
 
 
29
 
/* Syslink headers */
30
 
#include <listmp.h>
31
 
 
32
 
/*!
33
 
 *  @def        MESSAGEQ_MODULEID
34
 
 *  @brief      Unique module ID.
35
 
 */
36
 
#define MESSAGEQ_MODULEID                       (0xded2)
37
 
 
38
 
 
39
 
/* =============================================================================
40
 
 *  All success and failure codes for the module
41
 
 * =============================================================================
42
 
 */
43
 
 
44
 
/*!
45
 
 *  @def    MESSAGEQ_S_BUSY
46
 
 *  @brief  The resource is still in use
47
 
 */
48
 
#define MESSAGEQ_S_BUSY                         2
49
 
 
50
 
/*!
51
 
 *  @def    MESSAGEQ_S_ALREADYSETUP
52
 
 *  @brief  The module has been already setup
53
 
 */
54
 
#define MESSAGEQ_S_ALREADYSETUP                 1
55
 
 
56
 
/*!
57
 
 *  @def    MESSAGEQ_S_SUCCESS
58
 
 *  @brief  Operation is successful.
59
 
 */
60
 
#define MESSAGEQ_S_SUCCESS                      0
61
 
 
62
 
/*!
63
 
 *  @def    MESSAGEQ_E_FAIL
64
 
 *  @brief  Operation is not successful.
65
 
 */
66
 
#define MESSAGEQ_E_FAIL                         -1
67
 
 
68
 
/*!
69
 
 *  @def    MESSAGEQ_E_INVALIDARG
70
 
 *  @brief  There is an invalid argument.
71
 
 */
72
 
#define MESSAGEQ_E_INVALIDARG                   -2
73
 
 
74
 
/*!
75
 
 *  @def    MESSAGEQ_E_MEMORY
76
 
 *  @brief  Operation resulted in memory failure.
77
 
 */
78
 
#define MESSAGEQ_E_MEMORY                       -3
79
 
 
80
 
/*!
81
 
 *  @def    MESSAGEQ_E_ALREADYEXISTS
82
 
 *  @brief  The specified entity already exists.
83
 
 */
84
 
#define MESSAGEQ_E_ALREADYEXISTS                -4
85
 
 
86
 
/*!
87
 
 *  @def    MESSAGEQ_E_NOTFOUND
88
 
 *  @brief  Unable to find the specified entity.
89
 
 */
90
 
#define MESSAGEQ_E_NOTFOUND                     -5
91
 
 
92
 
/*!
93
 
 *  @def    MESSAGEQ_E_TIMEOUT
94
 
 *  @brief  Operation timed out.
95
 
 */
96
 
#define MESSAGEQ_E_TIMEOUT                      -6
97
 
 
98
 
/*!
99
 
 *  @def    MESSAGEQ_E_INVALIDSTATE
100
 
 *  @brief  Module is not initialized.
101
 
 */
102
 
#define MESSAGEQ_E_INVALIDSTATE                 -7
103
 
 
104
 
/*!
105
 
 *  @def    MESSAGEQ_E_OSFAILURE
106
 
 *  @brief  A failure occurred in an OS-specific call
107
 
 */
108
 
#define MESSAGEQ_E_OSFAILURE                    -8
109
 
 
110
 
/*!
111
 
 *  @def    MESSAGEQ_E_RESOURCE
112
 
 *  @brief  Specified resource is not available
113
 
 */
114
 
#define MESSAGEQ_E_RESOURCE                     -9
115
 
 
116
 
/*!
117
 
 *  @def    MESSAGEQ_E_RESTART
118
 
 *  @brief  Operation was interrupted. Please restart the operation
119
 
 */
120
 
#define MESSAGEQ_E_RESTART                      -10
121
 
 
122
 
/*!
123
 
 *  @def    MESSAGEQ_E_INVALIDMSG
124
 
 *  @brief  Operation is successful.
125
 
 */
126
 
#define MESSAGEQ_E_INVALIDMSG                   -11
127
 
 
128
 
/*!
129
 
 *  @def    MESSAGEQ_E_NOTOWNER
130
 
 *  @brief  Not the owner
131
 
 */
132
 
#define MESSAGEQ_E_NOTOWNER                     -12
133
 
 
134
 
/*!
135
 
 *  @def    MESSAGEQ_E_REMOTEACTIVE
136
 
 *  @brief  Operation is successful.
137
 
 */
138
 
#define MESSAGEQ_E_REMOTEACTIVE                 -13
139
 
 
140
 
/*!
141
 
 *  @def    MESSAGEQ_E_INVALIDHEAPID
142
 
 *  @brief  Operation is successful.
143
 
 */
144
 
#define MESSAGEQ_E_INVALIDHEAPID                -14
145
 
 
146
 
/*!
147
 
 *  @def    MESSAGEQ_E_INVALIDPROCID
148
 
 *  @brief  Operation is successful.
149
 
 */
150
 
#define MESSAGEQ_E_INVALIDPROCID                -15
151
 
 
152
 
/*!
153
 
 *  @def    MESSAGEQ_E_MAXREACHED
154
 
 *  @brief  Operation is successful.
155
 
 */
156
 
#define MESSAGEQ_E_MAXREACHED                   -16
157
 
 
158
 
/*!
159
 
 *  @def    MESSAGEQ_E_UNREGISTEREDHEAPID
160
 
 *  @brief  Operation is successful.
161
 
 */
162
 
#define MESSAGEQ_E_UNREGISTEREDHEAPID           -17
163
 
 
164
 
/*!
165
 
 *  @def    MESSAGEQ_E_CANNOTFREESTATICMSG
166
 
 *  @brief  Operation is successful.
167
 
 */
168
 
#define MESSAGEQ_E_CANNOTFREESTATICMSG          -18
169
 
/*!
170
 
 *  @def    MESSAGEQ_E_UNBLOCKED
171
 
 *  @brief  The resource is now unblocked
172
 
 */
173
 
#define MESSAGEQ_E_UNBLOCKED                    -20
174
 
 
175
 
 
176
 
/* =============================================================================
177
 
 * Macros and types
178
 
 * =============================================================================
179
 
 */
180
 
/*!
181
 
 *      @brief  Mask to extract version setting
182
 
 */
183
 
#define MESSAGEQ_HEADERVERSION                  0x2000u
184
 
 
185
 
/*! Mask to extract Trace setting */
186
 
#define MESSAGEQ_TRACEMASK                      (uint) 0x1000
187
 
 
188
 
/*! Shift for Trace setting */
189
 
#define MESSAGEQ_TRACESHIFT                     (uint) 12
190
 
 
191
 
/*!
192
 
 *      @brief  Mask to extract priority setting
193
 
 */
194
 
#define MESSAGEQ_PRIORITYMASK                   0x3u
195
 
 
196
 
/*!
197
 
 *  Used as the timeout value to specify wait forever
198
 
 */
199
 
#define MESSAGEQ_FOREVER                        (~((u32) 0))
200
 
 
201
 
/*!
202
 
 *  Invalid message id
203
 
 */
204
 
#define MESSAGEQ_INVALIDMSGID                   0xFFFF
205
 
 
206
 
/*!
207
 
 * Invalid message queue
208
 
 */
209
 
#define MESSAGEQ_INVALIDMESSAGEQ                0xFFFF
210
 
 
211
 
/*!
212
 
 * Indicates that if maximum number of message queues are already created,
213
 
 * should allow growth to create additional Message Queue.
214
 
 */
215
 
#define MESSAGEQ_ALLOWGROWTH                    (~((u32) 0))
216
 
 
217
 
/*!
218
 
 * Number of types of priority queues for each transport
219
 
 */
220
 
#define MESSAGEQ_NUM_PRIORITY_QUEUES            2
221
 
 
222
 
 
223
 
/* =============================================================================
224
 
 * Structures & Enums
225
 
 * =============================================================================
226
 
 */
227
 
/*!
228
 
 * Message priority
229
 
 */
230
 
enum messageq_priority {
231
 
        MESSAGEQ_NORMALPRI = 0,
232
 
        /*!< Normal priority message */
233
 
        MESSAGEQ_HIGHPRI = 1,
234
 
        /*!< High priority message */
235
 
        MESSAGEQ_RESERVEDPRI = 2,
236
 
        /*!< Reserved value for message priority */
237
 
        MESSAGEQ_URGENTPRI = 3
238
 
        /*!< Urgent priority message */
239
 
};
240
 
 
241
 
/*! Structure which defines the first field in every message */
242
 
struct msgheader {
243
 
        u32 reserved0;
244
 
        /*!< Reserved field */
245
 
        u32 reserved1;
246
 
        /*!< Reserved field */
247
 
        u32 msg_size;
248
 
        /*!< Size of the message (including header) */
249
 
        u16 flags;
250
 
        /*!< Flags */
251
 
        u16 msg_id;
252
 
        /*!< Maximum length for Message queue names */
253
 
        u16 dst_id;
254
 
        /*!< Maximum length for Message queue names */
255
 
        u16 dst_proc;
256
 
        /*!< Maximum length for Message queue names */
257
 
        u16 reply_id;
258
 
        /*!< Maximum length for Message queue names */
259
 
        u16 reply_proc;
260
 
        /*!< Maximum length for Message queue names */
261
 
        u16 src_proc;
262
 
        /*!< Maximum length for Message queue names */
263
 
        u16 heap_id;
264
 
        /*!< Maximum length for Message queue names */
265
 
        u16 seq_num;
266
 
        /*!< sequence number */
267
 
        u32 reserved;
268
 
        /*!< Reserved field */
269
 
};
270
 
 
271
 
/*! Structure which defines the first field in every message */
272
 
#define messageq_msg    struct msgheader *
273
 
/*typedef struct msgheader *messageq_msg;*/
274
 
 
275
 
 
276
 
/*!
277
 
 *  @brief      Structure defining config parameters for the MessageQ Buf module.
278
 
 */
279
 
struct messageq_config {
280
 
        bool trace_flag;
281
 
        /*!< Trace Flag
282
 
        *  This flag allows the configuration of the default module trace
283
 
        *  settings.
284
 
        */
285
 
 
286
 
        u16 num_heaps;
287
 
        /*!< Number of heapIds in the system
288
 
        *  This allows MessageQ to pre-allocate the heaps table.
289
 
        *  The heaps table is used when registering heaps.
290
 
        *  The default is 1 since generally all systems need at least one heap.
291
 
        *  There is no default heap, so unless the system is only using
292
 
        *  staticMsgInit, the application must register a heap.
293
 
        */
294
 
 
295
 
        u32 max_runtime_entries;
296
 
        /*!
297
 
        *  Maximum number of MessageQs that can be dynamically created
298
 
        */
299
 
 
300
 
        u32 max_name_len;
301
 
        /*!< Maximum length for Message queue names */
302
 
};
303
 
 
304
 
struct messageq_params {
305
 
        void *synchronizer;
306
 
        /*!< Synchronizer instance used to signal IO completion
307
 
        *
308
 
        * The synchronizer is used in the #MessageQ_put and #MessageQ_get calls.
309
 
        * The synchronizer signal is called as part of the #MessageQ_put call.
310
 
        * The synchronizer waits in the #MessageQ_get if there are no messages
311
 
        * present.
312
 
        */
313
 
};
314
 
 
315
 
/* =============================================================================
316
 
 *  APIs
317
 
 * =============================================================================
318
 
 */
319
 
/* Functions to get the configuration for messageq setup */
320
 
void messageq_get_config(struct messageq_config *cfg);
321
 
 
322
 
/* Function to setup the MessageQ module. */
323
 
int messageq_setup(const struct messageq_config *cfg);
324
 
 
325
 
/* Function to destroy the MessageQ module. */
326
 
int messageq_destroy(void);
327
 
 
328
 
/* Returns the amount of shared memory used by one transport instance.
329
 
 *
330
 
 *  The MessageQ module itself does not use any shared memory but the
331
 
 *  underlying transport may use some shared memory.
332
 
 */
333
 
uint messageq_shared_mem_req(void *shared_addr);
334
 
 
335
 
/* Calls the SetupProxy function to setup the MessageQ transports. */
336
 
int messageq_attach(u16 remote_proc_id, void *shared_addr);
337
 
 
338
 
/* Calls the SetupProxy function to detach the MessageQ transports. */
339
 
int messageq_detach(u16 remote_proc_id);
340
 
 
341
 
/* Initialize this config-params structure with supplier-specified
342
 
 * defaults before instance creation.
343
 
 */
344
 
void messageq_params_init(struct messageq_params *params);
345
 
 
346
 
/* Create a message queue */
347
 
void *messageq_create(char *name, const struct messageq_params *params);
348
 
 
349
 
/* Deletes a instance of MessageQ module. */
350
 
int messageq_delete(void **messageq_handleptr);
351
 
 
352
 
/* Open a message queue */
353
 
int messageq_open(char *name, u32 *queue_id);
354
 
 
355
 
/* Close an opened message queue handle */
356
 
int messageq_close(u32 *queue_id);
357
 
 
358
 
/* Allocates a message from the heap */
359
 
messageq_msg messageq_alloc(u16 heapId, u32 size);
360
 
 
361
 
/* Frees a message back to the heap */
362
 
int messageq_free(messageq_msg msg);
363
 
 
364
 
/* Initializes a message not obtained from MessageQ_alloc */
365
 
void messageq_static_msg_init(messageq_msg msg, u32 size);
366
 
 
367
 
/* Place a message onto a message queue */
368
 
int messageq_put(u32 queueId, messageq_msg msg);
369
 
 
370
 
/* Gets a message for a message queue and blocks if the queue is empty */
371
 
int messageq_get(void *messageq_handle, messageq_msg *msg, u32 timeout);
372
 
 
373
 
/* Register a heap with MessageQ */
374
 
int messageq_register_heap(void *heap_handle, u16 heap_id);
375
 
 
376
 
/* Unregister a heap with MessageQ */
377
 
int messageq_unregister_heap(u16 heapId);
378
 
 
379
 
/* Returns the number of messages in a message queue */
380
 
int messageq_count(void *messageq_handle);
381
 
 
382
 
/* Get the proc Id of the message. */
383
 
u16 messageq_get_proc_id(void *messageq_handle);
384
 
 
385
 
/* Get the queue Id of the message. */
386
 
u32 messageq_get_queue_id(void *messageq_handle);
387
 
 
388
 
/* Set the destination queue of the message. */
389
 
void messageq_set_reply_queue(void *messageq_handle, messageq_msg msg);
390
 
 
391
 
/* Set the tracing of a message */
392
 
void messageq_set_msg_trace(messageq_msg msg, bool trace_flag);
393
 
 
394
 
/*
395
 
 *  Functions to set Message properties
396
 
 */
397
 
/*!
398
 
 *  @brief   Returns the MessageQ_Queue handle of the destination
399
 
 *           message queue for the specified message.
400
 
 */
401
 
u32 messageq_get_dst_queue(messageq_msg msg);
402
 
 
403
 
/*!
404
 
 *  @brief   Returns the message ID of the specified message.
405
 
 */
406
 
u16 messageq_get_msg_id(messageq_msg msg);
407
 
 
408
 
/*!
409
 
 *  @brief   Returns the size of the specified message.
410
 
 */
411
 
u32 messageq_get_msg_size(messageq_msg msg);
412
 
 
413
 
/*!
414
 
 *  @brief      Gets the message priority of a message
415
 
 */
416
 
u32 messageq_get_msg_pri(messageq_msg msg);
417
 
 
418
 
/*!
419
 
 *  @brief   Returns the MessageQ_Queue handle of the destination
420
 
 *           message queue for the specified message.
421
 
 */
422
 
u32 messageq_get_reply_queue(messageq_msg msg);
423
 
 
424
 
/*!
425
 
 *  @brief   Sets the message ID in the specified message.
426
 
 */
427
 
void messageq_set_msg_id(messageq_msg msg, u16 msg_id);
428
 
/*!
429
 
 *  @brief   Sets the message priority in the specified message.
430
 
 */
431
 
void messageq_set_msg_pri(messageq_msg msg, u32 priority);
432
 
 
433
 
/* =============================================================================
434
 
 *  APIs called internally by MessageQ transports
435
 
 * =============================================================================
436
 
 */
437
 
/* Register a transport with MessageQ */
438
 
int messageq_register_transport(void *imessageq_transport_handle,
439
 
                                        u16 proc_id, u32 priority);
440
 
 
441
 
/* Unregister a transport with MessageQ */
442
 
void messageq_unregister_transport(u16 proc_id, u32 priority);
443
 
 
444
 
/* Unblock messageq to prevent waiting forever */
445
 
int messageq_unblock(void *messageq_handle);
446
 
 
447
 
#endif /* _MESSAGEQ_H_ */