source: trunk/hal/generic/hal_uspace.h @ 684

Last change on this file since 684 was 679, checked in by alain, 4 years ago

Mainly cosmetic.
File size: 5.4 KB
Line 
1/*
2 * hal_uspace.h - Generic User Space Access API definition
3 *
4 * Authors    Alain Greiner (2016,2017,2018,2019,2020)
5 *
6 * Copyright (c)  UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef  _HAL_USPACE_H_
25#define  _HAL_USPACE_H_
26
27#include <hal_kernel_types.h>
28
29//////////////////////////////////////////////////////////////////////////////////////////
30//           User space access API (implementation in hal_uspace.c)
31//
32// For sake of portability, user/kernel data transfers must use the following API.
33//
34// When moving data between user space and kernel space, the user address is always
35// a virtual address, and the kernel address is an extended pointer.
36// Therefore, each of these buffers can be located in any cluster.
37//
38// WARNING: these function must be executed by an user thread (i.e. PID > 0),
39//          to handle a possible page fault when accessing the user buffer.
40//////////////////////////////////////////////////////////////////////////////////////////
41
42
43/*****************************************************************************************
44 * This function moves <size> bytes from a source buffer in user virtual space,
45 * defined by the <u_src_ptr> argument, to a destination kernel buffer, defined by the
46 * <k_dst_xp> argument.
47 *****************************************************************************************
48 * @ k_dst_xp  : extended pointer on kernel destination buffer.
49 * @ u_src_ptr : source buffer address in user space.
50 * @ size      : size (number of bytes).
51 ****************************************************************************************/
52extern void hal_copy_from_uspace( xptr_t     k_dst_xp,
53                                  void     * u_src_ptr,
54                                  uint32_t   size );
55
56/*****************************************************************************************
57 * This function moves <size> bytes from a source kernel buffer, defined by the
58 * <k_src_xp> argument, to a destination buffer in user virtual space, defined by
59 * the <u_dst_ptr> argument.
60 *****************************************************************************************
61 * @ u_dst_ptr : destination buffer address in user space.
62 * @ k_src_xp  : extended pointer on kernel source buffer.
63 * @ size      : size (number of bytes).
64 ****************************************************************************************/
65extern void hal_copy_to_uspace( void     * u_dst_ptr,
66                                xptr_t     k_src_xp, 
67                                uint32_t   size );
68
69/*****************************************************************************************
70 * This function tranfers a string from the user space to the kernel space.
71 * The transfer stops after the first encountered NUL character, and no more than
72 * <max_size> characters are actually copied to target buffer.
73 *****************************************************************************************
74 * @ k_dst_xp  : extended pointer on kernel destination buffer.
75 * @ u_src_ptr : source address in user space.
76 * @ max_size  : max number of characters to be copied.
77 ****************************************************************************************/
78extern void hal_strcpy_from_uspace( xptr_t     k_dst_xp,
79                                    char     * u_src_ptr,
80                                    uint32_t   max_size );
81
82/*****************************************************************************************
83 * This function tranfers a string from the kernel space to the user space.
84 * The transfer stops after the first encountered NUL character, and no more than
85 * <max_size> characters are actually copied to target buffer.
86 *****************************************************************************************
87 * @ u_dst_ptr : destination buffer address in user space.
88 * @ k_src_xp  : extended pointer on kernel source buffer.
89 * @ max_size  : max number of characters to be copied.
90 ****************************************************************************************/
91extern void hal_strcpy_to_uspace( char     * u_dst_ptr,
92                                  xptr_t     k_src_xp,
93                                  uint32_t   max_size );
94
95/*****************************************************************************************
96 * This function returns the length of a string located in user space.
97 * This length does NOT include the terminating NUL character.
98 *****************************************************************************************
99 * @ string     : string pointer in user space.
100 * @ return length of the string.
101 ****************************************************************************************/
102uint32_t hal_strlen_from_uspace( char * string );
103
104
105#endif  /* _HAL_USPACE_H_ */
Note: See TracBrowser for help on using the repository browser.