jack/shm.h

   1 #ifndef __jack_shm_h__
   2 #define __jack_shm_h__
   3
   4 #include <limits.h>
   5 #include <sys/types.h>
   6 #include <jack/types.h>
   7
   8 #define MAX_SERVERS 8                   /* maximum concurrent servers */
   9 #define MAX_SHM_ID 256                  /* generally about 16 per server */
  10 #define JACK_SERVER_NAME_SIZE 256       /* maximum length of server name */
  11 #define JACK_SHM_MAGIC 0x4a41434b       /* shm magic number: "JACK" */
  12 #define JACK_SHM_NULL_INDEX -1          /* NULL SHM index */
  13 #define JACK_SHM_REGISTRY_INDEX -2      /* pseudo SHM index for registry */
  14
  15
  16 /* On Mac OS X, SHM_NAME_MAX is the maximum length of a shared memory
  17  * segment name (instead of NAME_MAX or PATH_MAX as defined by the
  18  * standard).
  19  */
  20 #ifdef USE_POSIX_SHM
  21 #ifndef SHM_NAME_MAX
  22 #define SHM_NAME_MAX NAME_MAX
  23 #endif
  24 typedef char       shm_name_t[SHM_NAME_MAX];
  25 typedef shm_name_t jack_shm_id_t;
  26 #else /* System V SHM */
  27 typedef int        jack_shm_id_t;
  28 #endif /* SHM type */
  29
  30 /* shared memory type */
  31 typedef enum {
  32         shm_POSIX = 1,                  /* POSIX shared memory */
  33         shm_SYSV = 2                    /* System V shared memory */
  34 } jack_shmtype_t;
  35
  36 typedef int16_t jack_shm_registry_index_t;
  37
  38 /**
  39  * A structure holding information about shared memory allocated by
  40  * JACK. this persists across invocations of JACK, and can be used by
  41  * multiple JACK servers.  It contains no pointers and is valid across
  42  * address spaces.
  43  *
  44  * The registry consists of two parts: a header including an array of
  45  * server names, followed by an array of segment registry entries.
  46  */
  47 typedef struct _jack_shm_server {
  48     pid_t                     pid;      /* process ID */
  49     char                      name[JACK_SERVER_NAME_SIZE];
  50 } jack_shm_server_t;
  51
  52 typedef struct _jack_shm_header {
  53     uint32_t                  magic;    /* magic number */
  54     uint16_t                  protocol; /* JACK protocol version */
  55     jack_shmtype_t            type;     /* shm type */
  56     jack_shmsize_t            size;     /* total registry segment size */
  57     jack_shmsize_t            hdr_len;  /* size of header */
  58     jack_shmsize_t            entry_len; /* size of registry entry */
  59     jack_shm_server_t server[MAX_SERVERS]; /* current server array */
  60 } jack_shm_header_t;
  61
  62 typedef struct _jack_shm_registry {
  63     jack_shm_registry_index_t index;     /* offset into the registry */
  64     pid_t                     allocator; /* PID that created shm segment */
  65     jack_shmsize_t            size;      /* for POSIX unattach */
  66     jack_shm_id_t             id;        /* API specific, see above */
  67 } jack_shm_registry_t;
  68
  69 #define JACK_SHM_REGISTRY_SIZE (sizeof (jack_shm_header_t) \
  70                                 + sizeof (jack_shm_registry_t) * MAX_SHM_ID)
  71
  72 /**
  73  * a structure holding information about shared memory
  74  * allocated by JACK. this version is valid only
  75  * for a given address space. It contains a pointer
  76  * indicating where the shared memory has been
  77  * attached to the address space.
  78  */
  79 typedef struct _jack_shm_info {
  80     jack_shm_registry_index_t index;       /* offset into the registry */
  81     void                     *attached_at; /* address where attached */
  82 } jack_shm_info_t;
  83
  84 /* utility functions used only within JACK */
  85
  86 extern void jack_shm_copy_from_registry (jack_shm_info_t*,
  87                                          jack_shm_registry_index_t);
  88 extern void jack_shm_copy_to_registry (jack_shm_info_t*,
  89                                        jack_shm_registry_index_t*);
  90 extern void jack_release_shm_info (jack_shm_registry_index_t);
  91
  92 static inline char* jack_shm_addr (jack_shm_info_t* si) {
  93         return si->attached_at;
  94 }
  95
  96 /* here beginneth the API */
  97
  98 extern int  jack_register_server (const char *server_name, int new_registry);
  99 extern void jack_unregister_server (const char *server_name);
 100
 101 extern int  jack_initialize_shm (const char *server_name);
 102 extern int  jack_cleanup_shm (void);
 103
 104 extern int  jack_shmalloc (jack_shmsize_t size, jack_shm_info_t* result);
 105 extern void jack_release_shm (jack_shm_info_t*);
 106 extern void jack_destroy_shm (jack_shm_info_t*);
 107 extern int  jack_attach_shm (jack_shm_info_t*);
 108 extern int  jack_resize_shm (jack_shm_info_t*, jack_shmsize_t size);
 109
 110 #endif /* __jack_shm_h__ */