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_ */
|