source: rtems/cpukit/include/rtems/media.h @ fb5f575

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

/**
 * @file
 *
 * @ingroup RTEMSIOMedia
 *
 * @brief Media Manager API.
 */

/*
 * Copyright (c) 2009, 2018 embedded brains GmbH.  All rights reserved.
 *
 * 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_MEDIA_H
#define RTEMS_MEDIA_H

#include <sys/types.h>
#include <rtems.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 * @defgroup RTEMSIOMedia Media Manager
 *
 * @ingroup LibIO
 *
 * @brief Removable media support.
 *
 * The media manager may be used to maintain the life cycle of a removable
 * media.  Currently only disk devices are supported.  The initiator posts an
 * event to the media manager and it will respond with appropriate default
 * actions.  For example a disk attach will lead to inspection of the partition
 * table and mounted file systems.  Clients can register listeners to react to
 * events.
 */
/**@{**/

#define RTEMS_MEDIA_MOUNT_BASE "/media"

#define RTEMS_MEDIA_DELIMITER '-'

/**
 * Disk life cycle events:
 * @dot
 *   digraph disk_events {
 *     "DISK ATTACH" -> "PARTITION INQUIRY";
 *     "DISK ATTACH" -> "MOUNT";
 *     "PARTITION INQUIRY" -> "PARTITION ATTACH";
 *     "PARTITION INQUIRY" -> "DISK DETACH";
 *     "PARTITION ATTACH" -> "MOUNT";
 *     "MOUNT" -> "UNMOUNT";
 *     "UNMOUNT" -> "PARTITION DETACH";
 *     "UNMOUNT" -> "DISK DETACH";
 *     "PARTITION DETACH" -> "DISK DETACH";
 *   }
 * @enddot
 */
typedef enum {
  RTEMS_MEDIA_EVENT_DISK_ATTACH,
  RTEMS_MEDIA_EVENT_DISK_DETACH,
  RTEMS_MEDIA_EVENT_MOUNT,
  RTEMS_MEDIA_EVENT_UNMOUNT,
  RTEMS_MEDIA_EVENT_PARTITION_INQUIRY,
  RTEMS_MEDIA_EVENT_PARTITION_ATTACH,
  RTEMS_MEDIA_EVENT_PARTITION_DETACH,
  RTEMS_MEDIA_EVENT_ERROR
} rtems_media_event;

/**
 * Normal state transition:
 * @dot
 *   digraph state {
 *     INQUIRY -> READY [label="all listeners\nreturned successful"];
 *     INQUIRY -> ABORTED [label="otherwise"];
 *     READY -> SUCCESS [label="the worker\nreturned successful"];
 *     READY -> FAILED [label="otherwise"];
 *   }
 * @enddot
 */
typedef enum {
  RTEMS_MEDIA_STATE_INQUIRY,
  RTEMS_MEDIA_STATE_READY,
  RTEMS_MEDIA_STATE_ABORTED,
  RTEMS_MEDIA_STATE_SUCCESS,
  RTEMS_MEDIA_STATE_FAILED,
  RTEMS_MEDIA_ERROR_DISK_UNKNOWN,
  RTEMS_MEDIA_ERROR_DISK_EXISTS,
  RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_UNKNOWN,
  RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_EXISTS,
  RTEMS_MEDIA_ERROR_PARTITION_UNKNOWN,
  RTEMS_MEDIA_ERROR_PARTITION_ORPHAN,
  RTEMS_MEDIA_ERROR_PARTITION_DETACH_WITH_MOUNT,
  RTEMS_MEDIA_ERROR_PARTITION_WITH_UNKNOWN_DISK,
  RTEMS_MEDIA_ERROR_MOUNT_POINT_UNKNOWN,
  RTEMS_MEDIA_ERROR_MOUNT_POINT_EXISTS,
  RTEMS_MEDIA_ERROR_MOUNT_POINT_ORPHAN
} rtems_media_state;

