path: root/cpukit/include/rtems/posix/shm.h

/* SPDX-License-Identifier: BSD-2-Clause */

/**
 * @file
 *
 * @brief Internal Support for POSIX Shared Memory
 */

/*
 * Copyright (c) 2016 Gedare Bloom.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _RTEMS_POSIX_SHM_H
#define _RTEMS_POSIX_SHM_H

#include <rtems/score/objectdata.h>
#include <rtems/score/threadq.h>

#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @defgroup POSIXShmPrivate POSIX Shared Memory Private Support
 *
 * @ingroup POSIXAPI
 *
 * Internal implementation support for POSIX shared memory.
 * @{
 */
typedef struct POSIX_Shm_Object_operations POSIX_Shm_Object_operations;
extern const POSIX_Shm_Object_operations _POSIX_Shm_Object_operations;

/**
 * @brief Encapsulation for the storage and manipulation of shm objects.
 */
typedef struct {
  /**
   * @brief The handle is private for finding object storage.
   */
  void                               *handle;

  /**
   * @brief The number of bytes allocated to the object. A size of 0 with
   * a handle of NULL means no object is allocated.
   */
  size_t                              size;

  /**
   * @brief Implementation-specific operations on shm objects.
   */
  const POSIX_Shm_Object_operations  *ops;
} POSIX_Shm_Object;

/**
 * @brief Operations on POSIX Shared Memory Objects.
 */
struct POSIX_Shm_Object_operations {
  /**
   * @brief Allocates a new @a shm_obj with initial @a size.
   *
   * New shared memory is initialized to zeroes.
   *
   * Returns 0 for success.
   */
  int ( *object_create ) ( POSIX_Shm_Object *shm_obj, size_t size );

  /**
   * @brief Changes the @a shm_obj size to @a size.
   *
   * Zeroes out the portion of the shared memory object that shrinks or grows.
   *
   * Returns 0 for success.
   */
  int ( *object_resize ) ( POSIX_Shm_Object *shm_obj, size_t size );

  /**
   * @brief Deletes the @a shm_obj.
   *
   * Zeroes out the memory.
   *
   * Returns 0 for success.
   */
  int ( *object_delete ) ( POSIX_Shm_Object *shm_obj );

  /**
   * @brief Copies up to @count bytes of the @a shm_obj data into @a buf.
   *
   * Returns the number of bytes read (copied) into @a buf.
   */
  int ( *object_read ) ( POSIX_Shm_Object *shm_obj, void *buf, size_t count );

  /**
   * @brief Maps a shared memory object.
   *
   * Establishes a memory mapping between the shared memory object and the
   * caller.
   *
   * Returns the mapped address of the object.
   */
  void * ( *object_mmap ) ( POSIX_Shm_Object *shm_obj, size_t len, int prot, off_t off);
};

/**
 * @brief Control for a POSIX Shared Memory Object
 */
typedef struct {
   Objects_Control      Object;
   Thread_queue_Control Wait_queue;

   int                  reference_count;

   POSIX_Shm_Object     shm_object;

   uid_t                uid;
   gid_t                gid;
   mode_t               mode;
   int                  oflag;

   time_t               atime;
   time_t               mtime;
   time_t               ctime;
} POSIX_Shm_Control;

/**
 * @brief The POSIX Shared Memory objects information.
 */
extern Objects_Information _POSIX_Shm_Information;

/**
 * @brief Macro to define the objects information for the POSIX Shared Memory
 * objects.
 *
 * This macro should only be used by <rtems/confdefs.h>.
 *
 * @param max The configured object maximum (the OBJECTS_UNLIMITED_OBJECTS flag
 * may be set).
 */
#define POSIX_SHM_INFORMATION_DEFINE( max ) \
  OBJECTS_INFORMATION_DEFINE( \
    _POSIX_Shm, \
    OBJECTS_POSIX_API, \
    OBJECTS_POSIX_SHMS, \
    POSIX_Shm_Control, \
    max, \
    _POSIX_PATH_MAX, \
    NULL \
  )

/**
 * @brief object_create operation for shm objects stored in RTEMS Workspace.
 */
extern int _POSIX_Shm_Object_create_from_workspace(
  POSIX_Shm_Object *shm_obj,
  size_t size
);

/**
 * @brief object_delete operation for shm objects stored in RTEMS Workspace.
 */
extern int _POSIX_Shm_Object_delete_from_workspace( POSIX_Shm_Object *shm_obj );

/**
 * @brief object_resize operation for shm objects stored in RTEMS Workspace.
 */
extern int _POSIX_Shm_Object_resize_from_workspace(
  POSIX_Shm_Object *shm_obj,
  size_t size
);

/**
 * @brief object_read operation for shm objects stored in RTEMS Workspace.
 */
extern int _POSIX_Shm_Object_read_from_workspace(
  POSIX_Shm_Object *shm_obj,
  void *buf,
  size_t count
);

/**
 * @brief object_mmap operation for shm objects stored in RTEMS Workspace.
 */
extern void * _POSIX_Shm_Object_mmap_from_workspace(
  POSIX_Shm_Object *shm_obj,
  size_t len,
  int prot,
  off_t off
);

/**
 * @brief object_create operation for shm objects stored in C program heap.
 */
extern int _POSIX_Shm_Object_create_from_heap(
  POSIX_Shm_Object *shm_obj,
  size_t size
);

/**
 * @brief object_delete operation for shm objects stored in C program heap.
 */
extern int _POSIX_Shm_Object_delete_from_heap( POSIX_Shm_Object *shm_obj );

/**
 * @brief object_resize operation for shm objects stored in C program heap.
 */
extern int _POSIX_Shm_Object_resize_from_heap(
  POSIX_Shm_Object *shm_obj,
  size_t size
);

/**
 * @brief object_read operation for shm objects stored in C program heap.
 */
extern int _POSIX_Shm_Object_read_from_heap(
  POSIX_Shm_Object *shm_obj,
  void *buf,
  size_t count
);

/**
 * @brief object_mmap operation for shm objects stored in C program heap.
 */
extern void * _POSIX_Shm_Object_mmap_from_heap(
  POSIX_Shm_Object *shm_obj,
  size_t len,
  int prot,
  off_t off
);

/** @} */

#ifdef __cplusplus
}
#endif

#endif