Media Manager

Removable media support. More...

Files
file	media.h
	Media Manager API.

Macros
#define	RTEMS_MEDIA_MOUNT_BASE   "/media"
#define	RTEMS_MEDIA_DELIMITER   '-'

Typedefs
typedef rtems_status_code(*	rtems_media_listener) (rtems_media_event event, rtems_media_state state, const char *src, const char *dest, void *listener_arg)
	Event listener.
typedef rtems_status_code(*	rtems_media_worker) (rtems_media_state state, const char *src, char **dest, void *worker_arg)
	Do the work corresponding to an event.

Enumerations
enum	rtems_media_event {   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 }
enum	rtems_media_state {   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 }

Base
rtems_status_code	rtems_media_listener_add (rtems_media_listener listener, void *listener_arg)
	Adds the listener with argument listener_arg.
rtems_status_code	rtems_media_listener_remove (rtems_media_listener listener, void *listener_arg)
	Removes the listener with argument listener_arg.
rtems_status_code	rtems_media_post_event (rtems_media_event event, const char *src, char **dest, rtems_media_worker worker, void *worker_arg)
	Posts the event with source src.

Server
rtems_status_code	rtems_media_server_initialize (rtems_task_priority priority, size_t stack_size, rtems_mode modes, rtems_attribute attributes)
	Initializes the media manager and media server.
rtems_status_code	rtems_media_server_post_event (rtems_media_event event, const char *src, rtems_media_worker worker, void *worker_arg)
	Sends an event message to the media server.

Path Construction
char *	rtems_media_create_path (const char *prefix, const char *name, rtems_device_major_number major)
	Creates a new path as "prefix/name-major".
char *	rtems_media_replace_prefix (const char *new_prefix, const char *path)
	Replaces the prefix of the path with new_prefix.
char *	rtems_media_append_minor (const char *path, rtems_device_minor_number minor)
	Appends the minor number to the path resulting in "path-minor".

Support
rtems_status_code	rtems_media_get_device_identifier (const char *device_path, dev_t *device_identifier)
	Returns the device identifier for the device located at device_path in device_identifier.
const char *	rtems_media_event_description (rtems_media_event event)
const char *	rtems_media_state_description (rtems_media_state state)

Detailed Description

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.

Typedef Documentation

rtems_media_listener

typedef rtems_status_code(* rtems_media_listener) (rtems_media_event event, rtems_media_state state, const char *src, const char *dest, void *listener_arg)

Event listener.

The listener will be called with the listener_arg passed to rtems_media_listener_add().

Source and destination values for each event and state:

Event	State	Source	Destination
RTEMS_MEDIA_EVENT_DISK_ATTACH	RTEMS_MEDIA_STATE_INQUIRY	driver name	NULL
	RTEMS_MEDIA_STATE_READY	driver name	NULL
	RTEMS_MEDIA_STATE_ABORTED	driver name	NULL
	RTEMS_MEDIA_STATE_SUCCESS	driver name	disk path
	RTEMS_MEDIA_STATE_FAILED	driver name	NULL
RTEMS_MEDIA_EVENT_DISK_DETACH	RTEMS_MEDIA_STATE_INQUIRY	disk path	NULL
	RTEMS_MEDIA_STATE_READY	disk path	NULL
	RTEMS_MEDIA_STATE_ABORTED	disk path	NULL
	RTEMS_MEDIA_STATE_SUCCESS	disk path	NULL
	RTEMS_MEDIA_STATE_FAILED	disk path	NULL
RTEMS_MEDIA_EVENT_PARTITION_INQUIRY	RTEMS_MEDIA_STATE_INQUIRY	disk path	NULL
	RTEMS_MEDIA_STATE_READY	disk path	NULL
	RTEMS_MEDIA_STATE_ABORTED	disk path	NULL
	RTEMS_MEDIA_STATE_SUCCESS	disk path	NULL
	RTEMS_MEDIA_STATE_FAILED	disk path	NULL
RTEMS_MEDIA_EVENT_PARTITION_ATTACH	RTEMS_MEDIA_STATE_INQUIRY	disk path	NULL
	RTEMS_MEDIA_STATE_READY	disk path	NULL
	RTEMS_MEDIA_STATE_ABORTED	disk path	NULL
	RTEMS_MEDIA_STATE_SUCCESS	disk path	partition path
	RTEMS_MEDIA_STATE_FAILED	disk path	NULL
RTEMS_MEDIA_EVENT_PARTITION_DETACH	RTEMS_MEDIA_STATE_INQUIRY	partition path	NULL
	RTEMS_MEDIA_STATE_READY	partition path	NULL
	RTEMS_MEDIA_STATE_ABORTED	partition path	NULL
	RTEMS_MEDIA_STATE_SUCCESS	partition path	NULL
	RTEMS_MEDIA_STATE_FAILED	partition path	NULL
RTEMS_MEDIA_EVENT_MOUNT	RTEMS_MEDIA_STATE_INQUIRY	disk or partition path	NULL
	RTEMS_MEDIA_STATE_READY	disk or partition path	NULL
	RTEMS_MEDIA_STATE_ABORTED	disk or partition path	NULL
	RTEMS_MEDIA_STATE_SUCCESS	disk or partition path	mount path
	RTEMS_MEDIA_STATE_FAILED	disk or partition path	NULL
