Changeset 9da9cf4a in rtems


Ignore:
Timestamp:
Jun 8, 2010, 3:40:00 PM (9 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
4.11, master
Children:
44b7bcd
Parents:
68cd765
Message:

2010-06-08 Sebastian Huber <sebastian.huber@…>

  • libcsupport/include/rtems/libio.h: Documentation.
Location:
cpukit
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • cpukit/ChangeLog

    r68cd765 r9da9cf4a  
     12010-06-08      Sebastian Huber <sebastian.huber@embedded-brains.de>
     2
     3        * libcsupport/include/rtems/libio.h: Documentation.
     4
    152010-06-08      Sebastian Huber <sebastian.huber@embedded-brains.de>
    26
  • cpukit/libcsupport/include/rtems/libio.h

    r68cd765 r9da9cf4a  
    11/**
    2  * @file rtems/libio.h
    3  */
    4 
    5 /*
    6  *  System call and file system interface definition
    7  *
    8  *  General purpose communication channel for RTEMS to allow UNIX/POSIX
    9  *  system call behavior under RTEMS.  Initially this supported only
    10  *  IO to devices but has since been enhanced to support networking
    11  *  and support for mounted file systems.
    12  *
     2 * @file
     3 *
     4 * @ingroup LibIO
     5 *
     6 * @brief Basic IO API.
     7 */
     8
     9/*
    1310 *  COPYRIGHT (c) 1989-2008.
    1411 *  On-Line Applications Research Corporation (OAR).
     
    2421#define _RTEMS_RTEMS_LIBIO_H
    2522
    26 #include <rtems.h>
    27 #include <rtems/chain.h>
    2823#include <sys/types.h>
    2924#include <sys/stat.h>
     
    3126#include <sys/statvfs.h>
    3227
    33 /*
    34  *  Define data types which must be constructed using forward references.
    35  */
    36 
     28#include <unistd.h>
     29#include <termios.h>
     30
     31#include <rtems.h>
    3732#include <rtems/fs.h>
     33#include <rtems/chain.h>
    3834
    3935#ifdef __cplusplus
     
    4137#endif
    4238
    43 /*
    44  * A 64bit file offset for internal use by RTEMS. Based on the newlib type.
     39/**
     40 * @defgroup LibIO IO Library
     41 *
     42 * @brief Provides system call and file system interface definitions.
     43 *
     44 * General purpose communication channel for RTEMS to allow UNIX/POSIX
     45 * system call behavior under RTEMS.  Initially this supported only
     46 * IO to devices but has since been enhanced to support networking
     47 * and support for mounted file systems.
     48 *
     49 * @{
     50 */
     51
     52/**
     53 * @brief A 64-bit file offset for internal use by RTEMS. Based on the Newlib
     54 * type.
    4555 */
    4656typedef _off64_t rtems_off64_t;
    4757
    48 /*
    49  * Valid RTEMS file types.
    50  */
     58/**
     59 * @name File system node types.
     60 *
     61 * @{
     62 */
     63
    5164#define RTEMS_FILESYSTEM_DIRECTORY   1
    5265#define RTEMS_FILESYSTEM_DEVICE      2
     
    5467#define RTEMS_FILESYSTEM_SYM_LINK    4
    5568#define RTEMS_FILESYSTEM_MEMORY_FILE 5
     69
     70/** @} */
     71
    5672typedef int rtems_filesystem_node_types_t;
    5773
    58 /*
    59  *  File Handler Operations Table
    60  */
     74/**
     75 * @name File System Node Operations
     76 *
     77 * @{
     78 */
     79
    6180typedef int (*rtems_filesystem_open_t)(
    6281  rtems_libio_t *iop,
     
    132151);
    133152
     153/** @} */
     154
     155/**
     156 * @brief File system node operations table.
     157 */
    134158struct _rtems_filesystem_file_handlers_r {
    135159    rtems_filesystem_open_t         open_h;
     
    149173};
    150174
    151 /*
    152  *  File System Operations Table
     175/**
     176 * @name File System Operations
     177 *
     178 * @{
    153179 */
    154180
     
    262288);
    263289
    264 /*
    265  * operations table that must be defined for every file system.
    266  */
    267 
    268 /*
    269  * File system types
     290/** @} */
     291
     292/**
     293 * @brief File system operations table.
    270294 */
    271295struct _rtems_filesystem_operations_table {
     
    308332 * @brief Per file system table entry routine type.
    309333 *
    310  * Return @c true to continue the iteration, and @c false to stop.
     334 * @see rtems_filesystem_iterate().
     335 *
     336 * @retval true Continue the iteration.
     337 * @retval false Stop the iteration.
    311338 */
    312339typedef bool (*rtems_per_filesystem_routine)(
     
    328355
    329356/**
    330  * @brief Returns the file system mount handler associated with the @a type, or
     357 * @brief Gets the mount handler for the file system @a type.
     358 *
     359 * @return The file system mount handler associated with the @a type, or
    331360 * @c NULL if no such association exists.
    332361 */
     
    365394);
    366395
    367 /*
    368  *  Structure used to contain file system specific information which
    369  *  is required to support fpathconf().
     396/**
     397 * @brief Contain file system specific information which is required to support
     398 * fpathconf().
    370399 */
    371400typedef struct {
     
    384413} rtems_filesystem_limits_and_options_t;
    385414
    386 /*
    387  * Default pathconf settings. Override in a filesystem.
     415/**
     416 * @brief Default pathconf settings.
     417 *
     418 * Override in a filesystem.
    388419 */
    389420extern const rtems_filesystem_limits_and_options_t rtems_filesystem_default_pathconf;
    390421
    391 /*
    392  * Structure for a mount table entry.
    393  */
    394 
     422/**
     423 * @brief Mount table entry.
     424 */
    395425struct rtems_filesystem_mount_table_entry_tt {
    396426  rtems_chain_node                       Node;
     
    423453
    424454/**
    425  * The pathconf setting for a file system.
     455 * @brief The pathconf setting for a file system.
    426456 */
    427457#define rtems_filesystem_pathconf(_mte) ((_mte)->pathconf_limits_and_options)
    428458
    429459/**
    430  * The type of file system. Its name.
     460 * @brief The type of file system. Its name.
    431461 */
    432462#define rtems_filesystem_type(_mte) ((_mte)->type)
    433463
    434464/**
    435  * The mount point of a file system.
     465 * @brief The mount point of a file system.
    436466 */
    437467#define rtems_filesystem_mount_point(_mte) ((_mte)->target)
    438468
    439469/**
    440  * The device entry of a file system.
     470 * @brief The device entry of a file system.
    441471 */
    442472#define rtems_filesystem_mount_device(_mte) ((_mte)->dev)
    443473
    444 /*
    445  *  Valid RTEMS file systems options
     474/**
     475 * @brief File systems options.
    446476 */
    447477typedef enum {
     
    451481} rtems_filesystem_options_t;
    452482
    453 
    454 /*
    455  *  An open file data structure, indexed by 'fd'
    456  *  TODO:
    457  *     should really have a separate per/file data structure that this
    458  *     points to (eg: size, offset, driver, pathname should be in that)
     483/**
     484 * @brief An open file data structure.
     485 *
     486 * It will be indexed by 'fd'.
     487 *
     488 * @todo Should really have a separate per/file data structure that this points
     489 * to (eg: size, offset, driver, pathname should be in that)
    459490 */
    460491struct rtems_libio_tt {
     
    471502};
    472503
    473 /*
    474  *  param block for read/write
    475  *  Note: it must include 'offset' instead of using iop's offset since
    476  *        we can have multiple outstanding i/o's on a device.
     504/**
     505 * @brief Paramameter block for read/write.
     506 *
     507 * It must include 'offset' instead of using iop's offset since we can have
     508 * multiple outstanding i/o's on a device.
    477509 */
    478510typedef struct {
     
    485517} rtems_libio_rw_args_t;
    486518
    487 /*
    488  *  param block for open/close
     519/**
     520 * @brief Parameter block for open/close.
    489521 */
    490522typedef struct {
     
    494526} rtems_libio_open_close_args_t;
    495527
    496 /*
    497  *  param block for ioctl
     528/**
     529 * @brief Parameter block for ioctl.
    498530 */
    499531typedef struct {
     
    504536} rtems_libio_ioctl_args_t;
    505537
    506 /*
    507  *  Values for 'flag'
    508  */
     538/**
     539 * @name Flag Values
     540 *
     541 * @{
     542 */
     543
    509544#define LIBIO_FLAGS_NO_DELAY      0x0001  /* return immediately if no data */
    510545#define LIBIO_FLAGS_READ          0x0002  /* reading */
     
    516551#define LIBIO_FLAGS_READ_WRITE    (LIBIO_FLAGS_READ | LIBIO_FLAGS_WRITE)
    517552
     553/** @} */
     554
    518555void rtems_libio_init(void);
    519556
    520 /*
    521  *  External I/O handlers
     557/**
     558 * @name External I/O Handlers
     559 *
     560 * @{
    522561 */
    523562
     
    555594  int           whence
    556595);
     596
     597/** @} */
     598
     599/**
     600 * @name Permission Macros
     601 *
     602 * @{
     603 */
    557604
    558605/*
     
    568615#define RTEMS_LIBIO_PERMS_RWX    S_IRWXO
    569616
    570 /*
    571  *  Macros
    572  */
    573 
    574 #include <unistd.h>
     617/** @} */
    575618
    576619union __rtems_dev_t {
     
    633676void rtems_filesystem_initialize( void );
    634677
    635 /*
    636  * Callbacks from TERMIOS routines to device-dependent code
    637  */
    638 #include <termios.h>
     678int unmount(
     679  const char *mount_path
     680);
     681
     682int mount(
     683  const char                 *source,
     684  const char                 *target,
     685  const char                 *filesystemtype,
     686  rtems_filesystem_options_t options,
     687  const void                 *data
     688);
     689
     690/*
     691 *  Boot Time Mount Table Structure
     692 */
     693
     694typedef struct {
     695  const char                              *type;
     696  rtems_filesystem_options_t               fsoptions;
     697  const char                              *device;
     698  const char                              *mount_point;
     699} rtems_filesystem_mount_table_t;
     700
     701extern const rtems_filesystem_mount_table_t *rtems_filesystem_mount_table;
     702extern const int                             rtems_filesystem_mount_table_size;
     703
     704typedef void (*rtems_libio_init_functions_t)(void);
     705extern  rtems_libio_init_functions_t rtems_libio_init_helper;
     706
     707void    open_dev_console(void);
     708
     709typedef void (*rtems_libio_supp_functions_t)(void);
     710extern  rtems_libio_supp_functions_t rtems_libio_supp_helper;
     711
     712typedef void (*rtems_fs_init_functions_t)(void);
     713extern  rtems_fs_init_functions_t    rtems_fs_init_helper;
     714
     715/**
     716 * @brief Creates a directory and all its parrent directories according to
     717 * @a path.
     718 *
     719 * The @a mode value selects the access permissions of the directory.
     720 *
     721 * @retval 0 Successful operation.
     722 * @retval -1 An error occured.  @c errno indicates the error.
     723 */
     724extern int rtems_mkdir(const char *path, mode_t mode);
     725
     726/** @} */
     727
     728/**
     729 * @defgroup Termios Termios
     730 *
     731 * @ingroup LibIO
     732 *
     733 * @brief Termios
     734 *
     735 * @{
     736 */
    639737
    640738typedef struct rtems_termios_callbacks {
     
    649747} rtems_termios_callbacks;
    650748
    651 /*
    652  *  Device-independent TERMIOS routines
    653  */
    654749void rtems_termios_initialize (void);
    655750
     
    699794);
    700795
    701 int unmount(
    702   const char *mount_path
    703 );
    704 
    705 int mount(
    706   const char                 *source,
    707   const char                 *target,
    708   const char                 *filesystemtype,
    709   rtems_filesystem_options_t options,
    710   const void                 *data
    711 );
    712 
    713 /*
    714  *  Boot Time Mount Table Structure
    715  */
    716 
    717 typedef struct {
    718   const char                              *type;
    719   rtems_filesystem_options_t               fsoptions;
    720   const char                              *device;
    721   const char                              *mount_point;
    722 } rtems_filesystem_mount_table_t;
    723 
    724 extern const rtems_filesystem_mount_table_t *rtems_filesystem_mount_table;
    725 extern const int                             rtems_filesystem_mount_table_size;
    726 
    727 typedef void (*rtems_libio_init_functions_t)(void);
    728 extern  rtems_libio_init_functions_t rtems_libio_init_helper;
    729 
    730 void    open_dev_console(void);
    731 
    732 typedef void (*rtems_libio_supp_functions_t)(void);
    733 extern  rtems_libio_supp_functions_t rtems_libio_supp_helper;
    734 
    735 typedef void (*rtems_fs_init_functions_t)(void);
    736 extern  rtems_fs_init_functions_t    rtems_fs_init_helper;
    737 
    738 /**
    739  * @brief Creates a directory and all its parrent directories according to
    740  * @a path.
    741  *
    742  * The @a mode value selects the access permissions of the directory.
    743  *
    744  * @retval 0 Successful operation.
    745  * @retval -1 An error occured.  @c errno indicates the error.
    746  */
    747 extern int rtems_mkdir(const char *path, mode_t mode);
     796/** @} */
    748797
    749798#ifdef __cplusplus
Note: See TracChangeset for help on using the changeset viewer.