RTEMS: Media Manager

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Files | Macros | Typedefs | Enumerations
Media Manager
IO Library

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_INLINE_ROUTINE 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

## ◆ 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_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_initialize()

RTEMS_INLINE_ROUTINE 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_SUCCESSFUL | Successful operation.
  RTEMS_NO_MEMORY | Not enough resources.

## ◆ 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.