/**
 * @brief Event listener.
 *
 * The listener will be called with the @a listener_arg passed to
 * rtems_media_listener_add().
 *
 * Source and destination values for each event and state:
 * <table>
 *   <tr><th>Event</th><th>State</th><th>Source</th><th>Destination</th></tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_DISK_ATTACH</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td><td>driver name</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td><td>driver name</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td><td>driver name</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td><td>driver name</td><td>disk path</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td><td>driver name</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_DISK_DETACH</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_PARTITION_INQUIRY</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_PARTITION_ATTACH</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td>
 *     <td>disk path</td><td>partition path</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_PARTITION_DETACH</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td><td>partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td><td>partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td><td>partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td><td>partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td><td>partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_MOUNT</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td>
 *     <td>disk or partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td>
 *     <td>disk or partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td>
 *     <td>disk or partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td>
 *     <td>disk or partition path</td><td>mount path</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td>
 *     <td>disk or partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="5">RTEMS_MEDIA_EVENT_UNMOUNT</td>
 *     <td>RTEMS_MEDIA_STATE_INQUIRY</td><td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_READY</td><td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_ABORTED</td><td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_SUCCESS</td><td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_STATE_FAILED</td><td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td rowspan="11">RTEMS_MEDIA_EVENT_ERROR</td>
 *     <td>RTEMS_MEDIA_ERROR_DISK_UNKNOWN</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_DISK_EXISTS</td><td>disk path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_UNKNOWN</td>
 *     <td>disk or partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_EXISTS</td>
 *     <td>disk or partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_PARTITION_UNKNOWN</td>
 *     <td>partition path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_PARTITION_ORPHAN</td>
 *     <td>partition path</td><td>disk path</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_PARTITION_DETACH_WITH_MOUNT</td>
 *     <td>partition path</td><td>mount path</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_PARTITION_WITH_UNKNOWN_DISK</td>
 *     <td>partition path</td><td>disk path</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_MOUNT_POINT_UNKNOWN</td>
 *     <td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_MOUNT_POINT_EXISTS</td>
 *     <td>mount path</td><td>NULL</td>
 *   </tr>
 *   <tr>
 *     <td>RTEMS_MEDIA_ERROR_MOUNT_POINT_ORPHAN</td>
 *     <td>mount path</td><td>disk path</td>
 *   </tr>
 * </table>
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_IO_ERROR In the inquiry state this will abort the action.
 * @retval RTEMS_INCORRECT_STATE In the failed state this will cause a retry.
 * Make sure to have a retry counter or similar to avoid endless loops if you
 * use this value.
 */
typedef rtems_status_code (*rtems_media_listener)(
  rtems_media_event event,
  rtems_media_state state,
  const char *src,
  const char *dest,
  void *listener_arg
);

/**
 * @brief Do the work corresponding to an event.
 *
 * The @a state will be
 * - RTEMS_MEDIA_STATE_READY, or
 * - RTEMS_MEDIA_STATE_ABORTED.
 *
 * It will be called with the @a src and @a worker_arg arguments passed to
 * rtems_media_post_event().
 *
 * The destination shall be returned in @a dest in case of success.  It shall
 * be allocated with malloc().
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_IO_ERROR Failure.
 */
typedef rtems_status_code (*rtems_media_worker)(
  rtems_media_state state,
  const char *src,
  char **dest,
  void *worker_arg
);

/**
 * @name Base
 */
/**@{**/

/**
 * @brief Initializes the media manager.
 *
 * Calling this function more than once will have no effects.  There is no
 * protection against concurrent access.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_NO_MEMORY Not enough resources.
 */
RTEMS_INLINE_ROUTINE rtems_status_code rtems_media_initialize(void)
{
  return RTEMS_SUCCESSFUL;
}

/**
 * @brief Adds the @a listener with argument @a listener_arg.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_NO_MEMORY Not enough memory.
 * @retval RTEMS_TOO_MANY Such a listener is already present.
 */