RTEMS_MEDIA_EVENT_UNMOUNT	RTEMS_MEDIA_STATE_INQUIRY	mount path	NULL
	RTEMS_MEDIA_STATE_READY	mount path	NULL
	RTEMS_MEDIA_STATE_ABORTED	mount path	NULL
	RTEMS_MEDIA_STATE_SUCCESS	mount path	NULL
	RTEMS_MEDIA_STATE_FAILED	mount path	NULL
RTEMS_MEDIA_EVENT_ERROR	RTEMS_MEDIA_ERROR_DISK_UNKNOWN	disk path	NULL
	RTEMS_MEDIA_ERROR_DISK_EXISTS	disk path	NULL
	RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_UNKNOWN	disk or partition path	NULL
	RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_EXISTS	disk or partition path	NULL
	RTEMS_MEDIA_ERROR_PARTITION_UNKNOWN	partition path	NULL
	RTEMS_MEDIA_ERROR_PARTITION_ORPHAN	partition path	disk path
	RTEMS_MEDIA_ERROR_PARTITION_DETACH_WITH_MOUNT	partition path	mount path
	RTEMS_MEDIA_ERROR_PARTITION_WITH_UNKNOWN_DISK	partition path	disk path
	RTEMS_MEDIA_ERROR_MOUNT_POINT_UNKNOWN	mount path	NULL
	RTEMS_MEDIA_ERROR_MOUNT_POINT_EXISTS	mount path	NULL
	RTEMS_MEDIA_ERROR_MOUNT_POINT_ORPHAN	mount path	disk path

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_IO_ERROR	In the inquiry state this will abort the action.
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.

rtems_media_worker

typedef rtems_status_code(* rtems_media_worker) (rtems_media_state state, const char *src, char **dest, void *worker_arg)

Do the work corresponding to an event.

The state will be

• RTEMS_MEDIA_STATE_READY, or
• RTEMS_MEDIA_STATE_ABORTED.

It will be called with the src and worker_arg arguments passed to rtems_media_post_event().

The destination shall be returned in dest in case of success. It shall be allocated with malloc().

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_IO_ERROR	Failure.

Enumeration Type Documentation

rtems_media_event

enum rtems_media_event

Disk life cycle events:

rtems_media_state

enum rtems_media_state

Normal state transition:

Function Documentation

rtems_media_append_minor()

char * rtems_media_append_minor	(	const char *	path,
		rtems_device_minor_number	minor
	)

Appends the minor number to the path resulting in "path-minor".

Returns

New string, or NULL if no memory is available.

rtems_media_create_path()

char * rtems_media_create_path	(	const char *	prefix,
		const char *	name,
		rtems_device_major_number	major
	)

Creates a new path as "prefix/name-major".

Returns

New string, or NULL if no memory is available.

rtems_media_get_device_identifier()

rtems_status_code rtems_media_get_device_identifier	(	const char *	device_path,
		dev_t *	device_identifier
	)

Returns the device identifier for the device located at device_path in device_identifier.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	No device at this path.

rtems_media_listener_add()

rtems_status_code rtems_media_listener_add	(	rtems_media_listener	listener,
		void *	listener_arg
	)

Adds the listener with argument listener_arg.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_NO_MEMORY	Not enough memory.
RTEMS_TOO_MANY	Such a listener is already present.

rtems_media_listener_remove()

rtems_status_code rtems_media_listener_remove	(	rtems_media_listener	listener,
		void *	listener_arg
	)

Removes the listener with argument listener_arg.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	No such listener is present.

rtems_media_post_event()

rtems_status_code rtems_media_post_event	(	rtems_media_event	event,
		const char *	src,
		char **	dest,
		rtems_media_worker	worker,
		void *	worker_arg
	)

Posts the event with source src.

The worker will be called with the worker_arg argument.

The destination will be returned in 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().

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_UNSATISFIED	One or more listeners aborted the action.
RTEMS_IO_ERROR	The worker returned with an error status.

rtems_media_replace_prefix()

char * rtems_media_replace_prefix	(	const char *	new_prefix,
		const char *	path
	)

Replaces the prefix of the path with new_prefix.

The prefix is everything up to the last '/'.

Returns

New string, or NULL if no memory is available.

rtems_media_server_initialize()

rtems_status_code rtems_media_server_initialize	(	rtems_task_priority	priority,
		size_t	stack_size,
		rtems_mode	modes,
		rtems_attribute	attributes
	)

Initializes the media manager and media server.

It creates a server task with the priority, stack_size, modes, and attributes parameters.

Calling this function more than once will have no effects. There is no protection against concurrent access.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_NO_MEMORY	Not enough resources.

rtems_media_server_post_event()

rtems_status_code rtems_media_server_post_event	(	rtems_media_event	event,
		const char *	src,
		rtems_media_worker	worker,
		void *	worker_arg
	)

Sends an event message to the media server.

See also

See rtems_media_post_event().

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_NO_MEMORY	Not enough resources to notify the media server.
RTEMS_NOT_CONFIGURED	Media server is not initialized.