From 9da9cf4a8719f794490f85eae01912e6511ae6d6 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 8 Jun 2010 15:40:00 +0000 Subject: 2010-06-08 Sebastian Huber * libcsupport/include/rtems/libio.h: Documentation. --- cpukit/libcsupport/include/rtems/libio.h | 283 ++++++++++++++++++------------- 1 file changed, 166 insertions(+), 117 deletions(-) (limited to 'cpukit/libcsupport/include/rtems/libio.h') diff --git a/cpukit/libcsupport/include/rtems/libio.h b/cpukit/libcsupport/include/rtems/libio.h index 04fdc6898f..3e020ee2e4 100644 --- a/cpukit/libcsupport/include/rtems/libio.h +++ b/cpukit/libcsupport/include/rtems/libio.h @@ -1,15 +1,12 @@ /** - * @file rtems/libio.h + * @file + * + * @ingroup LibIO + * + * @brief Basic IO API. */ /* - * System call and file system interface definition - * - * General purpose communication channel for RTEMS to allow UNIX/POSIX - * system call behavior under RTEMS. Initially this supported only - * IO to devices but has since been enhanced to support networking - * and support for mounted file systems. - * * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * @@ -23,41 +20,63 @@ #ifndef _RTEMS_RTEMS_LIBIO_H #define _RTEMS_RTEMS_LIBIO_H -#include -#include #include #include #include #include -/* - * Define data types which must be constructed using forward references. - */ +#include +#include +#include #include +#include #ifdef __cplusplus extern "C" { #endif -/* - * A 64bit file offset for internal use by RTEMS. Based on the newlib type. +/** + * @defgroup LibIO IO Library + * + * @brief Provides system call and file system interface definitions. + * + * General purpose communication channel for RTEMS to allow UNIX/POSIX + * system call behavior under RTEMS. Initially this supported only + * IO to devices but has since been enhanced to support networking + * and support for mounted file systems. + * + * @{ + */ + +/** + * @brief A 64-bit file offset for internal use by RTEMS. Based on the Newlib + * type. */ typedef _off64_t rtems_off64_t; -/* - * Valid RTEMS file types. +/** + * @name File system node types. + * + * @{ */ + #define RTEMS_FILESYSTEM_DIRECTORY 1 #define RTEMS_FILESYSTEM_DEVICE 2 #define RTEMS_FILESYSTEM_HARD_LINK 3 #define RTEMS_FILESYSTEM_SYM_LINK 4 #define RTEMS_FILESYSTEM_MEMORY_FILE 5 + +/** @} */ + typedef int rtems_filesystem_node_types_t; -/* - * File Handler Operations Table +/** + * @name File System Node Operations + * + * @{ */ + typedef int (*rtems_filesystem_open_t)( rtems_libio_t *iop, const char *pathname, @@ -131,6 +150,11 @@ typedef int (*rtems_filesystem_rmnod_t)( rtems_filesystem_location_info_t *pathloc /* IN */ ); +/** @} */ + +/** + * @brief File system node operations table. + */ struct _rtems_filesystem_file_handlers_r { rtems_filesystem_open_t open_h; rtems_filesystem_close_t close_h; @@ -148,8 +172,10 @@ struct _rtems_filesystem_file_handlers_r { rtems_filesystem_rmnod_t rmnod_h; }; -/* - * File System Operations Table +/** + * @name File System Operations + * + * @{ */ /* @@ -261,12 +287,10 @@ typedef int (*rtems_filesystem_statvfs_t)( struct statvfs *buf /* OUT */ ); -/* - * operations table that must be defined for every file system. - */ +/** @} */ -/* - * File system types +/** + * @brief File system operations table. */ struct _rtems_filesystem_operations_table { rtems_filesystem_evalpath_t evalpath_h; @@ -307,7 +331,10 @@ extern const rtems_filesystem_table_t rtems_filesystem_table []; /** * @brief Per file system table entry routine type. * - * Return @c true to continue the iteration, and @c false to stop. + * @see rtems_filesystem_iterate(). + * + * @retval true Continue the iteration. + * @retval false Stop the iteration. */ typedef bool (*rtems_per_filesystem_routine)( const rtems_filesystem_table_t *entry, @@ -327,7 +354,9 @@ rtems_filesystem_iterate( ); /** - * @brief Returns the file system mount handler associated with the @a type, or + * @brief Gets the mount handler for the file system @a type. + * + * @return The file system mount handler associated with the @a type, or * @c NULL if no such association exists. */ rtems_filesystem_fsmount_me_t @@ -364,9 +393,9 @@ rtems_filesystem_unregister( const char *type ); -/* - * Structure used to contain file system specific information which - * is required to support fpathconf(). +/** + * @brief Contain file system specific information which is required to support + * fpathconf(). */ typedef struct { int link_max; /* count */ @@ -383,15 +412,16 @@ typedef struct { int posix_vdisable; /* special char processing, 0=no, 1=yes */ } rtems_filesystem_limits_and_options_t; -/* - * Default pathconf settings. Override in a filesystem. +/** + * @brief Default pathconf settings. + * + * Override in a filesystem. */ extern const rtems_filesystem_limits_and_options_t rtems_filesystem_default_pathconf; -/* - * Structure for a mount table entry. +/** + * @brief Mount table entry. */ - struct rtems_filesystem_mount_table_entry_tt { rtems_chain_node Node; rtems_filesystem_location_info_t mt_point_node; @@ -422,27 +452,27 @@ struct rtems_filesystem_mount_table_entry_tt { }; /** - * The pathconf setting for a file system. + * @brief The pathconf setting for a file system. */ #define rtems_filesystem_pathconf(_mte) ((_mte)->pathconf_limits_and_options) /** - * The type of file system. Its name. + * @brief The type of file system. Its name. */ #define rtems_filesystem_type(_mte) ((_mte)->type) /** - * The mount point of a file system. + * @brief The mount point of a file system. */ #define rtems_filesystem_mount_point(_mte) ((_mte)->target) /** - * The device entry of a file system. + * @brief The device entry of a file system. */ #define rtems_filesystem_mount_device(_mte) ((_mte)->dev) -/* - * Valid RTEMS file systems options +/** + * @brief File systems options. */ typedef enum { RTEMS_FILESYSTEM_READ_ONLY, @@ -450,12 +480,13 @@ typedef enum { RTEMS_FILESYSTEM_BAD_OPTIONS } rtems_filesystem_options_t; - -/* - * An open file data structure, indexed by 'fd' - * TODO: - * should really have a separate per/file data structure that this - * points to (eg: size, offset, driver, pathname should be in that) +/** + * @brief An open file data structure. + * + * It will be indexed by 'fd'. + * + * @todo Should really have a separate per/file data structure that this points + * to (eg: size, offset, driver, pathname should be in that) */ struct rtems_libio_tt { rtems_driver_name_t *driver; @@ -470,10 +501,11 @@ struct rtems_libio_tt { const rtems_filesystem_file_handlers_r *handlers; /* type specific handlers */ }; -/* - * param block for read/write - * Note: it must include 'offset' instead of using iop's offset since - * we can have multiple outstanding i/o's on a device. +/** + * @brief Paramameter block for read/write. + * + * It must include 'offset' instead of using iop's offset since we can have + * multiple outstanding i/o's on a device. */ typedef struct { rtems_libio_t *iop; @@ -484,8 +516,8 @@ typedef struct { uint32_t bytes_moved; } rtems_libio_rw_args_t; -/* - * param block for open/close +/** + * @brief Parameter block for open/close. */ typedef struct { rtems_libio_t *iop; @@ -493,8 +525,8 @@ typedef struct { uint32_t mode; } rtems_libio_open_close_args_t; -/* - * param block for ioctl +/** + * @brief Parameter block for ioctl. */ typedef struct { rtems_libio_t *iop; @@ -503,9 +535,12 @@ typedef struct { uint32_t ioctl_return; } rtems_libio_ioctl_args_t; -/* - * Values for 'flag' +/** + * @name Flag Values + * + * @{ */ + #define LIBIO_FLAGS_NO_DELAY 0x0001 /* return immediately if no data */ #define LIBIO_FLAGS_READ 0x0002 /* reading */ #define LIBIO_FLAGS_WRITE 0x0004 /* writing */ @@ -515,10 +550,14 @@ typedef struct { #define LIBIO_FLAGS_CLOSE_ON_EXEC 0x0800 /* close on process exec() */ #define LIBIO_FLAGS_READ_WRITE (LIBIO_FLAGS_READ | LIBIO_FLAGS_WRITE) +/** @} */ + void rtems_libio_init(void); -/* - * External I/O handlers +/** + * @name External I/O Handlers + * + * @{ */ typedef int (*rtems_libio_open_t)( @@ -555,6 +594,14 @@ typedef rtems_off64_t (*rtems_libio_lseek_t)( int whence ); +/** @} */ + +/** + * @name Permission Macros + * + * @{ + */ + /* * The following macros are used to build up the permissions sets * used to check permissions. These are similar in style to the @@ -567,11 +614,7 @@ typedef rtems_off64_t (*rtems_libio_lseek_t)( #define RTEMS_LIBIO_PERMS_SEARCH RTEMS_LIBIO_PERMS_EXEC #define RTEMS_LIBIO_PERMS_RWX S_IRWXO -/* - * Macros - */ - -#include +/** @} */ union __rtems_dev_t { dev_t device; @@ -632,10 +675,65 @@ static inline rtems_device_minor_number rtems_filesystem_dev_minor_t( void rtems_filesystem_initialize( void ); +int unmount( + const char *mount_path +); + +int mount( + const char *source, + const char *target, + const char *filesystemtype, + rtems_filesystem_options_t options, + const void *data +); + /* - * Callbacks from TERMIOS routines to device-dependent code + * Boot Time Mount Table Structure + */ + +typedef struct { + const char *type; + rtems_filesystem_options_t fsoptions; + const char *device; + const char *mount_point; +} rtems_filesystem_mount_table_t; + +extern const rtems_filesystem_mount_table_t *rtems_filesystem_mount_table; +extern const int rtems_filesystem_mount_table_size; + +typedef void (*rtems_libio_init_functions_t)(void); +extern rtems_libio_init_functions_t rtems_libio_init_helper; + +void open_dev_console(void); + +typedef void (*rtems_libio_supp_functions_t)(void); +extern rtems_libio_supp_functions_t rtems_libio_supp_helper; + +typedef void (*rtems_fs_init_functions_t)(void); +extern rtems_fs_init_functions_t rtems_fs_init_helper; + +/** + * @brief Creates a directory and all its parrent directories according to + * @a path. + * + * The @a mode value selects the access permissions of the directory. + * + * @retval 0 Successful operation. + * @retval -1 An error occured. @c errno indicates the error. + */ +extern int rtems_mkdir(const char *path, mode_t mode); + +/** @} */ + +/** + * @defgroup Termios Termios + * + * @ingroup LibIO + * + * @brief Termios + * + * @{ */ -#include typedef struct rtems_termios_callbacks { int (*firstOpen)(int major, int minor, void *arg); @@ -648,9 +746,6 @@ typedef struct rtems_termios_callbacks { int outputUsesInterrupts; } rtems_termios_callbacks; -/* - * Device-independent TERMIOS routines - */ void rtems_termios_initialize (void); /* @@ -698,53 +793,7 @@ int rtems_termios_dequeue_characters( int len ); -int unmount( - const char *mount_path -); - -int mount( - const char *source, - const char *target, - const char *filesystemtype, - rtems_filesystem_options_t options, - const void *data -); - -/* - * Boot Time Mount Table Structure - */ - -typedef struct { - const char *type; - rtems_filesystem_options_t fsoptions; - const char *device; - const char *mount_point; -} rtems_filesystem_mount_table_t; - -extern const rtems_filesystem_mount_table_t *rtems_filesystem_mount_table; -extern const int rtems_filesystem_mount_table_size; - -typedef void (*rtems_libio_init_functions_t)(void); -extern rtems_libio_init_functions_t rtems_libio_init_helper; - -void open_dev_console(void); - -typedef void (*rtems_libio_supp_functions_t)(void); -extern rtems_libio_supp_functions_t rtems_libio_supp_helper; - -typedef void (*rtems_fs_init_functions_t)(void); -extern rtems_fs_init_functions_t rtems_fs_init_helper; - -/** - * @brief Creates a directory and all its parrent directories according to - * @a path. - * - * The @a mode value selects the access permissions of the directory. - * - * @retval 0 Successful operation. - * @retval -1 An error occured. @c errno indicates the error. - */ -extern int rtems_mkdir(const char *path, mode_t mode); +/** @} */ #ifdef __cplusplus } -- cgit v1.2.3