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 #ifdef __APPLE__
 109     /* we need to align and pack data to 32bit so that x86_64 and arm64 work together */
 110     typedef int32_t jack_shm_registry_index_t;
 111 #else
 112     typedef int16_t jack_shm_registry_index_t;
 113 #endif
 114
 115     /**
 116      * A structure holding information about shared memory allocated by
 117      * JACK. this persists across invocations of JACK, and can be used by
 118      * multiple JACK servers.  It contains no pointers and is valid across
 119      * address spaces.
 120      *
 121      * The registry consists of two parts: a header including an array of
 122      * server names, followed by an array of segment registry entries.
 123      */
 124     typedef struct _jack_shm_server {
 125 #ifdef WIN32
 126         int     pid;    /* process ID */
 127 #else
 128         pid_t pid;      /* process ID */
 129 #endif
 130
 131         char    name[JACK_SERVER_NAME_SIZE+1];
 132     }
 133     jack_shm_server_t;
 134
 135     typedef struct _jack_shm_header {
 136         uint32_t        magic;  /* magic number */
 137         uint16_t        protocol;       /* JACK protocol version */
 138         jack_shmtype_t  type;   /* shm type */
 139         jack_shmsize_t  size;   /* total registry segment size */
 140         jack_shmsize_t  hdr_len;        /* size of header */
 141         jack_shmsize_t  entry_len; /* size of registry entry */
 142         jack_shm_server_t server[MAX_SERVERS]; /* current server array */
 143     }
 144     jack_shm_header_t;
 145
 146     typedef struct _jack_shm_registry {
 147         jack_shm_registry_index_t index;     /* offset into the registry */
 148
 149 #ifdef WIN32
 150         int     allocator; /* PID that created shm segment */
 151 #else
 152         pid_t allocator; /* PID that created shm segment */
 153 #endif
 154
 155         jack_shmsize_t size;      /* for POSIX unattach */
 156         jack_shm_id_t id;        /* API specific, see above */
 157 #ifdef __ANDROID__
 158         jack_shm_fd_t fd;
 159 #endif
 160     }
 161     jack_shm_registry_t;
 162
 163 #define JACK_SHM_REGISTRY_SIZE (sizeof (jack_shm_header_t) \
 164                                 + sizeof (jack_shm_registry_t) * MAX_SHM_ID)
 165
 166     /**
 167      * a structure holding information about shared memory
 168      * allocated by JACK. this version is valid only
 169      * for a given address space. It contains a pointer
 170      * indicating where the shared memory has been
 171      * attached to the address space.
 172      */
 173
 174     PRE_PACKED_STRUCTURE
 175     struct _jack_shm_info {
 176         jack_shm_registry_index_t index;       /* offset into the registry */
 177         uint32_t size;
 178 #ifdef __ANDROID__
 179         jack_shm_fd_t fd;
 180 #endif
 181         union {
 182             void *attached_at;  /* address where attached */
 183             char ptr_size[8];
 184         } ptr;  /* a "pointer" that has the same 8 bytes size when compiling in 32 or 64 bits */
 185     } POST_PACKED_STRUCTURE;
 186
 187     typedef struct _jack_shm_info jack_shm_info_t;
 188
 189     /* utility functions used only within JACK */
 190
 191     void jack_shm_copy_from_registry (jack_shm_info_t*,
 192                 jack_shm_registry_index_t);
 193     void jack_shm_copy_to_registry (jack_shm_info_t*,
 194                                                jack_shm_registry_index_t*);
 195     int jack_release_shm_info (jack_shm_registry_index_t);
 196     char* jack_shm_addr (jack_shm_info_t* si);
 197
 198     /* here begin the API */
 199     int jack_register_server (const char *server_name, int new_registry);
 200     int jack_unregister_server (const char *server_name);
 201
 202     int jack_initialize_shm (const char *server_name);
 203     int jack_initialize_shm_server (void);
 204     int jack_initialize_shm_client (void);
 205     int jack_cleanup_shm (void);
 206
 207     int jack_shmalloc (const char *shm_name, jack_shmsize_t size,
 208                                   jack_shm_info_t* result);
 209     void jack_release_shm (jack_shm_info_t*);
 210     void jack_release_lib_shm (jack_shm_info_t*);
 211     void jack_destroy_shm (jack_shm_info_t*);
 212     int jack_attach_shm (jack_shm_info_t*);
 213     int jack_attach_lib_shm (jack_shm_info_t*);
 214     int jack_attach_shm_read (jack_shm_info_t*);
 215     int jack_attach_lib_shm_read (jack_shm_info_t*);
 216     int jack_resize_shm (jack_shm_info_t*, jack_shmsize_t size);
 217
 218 #ifdef __cplusplus
 219 }
 220 #endif
 221
 222 #endif /* __jack_shm_h__ */