LXR 6.1/​cpukit/​include/​rtems/​media.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:13

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSIOMedia
  *
  * @brief Media Manager API.
  */
 
 /*
  * Copyright (C) 2009, 2018 embedded brains GmbH & Co. KG
  *
  * 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.
  */
 static inline 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 */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team