/**
* @file
*
* @ingroup RTEMSIOMedia
*
* @brief Media Manager API.
*/
/*
* Copyright (c) 2009, 2018 embedded brains GmbH. All rights reserved.
*
* embedded brains GmbH
* Dornierstr. 4
* 82178 Puchheim
* Germany
* <rtems@embedded-brains.de>
*
* The license and distribution terms for this file may be
* found in the file LICENSE in this distribution or at
* http://www.rtems.org/license/LICENSE.
*/
#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.
*/
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 */
