RTEMS CPU Kit with SuperCore  4.10.99.0
Files | Defines | Typedefs | Enumerations
Media Manager

Removable media support. More...

Files

file  media.h
 

Media API.


Defines

#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
}
 Disk life cycle events: More...
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
}
 Normal state transition: More...

Base

rtems_status_code rtems_media_initialize (void)
 Initializes the media manager.
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

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:

EventStateSourceDestination
RTEMS_MEDIA_EVENT_DISK_ATTACH RTEMS_MEDIA_STATE_INQUIRYdriver nameNULL
RTEMS_MEDIA_STATE_READYdriver nameNULL
RTEMS_MEDIA_STATE_ABORTEDdriver nameNULL
RTEMS_MEDIA_STATE_SUCCESSdriver namedisk path
RTEMS_MEDIA_STATE_FAILEDdriver nameNULL
RTEMS_MEDIA_EVENT_DISK_DETACH RTEMS_MEDIA_STATE_INQUIRYdisk pathNULL
RTEMS_MEDIA_STATE_READYdisk pathNULL
RTEMS_MEDIA_STATE_ABORTEDdisk pathNULL
RTEMS_MEDIA_STATE_SUCCESSdisk pathNULL
RTEMS_MEDIA_STATE_FAILEDdisk pathNULL
RTEMS_MEDIA_EVENT_PARTITION_INQUIRY RTEMS_MEDIA_STATE_INQUIRYdisk pathNULL
RTEMS_MEDIA_STATE_READYdisk pathNULL
RTEMS_MEDIA_STATE_ABORTEDdisk pathNULL
RTEMS_MEDIA_STATE_SUCCESSdisk pathNULL
RTEMS_MEDIA_STATE_FAILEDdisk pathNULL
RTEMS_MEDIA_EVENT_PARTITION_ATTACH RTEMS_MEDIA_STATE_INQUIRYdisk pathNULL
RTEMS_MEDIA_STATE_READYdisk pathNULL
RTEMS_MEDIA_STATE_ABORTEDdisk pathNULL
RTEMS_MEDIA_STATE_SUCCESS disk pathpartition path
RTEMS_MEDIA_STATE_FAILEDdisk pathNULL
RTEMS_MEDIA_EVENT_PARTITION_DETACH RTEMS_MEDIA_STATE_INQUIRYpartition pathNULL
RTEMS_MEDIA_STATE_READYpartition pathNULL
RTEMS_MEDIA_STATE_ABORTEDpartition pathNULL
RTEMS_MEDIA_STATE_SUCCESSpartition pathNULL
RTEMS_MEDIA_STATE_FAILEDpartition pathNULL
RTEMS_MEDIA_EVENT_MOUNT RTEMS_MEDIA_STATE_INQUIRY disk or partition pathNULL
RTEMS_MEDIA_STATE_READY disk or partition pathNULL
RTEMS_MEDIA_STATE_ABORTED disk or partition pathNULL
RTEMS_MEDIA_STATE_SUCCESS disk or partition pathmount path
RTEMS_MEDIA_STATE_FAILED disk or partition pathNULL
RTEMS_MEDIA_EVENT_UNMOUNT RTEMS_MEDIA_STATE_INQUIRYmount pathNULL
RTEMS_MEDIA_STATE_READYmount pathNULL
RTEMS_MEDIA_STATE_ABORTEDmount pathNULL
RTEMS_MEDIA_STATE_SUCCESSmount pathNULL
RTEMS_MEDIA_STATE_FAILEDmount pathNULL
RTEMS_MEDIA_EVENT_ERROR RTEMS_MEDIA_ERROR_DISK_UNKNOWNdisk pathNULL
RTEMS_MEDIA_ERROR_DISK_EXISTSdisk pathNULL
RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_UNKNOWN disk or partition pathNULL
RTEMS_MEDIA_ERROR_DISK_OR_PARTITION_EXISTS disk or partition pathNULL
RTEMS_MEDIA_ERROR_PARTITION_UNKNOWN partition pathNULL
RTEMS_MEDIA_ERROR_PARTITION_ORPHAN partition pathdisk path
RTEMS_MEDIA_ERROR_PARTITION_DETACH_WITH_MOUNT partition pathmount path
RTEMS_MEDIA_ERROR_PARTITION_WITH_UNKNOWN_DISK partition pathdisk path
RTEMS_MEDIA_ERROR_MOUNT_POINT_UNKNOWN mount pathNULL
RTEMS_MEDIA_ERROR_MOUNT_POINT_EXISTS mount pathNULL
RTEMS_MEDIA_ERROR_MOUNT_POINT_ORPHAN mount pathdisk path
Return values:
RTEMS_SUCCESSFULSuccessful operation.
RTEMS_IO_ERRORIn the inquiry state this will abort the action.
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_SUCCESSFULSuccessful operation.
RTEMS_IO_ERRORFailure.

Enumeration Type Documentation

Disk life cycle events:

dot_inline_dotgraph_2.png

Normal state transition:

dot_inline_dotgraph_3.png

Function Documentation

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.
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_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_SUCCESSFULSuccessful operation.
RTEMS_INVALID_IDNo device at this path.
rtems_status_code rtems_media_initialize ( void  )

Initializes the media manager.

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

Return values:
RTEMS_SUCCESSFULSuccessful operation.
RTEMS_NO_MEMORYNot enough resources.
rtems_status_code rtems_media_listener_add ( rtems_media_listener  listener,
void *  listener_arg 
)

Adds the listener with argument listener_arg.

Return values:
RTEMS_SUCCESSFULSuccessful operation.
RTEMS_NO_MEMORYNot enough memory.
RTEMS_TOO_MANYSuch a listener is already present.
rtems_status_code rtems_media_listener_remove ( rtems_media_listener  listener,
void *  listener_arg 
)

Removes the listener with argument listener_arg.

Return values:
RTEMS_SUCCESSFULSuccessful operation.
RTEMS_INVALID_IDNo such listener is present.
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_SUCCESSFULSuccessful operation.
RTEMS_UNSATISFIEDOne or more listeners aborted the action.
RTEMS_IO_ERRORThe worker returned with an error status.
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_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_SUCCESSFULSuccessful operation.
RTEMS_NO_MEMORYNot enough resources.
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_SUCCESSFULSuccessful operation.
RTEMS_NO_MEMORYNot enough resources to notify the media server.
RTEMS_NOT_CONFIGUREDMedia server is not initialized.