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
  42 #define TRUE 1
  43 #define FALSE 0
  44
  45 #ifdef __cplusplus
  46 extern "C"
  47 {
  48 #endif
  49
  50 #define MAX_SERVERS 8                   /* maximum concurrent servers */
  51 #define MAX_SHM_ID 256                  /* generally about 16 per server */
  52 #define JACK_SERVER_NAME_SIZE 256       /* maximum length of server name */
  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 #else
  83     /* System V SHM */
  84     typedef int jack_shm_id_t;
  85 #endif /* SHM type */
  86
  87     /* shared memory type */
  88     typedef enum {
  89         shm_POSIX = 1,                  /* POSIX shared memory */
  90         shm_SYSV = 2,                   /* System V shared memory */
  91         shm_WIN32 = 3                   /* Windows 32 shared memory */
  92     } jack_shmtype_t;
  93
  94     typedef int16_t jack_shm_registry_index_t;
  95
  96     /**
  97      * A structure holding information about shared memory allocated by
  98      * JACK. this persists across invocations of JACK, and can be used by
  99      * multiple JACK servers.  It contains no pointers and is valid across
 100      * address spaces.
 101      *
 102      * The registry consists of two parts: a header including an array of
 103      * server names, followed by an array of segment registry entries.
 104      */
 105     typedef struct _jack_shm_server {
 106 #ifdef WIN32
 107         int     pid;    /* process ID */
 108 #else
 109         pid_t pid;      /* process ID */
 110 #endif
 111
 112         char    name[JACK_SERVER_NAME_SIZE];
 113     }
 114     jack_shm_server_t;
 115
 116     typedef struct _jack_shm_header {
 117         uint32_t        magic;  /* magic number */
 118         uint16_t        protocol;       /* JACK protocol version */
 119         jack_shmtype_t  type;   /* shm type */
 120         jack_shmsize_t  size;   /* total registry segment size */
 121         jack_shmsize_t  hdr_len;        /* size of header */
 122         jack_shmsize_t  entry_len; /* size of registry entry */
 123         jack_shm_server_t server[MAX_SERVERS]; /* current server array */
 124     }
 125     jack_shm_header_t;
 126
 127     typedef struct _jack_shm_registry {
 128         jack_shm_registry_index_t index;     /* offset into the registry */
 129
 130 #ifdef WIN32
 131         int     allocator; /* PID that created shm segment */
 132 #else
 133         pid_t allocator; /* PID that created shm segment */
 134 #endif
 135
 136         jack_shmsize_t size;      /* for POSIX unattach */
 137         jack_shm_id_t id;        /* API specific, see above */
 138     }
 139     jack_shm_registry_t;
 140
 141 #define JACK_SHM_REGISTRY_SIZE (sizeof (jack_shm_header_t) \
 142                                 + sizeof (jack_shm_registry_t) * MAX_SHM_ID)
 143
 144     /**
 145      * a structure holding information about shared memory
 146      * allocated by JACK. this version is valid only
 147      * for a given address space. It contains a pointer
 148      * indicating where the shared memory has been
 149      * attached to the address space.
 150      */
 151
 152     PRE_PACKED_STRUCTURE
 153     struct _jack_shm_info {
 154         jack_shm_registry_index_t index;       /* offset into the registry */
 155         uint32_t size;
 156         union {
 157             void *attached_at;  /* address where attached */
 158             char ptr_size[8];
 159         } ptr;  /* a "pointer" that has the same 8 bytes size when compling in 32 or 64 bits */
 160     } POST_PACKED_STRUCTURE;
 161
 162     typedef struct _jack_shm_info jack_shm_info_t;
 163
 164         /* utility functions used only within JACK */
 165
 166     void jack_shm_copy_from_registry (jack_shm_info_t*,
 167                 jack_shm_registry_index_t);
 168     void jack_shm_copy_to_registry (jack_shm_info_t*,
 169                                                jack_shm_registry_index_t*);
 170     int jack_release_shm_info (jack_shm_registry_index_t);
 171     char* jack_shm_addr (jack_shm_info_t* si);
 172
 173     // here begin the API
 174     int jack_register_server (const char *server_name, int new_registry);
 175     int jack_unregister_server (const char *server_name);
 176
 177     int jack_initialize_shm (const char *server_name);
 178     int jack_initialize_shm_server (void);
 179     int jack_initialize_shm_client (void);
 180     int jack_cleanup_shm (void);
 181
 182     int jack_shmalloc (const char *shm_name, jack_shmsize_t size,
 183                                   jack_shm_info_t* result);
 184     void jack_release_shm (jack_shm_info_t*);
 185     void jack_release_lib_shm (jack_shm_info_t*);
 186     void jack_destroy_shm (jack_shm_info_t*);
 187     int jack_attach_shm (jack_shm_info_t*);
 188     int jack_attach_lib_shm (jack_shm_info_t*);
 189     int jack_attach_shm_read (jack_shm_info_t*);
 190     int jack_attach_lib_shm_read (jack_shm_info_t*);
 191     int jack_resize_shm (jack_shm_info_t*, jack_shmsize_t size);
 192
 193 #ifdef __cplusplus
 194 }
 195 #endif
 196
 197 #endif /* __jack_shm_h__ */