rtems_status_code rtems_media_listener_add(
  rtems_media_listener listener,
  void *listener_arg
);

/**
 * @brief Removes the @a listener with argument @a listener_arg.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_INVALID_ID No such listener is present.
 */
rtems_status_code rtems_media_listener_remove(
  rtems_media_listener listener,
  void *listener_arg
);

/**
 * @brief Posts the @a event with source @a src.
 *
 * The @a worker will be called with the @a worker_arg argument.
 *
 * The destination will be returned in @a dest in case of success.  It will be
 * allocated with malloc() and should be freed if not needed anymore.
 *
 * The work will be done by the calling thread.  You can avoid this if you use
 * the media server via rtems_media_server_post_event().
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_UNSATISFIED One or more listeners aborted the action.
 * @retval RTEMS_IO_ERROR The worker returned with an error status.
 */
rtems_status_code rtems_media_post_event(
  rtems_media_event event,
  const char *src,
  char **dest,
  rtems_media_worker worker,
  void *worker_arg
);

/** @} */

/**
 * @name Server
 */
/**@{**/

/**
 * @brief Initializes the media manager and media server.
 *
 * It creates a server task with the @a priority, @a stack_size, @a modes, and
 * @a attributes parameters.
 *
 * Calling this function more than once will have no effects.  There is no
 * protection against concurrent access.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_NO_MEMORY Not enough resources.
 */
rtems_status_code rtems_media_server_initialize(
  rtems_task_priority priority,
  size_t stack_size,
  rtems_mode modes,
  rtems_attribute attributes
);

/**
 * @brief Sends an event message to the media server.
 *
 * @see See rtems_media_post_event().
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_NO_MEMORY Not enough resources to notify the media server.
 * @retval RTEMS_NOT_CONFIGURED Media server is not initialized.
 */
rtems_status_code rtems_media_server_post_event(
  rtems_media_event event,
  const char *src,
  rtems_media_worker worker,
  void *worker_arg
);

/**
 * @brief See rtems_media_server_post_event().
 */
static inline rtems_status_code rtems_media_server_disk_attach(
  const char *driver_name,
  rtems_media_worker worker,
  void *worker_arg
)
{
  return rtems_media_server_post_event(
    RTEMS_MEDIA_EVENT_DISK_ATTACH,
    driver_name,
    worker,
    worker_arg
  );
}

/**
 * @brief See rtems_media_server_post_event().
 */
static inline rtems_status_code rtems_media_server_disk_detach(
  const char *disk_path
)
{
  return rtems_media_server_post_event(
    RTEMS_MEDIA_EVENT_DISK_DETACH,
    disk_path,
    NULL,
    NULL
  );
}

/** @} */

/**
 * @name Path Construction
 */
/**@{**/

/**
 * @brief Creates a new path as "prefix/name-major".
 *
 * @return New string, or @c NULL if no memory is available.
 */
char *rtems_media_create_path(
  const char *prefix,
  const char *name,
  rtems_device_major_number major
);

/**
 * @brief Replaces the prefix of the @a path with @a new_prefix.
 *
 * The prefix is everything up to the last '/'.
 *
 * @return New string, or @c NULL if no memory is available.
 */
char *rtems_media_replace_prefix(const char *new_prefix, const char *path);

/**
 * @brief Appends the @a minor number to the @a path resulting in "path-minor".
 *
 * @return New string, or @c NULL if no memory is available.
 */
char *rtems_media_append_minor(
  const char *path,
  rtems_device_minor_number minor
);

/** @} */

/**
 * @name Support
 */
/**@{**/

/**
 * @brief Returns the device identifier for the device located at
 * @a device_path in @a device_identifier.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_INVALID_ID No device at this path.
 */
rtems_status_code rtems_media_get_device_identifier(
  const char *device_path,
  dev_t *device_identifier
);

const char *rtems_media_event_description(rtems_media_event event);

const char *rtems_media_state_description(rtems_media_state state);

/** @} */

/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* RTEMS_MEDIA_H */