LCOV - code coverage report
Current view: top level - include/zephyr/sys - fdtable.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 0 5 0.0 %
Date: 2022-08-18 11:36:24 Functions: 0 1 0.0 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /*
       2                 :            :  * Copyright (c) 2018 Linaro Limited
       3                 :            :  *
       4                 :            :  * SPDX-License-Identifier: Apache-2.0
       5                 :            :  */
       6                 :            : #ifndef ZEPHYR_INCLUDE_SYS_FDTABLE_H_
       7                 :            : #define ZEPHYR_INCLUDE_SYS_FDTABLE_H_
       8                 :            : 
       9                 :            : #include <stdarg.h>
      10                 :            : #include <sys/types.h>
      11                 :            : /* FIXME: For native_posix ssize_t, off_t. */
      12                 :            : #include <fs/fs.h>
      13                 :            : 
      14                 :            : #ifdef __cplusplus
      15                 :            : extern "C" {
      16                 :            : #endif
      17                 :            : 
      18                 :            : /**
      19                 :            :  * File descriptor virtual method table.
      20                 :            :  * Currently all operations beyond read/write/close go thru ioctl method.
      21                 :            :  */
      22                 :            : struct fd_op_vtable {
      23                 :            :         ssize_t (*read)(void *obj, void *buf, size_t sz);
      24                 :            :         ssize_t (*write)(void *obj, const void *buf, size_t sz);
      25                 :            :         int (*close)(void *obj);
      26                 :            :         int (*ioctl)(void *obj, unsigned int request, va_list args);
      27                 :            : };
      28                 :            : 
      29                 :            : /**
      30                 :            :  * @brief Reserve file descriptor.
      31                 :            :  *
      32                 :            :  * This function allows to reserve a space for file descriptor entry in
      33                 :            :  * the underlying table, and thus allows caller to fail fast if no free
      34                 :            :  * descriptor is available. If this function succeeds, z_finalize_fd()
      35                 :            :  * or z_free_fd() must be called mandatorily.
      36                 :            :  *
      37                 :            :  * @return Allocated file descriptor, or -1 in case of error (errno is set)
      38                 :            :  */
      39                 :            : int z_reserve_fd(void);
      40                 :            : 
      41                 :            : /**
      42                 :            :  * @brief Finalize creation of file descriptor.
      43                 :            :  *
      44                 :            :  * This function should be called exactly once after z_reserve_fd(), and
      45                 :            :  * should not be called in any other case.
      46                 :            :  *
      47                 :            :  * @param fd File descriptor previously returned by z_reserve_fd()
      48                 :            :  * @param obj pointer to I/O object structure
      49                 :            :  * @param vtable pointer to I/O operation implementations for the object
      50                 :            :  */
      51                 :            : void z_finalize_fd(int fd, void *obj, const struct fd_op_vtable *vtable);
      52                 :            : 
      53                 :            : /**
      54                 :            :  * @brief Allocate file descriptor for underlying I/O object.
      55                 :            :  *
      56                 :            :  * This function combines operations of z_reserve_fd() and z_finalize_fd()
      57                 :            :  * in one step, and provided for convenience.
      58                 :            :  *
      59                 :            :  * @param obj pointer to I/O object structure
      60                 :            :  * @param vtable pointer to I/O operation implementations for the object
      61                 :            :  *
      62                 :            :  * @return Allocated file descriptor, or -1 in case of error (errno is set)
      63                 :            :  */
      64                 :            : int z_alloc_fd(void *obj, const struct fd_op_vtable *vtable);
      65                 :            : 
      66                 :            : /**
      67                 :            :  * @brief Release reserved file descriptor.
      68                 :            :  *
      69                 :            :  * This function may be called once after z_reserve_fd(), and should
      70                 :            :  * not be called in any other case.
      71                 :            :  *
      72                 :            :  * @param fd File descriptor previously returned by z_reserve_fd()
      73                 :            :  */
      74                 :            : void z_free_fd(int fd);
      75                 :            : 
      76                 :            : /**
      77                 :            :  * @brief Get underlying object pointer from file descriptor.
      78                 :            :  *
      79                 :            :  * This function is useful for functions other than read/write/ioctl
      80                 :            :  * to look up underlying I/O object by fd, optionally checking its
      81                 :            :  * type (using vtable reference). If fd refers to invalid entry,
      82                 :            :  * NULL will be returned with errno set to EBADF. If fd is valid,
      83                 :            :  * but vtable param is not NULL and doesn't match object's vtable,
      84                 :            :  * NULL is returned and errno set to err param.
      85                 :            :  *
      86                 :            :  * @param fd File descriptor previously returned by z_reserve_fd()
      87                 :            :  * @param vtable Expected object vtable or NULL
      88                 :            :  * @param err errno value to set if object vtable doesn't match
      89                 :            :  *
      90                 :            :  * @return Object pointer or NULL, with errno set
      91                 :            :  */
      92                 :            : void *z_get_fd_obj(int fd, const struct fd_op_vtable *vtable, int err);
      93                 :            : 
      94                 :            : /**
      95                 :            :  * @brief Get underlying object pointer and vtable pointer from file descriptor.
      96                 :            :  *
      97                 :            :  * @param fd File descriptor previously returned by z_reserve_fd()
      98                 :            :  * @param vtable A pointer to a pointer variable to store the vtable
      99                 :            :  * @param lock An optional pointer to a pointer variable to store the mutex
     100                 :            :  *        preventing concurrent descriptor access. The lock is not taken,
     101                 :            :  *        it is just returned for the caller to use if necessary. Pass NULL
     102                 :            :  *        if the lock is not needed by the caller.
     103                 :            :  *
     104                 :            :  * @return Object pointer or NULL, with errno set
     105                 :            :  */
     106                 :            : void *z_get_fd_obj_and_vtable(int fd, const struct fd_op_vtable **vtable,
     107                 :            :                               struct k_mutex **lock);
     108                 :            : 
     109                 :            : /**
     110                 :            :  * @brief Call ioctl vmethod on an object using varargs.
     111                 :            :  *
     112                 :            :  * We need this helper function because ioctl vmethod is declared to
     113                 :            :  * take va_list and the only portable way to construct va_list is from
     114                 :            :  * function's ... parameters.
     115                 :            :  *
     116                 :            :  * @param vtable vtable containing ioctl function pointer
     117                 :            :  * @param obj Object to call ioctl on
     118                 :            :  * @param request ioctl request number
     119                 :            :  * @param ... Variadic arguments to ioctl
     120                 :            :  */
     121                 :          0 : static inline int z_fdtable_call_ioctl(const struct fd_op_vtable *vtable, void *obj,
     122                 :            :                                        unsigned long request, ...)
     123                 :            : {
     124                 :            :         va_list args;
     125                 :            :         int res;
     126                 :            : 
     127                 :          0 :         va_start(args, request);
     128                 :          0 :         res = vtable->ioctl(obj, request, args);
     129                 :          0 :         va_end(args);
     130                 :            : 
     131                 :          0 :         return res;
     132                 :            : }
     133                 :            : 
     134                 :            : /**
     135                 :            :  * Request codes for fd_op_vtable.ioctl().
     136                 :            :  *
     137                 :            :  * Note that these codes are internal Zephyr numbers, for internal
     138                 :            :  * Zephyr operations (and subject to change without notice, not part
     139                 :            :  * of "stable ABI"). These are however expected to co-exist with
     140                 :            :  * "well-known" POSIX/Linux ioctl numbers, and not clash with them.
     141                 :            :  */
     142                 :            : enum {
     143                 :            :         /* Codes below 0x100 are reserved for fcntl() codes. */
     144                 :            :         ZFD_IOCTL_FSYNC = 0x100,
     145                 :            :         ZFD_IOCTL_LSEEK,
     146                 :            :         ZFD_IOCTL_POLL_PREPARE,
     147                 :            :         ZFD_IOCTL_POLL_UPDATE,
     148                 :            :         ZFD_IOCTL_POLL_OFFLOAD,
     149                 :            :         ZFD_IOCTL_SET_LOCK,
     150                 :            : };
     151                 :            : 
     152                 :            : #ifdef __cplusplus
     153                 :            : }
     154                 :            : #endif
     155                 :            : 
     156                 :            : #endif /* ZEPHYR_INCLUDE_SYS_FDTABLE_H_ */

Generated by: LCOV version 1.14