l4/pkg/shmc/include/shmc.h

   1 /**
   2  * \file
   3  * Shared memory library header file.
   4  */
   5 /*
   6  * (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
   7  *               Björn Döbel <doebel@os.inf.tu-dresden.de>
   8  *     economic rights: Technische Universität Dresden (Germany)
   9  * This file is part of TUD:OS and distributed under the terms of the
  10  * GNU Lesser General Public License 2.1.
  11  * Please see the COPYING-LGPL-2.1 file for details.
  12  */
  13 #pragma once
  14
  15 #include <l4/sys/linkage.h>
  16 #include <l4/sys/types.h>
  17 #include <l4/sys/err.h>
  18
  19 /**
  20  * \defgroup api_l4shm Shared Memory Library
  21  *
  22  * L4SHM provides a shared memory infrastructure that establishes a
  23  * shared memory area between multiple parties and uses a fast notification
  24  * mechanism.
  25  *
  26  * A shared memory area consists of chunks and signals. A chunk is a
  27  * defined chunk of memory within the memory area with a maximum size. A
  28  * chunk is filled (written) by a producer and read by a consumer. When a
  29  * producer has finished writing to the chunk it signals a data ready
  30  * notification to the consumer.
  31  *
  32  * A consumer attaches to a chunk and waits for the producer to fill the
  33  * chunk. After reading out the chunk it marks the chunk free again.
  34  *
  35  * A shared memory area can have multiple chunks.
  36  *
  37  * The interface is divided in three roles.
  38  * - The master role, responsible for setting up a shared memory area.
  39  * - A producer, generating data into a chunk
  40  * - A consumer, receiving data.
  41  *
  42  * A signal can be connected with a chunk or can be used independently
  43  * (e.g. for multiple chunks).
  44  *
  45  * \example examples/libs/shmc/prodcons.c
  46  * Simple shared memory example.
  47  *
  48  */
  49 /**
  50  * \defgroup api_l4shmc_chunk Chunks
  51  * \ingroup api_l4shm
  52  *
  53  * \defgroup api_l4shmc_chunk_prod Producer
  54  * \ingroup api_l4shmc_chunk
  55  *
  56  * \defgroup api_l4shmc_chunk_cons Consumer
  57  * \ingroup api_l4shmc_chunk
  58  *
  59  * \defgroup api_l4shmc_signal Signals
  60  * \ingroup api_l4shm
  61  *
  62  * \defgroup api_l4shmc_signal_prod Producer
  63  * \ingroup api_l4shmc_signal
  64  *
  65  * \defgroup api_l4shmc_signal_cons Consumer
  66  * \ingroup api_l4shmc_signal
  67  */
  68
  69 #define __INCLUDED_FROM_L4SHMC_H__
  70 #include <l4/shmc/types.h>
  71
  72 __BEGIN_DECLS
  73
  74 /**
  75  * Create a shared memory area.
  76  * \ingroup api_l4shm
  77  *
  78  * \param shmc_name  Name of the shared memory area.
  79  * \param shm_size   Size of the whole shared memory area.
  80  *
  81  * \retval 0   Success.
  82  * \retval <0  Error.
  83  */
  84 L4_CV long
  85 l4shmc_create(const char *shmc_name, l4_umword_t shm_size);
  86
  87 /**
  88  * Attach to a shared memory area.
  89  * \ingroup api_l4shm
  90  *
  91  * \param      shmc_name  Name of the shared memory area.
  92  * \param[out] shmarea    Pointer to shared memory area descriptor to be filled
  93  *                        with information for the shared memory area.
  94  *
  95  * \retval 0   Success.
  96  * \retval <0  Error.
  97  */
  98 L4_CV L4_INLINE long
  99 l4shmc_attach(const char *shmc_name, l4shmc_area_t *shmarea);
 100
 101 /**
 102  * Attach to a shared memory area, with limited waiting.
 103  * \ingroup api_l4shm
 104  *
 105  * \param      shmc_name   Name of the shared memory area.
 106  * \param      timeout_ms  Timeout to wait for shm area in milliseconds.
 107  * \param[out] shmarea     Pointer to shared memory area descriptor to be
 108  *                         filled with information for the shared memory area.
 109  *
 110  * \retval 0   Success.
 111  * \retval <0  Error.
 112  */
 113 L4_CV long
 114 l4shmc_attach_to(const char *shmc_name, l4_umword_t timeout_ms,
 115                  l4shmc_area_t *shmarea);
 116
 117 /**
 118  * Add a chunk in the shared memory area.
 119  * \ingroup api_l4shmc_chunk
 120  *
 121  * \param      shmarea         The shared memory area to put the chunk in.
 122  * \param      chunk_name      Name of the chunk.
 123  * \param      chunk_capacity  Capacity for payload of the chunk in bytes.
 124  * \param[out] chunk           Chunk structure to fill in.
 125  *
 126  * \retval 0   Success.
 127  * \retval <0  Error.
 128  */
 129 L4_CV long
 130 l4shmc_add_chunk(l4shmc_area_t *shmarea,
 131                  const char *chunk_name,
 132                  l4_umword_t chunk_capacity,
 133                  l4shmc_chunk_t *chunk);
 134
 135 /**
 136  * Add a signal for the shared memory area.
 137  * \ingroup api_l4shmc_signal
 138  *
 139  * \param      shmarea      The shared memory area to put the chunk in.
 140  * \param      signal_name  Name of the signal.
 141  * \param[out] signal       Signal structure to fill in.
 142  *
 143  * \retval 0   Success.
 144  * \retval <0  Error.
 145  */
 146 L4_CV long
 147 l4shmc_add_signal(l4shmc_area_t *shmarea,
 148                   const char *signal_name,
 149                   l4shmc_signal_t *signal);
 150
 151 /**
 152  * Trigger a signal.
 153  * \ingroup api_l4shmc_signal_prod
 154  *
 155  * \param signal  Signal to trigger.
 156  *
 157  * \retval 0   Success.
 158  * \retval <0  Error.
 159  */
 160 L4_CV L4_INLINE long
 161 l4shmc_trigger(l4shmc_signal_t *signal);
 162
 163 /**
 164  * Try to mark chunk busy.
 165  * \ingroup api_l4shmc_chunk_prod
 166  *
 167  * \param chunk  chunk to mark.
 168  *
 169  * \retval 0   Chunk could be taken.
 170  * \retval <0  Chunk could not be taken, try again.
 171  */
 172 L4_CV L4_INLINE long
 173 l4shmc_chunk_try_to_take(l4shmc_chunk_t *chunk);
 174
 175 /**
 176  * Mark chunk as filled (ready).
 177  * \ingroup api_l4shmc_chunk_prod
 178  *
 179  * \param chunk  chunk.
 180  * \param size   Size of data in the chunk, in bytes.
 181  *
 182  * \retval 0   Success.
 183  * \retval <0  Error.
 184  */
 185 L4_CV L4_INLINE long
 186 l4shmc_chunk_ready(l4shmc_chunk_t *chunk, l4_umword_t size);
 187
 188 /**
 189  * Mark chunk as filled (ready) and signal consumer.
 190  * \ingroup api_l4shmc_chunk_prod
 191  *
 192  * \param chunk  chunk.
 193  * \param size   Size of data in the chunk, in bytes.
 194  *
 195  * \retval 0   Success.
 196  * \retval <0  Error.
 197  */
 198 L4_CV L4_INLINE long
 199 l4shmc_chunk_ready_sig(l4shmc_chunk_t *chunk, l4_umword_t size);
 200
 201 /**
 202  * Get chunk out of shared memory area.
 203  * \ingroup api_l4shmc_chunk
 204  *
 205  * \param      shmarea     Shared memory area.
 206  * \param      chunk_name  Name of the chunk.
 207  * \param[out] chunk       Chunk data structure to fill.
 208  *
 209  * \retval 0   Success.
 210  * \retval <0  Error.
 211  */
 212 L4_CV L4_INLINE long
 213 l4shmc_get_chunk(l4shmc_area_t *shmarea,
 214                  const char *chunk_name,
 215                  l4shmc_chunk_t *chunk);
 216
 217 /**
 218  * Get chunk out of shared memory area, with timeout.
 219  * \ingroup api_l4shmc_chunk
 220  *
 221  * \param      shmarea     Shared memory area.
 222  * \param      chunk_name  Name of the chunk.
 223  * \param      timeout_ms  Timeout in milliseconds to wait for the chunk to appear
 224  *                         in the shared memory area.
 225  * \param[out] chunk       Chunk data structure to fill.
 226  *
 227  * \retval 0   Success.
 228  * \retval <0  Error.
 229  */
 230 L4_CV long
 231 l4shmc_get_chunk_to(l4shmc_area_t *shmarea,
 232                     const char *chunk_name,
 233                     l4_umword_t timeout_ms,
 234                     l4shmc_chunk_t *chunk);
 235
 236 /**
 237  * Iterate over names of all existing chunks
 238  * \ingroup api_l4shmc_chunk
 239  *
 240  * \param shmarea     Shared memory area.
 241  * \param chunk_name  Where the name of the current chunk will be stored
 242  * \param offs        0 to start iteration, return value of previous
 243  *                    call to l4shmc_iterate_chunk() to get next chunk
 244  *
 245  * \retval 0   No more chunks available.
 246  * \retval <0  Error.
 247  * \retval >0  Iterator value for the next call.
 248  */
 249 L4_CV long
 250 l4shmc_iterate_chunk(l4shmc_area_t *shmarea, const char **chunk_name,
 251                      long offs);
 252
 253 /**
 254  * Attach to signal.
 255  * \ingroup api_l4shmc_signal
 256  *
 257  * \param      shmarea      Shared memory area.
 258  * \param      signal_name  Name of the signal.
 259  * \param      thread       Thread capability index to attach the signal to.
 260  * \param[out] signal       Signal data structure to fill.
 261  *
 262  * \retval 0   Success.
 263  * \retval <0  Error.
 264  */
 265 L4_CV L4_INLINE long
 266 l4shmc_attach_signal(l4shmc_area_t *shmarea,
 267                      const char *signal_name,
 268                      l4_cap_idx_t thread,
 269                      l4shmc_signal_t *signal);
 270
 271 /**
 272  * Attach to signal, with timeout.
 273  * \ingroup api_l4shmc_signal
 274  *
 275  * \param shmarea      Shared memory area.
 276  * \param signal_name  Name of the signal.
 277  * \param thread       Thread capability index to attach the signal to.
 278  * \param timeout_ms   Timeout in milliseconds to wait for the chunk to appear
 279  *                     in the shared memory area.
 280  * \param[out] signal  Signal data structure to fill.
 281  *
 282  * \retval 0   Success.
 283  * \retval <0  Error.
 284  */
 285 L4_CV long
 286 l4shmc_attach_signal_to(l4shmc_area_t *shmarea,
 287                         const char *signal_name,
 288                         l4_cap_idx_t thread,
 289                         l4_umword_t timeout_ms,
 290                         l4shmc_signal_t *signal);
 291
 292 /**
 293  * Get signal object from the shared memory area.
 294  * \ingroup api_l4shmc_signal
 295  *
 296  * \param shmarea      Shared memory area.
 297  * \param signal_name  Name of the signal.
 298  * \param timeout_ms   Timeout in milliseconds to wait for signal of a chunk
 299  *                     to appear in the shared memory area.
 300  * \param[out] signal  Signal data structure to fill.
 301  *
 302  * \retval 0   Success.
 303  * \retval <0  Error.
 304  */
 305 L4_CV long
 306 l4shmc_get_signal_to(l4shmc_area_t *shmarea,
 307                      const char *signal_name,
 308                      l4_umword_t timeout_ms,
 309                      l4shmc_signal_t *signal);
 310
 311 L4_CV L4_INLINE long
 312 l4shmc_get_signal(l4shmc_area_t *shmarea,
 313                   const char *signal_name,
 314                   l4shmc_signal_t *signal);
 315
 316
 317 /**
 318  * Enable a signal.
 319  * \ingroup api_l4shmc_signal_cons
 320  *
 321  * \param signal  Signal to enable.
 322  *
 323  * \retval 0   Success.
 324  * \retval <0  Error.
 325  *
 326  * A signal must be enabled before waiting when the consumer waits on any
 327  * signal. Enabling is not needed if the consumer waits for a specific
 328  * signal or chunk.
 329  */
 330 L4_CV long
 331 l4shmc_enable_signal(l4shmc_signal_t *signal);
 332
 333 /**
 334  * Enable a signal connected with a chunk.
 335  * \ingroup api_l4shmc_chunk_cons
 336  *
 337  * \param chunk  Chunk to enable.
 338  *
 339  * \retval 0   Success.
 340  * \retval <0  Error.
 341  *
 342  * A signal must be enabled before waiting when the consumer waits on any
 343  * signal. Enabling is not needed if the consumer waits for a specific
 344  * signal or chunk.
 345  */
 346 L4_CV long
 347 l4shmc_enable_chunk(l4shmc_chunk_t *chunk);
 348
 349 /**
 350  * Wait on any signal.
 351  * \ingroup api_l4shmc_signal_cons
 352  *
 353  * \param[out] retsignal  Signal received.
 354  *
 355  * \retval 0   Success.
 356  * \retval <0  Error.
 357  */
 358 L4_CV L4_INLINE long
 359 l4shmc_wait_any(l4shmc_signal_t **retsignal);
 360
 361 /**
 362  * Check whether any waited signal has an event pending.
 363  * \ingroup api_l4shmc_signal_cons
 364  *
 365  * \param[out] retsignal  Signal that has the event pending if any.
 366  *
 367  * \retval 0   Success.
 368  * \retval <0  Error.
 369  *
 370  * The return code indicates whether an event was pending or not. Success
 371  * means an event was pending, if an receive timeout error is returned no
 372  * event was pending.
 373  */
 374 L4_CV L4_INLINE long
 375 l4shmc_wait_any_try(l4shmc_signal_t **retsignal);
 376
 377 /**
 378  * Wait for any signal with timeout.
 379  * \ingroup api_l4shmc_signal_cons
 380  *
 381  * \param      timeout    Timeout.
 382  * \param[out] retsignal  Signal that has the event pending if any.
 383  *
 384  * \retval 0   Success.
 385  * \retval <0  Error.
 386  *
 387  * The return code indicates whether an event was pending or not. Success
 388  * means an event was pending, if an receive timeout error is returned no
 389  * event was pending.
 390  */
 391 L4_CV long
 392 l4shmc_wait_any_to(l4_timeout_t timeout, l4shmc_signal_t **retsignal);
 393
 394 /**
 395  * Wait on a specific signal.
 396  * \ingroup api_l4shmc_signal_cons
 397  *
 398  * \param signal  Signal to wait for.
 399  *
 400  * \retval 0   Success.
 401  * \retval <0  Error.
 402  */
 403 L4_CV L4_INLINE long
 404 l4shmc_wait_signal(l4shmc_signal_t *signal);
 405
 406 /**
 407  * Wait on a specific signal, with timeout.
 408  * \ingroup api_l4shmc_signal_cons
 409  *
 410  * \param signal   Signal to wait for.
 411  * \param timeout  Timeout.
 412  *
 413  * \retval 0   Success.
 414  * \retval <0  Error.
 415  */
 416 L4_CV long
 417 l4shmc_wait_signal_to(l4shmc_signal_t *signal, l4_timeout_t timeout);
 418
 419 /**
 420  * Check whether a specific signal has an event pending.
 421  * \ingroup api_l4shmc_signal_cons
 422  *
 423  * \param signal  Signal to check.
 424  *
 425  * \retval 0   Success.
 426  * \retval <0  Error.
 427  *
 428  * The return code indicates whether an event was pending or not. Success
 429  * means an event was pending, if an receive timeout error is returned no
 430  * event was pending.
 431  */
 432 L4_CV L4_INLINE long
 433 l4shmc_wait_signal_try(l4shmc_signal_t *signal);
 434
 435 /**
 436  * Wait on a specific chunk.
 437  * \ingroup api_l4shmc_chunk_cons
 438  *
 439  * \param chunk  Chunk to wait for.
 440  *
 441  * \retval 0   Success.
 442  * \retval <0  Error.
 443  */
 444 L4_CV L4_INLINE long
 445 l4shmc_wait_chunk(l4shmc_chunk_t *chunk);
 446
 447 /**
 448  * Check whether a specific chunk has an event pending, with timeout.
 449  * \ingroup api_l4shmc_chunk_cons
 450  *
 451  * \param chunk    Chunk to check.
 452  * \param timeout  Timeout.
 453  *
 454  * \retval 0   Success.
 455  * \retval <0  Error.
 456  *
 457  * The return code indicates whether an event was pending or not. Success
 458  * means an event was pending, if an receive timeout error is returned no
 459  * event was pending.
 460  */
 461 L4_CV long
 462 l4shmc_wait_chunk_to(l4shmc_chunk_t *chunk, l4_timeout_t timeout);
 463
 464 /**
 465  * Check whether a specific chunk has an event pending.
 466  * \ingroup api_l4shmc_chunk_cons
 467  *
 468  * \param chunk  Chunk to check.
 469  *
 470  * \retval 0   Success.
 471  * \retval <0  Error.
 472  *
 473  * The return code indicates whether an event was pending or not. Success
 474  * means an event was pending, if an receive timeout error is returned no
 475  * event was pending.
 476  */
 477 L4_CV L4_INLINE long
 478 l4shmc_wait_chunk_try(l4shmc_chunk_t *chunk);
 479
 480 /**
 481  * Mark a chunk as free.
 482  * \ingroup api_l4shmc_chunk_cons
 483  *
 484  * \param chunk  Chunk to mark as free.
 485  *
 486  * \retval 0   Success.
 487  * \retval <0  Error.
 488  */
 489 L4_CV L4_INLINE long
 490 l4shmc_chunk_consumed(l4shmc_chunk_t *chunk);
 491
 492 /**
 493  * Connect a signal with a chunk.
 494  * \ingroup api_l4shm
 495  *
 496  * \param chunk   Chunk to attach the signal to.
 497  * \param signal  Signal to attach.
 498  *
 499  * \return 0 on success, <0 on error
 500  */
 501 L4_CV long
 502 l4shmc_connect_chunk_signal(l4shmc_chunk_t *chunk,
 503                             l4shmc_signal_t *signal);
 504
 505 /**
 506  * Check whether data is available.
 507  * \ingroup api_l4shmc_chunk_cons
 508  *
 509  * \param chunk  Chunk to check.
 510  *
 511  * \retval 0   Success.
 512  * \retval <0  Error.
 513  */
 514 L4_CV L4_INLINE long
 515 l4shmc_is_chunk_ready(l4shmc_chunk_t *chunk);
 516
 517 /**
 518  * Check whether chunk is free.
 519  * \ingroup api_l4shmc_chunk_prod
 520  *
 521  * \param chunk  Chunk to check.
 522  *
 523  * \retval 0   Success.
 524  * \retval <0  Error.
 525  */
 526 L4_CV L4_INLINE long
 527 l4shmc_is_chunk_clear(l4shmc_chunk_t *chunk);
 528
 529 /**
 530  * Get data pointer to chunk.
 531  * \ingroup api_l4shmc_chunk
 532  *
 533  * \param chunk  Chunk.
 534  *
 535  * \retval 0   Success.
 536  * \retval <0  Error.
 537  */
 538 L4_CV L4_INLINE void *
 539 l4shmc_chunk_ptr(l4shmc_chunk_t *chunk);
 540
 541 /**
 542  * Get current size of a chunk.
 543  * \ingroup api_l4shmc_chunk_cons
 544  *
 545  * \param chunk  Chunk.
 546  *
 547  * \retval 0   Success.
 548  * \retval <0  Error.
 549  */
 550 L4_CV L4_INLINE long
 551 l4shmc_chunk_size(l4shmc_chunk_t *chunk);
 552
 553 /**
 554  * Get capacity of a chunk.
 555  * \ingroup api_l4shmc_chunk
 556  *
 557  * \param chunk  Chunk.
 558  *
 559  * \retval 0   Success.
 560  * \retval <0  Error.
 561  */
 562 L4_CV L4_INLINE long
 563 l4shmc_chunk_capacity(l4shmc_chunk_t *chunk);
 564
 565 /**
 566  * Get the signal of a chunk.
 567  * \ingroup api_l4shmc_chunk
 568  *
 569  * \param chunk  Chunk.
 570  *
 571  * \retval 0  No signal has been registered with this chunk.
 572  * \retval >0 Pointer to signal otherwise.
 573  */
 574 L4_CV L4_INLINE l4shmc_signal_t *
 575 l4shmc_chunk_signal(l4shmc_chunk_t *chunk);
 576
 577 /**
 578  * Get the signal capability of a signal.
 579  * \ingroup api_l4shmc_signal
 580  *
 581  * \param signal  Signal.
 582  *
 583  * \return Capability of the signal object.
 584  */
 585 L4_CV L4_INLINE l4_cap_idx_t
 586 l4shmc_signal_cap(l4shmc_signal_t *signal);
 587
 588 /**
 589  * Check magic value of a chunk.
 590  * \ingroup api_l4shmc_signal
 591  *
 592  * \param chunk  Chunk.
 593  *
 594  * \retval 0   Magic value is not valid.
 595  * \retval >0  Chunk is ok, the magic value is valid.
 596  */
 597 L4_CV L4_INLINE long
 598 l4shmc_check_magic(l4shmc_chunk_t *chunk);
 599
 600 /**
 601  * Get size of shared memory area.
 602  * \ingroup api_l4shm
 603  *
 604  * \param shmarea  Shared memory area.
 605  *
 606  * \retval >0  Size of the shared memory area.
 607  * \retval <0  Error.
 608  */
 609 L4_CV L4_INLINE long
 610 l4shmc_area_size(l4shmc_area_t *shmarea);
 611
 612 /**
 613  * Get free size of shared memory area. To get the max size to
 614  * pass to l4shmc_add_chunk, substract l4shmc_chunk_overhead().
 615  * \ingroup api_l4shm
 616  *
 617  * \param shmarea  Shared memory area.
 618  *
 619  * \retval 0   Free capacity in the area.
 620  * \retval <0  Error.
 621  *
 622  */
 623 L4_CV long
 624 l4shmc_area_size_free(l4shmc_area_t *shmarea);
 625
 626 /**
 627  * Get memory overhead per area that is not available for chunks
 628  * \ingroup api_l4shm
 629  *
 630  * \return size of the overhead in bytes
 631  */
 632 L4_CV long
 633 l4shmc_area_overhead(void);
 634
 635 /**
 636  * Get memory overhead required in addition to the chunk capacity
 637  * for adding one chunk
 638  * \ingroup api_l4shm
 639  *
 640  * \return size of the overhead in bytes
 641  */
 642 L4_CV long
 643 l4shmc_chunk_overhead(void);
 644
 645 #include <l4/shmc/internal.h>
 646
 647 __END_DECLS