common/shm.h

   1 /* This module provides a set of abstract shared memory interfaces
   2  * with support using both System V and POSIX shared memory
   3  * implementations.  The code is divided into three sections:
   4  *
   5  *      - common (interface-independent) code
   6  *      - POSIX implementation
   7  *      - System V implementation
   8  *  - Windows implementation
   9  *
  10  * The implementation used is determined by whether USE_POSIX_SHM was
  11  * set in the ./configure step.
  12  */
  13
  14 /*
  15  Copyright (C) 2001-2003 Paul Davis
  16  Copyright (C) 2005-2012 Grame
  17
  18  This program is free software; you can redistribute it and/or modify
  19  it under the terms of the GNU Lesser General Public License as published by
  20  the Free Software Foundation; either version 2.1 of the License, or
  21  (at your option) any later version.
  22
  23  This program is distributed in the hope that it will be useful,
  24  but WITHOUT ANY WARRANTY; without even the implied warranty of
  25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  26  GNU Lesser General Public License for more details.
  27
  28  You should have received a copy of the GNU Lesser General Public License
  29  along with this program; if not, write to the Free Software
  30  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  31
  32  */
  33
  34 #ifndef __jack_shm_h__
  35 #define __jack_shm_h__
  36
  37 #include <limits.h>
  38 #include <sys/types.h>
  39 #include "types.h"
  40 #include "JackCompilerDeps.h"
  41 #include "JackConstants.h"
  42
  43 #define TRUE 1
  44 #define FALSE 0
  45
  46 #ifdef __cplusplus
  47 extern "C"
  48 {
  49 #endif
  50
  51 #define MAX_SERVERS 8               /* maximum concurrent servers */
  52 #define MAX_SHM_ID 256              /* generally about 16 per server */
  53 #define JACK_SHM_MAGIC 0x4a41434b       /* shm magic number: "JACK" */
  54 #define JACK_SHM_NULL_INDEX -1          /* NULL SHM index */
  55 #define JACK_SHM_REGISTRY_INDEX -2      /* pseudo SHM index for registry */
  56
  57
  58     /* On Mac OS X, SHM_NAME_MAX is the maximum length of a shared memory
  59      * segment name (instead of NAME_MAX or PATH_MAX as defined by the
  60      * standard).
  61      */
  62 #ifdef USE_POSIX_SHM
  63
  64 #ifndef NAME_MAX
  65 #define NAME_MAX 255
  66 #endif
  67
  68 #ifndef SHM_NAME_MAX
  69 #define SHM_NAME_MAX NAME_MAX
  70 #endif
  71     typedef char shm_name_t[SHM_NAME_MAX];
  72     typedef shm_name_t jack_shm_id_t;
  73
  74 #elif WIN32
  75 #define NAME_MAX 255
  76 #ifndef SHM_NAME_MAX
  77 #define SHM_NAME_MAX NAME_MAX
  78 #endif
  79     typedef char shm_name_t[SHM_NAME_MAX];
  80     typedef shm_name_t jack_shm_id_t;
  81
  82 #elif __ANDROID__
  83
  84 #ifndef NAME_MAX
  85 #define NAME_MAX 255
  86 #endif
  87
  88 #ifndef SHM_NAME_MAX
  89 #define SHM_NAME_MAX NAME_MAX
  90 #endif
  91     typedef char shm_name_t[SHM_NAME_MAX];
  92     typedef shm_name_t jack_shm_id_t;
  93     typedef int jack_shm_fd_t;
  94
  95 #else
  96     /* System V SHM */
  97     typedef int jack_shm_id_t;
  98 #endif /* SHM type */
  99
 100     /* shared memory type */
 101     typedef enum {
 102         shm_POSIX = 1,                  /* POSIX shared memory */
 103         shm_SYSV = 2,                   /* System V shared memory */
 104         shm_WIN32 = 3,                  /* Windows 32 shared memory */
 105         shm_ANDROID = 4                 /* Android shared memory */
 106     } jack_shmtype_t;
 107
 108     typedef int16_t jack_shm_registry_index_t;
 109
 110     /**
 111      * A structure holding information about shared memory allocated by
 112      * JACK. this persists across invocations of JACK, and can be used by
 113      * multiple JACK servers.  It contains no pointers and is valid across
 114      * address spaces.
 115      *
 116      * The registry consists of two parts: a header including an array of
 117      * server names, followed by an array of segment registry entries.
 118      */
 119     typedef struct _jack_shm_server {
 120 #ifdef WIN32
 121         int     pid;    /* process ID */
 122 #else
 123         pid_t pid;      /* process ID */
 124 #endif
 125
 126         char    name[JACK_SERVER_NAME_SIZE+1];
 127     }
 128     jack_shm_server_t;
 129
 130     typedef struct _jack_shm_header {
 131         uint32_t        magic;  /* magic number */
 132         uint16_t        protocol;       /* JACK protocol version */
 133         jack_shmtype_t  type;   /* shm type */
 134         jack_shmsize_t  size;   /* total registry segment size */
 135         jack_shmsize_t  hdr_len;        /* size of header */
 136         jack_shmsize_t  entry_len; /* size of registry entry */
 137         jack_shm_server_t server[MAX_SERVERS]; /* current server array */
 138     }
 139     jack_shm_header_t;
 140
 141     typedef struct _jack_shm_registry {
 142         jack_shm_registry_index_t index;     /* offset into the registry */
 143
 144 #ifdef WIN32
 145         int     allocator; /* PID that created shm segment */
 146 #else
 147         pid_t allocator; /* PID that created shm segment */
 148 #endif
 149
 150         jack_shmsize_t size;      /* for POSIX unattach */
 151         jack_shm_id_t id;        /* API specific, see above */
 152 #ifdef __ANDROID__
 153         jack_shm_fd_t fd;
 154 #endif
 155     }
 156     jack_shm_registry_t;
 157
 158 #define JACK_SHM_REGISTRY_SIZE (sizeof (jack_shm_header_t) \
 159                                 + sizeof (jack_shm_registry_t) * MAX_SHM_ID)
 160
 161     /**
 162      * a structure holding information about shared memory
 163      * allocated by JACK. this version is valid only
 164      * for a given address space. It contains a pointer
 165      * indicating where the shared memory has been
 166      * attached to the address space.
 167      */
 168
 169     PRE_PACKED_STRUCTURE
 170     struct _jack_shm_info {
 171         jack_shm_registry_index_t index;       /* offset into the registry */
 172         uint32_t size;
 173 #ifdef __ANDROID__
 174         jack_shm_fd_t fd;
 175 #endif
 176         union {
 177             void *attached_at;  /* address where attached */
 178             char ptr_size[8];
 179         } ptr;  /* a "pointer" that has the same 8 bytes size when compiling in 32 or 64 bits */
 180     } POST_PACKED_STRUCTURE;
 181
 182     typedef struct _jack_shm_info jack_shm_info_t;
 183
 184     /* utility functions used only within JACK */
 185
 186     void jack_shm_copy_from_registry (jack_shm_info_t*,
 187                 jack_shm_registry_index_t);
 188     void jack_shm_copy_to_registry (jack_shm_info_t*,
 189                                                jack_shm_registry_index_t*);
 190     int jack_release_shm_info (jack_shm_registry_index_t);
 191     char* jack_shm_addr (jack_shm_info_t* si);
 192
 193     /* here begin the API */
 194     int jack_register_server (const char *server_name, int new_registry);
 195     int jack_unregister_server (const char *server_name);
 196
 197     int jack_initialize_shm (const char *server_name);
 198     int jack_initialize_shm_server (void);
 199     int jack_initialize_shm_client (void);
 200     int jack_cleanup_shm (void);
 201
 202     int jack_shmalloc (const char *shm_name, jack_shmsize_t size,
 203                                   jack_shm_info_t* result);
 204     void jack_release_shm (jack_shm_info_t*);
 205     void jack_release_lib_shm (jack_shm_info_t*);
 206     void jack_destroy_shm (jack_shm_info_t*);
 207     int jack_attach_shm (jack_shm_info_t*);
 208     int jack_attach_lib_shm (jack_shm_info_t*);
 209     int jack_attach_shm_read (jack_shm_info_t*);
 210     int jack_attach_lib_shm_read (jack_shm_info_t*);
 211     int jack_resize_shm (jack_shm_info_t*, jack_shmsize_t size);
 212
 213 #ifdef __cplusplus
 214 }
 215 #endif
 216
 217 #endif /* __jack_shm_h__ */